pit

A tmux-based orchestrator that automates parallel AI coding agent sessions.

pit manages git worktrees, tmux windows, and agent TUIs (Claude Code or opencode), driving each agent through a ticket loop powered by beads for issue tracking. The primary consumer of pit is an LLM in an orchestrator session -- the human talks to the model, the model calls pit.

                    +-----------------+
                    |  Orchestrator   |
                    |  (LLM session)  |
                    +--------+--------+
                             |
                         pit CLI
                             |
                    +--------+--------+
                    |     Daemon      |
                    | (Unix socket)   |
                    +--------+--------+
                             |
              +--------------+--------------+
              |              |              |
        +-----+-----+ +-----+-----+ +-----+-----+
        | Worktree 1 | | Worktree 2 | | Worktree 3 |
        | tmux win 1 | | tmux win 2 | | tmux win 3 |
        |  Agent TUI | |  Agent TUI | |  Agent TUI |
        +------------+ +------------+ +------------+

WARNING: EXPERIMENTAL SOFTWARE

    _____
   /     \
  | () () |
   \  ^  /
    |||||
    |||||

This software is highly experimental. It is under active development, APIs will change without notice, and things will break.

This software deliberately bypasses AI agent security features. pit launches Claude Code with --dangerously-skip-permissions, which disables ALL permission checks -- file writes, shell commands, network access, everything. Agents execute arbitrary commands without human confirmation.

This software is for people who like taking risks. If you are not comfortable with autonomous AI agents running shell commands in your codebase without asking first, this is not for you. If "move fast and break things" makes you nervous rather than excited, look elsewhere.

This software is built using itself. pit is developed with pit -- the codebase is almost entirely written by AI coding agents orchestrated by pit. If running AI-generated code makes you uncomfortable, this is not for you.

This software will burn through tokens. pit runs autonomous agents that work fast but are not frugal. Multiple agents running in parallel, each looping through tickets, each with full context windows. Monitor your API usage. You have been warned twice now.

Do NOT use pit on untrusted repositories or with untrusted ticket content. The agents will execute whatever they're told to, without confirmation. You have been warned.

Philosophy

pit is opinionated software. It encodes a specific workflow for AI-assisted development and does not try to be all things to all people.

The core belief: the quality of autonomous AI coding comes down to the quality of the tickets. pit's prompt loop is deliberately simplistic -- "find the next ticket and work on it" -- because all the nuance, context, and constraints should live in the tickets themselves. If you write vague tickets, you get vague results. If you write detailed, unambiguous tickets with clear acceptance criteria, agents can execute independently.

Context is cleared between tickets. When an agent finishes a ticket, pit clears its conversation context before sending the next one. Each ticket starts fresh -- the agent has no memory of previous tickets. This means tickets must be self-contained: include all relevant context, file paths, and constraints in the ticket itself. In practice this is rarely a problem if your tickets are well-written, and it prevents context window pollution from accumulating over a long epic.

The Intended Workflow

1. Write requirements. Start with a set of high-level requirements for the feature or project you want to build.

2. Refine into detailed beads. Break the requirements down into highly detailed beads tickets. Each ticket should contain enough context for a coding agent to pick it up and execute independently -- the problem statement, relevant file paths, expected behavior, edge cases, and constraints. This is where you invest your time.

3. Set up your AGENTS.md. Your project's AGENTS.md (or equivalent agent instructions file) should contain the "landing the plane" instructions -- quality gates to run, what to commit, when to push, coding conventions. This is the persistent context every agent session gets. pit injects its orchestrator instructions here via pit init.

4. Let pit run. pit start --epics <epic-id> spins up agents and they work through tickets autonomously. Monitor with pit status, intervene when agents pause.

5. Merge and clean up. Once an epic is done, the human operator (or an agent you instruct) merges the worktree branch back to main, runs quality gates, pushes, and calls pit teardown to clean up all pit artifacts.

pit does not try to be smart about what agents do. It manages the plumbing -- worktrees, tmux sessions, idle detection, ticket cycling -- and gets out of the way. The intelligence lives in your tickets and your AGENTS.md.

How It Works

1. You set up an epic (a group of tickets) using beads (bd or br)
2. You run pit start --epics <epic-id>
3. pit creates one git worktree + tmux window + agent TUI per epic
4. Each agent autonomously loops: pick ticket, work on it, commit, push, pick next
5. You monitor with pit status, intervene with pit pause/pit resume
6. When an epic completes, you merge the worktree branch back

Agents work in isolated git worktrees so they don't interfere with each other or your main checkout. Each agent has its own branch, its own files, its own tmux window.

Watching and Intervening

pit runs agents inside a tmux session (named pit by default). You can attach to it at any time to watch agents work in real time:

tmux attach -t pit

Use tmux's normal window-switching keys (Ctrl-b n / Ctrl-b p) to move between epic windows. Each window is named epic-<id> and shows the agent's TUI.

From any terminal (you don't need to be attached to tmux), you can:

# Check what all agents are doing
pit status --pretty

# Read an agent's recent output without attaching to tmux
pit log my-epic --lines 100

# Pause an agent that's going in circles
pit pause my-epic

# Resume with specific guidance
pit resume my-epic --message "The config file is in src/config.ts, not lib/config.ts"

# Resume without a message (re-prompts with the next ticket)
pit resume my-epic

You can also install tmux integrations for quicker access:

pit install-keybinding    # Binds prefix+R to resume and prefix+H to pause the current epic
pit install-status        # Appends #{@pit-status} to the tmux status bar

Prerequisites

• Node.js >= 24
• tmux installed and available in PATH
• beads installed and available in PATH — either bd or br (the Rust rewrite)
• An AI coding agent: Claude Code (claude) or opencode (opencode)
• A git repository with beads epics and tickets set up

Install

npm install -g pit

Or clone and build from source:

git clone https://github.com/anomalyco/pit.git
cd pit
npm install
npm run build
npm link

Quick Start

# 1. Initialize pit in your project (injects orchestrator instructions into AGENTS.md)
pit init

# 2. Optionally configure pit (or just use defaults)
cat > .pit.json << 'EOF'
{
  "agent": "auto",
  "baseBranch": "main"
}
EOF

# 3. Make sure you have beads epics set up
bd list

# 4. Start agents for one or more epics
pit start --epics my-epic-id

# 5. Monitor progress
pit status
pit status --pretty

# 6. Read agent output
pit log my-epic-id

# 7. Pause/resume as needed
pit pause my-epic-id
pit resume my-epic-id --message "Try a different approach for the auth module"

# 8. Clean up when done
pit teardown

CLI Reference

All commands output JSON by default (for LLM consumption). Add --pretty for human-readable output.

| Command | Description | | ------------------------- | ----------------------------------------------------------- | | pit init | Inject orchestrator instructions into AGENTS.md | | pit start --epics <ids> | Start agent sessions for given epic IDs | | pit status | Show status of all running epics | | pit log <epic> | Capture agent's recent terminal output | | pit pause <epic> | Pause a running epic | | pit resume <epic> | Resume a paused epic (optionally with --message) | | pit stop [epic] | Stop epic(s), transition to done | | pit add <epic> | Add an epic to a running session | | pit teardown [epic] | Tear down epics and clean up resources | | pit cleanup | Garbage-collect stale session directories | | pit daemon <cmd> | Manage the background daemon (start/stop/status/restart) | | pit install-keybinding | Install tmux keybindings for quick resume (R) and pause (H) | | pit install-status | Append #{@pit-status} to the tmux status bar |

For detailed flag reference, examples, and edge cases, see docs/cli.md.

Configuration

pit reads .pit.json from the project root. CLI flags override file values.

{
  // Which coding agent to run in each tmux window.
  //   "auto"        - tries opencode first, falls back to claude-code
  //   "opencode"    - use opencode (https://opencode.ai)
  //   "claude-code" - use Claude Code (https://docs.anthropic.com/en/docs/claude-code)
  "agent": "auto",

  // Model passed to the agent CLI. Format depends on the agent:
  //   Claude Code: "claude-sonnet-4-20250514", "claude-opus-4-20250514", etc.
  //   opencode:    "anthropic/claude-sonnet-4-20250514", etc.
  // null = let the agent use its default model.
  "model": null,

  // Which beads binary to use for issue tracking.
  //   "auto" - tries bd first, falls back to br
  //   "bd"   - use bd (https://github.com/anomalyco/beads)
  //   "br"   - use br (https://github.com/anomalyco/beads_rust)
  "beadsBinary": "auto",

  "worktreeDir": ".worktrees", // Where git worktrees are created
  "baseBranch": "main", // Branch worktrees are created from
  "tmuxSession": "pit", // tmux session name

  "clearDelay": 2000, // Ms to wait after clearing agent context
  "initDelay": 5000, // Ms to wait for agent TUI to start
  "ticketTimeout": null, // Minutes before auto-pausing a ticket (null = no limit)
}

| Field | Default | Description | | --------------- | -------------- | ---------------------------------------------------------------- | | agent | "auto" | Agent type: auto, opencode, or claude-code | | model | null | Model to pass to the agent CLI (null = agent default) | | beadsBinary | "auto" | Beads binary: auto, bd, or br (auto prefers bd) | | worktreeDir | ".worktrees" | Directory for git worktrees | | baseBranch | "main" | Base branch for worktrees | | tmuxSession | "pit" | tmux session name | | clearDelay | 2000 | Ms to wait before clearing agent context after ticket completion | | initDelay | 5000 | Ms to wait before starting the agent after setup | | ticketTimeout | null | Minutes before a ticket auto-pauses the agent (null = disabled) |

Security Model

pit is designed for autonomous agent operation. This comes with deliberate trade-offs:

• Claude Code is launched with --dangerously-skip-permissions, bypassing all permission checks. The agent can read/write any file, run any shell command, and make network requests without human approval.
• opencode uses its plugin system for event detection. Permission handling is managed through the plugin bridge.
• Each agent runs in an isolated git worktree, not your main checkout. The worktree is disposable and can be recreated from the base branch.
• The daemon communicates over a Unix domain socket in /tmp/pit/. No network exposure.

This is intentional. pit exists to let agents work autonomously. If you need human-in-the-loop approval for every file write, pit is the wrong tool.

Mitigations:

• Worktree isolation limits blast radius
• Worktrees are on branches, not main -- you review before merging
• pit pause lets you halt an agent at any time
• pit teardown cleans everything up

Documentation

| Document | Audience | Description | | ---------------------------------------------- | ----------------- | ----------------------------------------------------------- | | docs/cli.md | Agents + humans | Detailed per-command reference | | docs/architecture.md | Agents + humans | Internal architecture and design | | docs/orchestration.md | Orchestrator LLMs | How to drive pit from an LLM session | | AGENTS.md | Coding agents | Conventions and workflow for agents working on pit itself |

Releasing

Releases are published to npm and GitHub Releases automatically by CI when a version tag is pushed. Use the release script to bump the version and push the tag:

# Patch release (e.g. 1.2.3 -> 1.2.4)
npm run release -- patch

# Minor release (e.g. 1.2.3 -> 1.3.0)
npm run release -- minor

# Major release (e.g. 1.2.3 -> 2.0.0)
npm run release -- major

# Explicit version
npm run release -- 1.2.3

The script will:

1. Verify a clean working tree and that you're on main
2. Pull latest from origin
3. Run local quality gates (npm test, npm run test:e2e, npm run lint, npm run build)
4. Bump the version and create a git commit + tag via npm version
5. Push the commit and tag (git push --follow-tags), triggering the CI publish workflow
6. Print a link to GitHub Actions so you can monitor the publish

CI handles the actual npm publish and GitHub Release creation — you do not need to run npm publish manually.

What CI does automatically

When a v* tag is pushed, the Publish workflow:

1. Verifies the tag matches the version in package.json
2. Runs quality gates (lint, build, unit tests, E2E tests)
3. Publishes the package to npm (npm publish --access public)
4. Creates a GitHub Release with auto-generated release notes

Required secrets

The repository must have an NPM_TOKEN secret set in GitHub Actions:

1. Go to npmjs.com → Account → Access Tokens → Generate New Token
2. Choose Automation token type (bypasses 2FA requirement for CI publishing)
3. Add the token to GitHub: Repository → Settings → Secrets and variables → Actions → NPM_TOKEN

Verifying a release

Monitor the publish workflow at: https://github.com/elhu/pit/actions/workflows/publish.yml

License

MIT