An operating environment for AI coding agents.
TermAl gives you one place to run, supervise, review, and steer long-running software work performed by AI agents — structured around real agent workflows instead of raw terminal output.
- Multi-session workspace — run multiple agent sessions in parallel across a split-pane layout; session tabs stay mounted while they are live so scroll position survives tab switching and pane moves
- Orchestrator — visual graph editor for reusable multi-agent workflows; each node can choose an assistant, use the assistant default model, or pin a specific model from the same combobox used by sessions
- Control panel — dockable sidebar with sections for Workspaces, Projects, Sessions, Orchestrators, Files, and Git status, plus actions for Work, Test Runs, the Response Board, and preferences
- Multi-browser workspaces — server-backed layout persistence lets you run independent workspace views across multiple monitors (e.g.
?workspace=planneron one screen,?workspace=reviewon another) - Structured message cards — text, commands, diffs, thinking blocks, markdown, file-change summaries, parallel-agent updates, subagent results, approvals, user input, and MCP elicitations rendered as typed cards
- Streaming responses — token-by-token output with delta events for low-latency display
- Diff review — unified diff cards with Monaco diff preview, click-to-open in a side pane
- Workspace terminal — project- or session-scoped terminal tabs stream stdout/stderr live, preserve terminal history per tab, and intentionally have no production timeout for long-running dev tasks
- Smart pane placement — session, source, diff, terminal, files, Git, mailbox, Work, Test Runs, instruction-debugger, canvas, and control-surface tabs open across the split-pane workspace
- Explicit approvals — agents request permission for risky actions; you approve, reject, or set a session-wide policy
- Prompt queueing — send follow-up prompts while an agent is working; they render as visible queued cards and run automatically in order
- Response board — an Obsidian-style spatial canvas: drag any agent response (or pin it) onto a pannable, zoomable board of immutable snapshot cards with provenance links back to the source session
- Agent delegations — child sessions for review and exploration, with read-only or isolated-worktree policies and durable results; acceptance evaluation creates its own host-controlled evaluator children
- Durable agent mailboxes — root sessions coordinate through durable, cursor-acknowledged mailboxes; humans read the same threads in a dedicated live-refreshing mailbox tab that never advances agent cursors
- Coordination board — root sessions share small, versioned project facts through a durable board; board writes do not wake sessions
- Engram work tracking — project-scoped tracker integration, with a read-only Work tab for tasks, dependencies, hierarchy, labels, and retained project memories
- Test Runs — inspect registered launcher runs and host-observed tests, their stages, logs, owner sessions, notification targets, and verification settlement
- Checkpoint navigation — clickable checkpoint dots beside the native scrollbar; nearby checkpoints share a chooser, and jumps load bounded history when needed
- Bounded transcript paging — large sessions (tens of thousands of messages) open instantly on a bounded tail; history pages in on demand with jump-to-start, marker jumps, and full-text search over loaded messages
- Session model controls — Claude, Codex, Cursor, Gemini, OpenCode, and Kimi expose model lists and session controls according to each adapter's capabilities; Codex also exposes catalog-gated Fast mode
- SSH remotes — connect to remote machines over SSH tunnels; run agents on a build server while supervising from your laptop
- Session persistence — sessions and message history survive restart (
~/.termal/termal.sqlite) - Filesystem and git panels — browse files, view git status, edit source, review diffs, and react to local file watcher updates directly from the workspace
- 21 themes + 4 chrome styles — hand-crafted light and dark palettes selected as a light + dark pair with a Light / Dark / Auto mode (Auto follows the OS live), a ⌘⇧L toggle, independent chrome styles (Terminal, Editorial, Studio, Blueprint), font-size controls, and a density control switchable at runtime
TermAl integrates with Claude Code, OpenAI Codex, Gemini (through the
Antigravity CLI, agy), Cursor, OpenCode, and Kimi Code CLI. Agent protocol
differences are normalized into the same session, message, approval, and
streaming model in the UI.
See the agent comparison for protocol background and capability differences, and the current integration contracts for TermAl's supported adapter boundaries. Gemini, OpenCode and Kimi have dedicated Gemini (Antigravity CLI), OpenCode and Kimi setup guides.
TermAl uses Engram for work tracking. A repository declares its project in
.engram-project; the operator configures and enables the local integration,
which gives agents Engram tools and work context. The
Engram host adapter is the full host
contract.
Execution Observability is a project-level ON/OFF setting, on by default. It observes; it never decides whether a turn may run. With the integration enabled:
- Host observations. When a traced turn on a claimed item ends, TermAl reports it to Engram once, after it ran: how it ended, whether it changed source, and the checks it ran with their observed results. Turning the setting OFF stops only these automatic reports.
- Named source roots. An agent names the worktree its claim is measured in. Naming takes effect at the agent's next turn.
- Registered verification. A test-launcher run with committed input in that named root is sent to Engram as registered verification. It is the only source of test credit; a check that only appears in a turn report earns none.
- Acceptance evaluation. An item's acceptance criteria can be judged by an independent evaluator session. For now, completing an item does not wait for it.
The Work tab is an Engram-only, read-only view with its own project selector. It offers Dependencies, Hierarchy, Labels, Table, and Memories views, with explicit refresh. Opening it does not enable the integration, create a claim, or change tracker data.
As of 2026-10-29 (master 3fc13725), updated 2026-11-14 for Execution
Observability. The full snapshot, with limitations
and next steps, is in Project status.
Works now
- Federation on real machines. A Windows central host is linked to a
second Windows machine and a Mac.
- Saved endpoints can use DNS hostnames, so an address change needs no new pairing.
- Cross-host mail wakes idle satellite sessions.
- See the central control plane and satellite onboarding.
- Remote full gates. The full gate runs on a satellite and reports back to the coordinator. It passed on master on both the Windows satellite and the Mac. See Remote full gates.
- Execution Observability on every harness, confirmed on a running host. Turn gating has been removed. Codex, Claude, Cursor, Gemini (Antigravity CLI), OpenCode and Kimi turns are delivered without waiting for Engram, and each turn's end reaches Engram as a host observation of its outcome, source change and checks. On the running build, a root session of each of the six harnesses claimed an item, named a source root and earned test credit from a registered test-launcher run there. See Execution Observability.
Active limitations
- Test credit comes only from a registered run on the host that holds the claim. A run on another host, such as a remote full gate, is evidence for review and landing but earns no test credit on an item.
- A turn's own checks are reported without credit. Cursor, Gemini and OpenCode report a passing check as indeterminate unless their tool update carries the command's exit code.
- When a session's working directory is outside its named root, the root's first source-change report can come from the very turn that runs the test, after the test. In the observed case, that first registered run, made in the turn after naming, was recorded but did not satisfy that turn's source-change obligation; a rerun in a later turn did.
- In its default approval mode, Gemini (Antigravity CLI) asks for approval on every tool call, including Engram and TermAl tools.
- A program cannot yet send a prompt directly to a chosen session on another machine. A mailbox message is the supported route.
- The running hosts do not yet have the SSH link diagnostics now on master. Until they run a build with them, an early SSH failure still shows as a startup timeout, without its cause.
- Federation recovery after a restart still needs its live evaluation.
Next
- Run the SSH link diagnostics on the live hosts and evaluate hostname recovery there.
- Add direct remote prompts.
Browser (React + TypeScript) Rust Backend (axum + tokio)
┌──────────────────────────┐ ┌────────────────────────────────────┐
│ Workspace │ SSE │ AppState │
│ ├── Split panes + tabs │◄═════╡ ├── Sessions + message history │
│ ├── Chat + approvals │ REST │ ├── Agent processes + approvals │
│ ├── Source + diffs │─────>│ ├── Delegations + mailboxes │
│ ├── Terminal, Files, Git │ │ ├── Coordination board │
│ ├── Control panel │ │ ├── Remote registry │
│ │ └── Workspaces │ │ ├── Orchestrators + layouts │
│ ├── Orchestrator canvas │ │ ├── Test-run registry + artifacts │
│ ├── Response Board │ │ ├── Engram host adapter │──> Engram CLI
│ ├── Mailbox reader │ │ └── Persistence (~/.termal/) │
│ ├── Work (read-only) │ │ │
│ └── Test Runs │ │ Agent runtimes │
└──────────────────────────┘ │ ├── Claude (NDJSON stdio) │
│ ├── Codex (JSON-RPC stdio) │
│ ├── Gemini (ACP stdio) │
│ ├── Cursor (ACP stdio) │
│ ├── OpenCode (ACP stdio) │
│ └── Kimi (ACP stdio) │
└────────────────────────────────────┘
- Backend: Rust + axum + tokio on
127.0.0.1:8787by default (TERMAL_PORToverrides the port). Spawns agents as child processes and communicates via stdin/stdout; also serves an existingui/distbundle from the server's working directory. - Frontend: React 18 + TypeScript + Vite on
:4173(dev). State is split across focused app hooks, local stores, and typed API/live-update helpers; no Redux-style external state library. - Real-time: Server-Sent Events with a monotonic revision counter. Delta events for streaming; full snapshots for sync.
- Persistence: Sessions, projects, preferences, remotes, workspace layouts, and orchestrator instances in
~/.termal/termal.sqlite; orchestrator templates in~/.termal/orchestrators.json.
Pane tabs include sessions, source and diff viewers, terminals, Files, Git status, mailboxes, the Response Board, Work, Test Runs, the instruction debugger, the session canvas, the orchestrator canvas and library, and standalone control, session-list, and project-list surfaces.
TermAl can manage agent sessions on remote machines over SSH. The browser always connects to the local backend; remote operations are transparently proxied through persistent SSH tunnels.
TermAl currently launches SSH non-interactively, so the simplest setup is
key-based auth with your normal system ssh / ssh-agent flow.
If you do not already have an SSH key on your laptop:
ssh-keygen -t ed25519Install that public key on the remote machine:
ssh-copy-id user@hostOn Windows PowerShell, the equivalent is:
type $env:USERPROFILE\.ssh\id_rsa.pub | ssh {IP-ADDRESS-OR-FQDN} "cat >> .ssh/authorized_keys"If you generated an Ed25519 key above, use id_ed25519.pub instead of id_rsa.pub.
Then verify normal SSH works before configuring the remote in TermAl:
ssh user@hostNotes:
ssh-copy-idcopies your public key into the remote account's~/.ssh/authorized_keys.- This is a public key, not a certificate.
- If
ssh-copy-idis unavailable, append the contents of~/.ssh/id_ed25519.pubto~/.ssh/authorized_keyson the remote manually.
Your laptop Remote build server
┌──────────────┐ ┌────────────────────────┐ ┌────────────────────────┐
│ │ SSE │ Local TermAl (:8787) │ SSH │ Remote TermAl (:8787) │
│ Browser │◄═══════╡ │ tunnel │ │
│ │ REST │ RemoteRegistry │───────>│ Agent Runtimes │
│ │───────>│ ├── build-box ───────────────> │ ├── Claude │
│ │ │ └── gpu-server ─ ... │ │ ├── Codex │
└──────────────┘ └────────────────────────┘ │ ├── Gemini │
│ ├── Cursor │
│ ├── OpenCode │
│ └── Kimi │
└────────────────────────┘
- Configure a remote in Settings > Remotes — give it a name, SSH host, user, and optional port.
- Create a project bound to that remote. Sessions created inside the project run on the remote.
- TermAl opens an SSH tunnel (
ssh -L {local_port}:127.0.0.1:8787) and optionally starts a TermAl server process on the remote host. - All session operations (messages, approvals, stop/kill) are proxied through the tunnel as regular REST calls.
- An SSE event bridge subscribes to the remote's
/api/eventsstream, merging remote state and delta events into the local state so the UI stays live.
Local port (47000–56999) Remote host
│ │
▼ ▼
┌─────────┐ ssh -L 47001:127.0.0.1:8787 user@build-box ┌─────────┐
│ :47001 │ ─────────────────────────────────────────────────> │ :8787 │
└─────────┘ encrypted tunnel └─────────┘
│ │
Local TermAl Remote TermAl
proxies REST + SSE runs agents
through this port on remote fs
Each remote gets a dedicated local port from the 47000–56999 range. The tunnel carries all traffic: REST API calls, SSE event streams, and health checks.
Two startup modes:
| Mode | SSH command | When used |
|---|---|---|
| Managed server | ssh ... user@host termal server |
Default — starts a TermAl server on the remote |
| Tunnel only | ssh -N ... |
Fallback — assumes TermAl is already running remotely |
TermAl tries Managed server first (15 s timeout). If it fails (e.g. termal not installed on the remote), it falls back to Tunnel only mode automatically.
Remotes are bound at the project level, not per-session or per-action:
Project "backend-api" ── remote: build-box
├── Session 1 (proxied to build-box)
├── Session 2 (proxied to build-box)
└── Files / Git / Reviews (proxied to build-box)
Project "frontend" ── remote: local
├── Session 3 (runs locally)
└── Files / Git / Reviews (local filesystem)
When you create a session inside a remote-bound project, TermAl:
- Ensures a project binding exists on the remote (creates one via
POST /api/projectsif needed). - Creates the session on the remote and stores a local proxy record with the mapping.
- Starts the SSE event bridge for that remote (if not already running).
All subsequent operations — sending messages, approving actions, browsing files, viewing git status — route through the same tunnel automatically.
Remote TermAl Local TermAl Browser
│ │ │
│── SSE state ──────────────────>│ │
│ (full snapshot) │── merge + rewrite IDs ─────>│
│ │ (local session IDs) │
│── SSE delta ──────────────────>│ │
│ (text chunk, command update) │── apply delta + publish ───>│
│ │ (forwarded as local delta) │
│ │ │
│<── REST (proxied) ────────────│<── REST ─────────────────────│
│ POST /api/sessions/3/messages│ POST /api/sessions/5/messages
│ (remote session ID) │ (local session ID) │
The local backend is the single source of truth for the browser. It rewrites session and project IDs so the frontend sees a unified namespace — remote sessions look identical to local ones.
SSH remotes currently store only the connection settings needed to reach the machine:
- remote name
- SSH host
- optional SSH user
- optional SSH port
- enabled/disabled state
When a remote is used, TermAl first tries to start termal server over SSH. If
that fails, it falls back to tunnel-only mode and expects a TermAl server to
already be running on the remote host.
| Setting | Description | Default |
|---|---|---|
name |
Display name for the remote | (required) |
host |
SSH hostname or IP | (required for SSH) |
user |
SSH username | (current user) |
port |
SSH port | 22 |
enabled |
Whether the remote is available for new projects | true |
Remotes are configured in Settings > Remotes and persisted in ~/.termal/termal.sqlite alongside session data. A built-in local remote is always present and cannot be removed.
- Rust (edition 2024)
- Node.js (see
.nvmrcfor version) - At least one supported agent: Claude Code, Codex, Gemini through the Antigravity CLI, Cursor, OpenCode, or Kimi Code CLI
cargo runThe server starts on http://localhost:8787 by default. Set TERMAL_PORT to
choose another port. An existing ui/dist build is served from the same address
when TermAl runs from the repository root.
cd ui
npm install
npm run devThe dev UI uses http://localhost:4173. Its API proxy targets port 8787 in
ui/vite.config.ts; update that target if you change the backend port.
cargo run -- repl codexRuns an interactive terminal loop — reads prompts from stdin and runs one agent turn at a time. REPL mode does not support Claude; create a Claude session in the server UI instead.
Configure Telegram from Settings -> Telegram:
- Create a bot with Telegram's
@BotFatherand copy the bot token. - Paste the token, test the connection, choose the subscribed projects, and save.
- Enable the relay and save. TermAl starts, stops, or restarts the in-process relay from the saved settings.
- Open the bot chat in Telegram and send
/start.
The backend runs the relay in-process from saved Settings -> Telegram
configuration. Today the relay is bound to one Telegram bot/chat and can control
multiple subscribed TermAl projects from that chat. The planned multi-bot model
is documented in docs/features/telegram-ui-integration.md: each bot becomes a
named profile with its own token, linked chat, project subscriptions, defaults,
and relay runtime.
Telegram commands:
/projects— list subscribed projects/project <id>— switch the active project for this Telegram chat/sessions— list sessions in the active project by name, active first and then by latest update/session <name>— select a session inside the active project by exact name or id/session clear— return free text to the latest promptable root session in the active project
Project digests and digest actions are temporarily disabled. Free text is forwarded into the selected session, or into the latest promptable root session in the active project when no session is selected. Assistant replies from the selected session are tailed back to Telegram after they settle only when Forward assistant replies is enabled; that setting can send full assistant output, including code, file paths, file contents, or secrets, to Telegram.
After installing the UI dependencies, run the shared launcher from the repository root for the maintained six-stage gate:
node scripts/test-launcher.mjs fullIt runs Cargo fmt in check-only mode, Cargo check, TypeScript checking, fingerprint/launcher helper tests, Rust tests, and Vitest in order. For an authorized focused check:
node scripts/test-launcher.mjs focused -- COMMAND ARG...For example, node scripts/test-launcher.mjs focused -- node --test scripts/test-launcher.test.mjs
runs the launcher helper suite. The launcher saves complete logs and terminal
results under Git metadata and prints a bounded summary. See Testing
for prerequisites, platform details, detached runs, and result recovery.
Open the Test Runs tab from the control-panel rail to inspect runs, choose a view, filter by project or state, and read stages and logs. Session markers open a scoped list with a notice and a Show all runs action. Execution results and host verification settlement are shown separately.
termal/
├── src/
│ ├── main.rs # Entry point and CLI
│ ├── api.rs # Axum HTTP routes
│ ├── api_*.rs # Route groups for files, git, review, SSE, etc.
│ ├── state*.rs # AppState, boot, accessors, and persistence-facing state
│ ├── session_*.rs # Session lifecycle, messages, config, runtime, and sync
│ ├── claude*.rs # Claude runtime integration
│ ├── codex*.rs # Codex runtime, RPC, events, and thread actions
│ ├── gemini.rs / acp*.rs # Shared ACP runtime and Gemini integration
│ ├── opencode.rs / kimi*.rs # OpenCode and Kimi ACP adapters
│ ├── engram_*.rs # Engram host adapter, observations, checks
│ ├── work_*.rs # Read-only Work and project-memory readers
│ ├── delegat*.rs # Child sessions, policies, results, MCP tools, waits
│ ├── mailboxes.rs # Durable cross-session messaging
│ ├── coordination_*.rs # Coordination board, CLI, and injected guidance
│ ├── test_run*.rs # Test-run discovery, registration, evidence, waits
│ ├── remote*.rs # SSH tunnels, remote routing, proxies, and sync
│ ├── orchestrator*.rs # Orchestrator templates, instances, and transitions
│ ├── terminal*.rs # Terminal run/stream support
│ ├── wire*.rs # HTTP/SSE wire types
│ └── tests/ # Backend test modules
├── ui/
│ ├── src/
│ │ ├── App.tsx # App composition
│ │ ├── app-*.ts # Focused app hooks and state orchestration
│ │ ├── api.ts / types.ts # API client and shared TypeScript types
│ │ ├── live-updates.ts # SSE delta event application
│ │ ├── session-store.ts # Session slice publication for heavy panels
│ │ ├── workspace*.ts # Pane/tab/split state and layout persistence
│ │ ├── message-*.tsx # Message cards, icons, and render helpers
│ │ ├── themes/ # 21 color themes + chrome style presets
│ │ └── panels/
│ │ ├── AgentSessionPanel.tsx # Chat session view
│ │ ├── ControlPanelSurface.tsx # Dockable sidebar with section tabs
│ │ ├── WorkspacesPanel.tsx # Saved workspaces
│ │ ├── WorkPanel.tsx # Read-only Engram work browser
│ │ ├── WorkMemories.tsx # Retained Engram project memories
│ │ ├── TestRunsPanel.tsx # Run list, stages, and logs
│ │ ├── OrchestratorTemplatesPanel.tsx # Visual canvas editor for workflows
│ │ ├── OrchestratorTemplateLibraryPanel.tsx # Template library and instance management
│ │ ├── SessionCanvasPanel.tsx # Session graph overview
│ │ ├── SourcePanel.tsx # Source file viewer
│ │ ├── DiffPanel.tsx # Diff viewer
│ │ ├── FileSystemPanel.tsx # Filesystem browser
│ │ ├── GitStatusPanel.tsx # Git status and diff tree
│ │ ├── ResponseBoardPanel.tsx # Spatial board of pinned agent responses
│ │ ├── MailboxPanel.tsx # Durable agent mailbox reader
│ │ ├── TerminalPanel.tsx # Scoped terminal command runner
│ │ └── InstructionDebuggerPanel.tsx # Agent instruction tracing
│ └── vite.config.ts # Dev proxy: /api → :8787
├── docs/
│ ├── architecture.md # Full architecture reference
│ ├── vision.md # Product vision
│ ├── roadmap.md # Phased roadmap
│ └── features/ # Feature briefs (orchestration, workspaces, agent integrations, etc.)
├── scripts/
│ ├── test-launcher.mjs # Shared full/focused launcher and run recovery
│ ├── test-rust.sh # Native Rust test wrapper
│ └── review-freeze-fingerprint.mjs # Reviewed-input fingerprints
├── Cargo.toml
└── Cargo.lock
The orchestrator lets you design reusable multi-agent workflows as directed graphs. Each node is an agent session; each edge is a transition that fires when a session completes.
Open the orchestrator canvas to build a workflow visually:
- Add session cards — each card defines an agent, optional model override, input mode, auto-approval behavior, and instruction prompt
- Draw transitions — drag between anchor points on cards to create edges; set a trigger (
OnCompletion), result mode, and optional prompt template - Save as a template — templates are persisted to
~/.termal/orchestrators.jsonand reusable across projects
Launch an orchestrator instance from a template. TermAl creates the sessions, starts the first one, and then:
- When a session reaches
prompt_ready, the orchestrator evaluates outgoing transitions. - The transition assembles a follow-up prompt (optionally including the source session's last response or a summary).
- The follow-up prompt is delivered to the target session, which starts automatically.
Instances can be paused, resumed, or stopped from the control panel or via REST API.
| Setting | Options | Description |
|---|---|---|
| Trigger | OnCompletion |
Fires when the source session finishes its turn |
| Result mode | None, LastResponse, Summary, SummaryAndLastResponse |
What context to include in the delivered prompt |
| Input mode | Queue, Consolidate |
How multiple inbound transitions are handled |
| Prompt template | {{result}}, {{sourceSessionId}}, {{sourceSessionName}}, {{transitionId}} |
Custom prompt wrapping the result |
docs/architecture.md— system design, API reference, agent protocol detailsdocs/vision.md— product framing and guiding principlesdocs/roadmap.md— phased roadmapdocs/themes.md— current theme, chrome style, font, and density systemdocs/test.md— current backend/frontend test strategydocs/features/— feature briefs including:- Orchestration — multi-agent workflow design
- Multi-browser workspaces — server-backed layout persistence
- Workspace terminal — scoped terminal command execution and streaming
- Diff review workflow — structured diff review
- Agent integrations — protocol background, capability comparisons, and a Kimi appendix
- Current agent contracts — supported boundaries for Claude, Codex, Gemini, Cursor, OpenCode, and Kimi
- OpenCode integration — OpenCode over ACP
- Kimi integration — Kimi Code CLI setup and ACP behavior
- Engram host adapter — project configuration, agent context, and host observations
- Execution Observability — what the Engram integration does for a session
- Work visualizer — read-only Engram task and memory views
- Test Runs — launcher history, stage details, logs, and verification settlement
- Response board — spatial board of immutable agent-response snapshots
- Agent mailboxes — durable cross-session agent coordination
- Coordination board — versioned project facts shared by root sessions
- Agent delegation sessions — child sessions, write policies, structured results
- Checkpoint navigation — native scrollbar reach and grouped checkpoint dots
- Virtualized transcripts — bounded paging for huge sessions
- Project-scoped remotes — remote binding at project level
- Project status — dated snapshot: what works, active limitations, what comes next
- Central control plane — central host, satellite hosts, cross-host mailboxes; running on a Windows central with Windows and Mac satellites
- Satellite onboarding — adding a satellite, verification, hostname recovery
- Federation link — the OpenSSH link between the central host and each satellite
- Remote full gates — running the full gate on a satellite
Copyright 2026 TermAl contributors.
TermAl's code and documentation are licensed under the Apache License 2.0, unless stated otherwise.
Third-party components keep their own licenses.