wanman: a local supervisor for Claude Code and Codex agent matrices

The problem wanman targets: many agents, one dirty checkout

Running several coding agents against the same repository creates a collision problem. Two processes editing the same file, or a background agent rewriting your shell profile, turns an orchestration experiment into a recovery exercise. wanman's answer is structural rather than advisory: the README states that every agent is isolated in a per-agent worktree and a per-agent $HOME, so agents never mutate your dirty checkout or shell profile. The name comes from the Japanese one-man train, and the stated design goal is that the human steps back into an observer role while the matrix runs. The audience is narrow and specific: engineers who already have a logged-in Claude Code or Codex CLI and want a supervisor process coordinating role-based agents (the README lists CEO, dev, devops, marketing and feedback as examples) on their own hardware. It is not a way to avoid paying for model access, because you bring your own CLI auth.

Supervisor, message bus, and what each agent process actually is

The architecture diagram in the README shows three layers. The wanman CLI speaks JSON-RPC 2.0 to a Supervisor process. That Supervisor owns the message store, context store, task pool and artifact store, and spawns one child process per agent. Each child is a real Claude Code or Codex CLI subprocess, selected by the WANMAN_RUNTIME environment variable, which defaults to claude. Persistence sits in files plus SQLite, with the default database path given in the sample agent config as .wanman/wanman.db. Coordination runs over an async message bus with steer and follow-up priorities, and the CLI exposes the bus directly through wanman send and wanman recv. The steer flag matters for control flow: wanman send <agent> <msg> --steer interrupts the target rather than queueing behind whatever it is doing. Task dependencies are expressed with an --after flag on the task commands, so ordering is declared rather than inferred.

Getting a matrix running from source

The README does not describe an npm install path. The quickstart clones the repository, installs with pnpm, builds, and then runs the CLI from source, noting explicitly that no npm package publish is required. The prerequisites are Node 20 or newer, pnpm 9 or newer, git, and a logged-in Claude Code or Codex CLI. The takeover command is the entry point for existing code: pnpm --filter @wanman/cli exec wanman takeover /path/to/any/git/repo. If you prefer a single-file bundle, pnpm --filter @wanman/cli standalone produces packages/cli/dist/wanman.mjs, which you then invoke with node. When the binary is on your PATH, wanman takeover . works from inside the target repository. The supervisor listens on port 3120 by default, and WANMAN_URL overrides the HTTP URL the CLI talks to. Runtime selection and model overrides go through WANMAN_RUNTIME, WANMAN_MODEL, WANMAN_CODEX_MODEL and WANMAN_CODEX_REASONING_EFFORT. Agent definitions live in one JSON file with an agents array plus top-level dbPath, port and workspaceRoot keys.

Lifecycle modes and the parts of the config the README leaves open

Each agent entry carries a name, a lifecycle, a model tier and a systemPrompt. The README describes three lifecycle values. A 24/7 agent runs a continuous respawn loop. An on-demand agent stays idle until triggered. An idle_cached agent also stays idle until triggered, but preserves the prior Claude session_id across triggers via claude --resume, which is the difference that matters if you care about conversational continuity versus cold starts. The README text is truncated mid-sentence at that third value, so treat the full semantics of idle_cached as something to confirm in docs/architecture.md rather than something the front page settles. The same caution applies to the experimental @wanman/finops toolkit, which the README describes as covering API credential inventory, provider cost sync, Stripe revenue sync and product or company ROI summaries. An experimental label on a package that touches API credentials and Stripe data is a signal to read the source before pointing it at production keys.

Where the local edition stops and the hosted one begins

The README draws a line between what runs locally and what wanman.ai adds, and that line is the most useful thing in the document for a build-versus-buy decision. Local mode gives you the supervisor, the message bus, the task pool, artifacts, hypotheses, capsules, initiatives, and per-agent isolation. The hosted edition claims sandboxed runtime groups for high-concurrency execution, dynamic role configuration including extraction of roles from public agent role catalogs, dynamic skill self-evolution, and db9-powered global search and story retrieval. None of those four are in the local feature list. A local db9 brain adapter is mentioned as optional for cross-run memory, with a pointer to the brain and persistence section of the architecture doc, but that is a memory adapter, not the hosted search and retrieval layer. If your workflow depends on agents rewriting their own skills, the local build is the wrong tool today.

A real alternative: a single agent session with manual context

The obvious alternative is not another orchestrator. It is one Claude Code or Codex session in your actual checkout, with you pasting context between tasks. That approach needs no supervisor process, no SQLite store, no port 3120, and no per-agent $HOME, and it never has to reconcile two agents that disagree about a file. What it cannot do is the thing wanman's command surface is built around: durable shared context through wanman context get and context set, a task pool with declared dependencies, structured artifacts, and hypothesis tracking with status transitions. Those are the primitives that make state survive a single session. The trade is real in both directions. wanman adds a supervisor, a database and a JSON-RPC hop between you and the model, and the README's own framing, that you step back into an observer role, is a description of reduced moment-to-moment control. wanman skill:check exists precisely because this surface is large enough to drift: it validates that skill docs reference only real CLI commands.

Maintenance surface, licence, and what to verify before trusting it

Adoption cost here is a source checkout, not a versioned dependency. You clone, pnpm install, pnpm build, and rebuild when you pull. There is no retrieved release list in the material, so there is no changelog or semver contract to lean on, and the CLI command table is explicitly a snapshot: the README tells you to run wanman --help for the current list. That instruction is worth taking literally, because commands such as capsule, hypothesis and initiative are not things most teams already have muscle memory for. The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant, with the usual obligations around preserving notices and stating changes; that is a summary of the identifier, not legal advice, and the LICENSE file in the repository is the authority. The hosted edition is a separate product with separate terms, and the README does not state what happens to your data there. Verify three things first: that your CLI auth survives inside a per-agent $HOME, that the agent config JSON keys match what your installed build expects, and that docs/architecture.md resolves the truncated idle_cached description. The command that answers the third question fastest is wanman --help followed by a read of the architecture doc, not a trial run against a repository you care about.

Editorial conclusion

Adopt wanman if you already pay for Claude Code or Codex CLI access, you are comfortable running a local supervisor on port 3120, and your multi-agent work is tied to a git repository you want left untouched. Do not adopt it if you need a hosted control plane, a published npm package, or role catalogs and skill self-evolution, since the README places those in the hosted edition at wanman.ai. Before committing, verify the agent config schema end to end, confirm your CLI auth works inside a per-agent $HOME, and check whether the unresolved lifecycle values in the README are documented in docs/architecture.md.

Official sources

1. chekusu/wanman on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README