claude-code-tmux

Durable tmux control for interactive Claude Code sessions, plus a Pi extension that can delegate work to those sessions.

This does not call Claude Code --print and it does not use the Anthropic API directly. It starts the official claude interactive CLI inside tmux, pastes tasks into that terminal, captures logs, and optionally waits for a completion marker.

Why

If non-interactive Claude Code usage becomes a paid programmatic path, a local agent can still coordinate the interactive Claude Code app you are already logged into. ccmux makes that setup durable and scriptable:

• Claude Code keeps running in tmux if the parent agent dies.
• Any process can attach, steer, or inspect the session.
• Pi can call Claude Code as a delegated subagent via tools.
• The package can be installed from npm or GitHub as a Pi package.

Install

Requirements:

• tmux on PATH
• claude on PATH
• a normal Claude Code login or configured Claude Code auth
• Pi, if you want the provider or extension tools

Clean Pi provider setup

Install the package into Pi:

pi install npm:claude-code-tmux

Restart or reload Pi, then pick the provider from /model:

claude-code-tmux/opus

or:

claude-code-tmux/sonnet

You can verify the provider is installed with:

pi -e npm:claude-code-tmux --list-models claude-code-tmux

Then use Pi normally. When Pi calls the provider, ccmux starts or reuses an interactive Claude Code session in tmux, relays the turn to it, and returns the final response to Pi.

CLI install

npm install -g claude-code-tmux
ccmux --help

One-off CLI usage without global install:

npx -y -p claude-code-tmux ccmux --help

Local development:

git clone https://github.com/Mahir-Isikli/claude-code-tmux.git
cd claude-code-tmux
npm install
npm link

CLI usage

Start a session:

ccmux start --name demo --cwd .

By default, ccmux start launches Claude Code with:

claude --model opus --effort high --dangerously-skip-permissions

Claude Code resolves opus to the latest Opus model, currently Opus 4.7. You can override model and effort:

ccmux start --name demo --cwd . --model sonnet --effort xhigh
ccmux start --name demo --cwd . --model claude-opus-4-7 --effort max

For a safer interactive session, opt out of bypass mode:

ccmux start --name demo --cwd . --safe-permissions

Send work and wait for the completion protocol:

ccmux send --session demo --wait "Inspect this repo and summarize the architecture."

Send live steering:

ccmux steer --session demo "Keep the scope tiny and do not edit files yet."

Inspect or attach:

ccmux status
ccmux capture --session demo --lines 120
tmux attach -t ccmux-demo

Kill a session:

ccmux kill --session demo

Pi usage

Install the package into Pi from npm:

pi install npm:claude-code-tmux

For local development, use the checkout path instead:

pi -e /absolute/path/to/claude-code-tmux --list-models claude-code-tmux

The extension registers a native Pi provider:

• provider: claude-code-tmux
• models: opus, sonnet

Select it in Pi with /model, or start Pi with model filters that include claude-code-tmux/*.

The provider relays Pi model requests into an interactive Claude Code session in tmux. It starts a ccmux session for the current workspace, sends Pi's recent context to Claude Code, streams Claude Code hook lifecycle/tool progress as hidden thinking/progress, and returns Claude Code's final response to Pi. This is still best-effort terminal automation, but it behaves like a normal Pi provider from the model picker.

The extension also registers these tools:

• ccmux_start
• ccmux_send
• ccmux_steer
• ccmux_status
• ccmux_capture

Provider mode also injects temporary Claude Code hook settings. Hook events are recorded under ~/.pi/ccmux/events/ and can be inspected with:

ccmux events --session <session-name>
ccmux events --job <job-id>

The package also bundles a skill:

• /skill:claude-code-tmux

Use the skill when an agent needs the ccmux workflow, CLI fallback commands, AGENTS.md behavior, troubleshooting notes, or public packaging guidance.

Typical tool flow inside Pi:

1. Start a Claude Code session for the repo with ccmux_start.
2. The default model is opus, the default effort is high, and permission prompts are bypassed.
3. Send a task with ccmux_send.
4. If the task runs long, use ccmux_capture or attach to the tmux session.
5. Use ccmux_steer for corrections while Claude Code is running.

Typical provider flow inside Pi:

1. Install with pi install npm:claude-code-tmux.
2. Select claude-code-tmux/opus from /model.
3. Send a normal Pi prompt.
4. Pi calls the provider, which relays the turn into Claude Code running in tmux.

AGENTS.md support

Claude Code already reads CLAUDE.md. Many agent projects use AGENTS.md instead. On start, ccmux auto-discovers AGENTS.md files from the working directory upward to your home directory, combines them, and passes them to Claude Code with --append-system-prompt-file.

This means users do not need to symlink AGENTS.md to CLAUDE.md. If both files exist, Claude Code sees its normal CLAUDE.md context plus the imported AGENTS.md instructions.

Disable this behavior if needed:

ccmux start --name demo --cwd . --no-agents-md

Use an explicit file if you want:

ccmux start --name demo --cwd . --agents-md ./AGENTS.md

Completion detection

For each sent task, ccmux appends a protocol asking Claude Code to include:

CCMUX_DONE:<job-id>

It also asks Claude Code to write a JSON done file under .ccmux/jobs/ in the target workspace. The runner treats either the marker or the done file as completion.

This is intentionally best-effort. Interactive terminal UIs are not stable APIs. If the marker is not seen, the tmux session may still have completed. Use ccmux capture or attach to check.

Testing

Fast unit checks:

npm run check

Deterministic CI-safe package smoke. This does not need Claude Code auth, Pi, or tmux:

npm run test:ci

Full local provider matrix. This starts real Claude Code tmux sessions and can take a few minutes:

npm run test:provider

Published npm matrix, useful after a release:

npm run test:provider:npm

The deterministic CI suite covers:

• package manifest and tarball contents
• CLI bin smoke
• bundled skill frontmatter
• hook event broker
• hook CLI recorder
• native Pi tool request/response broker

The real provider matrix covers:

• provider registration
• fresh workspace trust prompt handling
• reused provider sessions
• file edits through Claude Code
• native Pi tool calls through the ccmux-pi-tool bridge
• AGENTS.md import
• opus and sonnet provider models
• hook event recording through ccmux events
• shadow replay events and native Pi tool bridge events

Remote Control

ccmux start --remote-control passes --remote-control to Claude Code. That makes the session visible to Claude Code Remote Control if your Claude account supports it. ccmux itself still controls the local terminal through tmux.

Safety and policy notes

This package is a terminal automation layer around the official interactive Claude Code CLI. It is not a hidden API client and does not impersonate a third-party integration. Users should only run it with Claude Code installations and accounts they are allowed to use. For public distribution, avoid language about bypassing billing or access controls.

Current limitations

• Terminal completion detection is heuristic.
• ccmux starts Claude Code with --dangerously-skip-permissions by default. Use --safe-permissions if you want Claude Code prompts.
• The Pi provider is best-effort terminal automation behind a normal provider entry.
• Claude Code uses its own tools inside tmux, so Pi does not receive structured Pi tool calls from this provider.
• File edits can happen through Claude Code, outside Pi's normal tool transcript.
• Streaming is currently final-response oriented. Use ccmux_capture or ccmux capture for terminal inspection.