martian-engineering

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)

# 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

uvx --from maniple-mcp@latest maniple

From Source

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

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

Using local clone