First-Run Walkthrough
A five-minute tour of TermFlow the first time you open it: a terminal appears, you add a tab, split a pane, then find where agents plug in.
By the end you'll have a working multi-pane terminal and you'll know exactly where the "Connect an AI agent" button lives — which is the doorway to everything that makes TermFlow different.
This page assumes TermFlow is already installed. If it isn't, see Installation first. TermFlow is version 0.1.0 — Early access · pre-release — so expect a few rough edges.
The five minutes at a glance
Each step below takes well under a minute.
Step 1 — Launch the app
Open TermFlow the way you'd open any application. On the first launch it does two things behind the scenes:
- Opens a terminal running your default shell profile. TermFlow detects the shells installed on your system (for example PowerShell or Command Prompt on Windows,
zshorbashon macOS and Linux) and starts the one marked as default. You'll see it badged as the default in Settings later. - Starts its local services: a REST + WebSocket API on port 42031 and an MCP server on port 42032, both bound to
127.0.0.1(your machine only). These are what let an AI agent drive TermFlow — more on that in Step 5.
A single window with one tab and one pane looks roughly like this:
┌───────────────────────────────────────────────────────────┐
│ TermFlow — □ ✕ │ ← title bar
├───────────────────────────────────────────────────────────┤
│ [ zsh ● ] [ + ] [ ▼ ] │ ← tab strip
├───────────────────────────────────────────────────────────┤
│ │
│ ~ % │ ← your default
│ │ shell, ready
│ │
└───────────────────────────────────────────────────────────┘
The + adds a tab; the ▼ opens the profile dropdown so you can pick which shell a new tab starts with.
Ctrl+TTermFlow intentionally leaves Ctrl+T unbound, because many shells and TUIs use it. Create tabs with the + button or the ▼ profile dropdown instead.
Step 2 — Open a new tab
Click the + button in the tab strip to open a second tab with your default profile, or click ▼ to choose a different shell profile for it.
A few things worth knowing about tabs from the start:
| Action | How |
|---|---|
| Switch tabs | Ctrl/Cmd+1…9, or Ctrl+Tab / Ctrl+Shift+Tab |
| Close a tab | Ctrl/Cmd+W, the ×, middle-click, or right-click → Close |
| Reorder tabs | Drag a tab left or right |
| Rename a tab | Double-click its title |
When you close a tab that still has a real running process, TermFlow shows a smart confirmation listing what would be killed. Tabs whose shell has already exited cleanly close without nagging you.
Step 3 — Split a pane
Now split the current tab so you can watch two things at once. Press Ctrl+Shift+D to split horizontally — the pane divides and a second shell opens beside the first:
┌───────────────────────────────────────────────────────────┐
│ [ zsh ] [ + ] [ ▼ ] │
├──────────────────────────────┬────────────────────────────┤
│ │ │
│ ~ % npm run dev │ ~ % git status │
│ │ │
│ (pane A) │ (pane B) │
│ │ │
└──────────────────────────────┴────────────────────────────┘
drag the divider to resize (10%–90%) ↔
Panes are a recursive split tree, so you can keep splitting either side. A new pane inherits the live working directory of the pane you split from, so you don't have to cd back to where you were.
| Action | Shortcut |
|---|---|
| Split (horizontal) | Ctrl+Shift+D |
| Maximize / restore the focused pane | Ctrl+Shift+Enter |
| Close the focused pane | Ctrl+Shift+W (with a confirm) |
You can also split from the pane-header buttons or the right-click context menu, and drag a tab or pane out of the window to tear it into its own window. Those are covered in Split Panes.
Step 4 — Open Settings
Press Ctrl/Cmd+, to open Settings. It's organized into four tabs:
| Tab | What lives there |
|---|---|
| Appearance | Font size, tab overflow behavior, color schemes |
| Terminal Behavior | Smart Ctrl+C, command-history suggestions, focus rules |
| Shell Profiles | Pick your default shell and each profile's start directory |
| Connections | Ports, LAN exposure, the auth token, and connecting an agent |
For this walkthrough, head straight to the Connections tab.
Step 5 — Find Connections and "Connect an AI agent"
The Connections tab is where TermFlow's local API meets the outside world. You'll see the ports, a network-exposure toggle, an auth token, and — the reason you're here — the Connect an AI agent button.
┌─ Settings ──────────────────────────────────────────────────┐
│ Appearance | Terminal Behavior | Shell Profiles | [Connections] │
├─────────────────────────────────────────────────────────────┤
│ │
│ API port [ 42031 ] Health ● healthy │
│ MCP port [ 42032 ] │
│ │
│ Expose on local network [ OFF ] │
│ │
│ Auth token •••••••••••••••••••• [Reveal] [Copy] [Rotate] │
│ │
│ [ Save & apply (restart) ] [ Stop ▾ ] [ Start ▾ ] │
│ │
│ ┌───────────────────────────────────────────────┐ │
│ │ Connect an AI agent │ ← this │
│ └───────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Clicking Connect an AI agent opens a modal that generates paste-ready configuration for Claude Code, Codex CLI, and Gemini CLI, all pointed at your MCP server (http://127.0.0.1:42032/mcp). That's the fast path to your first agent-driven session — but before you click it, it helps to understand the token you can see on this screen.
What that auth token is (and why you probably don't need it yet)
On its very first run, TermFlow generates a 64-character hex bearer token and writes it into its config file, in your operating system's application-config directory:
- Windows: under
%APPDATA% - macOS: under
~/Library/Application Support - Linux: under
~/.config
That token is the credential shown (masked) in Settings → Connections, where you can reveal, copy, or Rotate it.
Here's the important, honest part:
An honest note: In the default localhost-only mode, the API and MCP endpoints are unauthenticated — no token required. That is safe because the services are bound to
127.0.0.1and never leave your machine. The token is only enforced when you turn on "Expose on local network" in the Connections tab, which rebinds the services so other devices can reach them. In other words: local agents just work; the token exists to protect the moment you deliberately open TermFlow up to your LAN.
Flip on Expose on local network, then hand your agent or client the token from Settings → Connections as an Authorization: Bearer <token> header. Rotating the token takes effect immediately without a restart, and existing UI connections survive the rotation. The full model is explained in Local API & Auth.
That's the whole first run: you launched TermFlow, got a shell, added a tab, split a pane, and found the door that agents walk through.
Next steps
- Connect an agent — Overview — click that button for real and wire up Claude Code, Codex, or Gemini in a couple of minutes.
- Interface Tour — a fuller map of the window: tab strip, panes, indicators, and menus.