Supacode: terminal-first agent harness manager for macOS

My notes

Summary

A long-time CLI user reviews Supacode, a terminal-first “agent harness session manager” built on libGhostty for macOS, and explains why it replaced raw Ghostty/iTerm for running many AI coding agents at once. The core value is a project/worktree sidebar plus agent-aware hooks that fix the “1,000 tabs” problem when juggling Claude Code, OpenCode, Codex and Pi sessions. It situates Supacode inside a fast-growing libGhostty ecosystem and contrasts it with heavier GUI alternatives.

Key Insight

• libGhostty is the real story. Mitchell Hashimoto split Ghostty into a core library (libGhostty) + thin per-OS UI shell. Result: dozens of terminal apps now share the same fast core - see the awesome-libGhostty list. They read the same Ghostty config file, so fonts/keybindings/themes carry across apps for free.
• “Agent harness” defined concretely: an agent = permissions + model choice + system prompt + tools. A harness (Claude Code, OpenCode) contains multiple agents/sub-agents. Supacode is a layer above the harness to manage many of them.
• Not Git-locked. Unlike worktree-centric tools, Supacode treats any folder as a project (folder icon vs Git-branch icon vs PR icon in the sidebar). You can pin, color, reorder, rename projects independently of the directory name.
• Three agent-integration tricks via opt-in hooks (supports 4 harnesses today; Claude Code + Pi shown enabled, Codex not yet): (1) toast + macOS notifications when an agent needs attention or finishes; (2) its own CLI meant for the agents, not the human - the agent drives the GUI (e.g. “open this dir as a new Supacode project”, create worktrees); (3) a bundled skill so the agent knows how to manage Supacode itself.
• Worktrees made painless: set one worktree location in settings, hit + on a project to create branch + worktree together; the three entries under one project in the demo were three worktrees (you can’t have three branches checked out at once otherwise).
• GitHub awareness: OAuths to GitHub and also borrows auth via the gh CLI’s token-passthrough API. A title-bar “notch” shows PR check status (partial-fail shown), hover for full check list, click through to the PR.
• ZMX (Tmux-like) persistence added recently: kill/restart Supacode and you get back all tab/pane history; anything running (e.g. a Claude Code session) keeps running in the background and reattaches.
• Active/pinned sessions float to top of the sidebar; supported-harness logo marks sessions that ran overnight. Command palette = Cmd+P.
• Ecosystem comparison: Cmux (terminal-centric, libGhostty, but a cluttered/low-value left menu); Superset (similar but busier, right-side diff list); OpenChamber (OpenCode-only, very polished but terminal is an afterthought like VS Code’s). The reviewer still prefers driving diffs from the shell with Lazy Git in a small side pane rather than GUI diff panels.