Multi-agent manager for Claude Code and Codex. Launches and monitors concurrent autonomous agent sessions, coordinating via GitHub issues, labels, and PRs.
# Install
uv tool install git+https://github.com/FormalFrontier/pod.git
# For development: uv pip install -e .
# Bootstrap a project
cd your-project
pod init
# Now write your long-term PLAN.md
# Launch the TUI
pod
# Or use CLI commands
pod add 3 # launch 3 agents
pod status # queue depth, agent count, cost
pod list # show running agentsPod manages a pool of autonomous agents, each running in its own git worktree on its own branch. Agents coordinate through GitHub issues and PRs:
- Write a
PLAN.mddescribing the project goals, stages, and structure - Planners read
PLAN.mdand create scoped work items as GitHub issues - Workers claim issues, implement changes, and open PRs
- Auto-merge handles the rest
PLAN.md is the single source of truth — planners decompose it into
issues, workers execute those issues. Agents never modify PLAN.md
itself; update it directly when you want to steer the project.
- Python 3.10+
- Claude Code CLI (
claude) or OpenAI Codex (codex) - GitHub CLI (
gh), authenticated - Git
| Command | Description |
|---|---|
pod |
Interactive TUI |
pod init [--force] |
Bootstrap .pod/ in current git repo |
pod update |
Re-populate agent config from installed package |
pod add [N] |
Launch N agents (default 1) |
pod list |
Show running agents |
pod finish [ID|all] |
Signal agent(s) to finish after current work |
pod kill [ID|all] |
Kill agent(s) immediately |
pod status |
Queue depth, agent count, total cost |
pod log [ID] |
Tail agent's session output |
pod config [--edit] |
Show or edit configuration |
pod coordination ... |
Run bundled coordination script directly |
After pod init, edit .pod/config.toml to customize:
- Worker types: define agent roles (
/plan,/feature,/review, etc.) - Dispatch strategy:
queue_balanceorround_robin - Claude model: default
opus - Build cache: directory to rsync into worktrees
- Protected files: files agents may not modify in PRs
For Claude, agent session config (commands, skills) lives in
.pod/claude-config/ and is managed by pod -- run pod update after
upgrading pod to get the latest agent prompts.
For Codex, isolated_config = true creates a strict pod-managed
CODEX_HOME per worktree. It contains only pod-managed Codex skills, a
minimal pod-owned config.toml, and an auth.json symlink for login
reuse. Pod does not inherit global ~/.codex prompts, skills, plugins,
or session state into isolated homes. This intentionally drops user
Codex configuration such as custom providers, base URLs, MCP settings,
and other global config; isolated Codex sessions use only pod-managed
configuration plus the shared auth token.
pod coordination <subcommand> runs the bundled coordination script
that agents use to interact with the GitHub issue queue. You can call
it directly for debugging or manual intervention.
| Subcommand | Description |
|---|---|
orient |
Show current state: oversight directives, unclaimed issues, claimed issues, open PRs |
plan --label <type> [--critical-path] "title" |
Create an issue from stdin body with agent-plan + type label |
list-unclaimed [--label <type>] |
List unclaimed issues, optionally filtered by label |
queue-depth [<label>] |
Print count of unclaimed issues |
critical-path-depth |
Print count of unclaimed critical-path issues |
claim <N> |
Claim issue #N for the current session (label + race detection) |
skip <N> "reason" |
Release claim on #N and mark it replan |
add-dep <N> <M> |
Add depends-on: #M to issue #N; mark blocked if #M is open |
check-blocked |
Unblock issues whose dependencies are all closed |
release-stale-claims [seconds] |
Release claims older than threshold (default 4h) |
| Subcommand | Description |
|---|---|
create-pr <N> [--partial] ["title"] |
Open a PR for issue #N (enforces protected files) |
claim-fix <N> |
Claim a broken PR for fixing (advisory, not strict lock) |
close-pr <N> "reason" |
Close PR #N with a reason |
| Subcommand | Description |
|---|---|
lock-planner |
Acquire the planner lock (managed by pod, not agents) |
unlock-planner |
Release the planner lock |
lock-status |
Show who holds the planner lock |
force-unlock-planner |
Force-release a stuck lock |
| Subcommand | Description |
|---|---|
set-target <N> |
Recommend N agents; pod uses min(user target, planner target) |
set-min-queue <N> |
Recommend min_queue of N; pod floors at 1 |
return-to-human |
Signal pod to stop spawning and return control to operator |
check-return-to-human |
Check if the return-to-human signal is set |
clear-return-to-human |
Clear the signal to resume operation |
Apache 2.0