Running coding agents

The parts of TermHQ built specifically for running Claude Code, Codex, and other coding agents.

TermHQ is a terminal, so any agent that runs in a terminal runs in it. These are the parts that exist because of agents specifically.

Recognizing a running agent

A recognized local agent replaces the terminal’s generic mark with its product icon. This works whether you use a launcher or type the command yourself. The same live identity appears in Stash, Waiting and Undo Close, including the latest waiting and undo items in the status bar. Stashing or closing a terminal for Undo does not freeze its icon: it follows the agent that is actually running and clears after that agent exits.

Settings → Agents → Show active agent icons is on by default. Turn it off to remove these marks and stop the window’s agent checks. Detection uses local process ownership, rather than terminal titles or text printed by a command. It checks about once a second and does not send agent commands or prompts. GitHub Copilot’s native WinGet and Homebrew packages are recognized alongside its npm installation.

SSH panes, and installations TermHQ cannot identify, keep a generic mark. In a WSL pane running bash, agents are recognized too, read from the distribution’s own processes while a command runs. A WSL pane running zsh or fish, a .bashrc that replaces PROMPT_COMMAND, or wsl.exe typed into another shell keeps the generic mark. On custom or older Windows shells, a background agent can sometimes look active when the shell does not expose its prompt boundary. An icon identifies a running program; it does not indicate whether a task succeeded.

Launching one in the focused terminal

A terminal pane’s header has an ✳ button listing your agent commands — Claude Code, Codex, OpenCode, Antigravity, Grok Build, Gemini CLI, GitHub Copilot CLI, Cursor CLI, Muse Code, Hermes Agent and OpenClaw out of the box. Like the header’s other tools, it shows on the focused pane, and on any other pane while the pointer is over it. Picking one types its command into that pane’s shell and hands keyboard focus back to the terminal. The menu ends with Manage agents…, which opens Settings → Agents.

A launcher appears once its command is on your PATH, and an install that predates one of them picks it up on its own. Gemini CLI, GitHub Copilot CLI, Cursor CLI, Muse Code, Hermes Agent and OpenClaw must also be the product they claim. A program name can belong to something else — agent is also Grok’s, and copilot is also AWS’s — so TermHQ runs each with --help and checks that it names the right product before listing it. That check passes nothing else, not your configured prompt or flags, and gives up after five seconds. With none found, the button stays, dimmed, and takes you to Settings → Agents to set one up. A pane whose shell has ended has no agent button, since there is nothing to type into, and neither has an SSH pane: the agents TermHQ found are on this machine, and the command would run on the far host.

An agent you install while TermHQ is open shows up the next time the window comes to the front, when Settings or the agent picker opens, or when you press the refresh button in Settings → Agents. On macOS, if the installer added a folder of its own to your PATH, the refresh button is what finds it — see Command detection on macOS. Once TermHQ has found it, a terminal you open finds it by name. One that was already open may not, since its shell’s PATH was set when it started: typing the name there can fail, but launching the agent from TermHQ types its full path instead, flags kept. A WSL terminal still gets the name, since its PATH is Linux’s.

Use a terminal at an idle shell prompt. Finish or clear any partially typed command first, and do not launch into a program that is already using the terminal. To keep that program running, launch the agent in a new pane instead.

A pane that already has an agent running in it is left alone. Neither the pane’s ✳ menu, nor the numbered picker below, nor the command palette’s Run entries type anything into it, and the pane says so — Claude Code is already running in this pane, with that agent’s name. The picker’s shortcut shows the same note instead of its list.

TermHQ knows the agent from the ones it recognizes in the pane, whether or not Show active agent icons is on. Where the shell reports each prompt to TermHQ — as PowerShell, Command Prompt, Git Bash and WSL’s bash do on Windows — an agent a launcher started there also counts until the shell’s next prompt, which covers agents TermHQ doesn’t recognize. For a second agent, open it in a pane of its own; Duplicate does that in one step.

In any shell, a second launch into the same pane within three seconds is not sent at all, so a double click never types the command twice; the pane says Sent a moment ago · one command every 3 s.

The list is yours to edit in Settings → Agents → Agent launchers, flags included, so claude --dangerously-skip-permissions is one click rather than something you retype all day. It holds the agents TermHQ found and the ones you added or edited yourself. Each row shows the number the agent answers to (a dash if it has none), its mark, its name, whether its command was found — found, not on PATH, not verified (found, but not the product it’s named for; its hint says why), or checking… — and the command itself. Add agent starts a new row; drag a row by its grip to reorder, or focus the grip and use the arrow keys; removing one asks Remove? first.

Built-in launchers TermHQ has not found wait under the list, folded into Built-in agents not detected, and join it on their own once installed. A built-in you removed is offered under Restore removed agents: one click puts it back, and it is checked like the rest. Entries whose program is not on your PATH are hidden from the menus automatically, so a launcher missing from the menu is explained where you would look for it. If the numbered picker has no available entries, the command palette tells an empty agent list apart from agents it could not find on your PATH.

Command detection on macOS

Opening TermHQ from Finder or the Dock should find the same agent CLIs as your terminal. TermHQ reads the PATH from your interactive login shell and caches it, including paths added by Homebrew, npm and shell startup files. IDE and file openers use that resolved path too. The initial launcher lookup runs in the background so it does not hold up the interface.

If your shell’s PATH changes while TermHQ is open — an installer adding a folder of its own, say — press the refresh button in Settings → Agents: it asks your login shell for its PATH again before it looks, so there is no need to restart. The one under the Open in IDE picker does the same for editors. The quiet checks — when the window comes to the front, or when Settings or the agent picker opens — keep the PATH TermHQ already read, which still finds an agent installed into a folder already on it. On Windows, TermHQ uses the path in its process environment plus any folders an installer has added since, so a new install is found without restarting.

Launching one in a folder or worktree

You do not need to open a terminal first. Anywhere TermHQ offers an Open in <shell> list — a folder in Files, a favorite, or a row in the global Worktrees view — open the flyout on the shell you want: click the chevron at the row’s edge, right-click the row, or press → on it. The flyout lists the installed agents under the same marks as the pane-header launcher. Pick one and TermHQ opens that shell in the selected folder, then starts the agent in it.

A click on the row itself still opens only the shell. The agent list waits behind the chevron so the ordinary “open a terminal here” action stays unambiguous.

The arrow beside the + button in the title bar opens the shell menu, which reaches the same place without the Files panel: a shell’s flyout lists your favorite folders, and a favorite’s flyout lists the agents to start there.

By number, without the mouse

Several agents across several panes should not mean a trip to a dropdown for each. Ctrl+Shift+A then a digit runs an agent in the focused terminal: 1–9 and 0 for the tenth, in the order the list is arranged in Settings. While it is armed, a card lists the numbered agents so the mapping is never guesswork, and its title names the terminal the command will be typed into; Esc cancels.

Only installed agents are numbered — the same PATH filtering as the dropdown, so the numbers always match what you can see. Both the number row and numeric keypad work, including 0 for the tenth entry.

The chord needs a terminal with its shell still running, since what it does is type a command into it. With an editor or a browser pane in front, a terminal whose shell has ended, or an SSH pane, it does not open a picker that could not work: the key goes on to the pane, and the command palette’s Run an agent by number row says why.

The command palette also lists each installed agent by name — Run Claude Code and the like — to type into the focused terminal.

A second agent beside the first

Duplicating a terminal that has an agent running in it — the pane header’s clone button, or Ctrl+Shift+J — starts the same agent in the copy. It’s a fresh session from that agent’s launcher, in the same shell and, with Clone keeps directory on, the same folder. It isn’t a copy of the running conversation. Settings → General → Clone starts the agent too turns this off, and the copy is then a plain shell. So is the copy of an agent that has no launcher in Settings → Agents.

Agents that work TermHQ themselves

Agents can also use TermHQ for themselves: list and read the other panes, start another agent and hand it a task, open files, or ask you a question, each only as far as you allow in Settings → MCP. See Letting agents use TermHQ.

You can follow that work from the panes themselves. A pane an agent started says from pane 3 in its header, and the pane that started it counts its helpers in a chip of its own. When one agent leaves another a message, the sender and its first line show for a moment under the receiving pane’s header.

When a pane needs your attention

The problem with running several agents is not starting them, it is noticing when one stops.

A pane that was busy while it was out of sight and has since gone quiet gets a pulsing header: the icon at its left that shows what kind of pane it is pulses in the theme’s attention color, and an inset wash and the bottom hairline breathe with it. A stashed terminal moves to the top of the stash shelf under Waiting on you, with the time it went quiet, and its row glows the same way, so a parked job can still get your attention. This works for longer-running commands as well as coding agents.

Only a pane out of sight can be waiting: one behind another pane’s maximize, or one parked on the stash shelf. A pane you can see, focused or not, never counts.

Waiting panes collect in the bottom status bar as a count — N waiting — that stays as long as anything is waiting. For a few seconds after a new pane goes quiet, a chip joined to its left names that pane under a draining bar; click the chip to jump straight to it. Click the count to open the list, newest first, laid out like the stash shelf’s: each entry shows what kind of pane it is, its name and its folder — followed by · stashed when it is parked on the shelf — and, at the right, the time it went quiet, such as 2:45 PM.

Click an entry to focus that pane, restoring it from the shelf or bringing it back into view if another pane is maximized. From the keyboard, Tab to the count and press Enter: the list opens with focus on its first entry, ↑ ↓, Home and End move between entries, and Enter or Space jumps. The × on an entry — or Delete, or a middle click — dismisses only the notice; it does not close the pane or stop its work. With more than one waiting, Dismiss all at the foot of the list clears every notice at once. Esc closes the list without clearing it.

Ctrl+Shift+N — Jump to the newest waiting pane — goes straight to the pane that went quiet most recently, the first entry in the list, without opening it.

Notices do not expire on a timer. Returning to the pane, dismissing its notice, or closing the pane clears its entry. Leaving the maximize clears the notices of the panes in the grid, and opening the stash shelf clears those of the stashed panes. The waiting item disappears when the list is empty by default. To keep it visible, enable Settings → Agents → Always show it, even when nothing is waiting. It then reads 0 waiting, and opening the empty list shows Nothing waiting right now.

When TermHQ is in the background, a pane out of sight that goes quiet also sends a native OS notification, and the in-app entry is waiting for you when you return. Show waiting panes in the status bar in Settings → Agents controls both kinds of notification; Agent idle badge controls the pane and shelf highlights separately.

TermHQ ignores the echo of your own typing, work that finished in view, and jobs over in under three seconds. A fresh terminal’s startup output does not trigger a waiting notice before you run a command or launch an agent in it.

Quiet does not necessarily mean finished or successful. An agent may be thinking or asking for input. Read the pane’s output to confirm its state. The default quiet period is 10 seconds; increase Quiet seconds before badge in Settings → Agents if an agent is being flagged during normal pauses. That threshold also applies to waiting notices.

Agents come up in color

Coding agents often render monochrome inside other terminals, and the usual culprit is not the agent. When one tool launches another, environment variables leak: a NO_COLOR=1 set by whatever started your terminal is inherited by every shell it spawns, and well-behaved programs obey it.

TermHQ scrubs those leaked variables on every shell it starts and sets the capability variables that say color is supported. Agents come up in color because the environment they are handed is correct, not because TermHQ special-cases any particular tool.

Panes are born at their final width

A pane is created at the size it will be displayed at, so a shell’s startup output — and an agent’s first banner — is composed for the width you will read it at rather than reflowed afterwards.

Watching several at once

Tiling is the point. Agents working means panes visible, not tabs where all but one are hidden. There is no cap on how many — the grid keeps growing, and when it gets busy you can park the ones you are not watching without stopping them.

Each pane’s font size is independent, so an agent producing a wall of output can be small while the shell you type in stays comfortable.

Watching what an agent is building

An agent building a web app is producing something you have to look at, and alt-tabbing to a browser window is how you lose the pane it is working in. Ctrl+Shift+B opens a browser pane in the grid instead — point Settings → Browser → New panes open at localhost:3000 and every new one lands on your dev server. Drag the boundary between it and the agent’s terminal to give the page the width it wants; a web page has a natural width and a terminal does not.

Long jobs survive you leaving

Agents run long. Because shells live in a separate process (Persistent sessions), you can quit TermHQ while an agent is mid-task and pick it up later with its output intact.

Installing an update restarts the shells, however. Finish important jobs before choosing Update and restart; see Updating.

Directory awareness

TermHQ knows which directory each pane is in, and keeps up as the shell moves around. The file panel follows the focused pane, so it is already showing the folder the agent is working in rather than your home directory. So does Source Control — repository, branch, changes, staging, commits and history for whichever pane you are looking at, which is how you review and ship what an agent just did without leaving the app.

If you use separate Git checkouts for parallel tasks, the global Worktrees view keeps them grouped by repository and puts a terminal or agent action directly on each one. It shows checkout state without guessing whether an agent is running there.

Files follows WSL directories too, and Source Control opens repositories inside WSL with that distribution’s own git.

The </> button in the pane header opens that directory in your editor, for the moments when the right move is to take over by hand. For a smaller intervention — one line in a config, a typo in a prompt file — an editor pane opens the file right there in the grid, beside the agent that is waiting on it. A file an agent rewrites while you have it open reloads on its own, or asks first if you have unsaved edits of your own.

The editor the </> button opens is the one chosen in Settings → Agents → Open in IDE, and the same choice serves every Open in IDE in the app. The picker lists the supported editors installed on this machine, each under its mark: Visual Studio Code, Visual Studio (on Windows), Cursor, Antigravity IDE, Windsurf, VSCodium, Zed, IntelliJ IDEA, PyCharm and WebStorm. Automatic uses the first one listed. An editor you pick stays picked, and if it goes missing it is marked not found rather than swapped for another. Use IDE command…, at the end, runs a command of your own, flags included; a configuration from before the picker starts there, so its command keeps working. With no supported editor found, the picker says so and there is no </> button: install one and press the refresh button under the picker, or give a command of your own.

Dictating to an agent

Prompts are long, and typing them is the slow part. TermHQ’s dictation types into the terminal you started it in, so you can talk a prompt at an agent and edit it before sending — and click over to another pane while it transcribes without the words following you. Opt in to Hold to talk and holding the space bar for a moment is the whole gesture, the way Claude Code’s own dictation works, for every program; rebind it to a key of its own (Right Ctrl, say) and Claude Code’s keeps working beside it.

Transcription happens on your machine, on a local Whisper model you pick and download once in Settings → Voice (or bring your own) — which matters for a tool sitting in front of proprietary source. English by default, fifteen other languages in the same panel. Linux support is pending. The whole feature has its own page: Dictation.

Keeping their keystrokes theirs

Agents with full-screen interfaces want chords TermHQ also uses. Ultra focus hands the terminal every key unmodified; only its own toggle and Ctrl+Shift+V, which pastes, stay TermHQ’s. See Keyboard shortcuts.