nicksmits1/wayfinder-sidebar

Contribute to nicksmits1/wayfinder-sidebar development by creating an account on GitHub.

Summary

wayfinder-sidebar is a Claude Code plugin that places a /wayfinder ticket map beside the chat. It helps engineers see which tickets are ready, claimed, or blocked, then start work in the current session or a new terminal tab with an optional handoff note and visible context usage.

The plugin is read-only: it reads local Markdown or GitHub issue trackers but never edits tickets, maps, or the wayfinder, grilling, and handoff skill files.

What it is useful for

This is useful when one engineering project is being handled across multiple Claude Code sessions. Instead of relying on the chat to remember what everyone is doing, engineers get a shared map of ticket ownership, dependencies, and remaining work.

For example, a backend engineer can identify a ticket blocked by two other tickets and avoid starting it prematurely. When a dependency is resolved, the ticket becomes unblocked and flashes in the sidebar. A ▶ button can start a ready ticket with several options:

• Run it in the current Claude Code session.
• Open a fresh terminal tab without a handoff.
• Write a handoff note and launch a new session with that context.
• Select multiple ready tickets and start them together with one shared handoff.

Each session reports its context usage against a configurable budget, defaulting to 200,000 tokens. The bar turns yellow at 60% and red when it exceeds the budget, supporting the documented one-ticket-per-session workflow.

The map supports local Markdown files under .scratch/<effort>/map.md and GitHub issues labeled wayfinder:map. Local changes appear immediately in the originating tab and within a few seconds in other tabs; GitHub maps refresh every 45 seconds.

How engineers can use it

Install the plugin from a Claude Code terminal session:

/plugin install wayfinder-sidebar --marketplace nicksmits1/wayfinder-sidebar

Alternatively, run:

claude plugin install wayfinder-sidebar --marketplace nicksmits1/wayfinder-sidebar

It requires Claude Code 2.1.275 or later and the wayfinder skill; handoff is optional. The gh CLI must be signed in for GitHub-hosted maps. When the working directory contains a map, the sidebar opens automatically; /wayfinder-map opens it manually.

Use md or gh on a row to open the underlying ticket, and ▶ to choose how to start it. If the sidebar does not appear, or tracker and launcher setup differs in your environment, consult the README and plugin settings.

Launching new terminal tabs is documented for macOS with iTerm or Terminal.app. On Linux, the command is copied to the clipboard after using xdg-open; Windows is untested. Handoff notes are stored temporarily under $TMPDIR/wayfinder-handoffs/, not in the repository.