Tmux Core Flow

tmux-core-flow

Deterministic state tracking and permission control for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) agents running in tmux.

[](https://github.com/dimaCaptain/tmux-core-flow/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org/downloads/)

Running several Claude Code agents at once, two things get tedious: knowing which one needs you, and approving a permission prompt for every safe tool call. This does both from Claude Code's own hooks — no screen scraping, no simulated keypresses, no background daemon.

1. State — claude-hook-notify turns hook events into a colour on the tmux tab: 🟡 working, 🟢 waiting for your approval, 🔴 finished. It also writes timestamps and a pane→session map to disk.
2. Permissions — flow-approve is a PreToolUse hook that auto-approves tool calls except those matching an always_ask deny-list.
3. Survival — flow-session-index records which session ran in which window, so a reboot does not cost you the context of a dozen agents, and flow-sync keeps an encrypted copy of that state off the machine entirely.

No dashboard here — on purpose

You get the state, not a widget. The hard part is the state machine: knowing that a finished agent must *stay* red when its pane keeps printing, that green clears when a tool runs because that means you approved. Rendering is the easy part, and it is where everyone's needs differ — your columns are not mine.

So the tab colour is already a usable display on its own, and [`docs/state-format.md`](docs/state-format.md) documents every file this writes so you can build exactly the widget you want, in any language. That contract is stable and versioned; a dashboard shipped here would only rot.

How th