tmux-orche 🎼
Control plane for tmux-backed agent orchestration.
Hire agents. Route their results. Take over when you need to.
中文 · Installation · Docs
What is tmux-orche?
When an agent delegates work to another agent, the hard part isn't starting the task—it's managing the loop.
Before orche, you have to keep polling to see if the worker is done, burning tokens on every status check. Long tasks are especially painful: the worker might run for ten minutes, and you're stuck either waiting idly or building fragile retry logic. If the worker hangs or stalls, you only find out after wasting dozens of polling rounds. And when you finally want to jump in and fix something, you have no idea which terminal the agent is actually running in.
tmux-orche solves this by turning your tmux sessions into durable, named agent workers. Instead of polling, you open a named session, send the task, and walk away. The worker keeps running inside tmux with full terminal state. When it's done, the result routes back automatically. If something gets stuck, you—or another agent—can attach to the exact live terminal and take over.
Whether you are running Codex, Claude, or any OpenClaw-compatible agent, orche gives you:
- Stable session names instead of raw pane IDs like
%17 - Explicit routing for results to come back exactly where they should
- Durable terminal state that survives beyond one prompt
- Human takeover when automation needs a nudge
Installation
Dependencies
- tmux
- Python 3.9+ for
pip,uv, or source installs codexCLI and/orclaudeCLI (depending on which agents you use)
Quick Install
Install the latest prebuilt binary without Python:
curl -fsSL https://github.com/parkgogogo/tmux-orche/raw/main/install.sh | sh
Update in place:
orche update
Or install with uv:
uv tool install tmux-orche
If install.sh or uv is not a fit, check install.md for pip, source checkout, and troubleshooting paths.
Verify the install:
orche --help
For Agents
If you want another agent to install tmux-orche for you, paste this raw guide link into that agent session:
https://raw.githubusercontent.com/parkgogogo/tmux-orche/main/install.md
Commands
orche exposes a small set of CLI commands that agents call directly to manage the orchestration loop:
orche open— Create or reuse a named control endpoint. An agent calls this to spin up a durable worker with a fixed working directory and an explicit notify route.orche prompt— Delegate work into an existing session. This is how a supervisor agent sends a task to a worker without blocking.orche status— Check whether the pane and agent are alive, and whether a turn is pending. Useful for agents to decide whether to wait or take action.orche read— Inspect recent terminal output without stealing the TTY. Agents use this to catch up on what a worker has produced so far.orche attach— Take over the live terminal. When an agent gets stuck, a human (or another agent) can drop straight into the exact tmux pane.orche close— End the session and clean up state. Called when the worker is no longer needed.
There are also a few helper commands for advanced control:
orche input— Type text into a session without pressing Enter.orche key— Send special keys such asEnter,Escape, orC-c.orche list— List locally known sessions.orche cancel— Interrupt the current turn but keep the session alive.orche config— Read or update shared runtime config.
Usage Scenarios
1. Codex / Claude Multi-Agent Loop
Use orche when you want agents to collaborate inside tmux. For example, let Claude review while Codex writes code:
For the common case where you just want to open a default worker quickly, orche also provides shorthand commands:
orche codex # same as: orche open --agent codex
orche claude # same as: orche open --agent claude
These shortcuts are convenient when you want a tmux session with the default agent and do not need to spell out orche open.
# Open a reviewer session
orche open --cwd ./repo --agent claude --name repo-reviewer
# Open a worker that reports back to the reviewer
orche open \
--cwd ./repo \
--agent codex \
--name repo-worker \
--notify tmux:repo-reviewer
# Delegate work and walk away
orche prompt repo-worker "refactor the auth module"
The image above shows a Codex supervisor using 2 Codex and 2 Claude agents to simultaneously perform code review.
2. OpenClaw Supervision Loop
When using OpenClaw, the configured model may not handle long-running tasks as well as Codex or Claude, especially for coding work. OpenClaw's built-in acpx also has many practical issues. A pragmatic approach is to use orche to let OpenClaw create Codex or Claude sessions and delegate tasks to them; when the work is done, Codex feeds the result back into the group chat, forming a closed loop.
This setup requires creating a separate Discord Bot for Codex and configuring it correctly with
orche config. See Configuration for details.
When OpenClaw is supervising the worker and the loop should close back into Discord:
orche open \
--cwd ./repo \
--agent codex \
--name repo-worker \
--notify discord:123456789012345678
orche prompt repo-worker "analyze the failing tests"
OpenClaw opens the worker, the worker runs in tmux with durable state, and completion events route back through Discord so the supervisor can decide what happens next.
3. Install SKILL (Recommended)
Installing SKILL correctly for your agent can help them quickly learn how to use orche.
For example, to install the orche skill from this repository for Codex:
mkdir -p ~/.codex/skills/orche
curl -fsSL https://raw.githubusercontent.com/parkgogogo/tmux-orche/main/skills/codex-claude/SKILL.md \
-o ~/.codex/skills/orche/SKILL.md
For Claude:
mkdir -p ~/.claude/skills/orche
curl -fsSL https://raw.githubusercontent.com/parkgogogo/tmux-orche/main/skills/codex-claude/SKILL.md \
-o ~/.claude/skills/orche/SKILL.md
For OpenClaw:
mkdir -p ~/.openclaw/skills/orche
curl -fsSL https://raw.githubusercontent.com/parkgogogo/tmux-orche/main/skills/openclaw/SKILL.md \
-o ~/.openclaw/skills/orche/SKILL.md
Configuration
orche stores user configuration in ~/.config/orche/config.json (or $XDG_CONFIG_HOME/orche/config.json).
Common settings you may want to adjust:
# Override the Claude CLI command
orche config set claude.command /opt/tools/claude-wrapper
# Override Claude source paths mirrored into managed runtimes
orche config set claude.home-path ~/custom/.claude
orche config set claude.config-path ~/custom/claude.json
# Set Discord notify credentials
orche config set discord.bot-token "$BOT_TOKEN"
orche config set discord.mention-user-id 123456789012345678
orche config set discord.webhook-url "$WEBHOOK_URL"
# Adjust managed session idle TTL (default 43200s, <=0 disables expiry)
orche config set managed.ttl-seconds 1800
# Enable or disable notify delivery globally
orche config set notify.enabled true
You can also view and reset values:
orche config list
orche config get claude.command
orche config reset claude.command
Roadmap
- Support Discord notifications
- Support Telegram notifications
- Support more agents, like pi
- Support codex as an independent subagent form, with independent skills / mcp, etc., specializing agent capabilities
Because both notify and agent are designed as plugins, you can also develop your own. Check out:
Acknowledgements
tmux-orche was inspired by ShawnPana/smux, which gave us many ideas on tmux session management and agent orchestration.
License
1 maintainer
Metadata
1 maintainer
Release files for tmux-orche 0.4.70
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tmux_orche-0.4.70.tar.gz | 105.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tmux_orche-0.4.70-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 178.1 kB
Release files / tmux_orche-0.4.70.tar.gz
| Download URL | tmux_orche-0.4.70.tar.gz |
|---|---|
| Size | 105.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
96391fc170d5c102852aba001fdd037a123d883946a0be99e428da9075e9cb65
|
|
BLAKE2b-256 checksum How to use checksums |
b23ae0b4bd4f29c35847f2a7dea3c0152ae25553765143cc614b51ae9c9c35f7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 10, 2026.
Transparency logRelease files / tmux_orche-0.4.70-py3-none-any.whl
| Download URL | tmux_orche-0.4.70-py3-none-any.whl |
|---|---|
| Size | 72.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
64f62db49f44c65de43be0acc3f1debefbdd597ae9299b927b2e5e0f491a5e6d
|
|
BLAKE2b-256 checksum How to use checksums |
0e5e4170a3ff0b363dd45363c11743fccd603997d511ce5567a58f76f74eaa6a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 10, 2026.
Transparency log
