Skip to main content

Agent Color Schemes

TermFlow can recolor a pane automatically based on which coding agent is running inside it — so a glance at the screen tells you "this pane is Codex, that one is Claude." This page explains how detection works, how to assign a scheme to an agent, and the sticky rules that decide when a pane keeps or drops its agent colors.

What this does​

When a coding-agent CLI (Codex, Claude, Gemini, and friends) is the foreground process in a pane, TermFlow can apply a terminal color scheme you have mapped to that agent. The mapping is keyed by the agent's name, not by a specific pane — assign Codex the Dracula scheme once, and every pane where Codex is running turns Dracula.

Two things drive the feature:

  • A small AgentChip pill in the pane's top-right corner that names the running agent.
  • A background poller that watches each pane's foreground process and applies (or reverts) the matching color scheme.
Nothing to configure to see the chip

Agent detection and the AgentChip work out of the box. Color schemes only change once you actually assign one to an agent — until then, detection is purely informational.

How detection works​

TermFlow polls its own local API endpoint GET /api/processes roughly every two seconds. That endpoint reports each terminal's foreground process and, when it recognizes one, the coding agent behind it. For every pane your window owns, TermFlow records:

  • the detected agent (whatever is running — powers the AgentChip and the right-click menu), and
  • the effective agent (only agents you have mapped to a scheme — this is what actually recolors the pane).

The poller is deliberately economical: it pauses while the window is hidden, and if you have no agent schemes mapped and nothing is currently themed, it skips the enumeration entirely. Opening the pane's right-click menu forces an immediate refresh so a just-started agent is offered right away.

The AgentChip​

The AgentChip is a floating pill in the top-right corner of a pane that names the detected agent. When TermFlow can resolve the agent's executable it shows the binary's real icon; otherwise it falls back to a small running dot. The chip is purely informational — it never intercepts clicks or text selection — and it disappears within one poll after the agent exits.

+-------------------------------- Pane ------------------------------+
|                                                     ( . ) codex  <-- AgentChip
|  $ codex                                                          |
|  > refactoring the auth module...                                 |
|                                                                   |
|  (this pane is tinted with the scheme mapped to "codex")          |
+-------------------------------------------------------------------+

Assigning a scheme to an agent​

There are two ways to map an agent to a color scheme. Both write the same per-agent mapping, so a change in one place is reflected in the other.

1. From the pane right-click menu​

Right-click inside a pane where an agent is running. Near the top of the menu you'll see Color scheme for "<agent>" (for example, Color scheme for "codex"). Expand it to reveal a swatch grid of every built-in scheme:

  • Pick a scheme to map it to that agent.
  • Pick Use tab / default to remove the mapping and let the pane fall back to its tab or global scheme.

If no agent is detected in the pane, the menu item is disabled and reads "No coding agent detected in this pane."

+- codex ----------------------------+
|  Pane ID:      p-3f9a...            |
|  Terminal ID:  t-71c2...            |
|  --------------------------------   |
|  [*] Color scheme for "codex"   v   |
|     +--------------------------+    |
|     | ( ) Use tab / default    |    |
|     | [#] Dracula   [#] Nord   |    |
|     | [#] Monokai   [#] Tokyo  |    |
|     | ...                      |    |
|     +--------------------------+    |
|  --------------------------------   |
|  [+] Open New Tab                   |
|  [ ] Open New Window                |
+-------------------------------------+

2. From Settings → Appearance → Agent Color Schemes​

Open Settings → Appearance and scroll to Agent Color Schemes. Every agent you've mapped appears as a row with a scheme dropdown and a remove (×) button. This is the place to review, re-point, or delete mappings without hunting for a running pane. When the list is empty, it points you back to the right-click flow.

The built-in library offers more than twenty color schemes — the same set used by the global Color Schema picker — including Default, Dracula, Nord, Solarized (dark and light), Tokyo Night, Gruvbox, Monokai, One Dark, Night Owl, and Rosé Pine.

Precedence: which scheme wins​

While a mapped agent is running in a pane, its scheme overrides both the tab scheme and the global default scheme for that pane only. Remove the mapping and the pane goes back to its tab or default colors.

agent scheme  >  tab scheme  >  global Color Schema (default)
  (highest)                             (fallback)

Sticky by last writer​

An agent finishing a task shouldn't make its pane flicker back to plain colors the instant it exits — especially when an API or MCP client kicked off a long job. TermFlow decides whether to keep the agent's colors based on who wrote to the terminal last, not on a timer:

SituationWhat happens to the pane
A mapped agent is runningPane uses that agent's scheme
Agent exited, API/MCP wrote lastScheme stays (sticky — an automated task is driving it)
Agent exited, you typed lastReverts to the tab/default scheme on the next poll
You remove the agent's mappingReverts on the next poll
Agent running but not mappedNo color change; the chip still names it so you can assign one

The rule of thumb: while an API or MCP client is the last thing to touch the terminal, its colors stick; the moment you type, the next poll hands the pane back to its normal scheme.

An honest note: Only agents that TermFlow's process detection recognizes get an AgentChip, and only agents you've explicitly mapped ever recolor a pane. An unrecognized or unmapped tool runs in your normal terminal colors. Detection reflects the foreground process reported by GET /api/processes, so it updates within a poll cycle (about two seconds) rather than instantly.

Next steps​