SubstackSource
Building Agent Navigator: a desktop app to coordinate multiple CLI coding agents
by Krishna Suraj · 2026-03-17
✓ Opened with WebFetch on 2026-10-15
Read the original ↗Part 1 · What the source did
Each agent gets its own git worktree and terminal; a board sorts them into Idle, Working and Needs Input so you only look at the ones blocked on you.
- Built an open-source Electron app wrapping real terminals for Claude Code and Codex CLI.
- Derived each agent's state from its JSONL session log plus terminal patterns.
- Created a worktree per agent and fired desktop notifications when one needs approval.
“The app should wrap the terminal, not replace it.”— Krishna Suraj, Substack
Summary written by Agent Cookbook. See the original for the full context.
Part 2 · Our copy-paste version
Adapted by us from what the source described. Fill in the [BRACKETS].
The prompt
For each parallel task:
1. git worktree add ../wt-[BRANCH] -b [BRANCH]
2. Start the agent there with: "Work only inside this worktree on [TASK]. When you need a permission or a decision, stop and write NEEDS INPUT on its own line. When finished, write DONE plus a 3-line summary and the test command."
3. Track every worktree on a 3-column list: Idle / Working / Needs Input.
🛡
Approval rulePermission prompts stay interactive. Don't run parallel agents with permissions skipped.
Set it up
- Install Agent Navigator from the repo, or just use worktrees plus tmux.
- Create one worktree per task.
- Give each agent the bounded prompt above.
- Check the Needs Input column first, approve or redirect, then move on.
- Remove worktrees after merging.
Common failures
⚠
What usually goes wrong
- Projects that need several Docker stacks at once break when run in parallel.
- Uncommitted work is lost if you delete a worktree; the app warns, plain git doesn't.
Variations
- Name worktrees and add shell aliases to hop between them.
- Keep one read-only 'analysis' worktree for logs and queries.