Skip to content

tmux-pilot documentation

Run Codex, Claude Code, and Pi in tmux without losing the thread.

tmux-pilot gives you one operational CLI for starting agent sessions, bootstrapping task worktrees, refreshing PR state, steering live agents, and cleaning up after the branch lands.

Install and quickstart CLI cookbook Command reference

Launch in an existing checkout

tp new docs-pass --profile codex -c ~/repos/tmux-pilot

Bootstrap a task worktree

tp new auth-fix --profile claude --repo ~/repos/myapp --issue 771

Refresh a repo dashboard

tp refresh --repo myapp
tp ls --cols NAME,PR,STATUS,DIR --repo myapp

What You Actually Do With tp

tp new docs-pass --profile codex -c ~/repos/tmux-pilot
tp new review-pass --profile claude -c ~/repos/myapp
tp new pi-local --profile pi -c ~/repos/pi-mono

tp new oauth-fix --profile codex --repo ~/repos/myapp
tp new issue-771 --profile claude --repo ~/repos/myapp --issue 771
tp new pi-smoke --profile pi --repo badlogic/pi-mono

tp refresh --repo myapp
tp ls --cols NAME,PR,STATUS,DIR --repo myapp
tp ls --status active
tp peek docs-pass -n 50
tp send --wait docs-pass "continue with regression coverage"
tp status docs-pass

Built For CLI-Heavy Work

  • Concrete examples first

    The docs lead with commands you can paste directly into a shell, not abstract architecture diagrams.

  • Profiles for the common agents

    Built-in launch profiles cover Codex, Claude Code, and Pi, and custom profiles let you codify repo-specific defaults.

  • Task bootstrap included

    tp new --repo ... can resolve or clone a repo, derive a task branch, create a worktree, and launch the agent there.

  • Steering without attaching

    tp refresh, tp ls, tp peek, tp send --wait, and tp status let you manage live sessions from another terminal.

Start With One Of These Pages

  • Install and Quickstart

    Get tp installed and run your first Codex, Claude Code, or Pi session in a few commands.

  • CLI Cookbook

    Find copy-paste examples for common flows: listing sessions, refreshing PR dashboards, sending follow-ups, bootstrapping worktrees, cleaning up, and reaping merged branches.

  • Profiles and Worktrees

    See the exact CLI flows for reusable profiles and repo-backed task sessions.

  • CLI Reference

    Keep a compact command-by-command reference open in another tab while you work.

Why The Site Is Structured This Way

The emphasis here is intentionally narrow:

  • the CLI guides show real shell commands and workflows
  • the concept pages explain how readiness and transcript-backed state work
  • the reference section stays compact, with Python automation treated as a small secondary surface

If you only read one thing before trying `tp`, read Install and Quickstart.