maniple-mcp 0.12.1
MCP server for managing multiple Claude Code sessions via iTerm2
License: MIT
Requires Python: >=3.11
Keywords: ai, anthropic, automation, claude, claude-code, iterm2, mcp, multi-agent, orchestration

# Maniple MCP Server

An MCP server that allows one Claude Code session to spawn and manage a team of other Claude Code (or Codex) sessions via terminal backends (tmux or iTerm2).

## Introduction

`maniple` is an MCP server and a set of slash commands for allowing Claude Code to orchestrate a "team" of other Claude Code or Codex sessions. It uses terminal backends (tmux or iTerm2) to spawn new terminal sessions and run Claude Code or Codex within them.

### Why?

- **Parallelism:** Many development tasks can be logically parallelized, but managing that parallelism is difficult for humans with limited attention spans. Claude, meanwhile, is very effective at it.
- **Context management:** Offloading implementation to a worker gives the implementing agent a fresh context window (smarter), and keeps the manager's context free of implementation details.
- **Background work:** Sometimes you want to have Claude Code go research something or answer a question without blocking the main thread of work.
- **Visibility:** `maniple` spawns real Claude Code or Codex sessions. You can watch them, interrupt and take control, or close them out.

But, *why not just use Claude Code sub-agents*, you ask? They're opaque -- they go off and do things and you, the user, cannot effectively monitor their work, interject, or continue a conversation with them. Using a full Claude Code session obviates this problem.

### Terminal Backends

`maniple` supports two terminal backends:

| Backend | Platform | Status |
|---------|----------|--------|
| **tmux** | macOS, Linux | Primary. Auto-selected when running inside tmux. |
| **iTerm2** | macOS only | Fully supported. Requires Python API enabled. |

Backend selection order:
1. `MANIPLE_TERMINAL_BACKEND` environment variable (`tmux` or `iterm`)
2. Config file setting (`terminal.backend`)
3. Auto-detect: if `TMUX` env var is set, use tmux; otherwise iTerm2

### Git Worktrees: Isolated Branches per Worker

A key feature of `maniple` is **git worktree support**. When spawning workers with `use_worktree: true` (the default), each worker gets:

- **Its own working directory** - A git worktree at `{repo}/.worktrees/{name}/`
- **Its own branch** - Automatically created from the current HEAD
- **Shared repository history** - All worktrees share the same `.git` database, so commits are immediately visible across workers

Worktree naming depends on how workers are spawned:
- With an issue ID: `{repo}/.worktrees/{issue_id}-{badge}/`
- Without: `{repo}/.worktrees/{worker-name}-{uuid}-{badge}/`

The `.worktrees` directory is automatically added to `.gitignore`.

### Codex Support

Workers can run either Claude Code or OpenAI Codex. Set `agent_type: "codex"` in the worker config (or set the default in the config file) to spawn Codex workers instead of Claude Code workers.

## Features

- **Spawn Workers**: Create Claude Code or Codex sessions with multi-pane layouts
- **Terminal Backends**: tmux (cross-platform) and iTerm2 (macOS)
- **Git Worktrees**: Isolate each worker in its own branch and working directory
- **Send Messages**: Inject prompts into managed workers (single or broadcast)
- **Read Logs**: Retrieve conversation history from worker JSONL files
- **Monitor Status**: Check if workers are idle, processing, or waiting for input
- **Idle Detection**: Wait for workers to complete using stop-hook markers
- **Event Polling**: Track worker lifecycle events (started, completed, stuck)
- **Visual Identity**: Each worker gets a unique tab color and themed name (Marx Brothers, Beatles, etc.)
- **Session Recovery**: Discover and adopt orphaned sessions after MCP server restarts
- **HTTP Mode**: Run as a persistent service with streamable-http transport
- **Config File**: Centralized configuration at `~/.maniple/config.json`

## Requirements

- Python 3.11+
- `uv` package manager
- **tmux backend**: tmux installed (macOS or Linux)
- **iTerm2 backend**: macOS with iTerm2 and Python API enabled (Preferences > General > Magic > Enable Python API)
- **Codex workers** (optional): OpenAI Codex CLI installed

## Installation

### As Claude Code Plugin (recommended)

```bash
# Add the Martian Engineering marketplace
/plugin marketplace add Martian-Engineering/maniple

# Install the plugin
/plugin install maniple@martian-engineering
```

This automatically configures the MCP server - no manual setup needed.

### From PyPI

```bash
uvx --from maniple-mcp@latest maniple
```

### From Source

```bash
git clone https://github.com/Martian-Engineering/maniple.git
cd maniple
uv sync
```

## Configuration for Claude Code

Add to your Claude Code MCP settings. You can configure this at:
- **Global**: `~/.claude/settings.json`
- **Project**: `.claude/settings.json` in your project directory

### Using PyPI package

```json
{
  "mcpServers": {
    "maniple": {
      "command": "uvx",
      "args": ["--from", "maniple-mcp@latest", "maniple"]
    }
  }
}
```

### Using local clone

```json
{
  "mcpServers": {
    "maniple": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/maniple", "python", "-m", "maniple_mcp"]
    }
  }
}
```

### Project-level with auto project path

For project-scoped `.mcp.json` files, use `MANIPLE_PROJECT_DIR` so workers inherit the project path:

```json
{
  "mcpServers": {
    "maniple": {
      "command": "uvx",
      "args": ["--from", "maniple-mcp@latest", "maniple"],
      "env": { "MANIPLE_PROJECT_DIR": "${PWD}" }
    }
  }
}
```

After adding the configuration, restart Claude Code for it to take effect.

## Config File

`maniple` reads configuration from `~/.maniple/config.json`. Manage it with the CLI:

```bash
maniple config init          # Create default config
maniple config init --force  # Overwrite existing config
maniple config show          # Show effective config (file + env overrides)
maniple config get <key>     # Get value by dotted path (e.g. defaults.layout)
maniple config set <key> <value>  # Set and persist a value
```

### Migration Notes (from `claude-team`)

- Config directory: `~/.claude-team/` is auto-migrated to `~/.maniple/` on first run.
- Environment variables: `MANIPLE_*` takes precedence; `CLAUDE_TEAM_*` is supported as a fallback and may emit a deprecation warning to stderr.

### Config Schema

```json
{
  "version": 1,
  "commands": {
    "claude": null,
    "codex": null
  },
  "defaults": {
    "agent_type": "claude",
    "skip_permissions": false,
    "use_worktree": true,
    "layout": "auto"
  },
  "terminal": {
    "backend": null
  },
  "events": {
    "max_size_mb": 1,
    "recent_hours": 24
  },
  "issue_tracker": {
    "override": null
  }
}
```

| Section | Key | Description |
|---------|-----|-------------|
| `commands.claude` | string | Override Claude CLI command (e.g. `"happy"`) |
| `commands.codex` | string | Override Codex CLI command (e.g. `"happy codex"`) |
| `defaults.agent_type` | `"claude"` or `"codex"` | Default agent type for new workers |
| `defaults.skip_permissions` | bool | Default `--dangerously-skip-permissions` flag |
| `defaults.use_worktree` | bool | Create git worktrees by default |
| `defaults.layout` | `"auto"` or `"new"` | Default layout mode for spawn_workers |
| `terminal.backend` | `"tmux"` or `"iterm"` | Terminal backend override (null = auto-detect) |
| `events.max_size_mb` | int | Max event log file size before rotation |
| `events.recent_hours` | int | Hours of events to retain |
| `issue_tracker.override` | `"beads"` or `"pebbles"` | Force a specific issue tracker |

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MANIPLE_TERMINAL_BACKEND` | (auto-detect) | Force terminal backend: `tmux` or `iterm`. Highest precedence. |
| `MANIPLE_PROJECT_DIR` | (none) | Enables `"project_path": "auto"` in worker configs. |
| `MANIPLE_COMMAND` | `claude` | Override the CLI command for Claude Code workers. |
| `MANIPLE_CODEX_COMMAND` | `codex` | Override the CLI command for Codex workers. |

## MCP Tools

### Worker Management

| Tool | Description |
|------|-------------|
| `spawn_workers` | Create workers with multi-pane layouts. Supports Claude Code and Codex agents. |
| `list_workers` | List all managed workers with status. Filter by status or project. |
| `examine_worker` | Get detailed worker status including conversation stats and last response preview. |
| `close_workers` | Gracefully terminate one or more workers. Worktree branches are preserved. |
| `discover_workers` | Find existing Claude Code/Codex sessions running in tmux or iTerm2. |
| `adopt_worker` | Import a discovered session into the managed registry. |

### Communication

| Tool | Description |
|------|-------------|
| `message_workers` | Send a message to one or more workers. Supports wait modes: `none`, `any`, `all`. |
| `read_worker_logs` | Get paginated conversation history from a worker's JSONL file. |
| `annotate_worker` | Add a coordinator note to a worker (visible in `list_workers` output). |

### Monitoring

| Tool | Description |
|------|-------------|
| `check_idle_workers` | Quick non-blocking check if workers are idle. |
| `wait_idle_workers` | Block until workers are idle. Modes: `all` (fan-out/fan-in) or `any` (pipeline). |
| `poll_worker_changes` | Read worker event log for started/completed/stuck workers since a timestamp. |

### Utilities

| Tool | Description |
|------|-------------|
| `list_worktrees` | List git worktrees created by maniple for a repository. Supports orphan cleanup. |
| `issue_tracker_help` | Quick reference for the detected issue tracker (Beads or Pebbles). |

### Worker Identification

Workers can be referenced by any of three identifiers:
- **Internal ID**: Short hex string (e.g., `3962c5c4`)
- **Terminal ID**: Prefixed terminal session ID (e.g., `iterm:UUID` or `tmux:%1`)
- **Worker name**: Human-friendly name (e.g., `Groucho`, `Aragorn`)

All tools accept any of these formats.

### Tool Details

#### spawn_workers

```
WorkerConfig fields:
  project_path: str         - Required. Explicit path or "auto" (uses MANIPLE_PROJECT_DIR)
  agent_type: str           - "claude" (default) or "codex"
  name: str                 - Optional worker name override (auto-picked from themed sets if omitted)
  badge: str                - Task description (shown in badge, used in branch names)
  issue_id: str             - Issue tracker ID (for badge, branch naming, and workflow instructions)
  prompt: str               - Additional instructions (combined with standard worker prompt)
  skip_permissions: bool    - Start with --dangerously-skip-permissions
  use_worktree: bool        - Create isolated git worktree (default: true)
  worktree: WorktreeConfig  - Optional worktree settings:
                              branch: Explicit branch name (auto-generated if omitted)
                              base: Ref/branch to branch FROM (default: HEAD). Set this
                                    when subtask workers need a feature branch's commits
                                    (e.g. {"base": "epic-id/feature-branch"})

Top-level arguments:
  workers: list[WorkerConfig]  - 1-4 worker configurations
  layout: str                  - "auto" (reuse windows) or "new" (fresh window)

Returns:
  sessions, layout, count, coordinator_guidance
```

Worker assignment is determined by `issue_id` and/or `prompt`:
- **issue_id only**: Worker follows issue tracker workflow (mark in_progress, implement, close, commit)
- **issue_id + prompt**: Issue tracker workflow plus additional custom instructions
- **prompt only**: Custom task with no issue tracking
- **neither**: Worker spawns idle, waiting for a message

#### message_workers

```
Arguments:
  session_ids: list[str]   - Worker IDs to message (accepts any identifier format)
  message: str             - The prompt to send
  wait_mode: str           - "none" (default), "any", or "all"
  timeout: float           - Max seconds to wait (default: 600)

Returns:
  success, session_ids, results, [idle_session_ids, all_idle, timed_out]
```

#### wait_idle_workers

```
Arguments:
  session_ids: list[str]   - Worker IDs to wait on
  mode: str                - "all" (default) or "any"
  timeout: float           - Max seconds to wait (default: 600)
  poll_interval: float     - Seconds between checks (default: 2)

Returns:
  session_ids, idle_session_ids, all_idle, waiting_on, mode, waited_seconds, timed_out
```

#### poll_worker_changes

```
Arguments:
  since: str                    - ISO timestamp to filter events from (or null for latest)
  stale_threshold_minutes: int  - Minutes without activity before marking stuck (default: 20)
  include_snapshots: bool       - Include periodic snapshot events (default: false)

Returns:
  events, summary (started/completed/stuck), active_count, idle_count, poll_ts
```

## HTTP Server Mode

Run `maniple` as a persistent HTTP service instead of stdio:

```bash
maniple --http              # Default port 8766
maniple --http --port 9000  # Custom port
```

HTTP mode enables:
- **Streamable HTTP transport** for MCP communication
- **Worker poller** that periodically snapshots worker state and emits lifecycle events
- **MCP Resources** for read-only session access:
  - `sessions://list` - List all managed sessions
  - `sessions://{session_id}/status` - Detailed session status
  - `sessions://{session_id}/screen` - Terminal screen content

## Slash Commands

Install slash commands for common workflows:

```bash
make install-commands
```

| Command | Description |
|---------|-------------|
| `/spawn-workers` | Analyze tasks, create worktrees, and spawn workers with appropriate prompts |
| `/check-workers` | Generate a status report for all active workers |
| `/merge-worker` | Directly merge a worker's branch back to parent (for internal changes) |
| `/pr-worker` | Create a pull request from a worker's branch |
| `/team-summary` | Generate end-of-session summary of all worker activity |
| `/cleanup-worktrees` | Remove worktrees for merged branches |

## Issue Tracker Support

`maniple` supports both Pebbles (`pb`) and Beads (`bd --no-db`).
The tracker is auto-detected by marker directories in the project root:

- `.pebbles` -> Pebbles
- `.beads` -> Beads

If both markers exist, Pebbles is selected by default. This can be overridden in the config file with `issue_tracker.override`. Worker prompts and coordination guidance use the detected tracker commands.

## Usage Patterns

### Basic: Spawn and Message

From your Claude Code session, spawn workers and send them tasks:

```
"Spawn two workers for frontend and backend work"
-> Uses spawn_workers with two WorkerConfigs pointing at different project paths
-> Returns workers named e.g. "Simon" and "Garfunkel"

"Send Simon the message: Review the React components"
-> Uses message_workers with session_ids=["Simon"]

"Check on Garfunkel's progress"
-> Uses examine_worker with session_id="Garfunkel"
```

### Parallel Work with Worktrees

Spawn workers in isolated branches for parallel development:

```
"Spawn three workers with worktrees to work on different features"
-> Uses spawn_workers with use_worktree=true (default)
-> Creates worktrees at {repo}/.worktrees/
-> Each worker gets their own branch

"Message all workers with their tasks, then wait for completion"
-> Uses message_workers with wait_mode="all"

"Create PRs for each worker's branch"
-> Uses /pr-worker for each completed worker
```

### Issue Tracker Integration

Assign workers to issue tracker items for structured workflows:

```
"Spawn a worker for issue cic-123"
-> spawn_workers with issue_id="cic-123", badge="Fix auth bug"
-> Worker automatically marks issue in_progress, implements, closes, and commits

"Spawn workers for all ready issues"
-> Check `bd ready` or `pb ready` for available work
-> Spawn one worker per issue with issue_id assignments
```

### Coordinated Workflow

Use the manager to coordinate between workers:

```
"Spawn a backend worker to create a new API endpoint"
-> Wait for completion with wait_idle_workers

"Now spawn a frontend worker and tell it about the new endpoint"
-> Pass context from read_worker_logs of the backend worker

"Spawn a test worker to write integration tests"
-> Coordinate based on both previous workers' output
```

## Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│                Manager Claude Code Session                       │
│                (has maniple MCP server)                          │
├──────────────────────────────────────────────────────────────────┤
│                         MCP Tools                                │
│  spawn_workers | message_workers | wait_idle_workers | etc.      │
└───────────────────────────┬──────────────────────────────────────┘
                            │
               ┌────────────┼────────────┐
               ▼            ▼            ▼
         ┌──────────┐ ┌──────────┐ ┌──────────┐
         │ Groucho  │ │ Harpo    │ │ Chico    │
         │ (tmux)   │ │ (tmux)   │ │ (tmux)   │
         │          │ │          │ │          │
         │  Claude  │ │  Claude  │ │  Codex   │
         │   Code   │ │   Code   │ │          │
         │          │ │          │ │          │
         │ worktree │ │ worktree │ │ worktree │
         │ .worktrees/ │ .worktrees/ │ .worktrees/ │
         └──────────┘ └──────────┘ └──────────┘
```

The manager maintains:
- **Session Registry**: Maps worker IDs/names to terminal sessions
- **Terminal Backend**: Persistent connection to tmux or iTerm2 for terminal control
- **JSONL Monitoring**: Reads Claude/Codex session files for conversation state and idle detection
- **Worktree Tracking**: Manages git worktrees for isolated worker branches
- **Event Log**: Records worker lifecycle events for polling and diagnostics

## Development

```bash
# Sync dependencies (with dev tools)
uv sync --group dev

# Run tests
uv run pytest

# Run the server directly (for debugging)
uv run python -m maniple_mcp

# Run in HTTP mode
uv run python -m maniple_mcp --http

# Install slash commands
make install-commands
```

## Troubleshooting

### tmux backend

**"tmux not found"**
- Install tmux: `brew install tmux` (macOS) or `apt install tmux` (Linux)
- Ensure tmux is in your PATH

**Workers not detected after restart**
- Use `discover_workers` to find orphaned sessions
- Use `adopt_worker` to re-register them
- Sessions are matched via markers written to JSONL files

### iTerm2 backend

**"Could not connect to iTerm2"**
- Make sure iTerm2 is running
- Enable: iTerm2 > Preferences > General > Magic > Enable Python API

### General

**"Session not found"**
- The worker may have been closed externally
- Use `list_workers` to see active workers
- Workers can be referenced by ID, terminal ID, or name

**"No JSONL session file found"**
- Claude Code may still be starting up
- Wait a few seconds and try again
- Check that Claude Code is actually running in the worker pane

**Worktree issues**
- Use `list_worktrees` to see worktrees for a repository
- Orphaned worktrees can be cleaned up with `list_worktrees` + `remove_orphans=true`
- Worktrees are stored at `{repo}/.worktrees/`

## Upgrading

After a new version is published to PyPI, you may need to force-refresh the cached version:

```bash
uv cache clean --force
uv tool install --force --refresh maniple
```

This is necessary because `uvx` aggressively caches tool environments.

## License

MIT