claude-wayfinder

claude-wayfinder

A typed, auditable dispatch matcher for Claude Code — post-cognitive routing with a deterministic-first scoring kernel.

What this is — and why it matters

A conventional LLM router enforces routing policy through prose instructions read at every decision point. In practice, this means the routing decision is made by the same model that's about to do the work — using the same signal that drove the original request. It drifts silently, makes the same decision differently across turns, and leaves no structured artifact you can inspect or replay.

claude-wayfinder replaces that loop for the mechanical cases — the ones that don't need judgment. It scores agents and skills against a structured task description composed by the router agent, not the raw user prompt, and returns one of seven typed decisions with confidence, rationale, and alternatives.

Three properties that matter:

• Auditable. Every dispatch decision is a structured artifact. Given the same context and catalog, the matcher returns the same answer. You can replay any past decision.
• Post-cognitive. The matcher fires after the router agent has read the conversation and extracted intent, file paths, and tools. Raw prompts are signal-poor; the router's interpretation is richer — same model, more signal.
• Auto-generated catalog. Built from skill sidecars and agent frontmatter at session start. No hand-curated rule config to drift out of sync.

The decision contract is a seven-member typed enum: delegate / self_handle / self_handle_unaided / advisory / ask_user / needs_more_detail / mixed_content.

Advanced reading: for the design rationale, see docs/design.md. For the algorithm specification, see docs/schema.md.

Install (Claude Code users)

Requires Python >= 3.11. The setup skill discovers Python automatically; it does not need to be on your $PATH.

Inside Claude Code, run these two commands:

/plugin marketplace add glitchwerks/claude-wayfinder
/plugin install claude-wayfinder@glitchwerks

Troubleshooting

claude-wayfinder requires setup banner on session start

The plugin uses a venv-based architecture introduced in v0.4 (#99). On first install you will see a SessionStart banner:

⚠ claude-wayfinder requires setup. Run /setup-wayfinder to materialize the Python venv.

Run /setup-wayfinder once. The skill will:

1. Discover a Python >= 3.11 on your machine.
2. Create a venv at ~/.claude/plugins/data/claude-wayfinder-glitchwerks/venv/.
3. Install claude-wayfinder from PyPI.
4. Write a setup-state flag so subsequent sessions know setup is complete.

The same skill runs again after plugin updates — a STALE banner will prompt you.

"No Python >= 3.11 found"

The skill will ask you for an absolute path. Provide one such as /usr/local/bin/python3.12 or C:\Python313\python.exe. The path is persisted in the setup-state flag for re-runs.

Setup completed but dispatch still does not fire

Open a new session. Hooks read the setup-state flag at session start; an in-progress session does not pick up the flag retroactively.

How to use it

There are two distinct paths depending on your goal.

What is a dispatch context?

Before using either path, it helps to understand what the matcher actually reads. When the router agent invokes /dispatch, it passes a dispatch context — a small JSON object with up to five fields:

Field	Type	What it carries
task_description	string	The task sentence. Tokenized into keywords for matching. Required.
file_paths	array of strings	File or directory paths mentioned or implied by the current turn.
agent_mentions	array of strings	Agent names the user explicitly named (e.g. "code-writer").
tool_mentions	array of strings	Tool names the user explicitly named (e.g. "Bash", "Grep").
command_prefix	string or null	The slash command the user typed, if any (e.g. "/refactor").