# Supacode: terminal-first agent harness manager for macOS

> Supacode is a terminal-first agent harness session manager on libGhostty for macOS, built to manage many AI coding agents and worktrees at once.

Published: 2026-06-21
URL: https://daniliants.com/insights/supacode-terminal-first-agent-harness-manager-for-macos/
Tags: ai-coding-agents, terminal, git-worktrees, developer-tools

---

## 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.