Skip to main content

How Agents Drive the Terminal

TermFlow is a terminal emulator that an AI coding agent can operate directly — opening terminals, running commands, and reading output — instead of you copy-pasting between a chat window and a shell. This page explains the mental model behind that.

The core idea​

TermFlow does not contain an AI. You bring your own agent (Claude Code, Codex CLI, Gemini CLI, or any other MCP client) and your own API keys. What TermFlow adds is a pair of local interfaces that let that agent treat the terminal as something it can control programmatically:

  • a built-in MCP server (streamable HTTP) that any MCP client can connect to, and
  • a REST + WebSocket API on localhost for building your own tooling.

Through either interface, an agent performs the same handful of verbs a human does at a terminal:

The agent wants to...How it does it
Open a terminal or split a panecreate_terminal (MCP) / POST /api/terminals (REST)
Run a commandexecute_command (MCP) / POST /api/terminals/:id/execute (REST)
Read what came backget_terminal_output (MCP) / GET /api/terminals/:id/output (REST)
List what's runninglist_terminals (MCP) / GET /api/terminals (REST)
Close a terminalclose_terminal (MCP) / DELETE /api/terminals/:id (REST)

That's the whole relationship: the agent is a client, TermFlow is the terminal it drives. Agents are complements, not competitors — TermFlow sells no AI usage and ships no model.

info

The MCP server and the REST API are two front doors to the same engine. The MCP tools are a thin, agent-friendly wrapper over the REST API. Anything an agent can do over MCP, you can also script directly over REST — see The REST + WebSocket alternative.

Two processes, two ports​

Under the hood, TermFlow runs two cooperating servers on your machine (default production ports shown):

ComponentPortWhat it is
API server42031An Axum (Rust) HTTP + WebSocket server that owns the real terminals (PTYs).
MCP sidecar42032A separate process that speaks MCP to agents and translates their tool calls into API calls.

Both bind to 127.0.0.1 (localhost) by default. An MCP client connects to the sidecar at http://127.0.0.1:42032/mcp; the sidecar forwards to the API server, which actually spawns shells and streams their output back. You can change either port in Settings → Connections.

note

Because both servers bind to 127.0.0.1 by default, every endpoint is unauthenticated in that mode — which is safe precisely because nothing outside your machine can reach it. A bearer token is required only if you turn on "Expose on local network." See Local API and auth for the full model.

Terminal identity: how an agent knows which terminal is "its own"​

When an agent runs inside a TermFlow terminal, TermFlow injects an environment variable into that terminal's shell:

echo "$TERMFLOW_TERMINAL_ID"
# → the id of the terminal this process is running in

The agent forwards that value back to TermFlow as an HTTP header on its MCP requests:

X-Termflow-Terminal-Id: <the value of $TERMFLOW_TERMINAL_ID>

With that header present, TermFlow can resolve the caller's own terminal. Two conveniences fall out of this:

  • The get_my_terminal tool returns the terminal the agent is running in — no id required.
  • Anywhere a tool expects a terminalId, the agent can pass the literal string "me" as shorthand for its own terminal. For example, close_terminal("me") makes the agent self-terminate its terminal.

This is what lets an agent reason about itself ("read the last 50 lines of my own output," "split a pane next to me") without you having to wire terminal ids into its prompt by hand.

tip

The copy-paste MCP config that TermFlow generates for Claude Code and Codex CLI already sets X-Termflow-Terminal-Id to expand from $TERMFLOW_TERMINAL_ID for you. Gemini CLI does not expand variables inside header values, so the identity header is omitted there — a Gemini agent passes its terminal id explicitly when it needs one. See Connect an agent — overview.

What happens when an agent runs a command​

Here is the full round-trip for a single execute_command call, from the agent's tool call to the output landing back in the terminal:

Two things in that diagram are worth calling out:

  • execute_command is asynchronous. It writes the command to the shell and returns immediately — it does not wait for the command to finish. Long-running or interactive commands keep producing output after the call returns.
  • Output arrives two ways. Live output is pushed as output.data events over the WebSocket stream (ws://127.0.0.1:42031/ws) as it happens; an agent can also pull a clean text snapshot at any time with get_terminal_output. Most agents poll get_terminal_output after issuing a command; tooling that wants a live feed subscribes to the WebSocket. See the WebSocket reference.

Batch fan-out​

Because execute_command accepts an array of terminal ids as well as a single one, an agent can send the same command to many terminals at once — the foundation for multi-agent and multi-pane workflows.

execute_command(["term-a", "term-b", "term-c"], "git pull")
        │
        ├──▶ terminal A: git pull
        ├──▶ terminal B: git pull
        └──▶ terminal C: git pull

Over REST the same idea is POST /api/terminals/batch/execute, which returns a per-terminal results[] plus a summary of totals. See Execute and batch and the tutorial Fan a command to many panes.

Roadmap: hosting agents inside TermFlow​

Today the relationship is one-directional in one sense: the agent is always the client that reaches in to drive TermFlow, whether it runs inside a TermFlow terminal or in a separate process.

An honest note: ACP — hosting an agent inside TermFlow, so TermFlow itself launches and manages the agent's lifecycle — is on the roadmap and not implemented. No ACP code exists in this release. Anything you read elsewhere describing TermFlow as an agent host is describing a future direction, not current behavior. For now, you run your own agent and point it at TermFlow's MCP server or REST API.

Next steps​