╔═══════════════════════════════════════════════════════╗
║ @@@@@@@@@@@@@@@@@@@@@@@@@@@%%%#*++**#%%@@@@@@@@@@@@@@ ║
║ @@@@@@@@@@@@@@@@@@@@@@@@%*====-----::::-:=%@@@@@@@@@@ ║
║ @@@@@@@@@@@@@@@@@@@@@%#=:.:-=------:... -%@@@@@@@@ ║
║ @@@@@@@@@@@@@@@@@@%%#= .....:-:.......... *%@@@@@@ ║
║ @@@@@@@@@@@@@@%+==-+%*: .:---::::....:.... #@@@@@@ ║
║ @@@@@@@@@@@@%#:. ..:. ..:-...:..... . :%@@@@@@ ║
║ @@@@@@@@@@@@#:.:.. :*= ............ . :%@@@@@@ ║
║ @@@@@@@@@@@@#--:.. -%+............... .. *%#=-:.: ║
║ @@@@@@@@@@%#----.:#%+.::::... ..... .... .:# ║
║ @@@@@@@@%+-:::.. :%@@@@@@@@%*=: ..*%@ ║
║ @@@@@@%*-=:..::.:-..+@@@@@@%%#=:. .. . ... *@@@ ║
║ @@@@#==::%@@@@@@%=:::=%*-:. .... . ... :%@@@@ ║
║ @@#::=#@@@@%#-.:-... .::... :#%@@@@@ ║
║ %=:%%%#####+:.: . ..... . . *%@@@@@@@ ║
║ :::.:.:::..::. . .. :#@@@@@@@ ║
║ %#*++===--============++===-::::::::---=====#%@@@@@@@ ║
║ _____ _____ _______ _______ _ _ _ _ _____ ║
║ / ___|_ _/ ___\ \ / / ___ \ | | | | | / ___| ║
║ \ `--. | | \ `--. \ V /| |_/ / |_| | | | \ `--. ║
║ `--. \ | | `--. \ \ / | __/| _ | | | |`--. \ ║
║ /\__/ /_| |_/\__/ / | | | | | | | | |_| /\__/ / ║
║ \____/ \___/\____/ \_/ \_| \_| |_/\___/\____/ ║
╚═══════════════════════════════════════════════════════╝
sisyphus
A tmux-integrated orchestration daemon for Claude Code multi-agent workflows.
What this is
Sisyphus runs multiple Claude Code instances in tmux panes and coordinates them. That's it. Every agent is a real claude process with full access to your codebase, your CLAUDE.md, your hooks. Sisyphus just handles the "run N of them in parallel and loop until done" part.
If you know the Ralph Wiggum loop (while true; do claude --prompt task.md; done), this is that idea taken further. Instead of one agent in a loop, an orchestrator decomposes work into parallel agents, each looping independently, with structured state that persists across cycles. The orchestrator itself is in a Ralph loop: plan, spawn agents, get killed, respawn fresh with all the results.
How it works
Most hard tasks aren't hard because any single piece is difficult. They're hard because there are many pieces and context gets lost between them. You're working a 12-file refactor, you hold it all in your head until you don't, and you make a mistake three files from the end because you forgot a constraint from the beginning.
The fix is structural. An orchestrator Claude instance reads the full task, breaks it into subtasks, and spawns parallel agent instances, each in its own tmux pane with a focused instruction. Agents work simultaneously and submit reports when done. Then the orchestrator respawns to review progress and plan the next round.
The trick: the orchestrator is stateless. After it spawns agents and yields, it gets killed. When all agents finish, the daemon respawns a fresh orchestrator with the complete session state (every agent report, every cycle's history, the running plan). Cycle 1 and cycle 15 get the same quality of reasoning because each one starts with a full context window and a clean slate. The boulder rolls back down; Sisyphus walks back down after it, picks it up, and pushes again. But this time he remembers everything from every previous push.
The daemon handles lifecycle: spawning panes, detecting when agents finish, persisting state to disk, respawning the orchestrator.
Requirements
- Node.js >= 22
- tmux >= 3.2 (you must be inside a tmux session)
- Claude Code CLI (
claude) installed and authenticated
- Neovim (optional, enables embedded editor in the dashboard)
Install
npm install -g sisyphi
Then run setup once:
sisyphus setup
This installs the background daemon (macOS launchd), tmux keybindings (M-s to cycle sessions, M-S for dashboard), and checks your environment. The daemon auto-updates when new versions are published.
Verify:
sisyphus doctor
Quick start
sisyphus start "your task description" # Start a session
sisyphus dashboard # Open the TUI (auto-opens on start)
sisyphus status # Check session state from the CLI
Sisyphus is a CLI that Claude Code calls for you. Tell Claude to use it and it handles the rest.
In Claude Code, say something like:
Use sisyphus to migrate our REST API from Express to Hono. The API lives in src/api/ with 14 route files...
Claude calls sisyphus start with a detailed task description, and tmux panes start appearing with parallel agents working on your codebase.
Slash command (recommended)
Create .claude/commands/sisyphus-begin.md in your project:
Run `sisyphus start` with a detailed task description:
```bash
sisyphus start "your task description"
```
