"D'oh!" — Homer Simpson
Multi-agent TUI orchestrator for AI coding tools. Wraps Claude Code, Codex, Aider, or any AI CLI in a polished terminal dashboard with parallel agents, task management, and automated verification.
Named after Homer Simpson — he may not look like he's working, but somehow things get done. Homer orchestrates your AI agents so you don't have to.
┌──────────────────────────────────────────────────────────┐
│▓▓▓▓▓▓▓▓▓▓▓▓▓▓│ │
│▓ ◆ HOMER ▓│ ┌──────────────────────────────────┐ │
│▓ active (1) ▓│ │ ⬢ agent-1 · #42 ● working │ │
│▓ ▓│ │ │ │
│▓ ⬢ Claude ▓│ │ [live terminal output] │ │
│▓ v2.1.15 ▓│ │ │ │
│▓ ▓│ │ │ │
│▓ STORIES 2/5 ▓│ └──────────────────────────────────┘ │
│▓ ████████░░░ ▓│ │
│▓ ✓ Auth ▓│ │
│▓ ● Dashboard ▓│ │
│▓ ▓│ │
│▓ AGENTS ▓│ │
│▓ ▸● agent-1 ▓│ │
│▓ ○ agent-2 ▓│ │
│▓▓▓▓▓▓▓▓▓▓▓▓▓▓│─────────────────────────────────────────│
│ 01:23 │ ● TYPING ^A=nav ^N=agent ^G=join │ 2/5 │
│ + agent j join t tool 1-2 switch q quit │
└──────────────────────────────────────────────────────────┘
- Multi-agent terminals — Run up to 5 AI agents side-by-side in split panes
- Tool-agnostic — Claude Code, Codex CLI, Aider, Cline, or any CLI tool
- Task sources — Load from
prd.json(Ralph-compatible) or GitHub Issues - Verification loop — Agents signal
HOMER_DONE, Homer runs typecheck/lint/tests, re-injects errors if they fail - Session persistence — Quit and resume where you left off
- Project index — Scans your codebase on startup so agents don't waste time re-scanning
- Agent coordination — Agents leave notes for each other; shared context prevents duplicated work
# Install globally (requires Bun)
bun add -g homer-cli
# Or with npm
npm install -g homer-cli
# Verify
homer --help
homernot found? Bun's global bin directory (~/.bun/bin) may not be on your PATH. Add it:echo 'export BUN_INSTALL="$HOME/.bun"' >> ~/.zshrc echo 'export PATH="$BUN_INSTALL/bin:$PATH"' >> ~/.zshrc source ~/.zshrc(Use
~/.bashrcinstead if you're on bash.)
git clone https://github.com/ProfVex/homer.git
cd homer && bun install
bun link
homer --help| Tool | Required | Install |
|---|---|---|
| Bun | v1.0+ | curl -fsSL https://bun.sh/install | bash or brew install oven-sh/bun/bun |
gh CLI |
For GitHub issues | brew install gh then gh auth login |
| At least one AI CLI | Yes | See below |
Supported AI CLIs (install at least one):
| Tool | Install |
|---|---|
| Claude Code | claude.ai/download |
| Codex CLI | npm install -g @openai/codex |
| Aider | pip install aider-chat |
| Cline | npm install -g cline |
# Open TUI — auto-detects tools, shows picker if multiple installed
homer
# Use a specific tool
homer --tool claude
# Auto-mode: works through stories/issues without manual intervention
homer --auto
# Resume a previous session
homer --resume- Homer scans your project on startup — builds an index of exports, dependencies, and conventions
- You pick a task — from a
prd.jsonfile (user stories) or GitHub Issues - Homer spawns an AI agent in a real PTY terminal with project context injected
- Agent works autonomously — you can watch, type into it, or let it run
- Agent signals
HOMER_DONEwhen it thinks it's finished - Homer runs verification — typecheck, lint, tests (auto-detected from your project)
- If checks fail — errors are re-injected into the agent to fix (tight feedback loop)
- If checks pass — story is marked complete, next task is picked up
This verification loop is inspired by Ralph — the agent can't claim "done" until the code actually passes.
Nav mode (default — press Ctrl+A to enter):
| Key | Action |
|---|---|
Enter |
Spawn agent / focus terminal |
+ |
Spawn another agent |
j |
Join agent (picker overlay) |
i |
Pick a task (stories + issues) |
t |
Change AI tool |
Tab |
Cycle between agent panes |
1-9 |
Switch to agent N |
c |
Rebuild project index |
w |
Show workflow history |
r |
Refresh sidebar |
q / Ctrl+C |
Quit (press twice to confirm) |
Terminal mode (typing into an agent — press Ctrl+A to exit):
| Key | Action |
|---|---|
Ctrl+A |
Exit to nav mode |
Ctrl+N |
Spawn new agent (without leaving terminal) |
Ctrl+G |
Join/switch agent (without leaving terminal) |
| Flag | Default | Description |
|---|---|---|
--tool NAME |
auto-detect | AI CLI to use (claude, codex, aider, cline, openrouter) |
--model MODEL |
— | Model selection (for aider/openrouter) |
--repo OWNER/REPO |
auto-detect | GitHub repo for issues |
--auto |
off | Auto-claim and work through tasks |
--agents N |
5 | Max concurrent agents |
--label PREFIX |
homer |
Label prefix for GitHub issues |
--permission-mode MODE |
bypassPermissions |
Claude Code permission mode |
--resume |
— | Auto-resume previous session |
--fresh |
— | Start clean, ignore previous session |
-h, --help |
— | Show help |
Homer supports two task sources that can be used together:
Drop a prd.json in your project root with user stories. Homer picks them up automatically.
{
"project": "MyApp",
"branchName": "homer/feature",
"userStories": [
{
"id": "US-001",
"title": "Add user login",
"description": "As a user, I want to log in with email and password.",
"acceptanceCriteria": ["Login form renders", "JWT token stored", "Typecheck passes"],
"priority": 1,
"passes": false,
"notes": ""
}
]
}With --repo (or auto-detected), Homer shows all open issues. You pick one, and it's sent to the agent with full context.
Issues with checkbox acceptance criteria are parsed automatically. Label issues with homer:ready to use auto-mode.
Homer creates a .homer/ directory in your project with:
context.md— Auto-generated index of exports, dependencies, and recent agent workprogress.txt— Log of completed stories
This directory is auto-added to .gitignore. Agents read context.md on startup to avoid re-scanning your codebase.
Global data lives in ~/.homer/:
sessions/— Session snapshots for resumecontext/{repo}/— Project index, agent notes, shared context
Homer auto-detects verification commands from your project:
| Project Type | Detected Commands |
|---|---|
| TypeScript | npm run typecheck or npx tsc --noEmit |
| ESLint | npm run lint |
| Jest/Vitest | npm test |
| Python + mypy | mypy . |
| Python + pytest | pytest |
| Python + ruff | ruff check . |
| Makefile | make check |
When an agent signals HOMER_DONE, all detected commands run. If any fail, errors are fed back to the agent.
- macOS — Full support
- Linux — Full support
- Windows — Not supported (node-pty platform limitation)
"I'm helping!" — Ralph Wiggum
Homer's verification loop is directly inspired by Ralph — an autonomous agent system that enforces a tight feedback loop: agents can't claim "done" until tests actually pass.
Ralph uses prd.json files (Product Requirement Documents) to define user stories with acceptance criteria. Homer reads the same format, making them fully compatible.
- Homer and Ralph are named after characters from The Simpsons, created by Matt Groening. All Simpsons references are used as fan tributes — this project has no affiliation with 20th Century Fox or The Simpsons.
- Built with OpenTUI for the TUI, ghostty-opentui for terminal rendering, and node-pty for real PTY emulation.
- Designed to wrap Claude Code, Codex CLI, Aider, and other AI coding tools.
- Created by @ProfVex.
MIT