System & Processes

Read-only endpoints that report the host machine, the live foreground process (and any coding agent) running inside each terminal, per-process CPU/memory metrics, and tmux availability. These are the endpoints an orchestrator or dashboard polls to answer "what is actually running right now?"

All routes live under the local REST API at http://127.0.0.1:42031/api and are safe to poll.

Endpoints at a glance

Method	Path	Purpose
GET	/api/system/info	Host platform, architecture, app version, hostname, clock
GET	/api/processes	Per-terminal foreground process + coding-agent detection
GET	/api/processes/:id/metrics	CPU and memory for one terminal's process
GET	/api/system/tmux-status	Whether the tmux backend is available

Authentication

In the default localhost-only mode every endpoint here is unauthenticated — that is safe because the server is bound to 127.0.0.1 and reachable only from your own machine. A bearer token is required only when you turn on Expose on local network in Settings → Connections. See Overview & auth for the full model.

---

GET /api/system/info

Returns a small, static snapshot of the host and the running app. Useful as a lightweight probe to confirm you are talking to a TermFlow instance and to learn the OS/architecture before you branch behavior.

Response fields

Field	Type	Description
platform	string	Host OS as reported by the Rust runtime — windows, macos, or linux.
arch	string	CPU architecture — e.g. x86_64 or aarch64.
version	string	TermFlow version (0.1.0).
hostname	string	Machine hostname (COMPUTERNAME / HOSTNAME, or unknown if neither is set).
uptime	number	A seconds counter (see the note below).

Example

curl http://127.0.0.1:42031/api/system/info

{
  "platform": "windows",
  "arch": "x86_64",
  "version": "0.1.0",
  "hostname": "DEV-BOX",
  "uptime": 1751600000
}

An honest note: The uptime field currently reports the host clock as seconds since the Unix epoch, not the machine's actual uptime. Treat it as a monotonically increasing timestamp, not as "how long the box has been up." Prefer it only for coarse liveness/ordering checks until this is refined.

---

GET /api/processes

Lists every open terminal together with the real foreground process running inside it and, when recognizable, the coding agent driving that terminal. TermFlow builds this by cross-referencing its own terminal registry against a fresh OS-wide process snapshot (via the sysinfo crate) and walking the child tree of each terminal's shell.

This is the same signal the app itself polls to drive per-agent color schemes and the AgentChip pill — so an external orchestrator can use it to answer "which pane is running Claude Code vs. Codex?"

Response shape — a processes array plus a count. Each entry:

Field	Type	Description
id	string	Terminal id.
pid	number	PID of the terminal's shell process.
shell	string	Shell program for the terminal.
name	string	Terminal / tab name.
currentApp	object	The actual foreground process: { "pid": number, "name": string }. Equals the shell when nothing else is running.
agent	string | null	Friendly coding-agent label derived from the foreground process (e.g. claude, gemini, codex, cursor-agent, aider). null when no agent is recognized.
agentExe	string | null	Executable path of the detected agent process, used for icon extraction. null when no agent is detected, or when the OS won't report the path.
lastInputSource	string | null	Where the terminal's last input came from (e.g. user vs. API).
lastInputAt	number | null	Timestamp of the last input.
createdAt	number	When the terminal was created.
isAlive	boolean	Always true for entries returned here (only live terminals are listed).

Example

curl http://127.0.0.1:42031/api/processes

{
  "processes": [
    {
      "id": "term_ab12cd",
      "pid": 12044,
      "shell": "pwsh.exe",
      "name": "backend",
      "currentApp": { "pid": 23110, "name": "node" },
      "agent": "claude",
      "agentExe": "C:\\Users\\dev\\AppData\\Roaming\\npm\\node.exe",
      "lastInputSource": "api",
      "lastInputAt": 1751599800,
      "createdAt": 1751599700,
      "isAlive": true
    }
  ],
  "count": 1
}

How the agent label is derived

Interpreter-hosted agents (a Node or Python process) are labeled from their command line — for example @anthropic-ai/claude-code → claude, @google/gemini-cli → gemini, aider → aider. A native binary is labeled by its own executable name (so codex shows as codex). If the foreground process isn't a known agent, agent is null.

---

GET /api/processes/:id/metrics

Returns point-in-time CPU and memory usage for the shell process backing a single terminal. Take two samples a second or two apart if you want a rate.

Path parameter

Name	Description
:id	Terminal id (from /api/terminals or /api/processes).

Response fields

Field	Type	Description
id	string	The terminal id you requested.
cpu	number	CPU usage percent, as reported by sysinfo.
memory	number	Resident memory of the process, in bytes.
timestamp	string	RFC 3339 timestamp of the sample.

Example

curl http://127.0.0.1:42031/api/processes/term_ab12cd/metrics

{
  "id": "term_ab12cd",
  "cpu": 3.7,
  "memory": 84508672,
  "timestamp": "2026-07-04T09:15:22.104Z"
}

If the terminal id is unknown, the endpoint returns HTTP 404 with a JSON error body:

{ "error": "Process not found" }

This one really is 404

Unlike some terminal write endpoints (which return HTTP 200 with an {"error":...} body when a terminal is missing — see Overview & auth), /api/processes/:id/metrics returns a proper 404 for an unknown id. You can rely on the status code here.

---

GET /api/system/tmux-status

Reports whether TermFlow can use the tmux backend for content reflow on resize, and how many tmux-backed sessions are currently active. Poll this before offering tmux-dependent behavior; on Windows it typically reflects a WSL-hosted tmux.

Response fields (note the snake_case keys):

Field	Type	Description
available	boolean	Whether a usable tmux binary was found.
tmux_path	string	Resolved path to the tmux binary (empty when not available).
wsl_distro	string | null	WSL distribution hosting tmux, when tmux is reached via WSL; otherwise null.
active_sessions	number	Count of currently active tmux-backed sessions.

Example

curl http://127.0.0.1:42031/api/system/tmux-status

{
  "available": true,
  "tmux_path": "/usr/bin/tmux",
  "wsl_distro": "Ubuntu",
  "active_sessions": 2
}

See tmux backend for what tmux-backed terminals change and when to enable them.

---

A note on system metrics

There is no supported host-wide CPU/memory endpoint. For real numbers, use GET /api/processes/:id/metrics per terminal (above) and aggregate across the terminals returned by GET /api/processes.

Next steps

• API overview & auth — base URL, the localhost-vs-LAN auth model, and error conventions.
• Terminals — create, inspect, and manage the terminals these endpoints report on.