Claude Control

MCP server that lets a Claude Code session coordinate with Claude Code or Codex instances running in other project directories.

How It Works

Claude Control is an MCP server (stdio transport) that exposes tools for dispatching prompts to Claude Code or Codex instances in configured project directories. Each remote instance:

• Preserves conversation context across short-lived CLI invocations by resuming sessions
• Loads the target project's own context files and settings
• Runs fully autonomously by default

Claude jobs use the target project as the subprocess working directory. Codex jobs additionally pass --cd <target-project-path> so Codex discovers the target project's AGENTS.md, .codex/config.toml, hooks, and project root even when this MCP server is launched from a different coordinating project.

Codex jobs ignore the user-level Codex config by default because some Codex CLI versions reject HTTP MCP entries such as [mcp_servers.clickup] url = ... in non-interactive codex exec mode. The target project still loads via --cd, and Codex auth still uses CODEX_HOME. Set CLAUDE_CONTROL_CODEX_IGNORE_USER_CONFIG=false to let Codex load the user config when the local Codex CLI supports it.

Installation

From PyPI

pip install claude-control

Or with uv:

uv tool install claude-control

From Source

git clone https://github.com/redducklabs/claude-control.git
cd claude-control
pip install .

Setup

1. Configure Projects

Create a projects.json file (see projects.json.example):

{
  "projects": [
    {
      "name": "my-backend",
      "path": "D:\\repos\\my-backend",
      "description": "Backend API service"
    },
    {
      "name": "my-frontend",
      "path": "D:\\repos\\my-frontend",
      "description": "Frontend web application"
    }
  ]
}

2. Register as an MCP Server

Add to the .mcp.json of the project where you want coordination tools available.

Using uvx (recommended — no global install needed):

{
  "mcpServers": {
    "claude_control": {
      "command": "uvx",
      "args": ["claude-control"],
      "env": {
        "CLAUDE_CONTROL_PROJECTS": "/path/to/your/projects.json"
      }
    }
  }
}

Using a pip install:

{
  "mcpServers": {
    "claude_control": {
      "command": "claude-control",
      "env": {
        "CLAUDE_CONTROL_PROJECTS": "/path/to/your/projects.json"
      }
    }
  }
}

Using python -m:

{
  "mcpServers": {
    "claude_control": {
      "command": "python",
      "args": ["-m", "claude_control"],
      "env": {
        "CLAUDE_CONTROL_PROJECTS": "/path/to/your/projects.json"
      }
    }
  }
}

3. Restart Claude Code

The tools will appear as mcp__claude_control__send_command, mcp__claude_control__list_projects, etc.

Tools

send_command

Send a prompt to a Claude Code or Codex instance in the specified project directory.

Returns job metadata plus a bounded tail of assistant text by default. Sessions persist across calls per project and per agent — Claude and Codex do not share session history.

To reduce token usage, status/list tools omit assistant text unless include_text=true; send_command and wait_for_job include only the last text_limit characters by default. Set include_text=false for fire-and-forget orchestration, or raise text_limit only when the host agent needs the remote agent's full answer.

Each job also writes assistant text to a local artifact file and returns artifact_path, artifact_char_count, and artifact_available. By default artifacts are stored under ~/.cache/claude-control/artifacts; override this with CLAUDE_CONTROL_ARTIFACT_DIR.

Terminal responses also include available token usage, model usage, retained-context telemetry, a session_action, and any validated handoff path. Values that the selected CLI does not expose are left absent or null, rather than estimated.

Background jobs and completion inbox

start_job accepts a job_size of one_off, small (default), medium, or large. Its response tells the controlling agent to set a timer for 60, 300, 600, or 1200 seconds respectively and then call drain_completion_inbox.

drain_completion_inbox returns compact unread completion/error receipts and the jobs still active. Receipts are stored as result.json beside each response artifact and survive MCP server restarts. Calling the tool acknowledges the receipts it returns.

Every child prompt receives a short control footer requiring the child to follow its project's context-health and handoff policy. When the final response ends with a Markdown link to a real file inside the project's handoffs directory, Claude Control clears the old default session. The next default job starts fresh and is directed to continue from that handoff.

Codex retained-context percentage is read from the matching local rollout when available. At 50% the receipt recommends a handoff; at 60% it requires one. Claude CLI usage is reported, but no retained-context percentage is inferred when Claude does not expose one.

read_job_artifact

Read a bounded slice of a job's assistant-text artifact.

Use this when the host agent needs detailed output after a compact status call. The response includes text, next_offset, and has_more for chunked reads.

list_projects

List all configured projects with their paths, descriptions, and session status.

reset_session

Clear a project's remembered session and pending handoff. The next default call creates a fresh session with no prior context.

get_session_status

Check whether a project has an active session, its ID, and turn count.

Dependencies

• Python >= 3.11
• claude-code-sdk >= 0.0.25
• mcp >= 1.12.0
• Claude Code CLI installed and on PATH
• Codex CLI installed, authenticated, and on PATH if using agent="codex"

Configuration

The CLAUDE_CONTROL_PROJECTS environment variable points to your projects.json. If unset, defaults to projects.json in the package's parent directory.