Foreman
Keeps your AI coding sessions alive and restarts the ones that hang.
A terminal session supervisor that watches AI coding agents across tmux panes, classifies their state, and nudges or restarts the ones that hang.
- language
- TypeScript (Bun runtime)
- architecture
- 4 daemons (monitor, nudger, overseer, PR watcher)
- strategies
- 14 built-in nudge strategies
- tests
- 58 files, ~11,700 LOC (about 80% of source)
- history
- 155 commits in 46 days
- repo
- Private
The problem
Running ten or more AI coding agents across tmux panes creates a supervision gap: they stall on permission prompts, enter retry loops, or exhaust context with no signal. No tool treated AI-occupied panes as supervised processes with typed state and a queryable event log.
How it is built
-
Stall detection that ignores UI noise
Before hashing a pane transcript, the monitor strips Claude Code spinner and elapsed-timer lines, so "stalled" reflects a genuine content freeze rather than every animation tick. A pane has to actually stop changing to register.
-
A configurable strategy chain, not a hardcoded script
The nudger resolves a named list of strategies per session and short-circuits on the first match. Operators reorder them, disable them, add completion patterns, and allowlist permission prompts in JSON config, without touching code.
-
LLM escalation with cost guards
When heuristic nudges fail, it escalates to an LLM with the cleaned transcript and sibling-pane context, scaling the model tier (haiku to sonnet to opus) with nudge count and aborting after repeated failures so a genuinely stuck pane cannot run up the bill.
By the numbers
Where this honestly stands
Live and running locally, open-sourced with documented launch criteria. Three P0 blockers remain open, and CI runs on manual trigger only (a documented cost workaround).
Want the parts that are not in a public repo? I will walk you through the architecture and the decisions on a call.