Skip to main content

What is TermFlow

TermFlow is a cross-platform terminal emulator built so that AI coding agents can drive it — the "terminal for AI agents." This page explains what that means, how the pieces fit together, and where TermFlow deliberately stops.

Version

TermFlow 0.1.0 — Early access · pre-release. Licensed under Apache-2.0. Built with Tauri 2 (Rust backend) + React + xterm.js — not Electron.

The one-sentence version​

TermFlow is a normal, fast terminal you can use by hand — tabs, split panes, shell profiles, search — with one differentiator: an AI agent can open terminals, split panes, run commands, and read the output on your behalf, through local interfaces that TermFlow exposes.

You bring the agent and your keys — TermFlow bundles no AI. It ships no model, no API key, and sells no AI usage. You point your own agent (Claude Code, Codex CLI, Gemini CLI, or any other MCP client) at TermFlow, and it drives your terminal.

Two ways an agent drives TermFlow​

An agent can control TermFlow through either of two local interfaces. Most people only need the first.

InterfaceWhat it isWho it's for
Built-in MCP serverA streamable-HTTP MCP endpoint that any MCP client connects to. Exposes a small set of terminal tools (list, create, execute, read output, close).Anyone using an MCP-capable agent. This is the paved path.
REST + WebSocket APIAn HTTP + WebSocket API on localhost for building your own tooling and orchestrators.Power users building custom automation on top of TermFlow.

Both interfaces are local by default and speak to the same underlying terminals. Pick MCP if you're wiring up an existing agent; reach for REST/WS when you're writing your own controller.

The mental model​

Under the hood, TermFlow runs two cooperating local processes:

  • A local API server (Axum, in Rust) that owns the real terminals (the PTYs) and listens on a localhost port — 42031 by default.
  • A separate MCP sidecar process that bridges MCP clients to that API on its own port — 42032 by default.

When an agent runs inside a TermFlow terminal, TermFlow injects a $TERMFLOW_TERMINAL_ID into its environment. By sending that value back in the X-Termflow-Terminal-Id header, the agent can identify "its own" terminal — that's what the get_my_terminal tool and the "me" shorthand resolve to.

An agent's request flows left to right: the MCP client calls the sidecar, the sidecar calls the local API, and the API writes to the terminal's PTY. Terminal output streams back the same way, so the agent sees what the command actually produced.

Ports are configurable

42031 (API) and 42032 (MCP) are the defaults for an installed build. Both are user-overridable in Settings → Connections. By default the servers bind to 127.0.0.1, so they're reachable only from your own machine.

How it compares to other agent terminals​

TermFlow treats agents as complements, not competitors. It doesn't try to be the agent — it's the terminal the agent drives. That framing keeps the surface honest:

  • If you already have an agent you like, TermFlow gives it a real, visible terminal to work in instead of a hidden subprocess.
  • Because the agent connects over standard MCP or a plain HTTP API, you aren't locked into one vendor's assistant.
  • Multiple agents (and you) can share the same TermFlow window, each in its own tab or pane.

An honest note: In the default localhost mode, every API and MCP endpoint is unauthenticated — and that's intentional. The servers are bound to 127.0.0.1, so only software on your own machine can reach them. Authentication (a bearer token) is enforced only if you turn on Expose on local network in Settings → Connections. See Local API and auth for the full model.

An honest note: TermFlow does not yet host agents inside itself. "Bring your own agent" is the current model — the agent runs as its own process and connects in. Hosting agents directly inside TermFlow (via ACP) is on the roadmap, not something that exists today. Nothing on this site describes ACP as a shipping feature.

Next steps​