English | 한국어
claude-ipc
Session-to-session IPC for Claude Code. Delegate tasks between tmux sessions.
One Claude session sends the work. Another does it. Results come back automatically.
Quick Start • Commands • How It Works • Requirements
Quick Start
Step 1: Install
/plugin marketplace add https://github.com/kungbi/claude-ipc.git
/plugin install claude-ipc
Step 2: Send a task
/claude-ipc:send
That's it. Pick a session, describe the task, and get the result back when it's ready.
Why claude-ipc?
- Zero overhead — File-based IPC, no external services or daemons
- tmux-native — Built on top of claude-tmux-session
- No OMC dependency — Pure files and tmux, works with any Claude Code setup
- Async results — Send a task and keep working; results arrive when ready
- Simple JSON format — Task files are human-readable and easy to debug
Commands
| Command | Description |
|---|
/claude-ipc:send | Select a session and send a task to it |
/claude-ipc:work | Process pending tasks sent to this session (asks for explicit approval before executing) |
/claude-ipc:recv | Receive and display results from completed tasks |
/claude-ipc:clean | Delete sent/ and outbox/ files older than 7 days |
How It Works
Session A → /claude-ipc:send → picks target session → writes task file → notifies B
Session B → /claude-ipc:work → processes task → writes result → notifies A
Session A → /claude-ipc:recv → reads result
File Layout
~/.claude/ipc/
├── inbox/
│ └── <target-session>/
│ ├── <task-id>.json # Pending tasks
│ ├── .rejected/ # Tasks the receiver explicitly denied
│ └── .failed/ # Malformed / unparseable task files
├── outbox/
│ └── <sender-session>/
│ ├── <task-id>.json # Completed results (status: done | failed)
│ └── .failed/ # Malformed / unparseable result files
└── sent/
└── <sender-session>/
└── <task-id>.json # Sender-side log of dispatched tasks
Message Format
The id format is <ms-epoch>-<8 hex chars> and matches ^[0-9]+-[a-f0-9]{8}$. The leading timestamp in the id corresponds to the same moment as created_at.
{
"id": "1745625600000-a1b2c3d4",
"from": "claude_3f0fe706",
"to": "claude_7a3b8fbb",
"task": "Summarize the logs in ~/app/logs/error.log",
"status": "done",
"created_at": "2026-04-26T01:00:00Z",
"result": "Found 3 critical errors...",
"completed_at": "2026-04-26T01:00:45Z"
}
On failure, the result file is the same superset shape with status: "failed", result: null, and an error field:
{
"id": "1745625600000-a1b2c3d4",
"from": "claude_7a3b8fbb",
"to": "claude_3f0fe706",
"task": "Summarize the logs in ~/app/logs/error.log",
"created_at": "2026-04-26T01:00:00Z",
"status": "failed",
"result": null,
"error": "Log file not found",
"completed_at": "2026-04-26T01:00:12Z"
}
Status Values
| Status | Description |
|---|
pending | Task received, not yet processed |
done | Task completed, result available |
failed | Task could not be completed; see error field |
Requirements
| Requirement | Description |
|---|
| Claude Code | CLI tool (active session required) |
| claude-tmux-session | Provides claude-tmux ls and named tmux sessions |
| tmux | Terminal multiplexer |
Note: Sessions are identified by their claude_ tmux session names provided by claude-tmux-session. Make sure both the sender and receiver sessions are running under that naming scheme. Session names must match ^claude_[a-zA-Z0-9_-]+$ — commands will refuse to run against names that don't.
Receiver permissions: The receiver session executes the delegated task in its own Claude Code instance. It must already have pre-approved tool permissions (e.g. Bash, Read, Write, Edit) for the kinds of work being delegated, otherwise the receiver will pause to ask the human to approve each tool call. The receiver also explicitly asks for human approval before running any IPC task — auto-execution is intentionally not supported.
Contributing
