KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

ittybitty

★ 39 Open GitHub ↗

A barebones multi-agent orchestration tool for claude code.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ittybitty (`ib`)

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

![screenshot of ittybitty in action](https://raw.githubusercontent.com/adamwulf/ittybitty/main/screenshot.png)

**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`

## How It Works

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.

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.

## Installation

### Prerequisites

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

### Add to PATH

```bash
# 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
```

### Project Setup

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:

```bash
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:

| Option | Purpose |
|--------|---------|
| **Safety hooks** | Enforces path isolation (agents can only access files in their own worktree), injects agent status after Bash/Task tools, and delivers ittybitty instructions to Claude at conversation start via SessionStart hook. |
| **Task interception** | Redirects Claude's native Task tool to spawn ib agents instead of native subagents. |
| **.gitignore** | Adds `.ittybitty/` to your .gitignore |
| **Config file** | Creates `.ittybitty.json` for `ib config` settings |
| **Ext diff tool** | Configure an external diff tool for reviewing agent changes |

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

## Your First Agent

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.

```bash
# 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):**

```bash
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.

```bash
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:

| State | Meaning |
|-------|---------|
| `creating` | Agent is starting up |
| `running` | Actively working |
| `waiting` | Idle, may need input |
| `complete` | Agent signaled it finished |
| `stopped` | Session ended (eg from system reboot), use `ib resume` to continue |
| `compacting` | The claude session is compacting and will resume soon |
| `rate_limited` | The 5 hour session or weekly limit has been reached, and claude is paused. |
| `unknown` | In rare cases, the status cannot be determined. This is treated as a `waiting` status. |

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

```bash
# 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.

```bash
# 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.

## Safety Comes First

**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.

## Using with Claude Code

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.

### Real-time Status Updates

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.

### Agent Questions

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

```bash
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

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.

```bash
# 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).

## Configuration

### Config Files

ittybitty uses two config files with this precedence:

| File | Scope | Priority |
|------|-------|----------|
| `.ittybitty.json` | Project (repo root) | Highest - overrides user settings |
| `~/.ittybitty.json` | User (home directory) | Lower - provides personal defaults |

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

### Quick Config with `ib config`

```bash
# 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
```

### Configuration Options

| Option | Default | Description |
|--------|---------|-------------|
| `maxAgents` | 10 | Maximum concurrent agents (safety limit) |
| `model` | (none) | Default model for new agents (opus, sonnet, haiku) |
| `fps` | 10 | Refresh rate for `ib watch` |
| `createPullRequests` | false | Create PRs instead of leaving changes on branch |
| `allowAgentQuestions` | true | Allow root managers to ask user questions via `ib ask` |
| `autoCompactThreshold` | (none) | Context % to trigger `/compact` (1-100, unset=auto) |
| `externalDiffTool` | (none) | External diff tool for reviewing agent changes |
| `hooks.injectStatus` | true | Enable status injection via hooks |
| `hooks.statusVisible` | true | Show status updates in user messages |
| `permissions.manager.allow` | [] | Additional tools to allow for manager agents |
| `permissions.manager.deny` | [] | Tools to deny for manager agents |
| `permissions.worker.allow` | [] | Additional tools to allow for worker agents |
| `permissions.worker.deny` | [] | Tools to deny for worker agents |

### MCP Servers

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.

### Spawn Options

```bash
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
```

## Extensibility

### Custom Agent Prompts

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

| File | Applied To |
|------|------------|
| `all.md` | All agents |
| `manager.md` | Manager agents only |
| `worker.md` | Worker agents only |

**Example `.ittybitty/prompts/all.md`:**
```markdown
## Project Standards
- Use TypeScript strict mode
- Run `npm test` before committing
- Follow existing code style
```

### Agent Creation Hooks

Run custom scripts when agents are created:

```bash
# 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:

| Variable | Description |
|----------|-------------|
| `IB_AGENT_ID` | Agent's unique ID |
| `IB_AGENT_TYPE` | "manager" or "worker" |
| `IB_AGENT_DIR` | Path to agent's data directory |
| `IB_AGENT_BRANCH` | Git branch name |
| `IB_AGENT_MANAGER` | Parent manager ID (if any) |
| `IB_AGENT_PROMPT` | The task prompt |
| `IB_AGENT_MODEL` | Model being used |

## Troubleshooting

### Agent stuck in "creating" state

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

### "Path violation" errors in agent logs

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

### Merge conflicts

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.
### View agent logs

```bash
# 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`.

## Enjoying `ittybitty`?

[Buy me a coffee](https://github.com/sponsors/adamwulf) ☕️

ittybitty

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README