agent-dispatch as a Cross-Project Claude Code Router

The weak version of this article says agent-dispatch improves productivity by automating cross-project work. That misses the point.

The useful version starts with a common failure in agent workflows: the current session knows one repository, but the answer lives in another. The backend agent needs container logs from the infra repo. The frontend agent needs a database migration check. The release agent needs a package version from a sibling project with its own MCP config.

agent-dispatch is worth saving because it gives that handoff a local MCP shape. A calling agent can list configured project agents, inspect their capabilities, and dispatch a self-contained task to a separate claude -p session running in the target directory. That target session inherits its own files, MCP servers, CLAUDE.md, and permission profile. The article should teach readers when that boundary helps, how to configure it, and where the security edge is.

Use it for context you do not have

The README's rule is the right editorial center: dispatch when a task needs tools, files, or context from another project. Do not dispatch when the current agent can do the work itself.

Good dispatch tasks look like this:

- Ask the infra agent to check container logs through its Portainer MCP.
- Ask the database agent whether migrations are applied.
- Ask the frontend agent to run its local typecheck after an API contract change.
- Ask a package agent to inspect its own CLAUDE.md and build conventions.

Weak dispatch tasks look like this:

- Summarize code already visible in the current repo.
- Ask another agent for an opinion with no extra tools or files.
- Split one tightly coupled debugging path into parallel guesses.

The value is project-local context, not agent multiplication.

The setup is deliberately small

The basic setup path is straightforward:

pip install agent-dispatch
agent-dispatch init
agent-dispatch add infra ~/projects/infra
agent-dispatch add backend ~/projects/backend
agent-dispatch test infra

agent-dispatch init creates the config and registers the MCP server with Claude Code. The config lives at ~/.config/agent-dispatch/agents.yaml unless AGENT_DISPATCH_CONFIG overrides it. The config writer uses owner-only permissions because it records project paths and permission settings.

A minimal team-local map should start with two or three agents. Do not register every repo on the machine just because the command exists.

Start with discovery, not dispatch

The MCP server instructions say to call list_agents() first. The implementation makes that useful: it reports the configured name, directory, description, health, whether CLAUDE.md exists, whether .mcp.json exists, detected MCP servers, stacks, database indicators, and permission fields.

Then use inspect_agent(name) for a cheap deeper lookup. It reads the target project files without spawning a Claude subprocess and can include previews of CLAUDE.md and README.md.

That sequence matters:

1. `list_agents()` to see available targets.
2. `inspect_agent("infra")` to confirm tools and context.
3. Dispatch only if the target has the thing the current agent lacks.

Without that discipline, delegation becomes a slower way to guess.

How the dispatch actually runs

The runner builds a claude -p command with --output-format json, sets the working directory to the target agent's project directory, and runs the task as a subprocess.

The prompt can include structured sections:

## Goal
Debug the production scheduler crash.

## Dispatched by
backend

## Context
TypeError at scheduler.py:42 after deploy.

## Task
Check the infra logs for scheduler container errors from the last hour.

The caller and goal fields are not polish. They are how the target agent understands why it is being asked and how much judgment it should apply.

Use refs for large output

Cross-project agents can return long logs, build output, or code review notes. The server has a context-control pattern for that: call dispatch(..., return_ref=true) and then fetch the full result only when needed with fetch_result(ref).

That is the right pattern for logs and reports:

Dispatch to infra with return_ref=true.
Ask for a 500-character summary plus the ref.
If the summary shows the scheduler error, fetch the full result.

This preserves the calling agent's context window. It also creates on-disk job records, which means sensitive output now exists outside the chat transcript. Treat refs as local secrets.

Parallel dispatch has a narrow use case

dispatch_parallel is useful when tasks are independent: infra checks logs, db checks migrations, frontend checks the build. The implementation bounds fan-out and can optionally send all results to an aggregate agent.

Use it like this:

[
  {"agent": "infra", "task": "check pod logs for scheduler errors", "caller": "backend", "goal": "debug crash"},
  {"agent": "db", "task": "confirm all migrations are applied", "caller": "backend", "goal": "debug crash"}
]

Do not use parallel dispatch when one answer should change the next question. For sequential debugging, use one dispatch, read the result, then decide the next step.

Permissions are the real design decision

The example config shows agent-level permissions:

agents:
  staging-db:
    directory: ~/projects/staging-db
    description: Read-only database agent.
    timeout: 120
    permission_mode: bypassPermissions
    allowed_tools:
      - Read
      - Grep
      - Bash

bypassPermissions is convenient for non-interactive dispatch, but it removes Claude Code's permission prompts for that agent. The security policy is direct: enable it only for trusted project directories, and prefer allowed_tools or disallowed_tools for least privilege.

A safer first pass is a read-only agent: Read, Grep, maybe Bash for inspection commands. Add write tools only when the project actually needs remote edits.

The trust boundary is same-user local

agent-dispatch is not a multi-tenant work queue. Its security policy says the MCP caller and agent configurations are part of the same trust domain as the user running the server.

Important consequences:

- Dispatched sessions inherit the full parent environment.
- Job records can contain full task, context, and result payloads.
- `job_id` values are bearer references for anyone who can call the MCP tool.
- Recursion depth is best-effort and protects accidental loops, not hostile agents.
- Project directories are trusted local directories, not sandboxed tenants.

This is fine for a single developer coordinating local repos. It is not enough for untrusted contributors, shared machines, or team-wide automation without additional controls.

What the implementation does right

The source has details worth crediting.

The runner passes commands as argument lists, not through a shell. It also rejects structured CLI argument values that start with - for fields such as session_id, model, permission_mode, and tool names, which prevents option smuggling into the Claude CLI.

The job store validates refs as 32-character hex IDs before file access, writes job files atomically, sets the jobs directory to 0700, and sets job files to 0600. The config writer also uses owner-only permissions.

Those details do not make unsafe delegation safe. They do show the tool is designed around real local failure modes, not only a happy-path README.

A practical routing policy

A team or solo operator should write a small policy next to the config:

Dispatch policy
- Call `list_agents` and `inspect_agent` before first dispatch in a session.
- Pass `caller` and `goal` on every dispatch.
- Prefer `return_ref=true` for logs or reports over 2,000 characters.
- Use `dispatch_parallel` only for independent checks.
- No `bypassPermissions` without `allowed_tools` or `disallowed_tools`.
- No dispatch to repos containing unrelated secrets.
- Never ask a dispatched agent to modify another repo unless that repo is its own directory.

That turns agent-dispatch from a clever bridge into an operating convention.

When to skip it

Skip it for small tasks inside the current repository. The overhead of another Claude session is real.

Skip it when the target repo has secrets in its environment or working tree that the current task should not see. The subprocess inherits the parent environment, and the agent can read its configured directory.

Skip it when auditability matters more than speed. Local job files and cached results help a single operator, but they are not a full team audit log.

Skip it when the answer requires shared state between agents. In that case, keep the reasoning in one session or use a more explicit orchestration plan.

Save the article as a cross-project delegation field guide. agent-dispatch is useful when a Claude Code workflow needs another repo's files, MCP servers, CLAUDE.md, and permission profile. It is not a reason to spawn agents for work the current session can already do.

Practical takeaway

Use agent-dispatch for project-local context gaps: infra logs, database checks, sibling repo builds, and repo-specific MCP tools. Keep the agent map small, inspect before dispatch, pass caller and goal, use refs for large outputs, restrict permissions, and remember that this is a same-user local trust model.