dispatch

Local control plane for orchestrating Codex agent lanes over the Codex App Server. One authored contract per operation, projected to CLI + MCP (+ remote later) with no drift.

Quick Start

Install the CLI from PyPI:

uv tool install outfitter-dispatch
dispatch --help
dispatchd --help
dispatch doctor

From a source checkout:

uv sync
uv run dispatch --help
uv run dispatch doctor --no-app-server
uv run dispatch up
uv run dispatch daemon status

Create an owned managed thread, send it work, and inspect the daemon:

uv run dispatch new \
  --name docs \
  --cwd /path/to/dispatch \
  --text "Please summarize the current stack state."
uv run dispatch list
uv run dispatch tail <dispatch-ref> --limit 20
uv run dispatch goal set <dispatch-ref> "Finish the docs review."
uv run dispatch daemon log --limit 10
uv run dispatch down

Use owned managed threads for turn-writing work. Existing desktop Codex threads can be attached as managed threads, but ADR-0005 still blocks turn-writing and history-mutating commands such as send, stop, goal set, and goal clear on attached lanes. Every managed thread has a dispatch-local ref; full Codex thread UUIDs remain accepted everywhere. Titles and @handles are mutable convenience labels, not stable identity. Metadata lifecycle actions (rename, archive, restore) can target managed refs or raw unmanaged Codex thread ids, and search can span both. Attach is metadata-only by default; use dispatch sync <selector> when you want dispatch to refresh its local indexed view of an attached thread.

For the operator guide, CLI/MCP examples, triggers, and plugin setup, start at docs/usage/README.md.

Start troubleshooting with dispatch doctor. It checks PATH visibility, the Codex CLI and auth footprint, daemon socket/pidfile state, registry schema/integrity, packaged skills/plugin assets, and a low-risk Codex App Server initialize smoke.

Agent And Plugin Support

This repo ships first-party skills in skills/:

• skills/dispatch/SKILL.md teaches agents how to operate dispatch safely.
• skills/dm/SKILL.md is the dispatch-backed "dispatch message" workflow for short inter-lane messages.

The workspace-local Codex plugin bundle lives at plugins/dispatch/, with a marketplace entry in .agents/plugins/marketplace.json. Restart Codex if the plugin does not appear immediately.

Project Docs

• docs/development/design.md - architecture and design notes.
• docs/adrs/ - accepted architecture decisions.
• docs/research/ - verified Codex App Server findings.
• .agents/plans/v0/RETRO.md - v0 execution ledger and verification record.

For contributors, AGENTS.md is the canonical fieldguide.