Multi-AI Terminal

English | 繁體中文

A local web workbench for composing and running multi-agent workflows across headless coding-agent runtimes — Claude Code, Codex, Grok, Antigravity (Gemini), and OpenRouter through Codex-as-runtime. Drag agents onto workflow stages, let a real LLM orchestrator gate each stage, and watch every agent's output stream into one categorized, replayable feed.

Successor to multi-ai-chat-desktop: instead of scraping web chats, every agent is driven through a real headless CLI, app-server, or SDK runtime whose stream is normalized into one durable evidence schema.

The latest published release is v0.2.10, adding OpenRouter through Codex-as-runtime, common Grok/Agy managers, and the canonical provider contract.

How it works

• Projects + Launchpad — each workspace points at a directory (git-aware). The icon-and-text rail switches between project selection and a launch composer without losing drafts; common mode/readiness/task settings stay visible while advanced stage editing lives under Customize.
• Workflows — ordered stages; each stage holds agent slots (drag from the advanced palette; multiple same-provider instances allowed, Σ ≤ 12 per stage). Per-slot: model, reasoning effort, permission tier, prompt template, count.
• Orchestrator — a real CLI agent (any provider) that receives a digest of each gated stage's candidates and answers with a strict-JSON gate decision: advance / retry (with per-node targeting + prompt addendum) / abort. Deterministic budget caps; parse failures degrade to safe advance.
• Stage isolation — optional git-worktree isolation per node; each attempt's work is captured as a binary patch you can inspect and apply from the UI.
• Run Workspace — a Narrative-first Conversation makes every node's answer, decision, verification, and failure easy to scan. Timeline preserves the virtualized raw categories, node/role/search filters, and full replay from the durable event log.
• Health & diagnostics — server, provider, workspace, run, verification, and evidence-continuity findings with safe Setup, provider recheck, inspect, redacted-log, and debug-bundle actions. CLI detection is never presented as proof of sign-in.
• Language + themes — follows the system language or switches between English and Traditional Chinese, with persistent Midnight, Daylight, and violet/gold/teal Aurora themes.

Verification (evidence plane)

Workspaces can define a verification command such as npm test and an optional timeout (600 seconds by default). Worktree-isolated candidates with a non-empty patch run that command after artifact capture; the normalized pass, fail, error, or skipped result and full log are persisted with the run. A gated stage can enable requireVerified, which retries failed checks when no candidate passed, subject to the existing retry budget.

The UI and generated Markdown report distinguish generated, reviewed, advanced, and verified work. A degraded or unverified advance is labeled, never hidden. Open Report in the run panel or request GET /api/runs/:id/report for a PR- and retrospective-ready record of outcomes, handoffs, decisions, provider CLI versions, usage, patches, and verification evidence. The builtin Pipeline: Implement → Test → Review preset provides the shortest evidence-gated production line.

Steering

While a run is active, enter a new instruction in the run panel. Interrupt (the default) terminates the active candidate process trees, preserves their partial logs and patches, runs the new instruction through the normal evidence path, then records a gate-style review that decides whether to redo the interrupted stage, continue, or abort. Queue waits for the next stage boundary and applies the instruction without killing current work. Steering is FIFO, capped at eight messages per run, and remains deterministic when the orchestrator is disabled. It never uses a PTY or writes to a running child's stdin.

Debug bundle

Choose Debug beside Report, or use the read-only Health drawer, to download one mat-debug-<runId>.zip. It contains the full run snapshot, events, diagnostic journal, Markdown report, raw adapter output, patches, verification logs, runtime/provider versions, and the tail of the server diagnostic log. Browser errors are also reported best-effort to the server journal; environment variable values are never intentionally recorded.

Quickstart

Requirements: Node.js ≥ 20 and Git ≥ 2.32 recommended (older Git falls back to plain git apply --check), plus the runtimes for the providers you use: Claude and Codex can use MAT-managed pinned runtimes; Grok uses grok; Antigravity uses agy. OpenRouter has no CLI of its own: it requires the Codex runtime and OPENROUTER_API_KEY in MAT's environment. In the editor, choose an OpenRouter model first and then a version; MAT persists and sends the selected version's exact OpenRouter request slug.

npm install
npm run build
npm start                      # serves web UI + API on http://127.0.0.1:7788
# options: --port N --host H --data-dir DIR --token SECRET

Open the UI, choose Projects to add a workspace (absolute path), return to Launch, pick a builtin workflow (Planning / Build / Review / Pipeline), write the task, and Start. Use Customize only when you need to change stages or agent bindings.

Use Language · Theme in the top bar to override the system language or choose one of the three themes. Both choices persist across restarts.

Dev mode: npm run dev (vite + API with hot reload). Tests: npm test. Typecheck: npm run typecheck. Version contract: npm run verify:version. Built-server evidence suite: npm run evidence after npm run build.

Desktop app

Install desktop builds from the repository's GitHub Releases page. The desktop app requires Node.js ≥ 20 on PATH; set MAT_NODE to the path of a specific compatible Node.js binary if needed.

• Windows: download the -setup.exe (NSIS) or .msi and run it. The WebView2 runtime is preinstalled on Windows 10/11, and the installer bootstraps it if missing. Install Node.js ≥ 20 with winget install OpenJS.NodeJS.LTS; Git for Windows is also required for worktree isolation features. Set MAT_NODE to the path of a specific node.exe if needed.
• Debian/Ubuntu: download the .deb, then run sudo apt install ./file.deb.
• Other Linux distributions: download the .AppImage, run chmod +x ./Multi-AI-Terminal*.AppImage, then launch it. RPM packages are also provided.
• macOS: open the downloaded .dmg and copy the app to Applications. Version 1 builds are unsigned and not notarized, so on first launch right-click Multi-AI Terminal and choose Open to pass Gatekeeper.

The desktop shell runs the exact same bundled server on an ephemeral 127.0.0.1 port and keeps data in ~/.multi-ai-terminal/, just like the web-served build. To build the desktop resources locally, run npm run build followed by npm run desktop:bundle; npm run desktop:build additionally requires the Rust and native Tauri build prerequisites.

When adding a workspace, desktop builds provide a native Browse… folder picker. Pure-browser use keeps the manual absolute-path field and does not load the desktop dialog integration.

Agent-driven launch (agent-ready source release)

This repository can be driven by coding agents such as Claude Code and Codex. agent-release.json is a machine-readable contract (validated against agent-release.schema.json) declaring the entrypoints, permissions, side effects, runtime states, and exit codes of the source-web lane, and matching skills ship in-repo under .claude/skills/launch-multi-ai-terminal/ and .agents/skills/launch-multi-ai-terminal/. The skills are explicit-only: an agent may use them solely when you ask, never implicitly.

npm run agent:doctor -- --json           # prerequisites (Node 20+, npm); never installs anything
npm run agent:launch -- --wait --json    # npm ci if needed, build, start on a free 127.0.0.1 port
npm run agent:status -- --json           # state + URL; ready only after "[MAT_AGENT] READY url=..."
npm run agent:stop -- --json             # stops only the identity-verified launcher process tree
npm run agent:audit -- --json            # declared permissions/side effects vs observed artifacts

The lane is source-web only: no Rust toolchain, no installers, no release-asset downloads. Lifecycle records stay in the gitignored .agent-runtime/ directory. Lifecycle scripts never read provider credentials, and the skills are forbidden from driving the launched server's provider install, update, or sign-in APIs on your behalf. Do not run this lane while the installed desktop app is open — both use the same data directory (MAT_DATA_DIR or ~/.multi-ai-terminal/), and two servers over one data directory race its stores.

Provider setup

The desktop quietly bootstraps missing supported Claude/Codex managed runtimes on first run, including the Codex runtime reused by OpenRouter. These artifacts are fixed, catalog-pinned, integrity-verified, and written only under <dataDir>/runtimes/; MAT does not install @latest globally or modify the host PATH. Unavailable providers still expose Setup as recovery and for provider-specific fixed recipes where no managed artifact exists. Those recipes accept no command input, and each provider's license and sign-in remain independent.

Automatic bootstrap and Setup both rerun runtime/provider discovery when installation finishes; Setup also shows elapsed time and keeps completion/restart guidance visible. Retry detection clears MAT's local PATH/version caches without reinstalling anything. Windows version probes allow cold CLI shims 15 seconds to start; transient failures are cached for only two seconds, while successful versions remain cached for ten minutes.

MAT augments child-process PATH with existing well-known CLI locations: %LOCALAPPDATA%\Antigravity and %APPDATA%\npm on Windows, or ~/.local/bin, /usr/local/bin, and /opt/homebrew/bin elsewhere. This lets the desktop server discover common user-level installs without inheriting environment-variable values into diagnostics.

Provider sign-in & parallel sessions

Some Codex authentication failures are caused by concurrent CLI sessions racing rotation of a single-use OAuth refresh token. MAT spaces launches of the same real provider at least 1.5 seconds apart to reduce the race, including orchestrator launches, but this cannot make upstream token rotation atomic. See openai/codex#9634 and openai/codex#15502.

The durable options are API-key authentication or serial provider usage. Codex supports API-key login, and Claude Code honors ANTHROPIC_API_KEY. If an OAuth refresh token has already been revoked, sign out and back in with that CLI first; for Codex, run codex logout && codex login.

When a real provider fails with a recognized sign-in error, its node card shows multi-line amber guidance with the verified command, its provider chip gains an auth badge, and Setup exposes a copyable Sign in block. The composer warns before another run uses that provider without blocking it; a later successful node clears the alert.

OpenRouter authentication is environment-only: set OPENROUTER_API_KEY before starting MAT and restart MAT after changing it. MAT reports only whether the variable is present; it never exposes or persists its value.

Providers and runtime paths

Provider	Runtime / transport	Stream	Notes
claude	Agent SDK driving the resolved claude runtime	full (text/thinking/tools/usage)	persistent session runtime; explicit legacy CLI mode remains
codex	persistent codex app-server JSON-RPC/JSONL controller	full (thinking/tools/usage)	one shared controller owns resumable threads
grok	grok --prompt-file F --output-format streaming-json, behind a FIFO manager	thought/text only (tools run silently)	grok ≥ 0.2.93: don't pass -p with --prompt-file
agy	agy -p "PROMPT" --model "Gemini 3.1 Pro (High)", behind a FIFO manager	plain text	model = display name; no JSON mode or resume
openrouter	no OpenRouter CLI; persistent Codex app-server with an isolated OpenRouter config	full where the selected model supports it	requires OPENROUTER_API_KEY; select model → version; the exact version slug is sent
mock	in-process	scripted	deterministic; MOCK_REPLY: echo mode for tests

Permission tiers per slot: safe (read-only), auto (accept edits), full (bypass sandbox) — mapped to each runtime's native policy (SPEC §4.6).

Trust model

Binds 127.0.0.1 by default. --host 0.0.0.0 exposes the API/UI to your network — set --token (REST bearer + WS query token). Anyone with access can run arbitrary CLI agents in your workspaces; treat the port accordingly (Tailscale-only exposure recommended).

Data

~/.multi-ai-terminal/ (override with --data-dir / MAT_DATA_DIR): workspaces.json, workflows/*.json, runs/<runId>/run.json + events.jsonl + raw/*.jsonl (environment-value-sanitized CLI output per attempt) + artifacts/*.patch + artifacts/*.verify.log. Retention: last 100 runs per workspace, worktrees/branches pruned on delete.

Docs

• SPEC.md — the engineering contract (v1.5, including BAT-runtime alignment)
• docs/project-audit-2026-07-20.md — current hardening record and ordered continuation backlog
• docs/spec-review-panel.md — 4-model spec review record
• docs/code-review-panel.md — 4-model code review record (25 findings fixed, 3 refuted)

Built by a 4-model panel process: spec + code review by Claude Fable 5, Codex GPT-5.6-sol, Gemini 3.1 Pro, and Grok 4.5; implementation by parallel Codex workers in isolated git worktrees.

Known limitations (v1)

• Grok's streaming JSON emits no tool events — grok nodes show thinking/text only; digests report tool-count "n/a".
• Antigravity (agy) has no headless JSON mode — plain-text stream, no session resume (orchestrator re-briefs each gate).
• After a machine reboot, crash recovery kills stale process groups by persisted PID; PID-recycling risk is accepted.
• Event ring keeps 20k events in browser memory; older history pages in from the server with an explicit trim notice.
• On Windows, process termination uses taskkill /T /F (forced tree kill); if node exits on its own first, detached grandchildren are reaped by the stale-PID sweep on next server start.