Foreman
Keeps your AI coding sessions alive and restarts the ones that hang.
A supervisor for AI coding sessions that spots stuck agents and restarts the ones that hang.
Who it helps: For developers supervising a fleet of AI coding agents in tmux, stalls, permission prompts, and retry loops surface as typed state instead of silently frozen panes.
At a glance
- language
- TypeScript (Bun runtime)
- architecture
- 4 daemons (monitor, nudger, overseer, PR watcher)
- strategies
- 14 built-in nudge strategies
- tests
- test code is ~80% of source by LOC (58 files)
- ownership
- Sole engineer: built and run locally day to day
- history
- built 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. Foreman treats AI-occupied panes as supervised processes, with typed state and a queryable event log.
How it’s 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 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 stands today
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).