wanman - worktree-isolated multi-agent runtime for Claude Code and Codex

wanman is a multi-agent runtime for coordinating Claude Code or Codex sessions on a single machine. The metaphor in the README is Japanese one-man trains - the human is the conductor watching the line, not driving each car. The technical version: each agent runs in its own git worktree with its own home directory, lifecycle is managed via JSON-RPC subprocess control, and the operator's job is to observe rather than orchestrate.

The repo is at 451 stars, MIT-licensed, TypeScript. The interesting design choice (and the reason it's worth looking at over the dozen other "multi-agent CC orchestrators" that landed this month) is the isolation model.

Worktree-per-agent is the right primitive

Most multi-agent harnesses share a working directory. Two agents touching the same files at once is the obvious failure mode, and the usual fix is some flavour of file lock. wanman skips the problem: each agent gets its own git worktree, its own ~/ equivalent, and its own state. Cross-contamination - one agent's edits showing up in another's context - just doesn't happen.

This is the same isolation pattern Claude Code's --worktree flag uses for individual tasks. wanman is "what if you ran ten of those at once and treated the worktree set as the unit of work."

How it actually runs

Each agent is a long-lived claude (or codex) subprocess managed by wanman's CLI:

• JSON-RPC over stdio for lifecycle and task dispatch (not API calls into a hosted service)
• Subprocess wrappers spawn the real CLI binary, so you keep the agent's full interactive surface (approvals, hooks, custom slash commands) rather than working through the limited non-interactive --print mode
• Task pool + artifact storage for handoffs between agents
• Unified context management via the CLI - one place to see what each agent is working on

The combination matters: long-lived subprocesses + worktree isolation + pooled handoffs is the shape that makes "leave it running while I sleep" actually work. Sessions don't accumulate cross-talk, the harness can resume after a crash, and you can attach to any individual agent's TUI to debug.

Install

git clone git@github.com:chekusu/wanman.git wanman.dev
cd wanman.dev
pnpm install && pnpm build
pnpm --filter @wanman/cli exec wanman takeover /path/to/git/repo

wanman takeover is the entry point: hand it a repo, it provisions worktrees, spawns agents, and starts the task loop.

When to reach for it

• You want multiple agents on the same project without writing your own worktree-management glue. wanman has solved that piece.
• You've tried the share-a-directory approach and watched two agents stomp on each other. The isolation model is the upgrade.
• You're observing more than directing - "build me X" workflows where the human checks in periodically rather than approving every tool call.

When not to

• You only need one agent. The complexity payoff starts at 2+; below that, vanilla Claude Code with --worktree is the right call.
• Your work is tightly serial - feature branch, single PR, single review. Multi-agent is for parallelisable workloads (refactors that touch many files, exploratory spikes, doc-and-code-in-parallel) where worktree isolation is a feature rather than overhead.
• You want a hosted control plane. wanman is local-only. If your model is "send tasks from Slack, have agents pick them up in the cloud," look at TeamFuse or one of the AgentDM-style products instead.

Trade-offs

Worktree isolation is the right primitive but it's not free: each worktree is a full clone of working state. On a large monorepo that's tens of GB per agent, which constrains how many you can run in parallel.

The "observe, don't direct" framing is honest but it does mean the human-in-the-loop UX is thinner than a pure orchestrator's. wanman gives you a unified status view; it doesn't give you a Linear-style kanban of agent tasks. If you want one, you'd be wiring it up on top.

The Japanese one-man-train metaphor is charming and load-bearing - the README really does treat humans as conductors who occasionally intervene, not as supervisors who approve every action. That's the right model for autonomous workflows but a foreign one if you're used to RLHF-style step-by-step approval. Worth knowing before you point ten agents at a repo overnight.