Metadata-Version: 2.4
Name: tmux-orche
Version: 0.4.64
Summary: Typer-based CLI for tmux-backed Codex orchestration sessions
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: certifi>=2024.0.0
Requires-Dist: rich>=13.9.0
Requires-Dist: typer>=0.16.0
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-cov>=5.0; extra == "test"

<p align="center">
  <img src="./assets/b9f91b78-1852-453a-8b0d-2cae29185174.png" alt="tmux-orche" width="100%">
</p>

<h1 align="center">tmux-orche 🎼</h1>

<p align="center">
  <a href="https://github.com/parkgogogo/tmux-orche/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a>
  <img src="https://img.shields.io/badge/Python-3.9%2B-blue" alt="Python 3.9+">
  <img src="https://img.shields.io/badge/tmux-required-green" alt="tmux required">
</p>

<p align="center">
  <b>Control plane for tmux-backed agent orchestration.</b><br>
  Hire agents. Route their results. Take over when you need to.
</p>

<p align="center">
  <a href="README.zh.md">中文</a> · <a href="#installation">Installation</a> · <a href="./docs">Docs</a>
</p>

## 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](https://github.com/tmux/tmux)
- Python 3.9+ for `pip`, `uv`, or source installs
- `codex` CLI and/or `claude` CLI (depending on which agents you use)

### Quick Install

Install the latest prebuilt binary without Python:

```bash
curl -fsSL https://github.com/parkgogogo/tmux-orche/raw/main/install.sh | sh
```

Update in place:

```bash
orche update
```

Or install with `uv`:

```bash
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:

```bash
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 as `Enter`, `Escape`, or `C-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:

```bash
# 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"
```

![Claude + Codex workflow](./assets/b9f91b78-1852-453a-8b0d-2cae29185174.png)

*The image above shows a Codex supervisor using 2 Codex and 2 Claude agents to simultaneously perform code review.*

### 2. OpenClaw Supervision Loop

When OpenClaw is supervising the worker and the loop should close back into Discord:

```bash
orche open \
  --cwd ./repo \
  --agent codex \
  --name repo-worker \
  --notify discord:123456789012345678

orche prompt repo-worker "analyze the failing tests"
```

![OpenClaw supervision](./assets/openclaw-supervision-loop.png)

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. Extending with Skills

`orche` supports skills to extend agent capabilities. A skill is a set of instructions placed in the agent's skills directory.

For example, to install the `orche` skill from this repository for Codex:

```bash
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:

```bash
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:

```bash
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:

```bash
# 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 3600s, <=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:

```bash
orche config list
orche config get claude.command
orche config reset claude.command
```

## Roadmap

- [ ] Support more code agents
- [ ] Support more notify providers
- [ ] Plugin-based agent & notify architecture

Because both `notify` and `agent` are designed as plugins, you can also develop your own. Check out:

- [Developing Agent Plugins](./docs/agent-plugin-dev.md)
- [Developing Notify Plugins](./docs/notify-plugin-dev.md)

## Acknowledgements

`tmux-orche` was inspired by [ShawnPana/smux](https://github.com/ShawnPana/smux), which gave us many ideas on tmux session management and agent orchestration.

## License

[MIT](LICENSE)
