Mission control for Claude Code, Codex, OpenCode, Antigravity & pi.
A native macOS terminal for running coding agents side by side —
with live per-agent state, project-aware panes, rendered Markdown & PDF previews,
and updates that don't end your sessions.
Download for macOS · termy.nugo.cc · macOS 14+
Press ⌘G to jump straight to the next WAIT agent.
Running N coding agents — Claude Code, Codex CLI, OpenCode, Antigravity CLI, pi, or any mix — in a stock terminal turns into tab roulette: which session is blocked on a permission prompt, which is mid-tool, which already finished? You end up Cmd-Tabbing through windows, scanning panes, and missing the one that was waiting on you five minutes ago.
termy pulls that state out of the panes and into a glanceable dashboard.
Every running agent gets a chip at the bottom of the window with its live
status: IDLE, THINK, WAIT, or ERR. When an agent needs permission or
input, macOS notifies you — even when termy is in the background. One keystroke
takes you there.
Other terminals give you tabs. termy gives you projects.
Every pane belongs to a project (its cwd), and the top filter bar shows one
pill per project. Click termy to see only the termy panes. Click ALL to
see everything. Same project → same jewel-tone accent everywhere — pane header,
dashboard chip, filter pill — so a four-agent window stops looking like a soup
of identical black rectangles.
Drag the titlebar chips to put projects in your order. The same order drives ⌘1–⌘9, the ALL view, and focus order. ALL packs every pane into one even grid with each project's panes kept together, while a single project keeps the split layout you built.
Hold ⌘ and a number appears on every filter pill. Press the number — you're there. ⌘0 is always All; ⌘1–⌘9 jump straight to that project's pane grid. ⌘⇧[ and ⌘⇧] walk the filters in order.
Prefer names? ⌘K opens a fuzzy project switcher over every project termy has seen, with pane counts and "last used" timestamps. Picking one restores that project's saved pane grid. Renamed or deleted a project folder? The trash button at the end of its row (or ⌘⌫ with an empty search) removes it from the list; the folder itself is never touched.
The strip along the bottom of the window is one chip per running agent — Claude Code, Codex CLI, OpenCode, Antigravity CLI, or pi, mixed freely. Each chip shows project / branch and a live state. While an agent works, a bar in the project's color slides along that pane's header.
IDLE— agent is at the prompt, nothing running.THINK— a tool call is in flight. The model is doing work.WAIT— blocked on a permission prompt or a question, or finished a turn you haven't looked at yet. Your attention needed.ERR— the agent or its shell exited with an error. The chip stays red until you look.INIT— a fresh pane, until the agent reports its first event.
⌘G jumps to the next WAIT pane, wherever it is —
across splits, across project filters, across windows. The single most useful
keystroke in the app. ⌘⌥G walks every
dashboard chip in order.
Hold ⌘⌥ and a number appears on each dashboard chip; press the number to focus that pane directly, even if it's in a different project filter.
Open several windows and each strip shows the chips for every window at
once. Click a chip — or tap a WAIT notification — and termy brings the
owning window forward and focuses the right pane.
⌘-click a Markdown or PDF path in any pane — a spec an agent just
wrote, a plan, a generated report — and termy opens it in its own preview
window. Drop a Markdown or PDF file on a Markdown preview window to do the
same. Previews follow your light or dark appearance and update live as the
agent writes. PDF links inside a Markdown preview, and file:// links to
PDFs, open there too — even when the filename has spaces or parentheses.
- Markdown, live. Tables, task lists, and code blocks look the way they do on GitHub. When an agent edits the file, the preview updates in place and keeps your scroll position. ⌘W closes the preview without touching your panes.
- PDF, live. Open a PDF path the same way. A regenerated file updates the preview while keeping the page and zoom you were reading; a half-written file leaves the previous version on screen.
- Show in Finder. ⌥⌘R, or right-click the preview, opens the file's folder with the file selected.
- Five agents, one dashboard. Claude Code, Codex CLI, OpenCode, Antigravity
CLI, and pi — mixed freely in the same window. Every integration except pi
installs from the termy menu and reports live state through hooks or a
plugin. pi needs no install — it reports its own state over OSC 7501. A
WAITflip pings macOS even when termy is in the background. - Workspace that survives. Splits, project grouping, and cwd are all persisted per project. Pick a project in ⌘K and termy rebuilds the pane grid you left it in.
- Updates that wait for you. Install and Relaunch waits while an agent is
mid-turn, then restarts once every agent has finished. Claude Code, Codex,
and Antigravity conversations reopen in place (
claude --resume,codex resume,agy --conversation), flags included. pi conversations are not resumed yet. In a hurry, choose termy ▸ Restart Now to Install Update. - One window per monitor. ⌘N opens an independent window — its own pane grid, project filter, and split behaviour.
- Quit and come back. Relaunch and every window returns — frames, positions, pane layouts, and project filters. A window stranded off-screen is clamped back onto a visible display.
- Agents that outlive termy. Turn on Settings… → Run local panes in herdr-core and panes run inside herdr-core instead of a PTY termy owns. Quit termy or install an update and Claude Code keeps working; the next launch puts each pane back on the same terminal, with the same screen and process. Off by default; termy offers to install herdr-core when it is missing. These panes show a small herdr mark at the right end of their header.
- Remote projects. ⌘K → New Remote Project… opens a
folder on another machine you added with
hc machine add. Panes are titled<folder>@<machine>, new panes and splits open on the same machine, and the agents there show up in the dashboard like local ones. - Real splits. ⌘T new pane, ⌘D splits the focused pane right, ⇧⌘D splits it down. Drag the dividers, and the sizes stick. ⌘⏎ toggles maximize.
- Drag panes around. Drag a pane by its header and a shadow box shows where it will land and how big it will be: a pane's edge splits just that pane, the gap between two panes slots it in between, the window's edge spans the whole side, and a pane's middle swaps the two. Esc cancels. The layout is saved per project and comes back after a restart.
- Input that stays out of your way. Drop files from Finder onto a pane and termy types the absolute paths, escaped and ready for zsh. ⇧⏎ inserts a newline in Claude Code instead of submitting the prompt.
- Real mouse apps. Clicks and drags go to apps that use the mouse — Claude Code fullscreen, tmux, vim — the way Ghostty and iTerm2 do. Hold ⇧ to select with termy instead, and the selection survives scrolling.
- Scrolling that follows your fingers. Trackpad scrolling moves by the
distance you swipe, with Ghostty-style momentum; a mouse wheel moves three
rows a notch. Scrollback stops snapping to the bottom while you read, and
follows again once you scroll back down. Tune the speed with
termy.scrollSensitivity. - Fonts, themes & Korean input. Pick a monospaced font, a Korean fallback, and a size — changes apply live. ⌘⇧T cycles System / Light / Dark. Korean IME composition and circled numbers like ①②③ no longer cover the line.
- Projects in your order. Drag titlebar chips to reorder projects; the order drives ⌘1–⌘9, the ALL view, and focus order. Remove folders you renamed or deleted from the ⌘K list — the folder itself is never touched.
- Native, not Electron. AppKit + SwiftTerm. A signed, notarized DMG, real
UserNotifications, Full Disk Access, titlebar chrome — and Sparkle updates that verify every build.
Each installer is non-destructive: termy owns only its own keys or file, preserves the hooks and plugins you already have, and backs up any existing configuration file before changing it. Move the app and the next launch re-registers the new hook path. You can uninstall any integration from the termy menu without touching your own configuration.
First launch asks once — "Install termy hooks into Claude Code?" — and the
app merges its entries into ~/.claude/settings.json, preserving any hooks
you already have. Every entry is tagged _termy_managed: true so uninstall
is surgical, and the previous file is backed up to
settings.json.backup-<ts> before any write.
- If you move the app, the next launch detects the stale path and silently re-registers against the new location.
- To uninstall, use the termy menu → Claude Code Hooks… → Uninstall. Your own hooks are untouched.
termy-hookalways exits0and write-timeouts after 100 ms — it cannot stall Claude Code even if termy isn't running.- Permission, question, and MCP-tool approvals all flip the pane to
WAITand trigger the macOS notification.
Codex CLI is supported via the same termy-hook binary. If
~/.codex/hooks.json exists, termy writes its hook entries there; otherwise
it uses ~/.codex/config.toml. Either way it enables [features] hooks = true.
Blocks are tagged _termy_managed = true, your other hooks and feature
settings are preserved, and the files it changes are backed up before a write.
If termy detects a Codex install (it probes ~/.codex and the common
Homebrew / npm / cargo / mise / asdf install paths), it will offer to install
the integration on first launch; otherwise opt in any time via
termy menu → Codex Hooks…
Mappings (per developers.openai.com/codex/hooks):
| Codex event | Pane state |
|---|---|
SessionStart |
hard reset to IDLE |
PreToolUse / PostToolUse |
THINK |
PermissionRequest |
WAIT + macOS notification |
Stop |
IDLE after 30 s |
Codex has no native SessionEnd hook; termy synthesizes one by watching
the foreground process group of each pane's PTY (tcgetpgrp + libproc).
Once codex leaves the foreground (/exit, Ctrl-C), the chip resets to
neutral INIT automatically — even though no hook fired.
Claude Code exposes a complete state-tracking surface: Notification fires
the moment Claude stops to ask for input, and Stop fires when the agent
finishes a turn. Codex's hook surface is narrower. There's no
Notification-equivalent — PermissionRequest fires only for explicit
permission asks, not the general "I'm waiting on you" pauses that reasoning
models (GPT-5, o-series) lean on. Result: a Codex pane can sit silent at a
> prompt with no hook ever firing.
termy fills the gap with a two-stage silence detector: ~8 s of PTY quiet
moves the chip to a silent POSSIBLY_WAITING (visual only, no sound), and
~12 s of further quiet promotes it to WAITING (chip + macOS notification).
Any byte from the PTY reverts the silent state instantly. The trade-off:
Codex WAIT lands ~20 s after the agent actually paused rather than
instantly, and the false-positive rate isn't zero. If Codex ships a
Notification-equivalent in future, termy will switch to it and drop the
heuristic.
OpenCode talks to termy through a small TUI plugin instead of hooks.
termy menu → OpenCode Plugin… installs exactly one file,
~/.config/opencode/plugins/termy/tui.js, and never edits opencode.json.
The plugin watches the routed root session's permission, question, and busy
flags plus its execution outcome, and reports transitions. termy maps them to
IDLE, THINK, WAIT, and ERR. OpenCode sessions that are already open
pick it up right away. Uninstall removes termy's file and keeps other plugins
in place.
Antigravity CLI (agy) loads global hooks from
~/.gemini/config/hooks.json. termy owns a single top-level "termy" group;
your other hook groups stay untouched, and the previous file is backed up
before a write. Install or remove it from termy menu →
Antigravity Hooks…
The hooks report the same IDLE, THINK, WAIT, and ERR states, and let
termy reopen the same conversation with agy --conversation after an update.
| ⌘G | Jump to next WAIT pane |
| ⌘⌥G | Jump to the next dashboard chip |
| ⌘⌥1–9 | Jump to dashboard chip N (hold ⌘⌥ to see numbers) |
| ⌘0 | Show all projects |
| ⌘1–9 | Jump to project filter N (hold ⌘ to see numbers) |
| ⌘⇧[ / ⌘⇧] | Previous / next project filter |
| ⌘K | Fuzzy project switcher |
| ⌘⌫ | In ⌘K, remove the selected project from the list |
| ⌘[ / ⌘] | Previous / next pane |
| ⌘⌥←↑↓→ | Focus pane in direction |
| ⌘D / ⇧⌘D | Same-row / new-row split |
| ⌘T | New pane — auto-splits, picks row/column from aspect ratio |
| ⌘N | New window — its own pane grid, project filter, and splits |
| ⌘⏎ | Toggle maximize on the focused pane |
| ⌘W | Close focused pane (or the current preview) |
| ⌘⇧W | Close window |
| ⌘⇧T | Cycle theme — System → Light → Dark |
| ⌘+ / ⌘− | Increase / decrease terminal font size |
| ⌘, | Settings — font, alerts, quitting |
| ⌥⌘R | Show the previewed file in Finder |
| ⌘/ | Full shortcut overlay |
Claude Code ──hook───▶ termy-hook --agent claude-code ─┐
Codex CLI ──hook───▶ termy-hook --agent codex ─┤
OpenCode ──plugin─▶ termy-hook --agent opencode ─┼─ unix socket ─▶ HookDaemon (in-app actor)
Antigravity ──hook───▶ termy-hook --agent antigravity ─┘ │
pi ──OSC 7501─▶ pane terminal (in-process, fg must be an agent) ───────┤
▼
┌─────────────────┐
▼ ▼
PaneStateMachine fg-process watcher
│ (synthetic SessionStart/End)
▼
MissionControlView + Notifier
- SwiftTerm renders the PTY and owns the child shell lifecycle.
- herdr-core (optional). A herdr-core pane has no local PTY: termy talks
to the terminal through
herdr-core connect, and the terminal (with the agent in it) lives in herdr-core until you close the pane. termy finds its terminals again by label on launch. herdr-core's own agent status drivesTHINK/WAIT/IDLEfor those panes, and hooks fill in the prompt and last reply. termy-hookis a tiny Swift CLI that Claude Code, Codex, and Antigravity invoke per hook event; OpenCode's plugin spawns it too. It slims the payload and sends one JSON line over/tmp/termy-$UID.sock. It always exits0and times out writes after 100 ms, so it cannot stall an agent. pi does not use it — pi reports its own state over OSC 7501.HookDaemonis an actor that receives those events. They flow throughPaneStateMachine, the pure reducer covered by 870+ unit tests — including Claude Code's permission, question, and MCP-tool approval events.- OpenCode plugin. A small
tui.jswatches the active session's permission, question, and busy flags and reports transitions; termy maps them toIDLE,THINK,WAIT, andERR. - Antigravity hooks. Installed into
~/.gemini/config/hooks.json, they report the same states and let termy reopen the same conversation withagy --conversationafter an update. - Every installer is non-destructive. termy owns only its own keys or file, backs up configuration before changing it, and uninstalls from the termy menu without touching your own hooks.
- Synthetic
PtyExitfills the gap hooks can't — hard crashes (Ctrl+C mid-response, SIGKILL) fire no hook, so termy emits a synthetic event on PTY EOF. A 1 Hz foreground-process watcher does the same whenclaude,codex,opencode,agy, orpileaves a pane. - Codex hook coverage caveat. Claude Code emits a
Notificationhook the moment it stops for input; Codex doesn't.PermissionRequestonly fires for explicit asks, not the general "I'm waiting on you" pauses reasoning models lean on. termy fills the gap with a two-stage silence detector (~8 s → silentPOSSIBLY_WAITING, ~12 s →WAITING+ sound). Trade-off: CodexWAITlands ~20 s after the agent paused, not instantly.
Shipping. The core loop is working end-to-end:
- Five agents end-to-end — Claude Code, Codex CLI, OpenCode, Antigravity CLI, and pi (OSC 7501, no install)
- Live dashboard with
THINK/WAIT/IDLE/ERR, notifications, and ⌘G navigation - SwiftTerm panes with OSC 7 cwd tracking, splits, mouse-aware TUIs, and ⌘-click URLs
- Markdown and PDF previews with live updates, drag-to-open, and Show in Finder
- Hook daemon +
termy-hook+ non-destructive installers for every hook-based integration - Workspace autosave, multi-window dashboard, and full session restore
- Project chips you can reorder and prune, per-project accents, and ⌘1–⌘9 filters
- Sparkle auto-update that waits for running agents and resumes their conversations
- Optional herdr-core panes whose agents survive quitting termy, and remote projects on other machines
- Developer ID-signed, notarized DMG pipeline and 870+ unit tests
See TODOS.md for deferred work — screen-scraping fallback for agents without
hooks, a separate LaunchAgent daemon, user-editable hook config, and a
per-project settings UI.
docs/project-overview.md— architecture, runtime, hook system constraintsdocs/auto-update.md— Sparkle release and update runbookTODOS.md— scoped-out work with reasoningapps/termy/Sources/— the appapps/termy-hook/Sources/— the hook helper CLIapps/termy-tests/Sources/— 870+ tests across 70+ suites