KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

pi-tmux

★ 33 Open GitHub ↗

tmux controls for pi coding agent.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# pi-tmux

Tmux tools for [pi](https://github.com/badlogic/pi-mono) to run long-running commands and control panes by lock name.

## Requirements

- Must be running inside a tmux session (`TMUX` env var set)
- tmux must be installed
- [pi-semaphore](https://github.com/offline-ant/pi-semaphore) should be installed

## Installation

```bash
pi install git:github.com/offline-ant/pi-tmux
```

Or try without installing:

```bash
pi -e git:github.com/offline-ant/pi-tmux
```

## Tools

| Tool | Description |
|------|-------------|
| `tmux-bash` | Create a new tmux pane with a lock name and execute a command (defaults to `bash`) |
| `tmux-capture` | Capture output from a pane by lock name or pane id |
| `tmux-send` | Send text or keys to a pane by lock name or pane id; for coordinated workflows, pair with `semaphore_wait` on the same lock name (unless the command launches a nested pi, then wait on the inner lock) |
| `tmux-kill` | Kill a pane by lock name or pane id |
| `tmux-coding-agent` | Spawn a pi coding agent in a pane and return startup output |
| `minitask` | Run multiple independent questions/tasks through `pi -p` in serial and return `<question>/<answer>` blocks |

## Lock + Pane Mapping

`tmux-bash` creates a lock in `/tmp/pi-semaphores/<name>`.

- The lock file content is the tmux pane id (for example `%42`)
- Control tools resolve `<name> -> pane id` and target that pane
- When the command exits, the lock is removed and `idle:<name>` is written

This allows any agent in the same tmux server to control panes it did not spawn, as long as it knows the lock name.

## Example

1. Start: `tmux-bash` with name `worker` and command `npm run dev`
2. Capture: `tmux-capture` with name `worker`
3. Send keys: `tmux-send` with name `worker` and text `C-c`
4. Kill: `tmux-kill` with name `worker`

Spawn a coding agent:

1. `tmux-coding-agent` with name `reviewer`, folder `../project`
2. `tmux-send` with name `reviewer` and text `analyze lint failures`
3. `semaphore_wait` with name `reviewer`

`tmux-coding-agent` runs `pi` without model arguments unless `piArgs` is set, so it uses pi's saved last active model by default. Pass `--provider`/`--model` in `piArgs` only when you want to override that selection.

Run independent quick tasks:

1. `minitask` with `questions: ["What is module X?", "Give a one-line status of task Y"]`
2. Read `<question>...</question><answer>...</answer>` blocks from output

## Safety Policy

This extension blocks `git restore` when invoked through:
- built-in `bash`
- `tmux-bash`
- `tmux-send`

Blocked calls are denied before execution. Other work might be in progress; ask the user to resolve the issue if necessary.

## Commands

- `/tmux-list` lists active tmux panes
- `/supervise <task>` spawns a supervised coding agent workflow: writes a task file to `./dev/scratch/<id>/task.md`, then turns the current agent into a supervisor that spawns a 'main' agent to do the work. The supervisor keeps the main agent on track, enforces the >78% context handoff rule, and ensures **architectural quality over speed** — nudging the main agent to investigate properly and build well-structured solutions rather than rushing to quick fixes. The main agent is unaware it has a supervisor.

## License

MIT

pi-tmux

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README