Skip to main content

The AI-Assisted Developer

A setup guide for the solo developer who pairs with a single coding agent — such as Claude Code — running right inside TermFlow.

This persona is the shortest path to value in TermFlow: one human, one agent, one project. You keep driving the keyboard; the agent drives the terminal alongside you.

Profile​

You are a developer who already works with an AI coding agent and wants it to do things in a real terminal — run builds, tail logs, execute tests — instead of just suggesting commands you copy and paste. You are not orchestrating a swarm of agents (that is the Multi-Agent Power User); you want one capable assistant with its hands on a shell, and a clean terminal for yourself right next to it.

  • Tools you bring: your own agent (e.g. Claude Code) and your own model API key. TermFlow ships no AI and no keys — it is the terminal the agent operates.
  • How you work: one project at a time, usually a single window with a couple of tabs and a split pane.
  • What you want from TermFlow: let the agent open and drive terminals over MCP, while giving you first-class terminal ergonomics (panes, search, clickable links) to stay in the loop.

Goals​

  • Connect one agent to TermFlow in a couple of minutes and confirm it can drive a terminal.
  • Keep your own hands-on shell visible beside the agent's, so you can verify what it does.
  • Jump straight from an agent-surfaced error (a file path, a URL) to the right place in your editor or browser.
  • Never worry that the local API is a security hole while you work on localhost.

1. Install and pick sensible OS versions​

Grab the installer for your platform from termflow.app/download and run it (see Installation for details). Recommended minimums: Windows 10/11, macOS 12+, or Linux (glibc 2.31+).

TermFlow is 0.1.0 — Early access · pre-release (Apache-2.0). First launch generates a local auth token and writes defaults into your OS application-config folder; there is nothing else to configure to get started.

2. Connect your agent (Claude Code)​

The fastest route is the in-app Connect an AI agent modal: Settings → Connections → "Connect an AI agent". It generates paste-ready config for Claude Code, Codex CLI, and Gemini CLI. For Claude Code, that config goes in your project's .mcp.json:

{
  "mcpServers": {
    "auto-terminal": {
      "type": "http",
      "url": "http://127.0.0.1:42032/mcp",
      "headers": {
        "Authorization": "Bearer <token>",
        "X-Termflow-Terminal-Id": "${TERMFLOW_TERMINAL_ID}"
      }
    }
  }
}
  • The server key auto-terminal is an identifier — keep it exactly as shown.
  • The MCP endpoint is http://127.0.0.1:42032/mcp (prod default MCP port 42032).
  • Claude Code expands ${TERMFLOW_TERMINAL_ID} in header values, which lets the agent recognize its own terminal (more on this below).
Localhost mode: the token is optional

In the default localhost-only mode, every TermFlow endpoint is unauthenticated — which is safe precisely because the server is bound to 127.0.0.1 and nothing off your machine can reach it. The Authorization header only matters once you turn on Expose on local network. If you ever do expose it, the real credential is the config auth token shown in Settings → Connections (reveal/copy/rotate it there) — paste that value in place of <token>. See Local API and auth.

Full walkthrough: Connect Claude Code and the step-by-step tutorial.

3. Lay out one window for pairing​

A two-pane split is the sweet spot: the agent runs claude in one pane, you keep a shell in the other.

┌─ TermFlow ─────────────────────────────────────────────────┐
│  [ project ▾ ]  [ + ]                                       │
├────────────────────────────────┬───────────────────────────┤
│  Left pane: Claude Code         │  Right pane: you           │
│  AgentChip: claude              │                            │
│  $ claude                       │  $ git status              │
│  > implement the parser...      │  $ npm test                │
│  (agent drives this pane        │  (you verify, poke,        │
│   and can spawn its own)        │   inspect)                 │
└────────────────────────────────┴───────────────────────────┘

Create the split with Ctrl+Shift+D (horizontal). New panes inherit the live working directory, so the right pane opens where you already are.

Essential Features​

FeatureWhy it matters hereHow
Connect an agentThe whole point — let the agent drive real terminalsSettings → Connections → "Connect an AI agent"
Split panesAgent in one pane, you in the other, both visibleCtrl+Shift+D; drag divider to resize (10–90%)
TabsKeep the app session, a scratch shell, and logs apart+ to create; Ctrl/Cmd+1..9 to select; Ctrl/Cmd+W to close
SearchFind that one error line in a wall of agent outputCtrl/Cmd+F overlay: incremental, N-of-M counter, case / whole-word / regex toggles
Links & clipboardJump from an agent-surfaced path or URL to the sourceModifier+click a URL or a file:line:col path
Agent color schemesSee at a glance which pane your agent is inAuto-detected from the running agent; an AgentChip pill names it
ZoomEnlarge just the agent's pane while you read alongCtrl/Cmd + =/-/0, or Ctrl/Cmd+wheel — per pane, never global

A few details worth knowing:

  • Clickable file paths. Modifier+click a path like src/parser.ts:42:9 and TermFlow opens it at that line/column in your configured editor (set Default editor for file links in Terminal Behavior); relative paths resolve against the pane's working directory. URLs open in your browser.
  • Tab activity indicators. When the agent is working in a background tab, that tab shows running/activity cues — a 🔔 bell, an external-activity dot, or an ⊘ exited marker — so you know when to look.
  • Smart close confirm. Closing a tab that still has a live agent process pops a confirmation listing the real foreground processes, so you don't kill a running agent by reflex. Cleanly exited shells close silently.

Example Workflows​

How the agent drives your terminal​

When you launch claude inside a TermFlow pane, TermFlow injects a $TERMFLOW_TERMINAL_ID into that pane's environment. Your .mcp.json forwards it as the X-Termflow-Terminal-Id header, so the agent can act on its own pane — using get_my_terminal, or simply passing "me" wherever a terminal id is expected. It can also spawn a fresh terminal to run a build without scrolling its own conversation off-screen.

See How agents drive the terminal and the MCP tools reference for the full tool set.

Workflow 1 — "Run it in its own pane"​

  1. In your claude pane, ask: "Run the test suite and fix the first failure."
  2. The agent calls create_terminal to open a split pane, then execute_command to run npm test there.
  3. It reads results back with get_terminal_output, edits the code, and reruns — all in that dedicated pane.
  4. You watch the test pane and keep your own shell free for git diff.

Workflow 2 — "Drive my current terminal"​

  1. You are mid-session in a REPL or an SSH box inside a TermFlow pane.
  2. Ask the agent to act on this terminal; it uses "me" (backed by the identity header) to target the exact pane you are in.
  3. It sends input and reads output without you switching context. Close its own pane with close_terminal on "me" when done.

Workflow 3 — "From error to source in one click"​

  1. The agent runs a build; it fails with src/api/client.ts:88:14 — type error.
  2. Press Ctrl/Cmd+F and search the scrollback for the failing symbol if you need surrounding context.
  3. Modifier+click the src/api/client.ts:88:14 path — TermFlow opens your editor at line 88, column 14. Fix, rerun, repeat.

Pro Tips​

Decide whether agent tabs steal focus

By default, "Focus new tabs opened by API/MCP" is off in Terminal Behavior — so when the agent spins up a terminal, it won't yank you away from what you're typing. Turn it on if you'd rather have TermFlow jump to whatever the agent just opened.

  • Let color-coding do the tracking. TermFlow polls running processes and themes each pane by the agent it detects, and the AgentChip pill names it. In a two-pane pairing session this is the quickest way to know which pane is "the agent's."
  • Zoom the pane you're reading. Ctrl/Cmd + = enlarges only the agent's pane — handy when you're following its output on a shared screen — without touching your global font size.
  • Keep the agent's shell honest with search. Ctrl/Cmd+F with the regex toggle (.*) is faster than re-prompting the agent to "find where it printed the URL."
  • If you go remote, rotate deliberately. Only enable Expose on local network when you actually need another device to reach TermFlow; that's the moment the auth token starts being enforced. Rotate it any time from Settings → Connections (existing UI connections survive). See Connections & network.

An honest note: Today your agent runs as its own process — in a TermFlow pane or elsewhere — and connects over MCP; TermFlow provides the terminals and the tools, not the model. Fully hosting an agent inside TermFlow (ACP) is on the roadmap, not something you can do in 0.1.0. And because TermFlow bundles no AI, everything here assumes you've brought your own agent and API key.

Next steps​