agent-dispatcher

Give each Claude Code or Codex task the specialist, context, and skills it needs.

Agent Dispatcher routes your request to a focused role, loads relevant guidance, and defines what evidence will count as done. Ask it to debug a failure, design an interface, review a change, or research a decision. It adapts to the work and keeps small tasks small.

Quick start · Usage · Catalog · Documentation · Contributing

Why use it?

• Match the method to the task. A debugger reproduces the failure; a reviewer evaluates the change; a designer works through the interface and interaction.
• Load context as needed. Roles select a small set of skills, project files, and available tools. Full skill instructions are read only when selected.
• Make verification explicit. The role defines the evidence needed and reports which checks actually ran, what passed, and what remains unverified.
• Keep control of routing. Let the dispatcher choose, force a role yourself, or opt into automatic activation for future sessions.

Roles are working instructions the coding agent adopts within a session. It can chain roles or assign roles to subagents when authorized and useful. Installing the pack does not start a team of agents or connect external services.

Quick start

You need an installed, authenticated Claude Code or Codex, and Git. The installers, validation suites, and optional decision engine use Python 3.10+ with no third-party Python packages. The Claude session hook also uses Bash and standard Unix utilities. CI covers Python 3.10–3.14 on Linux and Python 3.14 on macOS. Native Windows installation is not covered; use a Unix environment such as WSL.

Codex

Run in your terminal:

git clone https://github.com/nahid-sparktales/agent-dispatcher.git
cd agent-dispatcher
python3 install_codex.py

Start a new Codex task, select Agent Dispatcher from the skill picker or invoke it with $:

$agent-dispatcher Find why the tests are failing, fix the cause, and verify the fix.
$agent-dispatcher reviewer Review this change for correctness and missing tests.
$agent-dispatcher context explain
$agent-dispatcher status

This installs one skill in ~/.agents/skills/agent-dispatcher/. It includes all 27 roles and 79 supporting guides from the same sources as Claude. Guides load only when selected. Automatic session activation is off by default; enabling it requires Codex's hook trust review. See Codex setup, controls, and uninstall.

Claude Code plugin

Run in your terminal:

claude plugin marketplace add nahid-sparktales/agent-dispatcher
claude plugin install agent-dispatcher@agent-dispatcher

Start a new Claude Code session in your project, then try:

/agent-dispatcher:agent-dispatcher Find why the tests are failing, fix the cause, and verify the fix.

The dispatcher reads the selected role and guides, then announces the role, loaded skills, and selected tools before starting the task. To inspect the installation and activation state:

/agent-dispatcher:agent-dispatcher status

Plugin commands use the agent-dispatcher: prefix, following Claude Code's plugin namespacing. For example, the reviewer command is /agent-dispatcher:agent-reviewer.

git clone https://github.com/nahid-sparktales/agent-dispatcher.git
cd agent-dispatcher
./install.sh

/agent-dispatcher Find why the tests are failing, fix the cause, and verify the fix.
/agent-dispatcher status

No additional API key is needed for normal dispatcher use. Your coding agent's access and usage requirements still apply. External skills and MCP servers are catalog references; the pack does not install them.

Usage

The examples and catalogs below use Claude Code manual-install command names. For a Claude plugin install, add agent-dispatcher: after the slash: /agent-context becomes /agent-dispatcher:agent-context.

In Codex, use $agent-dispatcher <request>. Choose a role with $agent-dispatcher reviewer, inspect context with $agent-dispatcher context, and use $agent-dispatcher decision for decision settings. The catalog's /agent-uidesigner maps to $agent-dispatcher uidesigner, and the other role aliases work the same way. Activation arguments such as on here and off everywhere are shared between hosts; their settings are stored separately.

Let the dispatcher choose

/agent-dispatcher Redesign the settings page, implement it, and check it on mobile.
/agent-dispatcher Review this change for correctness and missing tests.
/agent-dispatcher Compare the approaches already used in this repository and recommend one.

Routing follows the requested deliverable. A UI task can move through designer, implementer, and tester; a label change goes straight to implementation. Trivial edits need no role or context plan. While active, the dispatcher re-routes when the kind of work changes.

Choose a role or inspect a decision

A directly selected role stays active until you choose another or stop the dispatcher.

See what the dispatcher loads

Compact output is the default. It combines the role and resources into one progress line:

→ reviewer · Skills loaded: secure-code-review · Tools selected: files, terminal · MCPs: none selected

For more detail, switch to verbose output. In Codex:

$agent-dispatcher output verbose
$agent-dispatcher output compact
$agent-dispatcher output

In Claude Code, use /agent-dispatcher output verbose or output compact (with the agent-dispatcher: prefix for plugin installations). output reports the current style. You can also say "use verbose output" or "show what you load".

Verbose output explains the selections and names context read, recipes loaded, unavailable resources and fallbacks, and planned verification. For example:

Role: reviewer — evaluate the change for correctness and regressions
Skills loaded: secure-code-review — inspect the changed security boundary
Tools selected: files, terminal — available; inspect the diff and run checks
MCPs: none selected
Recipe loaded: review-pull-request — structure the review
Verification planned: focused regression checks; not run yet

These are examples, not a fixed loadout. Only skills actually read are labeled loaded; selected MCP servers are marked used only after a call. Later additions get a short update, and the final report names tools used and checks performed. Trivial tasks skip the summary.

The setting lasts for the conversation; new conversations default to compact. It changes activity reporting, not routing, permissions, or the length of the requested deliverable. context verbose remains a one-time inspection of the context plan.

List what is usable and what needs setup

In Codex:

$agent-dispatcher inventory
$agent-dispatcher inventory skills
$agent-dispatcher inventory tools
$agent-dispatcher inventory mcps
$agent-dispatcher inventory setup
$agent-dispatcher inventory setup verbose

In Claude Code, use /agent-inventory with the same filters, or /agent-dispatcher:agent-inventory for a plugin install. /agent-dispatcher inventory also works.

The report covers bundled guides, referenced external skills, other host-exposed skills, visible tools, and catalog or host-exposed MCP servers. Each entry has a status and a next step:

setup filters to entries needing attention. verbose adds evidence, prerequisites, source links, and fallbacks; compact still lists every entry in the requested scope. The command inspects availability without loading every skill, probing accounts, or installing anything. It reports discovery limits rather than treating an unseen integration as missing. Usability is separate from permission to perform a particular action.

Build local context

The dispatcher uses a local selector after choosing a role for substantial or unfamiliar workspace tasks. It skips trivial edits and configuration controls. To inspect context directly:

$agent-dispatcher context build Investigate why validate_login rejects valid sessions
/agent-context build Investigate why validate_login rejects valid sessions

The first form is for Codex, the second for Claude Code. Inspection returns relevant passages, file locations, line numbers, selection reasons, exclusions and an estimated size budget; it does not perform the requested change. Existing context, context explain, and context verbose commands still inspect the context plan.

The selector searches local files, favors definitions and related tests, and follows at most one hop of simple relative imports. It respects ignore rules, skips generated and sensitive files, and reports when scan limits or unavailable search tools leave gaps. It uses no model requests, network services, persistent index, or background process. A limited result is a starting point: the agent can read additional evidence when needed.

The dispatcher entrypoint and concise context guide are each capped at 6 KiB per host. Role catalogs, configuration controls, delegation and advanced examples live in references read only when needed. These are limits on dispatcher instructions and retrieved passages, not the host's whole context window or a claim of improved model performance.

From the source checkout, run python3 -B context.py --project /path/to/project --task "Check login". Use --task-file - for standard input, --role debugger, --size small|standard|complex, --max-tokens N, and --json as needed. See context selection for limits.

Check health and get setup recommendations

In Codex:

$agent-dispatcher doctor
$agent-dispatcher doctor all reviewer
$agent-dispatcher doctor mcps
$agent-dispatcher doctor setup

In Claude Code, use /agent-doctor with the same arguments, or /agent-dispatcher:agent-doctor for a plugin install. /agent-dispatcher doctor also works.

The default checks the installation and goes through all bundled guides, referenced external skills, catalog MCPs, and additional skills/tools exposed in the current session. Each entry states what is usable, what connection has been verified, what needs setup, or what remains unknown. It also checks activation and hook registration; a registered hook does not prove trust. The full inventory is followed by a ranked shortlist of useful missing capabilities, with a reason, source link, next step, and existing fallback. A role argument focuses recommendations without hiding other inventory entries or changing your active role.

Doctor checks availability without loading every guide or calling every integration. It never connects accounts, enables services, uses stored credentials, or changes permissions. A configured server is not automatically connected; incomplete host discovery is reported as unknown. Disabled and retired integrations are not recommended for activation.

For an offline local check from the source checkout:

python3 -B doctor.py --project /path/to/project --role reviewer
python3 -B doctor.py mcps --project /path/to/project --json

The standalone command cannot see a running agent's connections by itself. In-session commands supply a sanitized observation snapshot using --evidence; see doctor procedure and evidence format. JSON output is available for tooling.

Activate automatically in future sessions

Automatic activation is opt-in. These commands manage the settings for you:

Claude project activation requires both a local flag and an allow-list entry in your Claude config directory. Codex keeps its allow-list in your Codex config directory and ignores local activation flags. Cloning a repository with an activation flag is not enough to enable the dispatcher. Project and session silences take precedence over activation.

Uninstall

For Codex, run from your clone:

python3 install_codex.py --uninstall

For a Claude plugin install:

claude plugin uninstall agent-dispatcher@agent-dispatcher

For a Claude manual install, run from your clone:

./install.sh --uninstall

The manual uninstaller removes the installed pack, its recorded commands, and its hook registration. It leaves activation flags in place.

How it works

Your request
  → specialist role
  → context plan: relevant skills, project files, available tools, verification
  → execution
  → evidence and result

A role owns the outcome. A skill supplies a reusable method. An MCP server or tool provides a capability. A recipe suggests a workflow across roles. The context plan assembles what the specialist needs before it plans the work.

Project signals such as package.json, Dockerfile, or components.json help select relevant guidance. Missing skills or tools lead to documented fallbacks and explicit verification limits. The build caps always-on skills at five and 30 KB per role.

These are instructions and validation rules, not a sandbox. Authorization remains with the user and the host's permission controls. Detecting a stack, selecting a tool, or switching roles does not grant permission to use it.

Verification is specific to the work: a bug fix needs the original reproduction and regression evidence; a UI change needs rendered interaction checks when a browser is available. A review of work produced in the same session is a self-check, even when another role performs it. See verification expectations and the context engine.

Catalog

Counts and catalog entries below are generated from the repository's canonical sources. External skills are referenced, not bundled. The MCP registry includes a workspace-tool entry and an unmaintained server recorded as a warning; its count is not a list of installed integrations.

External skill provenance, license notes, and fallback behavior are recorded in catalog/external-skills.json. Review dependencies that execute scripts before enabling them; see the security guide.

Optional decision engine

Claude handles routing by default. The pack also includes an opt-in Jev integration for selecting roles, skills, and tools from the catalog. All Jev scopes ship disabled. Normal use requires no Jev account, key, or configuration.

Enabling Jev sends task text, candidate metadata, and relevant routing context to TypeSafe's API using your own credential and billed usage. Task redaction is best-effort. See the Jev guide for setup, payload details, modes, fallback behavior, and evaluation results.

The recorded comparison favors keeping the default path for routing and skill selection. These are selection benchmarks, not evidence of better completed work: the Claude results reconstruct the routing step in isolated cases, and end-to-end task evaluations are still missing.

Documentation

Contributing

Bug reports, routing examples, documentation improvements, and focused contributions are welcome. Read CONTRIBUTING.md before editing: this repository keeps canonical sources separate from generated artifacts.

templates/                 Role definitions
skills/<category>/<id>/    Local skills and manifests
recipes/                   Workflow definitions
catalog/                   Registries and schemas
*.template.*               Dispatcher, context, and hook sources
decision/                  Optional decision-engine implementation
evals/decision/            Selection fixtures and evaluation harness
docs/                      Detailed guides
build.py                   Generator and validator

Edit source files, then run from the repository root:

python3 build.py
python3 test_build.py
python3 test_decision.py
python3 test_doctor.py
python3 test_context.py

These checks run offline without provider credentials. They validate generated-file agreement, references, loadout limits, registry consistency, hook behavior, and decision-engine boundaries. The manual installer runs them before installation.

To run the offline keyword baseline:

python3 evals/decision/run.py

The keyword baseline is a measurement floor; it does not run Claude's in-session routing. See adding a role or adding a skill to extend the catalog. Preserve generated regions between <!-- name:start --> and <!-- name:end --> markers in this README and the documentation.

For vulnerabilities, follow SECURITY.md.

License and provenance

MIT License. Role origins and adaptation history are documented in NOTICE. Referenced third-party skills retain their own licenses. This project is not affiliated with or endorsed by Anthropic or Locus.