A single bash script that lets you spawn, organize, and control multiple Claude Code agents.

Benefits:

• Staying safe: Tool use is pre-approved only, all others denied. Yolo mode is optional, not required.
• Simple command line interface to start, stop, monitor, merge, and kill agents. Simple for Claude to understand and use within your normal Claude sessions. Use Claude to spawn teams of Claude agents!
• View and control any agent, use $ ib watch to view and control all agents running in a repo
• Each agent gets its own git worktree (keep working in your normal git repo while agents fix bugs for you.)
• Agents can spawn helper agents and message each other
• Optional custom prompt for all new agents
• Automatic notifications to agents when their dependencies complete
• Agents can even resume after a system reboot and pick up where they left off
• Minimal dependencies, only requires claude, tmux, and git

When you spawn an agent with ib, it:

1. Creates a git worktree on a new branch (agent/<id>) - isolated from your main working tree (inside .ittybitty/agents/<id>/)
2. Starts a tmux session running Claude Code in that worktree
3. Monitors the agent's state (running, waiting, complete, stopped)

Agents are either managers or workers. Manager agents coordinate work and can spawn other managers and workers; worker agents execute focused tasks and cannot create new agents. When an agent completes, you review its changes and merge them back to your branch.

flowchart LR
    A[You - Human] <-->|claude code| B[Primary Claude]
    B -->|spawns via ib| C[Manager Agent]
    C -->|spawns via ib| D[Worker Agents]
    E[ib watch] -->|new agent 'a' key| C
    A -->|command line| E

You don't need to change your workflow to use ittybitty. You can think of its agents as just another Claude Code terminal that can work independently, stays within allowed tool permissions, and can spawn and message other agents. You can view, merge, or kill any agent at any time.

• tmux - terminal multiplexer
• git - version control
• claude - Claude Code CLI

# Clone the repository
git clone https://github.com/anthropics/ittybitty /path/to/ittybitty

# Add to PATH (add to your shell profile for persistence)
export PATH="/path/to/ittybitty:$PATH"

# Run ib to see its help
ib

All setup steps are optional (but recommended). You can test ib just by downloading and running it.

Run ib watch in your project directory and press h to open the setup dialog:

cd your-project
# open realtime ib console
ib watch
# Press 'h' to open setup dialog

The setup dialog has 3 tabs: Setup (toggles), Project Settings, and User Settings. The Setup tab lets you configure:

Toggle options with Space or Enter. Enable Safety hooks and .gitignore for full functionality.

Spawning a new agent is easy. By default, all new agents are managers, which means they can also spawn agents. You can force a worker agent by adding --worker to any of the new-agent commands below.

# Basic usage
ib new-agent "Refactor the authentication module to use JWT tokens"

# 'new' is a shorthand alias for 'new-agent'
ib new "Refactor the authentication module to use JWT tokens"

# With a custom name
ib new-agent --name auth-refactor "Refactor authentication to use JWT"

# Using a specific model
ib new-agent --model haiku "Write unit tests for the utils module"

The command returns an agent ID (or uses your --name) that you'll use for all subsequent commands.

Next, monitor your agent with the Interactive dashboard (recommended):

ib watch

The watch UI shows all agents, their states, and recent activity. Keyboard shortcuts are listed in the UI's footer.

You can also monitor with the command line. This makes it easy to integrate ib into other tools.

ib list                     # Show all agents and their states (alias: ib ls)
ib look <id>                # View agent's recent output
ib status <id>              # Show agent's git commits and changes
ib info <id>                # Display agent metadata
ib tree                     # Show agent hierarchy as a tree

As you monitor agents, each agent will move between these states:

You can interact with agents by sending messages, and viewing their git status, git diff, or even their Claude session

# Send input to an agent (answers questions, provides guidance)
ib send <id> "Focus on the login flow first"

# Send a message with explicit sender (auto-detected in agent worktrees)
ib send --from <sender-id> <id> "message"

# View what the agent has done
ib diff <id>                # Full diff of changes
ib status <id>              # Commits and file changes

# View the agent's running claude session
ib look <id>

# Pause/resume agents
ib pause <id>               # Pause a running agent without killing it
ib resume <id>              # Resume a paused or stopped agent

# Reassign an agent to a different parent manager
ib reassign <id> <new-parent>

Once you're happy (or sad!) with an agent's work, you can merge or kill the agent. ib merge will merge the agent's work into your currently active branch. The merge will preemptively fail if there is a merge conflict. This keeps your git status clean, and you can tell an agent to fix any merge conflicts and try again when it's finished.

# Check if the merge would succeed
ib merge-check <id>

# Merge agent's branch into your current branch
ib merge <id>

# Or discard the agent's work
ib kill <id>

Use --force to skip confirmation prompts.

Tools

ittybitty is built for safety first, and does not require --yolo mode. Any tool that is not explicitly allowed in Claude's normal settings.json will be auto-denied. This keeps you in control of what agents can and can't do.

Some tools are required for ib to function properly, and will always be enabled: Bash(ib:*), Bash(./ib:*), Bash(git status:*), Bash(git add:*), Bash(git commit:*), Bash(git diff:*), Bash(git show:*), Bash(git log:*), Bash(git ls-files:*), Bash(git grep:*), Bash(git rm:*), Bash(git merge:*), Bash(git rebase:*), Bash(pwd:*), Bash(ls:*), Bash(head:*), Bash(tail:*), Bash(cat:*), Bash(grep:*), Read, Write, Edit, MultiEdit, Glob, Grep, LS, TodoWrite, Task, TaskOutput, KillShell, NotebookEdit, WebFetch, WebSearch, AskUserQuestion

Plan mode tools are always disabled: EnterPlanMode, ExitPlanMode

Hooks

ittybitty uses hooks to prevent agents from moving into other agent's worktrees, including the primary repository. All agent worktrees are located in .ittybitty/agents/<id>.

Archives

All Claude sessions go through the normal archive process that is managed by Claude. In addition, ittybitty archives the full Claude session log, the ittybitty agent log, which includes sent messages and status updates, metadata about the agent including its model and creation time.

Simplicity

The safest systems are the ones you can understand. ittybitty runs normal Claude in normal terminal sessions, and sends them commands just like you do when you type in a claude session. You have full visibility into the running agents, their state, and their relationships. You have full control and visibility into agents you already understand.

Nuke it from orbit

If for some reason your agents get out of control, you can run ib nuke to immediately kill and archive all agents. All of their session history and logs are archived in .ittybitty/archives/[timestamp]-[agent] so you can review exactly what happened, if you ever need to.

Once you've enabled Safety hooks in the setup dialog (ib watch → h), Claude automatically receives ittybitty instructions at the start of every conversation via the SessionStart hook. No manual CLAUDE.md editing is needed.

You: "Refactor the API layer. This is a big task, so spawn some agents to help."

Claude: spawns agents using ib new-agent

Claude will tell you to run ib watch in another terminal to monitor progress. Agents work in the background while your conversation continues.

When safety hooks are enabled, Claude receives real-time agent status updates via hooks:

• At conversation start: Full agent tree with status, age, and prompt
• After Bash/Task tools: Updated status if agents have changed state

This means Claude always knows the current state of your agents without you having to ask. A brief status summary appears in the conversation when agents change state.

Agents can ask questions that appear in your Claude conversation. When you see a question:

ib questions               # List pending questions
ib acknowledge <q-id>      # Mark question as handled
ib send <agent-id> "answer"  # Send your response

You can always ask Claude to check on agents, and it will ib list to see their status, and can check on them and message them if needed.

Task interception lets ib automatically redirect Claude's native Task tool calls to spawn ib agents instead. When Claude tries to use Task(subagent_type=Explore) or similar, it creates an ib manager agent rather than a native subagent.

# Enable task interception
ib hooks install-intercept

# Disable task interception
ib hooks uninstall-intercept

Some Task types are always handled natively (Bash, statusline-setup, claude-code-guide, meta-agent, ib-merge). You can also toggle this in the ib watch setup dialog (h key).

ittybitty uses two config files with this precedence:

Use project config for repo-specific settings. Use user config for personal preferences like externalDiffTool.

# View all settings with their sources
ib config list                              # Shows (project), (user), or (default)

# Get/set project config (default)
ib config get maxAgents
ib config set maxAgents 20

# Get/set user config (with --global)
ib config --global set externalDiffTool "code --diff"
ib config --global list                     # Show user config only

Agent worktrees inherit MCP servers from two sources automatically:

• User-scoped MCPs (claude mcp add --scope user ...) — stored in ~/.claude.json, available in all projects and all worktrees
• Project-scoped MCPs (claude mcp add --scope project ...) — stored in .mcp.json committed to the repo, available in all worktrees since they share the same git history

Local-scoped MCPs (claude mcp add --scope local ...) are scoped to a specific directory path and will not be available in agent worktrees. If you need an MCP in agents, add it at user or project scope instead.

ib new-agent [options] "prompt"

Options:
  --name <name>        Custom agent name (default: auto-generated)
  --worker             Worker agent that cannot spawn sub-agents
  --model <model>      Model to use (opus, sonnet, haiku)
  --manager <id>       Set parent manager for hierarchy tracking
  --no-worktree        Work in repo root instead of isolated worktree
  --yolo               Full autonomy, skip all permission prompts
  --print              One-shot mode: run and exit
  --allow-tools LIST   Only allow these tools (comma-separated)
  --deny-tools LIST    Deny these tools (comma-separated)
  --prompt-file FILE   Read prompt from a file instead of command line

Add project-specific instructions to agents by creating markdown files in .ittybitty/prompts/:

Example .ittybitty/prompts/all.md:

## Project Standards
- Use TypeScript strict mode
- Run `npm test` before committing
- Follow existing code style

Run custom scripts when agents are created:

# Create the hooks directory
mkdir -p .ittybitty/hooks

# Create your hook
cat > .ittybitty/hooks/post-create-agent << 'EOF'
#!/bin/bash
echo "[$(date -Iseconds)] Agent $IB_AGENT_ID ($IB_AGENT_TYPE)" >> .ittybitty/creation.log
EOF

# Make it executable
chmod +x .ittybitty/hooks/post-create-agent

Available environment variables in hooks:

The agent may be waiting on a workspace trust prompt. Check with ib look <id>.

The agent tried to access files outside its worktree. This is expected behavior - agents are isolated to their own worktree.

If ib merge fails due to conflicts, you can ask the agent to fix the conflicts and try to merge again when it's done.

# Each agent has a log file
cat .ittybitty/agents/<id>/agent.log

# Archived agents (after kill/merge)
ls .ittybitty/archive/

Agent logs are also the default visible pane when launching ib watch.

Buy me a coffee ☕️