Skip to main content

The Multi-Agent Power User

You run several AI agents at once — one per pane, sometimes one per window — and you need them to stay legible, controllable, and easy to fan commands across. This guide maps the TermFlow features that make a multi-agent cockpit workable.

Who this is for​

You are comfortable at the terminal and already bring your own agents (Claude Code, Codex CLI, Gemini CLI, or any other MCP client) and your own API keys. TermFlow ships no AI of its own — it is the terminal those agents drive. Your problem is not "how do I run one agent," it is "how do I run five without losing track of which pane is doing what."

The four features you will lean on:

NeedFeatureWhere
Scaffold a shared workspace for several agentstk CLI (tk init)/multi-agent-workflows/tk-cli
Tell agents apart at a glancePer-agent color schemes/using-the-terminal/agent-color-schemes
Fan one command out to many terminalsBatch execute/api-reference/execute-and-batch
Pull a busy agent into its own windowTear-off/using-the-terminal/windows-and-tear-off

The cockpit at a glance​

A common layout: one tab per project, split into panes, one agent per pane, each pane tinted by whichever agent is running in it.

+--------------------------------------------------------------+
| ● proj-api   ● proj-web   ● scratch          [Settings ⚙]    |  tab strip
+----------------------------+---------------------------------+
| pane A  [AgentChip: claude]| pane B  [AgentChip: codex]      |
|                            |                                 |
|  claude> refactor auth...  |  codex> add tests for parser... |
|  (claude color scheme)     |  (codex color scheme)           |
|                            |                                 |
+----------------------------+---------------------------------+
| pane C  [AgentChip: gemini]  (gemini color scheme)           |
|  gemini> summarize the diff on branch feature/login          |
+--------------------------------------------------------------+

Each pane is a real PTY. Split with Ctrl+Shift+D (horizontal), the pane-header buttons, or the context menu; new panes inherit the live working directory of the pane they came from, so an agent split off from proj-api starts in the same folder. Maximize a pane to focus on one agent with Ctrl+Shift+Enter, and restore with the same key. See /using-the-terminal/split-panes for the full split model.

1. Scaffold the workspace with tk​

When several agents share a repo, they need a shared place to leave requests, responses, status, and findings for each other. tk init (from the terminal-kit CLI) scaffolds that for you:

tk init

It creates a .agent-comms/ directory (with requests/, responses/, status/, shared/, findings/, and a README), plus starter config files (.mcp.json, .gemini/settings.json, .claude/settings.local.json) and docs/multi-team-agent-workflow.md. Useful flags:

FlagEffect
-f, --forceOverwrite existing scaffold files
--no-docsSkip generating the workflow doc
--api-urlPoint the scaffold at a non-default API URL
warning

The .mcp.json that tk init generates is stale — it uses a placeholder stdio path, the wrong server key, and lists only a subset of the tools. Use tk init for the .agent-comms/ scaffolding, but configure MCP itself from the in-app Connect modal (Settings → Connections → "Connect an AI agent"), which emits paste-ready config for Claude Code, Codex CLI, and Gemini CLI pointed at http://127.0.0.1:42032/mcp.

Full walkthrough: /multi-agent-workflows/tk-cli.

2. Tell agents apart with color schemes​

With four agents on screen, color is your fastest signal. TermFlow polls /api/processes to detect which coding agent (codex, claude, and so on) is running in each pane and automatically applies that agent's terminal color scheme. A small AgentChip pill names the agent in the pane header, so "which pane is Codex?" is answered at a glance.

The theming is sticky by last-writer: a pane themed by agent detection stays themed, and when you start typing into it yourself, it reverts. You can assign or override a scheme from a pane's right-click menu → "Color scheme for '<agent>'", or manage the whole set under Settings → Agent Color Schemes.

tip

Give each agent a distinctly different scheme (not four blues). The goal is that a glance at the wall of panes tells you who is who without reading the AgentChip.

More detail: /using-the-terminal/agent-color-schemes.

3. Fan one command out to many panes​

The signature multi-agent move is broadcasting a single instruction to every agent at once — "run the tests," "read CONTRACT.md," "report status." TermFlow supports this two ways.

Over MCP, the execute_command tool accepts an array of terminal ids in terminalId. Pass several ids and it fans the command out to all of them in one batch. It is asynchronous and returns immediately rather than blocking on output.

{
  "terminalId": ["term-a", "term-b", "term-c"],
  "command": "read .agent-comms/shared/CONTRACT.md and acknowledge",
  "cliType": "claude"
}

cliType selects how the prompt is delivered per agent (default, claude, gemini, chatgpt, or copilot; the code default is copilot). Use "me" anywhere a terminal id is expected to target the caller's own terminal. See the tool schemas in /api-reference/mcp-tools.

Over REST, if you are building your own orchestrator, POST /api/terminals/batch/execute takes terminalIds[] and a prompt and returns a per-terminal result set plus a summary:

{
  "results": [ /* one entry per terminal */ ],
  "summary": { "total": 3, "succeeded": 3, "failed": 0 }
}

There is also POST /api/terminals/batch/input for sending raw keystrokes to many terminals at once. Both live at the prod API base http://127.0.0.1:42031/api. Full reference: /api-reference/execute-and-batch.

Here is how the pieces connect once you are set up:

4. Tear a busy agent off into its own window​

When one agent needs full attention — a long refactor, a noisy log stream — pull it out. Drag a tab or a pane out of the window and TermFlow opens a new OS window with the live PTY handed over, not respawned: the agent keeps running, its scrollback intact, its process uninterrupted. You can also right-click → "Move to New Window." Drop the tab or pane back onto another window to reattach it.

This is what lets you scale past one screen: keep the orchestration panes together, and tear each long-running agent onto its own monitor. Details and platform notes (a DOM ghost fallback is used on Linux/dev) are in /using-the-terminal/windows-and-tear-off.

Keeping track of what is running​

  • Tab and pane indicators flag activity you are not watching: a running style while a process is live, a 🔔 bell, a ● external-activity dot, and a ⊘ marker when a shell has exited.
  • Smart close confirmation — closing a tab lists the real foreground processes that would be killed, so you do not accidentally take down an agent mid-task. Cleanly exited shells skip the prompt.
  • Per-pane zoom (Ctrl/Cmd with =, -, 0, or the scroll wheel) resizes one pane's text without touching the others — handy for pushing a monitoring pane small and a focus pane large.

An honest note: Hosting agents inside TermFlow (an agent runtime built into the app) is on the roadmap, not shipped. Today, TermFlow drives agents that you launch yourself — either inside a TermFlow terminal (where they are handed a $TERMFLOW_TERMINAL_ID and can call get_my_terminal / use "me" to act on their own pane) or as external MCP clients. There is no built-in command palette and no Alt+Arrow pane navigation; the working cross-pane primitives are the shortcuts and drag gestures described above.

info

If you want to watch or control headless TermFlow instances from a browser — for example a fleet running on another machine — the companion terminal-monitor dashboard (port 42030) is the tool for that. The experimental agent-monitor sample shows one way to chain prompts across agents automatically; treat it as a reference, not a finished product. See /multi-agent-workflows/terminal-monitor and /multi-agent-workflows/agent-monitor.

Next steps​