Introduction
TUICommander Documentation
Run multiple AI coding agents in parallel across isolated Git worktrees. Observe, control, and merge AI development from a single terminal workspace.
Popular articles
Browse by section
- User Guide — install, configure, and drive TUICommander day to day
- Architecture — how the app is put together, and how agent detection works
- Backend — Rust subsystems: PTY, git, MCP, output parsing
- Frontend — Solid components, stores, transport layer, terminal internals
- API Reference — HTTP, Tauri commands, SDK, and plugin authoring
- Developer Guide — build from source, profile, and release
Key Features
- Terminal Management — Tabbed terminals with split panes, drag-and-drop reordering, and per-branch isolation via Git worktrees
- AI Agent Support — Auto-detect Claude Code, Codex, Gemini CLI and more. Monitor progress, costs, and active subtasks in real time
- Git Worktrees — Each branch gets its own working directory. Create, merge, archive, and batch-manage worktrees from the UI
- GitHub Integration — PR badges, CI status rings, merge from the UI, post-merge cleanup, and notification bell for PR events
- Plugin System — Extend TUICommander with JavaScript plugins. Full API for terminals, git, notifications, and status bar widgets
- MCP Bridge — Expose app capabilities to AI agents via Model Context Protocol
- Project Progress — Append-only journal per project: agent
doneandblockedreports plus theintent:markers TUICommander captures, surfaced through the toolbar bell - Design Mode — Pick an element in a dedicated Chrome window and add its context to an agent terminal’s editable draft
- Remote Daemon —
tuic-remoteruns the backend headless on a server or build host: same HTTP/WebSocket API, no Tauri, no GUI
The complete, always-current capability inventory lives in the Feature Reference.
Community & support
Join TUICommander & Co on Discord for questions and ideas. Use #support, #ideas, or #plugins in the TUICommander category. The server is checked once a day. Report reproducible bugs in GitHub issues.
TUICommander — Complete Feature Reference
The parallel Catalog authoring view includes trigger bindings: select a pinned workflow, map installed source fields, preview normalized payloads and inspect overlap revisions before explicit enable acknowledgement. A stored binding that an installed-source prerequisite holds without intake shows its reason (“No intake: …”) next to it in the binding list. Authoring uses the shared desktop/HTTP action contract; native activities require the installed backend catalog/provider. Catalog failures remain explicit while independent saved drafts stay available.
Neutral catalog authoring
The Workflow Designer offers Catalog authoring alongside legacy definitions. Neutral drafts have no development kind. Configuration forms use backend schemas; labels are presentation metadata, and named outcomes and typed mappings retain the backend contract. Pinned metanodes open read only and customize into new drafts. Validation precedes publication. Sample preview and retained run inspection are separate actions; preview never requests activity execution or trigger activation. A compatible neutral backend is required. Missing catalog/transport support is reported explicitly; this authoring view does not establish native runtime parity.
Internal correction metanode contracts retain the selected publication, durable correction limit and source-bound assessment data. The neutral loop owns admission/replay; native committed-candidate review/check assessment and generation fences refuse stale evidence. MCP exposes pinned criteria and the region through the existing neutral action; Designer renders criteria, selected child publication, correction limits and generated contracts; retained scope iteration drives the displayed consumed correction count (#016-358f).
- Configured neutral workflow adapters — One installed native provider delegates saved script/HTTP operations, configured mediated model requests, installed Jira/GitLab project bindings and the enabled Telegram alias. Catalog discovery is local; agent execution rechecks Operator authority and external writes require exact approval. Pure preview needs no run binding. Public starts bind trusted backend callers before dispatch; see workflow transport. Internal correction metanode contracts retain the selected publication, durable correction limit and source-bound assessment data. The neutral loop owns admission/replay; native committed-candidate review/check assessment and generation fences refuse stale evidence. MCP exposes pinned criteria and the region through the existing neutral action; Designer rendering remains pending (#016-358f).
Internal structured workflow scripts now have a bounded, versioned input/result adapter with exact effect identity and conservative mutation reconciliation. Authenticated public start binding is installed; generic Designer script rendering is verified. See the script interface.
-
Scheduled neutral text workflows — Cron bindings reuse the automation timer and durable trigger receipts. Literal text can feed a model, condition and local exact approval inbox in a plain directory. Native repository actions retain their Git scope.
-
Neutral source triggers — Pinned workflow bindings validate typed mappings, preview overlapping filters, deduplicate source generations and retain uncertain effects before PR replacement. See trigger admission.
-
Internal typed workflow HTTP — Installed connector contracts bind credentials, destinations and method semantics; bounded cursor output feeds collections. Configured host composition is installed; authenticated public start binds trusted backend callers. See the contract.
-
Forced steering: Chat Send now, Compose Steer and urgent peer mail interrupt the active Claude Code, Codex or ego turn before submitting the full message, including during Stop hooks.
Prompt composers share Enter/Ctrl+Enter to send, Shift+Enter for newline, and Cmd+S/Ctrl+S to park or swap drafts without sending. See the keyboard model.
Managed worker recovery: after the configurable stall threshold, a silent local managed PTY receives one nudge and its parent one stalled notice that names the stop command. Recovery never stops the PTY; the parent decides. A BLOCKED hold is not silence; running background work is reported in the notice. Independently, a managed child that stops (idle, refused turn, dialog or exit) without a RESULT or BLOCKED for its current task gives its parent one typed child_report mail of subscription kind report within about 15 s. A parent mail to an idle managed child that starts no turn within 20 s gives the parent one typed delivery_failed mail with the reason.
- Typed agent reports — Claude, Codex and ego can send ready/waiting/blocked/failed/dropped/progress metadata and structured questions. Session inventories derive stages from live facts and expose host report time. See Agent Teams.
Internal neutral workflows have typed native workspace/artifact pins, named verification, story transitions, exact-approved commit and canonical local bare push adapters. Native exact-change review uses the existing reviewer and pins the staged artifact; commit requires its passing persisted receipt. Native GitHub publication supports separately approved account/repository/artifact-bound branch and PR actions, with provider read-back receipts. Trusted public caller/run binding remains pending; unbound dispatch refuses. See native workflow operations.
-
Compose queue controls — The Compose N queued list has a labelled Cancel action for each item and keeps Clear all. Supported items also show Steer, which uses the same backend delivery as Session Chat Send now. Claude Code, Codex and ego interrupt the running turn, confirm idle, then submit the selected full text. The tooltip states that the current request stops. Steer is hidden while a native question waits.
-
Pending Chat prompt controls — Busy Session Chat sends wait in TUIC’s existing idle-gate queue on desktop and mobile. Each host-owned Pending prompt has Cancel and, for Claude, Codex and ego, a compact return-key Send now action. Send now uses one forced-steer flow for all three harnesses: reserve the next ready composer, send Escape to a working turn, confirm idle, then submit the selected full text before ordinary queued inputs or mail wakes. The tooltip reads Send now: stop the current request. An idle recipient skips Escape. A prompt already taken by the idle gate is not sent again, and a refused Send now keeps the prompt queued. Native CLI receipts from earlier direct sends remain read-only. (#2589-4bc4).
-
Terminal Ctrl+Enter — Desktop and browser/remote CLI grids use CSI u for negotiated Kitty reporting and identified ego sessions, enabling ego busy-turn steering. Legacy shells and other nonnegotiating agents receive CR. Plain Enter and Compose shortcuts stay unchanged (#2599-0a6b).
-
Native integration trial (WF07) — Disabled-by-default typed workflow integration checks and publishes one pinned no-ff merge, retains proof debt across restart, and keeps cleanup independent. Only isolated trial clones may enable it before repository parity approval; WF08 proof batching is not included (#2514-3d1e).
-
Mobile terminal and AI Chat composers add one space after a pasted HTTP(S) URL when neither the paste nor the following draft character supplies whitespace (#2494-921f).
-
Mobile list identities stay inside their rows; long session and file names use ellipsis, badges and actions remain visible, and Progress text wraps (#2493-061e).
AI Chat shares the active conversation across desktop and mobile for the configured host workspace. The last saved selection wins; reconnect catches up. Open-tab layout, drafts and the session CLI | Chat switch remain per device.
- Mobile Chat queue — Terminal CLI and Chat show pending prompt text and a Queued count above the input, including CLI/desktop additions. Cancel one prompt or clear the queue; delivered entries disappear (#2463-ad1c).
- Chat message menus — User and assistant messages in AI Chat and Session Chat have a quiet ⋯ menu with Copy, raw/formatted Markdown, and Quote reply. AI Chat adds conversational thumbs up/down, heart, celebrate, and comments for completed answers with native IDs. Add/remove actions name the exact source and use the original conversation queue; accepted marks persist across desktop and phone. Offline errors do not change marks. Terminal Chat retains drafted response feedback. Menus stay inside the viewport and support keyboard navigation (#2539-6c53, #2872-6aff).
- AI Chat state from ACP — Each AI Chat shows working while its turn, a tool call or an ego child runs, and waiting while a permission or question is open. The state is derived once in Rust and is the same on desktop, browser and phone; a child in one chat never marks another busy, and an answered question does not return after a reconnect (#2637-c6d3).
- Chat working feedback — Desktop and mobile AI Chat and Session Chat show a theme-accent breathing orb with accessible Working… text. Reduced motion shows a static dot. Existing busy state controls its lifetime; provider retry status, native questions and permissions take precedence (#2535-8b6b).
AI Chat automatically connects on opening, restores the selected conversation, and keeps its transcript visible when stopped. Retry after a failed initial connection starts connecting without Send (#2407-84f5). Session model changes keep the same conversation; the global default affects new ego runs only (#2404-e946).
AI Chat uses a compact composer card: repository pinning and draft parking in the header, an input/send row, and live context plus clickable model/effort/mode details in the footer. Conversation actions remain in ⋯ (#2394-e3c4).
-
Select text in a Markdown file and use Send to AI Chat to append its path, source line range and quoted text to an open conversation, without sending. Desktop and mobile share the selection action. Source lines follow the selected rendered block and ignore invisible Markdown link destinations (#2361-8099). Desktop and mobile selection changes reuse the current document’s reference-link definitions; a source edit refreshes them on the next selection (#2434-73ec).
-
The owning daemon starts allowlisted GitHub issue intake without a UI. Intake keeps all-issue polling across client filter and stop calls, re-reads configuration on repository/settings events and its 30-second tick, and reports unregistered entries in daemon logs (#2323-c294).
Development builds show a dismissible restart warning when Cargo dep-info inputs are newer than the backend executable, or that executable was rebuilt after application entry. Main and used bridge inputs are checked independently; unrelated frontend-only changes stay quiet. An edit followed by a revert still warns, as Cargo would rebuild. Missing build artifacts report identity unavailable. Release builds contain no warning module or debug identity (#2332-3eef). In development, missing local IPC commands explain the backend/frontend version mismatch and manual restart; AI Chat does not offer Retry for that failure. Release and remote-owner errors are unchanged (#2409-aa48).
The Plans column groups Edit plan with Archive plan and keeps the archived toggle with list filters. Edit plan and New story use the main dialog area. The plan editor offers repository-document selection, wrapping title/source fields, an openable full source, a disabled-Save explanation, and conflict-safe draft retention. Native plan title/source corrections use atomic update_plan patches with a stored expected revision across MCP, HTTP, IPC, and CLI. Workflow planning and verification subjects include current plan metadata. Source changes wait until any running plan coordinator/planner finishes or is cancelled; title-only corrections stay available (#2170-d828).
Workflows is a separate space (palette Workflows) with Definitions/Designer and every project run; it links to and from Plans and Stories, which keeps planning and linked plan runs.
Plans and Stories offers an explicit All plans choice for a combined List/Kanban view. Rust supplies the project-scoped stories, visible ids and columns. Rows and cards label their plan; existing filters and archive scopes still apply. Story actions and dependency candidates retain plan ownership. Select one plan for plan actions or story creation (#2358-b0b2).
Native story API and CLI lists support combined state, priority and type filters, with optional cursor pages of 1–100 records; existing full-list reads and dispatch order are unchanged (#2174-6b3f).
-
Desktop frame receipts no longer keep silent terminals redrawing; missed-frame recovery avoids offering the same desktop snapshot twice without recreating its own delivery debt (#2040-16b2).
-
Native MCP tools with long guidance expose compact action contracts and return the full guide through
action=help; existing owner gates and Settings copy remain unchanged (#2069-7347). -
Independent durable peer-mail readers filter routine lifecycle traffic, retain acknowledged cursors across reconnect, and support continuous HTTP/ACP notification delivery (#2004-4760).
-
Mobile session headers offer an open-Markdown dropdown at widths of 768 px or more. Phones keep the same list in More session actions, with stable in-place refreshes.
-
AI Chat tables protect short fields, scroll wide content, toggle exact Markdown source, copy Markdown, and open read-only documents (#1923-c6fb).
-
AI Chat automatically compacts an exhausted ego context through the advertised extension, opens the continuation and replays the original prompt once. Failures and a second overflow stop recovery (#2392-b2e3).
-
AI Chat uses a compact title picker, labelled overflow actions and one-line process disclosures; model and repository sit below the composer (#1958-b67e).
Repository Settings exposes inherited overrides, scripts, team sharing, and a scoped reset card in the shared Settings vocabulary.
Agents Settings uses machine-scoped headers, section cards, and responsive named run-configuration editors, with separate terminal permissions and hibernation sections.
Workspace Settings uses consistent headers, section cards, and aligned fields across Terminal, Keyboard Shortcuts, and Git & GitHub, with the existing preview, bindings, and account flows.
Application Settings pages use shared headers, cards and right-aligned controls. Audio output discovery remains explicit; visual notification and client-local preferences retain their existing scope.
Settings policy foundation (#1786-9cbd): shared owner-service writes enforce host-issued caller authority, write-only secrets and one-use, five-minute human approval for exposure/execution changes. The existing desktop/browser/mobile confirmation dialog shows a backend-built diff. Replacement settings transport publication remains a separate integration step.
Mobile terminal Send supports long-press Queue for the next agent ready window.
Published story workflows can start in Plans and Stories through the owning daemon. When the existing readiness check reports no imported host routing policy, Plans and Stories hides workflow Start controls and shows a neutral sentence. Routing policy controls arrive in a later version. Hosts with a policy retain the existing start flow. Run history renders graph positions, decisions, evidence and paged event payloads, with explicit graph recovery and cancellation. IPC/HTTP and the generated workflow action=run MCP schema share the native run service. Plan start remains visibly unavailable pending plan dispatch. The grouped workflow MCP tool exposes typed story, run, proposal_create, report and launch actions through existing service owners. Proposal retries preserve coordinator ownership and proposal-key idempotency. Legacy workflow tools remain until cutover; scheduled automations stay separate. tuic workflow forwards the same envelope.
Terminal workflow runs remove their own untouched checkouts and branches after verified agent closure. Changed or still-owned work is retained with a run incident and a base-cleanup refusal that names its run. Allocation receipts survive restart; caller-supplied checkouts keep their existing lifecycle. See Run checkout lifecycle.
Native workflow backend definitions support bounded Fork/all-Join regions, nested and collection branches, typed If/else outcomes, persisted resource waits and generation-fenced critic repair. Exclusive Join and old serial replay remain unchanged. Dedicated Designer controls are a separate delivery.
Canonical capability inventory. Update this file when adding, changing, or removing user-visible features. See AGENTS.md for the maintenance requirement.
This document intentionally serves two audiences: users need a searchable overview of what exists, while LLMs and contributors need stable names, shortcuts, settings, and implementation anchors. It is an inventory, not a replacement for the chronological CHANGELOG.
Current version: 2.0.0
Last verified: 2026-09-16
Recent feature delta: See the Unreleased changelog section for what changed recently. Keep this page focused on the current state; do not duplicate the full changelog here.
Desktop AI Chat uses the terminal composer’s pin and blue play buttons. The pin highlights a parked draft; tooltips identify Park, Restore, Swap, Send and Queue. Mobile Park and Stop share the input row with Attach and Send.
AI Chat image paste discovers capabilities on first use and shares clipboard precedence with Ideas, terminal Compose, and terminal input: Finder image filenames allow attachments, while substantive text takes priority. An empty text clipboard flavor does not suppress an available image.
Mobile CLI and log snapshots use the active session identity when hiding agent chrome. Shell output remains visible after agent exit, and retained agent input does not become the shell composer draft (#2178-24da).
Connected PR conversations
PR popovers, unresolved-thread counts and notifications open the exact account-scoped PR in Tasks at Comments, including its first review-thread page. Without a loaded provider they open the GitHub conversation. Tasks PR details return to a matching live sidebar branch/worktree through the normal branch-selection path (#2559-dc9e).
Desktop close and quit
PTY close and kill stop polling when child status is unavailable. A persistent OS status error does not keep the desktop quit cleanup waiting forever.
Rust owns main-window close: Ask (default) offers Background, Quit and Cancel with Remember; Background hides all visible windows and keeps sessions running. Explicit Quit ignores the close preference and confirms if enabled with live terminals. Detached-panel close affects only that panel. This stage keeps the WebView loaded and does not add a tray.
Shared form controls
Desktop and mobile select fields use a shared native Select, with consistent theme colours, visible focus, disabled states and touch sizing. Tasks, Settings, Automations, Git and chat forms also share Input and Textarea controls. Desktop fields are 36px; mobile fields retain 44px touch targets. The Tasks List, Board and Roadmap switch supports arrow keys, Home and End.
Tasks create
Tasks forms show provider-required fields with inline errors that preserve typing focus. User fields can search provider accounts; labels without static choices accept comma-separated text. Jira supplies configured Project and selected Type, and encodes sub-task Parent keys for creation.
Tasks roadmap component
The host-rendered roadmap shows provider date fields on a month or quarter timeline. Date-only values retain their day; timestamps use the viewer’s local time zone. Undated or invalid schedules stay in a side list, and single dates show as milestones. Both lists use virtual rows and provider cursor pagination. The host can choose start and target field IDs; the fallback uses the first two date descriptors in order. The component is ready for Tasks shell integration and does not add a tab by itself.
Tasks list component
Jira searches accept jql: and text: prefixes. Intended JQL failures keep the
server parse message and typed query in Lists and Boards; plain text and issue-key
lookups retain their fallback behavior.
The generic Tasks list renders data-only work-item providers with account-scoped sources, saved presets, field filters, debounced search, sorting, virtual rows, and provider cursor pagination. Failed refreshes retain rows with a stale label. Filters, sort and group sit behind a Filters button that shows the active count. The Tasks shell uses container queries: below 700 px the list and the detail take turns, with a Back to list control. Rows show the open task, assignee, age, a state shape and a mark for tasks linked to a worktree; a Filters checkbox lists only linked tasks among the loaded rows. The component is available for Tasks shell integration; it does not add a tab by itself.
ego Perimeter Settings
- Settings > AI Chat edits ego roots, root access, read allowlists, writable directories and network mode through the configured CLI.
- Preview comes from ego’s effective view for the AI Chat workspace/profile.
The exec-sandbox badge reports unverified enforcement when ego says
not_checkedand renders measured capability arrays without inferring enforcement from backend names.
How to use this reference
- Users: start with the relevant section, then follow its user-guide link.
- LLMs and contributors: search for the feature name, shortcut, setting, command, or source anchor. The bullets describe current behavior, including important limitations.
- Release work: update the relevant section when behavior changes, and add the chronological explanation to
CHANGELOG.md.
User-guide map
| Feature area | User guide |
|---|---|
| Terminal, tabs, splits, and search | Terminal Features |
| Sidebar, repositories, and branches | Sidebar · Branch Management |
| Git worktrees | Worktrees |
| AI agents and agent teams | AI Agents · Agent Teams |
| Visual element inspection | Design Mode |
| GitHub, PRs, and CI | GitHub Integration |
| Smart Prompts and Prompt Library | Smart Prompts · Prompt Library |
| Settings and shortcuts | Settings · Keyboard Shortcuts |
| Plugins and MCP | Plugins · MCP Proxy Hub |
| Remote, mobile, and browser modes | TUICommander Modes · Remote Access |
| Setup and recovery | Getting Started · Troubleshooting |
| Project history, mobile outcome-first list and full hand-off Flow | Project Progress |
| Native plans and stories | Native plans and stories |
Selecting a New plan source that already belongs to an archived plan shows its title and ID with instructions to enable Archived plans, select it, and choose Restore plan. This does not create a duplicate or restore the plan implicitly; an active source match still selects its existing plan.
Story details show the persisted origin, plan step, revision and claiming session. A live terminal name appears beside the stable session ID; closed or unavailable terminals retain the ID. Transition history shows committed commands, revisions and actors in backend order, with Refresh history and explicit loading, error and empty states. New story offers Native or Plan step origin; a plan-step story requires a step label.
New story and Edit plan keep the primary action, then Cancel, together at the bottom-left. New story has no permanent manual-prefix hint below acceptance criteria; [MANUAL] criteria remain supported. Story Edit stays in the story header. Disabled Add dependency exposes its reason as a native tooltip and accessible description.
Plans and Stories combines open/closed and optional story-type filters, including untyped historical stories, with a session-retained List/Kanban switch that also survives detach and reattach. Rust supplies the shared display projection; the native board follows the Wiz Kanban layout without importing plugin code. Cards support pointer-based phase moves to backend-provided legal destinations; List rows and story detail share revision-checked Phase selectors. Illegal or rejected drops retain placement and show the reason.
Native stories support one revision-checked update_story patch through MCP, CLI, IPC and HTTP. It amends metadata including nullable story type, optional problem/risk, ordered criteria and dependencies on unclaimed Backlog/Ready stories without active run ownership. Changed requirements lose checks; priority-only edits keep them, and workflow evidence follows existing fingerprints. StoriesDialog provides one revision-checked Edit form with Save/Cancel, retained conflict drafts, and metadata, criteria and dependency fields. QA and other started work are not editable. Criteria use separate ordered entries so multiline requirement text is preserved during edits. Edited titles must contain 1 to 200 Unicode characters after trimming. Invalid titles disable Save without truncating the draft.
Native plans and stories are available through tuic story, the story MCP tool, desktop IPC, and authenticated HTTP. They support criteria, dependencies, revision-checked transitions, and live-tab claims. WontFix closes cancelled scope but never satisfies a prerequisite; a human can remove a cancelled dependency from a Backlog story. In manual plans, approving a prerequisite immediately releases eligible dependents. Plans with a workflow run require current integration receipts before release. Story import/export is outside this release.
Plans and Stories keeps a stable, viewport-bounded size while tabs and selections change; long content scrolls inside. On desktop, its header can detach it into a resizable window and bring it back through the shared panel controls. The Plans and Stories dialog provides a manual project view on desktop and in the browser: choose a top-level Markdown plan from the project, add a path or link when needed, create stories, inspect criteria and dependency status, identify transitively abandoned prerequisites, remove a direct cancelled prerequisite, start work without a terminal, check criteria, submit reviews, approve, and block outcomes. It renders the service’s cancellation count, all-cancelled flag, and plan state, including while a story is selected. A coordinator or independent reviewer may approve after checking the acceptance criteria; the session that claimed a story cannot approve it. Approval records the acting session or local API provenance.
Versioned workflow definitions are available through IPC and HTTP. The Plans and Stories Designer tab can select a seeded draft, add nodes by dragging (mouse, pen or touch) to a canvas position or by clicking, move nodes by six-dot handle or arrow keys with a persisted layout, apply Author presets (Planner, Research, Prompt draft, Mockup, Implement, Validate) that keep the host route authoritative, add For each and Splitter regions, connect, re-label and remove outcome links, edit node settings, save, and publish. Published revisions are immutable and validated before use. The two built-in templates are Story delivery and Resolve plan; automatic graph execution is still under development.
Durable workflow run storage records event history, pinned graph revisions, node attempts, external effect intents, TUIC-run check receipts, and checked integration receipts. Desktop and HTTP clients can start and inspect a run, list a plan’s runs, replay events, and send explicit run commands. The Plans and Stories dialog shows a run timeline with paged events. A managed MCP caller can explicitly launch a pinned attempt in a registered isolated worktree, create a plan story with an idempotent proposal key, and submit a typed outcome bound to the spawned session. Story attempts with overlapping or unknown file scope are serialized, and story worktree assignments are recorded before spawn. Dependents remain held until the accepted prerequisite has a current canonical integration receipt; an operator performs the merge explicitly in this slice. An unrelated canonical commit requires a fresh TUIC-computed recertification with pinned checks before release resumes. Reviewer reports can retain criterion-indexed findings and an artifact digest as advisory evidence. A worker input request pauses its run until an operator records an answer and resumes it; valid reports from other running workers remain durable during that pause. The daemon now owns run recovery, serial graph positioning, explicit graph resume, cancellation and idle duration timers under a database owner lock. Serial Agent effects, independent story policy and plan dispatch execute in the owning daemon; public story graph starts and history controls are available. Public API plan starts use slice E dispatch; the plan UI control remains visibly unavailable. E2E evaluation remains pending.
1. Terminal Management
-
Unobstructed terminal Find — Search opens below the Context and CLI/Chat switch row. Search controls wrap inside narrow panes while the view switch remains reachable.
-
Bounded input frame priority — Desktop and browser/PWA input can wake the existing grid ticker after reader-applied output, without waiting for animation rate floors. A rolling send budget preserves output coalescing; newer reader work retains its bounded retry across a send. Desktop receipt gates and synchronized output remain in force.
On desktop and mobile CLI views, adjacent 💬 answer paragraphs share one continuous green left bar without a background tint (Paper uses its darker success green for contrast), including blank rows between them. Mobile places this bar in a separate gutter outside the text box, so column-zero text stays clear and existing agent indentation stays unchanged. An unmarked prose paragraph after a blank row ends the answer; an uninterrupted indented continuation stays inside. The CLI gutter joins separate marked answer sections across internal blank rows and indented section headings when a later marked answer closes the gap. Trailing unmarked prose, unmarked list siblings, tools, prompts and status rows stay outside that gutter; extracted Answers and Chat keep their semantic paragraph boundaries. Lists, tables, quotations and fenced code remain attached to the answer. Fenced blocks keep a separate Copy row above the code on desktop and mobile, without covering wrapped text. A non-answer output row or prompt ends the region. The CLI blanks only the marker glyph cells; selection and search retain their grid coordinates. Clipboard copy removes answer-prefix markers through the same helper used by AI Chat answer buttons (including mobile) and selectable Answers text. Inline emoji and fenced examples stay literal. Chat uses the same answer extent and strips every paragraph marker.
Terminal prompt colours apply to Chat user messages only. The CLI grid retains prompt scrollbar ticks and answers-only prompt grouping without tinting prompt rows.
- Tablet keyboard input — Touch taps and mouse presses focus the same terminal input. Soft-keyboard text and deletion use the shared input handler. Primary presses suppress the browser default canvas focus change.
Terminal text retains stored combining marks through rendering, scrolling, copy and exact-codepoint search, including marks arriving in a later output chunk. Search and link positions account for the difference between grid cells and Unicode string offsets. The existing bound of nine zero-width characters per cell and the configured history limit still apply.
1.0 Design Mode for agent terminals
The extension offers Let agents capture any site as an optional Chrome all-sites grant. Approved capture needs no further browser-action gesture; without the grant, temporary activeTab access remains available. Capture consent is separate from agent eval and remote error-read consent. The sidebar reports when Chrome does not add a separate eval grant.
Agents can use ui action=design_start/stop/status/reload/navigate/screenshot/errors/eval with the same armed-recipient ownership and the sidebar host consent. Existing Design Mode denials remain effective. The separate design_mode tool is retired without an alias.
The extension sends a heartbeat every five seconds. A stale mode stops after 60 seconds without a heartbeat, or ten minutes after Start if the extension has not connected. Agents can request a page reload with ui action=design_reload repo_path=<repoPath>; the worker reloads the reviewed tab once per new sequence.
Right-click an HTTP(S) terminal link (including localhost) and choose Start in Design Mode, then Edge or Chrome, to open that exact page with the terminal agent connected. Agent coordinators use ui action=design_start session_id=<terminal> url=<page> for layout work; stop uses the returned repoPath.
- Start from an agent terminal’s context menu or the Command Palette. Choose Edge or Chrome; TUIC uses a dedicated profile per repository and browser. The launching terminal remains the default recipient and carries the armed D badge.
- Design Mode loads the profile’s own extension automatically on a cold Edge launch. A single discovered dev server opens directly; otherwise, the page explains how to choose or start one. Running profiles must be closed before starting again; branded Chrome reports an unsupported-autoload error. The sidebar lists configured URLs and live servers attributed to this repository and its linked worktrees, with fresh PTY advertisements validated against listeners.
- Pick element selects once, then browsing resumes. Multi-pick, Escape and Stop control longer collection. Cards keep extraction evidence, optional screenshots and independent comments; delete removes a card. The sidebar offers live local agents from the same repository and reports an exited recipient without switching silently.
- Send to agent sanitises and fences page evidence in Rust, then uses the same idle gate as Markdown reviews: deliver now when idle, queue when busy. Failed sends retain the cards; retry keys prevent duplicate delivery. See the pilot guide for setup and validation limits.
1.1 PTY Sessions
-
Mobile state filters — Tap Working, Idle or Awaiting counters to select any combination of session states. No selection shows all sessions. Counts stay global; state filters combine with search and sorting, and zero-count states remain selectable.
-
Up to 50 concurrent PTY sessions (configurable in Rust
MAX_SESSIONS) -
Each tab runs an independent pseudo-terminal with the user’s shell
-
Terminals are never unmounted — hidden tabs stay alive with full scroll history
-
Session persistence across app restarts (lazy restore on branch click); only agent tabs are restored — plain shell tabs are discarded and a fresh terminal is spawned instead
-
Orchestrated PTYs show a task description above the terminal alongside the last submitted user prompt; MCP callers can supply
pty_description, while spawn-only orchestration schemas fall back to a compact summary of the task prompt without changing agent launch or prompt-delivery behavior -
Managed-agent automation submits a command with one MCP
session action=submitcall: an idle empty composer is claimed atomically, raw-mode text/Enter framing cannot interleave with another writer, and the same response reports terminal acknowledgement or a precise non-retryable timeout. The action never queues or overwrites a draft;session action=inputremains write-only compatibility, with a text-to-Enter gap for detected agent sessions -
Agent session restore shows a clickable banner (“Agent session was active — click to resume”) instead of auto-injecting the resume command; Space/Enter resumes, other keys dismiss
-
Foreground process detection (macOS:
libproc, Windows:CreateToolhelp32Snapshot) -
PTY environment:
TERM=xterm-256color,COLORTERM=truecolor,LANG=en_US.UTF-8. A parentNO_COLORis stripped (sanitize_pty_parent_env) so a TUICommander launched from Codex does not leak that opt-out into independent sessions; per-command flags and per-agent environment can still request monochrome deliberately -
Pause/resume PTY output (
pause_pty/resume_ptyTauri commands) — suspends reader thread without killing the session -
Remote replay health — Stream failure, unreadable frames and initial replay stalls show a persistent error toast. Reconnect success requires a delivered frame; healthy idle terminals have no output-silence deadline.
-
Mobile dictated drafts — The first local edit replaces any different draft in the current terminal input snapshot, without importing that draft into the mobile composer. The slash quick key inserts
/only when tapped; it is not a modifier. Claude slash-command messages display their command name and arguments rather than transcript XML. -
Mobile Claude CLI / Chat — Switch in the existing session header; the composer and terminal stream stay mounted. Both desktop and mobile let the backend decide Claude transcript binding and show a notice when unavailable. Returning to CLI follows the latest output. Fresh session snapshots clear stale agent/question controls after exit, including when the output socket pauses; the composer then targets the remaining shell.
-
CLI / Chat view — Claude, Grok, Codex and ego terminals switch between the grid and a conversation view with docked Compose input, built from the agent’s session file (Grok: its
chat_history.jsonl, bound only through the exactactive_sessions.jsonregistry entry; including older prompts, human text/image follow-ups queued while Claude is busy, replies, folded tool cards, image/PDF markers and model-change cards). ego uses the exact live PID-to-lease session binding and the documentedego export --format transcript --aftercontract, not private conversation storage. Completed messages and tool lifecycle updates use the shared ticker; goal continuations and compaction checkpoints are notices. An ego executable with transcript v1 support must be configured. Desktop and mobile support Claude, Grok, Codex and ego Chat. The grid is hidden, never unmounted. On desktop, returning to CLI restores keyboard focus for the active terminal; unavailable Chat does not take focus from another editor, and inactive panes never take focus. Progress-toast navigation selects the reporting terminal, a surviving destination tab, or an empty area; it never retains another repository’s Chat composer. -
Readable session edits — Expand a Chat tool card to read structured old/new edit blocks with aligned four-space tab stops and horizontal scrolling.
-
Native terminal Chat questions — Desktop and mobile expose exported native question titles and choices. Answers use agent-specific PTY keys, not Compose submission or ACP replies. Desktop preserves transcript binding and returns to CLI for unexported or free-form prompts.
-
Pending terminal Chat prompts — Prompts submitted through the open desktop or mobile Chat composer appear immediately as muted Pending bubbles in send order, including sends while Claude or Codex is busy. Matching new native transcript messages replace them without a duplicate bubble and retire older unmatched sends, so a local slash command cannot block later receipts. This is local send feedback, not a cancellable CLI queue; prompts typed directly into the CLI or sent by another client cannot be shown before the native transcript records them. Expanded tool rows use theme colours for Bash/execute commands, flags, strings and operators. Read, Edit and Write keep the tool name separate from the path; other tools retain readable text. The collapsed activity summary and row sizing are unchanged.
-
Mobile session Chat appearance — The session detail CLI/Chat view shares desktop prompt/answer theme tokens and transcript typography. Mobile keeps its existing touch-sized switch and native input; AI Chat is a separate surface.
-
Deferred update restart — After an in-app update installs, TUICommander restarts only when no session is busy or awaiting input; the APP UPDATE notification shows how many are busy and offers Restart now (with confirmation). Turn off in Settings → General → Updates → Wait for agents before restarting (
defer_update_relaunch, default on). -
Eager resume after an update — When the app restarts to apply an update, every agent tab with a confirmed session id resumes by itself on every branch, without selecting the branch first. Tabs without a confirmed id keep the click-to-resume banner. Turn off in Settings → General → Updates → Resume all agents after an update (
eager_resume_after_update, default on). -
Terminal Chat reading layout — One reading card per turn with whole-answer Copy on hover or focus. The green bar encloses adjacent CLI-owned answer blocks in an outer region, not the whole message, on desktop and mobile. A marked item at any nesting level puts its intact outer list inside the rail; unmarked items remain context without acquiring answer ownership. Bullets and numbering always stay to the right of the rail; 96-character answer and 80-character prompt limits, collapsible two-line terminal pastes, and compact system notices. Tool activity stays in its collapsed row; Claude Bash uses its description when present. No time separators are shown because transcript entries carry no timestamp.
-
Codex tool activity — Trusted native tool hooks restore Working for the exact session and turn. Native user-input questions set Input and settle on their own result, prompt replacement, stop, interruption or exit. Background tools preserve open human approvals; permission-owner hooks await upstream support (#2626-f570, #2695-41da).
-
Current tool readout — The mobile session card and details sheet show the tool an agent runs now, from verified native metadata of Claude, Codex, Grok, ego terminals, Pi and OpenCode. Name only (64 characters), never arguments; one tool end never hides another live tool; turn, session and shell end clear it. Metadata only, never a state change (#2636-5551).
-
Codex hook trust — Explicit global installation trusts only exact TUIC definitions returned by the installed CLI and verifies native readback. Missing support or unverified trust shows review in
/hooks, never an operational badge. Status reads do not grant trust. -
Codex terminal Chat — Completed rollout messages and tools use the shared ACP transcript after a native SessionStart hook supplies exact ownership. Live PID, rollout id and cwd are validated on every read; heuristic IDs never enable Chat. Requires trusted TUIC native hooks on macOS/Linux; unsupported or unbound terminals keep Chat unavailable.
-
Intermediate Chat text — Assistant text that a tool call follows in the same turn renders smaller in the terminal Chat view, AI Chat and mobile chat, but keeps the normal readable text colour in dark and light themes; the last text of a turn keeps the normal size. Switch it off in Settings → Appearance → Chat → Mute Intermediate Text (
chat_mute_intermediate_text, default on). -
Prompt image previews — Path-based image attachments in Pending bubbles, session Chat, AI Chat messages and queue lists share framed previews above the text. One image uses one frame, two sit side by side, and three or more use a two-column grid. Missing images show an unavailable placeholder; the raw
[image: path]markers do not appear in the message text. -
Chat transcript presentation — Harness notices use compact system notes, image placeholders use attachment chips, adjacent thinking blocks share a disclosure, and TUIC answers retain the CLI highlight. Historical tool cards show status without fabricated execution timing.
1.2 Tab Bar
- Create:
Cmd+Tfor a plain terminal;+opens the agent launch menu (Alt/Option-click opens a plain terminal) - Close:
Cmd+W, middle-click, context menu - Reopen last closed:
Cmd+Shift+T(remembers last 10 closed tabs) - Switch:
Cmd+1throughCmd+9,Ctrl+Tab/Ctrl+Shift+Tab - Hold
Cmdalone (Ctrlon Windows/Linux) for 450 ms to reveal the first nine terminal-tab shortcuts; other keys, mouse buttons, scrolling, release, blur, or visibility changes dismiss the hints. - Rename: double-click tab name (inline editing)
- Reorder: drag-and-drop with visual drop indicators (works for all tab types: terminal, diff, editor, markdown, plugin panels)
- Tab status dot (left of name): grey=idle, blue-pulse=busy, green=done, purple=unseen (completed while not viewed), orange-pulse=question (needs input), red-pulse=error
- Tab type colors: red gradient=diff, blue gradient=editor, teal gradient=markdown, purple gradient=panel, amber gradient=remote PTY session
- Remote PTY sessions (created via HTTP/MCP) show “PTY:” prefix and amber styling
- Progress bar (OSC 9;4)
- Context menu (right-click): Close Tab, Close Other Tabs, Close Tabs to the Right, Detach to Window, Copy Path. Terminal tabs also offer Copy session ID, Copy process ID and Copy alias when available.
- Copy Path appears on every file-backed tab — diff, editor, markdown, HTML preview, and a plugin panel opened from a
file://url — and copies the ABSOLUTE path with$HOMEshortened to~. The tab stores keepfilePathrelative to the tab’s filesystem root, so the root is joined back on before copying - “Open in Browser” on a
file://plugin panel hands the file to the OS default application, not to the URL allowlist (which permits only http/https/mailto, because the URLs it was built for come off a PTY)
- Copy Path appears on every file-backed tab — diff, editor, markdown, HTML preview, and a plugin panel opened from a
- Context menu shortcut chords — while a context menu is open, pressing a menu item’s keyboard shortcut chord (modifier + key, or Enter) fires that action directly without needing to click. Modifier-only keystrokes (Cmd, Shift, etc.) do not close the menu so multi-key chords can form; any other non-matching key closes the menu normally
- Detach to Window: right-click a tab to open it in a floating OS window
- PTY session stays alive in Rust — floating window reconnects to the same session
- Closing the floating window automatically returns the tab to the main window
- Requires an active PTY session (disabled for tabs without a session)
- Overflow menu on scroll arrows (right-click) shows clipped tabs; the
+button always stays visible regardless of scroll position +button: click, right-click or long press (500 ms) opens the agent launch menu below the button, with each agent and run config listed directly. The most-used choice in the active branch comes first; a branch with no history uses repository counts, and ties keep the configured order. Successful menu launches persist in local UI preferences across restarts. Choose Terminal, Alt/Option-click+, or useCmd/Ctrl+Tfor a plain terminal Each row shows the agent icon, with a separate run-config label when multiple configs exist and a check for the default. The picker uses larger rows; Terminal has its own icon.- Tab pinning: pinned tabs are visible across all branches (not scoped to branch key)
- Right-click a sidebar session row to add it to the Global Workspace, or remove it when already included. This uses the same membership action as the tab context menu.
1.3 Split Panes
- Vertical split:
Cmd+\(side by side) - Horizontal split:
Cmd+Alt+\(stacked) - Navigate:
Alt+←/→(vertical),Alt+↑/↓(horizontal) - Close active pane:
Cmd+W - Drag-resize divider between panes
- Drag to split: drag a tab from the tab bar or a pane tab strip onto the left, right, top or bottom edge of a pane (or of the unsplit terminal area) to split it 50/50 with the tab on that side. A highlight shows the half the tab will take. The pane center moves the tab into that pane. An edge that cannot split (depth limit, or the tab is the only one in that pane) acts as the center. A pane that the move leaves empty closes
- Up to 6 panes in same direction (N-way split)
- Split layout persists per branch
1.4 Zoom (Per-Terminal)
- Desktop session Chat and AI Chat share a 14px default reading scale and the terminal zoom delta; AI Chat follows the active terminal. Active and all-terminal zoom actions update both Chat views; mobile keeps its device-local reading preference
- Zoom in:
Cmd+=(+2px) - Zoom out:
Cmd+-(-2px) - Reset:
Cmd+0 - Range: 8px to 32px
- Current zoom shown in status bar
1.5 Copy & Paste
- Copy selection:
Cmd+C - Selection follows retained text during output and history eviction; evicted endpoints are cleared instead of selecting replacement rows. Copy requests rebase against their displayed history snapshot under the backend grid lock.
- Paste to terminal:
Cmd+V - Trailing whitespace trimmed — All copy paths (Cmd+C, Ctrl+C, copy-on-select) strip trailing spaces from terminal rows
- Claude gutter normalization — Multi-line terminal selections remove Claude’s repeated non-breaking-space plus
▎visual margin while preserving isolated block characters and the content’s indentation - Claude prompt copy — Selections remove the composer prompt marker and continuation margin, rejoin width-supported wraps, and preserve typed breaks and pasted glyphs. Composer cleanup requires a column-zero origin outside VT soft-wrap continuations; partial body selections remain literal.
- Copy on Select — When enabled (Settings > Terminal > Copy on select), selecting text in the terminal automatically copies it to the clipboard. A brief “Copied to clipboard” confirmation appears in the status bar.
- Copy feedback (Cmd+C) — Copying via Cmd+C shows “Copied to clipboard” in the status bar, consistent with copy-on-select and Ctrl+C paths.
- OSC 52 clipboard writes — Terminal programs (tmux, vim, ssh yank) can set the system clipboard via the OSC 52 escape sequence. Because any displayed file/log can also emit it, each write surfaces a non-blocking “Clipboard updated by <session>” notice, and the behavior can be disabled entirely via Settings > Terminal > “Allow OSC 52 clipboard writes”. Suggestion chips (OSC 7770
suggest=) carrying shell metacharacters are inserted without auto-Enter so a click cannot silently execute a spoofed command.
1.6 Clear Terminal
Cmd+L— clears display, running processes unaffected
1.7 Clickable File Paths
- File paths in terminal output are auto-detected and become clickable links; a sentence period after a path is excluded from its filesystem target
- Terminal directory links open the File Browser at the resolved directory; missing paths show a notification without opening a tab
- Existing absolute paths outside registered repositories, including files under hidden directories, open in the native Markdown viewer or editor from terminal links
- Paths validated against filesystem before activation (Rust
resolve_terminal_path) .md/.mdx→ opens in Markdown panel; preview-capable files (HTML, PDF, images, video, audio, plain text/data) → open in the Preview tab (section 3.15); all other code files → open in the built-in code editorfile://URLs are recognized in addition to plain paths — the prefix is stripped and the path resolved like any other- Verified terminal link underlines remain visible during unrelated spinner redraws, including wrapped links and file paths beside a changing tool indicator.
- OSC 8 hyperlinks: programs that emit hyperlink escape sequences (e.g. Claude Code, modern
ls) produce clickable links; hover underline spans the full link text (viaterminal_hyperlink_spanbackend API) - Supports
:lineand:line:colsuffixes; the built-in editor moves to that position even when the file is already open - Single left-click opens the link instantly (UI-first — opening is a primary action, not gated behind a modifier); drag-select over a link still copies text without opening
- Right-click on a link shows a context menu with Open and Copy link (copy the resolved path/URL without opening). Right-clicking elsewhere shows the standard terminal context menu
- Recognized extensions: rs, ts, tsx, js, jsx, py, go, java, kt, swift, c, cpp, cs, rb, php, lua, zig, css, scss, html, vue, svelte, json, yaml, toml, sql, graphql, tf, sh, dockerfile, and more
1.8 Find in Content
Cmd+Fopens search overlay — context-aware: routes to terminal, markdown tab, or diff tab based on active view- Terminal: CLI incremental search with highlight decorations; Chat searches the visible transcript across inline Markdown, skips collapsed thinking bodies, and selects matches with next/previous navigation. Switching views closes search and clears highlights.
- Markdown viewer: DOM-based search with cross-element matching (finds text spanning inline tags)
- Diff viewer: DOM-based search via SearchBar + DomSearchEngine (same engine as markdown viewer)
- Yellow highlight for matches, orange for active match
- Navigate matches:
Enter/Cmd+G(next),Shift+Enter/Cmd+Shift+G(previous) - Toggle options: case sensitive, whole word, regex
- Match counter shows “N of M” results
Escapecloses search and refocuses content
1.9 International Keyboard Support
- Terminal handles international keyboard input correctly
- Rate-limit false positives reduced for non-ASCII input
1.10 Move Terminal to Worktree
MCP worktree creation registers the new workspace without moving a caller whose
cwd is outside it. Agents working through git -C can record an association with
session action=declare_worktree worktree_path=/absolute/path. That association
sets only the caller’s tab placement without changing shell cwd. Later cwd reports
and restore keep that placement while the declared checkout exists. Removing or recycling a
worktree closes only terminals whose current cwd lies inside it; unrelated tabs
filed under a stale workspace survive and are re-homed. See MCP backend.
- Right-click a terminal tab → “Move to Worktree” submenu lists available worktrees (excluding the current one)
- Selecting a worktree sends
cdto the PTY; OSC 7 auto-reassigns the terminal to the target branch - Also available via Command Palette: dynamic “Move to worktree: <branch>” entries appear when the active terminal belongs to a repo with multiple worktrees
- Only shown when the repo has more than one worktree
- When a worktree is created while an agent is running, Open Worktree opens or focuses a terminal rooted there; the agent terminal remains attached to its original branch and working directory
1.11 OSC 7 CWD Tracking
- Terminals report their current working directory via OSC 7 escape sequences
- Parsed in the Rust backend from PTY output and stored per-session as
session_cwd - When a terminal’s CWD falls inside a known worktree path, the session is automatically reassigned to the correct branch in the sidebar
- Sessions spawned into a new sibling worktree refresh their registered repository before final tab placement
- Enables accurate branch association even when the user
cds into a different worktree from a single terminal
1.12 Kitty Keyboard Protocol
- Supports Kitty keyboard protocol flag 1 (disambiguate escape codes)
- Per-session flag tracking via
get_kitty_flagsTauri command - Enables correct handling of
Shift+Enter(multi-line input),Ctrl+Backspace, and modifier key combinations in agents that request the protocol (e.g. Claude Code)
1.13 File Drag & Drop
- Drag files from Finder/Explorer onto the terminal area or any panel
- Uses Tauri’s native
onDragDropEventAPI (not HTML5 File API — Tauri webviews do not expose file paths via HTML5) - Active PTY session: dropped file paths are forwarded directly to the terminal as text (enables Claude Code image drops and similar workflows)
- No active PTY session:
.md/.mdxfiles open in Markdown viewer, preview-capable files open in the Preview tab (section 3.15), all other files open in Code Editor - Multiple files can be dropped at once
- Visual overlay with dashed border appears during drag hover
- Global
dragover/droppreventDefaultprevents the Tauri webview from treating drops as browser navigation (which would replace the UI with a white screen) - macOS file association:
.md/.mdxfiles registered with TUICommander — double-click in Finder opens them directly - Drag to external apps: Drag files from the File Browser to external applications (Finder, email clients, etc.) using native OS-level drag via
tauri-plugin-drag. Works alongside internal drag & drop (tab reorder, split panes)
1.14 Cross-Terminal Search
- Type
~in the command palette (Cmd+P) to search text across all open terminal buffers - Results show terminal name, line number, and highlighted match text
- Selecting a result switches to the correct terminal tab/pane and scrolls to the matched line (centered in viewport)
- Minimum 3 characters after prefix
- Also accessible via the explicit “Search Terminals” command in the palette
1.15 Refresh Terminal (Cmd+Shift+L)
- Rebuilds the terminal renderer to fix corrupted glyphs (WebGL atlas issues, font rendering artifacts)
- Does not clear content or affect the PTY session — purely a visual refresh
- Action name:
refresh-terminal
1.16 Terminal Bell
- Terminal Bell — Configurable bell behavior when the terminal receives a BEL character (
\x07). Four modes:none(silent),visual(screen flash animation),sound(plays the Info notification sound),both(flash + sound). Setbell_styleinconfig.json; Settings has no control for it.
1.17 Alternate-Screen Scrollback
- Fullscreen apps (
gh run watch,less,man, TUIs) run on the terminal’s alternate screen, which per XTerm semantics has no scrollback — output past the bottom of the window is normally lost and no scrollbar is shown - TUICommander keeps those lines with a user-visible save-to-scrollback behavior: scrollbar, wheel, and scrollbar drag all work while the app is running
- Output is byte-faithful: only lines that genuinely scroll off the top are kept. An in-place redraw produces no history, while a refresh taller than the viewport (as emitted by
gh run watch) keeps each overflowing snapshot, including repetitions - The alternate grid has its own bounded, ephemeral history. It is wiped on every enter/exit and never mixes with the shell’s history
- Entering or leaving the alternate screen atomically invalidates scroll, selection, search, link, and row-cache state before the new grid is painted
- Apps with mouse reporting (
vim,htop,lazygit,grok --no-alt-screen) still receive the wheel themselves —Shift+wheelor a scrollbar drag scrolls TUICommander’s history - An inline TUI that enables mouse reporting without
1049h(grok --no-alt-screen) is classified as FullscreenTui and excluded from the durable log the same way alt-screen is. Grid history stays so the scrollbar works.
1.18 Scrollback History Overlay — removed
The experimental read-only scrollback overlay (AltScreenHistory) and its scrollHistoryEnabled flag were removed in 86471444. The terminal’s own scrollback and search replace it.
1.19 Command Blocks
Terminal output is segmented into command blocks — one per prompt+output cycle. Blocks are detected via OSC 133 shell integration markers (A/C/D sequences) or OSC 7770;block= agent-emitted markers. For Claude Code, heuristic detection synthesizes blocks from tool call headers (⏺ ToolName(args)).
- Scrollbar marks — Color-coded indicators on the scrollbar for each command block boundary. Provides a visual map of command history at a glance. Toggled by Show scrollbar marks in Settings > Terminal (
show_scrollbar_marks, on by default). The flag covers the history markers — these ticks and the user-prompt ticks below — and deliberately not the search-match ticks, which stay visible so a search never silently draws nothing - User-prompt scrollbar markers — A distinct green tick on the scrollbar marks each line where the user submitted a prompt to the agent (recorded from the OSC 7770
state=promptthe submit-prompt hook emits; tool-callstate=busycarries no row viauserPromptLines). These are separate from command-block boundary marks and help you quickly locate your own prompts in long sessions - Timestamp overlay — Hold
Ctrl+Cmdto reveal timestamps showing when each block started, displayed as relative time (e.g. “2m ago”) - Gutter click — Click the gutter area to select the entire block output for easy copying
- Block folding — Collapse/expand block output with
Cmd+Shift+.toggle. Folded blocks show a summary line. Backend stores fold state per session viaset_block_foldTauri command - Block-scoped search — Toggle with
Cmd+Shift+Bto restrict terminal search to the current block only - Block navigation —
Cmd+Shift+Up/Downjumps between block boundaries - Block cap — Sessions are capped at 500 command blocks; oldest blocks are evicted when the cap is reached
- Settings — Configure block features at Settings > Terminal > Terminal: show/hide timestamps, enable/disable folding
1.20 Compose Panel (Cmd+I)
A multi-line editor docked under the terminal for writing a prompt without fighting the agent’s own input box.
- CLI Compose layout — Desktop terminals reserve the minimum editor row and footer when Compose opens. Longer drafts overlay terminal output without repeated PTY resizing; closing restores the full viewport. Pinning keeps the same reservation. Leaving Compose focus collapses its extra height to reveal terminal input; refocusing restores growth and retains the draft.
- Chat input — Chat opens and focuses Compose automatically below the conversation. It stays docked after send or queue and clears submitted text. Chat hides the close and pin controls;
Escreturns to CLI, where permission prompts must be answered. Returning to CLI restores the tab’s previous open/pin state, and unsent drafts survive both directions, including while send or queue is pending - Send now —
Enter(or the ▶ button) types the text into the composer and submits it immediately, steering whatever the agent is doing - Shortcut hints — the newline legend shows only
Ctrl+Enter. Panels up to 640px wide hide the legend instead of wrapping; all keyboard bindings remain available - New line —
Ctrl+EnterorShift+Enterinserts a line break without sending. Enter used to confirm an IME candidate does not send - Queue for the next idle window —
Shift+Ctrl+Enter(or the ☰ button) hands the text to the backend’s idle gate instead: it is submitted at once if the agent is already idle, otherwise parked until the agent’s next busy→idle transition. This is the way to leave follow-up work for an agent mid-turn without interrupting it - Collapsed handle — transparent chrome and a muted label at rest; hover or keyboard focus reveals the background and border. Label and count remain fully opaque
- Queue count — the collapsed Compose button shows a muted pill for every waiting FIFO item, including commands and peer/orchestrator notices, hidden at zero. Hover or focus shows the command/message breakdown. The open panel shows
N queued; click it to inspect and remove entries, or clear the queue. Counts come from the backend (state.queued_commands), including across reloads and remote clients - Order — queued commands are typed one per idle window, in the order they were composed; a new one never overtakes one already waiting. Hands-free speech does not use this queue at all — see 9.9
- Progress replies — a queued user command can resume an idle agent waiting on a blocked progress report. Native questions and approval dialogs still block queued delivery; server notices cannot use this exception or be overtaken
- Agents only — queueing is hidden for a plain shell: its idle state says nothing about which program currently owns stdin
- Pin — the pin button docks the panel under the terminal instead of over it: the terminal shrinks and the PTY resizes, so no output hides behind the panel. A pinned panel stays open after a send or a queue and removes the sent text, so it can replace the agent’s own input box. Text typed while the send runs is kept, and a second send before the first finishes is ignored. When the terminal has no session or the send fails, a toast shows the error and the text stays.
EscandCmd+Imove the caret between the panel and the terminal instead of closing it. Per tab, not persisted - Close button — the ✕ in the status bar closes the panel and releases the pin;
Esccloses an unpinned panel
1.21 Auto-Standby (Unix)
Idle, unfocused terminals can be paused to reduce CPU and battery use. A background checker (every 30s) sends SIGSTOP only when the PTY child owns the foreground process group. An agent running as a separate foreground job inside an interactive shell is not stopped: shell job control would reclaim the terminal and leave that job suspended. Processes in the eligible child’s group are paused together.
- Entry conditions (all required) — timeout enabled (
> 0), tab not focused, shell state idle, no tracked agent background work, idle for at least the timeout, session startup settled, and not already in standby. Claude/Codex/Gemini/Grok/pi/OpenCode additionally require confirmed idle (explicit lifecycle marker or stable ready screen); silence-only idle cannot suspend them. Grok distinguishes its active Braille-spinner status row from the persistent❯composer. - Remote activity — remote input, HTTP output reads, and remote observer disconnects start a full timeout window before standby can resume; connected terminal WebSockets and SSE observers prevent standby. Recent local input also prevents standby. Desktop raw input wakes an already parked shell through the same visibility-serialized activity path.
- Wake —
SIGCONTtargets the exact recorded stopped group when the tab is focused, remote input/output arrives, or a message arrives for the agent; the process resumes where it stopped (no session loss, no restart) - Safety — the process-group id is validated before signalling; an unsafe pgid is refused rather than risking a stop sent to the wrong group
- Pause badge — suspended tabs show a pause indicator in the tab bar
- Event —
session-standby({ session_id, standby }) emitted on stop/wake - Settings — Settings > General > Power Management > Auto-Standby Timeout (default 5 min;
0disables) - Not Suspend — standby only
SIGSTOPs the process group and keeps its memory; Suspend Tab ends the process
1.21a Suspend Tab
A terminal tab can be suspended from its context menu (Suspend Tab) or with MCP session action=suspend. The PTY and its agent end, so memory and CPU are released, while the tab stays restorable exactly like a tab after a TUICommander restart.
- Kept on the tab — cwd, worktree, alias,
tuic_session, agent type, agent session id and launch command. The tab shows azzbadge and a Suspended notice with a Resume button. - Resume — the button and menu ask Rust to verify the saved agent session against its launch profile and open a replacement PTY in the same folder. A shell tab reopens its shell; the frontend attaches the returned PTY without sending another command.
- Persistence — Rust writes
suspended-sessions.jsonin the config directory before ending the PTY. Records keyed bytuic_sessionretain cwd, worktree, alias, agent type, agent session id, launch command, pane slot and reason (user, reservedidle_hibernate). A recreated frontend lists these records and renders suspended tabs without starting processes. - Refusals — working/starting agents, background work, unanswered questions, queued commands, busy shells, exited sessions and non-resumable agents remain protected by Rust checks.
- MCP verdict —
session action=suspendreturns{ok:true}after Rust persists and ends the PTY, including when no UI is attached. Refusals returnCannot suspend: <reason>. - Event —
session-suspendedcarries{record}over desktop events and SSE before the PTY closes. The IPC/HTTPsuspended_session_actionendpoint supports listing, suspending, resuming, forgetting and metadata synchronization.
2. Sidebar
- Right-click a session row to copy its PTY session ID, live PTY child PID, or exact session alias. Entries show their values on hover and confirm copies; unknown PID and absent alias entries are hidden.
Automatic repository refreshes start at least five seconds apart per repository. Event bursts retain one trailing refresh; badges can lag by five seconds plus backend read time. Explicit repository additions, branch checkouts and merge cleanup refresh the affected repository immediately, while still waiting for any active refresh to finish.
2.1 Repository List
- Add repository via
+button or folder dialog - Click repo header to expand/collapse branch list
- Click again to toggle icon-only mode (shows initials)
⋯button: Repo Settings, Switch Branch (via context menu on main worktree), Create Worktree, Move to Group, Park Repository, Remove- macOS TCC access dialog: when the OS denies access to a repository directory (e.g. Desktop, Documents), a dialog explains the issue and guides the user to grant Full Disk Access in System Settings
2.2 Repository Groups
- Named, colored groups for organizing repositories
- Create: repo
⋯→ Move to Group → New Group… - Move repo: drag onto group header, or repo
⋯→ Move to Group → select group - Remove from group: repo
⋯→ Move to Group → Ungrouped - Group context menu (right-click header): Rename, Change Color, Delete
- Collapse/expand: click group header
- Reorder groups: drag-and-drop
- Color inheritance: repo color > group color > none
2.2.1 Switch Branch
Right-click the main worktree row → Switch Branch submenu to checkout a different branch. The submenu shows all local branches with a checkmark on the current one. If the working tree is dirty, prompts to stash changes first. Blocks switching when a terminal has a running process.
2.3 Branch Items
- Click: switch to branch (shows its terminals, creates worktree if needed)
- Double-click branch name: rename branch
- Right-click context menu: Copy Path, Add Terminal, Create Worktree, Merge & Archive, Delete Worktree, Open in IDE, Rename Branch
- Worktree removal makes read-only build artifacts removable inside the checkout before Git deletes it; an unregistered directory left behind is reported with its path.
- Stale creation recovery preserves registered Git checkouts on name collisions. Force branch deletion saves an exact-tip archive ref and refuses conflicting archives.
- Background Git actions share a subcommand and per-command flag policy across desktop IPC and HTTP.
+button: click opens a terminal in that branch; long press (500 ms) lists the enabled agents and opens a tab running the chosen one (a shell row has no agents, so there a long press acts as it did before: a click, or the row menu on touch); right-click opens the row menu- CI ring: proportional arc segments (green=passed, red=failed, yellow=pending)
- PR badge: always shows
#numberplus its highest-priority state when applicable (Draft, Conflicts, CI, review, merged/closed), with state color — click for detail popover - Diff stats:
+N / -Nadditions/deletions. Clicking the stats chip or theN dirtychip selects that workspace and opens the Git panel on the Changes tab (it stays open if already there) - Merged badge: branches merged into main show a “Merged” badge
- Unmerged mark: a small neutral outlined square shows commits outside the default branch even when the diff and dirty counts are zero
- Question indicator:
?icon (orange, pulsing) when agent asks a question - Idle indicator: branch icons turn grey when the repo has no active terminals
- Quick switcher badge: numbered index shown when
Cmd+Ctrlheld - Remote-only branches with open PRs: shown in sidebar with PR badge and inline accordion actions (Checkout, Create Worktree). Additional actions when PR popover is open: Merge, View Diff, Approve, Dismiss
- Dismiss/Show Dismissed: remote-only PRs can be dismissed from the sidebar; a “Show Dismissed” toggle reveals them again
- Branch sorting: main/master/develop always first, then alphabetical; merged PR branches sorted last
2.3.1 Nested Terminal Tabs (opt-in)
- Disabled by default. Enable it via Settings → Appearance → Tabs → Nested Terminal Tabs (
tab_tree_enabled). The change applies immediately; no restart is required. - While disabled, the sidebar keeps the normal branch rows and does not render the activity card or nested agent/session rows. Missing nested agents therefore usually means this opt-in setting is still off.
- When enabled, every branch with at least one open terminal session gets an expandable activity card. Enabling the setting does not create sessions: an agent appears only after it is running in a terminal assigned to that branch.
- Agent rows show the agent icon, terminal name, current intent/task (falling back to the last substantial prompt), compact age since the backend’s last semantic session activity, and the same busy/idle signal used by the terminal tab and branch icon. Terminal redraws do not reset this age. Plain shells remain visible as terminal rows.
- A sub-agent row shows a muted robot tag with its parent agent in the tooltip; the repo GitHub badge retains the accent color to distinguish its action from session metadata.
- Clicking a row switches to that session.
- Every branch shows its agents by default; collapsing is remembered per workspace. A separate, always-visible chevron toggles the list by click or Enter/Space. The status icon and row select the branch without changing agent visibility.
- Single-session branches can expand too.
- A collapsed list shows its session count beside the chevron; an expanded list hides the count.
2.4 Git Quick Actions
- Bottom of sidebar when a repo is active
- Pull, Push, Fetch, Stash buttons — execute in active terminal
2.5 Sidebar Resize
- Drag right edge to resize (300-500px range)
- Row starts stay visible while resizing or focusing branch actions; horizontal overflow does not scroll the list
- Toggle visibility:
Cmd+[ - Width persists across sessions
2.6 Quick Branch Switcher
- Hold
Cmd+Ctrl(macOS) orCtrl+Alt(Win/Linux): show numbered overlay Cmd+Ctrl+1-9: switch to branch by index (in the Global Workspace: switch to tab N)
2.7 Park Repos
- Right-click any repo in the sidebar to park or unpark it
- Group park/unpark: right-click a group header or use the command palette to park or unpark all repos in a group at once
- Parked repos are hidden from the main repository list
- Sidebar footer button opens a popover showing all parked repos
- Unpark a repo from the popover to restore it to the main list
2.7a Sidebar Layout (compact / rich)
- Rich repository metadata hides zero PR and worktree counts; positive counts update live
- Toolbar button (left of the filter icon) cycles rich, compact and harness-only and prints the mode (R, C, H); H keeps rich rows and only branches with live harness sessions; the mode is saved in UI prefs (
sidebar_density) - Compact: one-line rows. Rich: compact-sized navigation with inline branch facts and expanded intent only for working agents. H: only branches with live harness sessions, using rich rows
- Rich branch row: PR state word and title; last-commit age, ahead/behind the upstream, diff stats, dirty-file count (opens Changes), merged, stale (no commit for 30 days), unknown (removal blocked), unmerged; never stale, merged, dirty or unknown on a main checkout. Compact carries the age, ahead/behind and stale rule on the branch name tooltip
- Rich agent row: state (working, idle, needs input, error) and the agent’s intent, task or last prompt; in-session subagents (state, title, tool calls, age; more than 3 fold into a count); TUIC child sessions nested under the parent. Compact carries state and line on the row tooltip
- Rich repo header: current branch, open PR count, worktree count, age of the last remote poll
2.8 Active-Only Filter
- Toggled from the filter icon in the toolbar (next to the sidebar collapse button); the icon turns accent-colored while engaged
- When on, the sidebar shows only repositories that have at least one open terminal — empty groups are dropped entirely (no orphaned headers)
- An accent banner at the top of the sidebar makes it unmistakable that repos are hidden, shows a
shown / totalcount, and offers “Show all” to clear the filter - If the filter hides every repo, a dedicated empty state offers “Show all”
- Session-only (not persisted across restarts)
2.9 H View (Live Harness Only)
- Toggled from the H button next to the Active-only filter icon; the button turns accent-colored while engaged
- Keeps only session rows whose harness is alive (working, idle or awaiting input); shell-only terminals and ended harness sessions are dropped
- Keeps only branches with such a session, repositories with a kept branch and groups with a kept repository; other branches of a qualifying repository are hidden. Order, indentation, icons and badges of the kept rows are unchanged
- Shares the banner, the
shown / totalcount and the “Show all” empty state with the Active-only filter; visibility follows session state live - Session-only (not persisted across restarts)
3. Panels
3.1 Panel System
- File Browser, Markdown, Diff, and Plan panels are mutually exclusive — opening one closes the others
- Ideas panel is independent (can be open alongside any of the above)
- Subtle fade transition when closing side panels (opacity + transform animation)
- All panels have drag-resize handles on their left edge (200-800px)
- Min-width constraints prevent panels from collapsing (Markdown: 300px, File Browser: 200px)
- Toggle buttons in status bar with hotkey hints visible during quick switcher
3.2 Diff Panel (Removed in 0.9.0)
Replaced by the Git Panel’s Changes tab (section 3.8). Cmd+Shift+D now opens the Git Panel
3.3 Markdown Panel (Cmd+Shift+M)
- Selective review reads: desktop and mobile send the changed current-file line ranges across saved local edits, with enclosing-section guidance; first-open reviews without local saves, external replacements, and unavailable baselines keep whole-file reading. Tweak counts and resolved-marker cleanup remain included.
- Mobile review send: send saved checkbox edits, source edits, and tweak comments from the mobile Markdown view. Choose a repository agent; the originating session is selected when available. The backend delivers at idle or queues for the next idle window and reports the outcome.
- Renders
.mdand.mdxfiles with syntax-highlighted code blocks - A Markdown document tab, including one opened through
tuic://open, can be detached from its tab context menu into a resizable window. Its tab remains in the main window; selecting it focuses the document window, and closing that window returns the document to the tab. The detached viewer rereads the file on focus and while open. - Rendered Markdown links open files and directories in TUICommander, including local symlinks and parent paths; direct UNC hrefs open with the system handler after a click and confirmation (the host is never probed), and paths that reach macOS privacy-protected home directories are not probed. Heading and
file:lineorfile:line:columntargets work without navigating the WebView; web and email links use the system handler - File list from repository’s markdown files
- Clickable file paths in terminal open
.mdfiles here - Auto-show: adding any markdown tab automatically opens the Markdown panel if it’s closed
- Header bar shows file path (or title for virtual tabs) with Edit button (pencil icon) to open in CodeEditor
Cmd+Fsearch: find text in rendered markdown with highlight navigation (shared SearchBar component)- Interactive GFM checkboxes:
- [ ],- [x], and- [~]task-list items render as clickable checkboxes. Clicking cycles through unchecked → checked → in-progress → unchecked. Changes are written back to the source.mdfile on disk. The[~]state renders as an indeterminate (half-filled) checkbox — non-standard GFM extension for tracking in-progress items - Mermaid diagrams: fenced code blocks with
```mermaidare rendered as interactive SVG diagrams. Mermaid.js is lazy-loaded on first use with dark theme - Inline review comments (tweaks): review-comment any passage of a rendered markdown file without leaving the viewer.
- Create: select text in the rendered markdown → a floating Comment button appears next to the selection → click it to open an inline popover and type the note (
Ctrl+Enterto save) - Block comments: move through the gutter left of a heading, paragraph, individual list item (including task and nested items), quote, table, or code block to highlight its exact Markdown source and reveal its comment button. List-item markers sit on an indented continuation line below the chosen item’s own content, preserving the list. Block anchors use the renderer’s raw-source ranges, so links and inline HTML do not depend on matching rendered text back to Markdown
- After each save, block ranges and highlights are refreshed from the updated source even when the visible Markdown is unchanged by the invisible comment markers. Consecutive comments remain attached to the items that were selected.
- Send to agent: the Markdown topbar lists live agents belonging to the same repository. Sending queues one file-scoped instruction through the existing agent idle gate; an idle agent receives it immediately, while a busy agent receives it at its next idle window. After a successful send, Agent and Send hide until a new tweak comment, checkbox change or saved text edit. Edits saved while a send is pending keep the controls available for another send. Failed sends keep the controls available for retry
- View / edit / delete: commented passages and blocks are highlighted; hovering one shows the comment in a tooltip, clicking it reopens the popover to edit or delete. Deleting removes the saved marker and its highlight, closes the popover, and leaves other comments intact, including comments on rendered Mermaid diagrams, even when the rendered Markdown text is unchanged
- Storage: comments live inside the
.mdsource as HTML-comment markers. Inline comments wrap their source text withtweak:begin/tweak:end; block comments use atweak:blockmarker immediately before the target block, while list-item comments use atweak:itemmarker within that item. Both forms are invisible to standard Markdown renderers, survive round-trips, and are committed with the file. The only escaped sequence is-->(→-->) - Save failures: Markdown files opened by absolute path use the external file writer. A failed comment save shows an error toast and keeps the comment popover and draft open for retry.
- LLM-friendly: the first comment added to a file prepends an invisible HTML-comment header explaining inline, block, and list-item markers, so an AI agent reading the raw file understands them without external context. Existing files with the older header remain readable and editable. The intended workflow is “human highlights + comments → agent applies the feedback to the highlighted text → agent removes the markers”
- Rendering: highlights are wrapped in the DOM after markdown parsing, so a selection that straddles inline formatting (
**bold**,`code`) stays intact and the highlight spans contiguously. Implemented inContentRenderer, whose consumers are the Markdown panel and the AI Chat transcript
- Create: select text in the rendered markdown → a floating Comment button appears next to the selection → click it to open an inline popover and type the note (
3.4 File Browser Panel (Cmd+E)
-
Bounded remote file API:
/fs/readcan return exact byte pages as base64, including files above the text editor limit. Pages are capped at 1 MiB with total size, continuation and clamp fields. Existing text reads are unchanged. -
Symbolic links: link icon, target path and target kind in tree and list views; links are followed wherever they point, also to another volume, for reads, edits, creates and deletes inside a linked directory; requested paths stay repository-relative (absolute, drive, network and above-root
..paths are refused). Delete removes only the link, including unavailable links, and failed deletes show an error notification. -
Remote file drops: native OS files dropped onto a connected remote repository are copied through its authenticated daemon connection; sources remain on the Mac. Directory copies require confirmation and existing names are skipped. Each top-level upload is limited to 256 MiB (including archive overhead) and 10,000 entries; symlinks and special files are rejected. Native destination filenames and safe executable permissions are preserved; uploads abort after 30 seconds without data.
-
Directory tree of active repository
-
Auto-refresh: nonrecursive directory watchers cover the current listing and visible expanded tree folders, including non-Git roots and nested repositories. External file and folder creation, deletion and renaming refresh the affected listing; collapsed folders reload when reopened
-
Navigation:
↑/↓(navigate),Enter(open/enter dir),Backspace(parent dir) -
Breadcrumb toolbar: always-visible path bar with click-to-navigate segments + inline sort dropdown (funnel icon)
-
Search filter: text input with
*and**glob wildcard support -
Git status indicators: orange (modified), green (staged), blue (untracked)
-
Context menu (right-click): Copy (
Cmd+C), Cut (Cmd+X), Paste (Cmd+V), Rename, Delete, Add to .gitignore -
Keyboard shortcuts work when panel is focused (copy/cut/paste)
-
Sort dropdown: Name (alphabetical, directories first) or Date (newest first, directories first)
-
Drop refresh: successful local moves, copies and remote uploads refresh expanded destination and source folders, including transfers that require confirmation.
-
View modes: tree view (default) and flat list — toggle via toolbar buttons. Tree view shows a collapsible hierarchy with lazy-loaded subdirectories on expand. Switching to tree resets to repo root. Search always uses flat results
-
Click file to open in code editor tab
3.4.1 Content Search (Cmd+Shift+F)
- Full-text search across file contents — toggle from filename search via the
Cbutton in the search bar - Options: case-sensitive, regex, whole-word
- Results stream progressively and are grouped by file with match count per file
- Each result row shows file path, line number, and highlighted match context
- Match highlighting stays aligned after Unicode text, including non-BMP emoji
- Click a result to open the file in the code editor at the matched line
- Binary files and files larger than 1 MB are automatically skipped
- Backed by
search_contentTauri command; results delivered viacontent-search-batchevents, each carrying thesearch_idof the panel that asked (the event is global and three panels listen)
3.5 Code Editor (CodeMirror 6)
- Opens in main tab area when clicking a file in file browser
- Hold
Cmd(macOS) orCtrl(Windows/Linux) while hovering to underline a link, then click to open it. HTTP(S) URLs open in the system browser; Markdown links and file paths open in TUICommander. Paths may be absolute,~/-prefixed, relative to the edited file, or relative to its repository, with an optional:line. Directories open in the File Browser; missing paths show a toast. Other modified clicks keep go-to-definition behavior. - Syntax highlighting auto-detected from extension (disabled for files > 500 KB)
- Line numbers, bracket matching, active line highlight, Tab-to-indent
- Find/Replace:
Cmd+F(find),Cmd+G/Cmd+Shift+G(next/prev),Cmd+H(replace), selection match highlighting - Save:
Cmd+S(when editor tab is focused) - Read-only toggle: padlock icon in editor header
- Line wrapping: header toggle or
Alt+Z; text-like and Markdown files start wrapped, code files start unwrapped; each kind remembers its choice - Per-tab font zoom:
Cmd+=/Cmd+-changes the active editor by 2px (8–32px);Cmd+0resets it to the configured default - Unsaved changes: dot indicator in tab bar and header
- Disk conflict detection: banner with “Reload” (discard local) or “Keep mine” options
- Auto-reloads silently when file changes on disk and editor is clean
- Undo/Redo:
Cmd+Z/Cmd+Shift+Zwith full history - Code folding: collapse/expand blocks via gutter arrows or
Cmd+Shift+[/] - Auto-close brackets: typing
(,[,{,",'inserts matching pair - Scroll past end: last line can scroll to the top of the viewport
- Block selection:
Alt+dragfor rectangular/column selection with crosshair cursor - Drop cursor: ghost cursor shown when dragging text over the editor
- Special character highlighting: invisible chars (zero-width spaces, control chars) rendered as placeholders
- CSS color preview: inline color swatches next to hex/rgb/rgba/hsl values
- Large-file support: files up to 250 MB open via a dedicated read path (
read_file_editor/MAX_EDITOR_LARGE_FILE_SIZE). Files that exceed this cap are refused up front with an informational notice instead of hanging the UI. In a browser or on the phone, the whole-file read stops at 10 MB on atuic-remotehost; the notice then offers Load in pages, which reads the file in bounded 1 MiB pages up to the same 250 MB limit and stops if the file changes on disk. Standard syntax highlighting is disabled above 500 KB, but the file still opens and is fully editable - Inline git blame (GitLens-style): a dim italic
author · relative time · summaryannotation at the end of the active line, following the cursor over already-loaded blame data (fetched on load/save/repo-revision viaget_file_blame, never per keystroke). Lines with uncommitted edits showYou · Uncommitted changes. On by default (inline_blame_enabledconfig field); no annotation for external (non-repo) files
3.6 Ideas Panel (Cmd+Alt+N)
- Quick notes / idea capture with send-to-terminal
- Agents use planner
add_idea,list_ideas, andupdate_ideathrough thestoryMCP tool,tuic story, IPC, or HTTP. Ideas keep their agent/session source and project scope innotes.json. Backend changes reload open panels throughideas-changed; stale panel saves merge by idea id and changed field, so they do not erase agent additions. Entersubmits idea,Shift+Enterinserts newline- Per-idea actions: Edit (copies back to input), Queue (agent tabs only), Send to Terminal (sends + return), Delete
- Queue leaves the idea in the agent’s Compose FIFO for its next idle window instead of typing it into the prompt now, so it never steers the running turn. The action appears only when the active tab runs a detected agent; a detached Ideas window always shows it and reports a refusal by toast.
- Mark as used: notes sent to terminal or queued are timestamped (
usedAt) for tracking - Badge count: status bar toggle shows count of notes visible for the active repo
- Per-repo filtering: notes can be tagged to a repository; untagged notes visible everywhere
- All-repositories toggle (stacked-layers button, header): shows the ideas of every repository together; in memory only. Badge and “clear completed” follow the visible list; new ideas stay tagged with the active repo
- Image paste:
Ctrl+V/Cmd+Vpastes clipboard images as thumbnails attached to the note- Images saved to
config_dir()/note-images/<note-id>/on disk - Thumbnails displayed inline below note text and in the input area before submit
- Image-only notes (no text) are supported
- Images removed from disk when the note is deleted
- Send to terminal appends absolute image paths so AI agents can read them
- Max 10 MB per image; accepted formats: PNG, JPEG, WebP, GIF
- Images saved to
- Edit preserves note identity (in-place update, no ID change)
Escapecancels edit mode- Data persisted to Rust config backend
3.7 Help Panel (Cmd+?)
- Shows app info and links (About, GitHub, Discord Community, docs)
- Keyboard shortcuts are now in the Settings > Keyboard Shortcuts page (auto-generated from
actionRegistry.ts)
3.8 Git Panel (Cmd+Shift+D)
Tabbed side panel with four tabs: Changes, Log, Stashes, Branches. Replaces the former Git Operations Panel floating overlay and the standalone Diff Panel.
Changes tab:
- Porcelain v2 working tree status via
get_working_tree_status(branch, upstream, ahead/behind, stash count, staged/unstaged/untracked files) - Sync row: Pull, Push, Fetch buttons (background execution via
run_git_command) - Stage / unstage individual files or stage all / unstage all
- Discard unstaged changes (with confirmation dialog)
- Inline commit form with message input and Amend toggle
- Click a file row to open its diff in the diff panel
- Status icons per file: Modified, Added, Deleted, Renamed, Untracked
- Per-file diff counts (additions/deletions) shown inline
- Glob filter to narrow the file list
- Path-traversal validation on all stage/unstage/discard operations
- History sub-panel (collapsible): per-file commit history via
get_file_history(follows renames), paginated with virtual scroll - Blame sub-panel (collapsible): per-line blame via
get_file_blame(porcelain format), age heatmap (green=recent, fading to neutral), commit metadata per line
Log tab:
- Paginated commit log via
get_commit_log(default 50, max 500) - Virtual scroll via
@tanstack/solid-virtualfor large histories - Canvas-based commit graph via
get_commit_graph: lane assignment, Bezier curve connections, 8-color palette, ref badges (branch, tag, HEAD). Graph follows HEAD only - Click a commit row to expand and see its full commit message body (multi-line, untruncated) and changed files (via
get_changed_files) - Click a file in an expanded commit to open its diff at that commit hash
- Relative timestamps (e.g., “3h ago”)
Stashes tab:
- List all stash entries via
get_stash_list - Per-stash actions: Apply, Pop, Drop (via
run_git_command)
Branches tab (Cmd+G — opens Git Panel directly on this tab):
- Local and Remote branches in collapsible sections
- Rich info per branch: ahead/behind counts (↑N ↓M), relative date, merged badge, stale dimming (branches with last commit > 30 days)
- Prefix folding: groups branches by
/separator (e.g.feature/,bugfix/), toggle to expand/collapse groups - Recent Branches section from git reflog
- Inline search/filter to narrow branch list
- Checkout (Enter / double-click): switches to the selected branch, with dirty worktree dialog (stash / force / cancel)
- n — Create new branch (inline form, optional checkout)
- d — Delete branch (safe + force options; refuses main branch and current branch)
- R — Rename branch (inline edit)
- M — Merge selected branch into current. Result is surfaced as a toast: conflict error on failure, “Already up to date” on a no-op, or a success toast with a one-click “Delete branch” action for the now-merged branch
- r — Rebase current onto selected branch
- P — Push branch (auto-detects missing upstream and sets tracking)
- p — Pull current branch
- f — Fetch all remotes
- Context menu (right-click): Checkout, Create Branch from Here, Delete, Rename, Merge into Current, Rebase Current onto This, Push, Pull, Fetch, Compare (shows
diff --name-status) - Delete merged: a broom button (with a count badge of how many qualify) bulk-deletes all local branches already merged into main, behind a confirm dialog listing the targets. Uses the same fresh integration proof as MCP and compares each ref with the proved tip. Content-based proofs require an archive of that tip
- MCP
repo branch_integrationsandrepo branch_integrationreport proof, tip, archive requirements and worktree paths. The branch panel and sidebar use the same backend classifier. - Backend:
get_branches_detail,get_merged_branches,delete_branch,create_branch,get_recent_branches. The list renders fromget_branches_detailfirst; merged badges arrive fromget_merged_brancheswhen the classification is done - Click on sidebar “GIT” vertical label also opens Git Panel on the Branches tab
Keyboard navigation:
Escapeto close the panelCtrl/Cmd+1–4to switch between tabs (1=Changes, 2=Log, 3=Stashes, 4=Branches)- Auto-refreshes via repo revision subscription
3.9 Quick Branch Switch (Cmd+B)
- Fuzzy-search dialog to switch branches instantly
- Shows all local and remote branches for the active repo
- Badges: current, remote, main branch indicators
- Keyboard navigation: Arrow keys, Enter to switch, Escape to close
- Remote branches auto-checkout as local tracking branch
- Fetches live branch list via
get_git_branches
3.10 Task Queue Panel (Cmd+J)
- Task management with status tracking (pending, running, completed, failed, cancelled)
- Drag-and-drop task reordering
3.11 Command Palette (Cmd+P)
- Fuzzy-search across all app actions by name
- Recency-weighted ranking: recently used actions surface first
- Each row shows action label, category badge, and keybinding hint
- Keyboard-navigable:
↑/↓to move,Enterto execute,Escto close - Browser mode mounts the same palette and exposes it through the magnifying-glass toolbar button, so it does not depend on the browser forwarding
Cmd/Ctrl+P - Browser actions are fail-closed: only commands explicitly verified against the web UI or HTTP transport are shown; native dialogs, detached windows, updater controls, MCP configuration, and user-plugin management remain omitted
- Search modes: type
!to search files by name,?to search file contents,~to search across all open terminal buffers. File/content results open in editor tab (content matches jump to the matched line). Terminal results navigate to the terminal tab/pane and scroll to the matched line. Leading spaces after prefix are ignored - Browser filename and content searches use the existing HTTP routes. Content results are correlated with a per-search random ID and republished only inside the requesting page, preventing results from leaking across windows or panels
- Discoverable search commands: “Search Terminals”, “Search Files”, “Search in File Contents” appear as regular palette commands and pre-fill the corresponding prefix
- QR for Remote Mobile Connection: opens a large black-on-white QR (in a dialog) that a phone can scan to launch the mobile companion PWA. Reuses the Settings → Remote Access connect flow (
get_connect_url— token stays server-side); shows a hint when Remote Access is disabled and a network picker for multi-IP machines. Failed local IP discovery shows a wrapped inline error and Retry without closing the dialog - Powered by
actionRegistry.ts(ACTION_METAmap)
3.12 Activity Dashboard (Cmd+Shift+A)
- Open from the status bar Agents ticker by clicking its label or counts, or focus it and press Enter or Space. The cycle badge advances tickers without opening the dashboard
- Real-time view of all active terminal sessions in a compact list
- The inline overlay stays close to the detached window’s compact width and fits narrow main windows
- An oversized saved detached Activity window opens at its compact 550×650 default after restart; smaller saved sizes remain available
- Each row shows: terminal name, repository display name badge (plus the branch for linked worktrees; folder name outside a repository), agent type, status, last activity time
- A PTY spawned by another agent (
agent action=spawn) shows the same monochrome robot-head icon in the dashboard and nested sidebar row. Its tooltip and accessible name readSpawned by <parent tab name>, resolved from either the parent’s PTY ID or live TUIC identity; an absent parent tab readsSpawned by external agent - Sub-rows (up to one shown per terminal, in priority order):
currentTask(gear icon) — current agent task from status-line parsing (e.g. “Reading files”). Suppressed for Claude Code (spinner verbs are decorative)agentIntent(crosshair icon) — LLM-declared intent viaintent:tokenlastPrompt(speech bubble icon) — last user prompt (>= 10 words). Shown only when noagentIntentis present
- Status color codes: green=working, yellow=waiting, red=rate-limited, gray=idle
- Ready input composers remain gray/idle when an agent leaves a long-lived background terminal running
- Rate limit indicators with countdown timers
- Click any row to switch to that terminal and close the dashboard. Sessions outside registered repositories open their own Global Workspace tabs; the previous repository tab keeps its session. Opening an existing session focuses its tab without creating another session.
- Relative timestamps auto-refresh (“2s ago”, “1m ago”)
3.13 Error Log Panel (Cmd+Shift+E)
- Centralized log of all errors, warnings, and info messages across the app
- Sources: App, Plugin, Git, Network, Terminal, GitHub, Dictation, Store, Config
- Level filter tabs: All, Error, Warn, Info, Debug — uses a severity threshold: selecting a level shows that level and everything more severe (e.g. Warn shows Warn + Error intermingled). Each tab has a tooltip describing what it includes
- Source filter dropdown to narrow by subsystem
- Text search across all log messages
- Each entry shows timestamp, level badge (color-coded), source tag, and message
- Copy individual entries or all visible entries to clipboard
- Clear button to flush the log
- Status bar badge shows unseen error/warning count (red, resets when panel opens)
- Global error capture: uncaught exceptions and unhandled promise rejections are automatically logged
- Ring buffer of 1000 entries (oldest dropped when full), Rust-backed — warn/error entries survive webview reloads via
push_log/get_logsTauri commands - Also accessible via Command Palette: “Error log”
3.14 Plan Detection
- Delivered by the preinstalled external Plan Tracker plugin
- Plans are detected via structured
plan-fileevents from the output parser and via aplans/directory watcher - Auto-open: restores the active plan from
.claude/active-plan.jsonon startup; new plans opened as background markdown tabs on first detection (no focus change) - Repo-scoped: only processes plans belonging to the active repository
3.15 Preview Tab
- Multi-format file previewer opened from clickable file paths, drag & drop, File Browser, or Command Palette
- File routing handled by
classifyFile()insrc/utils/filePreview.ts - Supported formats:
- HTML — rendered in sandboxed iframe with “Open in browser” button;
Cmd/Ctrl+Ffind-in-page uses the shared SearchBar pill (case/regex/whole-word toggles), which drives the iframe over a postMessage bridge and highlights matches in place - PDF — rendered via asset protocol in embedded iframe
- Images — PNG, JPG/JPEG, GIF, WebP, SVG, AVIF, ICO, BMP — rendered as
<img>via asset protocol - Video — MP4, WebM, OGG, MOV — rendered as
<video>with native controls - Audio — MP3, WAV, FLAC, AAC, M4A — rendered as
<audio>with native controls - Text / data — TXT, JSON, CSV, LOG, XML, YAML, TOML, INI, CFG, CONF — raw text in a
<pre>block
- HTML — rendered in sandboxed iframe with “Open in browser” button;
- Header bar shows shortened file path with Edit button (pencil icon — opens file in code editor) and Open externally button
- Reload: when a web or HTML-preview tab is active,
Cmd/Ctrl+R(actionreload-tab) reloads its content - File content auto-refreshes on repository revision bumps (git change detection)
- Uses Tauri’s
convertFileSrc()asset protocol for binary files,read_external_fileIPC for text content - The permissive
default-srcCSP allowsasset:andhttp://asset.localhostfor frames and media; no per-directive CSP overrides it
3.16 Focus Mode (Cmd+Alt+Enter)
- Hides sidebar, tab bar, and all side panels to maximize the active tab’s content area
- Toolbar and status bar remain visible for repo/branch state and mode exit
- Session-only (not persisted across restarts)
- Toggle again to restore the previous layout
3.17 Detachable Panels
- Any panel (AI Chat, Activity Dashboard, Git Panel, Plans and Stories) can be detached into a separate OS window
- Generic system via
open_panel_window/close_panel_windowRust commands with per-panel adapters - Two-tier sync: self-sufficient panels (Git Panel) call Rust directly; projection panels (Activity Dashboard) receive state snapshots via
emitToat 1 Hz - Shared
PanelWindowControlscomponent provides consistent detach/reattach/close buttons across all panels - Closing a detached window automatically restores the panel to the main window
- Tab bar “Detach to Window” context menu entry for per-tab detach (PTY session stays alive in Rust)
- Markdown document tabs use the same panel-window commands with a window per document; their file path is passed to the detached viewer, which reads from disk and routes linked files back to the main window.
- Generic lifecycle functions:
togglePanel(),detachPanel(),reattachPanel()replace per-panel callsites uiStore.detachedPanelsmap tracks all detached panels (replaces formeraiChatDetachedboolean)- Disk-backed panels hand over through their store, not through a live link: the detached window is opened with the params from
detachParams()and reads its own state on mount, and the main window re-reads it inonReattach()when the detached copy closes or reattaches
4. Toolbar
4.1 Sidebar Toggle
◧button (left side) — same asCmd+[- Hotkey hint visible during quick switcher
- Adjacent filter icon (shown while the sidebar is visible) toggles the “Active only” repo filter — see section 2.8
4.2 Branch Display
- Center: shows
repo / branchname - Click to open branch rename dialog
4.3 Plan File Button
- Appears when an AI agent emits a plan file path (e.g.,
PLAN.md) - Click:
.md/.mdxfiles open in Markdown panel; others open in IDE - Dismiss (×) button to hide without opening
4.4 Notification Bell
- Bell icon with count badge when notifications are available
- Click: opens popover listing all active notifications
- Empty state: shows “No notifications” when nothing is pending
- PR Updates section — types: Merged, Closed, Conflicts, CI Failed, CI Passed, Changes Requested, Ready
- Git section — background git operation results (push, pull, fetch) with success/failure status
- Worktrees section — worktree creation events (from MCP/agent)
- Messages section — agent/MCP notices and agent spawns go directly to the bell, with repository scope and an explicit Open terminal action when a session is known. Consecutive identical notices from the same origin within five seconds produce one item and one requested sound. User-action toasts are also retained when Keep toasts in the bell is enabled. Overflow from the two-card limit is retained even with that setting off; dedicated-domain toasts that explicitly opt out of Messages stay visible or queued.
- Automatic agent toast cards — MCP toast notices show a transient card only while their origin terminal tab is active. Settings → Notifications → Show cards from the active terminal defaults on and is saved per client; turning it off restores urgent-only cards. Urgent notices always show a card, and notices without an origin session remain bell-only unless urgent.
- Transient toast placement — top-right of the terminal area, offset left of a docked panel, with at most two visible cards. Same-kind notices in the same repository/session within five seconds show a ×N summary; every new member restarts its dismissal timer. Errors take a visible slot ahead of informational cards. Tall cards scroll within the upper region so their action buttons remain reachable without covering the bottom input. Clicking a card dismisses it; navigation uses its explicit action.
- Plugin activity sections — registered by plugins via activityStore
- Click PR notification: opens full PR detail popover for that branch
- Individual dismiss (×) per notification, section “Dismiss All”, auto-dismiss after 5min focused time
4.5 IDE Launcher
- The Terminals section opens a TUICommander shell tab in the active repository or worktree.
- Button with current IDE icon — click to open repo/file in IDE
- Dropdown: shows all detected installed IDEs, grouped by category
- Categories: Code Editors, JetBrains, Terminals, Git Tools, System
- JetBrains family: IntelliJ IDEA, PyCharm, WebStorm, GoLand, CLion, PhpStorm, RubyMine, Rider, DataGrip, RustRover, Android Studio, Fleet — launched via their CLI launcher (
idea,pycharm, …) with--line/--columngoto, falling back toopen -aon macOS when the Toolbox shell scripts aren’t on PATH - File-capable editors (including JetBrains IDEs) open the focused file (from editor or MD tab); others open the repo
- Custom launchers (#71): user-defined entries configured at Settings → General → Custom Launchers (name, executable on
PATHor absolute, args, per-OS platform, enable toggle), shown under a “Custom” section in the dropdown. Args support placeholder tokens resolved at launch:{path}/{file}(focused file, else repo),{repo},{fileDir}(focused file’s directory, else repo),{cwd}(focused terminal cwd, else repo),{home}, and{line}/{column}(editor cursor, default 1) - Run command button:
Cmd+Shift+R(run); edit & run has no default shortcut (actionedit-command)
5. Status Bar
5.1 Left Section
- Zoom indicator: current font size (shown when != default)
- Status info text (with pendulum ticker for overflow, pulse animation on new messages)
- CWD path: shortened with
~/, click to copy to clipboard (shows “Copied!” feedback)
5.2 Right-Aligned Status Group
- One group, in order: agent usage badge (or provider recovery), plugin tickers, Offline machines, PR/CI badges, panel controls. The cwd stays left; unused space is before the right group. Labels truncate and excess tickers rotate at narrow widths.
- Unified agent badge with priority cascade:
- Rate limit warning (highest): count + countdown timer when sessions are rate-limited
- Matching Claude or Codex Usage API ticker: live utilization from the active provider (click opens that provider’s dashboard)
- PTY usage limit: weekly/session percentage from terminal output detection
- Agent name (lowest): icon + name of detected agent
- Claude usage HTTP 429 returns an immediate rate-limited, retry HH:MM badge in host local time, with a shared per-profile two-to-five-minute cooldown and credential-free profile diagnostics. The request never sleeps through a provider retry hint or invokes a generating fallback for that throttle.
- The subscription quota registry registers Claude and Codex readers. Codex can use recorded rollout limits; active reads use non-generating usage endpoints. An expired Claude login is rejected before a request. The Claude usage dashboard no longer sends a generating fallback when the usage request fails.
- The status-bar quota display shares the registry store with the Claude and Codex dashboards. Switching between bound sessions selects cached quota, with no provider request or frontend quota interval. Mobile session details read cached Claude/Codex quota from the registry through the session usage endpoint. A Grok reader joins the registry: the Grok CLI’s ACP
_x.ai/billingrequest runs with the boundGROK_HOME(TUIC never reads the Grok token store), the current period gives the window, and a failed read waits for the registry cooldown; an expired login waits for a newgrok login. The Grok dashboard reads the same registry entry, so it no longer starts the CLI on every refresh. - The registry also registers an ego reader. It reads only ego’s
rate_limitscontract: passively from the usage report v6 that the session usage reader already runs, and actively fromego auth usage <provider> --jsonwith the boundEGO_HOME. No Claude, Codex or Grok CLI is needed. This requires an ego release withauth usage; an older ego reports the quota as unavailable. - Color coding: blue < 70%, yellow 70–95%, red pulsing >= 96%
- One placement rule (
usagePlacementinagentUsage.ts) decides where usage shows: the usage message of the active agent session goes to its badge, and the ticker area excludes the same messages. A result for another session (the previous tab during a switch) shows nowhere. An ego tab shows the usage of the subscription it is bound to, labelled by that provider; it never needs a Codex or Claude CLI login, and its badge opens no CLI dashboard (#3068-c03b) - One formatter (
formatAgentUsage) writes the badge for every provider, in a fixed order: the weekly window percent (only when the snapshot has one), then what is left before the monthly limit (a monthly window as percent left, a credit balance as an amount). Claude extra usage is a pay-as-you-go overage budget, not a limit, and is never shown. Each shown limit carries the time to its reset, for example7d: 78% -4d · 30d: 60% left -5h. The tooltip keeps the full reset date. No tool name is shown in the badge - The badge is written only when its text, label or priority changes: a same-value refresh or another account’s push causes no repaint, a switch between sessions with quota never empties it, and a stale or backoff state keeps the last good text
- The usage poll has no default provider: it stays silent until a Claude or Codex tab is focused, then follows that provider and stays on it while the active tab is a shell. A Codex-only install is therefore never shown a Claude reading (or a Claude “no token”) it did not ask for
- Codex windows are named by duration (
5h,7d) because the API does not label them, and only the account limit is rendered. A plan whose account limit reports a single window shows a single reading; per-model limits stay in the dashboard, where their model name is visible
- Shared ticker area: multi-source rotating messages from plugins with source labels, counter badge (1/3 ▸), click-to-cycle, right-click popover, and priority tiers (low/normal/urgent)
- Non-modal popups (ticker popover, status info balloon, GitHub panel, Smart Prompts dropdown) have no backdrop: wheel and clicks reach the sidebar and terminal while they are open, and an outside press dismisses them without being consumed (shared
useOutsideDismisshook) - Update badge: “Update vX.Y.Z” (click to download & install), progress percentage during download
5.3 GitHub Section (inside the right group)
- Branch badge: name + ahead/behind counts — click for branch popover
- PR badge: number + highest-priority state label and color — click for PR detail popover
- PR lifecycle filtering: CLOSED PRs hidden immediately; MERGED PRs hidden after 5 minutes of accumulated user activity
- CI badge: ring indicator — click for PR detail popover
5.3 Right Section — Panel Toggles
- Ideas (lightbulb icon) —
Cmd+Alt+N - File Browser (folder icon) —
Cmd+E - Markdown (MD icon) —
Cmd+Shift+M - Git (diff icon) —
Cmd+Shift+D(opens Git Panel) - Mobile session header: handset for two-way voice calls; composer dictation keeps its microphone.
- Mic button (when dictation enabled): hold to record, release to transcribe
6. AI Agent Support
-
Env-prefixed Claude launches — named Unix launches and resumes receive status hooks and init instructions through the same PATH shim, including
env CLAUDE_CONFIG_DIR=… claude. Explicit settings and administrative commands retain precedence. -
Independent ego advisors — the Unix shim isolates headless and redirected advisors from implicit parent UI instructions, attachments and MCP identity. Direct terminals and explicit one-launch hosted peers retain their context.
-
Pi managed status extension — opt-in native lifecycle status with paired extension-modal waits, safe marked-file installation and session-shutdown cleanup. Background tools cannot clear an open modal (#2629-9537).
-
Grok native hooks settle cancelled/failed turns and retract permission waits on matching tool outcomes, replacement prompts and turn/session end (#2624-848f).
Launch instruction editing
Settings → Agents shows read-only default and inherited launch instruction previews. Customize creates an editable global or per-agent copy. Use global restores an agent’s inheritance; Reset to default removes the global copy. Agent previews use backend resolution, marker toggles and the current TUIC version. Empty custom text disables injection. Custom text saves on blur and warns about missing markers.
Launch instruction inspector
The terminal context menu offers Inspect Launch Instructions…. Collapsible sections show the prospectively captured final launch brief, explicit system instruction arguments/file snapshots and served MCP initialize responses, with recorded source and original UTF-8 byte count. Redacted text is bounded to 32 KiB per section, 64 KiB per receipt and 16 captured sections. Queued briefs are labeled until submission succeeds. Historical launches, shell-launched agents and files the agent reads independently show Not observable by TUIC. Receipts belong to live PTY/MCP metadata, survive frontend reloads and end with the backend/session lifetime; workflow preview/hash receipts remain unchanged.
6.1 Supported Agents
| Agent | Binary | Resume Command |
|---|---|---|
| Claude Code | claude | claude --resume <uuid> (session-aware) / claude --continue (fallback) |
| Gemini CLI | gemini | gemini --resume <uuid> (session-aware) / gemini --resume (fallback) |
| OpenCode | opencode | opencode -c |
| Codex CLI | codex | codex resume <uuid> (session-aware) / codex resume --last (fallback) |
| Amp | amp | amp threads continue |
| Cursor Agent | cursor-agent | cursor-agent resume |
| Goose | goose | goose session --resume --name <uuid> (session-aware) / goose session --resume (fallback) |
| Droid (Factory) | droid | — |
| pi | pi | pi --continue |
| Git (background) | git | — |
The per-agent Prevent alternate screen setting defaults on. New TUIC shells export Claude’s environment control and, after a supported-CLI probe, the Codex/Grok --no-alt-screen and OpenCode --mini choices for manually typed commands. A timed-out help probe is cached for that binary version and its child process tree is stopped, so later launches do not repeat the delay. One Rust policy also covers menu, IPC/HTTP/MCP, worktree, and resume launches. A CLI without a verified control receives no invented option; an unexpected alternate-screen entry emits one warning per session.
6.1.1 Session-Aware Resume
When an agent is detected running in a terminal, TUICommander automatically discovers its session ID from the filesystem and stores it per-terminal (agentSessionId). On restore, this enables session-specific resume instead of generic fallback commands.
- Claude Code — Sessions stored as
~/.claude/projects/<slug>/<uuid>.jsonl; UUID from filename. Windows drive colons become dashes in the project slug (C:\Users\foo\bar→C--Users-foo-bar). - Gemini CLI — Sessions stored in
~/.gemini/tmp/<project>/chats/session-*.jsonl(legacy.jsonalso supported). Discovery and restore match the recordedprojectHashto the session project and readsessionIdfrom metadata. Discovery selects the newest unclaimed recent session; multiple tabs in the same project remain heuristic. - Codex CLI — Sessions stored in
~/.codex/sessions/YYYY/MM/DD/rollout-*-<UUID>.jsonl; UUID from filename. Codex does not partition by project, so candidates are filtered on the working directory recorded in the rollout’s firstsession_metarecord — otherwise a terminal in one project would bind to another project’s session. A rollout whosecwdcan’t be read is rejected rather than accepted - Goose turn completion — A reply followed by the ready composer returns the tab to idle and allows the next submission, without the five-minute stale recovery (#1812-022d).
- Goose — Sessions stored in SQLite (
~/Library/Application Support/Block/goose/sessions/sessions.db); shell wrapper injects--name $TUIC_SESSIONfor deterministic binding on normalsession/runlaunches, preserving explicit names, paths, resume and stateless arguments; resume by name
Discovery runs once per terminal on null→agent transition. Multiple concurrent agents are handled via a claimed_ids deduplication list. On agent exit, the stored session ID is cleared to allow re-discovery on next launch.
Every agent rejects candidates older than 5 minutes (SESSION_MAX_AGE), so a terminal opened now never resumes a session abandoned earlier in the day.
6.1.2 TUIC_SESSION Environment Variable
Every terminal tab has a stable UUID (tuicSession) injected as the TUIC_SESSION environment variable in the PTY shell. This UUID persists across app restarts and enables:
- Automatic session binding: Shell integration injects wrapper functions that transparently bind agent sessions to the current tab (zsh, bash, fish):
- Claude Code:
claude()adds--session-id $TUIC_SESSION; bypassed when--session-id,--resume, or--continueare explicit - Goose:
goose()adds--name $TUIC_SESSIONtosessionandrunsubcommands; bypassed when--name,-n,--resume, or-rare explicit - Session conflict handling: When an agent reports a session conflict (in-use or not-found), TUICommander creates a
no-session-inject.$TUIC_SESSIONflag file in the config directory. Shell wrappers check for this file and skip--session-idinjection when it exists — avoiding PTY writes that could corrupt TUI output
- Claude Code:
- Automatic resume: On restore, TUICommander verifies if the session file exists on disk (
verify_agent_session) before using--resume $TUIC_SESSION - UI spawn coherence: When spawning agents via the context menu,
TUIC_SESSIONis used as--session-idautomatically - Custom scripts:
$TUIC_SESSIONis available as a stable key for any tab-specific state
6.2 Agent Detection
- Native ego empty-composer detection can recover an unconfirmed input after a fresh stable repaint, without replaying the earlier payload. Retained text and dialogs remain blocked; later queued BG wakes use the normal idle queue flush.
- Hand-launched agents are classified and recorded by the backend on desktop and headless hosts; HTTP foreground queries share the desktop detection logic. Plain shells remain ineligible for agent submit and mail wake.
- Protocol completion survives terminal redraws and decorative idle animation; new input and recognized semantic working signals can reopen activity.
- Auto-detection from terminal output patterns
- Multi-agent status line detection via regex patterns anchored to line start: Claude Code (
*/✢/·+ task text +.../…),[Running] Taskformat, Codex CLI (•/◦bullet spinner with time suffix), Goose (<message>... (Ctrl+C to interrupt)), Copilot CLI (∴/●/○indicators), Gemini CLI (braille dots⠋⠙⠹...) - Movement-based activity: BUSY is normally latched/kept by text changing above the input area, user submission, and OSC lifecycle markers, which outrank silence. Ready prompts require a stable 1.5s observation before idle.
- A Claude mail wake submitted after a hook idle cannot leave the session Working indefinitely when the detailed transcript hides the composer: without output or a later busy hook, the indicator returns to idle after five minutes.
- Codex and Claude also use narrow semantic active markers because their current TUIs can freeze or retain an empty composer during real work. Codex scopes
Working … esc to interruptto the lowest›or»composer. Claude requires a spinner-prefixed phase with an ellipsis and parenthesized progress; completed summaries remain idle-safe, and live work can supersede a premature blocking Stop-hook completion. - Ctrl-C/Escape are interrupt intent only; status changes after the agent confirms interruption, returns to a stable prompt, emits Stop, or exits.
- Status lines rejected when they appear in diff output, code listings, or block comments
- Brand SVG logos for each agent (fallback to capital letter)
- Agent badge in status bar showing active agent
- Binary detection: Rust probes well-known directories via
resolve_cli()for reliable PATH resolution in desktop-launched apps - Foreground process detection:
tcgetpgrp()on the PTY master fd, then macOSproc_pidpath()or Linux/proc/<pid>/exewith a/proc/<pid>/commfallback to get the binary name. Identities are revoked when a shell returns to the foreground after agent observation; run-config presets remain armed during startup, and transient non-shell helpers preserve identity. Linux updater-replaced executables retain classification after removing the proc(deleted)suffix. Handles versioned binary paths (e.g. Claude Code installs as~/.local/share/claude/versions/2.1.87) by recognising the exactclaude/versions/<numeric-version>layout when the basename is not a known agent; arbitrary agent-named ancestor directories do not classify an executable; Droid is classified explicitly so it receives the agent idle threshold.
6.3 Rate Limit Detection
- Provider-specific regex patterns detect rate limit messages
- Status bar warning with countdown timer
- Per-session tracking: rate-limit events are only accepted for sessions where agent activity has been detected (prevents false warnings in plain shell sessions)
- Auto-expire: rate limits are cleared automatically after
retry_after_ms(or 120s default) without requiring agent output
6.4 Question Detection
-
OpenCode 2.2.3 private
--standalonelaunches use the native v2 plugin interface. Native form and permission waits settle by request/session ownership on answer, cancel, rejection or execution/session shutdown, without requiring another tool. The shared background service remains uninstrumented. -
ego question titles exclude preceding diagnostics and working rows. Default-mode command approvals expose native keys and preserve the refusal explanation wait.
-
Ego terminal project-trust prompts (
? [y/N]) expose mobile Yes/No controls and an Input state, including hard-wrapped project paths. -
Grok native Ask and enforced command-approval radio forms export their options, selected state and immediate numeric-answer semantics; the Ask free-text action remains waiting until submission.
-
Codex 0.162.1 native panels export their question and options. Mobile opens queued questions with Shift+Left; numeric options submit immediately. CLI-enforced command approvals also export their title and options past command metadata.
-
An open Ink selection dialog restores a missing question badge with native hooks enabled, including after a later busy hook; repeated paints do not duplicate the notification.
-
Codex
/planquestions export narrow-layout choices with separate wrapped hints and retain Input through delayed idle hooks until answered. Native counter and footer anchors remain required. -
Recognizes interactive prompts (yes/no, multiple choice, numbered options)
-
Tab dot turns orange (pulsing) when awaiting input; sidebar branch icon shows
?in orange -
Prompt overlay: keyboard navigation (↑/↓, Enter, number keys 1-9, Escape)
-
Two detection strategies run in priority order:
- Screen-based (Strategy 1): reads the live terminal screen, finds the last chat line above the prompt box (delimited by separator lines), checks if it ends with
?. Works with Claude Code, Codex (›prompt), and Gemini (>prompt) layouts - Silence-based (Strategy 2, fallback): if terminal output stops for 10s after a line ending with
?, the session is treated as awaiting input
- Screen-based (Strategy 1): reads the live terminal screen, finds the last chat line above the prompt box (delimited by separator lines), checks if it ends with
-
Stale candidate clearing: candidates that fail screen verification are purged so the same question can re-fire in a future agent cycle
-
Echo suppression: user-typed input echoed by PTY is ignored for 500ms to prevent false question detection
-
extract_question_line()scans all changed rows (not just the last) for question text, applied in both normal and headless reader threads -
Wrapped
suggest: [ … ]items remain follow-up actions even when an item contains?; they cannot set the question state. -
Question state auto-clears when a
status-lineevent fires (agent is actively working, so it’s no longer awaiting input) -
Canceling a Codex approval with Esc clears its waiting badge when the idle composer returns, while a later question remains active.
6.5 Usage Limit Detection
- Claude Code weekly and session usage percentage (from PTY output patterns)
- Color-coded badge in status bar (blue < 70%, yellow 70–95%, red pulsing >= 96%)
- Integrated into unified agent badge (see section 5.1)
6.6 Provider Usage Dashboards
- Native SolidJS component (not a plugin panel — renders as a first-class tab)
- The active Claude, Codex, or Grok badge opens its matching dashboard;
Cmd+Shift+Aopens Claude Usage - Rate Limits section: Live utilization bars from Anthropic OAuth usage API
- Follows the focused Claude terminal’s
CLAUDE_CONFIG_DIRcredential profile; an unresolved profile shows unknown rather than another account’s quota - 5-Hour, 7-Day, 7-Day Opus, 7-Day Sonnet, 7-Day Cowork buckets
- Color-coded bars: green < 70%, yellow 70-89%, red >= 90%
- Reset countdown per bucket
- Follows the focused Claude terminal’s
- Usage Over Time chart: SVG line chart of token usage over 7 days
- Input tokens (blue) and output tokens (red) stacked area
- Interactive hover crosshair with tooltip
- Insights: Session count, message totals, input/output tokens, cache stats, tokens-per-hour metric (based on real active hours from session timestamps)
- Activity heatmap: 52-week GitHub-style contribution grid
- Tooltip shows date, message count, and top 3 projects
- Model Usage table: Per-model breakdown (messages, input, output, cache)
- Projects breakdown: Per-project token usage with click to filter
- Scope selector: Filter all analytics by project slug
- Auto-refresh: API data polled every 5 minutes
- Rust data layer: Incremental JSONL parsing of
~/.claude/projects/*/transcripts- File-size-based cache (only new bytes parsed on each scan)
- Cache persisted to disk as JSON for fast restarts
- Codex dashboard: account rate-limit windows, per-model limits, reset times, plan type, credit balance, and token history from the official local Codex App Server. The Codex CLI owns OAuth and refresh; TUIC does not read its token.
- Grok dashboard: billing-period usage, subscription tier, on-demand spend,
cap, and prepaid balance from Grok Build’s official
_x.ai/billingACP extension, read through the quota registry. The short-lived connection is telemetry-only; normal Grok tabs remain PTY sessions. - Gemini: terminal rate-limit detection remains available, but there is no
account dashboard because Gemini CLI has no stable machine-readable account
quota interface. Session-local
/statsis not treated as account headroom.
Coordinator mail address
agent action=send to=orchestratorreaches the registered coordinator in the caller parent chain, or the unique role in its registered repository path, without peer discovery. Missing or ambiguous roles fail explicitly.
6.7 Intent Event Tracking
- Agents declare work phases via
intent: text (Title)tokens at the start of a row. The canvas tints intent rows and their soft-wrapped or indented hard-wrapped tails, preserving row coordinates. Blank rows and new output, answer, prompt or marker blocks end an indented tail. The token is also read when it follows the ack sentence on one row, and when the agent’s own wrapping split it across many rows; terminal width distinguishes wrapped text from adjacent indented prose, and input-box chrome is excluded. A long intent keeps its full tab-title event while the Progress journal stores a redacted, capped copy - MCP instructions request an intent on its own line, at the start of every task and on each material phase change; the terminal Context bar shows it separately from the orchestrator assignment and user prompt
- Ego uses its native status/composer pair to exclude input chrome. A second soft-wrapped intent remains visible to the parser while ego replaces that composer; historical submitted prompts do not hide it. Intent tint and state capture share one anchor grammar across agent types.
- Session snapshots restore captured intent and the last substantial prompt after reconnect, even while the agent remains idle; live state updates use the same reconciliation path.
- Intent titles may replace spawn-assigned tab labels; only an explicit user rename locks the tab title, including after reconnect
- Colorization is agent-gated (only applied in sessions with a detected agent) to prevent false positives
- Structural tokens stripped from log lines served to PWA/REST consumers via
LogLine::strip_structural_tokens() - Structured
Intentevents emitted for LLM-declared work phase tracking - Centralized debounced busy signal with completion notifications for accurate idle/active status
- One Notifications control mutes sounds and OS notices for agent-spawned sessions, using backend parentage; Activity, bell entries and urgent cards remain. Parent/user sessions are unaffected, and unparented HTTP/MCP sessions retain the completion-chime-only mute. HTTP/MCP origin survives reconnects; BUSY→IDLE and exit share one notification per busy cycle
6.8 API Error Detection
- Detects API errors (server errors, auth failures) from agent output and provider-level JSON error responses
- Claude friendly auth/transport detection excludes tool receipts and their indented diagnostic continuations
- Covers Claude Code, Codex CLI, Gemini CLI, Copilot, and raw API error JSON from providers (OpenAI, Anthropic, Google, OpenRouter, MiniMax)
- Retains final failures in the red Error state through idle and unsuccessful auto-retry; supports Claude connection-loss prose, Codex native final-error rows and ego native provider-failure notifications. Native recovery countdowns do not set Error.
- Triggers error notification sound and logs to the Error Log Panel
6.9 Agent Configuration (Settings > Agents)
-
ego permissions: Select
plan,default,edits,auto, oryoloand filesystem sandboxroorworkspace. Each choice can remain unset to use ego configuration. One backend translator applies these overrides to terminal launches, MCP spawns, and resumes, replacing matching raw flags. AI Chat over ACP uses separate settings. -
Claude and Codex receive process-scoped native status signals at launch by default (
--settings/-c notify), independently switchable per agent. Existing user overrides take precedence and no global settings are changed. -
Managed workspace trust: Claude and Codex agent-to-agent spawns accept their new working directory by default, controlled by Accept workspace trust for managed spawns for each agent. Codex receives a launch-only project trust override, including through custom launchers that forward arguments; Claude’s startup picker is answered from its own PTY after the exact question and default No, exit selection appear. Normal user-opened terminals retain each CLI’s trust behavior. No agent config file is rewritten.
-
Agent list: All supported agents with availability status and version detection
-
Run configurations: Named command templates per agent (binary, args, optional model, env vars). MCP spawn can override the model and environment per child.
-
Default config: One run config per agent marked as default for quick launching. Codex defaults carry the approvals/sandbox bypass explicitly in editable args, with a warning icon; removing the argument persists.
-
MCP bridge install: One-click install/remove of
tui-mcp-bridgeinto agent’s native MCP config file -
Supported MCP agents: Claude, Cursor, Windsurf, VS Code, Zed, Amp, Gemini, Codex, Grok, OpenCode, Droid, Goose, pi (through pi-mcp-adapter)
-
Shared settings files are opt-in: Zed, Amp and Gemini store MCP servers inside their general
settings.json, so those three are never written automatically — the panel says so and the Install button does it on request -
Remove all MCP integrations: Lists every client holding a bridge entry and clears them in one action, so uninstalling TUICommander does not leave a dangling
tuic-bridgeserver behind -
Edit agent config: Opens agent’s own configuration file in the user’s preferred IDE
-
Context menu integration: Right-click terminal > Agents submenu with per-agent run configurations; selected environment variables apply only to the launched agent, including from the sidebar menu
-
Busy detection: Agents submenu disabled when a process is already running in the active terminal
-
Environment Flags — Per-agent environment variables injected into every new terminal session. Configure in Settings > Agents > expand an agent > Environment Flags. Useful for setting feature flags like
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1without manual export.
6.10 Agent Teams
- Purpose: Enables Claude Code’s Agent Teams feature to use TUIC tabs instead of tmux panes
- Approach: Environment variable
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1injected into PTY sessions, which unlocks Claude Code’s TeamCreate/TaskCreate/SendMessage tools. Agent spawning uses direct MCP tool calls (agent spawn) instead of the deprecated it2 shim - Session lifecycle events: MCP-spawned sessions emit
session-createdandsession-closedevents so they automatically appear as tabs and clean up on exit - Settings toggle: Settings > Agents > Agent Teams
- Suggest follow-ups: Agents can propose follow-up actions via
suggest: [ A | B | C ]tokens, displayed as floating chip bar - Deprecated: The it2 shim approach (iTerm2 CLI emulation) is commented out — superseded by direct MCP tool spawning
6.11 Suggest Follow-up Actions
- Protocol: Agents emit
suggest: [ action1 | action2 | action3 ]at column 0 after completing a task. The whole token sits on one row, bounded by[ … ]with no nested brackets — so stray pipes/brackets in surrounding output (mermaid, markdown tables, prose) can never be mis-parsed as items - Answer marker: The MCP initialize instructions (Required Output Markers block) also teach every agent to prefix each sentence that directly answers the user’s question with
💬at the start of the row; the answers-only view (Cmd+Alt+R) parses it. Always sent, independent of the intent/suggest settings - Token concealment: Suggest tokens are concealed in terminal output via line erasure or space replacement — the raw token never appears on screen. Concealment is agent-gated
- Desktop: Floating chip bar (SuggestOverlay) above terminal with larger buttons and keyboard shortcut badges (
1–9to select,Escto dismiss). Auto-dismiss after 30s, on typing, or on Esc - Mobile: Horizontal scrollable pill buttons above CommandInput in SessionDetailScreen
- Action: Clicking a chip (or pressing its number key) sends the text to the PTY via
write_pty - Settings: Configurable via Settings > Agents > Show suggested follow-up actions
6.12 Slash Menu Detection
- When the user types
/in a terminal,slash_modeactivates and the output parser scans the bottom screen rows for slash command menus - Filtered menus with one result replace the previous list. When completion closes or has no matches, the backend retracts the list, including ego exact-command completion.
- Detection: 2+ consecutive rows starting with
/commandpatterns, with❯highlight for the selected item - Produces
ParsedEvent::SlashMenu { items }— used by mobile PWA to render a native bottom-sheet overlay slash_modecleared on user-input events and status-line events
6.13 Inter-Agent Messaging
- Claude background output: managed MCP peers default to
CLAUDE_CODE_TMPDIR=$HOME/Gits/.tmp/claude/, created before spawn; explicit inherited, run-config or caller values take precedence. - Agent-to-agent coordination when multiple agents are spawned in parallel, carried by the
agentMCP tool — there is no separatemessagingtool - Identity: Each agent uses its
$TUIC_SESSIONenv var (stable tab UUID) as its messaging identity. A headerless external caller mayregisterwithouttuic_sessionto be issued an MCP-scoped UUID, or supply a stable UUID to reclaim an existing identity - Actions:
register(announce presence, or rename/re-project an auto-bound peer),list_peers(discover other agents, optionalpathfilter),send(message a peer byto= tuic_session),inbox(poll for messages),wait(block until new mail) - Dual delivery: Real-time push via MCP
notifications/claude/channelover SSE into already working Claude Code turns; idle/completed managed agents and managed non-Claude agents use submitted PTY delivery even when their MCP bridge has an SSE stream; polling fallback viainboxis always available - Channel support: TUICommander declares
experimental.claude/channelcapability; spawned Claude Code agents automatically get--dangerously-load-development-channels server:tuicommander - Lifecycle: Peer registrations cleaned up on MCP session delete and TTL reap;
PeerRegistered/PeerUnregisteredevents broadcast via event bus for frontend visibility - Inbound webhook:
POST /agent/webhook/{to}files the raw body (max 64 KB) as mail from senderwebhookin the inbox of the peer that{to}names (id, name, PTY id or alias); an unknown recipient is refused and nothing is filed. Managed agents learn from their launch instructions that a script can call them back this way when it ends - Limits: 64 KB max message size, 100 messages per inbox (lifecycle-first eviction; peer mail back-pressure), optional path filtering for
list_peers - TUICommander acts as the messaging hub — no external daemon needed
- Durable task handles:
agent action=spawnreturnstask_idandpoll_interval_msalongsidesession_id. TheagentMCP tool polls that handle without blocking —agent action=task_getreturns{task_id, status, status_message?, result?, error_detail?, poll_interval_ms}where status isworking|input_required|completed|failed|cancelled(the last three final), andagent action=task_cancelmarks the task cancelled without killing the agent (session action=killdoes that). Use this instead ofagent action=wait/session action=waitwhen work runs past their 300 s cap or when the client may reconnect: the outcome is recorded by the session exit path whether or not anyone was listening. Tasks live for the TUICommander process only — they are deliberately not persisted, because a restart tears down every PTY
6.14 AI Chat Panel (Cmd+Alt+A) — ego over ACP
- When no ego executable is configured, AI Chat offers the detected path with Use this. Only confirmation saves it; Configure ego remains available.
AI Chat keeps the active conversation usable while saved-conversation discovery is pending or fails. Background saved-tab load failures do not replace the selected conversation’s state. New chat opens a fresh session without first replaying the saved conversation, so an old greeting title or refused replay cannot block it.
- Delete conversations — the capability-gated Conversations list confirms the named conversation, deletes its ego history and closes its tab; refusals keep the conversation (#1917).
When new content arrives while you read earlier messages, New text below appears above the composer. Select it to return to the bottom and resume following. Scrolling to the bottom also clears it; a search jump alone does not show it. Terminal Chat shares this behavior. Disable New text indicator in Settings → Appearance → Chat, or mobile Settings. The preference stays on the current client.
Start conversations with New chat tab in the tab bar. The session control bar contains no duplicate + action.
The conversation lives in ego, not in TUICommander. There is no LLM client
here: no provider, no API key, no tool loop, no sandbox. TUICommander launches
one configured ego binary and speaks ACP to it, per
plans/ego-integration/archive/plan.md section 1.
- One chat across repositories, never bound to a terminal. A turn ego runs outlives any tab and may touch files no tab is showing. Switching repository keeps the same conversations; the viewed repository is sent with each prompt. The conversation picker lists ego’s durable sessions by title and latest activity. Desktop and mobile clients connecting to one peer share one ego process, even when both connect at the same time.
- Docked on the right, resizable by its left edge (session-scoped width, not
persisted); detaches into its own window, with
DetachedPlaceholderin the main window meanwhile - The conversation view loads on first opening, including in a detached window; the desktop terminal is ready before this optional view loads
- Multiple chat tabs keep separate ACP sessions, transcripts and composer drafts
within one panel. Open tabs and the selected tab survive hide/show and detach;
closing a tab leaves its durable ego conversation available in the picker.
Selecting a saved tab attaches or replays it without sending a message, with
connecting status or a failure reason and Retry. Reopening the panel also
attaches the selected saved tab and automatically replaces a missing conversation;
other load failures remain visible. Provider retries show one live
countdown from the received delay, with cause and attempt number; zero reads
“retrying now”. Recovery or final failure clears the retry status.
Tabs use conversation titles
or prompts; model/mode controls show pending values until options arrive.
The focused panel uses
Cmd/Ctrl+Tfor a new tab (Cmd/Ctrl+Alt+Tin browser mode) andCmd/Ctrl+Wto close one (Cmd/Ctrl+Alt+Win browser mode) - Transcript text and tool output are selectable. User and assistant messages
and tool outputs have copy actions using the terminal clipboard adapter.
Message Copy includes fenced code without a separate code-block button. Web links open externally; after backend resolution, file paths use
the terminal file opener and directory paths open the file browser, including
from a detached chat. Transcript focus gives
Cmd/Ctrl+A(select this transcript),Cmd/Ctrl+F(find), andCmd/Ctrl+K(clear this tab’s view) - Streamed answers, reasoning folded into a disclosure, one collapsed tool activity line per turn with calls and outputs expandable, and the agent’s plan replaced whole each time it changes. The view follows new output while the reader is at the bottom; collapsed tool rows keep full commands in details
- The connection acknowledgement is hidden;
intent:is shown as turn status; bracketedsuggest:items on their own line or at the end of an answer become buttons that send the selected reply. A sent reply appears once even when ego echoes it in chunks. Message Copy appears on hover or keyboard focus - Session title updates rename the panel header and picker entry. The footer shows context-window use and the cumulative cost when ego reports it
- Untitled sessions show a readable prompt or activity-time label in the picker; failed and empty turns show a message in the conversation
- Image paste stages a removable preview in the composer. Sending forwards base64 image content blocks only when the agent advertises image prompts; supported PNG, JPEG, GIF and WebP files are capped at 10 MiB per turn
- The composer grows up to a bounded height. Pastes over 200 words are shown as numbered markers until Send restores the full text
Ctrl+Sin the composer parks text and image previews with a visible chip; pressing it again restores or swaps drafts. Sending an intervening prompt restores the parked draft. Mobile AI Chat uses a labelled archive icon above the input for this action.- Mobile AI Chat shares session composer styles, auto-grow, Enter/send behaviour, right-side attachment and round Send icons. Suggestions and long text wrap; wide tables scroll inside the transcript block.
- Mobile AI Chat transcript links open resolved files or directories in the Files screen, using the chat workspace as the path base.
- Permission requests are answered with one of the option ids ego published.
Small single-choice elicitations use direct answer buttons; other elicitations
are drawn as a form, and only in
formmode — the client declines every other mode before it reaches a person - While AI Chat is hidden, its status-bar toggle counts pending permissions and forms. Each new question produces one desktop notification, cleared when the question settles
- Session settings come from the options the session publishes through
set_config_option. The one-row control bar summarizes the model’s short name and mode; Pause, Resume, Compact and New use named icon buttons. A dialog labels every select option and shows its description and current choice. Errors from rejected changes appear in the dialog. TUICommander holds no model list - Pause, resume and compact are drawn only when ego advertised each extension
- A stream gap is a state, not a skip: the panel says it missed part of the
conversation and offers the one recovery there is — a fresh process replaying
the history through
session/load - Terminal right-click keeps Explain with AI and Fix this error; both write a question about the selection into the composer and open the panel
- Gated by
experimental_features_enabled(settingsStore.isAiChatEnabled, off by default) plus a configuredego_executable. While that path is empty the panel explains why it is inactive and offers Configure ego to open the ego controls in Settings → General. Provider login and the default model remain in Settings → AI Chat. Saving the executable enables chat without an app restart (detached windows refresh their settings when focused again) - Full user guide:
docs/user-guide/ai-chat.md
What went with the embedded engine (#784-0aec) and did not come back here:
| Removed | Returns as |
|---|---|
| Provider registry, models, slots, API keys in the keyring, Ollama detection | 786-4a6d — configured in ego; TUICommander stores no API key |
The ReAct agent loop, its 31 tools, SafetyChecker, FileSandbox, unsafe mode, agent model overrides, cross-session memory injection | nothing. ego runs its own loop and drives terminals from outside, through the session MCP tool family |
Terminal watchers and the cron scheduler (ai-watchers.json, ai-cron.json) | not scheduled |
| AI diff triage | nothing. #795-320b restored the review but not the triage: one unattended turn gets the whole diff, so there is no per-file classification pass to run |
| PR AI review, changelog generation, improvement scan | 795-320b — one unattended ego turn each; see 8.3 and 8.10 |
Smart Prompts api execution mode | 787-ee50 — one unattended ego turn; see 10.5 |
6.15 TUI Application Detection
- Alternate-screen tracking (
ESC[?1049h/l) and primary-screen mouse reporting classify shell versus fullscreen TUI activity. TerminalMode::FullscreenTui { app_hint, depth }remains part of session state and protects agent-session conflict handling.- The write-only command knowledge store and its background disk flush were removed in #2115-1333. Existing history files are not deleted or migrated.
- Code:
src-tauri/src/ai_agent/tui_detect.rs.
6.16 ChoicePrompt Detection
- Claude AskUserQuestion is parsed from its full-bleed Ink footer and numbered options, including rows with descriptions and imperative titles without a question mark (
Pick a colour). Itsselection_mode: navigate-entertells mobile to move the highlight with arrows and submit with Enter; the mobile screen retains the whole open dialog - New
ParsedEvent::ChoicePrompt { title, options, dismiss_key, amend_key }recognises Claude-Code-style numbered confirmation menus (footer matchesEsc to cancel · Tab to amend) - Options parsed by regex with optional cursor marker (
❯,›,>). Title heuristics require?or a verb prefix (proceed,confirm,do you want, …) to avoid matching Markdown numbered lists. Minimum two options - Destructive labels (
no,cancel,reject,abort,deny,don't) flagged for styling - Piped into
SessionState.choice_prompt; dispatched to plugins viapluginRegistry.dispatchStructuredEvent("choice-prompt", …); rendered as PWA overlay - Single-key replies routed through
sendPtyKey()(src/utils/sendCommand.ts) — nevertext + \r. Desktop listener plays a warning sound when the prompt arrives on an inactive tab
7. Git Integration
7.1 Repository Info
- Branch name, remote URL, ahead/behind counts
- Read directly from
.git/files (no subprocess for basic info) - Repo watcher: monitors
.git/index,.git/refs/,.git/HEAD,.git/MERGE_HEADfor changes
7.2 Worktrees
- MCP creation receipts and worktree inventory include the durable creator’s TUIC session identity, including ACP peers without a terminal. Legacy and unbound checkouts report
null; recycled allocations receive the new creator. - Shared story, plan, and idea stores link only when the main checkout already ignores them. Directory-only ignores also cover the new symlinks; unignored stores are skipped with a warning instead of making the worktree dirty or hiding main-checkout files.
- Auto-creation on branch select (non-main branches)
- Configurable storage strategies: sibling (
__wt), app directory, inside-repo (.worktrees/), or Claude Code default (.claude/worktrees/) - Sci-fi themed auto-generated names
- Three creation flows: dialog (with base ref dropdown), instant (auto-name), right-click branch (quick-clone with hybrid
{branch}--{random}name) - Base ref selection: choose which branch to start from when creating new worktrees
- Orphan cleanup ignores detached checkouts under OS/environment temporary roots and
~/Gits/.tmp, including symlink aliases and missing checkout registrations. Detached sidebar rows remain visible; stale removal requests are refused. - Per-repo settings: storage strategy, prompt on create, delete branch on remove, auto-archive, orphan cleanup (safe orphan countdown defaults to 10 seconds), PR merge strategy, after-merge behavior, PR visibility filters (hide drafts/conflicting/CI-failing)
- Setup script: runs once after creation (e.g.,
npm install) - Archive script: runs before an existing worktree is archived or deleted; non-zero exit blocks the operation. Cleanup of an already missing checkout skips it
- Removal previews distinguish untouched branch history from merged commits, name live sessions, and count uncommitted and untracked files. Automatic PR-close cleanup and merged-worktree archiving skip live or dirty worktrees.
- Merge & Archive: right-click → merge branch into main, then archive or delete based on setting. Conflict cleanup reports
(aborted)only whengit merge --abortsucceeds; if abort fails, the error includes the manual recovery command. - Archived worktrees remain usable Git checkouts under
__archived, including HEAD, reflogs, and initialized submodule refs; locked checkouts are left in place and archived paths are hidden from the active workspace list. - External worktree detection: monitors
.git/worktrees/for changes from CLI or other tools - Remove via sidebar
×button or context menu (with confirmation) - Warm linked worktrees: every workspace shares refs and objects with the parent. After
git worktree add, ignored directories such asnode_modules,target, and.venvare copied with clonefile/reflink when supported;.tmpand.mdkbdirectories, tracked paths, ignored files, nested repositories, and the destination ancestor are never copied- Capability is measured against the actual source/destination pair. Unsupported filesystems produce one warning and a valid cold worktree
- Read-only copied files and directories gain owner write permission in the new worktree only; symlinks are not followed
- Parent tracked and untracked changes are not carried into the new checkout
- Shared lifecycle state: sidebar, Worktree Manager, and removal confirmation render one workspace-id keyed backend verdict (
Dirty,Merged, orUnknown); sidebar Dirty/Unknown badges explain their meaning on hover or keyboard focus, and unknown blocks removal. Branch-name status diagnostics appear once; main-checkout tooltips do not describe removal - Desktop IPC, HTTP, and MCP creation payloads report
warm_artifacts.status(pendinguntil the background copy finishes) and state the linked-worktree isolation semantics; workspace path listing reports the current status. A cancelled create marks warming failed; removal and archive cancel queued copies - The Archive workspace dialog shows backend-owned file, commit and open-session checks with counts. Failed or unknown checks disable Delete; Archive keeps dirty and unmerged work.
- The Archive workspace dialog offers a red Delete alternative for a clean, integrated checkout without live sessions. Delete removes the checkout and local branch through the existing safety checks instead of recycling it; Archive remains the default.
- Removal without force keeps dirty worktrees and submodules, refuses an in-progress Git operation, and keeps a branch that changed after the removal check. Submodule commits, stash history, and reflog-only commits receive durable refs in the initialized main-checkout module repository. An uninitialized, misdirected, or deinitialized module with retained Git history stops removal, including nested modules with names different from their paths. A registered checkout whose directory is missing has an explicit lifecycle verdict and needs confirmed force to prune its registration; cleanup skips its inaccessible archive script. Dirty-file force still proves branch safety and never overrides a lock by itself
- Automatic archive keeps fresh empty-start branches, including those without a live session. Content-based integration requires a delta from the branch point; an unchanged virtual merge is not enough for an empty-start branch
- Branch deletion accepts default-branch ancestry, ancestry in the checked-out integration branch, patch equivalence, or a merged GitHub PR whose fetched head contains the local tip
- Merged-PR proof uses paginated HTTP GraphQL with the repository-bound account and host; incomplete reads remain unknown and retryable
- MCP
repo action=branch_deleteremoves an integrated local branch without a worktree after the same safety proof; it preserves remote refs and refuses checked-out, current, default, or changed local refs - Worktree Manager panel (
Cmd+Shift+Wor Command Palette → “Worktree manager”): - Dedicated overlay listing all worktrees across all repos with metadata: branch name, repo badge, PR state (open/merged/closed), dirty stats, last commit timestamp
- Dirty, merged, and unknown badges from the shared progressive refresh
- Orphan worktree detection with warning badge and Prune action; pruning refuses in-progress Git operations and detached commits absent from durable refs
- Repo filter pills and text search for branch names
- Multi-select with checkboxes and select-all for batch operations
- Batch delete and batch merge & archive
- Single-row actions: Open Terminal, Merge & Archive, Delete (disabled on main worktrees)
7.3 Auto-Fetch
- Per-repo configurable interval (5/15/30/60 minutes, default: disabled)
- Background
git fetch --allvia non-interactive subprocess - Bumps revision counter to refresh branch stats and ahead/behind counts
- Errors logged to appLogger, never blocking
- Master-tick architecture: single 1-minute timer checks all repos
7.4 Unified Repo Watcher
- Single watcher per repository monitoring the entire working tree recursively (replaces separate HEAD/index watchers)
- Uses raw
notify::RecommendedWatcherwith manual per-category trailing debounce - Event categories:
Git(HEAD, refs, index, MERGE_HEAD),WorkTree(source files),Config(app config changes) - Each category has its own debounce window — git metadata changes propagate faster than file edits
- Respects
.gitignorerules — ignored paths do not trigger refreshes - Gitignore hot-reload: editing
.gitignorerebuilds the ignore filter without restarting the watcher - When a terminal runs
git checkout -b new-branchin the main working directory (not a worktree), the sidebar renames the existing branch entry in-place (preserving all terminal state) instead of creating a duplicate
7.5 Diff
- Working tree diff and per-commit diff via Git Panel Changes tab
- Per-file diff counts (additions/deletions) shown inline in Changes tab
- Click a file row to view its diff
- Side-by-side (split), unified (inline), and scroll (all files) view modes — toggle in toolbar, preference persisted
- Scroll mode (all-files diff) — shows every changed file (staged + unstaged) in a continuous scrollable view with collapsible file sections, per-file addition/deletion stats, sticky header with totals, and clickable filenames that open in the editor. Reactively reloads on git operations via revision tracking
- Auto-unified for new/deleted files — split view is forced to unified when the diff is one-sided
- Word-level diff highlighting via
@git-diff-view/solidwith virtualized rendering - Hunk-level restore — hover a hunk header to reveal a revert button (discard for working tree, unstage for staged)
- Line-level restore — click individual addition/deletion lines to select them (shift+click for ranges), then restore only the selected lines via partial patch
- Text selection and copy enabled in diff panels (
user-select: text) Cmd+Fsearch in diff tabs via SearchBar + DomSearchEngine- Submodule entries are filtered from working tree status (not shown as regular files)
- Standalone DiffPanel removed in v0.9.0 (see section 3.2)
8. GitHub Integration
8.1 PR Monitoring
- GraphQL API (replaces
ghCLI for data fetching) - PR badge colors: green (open), purple (merged), red (closed), gray (draft)
- Merge state: Ready to merge, Checks failing, Has conflicts, Behind base, Blocked, Draft
- Review state: Approved, Changes requested, Review required
- PR lifecycle rules: CLOSED PRs hidden from sidebar and status bar; MERGED PRs shown for 5 minutes of accumulated user activity then hidden
- Auto-show PR popover filters out CLOSED and MERGED PRs (configurable in Settings > Git & GitHub > Pull Requests). The popover is non-modal: wheel scrolling over the sidebar keeps terminal keyboard focus; an outside press dismisses it and reaches the underlying control.
8.2 CI Checks
- Ring indicator with proportional segments
- Individual check names and status in PR detail popover
- Labels with GitHub-matching colors
8.3 PR Detail Popover
- Title, number, link to GitHub
- Author, timestamps, state, merge readiness, review decision
- CI check details, labels, line changes, commit count
- View Diff button: opens PR diff as a dedicated panel tab with collapsible file sections, dual line numbers, and color-coded additions/deletions
- AI Review: one unattended ego turn over the PR diff (#795-320b). Findings are listed with severity, path and line; each one with a concrete line can be
selected and posted to GitHub as an inline review comment. Findings below the confidence threshold (default
0.7,TUIC_REVIEW_CONFIDENCE_THRESHOLDoverrides) never leave the backend. TUICommander stores no API key and names no model — that is ego’s configuration. When ego is not reachable the popover shows ego’s own sentence, never an empty finding list - Merge button: visible when PR is open, approved, CI green — merges via GitHub API. Merge method auto-detected from repo-allowed methods; auto-fallback to squash on HTTP 405 rejection
- Approve button: submit an approving review via GitHub API (remote-only PRs)
- Post-merge cleanup dialog: after merge, offers checkable steps (switch to base, pull, delete local/remote branch)
- Review button: if the branch’s active agent has a run config named “review”, spawns a terminal running the interpolated command with
{pr_number},{branch},{base_branch},{repo},{pr_url}. Hidden when no matching config exists - Triggered from: sidebar PR badge, status bar PR badge, status bar CI badge, toolbar notification bell
8.4 PR Visibility Filters
- Global filters and nullable repository overrides persist across restarts; an explicit Show overrides a global Hide. Rust catalogue metadata and owner refresh cover both scopes.
- Global settings (Settings > Git & GitHub > Pull Requests): hide draft PRs, hide conflicting PRs, hide CI-failing PRs
- Per-repo overrides (Settings > [Repo] > PR Visibility): tri-state toggle per filter (Show / Default / Hide)
- Default = inherit from global setting, shown in parentheses (e.g. “Draft PRs (Show)”)
- Resolution chain: per-repo override → global setting
- TriStateToggle component: 3-position pill switch (left=hide, center=default, right=show) matching existing toggle style
8.5 Auto-Heal
- Auto-heal resolves failing checks from the exact commit over account-bound GraphQL, including external CI; check pagination and newest-rerun deduplication do not depend on the open PR count.
- When a PR on a branch with an active agent terminal becomes blocked, auto-heal hands the problem to the agent:
- CI failure — fetches failure logs and injects them with a fix prompt
- Merge conflict (
mergeable === "CONFLICTING") — injects a resolve-conflicts prompt
- Toggle per-branch via pill-switch toggle in PR detail popover (visible when CI is failing or the PR is conflicting), styled consistently with CI check item rows
- Fetches completed failed-job logs directly via the GitHub Actions jobs API and configured CircleCI jobs, including when sibling jobs keep the workflow run in progress; logs are sanitised and truncated before injection
- Waits for agent to be idle/awaiting input before injecting
- Max 3 delivered attempts per block cycle, then stops and logs a warning; log-fetch and terminal-delivery failures do not consume the budget
- Enabling while already blocked kicks off a heal immediately
- Attempt counter visible in PR detail popover
- Status tracked per-branch in
BranchState.ciAutoHeal
8.6 PR Notifications
- Types: Merged, Closed, Conflicts, CI Failed, Changes Requested, Ready
- Toolbar bell with count badge
- Individual dismiss or dismiss all
- Click to open PR detail popover
8.7 Merge PR via GitHub API
- Merge PRs directly from TUICommander without switching to GitHub web
- Configurable merge strategy per repo: merge commit, squash, or rebase (Settings > Repository > Worktree tab)
- Merge method auto-detected from repo’s allowed methods via GitHub API (
get_repo_merge_methods); auto-fallback to squash on HTTP 405 rejection. Squash is preferred first when several methods are allowed (src/utils/prMerge.ts) - Merge stays available while CI is still running:
canMergePrrequires the PR to be open, non-draft, approved, and free of definitively failed checks — pending checks do not hide the action - Triggered from: PR detail popover (local branches), remote-only PR popover, Merge & Archive workflow (sidebar context menu)
- Post-merge cleanup dialog: sequential steps executed via Rust backend (not PTY — terminal may be occupied by AI agent)
- Switch to base branch (auto-stash if dirty — inline warning shown with “Unstash after switch” checkbox)
- Pull base branch (ff-only)
- Close terminals + delete local branch (safe delete, refuses default branch)
- Delete remote branch (gracefully handles “already deleted”)
- Steps are checkable — user can toggle which to execute
- Per-step status reporting: pending → running → success/error
- After-merge behavior setting for worktrees:
archive(auto-archive),delete(remove),ask(show dialog) - When
afterMerge=ask: unified cleanup dialog includes an archive/delete worktree step (with inline selector) alongside branch cleanup steps — replaces the old 3-button MergePostActionDialog
8.8 Auto-Delete Branch on PR Close
- Per-repo setting: Off (default) / Ask / Auto
- Triggered when GitHub polling detects PR merged or closed transition
- If branch has a linked worktree, removes worktree first then deletes branch
- Safety: never deletes default/main branch; dirty worktrees always escalate to ask mode
- Removes the checkout and local branch when the shared backend verdict proves integration or finds its tip on any remote-tracking ref; the containing ref is named as proof.
- When removal would delete an unmerged branch, the error card offers Remove worktree, keep branch. The action reruns lifecycle checks and confirmation with branch deletion disabled for that removal only; the repository setting stays unchanged.
- Deduplication prevents double-firing on the same PR
8.9 GitHub Issues Panel
- Issues displayed in a collapsible section within the GitHub panel alongside PRs
- Filter modes: Assigned (default), Created, Mentioned, All, Disabled
- Filter persisted in app config (
issue_filterfield) and configurable in Settings > Git & GitHub > Issues - Each issue shows: number, title, state (OPEN/CLOSED), author, labels, assignees, milestone, comment count, timestamps
- Labels rendered with GitHub-matching colors (background opacity 0.7, contrast-aware text color)
- Issue actions: Open in GitHub, Close/Reopen, Copy issue number
- Expand accordion to see full details (milestone, assignees, labels, timestamps)
- Skeleton loading rows shown during first fetch
- Empty state message when no issues match the filter
- MCP HTTP endpoint:
GET /repo/issues?path=...returns issues JSON - MCP HTTP endpoint:
POST /repo/issues/closecloses an issue
8.10 GitHub Ops Dashboard
- Dedicated GitHub Ops dashboard tab with live columns for PR review findings, auto-fix sessions, conflict assists, improvement proposals, and CI / merge readiness.
- The review column shows Working, Done with a finding count, or ego’s own failure sentence. It deliberately never names a model: one unattended turn is all ego reports.
- Improvement scans run one unattended ego turn over local repo context with focus modes:
refactor,testing, andperf. At most five proposals survive one scan. - Proposals are notification-first: scan results emit
proposals-readyover desktop events and/eventsSSE; that event is the only path that publishes them into the store — the scan’s return value is for the caller, not for the panel. No GitHub issue is created automatically. - Each proposal can be promoted to a GitHub issue only through an explicit user action, using the existing authenticated issue creation path.
8.10a Changelog Generation
- Button in the GitHub panel header opens the Changelog modal, which runs one unattended ego turn over the merged PRs since the last tag (#795-320b).
- The result is markdown plus a structured JSON split; the modal renders the markdown and offers Copy and Save (
CHANGELOG-ai.md). HTTP and MCP callers get both halves. - Ego answering in prose only is a valid answer — the JSON half is
nulland the markdown still renders. Ego being unreachable shows ego’s own sentence, never a blank changelog.
8.11 Polling
- Active window: every 30 seconds
- Hidden window: every 2 minutes
- API budget: ~2 calls/min/repo
8.12 Token Resolution
- Priority:
GH_TOKENenv →GITHUB_TOKENenv → OAuth keyring token - Empty environment variables are ignored
- The
ghCLI login is not a token source
8.13 OAuth Device Flow Login
- One-click GitHub authentication from the Settings > Git & GitHub page
- Uses GitHub OAuth App Device Flow (no client secret, works on desktop)
- Token stored in OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service)
- Requested scope:
repo - Shows user avatar, login name, and token source after authentication
- OAuth status exposes Logout; it removes the OAuth token and falls back to environment tokens
- Environment status exposes Switch to OAuth and Disconnect; disconnect remains in effect across status refresh and lazy requests until login or restart
- On 401: auto-clears invalid OAuth token and prompts re-auth
PR creation, issue creation, and review submission use account-aware REST requests for the bound repository, including GitHub Enterprise, without spawning gh.
8.14 Multiple Accounts (github.com + GitHub Enterprise)
GitHub integration is account-centric: TUICommander can manage N accounts and each workspace repo is explicitly bound to the account that monitors it (a persisted binding, not derived live from origin).
Account kinds
- Ambient github.com default — the account you authenticate with via the OAuth device flow above (or
GH_TOKEN/GITHUB_TOKEN). Behaves exactly as before; a github.com-only user sees zero change. - Additional github.com accounts — extra named github.com logins added via the device flow (Settings → Git & GitHub → Additional GitHub Accounts → “Add another github.com account”).
- GitHub Enterprise Server (GHE) — added by host + a pasted Personal Access Token (no per-host OAuth App). Validated against
https://{host}/api/v3/user; PAT stored in the OS keyring undergithub/account/{id}/token.
Repository bindings (Settings → Git & GitHub → Repository Bindings)
- Each workspace repo resolves to one of: Bound (shows the account + Unbind), NeedsBind (a candidate chooser — no silent
originpick when multiple GitHub remotes/accounts match), NeedsAccount (a github.com repo with no account yet → points to setup), or Unmonitored. - A single account/remote candidate resolves automatically without persisting a binding; the default-only setup hides Repository Bindings. Multiple candidates always ask, including fork/upstream repositories on one account. Worktrees of a repo share the main checkout’s binding.
Per-account isolation (hybrid model)
- github.com keeps the global breaker/viewer/rate/cooldown state byte-for-byte; each GHE account gets its own
ghe_state(circuit breaker, viewer login, rate budget). - The poller groups active repos by account and runs one batch per account, so a 401 / rate-limit / fault on one account never opens another’s breaker or blocks its polling.
- Cooldown keys are account-scoped (
{account_id}:owner/repofor GHE;owner/repounchanged for cloud); github.com logout clears only cloud cooldowns; removing an account drops only its token, record, bindings, and caches.
Limitations
- REST + GraphQL (PRs, CI, issues, merge, approve, issue comments) work against bound GHE repos. CI Auto-Heal fetches Actions logs over REST using the bound GHE account; downloads keep bounded failure tails and share one 60-second sweep deadline.
Backend: github_account.rs (GitHubHost, account model, binding store, resolve_repo_account), commands github_list_accounts / github_remove_account / github_bind_repo / github_unbind_repo / github_list_bindings / github_resolve_repo.
9. Voice Dictation
Voice settings retain the resolved speech engine when saved. Inactive external commands do not implicitly replace the selected Italian voice. Authorized isolated agent-test builds can enable speech output while microphone capture remains disabled.
The tuic-dictation Rust crate implements audio, transcription and speech; the desktop application retains the commands, browser transport and event emission.
9.1 Whisper Inference
- Local processing via
whisper-rs(no cloud) - macOS: GPU-accelerated via Metal
- Linux: GPU via Vulkan when a Vulkan driver is present, CPU otherwise
- Windows: GPU via Vulkan when a Vulkan driver is present, CPU otherwise
9.2 Models
| Model | Size | Quality |
|---|---|---|
| small | ~488 MB | Good |
| small.en | ~488 MB | Good (English-only) |
| large-v2 | ~3.0 GB | Highest accuracy (slow) |
| large-v3-turbo | ~1.6 GB | Best (recommended, default) |
9.3 Push-to-Talk
- Native macOS Fn stays recording across window focus changes while held. Physical release stops capture even when another app has focus.
- Default hotkey:
F5(configurable, registered globally) - Mic button in status bar: hold to record, release to transcribe
- On macOS, releasing Fn stops microphone capture in Rust before the WebView handles the event. A late Fn start is refused. DOM hotkeys release on blur if key-up was lost; native Fn follows physical key state. The file log records release-to-stop latency without storing spoken text.
- The destination and selection are captured at key-press time, before asynchronous work. Explicit editors take priority. In terminal Chat, Compose, transcript or BODY focus delivers to Compose through a CodeMirror transaction; Auto-send then uses its normal Send action once, while disabled Auto-send leaves an editable draft. Other fields stay review-only. CLI uses the captured PTY session with existing auto-send behavior. Focus and tab changes do not redirect the text.
- Long Claude CLI dictation uses bracketed paste to preserve its beginning, with or without Auto-send. Short dialog answers remain key events.
- If the target disappears or the draft changes before delivery, the transcript stays in a sticky error message and the Messages bell for recovery. Delivery logs contain metadata without spoken text.
9.4 Streaming Transcription
- Real-time partial results during push-to-talk via adaptive sliding windows
- First partial within ~1.5s, subsequent windows grow to 3s for quality
- Streaming skips only all-zero audio windows; the shared RMS and speech-confidence gates reject quiet/no-speech audio. A trailing pause does not discard the preceding speech.
- Floating toast shows partial text above status bar during recording, with a live microphone meter beside the partial text. The level is an RMS reading curved as
sqrt(rms * 20)and clamped to 0–1 so ordinary speech is visible rather than pinned near zero, published through an atomic so the UI never blocks audio capture - 200ms audio window overlap (
keep_ms) carries context across windows for continuity - Final transcription pass on full captured audio at key release
- Before the final pass, the hands-free 20 ms frame and sustained-duration rule rejects short bursts; push-to-talk uses the configured transcription RMS floor for frame activity so quiet sustained speech still reaches Whisper. Speech still open at key release is kept.
- A skipped final pass shows its specific speech-gate reason in the dictation status; an empty successful pass reports
no speech detected. - Hallucination filter (
transcribe.rs) as the backstop after the RMS gate: quiet audio makes Whisper emit a subtitle credit in whatever language it guessed. Short thanks (grazie,thank you,merci,danke,спасибо, …) are dropped only when they are the entire transcript, so a dictated sentence containing one survives; channel boilerplate (amara.org,sottotitoli e revisione a cura di,thanks for watching, …) is dropped anywhere in the text. Covers all 11 languages inWHISPER_LANGUAGESbecause the default setting isauto
9.5 Microphone Permission Detection (macOS)
- On first use, checks microphone permission via macOS TCC (Transparency, Consent, and Control) framework
- Permission states:
NotDetermined(will prompt),Authorized,Denied,Restricted - If denied, shows a dialog guiding the user to System Settings > Privacy & Security > Microphone with an “Open Settings” button
- Linux/Windows: always returns
Authorized(no TCC framework)
9.6 Configuration
- Enable/disable, hotkey, language (auto-detect or explicit), model download
- Audio device selection
- Text correction dictionary (e.g., “new line” →
\n) - Auto-send — Enable in Settings > Voice to automatically submit (press Enter) after transcription completes.
- Spoken-reply voice, hands-free activation phrase and hold-back delay — see 9.11.
9.7 Speech Engines and Assets
- Microsoft Edge voices are the default engine. No download; the voice list comes from the service, filtered by the dictation language, with a Listen button, and the chosen voice persists. It needs the internet and sends the reply text to Microsoft’s speech service (stated in the settings). Offline or a service error shows a clear message in the Voice section, never silence or a hang; a cancelled or over-budget reply stops promptly.
- Expert > Speech engine switches to Pocket TTS (local) or an external command. A fresh install gets Edge; an installation with a chosen Pocket voice, the Pocket runtime on disk or a configured speech command keeps that engine. Echo cancellation, hush, volume, levelling and the voice choice apply to all engines.
- The rest of this section describes the Pocket engine’s assets.
- Spoken replies need two downloads beside the Whisper models: a language bundle (ONNX graphs, tokenizer, voice — about 130 MB, French about 390 MB) and ONNX Runtime itself (42 MB). Neither ships with the app.
- Bundled languages: English, French, German, Italian, Portuguese and Spanish, each with the voice Kyutai lists as native to it (alba, estelle, juergen, giovanni, rafael, lola). French exists upstream only as the larger 24-layer model.
- The catalogue is an allowlist compiled into the binary, not a fetched manifest: every file is pinned to an immutable upstream revision and to a sha256, and a download whose bytes do not match that hash is refused instead of installed.
- Downloads report progress, can be cancelled, and install atomically — the bytes land in a staging directory, are verified there, and only then replace the installed version. An interrupted or corrupt download never appears ready.
- Three states, told apart on purpose:
absentoffers a download,incompletenames the files that are missing,readyis the only one a language can be spoken from. - Replacing or deleting a language waits for any reply being spoken to finish, then unloads its graphs. The 125 MB an engine holds resident is released on deletion and at shutdown.
- Every voice. Each language has 26 Kyutai voices. One ships in the language bundle; the other 25 are separate downloads (about 6 MB each, 25 MB for French) that the user chooses in Settings > Voice > Voices, grouped as Installed, Downloadable and Yours.
- Your own voice files. “Add voice file…” imports a
.safetensorsvoice into the current language. The file is checked against that language’s model before it is stored, and a file that does not fit is refused with the reason. TUICommander does not create or clone voices. - Listen plays a short sample of the selected voice on this machine’s speaker, without a hands-free conversation and without changing the saved voice. It is refused while a hands-free reply is being spoken.
- Sources and licensing: the graphs come from a public Hugging Face export of Kyutai’s Pocket TTS weights; the voices come from Kyutai’s ungated repository without the voice-cloning weights. Both are CC-BY-4.0, attributed in
THIRD_PARTY_NOTICES.md.
9.8 Spoken Replies
- Hands-free listening and spoken replies are independent. Settings → Voice has a toggle for each (mobile Settings too): listening only, replies only (push-to-talk dictation, answers spoken), both, or none. Existing users keep listening on. The dictation toast carries a speaker button that turns spoken replies on and off for the next reply and stops one that is playing.
- Spoken replies defaults on and can be disabled from Voice Settings or mobile Settings. Off keeps dictation armed, cancels the speech queue, and enforces text replies server-side. Edge 401/403 rejections start a five-minute cool-down across conversations.
- Arming hands-free also opens a reply queue for that conversation, so the model can answer out loud. Arming without a working voice still works — that is ordinary dictation — and the reason is reported rather than discovered on the first reply.
- The user can talk over a reply. Speaking stops the moment the capture loop hears them, and their words land in the new turn rather than behind the sentence they interrupted. Echo cancellation runs first, so a reply never interrupts itself on its own voice coming back through the microphone.
- Accepting a reply is not the user hearing it. Every reply gets an id and one of six fates:
queued,rendering,speaking,finished,interruptedorfailed. Onlyfinishedmeans somebody heard it to the end, and only the audio device going quiet can produce it. - A reply written for a turn the user has already talked over is refused, not spoken over whatever they said next.
- Every reply is at one level. A loudness stage levels each reply, brings it to the Voice volume (-30 to -12 dB, default -18) and limits the peaks to -1 dBFS, so no slider position clips. Levelling (Off to Strong, default 67%) sets how much the quiet and loud words of one reply are evened out. A change applies to the next reply and does not stop speech.
- Speech belongs to a conversation, not to the application. A model reaches it through the
voiceMCP tool and may drive only the conversation armed for its own terminal; a connection bound to no terminal is refused rather than allowed to speak into whichever conversation happens to be armed. - The
voicetool is always listed, on every build, and answersavailable: falsewith a reason when it cannot speak — discovery does not depend on tool-list change notifications, which not every client acts on.
9.9 One language, end to end
- The dictation language decides everything: what Whisper transcribes, which language the model is told to answer in, and which voice speaks the answer. There is no separate speech language and the model cannot override it.
- A spoken turn is typed into the agent at once, even while it is working — the same as a line you type by hand into a busy agent, which the agent queues or takes mid-turn itself. It never waits in the Compose queue. Only an open permission dialog or text you are typing in the terminal holds it; it stays in the hands-free panel and is typed the moment they are gone, joined with anything you said meanwhile. Held phrases are separated by line breaks inside one paste and submitted once.
- Every hands-free turn reaches the model as
<what you said> (reply in <Language>). It is part of the typed entry, so turning optional hints off does not remove it. - With Auto, the language is the one Whisper actually detected, and it is shown. Before the first turn there is none — spoken replies are unavailable and say so, rather than falling back to English.
- A language TUICommander transcribes but ships no voice for is named, never substituted: the status says which bundle is missing instead of answering in a language the user is not speaking.
- Which voice speaks is a setting; which language speaks is not. A language that ships several voices offers them in the Dictation panel; left untouched, the setting means “the first voice this language ships”. A named voice the language does not ship is refused with the list of the ones it does, rather than replaced by a voice nobody chose.
- Changing the language or the voice stops the reply written for the previous one mid-sentence — a sentence half said in one voice does not finish in another. Changing any other dictation setting leaves the voice alone.
9.10 The model is told when you start and stop talking
- Notify model when hands-free changes (on by default): arming tells the agent that messages are spoken and asks it to acknowledge aloud at once, then give a short spoken answer when done; disarming tells it to go back to text.
- Both notices are typed like a spoken turn — at once, even into a busy agent — and land in the terminal the conversation was armed for, not in whatever tab you focused since. A start notice held by a dialog goes before any spoken turn; a stop notice that meets a dialog is dropped, because the conversation it belonged to is already over.
- Change your mind before the agent reads the start notice and it is withdrawn, with no stop notice behind it. What the agent ends up holding always matches the mode you are actually in.
- Your own start notice: replace the text the agent reads at the start with your own instructions (for example a reply language or a length limit). Leave it empty, or press Reset to default, to send the built-in text. A notice written on several lines is sent as one line.
- Turning the option off silences both notices and nothing else: disarming still stops the voice, drops queued audio and refuses late replies.
- Push-to-talk is untouched. Holding the hotkey never starts continuous listening, never uses the activation phrase, never makes speech available and never notifies anyone.
9.11 Driving it from Settings > Voice
- Browser Now Playing controls identify TUICommander hands-free. Play/Pause resume or hold spoken replies without stopping the microphone; Stop ends hands-free and drops replies. Controls are released when the conversation ends.
- One titled section per job, speech-to-text and text-to-speech kept apart: Dictation (enable, hotkey, auto-send), Speech recognition (input device, Whisper model, language, voice tuning), Auto-Corrections, Hands-free conversation, Spoken replies. Each section holds its own advanced settings; there is no shared “Advanced” section.
- Spoken replies lists the speech languages and the ONNX runtime with their state, size and Download / Repair / Cancel / delete, plus the voice to speak with. There is no speech-language control — the language is the Whisper one, and a second control would be a second source that disagrees with it.
- Conversation controls — Start conversation is an accent action, Stop is distinct, and a coloured Running/Stopped indicator accompanies the backend phase.
- Early wake acknowledgement: VAD stays Listening; a recognized leading activation phrase shows Go ahead before the final Transcribing pass. Desktop and browser capture share up to four prefix checks with the existing local model. A partial match never bypasses final admission.
- Hands-free conversation picks the terminal to talk to, starts and stops the mode, and shows the live phase (waiting, capturing, wake confirmed, transcribing, holding back, delivered), the turn being held back, what is being spoken and any error. It also holds the activation phrase and the hold-back delay.
- Breath and continuation: 1.5 s of quiet closes an utterance. With an activation phrase, a turn waits at least 5 s for speech that continues without repeating the phrase; the displayed pending text grows before it reaches the agent as one message.
- Earcons — an 80 ms blip when a spoken turn reaches the agent, and a softer, lower one when the activation phrase drops a turn, so the user knows without looking. Web Audio on the desktop and in a browser alike, played only by the client whose microphone holds the conversation. Too short for the capture VAD to take as speech (
min_speech_msis 200 ms). On by default; thehands_free_earconsdictation setting turns them off. - Opening the panel never opens the microphone, and neither does starting the app. Nothing arms by itself; the mode starts only when you press Start (here or in the Command Palette) or say the activation phrase in a conversation you already armed.
9.12 Starting it from the Command Palette
- “Start hands-free conversation” / “Stop hands-free conversation” — one entry (
toggle-hands-free, category Dictation), labelled for what it will do. Starting binds the active terminal; an active tab with no live session starts nothing. Hidden on the desktop while dictation is disabled; available in browser mode, where it uses the tab’s own microphone. Cmd+Alt+V(Ctrl+Alt+Von Windows/Linux) starts or stops hands-free on the active terminal. User keybinding overrides take precedence. With desktop dictation disabled, the shortcut does nothing.- One function (
src/actions/handsFreeConversation.ts) reuses the store’s arm/disarm, so the audio owner and earcon priming are the same as in Settings. - Push-to-talk and continuous listening are two mechanisms, not a mode switch. Push-to-talk is the hotkey; continuous is Start. There is no setting that flips between them.
- The dictation hotkey is also the stop control. Pressed while a conversation is running, it ends the whole thing — capture, the transcript waiting out its hold-back or held by a dialog, and whatever is being spoken. Turns already typed stay in the terminal. Pressed otherwise it records as usual.
- Hands-free works in a browser too, on the browser’s own hardware. A tab opens its microphone and speaker and streams them to TUICommander, so a conversation started from a laptop is heard and answered there. The two sides never mix: arming from a browser cannot open the microphone on the machine running TUICommander, and arming from the desktop cannot take audio from a browser. A tab whose owner has no audio connection is refused rather than quietly served the server’s hardware, and closing the tab ends the conversation it held. The global dictation hotkey and the microphone-device list stay desktop-only — a browser cannot register a system hotkey, and that device list belongs to the other machine.
10. Prompt Library
10.1 Access
Cmd+Kto open drawer- Toolbar button
10.2 Prompts
- Create, edit, delete saved prompts
- Variable substitution:
{{variable_name}} - Built-in variables:
{{diff}},{{changed_files}},{{repo_name}},{{branch}},{{cwd}} - Custom variables prompt user for input
- Categories: Custom, Recent, Favorites
- Pin prompts to top
- Search by name or content
10.3 Keyboard Navigation
↑/↓: navigate,Enter: insert (restores terminal focus),Ctrl+N: new,Ctrl+E: edit,Ctrl+F: toggle favorite,Esc: close
10.4 Run Commands
Cmd+Shift+R: run saved command for active branchedit-command: edit command before running (no default shortcut; bind it inkeybindings.json)Cmd+R: reload the active web/preview tab- Configure per-repo in Settings → Repository → Scripts
10.5 Smart Prompts
AI automation layer with 29 built-in context-aware prompts. Each prompt includes a description explaining what it does. Prompts auto-resolve git context variables and execute via inject (PTY write), shell script (direct run), headless (one-shot subprocess), or API (direct LLM call) mode.
- Open:
Cmd+Kor toolbar lightning bolt button - Drawer with category filtering (All/Custom/Recent/Favorites), search by name/description, and enable/disable toggles
- Prompt rows show inline badges: execution mode (inject/shell/headless/api), built-in, placement tags
- Prompts are context-aware: 31 variables auto-resolved from git, GitHub, and terminal state
- Git context follows the active terminal checkout;
{base_branch}uses an explicit repository setting or Git detection for Automatic. Templates using both{branch}and{base_branch}are disabled with an explanation when refreshed checkout context shows equal branches. Cached workspace names do not veto execution; each run checks Git again. - Variable Input Dialog: unresolved variables show a compact form with variable name + description before execution
- Edit Prompt dialog: full editor with name, description, content textarea, variable insertion dropdown (grouped by Git/GitHub/Terminal with descriptions), placement checkboxes, execution mode, auto-execute, and keyboard shortcut capture
- Inject target: when a prompt is not submitted immediately, the target selects the review surface: the Compose box (default) or editable text in the Terminal
- Auto-execute: when enabled, a prompt submits exactly once through agent-aware
sendCommand, regardless of its review target. When disabled, it remains editable. Explicit Insert and Insert & Run actions override the saved setting. - API execution mode runs one unattended ego turn (#787-ee50): it used to call LLM providers directly over HTTP from TUICommander; that client, its provider registry and its keyring entry were deleted with the embedded AI engine (#784-0aec). It now goes through
acp_one_shot_prompt— launch the configured ego, onesession/newwith no MCP server, one prompt, shut down — and the turn’s final text goes to the prompt’soutputTarget. Nothing streams: a Smart Prompt runs with no panel open. Aheadlessprompt whose resolved agent isapitakes the same one path. Every permission request and elicitation is declined the instant it arrives, because a seat nobody takes is a turn that never ends; the count comes back asdeclinedso an empty answer caused by a refused tool is reported as that rather than as an empty answer. The turn is abandoned after 300s - No LLM API config: there is no global provider/model/API key in
Settings > Agentsany more, and TUICommander stores no API key. The model anapiprompt runs on is ego’s default, set inSettings > AI Chat(786-4a6d). With no ego binary named, the mode refuses and namesSettings > Generalfor the binary andSettings > AI Chatfor the model
10.6 Built-in Prompts by Category
| Category | Prompts |
|---|---|
| Git & Commit | Smart Commit, Commit & Push, Amend Commit, Generate Commit Message |
| Code Review | Review Changes, Review Staged, Review PR, Address Review Comments |
| Pull Requests | Create PR, Update PR Description, Generate PR Description |
| Merge & Conflicts | Resolve Conflicts, Merge Main Into Branch, Rebase on Main |
| CI & Quality | Fix CI Failures, Fix Lint Issues, Write Tests, Run & Fix Tests |
| Investigation | Investigate Issue, What Changed?, Summarize Branch, Explain Changes |
| Code Operations | Suggest Refactoring, Security Audit |
10.7 Context Variables
Variables are resolved from the Rust backend (resolve_context_variables) and frontend stores:
| Variable | Source | Description |
|---|---|---|
{branch} | git | Current branch name |
{base_branch} | repository settings / git | Explicit configured base branch, with Git detection for Automatic or unloaded settings |
{repo_name} | git | Repository directory name |
{repo_path} | git | Full filesystem path to the repository root |
{repo_owner} | git | GitHub owner parsed from remote URL |
{repo_slug} | git | Repository name parsed from remote URL |
{diff} | git | Full working tree diff (truncated to 50KB) |
{staged_diff} | git | Staged changes diff (truncated to 50KB) |
{changed_files} | git | Short status output |
{dirty_files_count} | git | Number of modified files (derived from changed_files) |
{commit_log} | git | Last 20 commits (oneline) |
{last_commit} | git | Last commit hash + message |
{conflict_files} | git | Files with merge conflicts |
{stash_list} | git | Stash entries |
{branch_status} | git | Ahead/behind remote tracking branch |
{remote_url} | git | Remote origin URL |
{current_user} | git | Git config user.name |
{pr_number} | GitHub store | PR number for current branch |
{pr_title} | GitHub store | PR title |
{pr_url} | GitHub store | PR URL |
{pr_state} | GitHub store | PR state (OPEN, MERGED, CLOSED) |
{pr_author} | GitHub store | PR author username |
{pr_labels} | GitHub store | PR labels (comma-separated) |
{pr_additions} | GitHub store | Lines added in PR |
{pr_deletions} | GitHub store | Lines deleted in PR |
{pr_checks} | GitHub store | CI check summary (passed/failed/pending) |
{pr_open_threads} | get_pr_open_threads | Open, current review threads as a fenced untrusted list (max 30, most severe first) |
{merge_status} | GitHub store | PR mergeable status |
{review_decision} | GitHub store | PR review decision |
{agent_type} | terminal store | Active agent type (claude, gemini, etc.) |
{cwd} | terminal store | Active terminal working directory |
{issue_number} | manual | Prompted from user at execution time |
10.8 Execution Modes
- Inject (default): routes the resolved prompt text to the active terminal. Auto-execute decides whether the action submits. Submissions are idle-gated (configurable via
requiresIdle) and use agent-aware Enter semantics. Review-only actions are not idle-gated; the Target sub-option places their editable text in the Compose box (default) or directly in the terminal input. If the Compose box is unavailable, the terminal input is the fallback. - Shell script: executes the prompt content directly as a shell script via
execute_shell_scriptTauri command. No agent involved — runs content as-is viash -c(macOS/Linux) orcmd /C(Windows) in the repo directory. Output routed viaoutputTarget. 60-second timeout cap. No prerequisites (no terminal, agent, or API config needed) - Headless: runs a one-shot subprocess via
execute_headless_promptTauri command. Requires a per-agent headless template configured in Settings → Agents (e.g.claude -p "{prompt}"). Output routed to clipboard or toast depending onoutputTarget. Falls back to inject in PWA mode. 5-minute timeout cap
10.9 UI Integration Points
| Location | Prompts shown | Trigger |
|---|---|---|
| Toolbar dropdown | All enabled prompts with toolbar placement | Cmd+Shift+K or lightning bolt button |
| Git Panel — Changes tab | SmartButtonStrip with git-changes placement | Inline buttons above changed files |
| PR Detail Popover | SmartButtonStrip with pr-popover placement | Inline buttons in PR detail view |
| Command Palette | All prompts with Smart: prefix | Cmd+P then type “Smart” |
| Branch context menu | Prompts with git-branches placement | Right-click branch in Branches tab |
10.10 Smart Prompts Management (Cmd+Shift+K Drawer)
- Settings → Smart Prompts and the Cmd+Shift+K drawer use one shared aligned editor. Settings saves changes immediately; the drawer uses explicit Save and Cancel.
- Enable/disable individual prompts via toggle button on each row
- Edit prompt: opens a modal with name, description, content, variable dropdown, eight readable placement choices, execution mode and its conditional target/agent/output fields, plus keyboard shortcut. Placement choices use two columns on the shared label/control grid.
- A normal click or Enter follows the saved auto-execute setting; double-click and Insert & Run force one submission, while Insert always keeps the result editable
- Variable insertion dropdown below content textarea: grouped by Git/GitHub/Terminal, click to insert
{variable}at cursor - Create custom smart prompts with
+ New Promptbutton - Built-in prompts show a “Reset to Default” button when content is overridden
10.11 Headless Template Configuration
- Settings → Agents → per-agent “Headless Command Template” field
- Template uses
{prompt}placeholder for the resolved prompt text - Example:
claude -p "{prompt}",gemini -p "{prompt}" - Required for headless execution mode; without it, headless prompts fall back to inject
11. Settings
AI Chat settings retain model controls when ego health diagnostics fail, with a non-blocking explanation and preserved credential evidence.
Malformed config fields recover independently, retaining valid preferences. A startup warning names reset fields and the original backup path. Legacy scrollback reflow is enabled once, without overriding later user choices.
The navigation groups the global pages by task. Each group is a static label row above its pages:
| Group | Pages |
|---|---|
| Application | General (11.1), Appearance (11.2), Notifications (11.5) |
| Workspace | Terminal (11.9), Keyboard Shortcuts (11.6), Git & GitHub (11.10) |
| AI | Agents (11.7), AI Chat (11.8), Voice (section 9), Smart Prompts (10.5) |
| Integrations | MCP (11.3), Remote Access (11.3), Remote Machines (11.3), Plugins (17.2) |
| Repositories | One page per configured repository (11.4) |
11.0 Search
- Search box at the top of the page list; filters every setting across every page at once
- Each result shows the setting name and its
Page › Sectiontrail; selecting one opens that page and scrolls to the field - Repository pages are not indexed — a global box cannot know which repository a query means
- Settings the current build does not render (the AI Chat page while Experimental Features is off, for example) report no match instead of opening an absent page
- A result inside an expert setting shows an Expert badge; opening it reveals that setting (see 11.11)
- The index is committed, not scanned from the DOM: only one page mounts at a time, and mounting the rest would fire CLI status, mdkb status, GitHub and audio probes on every keystroke. A drift test re-derives it from the sources, so a setting added without indexing fails CI
11.1 General
- Language: the locales that ship a message catalog, each named in its own language. The pick persists to
config.jsonand re-renders every translated string without a reload. Locales with no catalog are not listed — they would render English while claiming to be translated — so the list holds only English until more catalogs land - Show agent context bar
- Confirmations: quit, close tab (only when a process is running — agents or busy shell; idle shells close immediately)
- Power management: prevent sleep when busy, auto-standby timeout, content indexing strategy
- Updates: auto-check, update channel, check now. Beta builds migrate old saved Stable preferences to Beta once; later explicit channel choices are preserved
- TUIC CLI install/uninstall (see 21), Code Intelligence (MDKB, see 14.8)
- ego executable (ego section, after Code Intelligence): the ego binary the AI Chat panel talks to over ACP. Desktop: status line with Install latest (downloads the latest ego release binary, installs it like MDKB and selects it)/Select…/Clear; browser: a text field. Always shown, also while Experimental Features is off
- Default IDE, custom launchers (see 4.5)
- Experimental Features: one master toggle, no sub-flags. It opts in to the AI Chat panel, the AI Chat settings page (11.8) and SSH Tunnels. The three AI sub-flags went with the embedded engine (#784-0aec)
11.2 Appearance
- Split tab mode: separate / unified
- Tab ordering mode: grouped-by-type (default, tabs grouped by kind), terminals-first (terminals left, others freely interleaved), free (any tab anywhere)
- Cycle all tab types, nested terminal tabs
- Max tab name length: 10-60 slider
- Repository groups: create, rename, delete, color-coded
- Layout: reset panel sizes (restore sidebar and panel widths to defaults)
- UI legend: reference for colors, symbols and badges
11.3 MCP, Remote Access and Remote Machines
Three pages under Integrations. They were one “Services & MCP” tab; each page now mounts only its own content, and the MCP and Remote Access pages share one status poll.
- MCP — HTTP API server: always active on IPC listener (Unix domain socket on macOS/Linux, named pipe
\\.\pipe\tuicommander-mcpon Windows). TCP port only for remote access - MCP — MCP connection info: bridge sidecar auto-installs configs for supported agents (Claude Code, Cursor, etc.)
- MCP — TUIC capability switches: enable or deny capability domains and grouped actions to restrict what AI agents can access; three always-visible sections group approved domains and nested member denials, with configuration status for conditional domains; parent-blocked member switches show off with an enable-parent hint and retain their saved preferences
- MCP — Upstream MCP Servers: add/edit/remove upstream MCP servers (HTTP or stdio with optional
cwd), per-upstream enable/disable, reconnect, Bearer/OAuth and multiple masked secret header rows backed by the OS credential vault, origin-bound credentials that fail closed on provider changes or unbound old entries, same-origin-only credential redirects, live status dots, tool count and metrics. Saved upstreams auto-connect on boot. The MCP popup’s “Manage in Settings” opens this page at this section - MCP Per-Repo Scoping: each repo can define which upstream MCP servers are relevant via an allowlist in repo settings (3-layer: per-repo >
.tuic.json> defaults). Null/empty allowlist = all servers. Quick toggle via Cmd+Shift+M popup - Remote Access — port, username, password (bcrypt hash), URL display, QR code, token duration, IPv6 dual-stack, Tailscale HTTPS, cloud relay. A discovery failure replaces only the address choices with an inline error and Retry; other settings remain available
- Remote Machines —
tuic-remoteconnections over SSH or a direct URL; the page lists SSH hosts discovered from~/.ssh/configandknown_hosts(hashed entries are only counted), shows the loaded agent keys, probes hosts on demand and prefills the Add form from a click - Voice dictation has its own Voice page (section 9)
11.4 Repository Settings (per-repo)
- Display name
- Worktree tab: storage strategy, prompt on create, delete branch on remove, auto-archive, orphan cleanup, PR merge strategy, after-merge action (each overridable from global defaults)
- Scripts tab: setup script (post-worktree), run script (
Cmd+Shift+R), archive script (pre-archive/delete hook), and optional local development-server URL for Design Mode - Repo-local config:
.tuic.jsonin repo root provides team-shared settings. Three-tier precedence:.tuic.json> per-repo app settings > global defaults. Scripts (setup, run, archive) are intentionally excluded from.tuic.jsonmerging — arbitrary script execution by a checked-in file poses a security risk; scripts are always sourced from the local per-repo app settings only
11.5 Notifications
- Master toggle, volume (0-100%)
- Per-event: question, error, completed, warning, info
- Test buttons per sound
- Reset to defaults
- Keep toasts in the bell — mirrors toasts into the bell’s Messages section (see 4.4). Outside the audio block, because the bell is visual and must stay configurable without an audio device
11.6 Keyboard Shortcuts
- Settings > Keyboard Shortcuts page (
Cmd+,to open Settings), also accessible from Help > Keyboard Shortcuts (same editor) - All app actions listed with their current keybinding
- Click the pencil icon to rebind — inline key recorder with pulsing accent border
- Conflict detection: warns when the new combo is already bound to another action, with option to replace
- Overridden shortcuts highlighted with accent color; per-shortcut reset icon to revert to default
- “Reset all to defaults” button at the bottom
- Custom bindings stored in
keybindings.jsonin the platform config directory - Auto-populated from
actionRegistry.ts(ACTION_METAmap) — new actions appear automatically - Global Hotkey: configurable OS-level shortcut to toggle window visibility from any application. Set in the “Global Hotkey” section at the top of the Keyboard Shortcuts page. No default — user must configure. Toggle: hidden/minimized → show+focus, visible but unfocused → focus, focused → instant hide (no dock animation). Cmd and Ctrl are distinct modifiers. Uses
tauri-plugin-global-shortcut(no Accessibility permission required on macOS). Hidden in browser/PWA mode.
11.7 Agents
- See 6.9 Agent Configuration for full details
- Claude Usage Dashboard enable/disable toggle (under Claude agent section)
11.8 AI Chat
ego’s own configuration; the ego_executable path and the ai_chat_workspace folder (AI Chat workspace, empty = home directory, absolute paths only) are on General (11.1). Shown only while Experimental Features is on, because that flag is what offers the AI Chat panel — the one place ego is reachable from.
- Reads and writes ego’s configuration by running ego:
config ls --json,models --json,doctor --json, andconfig set model="<slug>". All three reads must succeed, so the page is never a partial picture - Default model: a picker over every model ego knows, grouped by provider, with unavailable models disabled. A write is followed by a fresh read, so what is shown is what ego persisted. It survives a restart because ego holds it, not TUICommander
- Refresh from providers:
ego models --refresh, the only action in TUICommander that reaches a provider over the network — and it is ego that reaches it. Opt-in; opening the page does not - Per-provider rows: how many models are usable, and ego’s own words for why the rest are not (once per distinct reason)
- Credential state from
ego doctor: stored, expired (ego renews it on its next run), missing, or “could not read the store” — which is deliberately not the same as an empty store - No API key enters TUICommander: none is stored, none reaches the OS keyring, and no provider HTTP call is made from this process.
ego auth login <provider>runs in a terminal tab opened by the provider’s Login button, typed as a command and answered by the person in the terminal, so the secret never passes through TUICommander modelis the only writable key, exposed as its own operation rather than a key/value pair, so no caller over IPC or HTTP can reachsandboxorpermissions.judge- Four failure states, each distinct: ego not configured (names the field to fill), a configured path that will not start, an ego command that failed (shown with the command, exit code and its verbatim output), and a transport fault that is not attributed to ego
11.9 Terminal
- Background entry hides all visible desktop windows after a forced terminal snapshot (two-second acknowledgement limit). It clears desktop focus for phone push and saves terminal visibility. Showing the app restores open panels and wakes the previous visible terminal. Remote terminal WebSockets and SSE observers prevent standby while connected.
- macOS General setting: Hide Dock icon in background (default on). Show restores the Dock icon. Windows requests a low WebView memory target while hidden and the normal target on Show.
- Theme: terminal and app color theme, color swatches. Bundled themes include Commander (default and fallback for an unknown key), Paper (key
vscode-light, the light theme), Minimal Kiwi (dark green-tinted background with muted warm accents) and Ink (keyclean; neutral dark:#0a0a0acanvas,#171717surfaces, white accent, Ghostty ANSI palette, neutral tab-type tints keyed onhtml[data-theme]). The UI usesantialiasedfont smoothing with 0.01em tracking on every theme - Shell
- Terminal font: bundled monospace fonts (JetBrains Mono default), default font size (8-32px slider), font weight, cursor style (bar / block / underline)
- Copy-on-select toggle (auto-copy selection to clipboard), OSC 52 clipboard writes, block timestamps (elapsed-time label per command block while Ctrl+Cmd is held), block folding (gates the Toggle Block Fold shortcut and its palette entry), scrollbar marks, scrollback reflow on resize
11.10 Git & GitHub
- GitHub authentication (see 8.13), additional accounts and repository bindings (see 8.14)
- Pull requests: auto-show PR popover, hide draft / conflicting / CI-failing PRs, auto-delete on PR close
- Issues: show issues, issue filter
- Repository defaults: base branch, copy ignored files, copy untracked files (two separate toggles), setup/run/archive scripts
- Worktree defaults: storage strategy, prompt on create, delete branch on remove, auto-archive, orphan cleanup, PR merge strategy, after-merge behavior, auto-fetch interval
11.11 Expert Mode
- Expert switch in the Settings header; persisted as the UI pref
settings_expert_mode(default off) - An expert setting is hidden in basic mode only while its value equals the config default. A modified value always stays visible, so an override is never hidden
- A setting the user edits stays shown until Settings is opened again, also when it is set back to the default in the same open. A value that differs only until the page loads its config is not an edit
- Defaults come from the read-only
get_config_defaultscommand (GET /config/defaults). While they are unknown, or a lookup fails, the setting stays visible - A search result for an expert setting carries an Expert badge; opening it opens the page, reveals the setting and scrolls to it. The reveal lasts until Settings is opened again and does not change the switch
- Expert settings per page: General (auto-standby timeout, content indexing, update channel); Notifications (master volume, audio output device); Terminal (shell, font weight, OSC 52 clipboard, block folding, scrollbar marks, scrollback reflow); Git & GitHub (auto-delete on PR close, copy ignored files, copy untracked files, storage strategy, auto-archive merged, orphan cleanup, after-merge behavior, auto-fetch interval, the “Add another GitHub account” button while no additional account exists); Agents (collect project progress, and per agent idle-close delay, auto-retry, native status signals, install hooks globally, track intent, collect progress, suggested follow-ups, headless command template, Claude environment flags); Voice (long-press threshold, auto-send, input device, level gate, speech confidence gate, hold-back, notify model on hands-free, start notice); MCP (collapse tools); Remote Access (port, session token duration, IPv6). Full table: Settings → Expert Mode
- Every section keeps at least one basic setting, so no heading and no page hides in basic mode
12. Persistence
12.1 Rust Config Backend
All data persisted to platform config directory via Rust:
app_config.json— general settingsnotification_config.json— sound settingsui_prefs.json— sidebar visibility/widthrepo_settings.json— per-repo worktree/script settingsrepositories.json— repository list, groups, branches (shared by debug and release builds, like every other file here)agents.json— per-agent run configurationsprompt_library.json— saved promptsnotes.json— ideas panel datadictation_config.json— dictation settings.tuic.json— repo-root team config (read-only from app, highest precedence for overridable fields)claude-usage-cache.json— incremental session transcript parse cache
12.2 Hydration Safety
save()blocks beforehydrate()completes to prevent data loss
13. Cross-Platform
13.1 Supported Platforms
- macOS (primary), Windows, Linux
13.2 Platform Adaptations
Cmd↔Ctrlkey abstractionresolve_cli(): probes well-known directories when PATH unavailable (release builds)- Windows:
cmd.exeshell escaping,CreateToolhelp32Snapshotfor process detection - IDE detection:
.appbundles (macOS), registry entries (Windows), PATH probing (Linux)
14. System Features
14.1 Auto-Update
- Check for updates on startup via
tauri-plugin-updater - Stable, Beta and Nightly channels. Beta automatically checks the next beta and final stable; beta downloads open the versioned release page, and stable updates install in-app. Fresh beta installations default to Beta; saved channel choices stay unchanged
- Status bar badge with version
- Download progress percentage
- One-click install and relaunch
- Menu: Check for Updates (app menu and Help menu)
14.2 Sleep Prevention
- With prevention disabled, an agent run lasting at least one minute shows dismissible idle-sleep guidance; short runs and plain shells do not. The guidance does not inspect battery or OS sleep policy. Dismissal persists in this client.
- Backend-owned
keepawakeassertions cover active turns, meaningful background descendants, detachedtuic bgrunners and live managed agents markedkeep_open - Sleep prevention does not depend on WebView activity; hidden, unloaded or blocked views cannot release it
- The user setting still disables inhibition; idle agents without live work and closed sessions do not retain the hold
- Configurable in Settings
14.3 Splash Screen
- Branded loading screen on app start
14.4 Confirmation Dialogs
- In-app
ConfirmDialogcomponent replaces native Tauriask()dialogs - Dark-themed to match the app (native macOS sheets render in light mode)
useConfirmDialoghook provides aconfirm()→Promise<boolean>API- Pre-built helpers:
confirmRemoveWorktree(),confirmCloseTerminal(),confirmRemoveRepo() - Keyboard support:
Enterto confirm,Escapeto cancel
14.5 Error Handling
- ErrorBoundary crash screen with recovery UI
- WebGL canvas fallback (graceful degradation)
- Error classification with backoff calculation
14.6 MCP & HTTP Server
MCP session output reports continuation instructions for retained output pages.
Text pages use scrollback positions; raw pages use source-byte positions and mask
secrets before slicing. Local HTTP and remote MCP retain the same paging contract.
Buffer eviction is reported; it does not create another output store.
- REST API on localhost for external tool integration
- Exposes terminal sessions, git operations, agent spawning
- WebSocket streaming, Streamable HTTP transport
- Used by Claude Code, Cursor, and other tools via MCP protocol
tuic-bridgeships as a Tauri sidecar; auto-installs MCP configs on first launch for Claude Code, Cursor, Windsurf, VS Code, Codex, Grok, opencode, Droid, goose and pi — but only for the ones actually installed on the machine. Zed, Amp and Gemini keep MCP inside their generalsettings.jsonand wait for an explicit install. JSON configs are edited member-by-member, never reserialized, so comments, key order and indentation survive (see MCP auto-install)- Local connections use Unix domain socket (
<config_dir>/mcp.sock) on macOS/Linux or named pipe (\\.\pipe\tuicommander-mcp) on Windows; TCP port reserved for remote access only - Unix socket lifecycle is crash-safe: RAII guard removes the socket file on
Drop; bind retries 3× (×100 ms) removing any stale file before each attempt; liveness check uses a realconnect()probe so a dead socket from a crashed run never blocks MCP tool loading
14.7 Cross-Repo Knowledge Base
- Knowledge base functionality is available via the
mdkbMCP upstream server (configure in MCP Upstreams settings) - Provides hybrid BM25 + semantic search across docs, code, symbols, and memory
- Call graph queries (calls, callers, impact analysis) via
code_graphtool - Requires
mdkbbinary on PATH (installed separately)
14.8 Code Intelligence (MDKB integration)
- Go-to-definition: Cmd+Click on symbols in the editor navigates to the definition via
mdkb_goto_definition. Holding Cmd (macOS) / Ctrl underlines the symbol under the cursor (cm-hover-link) as a click affordance; the underline clears on release or when the pointer leaves the editor, and its position is remapped through edits so it never goes stale - Find references: Shift+F12 finds all callers of a symbol via
mdkb_references(uses code_graph callers query) - Symbol outline: file-level symbol tree via
mdkb_outline(functions, types, structs) - Install/uninstall managed from Settings → General → Code Intelligence
is_available()checks binary existence on disk (not cached path) — survives external uninstalls- The daemon ping version must match the installed binary; an older detached daemon is restarted automatically after upgrades
- Homebrew-managed installs show
brew uninstall mdkbguidance instead of silent failure - Graceful fallback: all commands return empty results when mdkb is unavailable
- A daemon that goes silent cannot wedge the app: every request/response exchange is bounded (10 s), the liveness probe runs on a shorter 2 s leash, and a connection cut short by a deadline is abandoned rather than reused — a half-read stream would answer the next question with the previous reply
- The shared daemon lock is held only either side of a query, never across it, so one stalled call cannot make unrelated Code Intelligence calls wait out its deadline. Daemon startup stays exclusive on purpose, so two callers never race two spawns
14.9 macOS Dock Badge
- Badge count for attention-requiring notifications (questions, errors)
14.9 Tailscale HTTPS
- Auto-detects Tailscale daemon and FQDN via
tailscale status --json(cross-platform) - Headless daemon refreshes Tailscale Host trust every 30 seconds, recovering late startup and removing stale names after rename or stop
- Provisions TLS certificates from Tailscale Local API (Unix socket on macOS/Linux, CLI on Windows)
- HTTP+HTTPS dual-protocol on same port via
axum-server-dual-protocol - Graceful fallback: HTTP-only when Tailscale unavailable or HTTPS not enabled
- QR code uses
https://scheme with Tailscale FQDN when TLS active - Background cert renewal every 24h with hot-reload via
RustlsConfig::reload_from_pem() - Session cookie gets
Secureflag on TLS connections - Settings panel shows Tailscale status with actionable guidance
15. Keyboard Shortcut Reference
Terminal Compose starts at one control line, grows with newlines and wrapping up to 96px, and scrolls longer drafts internally. Clearing or sending restores one line.
Terminal Compose uses Enter to send, Ctrl+Enter or Shift+Enter for a new line, and Shift+Ctrl+Enter to queue. These editor-local shortcuts use the Control key on every platform and are not global keybindings.
Terminal
| Shortcut | Action |
|---|---|
Cmd+T | New terminal tab |
Cmd+W | Close tab / close active split pane |
Cmd+Shift+T | Reopen last closed tab |
Cmd+1–Cmd+9 | Switch to tab by number |
Ctrl+Tab / Ctrl+Shift+Tab | Next / previous tab |
Cmd+Ctrl+Backspace | Return to last terminal — toggles back to the previously focused terminal, switching repo/branch if needed (focus-last-terminal) |
Cmd+Alt+← / Cmd+Alt+→ | Terminal history back / forward — walks the last 10 activated terminals across repos/branches, browser-style: stepping does not reorder the history and activating another terminal drops the forward part; closed terminals leave it. When a model-driven open (ui tab, file or markdown open) moves the view to another repository, the first Back returns to the terminal that was on screen; a same-repository open adds no step. The toolbar has matching arrow buttons (disabled at the ends, tooltip names the target). The Mobile Sessions screen has a sort button (Default / Recent) next to the search lens; Recent orders by the sessions last opened on that device (history-back, history-forward) |
Cmd+U | Jump to next waiting terminal — cycles to the next terminal awaiting input (agent question/error) across all repos/branches, switching context as needed; does nothing if none are waiting (jump-waiting-terminal) |
Cmd+L | Clear terminal |
Cmd+Shift+L | Refresh terminal (fix glyphs) |
Cmd+C | Copy selection |
Cmd+V | Paste to terminal |
Cmd+Home | Scroll to top |
Cmd+End | Scroll to bottom |
Down (while scrolled back) | Scroll to bottom. The key is not sent to the terminal; at the bottom, Down goes to the program as usual |
Shift+PageUp | Scroll one page up |
Shift+PageDown | Scroll one page down |
Cmd+Shift+R | Run saved command |
Cmd+R | Reload active web/preview tab |
Cmd+Shift+. | Toggle block folding |
Cmd+Shift+Up | Jump to previous block |
Cmd+Shift+Down | Jump to next block |
Cmd+Shift+B | Toggle block-scoped search |
Zoom
| Shortcut | Action |
|---|---|
Cmd+= | Zoom in (+2px) |
Cmd+- | Zoom out (-2px) |
Cmd+0 | Reset zoom |
Cmd+Shift+= / Cmd+Shift+- | Zoom all open terminal, Markdown, and code editor tabs in / out |
Cmd+Shift+0 | Reset zoom in all open terminal, Markdown, and code editor tabs |
Split Panes
| Shortcut | Action |
|---|---|
Cmd+\ | Split vertically |
Cmd+Alt+\ | Split horizontally |
Alt+←/→ | Navigate vertical panes |
Alt+↑/↓ | Navigate horizontal panes |
Cmd+Shift+Enter | Maximize / restore active pane |
Cmd+Alt+Enter | Focus mode (hide sidebar, tab bar, panels) |
AI
| Shortcut | Action |
|---|---|
Cmd+Alt+A | Toggle AI Chat panel (toggle-ai-chat) |
Ctrl+S (AI Chat composer) | Park, restore, or swap the current prompt draft |
Cmd+Enter (panel focused) | Send message |
Esc (panel focused) | Cancel in-flight stream |
Panels
| Shortcut | Action |
|---|---|
Cmd+[ | Toggle sidebar |
Cmd+Shift+D | Toggle Git Panel |
Cmd+Shift+M | Toggle markdown panel |
Cmd+Alt+N | Toggle Ideas panel |
Cmd+E | Toggle file browser |
Cmd+O | Open file… (picker) |
Cmd+N | New file… (picker for name + location) |
Cmd+P | Command palette |
Cmd+, | Open settings |
Cmd+? | Toggle help panel |
Cmd+Shift+K | Prompt library |
Cmd+J | Task queue |
Cmd+Shift+E | Error log |
Cmd+Shift+W | Worktree manager |
Cmd+Shift+A | Activity dashboard |
Cmd+Shift+M | MCP servers popup (per-repo) |
Cmd+I | Toggle compose panel |
Cmd+Alt+L | Toggle outline panel |
Git
| Shortcut | Action |
|---|---|
Cmd+B | Quick branch switch (fuzzy search) |
Cmd+Shift+D | Git Panel (opens on last active tab) |
Cmd+G | Git Panel — Branches tab |
Branches Panel (when panel is focused)
| Shortcut | Action |
|---|---|
↑ / ↓ | Navigate branches |
Enter | Checkout selected branch |
n | Create new branch |
d | Delete branch |
R | Rename branch (inline edit) |
M | Merge selected into current |
r | Rebase current onto selected |
P | Push branch |
p | Pull current branch |
f | Fetch all remotes |
File Browser (when focused)
| Shortcut | Action |
|---|---|
↑/↓ | Navigate files |
Enter | Open file / enter directory |
Backspace | Go to parent directory |
Cmd+C | Copy file |
Cmd+X | Cut file |
Cmd+V | Paste file |
Cmd+Shift+F | Open file browser and activate content search |
Code Editor (when focused)
| Shortcut | Action |
|---|---|
Cmd+= / Cmd+- / Cmd+0 | Zoom editor text in, out, or reset |
Cmd+F | Find |
Cmd+G | Find next |
Cmd+Shift+G | Find previous |
Cmd+H | Find and replace |
Cmd+S | Save file |
Ideas Panel (when textarea focused)
| Shortcut | Action |
|---|---|
Enter | Submit idea |
Shift+Enter | Insert newline |
Cmd+V / Ctrl+V | Paste image from clipboard |
Escape | Cancel edit mode |
Quick Switcher
| Shortcut | Action |
|---|---|
Hold Cmd+Ctrl | Show quick switcher overlay |
Cmd+Ctrl+1-9 | Switch to branch by index (in the Global Workspace: switch to tab N; only the tab hints show) |
Voice Dictation
| Shortcut | Action |
|---|---|
Hold F5 | Push-to-talk (configurable) |
Mouse Actions
| Action | Where | Effect |
|---|---|---|
| Click | Sidebar branch | Switch to branch |
| Double-click | Sidebar branch name | Rename branch |
| Double-click | Tab name | Rename tab |
| Right-click | Tab | Tab context menu |
| Right-click | Sidebar branch | Branch context menu |
| Right-click | Sidebar repo ⋯ | Repo context menu |
| Right-click | Sidebar group header | Group context menu |
| Right-click | File browser entry | File context menu |
| Middle-click | Tab | Close tab |
| Drag | Tab | Reorder tabs |
| Drag | Sidebar right edge | Resize sidebar |
| Drag | Panel left edge | Resize panel |
| Drag | Split pane divider | Resize panes |
| Drag | Repo onto group | Move repo to group |
| Click | Status bar CWD path | Copy to clipboard |
| Click | PR badge (sidebar/status) | Open PR detail popover |
| Click | CI ring | Open PR detail popover |
| Click | Toolbar bell | Open notifications popover |
| Click | Status bar panel buttons | Toggle panels |
| Hold | Mic button (status bar) | Record dictation |
Recording a Custom Combo
Every shortcut above is rebindable from Help > Keyboard Shortcuts (see
docs/user-guide/keyboard-shortcuts.md).
On macOS, Ctrl+Tab and F13–F20 never reach the WebView — AppKit consumes the
first for native tab cycling and simply does not forward the rest — so a
keydown listener sees nothing. src-tauri/src/native_keys.rs installs a single
NSEvent monitor that catches both and re-emits them (ctrl-tab,
native-key-down), which is what makes F13–F20 recordable for both per-action
shortcuts and the Global Hotkey. Keys macOS itself claims before the process
(F14/F15 keyboard illumination) still need remapping in System Settings.
16. Build & Release
16.1 Makefile Targets
| Target | Description |
|---|---|
dev | Start development server |
build | Build production app |
build-dmg | Build macOS DMG |
sign | Code sign the app |
notarize | Notarize with Apple |
release | Build + sign + notarize |
build-github-release | Build for GitHub release (CI) |
publish-github-release | Publish GitHub release |
github-release | One-command release |
clean | Clean build artifacts |
16.2 CI/CD
- GitHub Actions for cross-platform builds
- macOS code signing and notarization
- Linux:
libasound2-devdependency,-fPICflags - Updater signing with dedicated keys
17. Plugin System
17.1 Architecture
- The MDKB dashboard distinguishes disabled hook telemetry from zero activity and hides retained activity metrics while telemetry is off.
- Rust-owned scoped plugin settings: typed schemas, revision-checked atomic patches, write-only secret readback, five legacy migrations, reload callbacks and unload cleanup.
- Obsidian-style plugin API with 4 capability tiers
- Built-in plugins (TypeScript, compiled with app) and external plugins (JS, loaded at runtime)
- Hot-reload: file changes in plugin directories trigger automatic re-import
- Per-plugin error logging with ring buffer (500 entries)
- Capability-gated access:
pty:write,pty:read,ui:markdown,ui:sound,ui:panel,ui:ticker,ui:context-menu,ui:sidebar,ui:file-icons,ui:file-preview,net:http,credentials:read,invoke:read_file,invoke:list_markdown_files,fs:read,fs:list,fs:watch,fs:write,fs:rename,fs:scan,fs:delete,exec:cli,git:read - CLI execution API: sandboxed execution of whitelisted CLI binaries (
mdkb) with timeout and size limits - Filesystem API: sandboxed text read, base64 binary read, write, rename, list, tail-read, and watch operations restricted to
$HOME; binary reads keep a 10 MiB default and accept a per-call budget capped at 512 MiB - HTTP API: outbound requests scoped to manifest-declared URL patterns (SSRF prevention)
- Credential API: cross-platform credential reading (macOS Keychain, Linux/Windows JSON file) with user consent
- Panel API: rich HTML panels in sandboxed iframes (
sandbox="allow-scripts allow-same-origin") with structured message bridge (onMessage/send), transferable buffer ownership, and automatic CSS theme variable injection - URL tabs support external HTTPS and localhost HTTP in sandboxed frames through the permissive
default-srcCSP. Sites can still refuse embedding through their own frame policy. - Hidden plugin and URL tab iframes unload and reload when shown again, preventing background pages from blocking terminal input on the shared WebContent main thread
- Explicit
http/https/mailtoclicks in inline plugin panels and HTML previews open outside the app; blocked navigation from cross-origin dashboard frames shows a toast directing users to the tab’s Open in Browser action - Shared ticker system:
setTicker/clearTickerAPI with source labels, priority tiers (low <10, normal 10-99, urgent >=100), counter badge, click-to-cycle, right-click popover - Agent-scoped plugins:
agentTypesmanifest field restricts output watchers and structured events to terminals running specific agents (e.g.["claude"]) - Output watchers match in Rust on the PTY reader thread: the frontend pushes its pattern set (
set_plugin_output_watchers), Rust assembles and cleans the lines, and the WebView is only woken for a line that matched. Rust is the only line assembler, so a watcher that registers mid-line still sees that line whole. A pattern the Rustregexcrate cannot express (lookaround, backreferences) is reported back and keeps matching in the WebView, which then receives every line - Watcher sets are per client (max 8): a desktop window and a browser tab keep independent sets, and browser/PWA clients receive watcher matches as well
- Plugin manifest fields use camelCase (
minAppVersion,agentTypes,contentUri) — matches Rust serde serialization
17.2 Plugin Management (Settings > Plugins)
- Installed tab: List all plugins with enable/disable toggle, logs viewer, uninstall button
- Browse tab: Discover plugins from the community registry with one-click install/update
- Enable/Disable: Persisted in
AppConfig.disabled_plugin_ids - ZIP Installation: Install from local
.zipfile or HTTPS URL - Folder Installation: Install from a local folder (copies plugin directory into plugins dir)
- Uninstall: Removes plugin directory (confirmation required)
17.3 Plugin Registry
- Remote JSON registry hosted on GitHub (
tuicommander-pluginsrepo) - Fetched on demand with 1-hour TTL cache
- Version comparison for “Update available” detection
- Install/update via download URL
docx-previewplugin: previews Word.docx/.dotxfiles as clean HTML using Mammoth.jsxlsx-previewplugin: previews Excel.xlsx/.xlsm/.xlsb/.xlsand OpenDocument.odsspreadsheets as sortable per-sheet tables using SheetJSsqlite-viewerplugin: opens.db,.sqlite,.sqlite3,.db3, and.s3dbfiles in a self-contained sql.js/WebAssembly viewer with schema and index browsing, per-column filters, sorting, native pagination, bounded read-only queries, visual query plans, CSV copy, and explicit atomic inline-edit saves for primary-key tables
17.4 Deep Links (tuic://)
tuic://install-plugin?url=https://...— Download and install plugin (HTTPS, or plain HTTP fromlocalhost/loopback; confirmation dialog)- CLI
tuic <dir>/tuic open <dir>and MCPrepo action=addregister and activate directories through the running server, without an OS URL handler; repeat adds preserve existing workspaces and terminals. MCPui tabrejectstuic://open-repoand directs callers torepo add. tuic://open-repo?path=/path— Activate a repo already in the sidebar; a folder that is not in it yet is added after one confirmation (native deep-link flow)tuic://settings?tab=plugins— Open Settings to specific tab- Markdown document links using
tuic://open/<path>open Markdown in a document tab, images and HTML in a preview, and directories in the file browser. Desktop and mobile/browser views support absolute paths across repositories and worktrees. Local desktop and loopback browser clients can open unregistered local files; network external-text reads retain their registered-repository boundary and HTTP authentication. tuic://open/<path>— Open a Markdown file in a native tab. MCPui action=tabalso accepts absolute Markdown paths outside registered repositories; the iframe SDK keeps its repository path validation.- Absolute file URLs use
tuic://open//Users/name/file.mdortuic://edit//home/name/file.rs. Redundant leading slashes normalize to one filesystem root before tab creation, including iframe SDK and mobile output links; relative paths and Windows drive paths keep their existing meaning. - Focused absolute
tuic://open/tuic://edittargets switch to their owning registered repository so the native file tab remains visible; background opens preserve the current repository - MCP
ui action=tabtabs, including external native files and HTML/URL previews, bind to the calling session’s registered repository when known. Focused opens switch there so the tab stays reachable; background opens preserve the current view. Unpinned tabs hide in other repositories and return when their repository is selected; pinned tabs remain visible across repositories. - Native MCP file tabs use the supplied
idfor identity: different ids remain separate even when they target the same path, and repeating an id updates that tab. Tabs remain visible when another terminal is selected in the same repository, including before a workspace is chosen. tuic://terminal?repo=<path>— Open terminal in repo (iframe SDK only)tuic://cmd/{tool}/{action}?{params}— MCP gateway for external automation (scripts, Shortcuts, browser pages). Routes to the same tool/action handlers as the MCP server. Gating is default-deny:- Read-only / notify actions (e.g.
session/list,session/status,repo/list,agent/inbox,ui/toast) run silently without a dialog - Destructive or unknown actions (anything not in the safe list) require a confirmation dialog before executing — prevents a malicious page from acting unattended
config/saveanddebug/invoke_jsare blocked entirely and never execute even with user confirmation Source:src/deep-link-handler.ts(SAFE_COMMANDS,BLOCKED_COMMANDS); Rust backstop:deep_link_mcp_callinsrc-tauri/src/lib.rs
- Read-only / notify actions (e.g.
17.4.1 TUIC SDK (window.tuic)
- Injected automatically into every plugin iframe (inline and same-origin URL mode)
- Feature detection:
if (window.tuic)—tuic.versionreports SDK version - Files:
tuic.open(path, {pinned?}),tuic.edit(path, {line?})(both accept an absolute path outside registered repositories as an external file),tuic.getFile(path): Promise<string> - External URLs:
tuic.openUrl(url)acceptshttp,https, andmailtoonly - Path resolution: relative paths resolve against the asking panel’s repository; absolute paths match longest repo prefix;
../traversal outside repo root is blocked - Repository:
tuic.activeRepo()returns active repo path;tuic.onRepoChange(cb)/tuic.offRepoChange(cb)for live updates - Terminal:
tuic.terminal(repoPath)— open terminal in repository - UI feedback:
tuic.toast(title, {message?, level?, sound?})— native toast notifications with optional sound (info blip, warn double-beep, error descending sweep);tuic.clipboard(text)— copy to clipboard from sandboxed iframe - Messaging:
tuic.send(data)/tuic.onMessage(cb)— bidirectional host↔plugin communication;PanelHandle.sendreaches SDK listeners through the host-message envelope - Plugin lifecycle: panel tabs and bridges close on plugin unload; state observers receive active branch, shell state and awaiting-input transitions
- HTTP scope:
net:httprequires a non-emptyallowedUrlsmanifest declaration - Theme:
tuic.theme— current theme as JS object (camelCase CSS vars);tuic.onThemeChange(cb)for live updates <a href="tuic://open/...">and<a href="tuic://terminal?repo=...">links intercepted automaticallydata-pinnedattribute on links sets pinned flag- Interactive test page:
docs/examples/sdk-test.html(seedocs/tuic-sdk.mdfor launch instructions)
17.5 Preinstalled External Plugins
- Plan Tracker — Detects agent plan files from structured events and opens them as background tabs
- Stories Ticker — Shows the active repository’s open story count in the shared status ticker
- Both are seeded once during migration, then remain independently uninstallable and updateable through the plugin catalog
Note: Claude Usage Dashboard was promoted from a plugin to a native SolidJS feature (see section 6.6). It is managed via Settings > Agents > Claude > Usage Dashboard toggle.
17.6 Example External Plugins
See examples/plugins/ for reference implementations:
hello-world— Minimal output watcher exampleauto-confirm— Auto-respond to Y/N promptsci-notifier— Sound notifications and markdown panelsrepo-dashboard— Read-only state and dynamic markdownreport-watcher— Generic report file watcher with markdown viewerclaude-status— Agent-scoped plugin (agentTypes: ["claude"]) tracking usage and rate limitswiz-kanban— Wiz framework plugin: kanban board for managing the workflow of plans, stories, and reviews with drag-and-drop
17.7 Claude Wakeup Plugin
Agent-scoped plugin (agentTypes: ["claude"]) that wakes Claude Code when it stalls without asking a question. Ships in plugins/claude-wakeup/.
- Idle detection: After 20 s of shell idle with no pending question, no active sub-tasks, and no choice prompt, sends a verification message to the agent
- Typing suppression: Every busy→idle transition resets the idle clock, so keystroke-generated shell-state blips prevent false wakes
- Done detection (primary): Watches the busy-cycle duration after a wake — short cycle (<8 s) = agent acknowledged (“done”), long cycle (≥8 s) = agent continued working
- Done detection (secondary): OutputWatcher fast-path for agents that emit a clean
doneline - Disarm/re-arm: Disarms after confirmed done; re-arms only when the user gives new input after the disarm timestamp and the agent works >10 s
- Limits: Max 3 wakes per stall, max 12 per session lifetime
- Dashboard: Markdown stats panel with wake counts, done rate, active session state, and history
- Pause/Resume: Via Activity Center toggle (transient, not persisted)
- Configuration:
data/config.json—idleThresholdMs,maxWakes,maxWakesEver,doneMaxBusyMs,checkIntervalMs,minBusyDurationMs,questionStaleMs,pendingTimeoutMs - Capabilities:
pty:write,pty:read,ui:ticker,ui:markdown
18. Mobile Companion UI
Mobile resume diagnostics retain a bounded per-tab lifecycle trail and upload the prior abnormal document automatically after the next boot. Log writes acknowledge HTTP 204 responses. This collects evidence; it does not claim to fix the reported iPhone grey screen. See the remote-access guide for storage limits.
The session overflow menu has a Markdown section with the file tabs open on the desktop for the session repository. Each entry shows its title and relative path and opens the existing mobile Markdown viewer. Desktop opens and closes update the list through SSE; worktree files retain their original checkout.
Waiting terminal ego questions show Input, including narrow terminals whose selector footer wraps mid-word. Native selectors open automatically when a new question arrives or a waiting session opens. Tap the question icon in the session header to hide or reopen the full question and its wrapping options. A selection_required reply refusal reopens the controls and preserves the draft without sending an answer. Single-choice submits one option; multiple-choice toggles options until Submit answers; free-text uses the composer. The card overlays the terminal without reserving rows. Native choice dialogs hide suggested actions while their answer controls are open. Other waiting reports show their current suggested actions instead of generic Yes/No confirmations.
Phone-optimized progressive web app for monitoring AI agents remotely. Separate SolidJS entry point (src/mobile/) served by the existing HTTP server at /mobile.
Both mobile composers share the + menu, text box with browser dictation, and Send layout. Attach file and Take photo use separate pickers. Terminal Queue keeps its long-press shortcut; Commands (/) inserts a slash in agent terminals. AI Chat offers Park/Restore/Swap draft, plus Queue and Stop while busy. Unsupported actions are hidden. Menus close on outside tap or Escape and use 44 px action targets. Desktop Chat controls and Ctrl+S are unchanged.
18.1 Architecture
- Separate Vite entry point (
mobile.html+src/mobile/index.tsx) - Shares transport layer, stores, and notification manager with desktop
- Sessions opens by default; the five bottom tabs are Sessions, Chat, Files, Progress, and Activity. Settings opens from the app-bar overflow.
- Chat opens the cross-repository chat directly. Read ego’s streamed ACP conversation with shared transcript cards and collapsed activity, answer pending interactions, and switch among titled saved conversations.
- Server-side routing:
/mobile/*→mobile.html, everything else →index.html - On iPad, the root URL opens mobile by default. Settings → Open Desktop UI remembers the choice on that device; the desktop banner’s Switch link clears it and returns to mobile. The installed PWA scope includes both interfaces.
- Session state accumulator enriches
GET /sessionswith question/rate-limit/busy state - SSE endpoint (
/events) and WebSocket JSON framing for real-time updates
18.2 Sessions Screen
- Hero metrics header: Working, Idle and Awaiting counts with large tabular-nums display. Counts share the row badge state and Working hold across poll updates. Sub-tasks rows count as Working; Finished, Error and Rate Limited rows count in none of these totals. Exited sessions leave the live list.
- Search button at the top right filters the live session list by name, repository path, worktree path, branch, or agent type; closing search restores the full list
- Waiting sessions appear first; the list preserves order within waiting, idle-agent, and shell groups. Session names keep their original casing, and busy state reads “Working”.
- The new-session sheet selects Claude Code, Codex, or Gemini, searches repositories, and opens the created agent session. Its close button and backdrop dismiss the sheet.
- Question banners identify the session and repository; the AWAITING tile is the only awaiting total and opens the first waiting session.
- Elevated session cards with agent icon, status badge, project/branch, relative time
- Rich sub-rows per card: agent intent (crosshair icon) or last prompt (speech bubble), current task (gear icon) with inline progress bar, usage limit percentage
- Question state highlighted via inset gold box-shadow
- Pull-to-refresh spinner via touch events
- Loading skeletons during initial data fetch
- Empty state with instructional hint
- Tap card to open session detail
18.2.1 Files Screen
- Select a configured repository and browse its directories one level at a time
- Repository paths truncate from the left and reveal the complete path on long press; normal folders precede hidden folders
- Search recursively for files by name or repository-relative path from the tree
- File view and editor keep Back, file name, and Edit or Cancel/Save on one row with 44 px buttons; the editor fills the remaining height and soft-wraps lines
- From a session header’s overflow menu, open Files at that session’s worktree root, or at the registered repository containing its working directory; Back returns to the still-mounted session and preserves its output and draft
- Markdown paths in session output open here through the desktop terminal-path resolver. Absolute, relative,
file://, andtuic://open//references are supported, including line numbers. Files outside registered repositories open from their own folder; directories outside them are refused with a toast naming the path. - Show an explicit error when the session has no repository path, no registered repository contains its working directory, or the directory request fails
- Open
.mdfiles as rendered Markdown using the desktop’s sharedContentRenderer; other UTF-8 text files remain plain text - Tap a task-list checkbox (a 44 px target around the box) in a rendered
.mdfile to toggle- [ ]/- [x]/- [~]on disk; tap a paragraph, heading or list item to select it and add a comment, saved as the same<!--tweak:block:...-->/itemmarker the desktop Markdown tab writes - Every mobile write (checkbox, comment, Edit → Save) goes through
write_file_if_unchanged: if the file changed on disk since it was read, nothing is written, the view reloads and a notice asks to repeat the change (an edit draft or comment draft is kept) - Switch from View to Edit for source changes, then save and return to View
- Refuse files over 1 MB before reading and show a clear message for binary or non-text files
18.3 Session Detail Screen
- Mirrored sessions stream through the connected desktop server to their owning daemon, so the phone stays on its HTTPS origin; the session kill action reaches that owner too
- Live output via WebSocket with
format=log(VT100-extracted clean lines, auto-scrolling, 500-line live tail). Scrolling up or touching retains the reading window and fetched history; the next log update after returning to the bottom restores the live tail. - HTTP and HTTPS links in output open in the phone’s external browser; Markdown path controls open the Files editor.
- Mobile CLI preserves active dialog options and interaction footers, including startup trust, external-file imports and command permissions, without dialog-title exceptions.
- Claude
/resumeretains its full session list and filtered or no-match search results in both initial HTTP output and live log-WebSocket frames; key-bar arrows and Enter operate the real terminal picker - Source-width prose rows are rejoined before the phone wraps them; short lines, lists, and box-drawing blocks retain their layout
- When a mobile output line wraps, its continuation keeps the line’s leading spaces or tabs; unindented prose and horizontally scrolling box-drawing blocks retain their layout
- Claude tool-call status dots reserve one text cell in both visible and blank pulse frames; wrapped continuations retain the same hanging indent through the green completion frame
- Semantic colorization: log lines are color-coded by type (info, warning, error, diff +/-, file paths) via
classifyLine()utility - Search/filter in output: text search bar filters visible log lines in real time
- Compact 56 px header: desktop agent logo with a state dot, session display name, repository/branch, state, elapsed activity time, tasks count, and an overflow menu. Tapping the name reveals intent and current task in a transient sheet. Tasks opens current work and intent history; overflow Progress opens this session’s filtered journal in a bottom sheet. Files, output search, Ideas, quick commands, usage, copy ID, and terminate remain in overflow. The terminal keeps its height because these panels overlay it.
- Error bar (red tint) when
last_erroris set - Rate-limit bar (orange tint) with live countdown timer (
formatRetryCountdown) - Suggest follow-up chips: horizontal scrollable pills from
suggested_actions, tap to send - Slash menu overlay: the keybar
/inserts at the composer selection through the same input path as typing; both sync to the PTY and show only detected agent menu entries with navigation. Surrounding draft text is preserved. Removed commands are hidden, and the close button dismisses the menu. Picking a command fills the input; submitting waits for the agent’s Enter gap - Quick-action chips: Yes, No, y, n, Enter, Ctrl-C
- Mobile terminal queue: CLI and Chat share the pending prompt list. An older host without the queue-read endpoint does not show an error when there is no pending count or accepted local enqueue. Other queue-read failures remain visible and retryable.
- TerminalKeybar: 44 px tall, horizontally scrollable row of
/, Ctrl, Tab, Esc, arrow and Enter keys above the main input, with no visible scrollbar. Ctrl opens a menu for Ctrl+C, Ctrl+B, Ctrl+D and Ctrl+Enter; Ctrl+C and Ctrl+D are danger-coloured. A choice sends once and closes the menu; an outside tap or Escape dismisses without sending. Ctrl+Enter follows the agent registry: CSI-u submits in Claude Code and inserts a newline in OpenCode; LF supplies the newline fallback for Codex, Goose, Grok and pi; CSI-u steers a busy turn in current ego. Uninstalled agents use documented newline fallbacks or conservative CSI-u; seedocs/evidence/ctrl-menu-1660/README.md. When the agent is awaiting input without native choices or suggested actions, it adds Yes/No quick-reply buttons. Current suggested actions take priority over these generic confirmations without clearing the Input state. Tab and Up/Down still reach a waiting terminal picker when no parsed choices exist, without importing picker text into a local answer draft. The composer input and Send button also have 44 px touch targets. After the session ends, the keybar and composer are disabled and the stale status badge is hidden - CLI command widget: agent-specific quick commands (e.g.,
/compactfor Claude Code and/statusfor Codex) accessible via expandable button - Text command input with 16px font (prevents iOS auto-zoom),
inputmode="text" - Offline retry queue:
write_ptycalls that fail due to network disconnection are queued and retried when connectivity resumes - Back navigation to session list
- Header Files button opens the session repository without going through the repository picker
18.4 Question Banner
- Persistent overlay when any session has
awaiting_inputstate - Shows agent name, truncated question, Yes/No quick-reply buttons
- Visible on all screens, between top bar and content
- Stacks multiple questions
18.5 Activity Feed
- Chronological event feed grouped by time (NOW, EARLIER, TODAY, OLDER)
- Local 24-hour timestamps, minute-scale run durations, and singular block counts
- Hydrates persisted activity from the server when the mobile tab opens; dismissed items stay hidden and current live items remain visible
- Throttled grouping: items snapshot every 10s to prevent constant reordering with multiple active sessions; new items/removals trigger immediate refresh
- Sticky section headers, tap to navigate to session
18.6 Session Management
- Session kill: swipe or long-press a session card to kill/close the PTY session
- New session: create a new PTY session from the sessions screen (optional shell/cwd selection)
- Progress: lists projects with journal entries by recent activity, then shows and switches their saved entries without a desktop repository selection
- Long Progress messages collapse to four lines with a More/Less control on mobile
18.7 Settings
- Connection status: connectivity indicator with real-time Connected/Disconnected state
- Server URL display
- App and server versions, plus a persistent Dark/Light choice using desktop theme colors and a separate server-side mobile preference
- Notification sound toggle (localStorage-persisted)
- Open Desktop UI link
18.8 PWA Support
- Mobile session attachments use a bare icon on the left. Smaller mic and Send controls sit inside the input border on the right; compact gaps preserve draft width.
- Mobile session and AI Chat composers accept camera photos and files from one
picker. Binary files stream to
attachments/<session>/under TUIC’s data directory. Uploads never create repository files or edit.git/info/exclude. Claude gets--add-dirand Gemini gets--include-directories. Gemini uses a session-owned trusted-folders overlay that preserves existing trust decisions and trusts only this upload directory; global Gemini settings stay unchanged. Codex and Grok need no extra flag. Ego PTY launches get--read-only-dirfor this directory, including confined runs; no stored ego configuration changes. - Close, kill and process exit delete that session’s uploads. Startup removes session directories whose recorded owner process is provably dead. Live and unknown owners are preserved; resumed tabs get fresh PTY directories and grants. Old attachment references in a resumed transcript are unavailable and must be uploaded again. Generated old grants are removed from saved launch commands.
- An agent started before attachment grants were provisioned receives a clear
upload error asking for a new session. Absolute binary paths bypass shell
shims; use TUIC’s structured agent launch to receive its directory grant.
Custom wrapper binaries keep their arguments without added harness grant flags.
A wrapper that calls Claude/Gemini/ego by name uses the inherited shell shim; an
absolute harness hop must arrange its own read access. Disabling launch marker
instructions does not disable the Claude directory grant.
Typed ego commands receive the same read-only directory grant. Structured ego
runandresumelaunches receive the grant after the subcommand so the CLI does not interpret the subcommand as a prompt. - ACP binary uploads are scoped to the attached conversation and removed on detach or connection settlement (including EOF). Ego over ACP currently rejects extra read directories: the composer displays a notice that the stored path requires an existing ego profile root. Inline ACP images keep their native image-content transport and do not need a filesystem grant.
- Existing repository
.tuic/attachments/directories and local excludes are untouched. You can remove these old directories and exclude entries by hand. - Installed Android Chrome PWAs accept shared files through the manifest share target and stage them in AI Chat. Safari on iOS has no Web Share Target support.
- Web app manifest (
mobile-manifest.json) with standalone display mode - iOS Safari and Android Chrome Add to Home Screen support
apple-mobile-web-app-capablemeta tags- PNG icons (192x192, 512x512) for PWA installability
18.8.1 Push Notifications
- Web Push from TUICommander directly to mobile PWA clients (no relay dependency)
- VAPID ES256 key generation on first enable; the private key is held in the OS credential vault and the public key in config
- Service worker (
sw.js) handles push events and notification clicks PushManager.subscribe()flow with user gesture (click handler) for iOS/Firefox- Push subscriptions stored in
push_subscriptions.json, survive restarts - API endpoints:
POST/DELETE /api/push/subscribe,GET /api/push/vapid-key,POST /api/push/test - Push providers: built-in Google, Mozilla, Windows and Apple hosts, plus hosts the owner adds in Settings → All Settings (
services.push.added_providers). HTTPS is required; a subscription cannot add its own provider, and removing a host stops delivery to it - Triggers: an explicit managed-agent
progress type=blockedreport (with its question text), a parsed agent question when a real title is available,PtyExit(session completed), and a still-pending ACP permission or form elicitation. A bare AskUserQuestion hook can signal awaiting without text; it does not spend the push limit before the title arrives - Deep link: notification click navigates to
/mobile/session/<id>, opening the specific session detail - ACP interaction pushes link to
/mobile?repo=…&session=…, selecting the correct Chat conversation; answered requests and ordinary ACP activity do not push - Visible notifications use one tag per session, so a new question replaces only that session’s earlier notification; generic alerts keep a separate shared tag
- Delivery gate: push is sent when the desktop window is unfocused or macOS HID input has been idle for at least two minutes. An active desktop suppresses duplicate alerts; platforms without HID idle information retain the focus gate
- Silence subagent sounds and notifications also suppresses question and completion pushes from parented sessions. Exit events retain their spawn parentage until the state accumulator applies them; parent and user-started sessions are unaffected.
- Question and completion pushes share one 30-second limit per session
- ACP interaction pushes use the same 30-second limit for each conversation
- A managed session’s free-text mobile reply uses the atomic
session submitpath and retains the draft if the session rejects it. It can answer a confident question while queued automated messages stay parked. Numbered choices keep their key-input path. For Codexrequest_user_input, the session header opens the queued question; its title and options appear in the transient choice overlay, and numbered answers use one PTY key. TheOtherchoice opens Codex notes for a typed answer. The control uses the existing header, preserving all terminal rows - Claude AskUserQuestion publishes its actual choices in the same mobile overlay; a tap follows the backend’s arrow-and-Enter selection contract instead of using generic Yes/No keys
- Stale subscriptions cleaned on HTTP 410 Gone
- iOS standalone detection: shows “Add to Home Screen” guidance when not installed
- HTTP detection: shows “Push requires HTTPS (enable Tailscale)” when not on HTTPS
Mobile terminal queued prompts have a Hide action beside the existing FIFO count. The hidden panel keeps one compact count/Show control that updates as work changes. Tap it to restore Cancel and Clear all. An empty user queue resets the disclosure for new work. Server mail wakes and spawned task prompts stay out of this mobile list/count; Clear all preserves them (#2639-173b).
18.9 Notification Sounds
- Session notification sounds play only while the Sessions list and PWA document are visible; session detail, Chat, Files, Progress, Activity, and Settings remain silent. Muted transitions are tracked without replay, and deferred completions recheck visibility and the host subagent-silence setting before playback. Parented sessions follow Silence subagent sounds and notifications without replaying muted transitions. Mobile startup loads the host notification snapshot before subscribing to settings refresh, so a fresh PWA respects the saved host preference.
- Audio playback via Rust
rodiocrate (Tauri commandplay_notification_sound), replacing the previous Web Audio API approach - Eliminates AudioContext suspend issues on WebKit and works in headless/remote modes
- Native tones end on an exact zero-amplitude sample and keep the output stream alive for a 100 ms silent tail, avoiding end-of-chime clicks when CoreAudio releases a short-lived stream
- One shared 500 ms anti-spam gate covers every sound type, preventing different tones in a notification burst from overlapping; explicit Settings test playback bypasses it
- State transition detection: question, rate-limit, error, completion
- Completion notifications deferred 10s and suppressed when active sub-tasks are running (detected via
⏵⏵/››mode-line prefix) - In the desktop app, an unfocused agent question also sends a native OS notification naming its terminal. The Tauri notification plugin handles desktop delivery; macOS retains the native response handle through a desktop command so a click returns to the terminal. Permission is checked once, and focused windows and repeated notices within five seconds are suppressed
- Sounds:
question(C5→E5 chime),completion(C5→E5→G5 arpeggio),error(E4→C4),warning(A4 double-tap),info(single G5 pluck), andattention— a triangular G4→G4→E5 callback with two short knocks and a longer rise. Native and browser/PWA playback share the motif and 0.8 gain; each engine applies its own envelope. The repeated opening is immediately recognizable while the softer timbre avoids the old square buzzer’s harshness. Meant for an agent that is working unattended and is blocked on the user - Each sound has its own on/off toggle and Test button in Settings > Notifications, and all of them honour the global volume and chosen output device
- Agents can raise them over MCP:
ui action=toast sound="attention"(see 19.xuitool).sound: truestill means “the tone matchinglevel”; a name overrides it. These agent notices appear in the bell and also show a card only while their origin terminal tab is active (configurable);urgency="urgent"always shows a transient card; consecutive identical notices within five seconds play once. The sound plays through this scheme, so a muted sound stays muted no matter who asked for it
18.10 Visual Polish
-
Frosted glass bottom tabs:
backdrop-filter: blur(20px) saturate(1.8)with semi-transparent background -
Elevated card design:
border-radius: var(--radius-xl),background: var(--bg-secondary), margin spacing -
Safe-area-inset padding for notched devices
-
font-variant-emoji: texton output view — forces Unicode symbols (●, ○, ◉) to render as monochrome text glyphs instead of colorful emoji -
The mobile Ideas overlay uses the same browser dictation hook and mic as the composer. Speech replaces the selection captured at the start of a take; later hypotheses replace only that speech and keep the surrounding idea text. Dictation never saves an idea or sends it to a session. Typing or adding the idea cancels recognition. Empty takes preserve selected text; settings and failure handling match the composer. Its mic is disabled while a voice call or terminal browser dictation owns the microphone.
18.11 Standalone CSS
- Mobile human replies can answer an awaiting agent even while its shell remains busy and no question was recognized. Recognized native questions keep their direct answer controls. Rejected replies retain the draft and show the backend reason instead of a generic busy message.
- The mobile composer offers browser dictation directly next to Send (44 px touch targets) when
SpeechRecognitionorwebkitSpeechRecognitionis available. Interim and final speech append to the draft without focusing the textarea or sending; tap again to stop. Editing the draft cancels recognition and keeps the edit exactly; the mic becomes available again when the browser confirms the previous session has ended. Errors also retain the microphone claim until that confirmation, so repeated taps cannot overlap recognition sessions. Late results from the cancelled recording are ignored. Errors request cancellation through the same shutdown path, keep the draft, and show a toast. The toast is the only failure surface; no error label or failure colour remains on the composer mic. It uses the configured dictation language, falling back to the browser language for automatic detection. Browser dictation and server hands-free conversation cannot record together. Bounded, content-free lifecycle debug records carry session/take IDs to the existing diagnostic log ring for incident reconstruction. - Mobile CLI output follows the bottom through keyboard and viewport resizes while following; a reader who scrolled up keeps their position.
- Mobile CLI and Chat output show a floating down-arrow at the bottom-right of the output area while scrolled back, at least 8px above the key bar and outside the composer. It has its own touch target and never covers the key bar. Tap it to return to the latest output; it hides at the bottom and never sends a terminal key.
- Mobile Settings → Appearance offers independent Terminal and Chat font controls (10–24 px), each saved on this device. Existing defaults remain 14 px for CLI and Chat body text. Chat changes affect Session Chat and AI Chat transcripts only; composers and UI chrome do not change. CLI output rewraps locally and preserves the visible row without resizing the shared PTY.
- Mobile Settings → Input → Autocorrect and spellcheck enables keyboard correction and sentence capitalization for the terminal prompt and mobile Chat composers by default. Disable it for literal command entry. The preference stays on this device across reloads; file and code editors keep spellcheck off.
- Dictated mobile drafts survive reload without automatic terminal input. Send or the first edit reconciles the restored draft with the current terminal line, preserving cleared text without duplicating text still present.
- iPhone Home Screen availability remains device-dependent: WebKit bug 225298 documents the historical standalone restriction; Safari’s 14.1 release notes require Siri enabled. Feature detection and error handling apply; Safari tab support does not prove PWA support.
- Mobile PWA uses its own standalone stylesheet (
src/mobile/mobile.css), independent from the desktopglobal.css - Shares core color palette and border radius tokens; differs in font stacks, layout approach, and iOS-specific rules
- WebSocket state deduplication: duplicate state pushes are filtered to reduce unnecessary re-renders
19. MCP Proxy Hub
TUICommander aggregates upstream MCP servers and exposes them through its own /mcp endpoint. Any MCP client (Claude Code, Cursor, VS Code) connecting to TUIC automatically gains access to all configured upstream tools.
Forced urgent agent mail
agent action=send urgency=urgent (interrupt is an alias) uses the same
forced-steer flow as Chat Send now and Compose Steer. It sends Escape to a safe
working Claude Code, Codex or ego, confirms idle within ten seconds, then submits
the full message. Dialogs and drafts block input. Unsupported agents and timeouts
stay inbox-only, never an ordinary queued notice. Receipts report
urgent_delivered, interrupt_delivered, both failure reasons and delivery_path.
Normal mail remains non-interrupting. Interrupted tools may leave partial work,
and their child processes may continue.
19.1 Architecture
- TUIC acts as both an MCP server (to downstream clients) and an MCP client (to upstream servers)
- All upstream tools are exposed via the single
POST /mcpStreamable HTTP endpoint - Native TUIC tools (
session,agent,repo,story,workflow,automations,remote,secret,progress,ui,plugin_dev_guide,voice,settings,debug) coexist with upstream tools - Tool routing: names containing
__are routed to the upstream registry; all others handled natively
19.1.1 Lazy Tool Discovery (collapse_tools)
- Native MCP switches in Settings use domain sections, with rare and conditional tools separate. Each tool retains its own saved switch and existing permission gates.
- When
collapse_tools: true(Settings > MCP > TUIC Tools > “Collapse tools”), the full tool list is replaced with 3 meta-tools:search_tools,get_tool_schema,call_tool - Grok sessions (
clientInfo.namematchinggrok-shell-*) receive the same 3 meta-tools automatically because Grok rejects nested qualified names such astuicommander__upstream__tool; this per-session compatibility mode leaves the global setting and other clients unchanged, and the bridge restores it after TUIC reconnects - Cuts MCP context from ~35k tokens to ~500 tokens per agent turn; agent fetches schemas on demand via BM25-ranked search
- BM25 index backed by
AppState::tool_search_index(rebuilds automatically when the tool set changes) - Settings native-tool switches and descriptions come from the backend MCP registry, including disabled tools; newly registered tools appear automatically. Every native tool can be disabled.
- Capability filters (
mcp_capabilities.denied, upstream allow/deny) enforced at both discovery and dispatch time — agents cannot bypass filters by callingcall_tooldirectly - Conditional tools share discovery and call gates:
remoteneeds a connected remote server;voiceneeds enabled dictation and spoken replies;telegramneeds enabled setup, a bot alias and its private token file. Owner changes notify clients to refresh the catalogue. - Toggling fires
notifications/tools/list_changed; compatible connected clients refresh automatically, while clients that ignore the notification may require a reconnect
19.2 Tool Namespace
- Upstream tools are prefixed:
{upstream_name}__{tool_name} - Double underscore (
__) is the routing discriminator — native tool names never contain it - Tool descriptions are annotated with
[via {upstream_name}]to identify origin - Clients always see the merged tool list in a single
tools/listresponse
19.3 Supported Transports
- HTTP (legacy Streamable HTTP, revision 2025-11-25) — connects to any MCP server with an HTTP endpoint and sends
MCP-Protocol-Versionon every POST - Stdio (legacy revision 2025-11-25) — spawns local processes (npm packages, Python scripts, etc.) communicating via newline-delimited JSON-RPC
19.4 Circuit Breaker (per upstream)
- 3 consecutive failures → circuit opens
- Backoff: 1s → exponential growth → 60s cap
- After 10 retry cycles without recovery → permanent
Failedstate - Recovery: successful tool call or health check resets the circuit breaker
19.5 Health Checks
- Background task probes every
Readyupstream every 60 seconds viatools/list(HTTP) or process liveness check (stdio) CircuitOpenupstreams with expired backoff are also probed for recovery
19.6 Tool Filtering (per upstream)
- Allow list: only matching tools are exposed
- Deny list: all tools except matching ones are exposed
- Pattern syntax: exact match or trailing-
*prefix glob
19.6.1 Per-Repo Scoping
- Each repository can define an allowlist of upstream server names in
RepoSettings.mcpUpstreams - 3-layer merge: per-repo user settings >
.tuic.json(team-shareable) > defaults (null = all servers) - Quick toggle via Cmd+Shift+M popup: shows all upstream servers with status, transport, tool count, and per-repo checkboxes
- Toggling a checkbox immediately persists to repo settings (reactive, no refresh needed)
19.7 Hot-Reload
- Adding, removing, or changing upstreams takes effect on save without restarting TUIC or AI clients
- Config diff computed by stable
idfield; only changed entries are reconnected
19.8 Credential Management
- Bearer tokens stored in OS keyring (Keychain / Credential Manager / Secret Service)
- Keyring warm-up — resolved bearer token cached in memory after the first read. Health checks (every 60 s) and tool calls reuse the cache, invalidated on 401 and re-populated after token refresh. Eliminates repeated macOS Keychain permission prompts
- Config file (
mcp-upstreams.json) never contains secrets - Per-upstream credential lookup at call time
- OAuth 2.1 token sets persisted as structured JSON in the keyring (
{"type": "oauth2", "access_token", "refresh_token", "expires_at"})
19.8.1 OAuth 2.1 Upstream Authentication
- Full RFC 9728 (Protected Resource Metadata) + RFC 8414 (Authorization Server Discovery) flow with PKCE S256
UpstreamAuth::OAuth2 { client_id, scopes, authorization_endpoint?, token_endpoint? }joinsBeareras a credential type; endpoints auto-discovered from the resource server’sWWW-Authenticatechallenge when omitted- Completion via native deep link
tuic://oauth-callback?code=…&state=…— callbacks never touch the WebView console TokenManagershared across everyHttpMcpClientrefresh path with a per-upstream semaphore that defeats thundering-herd refresh. 60 s expiry margin;None expires_attreated as validUpstreamError::NeedsOAuth { www_authenticate }transitions the registry toneeds_auth; the Settings MCP page shows an Authorize button- Auto-triggered OAuth is gated behind explicit user consent; a blocking in-app confirm dialog surfaces the Authorization Server origin and prevents the pending flow from being cancelled behind the prompt
- Status values extended:
authenticating(“Awaiting authorization…”) +needs_auth - Tauri commands:
start_mcp_upstream_oauth,mcp_oauth_callback,cancel_mcp_upstream_oauth
19.9 Environment Sanitization (stdio)
- Parent environment is cleared before spawning to prevent credential leakage
- Safe allowlist re-applied:
PATH, HOME, USER, LANG, LC_ALL, TMPDIR, TEMP, TMP, SHELL, TERM - User-configured
envoverrides applied on top
19.10 SSE Events
upstream_status_changedevents emitted on status transitions (connecting, ready, circuit_open, disabled, failed)tools/list_changednotification emitted when upstream tool lists change, enabling live tool-list updates for connected MCP clients- Delivered via
GET /eventsSSE stream
19.11 Metrics (per upstream, lock-free)
call_count— total tool calls routederror_count— total failed callslast_latency_ms— last observed round-trip time
19.12 Validation
- Names: must match
[a-z0-9_-]+, must be unique - HTTP URLs: must use
http://orhttps://scheme only - Self-referential URL detection: rejects URLs pointing to TUIC’s own MCP port
- Stdio: command must be non-empty
- All errors collected (not just first) and returned to caller
- Respects sound toggle from Settings screen
20. Performance
20.1 PTY Write Coalescing
- Paint triggers coalesced per animation frame via
requestAnimationFrame(~60 repaints/sec) - High-throughput agent output (hundreds of events/sec) batched into single grid frame updates
- Reduces canvas render passes during burst output
- Flow control (pause/resume at HIGH_WATERMARK) unchanged
20.2 Async Git Commands
- All ~25 Tauri git commands run inside
tokio::task::spawn_blocking - Prevents git subprocess calls from blocking Tokio worker threads
get_changed_filesmerged from 2 sequential subprocesses to 1
20.3 Watcher-Driven Git Cache
repo_watcher(FSEvents/inotify) monitors the working tree with per-category debounce. macOS/Windows use one recursive watch; Linux splits into pruned non-recursive working-tree watches (skippingnode_modules/target/gitignored, with new dirs added dynamically) plus targeted.gitwatches (root +refs/worktrees, neverobjects/logs), to avoid inotify event storms (issue #82)- CategoryEmitter routes events to Git, WorkTree, or Config handlers with trailing debounce
.gitignore-aware filtering prevents unnecessary cache invalidations- Cache hit ~0.2ms vs git subprocess ~20-30ms
- 60s TTL as safety net for missed watcher events
20.4 Process Name via Syscall
proc_pidpath(macOS) //proc/pid/comm(Linux) replacespsfork- Eliminates ~100 fork+exec/min with 5 terminals open
20.5 MCP Concurrent Tool Calls
HttpMcpClientusesRwLockinstead ofMutex- Tool calls use read lock (concurrent); only reconnect takes write lock
20.6 Serialization
- PTY parsed events serialized once with
serde_json::to_value - Reused for both Tauri IPC emit and event bus broadcast (was serialized twice)
20.7 Frontend Bundle Splitting
- Vite
manualChunks: terminal, codemirror, diff-view, markdown as separate chunks - SettingsPanel, ActivityDashboard, HelpPanel lazy-loaded with
lazy()+Suspense - PTY read buffer increased from 4KB to 64KB for natural batching
20.8 Conditional Timers
- StatusBar 1s timer only active when merged PR countdown or rate limit is displayed
- ActivityDashboard snapshot signal uses default equality check (no forced re-render every 10s)
20.9 Profiling Infrastructure
- Scripts in
scripts/perf/: IPC latency, PTY throughput, CPU recording, Tokio console, memory snapshots tokio-consolefeature flag for async task inspection- See
docs/guides/profiling.md
20.10 Process Monitor
- Reports CPU% and resident memory (RSS) for TUIC and every child process tree, each row attributed to the session that owns it
- Agent lifecycle also classifies the owning process tree: meaningful background descendants keep
agent_state=workingwhile an input-ready terminal may remainshell_state=idle; persistentmdkb,tuic-bridge, andnode_replhelper subtrees plus Claude’s standalone timedcaffeinate -i -t <seconds>assertion are excluded by executable name or authoritative argv path. Acaffeinateinvocation that wraps a command remains meaningful. A descendant that started within 60s of the agent itself is also excluded whatever its name, which covers the daemons no list can anticipate —codex-code-mode-host, or an MCP server launched throughnpm exec; platforms that report no process age fall back to the name rule alone A ready observation waits for a newer shared process snapshot, and polling stops once no probe or background work remains - Unix: a single batched
ps -o pid,rss,%cpuquery across all PIDs (not one stat per process); Windows: per-process working-set size via the platform API - Process statistics use HTTP
GET /process/stats(JSON{ session_id, name, pid, rss_kb, cpu_pct }), whileGET /process/monitorserves a self-contained HTML dashboard with no build step or external assets. The removed MCPsession action=process_statsis not supported; clients must call the HTTP route directly. - Frontend
ProcessManagerModalopens the dashboard in-app - Use to diagnose which agent/terminal is driving high CPU or memory
20.11 Runtime Diagnostics (CPU watchdog + diagnostic mode)
-
Temporary mobile Send traces: the existing
perfDebuggate enables one metadata-onlymobile-senddebug summary per terminal-composer press, mirrored to the host log. Event retention is capped at 24 records with a five-second deadline. No draft or DOM text is recorded. See Temporary Send diagnostics (#2462-5839). -
Persistent stall evidence: selected slow refresh, UI freeze and heartbeat-gap observations use a bounded two-file metadata-only journal. The replay builder creates anonymized count-based inputs, not a reconstruction of the original stall. See Stall journal.
-
Always-on CPU watchdog (zero overhead when idle): polls
getrusage(RUSAGE_SELF)every 5s and logs a full snapshot when TUIC’s own CPU stays above 80% for 10+ consecutive seconds. PTY children (cargo, rustc, …) are separate OS processes and don’t count toward the measurement -
Sleep/wake aware: inter-tick gaps over 30s are treated as the machine having been asleep (lid closed) and skipped, so stale tokio-timer ticks after wake don’t trigger false spikes or idle cascades
-
Diagnostic mode (toggleable at runtime, off by default): emits a health snapshot every 30s and alerts on FD/thread growth trends. Each snapshot includes:
cpu_pct(TUIC self only, viaRUSAGE_SELF),children_cpu(aggregate %cpu of all PTY child process trees + the hottest individual child — note the CPU watchdog spike trigger intentionally ignores children, so a hotcargo/agent only surfaces here), thread count, FD count, PTY session count, content-index build state, semaphore permits, sessions with grid frames outstanding (session×count, from theGridGatecounters), event-bus subscriber count, andhead_emits_suppressed(repo-watcherhead-changedemits skipped by the resolved-HEAD-target guard — a climbing value signals a filesystem-event storm) -
Frontend liveness (always on, desktop only): the WebView beats every 5s from its main thread; six missed beats log
Frontend unresponsive: no heartbeat for Nsexactly once, and the return beat logs a matching recovery line. Sleep/wake re-baselines the clock so a lid-close is never charged to the frontend. Recover withPOST /debug/reload_webview— a native-side navigation that works while the JS thread does not, and keeps every PTY session (they live in the backend). Recovery remembers only a URL on the app origin, including the configured development origin. Native navigations log their trigger, action, and target URL; each frontend initialization logs the document navigation type and start time. Frontend:src/utils/frontendHeartbeat.ts; backend:src-tauri/src/frontend_liveness.rs,src-tauri/src/webview_recovery.rs -
Control via HTTP:
POST /diagnostics {"enabled":true}to toggle,GET /diagnosticsfor status,GET /logs?source=diagnosticsto read the snapshots -
Developer agent capture scenarios record installed CLIs in isolated headless debug sessions; fixture promotion preserves bytes and checks ordered expected states through the replay oracle. See
scripts/agent_capture/README.md. -
Raw PTY captures can be directed to an absolute
TUIC_CAPTURE_DIRfor isolated regression evidence; the capture status reports the chosen directory. -
Catches known failure patterns: IPC flush loops, content-index CPU saturation, a blocked or dead WebView main thread (missed heartbeats — not grid frames outstanding, which a hidden terminal produces on purpose by never acking), FD/thread leaks, and sleep/wake false-idle cascades
-
Backend:
src-tauri/src/cpu_watchdog.rs
21. CLI Companion (tuic)
21.1 Overview
- Standalone Rust binary embedded as a sidecar, installed to system PATH
- Combines VS Code-style file opening, tmux-style session management, and agent orchestration
- Cross-platform: macOS, Linux, Windows
- Communicates via IPC (Unix socket / Windows named pipe) with the running TUICommander instance
- Auto-launches TUICommander if not running
21.2 Editor Mode
tuic [path]— open file or directorytuic open --goto file:line:col— open at specific positiontuic open --wait— block until file closed ($EDITOR support)
21.3 Session Management (tmux-compatible)
tuic ls/tuic new/tuic kill/tuic send/tuic capturetuic resize <id> WxH/tuic pause/tuic resume- Targets accept UUIDs, ID prefixes, or session names
- tmux key name translation (Enter, C-c, Space, etc.)
21.4 Agent Orchestration
tuic bg <log> -- <cmd>— run a detached command without inheriting the foregroundTUIC_SESSIONorTUIC_PARENT; the runner retains caller-bound completion evidence and typed wake authority; a native user stop revokes old automatic wakes without removing explicit queued requeststuic agent spawn <type> <prompt> [--repo <path>]— spawn AI agent on an initial prompttuic agent ls— list running agentstuic agent send <peer-uuid> <message>— deliver to a registered peer’s inbox through the registry, the same path as the MCPagent action=sendtool. ReportsDeliveredonly when something surfaced the message; aninbox_onlyroute readsBufferedtuic agent type <id> <message>— type into an agent’s terminal and submit, with the text and the Enter as separate writes (raw-mode TUIs treat a combinedtext\ras an unsent prefill)
21.5 tmux Compatibility Mode
tuic aliascreatestmux → tuicsymlink;argv[0]detection switches to compat mode- Supports:
new-session,list-sessions,kill-session,kill-server,send-keys,capture-pane,resize-pane,attach-session,has-session - Tools expecting tmux (e.g. Claude Code
--tmux) transparently use TUICommander
21.6 Installation
- First-run prompt on app launch (one-time, dismissible)
- Settings > General > TUIC CLI (install/uninstall button with status)
- Auto-update on app startup (silent, no elevation prompt)
- Paths:
/usr/local/bin/tuic(macOS/Linux),%LOCALAPPDATA%\Microsoft\WindowsApps\tuic.exe(Windows) tuic install-cli/tuic aliasfor self-service
22. Remote Daemon (tuic-remote) — Beta
22.1 Overview
- Shared GitHub poller lifecycle controls, repository status, PR snapshots and issue reads work without a WebView; events use
/eventsSSE and TCP keeps the existing authentication. Account/auth and GitHub mutation routes remain outside the headless monitoring surface. - Standalone headless binary for running TUICommander on servers without a desktop environment
- Same HTTP/WebSocket API as the desktop app’s remote access feature
- No Tauri dependency — pure Rust binary
- Available as GitHub Release artifacts for Linux x64/ARM64, macOS ARM, and Windows x64
tuic-bridgeis published for every one of those targets too, and belongs next to the daemon: the daemon writes an MCP entry naming it into the config of each agent installed on the machine, so an agent launched there gets the fulltuicommandertool surface (session,repo,progress,agent, peer mail)- Agents reach the daemon over its local IPC endpoint (
mcp.sock, or thetuicommander-mcpnamed pipe) — never over the authenticated TCP port - Runs the desktop’s background tasks that a machine needs: process snapshots, standby parking, content indexing and boot pre-warm, tool search index, upstream MCP auto-connect and health checks, CPU watchdog, maintenance sweep. It does not run the WebView watchdog (no WebView). Command-knowledge persistence was removed in #2115-1333. The embedded assistant’s scheduler and watcher engine are not on this list any more — they were deleted outright in #784-0aec
22.2 Configuration
- Without
--instance, uses the desktop app’s existing platform config directory, keyring servicetuicommander, uservault, and legacy migrations unchanged --instance <id>selects an immutable isolated namespace before password setup or startup: files under<platform-app-config>/instances/<id>/and keyring servicetuicommander-instance-<id>, uservault- Instance IDs are lowercase ASCII DNS labels of 1–63 characters with
alphanumeric ends and optional internal hyphens;
defaultis reserved - Named instances start empty and never fall back to or migrate default/legacy files or credentials. A release daemon exits before binding if its named OS keyring vault cannot be opened
--credential-file <path>explicitly seeds a process-local vault from a private JSON string map in release or debug builds, without an OS keyring or session bus. Missing or malformed input fails boot without exposing contents. Runtime credential edits stay in memory; rotation requires a file replacement and daemon restart. Automatic updates relaunch the installed startup executable path, including on Linux after the running inode is replaced, and reread the selected file. Desktop keyring defaults remain unchanged- Default port: 9877 (overridable via
TUIC_PORTenv var) --set-passwordperforms interactive password setup (bcrypt hashed) inside the instance selected earlier on the same command line- LAN auth bypass always disabled in headless mode (security hardening)
--bind <ip>selects the listening address; desktop-managed deployments pin it to127.0.0.1--survive-secs <n>exits after that many seconds without SSE or WebSocket clients; client activity resets the timer--no-agent-configsskips startup host agent MCP configuration writes for ephemeral and installed desktop-managed daemons, and cluster workers that must preserve the OS user’s agent configs (~/.claude.json,~/.codex/config.toml). Without it,RemoteOptions.agent_configsdefaults totrue; workers sharing an agent-config owner must use the flag on every launch--no-automationsstarts no automation scheduler or event intake: no schedule, issue event or pull-request review starts a run or session, and the run ledger is not opened. Workflow runs started through the workflow API keep executing their steps. Without the flag, automations run as beforeTUIC_PAIRING_TOKENis consumed once as the daemon session token and removed from the environment before child processes can inherit it
22.3 TLS
- Manual TLS via
services.tlsin the instance’sconfig.json(mode: "manual", plus cert and key PEM paths); the daemon port supports HTTP+HTTPS, including SSE and WSS - Missing or invalid PEM files fail before bind, with no plaintext fallback; live listener state drives TLS diagnostics
- No TLS by default — use a reverse proxy or Tailscale for production
22.4 Lifecycle
- Graceful shutdown on SIGINT/SIGTERM/SIGHUP, with a pid file removed on exit
- Binds TCP, starts background tasks (MCP session reaper, upstream health checks)
- Fails fast if port is already in use
- Optional survive timer preserves sessions across short disconnects, then exits when its configurable idle window expires
23. SSH Tunnel Manager
23.1 Supervised Tunnels
- Managed SSH processes with automatic lifecycle supervision
- Tunnel states: Starting, Connected, Reconnecting, Stopped, Error
- Readiness check: SSH must survive 500 ms and every local forward must accept TCP connections before the tunnel is considered connected (30-second limit)
- Graceful shutdown: SIGTERM with 5s grace period, then SIGKILL escalation
- SSH agent forwarding: auto-discovers
SSH_AUTH_SOCKfor key-based auth
23.2 Reconnection with Exponential Backoff
- Automatic retry on retryable failures (network down, connection refused, timeout)
- Exponential backoff: 1s base, doubling per attempt, capped at 30s
- Jitter: +/-25% per delay to prevent thundering herd
- Maximum 10 retries before stopping; counter resets on successful connection
- Non-retryable failures (auth denied, host key mismatch, port in use) stop immediately
23.3 Exit Classification
- Stderr-based pattern matching classifies SSH exit reasons (AuthFailed, HostKeyMismatch, PortInUse, ConnectionRefused, NetworkDown, Timeout, UserKilled)
- Exit code used as fallback when stderr is empty
- Classification drives retry decisions — only network-related failures are retried
23.4 Audit Logging
- SQLite database with WAL mode for concurrent-safe, high-performance event logging
- Event types: Started, Connected, Disconnected, Error, Retry, Stopped
- Query by tunnel ID (most recent N events) or by time range
- Automatic rotation: configurable retention period deletes old events
- Indexed on
tunnel_idandtimestampfor fast lookups
23.5 Profile Configuration
- TOML-based profiles with name, host, port, user, identity file, and port forwards
- Global scope:
<config_dir>/tunnels/*.toml— available across all repos - Per-repo scope:
<repo>/.tuic/tunnels/*.toml— overrides global profiles with same ID - Forward types: Local (
-L) and Remote (-R) port forwarding - Options: ServerAliveInterval (default 15s), ServerAliveCountMax (default 3), StrictHostKeyChecking (Yes/AcceptNew)
- Validation: duplicate bind ports, empty fields, port range (1-65535)
- Pre-spawn port availability check for local forwards
23.6 Tauri IPC Commands
- All tunnel management exposed as native Tauri IPC commands (
tunnels/tauri_commands.rs) — profile CRUD, start/stop, status, audit log, SSH config host parsing, SSH agent key listing - Desktop app uses IPC directly; browser mode falls back to HTTP endpoints
23.7 Auto-Connect
- Profiles with
auto_connect: truestart automatically on app launch - Hydration runs once during startup, guarded against duplicate calls
- Non-blocking: failures are logged but don’t prevent app startup
23.8 SSH Agent Detection
- Auto-detects SSH agent type from
SSH_AUTH_SOCK: 1Password, Secretive, GPG Agent, generic SSH Agent - Lists loaded keys via
ssh-add -l(fingerprint, comment, key type) - Shown in the tunnel editor for identity verification
23.9 Orphan SSH Process Cleanup
check_local_port()distinguishesPermissionDenied(privileged ports) fromAddrInUsekill_ssh_on_port()finds SSH processes holding a port vialsof, verifies withps, sends SIGTERM- Only kills confirmed
sshprocesses — never unrelated services
23.10 Statusbar Shield
- Grey shield icon when tunnel profiles exist but none are connected
- Green shield with count badge when tunnels are connected
- Clicking the shield opens the Tunnels Panel
23.11 Shutdown on Exit
TunnelManager::shutdown_all()called onRunEvent::Exit- Stops all supervisors and clears the tunnel map — no orphaned SSH processes after app close
- Shutdown kills each tunnel’s whole process group, not only the
sshchild, and waits for confirmed exit within a bound; forkedProxyCommandgrandchildren are not orphaned. A start that arrives after shutdown began is refused.
23.12 UI
- TunnelsPanel — List of tunnel profiles with status badges and start/stop controls
- TunnelEditorModal — Create and edit tunnel profiles with form validation; file browse dialog for identity file; remote host pre-populated from tunnel host when adding forwards; type-aware Local/Remote forward endpoint fields; numeric input mode for port fields
- TunnelStatusBadge — Color-coded status indicator (green=connected, blue=starting, orange=reconnecting, red=error, grey=stopped)
- Command Palette —
toggle-tunnelsaction registered for quick access
24. Remote Connection Manager
24.1 Connection Types
-
SSH — Connects via SSH tunnel to a remote
tuic-remotedaemon; auto-creates port forwarding- Fields: host, SSH port (default 22), SSH user, optional identity file, remote daemon port (default 9877), deploy policy, survive time
- The host picker probes deduplicated SSH config hosts on demand and labels shell, no-shell, auth-failed and unreachable results; free text remains valid
-
Direct — Connects to a
tuic-remotedaemon URL directly (for Tailscale, LAN, or VPN scenarios)- Fields: URL, auth username
-
Relay — Reaches a
tuic-remotedaemon that has no inbound port through a relay. Paste the bundle printed bytuic-remote --relay-pair <url>; the end-to-end secret never reaches the relay. The desktop exposes the daemon on a loopback port, so repos, sessions and terminals use the same handlers as a direct connection. A lost link shows a typed state (relay_unreachable,daemon_offline,pairing_rejected,link_lost) and reconnects as a new attachment, without replaying what was in flight -
Update & restart remote — For either connection type, compare the daemon’s
/healthbuild SHA-256 with the release asset or a matching local build, show an out-of-date badge, confirm the number of live sessions that will be lost, deploy, and verify the new hash after automatic reconnect. Direct uses an authenticated, size-limited upload; SSH uses SCP. Windows in-process replacement is explicitly unsupported. -
Auto-update remote daemons — An opt-in per-connection setting. On connect, update an out-of-date daemon only when it reports zero live PTY sessions. With live sessions, show the count and offer the manual update without a queue. Progress, success and errors appear in Remote Machines. One update owns each connection at a time: manual and automatic updates both show in-progress, and overlapping requests over IPC, HTTP, or MCP receive an error.
-
Daemon version guidance — Show the last
/health.buildversion in every retained runtime state. A semantic version older than the client warns before authentication succeeds. Host refusals explain that an outdated daemon may be responsible and recommend installing the currenttuic-remoteand restarting the service. A bare 403 carries no version; without a prior health observation, the version stays unknown. Explicit disconnect clears the observation.
24.2 Storage
- Connections persisted in
<config_dir>/connections.json - Atomic writes via temp file + rename
- Each connection has UUID, name, transport, auth username, enabled flag,
deploy(never | on_connect | installed),survive_secsandauto_update(defaults to false) - The Basic Auth password goes to the OS credential vault (
Credential::RemoteConnection), keyed by the connection UUID — never toconnections.json, never readable back, and deleted with the connection - Relay peer admission publishes ordered presence before stats writes, so simultaneous joins do not restart the pairing handshake.
- The relay pairing bundle goes to the vault (
Credential::RelayPairing), keyed by the connection UUID, never toconnections.json - Desktop-managed SSH deployments use a separate vault pairing token. It is the
daemon session token, never appears in
connections.json, and survives a desktop restart so Connect can rejoin the same daemon
24.3 Authentication
- Both desktop and
tuic-remoterequire credentials on protected TCP requests, including loopback and LAN. Origin/Host checks reject foreign websites and DNS rebinding before any handler. Local IPC retains its existing trust. tuic-remoteauthenticates every TCP request: the headless build has no loopback bypass andrun_remoteforceslan_auth_bypassoff, so an SSH tunnel does not make it local.GET /healthis the only unauthenticated route- On connect, the backend trades the vault password for the daemon’s session token (
GET /api/auth/session-token, Basic Auth) — in Rust, so the password never reaches the WebView - The token is appended as
?token=to HTTP, the terminal WebSocket and the/eventsSSE stream by the single helperwithRemoteToken(transportRuntime.ts). A WS upgrade cannot set a header andAccess-Control-Allow-Origin: *rules out credentialed cookies, so the query string is the only credential all three share - Held in memory only, never persisted: the daemon mints a new one on every restart, and a 401 from the status poll triggers one re-authentication
- Status separates Not authenticated (reachable, credentials rejected) from Error (unreachable). An unauthenticated connection starts no poll, no event bridge and routes no calls
24.4 Connect and Install
- Deploy on connect resolves the host target with
uname, downloads and caches the matching release asset, compares its SHA-256, copies only when needed, then launches it on loopback with the configured survive time - SSH tunnel, remote exec and SCP share the TUIC-owned
~/.ssh/tuic-%CControlMaster socket, so one authenticated connection serves the whole flow without exceeding Unix socket path limits. The master persists only for the life of the process that owns it, preventing a completed one-shot command from making a later supervised tunnel exit immediately - Install writes a systemd user unit and protected environment file on Linux, or a protected launchd plist on macOS. Uninstall stops and removes them
- Deployment publishes
deployingstatus with the current step. Failures retain the step and remote log tail inerror; they are never misreported as an auth failure
24.5 Remote Repositories and Terminals
- Repos can be assigned to a remote connection; sidebar shows remote badge
- Remote repository browsing starts at the remote host’s reported home directory and exposes directory permission errors without blocking manual path entry
- Terminals on remote repos route WebSocket I/O through the connection’s base URL
- A terminal launch failure is shown in its pane, and a failed grid stream shows an error toast; the remote session owner is registered before the stream attaches
- One choke point decides the machine.
resolveOwningConnection(transportRuntime.ts) reads the call’s own arguments — a session id first, then a repository path — and answers which connection owns it. Both entry points ask it:rpc()for the HTTP transport andinvoke()for the desktop IPC path, which would otherwise short-circuit straight to the local backend. A call site cannot forget to route, because it never routes - Path→connection resolution reuses
resolveRepoPathFor(deepest registered repo or linked worktree wins); session→connection goes through the terminal’srepoPath, falling back to itscwdwhile ownership reconciliation has not run yet - A command with no HTTP route (
INTENTIONALLY_UNMAPPED) stays local and warns once — routing it would replace a working call with a throw - A call on a repo whose connection is down fails with
Remote connection <id> not connected; it is never answered by the local backend canvasTerminalTransport.tstakes theconnectionIdand derives both the base URL and the token from it- Status polling runs against
/api/version, not/health: only a route behind the auth middleware can tell a working connection from a rejected one
24.6 Event Mirror
- Remote MCP toasts are retained once in the desktop Messages bell with
[connection name]before the title. Their level and requested notification sound are preserved; Open terminal resolves the peer to its live remote PTY and never selects a local tab. Unknown or closed sessions leave focus unchanged. Toasts arriving after disconnect are dropped, with no replay queue. Malformed remote titles/messages are discarded without logging their content. Deduplication includes the connection id, so identically named hosts retain separate notices. remote_mirror.rsruns one task per connected connection: it reads the daemon’sGET /sessionsand then its/eventsstream, in Rust- The stream carries no
types=filter, and every frame is repeated on the local bus under the daemon’s own event name — a client cannot tell a mirrored event from a local one, so the existing handlers raise the same badge, the same notification and the same queue gate, and a new event type crosses for free - Mirrored sessions appear in
list_active_sessionsandGET /sessionsbeside local ones, each carryingconnection_id— the only field that says which machine runs it - The stream is re-seeded after every reconnect, so a gap in the SSE cannot leave a stale badge; losing the connection announces each mirrored session closed and then drops it
- Every mirrored payload is stamped
__tuic_origin, and a frame that already carries one is dropped: a mirrored event never crosses a second hop, so two machines pointed at each other stop after one repeat instead of looping. A body that is not a JSON object cannot be stamped and is dropped for the same reason - The desktop window hears only
session-state-changedandsession-closed. Those handlers are session-scoped;session-created,ui-tab,worktree-created,worktree-removedandrepo-changedmutate local state — a phantom tab per remote session, a workspace in the local store, git work on a path this machine does not have. They still reach the local bus and/events connectrefuses a base URL whose/healthreports this process’s owninstance_id: a machine cannot mirror itself. A daemon too old to publish the field still connects
Remote host cards name DNS, refused connections, timeout, TLS, and authentication failures. A 403 Untrusted Host explains that the daemon rejected the host name and stops automatic connection retries until an explicit Connect attempt. The cause remains visible without a retry delay. Repeated identical failure states do not add warnings. When a short name cannot resolve, a matching running Tailscale peer supplies its advertised full DNS name. Retryable failures show the automatic retry delay; active attempts clear the previous failure.
25. Generators
Secure value generators accessible from the command palette (open-generators action).
25.1 Available Generators
- Password — Configurable length, character classes (uppercase, lowercase, digits, symbols)
- UUID v4 — Standard random UUID (RFC 4122)
- UUID v7 — Time-ordered UUID (RFC 9562)
- ULID — Universally unique lexicographic identifier
- CUID2 — Collision-resistant unique identifier
- JWT Secret — 256-bit random hex key
- TOTP Secret — RFC 4226 base32 secret (160-bit)
- Nano ID — URL-friendly random ID with configurable length
- Slug — adjective-noun-NNNN random slug
- Ed25519 Key Pair — Public + private key pair
25.2 Architecture
- All generation happens in the Rust backend (
generators.rs) via theringcrate for cryptographic randomness - Frontend is a modal dialog with copy-to-clipboard and regenerate actions
- Password and Nano ID have configurable options (length, character classes)
26. ACP Client for ego
Backend-only so far: TUICommander can drive an ego agent over the Agent Client Protocol (v1). No frontend surface yet.
26.1 What it does
- Launches a supervised ego child per connection and initializes it, refusing anything the agent did not advertise before a byte reaches the wire
- Durable sessions: new, list, load, resume, fork, close, delete
- Turns: prompt, cancel, per-turn config options, and the ordered stream of what the agent said, replayable from any sequence a bounded journal still holds
- The agent’s questions back — permission and elicitation — parked so a person answers them without freezing the connection, and listed so a client that was not running when they were asked still finds them
- ego’s own extensions:
_ego/pause,_ego/resume,_ego/compact, each gated on the version ego advertised
26.2 Where it is reachable
- Desktop: 23
acp_*Tauri commands (docs/api/tauri-commands.md) - Browser/PWA/remote: an identical route per command under
/acp(docs/api/http-api.md), including the same error bodies - The turn stream is a dedicated Channel on the desktop and a dedicated
WebSocket in the browser;
/eventscarries only the low-frequencyacp-noticewake signal - Text sent during a running turn uses advertised ego v1 ACP steering and enters the current query at the next provider request. Accepted steering is shown only through ego’s user-message echo and is never resent. A not-busy response uses the normal prompt path. Attachments, unavailable steering, and rejections retain the shared queue.
- Queued prompt submissions share one FIFO per ACP session across desktop and phone; queued entries are visible and removable from either view, and active-turn cancellation is shared. Queue snapshots and events omit image bytes.
26.3 Process authority
The one binary this may launch is the ego_executable setting, read at each
connect. It is not an argument of any command or route, so no request — local
or remote — can choose what the host runs. An empty setting refuses every
connect rather than failing later inside a spawn.
The optional ego_profile setting selects one profile in ego’s user
configuration at ACP launch. Empty adds no --profile argument. TUIC sends no
profile rules or allow/deny policy in session/new. A workspace’s .tuic.json
may select ego_profile; TUIC passes that name and the explicit machine selection
as _meta.ego.{profile,ceilingProfile}. Ego owns restrictive composition of mode,
sandbox and perimeter. Its returned warnings appear as AI Chat warning notices.
Missing machine selection or missing ego acknowledgement refuses attachment.
27. Terminal Progress
-
Session-only popup mute: select Mute on a completion popup, then Unmute in Terminal Progress to restore future popups. Existing and queued completion cards close, but journal entries, unread counts and blocked warning popups remain. Restart or browser reload restores popups; native notification settings do not change.
-
One append-only journal per project with each new entry attributed to its source PTY when known: entries are written once, then kept or deleted. No pause, clear, correction, revision, deduplication or Markdown export
-
Three kinds. Agents report
doneandblocked; TUICommander writesintentfrom the agent’s ownintent:marker, so an agent that never calls the tool still leaves a trail -
Compact MCP
progresstool (type,text, optionalstep) that appends and toasts in one call, stays directly callable in collapsed tool mode, and refusesintent— that kind is observed, not claimed -
An imperative reporting obligation in
initializerather than only a tool description: the descriptive version recorded zero entries across 39 repositories -
One SQLite database in the configuration directory with the project as a column. Nothing is written inside a repository, so Progress produces no repository-change event, no Git-exclude entry and no indexing pass
-
Managed workspaces resolve to their parent project, so a worktree and its repository share one history; a directory belonging to no registered project is not recorded at all
-
A dialog, not a panel: one newest-first list for the active PTY by default, a selector for other PTYs and the repository aggregate, opened with at most 100 entries, with cursor-based Load older on desktop and mobile
-
Mobile identifies the selected project once in its selector, or a subtitle when the selector is unavailable; the desktop dialog retains its subtitle
-
A last-visit divider frozen while the dialog is open, so it never moves under the line being read
-
Blocked entries in red,
intententries muted, one blocked-only filter, per-entry deletion scoped to the project -
Aggregate notification-bell count plus exactly one live toast, silent by default; Progress entries are not duplicated into MESSAGES
-
On desktop,
doneandblockedentries also send a native OS notification with the project and entry text while TUICommander is unfocused. A macOS click opens Progress at that project and terminal.intent, hand-off, and message entries remain silent; identical notices within five seconds are coalesced -
The notification bell always offers Terminal Progress, including with zero unread updates;
Cmd/Ctrl+Shift+Pand the command palette open the same dialog -
progress_trackinggate: a global setting ANDed with a per-agent override. Global off removes the tool from every agent’s tool list
Remote MCP session ownership and peer mail
Desktop MCP discovers configured remote PTYs and peers, routes output and semantic submit to the owning daemon, and delivers connection-qualified peer mail through an authenticated desktop hub. Local mail remains independent of the hub.
Answers-only View
Use Toggle answers-only view (Cmd+Alt+R on macOS) to read selectable marked answers and their tracked prompts. Turns without marked answers are omitted. Output before the first tracked prompt remains available as a prompt-less turn, from the retained history base. If no answers qualify, the view shows a one-line notice. Toggle the view again to return to the terminal.
Private secret forms
Controllers can also put write-only task-scoped values with a TTL and select the scope at agent spawn. Values enter only the child environment. TTL stops new injection; existing session masks remain until teardown. PTY output is sanitized before HTTP, WS, history, watchers and diagnostic captures (#2319-02f6).
The private window offers a selectable full phone-entry URL, Copy URL, a browser link and QR code using the Remote Mobile address policy. Disabled remote access shows setup guidance. SSO HTTP(S) display URLs share the selectable link, copy and system-browser actions; other display values stay plain text. Account-vault entry remains native-only.
The secret MCP tool opens a separate native form for requested sensitive
fields and returns names/status only. Approved argv commands receive values in
the child environment; pipe output is masked for exact and common encoded
values, including wraps. User consent binds exact argv, names
and directory. Values and templates live only until exit. One-time nonce links
support browser entry on the existing application origin and transport. Use
HTTPS for phone entry. TUIC inspection and capture calls are gated while a form
is open; toasts and remote upstreams stay available. See
Private secret forms for limits and consent.
Workflow safety includes owned check-tree teardown, credential-derived operator authority, and receipt-based plan completion that reopens after canonical ref movement.
Workflow and dependency writes probe Git before opening write transactions, then reject concurrent run or story revision changes. Canonical ref changes invalidate integration evidence on the next read.
Stored terminal marker coordinates
Command boundaries and user prompt ticks retain their physical row after capped scrollback evicts older output. Answers-only history uses the same stable prompt coordinates.
Headless Telegram channel
Without an explicit registration, allowlisted text reaches the latest-connected
live AI Chat peer. Explicit registration always has priority over that fallback.
Any MCP-bound TUIC agent opts in with telegram register; one volatile
registration replaces the previous agent with one native notice. It ends on
MCP session end, PTY close, foreground-agent exit or daemon restart.
Allowlisted private text arrives as native peer mail. Without an agent the bot
replies “No agent is listening. Ask an agent in TUICommander to register for Telegram.” and drops the text; strangers stay silent.
The registered agent can stream concise activity, send exact replies and offer
opaque buttons. Any live MCP-bound agent can send notifications without registering or taking inbound ownership. Non-owner sends carry server-derived [session name] [alias: TUIC address] on every chunk (terminal alias, or stable peer ID without a terminal), allow no buttons, and are limited to one send per 30 seconds per peer. Telegram Replies to that prefix reach the unique live exact-name sender; other replies and new messages use the inbound owner, then live AI Chat. Unavailable named targets retain their name, address, quoted original and reply in fallback mail; the bot names the receiving session, or the unavailable target when nobody can receive it. Proactive sends use one allowlisted destination. Only the polling
cursor persists; live mint deployment remains pending. See
Telegram channel.
Telegram Settings
Mobile Settings does not offer Telegram setup.
Desktop Settings → Telegram provides token replacement/getMe check, one-use ten-minute pairing or explicit private-chat IDs, read-only registered-agent status, enable and safe status. Desktop and tuic-remote share one process-held polling lock; the standby takes over when the owner exits. Settings identifies the connected owner and enables pairing only while connected. Tokens stay in owner-only private files and never return to the UI.
Connected daemon notices carry their host identity. MCP confirmation responses and ACP permission/elicitation answers return to that daemon; disconnected questions disappear without changing local connections. AI Chat shows remote questions separately, with their ACP connection identity. Remote GitHub transitions fetch PR data from the repository owner, notify once, and do not run local repository automation. GitHub polling also works on the headless daemon. MCP upstream health refreshes use a separate host snapshot rather than this machine’s editable configuration.
- AI Chat mobile push: pending questions and ego notice cards share the 30-second per-conversation limit.
The graph runtime foundation now persists and replays pinned activations, serial predecessor history, edge decisions and repair counters. Executable validation requires Pause resume targets and deterministic final checks. Fork/all-Join schema and execution wait for slice G; scheduling and designer controls for these settings remain in development. Pause resolution respects uncertain-effect and pending-input fences, and serial history is bounded. Old pre-contract runs support inspect/cancel only.
Detached AI Chat owns its push-to-talk lifecycle and captured composer. Native Fn starts in the focused supported window; releasing it after a focus change still completes that recording. AI Chat dictation remains a draft for review.
AI Chat offers Fork beside a reply when ego advertises message-point forks. The new tab keeps history through that reply’s successful completed turn; the parent can keep running. During an active turn, Fork conversation and /fork use the last successful completed turn observed on the connection. No verified cutoff means refusal, never a partial-tip fallback.
Forked AI Chat tabs label inherited history. A separator marks where the child’s own conversation begins, including after loading saved history.
The AI Chat conversation picker groups fork and compaction descendants beneath their ancestors. Deleted immediate parents remain visible as disabled “Deleted conversation” rows.
Closed refusal turns show one plain-text card with the agent’s existing ACP refusal text. A refusal without text shows a generic refusal message.
Browser HTML and Markdown previews load local images only from open repositories and their linked worktrees, through the authenticated repository image route. Images outside those roots show “Image unavailable: outside open repositories.” Desktop asset loading is unchanged.
Native stories expose qa for work that waits on manual checks. A criterion starts with [MANUAL], or is marked through set_criterion_manual {index,manual}. Active work automatically enters QA when all unchecked criteria are manual; submit_qa explicitly requests that state. reject_qa returns QA to In progress; approve requires every criterion checked. QA keeps plans Active and dependencies blocked. All transitions retain expected-revision checks. See the native stories guide.
Reversible native record archival
In Plans and Stories, Archive plan and Archive story move the selected record out of the default list. Use Archived plans or Archived stories to select archived records, then choose Restore plan or Restore story. The toggles are independent, so archived stories remain reachable inside active plans. Archived detail stays readable; restore before starting work. Backend refusal messages remain visible when a claim or active run owns the record.
All native story transports share archive_story, unarchive_story, archive_plan, and unarchive_plan. Story actions take story_id; plan actions take plan_id. Each requires expected_revision and returns the updated record with its incremented revision and archived flag. Stale revisions fail without a write. Archival preserves status, criteria, dependencies, and child archive flags; it never deletes records or cascades to children.
list_plans and list_stories default to archived: false. Set archived: true to select archived records. The story filter combines with the other filters and is bound into pagination cursors. Direct reads remain available. Default plan views and workflow dispatch omit archived stories; archived plans and stories cannot start manual or workflow work. Restore the parent plan before starting its stories.
Both archive and restore refuse claimed stories and plans that contain a claimed story. Story archival also refuses any prerequisite that is not Done while an open dependent references it, including inside an archived plan. The refusal lists the dependent IDs and leaves the record and history unchanged. WontFix does not satisfy dependencies. Done prerequisites and unresolved stories with only closed dependents remain archivable. Adding a dependency to an archived unresolved story requires restoring it first; both dependency editors enforce this rule. Whole-plan archival does not change dependency readiness. An active or paused plan-root workflow owns the plan’s story set. A story-root workflow owns its target and execution stories, not unrelated siblings. Cleanup of an owned story or its parent plan is refused until the run ends. The workflow writer lock remains held through the archive transaction, so a concurrent run cannot start between the ownership check and the write.
story_archive_history (story_id) and plan_archive_history (plan_id) return {type:"archive_history",value:[{revision,archived,actor}]} in revision order. Events commit atomically with the record and retain caller provenance. Existing status transition history remains separate. Transition history uses readable command labels and 1-based criterion numbers, with the current criterion text when available. Actors show a live session name or an eight-character session ID; hover the actor to see the complete session ID. The current history API does not return timestamps. Consecutive archive-only revisions preserve accepted-work integration receipts; a work change or a moved canonical Git ref still invalidates them. Example: tuic story '{"action":"archive_story","story_id":"<id>","expected_revision":1}' --project /absolute/project.
Workflow graph slice C: the owning daemon executes pinned serial Agent/Judge/Loop/Pause/Notify/Join nodes through the existing RunStore ledger and managed launch fences. Named sol/sonnet profiles are required. New unsupported Gate and plan node publications are refused visibly. Manual pauses suspend active duration. Slice F supplies public story graph starts and history controls; D/E add independent approval and plan dispatch; graph completion alone never closes a native story.
Workflow story policy (slice D)
The daemon runs pinned deterministic checks before accepting an independent reviewer approval. Native approval history preserves the reviewer actor and revision; the run retains the reviewed artifact and check receipts. A workflow implementer cannot approve its story after exit or claim release. Integration remains an explicit operator action.
Workflow plan dispatch (slice E)
The owning daemon executes pinned plan coordinator and Create Stories visits through the existing proposal effects. Disjoint story children share a bounded project wave; overlapping or unknown scopes wait. A dependency starts only after its accepted revision has a current explicit Git integration receipt. Done alone and WontFix never release it. Approved children wait for an operator merge. The final plan Judge runs the pinned canonical checks and binds verification to the current plan fingerprint. Failed checks route through a bounded replan with a fresh coordinator attempt. Public start/history controls use the same graph entry point; parallel graph branches follow in slice G.
-
Run incidents and next steps: Plans and Stories run history connects recorded workflow and bound-agent failure/input outcomes to their cause, identifiers and manual next action. Session/task evidence is transient; no automatic incident retry.
-
Conversation launch options: AI Chat can give one conversation its own ego profile, executable and workspace, persisted with a dedicated peer identity. Creation and reopen are also available over HTTP.
-
Inbox read audit: MCP agent inbox reads log caller, owner and message ids at INFO without mail bodies.
Terminal stream reconnect notices identify the session and show the transport’s current attempt (up to 10). A received grid frame or confirmed empty replay removes only that stream notice; socket opening alone does not. Exhausted retries leave a persistent failure notice.
In rich mode, sessions idle for more than two hours fold into an expandable count. Backend activity timestamps determine age; busy sessions, awaiting input, unread output, selected rows and parents of visible children stay visible. Expanding preserves row order. Compact mode does not fold idle sessions.
Rich working agent rows reserve two clamped intent lines. Idle, awaiting-input and error rows stay on one line with status dots; their full intent, task or prompt remains in the tooltip. Compact rows keep their one-line layout.
Rich navigation keeps compact typography and padding. Branch identity and facts share one line, with names truncated and full PR/lifecycle facts in tooltips. Repository metadata disappears when PR and worktree counts are both zero. Header controls use compact sizing to protect repo names. Returned subagents fold into an expandable count independently of running work.
In rich mode, ungrouped repositories with open terminals appear first, followed by an Idle section. Manual order is preserved inside each section. Idle headers start on one line; disclosure reveals their branches without changing activity or saved order. Headers count agents in the backend working state, independently of open-terminal membership.
Rich active/idle sections also apply independently inside each existing repository group. Group membership and group ordering remain intact; active-only filtering hides idle-only groups and empty Idle headings.
Rich merged linked worktrees with no sessions and verified lifecycle facts use a one-line summary: Merged, N uncommitted, Clean up. Live, unmerged, or unknown worktrees retain full rows. Clean up enters the existing lifecycle preflight and confirmation workflow; cancellation preserves the worktree.
Rich parent terminal rows show N agents in each other repository containing live children. Clicking reveals the child group, repository and workspace, then selects a child through existing terminal navigation. Session placement and same-branch nesting stay intact; closed children disappear from summaries.
Browser Add Repository provides a server-side directory picker using the existing filesystem routes. Root HTML navigation offers form login; touch-capable iPad Safari selects the mobile interface even with its desktop Mac user agent. API authentication is unchanged.
Automation Once schedules (Rust foundation)
Definitions can schedule one wall-clock date-time in an IANA zone. Rust rejects past instants on creation and spring gaps, resolves folds to the earlier instant, and keeps consumed Once definitions for inspection. The backend supplies one preview instant and completed schedule state. Public automation controls arrive with the scheduler API and dialog. The shared Rust runtime now admits Once schedules on desktop and headless hosts, reserves before dispatch and records precheck decisions and launch pointers. Precheck stdout never changes the literal prompt. Public execution controls and completion/maximum-duration integration remain pending.
Lean one-shot automation creation
One-shot automation creation accepts name, prompt, in_secs and an explicit
saved run_config from a bound agent. Host-resolved repository defaults and
returned next-run/local fire times remove clock, list and get lookups. Identical
caller requests reuse the first saved occurrence; exact UTC storage preserves
elapsed delays across DST. Unknown caller profile identity fails explicitly.
Automation profile repair
Unresolved automation profiles appear in the desktop Messages bell on startup and after saved profile changes. Failed-run notices include their reason, independently of creator mail. Runs groups repeated identical failures with a count and a Fix action that focuses the current definition’s saved-profile picker.
Automations dialog (backend integration pending)
Machine-local scheduled-run editor with search, backend cadence/zone preview, prechecks, workspace and duration controls, pause/resume, Run now, confirmed delete and recent status history. Open Automations from the command palette. Step 8 API integration is required before use; see Automations.
The Automations palette action also matches scheduler and schedule. Automations cards show the repository name (full path on hover), common schedules in plain language, secondary cron and the backend next run in its named timezone. Definitions and Runs use keyboard tabs (Left/Right, Home/End). The dialog selects the first automation on open unless a specific definition, run or new draft is already requested. Refresh keeps unsaved edits.
Automation transport availability
Automations definition management, pause/resume, schedule previews/presets, retained run history and UTC aggregates are available through matching Tauri IPC and HTTP on desktop/headless hosts. Browser/PWA uses the same command mapping. Run Now uses the addressed machine’s runtime owner and supports paused Once and cron schedules; a due cron occurrence dispatches once. Full run replies retain output, workspace and task/session evidence.
Automation execution now reconciles task, PTY and progress completion evidence, retains bounded final output, and expires active runs at their persisted deadline. If stopping one run fails, it stays active while other runs still enforce their deadlines. Reconciliation reports the stop errors after processing those runs. Blocked runs remain active; idle alone does not prove success. Rust restart required.
Event-run details retain durable publication outcomes and exact pre-POST intent. Restart and lost-response reconciliation use a repository/head/base PR lookup; uncertain writes are never automatically repeated. Filtered, duplicate and capacity decisions retain coalesced skipped history without consuming admission. The outcome includes PR/comment URL slots, decision and failure/refusal reason; comment publication and machine-enforced review/check gating are not added.
Automation needs-you and failure notices use durable per-run/status/channel claims, existing notification preferences, and canonical saved-run/owning-session bell navigation. Unknown and interrupted outcomes remain history, not success. Notice navigation edits only the current definition; deleted definitions retain read-only run details.
The Automations editor exposes Include precheck stdout in the agent prompt,
off by default, using the same saved definition flag (#1624-c5f5).
Automation precheck context (#1631-45bf): definitions can opt in with
precheck.inject_output: true (default false). Proceeding checks prefix the
literal prompt with delimited, escaped untrusted stdout capped at 16 KiB;
truncation is marked and stderr is excluded. Empty output and manual bypasses
inject nothing. The run ledger records precheck_context: {injected, bytes} for
the prepared launch prompt, counting escaped stdout bytes before framing/marker.
Automation runs view
The Automations Runs view shows backend 24h/7d counts, paginated history, distinct needs-you/unknown/interrupted states, and saved output after definition deletion. New PTY run output is plain text with terminal escapes removed before retaining its newest UTF-8-safe 256 KiB; existing snapshots are unchanged. View run focuses only an available terminal on the owning daemon; otherwise it shows the saved report and workspace details without launching a replacement.
Reusable setting fields
Core form controls support account selection with a host-owned Add action, stable-ID editable rows, checkbox multiselect, read-only status tones and action buttons. They are controlled rendering components for settings and work-item forms; adding them does not add a settings page or a plugin manifest API.
Shared provider accounts
Core account/site list, add, Test and remove use one registry with write-only credential storage. GitHub metadata/tokens migrate without changing account IDs or repo bindings; core retains the GitHub provider and ambient auth chain. Generic provider descriptors allow token/basic verification for plugin providers. Native Settings secret entry and plugin-manifest/authenticated-request wiring are separate integration steps.
Account credential entry uses a private native form with one-time nonce and window identity checks. Settings sends account metadata only and receives status only; Enterprise PATs go directly to the account vault after verification. Account forms have no browser/mobile entry capability.
Tasks contract foundation
Provider-neutral Rust DTOs and generated TypeScript cover work-item queries, fields, comments, actions and boards. A deterministic local provider supports development; visible Tasks views and remote providers are separate integration work. See plugin guide.
Tasks detail component
Core provides a generic work-item detail component with descriptor-driven field editors, sanitized descriptions and comments, review threads and summaries, cursor pagination, add comment, and declared status actions with rollback. Visible details refresh every 60 seconds and preserve expanded sections. The Tasks shell and provider registration integrate this component separately.
Saved automation profiles (#2015-bdb3): create/update/re-enable and the runner share named-profile resolution. Invalid list rows expose a repair error with no next run. Failed agent-created runs notify their creator inbox once, including failures before spawn.
Automation agent surface (#1630-cbfa, #1621-5dce): MCP automations and
tuic automations share the HTTP/IPC action parser, definition results, schedule
previews, run history, summaries and Run Now runtime. Enabled-only updates and
Once definitions work identically; MCP creation retains host-bound provenance.
GitHub backend: paginated line review threads and replies, resolve/unresolve, and draft review submission pinned to the reviewed head are available through IPC and HTTP. The PR Files tab draws them on the diff lines: outdated threads are listed above their file, pending comments are added from the line gutter, and Submit review is refused once the PR head moves.
GitHub backend: failed-job reruns, auto-merge enable/disable, merge queue state/entry/removal and queue-aware merge are available over IPC and HTTP. Request changes requires review text.
Tasks board component
The core Tasks board component renders provider-declared columns and virtualized lanes. Each lane shows its loaded count and a More control while the provider has another board page. More loads the next page across all lanes, retaining earlier cards. Cards show assignee names and label chips, and support drag and drop and a keyboard-accessible Move button menu. Pending moves cannot be repeated; rejected actions restore the card and show the error. This component is available to the Tasks host; provider registration and the Tasks navigation surface determine where it is shown.
GitHub Work adapter — runtime integration pending
The github-work provider adapter supports account-scoped qualifier search, issue/PR identity, detail, paged comments and review summaries, create metadata, duplicate candidates, close reasons and host start-work intents. It is tested against recorded GitHub reads. Authenticated host wiring, lifecycle, manifest and catalog registration are present. The runtime binds account-scoped core review threads and PR actions; core retains reviewed-head and merge-queue policy. Recorded public Projects reads cover move and clear request contracts without live writes. Desktop load and live mutation verification remain pending.
Tasks create component
Core provides a generic work-item create form. The provider declares the item types and the fields of each type; the form uses the shared setting controls, blocks Create until the required fields of the current type are set, and opens the created item. The Tasks shell integrates this component separately.
Automation worktree cleanup (#1623-8b2a): Automation runs retain automation/run IDs and the exact created workspace path and ID in their saved snapshot, including after definition deletion. Worktree cleanup is explicit and limited to final runs. The backend resolves the saved identity and rechecks shared Git integration/archive proof, dirt, submodule commits and live sessions; it never forces removal or closes sessions. Shared automation_action actions worktree_preview and cleanup_worktree accept a saved run id on IPC, HTTP, MCP and CLI.
Built-in automation templates
New automation drafts offer weekday repository audit, release readiness, daily change review and hourly maintenance review templates. Enter the repository and run config, then select Apply template. Rust supplies the literal prompt, cadence, limits and zone (the backend host’s local IANA zone unless selected). Review and edit the draft, then select Save. Templates start paused; applying one never persists a definition or starts a run. Resume is a separate action. Templates use the existing checkout with no precheck and do not change agent permissions. Recurring cadence previews retain the existing runtime limitations.
- Finished worktree recycling: explicit completion permits safe reuse with a new branch and path while ignored build artifacts remain intact. Fresh allocations stay reserved.
History-anchored viewport scrolling
Terminal gestures hold the requested history row even when output arrives before the backend applies the scroll. If capped scrollback evicts that row, the viewport clamps to the oldest retained row.
GitHub OAuth requests repo project for Projects v2 reads and writes. Existing read-only logins get re-login guidance; Projects write denials leave board cards and repository actions available.
Internal repository settings owners
The typed settings service supports repository defaults and per-repository .tuic.json targets. One registered owner resolves only existing repository registrations; patches preserve sibling fields and check revisions under the file lock. Transport publication remains pending. Registration/group configuration remains an accepted inventory gap until its owner has a typed schema (#1825-4566).
GitHub settings backend: an internal typed owner adapter supports device login, verified Enterprise PAT accounts, labels, write-only credentials and revision-checked repository bindings. Shared settings transport publication is a separate step.
Ego settings owner service (#1775-330c)
The internal settings catalogue includes Ego managed model/provider selection,
roots, network and executable paths. Conditional atomic batches use Ego owner
revisions to reject concurrent external edits. Base-only provider headers and
credential commands use write-only actions; reads expose presence only.
Configurations remain profile/workspace scoped; absent
values and explicit empty roots stay distinct. Stored credentials are presence-only.
Launch profile/workspace stay in the app store; trusted executable writes await
the confirmation step. No new public settings transport is registered
by this adapter. Model changes from the existing Providers UI now use the same
configured profile and workspace as perimeter changes.
Tasks setup preserves saved account keys outside the form, including Enterprise hosts and login. Label choices use matching provider field IDs; assignee username filters stay text when create-form IDs differ. Display-only roadmap dates do not appear in list filters or grouping.
Tasks view memory
Tasks remembers the selected source per repository and List, Board or Roadmap plus list grouping, sort, preset, search and filters per repository/provider/account. The existing uiStore saves these preferences through load_ui_prefs and save_ui_prefs in ui-prefs.json. Results and page cursors remain transient. A rejected saved sort retries the last accepted order, then the provider default. Other query failures keep their error and Retry control. An unsaved scope keeps the normal defaults.
Tasks start-work briefs
Tasks Start work reads .tuic-start-work.md in the active repository root,
next to .tuic.json, with {{key}}, {{url}} and {{title}} placeholders.
Without the file, the existing key/title/body brief remains. Item control
characters are stripped before substitution; delivery keeps its 12,000-character
cap and untrusted-content wrapper. Desktop and browser use the same Rust builder.
Terminal Compose image attachments
Paste an image, drop PNG/JPEG/WebP/GIF files on Compose, or select several with Attach images beside Send. Each image is saved through the shared paste helper and inserted as [image: <path>] in gesture order. Drops use the pointer position; the picker replaces the selection. Unsupported files and save failures show a visible error. Native desktop drops are claimed by the mounted Compose editor before terminal and tab routing.
Tasks MCP access
The existing MCP repo tool reads linked work items or explicit references, URLs and exact provider keys, including paged comments. Provider content is enclosed in an untrusted-content block. Optional comments and workflow transitions use the same provider actions; mcp_work_item_writes defaults to false. A frontend with the provider loaded is required (#1854-4960).
MCP call audit view (#2136-dc79): Settings > MCP > Call audit lists the body-free GET /mcp/audit rows behind the mcp_call_audit_enabled setting (off in release, on in debug). Off records nothing. Effects distinguish read-only, completed, failed, not-started and uncertain dispatch; known operation and target names replace opaque metadata (#2299-07d3).
MCP usage rollup (#2808-5998): Settings > MCP > Usage keeps daily counts per client kind, role, tool and action (calls, errors, rejected arguments, reply size, catalogue bytes served) for 90 days and shows the last 7 days per role. On by default; the switch stops counting. No arguments, replies or names are stored.
Background tray and menu-bar icon
Tray and menu-bar icon: Settings > General offers Always, Only in background (default), or Never. The native menu shows live working/awaiting agent counts, Show TUICommander and Quit. An attention mark appears for awaiting agents while hidden and clears on Show. Left-click shows the app on macOS and Windows; Linux uses the menu. Never, a failed tray build, or a Linux desktop without a StatusNotifier host falls back to minimizing without clearing terminal visibility. A native notice appears on the first background entry of each app run.
Tasks list controls use provider-declared field sort, group and filter capabilities. A rejected selection restores the last successful sort, group and filter controls, keeps attempted search text for Retry, and shows the provider reason.
Tasks small-list mode (#1851-7ade): when the provider reports at most 1,000 matches, Tasks collects the complete search/preset scope and uses the Rust projection for all-field sort, group and filter. A changed total, missing rows or a nonterminal cursor cannot establish completeness. Unknown totals and larger lists keep provider-supported server controls. No extra cache or persisted state is added.
GitHub Tasks boards (#1846-55d7): the optional provider listBoards(signal) port discovers the current user Projects v2 when Board opens. The existing picker selects a project; paging preserves project identities. Missing read:project stays visible instead of claiming there are no boards. Providers without discovery retain their configured boards. Discovery does not persist selections or write to GitHub.
Background WebView unload
background.webview_unload_minutes defaults to 10 awake minutes; 0 keeps the hidden WebViews loaded. Changing it takes effect while hidden. Unload waits for a saved snapshot and defers during dictation or a close dialog. Rust PTYs, HTTP/MCP, Automations and remote terminal subscriptions continue. JavaScript plugins (including cache-keepalive, claude-wakeup and at-capacity-retry), sounds and updater checks pause until Show.
Show recreates the main window from Tauri configuration, restores window geometry through the window-state plugin and reconnects the saved tabs, split layout and live sessions created while unloaded. Suspended tabs remain suspended. The updater checks again when the frontend starts. Quit confirmation uses a native dialog while unloaded. ui MCP actions return {"error":"webview_unloaded"} immediately in that state. background-mode-changed is dual-emitted to desktop and SSE with {state:"hidden"|"unloaded"|"visible"}.
B0 measured WebContent exiting and about 1,090 MB released from a synthetic 1 GiB allocation on macOS. Actual TUIC workload savings, Windows and Linux are unmeasured. GPU and Networking processes may remain.
Design Mode captures accept per-call format (webp by default or png),
quality (WebP 1–100, default 25) and optional max_long_edge (positive pixels,
downsize only). Use WebP for text/layout, quality 50+ for small glyphs/icons, or
PNG for pixel-exact detail. Responses report path, format, quality (null for PNG),
bytes and media type; MCP sends a correctly typed image block. Token cost follows
pixel dimensions, not file format or bytes (Claude: about 1,296 tokens per
megapixel, capped at 1,568 standard / 4,784 high-res). HTTP/IPC use the same
screenshot fields in args; no user setting is added.
Design Mode agent control: immediate native-port navigate, reload, screenshot, page-error read and explicitly host-granted MAIN-world eval. The extension sidebar shows the last fifty agent actions. Screenshots require the reviewed tab to be visible.
Plugin settings pages
Loaded plugins with registered settings appear in a separate Settings > Plugin settings group. Navigation marks each entry as Plugin and exposes its source ID; the native editor shows the same ID. Catalogue loading never hides the Settings shell, and pending value reads use a local loading state. Search includes their catalogue field labels. Unloading removes the page and search entries. Reads, revision-checked edits, resets and secret set/unset status use the scoped Rust settings service; the UI owns no second configuration store.
Tasks notifications
Settings → Notifications → Tasks has OS notifications for Tasks, off by default and independent of the existing PR notification preference. Failed checks on a linked GitHub PR use the existing PR notice once and name the linked Tasks item. Click the notice to open the PR.
Use Follow task in an item detail to follow comments locally; use Unfollow task to stop. Follow state and the policy are saved in the existing Tasks UI preferences. A first observation establishes a silent baseline. Existing visible detail refreshes (including its 60-second refresh) and provider-bridge detail reads compare authoritative comments; there is no extra background poller. Your own comment action advances the baseline silently. Native notices recheck the Tasks policy after permission is granted and retain the existing background-window policy; browser clients do not send native OS notices.
GitHub provides a full normal-comment count, so an increase is detected even beyond the first page. Jira and GitLab provide paged comment entries: newly observed comments notify when their creation time is newer than the prior baseline, or when a previously unseen comment ID shares its latest timestamp. Unloaded pages, unseen review sources and items that are not refreshed cannot produce a notice. Editing a comment or loading older history does not notify. No Linear provider is shipped, so it is not covered.
Suspended tabs wake on open, submit or peer mail through the same Rust transition. Concurrent wakes share one replacement PTY and retain the TUIC peer identity. A failed wake leaves the suspended tab available for retry.
Automatic idle-agent hibernation
The backend checks unattended top-level agent tabs every five seconds. agents.hibernate_idle_minutes defaults to 60 awake minutes; zero disables the sweep. agents.hibernate_scope defaults to background_only; always also permits foreground hibernation. Both machine-owned controls are in Settings → Agents (Expert Mode).
Hibernation requires an idle agent and a verified resume session in its saved profile. Plain shells and agents without a verifiable resume session stay live. Unread peer mail, pending commands or background work, awaiting input, attached readers, keep-open tabs and open automation runs prevent hibernation. Managed children retain their separate idle-close policy. Sleep gaps longer than 30 seconds do not advance the idle clock.
The normal Rust suspension path persists reason: "idle_hibernate" before ending the PTY. Opening the tab, submitting input or sending peer mail uses the shared wake path. Storage or resume-verification failures leave the live session intact.
Settings transport cutover (#1787-4778)
The generated settings contract replaces the legacy MCP config tool and also serves HTTP and IPC. Trusted UI opt-in is independent of legacy config enablement. The resolved inventory enables owner transactions and typed workflows, including connection credential reconciliation scoped to one runtime. The inventory gate remains enforced for future additions.
Plugin HTTP requests accept AbortSignal cancellation through both desktop IPC and HTTP, including response body reads. Jira URL resolution forwards cancellation to every detail request.
Jira and GitLab expose a default project in their schema-driven plugin settings page. Jira uses a project ID; GitLab accepts a project path or ID. A project saved for an account in Tasks setup takes precedence. The default applies after the plugin reloads; empty means no fallback project. Account bindings remain in data/work-items.json, while these defaults use the settings service in data/config.json.
Mobile terminal streaming restarts on visibility return after retry exhaustion retires its subscription; confirmed ended sessions do not reopen (#2422-a267).
Mobile outage recovery: failed navigation shows a self-contained cached connection test with the server address, last error, manual retry and automatic backoff. It reopens the original address when the server returns. The running app shows a connection-test card for API or terminal-stream outages; bounded session reads and automatic recovery refresh failed view loads while mounted views preserve drafts (#1930-f4c2, #2294-078f).
Settings owner validation covers typed shortcut records and bounded pane geometry. Geometry references existing groups; runtime tab membership and focus are not configurable settings (#1914-cdf6).
Internal settings choice discovery
Owner-backed dynamic choices support cache-only describe and explicit refresh. Notification output devices retain their UI option objects and distinguish unavailable discovery from successful empty results (#1908-c327).
Agent model settings support typed model edits without starting a CLI. Explicit
choice refresh probes only the addressed Claude run config with --help, using
its command and environment. Published aliases are suggestions, not account
entitlement or an exhaustive model list. Other CLIs and failed probes report
unavailable choices; typed edits remain supported. Describe never probes. Model
edits preserve sibling configs and the default selection and apply next session
(#1910-451e).
App settings share bundled font and IDE option metadata between Rust and the UI. Theme/installed-IDE discovery uses explicit owner refresh; describe never launches discovery (#1915-d77f).
Voice owner discovery (#1909-0d24)
Internal voice settings refresh resolves devices, model state, installed voices and language-filtered Edge voices through existing owners. Describe is cache-only; typed asset actions retain existing owner validation and runtime effects. Public settings transport cutover remains separate.
AI Chat replies use plain chat prose without the terminal answer rail. Literal Markdown blockquotes keep their normal quote style.
AI Chat can pin repository context per conversation. A separate composer control shows Pinned repository or Follow repository and the configured repository name color; draft parking stays independent.
Settings layout foundation
Settings shares a responsive shell (1136px maximum, 80vh height) and reusable theme-aware cards, rows, status summaries and scoped action presentation across global, plugin and repository pages. Catalogue search preserves lazy page loading and reveals expert matches without changing Expert Mode. Section links retain their page mappings; plugin loading, read failures and unloads remain local to their scoped editors. Existing settings ownership and save behavior are unchanged.
Pocket spoken replies keep a missing selected voice visible and downloadable; while its download is absent, a ready bundle speaks with its own language default.
Terminal ego provider recovery
Native terminal ego can report provider recovery with phase, attempt and next
attempt time. Tabs show recovering; the status bar includes a countdown and
Force retry. Managed parents receive recovery entry/exit notices. MCP session
force_retry submits /retry once to the recovering ego terminal.
Telegram Settings includes a newest-first, process-local log of the last 20 inbound/outbound events with safe outcomes and 60-character redacted previews. This memory-only log clears on restart and does not include draft refresh traffic.
Telegram request streaming (1959-162a)
Telegram replies now use TUIC-driven receipt (👀), working (👨💻), waiting (🤔), answered (👍) and failed (👎) reactions. An ephemeral native draft shows Italian status lines or unapproved agent previews; it refreshes while work continues and the final reply replaces it. Acknowledgement of work requires inbox Read and a new recipient turn. PTY intent/activity and AI Chat assistant chunks share request correlation; finish remains authoritative after draft retirement. Telegram-mail-woken AI Chat turns automatically send their settled assistant text if finish has not answered. Queue and no-reply notices occur at ten minutes and sixty seconds after Read respectively. Restart keeps no request history. Phone rendering requires a live check after the backend restart.
Terminal text fidelity: soft-wrap rows preserve original spaces in session text, mobile CLI output, copied selections and ego question labels; explicit hard breaks remain. Chat uses its separate transcript source.
Settings MCP live refresh
Durable settings-facade writes publish a value-free process-local generation to desktop and SSE clients. Open settings consumers reread affected sections without saving; dirty edits survive, stale reads are discarded, and reconnect refetches snapshots. Vault-only credential writes and persisted apply failures also invalidate readers. Remote notices remain scoped to their owning connection.
Catalogue-backed Settings inspection
Settings includes a typed All settings expert inspector with explicit owner/path binding, revision-checked single-field edits, dirty-draft preservation and human confirmation recovery. Native controls expose catalogue identities, shared enums use owner metadata and search includes inspector descriptors. General exposes index-memory, attachment-size and WebView-unload resource limits. Per-ID ledgers document separate domain/legacy/read-only controls; CircleCI/corrections ownership and transient PR-filter persistence remain follow-ups.
Assisted Settings startup: published boundary
Startup workflow documentation covers GitHub device/Enterprise actions, read-only credential-source provenance and configured Ego settings/readback, with explicit owner revisions, human confirmation and partial-persistence recovery. Typed account enumeration and configured Ego interactive login start/status are published. Login returns a human-operated terminal and bounded handle; closed and expired handles never imply authentication success. Complete schema-only onboarding remains subject to integration verification.
CircleCI Settings owner (#1991-bd88)
Settings discovery includes the write-only machine setting circleci.token.
Typed set_token and clear_token actions share the existing token owner across
MCP, IPC and HTTP. Readback reports stored presence only (set, unset,
unavailable), never a secret. Git & GitHub keeps its effective-source status;
removing a stored token leaves environment and CircleCI CLI fallbacks unchanged.
Generated launch playbook
Settings > Agents selects generated Markers, Working with the user, Waiting, Git/worktrees, Process safety and child-only Children modules. Global and per-agent additions append after the modules; an explicit all-off switch suppresses the entire prompt. Effective previews use the selected machine. Exact old default copies migrate away without duplication. When mdkb is installed, the launch text also carries the fixed MDKB code-search rule.
Durable managed-child launch
- MCP
agent launch, HTTPPOST /agents/launch, and IPCmanaged_agent_launchshare an idempotent transaction. - Select/create a workspace, pin a stable name, link a registered parent, and choose keep-open in one request.
- Durable launch handles survive lost replies; conflicting retries and uncertain partial creation fail explicitly without a second PTY or fallback checkout.
- Receipts separate creation, prompt submission, native readiness, blocked state and warm-artifact status.
Bounded MCP reads
Session and peer inventories support scoped lookup and compact=true, including
explicit unknown state, activity age and omitted fields. Inbox and terminal
output support opt-in UTF-8 byte-budget pages with immutable, lossless
continuations. The envelope counts toward the budget; the inbox cursor advances
only after the final chunk. HTTP MCP-compatible output shares the same boundary.
Opt-in frame workload evidence
The debug frame recorder retains bounded real grid arrivals and immutable paint inputs, dumps on a recovered freeze/long paint or on demand, and replays production grid painting with per-frame timings. It is off by default, requires perfDebug, and stores sensitive terminal content separately from the numeric journal. See Persistent stall evidence. The synthetic smoke fixture is not a real-stall RED.
Dictation correction dictionaries are discoverable and editable through the shared Settings owner as stable heard-text keys. Revision-checked edits reuse TextCorrector persistence and refresh the runtime without microphone access (#1992-d4fa).
MCP discovery can include a complete top-match schema within a UTF-8 byte budget; clients can reuse it until catalogue invalidation (#2013-73f9).
Runtime MCP outcomes (#2010-30a7)
A bounded body-free /mcp/audit projection records actual HTTP/ACP runtime calls,
response text bytes, correlation UUIDs and separate application/transport/effect
observations. Unobserved delivery and effects stay unknown; native error:null
is not a failure. Client correlation and captured live traces remain separate.
Managed MCP reconnect context (#2008-5317)
Modern stateless managed calls recover mail/project routing from their exact live host-issued peer identity without model-driven registration. Unknown/headerless peers get bounded context-recovery guidance, not a guessed repository or identity. Existing explicit identity replacement and stranded-mail receipts remain intact.
Plugin catalogue update detection compares equal-version payload identities as well as versions. Installed identity is computed by Rust and ignores mutable plugin data.
MCP capability switches replace implementation-name switches. Saved denials migrate once, unknown names remain visible, and discovery and dispatch share the policy. Retired task/story/workflow-member/Design Mode names have no aliases; reconnect cached clients and review grouped allow rules (#2068-63b9).
Mobile offers the Chat tab only when the host has a configured ego executable, using the same availability predicate as desktop. Host settings changes update the tab without reloading. Removing ego configuration returns an open Chat view to Sessions; unavailable saved Chat links also stay on Sessions.
Agent desktop verification
make agent-test provides a preset isolated macOS desktop instance for authorized agent live checks. It uses a distinctly named binary and config namespace, loopback port 19876, disabled global input/microphone/Telegram/updater integrations, a side-effect-free dry-run and an instance-only stop target. See Development Setup.
Abandoned shells
Desktop sidebar session rows and mobile session cards mark a parentless plain shell as Abandoned after one idle hour and show its idle age. The five-second backend sweep requires a fresh OS process inventory: the PTY child must be an interactive shell with no child processes. An unknown inventory, script, foreground command, background child, detached TUIC job, managed identity, live child session, pending input or keep-open hold prevents closure. Unsupported or incomplete OS process observations fail closed.
Settings → Agents → Idle agent hibernation (Expert Mode) includes Close abandoned shells after (hours) (agents.abandoned_shell_hours). The machine-owned value defaults to 0 (off); whole hours from 1 to 65535 enable closure. Idle age is measured from the most recent input, output or semantic activity, including elapsed time while the machine sleeps. Closure rechecks the process inventory and activity at the destructive boundary, and uses the normal session close/tombstone path. The sweep can lag the threshold by one five-second tick. A remote daemon applies its own setting, not the desktop host’s value.
GitHub access diagnostics group exact API messages by account and owner, distinguish NOT_FOUND from retriable denials, and offer the OAuth organization authorization action for every github.com OAuth group.
GitHub Settings Refresh status releases NOT_FOUND retry delays for all accounts; ordinary diagnostics reads do not alter the retry cache (#2133-9213).
Detached checkout visibility: the sidebar shows directory name, short HEAD SHA and detached state in non-selectable rows, with a header count when folded. Discovery preserves newline paths and distinguishes the configured archive pool from unrelated __archived folders.
Mobile session usage (#2150-4e0c)
The session overflow loads a read-only usage block when opened. Session polling does not reload this block unless the selected session ID changes. One plan heading groups its quota windows; an absent tier is not inferred. Claude and Codex show shared account quota for the live process profile. ego shows only the exact PID-bound session row from its v3 usage report, including separate API-equivalent estimates and unknown cost reasons. Available model metadata is shown; missing model metadata does not obscure valid account quota. Unknown usage and stale data are labelled explicitly. Remote sessions use their owning daemon, never a local account. Desktop quota cards and the mobile menu use one presenter for provider/plan, window, percentage used and client-local reset times. The session menu scrolls inside the remaining session pane, below banners and above navigation. Markdown entries are unique by absolute file path; files in different worktrees remain separate.
Worktree discovery diagnostics: forced duplicate-branch checkouts remain visible as read-only paths, missing or moved registrations show repair guidance without automatic pruning, and a folded repository retains a diagnostic count. Bare repository metadata is excluded from missing-checkout diagnostics, including discovery from its linked checkouts. Discovery errors are reported and not cached as empty success. Bisect and relative-gitdir rebase preserve branch identity.
Unavailable detached registrations are excluded from automatic orphan cleanup in both Ask and On modes, including the Ask countdown. They remain repair diagnostics until restored or explicitly removed. Safe-only removal rechecks availability, so a directory moved after assessment cannot be pruned automatically. Explicit user-confirmed removal remains available.
Native story notes: the shared project-scoped story service appends immutable commentary with backend actor provenance, Unix-millisecond time and the current subject revision. Notes do not advance story revisions. Optional workflow evidence stores validated {runId, commandId} references to persisted receipts in the same project and plan, not copied payloads. Story detail lists notes with author/time/revision provenance and receipt IDs, provides an append-only add field, and has an explicit Refresh notes control for external additions. Drafts and pending replies stay scoped to the selected story.
AI Chat slash commands
A leading / opens the selected conversation’s ACP command offer with descriptions,
input hints, prefix filtering and keyboard/mouse completion. Agent invocations keep
/<name> <arguments> prompt text. Supported host actions (/new, /clear, /quit
with /q, /usage, and advertised /compact, /fork, /pause, /resume) use the
existing controls, not model prompts. Unknown or unsupported commands retain the
draft and show an inline list of available commands (#2393-19fc). A leading path
token with another / is prompt text unless it is an advertised command name;
bare unknown names remain command attempts (#2421-6e0a).
Ego terminal usage (#2386-6f7c)
Ego terminal usage uses the exact live pid lease and ego usage --json --session <id> reports v3–v6. The badge does not show the ego model or context. Subscription quotas come from the provider quota registry under the key that the foreground ego harness owns; an ego session never borrows a Claude or Codex CLI account. The status bar reads that quota from the shared registry store, with no provider request on a session switch. The ego quota owner reads only ego’s rate_limits contract: passively, the provider-limit observations in the usage report v6 supply the badge quota for every provider; actively, ego auth usage <provider> --json runs with the bound EGO_HOME. Ego ledger costs do not supply badge quotas; session details still show ledger accounting. Unsupported report versions return an error and log one warning per process, rather than silently emptying the badge. The executable comes from the live terminal, not the AI Chat setting.
Story drafts from requests
New story accepts a plain request and fills an editable draft through the existing unattended ego turn. Fill never saves; explicit Create story persists reviewed fields and the optional problem atomically. Busy, cancel and error states preserve the request. Cancel stops only the owned one-shot connection. See the native stories guide.
ACP controllers can supply a launch-only environment map to one fresh connection. Overrides are not persisted or exposed in connection reads; reconnect drops them, and an env-bearing connect to a live peer requires an explicit disconnect first.
Native story search projection
Native story commits feed an optional read-only mdkb daemon projection under
tuic-stories. Persisted ingest revisions include notes without advancing the
subject revision. Desktop and headless hosts compare ID/revision inventories on
connection, retry unavailable daemons every 30 seconds, and retain deletion
tombstones. Story mutations do not depend on daemon availability. Closed and
archived stories stay searchable. No story file is written to the project;
plans and the story mutation API are unchanged. See the native stories guide.
Archived worktree retention
Opt-in global and per-repository retention in days (0/Off by default). Repository refresh removes only eligible recorded checkouts under __archived/, keeps dirty or unsafe archives with named status reasons, and retains commit recovery refs. No new timer or branch deletion. See Worktrees.
Typed workflow commands (WF05)
Published Run command and versioned Tool nodes execute argv or explicit shell contracts in assigned workspaces. Durable resource waits and immutable source/target receipts reuse build-slot/rb admission; unknown effects retain resources until observed stop/release. Secret references and declared output schemas keep secrets out of receipts and refuse zero-match test proof. Native proof remains distinct from Linux execution. See docs/backend/workflows.md for the backend contract; Designer controls are not added by WF05.
Typed workflow plan proposals (WF04 foundation)
Contract-3 Create Stories visits accept a durable, activation- and plan-revision- bound proposal batch through the shared run command API. The daemon consumes native keyed story effects without a Coordinator node or session. Missing input is an incident, not a request to spawn an author. Contract-2 replay and the plan-only Create Stories boundary remain unchanged. ACP launch and lifecycle handover/closure are not part of this foundation.
WF04 attribution increment: new daemon workflow launches retain the original workspace baseline and managed launch reference before spawning. Retries do not replace the baseline with child edits. Bound typed reports also retain durable accepted/refused decisions, with accepted decisions atomic with their report event and read-only inspection through the shared run action. This is receipt disposition, not artifact approval. ACP/policy/continuation/successor/owned-close lifecycle remains incomplete; attribution and report receipt permit no cleanup.
Pinned workflow evidence policy
Workflow graph drafts can pin typed, source-and-requirement-bound review proof, seven-rule FIX/STORY/ACCEPT triage and separate review/repair budgets. The default policy permits two reviews and one repair. Native independent approval and required deterministic checks remain mandatory. PR review subjects do not mark native stories Done. Old publications and runs keep their prior policy. See workflow evidence policy.
Durable workflow timer receipts
Workflow contract-3 runs persist absolute deadlines, stable owner/effect keys, bounded retry/backoff and explicit expiry outcomes. Independent service timers can flush a one-row cohort through a recovery pause. Activation pauses retain their deadlines; cancellation fences delivery. Question expiry never implies approval. This is internal infrastructure for later proof, provider and inbox consumers, not a new Designer control. See workflows.
Pending prompt recall and transcript cleanup
ArrowUp in an empty desktop Compose or AI Chat composer recalls the latest host-owned user prompt after successful withdrawal. AI Chat supports text-only ACP prompts; desktop Compose supports the PTY idle-gate FIFO for every detected agent. Native CLI Pending receipts are not cancellation handles. Slash menus, nonempty drafts, and modified arrow keys retain their normal behavior.
Terminal Chat keeps short inline code chips together. Empty ACP plan snapshots clear the prior steps without drawing a blank Plan card.
Branch-local workflow decisions
Workflow questions and approvals retain structured answer schemas, revision and subject fences, actor provenance and restart-safe deadlines. An unanswered question suspends its activation, not disjoint delivery. The project inbox counts pending and expired questions without a coordinator; all transports use the same service. No timeout grants consent. See workflow decisions.
Post-land workflow proof cohorts
Workflow integration debt has repository-owned, timer-flushed cohorts of up to twelve landings, a single durable parent waiter, pinned validation commands and explicit unfinished states. Dispatch requires an approved explicit operator and complete gate policy. Later landings remain separate debt. Registry backup and restore preserve raw identities and omitted evidence with verified digests.
Pinned reusable workflow Calls
Contract-6 workflows can call bounded same-daemon decision/check definitions with transitive definition/routing-policy pins, declared boolean input/output receipts and stable activation-owned child identities. Completed, blocked, failed, cancelled and uncertain remain distinct. Recovery reuses the child; cancellation requests stop without erasing independent integration proof debt. Story Dispatch remains the delivery fan-out. Usage coverage stays unknown until measured. See backend contract. AI Chat settings includes a persisted Master prompt textarea for additive behavior instructions on new conversations (8192 UTF-8 bytes maximum). Existing conversations keep their original user instructions. Empty adds no user instructions. Separate attended-only host guidance tells the agent that Mermaid blocks render and should be preferred to ASCII diagrams when a diagram is useful; it does not consume the master prompt byte limit or apply to unattended work.
The Plans and Stories toolbar pill shows active-plan, Ready and In progress counts with distinct glyphs and a tooltip line for each number. Ready comes from the Rust summary action, not a frontend subtraction; Done/total remains the progress bar tooltip. Ready-only work therefore remains visible when no story is running.
AI Chat as a hands-free target
Spoken prompts retain the conversation’s pinned repository or the currently viewed worktree, just like typed prompts. Unpinning, switching repository or clearing the view updates the next spoken prompt’s hint without changing the agent cwd.
The Voice target picker includes attached AI Chat sessions, docked or detached. Speech uses the existing ACP prompt queue and caller-bound speech service. Switching targets or closing the bound chat releases the binding.
Native Windows agent hook availability
Native Windows does not install or inject TUIC’s external POSIX status hooks. Hook state returns unsupported, and hook/status setters reject changes before writing preferences or user hook files. Saved preferences and existing hooks remain intact. Settings hides these controls based on the owning backend response, including remote machines. External agents retain heuristic detection; ego keeps native PTY OSC signals and its separate ACP path.
- Claude permission attention: native permission requests and permission notifications set waiting for input; matching tool outcomes and native dialog answers retract it. Ordinary idle notices remain idle, and unrelated tools preserve open dialogs.
Workflow rule controls use the existing Designer: independent duplicates retain template origin/version, discard restores the latest publication, review caps and exact Agent contracts are editable, and typed command/decision contracts are validated before publication. Plans and Stories offers explicit routing import and live/replay pin inspection.
Managed PTYs expose a configurable silence flag with one parent alarm; detached background commands have a finite configurable deadline and a timeout completion wake.
Workflow run inspection
Run history offers Inspect delivery and cost: a committed snapshot and bounded cursor delta, pinned definitions and policy, nested activations, retained reports, evidence and owned sessions. Existing incident recovery, input answers and report acknowledgments remain authoritative. Provider observations in accepted reports retain run/node/attempt ownership and deduplicate stable provider request identities. Missing usage is unknown; estimates and subscription API equivalents cannot claim settled cost parity. Machine command duration stays separate.
Waiting on you
Plans and Stories lists the project’s stories that wait for manual checks, its unanswered workflow questions and its unread reports under Waiting on you. An entry selects its story, opens Run history on the question’s run, or opens the report in the main window. The activity bell notifies each item once in WAITING ON YOU; a refresh, a reseed or a restart does not notify it again, and the entry leaves the bell when the item is resolved. An unreadable source hides its items without clearing them. Activity Dashboard shows agent health only: failures, input delivery stalls and host-owned stalled flags.
Fabbrica help requests, approvals and ask-state outside requests also appear under Waiting on you in every project and in the bell. TUIC reads them through the Fabbrica control MCP, added as the MCP upstream named fabbrica in Settings › MCP (OAuth, one owner consent). It polls every 30 s, and at once when that upstream changes state: tasks_list, then help_list for each active task, then outside_requests_list. An entry opens the Fabbrica console. Help requests and approvals are answered there; an outside request also has Accept and Decline in the section (outside_request_answer, once, then the list is read again); an answered item leaves the section and the bell on the next read. Without consent the section says Connect Fabbrica; when a read fails it says that Fabbrica state is unknown, and the bell keeps its Fabbrica entries.
Portfolio delivery intake
Opt-in durable requests retain original manual/event/mail/result/decision input, claim one pinned coordinator-free plan delivery, recover timers and graph starts, and project bounded inventory with replayable wake cursors. Story Dispatch and the independent proof service retain their existing authority. See Portfolio delivery.
Release scope and publication authority
Per-release countdown with a once-only zero notice, readiness from proof and exact-commit CI, and a publication gate that needs recorded consent for the exact artifact. See Portfolio delivery.
Persistent reports
Unread answers stay until acknowledged, expiry upkeep never drops them, digest rewrites keep ticked decisions, and stale or unchecked progress reports are not offered as current evidence. See Workflows.
Automation completion tab policy
Automation definitions accept optional close_on_finish (default false) through
MCP, HTTP, IPC and the editor. Confirmed completed runs close only their recorded
session through the existing tab-close lifecycle. Failed, unknown and input-blocked
runs stay open. This option does not remove worktrees, branches or sibling tabs.
Automations timezone selection
The Timezone dropdown filters zone names while open. It includes the names accepted by the backend, including aliases and fixed-offset zones. New automations select the host-local zone returned by schedule preview, not the browser zone. A saved zone outside the list remains selected until you choose another zone.
Internal workflow rework: immutable project-owned script/subflow descriptors keep typed IO and outcomes outside instance configuration. Publication verifies inline script content and exact child-publication targets. Runtime and authoring integration remain pending; see workflow contracts.
Reusable-operation project catalogs combine host descriptors with verified saved versions. Host-owned target-kind registration prevents a user-defined script or subflow from selecting an available native handler; descriptor IDs cannot replace host entries. These remain internal contracts, not executable authoring features.
Automatic story backend selection
Plans and Stories identifies TUIC native or Wiz with automatic/explicit provenance, availability, version and reason. Passive Wiz markers select a globally user-approved installed connector; no per-repository command map is required. Generic stories folders do not select Wiz. Unapproved, changed or failed connectors remain visible and fail closed. Explicit bindings and existing records remain supported. Capabilities and provenance refresh with project and repository changes.
- Story backend discovery retains open native work before connector approval, exposes human native/automatic overrides, pins active-run selection across restarts, resolves applicable registry scopes, and compares displayed entry/version approval identity. Dialog refresh rejects mixed backend generations. Runs started before pins keep the pre-pin rule (legacy command binding, otherwise native).
Story backend capabilities preserve limited external editing: title, priority and one criterion addition can remain available independently of full editing. Restricted backends save exactly one supported change at a time; native editing and legacy aggregate behavior are unchanged.
Plugin binary previews can request file size and exact bounded ranges through the existing fs:read capability, without reading the entire file.
Opt-in backend heap profiling
Diagnostic heap-profile builds expose controlled jemalloc captures and separate Rust allocator/native/OS metrics. Normal builds keep the system allocator. See the runbook.
Internal Jira Cloud workflow adapters provide lookup/search/create/update/comment/transitions through pinned catalog contracts, separate current write grants and original-effect observation. Public authoring/composition and live adapter acceptance remain staged. See Jira workflow contracts (#011-2a30).
Neutral workflow transports (staged): shared catalog, versioned drafts, pinned metanode graphs, validation, pure preview and retained run inspection across desktop, HTTP and MCP. Native execution requires the installed backend provider. See workflow transport.
- Staged workflow migration preview: read-only old-to-new policy/configuration report, exact legacy source pins and explicit preservation blockers. Executable conversion and Designer integration remain pending (017-70f7).
Catalog-backed migration audit: the neutral action resolves installed component pins and explicitly lists missing replacements per source node. Current full templates remain blocked; no incomplete draft or live migration is emitted (017-70f7).
Scoped neutral roles use pinned mediated profiles, literal prompts, exact native tools and host-generated source/session-bound reports. Existing-story dispatch saves exact child publication/cohort pins and joins native completed/blocked receipts through the same run owner; combined-artifact batch approval remains explicitly unattested. See the contract.
Native story proposal creation retains exact effect approval, project backend selection, durable review caps and responsible caller receipts. See workflow contracts.
Native GitHub workflow publication supports exact-head review verdicts and the separately approved MarkReady action. See docs/backend/workflows.md (024-c9ee).
Source-bound native issue effects
Native workflows can read their admitted issue and request separately approved comments or additive labels with account, requirements and generation fences. Lost write replies remain uncertain. See the workflow reference.
Native GitHub publication keeps its approved literal HTTPS destination and token through command-scoped identity rewrites, overriding host-wide Git URL rewrites without modifying saved configuration. Competing exact rewrites refuse; artifact, approval and ref lease checks still apply.
Mediated model restart continuation reconciles owned tool effects, then sends their recorded identities and results in a new exact-model prompt. A durable replacement-session fence preserves original tool history and budgets; uncertain tools, active original transports and cancellation prevent continuation. This is new-prompt continuation, with protocol evidence only; it does not resume an interrupted provider turn (#006-6885).
Review policy composition exposes a durable shared reviewer admission budget, source-bound role findings and native proposal dispositions through native.review.bounded, native.correction.policy.assess and the shared correction_policy_region action. Native independent review/current configured checks remain required. Accounting separates reviews, corrections, check attempts and proposals; exhaustion routes to the existing operator port. See backend workflow policy composition.
- Retained workflow operator decisions: exact typed waits, human and proof-gated automatic closure, and frozen-scope release consent through existing native authorities. See contract.
Getting Started
What is TUICommander?
TUICommander is a desktop terminal orchestrator for running multiple AI coding agents in parallel (Claude Code, Gemini CLI, OpenCode, Codex). Built with Tauri + SolidJS + Rust, with a native terminal engine powered by alacritty_terminal.
Key capabilities:
- Up to 50 concurrent terminal sessions with split panes and detachable tabs
- 10 AI agents supported (Claude Code, Codex, Gemini, Amp, and more)
- Git worktree isolation per branch
- GitHub PR monitoring with CI status and notifications
- Obsidian-style plugin system with community registry
- Voice dictation with local Whisper (no cloud)
- Command palette, configurable keybindings, prompt library
- Built-in file browser and code editor
- MCP HTTP server for external AI tool integration
- Remote access from a browser on another device
- Auto-update, 13 bundled fonts, cross-platform (macOS, Windows, Linux)
First Launch
-
Add a repository — Click the
+button at the top of the sidebar, or use the “Add Repository” option. Select a git repository folder. -
Select a branch — Click a branch name in the sidebar. If it’s not the main branch, TUICommander creates a git worktree so you work in an isolated copy.
-
Start typing — The terminal is ready. Your default shell is loaded. Type commands, run AI agents, or execute scripts.
-
Open more tabs — Press
Cmd+T(macOS) orCtrl+T(Windows/Linux) to add more terminal tabs for the same branch.
Workflow Overview
Add Repository → Select Branch → Worktree Created → Terminal Opens
├── Run AI agent
├── Open more tabs
├── Split panes
└── View diffs/PRs
Each branch has its own set of terminals. When you switch branches, your previous terminals are preserved and hidden. Switch back and they reappear exactly as you left them.
Sidebar
The sidebar shows all your repositories and their branches.
Repository groups:
- Repositories can be organized into named, colored groups
- Drag a repo onto a group header to move it
- Right-click a group to rename, change color, or delete it
- Groups collapse/expand by clicking the group header
Repository entry:
- Click to expand/collapse branch list
- Click again to toggle icon-only mode (shows initials)
+button: Create new worktree for a new branch⋯button: Repo settings, remove, move to group
Branch entry:
- Click: Switch to this branch (shows its terminals)
- Double-click the branch name: Rename branch
- CI ring: Shows CI check status (green/red/yellow segments)
- PR badge: Shows PR number with color-coded state — click for detail popover. CLOSED and MERGED PRs are automatically hidden (MERGED PRs fade after 5 minutes of user activity).
- Stats: Shows +additions/-deletions
Git quick actions (bottom of sidebar when a repo is active):
- Pull, Push, Fetch, Stash buttons — run the git command in the active terminal
Next Steps
- Terminal Features — Tabs, splits, zoom, detachable tabs, find-in-terminal
- Sidebar — Repos, branches, groups, park repos, quick branch switcher
- AI Agents — Agent detection, rate limits, question detection
- Keyboard Shortcuts — All shortcuts and how to customize them
- Command Palette & Activity Dashboard — Fuzzy-search actions and monitor sessions
- File Browser & Code Editor — Browse files, edit code, git status
- GitHub Integration — PR monitoring, CI rings, notifications
- Git Worktrees — Worktree workflow, configuration
- Branch Management — Checkout, create, delete, merge, rebase, push/pull
- Prompt Library — Template management, variables
- Plugins — Install, browse, and manage plugins
- Voice Dictation — Push-to-talk setup
- Remote Access — Access from a browser on another device
- Settings — All configuration options
TUICommander modes
TUICommander has one backend and several ways to connect to it. The available features depend on the client mode.
| Mode | How it is used | Best for | Main limitations |
|---|---|---|---|
| Desktop app | Launch TUICommander normally | Full local development workflow | None of the client-side limitations below |
| Browser mode | Open the local HTTP server in a browser | Remote control from a laptop or another desktop | Native dialogs, global hotkeys, updater, dictation, detached windows, and some file/clipboard integrations are desktop-only |
| Mobile PWA | Open the mobile endpoint from a phone/tablet | Monitoring agents and answering prompts | Deliberately reduced UI; not a replacement for the desktop workspace |
| Remote daemon | Run tuic-remote and connect through the remote-access flow | Hosting the backend on another machine | Requires separate remote configuration and network/security setup |
Desktop app
The desktop app runs the Tauri shell and exposes the complete feature set: native file dialogs, IDE launchers, dictation, global hotkeys, detached panels, the complete Command Palette action set, and the native updater.
For local development, use make dev or pnpm tauri dev. Frontend files use Vite HMR; Rust changes require restarting the development process.
Browser mode
The browser client uses the same backend over HTTP, WebSocket, and SSE. It is not a mock UI: sessions, terminal output, Git operations, settings, and most panels use the same backend as the desktop app.
Browser mode provides the Command Palette through the magnifying-glass toolbar button, with filename/content search over HTTP and only actions verified for the browser client. Native file pickers, global hotkeys, detached OS windows, dictation, IDE launchers, auto-updater, MCP/hooks configuration, and user-plugin installation from local files remain desktop-only.
See Remote Access for setup and Troubleshooting if the browser cannot connect.
Mobile PWA
On iPad, the root URL opens the mobile interface by default. To use the full workspace, open Settings from the overflow menu and select Open Desktop UI. The device remembers your choice for future root visits. The desktop banner’s Switch link returns to mobile and clears that choice. Both interfaces are within the installed PWA’s scope; an older installation may need its manifest refreshed before the desktop link stays in the app window.
The mobile interface is optimized for observation and quick actions: inspect sessions, follow output, answer questions, and monitor agent activity. The Files tab shows saved desktop groups and repository order in inset surfaces, with display names and short paths. Folder icons and chevrons identify directories, and the breadcrumb shows the current location; long-press a repository path to see it in full, browse normal folders ahead of hidden ones, or search nested files. In a session, tap the folder button in the header to browse that session’s repository directly; Back returns to the session with its output and unsent command intact. File editing uses the remaining screen height and wraps long lines. Use the desktop or full browser workspace for worktree management and complex Git operations.
Remote daemon
tuic-remote provides a standalone backend process for remote access. It is useful when the machine running the repositories is different from the machine displaying the UI.
See Remote Access for connection methods, TLS/relay options, and configuration details.
Troubleshooting
This page collects the most common problems when using TUICommander. Start with the quick checks, then inspect the application logs if the problem persists.
Quick checks
- Confirm that the agent binary works outside TUICommander (
claude,codex,gemini, etc.). - Confirm the repository is a valid Git checkout and that the selected directory is writable.
- Check that the terminal is using the expected shell and PATH.
- Restart the affected terminal tab before restarting the whole app; the PTY and other tabs can remain alive.
- Check the application log endpoint:
curl 'http://localhost:9876/logs?limit=200'
A second debug/test instance normally uses the next available port, such as 9877.
The agent is shown as idle or busy incorrectly
Agent state is inferred from terminal output and, for supported agents, can also be driven by native hooks. Check the following:
- the correct agent type is selected or detected;
- the agent is not waiting for a hidden confirmation prompt;
- native hooks are enabled under Settings > Agents when available;
- the terminal is not displaying a full-screen TUI whose state cannot be inferred reliably;
- the agent has not changed its prompt format in a newer release.
If only one agent is affected, capture the terminal output and check the relevant agent page under docs/architecture/agents/ before reporting a regression.
A session was not restored
Session restore is lazy and branch-scoped. Select the repository and branch that owned the session first. Agent sessions may show a resume banner instead of executing a resume command automatically; activate the banner to continue.
Plain shell tabs are intentionally not restored as live processes after an application restart. Create a new shell tab instead.
A worktree is missing or the branch is not visible
Check the repository’s worktree list from a shell:
git worktree list
A worktree involved in a rebase, merge, cherry-pick, revert, or bisect should not be removed automatically. If the directory was deleted externally, refresh the repository state and check the application log for the removal reason.
GitHub, PR, or CI data is stale
- Verify that Settings > Git & GitHub shows the intended account as signed in. The
ghCLI login is not used. - Check the repository remote and account binding in Settings.
- Use Fetch or refresh the GitHub panel.
- Check whether the provider is rate-limited or temporarily unavailable.
- For multiple GitHub accounts, confirm that the repository is bound to the correct account.
Browser mode does not show a feature
Browser mode intentionally lacks some desktop integrations. See TUICommander modes for the complete distinction.
The Command Palette, native file picker, global hotkey, dictation, IDE launcher, updater, detached OS windows, and installation of user plugins from local files require the desktop app.
For a connection problem, verify that the backend is listening on the expected port and that the browser can reach it from the same network. Inspect the browser console and the backend logs before restarting.
Clipboard or file opening behaves differently in a browser
Browser mode uses browser clipboard and file-opening APIs where native integrations are unavailable. Permissions, HTTPS requirements, popup blocking, and browser focus can affect the result. Retry the action from the desktop app to distinguish a browser limitation from a backend problem.
Dictation cannot build or start on Windows
Whisper builds require CMake and libclang. This project currently expects LLVM 18 for the Windows whisper-rs bindings. Set LIBCLANG_PATH to the LLVM bin directory before building. See Development Setup.
MCP or OAuth problems
Check the upstream server status, authorization URL, and the application log. For a local MCP endpoint, verify that the client is using the current protocol/session configuration. A client that does not support tool-list refresh may need to reconnect after MCP configuration changes.
Performance problems
Enable runtime diagnostics only while reproducing the problem:
curl -X POST http://localhost:9876/diagnostics \
-H 'Content-Type: application/json' \
-d '{"enabled":true}'
curl 'http://localhost:9876/logs?source=diagnostics'
Disable diagnostics after the investigation. See Performance Profiling for a deeper investigation workflow.
What to include in a bug report
Include:
- TUICommander version and platform;
- desktop, browser, mobile, or remote-daemon mode;
- agent and agent version;
- repository/worktree context, without secrets;
- exact reproduction steps;
- relevant logs with tokens and credentials removed;
- whether the issue survives creating a fresh terminal tab.
Community & support
Join TUICommander & Co on Discord for questions and ideas. Use #support, #ideas, or #plugins in the TUICommander category. The server is checked once a day. Report reproducible bugs in GitHub issues.
Terminal Features
With CLI terminal input focused, Ctrl+Enter sends a distinct modified Enter when the program has negotiated Kitty keyboard reporting. Identified ego sessions also receive this encoding to steer a busy turn, because current ego does not negotiate the mode. Legacy shells and other nonnegotiating agents receive ordinary Enter (CR). Plain Enter submits normally; Shift+Enter keeps its multiline behavior. Browser and remote grid terminals use the same encoding. The mobile Ctrl menu uses the same Ctrl+Enter bytes for ego. Compose shortcuts remain separate.
Remote terminals replay their current viewport when attached or reconnected. A stream failure or stalled initial replay shows a persistent error toast; the client retries without requiring new terminal output. See Remote Access.
On desktop and mobile CLI views, adjacent 💬 answer paragraphs share one continuous green left bar without a background tint (Paper uses its darker success green for contrast), including blank rows between them. Mobile places this bar in a separate gutter outside the text box, so column-zero text stays clear and existing agent indentation stays unchanged. An unmarked prose paragraph after a blank row ends the answer; an uninterrupted indented continuation stays inside. The CLI gutter joins separate marked answer sections across internal blank rows and indented section headings when a later marked answer closes the gap. Trailing unmarked prose, unmarked list siblings, tools, prompts and status rows stay outside that gutter; extracted Answers and Chat keep their semantic paragraph boundaries. Lists, tables, quotations and fenced code remain attached to the answer. Fenced code keeps its inset and a separate Copy row above the text on desktop and mobile; the control does not cover wrapped lines. A non-answer output row, prompt or Codex Worked for duration footer ends the region. The desktop CLI blanks only the marker glyph cells; copy, selection and search keep the original text. Mobile omits the same protocol glyphs from displayed text while retaining ANSI styles and links; search still uses the original log text. Chat uses the same answer extent and strips every paragraph marker. A list item whose text starts with 💬 also opens an answer: hard-wrapped continuation rows and nested sub-items belong to it, but an unmarked sibling or dedented prose does not. The list bullet stays visible; only the answer marker is hidden. Standalone fenced terminal examples keep protocol-looking answer, intent and suggestion text literal, even when no marked answer precedes the fence. User prompt echoes do not open answer regions. A quoted marker inside uninterrupted pasted prose stays in the prompt. An agent output bullet, a column-zero answer marker, or a blank-separated answer marker begins output; indentation alone does not decide ownership. The viewport uses tracked prompt starts even when a long prompt begins outside its marker lookback. If that prefix is not cached, answer markers wait for bounded prompt-boundary reads rather than being inferred from the visible fragment. CLI marker classification examines at most 128 rows above the visible window and reuses unchanged row generations; an answer anchor farther above that window is not inferred from continuation prose.
Turning Show scrollbar marks off or on updates history ticks immediately, even when the terminal is idle. Search-match ticks remain visible when history marks are off.
The Context preview truncates before the CLI/Chat switch. The switch shares the Context row in both modes. When Context is hidden, both modes reserve the same control row above the content. Terminals without that switch use the full header width.
Tablet Keyboard
Tap the terminal to focus its keyboard input. Touch and mouse input use the same field, including soft-keyboard text entry and repeated deletion. Primary mouse presses keep focus on that input without a temporary canvas focus change.
Terminal Sessions
Each terminal tab runs an independent PTY (pseudo-terminal) session with your shell. Up to 50 concurrent sessions.
Files uploaded through the mobile picker live in a session directory under TUICommander’s data directory. New Claude and Gemini sessions receive read access at launch. Closing the terminal or ending its process removes these uploads; resumed sessions need files uploaded again. Uploads leave your repository and Git excludes untouched. Old .tuic/attachments/ directories can be removed by hand. Confined ego sessions need an existing user/profile read root; the picker shows an access notice.
Accents sent separately from their base letters remain part of terminal text when you scroll, select, copy or search. Search matches the exact characters printed by the program: precomposed and decomposed spellings are not automatically normalized into each other.
In the mobile session output, a small upward drag stops auto-follow. New output does not scroll the view until you return to the bottom. While following, opening the keyboard or resizing the viewport keeps the newest output visible. A reader who has scrolled up keeps their position through a viewport resize.
When the viewed agent exits, the mobile session returns to the shell: question controls close, Chat returns to CLI, and the composer sends shell input. The CLI view shows new shell output even when the terminal retains the old agent screen; the old agent input is not restored into the composer. Fresh session polling also clears stale agent controls if the output socket pauses or reconnects. If the PTY ends, Session ended offers Back to the session list.
In the mobile session output, completed lines continue into history even after the terminal history fills, while the live region redraws below. Long text wraps to the phone width. A continuation keeps the original line’s leading spaces or tabs, so indented lists and code remain readable. Claude tool-call status dots keep the same space while pulsing or turning green, and wrapped continuations align after that space. Box-drawing output keeps its horizontal scrolling layout.
Creating Terminals
- Cmd+T — New terminal for the active branch
+button on sidebar branch — Add terminal to specific branch+button on tab bar — Open the agent launch menu. Agent and run config choices rank by branch usage, then repository usage when the branch has no history. Choose Terminal or Alt/Option-click+for a plain terminal;Cmd/Ctrl+Tis unchanged. Agent icons and larger rows make the list easier to scan. Multiple configs show their names beside the agent; a check marks the default. Single-config agents show only the agent name.
New terminals inherit the working directory from the active branch’s worktree path.
Desktop frame receipts do not generate more terminal output. After a missed frame, desktop receives one full frame and connected browsers retain their delta stream. Output batching remains bounded. Input-related output that arrives during a frame send keeps its bounded retry; this does not guarantee echo within one display frame.
CWD Tracking (OSC 7)
When your shell reports directory changes via OSC 7, TUICommander updates the terminal’s working directory in real time. If the new directory falls inside a different worktree, the terminal tab is automatically reassigned to the corresponding branch in the sidebar.
Terminal Lifecycle
Terminals are never unmounted from the DOM. When you switch branches or tabs, terminals are hidden but remain alive. Switch back and your process, scroll position, and output are exactly as you left them.
Closing Terminals
- Cmd+W — Close active tab (confirmation only when a user-launched process is running — e.g. Claude Code, htop, npm; idle shells and shells still loading .zshrc close immediately)
- Middle-click on tab — Close tab
- Right-click → Close Tab — Context menu
- Right-click → Close Other Tabs — Close all except this one
- Right-click → Close Tabs to the Right — Close tabs after this one
Reopening Closed Tabs
- Cmd+Shift+T — Reopen the last closed tab
- Last 10 closed tabs are remembered with their name, font size, and working directory
- Reopened tabs start a fresh shell session in the original directory
CLI / Chat view
Busy Session Chat sends wait in TUIC’s idle-gate queue on desktop and mobile. Each host-owned Pending prompt has Cancel and, for Claude, Codex and ego, a Send now action. Send now forces the same steering flow for all three: interrupt the current turn with Escape, wait for its ready composer, then submit the selected prompt before queued mail. It does not background a tool or queue text inside the busy CLI. This applies while Stop hooks run too. The tooltip reads Send now: stop the current request. A prompt already claimed by another sender is not sent again. A refused action keeps an unwritten prompt queued and reports the error; an uncertain write requires inspection, not an automatic retry. Native CLI receipts from earlier direct sends remain read-only.
Session Chat and its composer belong to their terminal tab. Go to repo on a progress toast opens the reporting terminal when it is still open. Otherwise it selects a surviving tab in the destination workspace, or clears the terminal area when that workspace has none. It does not leave a foreign repository’s Chat active.
On desktop, returning from Chat to CLI focuses the terminal input. You can type immediately after using the switch, closing Chat Compose, answering in CLI, or falling back from unavailable Chat. Only the active terminal restores focus, and an automatic fallback does not take the caret from an editable field outside that terminal.
Session Chat shows a pulsing Working… row after Send and while the terminal reports busy. It disappears when the terminal reports idle or awaits a question or permission answer. Desktop and mobile use the existing session state; Chat does not infer activity from the conversation text.
A terminal that runs Claude Code, Grok, Codex or ego shows a CLI | Chat switch in its top-right corner. Chat replaces the grid with the conversation read from Claude’s own session file: your prompts as bubbles (including follow-ups typed while Claude is busy), Claude’s replies as text, and tool calls folded into one compact card each. Plumbing (hook output, system reminders) and empty thinking blocks are left out. The desktop switch has its own row in Chat, so it does not cover the first prompt even when the context bar is hidden. Compose opens and receives focus below the conversation. Reply with Enter, or queue follow-up work with Shift+Ctrl+Enter. Active native question and permission choices appear above Compose. Select a named choice to send its native keys to that terminal, without sending or clearing your Compose draft. Questions without exported choices show Answer in CLI; Codex free-form alternatives also return to CLI. PTY Chat is separate from ACP AI Chat. The grid keeps running while hidden, so scrollback and selection are unchanged. Prompts have a theme-coloured background in Chat and a reading width of up to 80 characters; the CLI grid does not tint submitted prompts.
Expanded tool rows use theme colours for Bash/execute commands, flags, strings and operators. Read, Edit and Write keep the tool name separate from the path; other tools retain readable text. The collapsed activity summary and row sizing are unchanged.
For ego, configure an absolute ego executable in Settings that supports local transcript v1, including --after. This is the executable Chat uses, even if your shell launches a newer ego from another path. A failed export reports the configured path and exit status; check that Settings points to the transcript-capable binary. TUICommander binds the foreground ego process to the session whose lease names that PID, then reads ego export SESSION --format transcript --after SEQ from the same EGO_HOME. It does not select the newest session in the folder or read ego’s private event files. The existing Chat ticker follows committed entries; message previews are omitted and completed answers appear once. Tool starts and results share a card. Goal continuations and compaction checkpoints appear as system notices, not user prompts. A new session binding resets the conversation rather than joining unrelated histories. Missing binding, unsupported export versions and unreadable sessions return to CLI with a reason. ego Chat is available immediately after a page reload, including while a native question or permission prompt is pending. It does not wait for the frontend to rediscover a session ID. The backend still checks the live process and lease before reading. ego Chat is also available on mobile through the same transcript lifecycle and existing event stream.
Notice cards preserve line breaks between their heading and body. Harness inbox wakes are hidden in terminal Chat. Interruption notices remain compact chips. Images without retained image data appear as attachment chips. Consecutive thinking blocks share one disclosure. Answer blocks in the same turn share one reading card, limited to about 96 characters wide. Only the answer blocks selected by the CLI boundary rule have a green bar; unmarked prose after a blank row and later status text remain outside it on desktop and mobile. Copy in its top-right corner appears on hover or keyboard focus and copies the whole answer. Intermediate status prose remains separate and uses the normal readable text colour. The green bar belongs to an outer answer-region container, never to a list item. Adjacent answer blocks share a continuous rail, including paragraph spacing. Answer lists retain their normal indent so bullets and numbering stay to its right. A partially marked or nested list stays intact inside that outer rail: unmarked parents and siblings are visible context, not additional marked answers. Lists are not split, so ordered numbering and nesting stay unchanged. Tool calls keep their single collapsed activity row; Claude Bash uses the agent-written description when available, while other tools and agents retain the backend title. Pasted CLI calls followed by a terminal output marker appear in a monospace block showing two lines; + N lines expands the rest. Ordinary multiline prose stays as prose. Historical tool rows show status without a duration. Turn timestamps do not reach the frontend, so time separators are omitted. The Compose handle is available in CLI view. It stays muted with no button chrome at rest; hover or keyboard focus reveals its background and border without fading the label or queue count.
After clicking the desktop Chat transcript, typing a printable character returns focus to Compose and inserts it at the draft caret or selection. Transcript text selection, copy, search, and scrolling keep their normal behavior; typing does not take focus while transcript text is selected.
On desktop CLI terminals, opening Compose reserves its minimum editor row and footer below the terminal. Longer drafts grow upward over terminal output, so typing does not repeatedly resize the terminal. Shrinking the draft keeps that space reserved; closing Compose restores the full terminal height. Pinning keeps Compose open without changing this layout. Clicking the terminal, or pressing Esc in pinned Compose, collapses the editor to its minimum so the terminal input row stays visible. The full draft remains scrollable. Focusing Compose again restores its growth without resizing the terminal. Mobile and Chat retain their existing layout.
In Chat, Compose stays docked and open after sending or queueing, clears the submitted text, and keeps focus for the next message. It cannot be closed or unpinned while Chat is active. Esc returns to CLI for terminal interaction; the Compose shortcut focuses the Chat input. Switching back to CLI restores that tab’s previous Compose open and pin state. Unsent drafts survive switching in either direction, including text entered while a send or queue is still pending.
On mobile, Codex and Grok also offer CLI | Chat in the session header. The backend must confirm the exact Codex native-hook or Grok registry transcript binding; a missing binding returns to CLI with a reason. The existing question controls, keyboard bar and composer keep targeting the same PTY. Select CLI for native terminal interaction.
Local agents started through tuic agent spawn or HTTP remain eligible for Chat. HTTP/MCP creation controls worker-tab styling, cleanup and completion sounds; it does not mean that the PTY runs on another machine. A session owned by a configured remote connection remains unavailable to Chat.
Chat is disabled, with the reason as its tooltip, when the terminal has no agent, the agent has no supported transcript adapter, or a required frontend binding is missing. Claude and ego check their transcript binding in the backend when Chat opens, so a missing saved session ID does not disable their switch. If the agent exits or the binding is lost while Chat is open, the terminal returns to CLI with a one-line notice.
Chat applies each transcript snapshot as one update on desktop and mobile. Opening or reopening Chat shows Loading conversation… until its first snapshot arrives; it reports an empty conversation only after the backend confirms that there are no entries. Opening Chat or switching back from CLI keeps the full history without rendering each partial replay. Chat follows new transcript entries while the agent writes. When you scroll up and more content arrives, New text below appears above Compose. Select it to return to the bottom and resume following. Reaching the bottom by hand also clears it. Search jumps show no indicator until later content arrives. Turn the indicator off in Settings → Appearance → Chat; this preference is saved on the current client. A replaced transcript resets the displayed conversation, including when the replacement keeps the same file name and size.
Older recorded prompts with a prompt ID also appear when Claude did not record a human-origin field. Command echoes, tool results and sidechain conversations stay out of user bubbles. Image and PDF tool outputs show [image] and [document] markers; a model fallback shows a Model changed card.
Suspending a Tab
Right-click → Suspend Tab ends the tab’s process and its agent, freeing the memory and CPU they used, and keeps the tab in the tab bar marked zz. It is not auto-standby: auto-standby pauses an eligible idle process, which keeps its memory, and wakes it when you focus the tab. Agents running as separate foreground jobs inside an interactive shell are not auto-stopped, because the shell would reclaim their terminal. Remote viewing and typing prevent standby for a full timeout window after the last activity or disconnect. Desktop typing also wakes an already parked shell, even if the tab did not send another visibility change. A suspended tab holds no process at all.
- Resume — click Resume in the tab, or right-click → Resume Tab. A new session opens in the same folder. An agent tab runs the same resume command a tab gets after a TUICommander restart, so the agent continues its conversation. A plain shell tab opens a fresh shell.
- Restart — Rust saves suspended tabs before ending their processes. They stay suspended after a restart or frontend recreation, even when suspension happened with no UI open; they are never resumed automatically.
- Refused while busy — Suspend is disabled while the agent is working, a question waits for your answer, commands are queued, or a command runs in a plain shell, so no turn is cut. An agent tab with no resumable session is refused too.
- MCP —
session action=suspend session_id=<id>does the same for a tab another agent wants to park, under the same refusals.
Tab Management
Tab Names
- Default naming: “Terminal 1”, “Terminal 2”, etc.
- Double-click a tab to rename it (inline editing)
- Press Enter to confirm, Escape to cancel
- Explicit custom names persist through reconnects and are never replaced by agent output
- Agent labels from the launch menus are base names, not custom names. Agent intent and terminal titles can replace them. An explicit user or MCP rename remains protected.
- Spawn-assigned agent labels are base names: an
intent: text (Title)marker may replace them with the current work phase, even when its text wraps across many terminal rows - Mobile CLI also keeps complete
intent:text visible, rejoins terminal soft wraps, and tints every browser-wrapped row with the same theme warning colour. - The canvas keeps
intent:rows visible with a theme-aware warning tint for ego, Claude and Codex. It removes completesuggest:marker rows and their continuation rows from the displayed grid. They occupy no selectable line and are excluded from copied text, including selections that cross scrollback. Suggestion chips remain independent of this projection. When blank separators surround the removed block, one separator remains instead of two adjacent blank lines. - Agent terminals show an expandable Context bar. It separates the model’s current Intent, the orchestrator-owned Assignment, and the last substantial user Prompt. MCP-connected models are instructed to refresh intent at task start and whenever the material work phase changes
- Captured intent and prompt are recovered when reconnecting to a live session, including an idle agent. Prompt retains the most recent submission with at least ten words; shorter follow-ups do not replace it.
Tab Reordering
Drag tabs to reorder them. Visual drop indicators show where the tab will land.
Tab Indicators
| Indicator | Meaning |
|---|---|
| Grey dot (dim) | Idle — no session or command never ran |
| Blue pulsing dot | Busy — producing output now |
| Green dot | Done — command completed |
| Purple dot | Unseen — completed while you were viewing another tab (clears when selected) |
| Orange pulsing dot | Question — agent needs user input |
| Red pulsing dot | Error — API error or agent stuck |
| Question icon | Agent is asking a question |
| Progress bar | Operation in progress (OSC 9;4). An indeterminate report (state 3) fills the tab width |
| Amber gradient | Session created via HTTP/MCP (remote session) |
Final API failures keep the red Error dot even when the agent prints a completion summary or returns to idle. Optional auto-retry (run by the backend, so it also works for mobile and headless sessions) sends up to three continue commands (after 5, 15 and 30 seconds); an idle agent that does not resume stays red. A retry that falls due while the session still reads busy waits and rechecks every 5 seconds instead of being dropped. Native provider retry countdowns do not count as final failures. Actual resumed work clears the error, and the next successful idle turn returns to Done.
Sidebar branch icons also show purple when they contain unseen terminals. The mobile session list and session header use the same status colors: blue for working, green for idle, orange for input, and purple for a completion not yet opened on that phone. Opening the session clears its purple status.
Agent activity combines native lifecycle hooks, terminal movement (text changing above the input area means the agent is active), and the visible ready prompt. Claude, Codex, Gemini, Grok, pi, and OpenCode require a stable ready screen before safety-sensitive actions such as auto-standby or queued agent message delivery. Pressing Ctrl-C or Escape requests interruption but does not turn the dot green until the agent confirms the interruption, returns to its prompt, or exits.
A newly launched detected agent remains in its starting state until terminal activity is actually observed. Question and answer transitions are retained by the backend even if a browser or event-stream client temporarily falls behind.
Current Claude and Codex status lines are also recognized when their interface keeps an empty composer visible or freezes during a long tool. Completed timing summaries are not treated as work, so the indicator can still return to idle. If a mail wake reaches Claude while its detailed transcript hides the composer and Claude produces no response, the indicator returns to idle after five minutes without output, provided the last lifecycle hook reported idle. Grok keeps its composer visible while responding, so TUICommander waits for the animated status row to disappear before treating that composer as ready. Queued notices to Claude and Codex may take several seconds to confirm while their hooks or internal prompt queues run. If TUIC reports that agent input was not confirmed, inspect the transcript and composer before pressing Enter again.
A ready prompt means the terminal can accept input; it does not necessarily mean the agent’s turn is finished. If the agent still owns a background command, the activity indicator remains working, parent-agent idle/completed notifications are deferred, and auto-standby will not pause the session. Persistent integration helpers are ignored, so they do not keep a completed turn active indefinitely.
Tab Shortcuts
Hover a tab to see its shortcut badge: “Terminal N (Cmd+N)”. Use Cmd+1 through Cmd+9 to jump directly. Ctrl+Tab / Ctrl+Shift+Tab — Next / previous tab.
Scroll Shortcuts
| Shortcut | Action |
|---|---|
Cmd+Home | Scroll to top |
Cmd+End | Scroll to bottom |
Shift+PageUp | Scroll one page up |
Shift+PageDown | Scroll one page down |
Selecting text during output
Selections remain attached to the same retained text while new output arrives, including when the scrollback buffer reaches its limit. Once selected rows are evicted, the selection is cleared instead of moving onto their replacements. Resizing or switching between the primary and alternate screen also clears the selection because the row layout changes.
Scrollback in fullscreen apps
Agents launched through TUICommander, including supported agents typed into a new TUIC shell, use native scrollback where their CLI supports it (see AI Agents). This keeps past conversation lines available after the agent exits. The separate alternate-screen history below remains for programs that use fullscreen mode, such as vim and less, and for agents that enter it despite their launch defaults.
Apps that take over the screen (gh run watch, less, man, TUIs) run on the terminal’s alternate screen, which by the original terminal spec has no scrollback at all — anything printed past the bottom of the window is gone. TUICommander enables an isolated alternate-screen history, so the scrollbar stays available and you can reach what rolled off the top.
Two details worth knowing:
- The scrollback of a fullscreen app is wiped when it exits, and never mixes with your shell’s history.
- TUICommander preserves the application’s actual output. A live view that reprints a frame taller than the viewport can therefore leave repeated snapshots in history; they are not deduplicated.
- Apps with mouse support (
vim,htop,lazygit) receive the wheel themselves — use Shift+wheel or drag the scrollbar to scroll TUICommander’s history instead.
Zoom
Per-terminal font size control:
| Action | Shortcut | Effect |
|---|---|---|
| Zoom in | Cmd+= | +2px font size |
| Zoom out | Cmd+- | -2px font size |
| Reset | Cmd+0 | Back to default size |
Range: 8px to 32px for the CLI grid. Each terminal has its own zoom level. Desktop session Chat and AI Chat share a 14px default reading scale, independent of the configured grid default. A terminal zoom step changes its Chat text by the same amount; AI Chat follows the active terminal. Reset returns both Chat views to their default reading scale. Chat body text stays between 8px and 32px. Zoom shortcuts work in either terminal view; the all-terminals variants update both views too. The current grid font size is shown in the status bar. Mobile keeps its device-local Chat font preference.
Split Panes
Split the terminal area into two panes:
Creating Splits
- Cmd+\ — Split vertically (side by side)
- Cmd+Alt+\ — Split horizontally (stacked)
The new pane opens a fresh terminal in the same working directory. Maximum 2 panes at a time.
Drag to Split
Drag a tab from the tab bar, or from the tab strip of a pane, into the terminal area. While you drag, a highlight shows where the tab goes:
- Near an edge (left, right, top or bottom) — the pane splits in half and the tab takes that side.
- In the center of a pane — the tab moves into that pane.
Without a split, the whole terminal area is one pane: drop on an edge to create the first split next to the tab on screen. When a pane cannot split again, its edges act as its center. A pane that loses its last tab closes.
Navigating Split Panes
- Alt+←/→ — Switch between vertical panes
- Alt+↑/↓ — Switch between horizontal panes
- The active pane receives keyboard input
Resizing Split Panes
Drag the divider between the two panes to adjust the split ratio. Both terminals re-fit automatically when you release.
Maximizing a Split Pane
- Cmd+Shift+Enter — Maximize / restore active pane (zoom pane). Expands the focused pane to fill the full terminal area; press again to restore the split.
Closing Split Panes
- Cmd+W closes the active pane and collapses back to a single pane
- The surviving pane automatically receives focus
Split Layout Persistence
Split layouts are stored per branch. When you switch branches and come back, your split configuration is restored.
Detachable Tabs
Float any terminal into its own OS window:
- Right-click a tab → Detach to Window
- The terminal opens in an independent floating window
- The PTY session stays alive — the floating window reconnects to the same session
When you close the floating window, the tab automatically returns to the main window.
Requirements: The tab must have an active PTY session. Tabs without a session (e.g., just created but not connected) cannot be detached.
Find in Terminal
Search within terminal output with Cmd+F:
- Press
Cmd+F— a search overlay appears at the top of the active terminal pane - Type your search query — matches highlight as you type (yellow for all matches, orange for active match)
- Navigate matches:
EnterorCmd+G— Next matchShift+EnterorCmd+Shift+G— Previous match
- Toggle search options: Case sensitive, Whole word, Regex
- Match counter shows “N of M” results
- Press
Escapeto close the search and refocus the terminal
In CLI, search is integrated directly with the terminal grid for accurate match highlighting. In Chat, Cmd/Ctrl+F opens the transcript search: enter text and press Enter / Shift+Enter, or use Next / Previous, to select and scroll to matches. Matches span inline Markdown formatting within a paragraph; collapsed thinking bodies are skipped until opened. Escape closes search, including after clicking the navigation buttons. Switching CLI/Chat closes the search and clears its highlight.
The search bar opens below the Context and CLI/Chat switch row. Both search navigation and the view switch stay reachable, including in narrow panes.
Cross-Terminal Search
Search text across all open terminal buffers from the command palette:
- Press
Cmd+Pand type~followed by your search query (e.g.~error) - Results show terminal name, line number, and highlighted match text
- Press
Enteror click a result to switch to that terminal and scroll to the matched line (centered in viewport) - Minimum 3 characters after the
~prefix
Also accessible via the “Search Terminals” command in the palette.
Copy & Paste
- Copy: Select text in the terminal, then
Cmd+C. A “Copied to clipboard” confirmation appears in the status bar. Multi-line Claude messages paste as clean text: the repeated▎visual gutter is removed while bullets, numbering, and indentation are preserved. Inside such a quote, rows that Claude broke only to fit the terminal width are joined back into one paragraph, so pasting into Slack or an email keeps whole sentences. Blank rows, list items and deeper indents keep their own line, and a quote that never reaches the terminal edge is copied exactly as shown. Claude prompt selections also remove the first❯marker and the two-column continuation margin. Width-supported wraps join, while short typed lines and additional content indentation remain. A glyph pasted inside the prompt remains part of the text. Composer cleanup applies only when the selection starts at column zero of the first composer row. Selecting body text or a VT soft-wrap continuation preserves literal markers and indentation. - Paste:
Cmd+Vwrites clipboard content to the active terminal. Text takes priority when a copied Chat selection or other rich content also includes an image. Screenshot-only pastes and copied image filenames from Finder still send Ctrl+V so terminal agents can attach the image.
Copy on Select
When enabled (Settings > Terminal > Copy on select), selecting text in the terminal automatically copies it to the clipboard. A brief “Copied to clipboard” confirmation appears in the status bar. This is enabled by default.
Clear Terminal
Cmd+L clears the terminal display. Running processes are unaffected.
Terminal Bell
The bell behavior when receiving BEL character (\x07) is set by bell_style in config.json (Settings has no control for it):
- none — silent
- visual — brief screen flash
- sound — plays notification sound
- both — flash and sound
Clickable File Paths
File paths appearing in terminal output are automatically detected and become clickable links. Hover over a path to see the link underline, then click to open it. Verified link underlines stay visible while unrelated tool indicators animate, including links that wrap across terminal rows.
.md/.mdxfiles open in the Markdown viewer panel- Other source files open in the built-in editor
- A
:lineor:line:colsuffix opens the built-in editor at that position, including for Markdown files. Clicking another position in an already-open file moves its cursor without replacing unsaved edits
Paths are validated against the filesystem before becoming clickable — existing files and directories show as links. Directory links open the File Browser at that directory; file links open the usual viewer or editor. Tilde paths expand to the home directory, and relative paths resolve from the terminal working directory. A path removed before opening shows a short notification instead of an empty tab. Sentence periods after a printed path are not part of the link. Dots inside file and directory names remain part of the path. Absolute paths can point outside a registered repository, including files in hidden directories.
Recognized extensions include: .rs, .ts, .tsx, .js, .jsx, .py, .go, .java, .css, .html, .json, .yaml, .toml, .sql, and many more.
Plan File Detection
When an AI agent emits a plan file path (e.g., PLAN.md), a button appears in the toolbar showing the file name. Click it to open the plan — Markdown files open in the viewer panel, others open in the IDE. Click the dismiss button (x) to hide it.
Working with AI Agents
When TUICommander sends text followed by Enter to an agent, it leaves a short pause so terminal-based agent interfaces can process the text first. An agent whose type is still unknown uses the longer Codex-safe pause.
TUICommander detects rate limits, prompts, and status messages from AI agents:
- Rate limit detection — Recognizes rate limit messages from Claude, Gemini, OpenCode, Codex
- Prompt interception — Detects when agents ask yes/no questions or multiple choice
- Status tracking — Parses token usage and timing from agent output
- Progress indicators — Shows progress bars for long-running operations
When an agent asks a question, the tab indicator changes and a notification sound plays (if enabled).
On the mobile PWA, a waiting Codex request_user_input question adds a control to the session header. Tap it to open Codex’s question panel. The question and numbered options appear above the composer; tap an option once to answer. Tap Other to enter a typed note. The panel overlays the terminal without permanently reducing its height. The Rust parser that supplies those options takes effect after TUICommander restarts.
For a Claude AskUserQuestion dialog, the mobile session shows the title and
all choices and presents those choices above the composer. Tap a choice to
navigate to it and submit it; the app uses Claude’s arrow-and-Enter contract.
If a Claude picker appears only in the CLI output, use the key bar’s Up/Down
and Tab buttons to navigate it, then Enter to select. Navigation does not send
or replace a typed answer in the mobile composer.
Claude /resume also keeps its session list and search results visible in CLI
view. Use Up/Down and Enter to select a session, or Esc to close the picker.
The backend update requires a TUICommander restart before it reaches an
already-running development instance.
Remote HTTP/MCP workers respect Silence orchestration completions even after
a frontend reload, and a single busy cycle produces at most one completion
notification when idle and process exit arrive separately.
Generic desktop notifications such as “needs your attention” do not by
themselves mark the tab as awaiting input; TUICommander requires explicit
permission, approval, or waiting-for-input wording, an agent hook, or a verified
question on screen.
Questions inside a wrapped suggested follow-up action do not mark the tab as awaiting input.
On mobile, a blocked report can keep its Input state and still offer suggested follow-up actions. These actions replace generic Yes/No buttons. Native dialog choices take priority over suggestions; without either, generic confirmations remain available.
Canceling a Codex approval with Esc clears its question indicator when Codex returns to its composer.
Queueing Follow-up Commands
Compose starts at one line. Newlines and wrapped text grow the editor up to 96px, then the draft scrolls inside it. Clearing the draft or sending it returns the editor to one line.
In Compose, paste an image, drop PNG, JPEG, WebP or GIF files on the editor, or use Attach images beside Send to choose several. Drops insert at the pointer; picked files replace the current selection in their chosen order. Each saved image appears as [image: <path>]. Other file types and failed saves show an error without inserting a tag.
The Compose panel can leave work for an agent without steering its current turn:
- Enter sends immediately.
- Ctrl+Enter or Shift+Enter inserts a new line without sending. The hint shows only Ctrl+Enter. Shortcut hints disappear in compact panels instead of wrapping; the bindings still work.
- Enter that confirms an IME candidate does not send the draft.
- Shift+Ctrl+Enter or the queue button submits immediately when the agent is already idle; otherwise it waits for the next idle window.
- Queued user commands and peer messages share one FIFO and are delivered one item per idle window in acceptance order.
- If an idle agent reports blocked progress, your queued command answers that wait. Native questions and permission dialogs still require an explicit answer before queued work can be delivered.
- The collapsed Compose button shows a small muted count for all waiting items, including commands and peer/orchestrator messages in the same FIFO. It disappears when the queue is empty. Hover or focus the button to see the command/message breakdown. On touch screens, open Compose and tap N queued to inspect the waiting items; opening Compose does not expand the list.
- In the open panel, N queued opens the queue list. Cancel removes one entry, or use Clear all to discard all waiting entries, including TUIC notices. Removing a mail notice does not delete the peer message from its inbox.
The Compose N queued list has a labelled Cancel action for each item and keeps Clear all. Supported items also show Steer, which uses the same backend delivery as Session Chat Send now. Claude, Codex and ego all interrupt the current request before submitting the selected text. There is no busy-queue fallback. Steer is hidden while a native question waits.
Queueing is available only for detected agent sessions, not plain shells.
After a queued command reaches Codex, TUICommander allows several seconds for a stop hook to finish before deciding whether the agent accepted it. If no Working screen appears, check the transcript and composer before pressing Enter again; TUICommander will not replay an uncertain command automatically.
Submitting through MCP
Automation that must start a new managed-agent turn uses one
session action=submit session_id=<id> input=<command> call. TUICommander
refuses busy agents, interactive dialogs, partial drafts, and sessions with
older queued work instead of steering or overwriting them. The same response
reports whether the complete PTY write occurred and whether the child terminal
moved after Enter; no follow-up polling call is required. Terminal movement
does not mean the agent understood the command or completed the work. If a
complete write times out without movement, do not replay it automatically.
session action=input remains available for raw text, prefilling, and
interactive keys. Its ok:true reports only that bytes were written.
Session Restore
On restart, only terminals that had an active agent session are restored — plain shell tabs are discarded and a fresh terminal is spawned. For restored agent tabs, a clickable banner appears: “Agent session was active — click to resume.” Clicking the banner sends the agent’s resume command. Press Escape or click the x button to dismiss the banner without resuming.
OSC 8 Hyperlinks
Terminal output that uses the OSC 8 standard for hyperlinks (e.g., URLs emitted by ls --hyperlink) is supported. Clicking an OSC 8 hyperlink opens the URL in your system browser. A network path or a custom-scheme link (editor://…, smb://…) opens with its system handler after you confirm the exact target in a dialog.
Answers-only View
Use Toggle answers-only view (Cmd+Alt+R on macOS) to read selectable marked answers and their tracked prompts. Turns without marked answers are omitted. Output before the first tracked prompt remains available as a prompt-less turn, from the retained history base. If no answers qualify, the view shows a one-line notice. Toggle the view again to return to the terminal.
Stored terminal marker coordinates
When old output leaves the scrollback, command boundaries and prompt ticks stay attached to their retained output. Ticks for discarded prompts disappear; answers-only history keeps the retained question and answer association.
Terminal stream reconnect notices use the current terminal name when available and show the transport’s current attempt (up to 10). A received grid frame or confirmed empty replay removes only that stream notice; socket opening alone does not. Exhausted retries leave a persistent failure notice. Closing the terminal removes its notice, and late subscription failures cannot publish a notice after closure.
Open a terminal link in Design Mode
Right-click an HTTP or HTTPS link, including a localhost dev server, then select Start in Design Mode and choose Edge or Chrome. The dedicated browser opens that URL and connects the agent in that terminal, not the focused tab. File and other non-web links retain Open and Copy link only. The extension loads automatically on a cold launch; close an open Design Mode window first.
History-anchored viewport scrolling
Scrolling into history keeps the requested lines in view while an agent writes more output. If the scrollback limit removes those lines, the view stops at the oldest retained line. Scroll to the bottom to follow output again.
Desktop dictation in Chat
Dictation inserts into Compose when focus is on the Chat transcript or page background. It replaces the selection that existed when you pressed the hotkey and keeps the rest of the draft. A focused search or form editor still receives dictation. In CLI, dictation keeps the usual terminal and auto-send behavior.
Changing focus or tabs while transcription finishes does not change the destination. If the original editor or session closes, or its draft changes, recover the text from the sticky error message or Messages bell. The app does not send it to another terminal.
Waking a suspended tab
Open a suspended tab to resume it. A submitted command or peer message can also wake it without the desktop UI. Commands wait until the agent is ready; messages stay in its inbox. The stable peer address does not change. If resume fails, the tab stays suspended and the caller receives the reason.
Mobile Claude Chat
Select Chat in the session header to read the shared conversation view. The backend decides whether the Claude transcript is available, including when the desktop has not discovered a session id yet. An unavailable transcript returns the view to CLI with a notice. The mobile composer stays available in both modes. Switch to CLI for questions missing from Chat; CLI returns to the latest output.
Automatic idle-agent hibernation
The backend checks unattended top-level agent tabs every five seconds. agents.hibernate_idle_minutes defaults to 60 awake minutes; zero disables the sweep. agents.hibernate_scope defaults to background_only; always also permits foreground hibernation. Both machine-owned controls are in Settings → Agents (Expert Mode).
Hibernation requires an idle agent and a verified resume session in its saved profile. Plain shells and agents without a verifiable resume session stay live. Unread peer mail, pending commands or background work, awaiting input, attached readers, keep-open tabs and open automation runs prevent hibernation. Managed children retain their separate idle-close policy. Sleep gaps longer than 30 seconds do not advance the idle clock.
The normal Rust suspension path persists reason: "idle_hibernate" before ending the PTY. Opening the tab, submitting input or sending peer mail uses the shared wake path. Storage or resume-verification failures leave the live session intact.
ego provider recovery
When terminal ego reports a provider outage, its tab shows recovering rather
than a working animation. The status bar shows the recovery phase, attempt,
next attempt time and seconds remaining. Zero seconds means the scheduled time
has arrived, not that the provider has recovered. Force retry submits
/retry once to that terminal. If the composer contains a draft, the retry is
refused without changing the draft. The status bar displays the refusal. Managed parents receive recovery entry and exit
notices; MCP callers can use session action=force_retry session_id=<id>.
Recovery clears when ego explicitly clears it, resumes busy/idle state, or
returns to the shell prompt. This terminal protocol is separate from ACP retry.
Copying marked answers
Terminal selection copy, AI Chat answer buttons (desktop and mobile), and the Answers view omit the leading 💬 protocol marker. List prefixes and emoji inside prose or fenced examples stay in the copied text.
Spaces at terminal wrap points
Mobile CLI output and session text reads preserve spaces when text wraps at the terminal margin. A word split across two terminal rows remains one word. Explicit line breaks remain separate. The mobile client uses exact wrap information from current backends; older backends retain the previous text reflow behavior. Chat reads the agent transcript separately and does not rebuild text from terminal rows.
On mobile, scroll back in CLI or Chat to show the floating down-arrow at the bottom-right of output, above the key bar. Tap it to return to the latest output without sending terminal input. The button hides at the bottom and stays outside the composer.
Abandoned shells
Desktop sidebar session rows and mobile session cards mark a parentless plain shell as Abandoned after one idle hour and show its idle age. The five-second backend sweep requires a fresh OS process inventory: the PTY child must be an interactive shell with no child processes. An unknown inventory, script, foreground command, background child, detached TUIC job, managed identity, live child session, pending input or keep-open hold prevents closure. Unsupported or incomplete OS process observations fail closed.
Settings → Agents → Idle agent hibernation (Expert Mode) includes Close abandoned shells after (hours) (agents.abandoned_shell_hours). The machine-owned value defaults to 0 (off); whole hours from 1 to 65535 enable closure. Idle age is measured from the most recent input, output or semantic activity, including elapsed time while the machine sleeps. Closure rechecks the process inventory and activity at the destructive boundary, and uses the normal session close/tombstone path. The sweep can lag the threshold by one five-second tick. A remote daemon applies its own setting, not the desktop host’s value.
Mobile dictation and command messages
Mobile dictation edits the visible composer. On its first edit, the composer reconciles an existing terminal input snapshot instead of appending to an unseen desktop draft. Later dictation takes continue the visible draft. The blue / quick key is an insertion action, not a selected modifier. Tap it to insert a slash; choose a command explicitly to use autocomplete.
In session Chat, a Claude slash-command user message shows its command name and arguments. Complete command envelopes are presentation metadata; quoted or incomplete XML remains literal text. The Copy action retains the original transcript text.
Terminal Chat removes a pending prompt bubble when the native transcript records its receipt, including prompts that the view truncates or redacts. The view keeps pending prompts in send order.
Recall a host-owned pending prompt
With an empty desktop Compose editor, press ArrowUp to withdraw the newest user command from TUIC’s idle-gate queue and edit it. Notices and initial prompts are not recalled. The command is restored only if queue removal succeeds before delivery. A normal Send’s muted Pending bubble belongs to the native CLI and cannot be withdrawn by this action. AI Chat’s shared ACP composer supports the same shortcut for text-only queued turns. Nonempty drafts and slash menus keep their normal arrow-key behavior.
Global Workspace membership
Right-click a terminal tab or a session row in the sidebar to copy its session ID, process ID or alias when available.
Right-click a terminal tab or a session row in the sidebar and select Add to Global Workspace. For an existing member, select Remove from Global Workspace instead. This changes workspace membership without closing the terminal.
Sidebar
The sidebar is your primary navigation for repositories, branches, and git operations.
Session identifiers
Right-click a session row under any main or linked branch to open its menu. Copy session ID copies the PTY session ID. Copy process ID copies the live PTY child PID, not an agent tool subprocess. A toast confirms each copy. Copy alias copies the exact alias accepted by MCP (for example, orc-1). The process and alias entries are hidden when their values are unknown. Hover an entry to see its value; process and alias values are read again before copying. Left-click still selects the terminal.
Toggle & Resize
- Toggle visibility:
Cmd+[ - Resize: Drag the right edge (200–500px range)
- Width persists across sessions
Repository Management
Adding Repositories
Click the + button at the top of the sidebar and select a git repository folder.
Repository Entry
Each repo shows a header with the repo name and action buttons:
- Click the header to expand/collapse the branch list
- Click again to toggle icon-only mode (shows repo initials — saves space)
⋯button — Opens a menu with: Repo Settings, Create Worktree, Move to Group (with submenus for existing groups, Ungrouped, and New Group), Park Repository, Remove Repository- Right-click main worktree row → Switch Branch submenu: shows all local branches with a checkmark on the current one. If the working tree is dirty, prompts to stash changes first. Blocks switching when a terminal has a running process.
Removing Repositories
Repo ⋯ → Remove. This only removes the repo from the sidebar — it does not delete any files.
Repository Groups
Organize repos into named, colored groups.
Creating a Group
- Repo
⋯→ Move to Group → New Group… - Enter a name in the dialog
Moving Repos Between Groups
- Drag a repo onto a group header
- Or: Repo
⋯→ Move to Group → select a group - To ungroup: Repo
⋯→ Move to Group → Ungrouped
Managing Groups
Right-click a group header for:
- Rename — Change the group name
- Change Color — Pick a new accent color
- Delete — Remove the group (repos become ungrouped)
Groups can be collapsed/expanded by clicking the header, and reordered by drag-and-drop.
Branches
Selecting a Branch
Click a branch name to switch to it. This:
- Creates a git worktree (for non-main branches) if one doesn’t exist
- Shows the branch’s terminals (or creates a new one)
- Hides terminals from the previous branch
Branch Indicators
Each branch row can show:
| Indicator | Meaning |
|---|---|
| CI ring | Proportional arc segments — green (passed), red (failed), yellow (pending) |
| PR marker | A colored square and the PR number. The color shows the highest-priority state; a conflict turns the square into a diamond. Hover or focus it for the state name, such as Draft, Conflicts, or CI Failed. Click for detail popover. |
| Diff stats | +N / -N additions and deletions, always shown beside the PR marker. Hover for exact counts and uncommitted files. |
| Dirty badge | The workspace contains staged, unstaged, or untracked changes. Hover or focus the badge for the removal-safety explanation. |
| Merged badge | Branches merged into main show a “Merged” badge |
| Unmerged mark | A small outlined square means the worktree has commits outside the default branch. A zero diff or dirty count does not mean those commits are merged. |
| Unknown badge | TUICommander could not verify the workspace state, so removal is blocked. Hover or focus the badge for the inspection error. A missing default branch shows No base branch. Branch-name tooltips show each diagnostic once; main checkouts do not show removal warnings. |
| Question icon | An agent in this branch’s terminal is asking a question |
| Grey icon | No active terminals in the repo — branch icons dim to grey |
Branch Actions
- Double-click the branch name to rename the branch
- Right-click for context menu: Copy Path, Add Terminal, Create Worktree (for branches without a worktree), Delete Worktree, Open in IDE, Rename Branch/Worktree, Merge & Archive
A clean worktree can be removed with its local branch when the branch tip is contained in any remote-tracking branch, even with a different name and no upstream. The remote branch stays intact.
When removal would delete an unmerged branch, the error card offers Remove worktree, keep branch. The action reruns lifecycle checks and confirmation with branch deletion disabled for that removal only; the repository setting stays unchanged.
Agent and session activity
Nested agent and terminal rows are an opt-in feature and are disabled by default. Enable Settings → Appearance → Tabs → Nested Terminal Tabs to show them; the change applies immediately.
When enabled, each branch with open terminal sessions has a separate, always-visible chevron to show or hide agents. The status icon and row select the branch. Enter or Space activates the focused chevron. The collapsed session count stays beside it. Agents are shown by default, and collapsed state is remembered. Expanded, the list shows a single activity card containing the sessions assigned to that branch:
- Detected agents show their icon, terminal name, current intent or task, last-update age, and status.
- A sub-agent row has a muted robot tag; hover or focus it to see the parent agent. The GitHub badge in the repo header keeps its accent color.
- Plain shells appear as terminal rows.
- Clicking a row switches to that session.
- A branch with one session can still expand.
When the setting is off, the sidebar intentionally shows none of the activity card or nested rows. Enabling it does not create a session or detect an agent outside an open terminal assigned to the branch.
Remote-Only PRs
When a repository has open PRs on branches that only exist on the remote (not checked out locally), a badge appears in the branch section. Click it to open a popover listing these PRs. Each row shows the PR number, title, and state badge. Click a row to expand an inline accordion showing PR details, with action buttons:
- Checkout — Create a local tracking branch
- Create Worktree — Create a worktree for the branch
- Merge — Merge the PR via GitHub API (shown when PR is mergeable)
- View Diff — Open PR diff in a panel tab
- Approve — Submit an approving review
Dismiss & Show Dismissed
Remote-only PRs can be dismissed to reduce sidebar clutter. Right-click the remote PRs badge or use the “Dismiss” action in the accordion. A “Show Dismissed” toggle at the bottom reveals dismissed PRs again.
Park Repos
Temporarily hide repos you’re not actively using.
Parking
Right-click any repo in the sidebar → Park. The repo disappears from the main list.
Viewing Parked Repos
A button in the sidebar footer shows all parked repos with a count badge. Click it to open a popover listing them.
Unparking
Click Unpark on any repo in the parked repos popover. It returns to the main sidebar list.
Compact and rich layout
The layout button in the toolbar (left of the filter icon) cycles the sidebar through three modes and prints the current one on itself: R (rich), C (compact), H (harness-only, with rich rows). R and C restore at startup. A saved H opens as R, because harness sessions are not live yet at startup.
Compact is the one-line rows. Rich keeps the same navigation density and adds facts:
- Branch: the PR state word and title; last-commit age; ahead/behind of the upstream (
↑2 ↓1); diff stats;N dirty(click opens Changes);Merged,Stale(no commit for 30 days, not merged),Unknown(removal blocked, status could not be read) andunmerged. Each chip explains itself in a tooltip, with the same removal-safety text compact shows. A main checkout never shows stale, merged, dirty or unknown. - Agent: its state (Working, Idle, Needs input, Error) and what it is doing; its in-session subagents, one line each with state, title, tool calls and age (more than three fold into “N subagents”, click to expand); TUIC child sessions nest under their parent agent.
- Repository: current branch, positive open-PR and worktree counts, and the age of the last remote poll.
Compact carries the same facts in tooltips: the branch name’s tooltip has the commit age, ahead/behind and the stale rule; an agent row’s tooltip has its state and line. Subagents and nesting exist only in rich.
H shows only branches with a live harness session, together with their repositories and groups. R and C clear this harness filter. The separate active-only filter stays available in every mode. Older Auto preferences open in rich mode.
Subagent lines come from the existing progress_flow command, read at most every 5 seconds per repository, only in rich.
Active-Only Filter
When you have many repos open, hide the ones you aren’t using right now.
Click the filter icon in the toolbar (next to the sidebar collapse button) to show only repositories that have at least one open terminal. The icon turns accent-colored while the filter is on, and a banner at the top of the sidebar shows how many repos are shown out of the total — click it (or “Show all”) to clear the filter. The filter is session-only and resets when you restart.
Quick Branch Switcher
Switch branches by number without the mouse:
- Hold
Cmd+Ctrl(macOS) orCtrl+Alt(Windows/Linux) - All branches show numbered badges (1, 2, 3…)
- Press a number (
1–9) to switch to that branch instantly - Release the modifier to dismiss the overlay
Git Quick Actions
When a repo is active, the bottom of the sidebar shows quick action buttons:
- Pull —
git pullin the active terminal - Push —
git push - Fetch —
git fetch - Stash —
git stash
For more git operations (staging, commit, push, pull, stash, blame, history), use the Git Panel (Cmd+Shift+D).
Touch Branch Actions
Swipe a branch row left to reveal More, +, and, for removable linked worktrees, a red remove button. More opens the branch menu. Tap + to add a terminal, or hold it to choose an agent. Removal uses the existing confirmation dialog and is disabled while removal is in progress.
Swipe right, tap the row, or tap elsewhere to close the actions. Opening another row closes the previous one. Vertical swipes continue to scroll the sidebar. Mouse and trackpad actions appear over the right edge of the row on hover or keyboard focus. Crowded facts do not push the actions outside the sidebar or scroll row names left.
In rich mode, sessions idle for more than two hours fold into an expandable count. Backend activity timestamps determine age; busy sessions, awaiting input, unread output, selected rows and parents of visible children stay visible. Expanding preserves row order. Compact mode does not fold idle sessions.
Rich working agent rows reserve two clamped intent lines. Idle, awaiting-input and error rows stay on one line with status dots; their full intent, task or prompt remains in the tooltip. Compact rows keep their one-line layout.
Rich navigation keeps compact typography and padding. Branch identity and facts share one line, with names truncated and full PR/lifecycle facts in tooltips. Repository metadata disappears when PR and worktree counts are both zero. Header controls use compact sizing to protect repo names. Returned subagents fold into an expandable count independently of running work.
In rich mode, ungrouped repositories with open terminals appear first, followed by an Idle section. Manual order is preserved inside each section. Idle headers start on one line; disclosure reveals their branches without changing activity or saved order. Headers count agents in the backend working state, independently of open-terminal membership.
Rich active/idle sections also apply independently inside each existing repository group. Group membership and group ordering remain intact; active-only filtering hides idle-only groups and empty Idle headings.
Rich merged linked worktrees with no sessions and verified lifecycle facts use a one-line summary: Merged, N uncommitted, Clean up. Live, unmerged, or unknown worktrees retain full rows. Clean up enters the existing lifecycle preflight and confirmation workflow; cancellation preserves the worktree.
Rich parent terminal rows show N agents in each other repository containing live children. Clicking reveals the child group, repository and workspace, then selects a child through existing terminal navigation. Session placement and same-branch nesting stay intact; closed children disappear from summaries.
Detached worktrees
Detached checkouts have non-selectable rows with their directory name, short SHA and detached. Hover shows the full path and HEAD SHA. The repository header retains a detached count while folded. These rows do not change branch selection, terminal placement or rich-mode idle-session folding.
File Browser & Code Editor
File Browser Panel
Drop files from Finder onto a folder or empty panel space to transfer them into that directory. A remote repository always receives a copy over its connected daemon; your Mac originals stay in place. Confirm directory recursion before copying folders. Existing destination names are skipped, as with local drops. Uploads are limited to 256 MiB (including archive overhead) and 10,000 entries per top-level source; symlinks and special files are not uploaded. The remote destination must be inside a registered repository. Executable scripts keep their safe permission bits, and filenames follow the destination platform rules. Slow uploads continue while data arrives; 30 seconds without data aborts the transfer.
Toggle with Cmd+E or the folder icon in the status bar. The file browser shows the directory tree of the active repository (or linked worktree when on a worktree branch).
The file browser, Markdown viewer, and Diff panels are mutually exclusive — opening one closes any other that is open.
The file browser opens in tree view by default. Use the toolbar buttons to switch between the tree and flat list. Your choice is saved.
Navigation
- Arrow keys (
Up/Down) — Move selection - Enter — Open a file or enter a directory
- Backspace — Go up to the parent directory
..row — Click to go up one level (appears when inside a subdirectory)- Breadcrumb bar — Click any path segment to jump directly to that directory; click the root
/to return to the repo root
Symbolic links show a link icon, target path and target kind (directory, file, or unavailable). The link text length is not shown as a file size. Links are followed wherever they point, also to another volume: you can open, edit, create and delete files through a linked directory or file. Typed and requested paths stay relative to the repository: absolute paths, drive or network paths and a .. that climbs above the repository root are refused. The .tuic-start-work.md Tasks template is the exception: its text goes to an agent without a click, so a link out of the repository is refused.
Delete removes the selected symbolic link, including an unavailable link, without deleting its target or target contents. A failed deletion shows the backend error in a persistent error notification.
Directories are listed first, then files. The entry count is shown as a badge in the panel header.
Sorting
Click the funnel icon in the toolbar to switch sort order:
| Mode | Order |
|---|---|
| Name (default) | Directories first, then alphabetical |
| Date | Directories first, then newest modified first |
Live Refresh
Successful drops refresh the listing and expanded tree folders immediately, including the source after a move and transfers accepted in the confirmation dialog.
The panel watches the current directory and each visible expanded tree folder for filesystem changes. Files and folders created, deleted, or renamed outside the app appear automatically without manual refresh. This also applies to non-Git folders and nested Git repositories. Collapsed folders reload when expanded again, so they do not retain changes missed while unwatched.
Git Status Indicators
The panel header shows a legend for git status colors:
| Color | Label | Meaning |
|---|---|---|
| Orange | mod | Modified (unstaged changes) |
| Green | staged | Staged for commit |
| Blue | new | Untracked (new file) |
File and directory names inherit these colors based on their git status. Gitignored entries are shown in a dimmed style.
View Modes
The file browser supports two view modes, toggled via toolbar buttons:
| Mode | Description |
|---|---|
| List (default) | Flat directory listing with breadcrumb navigation and .. parent entry |
| Tree | Collapsible hierarchy with lazy-loaded subdirectories. Expand folders by clicking the chevron |
Switching to tree mode resets to the repository root regardless of the current flat-mode subdirectory. When a search query is active, the view always shows flat results.
Filename Search
Type in the search box to search recursively across the entire repository by filename. Supports * and ** glob wildcards (e.g., *.ts, src/**/*.test.ts). Results appear with their full path. Clear the query with the × button or by emptying the input.
The search icon button to the left of the input toggles between filename mode (file icon) and content mode (magnifier icon).
Content Search
Switch to content mode (magnifier icon) to search inside file contents across the repository. Results are grouped by file, showing the matching line number and a highlighted excerpt. Highlights remain aligned on lines containing accented text, symbols, or emoji. Click any result to open the file in the editor, jumping to that line.
Content search options (shown when in content mode):
| Toggle | Meaning |
|---|---|
| Aa (case icon) | Match case |
.* (regex icon) | Use regular expression |
|ab| (word icon) | Match whole word |
A status bar below the search box shows match counts, files searched, files skipped (binary/large), and a “results limited” notice when the result set is truncated. Search begins after a short debounce and requires at least 3 characters.
File Operations (Context Menu)
Right-click any entry to open the context menu:
| Action | Shortcut | Notes |
|---|---|---|
| Copy Path | — | Copies the full absolute path to the clipboard |
| Copy | Cmd+C | Files only; stores file in the internal clipboard |
| Cut | Cmd+X | Files only; cut entries are shown dimmed |
| Paste | Cmd+V | Pastes into the current directory; disabled when clipboard is empty |
| Rename… | — | Opens a rename dialog; enter the new name and confirm |
| Delete | — | Requires confirmation; directories are deleted recursively |
| Add to .gitignore | — | Appends the entry’s path to .gitignore; disabled if already ignored |
The keyboard shortcuts (Cmd+C, Cmd+X, Cmd+V) also work when the file browser has focus, without opening the context menu.
Cut + Paste performs a move (rename). Copy + Paste duplicates the file into the current directory. Pasting into the same directory where the file already exists is a no-op.
Opening Files
- Click a file — Opens it in the code editor (see below), or in the Markdown viewer if the extension is
.mdor.mdx - Click a content search result — Opens the file and jumps to the matching line number
Panel Resize
Drag the left edge of the panel to resize it. Range: 200–800 px.
Code Editor
Clicking a non-Markdown file opens it in an in-app code editor tab in the main tab area, alongside terminal tabs.
Features
- Syntax highlighting — Auto-detected from file extension; disabled for files larger than 500 KB
- Line numbers, bracket matching, active line highlight, indentation support
- Save —
Cmd+Ssaves the file when the editor tab is focused - Wrap lines — Click the wrap button in the editor header or press
Alt+Z(Option+Zon macOS). Text, logs, unknown file types, and Markdown start wrapped; code starts unwrapped. The choice is remembered separately for text and code files on this client. - Open links — Hold
Cmd(macOS) orCtrl(Windows/Linux) to underline a link, then click it. HTTP(S) URLs open in the system browser. Markdown links and absolute,~/, file-relative, or repository-relative paths open in TUICommander. Add:lineto jump to a source line. Directories open in the File Browser; a missing path shows a toast.
Read-Only Mode
Click the padlock icon in the editor tab header to toggle read-only mode. When locked, the file cannot be edited.
Unsaved Changes
An unsaved-changes dot appears in both the tab bar and the editor header when the file has been modified but not saved.
Disk Conflict Detection
If the file changes on disk while you have unsaved edits, a conflict banner appears with two options:
- Reload — Discard local edits and load the disk version
- Keep mine — Dismiss the banner; the next save overwrites the disk version
When the editor has no unsaved changes, files reload silently when they change on disk.
Markdown Viewer
.md and .mdx files open in the Markdown viewer panel instead of the code editor. The viewer renders Markdown with syntax-highlighted code blocks.
Links in rendered Markdown stay inside TUICommander: file links open a Markdown or media preview when supported, otherwise the code editor; directory links open the File Browser. #heading scrolls within a document, and file.rs:42 or file.rs#L42 opens the editor at that line. Relative paths resolve from the Markdown file, including percent-encoded spaces and local symlinks; a direct UNC/network href (\\server\share\doc.md, //server/share/doc.md) and a custom-scheme link (editor://…, smb://…) open with the system handler only after you click it and confirm the exact target in a dialog. TUICommander never probes the network host before that. Missing files show a toast. Web and email links open with the system handler; javascript:, data: and similar WebView schemes stay blocked.
See ai-agents.md for how AI-generated plan files are detected and surfaced as a one-click shortcut to open in the viewer.
Browser HTML and Markdown previews load local images only from open repositories and their linked worktrees, through the authenticated repository image route. Images outside those roots show “Image unavailable: outside open repositories.” Desktop asset loading is unchanged.
Filename searches share a path-only inventory per repository. Repeated queries filter it in memory; result sizes and timestamps are read from disk for matches. Repository events invalidate the inventory, and a 60-second reconciliation bound covers roots without a repository watcher. Cold queries share one build per repository. Up to eight repository inventories are retained, with ten-minute idle eviction.
Markdown image paths can use . and .. to refer to images next to the document or in parent folders. The desktop preview resolves these segments before creating the local asset URL.
Command Palette & Activity Dashboard
Command Palette
In the desktop app, open the palette with Cmd+P (macOS) / Ctrl+P (Windows/Linux). In browser mode, use the magnifying-glass button at the right of the toolbar; this remains reliable when the browser reserves or swallows the shortcut. The command palette gives you fast access to the actions available in the current client mode.
How It Works
- Press
Cmd/Ctrl+Pin the desktop app, or click the browser toolbar button — the palette opens with a search input focused - Type to filter actions by name or category (substring match, case-insensitive)
- Navigate with
↑/↓arrow keys - Press
Enterto execute the selected action - Press
Escapeor click outside the palette to close
What You See
Each row shows:
- Action label — What the action does (e.g., “Git panel”, “New terminal tab”)
- Category badge — The action’s category (Terminal, Panels, Git, Navigation, Zoom, Split Panes, File Browser)
- Keybinding hint — The assigned keyboard shortcut, if any
Search Behavior
Filtering matches against the action label and its category simultaneously. Typing “git” surfaces all Git actions; typing “panel” surfaces all panel-toggle actions regardless of category. There is no minimum query length — results update on every keystroke.
Recency Ranking
When the search box is empty, recently used actions float to the top, ordered by most recent first. Remaining actions are sorted alphabetically. The ranking persists across palette opens so your most-used commands are always one keystroke away.
Mouse Support
Hovering over a row highlights it (same as keyboard selection). Clicking a row executes the action immediately.
Project Progress
Run Open Terminal Progress to open the active terminal’s journal in a dialog.
Use the selector to inspect another terminal or the whole repository.
This action is available in desktop and browser mode. The same dialog opens from
the always available Terminal Progress entry in the notification bell, or
with Cmd/Ctrl+Shift+P. The bell badge counts unread outcomes. Use Mark as read
in the bell’s Progress section to clear that count without opening or deleting the journal.
Powered by the Action Registry
The palette is auto-populated from actionRegistry.ts. The desktop app exposes the complete registered action set. Browser mode uses an explicit allowlist and omits actions that require native dialogs, detached OS windows, the native updater, desktop-only MCP configuration, or user-plugin management. This fail-closed policy prevents a newly added desktop action from appearing in the browser before it has a working web or HTTP implementation. Browser-capable plugin actions appear alongside built-in ones.
Search Modes
The command palette supports three search prefixes:
| Prefix | Mode | Description |
|---|---|---|
! | Filename search | Search files by name (min 1 char) |
? | Content search | Search inside file contents (min 3 chars) |
~ | Terminal search | Search across all open terminal buffers (min 3 chars) |
- Leading spaces after the prefix are ignored (
~ error=~error) - File results show as a flat list with file path
- Content matches include line number and highlighted match text
- Terminal matches include terminal name, line number, and highlighted match text
- Press
Enteror click to open the file in an editor tab, or navigate to the terminal match - Terminal match navigation switches to the correct tab/pane and scrolls to the matched line
- Delete the prefix to return to command mode
- Search runs with a 300ms debounce
- Footer shows
!,?, and~hints when in command mode - In browser mode, filename and content searches use the same backend over HTTP. Each content search carries a random correlation ID local to the requesting page, so another window or panel cannot inject results into the palette
If no repository is selected, file/content modes show “No repository selected”. If no terminals are open, terminal mode shows “No terminals open”.
Discoverable Search Commands
You can also access search modes via explicit commands in the palette:
| Command | Action |
|---|---|
| Search Terminals | Opens palette with ~ prefix |
| Search Files | Opens palette with ! prefix |
| Search in File Contents | Opens palette with ? prefix |
These appear as regular commands in the palette — type “Search” to find them.
Paste a work-item URL
Paste an issue, pull request or ticket URL into the palette. When an installed work-item plugin recognises it, the palette shows one entry above the commands:
- Open worktree <branch> (<key>) — a worktree is already linked to that item; the palette switches to it and creates nothing.
- Start work on <key>: <title> — creates a worktree for the item in the active repository and opens an agent with the item as a draft brief. Review the brief and press Enter to send it.
With no work-item plugin installed, a pasted URL is searched like any other text.
Activity Dashboard
Open with Cmd+Shift+A, or click the Agents ticker in the status bar. You can also focus the ticker and press Enter or Space. Its cycle badge still advances to the next ticker.
A real-time overview of all your terminal sessions.
The overlay stays compact in the main window and fits narrow windows; detaching
it keeps the same list in a separate window.
What You See
A compact list where each row shows:
| Column | Description |
|---|---|
| Terminal name | The tab name |
| Agent type | Detected agent (Claude, Codex, etc.) with brand icon |
| Status | Current state with color indicator |
| Last activity | Relative timestamp (“2s ago”, “1m ago”) — auto-refreshes |
Spawned agent rows include a robot-head marker. Hover it to see the parent terminal’s name, or “external agent” when its tab is unavailable.
Status Colors
| Color | Meaning |
|---|---|
| Green | Agent is actively working |
| Yellow | Agent is waiting for input |
| Red | Agent is rate-limited (with countdown) |
| Gray | Terminal is idle |
A terminal with a ready input composer is shown as idle even if the agent left a long-lived background terminal, such as a development server, running.
Interactions
- Click any row — Switches to that terminal and closes the dashboard
- Rate limit indicators — Show countdown timers for when the limit expires
The dashboard is useful when running many agents in parallel — you can spot at a glance which ones need attention, which are stalled, and which are making progress.
Automations
Automations opens scheduled agent runs on the connected app’s machine. The entry is available in desktop and browser mode. See the Automations guide. It requires the Automations backend API.
Plans and Stories
Plans and Stories opens the Plans and Stories dialog for the active repository.
Workflows
Workflows opens the Workflows space for the active repository: Definitions (the Workflow Designer) and Runs (every run of the project, newest first). It opens without a selected plan or story. A run started from a plan or story shows Open in Plans and stories, and Plans and Stories has a Workflows button; each space keeps its own selection. It does nothing when no repository is active. The entry is available in desktop and browser mode. See Native Stories.
Keyboard Shortcuts
All shortcuts use Cmd on macOS and Ctrl on Windows/Linux unless noted.
Customizing Keybindings
From the UI
Open Settings > Keyboard Shortcuts, or Help > Keyboard Shortcuts (or Cmd+? → Keyboard Shortcuts) — both show the same editor. Click the pencil icon next to any shortcut to enter recording mode, then press your new key combination. The app warns you if the combo is already used by another action. Overridden shortcuts are highlighted in accent color with a reset icon to revert individually. A “Reset all to defaults” button is at the bottom.
Extended function keys (macOS). F13–F20 are recordable, both here and for the Global Hotkey. macOS never forwards them to the app’s WebView, so TUICommander captures them natively and feeds them into the recorder; if one of them still appears dead, macOS itself consumed the key first (F14/F15 drive keyboard illumination on many Macs — remap or disable that in System Settings > Keyboard). F21–F24 are accepted in keybindings.json but have no macOS key code, so no Mac keyboard can produce them.
By editing the config file
You can also edit the keybindings.json file directly in your config directory:
- macOS:
~/Library/Application Support/tuicommander/keybindings.json - Windows:
%APPDATA%\tuicommander\keybindings.json - Linux:
~/.config/tuicommander/keybindings.json
The file is a JSON array of override objects. Only include shortcuts you want to change — anything not listed uses the default:
[
{ "action": "toggle-git-ops", "key": "Cmd+Shift+Y" },
{ "action": "toggle-markdown", "key": "Cmd+Shift+M" }
]
"key"usesCmdas the platform-agnostic modifier (resolved to Meta on macOS, Ctrl on Win/Linux)- Set
"key": ""or"key": nullto unbind an action - Changes made via the UI are saved to this same file
- The file is loaded at startup — restart TUICommander to pick up manual edits
See the action table below for all available action names.
Global Hotkey
A configurable OS-level shortcut to toggle TUICommander’s visibility from any application.
- Configure: Help > Keyboard Shortcuts > Global Hotkey (top of the tab)
- No default — you must set it yourself (e.g.,
Ctrl+Space, `Cmd+``) - Toggle behavior: hidden/minimized → show+focus, visible but unfocused → focus, focused → instant hide
CmdandCtrlare treated as distinct modifiers- Uses
tauri-plugin-global-shortcut(no Accessibility permission required on macOS) - Not available in browser/PWA mode
- Persists across app restarts
Terminal Compose Panel
These shortcuts apply while the terminal Compose editor has focus, in CLI or Chat.
They are editor-local, not configurable global keybindings. Ctrl means the
Control key on every platform, including macOS.
| Shortcut | Action |
|---|---|
Enter | Send the draft immediately |
Ctrl+Enter | Send the draft immediately |
Shift+Enter | Insert a new line |
Cmd+S / Ctrl+S | Park, restore or swap the prompt draft; never send |
Shift+Ctrl+Enter | Queue for the next idle moment (agent sessions only) |
Enter that confirms an IME candidate does not send the draft. Mobile terminal keybar controls send native terminal keys; they do not use Compose shortcuts.
AI Chat Composer
Compose, AI Chat and the mobile terminal composer handle Cmd+S and Ctrl+S
locally to park, restore or swap the prompt draft. Enter and Ctrl+Enter send;
Shift+Enter inserts a newline. The same action is available from the composer button on a
phone; it is not a configurable global shortcut.
Press Escape in the AI Chat composer or transcript to stop a running turn
without clearing your draft. When Find is open, Escape closes Find first.
Terminal Operations
| Shortcut | Action |
|---|---|
Cmd+T | New terminal tab |
Cmd+W | Close tab (or close active pane in split mode) |
Cmd+Shift+T | Reopen last closed tab |
Cmd+Shift+R | Run saved command |
Cmd+R | Reload active web/preview tab |
Cmd+L | Clear terminal |
Cmd+Shift+L | Refresh terminal (fix rendering glyphs) |
Cmd+F | Find in terminal / diff tab |
Cmd+G | Git Panel — Branches tab (or Find next match when search is open) |
Enter | Find next match (when search is open) |
Cmd+Shift+G / Shift+Enter | Find previous match (when search is open) |
Escape | Close search overlay |
Cmd+C | Copy selection |
Cmd+V | Paste to terminal |
Cmd+Home | Scroll to top |
Cmd+End | Scroll to bottom |
Down (while scrolled back) | Scroll to bottom; the key is not sent to the terminal |
Shift+PageUp | Scroll page up |
Shift+PageDown | Scroll page down |
Cmd+Shift+. | Toggle block folding |
Cmd+Shift+Up | Jump to previous block |
Cmd+Shift+Down | Jump to next block |
Cmd+Shift+B | Toggle block-scoped search |
Hands-free conversation: press Cmd+Alt+V (Ctrl+Alt+V on Windows/Linux) to start or stop listening on the active terminal. Dictation must be enabled. A custom binding or explicit unbind in Keyboard Shortcuts overrides this default.
Tab Navigation
| Shortcut | Action |
|---|---|
Cmd+1 through Cmd+9 | Switch to tab by number |
Ctrl+Tab | Next tab |
Ctrl+Shift+Tab | Previous tab |
Hold Cmd alone (Ctrl on Windows/Linux) for 450 ms to show shortcut badges on the first nine terminal tabs. Release the modifier to hide them. Any other key, mouse button, wheel event, window blur, or visibility change cancels the hints. Tab shortcuts work immediately, even without badges. The existing quick-switcher chord is unchanged.
Zoom
| Shortcut | Action |
|---|---|
Cmd+= (or Cmd++) | Zoom in (active terminal CLI/Chat view, Markdown tab, or code editor) |
Cmd+- | Zoom out (active terminal CLI/Chat view, Markdown tab, or code editor) |
Cmd+0 | Reset zoom to default (active terminal CLI/Chat view, Markdown tab, or code editor) |
Cmd+Shift+= (or Cmd+Shift++) | Zoom in all tabs |
Cmd+Shift+- | Zoom out all tabs |
Cmd+Shift+0 | Reset zoom all tabs |
The collective shortcuts affect all open terminal, Markdown, and code editor tabs, including inactive tabs. Each tab uses its existing zoom step and bounds. Reset uses the Markdown default or the configured terminal/editor default. Standard zoom shortcuts affect only the active tab.
Font size range: 8px to 32px, step 2px per action. A session shares one zoom level between its CLI and Chat views. The collective shortcuts also update terminal Chat views.
Split Panes
| Shortcut | Action |
|---|---|
Cmd+\ | Split vertically (side by side) |
Cmd+Alt+\ | Split horizontally (stacked) |
Alt+← / Alt+→ | Navigate panes (vertical split) |
Alt+↑ / Alt+↓ | Navigate panes (horizontal split) |
Cmd+W | Close active pane (collapses to single) |
Cmd+Shift+Enter | Maximize / restore active pane |
Cmd+Alt+Enter | Focus mode — hide sidebar, tab bar, and all side panels (keeps toolbar + status bar) |
Panels
| Shortcut | Action |
|---|---|
Cmd+[ | Toggle sidebar |
Cmd+Shift+D | Toggle Git Panel |
Cmd+Shift+M | Toggle markdown panel |
Cmd+Alt+N | Toggle Ideas panel |
Cmd+E | Toggle file browser |
Cmd+O | Open file… (picker) |
Cmd+N | New file… (picker for name + location) |
Cmd+, | Open settings |
Cmd+U | Jump to next waiting terminal |
Cmd+? | Toggle help panel |
Cmd+Shift+K | Prompt library |
Cmd+K | Clear scrollback |
Cmd+Shift+W | Worktree Manager |
Cmd+J | Task queue |
Cmd+Shift+E | Toggle error log |
Cmd+Shift+I | MCP servers popup (per-repo) |
Note: File browser and Markdown panels are mutually exclusive — opening one closes the other.
Navigation
| Shortcut | Action |
|---|---|
Cmd+P | Command palette |
Cmd+Shift+P | Open Terminal Progress |
Cmd+Shift+A | Activity dashboard |
Git
| Shortcut | Action |
|---|---|
Cmd+Shift+D | Git Panel (opens on last active tab) |
Cmd+G | Git Panel — Branches tab |
Cmd+B | Quick branch switch (fuzzy search) |
Branches Panel (when panel is focused)
The panel is mouse-first — branch actions (create, delete, rename, merge, rebase, push, pull, fetch, checkout) live in the right-click context menu, the + New-branch button, and row double-click. Only list navigation is on the keyboard.
| Shortcut | Action |
|---|---|
↑ / ↓ | Navigate branch list |
/ | Focus the filter |
Escape | Clear filter / deselect |
| double-click | Checkout branch |
Ctrl/Cmd+1–4 | Switch Git Panel tab (1=Changes, 2=Log, 3=Stashes, 4=Branches) |
Quick Branch Switcher
| Shortcut | Action |
|---|---|
Hold Cmd+Ctrl (macOS) or Ctrl+Alt (Win/Linux) | Show quick switcher overlay |
Cmd+Ctrl+1-9 | Switch to branch by index (in the Global Workspace: switch to tab N; only the tab hints show) |
While holding the modifier, all branches show numbered badges. Press a number to switch instantly.
File Browser (when panel is focused)
| Shortcut | Action |
|---|---|
↑ / ↓ | Navigate files |
Enter | Open file or enter directory |
Backspace | Go to parent directory |
Cmd+C | Copy selected file |
Cmd+X | Cut selected file |
Cmd+V | Paste file into current directory |
Code Editor (when editor tab is focused)
| Shortcut | Action |
|---|---|
Cmd+S | Save file |
Alt+Z | Toggle line wrapping and remember it for this file kind |
Ideas Panel (when textarea is focused)
| Shortcut | Action |
|---|---|
Enter | Submit idea |
Shift+Enter | Insert newline |
Voice Dictation
| Shortcut | Action |
|---|---|
Hold F5 | Push-to-talk (configurable in Settings) |
Hold to record, release to transcribe and inject text into active terminal.
Tab Context Menu (Right-click on tab)
| Action | Shortcut |
|---|---|
| Close Tab | Cmd+W |
| Close Other Tabs | — |
| Close Tabs to the Right | — |
| Copy Path | — (diff/editor/markdown file tabs) |
| Rename Tab | (double-click tab name) |
| Detach to Window | — |
While a context menu is open, pressing a menu item’s shortcut chord (modifier + key, or Enter) fires that action immediately — no click needed. Modifier-only keys (Cmd, Shift, Ctrl, Alt) do not close the menu so multi-key chords can form; any other non-matching key closes the menu.
Mouse Actions
| Action | Where | Effect |
|---|---|---|
| Click | Sidebar branch | Switch to branch |
| Double-click | Sidebar branch name | Rename branch |
| Double-click | Tab name | Rename tab |
| Right-click | Tab | Context menu |
| Right-click | Sidebar branch | Branch context menu |
| Middle-click | Tab | Close tab |
| Drag | Tab | Reorder tabs |
| Drag | Sidebar right edge | Resize sidebar (300-500px); sidebar text grows 1px at 350, 400 and 450px |
| Click | PR badge / CI ring | Open PR detail popover |
| Click | Status bar CWD path | Copy path to clipboard |
| Click | Status bar panel buttons | Toggle Git/MD/FB/Ideas panels |
| Drag | Panel left edge | Resize right-side panel (200-800px) |
| Drag | Split pane divider | Resize split terminal panes |
Action Names Reference (for keybindings.json)
| Action Name | Default Shortcut | Description |
|---|---|---|
zoom-in | Cmd+= | Zoom in |
zoom-out | Cmd+- | Zoom out |
zoom-reset | Cmd+0 | Reset zoom |
zoom-in-all | Cmd+Shift+= | Zoom in all tabs |
zoom-out-all | Cmd+Shift+- | Zoom out all tabs |
zoom-reset-all | Cmd+Shift+0 | Reset zoom all tabs |
new-terminal | Cmd+T | New terminal tab |
close-terminal | Cmd+W | Close terminal/pane |
reopen-closed-tab | Cmd+Shift+T | Reopen closed tab |
clear-terminal | Cmd+L | Clear terminal |
refresh-terminal | Cmd+Shift+L | Refresh terminal (fix glyphs) |
run-command | Cmd+Shift+R | Run saved command |
edit-command | (unbound) | Edit and run command |
reload-tab | Cmd+R | Reload the active web/preview tab |
split-vertical | Cmd+\ | Split vertically |
split-horizontal | Cmd+Alt+\ | Split horizontally |
prev-tab | Ctrl+Shift+Tab | Previous tab |
Hold Cmd alone (Ctrl on Windows/Linux) for 450 ms to show shortcut badges on the first nine terminal tabs. Release the modifier to hide them. Any other key, mouse button, wheel event, window blur, or visibility change cancels the hints. Tab shortcuts work immediately, even without badges. The existing quick-switcher chord is unchanged.
| next-tab | Ctrl+Tab | Next tab |
| focus-last-terminal | Cmd+Ctrl+Backspace | Return to last terminal (toggle, across repos) |
| history-back | Cmd+Alt+ArrowLeft | Back to the previous terminal in the activation history (last 10, across repos) |
| history-forward | Cmd+Alt+ArrowRight | Forward to the next terminal in the activation history |
| jump-waiting-terminal | Cmd+U | Jump to the next terminal awaiting input (cycles, across repos) |
| switch-tab-1..9 | Cmd+1..9 | Switch to tab N |
| toggle-sidebar | Cmd+[ | Toggle sidebar |
| toggle-markdown | Cmd+Shift+M | Toggle markdown panel |
| toggle-notes | Cmd+Alt+N | Toggle ideas panel |
| open-file | Cmd+O | Open file picker |
| new-file | Cmd+N | Create new file |
| toggle-file-browser | Cmd+E | Toggle file browser |
| prompt-library | Cmd+Shift+K | Prompt library |
| toggle-settings | Cmd+, | Open settings |
| toggle-task-queue | Cmd+J | Task queue |
| toggle-help | Cmd+? | Toggle help panel |
| toggle-git-ops | Cmd+Shift+D | Git Panel |
| toggle-branches-tab | Cmd+G | Git Panel — Branches tab |
| worktree-manager | Cmd+Shift+W | Worktree Manager panel |
| quick-branch-switch | Cmd+B | Quick branch switch |
| find-in-terminal | Cmd+F | Find in terminal |
| command-palette | Cmd+P | Command palette |
| progress | Cmd+Shift+P | Open Terminal Progress |
| activity-dashboard | Cmd+Shift+A | Activity dashboard |
| toggle-error-log | Cmd+Shift+E | Toggle error log |
| toggle-mcp-popup | Cmd+Shift+I | MCP servers popup (per-repo) |
| switch-branch-1..9 | Cmd+Ctrl+1..9 | Switch to branch N |
| scroll-to-top | Cmd+Home | Scroll to top |
| scroll-to-bottom | Cmd+End | Scroll to bottom |
| scroll-page-up | Shift+PageUp | Scroll page up |
| scroll-page-down | Shift+PageDown | Scroll page down |
| zoom-pane | Cmd+Shift+Enter | Maximize/restore pane |
| toggle-focus-mode | Cmd+Alt+Enter | Focus mode — hide sidebar/tab bar/panels |
| toggle-file-browser-content-search | Cmd+Shift+F | File content search |
| toggle-diff-scroll | Cmd+Shift+G | Diff scroll view |
| toggle-global-workspace | Cmd+Shift+X | Toggle global workspace |
| toggle-ai-chat | Cmd+Alt+A | Toggle the ego-backed AI Chat panel. Listed only while Experimental features is on |
| clear-scrollback | Cmd+K | Clear scrollback |
| open-folder | Cmd+Shift+O | Open folder picker |
| open-path | Cmd+Alt+O | Open path… |
| open-secondary-window | — | Open secondary window |
| command-overview | — | Command overview |
| open-tasks | — | Open Tasks (listed only while a work-item provider plugin is loaded) |
| toggle-outline | Cmd+Alt+L | Toggle outline panel |
| toggle-compose-panel | Cmd+I | Toggle compose panel |
| detach-activity-dashboard | — | Open Activity Dashboard in separate window |
| toggle-tunnels | — | SSH Tunnels panel |
| process-manager | — | Process Manager |
| open-generators | — | Open generators |
| show-remote-qr | — | QR for Remote Mobile Connection |
| block-fold-toggle | Cmd+Shift+. | Toggle block fold |
| block-prev | Cmd+Shift+Up | Previous command block |
| block-next | Cmd+Shift+Down | Next command block |
| block-search-toggle | Cmd+Shift+B | Search in block |
| answers-only | Cmd+Alt+R | Show every prompt of the session with its 💬 answers (turns without an answer are left out); press again to return to the live terminal |
| toggle-hands-free | Cmd+Alt+V | Start/stop hands-free conversation with the active terminal |
Plugin action discovery
A connected frontend publishes its registered plugin command IDs for the shared settings owner. Explicit keybinding-choice refresh includes those IDs and built-in actions. Unloading removes the plugin IDs from later refreshes. Before any frontend publication, plugin choices report unavailable rather than an empty successful list. Publication does not change shortcut overrides.
PR comments are also reachable without a shortcut: use Comments and review threads in the sidebar PR popover, its unresolved-threads count, or a PR notification. Each route opens that PR in Tasks; an unavailable provider falls back to GitHub.
Settings
If a saved setting has an invalid type or enum value, TUIC resets that field and keeps valid settings. Missing font settings and theme use their defaults. A Settings recovered warning lists the reset fields and the backup path of the original file. Truncated or invalid JSON still uses whole-file recovery.
Older installations receive a one-time scrollback reflow migration. You can turn reflow off again in Terminal settings; later starts keep that choice.
Repository Settings separates identity, inherited worktree overrides, Design Mode, scripts, team sharing, and reset. Nullable controls retain their global-default choice. Reset clears override fields, including scripts, but retains repository identity and its Design Mode URL. Team exports never include scripts. The Dev Server URL and setup, run, and archive script fields have contextual help; hover or focus a help badge to read it, or click to keep it open.
General places ego immediately after Local tools (the local tools card is desktop-only). MCP uses the shared Settings row typography and label/help spacing for capabilities and shows retained legacy denials as a warning.
Agents Settings shows the selected machine in the header. Run configuration editors keep explicit Save and Cancel actions. Terminal-agent permissions and filesystem sandbox remain separate from AI Chat ACP settings; launch instructions still save on blur.
Workspace pages use the same cards and aligned rows. Terminal retains its live canvas preview and all clipboard and scrollback controls. Keyboard Shortcuts places its searchable actions in Shortcut groups, before their keycaps, with explicit Rebind and Reset actions. Git & GitHub separates authentication, monitoring, repository defaults, worktree defaults, additional accounts, CircleCI, and repository bindings. Existing save boundaries and policy choices are unchanged.
The Application pages use section cards and labelled rows. General places the update status and its check action above the page header. On desktop, a Local tools card groups TUIC CLI, Code Intelligence, and Custom Launchers; this card is hidden in browser mode. General links to AI Chat defaults when AI Chat is enabled. The existing install, update, uninstall, and launcher actions keep their save and confirmation behavior. Appearance keeps group rename validation and client-local chat preferences. Notifications keeps visual controls available without audio; output-device discovery starts only after Choose output device. Changing master volume previews once on release.
The settings-service policy foundation keeps secrets write-only. Changes that expose TUIC or select executable code require the existing confirmation dialog; ordinary preferences, push settings and outbound HTTP destinations do not. The dialog uses a backend-built diff and approvals expire after five minutes and cannot be reused. The replacement settings MCP/API transport is still awaiting its separate cutover (#1786-9cbd).
Open settings with Cmd+,. Settings are organized into pages. The navigation
groups the pages by task:
| Group | Pages |
|---|---|
| Application | General, Appearance, Notifications |
| Workspace | Terminal, Keyboard Shortcuts, Git & GitHub |
| AI | Agents, AI Chat, Voice, Smart Prompts |
| Integrations | MCP, Remote Access, Remote Machines, Telegram, Manage plugins |
| Plugin settings | Loaded plugins with registered settings, marked Plugin |
| Repositories | One page for each repository in the sidebar |
The AI Chat page is shown only while Experimental Features is on (see AI Chat).
Settings uses short labels and behavior descriptions. Implementation ownership and persistence details stay in the documentation rather than page introductions. Repeated scope chips and permanent usage walkthroughs are omitted. Catalogue labels have space above their controls, and header scope badges stay within the page width. Catalogue actions use a wrapping row with 8px gaps and 8px clearance below the field separator; the field effect appears once beneath its name, while the status line reports only the value source.
On narrow screens, the page selector truncates long names before its arrow. Settings reserves the same scrollbar space on every page, including plugin loading and error states. Help badges follow the final line of wrapped labels, and repository color actions keep the shared right alignment.
Plugin pages show their source plugin ID below the page title and in the navigation tooltip. The Settings header, navigation and footer stay visible while plugin values load. Loading and read errors appear only inside the native editor; switching pages does not load a plugin iframe. Unloading a plugin removes its page and search entries.
Search
A search box sits at the top of the page list. Typing filters settings across
every page at once, so you do not have to know which page owns the one you want.
Each result shows the setting name and the Page › Section trail it lives under;
selecting one opens that page and scrolls to the field.
Search reads the settings catalogue without opening every page or running their service probes. Plugin search uses the loaded plugin’s described fields; values are read only when you open its editor. Reopening Settings clears the previous query so a requested page or section is visible.
The following search rules are deliberate:
- Repository pages are not searched. A repository page belongs to one specific repository, and a global box has no way to know which one you mean.
- Per-agent controls in expandable cards are not searched. Search cannot select a specific agent card or scroll to a control inside it. For managed workspace trust, open Settings → Agents, expand Claude, Codex or ego, then use Accept workspace trust for managed spawns in Expert Mode.
- ego permissions are searchable. Permissions and Filesystem sandbox are in a visible section on the Agents page; no agent card needs expansion.
- Settings the current build does not render are not listed. The same rule hides the AI Chat page while Experimental Features is off, so a search does not open a page that is not in the navigation.
A result for an expert setting shows an Expert badge. See the next section.
Expert Mode
Some settings have a default that is correct for almost everyone. These are expert settings. The Expert switch in the Settings header controls them:
- Expert off (basic mode) — an expert setting is hidden while it has its default value. When its value is different from the default, it is shown, so an override is never hidden from you.
- Expert on — all expert settings are shown.
The switch position is kept between restarts (UI preference
settings_expert_mode, see UI Preferences).
A setting that you change stays shown until you open Settings again. If you set it back to the default, it does not disappear under the cursor. The next time you open Settings, it is hidden again if it has its default value.
When you select a search result with the Expert badge in basic mode, Settings opens the page, shows that setting and scrolls to it. The setting stays shown until you open Settings again. The switch does not change.
If TUICommander cannot read the default values (the get_config_defaults
command), all expert settings stay visible.
These settings are expert. All other settings are always shown. A page is never all expert: in basic mode it would show an empty page.
| Page | Expert settings |
|---|---|
| General | Auto-Standby Timeout, Content Indexing, Update Channel |
| Notifications | Master Volume, Audio Output Device |
| Terminal | Shell, Font Weight, Allow OSC 52 clipboard writes, Block folding, Show scrollbar marks, Reflow scrollback on resize |
| Git & GitHub | Auto-Delete on PR Close, Copy ignored files, Copy untracked files, Storage Strategy, Auto-archive merged worktrees, Orphan Worktree Cleanup and safe cleanup countdown, After Merge Behavior, Auto-Fetch Interval, the Add another GitHub account button (shown while no additional account exists) |
| Agents | Collect project progress, Launch instructions (global); per agent: Launch instructions, Close idle managed child after, Auto-retry on server errors, Prevent alternate screen, Accept workspace trust for managed spawns (Claude, Codex and ego), Native status signals, Install hooks globally, Track agent intent, Collect progress, Show suggested follow-ups, Headless Command Template; Claude only: Environment Flags |
| Voice | Long-press threshold, Auto-send, Input device, Level gate, Speech confidence gate, Hold-back before sending, Notify model when hands-free changes, Start notice |
| MCP | Collapse tools |
| Remote Access | Port, Session Token Duration, Enable IPv6 (dual-stack) |
Application
General
| Setting | Description |
|---|---|
| Language | UI language. The list offers the locales that ship with a message catalog, each named in its own language, and the pick applies immediately — no reload. A locale without a catalog is never offered, because it would render English while claiming to be translated. The picker is hidden while only one catalog ships — today that is English alone — because a list of one is not a choice. |
| Show agent context bar | Show the model’s current intent, its orchestrator-assigned task, and the last prompt sent to an agent. |
| When closing the main window | Desktop: Ask (default), Background, or Quit. Ask offers Remember. Background hides visible windows and keeps sessions running. Use the application menu to quit; on macOS, click the Dock icon to show the window again. |
| Hide Dock icon in background | On |
| Confirm before quitting | Confirm real quit with active terminals, including Cmd/Ctrl+Q. Background does not prompt. Detached-panel close closes only that panel. |
| Confirm before closing a tab | Ask before closing terminal tab |
| Prevent sleep when busy | Keep the machine awake for active turns, background agent jobs and live managed agents marked keep_open; the backend retains the hold when the app is hidden or locked (Power Management section) |
| Auto-Standby Timeout | Pause idle background sessions after this duration to save resources. Default 5 min; 0 disables it. |
| Content Indexing | When to build search indexes: Disabled, Active repo only, Active + on switch, or All repos at boot |
| Automatically check for updates | Check for new versions on startup |
| Update Channel | Stable, Beta or Nightly. Beta checks the next beta and final stable; beta downloads open their release page. New beta installs default to Beta. Older beta installs with Stable saved move to Beta once; selecting Stable afterwards keeps that choice |
| Wait for agents before restarting | After an update installs, restart only when no session is busy or awaiting input. The APP UPDATE notification shows the busy count and offers Restart now. Default on |
| Resume all agents after an update | After the app restarts for an update, resume every agent tab with a confirmed session on every branch. Default on |
| TUIC CLI | Install or uninstall the tuic command-line tool, with its status. Desktop app only. See CLI. |
| Code Intelligence | Install and manage MDKB, which gives the editor go-to-definition, find references, and symbol outline, and serves as a memory manager for AI agents. Desktop app only. |
| ego executable | Path to the ego binary the AI Chat panel talks to over ACP (ego section, directly after Code Intelligence). Always shown, also while Experimental Features is off. On the desktop it is laid out like the TUIC CLI section: a status line (“Configured at …”) with Install latest, Select… (native file picker) and Clear. Install latest downloads the bare binary for this platform (ego-<os>-<arch>, for example ego-macos-arm64) from the latest sstraus/ego GitHub release, installs it like MDKB (/usr/local/bin/ego; Windows: %LOCALAPPDATA%\Microsoft\WindowsApps\ego.exe, with an elevation prompt when the folder is not writable) and saves that path as the ego executable. A browser client, which has no native picker, gets a text field. While it is empty, ACP is not configured: every connect is refused in Rust and the panel says so rather than launching nothing. Read at each connect, so a correction takes effect without a restart. |
| ego profile | Optional name of a profile in ego’s user configuration for the AI Chat panel. Leave empty to use ego’s normal profile selection. Names with whitespace or a leading dash are rejected. TUICommander passes the name to ego acp; the profile’s rules remain in ego’s configuration. |
| Default IDE | IDE for “Open in…” actions (IDE section). Only installed apps are offered, grouped by category: Code Editors (VS Code, Cursor, Zed, Windsurf, Neovim, Xcode, $EDITOR), JetBrains (IntelliJ IDEA, PyCharm, WebStorm, GoLand, CLion, PhpStorm, RubyMine, Rider, DataGrip, RustRover, Android Studio, Fleet), Terminals (Ghostty, WezTerm, Alacritty, Kitty, Warp, iTerm2), Git Tools (Sourcetree, GitHub Desktop, Fork, GitKraken, Sublime Merge, Tower), System (Terminal, Finder) |
| TUICommander shell | Open a plain shell tab in the active repository or worktree from the Open in menu. |
| Custom Launchers | Define your own tools for the “Open in” menu. Each launcher has a name, an executable (bare name resolved on PATH, or absolute path), and arguments (one per line). Arguments may use placeholders, expanded at launch: {path}/{file} (focused file, else repo root), {fileDir} (directory of the focused file), {repo} (repo/worktree root), {cwd} (focused terminal’s working directory), {home} (your home directory), {line}/{column} (1-based editor cursor position). Args are passed verbatim (no shell parsing), so paths with spaces are safe. |
| Experimental Features | One toggle, no sub-toggles. It opts in to the AI Chat panel (ego over ACP, #785-58ca) and SSH Tunnels. It also shows the AI Chat settings page. The AI Chat, AI Triage and AI Watchers sub-toggles went with the embedded AI engine (#784-0aec). |
Appearance
| Setting | Default | Description |
|---|---|---|
| Split Tab Mode | — | Separate or unified tab appearance |
| Tab Ordering | — | How tabs are ordered: grouped by type, terminals first, or freely interleaved |
| Cycle All Tab Types | Off | When on, next/prev-tab shortcuts also cycle file/diff/markdown/editor tabs (ordered like the tab bar). Off cycles terminals only. |
| Nested Terminal Tabs | Off | Opt in to collapsible branch activity cards. When off, the sidebar shows no activity caret or nested agent/session rows. When on, branches with open sessions show agent status, current activity, and last-update age. Applies immediately. |
| Max Tab Name Length | — | 10–60 slider |
| New text indicator | On | Show New text below when terminal Chat or AI Chat receives content while you read earlier messages. Saved on this client; mobile Settings offers the same toggle. |
| Repository Groups | — | Create, rename, delete, and color-code groups |
| Reset Panel Sizes | — | Restore sidebar and panel widths to defaults (Layout section). It also rebuilds the active Global Workspace layout and keeps the focused terminal. |
| Mute Intermediate Text | On | Chat section. In the terminal Chat view, AI Chat and the mobile chat, assistant text that is followed by a tool call in the same turn is drawn smaller and dimmer, so status lines such as “Pump restart.” are not mistaken for the answer. The last text of a turn keeps the normal style. Copy and Find work on muted text. Applies immediately. |
| UI Legend | — | Visual reference for colors, symbols, and badges used in the app |
The terminal and app color theme is on the Terminal page. Native window and webview backgrounds use the same theme color at startup and when the theme changes, including light themes. The mobile PWA offers a separate Dark/Light choice in its Settings screen, saved on the server for connected mobile clients; the screen also shows app and server versions.
Show agents under branches
Nested agent rows are disabled by default. To show them, open Settings → Appearance → Tabs and turn on Nested Terminal Tabs. No restart is required.
After you enable the setting, a branch gets an activity caret when it has at least one open terminal session. Expand the branch to see its agents and shells. Each detected agent row shows its status, current intent or task, and last-update age; clicking a row switches to that session. The setting only displays existing sessions—it does not start or discover an agent outside a terminal assigned to that branch.
Notifications
- When the desktop window is unfocused, agent questions and Progress
done/blockedentries can appear in the operating system’s Notification Center. TUICommander checks notification permission when the first alert is needed. On macOS, clicking an alert opens the named terminal or Progress project. An open, focused window receives no duplicate system alert. - Enable Audio Notifications — Master toggle
- Volume — 0-100% (applied natively by the Rust playback path). Releasing the slider plays a short preview at the new level.
- Audio Output Device — defaults to the system output. Click Choose output device… to enumerate available outputs and pick a specific one. Enumeration is deferred until you click, because on macOS the audio device scan triggers the microphone-permission prompt — notifications never record audio.
- Per-event toggles:
- Agent asks question
- Error occurred
- Task completed
- Warning
- Info
- Attention (agent needs you)
- Test buttons — Test each sound individually. Normal notifications share one anti-spam interval across every sound type so a burst cannot play overlapping tones. The Test button bypasses that limit, so rapid A/B volume comparisons always play.
- Silence subagent sounds and notifications — On desktop, browser-desktop and mobile/PWA, mute all session sounds and OS notifications from sessions spawned by another agent, including questions, errors, completion, attention requests and Progress updates. Tab state, Activity and bell entries still update; urgent user cards still show. Mobile question and completion Web Push also follow this host setting, including process exit after session teardown. Mobile sounds retain their per-device switch and visible-Sessions-list gate. Parent and user-started sessions are unaffected. This extends the existing orchestration control and keeps its default (on) and saved preference. Unparented HTTP/MCP sessions retain the completion-chime mute only. Each busy cycle can notify at most once, even when idle and process exit arrive separately.
- Reset to Defaults — Restore default notification settings
- Keep toasts in the bell — Retain user-action toasts in the toolbar bell’s MESSAGES section, including their level and explicit action. Turning this off leaves ordinary user feedback transient; agent/MCP notices and agent spawns still go directly to the bell (identical consecutive notices within five seconds are deduplicated), and overflow from the two-card limit is retained there regardless of this setting. Dedicated-domain toasts that explicitly opt out of Messages remain visible or queued. Transient cards sit top-right of the terminal, clear of docked panels and bottom input; same-kind bursts within five seconds show ×N and restart their dismissal timer. Informational toasts leave after 20 seconds and warnings after 60 seconds; an error toast stays until you click it away (the bell keeps a copy). Errors take priority over informational cards, and tall cards scroll to keep actions reachable. This setting is visual and remains available without audio output.
- Automatic agent toast cards — MCP toast notices show a transient card only while their origin terminal tab is active. Settings → Notifications → Show cards from the active terminal defaults on and is saved per client; turning it off restores urgent-only cards. Urgent notices always show a card, and notices without an origin session remain bell-only unless urgent.
Attention is the distinct call-back-to-keyboard sound available to agent toasts. Native playback and the browser fallback share a triangular G4→G4→E5 motif with two short knocks and a longer rise; each engine applies its own envelope. It remains subject to the master toggle, configured volume, and its own per-event toggle; native playback also uses the selected output device.
Workspace
Terminal
| Setting | Default | Description |
|---|---|---|
| Terminal Theme | — | Color theme for terminal output and app chrome, with preview swatches (Theme section) |
| Shell | — | Custom shell path (e.g., /bin/zsh, /usr/local/bin/fish). Leave empty for system default. |
| Terminal Font | JetBrains Mono | 13 bundled monospace fonts: Fira Code, Hack, Cascadia Code, Source Code Pro, IBM Plex Mono, Inconsolata, Ubuntu Mono, Anonymous Pro, Roboto Mono, Space Mono, Monaspace Neon, Geist Mono |
| Default Font Size | — | 8–32px slider. Applies to new terminals; existing terminals keep their zoom level. |
| Font Weight | — | Terminal font weight (200 = ExtraLight, 400 = Regular, 700 = Bold) |
| Cursor Style | — | Bar, Block, or Underline |
| Copy on select | On | Auto-copy terminal selection to clipboard. When text is selected in the terminal, it is immediately copied. A “Copied to clipboard” confirmation appears in the status bar. |
| Allow OSC 52 clipboard writes | On | Let terminal programs set the system clipboard via the OSC 52 escape sequence (used by tmux, vim, ssh yank-over-SSH, etc.). Because OSC 52 is honored from anywhere in the byte stream, a displayed file or log can also overwrite the clipboard — so a non-blocking “Clipboard updated” notice appears on every write. Disable to ignore OSC 52 entirely. |
| Show block timestamps | On | While Ctrl+Cmd is held, each command block is labelled at the right edge with how long ago it started. |
| Block folding | On | Let the Toggle Block Fold shortcut (Cmd/Ctrl+Shift+.) and its command-palette entry collapse a command block’s output. Blocks already folded stay collapsed when this is off. |
| Show scrollbar marks | On | Mark each command’s position on the terminal scrollbar, so a long scrollback shows where output began. Covers the history markers only — the blue/red block ticks and the green user-prompt ticks. Orange search-match ticks are not affected: they are the result of a search you just ran, not a display preference. |
| Reflow scrollback on resize | On | Re-wrap scrollback history when the terminal changes width, so output written at the old width stays readable after a side panel opens or closes. Turn it off to leave history lines as they were written and truncate them to the new width instead. The visible screen is never reflowed either way — cursor-addressed TUIs redraw themselves. A change applies to sessions already open. |
The terminal bell mode (none, visual, sound, both) has no control on
the dedicated Terminal page. Use All settings (Expert) to edit app.bell_style (see Terminal Bell).
Keyboard Shortcuts
Browse and rebind all app actions. The same editor is also in the Help panel (Help > Keyboard Shortcuts).
- Every registered action is listed with its current keybinding
- Click the pencil icon next to any action and press a new key combination to rebind it
- Custom bindings are stored in
keybindings.jsonin the platform config directory - Auto-populated from the action registry — new actions appear automatically
- Global Hotkey (Toggle Window) — an OS-level shortcut to show or hide TUICommander from any application (desktop app only)
- Plugin Commands — commands that plugins register, which you can bind like any other action
- Most shortcuts are also listed in the native system menu bar (desktop app only — browser/PWA clients have no native menu)
See Keyboard Shortcuts for the full reference and customization guide.
Git & GitHub
GitHub authentication, pull request and issue display, and the global repository and worktree defaults.
| Setting | Description |
|---|---|
| OAuth Login | Device Flow login — click “Sign in with GitHub”, enter code on github.com. Token stored in OS keyring. (GitHub Authentication section) |
| Auth Status | Shows current login, avatar, token source (OAuth/env/CLI), and available scopes |
| Disconnect | Clear all GitHub tokens (keyring + env cache). Falls back to next available source. |
| Diagnostics | Token source details, scope verification, API connectivity check |
| Auto-show PR popover | Automatically display PR details when switching branches. Only shows for OPEN pull requests — CLOSED PRs are hidden, and MERGED PRs fade after 5 minutes of user activity. (Pull Requests section) |
| Hide Draft PRs / Hide Conflicting PRs / Hide CI Failing PRs | Filter the pull requests the app shows |
| Auto-Delete on PR Close | Off (default), Ask, or Auto — controls branch cleanup when a PR is merged/closed |
| Show issues / Issue Filter | Which issues to show in the GitHub panel: Assigned (default), Created, Mentioned, All, or Disabled (Issues section) |
| Repository Defaults | Base branch, Copy ignored files and Copy untracked files (two separate toggles), setup/run/archive scripts applied to new repos |
| Worktree Defaults | Storage strategy, branch-name prompt, branch deletion, auto-archive, orphan cleanup, merge strategy, after-merge behavior, auto-fetch interval. See Worktrees. |
| Additional GitHub Accounts | Extra github.com or Enterprise logins. See GitHub Integration. |
| CircleCI | Store or remove a read-only CircleCI token for failed job logs. The saved token is never displayed again. |
| Repository Bindings | Which account each workspace repo resolves to |
Git & GitHub requests repo project during OAuth login. A connected account with
known scopes that omit project shows Log in again for Projects. This renews
consent without requiring logout first. Existing repository permissions do not
change; external tokens and organization access must be updated separately.
Token priority: GH_TOKEN env → GITHUB_TOKEN env → OAuth keyring. The gh CLI login is not used.
AI
Agents
Close idle managed child after sets the time a finished orchestrator-spawned agent stays open for follow-up. The default is 15 minutes; 0 disables automatic closure. User-created sessions are unaffected. Unread mail and background work keep a managed child open, and its parent receives an idle-timeout notice before closure. A child can also be marked keep-open at spawn or through the agent or session tool.
Launch instructions combines generated modules with user additions. Select Markers, Working with the user, Waiting and long work, Git and worktrees, Process safety, and Children. Each module has a (?) control that explains its instructions and the agent behavior they enable. Waiting continues independent work during background tasks and yields only for a needed result or your answer; yield reports are not completion claims. Children applies only to spawned children. Global switches are ceilings for the per-agent switches. Changing a module refreshes the generated preview without detaching Settings or resetting the page scroll position. Turn all launch instructions off suppresses the complete text, including additions. When mdkb is installed, a fixed “Code search” rule (search with MDKB first) follows the modules; it has no toggle and is absent without mdkb.
Add instructions and Add instructions for {VER} becomes the TUIC version.
Read-only effective previews follow the selected machine and draft changes. While its configuration loads, or if it fails, previews stay unavailable and Add instructions is disabled; text from the previous machine is not reused. Legacy default copies migrate away without duplication; custom text remains an addition. See AI Agents.
Each supported agent has an expandable row showing detection status, version, and MCP badge.
The default Codex run configuration includes
--dangerously-bypass-approvals-and-sandbox in its editable arguments.
The warning icon on a configuration identifies an active bypass. Remove that
argument through Edit to enable normal approvals and sandboxing for new
launches. The removal survives restart. Existing direct Codex defaults receive
the argument once during migration; wrapper configurations keep their own
arguments and the managed-launch wrapper warning.
| Setting | Description |
|---|---|
| Agent Detection | Auto-detects running agents from terminal output patterns. Shows “Available” or “Not found” for each agent. |
| Run Configurations | Custom launch configs (binary path, args, model, prompt) per agent. Add, set default, edit, or delete configurations (Edit / Delete live under the ··· menu on each row). A config named “review” enables the Review button in the PR Detail Popover — its args are interpolated with {pr_number}, {branch}, {base_branch}, {repo}, {pr_url}. The agent’s default run config also drives resume: launching / resuming the agent swaps the agent’s default binary (e.g. claude) for command and appends args after the resume flag. |
| MCP Integration | Install/remove TUICommander as MCP server for supported agents. Shows install status with a dot indicator. |
| Native status signals | Claude and Codex only. Enabled by default; injects process-scoped status configuration at launch without changing global agent files. The Signals: at launch badge identifies this mode. |
| Prevent alternate screen | Enabled by default for every agent. TUIC applies a verified native-scrollback control when the installed CLI supports one. Turning it off leaves new launches without TUIC’s screen control. Existing shells need to be reopened to receive the changed policy. |
| Accept workspace trust for managed spawns | Claude, Codex and ego only. In Expert Mode, expand the agent’s card to change whether agent-to-agent spawns skip that agent’s workspace trust question in a new folder. |
| Install hooks globally | Codex, Gemini, Grok, and OpenCode. Explicitly installs/removes sentinel-owned lifecycle hooks in the agent’s global configuration. Off by default. Codex verifies native trust; Hooks: review in /hooks requires normal Codex review. Profile-specific hooks require review in that profile. |
| Show agent intent as tab title | When agents declare their current work phase, update the tab name with a short title |
| Show suggested follow-up actions | Display actionable suggestions from agents after completing a task |
| Collect project progress | Global switch for the Progress journal. On by default. Off removes the progress tool from every agent’s tool list, stops the reporting obligation being sent, and records nothing — including the intent: markers TUICommander writes itself. |
| Collect progress (per agent) | Per-agent override, shown with the agent’s MCP settings and disabled while the global switch is off. The effective value is global AND (per-agent, default on), so an agent with no opinion follows the global switch. An agent that reports while its own override is off is answered progress_tracking_disabled rather than silently ignored. |
| Claude Usage Dashboard | (Claude Code only) Toggle under Features when the Claude row is expanded. Enables rate limit monitoring, session analytics, token usage charts, activity heatmap, and per-project breakdowns. Usage data appears in the status bar agent badge and in a dedicated dashboard tab. |
See AI Agents for details on agent detection, rate limits, and the usage dashboard.
AI Chat
Chat behavior → Master prompt adds your instructions to new AI Chat conversations. Use the multiline field to describe how the agent should answer or delegate work. The text is saved by TUIC and added to the existing TUIC rules; it does not replace them. Leave it empty for no extra user instructions. Separate AI Chat host guidance describes Mermaid rendering and does not count toward this limit. The limit is 8192 UTF-8 bytes; an edit above that limit shows an error and is not saved. Running and saved conversations keep their original instructions, including when reopened or forked. Do not put secrets in this field.
AI Chat model selection remains available when ego doctor reports a health problem. The page shows the affected health section and its detail. If doctor cannot return readable JSON, credential status is unknown, not missing; run ego doctor --json in a terminal to inspect it.
Shows the configuration of ego, the engine behind the AI Chat panel. Offered
only while Experimental Features (General page) is on, because that is what
offers the AI Chat panel — the one place ego is reachable from.
The ego binary itself is a TUICommander setting and is on the General page (ego executable), like MDKB.
The page shows which providers and models ego can use, and which model it
starts from. Everything here is ego’s, read and written by running ego:
- Perimeter — edit the first root, its read-only or read-write access, extra
read roots and extra writable roots (one absolute or
~/path per line). These roots extend the AI Chat workspace; they do not replace it. The absent roots setting uses ego’s inherited effective roots, including user roots for the selected profile, or read-write~/Gitsby default when present. Saving all paths empty publishes explicitroots=[]for workspace-only roots. A read root does not revoke access from a containing writable root. - Network enabled — persist ego’s
network="on"ornetwork="off"setting. Root saves and network writes are separate operations. A network change keeps any unsaved root draft. Reload from ego replaces that draft. - Effective perimeter —
ego config ls --effective --jsonin the configured AI Chat workspace and ego profile. It shows canonical admitted roots, origin layers, sandbox, backend, network and warnings. The form edits that profile’s user configuration (or user defaults if no profile is selected). Existing conversations keep their admitted perimeter. Enforcement not checked is ego’s current capability evidence, not proof that the OS enforces these roots. The badge is scoped to the exec sandbox for spawned processes. A measured array gets Enforced by OS only when every selected guarantee is present; partial or empty measured sets get Prompt only with an explanation.offwith online network never gets a vacuous OS badge. Unknown evidence stays unverified. The raw capability array, reason and probe reference remain in the preview. Root tool permissions also have their own policy checks. A failed write/readback retains the last successful preview; reload to check the stored state. An older ego without the effective-view command reports its CLI failure instead of showing an invented perimeter. - Default model — a picker over every model ego knows, grouped by provider.
Choosing one runs
ego config set model="<slug>"and then re-reads, so what you see afterwards is what ego persisted, not what was sent. It survives a restart because ego holds it, not TUICommander. A model ego marked unavailable cannot be picked. - Refresh from providers — asks ego to re-enumerate its sources
(
ego models --refresh). This is the only action anywhere in TUICommander that reaches a provider over the network, and it is ego that reaches it. Opening the page does not. - Providers — one row per source ego knows, with how many of its models are usable and why the rest are not, in ego’s own words.
- Credential state — read from
ego doctor. stored, expired (ego renews it on its next run; you do not log in again), no credential, or ego could not read its credential store — the last is not the same as an empty store.
No API key ever enters TUICommander. None is stored, none reaches the OS
keyring, and no provider HTTP call is made from this process. Login next
to a provider opens a terminal tab that runs ego auth login <provider> and
closes Settings so the tab is in front. The browser, device-code or API-key
prompt is ego talking to you directly in that terminal; TUICommander types the
command and never sees the key. The tab stays open after ego exits so a refusal
stays readable; reopening the page shows the credential state ego doctor now
reports.
When ego is not configured the page says so and points to the ego executable field in Settings → General instead of rendering an empty list. A path that is set but cannot be started is reported as its own thing, and also points to Settings → General. When an ego command fails, what ego printed is shown verbatim — the command, its exit code, and its output.
The in-chat model switch is a different control: that one is a session option and changes one conversation. This changes the default every new run starts from.
The old provider registry is gone
The provider registry, its slots and the API keys it put in the OS keyring were
deleted with the embedded AI engine (#784-0aec).
<config_dir>/providers.json is no longer read or written, and a file left by
an older version is inert. This page is not its replacement — it edits ego’s
configuration and stores nothing of its own.
Agent CLIs (Claude Code, Codex, …) are unaffected — they keep their own credentials and are configured on the Agents page.
Smart Prompts in API mode used the old registry’s headless slot. It now runs one unattended ego turn instead (#787-ee50): the model is whatever this page’s default is, the prompt is sent once, and the answer goes to the prompt’s output target. Nothing streams — there is no panel open to stream to. With no ego binary named, the mode refuses and says to name one and pick a model on this page. Shell, inject and headless-CLI modes are unaffected.
The turn runs with no TUICommander tools, so it cannot open a terminal or touch a repository, and any permission ego asks for is declined at once: nobody is watching, and a question nobody answers is a turn that never ends. If a prompt comes back empty because of that, the refusal is reported rather than the empty answer.
Voice
Dictation, speech recognition, spoken replies, and hands-free conversation.
Spoken replies defaults to on. Turn it off to keep hands-free dictation and receive text replies. The toggle is also in the mobile conversation header and mobile Settings. All controls save the same preference on the server device. Hands-free conversation uses an accent Start conversation action and a distinct Stop conversation action. The state row shows a coloured indicator with Running or Stopped, alongside the backend phase when available. The global dictation hotkey and this machine’s input devices are desktop-only; a browser client shows the rest of the page. See Voice Dictation for full details.
Smart Prompts
Manage the AI-powered actions surfaced in the toolbar, context menus, and command palette. Reachable from the nav or directly via “Manage Smart Prompts…” in the Smart Prompts drawer.
- Headless Agent — default agent for headless prompts; individual prompts can override it
- Prompt list — grouped by category, with enable/disable toggle and placement/mode badges
- Editor (click a row) — name, description, content with variable insertion, placement checkboxes, Execution Mode, inject target, Auto-execute, output target, system prompt, keyboard shortcut
- Built-in prompts show “Reset to Default” once overridden; custom prompts can be deleted
See Smart Prompts for the full guide.
Integrations
MCP
HTTP API Server
Enable the HTTP API server for external tool integration:
- Serves the REST API and MCP protocol for AI agents and automation tools
- Local MCP connections use a Unix domain socket at
<config_dir>/mcp.sock— no port configuration needed - AI agents connect via the
tuic-bridgesidecar (auto-installed on first launch for every supported agent that is installed on the machine — see MCP bridge auto-install) - Shows server status (running/stopped) and active session count
TUIC Tools
Native tools exposed to AI agents via MCP. Each tool can be individually enabled or disabled to restrict what agents can access.
Manual MCP configuration (expandable) — shows the tuic-bridge binary path and a ready-to-paste JSON snippet for manually configuring MCP clients that aren’t auto-installed. Click “Copy” to copy the snippet to clipboard.
Collapse tools (checkbox) — when enabled, replaces the full tool list sent to AI agents with 3 lazy-discovery meta-tools (search_tools, get_tool_schema, call_tool). Cuts the baseline MCP context cost the agent carries every turn. Measured 2026-09-13 against the running desktop instance with 190 tools connected: the full list is 154,117 bytes / 35,104 tokens, the collapsed list 2,810 bytes / 615 tokens — and the collapsed figure does not move with the number of upstream tools, because they are no longer in the list. The agent fetches schemas on demand via BM25-ranked search. (Tokenizer: tiktoken 0.14.0 o200k_base, a GPT tokenizer used as a proxy; Anthropic publishes no offline tokenizer. Method and full table: mcp-http.md.) Native semantics do not change: a managed command is still one call_tool request for session action=submit, and its bounded receipt comes back in that response. Default: off. Grok sessions receive this compact surface automatically for compatibility with Grok’s tool-name parser, without changing the checkbox or other clients. Toggling emits notifications/tools/list_changed; compatible clients refresh automatically, while clients that ignore the notification may require a reconnect.
Call audit (MCP page) — Record MCP call outcomes keeps a body-free, in-memory log of recent agent tool calls. When on, the table lists time, operation, known target name and id (or a digest when unresolved), outcome (Replied / Error / Cancelled), response bytes and effect (Read-only / Completed / Failed / Not started / Unknown), with an outcome filter and a Refresh button; it loads when the page opens and on Refresh only. Effect tooltips explain the observation: Completed means the handler returned, not that queued external work finished or the client received the reply. Unknown is reserved for uncertain completion, such as cancellation, an interrupted handler or a lost upstream reply. Default: off in release builds, on in debug builds.
Capabilities — three visible sections follow the approved MCP domains: Always listed (sessions, peers with task outcomes, repositories, workflows with story/run/proposal/report/launch controls, automations, user interaction with Design Mode, secrets, settings and progress), Rarely needed (diagnostics and plugin reference), and Conditional (voice, Telegram and remote deployment). Member controls stay nested under their domain without a disclosure. Conditional rows report whether voice or Telegram is configured or a remote server is connected, independently of their saved switch. Unavailable features remain configurable. A parent restriction also denies its member actions without changing saved member denials. Blocked member switches show off and cannot be edited; their help text names the parent to enable. Enable that parent to restore each saved member preference and edit individual members. Progress still requires global Progress tracking, and Settings requires trusted UI opt-in. Saved tool denials migrate once without re-enabling their new actions. Unknown old names remain visible as migration diagnostics. See Capability cutover for the breaking tool-name changes and reconnect requirements.
Upstream MCP Servers
Manage in Settings in the MCP popup (Cmd+Shift+I) opens the MCP page scrolled to this block — the block sits below the fold, so a plain page switch would look like nothing happened.
OAuth upstreams show Authorize when consent is required. TUIC prepares the OAuth request, then displays a blocking in-app confirmation naming the authorization-server origin before opening the system browser. Cancelling that confirmation discards the pending request.
Proxy external MCP servers through TUICommander. Their tools appear prefixed as {name}__{tool}:
- Add upstream servers via HTTP (Streamable MCP) or stdio (process) transport
- HTTP authentication starts with a masked Bearer field. Choose OAuth 2.1 when the upstream supports it.
- Use + beside Secret headers to add multiple name/value rows, and − to remove a row. Every value is masked and stored in the OS credential vault. Saved rows show an empty secret field: leave it blank to keep the current value, or enter a replacement.
- Header names and credential references are saved in
mcp-upstreams.json; values are never saved there. Invalid names, duplicate names and Authorization beside Bearer/OAuth are rejected. Routing, framing and MCP protocol headers are reserved. - An upstream with Bearer, OAuth or secret headers cannot change to another URL origin (scheme, host or port). Add a new upstream with a different name for a different provider. Same-origin path edits retain the saved auth settings. Stored credentials are checked against their saved origin before requests. After upgrading, credentials saved without an origin binding must be entered again, or authorized again for OAuth; the connection error explains this.
- Credentials are sent only to the configured origin. Same-origin redirects work; a redirect to another scheme, host or port stops with an upstream error.
- Live status (connecting, ready, circuit open, failed) with tool count and call metrics
- Reconnect and remove controls per upstream
- Per-repo scoping: each repo can define an allowlist of active upstream servers via Cmd+Shift+I popup (or repo settings). Empty/null allowlist = all servers active
See MCP Proxy for the full guide.
Remote Access
Enable HTTP/WebSocket access from other devices on your network: port, credentials, network interface, session token duration, IPv6, LAN access without authentication, Tailscale HTTPS, the connect QR code, and the Cloud Relay. See Remote Access for full setup guide.
Remote Machines
Add, connect, and manage tuic-remote daemons on other machines over SSH or a
direct URL. Auto-update remote daemons is a per-connection option, off by
default. It updates on connect only when the daemon has no live PTY sessions.
See Remote Access → Remote Connection Manager.
Plugins
Install, manage, and browse plugins. See Plugins for the full guide.
- Installed — List all plugins with enable/disable toggle, logs viewer, uninstall
- Browse — Discover and install from the community registry
- Check for plugin updates — fetch the registry at startup and show available updates
Repositories
Per-repository settings. Open them from the Repositories group in the
Settings navigation, or from the sidebar ⋯ → “Repo Settings”.
Worktree Tab
- Display Name — Custom name shown in sidebar
- Base Branch — Branch to create worktrees from (auto-detect, main, master, develop)
- Copy ignored files — Copy .gitignored files to new worktrees
- Copy untracked files — Copy untracked files to new worktrees
Scripts Tab
- Setup Script — Runs once after worktree creation (e.g.,
npm install) - Run Script — On-demand script launchable from toolbar with
Cmd+Shift+R - Archive Script — Runs before a worktree is archived or deleted; non-zero exit blocks the operation
- Dev Server URL — Optional address of this repository’s development server. Design Mode opens it in a dedicated Chrome window; with no URL, Chrome opens
about:blankso you can navigate manually. See Design Mode.
Repo-Local Config (.tuic.json)
A .tuic.json file in the repository root provides team-shareable settings that override per-repo app settings and global defaults. The dedicated repository page reads this file. All settings (Expert) can edit its catalogue fields through the registered-repository owner, with a revision check; you can also edit it in your repository.
Precedence: .tuic.json > per-repo app settings > global defaults
Supported fields: base_branch, copy_ignored_files, copy_untracked_files, setup_script, run_script, archive_script, worktree_storage, delete_branch_on_remove, auto_archive_merged, orphan_cleanup, pr_merge_strategy, after_merge, auto_delete_on_pr_close.
User-specific settings (promptOnCreate, autoFetchIntervalMinutes, and the Dev Server URL) are intentionally excluded from .tuic.json.
Repository-local config reads are independent. If a repository is unavailable, its last successful values stay in use while other repositories refresh. A successful read that finds no .tuic.json clears the cached local values. A later successful read adopts the recovered repository’s current values.
Telegram
Settings → Telegram configures the current machine. Bot setup, Chat access, Agent registration and Recent messages have separate cards. Authorized chats use named list rows with a Remove action, and Reload status refreshes the polling summary. Telegram setup is available only in desktop Settings, not in mobile Settings. Use it on the host running the desktop app or tuic-remote. Both share one polling owner on that machine.
- Paste the BotFather token into the password field and select Save and check bot. TUIC writes
bot.tokenwith owner-only permissions and checksgetMe. Settings shows the bot username and whether a token is set; it never reads the token back. - Enable Telegram. Ask an agent in the polling app to opt in with the Telegram MCP tool (
register/unregister); Settings shows the registered agent read-only, or No agent registered. When the status is connected, select Link chat, then send the displayed six-character code to the bot within ten minutes. The code works once. Alternatively, type a positive private chat ID and select Add chat ID. Remove revokes authorization. The bot confirms a successful link with Chat linked., and the consumed code hint disappears on the next Settings refresh. A bare/startexplains how to get a code but does not authorize a chat. Wrong or expired six-character hexadecimal codes receive a safe retry instruction; other unauthorized text receives no reply. With no registered agent, an authorized message reaches the latest-connected live AI Chat agent (connection order, not tab selection). An explicit registration always takes priority. Connecting another AI Chat changes only future inbound delivery; existing requests keep their original reply peer. Request-specific reply tools require that peer’s MCP binding. Explicit registration takeover revokes pending requests. Only when neither exists does the bot send a short English registration instruction. An ordinary message after pairing in the same poll uses the new authorization; the pairing code never reaches the agent. Link confirmation is best-effort: if sending it fails, the chat stays linked and the consumed code is not replayed as agent mail. The failed reply appears in Recent messages. - Recent messages shows the last 20 events in the process serving Settings, newest first: time, in/out direction, message/pairing/start/reply/button kind, outcome, and a preview of at most 60 characters. It refreshes while the page is open. Codes, tokens and unauthorized text are redacted before storage. This log stays in memory, clears when the app or daemon restarts, and is not shared between a polling owner and a standby process. Check connection status, safe error category and last accepted message time. Status identifies this app, tuic-remote, or another desktop owner. The desktop app starts the same adapter at boot; its process-held lock prevents a second local poller. A standby takes over when the owner exits. If no poller is connected, Settings explains the next action and disables Link chat. Config changes restart the owning adapter and retire its current transient draft state. Resolve any reported error, then disable and enable Telegram to retry a stopped adapter.
Keep a coordinator as the Telegram owner
Ask the coordinator in the app or daemon that owns Telegram polling to call the
telegram MCP tool with {"action":"register"}. This registers that caller,
not a named child. Settings shows its name under Agent registration. A second
agent that registers replaces it, so child agents should use send without
registering when the coordinator must keep inbound ownership.
Registration is in memory. After TUIC or the polling daemon restarts, reconnect
or resume the coordinator and ask it to call {"action":"register"} again.
The same call is safe to repeat. {"action":"unregister"} releases its own
registration. A role name alone does not register a Telegram owner.
Non-owner messages show [session name] [alias: TUIC address] on every chunk.
The address is the terminal alias, or the stable peer ID for a session without a
terminal. You can quote both to the coordinator. Reply selects a unique live
exact-name sender first, then the registered owner, then a live AI Chat.
If the sender has exited, the fallback mail carries its quoted name and address,
the original message and your reply. The bot names the session that received it;
this confirms inbox delivery, not that the session has read it. The coordinator
can use that context to find or recover the work; TUIC does not restart the child
automatically. If nobody can receive it, the bot names the unavailable sender
and asks you to register an agent. Older messages without an address retain the
name but cannot supply a historical alias.
Shared provider account storage
Core now stores provider accounts and sites in one registry. Existing GitHub accounts retain their identities and repository bindings. Token values remain in the core credential store; account reads show only set, unset or unavailable status. The Accounts controls and private native add flow are integrated separately by the Settings extension. A failed account operation may need storage repair before retrying; see migration and recovery.
GitHub Enterprise account creation asks for the host in Settings, then opens a separate private native window for the PAT. Settings never displays or stores the PAT. Decline or close that window before submission to cancel. A headless server cannot open this native credential window. After Submit is accepted, verification finishes even if you close the window.
The internal GitHub settings backend keeps OAuth device login for github.com and verifies Enterprise PAT identity before storage. Account reads expose credential status only. The new shared settings tool is published in a separate cutover step; this backend adapter does not add a new user-facing endpoint.
Work-item access for agents
Agents can read linked Tasks items through the MCP repo tool. Tracker comments and status changes are disabled by default. To enable them, set mcp_work_item_writes to true through the configuration save API, or edit config.json while the app is stopped. There is no separate Tasks write toggle in Settings. A frontend with the provider loaded must remain connected. After a write times out, read the item before retrying.
Background tray and menu-bar icon
In General > Confirmations, Tray and menu-bar icon selects Always, Only in background (default), or Never. Never disables the Background choice. If the tray cannot be created, or the Linux desktop has no tray host (such as stock GNOME), closing minimizes the window so it remains reachable. The tray menu offers Show TUICommander, live working/awaiting counts and Quit. An attention mark clears when you show the window. Linux uses the menu; macOS and Windows also support left-click to show.
Plugin integration pages
Loaded plugins with registered settings appear under Settings > Integrations. Search includes their catalogue field labels. Unloading removes the page and search entries. Reads, revision-checked edits, resets and secret set/unset status use the scoped Rust settings service; the UI owns no second configuration store.
String-list edits, added rows, and removed rows stay in a draft until focus leaves the list. Read failures show an alert on the plugin page and do not close Settings.
Automatic idle-agent hibernation
The backend checks unattended top-level agent tabs every five seconds. agents.hibernate_idle_minutes defaults to 60 awake minutes; zero disables the sweep. agents.hibernate_scope defaults to background_only; always also permits foreground hibernation. Both machine-owned controls are in Settings → Agents (Expert Mode).
Hibernation requires an idle agent and a verified resume session in its saved profile. Plain shells and agents without a verifiable resume session stay live. Unread peer mail, pending commands or background work, awaiting input, attached readers, keep-open tabs and open automation runs prevent hibernation. Managed children retain their separate idle-close policy. Sleep gaps longer than 30 seconds do not advance the idle clock.
The normal Rust suspension path persists reason: "idle_hibernate" before ending the PTY. Opening the tab, submitting input or sending peer mail uses the shared wake path. Storage or resume-verification failures leave the live session intact.
Tasks notifications
Settings → Notifications → Tasks has OS notifications for Tasks, off by default and independent of the existing PR notification preference. Failed checks on a linked GitHub PR use the existing PR notice once and name the linked Tasks item. Click the notice to open the PR’s Comments section in Tasks. If its work-item provider is not loaded, the conversation opens on GitHub.
Use Follow task in an item detail to follow comments locally; use Unfollow task to stop. Follow state and the policy are saved in the existing Tasks UI preferences. A first observation establishes a silent baseline. Existing visible detail refreshes (including its 60-second refresh) and provider-bridge detail reads compare authoritative comments; there is no extra background poller. Your own comment action advances the baseline silently. Native notices recheck the Tasks policy after permission is granted and retain the existing background-window policy; browser clients do not send native OS notices.
GitHub provides a full normal-comment count, so an increase is detected even beyond the first page. Jira and GitLab provide paged comment entries: newly observed comments notify when their creation time is newer than the prior baseline, or when a previously unseen comment ID shares its latest timestamp. Unloaded pages, unseen review sources and items that are not refreshed cannot produce a notice. Editing a comment or loading older history does not notify. No Linear provider is shipped, so it is not covered.
Settings MCP access (#1787-4778)
Enable the settings native tool under MCP to permit an agent to describe and edit settings. It is disabled by default, even if the removed config tool was enabled. Secrets are write-only. Changes to external access or the trusted executable require the existing confirmation dialog. The owner inventory is complete. Use explicit target/store/paths for owner reads and dynamic-choice describe/refresh. Typed workflows select their store and operation; credentials remain write-only. Future unresolved owner gaps block edits.
Agent model settings support typed model edits without starting a CLI. Explicit
choice refresh probes only the addressed Claude run config with --help, using
its command and environment. Published aliases are suggestions, not account
entitlement or an exhaustive model list. Other CLIs and failed probes report
unavailable choices; typed edits remain supported. Describe never probes. Model
edits preserve sibling configs and the default selection and apply next session
(#1910-451e).
Shortcut saves reject invalid action identities, duplicate action records and invalid modifier syntax. Plugin shortcuts retain stable namespaced IDs. Pane geometry saves reject invalid ratios, excessive nesting and missing groups without changing saved layout. Runtime tab membership and current pane focus remain session restoration state.
Font options come from the bundled font catalogue. Theme options include custom themes from the Rust theme owner. Settings choice discovery is explicit: describe does not probe installed applications; refresh requests host IDE discovery. Unavailable discovery is not an empty result.
Audio device availability
An empty device list means enumeration succeeded with no devices. If the audio backend cannot enumerate devices, refresh reports an error instead. Voice language and engine changes keep the existing speech runtime invalidation behavior.
Shared layout
Settings uses one bounded, responsive shell across pages, with independently scrolling navigation and content. The panel is at most 1136px wide and retains its size when you select another page. Saved navigation width remains in use. Shared presentation components support consistent cards, label/control rows, source-aware status, empty states and scoped destructive actions as pages adopt the approved restyle. Save behavior and configuration ownership do not change.
Scope and operation states
The page header identifies the setting owner. Repository edits remain tied to the selected repository; Agents uses its machine selector; plugin pages name the plugin that supplies their fields. A page change does not transfer settings between these owners. Done closes Settings; it is not a global Apply action.
Loading, empty results and failed reads are different states. A plugin catalogue with no fields adds no page. While plugin values load, the editor shows a local loading message and keeps navigation and Done available. A failed read shows an alert inside the editor. Rejected writes reload the latest revision rather than reuse stale values for the next edit. Unloading a plugin removes its editor even if a read is still pending.
Status words describe the reported state, not inferred connectivity. Saved credentials do not prove live access, and ego’s unchecked sandbox status is not proof of OS enforcement. Use the page’s existing Refresh or recovery action; opening Settings does not authorize extra network or sandbox probes.
Section links open the requested page and scroll after it mounts. Older
services links open MCP, and developer-tools links open General. A missing
section does not redirect to an unrelated control. Closing Settings cancels a
pending section scroll.
Task-based settings presentation
AI Chat groups new-run defaults into Agent and model, Workspace access, Network and sandbox, and closed Advanced and diagnostics. The executable, profile, and workspace remain owned by TUICommander in General. Model and access values remain owned by ego; these controls do not change running conversations.
Voice uses separate task cards for dictation, recognition, corrections, hands-free conversations, and spoken replies. Smart Prompts retains categorized prompt editors and the existing execution controls. Integration pages use local connection, access, and service cards. Remote token regeneration requires a scoped confirmation because it disconnects active remote sessions.
The plugin manager retains lazy Installed/Browse views. A loaded plugin’s settings page identifies its plugin source and uses schema-driven controls; saved credentials are not evidence of a live connection. Existing explicit-save and automatic-save boundaries still apply to each page.
Loaded plugins with described settings appear in a separate Plugin settings navigation group with a plug icon. The manager offers Settings only when the loaded catalogue provides a page. That action opens the same scoped page as the navigation entry; it does not create a second settings service.
AI Chat groups provider details in Other providers and available models. Workspace access shows the effective folders first. Add folder and Edit reveal the existing ego roots draft; Save roots in ego keeps its explicit save boundary. The network selector writes through ego. How to verify explains command-isolation evidence without running a probe.
Voice keeps downloadable models and voice management in Speech assets.
Speech assets and Spoken replies use the same aligned label/control rows.
Choose an installed Whisper model or reply voice with the shared dropdowns;
unavailable Whisper models remain disabled until downloaded. The configured model
stays selected while the model catalogue loads, even if it is not downloaded. Both asset lists
use named Download, Repair, Cancel and Remove actions where supported, shared
status badges and the same progress display. Voice processing and save rules do
not change. Remote Access separates connection status, Tailscale HTTPS and token revocation. Plugin rows keep secondary controls in Manage plugin; plugin pages identify their source and plugin-owned scope.
Native MCP tool help stays anchored during status refreshes. Focus a ? badge
with the keyboard or hover over it to read the full tool description. Help
placement follows panel scrolling, window resizing, and description size changes.
Contextual explanations
Selected settings show a ? only when the approved explanation adds decision guidance, requirements, consequences or owner-dependent defaults. Hover or focus the badge to read it. Click or press Enter/Space to pin it; click again, press Escape or click outside to dismiss it. Help does not save a setting, contact a service or run a sandbox probe. Long help scrolls inside the viewport and follows panel scroll/resize. Native MCP help retains tool-name identity while descriptions update during status polls (1928-e282).
AI Chat places provider refresh beside the default model and lists effective roots with their source, access and Edit action. Reload from ego is in Advanced and diagnostics. Voice lists Whisper downloads below the active-model selector and keeps correction import/export in the card actions. Smart Prompts uses Edit to open a separate editor card; the enable switch stays visible on each library row. Custom prompt deletion remains confirmed in the final danger section.
Loaded plugin pages use the same title-icon slot as other Settings pages. The source line identifies bundled or installed ownership without changing the page label, catalogue lifecycle, or scoped editor behavior.
Plugin field resets sit next to their controls and appear only for non-default values (or a set credential). Plugin management uses compact secondary actions.
Telegram request streaming (1959-162a)
Telegram replies now use TUIC-driven receipt (👀), working (👨💻), waiting (🤔), answered (👍) and failed (👎) reactions. An ephemeral native draft shows Italian status lines or unapproved agent previews; it refreshes while work continues and the final reply replaces it. Acknowledgement of work requires inbox Read and a new recipient turn. PTY intent/activity and AI Chat assistant chunks share request correlation; finish remains authoritative after draft retirement. Telegram-mail-woken AI Chat turns automatically send their settled assistant text if finish has not answered. Queue and no-reply notices occur at ten minutes and sixty seconds after Read respectively. Restart keeps no request history. Phone rendering requires a live check after the backend restart.
Settings search includes page titles and shared card controls. Page-title results scroll to the page header; when a page and card share a title, control results use the card. Runtime status badges and summaries are not settings search targets.
Changes made through MCP
An open Settings page refreshes after a durable MCP settings write. Unsaved fields stay in place; if another writer changes the same field, a warning asks you to review your edit before saving again. Incoming changes do not run startup migrations or save the snapshot back to the backend. A reconnected browser rereads its active settings sections, including after a server restart. Remote-machine changes refresh only that machine’s editors, not local settings. If a write persisted but its runtime apply failed, Settings still rereads the saved state; the caller must follow the returned recovery action rather than blindly replay the write.
All settings (Expert)
The Application → All settings (Expert) page provides typed scalar and string-list editors from the Rust catalogue. Search results update the inspector even when this page is already open. You can also select a setting manually. Bind any stable record keys, and select a registered repository or existing Ego profile when required. The inspector edits existing records; use the dedicated domain page to create records, manage credentials or edit structured pane/forward/root data. It does not expose an opaque JSON editor.
Reads show owner state and a revision. Save changes only that field with its read revision. A remote update keeps a dirty draft and its old revision, so a conflicting save cannot silently overwrite the new state. Discard draft and reload explicitly abandons that draft. Exposure/execution edits first return a proposal; Ask for confirmation uses the existing human dialog. If persistence succeeded but runtime application failed, or the transport lost the outcome, the inspector disables writes until you reload authoritative state. Read back before retrying.
General also exposes content-index memory budget, attachment byte limit and background WebView unload delay as expert resource controls. Enum-backed shared selects use catalogue values while retaining their existing readable labels. Search includes the inspector descriptors. In browser mode, these results open machine-owned fields in the HTTP-capable inspector; they do not open desktop-only controls such as the native global-hotkey recorder.
The explicit source ledgers distinguish read-only identities, derived credentials, legacy snapshots and separate domain controls. CircleCI credentials use the write-only circleci.token owner. Dictation corrections use stable heard-text keys in the machine-owned corrections collection; edits reuse TextCorrector and refresh open Voice pages without microphone access. Global PR visibility filters persist in config.json. Nullable repository overrides persist in repo-settings.json; null inherits the global filter and false explicitly shows matching PRs.
Assisted startup
The Settings startup contract describes discoverable GitHub device/Enterprise workflows and Ego settings/readback. GitHub list_accounts discovers existing account IDs and credential presence. Typed Ego begin_login opens a terminal for you to authenticate; login_status reports process lifetime and owner credential readback separately. Native inventory completeness does not mean every onboarding or live UI check is complete.
CircleCI Settings owner (#1991-bd88)
Settings discovery includes the write-only machine setting circleci.token.
Typed set_token and clear_token actions share the existing token owner across
MCP, IPC and HTTP. Readback reports stored presence only (set, unset,
unavailable), never a secret. Git & GitHub keeps its effective-source status;
removing a stored token leaves environment and CircleCI CLI fallbacks unchanged.
On narrow screens, search and page selection share one compact navigation row. The workspace path in AI Chat is a read-only field; select or scroll its text to inspect the full path.
Mobile font sizes
In mobile Settings, use the Terminal and Chat minus/plus controls under Appearance to set each size from 10 to 24 px. Each value is saved on this device. Terminal changes CLI output; Chat changes Session Chat and AI Chat transcripts. The defaults remain 14 px for terminal output and Chat body text. Composers, UI controls and desktop fonts stay unchanged. CLI text wraps to the available width without changing the shared terminal size.
Abandoned shells
Desktop sidebar session rows and mobile session cards mark a parentless plain shell as Abandoned after one idle hour and show its idle age. The five-second backend sweep requires a fresh OS process inventory: the PTY child must be an interactive shell with no child processes. An unknown inventory, script, foreground command, background child, detached TUIC job, managed identity, live child session, pending input or keep-open hold prevents closure. Unsupported or incomplete OS process observations fail closed.
Settings → Agents → Idle agent hibernation (Expert Mode) includes Close abandoned shells after (hours) (agents.abandoned_shell_hours). The machine-owned value defaults to 0 (off); whole hours from 1 to 65535 enable closure. Idle age is measured from the most recent input, output or semantic activity, including elapsed time while the machine sleeps. Closure rechecks the process inventory and activity at the destructive boundary, and uses the normal session close/tombstone path. The sweep can lag the threshold by one five-second tick. A remote daemon applies its own setting, not the desktop host’s value.
The monitored-repository count tracks successful snapshots in the running GitHub monitor, including repositories with no open PRs. Query-cache expiry and temporary poll failures do not reset this count. Removing a repository or stopping monitoring removes its entry.
Git & GitHub access diagnostics show exact per-repository messages grouped by owner and account. For github.com OAuth accounts, use the OAuth app authorization action, then select Refresh status to clear NOT_FOUND retry delays for all accounts before the next monitoring poll. Opening Settings does not clear these delays.
Archived worktree retention
Git & GitHub → Worktree Defaults includes Archived worktree retention (days). 0 is Off, the default. Repository → Worktree has a nullable override: leave it empty to inherit, or enter 0 to keep that repository’s archives. Cleanup uses recorded archive age on repository refresh, preserves committed work in archive refs, and keeps dirty or otherwise unsafe archives with named reasons. See Worktrees.
Grok hook updates
After updating native hooks in agent settings, relaunch Grok to load completion, cancellation, failure and permission lifecycle coverage. Installation updates the TUIC-owned hook file and preserves other hook files.
Windows agent hook controls
Native Windows does not install or inject TUIC’s external POSIX status hooks. Hook state returns unsupported, and hook/status setters reject changes before writing preferences or user hook files. Saved preferences and existing hooks remain intact. Settings hides these controls based on the owning backend response, including remote machines. External agents retain heuristic detection; ego keeps native PTY OSC signals and its separate ACP path.
Design Mode
Design Mode collects elements and comments in a browser sidebar before sending feedback to an agent. Ordinary page interaction remains available until you explicitly start picking.
Start Design Mode
- Open an agent terminal in your repository. Choose Start Design Mode from its context menu or the Command Palette. Choose Design Mode browser offers Edge or Chrome; the palette also offers a command for each browser. Safari is unsupported.
- TUIC opens a dedicated profile for this repository and browser. Start succeeds only after the extension acknowledges the launched page; a missing or incompatible worker returns
browser_not_readyand closes that launch. Edge loads the extension automatically from that profile’s own folder. A single discovered dev server opens directly; otherwise, a page explains how to choose or start one. No manual extension installation is required. - Click the TUICommander browser extension icon to open the sidebar. It lists configured and running dev servers. Choose one, enter a URL in the address bar, or use Start dev server if you have configured a Run Script in Repository Settings. Refresh rescans servers and agents.
- Choose Pick element, then click an element. A card appears and normal browsing resumes. Multi-pick continues collection until Stop, Escape or the two-minute timeout. Each card has an independent comment and Delete button. Drafts survive worker suspension; closing their browser tab deletes them. A tab holds at most 32 picks.
- Add comments, choose the receiving agent, and click Send to agent. The terminal that launched Design Mode is selected initially. Other live local agents in the same Git repository, including linked worktrees, are available. If your selection exits, the sidebar asks you to choose another; it never silently switches recipients.
- Feedback is delivered immediately when the agent is idle, or queued for its next idle window. The sidebar reports which happened. Failed sends retain your cards; retries to the same recipient reuse the exact batch and delivery key. Choosing a different recipient rebuilds the batch from retained commented picks with a new delivery key. Only commented picks are sent.
The D badge and Stop action remain on the launching terminal. Browsers open on the backend host, including when TUIC is controlled from a browser/PWA client. No debugging port or automation banner is requested by the v2 launcher. Close an existing Design Mode browser window before starting again: Chromium ignores new extension flags on a running profile, and a cold launch also repairs an extension loaded from another repository’s folder. TUIC reports this condition and does not stop an existing browser process.
On Unix, a reachable profile socket or a local owner with the exact --user-data-dir identifies a running profile. A stale lock whose PID was reused by an unrelated process does not block startup. TUIC does not delete lock files; the browser handles stale-lock cleanup. A foreign-host lock can be reclaimed on macOS; on Linux, close the browser on that host or unlock the shared profile first.
Stop Design Mode closes and reaps only the dedicated browser process that its successful start opened; closing the agent terminal still leaves the browser available for ordinary browsing.
Branded Google Chrome 137+ ignores automatic extension loading. TUIC reports an error and asks you to choose Edge or Chromium; CDP pipe installation is not implemented. Branded Chrome is unverified on the development machine because it is not installed. See the Chrome extension team announcement.
Page JavaScript errors
Design Mode records the current page’s uncaught errors, unhandled promise rejections, console.error calls and failed <script>, <link> and <img> loads (a 404 module included), in every frame, from the start of the page load. Each record has a message, source URL, line and column, stack and time. The sidebar keeps the last 50 per tab, deduplicated by message and source, and clears them when the tab loads a new page.
When errors exist, the sidebar shows an Errors section with a count badge. Tick Attach to feedback to send them with your next batch, or use Send errors only to send them alone, without any comment. Sent errors are removed from the list. They are untrusted page content: Rust strips terminal controls and URL queries, redacts recognised secrets, bounds the text and fences it, exactly like picks. Failed fetch and XHR requests are not observed.
Connection and evidence
The native host pins the extension identity, repository and exact TUIC instance. It relays a bounded set of operations over that instance’s local socket or named pipe. Reopen Design Mode after restarting TUIC to refresh its binding. Connection failures show the endpoint and reason. An older running backend can list agents but returns an explicit restart error for the new feedback/discovery route.
Cards retain selectors, DOM paths, snippets, selected styles, CSS tokens and available framework source hints. CSS tokens include references in shorthand declarations such as padding: var(--gap), inline styles and adopted sheets in open shadow roots; unrelated theme tokens are excluded. Rust bounds and sanitises page evidence, redacts recognised secrets, strips terminal controls and fences it as untrusted content. Captured PNG crops are saved in design-grabs and sent as readable [image: path] references. Screenshot capture is optional: permission errors and oversized crops retain DOM evidence. Cross-origin frame picks currently retain DOM evidence without frame screenshots.
Discovery lists only the dev servers of the agent selected in the side panel (initially the session that launched Design Mode; the list refreshes when you pick another agent): the configured Dev Server URL, live listeners attributed by process directory or an absolute command path to that session’s worktree, and URLs that session printed in its own terminal. Other worktrees of the repository and other sessions are not listed. Live listeners must answer HTTP GET / successfully with a text/html Content-Type within 750 ms. TUIC itself is excluded. Probes do not follow redirects; the scan has a 3-second budget. Fresh PTY URLs are accepted only when their port has a verified live owned HTML listener. Multiple candidates are listed instead of automatically choosing one. Windows native host registration currently targets Edge and awaits Chrome/multi-profile validation. Windows discovery offers configured URLs and the address bar; listener attribution is not claimed there. Repo-local .tuic.json cannot silently supply executable scripts.
The pilot has browser evidence from Chrome for Testing. Native Edge Load unpacked persistence, toolbar-granted screenshot permissions and sidebar restoration still need an Edge check. Agents ask the browser to reload the reviewed tab with MCP ui action: "design_reload" (for static pages without HMR). The extension also tells TUICommander it is alive every 5 s: Design Mode stops by itself 60 s after the browser goes away. Everyday-profile installation is later work.
Start from a link or coordinator
Right-click a terminal HTTP(S) link and choose Start in Design Mode, then Edge or Chrome. This always starts or rebinds to that terminal agent and opens the exact URL, even if another agent is already connected. The D badge follows the bound session.
For layout work, coordinators use MCP ui with action: "design_start", session_id naming the live terminal agent, and url naming the HTTP(S) page. Optional browser selects chrome or edge. Use action: "design_status" for bindings and action: "design_stop" with the returned repoPath as repo_path. Browser launch happens on the host; an ACP coordinator does not become the terminal agent.
If the sidebar icon is hidden, open the Extensions (puzzle) menu and pin TUICommander Design Mode. You can also press Option+Shift+D on macOS or Alt+Shift+D on Windows/Linux. Browser choice currently lists Edge and Chrome; launch reports if the chosen browser is not installed.
Agent browser commands
Agents can request design_navigate, design_reload, design_screenshot,
design_errors, and design_eval through ui. The native port returns a request-id-matched reply, with a ten-second
timeout. Start selects the launched page after an extension acknowledgment, without requiring the sidebar. Opening the sidebar on another page selects that page for later commands. Screenshot fails
if that tab is not visible; it never captures a different active tab. Captures are
stored in the instance’s design-grabs directory with the correct .webp or .png suffix.
The agent chooses the encoding on each ui action=design_screenshot call:
format:webp(default) for text and layout, orpngfor pixel-exact detail.quality: WebP quality from 1 to 100, default 25. Use 50 or more for small glyphs and icons. PNG ignores quality.max_long_edge: optional positive pixel limit. The extension downsizes before encoding and never upscales.
The response includes the image, path, format, quality (null for PNG), byte size
and media type. There is no user setting. Token cost follows pixel dimensions,
not format or byte size: Claude uses about 1,296 tokens per megapixel, capped at
1,568 standard / 4,784 high-res. Selected-element crops remain lossless PNG and
keep their existing 800 × 600 pixel bounds.
To let the agent of the current Design Mode session work on a host, click Allow agents on this host in the extension sidebar. This one click gives two things:
- Chrome’s optional all-sites permission. Chrome needs it to capture a tab without a toolbar gesture and to run scripts on remote hosts. Chrome asks only the first time.
- TUICommander’s consent for the armed session on the host of the active page.
The consent lets that session capture, read page errors from, navigate to and run JavaScript on that host. It applies to one session and one host. Another session or another host needs its own click. Consent is kept in browser session storage and ends when the browser closes. Chrome’s own grants, including all-sites or wildcard grants, are not TUICommander consent. You can revoke Chrome access in Chrome’s extension settings. TUIC still restricts commands to the armed session and the reviewed tab.
Local HTTP(S) pages need no consent to reload, navigate, read errors or take
screenshots. Agent JavaScript (design_eval) needs consent also on localhost.
Remote hosts need consent for every command. A denied eval replies at once with
eval_not_granted: grant needed: click Allow agents on this host; other remote
commands reply with host_denied. Neither waits for a grant or times out. Eval runs
in the page MAIN world without a debugger port. If the page moved to another host
after the check, eval returns page_changed.
Without Chrome’s all-sites permission, invoke the Design Mode browser action on the
reviewed tab for temporary activeTab capture access. Cross-origin navigation or tab
closure can remove that access. A missing grant returns capture_permission_required
and names Allow agents on this host; DOM evidence remains available.
Navigation reports acceptance, not page-load completion.
Screenshots that exceed 512 KiB are downscaled until they fit, and the response
reports downscaled: true. Eval scripts can be up to the 256 KiB command bound.
Eval results are redacted evidence, not instructions, and are paged in 16 KiB pages:
the response holds total_bytes and next_offset, and the agent passes
result_offset to read the next page. Each page evaluates the script again.
The sidebar retains the last fifty agent actions with session, action, time and outcome.
The server list, action history and permission section share the panel content inset.
Permission and error action buttons wrap with a gap, including in narrow sidebars.
The grouped ui tool always lists design_* actions. Discovery is not authorization:
dispatch requires the armed terminal session and repository. Lifecycle changes
emit notifications/tools/list_changed; clients that cache schemas may still show
actions while stopped, but dispatch refuses them with
Design Mode not armed for this session. Remote error capture starts on the next
page load after host consent and covers every consented remote host. Chrome’s
all-sites permission alone does not register remote error scripts. Remote
design_errors calls without consent refuse instead of reporting an unobserved
empty list.
The extension starts its command receiver at worker startup. Receive failures appear in the connection status instead of being silently discarded. Action-history storage failure cannot suppress a command reply. A disconnected native channel rejects later commands immediately with browser_disconnected; restart Design Mode to establish a new channel. The MCP bridge allows a 15-second transport budget around the browser’s 10-second command deadline, and 30 seconds for acknowledged startup, so browser errors are not replaced by an equal-deadline IPC timeout.
AI Agents
TUICommander detects, monitors, and manages AI coding agents running in your terminals.
Aider is no longer an agent harness. An aider command runs as a plain terminal command. Old settings remain readable, but Aider profiles are excluded from agent pickers and managed peer launches.
Supported Agents
| Agent | Binary | Resume Command | Session Binding |
|---|---|---|---|
| Claude Code | claude | claude --continue | claude --resume $TUIC_SESSION |
| Codex CLI | codex | codex resume --last | codex resume $TUIC_SESSION |
| Gemini CLI | gemini | gemini --resume | gemini --resume $TUIC_SESSION |
| OpenCode | opencode | opencode -c | — |
| Amp (limited support, need more tests) | amp | amp threads continue | — |
| Cursor Agent (limited support, need more tests) | cursor-agent | cursor-agent resume | — |
| Droid (Factory) (limited support, need more tests) | droid | — | — |
| Goose | goose | goose session --resume | goose session --resume --name $TUIC_SESSION |
| Grok | grok | grok --continue | grok --resume <discovered id> |
| pi | pi | pi --continue | — |
| ego (terminal CLI) | ego | ego resume | ego resume <discovered id> |
Ego session discovery uses its per-PID index and validates the active writer lease. Older ego versions without this index retain lease-based discovery. Invalid index entries never select another conversation.
Claude MCP profiles
At startup, the primary TUICommander instance repairs its MCP bridge in the
default Claude config, an existing ~/.claude-private/.claude.json, and profiles
selected by inherited CLAUDE_CONFIG_DIR or Claude agent/run-config environment
settings. Use absolute profile paths (or ~/…). Custom remote transports and
disabled integrations are preserved. A project .mcp.json entry is unnecessary
when the user profile already contains TUICommander; remove obsolete duplicate
entries pointing into a build target directory. Startup logs name any configured
absolute bridge path that is missing or not executable.
Native scrollback on launch
Prevent alternate screen in Settings → AI → Agents is enabled by default for every agent. TUIC applies Claude Code’s CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 and CLAUDE_CODE_DISABLE_AGENT_VIEW=1 environment controls when enabled. A terminal that enters the alternate screen within its first seconds raises a warning toast naming the session and the fix. Codex and Grok receive --no-alt-screen when their installed CLI advertises it in --help; OpenCode receives --mini when available. On Windows, the probe selects an executable .exe or .cmd launcher ahead of an extensionless npm shell shim. TUICommander checks the executable with a two-second deadline and shares concurrent checks. A timed-out check is not retried until that binary changes; a quick inconclusive exit is retried after a short cooldown. Older versions still start without an unsupported option. Existing flags are not duplicated. On Unix, the PATH shim also removes repeated native screen flags after shell alias expansion, before the real executable starts. Arguments after -- stay unchanged. Absolute executable paths bypass this shim. Integration scripts and shim hard links are refreshed when TUIC creates a new shell; an app update does not replace functions already loaded in an existing shell. Rust applies the same policy to structured IPC, HTTP and MCP launches and exports it to new TUIC shells, where zsh, bash and fish wrappers apply it to commands typed manually. command <agent> bypasses those wrappers, but not the launch-instructions shim. Reopen an existing shell after changing the setting. In typed OpenCode commands, --mini applies to interactive launches (bare, options or a project path), and skips all recorded subcommands and aliases, including mcp list and run. Goose wrappers omit TUIC --name when arguments include --no-session, --name NAME, --name=NAME, -n NAME, -nNAME, --path PATH, --path=PATH, --resume or -r. Normal session and run launches retain tab naming.
Gemini currently defaults to the primary screen (ui.useAlternateBuffer: false), Cursor enables fullscreen only when requested, and pi defaults to regular TUI mode. Other agents without a documented alternate-screen control keep their own defaults. If an agent enters the alternate screen despite these defaults, TUICommander records one warning for that session with the agent name and detected version.
To allow alternate screen, turn off Prevent alternate screen for that agent. The preference applies to new TUIC agent launches and new shells. An explicit CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN value in a Claude command’s environment retains precedence.
Startup updates for managed Codex peers
Managed MCP Codex spawns pass -c check_for_update_on_startup=false so an available update does not park a child at the Update now / Skip prompt. This applies to the launch; it does not change the user’s saved Codex configuration. Real-binary update-trigger and composer checks are tracked in to-test.md (1373-85a3).
Workspace trust for managed spawns
Accept workspace trust for managed spawns is on by default for Claude Code, Codex and ego in Settings → AI → Agents. When an agent starts another agent through TUICommander’s agent spawn action in a new folder, the child starts without waiting for a workspace trust answer. Codex receives a trust setting for that one launch and folder, including when a custom launcher forwards its arguments to Codex. TUICommander answers Claude Code’s initial trust picker only when it shows the expected question with No, exit selected. It also answers Claude Code’s external CLAUDE.md imports question with No, disable external imports. Workflow-launched agents get the same answers. Any other first-run dialog is left open and reported to the parent as a wait with the dialog text. ego receives --trust-workspace, and ego remembers that answer for the folder. Codex and Claude Code keep their saved trust configuration unchanged.
Turn this setting off for an agent if you want to answer its normal trust question during managed spawns. Terminals that you open yourself always use the agent’s normal trust behavior.
Agent Detection
A supported agent started by hand in a terminal is detected from its foreground process on macOS, Linux and Windows. The backend records that identity in both desktop and headless builds, without requiring an open UI. HTTP and desktop foreground queries use the same detection logic. TUIC_SESSION identifies the terminal; it does not turn a plain shell into an agent. An agent stops being eligible when its foreground returns to a shell. Configured launch presets remain available during startup until a non-shell foreground is first observed, including a custom wrapper; startup helpers can intentionally disarm the preset early to prevent unattended shell input; after that they are also revoked on return to a shell. Transient tool subprocesses preserve agent identity. Submission and mail wake still require a ready composer with no partial user input or approval prompt.
TUICommander auto-detects which agent is running in each terminal by matching output patterns. Detection uses agent-specific status line markers:
- Claude Code: Middle dot
·(U+00B7), dingbat asterisks✢✳✶✻✽(U+2720–273F), or ASCII* - Copilot CLI: Therefore sign
∴(U+2234), filled circle●(U+25CF), empty circle○(U+25CB) - Gemini CLI / Amazon Q / Cline: Braille spinners
⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ - Codex CLI: Bullets
•◦
When detected:
- The status bar shows the agent’s brand logo and name
- The tab indicator updates to reflect agent state
- Rate limit and question detection activate for that provider’s patterns
Binary detection uses resolve_cli() — Rust probes well-known directories so agents are found even in release builds where the user’s shell PATH isn’t available.
Unconfirmed ego input
If an ego input write is unconfirmed, TUICommander does not send that payload again. A new, stable empty ego composer can restore readiness and release later queued commands and background completion wakes. Retained draft text still blocks injection. A blocked raw write reports uncertainty after two seconds; it can still complete, so do not resend it automatically. Session close remains available without waiting for that writer.
AI Chat state
AI Chat does not use terminal detection. Its state comes from ego over ACP, and the desktop panel, a browser and the phone show the same state:
- Working while a turn runs, while a tool call of that turn runs, or while an ego child of that chat runs. A durable child can keep a chat working after its turn ended; you can still send the next prompt.
- Waiting for you while a permission or a question is open. Answering, rejecting, Stop and an ego exit each remove the wait. An answered question does not come back when the panel reconnects.
- Idle otherwise. A chat that you stopped is marked interrupted.
A child in one chat never marks another chat as working. Child state needs an ego that advertises it (ego 0.4.1 or later); an older ego shows turn and tool state only.
Rate Limit Detection
When an agent hits a rate limit, TUICommander detects it from terminal output:
- Status bar warning — Shows a badge with the number of rate-limited sessions and a countdown timer
- Per-session tracking — Each session’s rate limit is tracked independently with automatic cleanup when expired
- Provider-specific patterns — Custom regex for Claude (“overloaded”, “rate limit”), Gemini (“429”, “quota exceeded”), OpenAI (“too many requests”), and generic patterns
Question Detection
When an agent asks an interactive question (Y/N, multiple choice, numbered options), TUICommander:
- Changes the tab indicator to a
?icon - Shows a prompt overlay with keyboard navigation:
↑/↓to navigate optionsEnterto select- Number keys
1-9for numbered options Escapeto dismiss
- Plays a notification sound (if enabled in Settings → Notifications)
For unrecognized agents, silence-based detection kicks in — if the terminal stops producing output for 10 seconds after a line ending with ?, it’s treated as a potential prompt. User-typed lines ending with ? are suppressed from question detection for 500ms (echo window) to avoid false positives from PTY echo.
Launch Instructions (TUIC Output Markers)
TUICommander generates a launch playbook through the agent’s native instruction channel: Markers, Working with the user, Waiting and long work, Git and worktrees, Process safety, and Children. The Markers module asks agents to place 💬 at the start of a new line for each directly answering sentence, or after a list-item prefix. A marker after prose on the same line is literal text, not an answer marker. The Children module is included only for spawned children; children do not receive follow-up suggestions. MCP initialize instructions retain live discovery, but do not repeat playbook obligations for launch-capable agents. Other clients retain the MCP marker fallback. When mdkb is installed, the launch playbook also carries a fixed “Code search” rule that tells the agent to search with MDKB first; without mdkb it is absent. TUICommander checks once when it writes the launch files (startup, settings change, mdkb install or uninstall).
The Waiting and long work module runs long work in the background and continues ready, non-overlapping work. The agent yields only when a background result blocks its next useful action and no independent work remains, or it needs your answer. A yield reports what is running and what the result unblocks, without a completion claim or follow-up suggestions. The agent uses the launched mechanism’s completion wake, never polling or sleeping to wait. Terminal submissions still send text and Enter together in one call.
The Git and worktrees module routes delegated or parallel work through TUIC
agent action=spawn/launch, not client-native subagents such as Claude Code
Agent/Task. The CC-only cc_agent_hint isolated-task path remains the exception.
Clients without a launch instruction channel receive the delegation rule in MCP
instructions instead. The Children module still forbids further delegation.
| Agent | Channel |
|---|---|
| Claude Code | --append-system-prompt-file <config-dir>/agent-hooks/instructions-claude.md |
| Codex | -c developer_instructions="<text>" (a TOML string) |
| Grok | --rules=<text> |
| OpenCode | environment variable OPENCODE_CONFIG_CONTENT={"instructions":["<file>"]} |
| Goose | goose session --system=<text> |
| pi | --append-system-prompt <file> |
| ego | --append-system @<file> |
Resume launches get the flag too. Headless one-shot forms (claude -p, codex exec, grok -p, goose run, opencode run, pi -p, ego run) and non-session subcommands do not. When you pass the same flag yourself, TUIC does not add a second one.
Open Settings → Agents → Launch instructions to select generated modules. Each supported agent has its own switches. A global off switch is a ceiling: an agent cannot re-enable that module. Turn all launch instructions off suppresses modules and user additions; an empty additions field adds nothing.
Select Add instructions, or Add instructions for {VER} becomes the running TUIC version. Generated updates continue to reach agents with custom additions.
The effective preview uses the selected machine, module switches, additions and marker flags. It stays unavailable while that machine loads or fails; another machine’s preview is never reused. Root previews omit Children. Managed child launches use separate instructions-<agent>-child files so concurrent root launches do not overwrite their instructions.
On the first load after upgrading, TUIC removes exact saved copies of the old marker default (including rendered versions), retains real custom text as additions, and converts legacy empty replacements to explicit off. The migration runs once.
TUIC writes the effective text to <config-dir>/agent-hooks/instructions-<agent>.md (.toml for Codex) at startup, on every agent launch and when you save the agent settings.
Scope: agents that TUIC starts (Run, MCP/HTTP spawns, worktree launches) get the flag. In a TUIC shell on macOS and Linux, TUIC puts a shim directory first on PATH (shell-integration/bin). The shim adds the same flag and runs the next real binary on PATH, so a typed agent, an alias, and a wrapper script that runs the agent by name all get the instructions. The prompt hook of zsh, bash and fish moves the shim directory back to the front of PATH if your shell startup files prepend another directory. OpenCode gets OPENCODE_CONFIG_CONTENT instead, which also reaches an absolute-path launch. These agents have no env var or config file that appends instructions without side effects, so they use the shim: claude, codex, grok, goose, pi and ego. A shim-served agent launched by absolute path, and every typed launch on Windows or WSL, bypasses launch injection. MCP does not restore the playbook for a recognized launch-capable agent. The shim never adds a flag that you already pass. Agent names in the Unix shim directory are hard links to one script, so launchers that canonicalise executable paths retain the agent name. New shell launches replace legacy symlinks atomically. Unchanged installs retain the executable inode; a script update refreshes all agent links. The shim directory must support hard links. If installation fails, TUIC logs the error and does not prepend that directory to the new shell’s PATH.
Independent headless ego advisors
Use ego run - < brief.md > answer.md for a headless stdin prompt. A bare
ego - selects a prompt source, not the headless driver. TUIC does not change
ego retry defaults or add retry flags: explicit headless runs keep their finite
default (zero retries), and caller-supplied --retry N remains unchanged.
On macOS and Linux, the shim isolates ego run and ego session launches whose
stdin or stdout is not a terminal. They receive no implicit parent launch
instructions, attachment grant or TUIC_SESSION. A process boundary also stops
MCP ancestry recovery from binding their bridge to the parent terminal. Explicit
--append-system and --read-only-dir arguments remain unchanged.
Direct terminal launches retain their context. For a deliberately hosted,
redirected peer, supply its valid host identity and TUIC_EGO_HOSTED=1 on that
invocation. The shim consumes this one-launch opt-in; later tools do not inherit
it. The host remains responsible for assigning a distinct peer identity when
appropriate. Administrative commands and ACP keep their existing pass-through
behavior. These rules apply to the Unix PATH shim, not absolute-path launches or
native Windows launches.
Native Hook Instrumentation
With Codex global hooks installed and trusted, native tool start/end events restore Working for the exact terminal session. Native request_user_input hooks provide the question text and clear Input on their matching result, a new prompt, stop, interruption or session end. Native terminal rendering still supplies answer controls. Other tools do not dismiss an open human approval. Codex 0.166.0 does not identify permission ownership in hooks, so TUIC does not consume PermissionRequest; existing human-approval detection stays active. After updating TUIC, update and trust the changed hook definitions in /hooks. Codex SubagentStart/SubagentStop hooks keep a native child roster per terminal (#2635-8052): a lead that stops while children still work stays Working until the last child stops, and the session’s native_children lists them (shared with ego children). Progress Flow draws each live child as a Running column under its terminal; the column goes away when the roster drops the child. A child’s own prompt never moves the lead turn or rebinds Chat to the child transcript. A new lead prompt, interruption, session end or exit clears the roster, so a missing child stop cannot hold later turns; within one turn the five-minute stale-completion backstop bounds it. Grok child hooks are not wired yet.
Claude and Codex status signals are enabled by default and scoped to each TUIC launch. Claude receives an additional --settings <config-dir>/agent-hooks/claude.json; on macOS and Linux, the PATH shim applies this to named launches and resumes, including env CLAUDE_CONFIG_DIR=… claude and script wrappers. The shim consumes the hook-setting environment variable before running an agent, so later tool subprocesses do not inherit this implicit policy; Codex receives -c notify=["<config-dir>/agent-hooks/codex-notify.sh"]. Restored and discovered Claude launches use the same settings, including when the saved command names an absolute executable. Explicit --settings, --settings=…, --bare, administrative commands and the native-status opt-out keep their existing behavior. The Codex adapter emits idle on agent-turn-complete and then chains the user’s configured notify command with the original JSON payload. No global agent configuration is written by this default path.
After a completion hook, decorative terminal animation and redraws keep the session idle. New input and recognized active work can start another turn.
An open interactive selection dialog restores the question badge even when hooks are enabled and another hook cleared it before you answered.
Disable this per agent with Settings → Agents → Native status signals to restore screen-only heuristics. Codex, Gemini, Grok, and OpenCode have a separate, explicit Install hooks globally toggle.
Instead of inferring busy/idle/waiting from terminal output, TUICommander can drive an agent’s status directly from the agent’s own hook system.
When enabled, TUIC writes small shell hooks into the agent’s settings file that emit OSC 7770;state=… on each lifecycle event (busy on prompt/tool start, awaiting on an approval/question prompt, idle on stop). The session state then follows the hooks precisely, and the heuristic question-detection above is suppressed for that agent. Screen and ordinary silence cannot override a protocol-held turn. If its completion signal is lost, a stable Ready screen plus five minutes without PTY output recovers the session and writes a protocol-stale warning.
For OpenCode 2.2.3, update the managed plugin and launch opencode --standalone in the TUIC terminal. This starts a private native server that inherits the terminal. The shared background service cannot attribute its events to one terminal, so the plugin stays inactive there. Native question forms and permission requests set Input; answering or cancelling restores the current execution state without waiting for another tool. Concurrent requests keep Input until each owned wait settles. Execution success, failure, interruption, session deletion and plugin/location shutdown clear the affected waits. Native session and request ids stay separate from the TUIC tab id. The older named-function plugin is reported as outdated and needs an update; it does not load on this CLI.
For Claude, awaiting also covers MCP elicitation — the dialog an MCP server raises to ask you for input (MCP server "…" requests your input, with Accept/Decline). It arrives through Claude’s Elicitation event and is retracted by ElicitationResult; no screen scraping is involved, because that dialog matches none of the question heuristics.
Ownership is safe and reversible. Each managed hook carries a # tuic-managed-hook sentinel; enabling installs only TUIC’s entries and disabling removes only them — your own (and wiz/mdkb) hooks in the same file are never touched. The toggle is the source of truth; the effect applies on the agent’s next launch (hooks are read at startup).
| Agent | Hooks | Status |
|---|---|---|
| Claude | ~/.claude/settings.json | Supported |
| Gemini | ~/.gemini/settings.json | Supported |
| Codex | ~/.codex/hooks.json + ~/.codex/config.toml ([features] hooks = true) | Supported |
| Grok | ~/.grok/hooks/tuic.json (own file) | Supported |
| OpenCode | ~/.config/opencode/plugin/tuic.ts (Bun/TS plugin) | Supported |
| pi | ~/.pi/agent/extensions/tuic.ts (marked extension) | Supported on macOS/Linux; Pi 0.84.2 API recorded |
| Others (Amp, Cursor, Goose, Droid) | — | No TUIC-managed hook system — stays heuristic |
Pi uses Install hooks globally to install one owned extension. If
PI_CODING_AGENT_DIR selects another agent directory in TUIC’s environment,
that directory contains extensions/tuic.ts instead. An unmarked file is never
overwritten or removed. Restart Pi to load a changed extension.
Pi agent and tool callbacks report busy; agent end reports idle. Extension
select, confirm, input, editor and custom dialogs report awaiting
until their promises settle. Answer, rejection, Escape and exceptions all
restore the current run state. Tool activity cannot clear a still-open dialog.
Session replacement and extension shutdown drop old waits. Model selection
alone does not start work. Print and RPC UI methods are not PTY modal owners.
Platform note: On native Windows the generated hooks run the bundled
tuic.exe agent-state <verb> [state]instead of POSIXsh(#2632-97ef). It reads the hook event from stdin (at most 768 KiB; a larger event sends only its coarse state), builds the same OSC 7770 frames, and posts them over the named pipe toPOST /sessions/{TUIC_SESSION}/hook. When no TUIC answers, or the TUIC that owns the pipe does not know the session, the frames go in-band to the console (CONOUT$), which ConPTY delivers unchanged. Posts carry the hook’s process-start monotonic clock, so a late hook cannot revive a settled turn. Codexnotifyrunstuic.exe agent-state codex-notify -- <your notify>and chains your own notify command. Whentuic.exeis not next to the application, or its path holds",%,!,$or a backtick, hooks stay unsupported: hook state returnsunsupported, setters reject changes before any write, and Settings hides the controls. Saved preferences and existing hooks remain intact. Not yet verified on Windows hardware: the shell each agent uses for hook commands (cmdandshaccept the quoted path; PowerShell needs&), and end-to-end latency. ego keeps native PTY OSC signals and its separate ACP path.
Current tool readout
While an agent runs a tool, the status bar agent badge shows the tool name after a dot (for example claude · Bash). The mobile session card and the session details sheet show it as Current tool. The name comes only from verified native metadata of the terminal’s own session: Claude, Codex and Grok hooks, ego terminal events, and the managed Pi extension and OpenCode plugin. TUIC shows only the name, at most 64 characters, and never the tool arguments. When several tools run at the same time, the newest one shows. The end of one tool removes only that tool. A turn end, a cancelled turn, a session end, a shell return or an idle prompt removes all of them. The readout never changes Working, Idle or Input. Gemini and ego AI Chat show no tool readout. After updating TUIC, reinstall the Pi extension and the OpenCode plugin in Settings (they show Outdated) to get their readout.
pi sessions signed in to Claude Pro/Max or ChatGPT (Codex) show that subscription quota in the status bar. The managed Pi extension sends TUIC the quota headers of each model response, never a token or cookie. When the session is idle for a while, TUIC reads the usage endpoint with the pi login in ~/.pi/agent/auth.json (or PI_CODING_AGENT_DIR). The quota appears after the first model response of the session. GitHub Copilot quota is not available yet. Reinstall the Pi extension in Settings after updating TUIC.
ego terminal questions
Question titles exclude preceding diagnostics and working rows. Native single-choice and checkbox questions keep their existing selection behavior. A CLI-enforced command approval exposes the native approval keys; choosing no opens the explanation prompt, where Enter alone refuses the command.
Grok native questions
Grok Ask selectors expose numbered answers and the z free-text action to desktop and mobile. Numbered replies submit immediately. The CLI-enforced command approval also exposes its native numeric options; refusing a command clears the controls. These tool approvals are distinct from a model asking whether it may run a command.
Codex native questions
Codex 0.162.1 queues native questions before showing their options. Use Open Codex question on mobile, or Shift+Left in the terminal. A numbered key answers once; Ctrl+] skips, and Shift+Right returns to the main prompt. Open questions supply the same title and options to desktop and mobile.
Codex /plan questions also export named choices in narrow panes. The native
footer can span three rows, and wrapped descriptions stay separate from answer
labels. An unanswered question keeps Input state through a delayed idle hook;
answering it clears the controls. Only visible native options are exported.
CLI-enforced command approvals are separate from native questions. Their title and numeric controls are available to desktop and mobile; a numeric refusal submits immediately, and Escape cancels.
Codex hook trust
Codex global hook installation uses the installed CLI’s hooks/list and
config/batchWrite APIs. Codex 0.166.0 is verified. An explicit install/update
trusts only exact TUIC definitions, using identities and hashes returned by
Codex, then reads them back. Status checks never grant trust. User hook trust
and unrelated configuration remain unchanged.
Hooks: review in /hooks means that current trust cannot be verified. Open
/hooks in Codex, review the current definitions, and reopen the agent settings.
Missing CLI support, changed definitions, write conflicts and failed readback
never count as installed. The setting targets the host’s CODEX_HOME, or
~/.codex when unset. It verifies the base configuration, not every named
profile; review profile-specific hooks in that profile. Trust review is setup,
not a terminal permission wait. Launch-scoped completion notifications remain
separate and enabled by default.
Codex terminal Chat
Codex terminals offer CLI | Chat after trusted native hooks identify their own conversation. Install or update TUIC’s Codex hooks through the existing hook-instrumentation setting/API, enable native hooks in Codex, and accept Codex’s hook trust prompt before launching a new session. Codex 0.162.1 is verified. The launch-scoped status notification alone cannot enable Chat.
Each tab reads only the rollout whose native session id and cwd match that tab. An ID inferred from the newest file, including a restored resume ID, never enables Chat. Missing/untrusted hooks, unsupported versions, Windows and remote terminals leave Chat unavailable. Session replacement resets the conversation; process exit or return to the shell retracts the binding.
Usage Limit Tracking
For Claude Code, TUICommander detects weekly and session usage limit messages from terminal output:
- Unified agent badge — When Claude is the active agent, the status bar shows a single badge combining the agent icon with usage data. The badge displays rate limit countdowns (when rate-limited), Claude Usage API data (5h/7d utilization percentages), or terminal-detected usage limits, in that priority order.
- Blue: < 70% utilization
- Yellow: 70–95%
- Red (pulsing): >= 96%
- Clicking the badge opens the Claude Usage Dashboard.
The API quota follows the focused Claude session’s CLAUDE_CONFIG_DIR. Switching between Claude sessions using different accounts updates the badge. If the session’s profile or its credentials cannot be read, the badge shows unknown rather than the default account’s quota.
This helps you pace your usage across the week.
Codex session quota
Codex session quota follows the live process’s HOME, CODEX_HOME and selected
profile. For --profile work, TUIC reads <CODEX_HOME>/work.config.toml and passes
its TOML values to codex app-server through -c overrides. Codex 0.166 rejects
--profile for App Server. Codex still loads its base configuration and owns
credential access and token refresh. Before serialization, TUIC resolves Codex’s
path-valued fields against the selected profile file’s directory, including nested
agent, skill, provider-auth, workspace-root and OTEL TLS paths. Absolute paths and
~ home paths keep their meaning. Commands, arguments and unknown fields are not
rebased. An unreadable or invalid selected profile, or an App Server warning that
it discarded the configuration, shows unavailable usage instead of silently
querying the default configuration.
Claude Usage Dashboard
A native feature (not a plugin) that provides detailed analytics for your Claude Code usage. Enable it in Settings > Agents > expand Claude Code > Features > Usage Dashboard.
When enabled, TUICommander polls the Claude API every 5 minutes and shows:
- Rate limits — 5-hour and 7-day utilization bars with reset countdowns. Color-coded: green (OK), yellow (70%+), red (90%+). Enterprise/spend-based plans don’t populate these named buckets — the badge and dashboard fall back to that plan’s own usage figure instead of showing “no data.” Missing usage percentages show as unavailable, not 0%; available credit totals remain visible.
- Usage Over Time — 7-day token usage chart (input vs. output tokens) with hover tooltips.
- Insights — Session count, message counts, input/output/cache token totals.
- Activity heatmap — 52-week GitHub-style heatmap of daily message counts with per-project drill-down on hover.
- Model usage — Breakdown by model (messages, input, output, cache created, cache read).
- Per-project breakdown — All projects ranked by token usage. Click a project to filter the dashboard to that project.
The dashboard opens as a tab in the Activity Center. You can also reach it by clicking the Claude usage badge in the status bar.
When opened from the badge, its rate-limit data uses that session’s credential profile. Sessions with a nonempty ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN show a neutral API key label instead of subscription usage. TUICommander does not read OAuth credentials or call the usage API for these sessions, even when CLAUDE_CONFIG_DIR is set. The transcript-based charts and project statistics currently scan the default Claude projects directory.
If the usage API returns HTTP 429, the badge immediately shows rate-limited, retry HH:MM, using the host’s local time. It does not wait inside the request or send a generating fallback request. The account profile shares a two-to-five-minute cooldown with mobile quota reads; other profiles remain independent. This temporary throttle does not mean the plan lacks usage reporting.
Agent Teams
Agent Teams lets Claude Code spawn teammate agents as TUIC terminal tabs. Enable it in Settings > Agents > Agent Teams.
When enabled, PTY sessions receive the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 environment variable, which unlocks Claude Code’s TeamCreate, TaskCreate, and SendMessage tools. Agent spawning uses direct MCP tool calls (agent spawn) — the earlier it2 shim approach (iTerm2 CLI emulation) is deprecated.
Spawned sessions automatically emit lifecycle events (session-created, session-closed) so they appear as tabs and clean up on exit.
TUICommander Agents vs Codex Internal Subagents
This comparison primarily concerns Codex internal subagents. For substantial or long-running work, prefer agents spawned through TUICommander. Codex coordinates an internal subagent inside the parent conversation and runtime. A TUICommander agent runs in its own managed process and session, with a visible terminal and a stable address that the parent or user can use later.
| Concern | Codex internal subagent | TUICommander agent |
|---|---|---|
| Control | Controlled through the parent conversation | Visible session with explicit status, input, interrupt, close, and kill controls |
| Parent interruption | Its lifecycle remains coupled to the parent runtime | Continues independently after spawn; its terminal and task handle remain available |
| Context | May inherit parent conversation history | Receives only the assigned brief and files it reads |
| Worker output | Final output normally returns directly to the parent context | Terminal output stays outside the parent context until explicitly requested |
| Handoff | Returned through Codex’s internal collaboration mechanism | Worker sends a concise result or blocker through the TUICommander inbox |
| Recovery | Depends on Codex’s internal subagent lifecycle | Parent can reconnect, inspect task state, read the inbox, or resume supported agent sessions |
| User visibility | Usually summarized by the parent | Full terminal and lifecycle state remain observable and controllable |
Each worker performs its own model inference and consumes tokens in its own context. TUICommander does not reduce total model-token usage: MCP calls, briefs, messages, and handoffs also consume coordination tokens. The gain is operational efficiency. The parent can assign a focused context, let the worker continue when the parent turn or window stops, supervise it directly, and retrieve only the result needed for coordination. Unread terminal output does not enter the parent context, but this does not make the worker’s inference cheaper.
The terminal display itself has no model-token cost; it is rendered locally. A provider-wide quota or outage can still affect every agent using that provider. Recovery after a process or application restart depends on the selected agent’s documented session-resume support.
Codex internal subagents remain useful for short, tightly coupled work whose result is needed immediately in the current turn. TUICommander agents are more operationally efficient for parallel work that benefits from independent context, persistent supervision, direct human control, and selective result collection. Claude Code’s native Agent Teams use a separate lifecycle described in Agent Teams.
Session Binding (TUIC_SESSION)
Every terminal tab has a stable UUID that persists across app restarts. This UUID is injected into the PTY shell as the TUIC_SESSION environment variable.
How It Works
- When a terminal tab is created, a UUID is generated via
crypto.randomUUID() - The UUID is saved with the tab and restored when the app restarts
- On PTY creation, the UUID is injected as
TUIC_SESSION=<uuid>in the shell environment - Agents can use
$TUIC_SESSIONfor session-specific operations
Use Cases
Automatic session binding (Claude Code):
Shell integration automatically injects --session-id $TUIC_SESSION into every claude invocation via a shell function wrapper. You don’t need to pass it manually — just type claude and the session is bound to this tab. The wrapper is bypassed when you explicitly pass --session-id, --resume, or --continue.
# These are equivalent — the wrapper handles it transparently:
claude # wrapper adds --session-id $TUIC_SESSION
claude --session-id $TUIC_SESSION # explicit, wrapper bypassed
Claude Code stores the session locally. When you restart TUICommander and switch to this branch, the session resumes automatically via claude --resume <uuid>.
Goose returns to idle after a reply when its ready composer appears, so you can send the next prompt without waiting for stale-state recovery.
Automatic session binding (Goose):
Shell integration injects --name $TUIC_SESSION into goose session and goose run subcommands. The wrapper is bypassed when you explicitly pass --name, -n, --resume, or -r.
# These are equivalent:
goose session "fix the bug" # wrapper adds --name $TUIC_SESSION
goose session --name $TUIC_SESSION "fix the bug" # explicit, wrapper bypassed
Gemini CLI session binding:
TUICommander discovers Gemini’s native session ID from its project-scoped
transcript metadata; TUIC_SESSION is not the Gemini session ID. Current JSONL
and legacy JSON transcripts are supported. Restore verifies the same project
before using gemini --resume <discovered-id>. Discovery remains heuristic when
multiple Gemini tabs use the same project.
Custom scripts that persist state per-tab:
# Use TUIC_SESSION as a stable key for any tab-specific state
echo "Last run: $(date)" > "/tmp/tuic-$TUIC_SESSION.log"
Automatic Resume
When TUICommander restores saved terminals after a restart, only tabs that had an active agent session (agentType set) are restored. Plain shell tabs are discarded and a fresh terminal is spawned instead. For agent tabs, TUICommander checks whether the session file exists on disk before deciding the resume strategy:
Resume command reconstruction removes expired TUIC attachment-directory grants. It resolves the configuration root on both sides, so a native Windows path or a configuration-directory alias does not retain an old grant. User-supplied directory grants stay unchanged.
- Verified session — If the terminal’s saved agent session ID maps to an existing session file (e.g.
~/.claude/projects/…/<uuid>.jsonl), the agent resumes with that agent’s ID-specific command. On Windows, Claude’s project slug replaces the drive colon with a dash:C:\Users\foo\barbecomesC--Users-foo-bar. - No saved session ID — Falls back to the agent’s default resume behavior (e.g.
claude --continuefor the last session) - Saved ID no longer verifies — Refuses automatic resume instead of opening an unrelated last session
The resume command honours the agent’s default run config: TUICommander swaps the binary in the resume command (claude) for the run config’s command (e.g. c2) and appends the run config’s args after the resume flag. So a user with the default run config c2 --model claude-opus-4-6 will resume with c2 --resume <uuid> --model claude-opus-4-6, not claude --resume <uuid>.
UI Agent Spawn
When you spawn an agent via the context menu or command palette, TUICommander automatically uses the tab’s TUIC_SESSION as the --session-id. This ensures the spawned session is bound to the tab and will resume correctly on restart.
Sidebar agent launches wait for shell readiness and submit once, even if the first idle event arrives before the command is prepared or the terminal subscribes. Remote repositories use the owning daemon’s run configurations, environment and launch-scoped hook paths; desktop profile paths are not copied to that machine.
The active-terminal and sidebar agent menus apply the selected run configuration’s environment to that agent launch. The values do not persist in the tab’s shell for later commands. TUIC_SESSION and TUIC_PARENT remain controlled by TUICommander, including differently cased names on Windows. Windows menu launches preserve Unicode characters in environment values and commands.
When the run config’s command is a custom alias, symlink, or wrapper (e.g. c2, c), the foreground-process name no longer matches "claude" in classify_agent. TUICommander compensates by pre-seeding the session’s agent_type from the run config at PTY creation time, so intent/suggest parsing and tab-title binding work from the first output line. The foreground-process detector also falls back to the pre-seeded type whenever it sees a non-shell process it doesn’t recognise, which covers aliases and wrapper scripts without requiring every name to be hardcoded.
The embedded agent loop is gone
Unsafe mode, the per-conversation cost footer, per-phase model overrides and the
cron scheduler all belonged to TUICommander’s own ReAct loop, which was deleted
in #784-0aec. ego runs its own loop over ACP and reaches terminals from
outside, through the session MCP tool family — so none of those controls has a
TUICommander-side equivalent any more. Nothing on this page below is affected:
it describes PTY agents (Claude Code, Codex, Gemini, …), which are unchanged.
Sleep Prevention
When agents are actively working, TUICommander can keep your machine awake:
- Enable in Settings → General → Power Management → Prevent sleep when busy
- Uses the
keepawakesystem integration - Automatically releases when all agents are idle
Environment Flags
Per-agent environment variables can be injected into every new terminal session. Configure in Settings > Agents > expand an agent > Environment Flags.
This is useful for enabling feature flags (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) without manually running export commands. Flags are organized by category with toggle, enum, and number types.
Tips
- Multiple agents on the same repo — Use split panes (
Cmd+\) to run two agents side by side on the same branch - Different agents per branch — Each worktree is independent, so you can run Claude on one branch and Codex on another
- Monitor all at once — Use the Activity Dashboard (
Cmd+Shift+A) to see every terminal’s agent status in one view
ego launch permissions
In Settings > Agents > ego, choose a permission mode and filesystem sandbox for new terminal launches and managed spawns. Use ego configuration leaves that option unchanged. Mode choices are Read-only (plan), Ask (default), Auto-edit (edits), Auto reviewed (auto), and Full access (yolo). Sandbox choices are Read-only (ro) and Workspace writes (workspace). The selected choices replace matching raw launch flags. AI Chat uses separate ACP settings.
Inspect launch instructions
Right-click a terminal and select Inspect Launch Instructions…. Expand a section to read its captured text, source and original UTF-8 byte size. Secrets use the same redaction policy as logs. A queued brief is not yet sent; reopen the inspector after submission to read its updated state.
Capture starts with new managed launches after the backend update. It includes the final brief with TUIC peer context, --system-prompt/--append-system-prompt values, snapshots of explicitly supplied --system-prompt-file/--append-system-prompt-file files, and TUIC MCP initialize responses. File snapshots show the bytes available to TUIC before spawn, not confirmation of what the agent read. Shell-launched agents, older sessions and independently loaded files such as AGENTS.md are Not observable by TUIC. TUIC does not reconstruct them from current settings.
Redacted text is limited to 32 KiB per section and 64 KiB across 16 captured sections. Larger text is labeled truncated; missing, non-regular, non-UTF-8 or over-1-MiB instruction files are labeled unavailable. Byte counts describe the original payload, not the shorter redacted preview. A reconnecting MCP bridge does not add rows: the row MCP initialize instructions holds the newest response and shows how many times it was served and when it was last seen. Served rows never use the 16-section limit, so launch sections stay visible. If the receipt cannot be read, the dialog shows the reason from the backend. Receipts survive a frontend reload, but not session closure or a backend restart.
Answer terminal ego questions on mobile
The startup Trust project files in …? [y/N] prompt also shows Input and the key bar offers Yes and No. Each button sends the corresponding letter followed by Enter, including when the project path wraps across terminal rows.
When ego waits for your answer, the session shows Input. Tap the question icon in the header to read the full question. For a single-choice question, tap one option. For a multiple-choice question, tap the options to toggle their checkmarks, then tap Submit answers. For a free-text question, type your reply in the composer and tap Send. The card floats above the terminal; tap the header icon again to close it. Suggestions from the previous reply stay hidden while an answer is pending.
Ego terminal intents use the same marker grammar as Claude and Codex. A new
intent: description (Title) replaces the Context bar intent and, when intent
titles are enabled and the tab is not user-renamed, the tab title. Soft-wrapped
ego output is not hidden by an earlier submitted prompt during composer repaint.
Settings startup and Ego transport
Assisted configuration uses the published Settings owner contract, not agent-session keystrokes or direct credential-file edits. Ego AI Chat uses ACP; a missing settings owner or ACP capability does not select a PTY fallback. Typed Settings begin_login opens a human-operated terminal using the configured Ego executable/workspace. login_status reads credential presence after termination; an exited command is not proof of authentication. See Settings startup workflows.
Usage in the mobile session menu
Open More session actions to load usage for that session. Claude and Codex show Account quota and reported reset times for the live session profile. These are shared account windows, not the selected model’s session spend. If Claude rate-limits a mobile quota refresh, mobile and desktop reads share a 2–5 minute backoff for that account profile. The menu shows stale cached quota, or Usage not available when no cached quota exists; other profiles are not blocked. Mobile quota reads do not generate messages.
ego shows Session usage from its own durable ledger, with Cost when reported. Terminal usage uses the terminal executable and does not require the AI Chat ego executable setting. API-equivalent estimate is a subscription estimate, not money spent. Unknown/partial costs retain their reasons. Session totals can include more than one model; the model label is ego’s latest admitted model.
The menu shows Usage: loading…, Usage not available, or an explicit stale label as applicable. Model unavailable means no verified model is available; it does not substitute a global default. The old terminal warning percentage is not presented as a fresh usage measurement. Remote sessions read their owning daemon’s usage. No local account is used for a remote PTY.
Ego terminal usage (#2386-6f7c)
Ego terminal usage uses the exact live pid lease and ego usage --json v3 or v4. The shared badge shows observed context tokens, the observed context capacity when present, complete monetary spend, and complete subscription API-price equivalents. Spend and equivalents remain separate. Version 4 also shows explicitly reported remaining requests, tokens, input tokens, output tokens, or USD. Session observations must match the exact provider/model; a current OpenRouter credential balance is labelled openrouter key, not session spend. The hover text includes each limit’s observation time, source, and reported reset. Unknown fields stay hidden; TUIC does not calculate remaining balances from limit minus usage or borrow another provider account. The executable comes from the live terminal, not the AI Chat setting.
Grok completion and permission state
Grok native hooks report cancellation and API failure as idle. Only Notification(permission_prompt) opens a confident permission wait; idle and task-complete notifications do not. Matching tool success, tool failure or denial clears the wait, as do a new prompt, stop, cancellation and session exit. Updating hooks replaces only the TUIC-owned file and takes effect on the next Grok launch.
Claude permission attention
Claude native status hooks mark a tool permission as waiting for input. Ordinary idle notifications do not request attention. Answering, refusing or cancelling the native dialog clears that wait, including responses that produce no post-tool event. Background tool activity preserves an open question, plan or elicitation dialog. New hook registrations apply to new agent launches; global installation preserves user-owned hooks. Native Windows hook availability remains unchanged.
Agent Teams
Agent Teams let Claude Code spawn teammate agents that work in parallel, each in its own TUICommander terminal tab. Teammates share a task list, communicate directly with each other, and coordinate autonomously.
How It Works
TUICommander automatically injects CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 into every PTY session. This unlocks Claude Code’s TeamCreate, TaskCreate, and SendMessage tools. When Claude Code spawns a teammate, TUICommander creates a new terminal tab via its MCP agent spawn tool — no external dependencies required.
Setup
No configuration needed. Agent Teams is enabled by default for all Claude Code sessions launched from TUICommander.
To verify it’s active, check the environment inside any terminal:
echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
# Should print: 1
Usage
Tell Claude Code to create a team using natural language:
Create an agent team with 3 teammates to review this PR:
- One focused on security
- One on performance
- One on test coverage
Claude Code handles team creation, task assignment, and coordination. Each teammate appears as a separate tab in TUICommander’s sidebar.
Navigating Teammates
Claude Code supports two display modes for teammates:
| Mode | How it works | Requirement |
|---|---|---|
| In-process | All teammates run inside the lead’s terminal. Use Shift+Down to cycle between them. | None |
| Split panes | Each teammate gets its own pane. | tmux or iTerm2 |
TUICommander works with both modes. In-process mode is the default and requires no extra setup. With split panes, each teammate appears as a separate TUICommander tab.
Key Controls (In-process Mode)
| Key | Action |
|---|---|
Shift+Down | Cycle to next teammate |
Enter | View a teammate’s session |
Escape | Interrupt a teammate’s current turn |
Ctrl+T | Toggle the shared task list |
What Teams Can Do
- Shared task list — All teammates see task status and self-claim available work
- Direct messaging — Teammates message each other without going through the lead
- Plan approval — Require teammates to plan before implementing; the lead reviews and approves
- Parallel work — Each teammate has its own context window and works independently
Good Use Cases
- Code review — Split review criteria across security, performance, and test coverage reviewers
- Research — Multiple teammates investigate different aspects of a problem simultaneously
- Competing hypotheses — Teammates test different debugging theories in parallel and challenge each other
- New features — Each teammate owns a separate module with no file conflicts
Limitations
Agent Teams is an experimental Claude Code feature. Current limitations:
- No session resumption —
/resumedoes not restore in-process teammates - One team per session — Clean up before starting a new team
- No nested teams — Teammates cannot spawn their own teams
- Token cost — Each teammate is a separate Claude instance; costs scale linearly with team size
- File conflicts — Two teammates editing the same file leads to overwrites; assign distinct files to each
Troubleshooting
Teammates not appearing as tabs:
- Verify the env var is set:
echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSshould print1 - Check that TUICommander’s MCP server is running (status bar shows the MCP icon)
Teammates not spawning at all:
- Claude Code decides whether to create a team based on task complexity. Be explicit: “Create an agent team with N teammates”
- Check Claude Code version: Agent Teams requires a recent version
Too many permission prompts:
- Pre-approve common operations in Claude Code’s permission settings before spawning teammates
Inter-Agent Messaging
TUICommander includes a built-in messaging system that lets agents in different terminal tabs communicate directly. This works alongside (and independently from) Claude Code’s native Agent Teams messaging.
There is no separate swarm action: callers compose the agent and session primitives documented below.
How It Works
Every PTY session gets a stable TUIC_SESSION UUID injected as an environment variable. Agents use this as their identity to register, discover peers, and exchange messages through TUICommander’s MCP agent tool.
Managed workers receive a payload-free terminal notice that tells them to read their inbox. If a worker is busy, TUICommander waits for a safe idle composer before submitting the notice. This includes Claude Code workers with an SSE stream: a channel notification during one turn cannot start a later turn for unread mail. External Claude Code clients without a managed terminal can receive MCP channel notifications (notifications/claude/channel). Every message also lands in a buffered inbox.
A peer explicitly registered as an orchestrator keeps peer results and lifecycle payloads in its inbox. An idle/completed orchestrator receives only one coalesced notice that a message is available and should be read with agent action=inbox ([TUIC] message available …). The same safe notice may start a turn while background work keeps the task state working, but only when the shell is idle, the composer is confirmed ready and empty, and no question is active. Normal mail never injects or steers a genuinely busy or non-quiescent orchestrator. Explicit urgent mail uses the forced-steer flow described below. When that notice would cover nothing but child lifecycle events, it prints them instead ([TUIC] child agent 8c261794 is now idle; child agent 8c261794 exited (exit 0)) and no inbox read is needed — a peer message anywhere in the batch sends you back to the generic notice. An active agent wait receives the mail directly and suppresses that notice.
If writing that payload-free notice has an uncertain outcome, TUICommander retries it at most once after five seconds. A second uncertain result exhausts the wake budget for the whole unread-mail group; later and newly coalesced mail stays inbox-only until a successful agent action=inbox or agent action=wait observation clears the group. Later mail then receives a fresh initial wake and one-retry budget.
What Gets Injected Automatically
TUICommander injects these into every Claude Code PTY session — no manual configuration needed:
| Variable / Flag | Value | Purpose |
|---|---|---|
TUIC_SESSION | Stable UUID per tab | Agent identity for messaging |
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS | 1 | Unlocks TeamCreate/TaskCreate/SendMessage |
--dangerously-load-development-channels server:tuicommander | (CLI flag, agent spawn only) | Enables Claude’s channel capability; managed peer mail still uses the PTY wake |
Script callbacks and the inbound webhook
A managed agent’s launch instructions include this sentence: a script you start can call you back with its data when it ends, through the inbound webhook. The last step of the script posts its result to the agent’s own identity:
curl -sS --fail-with-body --unix-socket "$TUIC_SOCKET" --data-binary @result.txt \
"http://localhost/agent/webhook/$TUIC_SESSION"
On Windows, which has no $TUIC_SOCKET, the sentence names
tuic agent send <session> "<result text>" instead.
Any process can address any agent the same way: the path takes a peer id, registered
name, PTY id or terminal alias. The body arrives as mail from sender webhook and wakes
the agent like other mail, with a payload-free inbox notice; it is never typed into the
terminal. An unknown recipient or a body over 64 KB is refused, and nothing is filed.
See the HTTP API reference for the format.
Messaging Flow
Identity is automatic. The bridge asserts your
$TUIC_SESSIONat connect (x-tuic-sessionheader → server auto-bind), so an agent spawned inside TUICommander is already a registered peer.agent action=registeris only needed to set a friendly name/project, or from a standalone/external session where the env-var route is unavailable. External MCP clients do not need a plain-shell identity tab: callagent action=registerwithouttuic_sessionto receive an MCP-scoped UUID, or supply an explicit UUID when the same identity must be reclaimed after reconnect. Reconnecting under a new UUID? Addreplaces="<old-uuid>"or the old inbox is left behind — nothing links the two identities otherwise, and TUIC never guesses one from a name. The reply reportsmail_migrated, ormail_strandedwith a warning when the old identity still has a live terminal of its own.
Prefer blocking waits over polling.
agent action=waitreturns as soon as new mail arrives;session action=wait session_id=<id> until=idle|exitedblocks on a peer’s lifecycle. Both default to 60 seconds, cap at 300000 ms, and return{met, timed_out}. They are event-driven end to end; the bridge deadline follows the requested wait instead of its ordinary ten-second timeout. A successful agent wait also returns every retained fresh message (up to the 100-message inbox capacity) and a per-recipient logicalnext_sincecursor, so the normal path needs no separate inbox call. Ordinary idle workers receive a terminal notice that points to the inbox. An idle orchestrator instead receives a payload-freeagent action=inboxwake; an active wait suppresses it.
-
Register (optional — sets name/path) — the agent reads its
$TUIC_SESSION:agent action=register tuic_session="$TUIC_SESSION" name="worker-1" path="/path/to/repo" -
Discover peers — Find other agents connected to TUICommander:
agent action=list_peers agent action=list_peers path="/path/to/repo" # filter by repo -
Send a message — Address by the recipient’s
tuic_sessionUUID:agent action=send to="<recipient-tuic-session>" message="PR review done, 3 issues found" agent action=send to="<recipient-tuic-session>" message="Stop the current edit; the requirement changed" urgency="urgent"normalis the default and follows the existing inbox, channel and idle-wake paths. Useurgentwhen the recipient must change course before its next step. Urgent mail keeps an inbox copy but also forces a safe working Claude Code, Codex or ego to stop its turn, then submits the full message after confirmed idle.interruptis an alias. A draft, native dialog, unknown owner or timeout leaves the body inbox-only and returns the failure reason. It never falls back to an ordinary queued notice. The receipt proves input delivery, not model action. -
Wait for and receive messages — one blocking call returns the message bodies:
agent action=waitOmit
since: the server remembers where you got to and resumes from there, so a plainwaitnever re-reads mail you already saw. Pass it only to override —since=0deliberately replays the whole inbox.next_sincecomes back on every response, timeouts included. -
Check inbox directly — useful after a reported lifecycle eviction or if channel push was missed:
agent action=inbox agent action=inbox limit=10 since=1712000000000
agent action=send also returns recipient_state with the recipient’s shell_state and
agent_state when the recipient is a managed PTY. External generated peers omit this field.
Automatic lifecycle notifications contain state only (idle, completed, or exited). They do
not contain the worker’s result. Every worker reports completed output or a real blocker with
agent action=send; use session action=output only to investigate the anomaly where a child did
not send that report.
Channel Push vs Inbox
| Delivery | When | Latency | Requires |
|---|---|---|---|
| Channel push | External Claude client has an SSE stream and no managed PTY | Real-time | --dangerously-load-development-channels server:tuicommander on the recipient’s CC process |
| Managed wake | Ordinary managed peer has a safe idle composer | Immediate or next idle transition | Managed PTY |
| Orchestrator wake | Registered parent is idle/completed and not waiting | Real-time, coalesced | Managed PTY + authoritative lifecycle |
| Forced steer | Managed Claude Code, Codex or ego has a safe composer | Interrupt, confirmed idle, then full message | urgency="urgent" (interrupt is an alias) |
| Inbox buffer | Always | Poll-based | Registration only |
Urgent mail uses the same forced-steer flow as Chat Send now and Compose Steer. It sends Escape, waits up to ten seconds for confirmed idle, then submits the full message, including to an orchestrator. A running Stop hook does not make urgent mail an ordinary busy-queue entry. A draft, native question, unsupported agent or idle timeout leaves the message in the inbox only and returns delivered=false with the reason. There is no fallback Enter or queued wake. An active waiter may already own delivery and needs no interruption. interrupt_payload_and_inbox reports a written input, not proof the model obeyed it. Interrupted tools may leave partial work, and child processes may continue.
Historical native-key probes are retained in src-tauri/src/fixtures/agent_mail/urgent_cli_probe_2026_09_27.json. They show why ordinary busy Enter is not steering: Claude and Codex deferred that input to a tool boundary. Those probes predate the forced-steer contract.
Messages are always buffered in the inbox regardless of whether another delivery path succeeds. The inbox holds up to 100 messages per agent: it evicts safe lifecycle notices before peer mail, and rejects a peer send when only protected peer mail remains. Individual messages are capped at 64 KB.
Using Messaging from a Standalone Claude Code Session
If you run Claude Code outside TUICommander but still want to use TUIC messaging:
-
Connect to TUIC’s MCP server — the MCP channel is a Unix socket (Windows: named pipe), reached through the
tuic-bridgestdio adapter, not a TCP port. TUICommander auto-installs this entry into each supported agent’s config; to add it by hand:{ "mcpServers": { "tuicommander": { "command": "tuic-bridge", "args": [] } } }The bridge finds the socket via
TUIC_SOCKET→mcp.sock→ anymcp-*.sockin the config dir. -
Register identity — omit the UUID for a generated identity scoped to this MCP connection:
agent action=register name="external-reviewer" path="/path/to/repo"Pass
tuic_session="<stable-uuid>"instead when a future reconnect must reclaim the same identity. Registration never creates a PTY. -
Enable channel push (optional, for real-time delivery):
claude --dangerously-load-development-channels server:tuicommander
Messaging vs Claude Code Native SendMessage
| Feature | TUIC Messaging | CC Native SendMessage |
|---|---|---|
| Transport | MCP tool call → server-side routing | File append + polling (~/.claude/teams/) |
| Real-time push | Managed terminal wake or external MCP channel notification | No (polling only) |
| Cross-app | Any MCP client can participate | Claude Code processes only |
| Discovery | list_peers with path filter | Team config file |
| Persistence | In-memory ring buffer (lost on TUIC restart) | Files on disk (survives restart) |
Both systems work simultaneously. Claude Code agents spawned by TUICommander can use either or both.
Deprecated: it2 Shim
Earlier versions of TUICommander used an it2 shell script shim that emulated iTerm2’s CLI to intercept teammate creation. This approach is deprecated — teammate spawning now uses direct MCP tool calls (agent spawn). The shim at ~/.tuicommander/bin/it2 is no longer needed.
Teams across configured remote connections
Desktop MCP peer discovery returns a connection-qualified address for every
remote peer. Use this address for mail instead of assuming a terminal alias is
globally unique. Mail reaches the owning daemon’s native inbox and wake path;
remote replies and remote-to-remote messages pass through the desktop hub.
The mail link grants no remote spawn capability.
Independent result readers
Use agent action=subscribe subscription_id=pump filter=actionable when a
coordinator and a watcher must not consume each other’s mail. Read with
agent action=inbox subscription_id=pump or use the continuous HTTP SSE stream
/agent/subscriptions/pump/events with the bound Mcp-Session-Id header.
Routine lifecycle/idle messages do not wake this reader; peer RESULT/BLOCKED mail,
exits and failures remain actionable. Each batch has a cursor and has_more.
Process it, then call agent action=ack subscription_id=pump cursor=<cursor>.
Unacknowledged batches can replay after interruption, so deduplicate effects by
message ID. Acknowledged mail does not replay after reconnect with the same peer
UUID and subscription ID. The newest 1000 messages per peer survive restart;
missed_count reports matching unacknowledged retention losses. Use a different
subscription ID for each consumer. Legacy inbox readers keep their old cursor.
An ACP consumer can subscribe to tuic://inbox/subscriptions/pump for filtered
resource updates and idle wakes without a model wait loop. See the complete
mail contract
for acknowledgement, retention, reader limits and HTTP transport details.
Typed reports and agent stages
Claude, Codex and ego use the same MCP agent call (including ego over ACP).
The server binds the sender identity. message remains required:
{"action":"send","to":"orchestrator","message":"Implementation ready","report":{"state":"ready"}}
report.state is ready, waiting, blocked, failed, dropped or progress.
waiting requires wait_for: boss, review or dependency. Other states must
omit it. An optional question is allowed only with waiting on boss:
{"action":"send","to":"orchestrator","message":"Choose scope","report":{"state":"waiting","wait_for":"boss","question":{"id":"scope","text":"Which scope?","options":[{"id":"small","label":"Small"},{"id":"full","label":"Full"}],"recommended_option_id":"small"}}}
Question id/text and option id/label must be nonblank; option ids must be unique.
A recommendation must name an option. Invalid reports are rejected before mail
insertion. The combined message UTF-8 bytes and serialized report JSON must fit 64 KiB.
Inbox, wait and durable subscriptions return report as an object. Remote mail
preserves it. Free-text mail remains valid, has no report field and does not
change the latest typed report. Text prefixes are not a typed report protocol.
Session rows (GET /sessions, desktop IPC list_active_sessions, MCP session
list/status and peer inventories) expose report, report_at (host acceptance
Unix milliseconds), report_message_id, stage and stage_reason. Compact
inventories retain these fields. The latest accepted report is retained outside
the bounded inbox, independently of reads, ACK and eviction, for this daemon
lifetime. Historical acceptance time/id remain available after new input;
the report’s stage effect ends when its PTY assignment or submitted-input turn
generation changes. A stage is not a claim that output passed review.
One backend table selects the first matching fact:
| Order | Fact | Stage |
|---|---|---|
| 0 | Closed/exited PTY or no live peer binding | null |
| 1 | Pending initial prompt, failed or uncertain input write | undelivered_input |
| 2 | Current report waits on Boss, or a native question is active | waiting_on_boss |
| 3 | Current report is ready or waits on review | waiting_on_review |
| 4 | Current report is blocked/failed/dropped or waits on a dependency | blocked |
| 5 | Commands are queued | queued |
| 6 | Agent is idle/completed without background work | idle |
| 7 | Agent is working or owns background work | working |
| otherwise | Lifecycle is unknown | null |
progress never selects a stage by itself: native facts select working/idle or
another matching rule. ready means available for review, not approved. An ACP
peer without a PTY receives mail without a fabricated terminal row. No separate
stage mutation action exists.
Agent capabilities
A spawn fixes what the new agent may do. agent action=spawn (and
spawn.capabilities on agent action=launch) takes capabilities, a list of
land, push, tag, children, progress and operator. The operator capability permits the automation cutover, rollback and reconciliation actions. Uncapped roots have it; automation and workflow agents do not. TUIC saves an agent’s fixed set before launch and restores it with the session identity after restart. A legacy session without a record must be relaunched to use operator; desktop actions are unchanged. The local user can edit these files, so they are not a security boundary. A child, that is a spawn with a
parent, gets none of them unless the list names them. A spawn without a parent
and without the list stays uncapped, so hand-opened tabs keep their rights.
childrencoversagent action=spawn,agent action=launchandworkflow action=launch. Plain terminal sessions are not children.progresscovers theprogresstool.land,pushandtaghave no MCP call. TUIC exports the set asTUIC_CAPABILITIES(comma-separated, empty for none) and the repositorypre-pushhook refuses a branch push withoutpushand a tag push withouttag. For a capped agent TUIC also setscore.hooksPath(throughGIT_CONFIG_COUNT/KEY/VALUE) to a TUIC hooks directory, so a push is refused in a repository that has no such hook, also from a login shell such as the Claude Code Bash tool. Each hook there runs the repository’s own hook of the same name. Agitshim first onPATHadds the--no-verifycase, but a login shell can move it behind/usr/bin. Enforcement is advisory and holds only where TUIC starts the agent on macOS or Linux:git push --no-verifyin a login shell, an absolute path to git,git -c core.hooksPath=...,env -u GIT_CONFIG_COUNT, a resumed tab (story 2757) and Windows (repository hook only) are not covered.
TUIC refuses a call outside the set with code: "capability_denied", the
capability it needs and effect: "not_started". The parent gets one
capability_denied mail per refused capability, however often the child
retries. A capped agent can grant a child only capabilities it holds. The set is
written only by the spawn and removed with the PTY: mail, prompts and the
caller’s env (which cannot set TUIC_CAPABILITIES) cannot widen it.
Silent managed workers
One silence rule covers every agent session, managed or opened by hand: an
agent whose stage is working or queued, with no new output, submitted
input, agent hook event or accepted typed report for 30 awake minutes, is
stalled. Session and peer inventories then report stalled: true and
stage: "stalled" (stage_reason: "silent_past_threshold"), the session state
pushed to clients carries stalled: true, and the tab and sidebar dots show it
in the warning color instead of busy. An idle agent never stalls: it waits for
its user, and the stop of a managed child is a child report (below). Any new
activity clears the stall at once.
Only a managed PTY (one with a parent) also gets recovery: one
state_change parent mail with state: "stalled", recovery: "nudged_worker"
and stop, the command that stops the worker. The worker gets one nudge in its
inbox and terminal that asks for a progress, BLOCKED or RESULT report. Recovery
never stops the PTY: silence is not proof of a hang, so the stop is the parent’s
decision.
Activity before the threshold starts a new silence window. Declared waits for
Boss, review or a dependency do not count as silence; neither does a BLOCKED
mail to the parent (until the parent answers). Running background work does not
exempt a worker, since the command can hang; the notice carries background_work: true.
A worker whose latest mail to its parent starts with RESULT gets no nudge; its
parent notice says recovery: "parent_decides". keep_open does not exempt
a worker from stall recovery. An unknown or unbound peer is never a target.
The five-second maintenance sweep evaluates silence; sleep and daemon restarts
do not count toward the window. Exited workers and current terminal reports
remain excluded. Existing idle-close policy still applies to eligible workers.
Set TUIC_AGENT_STALL_MINUTES in the daemon environment to change the threshold;
0 disables alarms and recovery. An absent or invalid value uses 30 minutes. This covers local
managed PTYs; an ACP conversation without a PTY has no silence alarm here.
Child reports at a silent stop
Each parent mail or terminal submission to a managed child opens one report
obligation (the spawn task opens the first). A mail from the child to its parent
that starts with RESULT or BLOCKED, or any typed report except progress,
closes it. When the child stops while the obligation is open, TUIC closes it and
sends the parent one mail with type: "child_report" and subscription kind
report. The same sweep handles Claude, Codex, ego and every other agent:
state | Stop | Delay |
|---|---|---|
ended_without_result | agent idle or completed, no background work, no queued input, no live tuic bg runner and no background command under the agent (one started in the agent’s first minute is not seen) | 15 s without input |
error | the agent refused its turn (agent_state: "error"); detail.reason | 15 s |
blocked_dialog | a question or dialog owns the composer; detail.on is its text | 5 s without input |
dead | the agent exited by itself; detail.exit_code | at exit |
The mail also carries obligation (the opening message or submission id, or
spawn), obligation_open, last_text (the screen above the input box, at
most 2 KB) and resume (agent, the discovered id when known, and
tuic_session). A consecutive turn, a background wake or a queued input inside
the delay sends nothing. An exit that TUIC caused (kill, close, idle close,
suspend) sends no report. Subscribe with filter=report to read only these.
The report shares the maintenance sweep with the stall alarm, so
TUIC_AGENT_STALL_MINUTES=0 does not disable it.
Before that report, TUIC takes one automatic recovery step for each
obligation. At the first ended_without_result stop it reprompts the child to
continue or to send its report. At the first error stop it waits 60 s, then
types one continue into the refused turn when the composer is idle and empty.
The parent gets a child_report notice of the step with recovery: "reprompt"
or "retry", and the obligation stays open. A second stop for the same
obligation sends the report with recovery: "exhausted" and takes no further
step. A report without a step carries recovery: "none". A new parent task
opens a new obligation with its own step.
Mail delivery to an idle child
A parent mail to its idle managed child counts as delivered only when the child
starts a turn: TUIC types the wake and then sees the agent’s own busy edge (a
native busy hook or a Working screen), or the child reads its inbox. The send
result then has turn_check: "pending". When neither happens within 20 s, the
parent gets one mail with type: "delivery_failed" (subscription kind
failure): reason is agent_not_ready or awaiting_input (the wake is still
queued), composer_not_confirmed, no_turn_started or exited; message_id,
pending (unread mails of the child), session_id, tuic_session and name.
The mail stays in the child’s inbox. The failure closes the report obligation
that mail opened, so no child_report and no recovery step follow for it. A child that was busy
when the mail arrived is not checked.
Waiting on you
Plans and Stories shows Waiting on you above the plans: native stories waiting for manual checks and unanswered workflow questions of the open project. Select an entry to open its story, or the Run history of the question’s run, where you answer it. Answered, superseded and cancelled workflow questions disappear through the workflow engine’s inbox projection.
The activity bell notifies each waiting item once, in WAITING ON YOU, for every registered local project. The entry opens the same story or run. It leaves the bell when the story leaves manual checks or the question is answered; a dismissed entry stays dismissed while the item waits. Terminal questions are not waiting items: the terminal’s awaiting badge and the Activity Dashboard row report them.
Agent health
Activity Dashboard shows reported failures, blocked agents, undelivered input and the owning host’s explicit stalled flag. The view does not run its own silence timer. Missing live stage data is shown as unknown. Refresh health retries a failed read. Connected remote sessions supply their host-owned stages.
Automations
The backend Once runtime starts on desktop and headless hosts. It records
precheck decisions before launching the saved agent profile with the literal
prompt. Precheck output is saved in history. It is not added to the prompt unless
the definition opts in with precheck.inject_output: true.
Recurring cron definitions dispatch once per due occurrence and Run Now works for
them. Overlap skip still refuses an occurrence while the previous run is open.
Open the command palette and select Automations. This dialog manages runs on this machine. It does not dispatch onto a different saved remote connection.
Select New automation, enter a name, repository path, select a saved run config and enter a literal prompt. Choose an existing checkout or a new worktree per run with a base branch. The agent uses its run config’s permissions.
Saved run configurations are validated against the same named-profile lookup used
by the runner. Names are case-insensitive; a bare agent type such as claude
is not a saved profile unless a profile has that name. Create, definition
updates and re-enabling reject an unresolved name with a repair hint listing
valid saved profiles. Existing list rows retain invalid definitions, but expose
run_config_error and return next_run_ms: null until repaired. A profile can
be removed after saving; launch checks it again and records a failed run.
On desktop startup, backend validation reports unresolved definitions in the Messages bell without opening Runs. Renaming or deleting a profile triggers the same check as soon as its settings save completes. Fix opens the current definition and focuses the profile picker. Select a saved profile and Save; TUIC never substitutes an agent default or starts a replacement run automatically.
Choose Hourly, Daily, Weekdays or Weekly, set the time controls and select
Apply cadence. The backend converts the cadence to cron. You can also edit a
five-field cron expression directly. For a one-time run, choose Once and
enter Once local time in the named timezone. The backend resolves the
instant; the browser does not convert it through your browser timezone.
A completed one-time occurrence stays visible without another next run. Enter an IANA timezone such as
Europe/Madrid and select Preview schedule. An empty creation zone resolves
to the backend’s local zone. Preview shows backend occurrences in that named
zone. The backend validates schedules and handles daylight-saving transitions.
Set a maximum duration and catch-up grace in seconds. Overlap always skips an occurrence while a previous run remains open. An optional precheck runs before scheduled launches: exit 0 allows the agent to run; other exits skip quietly. Save the definition before running it.
To pass what the precheck found to the agent, enable Include precheck stdout in
the agent prompt in the Precheck section and save. The checkbox starts off and
can be changed for each definition. Turning the precheck off and on resets consent.
The same setting is inject_output: true in the precheck object through the
definition API or MCP, for example:
{"command":"git status --short","timeout_secs":30,"inject_output":true}
The flag defaults to false. A successful scheduled precheck adds stdout before
the unchanged prompt in a <precheck-output untrusted="true"> block, labeled as
data rather than instructions. XML delimiters are escaped. The escaped stdout
payload is capped at 16 KiB on character boundaries; [output truncated] marks
omitted data. Framing and this marker are outside the payload budget. stderr is
never included. Empty stdout, refused checks, absent checks and Run Now bypasses
do not add context. Run history includes precheck_context.injected and bytes
for the prepared launch prompt; bytes counts escaped stdout only, not framing
or the marker. A failed launch can retain this preparation receipt.
Pause stops scheduled launches; Resume enables them. Run now works while paused, bypasses precheck, obeys capacity and overlap, and leaves the scheduled cursor unchanged. A skip receipt is shown as a skip, not as a launch. The list shows next-run time and last status; recent history shows saved run statuses and reasons. Delete asks for confirmation and keeps saved history.
Errors stay visible and failed saves retain the draft. Refresh retries a failed list load. Escape closes the dialog and Tab stays inside it.
Needs-you and failure notices
An agent-created run that ends unknown (for example the agent went idle after a provider error) sends the creator one automation_run_unknown message with run_id, session_id (the session to resume) and last_error (the last output line mentioning an error).
A failed agent-created run also sends one automation_run_failed inbox message
to its recorded creator, including the run id, definition id and failure reason.
This includes failures before a session or task exists and does not depend on
sound preferences. Mail uses the normal payload-free peer wake route. The
recipient must still be registered; acceptance means queued, not read. The
durable owner-channel claim prevents duplicate or restart replay. Definitions
created by HTTP/IPC without a creator still use the bell and configured alerts.
A live transition to needs_you or failed adds a Messages bell item, including
the failure reason even when the creator session is closed. Select
it to open the canonical saved run, including its status, output and owning
session. Editing uses the current saved definition, not the historical run snapshot.
The run stays available after its definition is deleted, with no definition editor. Open owning
session is disabled when the session no longer has a terminal tab.
Native alerts use Notifications → Enabled and the existing Question or Error preference. Web Push also requires its existing service opt-in and a subscribed device. Push opens the owning mobile session when one exists; the message names the saved run. Telegram uses only the owning agent’s existing registration and allowlisted destination. Automations never register an agent or select another conversation on its behalf. Without a matching registration, Telegram remains quiet.
Each run/status/channel is claimed in SQLite before delivery. Repeated awaiting
signals, reconnects and restarts do not replay notices. needs_you is announced
at most once per run per channel, even if that run resumes and blocks again.
Precheck skips, success, unknown, interrupted and timeout outcomes stay in history
without these alerts. A failed or ambiguous send never changes execution status
or saved output. Delivery acceptance does not prove a notification appeared on
a device. The bell is live-only: disconnected clients can miss the event and
must inspect run history; boot never replays historical notices. On non-macOS
desktop platforms native alerts do not support click navigation; use the bell.
The dialog’s backend integration is pending Step 8 (story 1617). Until that API
is installed, requests show a backend error. The injectable adapter is verified
independently; this guide does not claim an installed scheduler is available.
Run history and saved output
The dialog addresses the daemon that owns the active repository when you open it (or this machine for a local repository). Switch repository and reopen to view another owner. Select Runs to view all persisted runs, including runs of deleted automations. The 24h and 7d counts come from the backend and use elapsed UTC windows, not local calendar days. Identical failures (same definition, repository, profile and reason) share one row
with an occurrence count and the newest run as representative. Fix opens the
saved definition’s profile picker, not an editable copy of historical settings.
Deleted definitions retain read-only history. Previous runs and Next runs
page through grouped rows; summaries still count individual runs. Each row retains its original automation name, repository and status. needs_you, unknown and interrupted are distinct; none implies success.
View run focuses the owning live terminal when it is present in this client. If the terminal is absent, suspended, exited or belongs to another daemon, the dialog shows saved stdout/stderr, truncation warnings, the recorded workspace and run configuration. A missing or removed workspace is not recreated. Viewing a run never starts another run. History and output retention remain backend-controlled. New PTY run snapshots save plain text from the session’s existing rendered terminal grid, including retained scrollback and the current screen. Cursor repaints replace earlier spinner frames instead of saving them as output. The newest 256 KiB of UTF-8 text is kept, so a long log does not discard the final report. Plain-command stdout capture is unchanged. Older saved output is not rewritten.
Agents and scripts can use MCP automations or tuic automations '<action JSON>'
for the same operations. List returns definition rows with next-run/last-status
metadata; create/update return the saved definition. Agent-created definitions
record the bound session. See the CLI guide for examples and the HTTP API
Automations table for fields.
In Runs, select Inspect worktree cleanup for a run that created a worktree. Review its recorded path and safety result, then select Remove safe worktree and branch. Cleanup retains the saved report and run provenance. Open runs, existing repositories, dirty or unmerged work, missing required archives, locked worktrees and live sessions are preserved. A stale preview cannot authorize unsafe removal.
Built-in automation templates
New automation drafts offer weekday repository audit, release readiness, daily change review and hourly maintenance review templates. Enter the repository and run config, then select Apply template. Rust supplies the literal prompt, cadence, limits and zone (the backend host’s local IANA zone unless selected). Review and edit the draft, then select Save. Templates start paused; applying one never persists a definition or starts a run. Resume is a separate action. Templates use the existing checkout with no precheck and do not change agent permissions. Recurring cadence previews retain the existing runtime limitations.
Reading the Automations dialog
Search for Automations, scheduler or schedule in the command palette to open the dialog.
Definition cards show a short repository name; hover it for the full path. Daily, weekly, hourly and every-N-minute schedules have plain-language labels. Other expressions retain their cron text. Next-run times come from the backend and use the definition’s timezone.
Use Left/Right or Home/End on the Definitions and Runs tabs. New automation, Refresh and search share a toolbar. The dialog opens the first automation unless a specific definition, run or new draft is already requested. Refresh does not replace unsaved edits.
Ask an agent to schedule a one-time check
A bound agent can call automations once with
{"action":"create","definition":{"name":"Recheck","prompt":"Check again","in_secs":3600,"run_config":"Your saved profile"}}.
The host uses its own clock and this caller’s repository. Specify the actual
saved agent profile in run_config; the host does not infer an account/model
profile from agent type. It returns the saved schedule and next-run timestamp;
no clock or list lookup is needed. Retrying the identical request from the same
caller returns the original reminder without resetting its delay. Supply a new
explicit id to schedule a separate identical reminder. Elapsed delays remain
exact across daylight-saving changes.
Manual configuration edits
You can edit the selected instance’s automations.json with an external editor.
Reads and edits reject incomplete or invalid documents without renaming or
replacing them. If a read overlaps an in-place save, it can report an error;
after the save finishes, Refresh or the next runtime tick reads the completed
file. A genuinely invalid document continues to report an error until you repair
it. TUIC does not replace it with an empty configuration.
Durable event outcomes
The run and list_runs actions return outcome independently of execution
status: decision, pr_url, comment_url, failure_reason and
publication_intent (repository, head, base and issue number). Existing records
without an outcome remain readable. A completed agent is not proof of a
published PR. No comment publisher is added; comment_url remains null.
Before publication, TUIC saves the exact intent and claims it once. It looks up
all PR states for the same repository/head/base before creation and after a lost
response. On restart it reconciles saved pending/unknown intents by lookup only,
even if the worktree was removed. An unavailable, incomplete or empty lookup
leaves publication_unknown with a reason; TUIC never automatically repeats an
uncertain POST. Inspect the repository and saved intent before operator action.
Historical runs from older builds are not automatically republished.
Filtered issues with a valid GitHub issue identity, duplicate admissions,
disabled definitions and capacity refusals retain skipped history rows and
reasons. Repeated observations of the same event/reason update one row’s
updated_ms, not one row per poll. These rows do not consume the admission key;
a later eligible issue or free slot can still be admitted. Invalid issue URLs
have no trusted event identity and are ignored. An empty intake allowlist stays
disabled and performs no evaluations. History retention also applies to these
rows; summaries count rows, not poll observations. The saved run API exposes
outcomes; this change does not add outcome controls to the Automations dialog.
Durable event outcomes
The run and list_runs actions return outcome independently of execution
status: decision, pr_url, comment_url, failure_reason and
publication_intent (repository, head, base and issue number). Existing records
without an outcome remain readable. A completed agent is not proof of a
published PR. No comment publisher is added; comment_url remains null.
Before publication, TUIC saves the exact intent and claims it once. It looks up
all PR states for the same repository/head/base before creation and after a lost
response. On restart it reconciles saved pending/unknown intents by lookup only,
even if the worktree was removed. An unavailable, incomplete or empty lookup
leaves publication_unknown with a reason; TUIC never automatically repeats an
uncertain POST. Inspect the repository and saved intent before operator action.
Historical runs from older builds are not automatically republished.
Filtered issues with a valid GitHub issue identity, duplicate admissions,
disabled definitions and capacity refusals retain skipped history rows and
reasons. Repeated observations of the same event/reason update one row’s
updated_ms, not one row per poll. These rows do not consume the admission key;
a later eligible issue or free slot can still be admitted. Invalid issue URLs
have no trusted event identity and are ignored. An empty intake allowlist stays
disabled and performs no evaluations. History retention also applies to these
rows; summaries count rows, not poll observations. The saved run API exposes
outcomes; this change does not add outcome controls to the Automations dialog.
Returned issues and requirements changes
Intake polls fetch each issue’s body and keep only a digest of its title and body.
A triage verdict is published only if the issue still has that digest; an edit after
admission retires the verdict without writing anything. An issue returned by triage
(rejected or needs input) is admitted once more, as the next generation, when it
still carries the intake label and its digest differs from the returned one.
Removing and re-adding the label alone changes nothing. A triage policy with
needs_input_comment: true posts one question comment for a needs-input verdict;
without it, needs-input still writes nothing.
Close completed run tabs
Set close_on_finish: true on an automation definition, or select Close the run
tab after confirmed completion in the Automations editor. The optional boolean
defaults to false. Create and update accept the same field over MCP, HTTP and
desktop IPC, and store it in automations.json and the immutable run snapshot.
Only a positively confirmed completed run closes its recorded session through
the existing session-close path and tab countdown. Failed, unknown, timed-out,
interrupted and needs_you runs do not trigger this option. Idle is not completion.
The option never removes a worktree or branch and never closes sibling sessions
in an existing checkout. Worktree removal remains a separate explicit
cleanup_worktree action with its existing safety checks.
Timezone selection
The Timezone dropdown filters zone names while open. It includes the names accepted by the backend, including aliases and fixed-offset zones. New automations select the host-local zone returned by schedule preview, not the browser zone. A saved zone outside the list remains selected until you choose another zone.
Project Progress
Progress answers one question: what happened in this terminal while I was not watching?
It is a journal. Entries are appended, never edited. You read it, and you delete what you do not want to keep. There is nothing else to operate.
What lands in the journal
Five kinds of entry.
| Kind | Written by | Meaning |
|---|---|---|
done | the agent | The work an intent: announced is finished. |
blocked | the agent | The agent stops and waits for you, because it cannot continue without you. |
intent | TUICommander | The agent said what it was starting. Recorded from its intent: marker. |
delegated | TUICommander | The agent started another agent with agent action=spawn. The text is the task it handed over. |
message | TUICommander | The agent sent another agent a message with agent action=send. |
A delegated or message entry keeps its text redacted and cut to 500
characters. Status mail that TUICommander sends on an agent’s behalf is not
recorded.
intent is the reliability floor. An agent’s obligation to report sits in the
initialize blob it read hours ago, but its intent: marker fires at the start
of every task — so even an agent that never calls the tool leaves a trail of
what it set out to do. An agent cannot write an intent entry itself; the
reporting tool refuses that kind.
TUI agents can redraw an intent one word at a time. Progress waits for the completed line or turn boundary before saving it, so a growing preview appears as one entry rather than a series of partial entries. The journal redacts secrets from intents and agent reports before writing them. Long intents keep their full terminal event, while the stored note is shortened to 500 characters after redaction.
How an agent reports
The MCP progress tool is for root agents that report to you. Managed child
agents send their final RESULT or BLOCKED report to the parent agent with
agent action=send. A child that calls progress receives an error with its
parent’s address; it does not create a journal outcome, notification, or waiting
badge. Host-observed intents and agent mail can still appear in the journal.
The MCP progress tool takes three fields.
| Field | Required | Limit | Meaning |
|---|---|---|---|
type | yes | done or blocked | The kind of entry |
text | yes | 500 characters | One standalone sentence |
step | no | 80 characters | What the entry belongs to |
{"type": "done", "text": "OpenRouter applications can now be identified.", "step": "Shadow AI Detection"}
A blocked report marks the agent’s tab as waiting for your answer. The mark
clears when you reply in the terminal, or when the same terminal later reports
done or starts another agent. A progress report never clears a question that
the agent shows on its screen, such as an approval dialog.
TUICommander adds the project, the time, the agent’s name and the source PTY when it can identify one. The agent does not supply them.
For a repository on a connected remote machine, Progress commands run on that
machine. Its new entries appear in the local desktop and browser views through
the mirrored progress-recorded event.
The receipt is {"id": <n>} and nothing more. Each call appends one entry: the
journal does not deduplicate agent reports, because an agent that reported the
same step twice did the work twice, and only you can decide what that means.
Intents are the exception. TUICommander reads them off the screen, and a repaint
of the same intent: line is not a new intent, so a repeat of the PTY’s
newest intent — same text, same agent — returns that entry instead of adding one.
step is a free-text label, not a registered object. Nothing has to be created
in advance, and two agents writing the same label are simply two entries with
the same label.
Reading it
Open the Progress dialog from the command palette (progress), with
Cmd/Ctrl+Shift+P, or from Terminal Progress in the toolbar bell. The bell
entry remains available when there are no unread updates; its badge counts
entries that arrived since you last opened the dialog.
An outcome toast’s Go to repo action also opens the reporting terminal
in its workspace when that terminal is still open. If it has closed, the
action selects a surviving terminal in the repository’s active workspace, preferring
the last active terminal. If none remains, it shows the empty terminal area.
It never keeps another repository’s Session Chat or composer active.
Clicking the toast body closes it without changing the current repository or
terminal. Use Go to repo when you want to navigate.
The dialog opens on the active PTY, newest first. The selector switches to another PTY in the project or All repo, which combines their histories. List opens with the newest 100 entries or fewer. Scroll to Load older to append the next page. Changing the project, terminal or Blocked only filter starts again at the newest page. A live update or deletion also refreshes the newest page. Older-page failures keep the entries already loaded and can be retried. The same paging applies on desktop and mobile. The mobile header identifies the project in its project selector, without a second project-name subtitle. If the project selector is unavailable, the subtitle identifies the selected project instead. In the mobile Progress tab, a long entry initially shows about four lines; tap More to read it all and Less to collapse it again. Closed PTYs with saved entries remain selectable. A PTY with no entries has an empty view; it does not inherit another PTY’s work. Entries recorded before terminal identity was stored, and direct local reports with no PTY binding, appear in All repo as Terminal unknown. They are never assigned by guess.
Each PTY and All repo has its own last-visit divider. The divider stays fixed while you read a view; switching views loads that view’s mark. Closing the dialog marks every view you visited during that opening.
On desktop, blocked entries are red and intent entries are muted, because
they describe what an agent started rather than a result. Mobile keeps summary
text in the primary foreground, with status colour in the icon and label. A checkbox narrows the list to blocked
entries only. A row can be deleted, and deletion is permanent.
On a phone, Progress defaults to Started (intent), Done, and Blocked entries. The backend filters before paging, so messages do not leave short pages. Open Filters to select a terminal, show only blocked entries, or include Messages and delegations. Flow keeps all hand-offs regardless of the list filter. Each card shows the status, time, regular-weight summary and one agent identity. Entry actions opens the step, terminal, recipient and Delete action. Long summaries retain More/Less, and Load older reads the next page.
The Flow view
List | Flow in the dialog header switches to a sequence diagram of the same journal. Each terminal is a column, and so is each Claude subagent of an open terminal. A Codex or ego terminal adds a Running column for each native child it reports live; that column has no arrows and goes away when the child stops or the lead’s turn is cleared. Rows run from oldest at the top to newest at the bottom; there is no time scale.
- A delegation is an arrow from the parent to the child, labelled with the task.
- A child’s
done(green) orblocked(red) is an arrow back to its parent. - A message is an arrow from sender to recipient.
- A subagent’s task (dashed) and its final report are arrows between it and its terminal.
- An
intentis a muted note on its own column, and the newest one is also shown under the column’s name.
Click a label to read all of it. A journal text opens in place; a subagent’s full prompt or report is fetched when you click, with secrets redacted. All repo shows every terminal. One terminal shows itself, the terminal that started it, and the terminals it started. A closed terminal keeps its column, but its subagents disappear with it, because TUICommander can only find their transcripts while the agent runs.
There is no export, no pause, no clear and no correction. An entry is appended once, and it is either there or deleted.
Muting popups
Select Mute on a completion popup to hide completion popups for the current app session, across all repositories and terminals. Existing and queued completion cards close too. Entries are still collected, counted in Terminal Progress, and shown in the journal. Open Terminal Progress to see the muted state and select Unmute. The next completion report can show a popup again; old reports are not replayed. Restarting the app also restores popups. In a browser, the mute belongs to that page and resets on reload; it is not saved or shared with other clients.
Blocked reports keep their warning popup, because the agent is waiting for your answer. Muting completion cards does not change collection settings or native OS notification preferences.
Turning it off
Settings → Agents → Collect project progress turns collection off for every
agent. The progress tool then disappears from every agent’s tool list, and no
intent: marker is recorded.
Each agent also has its own Collect progress toggle in its expanded settings card. Off there keeps that one agent out of the journal while the rest keep reporting. The global switch wins: off globally means off everywhere.
Where it is stored
One SQLite database, progress.sqlite3, in TUICommander’s configuration
directory, with the project and nullable PTY ID as columns. Nothing is written inside your
repositories — no .tuic directory, nothing for Git to ignore, nothing for a
file watcher to react to.
A worktree’s entries are filed under its parent project, so switching between a repository and its worktrees shows one history rather than several. A linked checkout registered as a separate repository still shares that history when its workspace has no explicit parent project. A registered submodule keeps its own checkout’s history; its Git administration directory is not a project owner.
An agent running in a directory that belongs to no registered repository writes nothing. There is no project to file the entry under, and the repository you happen to be looking at is not the answer.
Flow refreshes cache subagent metadata by modification time and file size. Unchanged metadata is not reopened; transcript byte cursors continue to read appended complete rows. Metadata and transcript caches expire after ten minutes without use.
Progress reporting evaluation
Historical. This measurement was taken against the first Progress design — four event kinds, workstreams, pause/resume and
repo’s nineprogress_*actions. The 2026-09-14 revision ofplans/project-progress.mdreplaced all of that with one append-only journal, so the conditions below no longer describe any shipped surface. The finding that survived the rewrite and shaped it is the one about where the instruction lives: a tool description says what a tool does, never that you must call it, and 39 repositories recorded zero entries under the description-only condition. The obligation now sits ininitializeand is imperative. The numbers are kept as a record, not as a spec.
This page records a measured comparison of the two ways to instrument an agent for Project Progress:
- Condition A — short default. Only the shipped
progresstool description and its JSON schema (src-tauri/src/mcp_http/mcp_transport.rs:1138). This is what every agent receives with no extra configuration. - Condition B — optional prompt. The same tool description and schema, plus the optional instruction block from the user guide.
The two conditions differ only in that block.
Method
| Item | Value |
|---|---|
| Date | 2026-09-13 |
| Model | Claude Sonnet 5 (claude-sonnet-5) |
| Settings | Default sampling. No tool execution. One turn for each condition. |
| Tool inventory | progress, ui (toast, confirm), repo with its nine progress_* actions |
| Scenarios | Seven, given in the same order to both conditions, as one continuous session on one project |
| Output | For each scenario: the calls, and a one-sentence reason |
The model declared its calls; it did not execute them. Therefore this evaluation measures the reporting choice, not the transport. It is a small qualitative sample, not production telemetry. TUICommander collects no telemetry for this purpose.
The scenarios are: a capability achievement (S1), an architecture decision (S2),
a changed approach after a discovery (S3), a partial validation (S4), a
worker-only conflict (S5), a genuine project blocker (S6), and a completed
objective whose receipt reports paused (S7).
Result
| Measure | A: short default | B: optional prompt |
|---|---|---|
progress calls | 5 | 5 |
Duplicate ui.toast calls for the same event | 2 | 0 |
| Extra discovery or history calls | 1 | 0 |
| Missed meaningful events (S1–S4, S6) | 0 | 0 |
| Irrelevant events reported (S5) | 0 | 0 |
| Claims of unverified scope | 0 | 0 |
| Uncertainty kept in the wording | S4 | S4 |
Both conditions found every meaningful event and neither reported the worker-only conflict. The differences are in the type, in the noise, and in the answer to a paused receipt.
What each scenario showed
| Scenario | A: short default | B: optional prompt |
|---|---|---|
| S1 capability | done for a capability that was verified | milestone, with the verification named |
| S2 decision | milestone | milestone, and it says that nothing is built yet |
| S3 changed approach | milestone | milestone |
| S4 partial validation | milestone, Windows named as untested | milestone, Windows named as untested |
| S5 worker-only conflict | no call | no call |
| S6 project blocker | blocked, and a ui.toast for the same event | blocked only |
| S7 paused receipt | a repo progress_status lookup and a ui.toast that called the paused state an anomaly | no further call |
Findings
-
The short default is sufficient to find the right events. With no extra prompt, the model reported all five meaningful outcomes and skipped the worker-only conflict. The
Started/done apply to objectives, not agent taskssentence in the tool description carries that distinction on its own. -
The short default over-scopes
done. In S1 it closed the whole workstream for one verified capability.donesets every active blocker of that workstream inactive (src-tauri/src/progress/store.rs:1088), and a latermilestonekeeps a done workstream done (src-tauri/src/progress/store.rs:1082). A prematuredonetherefore hides a blocker and stops the workstream from moving again until a person sets its state. The optional prompt gives the correctmilestone. This is the clearest reason to use the optional prompt. -
The short default duplicates the toast. The tool description already says
Persists and shows a toast, but in S6 and S7 the model added aui.toastfor the same event. The optional prompt is explicit and removed both. -
The short default does not know what a
pausedreceipt means. In S7 it treatedpausedas a contradiction, made aprogress_statuslookup, and raised a warning. It did not retry and it did not resume, so the failure is noise and not a policy breach. The optional prompt stopped after the receipt. -
Both conditions kept honest uncertainty. Neither claimed Windows support in S4, and neither claimed completion of scope that was not verified. The
Outcome, not implementation.description ofsummaryis enough for that.
Recommendation
Keep the short default as it is. It reports the right events at the lowest instruction cost, and its three faults are noise rather than lost or false history.
Add the optional prompt when the correct workstream state matters — that is, when you use the Blockers and Completed views to steer work. It removed the type error, the duplicate toasts, and the extra lookups in this sample.
The optional prompt stays out of the default payload for that reason: it buys precision that not every project needs, at a cost that every project would pay.
AI Chat
While an agent works, Chat shows a breathing dot and ring in the theme accent color beside Working…. Desktop and mobile share this indicator. With reduced motion enabled, the dot is static and the ring is hidden. The indicator disappears when the turn ends; provider retry messages take its place while a request waits to retry.
The open AI Chat conversation follows across desktop, phone and tablet connected to the same host. Open or select a conversation on either device to show it on the others. The last selection saved by the host wins. A device that was offline reads the current selection when it reconnects. This does not change a session header’s CLI | Chat choice: that view stays per device. Drafts, tab layout and repository pins also stay local.
On desktop, AI Chat and session Chat share the same 14px default reading scale. Terminal zoom in, zoom out and reset also update AI Chat using the active terminal’s zoom step. With no active terminal, AI Chat uses its default size. Font family, line height, weight and colors do not change when you switch between the two Chat views. Mobile keeps its device-local Chat font preference.
Use ⋯ → Delete conversation… to delete saved conversations. Each row has a trash button. Confirm the conversation name before deletion; this permanently removes its history and closes its open tab. If ego refuses deletion (for example, while the conversation is running), the conversation stays and the error is shown. The list offers deletion only when ego advertises the ACP delete capability. If you select another conversation while deletion cleanup is pending, that selection stays active.
AI Chat is a conversation with ego, which TUICommander launches and speaks to over ACP. TUICommander is the environment — terminals, repositories, the MCP server — and ego is the intelligence. TUICommander keeps no provider, no API key, no tool loop and no sandbox of its own.
Before it can talk
- Turn on Experimental Features in
Settings > General. The panel is behind it and there is no separate AI Chat switch. - Set ego executable in
Settings > General(Install latest downloads and selects the latest ego release; Select… opens a file picker). While it is empty, ACP is not configured: the panel explains why it is inactive and offers Configure ego, which opens the ego section in General. UseSettings > AI Chatto log in to a provider and select the default model (ego config set model). Saving the executable enables the composer immediately, without restarting TUICommander. If the panel is detached, return to its window after saving; it refreshes the settings on focus. - Optionally set ego profile in
Settings > Generalto select a profile from ego’s user configuration. An empty value leaves ego’s usual profile selection in effect. TUICommander passes only the name at launch; it does not send profile rules insession/new.
A repository can select an ego profile with "ego_profile": "team" in its
.tuic.json. For that conversation’s workspace, TUIC sends the selected name and
the explicit machine profile from Settings as ceilingProfile. Ego restricts mode,
sandbox and perimeter to that ceiling and returns warnings, shown in AI Chat’s
existing warning notices. The repository cannot raise the machine policy.
A repo selection requires an explicit machine profile and an ego build that
acknowledges the ceiling. Without a repo selection, launch behavior is unchanged.
The desktop composer uses one compact card. Its header shows Repository · name and an independent repository pin. The document button on the right parks the draft; its tooltip offers restore or swap when a draft is parked. The blue play button sends while idle and queues while ego is busy. Stop remains beside the input during a running turn. The desktop input grows with the draft. Stop and Send keep their fixed control size and align to its bottom edge. The header, input row and footer use the same content edges.
Pasting an image starts ego when needed before checking image support. Finder image copies attach the image rather than its filename; mixed clipboard data with substantive text pastes as text, as in Ideas and terminal Compose. An empty text clipboard flavor does not suppress an available image.
While ego waits to retry a provider request, AI Chat shows the cause, attempt number and a live countdown. The countdown starts when the update arrives and ends at retrying now. Recovery removes the line; a final failure replaces it with the error. The message actions button beside a user message stays on one line.
With the transcript focused, Cmd/Ctrl+K clears only its local view. A notification confirms that saved history and agent context are unchanged; reopening the conversation restores its history. These clear actions are local and synchronous, not requests to erase an ego session.
Click an empty part of AI Chat or its transcript to focus the message composer. Clicked controls keep their own focus. Selecting transcript text keeps the selection for copying; typing while a chat control or selection has focus does not send characters to a terminal.
Slash commands
Start a draft with / to see the commands available in the selected conversation.
Type a command name to filter the list. Each agent command shows its description
and input hint. Use Up/Down and Tab or Enter to complete a name, or click a row.
Completion does not submit it. Add arguments and press Enter or Send to run it.
Escape closes the list without stopping a turn.
Agent commands come from ACP available_commands_update and are sent as
/<name> <arguments>. The latest offer replaces the previous list, including an
empty offer. Commands from another conversation do not enter this list.
TUICommander handles these actions locally instead of sending them to the model:
| Command | Action |
|---|---|
/new | Start a new conversation with the existing New action. |
/clear | Clear this composer’s text and attachments. An inline status confirms that history and agent context are unchanged. |
/quit, /q | Stop the current AI Chat connection through the existing stop action. Saved history remains. Other tabs on that connection also disconnect. |
/usage | Show the context usage and cost already reported for this conversation. |
/compact | Run the same action as Compact context. Available only when advertised; wait for the turn to finish. |
/fork | Fork into a new tab. While busy, use the last successful completed turn observed on this connection; requires message-point fork support. |
/pause, /resume | Run the advertised pause/resume controls in their applicable turn state. |
Host actions do not accept arguments or attachments, except /clear, which
removes attachments. Unsupported commands, including /name and /retry, stay
in the composer with an inline not available in AI Chat explanation and a
list of available names. A leading path token with another /, such as
/Users/x/file.ts or /tmp/error.log, is sent as prompt text unless it matches
an advertised command name. Bare names such as /retry remain command attempts;
write /tmp/ with its trailing slash when referring to a top-level directory.
Nothing is sent silently. Open a conversation with
New or /new to receive its agent command offer.
Automatic context compaction
When ego reports an exhausted context and supports compaction, AI Chat shows Compacting conversation, opens the compacted continuation and sends the original prompt again once. Text, images, file references and repository context stay the same. Conversation compacted confirms that the continuation opened. A compaction or load failure stops recovery and shows the error. If the repeated prompt exhausts context again, AI Chat stops instead of compacting in a loop. The manual Compact action uses the same continuation path. The continuation replaces the compacted conversation in its own tab and keeps that tab’s repository pin; compaction never opens a second tab. A phone or browser that follows the desktop selection replaces the same tab. Switching conversations while compaction is pending keeps your newer selection and prevents an automatic replay into it. A different conversation can still send while compaction is pending. Its own manual or automatic compaction waits for the first operation, then runs only if that conversation is still selected. In the compacting conversation, Send or Queue leaves your draft and attachments in the composer until compaction finishes; submit them again when ready.
Compact panel controls
The header contains the conversation title picker, New, ⋯, and window controls. The tab strip appears only when two or more tabs are open. ⋯ contains labelled session settings, pause/resume, compact, fork, new-conversation options, and deletion actions. Capability and busy-state restrictions still apply.
Changing Session settings → Model updates the current conversation in place. It does not reconnect ego or create a conversation, and the transcript stays visible. After ego confirms the option, the next turn uses that model. Settings → AI Chat → Default model is different: it changes the default for new ego runs only. An open conversation keeps its selected model; use Session settings to change it.
The footer shows context occupancy, used/window tokens and approximate free tokens when ego publishes usage. It also keeps any reported cost. The model, reasoning and permission summary stays on the right and opens Session settings. Repository pinning stays in the card header. Process titles and tool disclosures share one line; failed groups and calls stay collapsed until you open them, with a red dot and Failed label. Suggested replies appear only under the latest answer. Loaded history does not show execution durations measured from the view mount.
Tables
AI Chat keeps short fields and headers on one line. Longer text uses the remaining space. Tables with multiple long columns use the approved wide layout; the first column stays visible while you scroll. A scroll hint appears only when the table is wider than its viewport. Priority values use compact badges.
Each table has Markdown, Copy as Markdown, and Open as document actions. Markdown toggles the original source, including inline formatting and escaped pipes; Copy uses that source in either view. Open creates a read-only TUIC Markdown tab. In a detached AI Chat window, the document opens in the main window. On mobile, it opens a document view with Back to Chat. Other Markdown documents and terminal transcripts retain their existing layout.
Opening it
Cmd+Alt+A (macOS) / Ctrl+Alt+A toggles the panel; so do the status-bar
button and the command palette. The detach control moves it into its own window,
and the main window shows the Bring back placeholder. Drag the left edge to
resize — the width applies for the session and is not persisted.
Opening the configured panel automatically connects ego and restores the selected
conversation. With no saved conversation, it opens a new one without sending a
message. Terminal input remains available while it connects. Switching repositories
does not start another agent. A failed connection stays visible for explicit Retry;
Retry starts the connection and shows its connecting state without requiring Send.
When ego reports no model: pass --model … (no provider or model configured), the failed turn shows
Set up provider and model, which opens Settings > AI Chat for provider login and model selection.
TUIC collects no credentials there.
It does not retry in a loop. Stopping ego keeps the selected transcript visible.
Reopening the panel, or sending another message, reconnects the same conversation.
Mobile offers the Chat tab only when the host has a configured ego executable, using the same availability predicate as desktop. Host settings changes update the tab without reloading. Removing ego configuration returns an open Chat view to Sessions; unavailable saved Chat links also stay on Sessions.
On the mobile PWA, Chat is the second tab, after the default Sessions tab, and opens without choosing a repository. It uses the same workspace root and saved sessions as desktop. The composer shares the session input styling, auto-grow, right-side attachment icon and round Send button. Enter sends; Shift+Enter inserts a new line. Long transcript content wraps, while tables scroll inside their own block. A repository in a push link is sent with a message as context, not used as the chat root. The conversation picker shows the titles of saved sessions; choose one to load its history, or tap New. Messages, collapsed tool activity and pending permission or form cards use the same ACP stream as desktop. Tap a file link in the transcript to open it in Files. A directory link opens that directory in Files. Links use the AI Chat workspace as their base. Saved tabs are attached before a message is sent, including when Chat is reopened after switching mobile tabs. If ego no longer has a saved conversation, Chat opens a fresh one automatically and removes only the stale local tab. Other load failures remain visible for explicit retry; they do not replace history. If the connection drops, the client resumes from its last received event. A missing part of the journal is shown as a gap with a Recover action.
When ego requests permission or a form response, a subscribed phone receives one push linking to that conversation in mobile Chat if the desktop is unfocused or idle. Answering on desktop before the notice is delivered suppresses the alert. Repeated requests in one conversation share a 30-second push limit. Activity updates do not alert the phone.
What it is bound to
One chat for the whole app, never a terminal. Every conversation works
across all your repositories: ego runs in ~/Gits, and the repository on screen
is sent with each message as context — a hint, never a limit on what ego may
reach. The header names that repository. Switching repository keeps the same
tabs and the same conversation, and starts or loads nothing.
If desktop and mobile open the chat together, they attach to the same running ego.
ego connects when you open the panel. Sending after a stop, clicking +, or selecting a saved tab also connects it when needed. There is one ego for the app: a reloaded window or the phone gets the one already running, and quitting TUICommander ends it. New chat tab in the tab bar starts another conversation; the conversation picker lists previous conversations by title, newest first. Selecting one loads its history. The open tabs and the selected tab are restored after restarting TUICommander, and their history is replayed when ego starts. Selecting a saved tab connects and loads it without sending a message. The panel shows Connecting conversation… while it attaches, or the failure reason and Retry if it cannot open the conversation. Reopening the panel on an existing connection also attaches the selected saved tab. If ego no longer has that conversation, Chat opens a fresh one automatically, without requiring a message or Retry. Other load failures remain visible. Opening a new chat leaves that failure behind, including when its connection is still pending. A saved conversation that finishes loading later does not switch you away from the new chat.
The saved-conversation list loads separately from the active chat. You can keep sending while the list is slow or unavailable. A missing background tab does not fail the selected conversation; its refusal is handled when that tab is selected.
The panel has chat tabs for parallel conversations.
Click + or press Cmd+T (Ctrl+T on Windows/Linux) while the panel has
focus to start another ACP session; in browser mode use Cmd/Ctrl+Alt+T so the
browser keeps its own new-tab shortcut. New chat opens a fresh conversation
without first loading the saved selection. A saved greeting or title does not
become the new tab’s name, and an unavailable saved conversation cannot block it.
Click a tab to switch, or close it to
remove it from the panel. Closing a chat tab does not delete ego’s conversation:
the conversation picker can reopen it. Each tab keeps its own transcript and
unsent composer draft. Open tabs and the selected tab return when the panel is
hidden and shown or detached into its own window; the detached view replays
their histories from ego.
Tabs and the picker use the conversation title, its first prompt, or its latest activity time. A conversation without these details shows Untitled conversation; its session ID is available in the tooltip. The model/mode row remains visible with pending values until the selected session publishes its options.
The header and conversation picker stay on the selected transcript when the saved-conversation list loads or refreshes, even when other sessions are attached. When ego updates the session title, the panel header and conversation picker show the new title. During a turn, the footer shows context-window use as a percentage and shows the cumulative cost when ego reports one.
ego reaches terminals and repositories by calling TUICommander’s own MCP
server, served on the ACP connection itself — no bridge process in between. The
entry for it is built by TUICommander, not by whoever opened the session, so a
conversation can never be pointed at some other endpoint, and a second copy
started with TUIC_APP_INSTANCE=<id> serves its own terminals and repositories.
ego also reads a workspace summary and its inbox from that server, and new mail
wakes an idle ego with a short notice.
During a turn
Select text in user messages, answers, code blocks, and tool output and use
Cmd/Ctrl+C to copy it. The ⋯ message actions button appears when a message is
hovered or has keyboard focus, and always on touch screens. Its menu has Copy message
(the whole raw message, including fenced code, through the same clipboard adapter as the
terminal), Show raw Markdown / Show formatted message (answers only; a per-message
view that does not change what Copy copies) and Quote reply (every chat surface, one shared
flow: AI Chat and Terminal Chat on desktop and mobile append the message as a > quote to the
composer draft and focus it; it never sends).
AI Chat answers with a native source message ID also offer Thumbs up, Thumbs down, Heart, Celebrate, and Comment on message in the same menu. These are conversational reactions, not correct/wrong votes, model evaluations, or permission to execute actions. Adding a reaction sends an ordinary user turn to that conversation, with its exact message ID and a readable source excerpt (up to 4000 characters). Click its visible mark, or select the same item in the menu, to remove it; removal sends another conversational turn. You can use more than one reaction. The backend saves accepted marks, so they survive reopening and agree between desktop and phone. A mark means the host accepted the action, not that the model read or understood it. Busy conversations use their existing prompt queue without interruption. Cancelling a queued prompt does not undo a mark; send a removal separately. Removal cannot erase context that already reached the agent.
Comments use a separate field and do not replace the composer draft. Cancel sends nothing. An unavailable/offline conversation shows an error and leaves the mark unchanged; reconnect before retrying. If the host accepted the action but could not save its mark, the error says Do not resend: the action already reached the conversation. Desktop and browser menus show the error message. The action never starts a replacement conversation or falls back to a terminal. Messages without a native ID have Copy and Quote reply but no reactions or comments. The current streaming answer cannot receive reactions. Terminal Chat keeps its existing Approve response and Disapprove response draft actions; these are not AI Chat reactions.
Use Up/Down, Home/End, Enter or Space
and Escape in the menu; focus returns to ⋯. Answers have no separate code-block
Copy button. Fork stays in the row below its answer
and does not overlap the next message. Web links open in the
system browser; file links and plain source paths are resolved by the backend.
Files open in TUICommander’s viewer or editor, while directories open in the
file browser, including when AI Chat is detached.
With focus in the transcript, Cmd/Ctrl+A selects that transcript,
Cmd/Ctrl+F opens its search, and Cmd/Ctrl+K clears the visible history of
the current tab. Search matches displayed prose with collapsed whitespace; code blocks retain literal whitespace. Clearing the view does not delete ego’s saved conversation.
Paste a PNG, JPEG, GIF or WebP image into the composer to preview it before
sending. Remove a preview with its close button if you change your mind. An
image can be sent without text. The composer refuses images when the connected
agent did not advertise image prompts, or when the pasted images exceed 10 MiB
in total. Text paste works as usual.
Pastes longer than 200 words appear as a numbered [Pasted text #… +N words]
marker while you compose; the full text is sent when you press Send. The
composer grows with shorter text up to its height limit, then scrolls.
Press Ctrl+S in the composer, or tap the Park draft archive icon on a phone, to set aside the
current text and image previews. The Parked draft control on desktop, or the
Restore parked draft icon on mobile, shows that a
draft is waiting. Press Ctrl+S or tap it again while the composer is empty to
restore the draft; when the composer contains another draft, the two swap.
On mobile, Park and Stop use labelled icons in the input row beside Attach and
Send. They do not reserve a separate row above the composer.
Sending the intervening prompt also restores the parked draft automatically.
Parking survives closing and reopening the panel or reloading its window, and
stays with its chat tab. If browser storage is unavailable, the composer warns
that a reload may lose the parked draft.
Claude Code’s documented Ctrl+S behavior
is the reference for stashing and
restoring an empty prompt; automatic restoration after Send and swapping two
nonempty drafts are TUICommander behaviors requested for this composer.
The transcript follows new output while you are at the bottom and keeps your
position when you scroll up. A touch pauses automatic scrolling until you release
or cancel it. If you did not scroll up, the transcript then catches up to the latest
output, even when the answer finished during the touch. Tool activity rows show names; expand a call to
read its full command and output.
- Streamed answer. Text arrives a chunk at a time. Reasoning is folded into a Thinking disclosure, kept apart from the answer. When a saved conversation is loaded, its earliest replayed chunks remain in order even if ego sends them before the load request finishes.
- Turn markers. AI Chat hides ego’s TUICommander connection acknowledgement,
shows
intent:as a labelled status, and turns asuggest: [ A | B | C ]line or trailing token at the end of an answer into reply buttons. Choosing one sends that text as the next prompt. Mentions in ordinary prose and code examples remain in the answer. Sent messages appear once, including when ego streams an echo after a reply button is chosen. - Failed or empty turn. An ACP prompt error appears in the conversation with the agent’s diagnostic. A turn that finishes without an answer says so; the composer becomes available for another prompt.
- Provider retries. When the provider or the network fails before the
agent shows anything, ego retries up to six times and waits longer each time.
The conversation shows one orange line with the cause, the wait and the
attempt, for example
… — connection problem, retrying in 2s (attempt 2/6). The line goes away when an attempt succeeds. After the sixth failure, the turn error replaces the line and the next prompt can be sent. - Tool activity appears as one collapsed line per turn, with a count, observed duration, status and the first two call titles. Expand it to see each call’s title, kind and status; expand a call to see its output. The duration measures only time observed while this panel is open. A replayed conversation has no recorded timing data.
- The plan ego publishes is shown as a list and replaced whole each time it changes.
- Stop cancels the turn. Pause and Resume hold it where ego supports them; Compact shortens the conversation. Each button is drawn only when ego advertised that extension, so a build without it shows no button rather than a button that fails. Resume remains available when a paused turn ends at its boundary; select it to continue the conversation.
- Send during a turn integrates text into the running query when ego advertises steering. Ego consumes it at the next provider request and echoes it into the conversation; TUICommander never sends accepted steering twice. If the turn has already ended, the message follows the normal prompt path. Attachments, agents without steering, and rejected steering use the Queue: messages stay in order until the running turn ends. A paused queue waits for Resume. Every connected view can remove a queued item before ego receives it. Stop affects the running turn for every view. A queued message appears in the conversation when it reaches ego; steering appears when ego echoes it.
- Session settings are published by the current conversation. On desktop, click the model, reasoning and mode summary below the input, or use ⋯ → Session settings. Both open the same dialog. Before the conversation publishes its options, the settings action stays visible but disabled, with a tooltip that explains why. The dialog has labeled choices and descriptions for every select option ego offers, including reasoning effort and sandbox when available. Changes apply to this conversation and the displayed values follow ego’s reply. The summary uses the published choice labels, including Choose a value when a model change leaves reasoning effort unselected. A rejected change shows its error in the dialog. TUICommander keeps no separate model list. The model every new run starts from is ego’s own default, editable in Settings → AI Chat (see Settings).
Questions ego asks back
- Permission. The buttons are the options ego published, answered with one of its own option ids. TUICommander never invents an Allow/Deny pair of its own.
- A form. An elicitation is drawn as a form built from the schema ego sent.
A single choice field with one to three values appears as direct answer
buttons plus Cancel; larger or more complex forms keep their fields.
Only
formmode is ever drawn; any other mode is declined before it reaches the panel.
A question raised while this window was not listening is still shown: the panel fetches what is open when it attaches, rather than waiting for an announcement that already happened.
When AI Chat is hidden, its status-bar button shows the number of unanswered permissions and forms. The desktop sends one notification for each new question; answering it removes the badge and closes its notification.
On a phone, the AI Chat title and conversation picker share one header row. Use the + button (New conversation) to start a chat. The composer uses one focus frame around the editor and microphone. The model, reasoning and mode summary wraps when needed. The conversation picker keeps the current conversation available even while the optional saved-conversation list is empty or still loading.
When it misses something
- “Missed part of this conversation” means the journal no longer holds the point the panel had read up to — a gap, not a dropped connection. Recover starts a fresh ego process and replays the conversation into it.
- “Not receiving updates” means the connection is up but nothing is reading its journal any more. The conversation on screen is intact; it has stopped moving.
From a terminal
Right-click a terminal: Explain with AI and Fix this error put a question about the selection — or about the last 50 lines when nothing is selected — into the panel’s composer and open it. They write the question; you send it.
The session knowledge store
The write-only command knowledge store was removed in #2115-1333. TUICommander no longer records or periodically saves command outcomes for AI context. Existing <config_dir>/ai-sessions/<session_id>.json files remain untouched. Shell activity and command blocks still use OSC 133 markers.
Not here
| Feature | Where it went |
|---|---|
| Providers, models, slots, API keys, Ollama detection | Settings → AI Chat shows what ego is configured with and sets its default model (#786-4a6d). Slots, API keys and Ollama detection did not come back: no key is stored by TUICommander and no provider call is made from it |
| Agent mode (ReAct loop), the safety checker, the file sandbox | nothing. ego runs its own tool loop and reaches terminals through TUICommander’s MCP server |
| Terminal watchers (autonomous rules) | not scheduled |
| PR AI review, changelog generation, improvement scan | 795-320b |
Smart Prompts api execution mode | One unattended ego turn (#787-ee50), with no interactive tools and the final text routed to the prompt’s configured output |
See also
docs/backend/acp.md— the ACP client, its journal and the authority a session is given.docs/backend/mcp-http.md— how an external agent drives TUICommander terminals, which is the path ego uses.docs/backend/pty.md— PTY lifecycle, OSC 133, TUI detection, silence-based idle.
Pending permissions and ego notice cards can alert your phone when the desktop is away. Both share a 30-second limit per conversation; ordinary activity does not send a push.
AI Chat offers Fork beside a reply when ego advertises message-point forks. The new tab keeps history through that reply’s successful completed turn; the parent remains open and can keep running. An unfinished or failed turn is not a valid cutoff, and ego reports a refusal without creating a child.
While a turn runs, Fork conversation and /fork use the last successful completed turn observed on the current connection, never partial output. If no verified cutoff is available (including after a fresh load), select an earlier reply or wait for completion. Agents without message-point fork support still require an idle conversation. Cancellation and failure do not advance the saved cutoff.
Forked AI Chat tabs label inherited history. A separator marks where the child’s own conversation begins, including after loading saved history.
The AI Chat conversation picker groups fork and compaction descendants beneath their ancestors. Deleted immediate parents remain visible as disabled “Deleted conversation” rows.
Closed refusal turns show one plain-text card with the agent’s existing ACP refusal text. A refusal without text shows a generic refusal message.
Conversation launch options
Use New conversation with options beside the + button to override the ego profile, workspace or executable for one conversation. Empty fields use Settings defaults. The header shows the resolved values. The conversation keeps these values and its peer identity after a restart; other chats keep their existing launch configuration. The plain + action creates a chat with the global defaults.
A custom conversation runs its own ego ACP process. Its mail identity is separate from daily chats, even when both use the same workspace.
When you scroll up and more conversation content arrives, New text below appears as a compact badge floating at the bottom-right of the transcript, above the composer, without reserving a row. Select it to return to the bottom and resume following. Reaching the bottom by hand clears it too. Search jumps do not show the badge until later content arrives. Disable New text indicator in Settings → Appearance → Chat, or mobile Settings. This preference is saved on the current client and applies to terminal Chat too.
AI Chat replies use plain chat prose without the terminal answer rail. Literal Markdown blockquotes keep their normal quote style.
Use Pin repository beside the composer to keep that conversation’s repository context while you navigate elsewhere. Pinned repository identifies the frozen context. Unpin to follow the repository on screen again. The name uses the repository or group color, with the normal light-theme text adjustment. This does not move or filter conversation tabs. The existing pin icon still parks your draft; it is a separate action.
Middle-click a conversation tab to close it through the same path as its close button. The last conversation tab stays open. Press Escape from the composer or transcript to stop a running turn without clearing your draft. When Find is open, Escape closes Find first, including when focus has moved back to the composer. Desktop Stop and Send stay at the bottom of the input without growing with it. Park remains in the card header.
Repository names in linked worktree contexts use the registered parent repository color, including its inherited group color. Pinning a worktree keeps that color while you browse another repository.
Telegram replies
After Telegram is configured in Settings, allowlisted phone text reaches the
latest-connected live AI Chat agent when no agent has explicitly registered.
With several live chats, connection order determines the fallback, not the
selected tab. An agent can call telegram register to take over the channel;
that registration has priority until it ends or another agent replaces it.
Registration lasts only while its MCP identity remains live. No PTY is needed.
Incoming phone text arrives through the normal peer inbox and TUIC wakes an idle
conversation. The no-agent reply appears only when neither a registered agent
nor a live AI Chat agent is available.
The phone shows a receipt reaction, then a working reaction once the mail is read and a new turn starts. Assistant message chunks stream into the ephemeral Telegram preview; thought chunks and tool arguments do not. Permissions show a waiting reaction and ask you to respond in TUICommander. The preview is never approval to publish anything.
telegram begin is optional. telegram finish supplies the exact final phone
answer and remains valid after the preview ends. If a turn started by TUIC’s
peer-mail wake settles without finish, TUIC sends that turn’s assistant text
once. Turns started from an unrelated conversation prompt do not auto-publish.
A failed turn sends one safe stopped notice. Stop on the phone targets only the
captured turn; a queued Stop does not interrupt unrelated work.
Settings MCP startup boundary
The Settings owner can read and edit the configured Ego model/perimeter and base provider-auth configuration, with owner revisions and next-session effects. The AI Chat Settings button still opens the human login workflow. A schema-only assistant can also request typed begin_login and login_status from the configured Ego owner; you complete the exchange in its terminal. Terminal exit is not success: the owner reads credential presence, then the assistant refreshes provider state. Missing binary/capability is not permission to use a different executable or PTY fallback for ACP. See startup workflows.
Discuss a Markdown selection
With a conversation open in AI Chat, select text in a Markdown file and choose Send to AI Chat beside the comment action. TUIC appends the file path, original source line range and quoted selected text to that conversation’s draft, then focuses the composer. It preserves your existing draft and attachments and does not send a message. This action is also available in the mobile Files Markdown view after you open a chat conversation.
Selections can include inline links and adjacent punctuation. Link destinations and reference identifiers do not count as visible occurrences when locating the source lines.
Development backend mismatch
When a development frontend calls a command missing from the running backend,
AI Chat explains the Backend/frontend version mismatch instead of offering
Retry. Restart make dev (or pnpm tauri dev) when you are ready to end the
current backend session. Reloading the frontend does not rebuild the backend.
Release and remote-owner errors keep their existing recovery controls.
Dictation in a detached chat
The detached AI Chat window owns its dictation input. Focus that window and hold its configured push-to-talk key. On macOS, Fn starts in the focused chat window; releasing it still stops that recording if focus moves away. The transcript goes to the input and selection captured at recording start, not to the main window. If the chat transcript has focus, dictation targets that window’s composer.
AI Chat dictation inserts a draft for review. It does not submit the draft. If the captured input is removed or edited before transcription completes, the transcript is retained in Messages instead of overwriting the new draft. If the model is missing, the setup action opens Voice settings in the main window.
Confirm a detected ego executable
If no ego executable is configured, opening AI Chat checks the host’s agent detection. When it finds ego, the panel shows its path and Use this. Select Use this to save that path through the normal settings writer and activate AI Chat. Detection never saves a path automatically and never replaces a configured executable. Configure ego still opens manual setup. If detection finds nothing or fails, the existing inactive message and manual setup action remain available.
Hands-free voice
Settings → Voice → Hands-free conversation lists attached AI Chat sessions in the Target picker, including sessions in detached panels. Select a chat and start the conversation to submit speech through its normal ACP prompt queue and allow replies through the voice tool. Closing or leaving the selected chat releases its voice binding.
Master prompt
Settings → AI → AI Chat → Chat behavior has a multiline Master prompt field. It adds instructions to new conversations without replacing TUIC launch rules. Empty means no extra user instructions. The limit is 8192 UTF-8 bytes. Existing conversations keep their saved instructions, also after reopening. Smart Prompts, PR reviews, changelog generation and story drafting do not use this field. Do not use it to store secrets.
The host separately tells attended AI Chat sessions that fenced mermaid code blocks render as diagrams. When a diagram helps explain architecture, flows or relationships, the agent is asked to prefer Mermaid over ASCII. Diagrams are not required. This guidance applies with an empty or custom master prompt and when a saved conversation starts a new process. It does not consume the user prompt limit or reach unattended tasks.
Path-based image previews
Messages with [image: /absolute/path.png] attachments show framed previews above the text in Pending bubbles, session Chat, AI Chat and queue lists. One image uses one frame. Two images sit side by side. Three or more use a two-column grid. The marker is hidden from the displayed text. If the image cannot be read, its frame shows Image unavailable. Copy and reply actions keep the original attachment paths. Native image placeholders without a file path keep their attachment labels.
Smart Prompts
One-click AI automation for common git and code tasks. Smart Prompts inject context-aware commands into your active agent terminal, run headless one-shot operations, execute shell scripts directly, or call LLM APIs.
What are Smart Prompts?
Smart Prompts are context-aware automation shortcuts that turn repetitive developer workflows into single-click actions. They automatically resolve git context (branch, diff, changed files, PR data) and deliver a well-crafted prompt to your AI agent — no manual typing, no copy-pasting, no context switching.
TUICommander ships with built-in prompts covering commit workflows, code review, PR management, CI fixes, and code investigation. Each prompt includes a description explaining what it does, so you always know what will happen before clicking.
How to Use
Toolbar Dropdown
Press Cmd+Shift+K (Ctrl+Shift+K on Windows/Linux) or click the lightning bolt icon in the toolbar. The dropdown shows all enabled prompts grouped by category with a search bar at the top.
Git Panel — Changes Tab
The SmartButtonStrip appears above the changed files list. Quick access to prompts like Smart Commit, Review Changes, and Write Tests.
PR Detail Popover
Click a PR badge in the sidebar to open the popover. The SmartButtonStrip shows PR-specific prompts: Review PR, Address Review Comments, Fix CI Failures, Update PR Description.
Command Palette
Open with Cmd+P and type “Smart” to see all smart prompts prefixed with “Smart:”.
Branch Context Menu
Right-click a branch in the Branches tab (Cmd+G) for branch-specific prompts like Create PR, Merge Main Into Branch, and Summarize Branch.
Built-in Prompts
| Category | Prompts |
|---|---|
| Git & Commit | Smart Commit, Commit & Push, Amend Commit, Generate Commit Message |
| Code Review | Review Changes, Review Staged, Review PR, Address Review Comments |
| Pull Requests | Create PR, Update PR Description, Generate PR Description |
| Merge & Conflicts | Resolve Conflicts, Merge Main Into Branch, Rebase on Main |
| CI & Quality | Fix CI Failures, Fix Lint Issues, Write Tests, Run & Fix Tests |
| Investigation | Investigate Issue, What Changed?, Summarize Branch, Explain Changes |
| Code Operations | Suggest Refactoring, Security Audit |
Git variables are resolved in the active terminal’s checkout, not the parent
repository directory. A template that uses both {branch} and {base_branch}
is unavailable when refreshed Git context shows the same branch for both.
Toolbar and Git Branches actions show the reason in their tooltip. Cached
workspace branch names do not decide availability or block execution. Every run
checks the target checkout again before sending text. Select a different branch
before running a merge or rebase template. Templates that use only {branch} remain available.
Customizing Smart Prompts
Open Settings > Smart Prompts to manage prompts:
- Enable/disable individual prompts (disabled prompts are hidden from all UI surfaces)
- Edit prompt content — built-in prompts show a “Reset to default” button to revert your changes
- Create your own smart prompts with the same placement options and variable system
- View each prompt’s placement (toolbar, git-changes, pr-popover, git-branches) and execution mode
Status Feedback
When prompts cannot execute, the dropdown shows a status banner at the top explaining why:
- “No active terminal” — open a terminal first
- “No AI agent detected” — the active terminal has no agent running
- “Agent is busy” — wait for the current operation to finish
Items are visually dimmed but visible, so you can still browse what’s available.
Context Variables
Prompts use {variable_name} syntax. Most variables are auto-resolved at execution time — no manual input needed.
Git Context (from Rust backend)
| Variable | Description |
|---|---|
{branch} | Current branch name |
{base_branch} | Explicit base branch from repository settings; Automatic or unloaded settings use origin/HEAD, then local main, master, or develop |
{repo_name} | Repository directory name |
{repo_path} | Full filesystem path to the repository root |
{diff} | Working tree diff (truncated to 50KB) |
{staged_diff} | Staged changes diff (truncated to 50KB) |
{changed_files} | Short status output |
{commit_log} | Last 20 commits |
{last_commit} | Last commit hash + message |
{conflict_files} | Files with merge conflicts |
{stash_list} | Stash entries |
GitHub/PR Context (from frontend stores)
| Variable | Description |
|---|---|
{pr_number} | PR number for current branch |
{pr_title} | PR title |
{pr_url} | GitHub pull request URL |
{pr_state} | PR state: OPEN, MERGED, or CLOSED |
{pr_checks} | CI check summary (e.g. “3 passed, 1 failed”) |
{pr_open_threads} | Open review threads that are not outdated, one line each (location, tool, severity, title, link), most severe first, max 30. Read from GitHub only when a prompt uses it. The list is untrusted PR text in a fenced block; “Address Review Comments” sends it |
{merge_status} | Merge status: MERGEABLE, CONFLICTING, or BEHIND |
{review_decision} | Review status: APPROVED, CHANGES_REQUESTED, or REVIEW_REQUIRED |
Agent/Terminal Context
| Variable | Description |
|---|---|
{agent_type} | Active agent type (claude, gemini, codex, etc.) |
{cwd} | Active terminal working directory |
Manual Input Variables
| Variable | Description |
|---|---|
{issue_number} | GitHub issue number to investigate |
Variable Input Dialog
When a prompt contains variables that cannot be auto-resolved, a Variable Input Dialog appears before execution. Each field shows the variable name and a human-readable description, so you know exactly what to fill in. Pre-populated suggestions are shown where available.
Execution Modes
Inject Mode (Default)
The resolved prompt is inserted into the active terminal. With Auto-execute enabled, TUICommander submits it exactly once through the agent-aware command path and checks that the agent is idle first (configurable per prompt). With Auto-execute disabled, the text remains editable in the Compose box or terminal input and is not idle-gated. If the Compose box is unavailable, the terminal input is used without pressing Enter.
An explicit Insert action always keeps the text editable. Insert & Run and double-click always submit once, regardless of the saved Auto-execute setting.
Shell Script Mode
Executes the prompt content as a shell script directly — no AI agent involved. The content runs via the system shell (sh -c on macOS/Linux, cmd /C on Windows) in the active repository’s directory.
Useful for automating repetitive CLI tasks: pruning orphan branches, running linters, collecting metrics, or any command pipeline you’d otherwise type manually. Context variables like {branch} and {repo_path} are resolved before execution.
Output is routed based on the prompt’s output target (clipboard, toast, panel, or returned in result). Timeout: 60 seconds.
Headless Mode
Runs a one-shot subprocess without using the terminal. Useful for quick operations like generating a commit message. Output is routed to the clipboard or shown as a toast notification.
Setup: Go to Settings > Agents and configure the “Headless Command Template” for each agent type. The template uses {prompt} as a placeholder:
- Claude:
claude -p "{prompt}" - Gemini:
gemini -p "{prompt}"
Without a template, headless prompts automatically fall back to inject mode. A prompt run from a branch menu, terminal menu or the command palette that cannot start (for example, no headless agent configured) shows a warning toast naming the reason.
Note: Headless mode is not available in the Mobile Companion (PWA) — prompts fall back to inject mode automatically.
API Mode
Calls LLM providers directly via HTTP API without terminal or agent CLI. Supports an optional system prompt per prompt. Output routed via the same output target options. Requires LLM API configuration in Settings > Agents.
Execution failures
A failed Smart Prompt reports the backend error message. Structured errors also show their code, for example agent_error: Internal error: .... This does not retry the failed agent operation.
Smart Prompts Library
The Smart Prompts Library stores and manages all your prompt templates — both built-in AI automation prompts and your custom templates. Prompts are injected directly into the active agent terminal or run headless for quick one-shot operations.
Looking for one-click AI automation? See Smart Prompts for the full guide on built-in automation prompts, context variables, and headless execution.
Opening the Drawer
- Cmd+Shift+K — Toggle the prompt library drawer
- Toolbar button — Prompt library icon in the main toolbar
Browsing and Searching
When the drawer opens, the search input is focused automatically. Type to filter prompts by name, description, or content. Matching is case-insensitive and searches all three fields simultaneously.
Use the category tabs to narrow the list:
| Tab | Shows |
|---|---|
| All | Every saved prompt, sorted by most recently used |
| Custom | User-created prompts |
| Favorites | Prompts you have starred |
| Recent | Last 10 prompts you used |
Keyboard Navigation
| Key | Action |
|---|---|
↑ / ↓ | Move selection up/down |
Enter | Run the selected prompt using its Auto-execute setting |
| Double-click | Insert and submit exactly once |
Ctrl+N / Cmd+N | Create a new prompt |
Ctrl+E / Cmd+E | Edit the selected prompt |
Ctrl+F / Cmd+F | Toggle favorite on the selected prompt |
Escape | Close the drawer |
Creating a Prompt
- Open the drawer (
Cmd+Shift+K) and click + New Prompt, or pressCtrl+N/Cmd+N - Fill in the fields:
- Name (required) — shown in the list
- Description — optional subtitle, also searchable
- Content (required) — the text to insert; use
{{variable}}for dynamic values - Auto-execute — submit immediately, or leave the inserted text editable for review
- Keyboard Shortcut — optional global shortcut to trigger this prompt directly
- Click Save
Editing and Deleting
The drawer and Settings > Smart Prompts use the same aligned editor. Placement choices have readable names and include File menu. Execution mode controls which target, agent and output fields appear. Send immediately appears only for injection directly into the terminal.
In the drawer, Save applies your draft and Cancel discards it. Settings applies each edit immediately. Changing the execution mode does not convert prompt content: use Shell script (direct run) only for shell commands, not natural-language instructions.
- Click the pencil icon on any prompt row, or select it and press
Ctrl+E/Cmd+E - Click the trash icon to delete — a confirmation dialog appears before deletion
Variable Substitution
Use {{variable_name}} placeholders in prompt content. When you send a prompt that contains variables, a dialog appears asking you to fill in each value before injection.
cd {{project_dir}} && cargo test -- {{test_filter}}
Built-in Variables
These are resolved automatically by the backend when present:
| Variable | Value |
|---|---|
{{diff}} | Current git diff |
{{changed_files}} | List of changed files |
{{repo_name}} | Repository name |
{{branch}} | Current branch name |
{{cwd}} | Current working directory |
Custom Variables
Any {{name}} not in the built-in list becomes a custom input field in the variable dialog. You can optionally add a description and default value per variable when editing the prompt — the description appears as placeholder text in the dialog.
Inserting with Variables
The variable dialog offers two actions:
- Insert — writes the resolved text to the terminal input line (you can review before pressing Enter)
- Insert & Run — submits the resolved text once through the agent-aware command path
These explicit actions override the saved Auto-execute setting for that use.
Favorites and Pinning
Click the star icon on any prompt row to toggle its favorite status. Favorited prompts appear at the top of any list view with a ★ prefix and are accessible via the Favorites category tab.
Recently Used
The Recent tab shows the last 10 prompts you sent, in order of use. Recency is also used to sort the All view — most recently used prompts appear first.
Sending to Terminal
Selecting a prompt (click or Enter) writes its content to the currently active terminal. Auto-execute submits it immediately; otherwise the text remains editable. If the prompt has variables, the variable dialog appears first and its Insert or Insert & Run choice takes precedence.
The drawer closes automatically after a successful injection and focus returns to the terminal.
Run Commands
A lighter-weight alternative for per-branch one-off commands:
- Cmd+Shift+R — Run the saved command for the active branch
- Cmd+R — Reload the active web/preview tab
Configure run commands in Settings → Repository → Scripts tab.
Voice Dictation
TUICommander includes local voice-to-text using Whisper AI. All processing happens on your machine — no cloud services.
Setup
- Open Settings → Voice
- Enable dictation
- Download a Whisper model under Speech recognition (recommended:
large-v3-turbo, ~1.6 GB) - Wait for download to complete (progress shown in UI)
- Optionally configure the hotkey, the microphone and the language
The page has one titled section per job, speech-to-text first and text-to-speech last: Dictation (enable, hotkey, auto-send), Speech recognition (input device, Whisper model, language, and voice tuning at the bottom), Auto-Corrections, Hands-free conversation, and Spoken replies. Each section keeps its own advanced settings at its bottom; there is no shared “Advanced” section.
Usage
Push-to-talk workflow:
- Hold the dictation hotkey (default:
F5) or the mic button in the status bar - Speak your text
- Release the key/button
- Transcribed text is inserted into the focused input element (textarea, input, or contenteditable). If no text input has focus, the text falls back to the active terminal PTY. The focus target is captured at key-press time.
The hotkey works globally — even when TUICommander is not focused.
Pauses do not discard preceding speech from the live preview. Streaming passes non-zero audio windows through the same speech gates used by the final transcription; the final pass processes the complete retained recording.
Hands-Free Conversation
Push-to-talk sends one dictation to whatever has focus. Hands-free is the other mode: it binds one terminal, keeps the microphone open, and sends each utterance by itself.
To start it on the terminal you are looking at, open the Command Palette and
run Start hands-free conversation. While it runs, the same entry reads
Stop hands-free conversation. The binding does not follow focus: switch
tabs and the conversation stays with the terminal you started it on. The
action has no default shortcut; bind toggle-hands-free in Settings →
Keyboard Shortcuts if you want one. You can also choose a terminal in
Settings → Voice → Hands-free conversation and select Start
conversation.
Hands-free conversation uses an accent Start conversation action and a distinct Stop conversation action. The state row shows a coloured indicator with Running or Stopped, alongside the backend phase when available.
While it runs, the panel shows the state, the bound terminal, where the audio comes from, and the text that is about to be sent. The dictation hotkey stops the conversation, and so does Stop conversation.
With an activation phrase, Listening means the microphone is waiting or hearing speech that has not yet matched. Go ahead means local recognition matched your phrase during the open utterance. Prefix checks cover its first four seconds; their speed depends on your model and machine. Transcribing means the utterance has ended and the final pass is running. A partial wake match is only an acknowledgement: the final transcript still decides whether the speech is addressed here and can be sent.
You do not need to watch the screen: two short rising notes mean your turn was sent to the agent, and two softer falling notes mean the activation phrase was missing and the turn was dropped. Only the device you are talking into plays them. Turn them off with the Earcons setting.
| Control | What it does |
|---|---|
| Activation phrase | When set, only speech that opens with this phrase is sent, and the phrase is removed first. Case, punctuation and accents do not matter, and the usual transcription variants (a joined Sentimac, an extra letter as in Mack) still count. Leave it empty to send every utterance. The match runs on your machine. The field suggests computer: it is distinctive, Whisper transcribes it reliably, and ordinary speech rarely contains it. |
| Hold-back before sending | How long a finished utterance stays visible before it goes to the terminal, so you can stop one you did not mean. With an activation phrase, the effective delay is at least five seconds to include a continuation. It applies to the next conversation, not to the one already running. |
| Earcons | Plays the short sounds described below when a turn is sent or dropped. On by default. |
| Notify model when hands-free changes | Tells the agent that it can answer out loud when the conversation starts, and to go back to text when it ends. |
| Start notice | Shown while Notify model is on. The text the agent reads when the conversation starts; the built-in text is shown in grey. Write your own instructions here; leave it empty or press Reset to default to send the built-in text. Line breaks are sent as spaces. When the dictation language is set explicitly, TUICommander adds “Reply in <language>.” to the notice itself. |
Speech is typed straight into the bound terminal. It does not wait for the agent to finish: a turn is typed at once, even while the agent is working, the same as when you type into a busy agent by hand. It does not use the Compose queue, so commands you queued there keep their order and their timing. A permission prompt, or text you are typing in the terminal, keeps your turn until it is gone — your speech is never typed into a dialog. A kept turn stays visible in the hands-free panel, and anything you say meanwhile is added to it, so it arrives as one message in the order you said it. The conversation ends by itself when the bound terminal closes or the audio device goes away.
Say the activation phrase on its own to open a short window in which the following turns need no phrase. After a phrase addressed with the activation phrase, you can pause and continue speaking within five seconds without repeating it. The pending text is sent as one message; the hold-back is at least five seconds while the phrase is configured, even if you saved a shorter delay.
Spoken Replies
The agent can answer out loud. By default the voice is a Microsoft Edge neural voice: nothing to download, many languages, a voice list filtered by the dictation language and a Listen button to hear each one. It needs the internet, and the text of each reply is sent to Microsoft’s online speech service. Offline, the Voice section says so instead of staying silent.
Echo cancellation, hush, volume and levelling work the same for every engine. Expert mode adds a Speech engine setting: Pocket TTS runs fully on this machine (Settings → Voice → Spoken replies then lists one shared runtime library plus a bundle per language, each with its own voices; English, French, German, Italian, Portuguese and Spanish), and External command pipes the reply text to a program you name. Installations that already chose a Pocket voice or downloaded Pocket keep Pocket.
Replies are spoken in the language of the conversation. When the dictation
language is set to auto-detect, nothing is spoken until somebody speaks — the
language of the first utterance decides.
The agent is told which language to reply in once: in the start notice when the
language is set explicitly, otherwise on your first spoken turn as
(reply in Italian). Later turns in the same language are sent exactly as you
said them; the hint returns only when you switch language.
The language list marks every language with no bundle as “no spoken
replies”. You can still dictate in it, but replies stay silent, and Whisper
expects you to speak that language — choose the one you speak, or Auto-detect.
Talk over a reply and it stops within about a fifth of a second, and what you say becomes the next turn. Echo cancellation runs on the captured audio, so the reply coming out of your own speaker does not interrupt itself and does not become a turn.
Models
| Model | Size | Quality |
|---|---|---|
| small | ~488 MB | Good |
| small.en | ~488 MB | Good (English-only) |
| large-v2 | ~3.0 GB | Highest accuracy (slow) |
| large-v3-turbo | ~1.6 GB | Best (recommended, default) |
Models are downloaded to <config_dir>/models/ and cached between sessions.
Languages
Auto-detect (default), or set explicitly: English, Spanish, French, German, Italian, Portuguese, Dutch, Japanese, Chinese, Korean, Russian.
Text Corrections
Configure word replacements applied after transcription:
| Spoken | Replaced with |
|---|---|
| “new line” | \n |
| “tab” | \t |
| “period” | . |
Add custom corrections in Settings → Voice → Auto-Corrections.
Audio Device
Select which microphone to use from Input device in Settings → Voice → Speech recognition. Lists all available input devices.
Voice Tuning
Settings > Voice > Speech recognition → Voice tuning records a test phrase and shows the result in the panel — nothing is sent to a terminal. Use it to set two gates that decide whether captured audio counts as speech.
| Control | What it does |
|---|---|
| Level gate | Audio quieter than this never reaches Whisper. The marker on the meter is the gate; the bar is your live level. |
| Speech confidence gate | Discards a transcript when Whisper itself reports it probably heard no speech. Lower is stricter; 100% turns it off. |
When a recording produces no text, the panel says why (“Rejected: …”). Without that line a gate that swallowed your speech and a microphone that captured nothing look identical.
Symptom → fix:
- Random “Grazie” / “Thank you” appear when you are not speaking — usually a distant microphone that keeps picking up room noise. Raise the level gate until room noise sits below the marker, then lower the speech confidence gate.
- Quiet speech is dropped — lower the level gate, or raise the speech confidence gate toward 100%.
Platform Notes
- macOS: GPU-accelerated transcription via Metal
- Windows: GPU-accelerated transcription via Vulkan when a Vulkan driver is present, CPU otherwise
- Linux: GPU-accelerated transcription via Vulkan when a Vulkan driver is present, CPU otherwise
- Microphone permission is requested on first use (not at app startup)
Status Indicators
| Indicator | Meaning |
|---|---|
| Mic button (status bar) | Click/hold to start recording |
| Recording animation | Audio is being captured |
| Live level meter in the dictation preview | The selected microphone is receiving sound; it appears immediately while recording |
| Processing spinner | Whisper is transcribing |
| Model downloading | Progress bar with percentage |
Hotkey Configuration
Change the push-to-talk hotkey in Settings → Voice. The hotkey is registered globally via Tauri’s global-shortcut plugin.
Default: F5
Auto-Send
Enable Auto-send in Settings → Voice to submit the terminal input after transcription. In terminal Chat mode, dictation inserts at the captured Compose selection and uses the normal Compose Send action exactly once, including draft cleanup after success. This works with Compose or transcript focus. With Auto-send off, the text stays in Compose for review. Other editors, search fields and form inputs never submit automatically.
Mobile Dictate into draft uses browser speech recognition and stays review-only; tap Send when ready. The separate hands-free conversation sends through its existing server-owned path.
AI Chat voice targets
In Settings → Voice → Hands-free conversation, choose an AI Chat entry in Target, then select Start conversation. Attached chats are available whether the panel is docked or detached. Spoken turns use the same ACP prompt queue as typed turns. The chat can answer through the existing voice tool and speech engine. Changing the voice target stops the previous conversation; select Start to bind the new target. Closing the bound tab or its last panel view, selecting another chat, or stopping ego also stops its voice binding. Moving the panel between docked and detached views does not change the target.
Branch Management
TUICommander has a built-in Branches tab inside the Git Panel. It lets you view, create, delete, rename, merge, rebase, push, pull, and compare branches — all without leaving the app.
Opening the Branch Panel
Three ways to open it:
Cmd+G— Opens the Git Panel directly on the Branches tab- Click the “GIT” vertical label in the sidebar — Opens the Git Panel on the Branches tab
Cmd+Shift+D, then click the “Branches” tab header — Opens the Git Panel on the last active tab; click Branches to switch
Branch List Overview
The panel shows two collapsible sections:
- Local — all branches in your local repo
- Remote — tracking branches from all remotes
Each branch row displays:
- Branch name
- Ahead/behind counts relative to its upstream (e.g.
↑2 ↓1) - Relative date of the last commit (e.g. “3h ago”, “2d ago”)
- Merged badge — shown on branches already merged into the default branch
- Stale dimming — branches with no commit in the last 30 days appear dimmed
A Recent Branches section at the top shows recently checked-out branches from the git reflog, for quick re-access.
Prefix Folding
When you have many branches following a naming convention (feature/, bugfix/, chore/), prefix folding groups them automatically:
- Branches sharing a common
/-delimited prefix collapse into a folder row (e.g.feature/ (5)) - Click the folder row (or press
→/←) to expand or collapse it - The toggle button in the panel header enables or disables prefix folding globally
Search / Filter
Type in the search bar at the top of the panel to filter branches by name. The filter applies to all sections simultaneously. Press Escape to clear the search.
Keyboard Operations
The Branches panel is mouse-first: all branch actions live in the right-click context menu, the + (New branch) button, and row double-click. Only list navigation is on the keyboard:
| Key | Action |
|---|---|
↑ / ↓ | Navigate branches |
/ | Focus the filter |
Escape | Clear filter / deselect |
Switching between Git Panel tabs:
| Key | Tab |
|---|---|
Ctrl/Cmd+1 | Changes |
Ctrl/Cmd+2 | Log |
Ctrl/Cmd+3 | Stashes |
Ctrl/Cmd+4 | Branches |
Checkout
Double-click any branch (or right-click → Checkout) to check it out.
If your working tree has uncommitted changes, a dialog appears with three options:
- Stash — automatically stashes changes, then checks out
- Force — discards changes and checks out
- Cancel — aborts the checkout
Create Branch
Click the + (New branch) button in the panel header to open the inline branch creation form:
- Type the new branch name
- Optionally change the start point (defaults to HEAD)
- Toggle “Checkout after create” (on by default)
- Press
Enterto confirm orEscapeto cancel
Delete Branch
Right-click a branch → Delete.
- Uses safe delete (
git branch -d) by default — refuses to delete unmerged branches - A confirmation prompt lets you switch to force-delete (
git branch -D) if needed - Deleting the current branch or the default branch (
main,master,develop) is blocked
Delete merged branches (bulk)
When one or more local branches are already merged into the default branch, a broom button (with a count badge) appears in the Branches tab header. Click it to delete them all at once, after confirming a dialog that lists the targets. Each deletion uses safe git branch -d, so a branch that isn’t truly merged is kept rather than force-deleted.
Rename Branch
Right-click a branch → Rename to edit the branch name inline. The current name is pre-filled. Press Enter to confirm or Escape to cancel.
Merge
Right-click a branch → Merge into Current to merge it into the current branch. The merge runs in the background, and the result is shown as a toast: a conflict error on failure, “Already up to date” when there was nothing to merge, or a success toast with a one-click Delete branch action to clean up the branch you just merged.
Rebase
Right-click a branch → Rebase Current onto This to rebase the current branch onto the selected branch. Runs in the background; conflicts are reported.
Push
Right-click a branch → Push. If no upstream is set, TUICommander automatically configures the tracking relationship (--set-upstream origin <branch>).
Pull
Right-click a branch → Pull to pull the current branch from its upstream.
Fetch
Right-click a branch → Fetch to fetch all remotes (git fetch --all).
Context Menu
Right-click any branch for the full context menu:
| Action | Description |
|---|---|
| Checkout | Switch to this branch |
| Create Branch from Here | Create a new branch starting from this commit |
| Delete | Delete branch (safe by default) |
| Rename | Rename inline |
| Merge into Current | Merge this branch into the current one |
| Rebase Current onto This | Rebase current branch onto this one |
| Push | Push this branch |
| Pull | Pull this branch |
| Fetch | Fetch all remotes |
| Compare | Show git diff --name-status between this branch and current |
Stale and Merged Indicators
- Stale (dimmed): the branch has no commits in the last 30 days — a visual cue that it may be abandoned
- Merged badge: the branch has been merged into the default branch and is safe to delete
Git Worktrees
TUICommander uses git worktrees to give each branch an isolated working directory.
What Are Worktrees?
Git worktrees let you check out multiple branches simultaneously, each in its own directory. Instead of stashing or committing before switching branches, each branch has its own complete copy of the files.
How TUICommander Uses Them
When you click a non-main branch in the sidebar:
- TUICommander creates a git worktree for that branch
- A terminal opens in the worktree directory
- You work independently without affecting other branches
Main branches (main, master, develop) use the original repository directory — no worktree is created.
When an agent creates a worktree without spawning a separate session, its tab stays associated with that worktree during repository refreshes. This changes sidebar placement while preserving the shell’s working directory. An explicit worktree declaration also survives restart when a saved agent tab is restored. Removing the worktree also removes its saved placement declaration, so a recycled checkout does not leave an agent pointed at the old directory.
Suspended tabs still own their checkout. Close or resume and move these tabs before removing, archiving, or recycling that checkout. Cleanup names the suspended tab and refuses even a forced removal; recycling skips it. A removed checkout also loses its old Worktrees bell offer, so that offer cannot open the obsolete path.
Worktree removal uses the same checkout identity as the sidebar. A symbolic branch name remains addressable even when Git reports its target branch. Deleting that alias after removal preserves the target branch. If a branch was renamed externally, refresh the repository before removal; the directory name does not define its identity.
Unrelated histories
A branch with no common ancestor with the default branch shows Unrelated history in compact and rich sidebar rows. The repository and its other branches still load normally. In compact rows, a dirty-file badge keeps its count and opens Changes, including when the only changes are untracked files. This is not a failed refresh or merged work. Keep the branch when removing its checkout. Branch deletion requires an archive at the current tip so the independent history remains recoverable.
Worktree Storage Strategies
Configure where worktrees are stored (Settings → Git & GitHub → Worktree Defaults → Storage):
| Strategy | Location | Use case |
|---|---|---|
| Sibling (default) | {repo_parent}/{repo_name}__wt/ | Keeps worktrees near the repo |
| App directory | ~/Library/Application Support/tuicommander/worktrees/{repo_name}/ | Centralised storage |
| Inside repo | {repo_path}/.worktrees/ | Self-contained, add to .gitignore |
| Claude Code default | {repo_path}/.claude/worktrees/ | Compatible with Claude Code’s native EnterWorktree |
Override per-repo in Settings → Repository → Worktree.
Warm Linked Worktrees
git worktree add checks out the tracked files and nothing else, so every
ignored build directory is missing and the first build is a full one.
TUICommander asks git which directories the parent ignores and copies them into
the new worktree copy-on-write, at the same near-zero disk cost. It is
language-agnostic — node_modules, target, .venv, dist, vendor and
anything else your .gitignore covers, except .tmp and .mdkb directories —
and it copies directories only: an
ignored file such as .env stays where it is, because materialising a
credential into a new workspace is not a convenience.
A moved cargo target directory keeps its cache. A CMake one does not:
CMakeCache.txt records the directory it was configured in, so anything built
through CMake (whisper.cpp here) reconfigures and rebuilds in the new worktree.
Warming is best-effort. Git has already produced a complete worktree by the time
it runs, so a copy that fails costs build time and nothing else — creation still
succeeds and the response carries a warning naming the directory that stayed
cold. Measured on this repository: ~38 s for 30 GB across 80k files
(node_modules 19.5 s, src-tauri/target 17.4 s, everything else under 0.3 s).
For desktop, HTTP, and MCP creation, wait until the workspace’s warm status is
done or failed before installing dependencies or building. When creation
runs a configured setup script through HTTP or MCP, it finishes before the copy
starts. Desktop setup and warming can overlap.
Copy-on-write warming needs filesystem support (APFS, Btrfs, XFS with reflink…) and both
directories on the same volume. TUICommander never trusts the filesystem name
for this — it makes a real copy-on-write copy of one file and looks at whether it
worked, trying macOS clonefile and then a reflink copy. Where neither works,
creation still succeeds with one warning and a cold worktree.
Copied files and directories gain owner write permission in the new worktree,
even when ignored build evidence is read-only in the source. Symlinks are not
followed, and the source permissions and contents stay unchanged.
Creating Worktrees
From the + Button (with prompt)
Click + next to a repository name. A dialog opens where you can:
- Type a new branch name (creates branch + worktree)
- Select an existing branch from the list
- Choose a “Start from” base ref (default branch, or any local branch)
- Generate a random sci-fi name
From the + Button (instant mode)
When “Prompt on create” is off (Settings → Git & GitHub → Worktree Defaults), clicking + instantly creates a linked worktree with an auto-generated name based on the default branch.
The default branch is the main checkout’s explicitly configured base when it
resolves to a commit. Otherwise, TUICommander uses local main, then local
master, then the remote HEAD branch, then the main checkout’s attached branch. This also supports repositories with no remote and
a non-standard base branch. Linked worktrees do not supply the fallback branch.
From Branch Right-Click (quick-clone)
Right-click any non-main branch without a worktree → Create Worktree. This creates a new branch named {source}--{random-name} based on the selected branch, with a worktree directory.
Every creation path uses the same linked-worktree implementation. The parent’s tracked and untracked changes stay in the parent; only Git-ignored directories are considered for warming.
Worktree Settings
Global defaults apply to all repos. Per-repo overrides take precedence when set.
Global Defaults (Settings → Git & GitHub → Worktree Defaults)
| Setting | Options | Default |
|---|---|---|
| Storage | Sibling / App directory / Inside repo / Claude Code default | Sibling |
| Prompt on create | On / Off | On |
| Delete branch on remove | On / Off | On |
| Auto-archive merged | On / Off | Off — archives a clean merged worktree, then deletes its branch (the tip stays recoverable under refs/archive/); a locked or dirty one stays and its row says why |
| Archived worktree retention (days) | 0 (Off) or a positive number of days | Off |
| Orphan cleanup | Ask before removing / Auto-remove / Keep | Ask |
| Safe orphan countdown (Expert Mode) | 5 / 10 / 20 / 30 seconds | 10 seconds |
| PR merge strategy | Merge / Squash / Rebase | Merge |
| After merge | Archive / Delete / Ask | Archive |
Automatic archive runs after the repository lifecycle refresh. It inspects each linked checkout with fresh backend proof, including PR-only merges that local ancestry does not report as merged. Missing, failed, stale or unsafe proof keeps the checkout. Dirty or untracked files, submodule hazards, open sessions and locks still block automatic cleanup; the backend checks again before it acts, without force.
Each inspection records the exact workspace, branch tip, integration base, proof source and time, separately from a cleanup decision. The decision is one of merged (eligible), uncertain, unmerged or safety-blocked. Proof older than 60 seconds, or without a named tip, base and source, is uncertain and never eligible. The archive call carries the inspected checkout fingerprint, so changed work is refused. A failed archive is retried once, after a new inspection that must show the same tip and still be eligible. A recreated workspace is inspected again and never skipped because an earlier one with the same id was archived.
A detached HEAD does not mean that a branch was deleted. Cleanup excludes a
checkout when a non-default local branch still points at its HEAD. Cleanup also
ignores checkouts under temporary roots: the OS temporary directory, TMPDIR,
TMP, TEMP, ~/Gits/.tmp, and (on Unix) /tmp, /private/tmp,
/var/folders and /private/var/folders. Both registered and resolved paths are
checked, including missing paths below symlinked directories. These checkouts
are never offered for orphan removal or removed by orphan cleanup, even after
a previous review. They remain visible as read-only detached rows in the sidebar;
visibility does not grant cleanup permission. Outside temporary roots, a missing
checkout directory remains eligible for registration cleanup. Detached checkouts
without that branch protection retain the dirty-file, operation and live-session
checks. Clean, reachable checkouts without live sessions are removed silently;
other candidates require review in Ask mode. Choosing Keep holds until the
checkout fingerprint changes. An agent can answer an open review through MCP
repo action=orphan_cleanup_answer path=<repo> decision=remove|keep; the backend
checks removal again. A confirmed dirty checkout is removed only when its reviewed fingerprint still matches. The fingerprint includes collapsed ignored path names, but does not detect edits within an already-dirty file or new entries inside an already-ignored directory. The final check and Git removal are not atomic. Dirty orphan removal is available only through the desktop confirmation path. A failed removal shows its error and is not offered again until the fingerprint changes or the app restarts.
The scan runs during repository refresh, not on a dedicated orphan timer. It
runs at startup and after repository operations or repo-changed events. Event
refreshes are debounced for 500 ms (1000 ms if already refreshing), with automatic
starts at least five seconds apart per repository; explicit UI operations can
refresh sooner. Opening Worktree Manager also scans the displayed repositories
and rescans when their revision changes.
Per-Repository Overrides (Settings → Repository → Worktree)
Each setting can use the global default or be overridden for a specific repository.
Merge & Archive
Right-click a worktree branch → Merge & Archive to:
- Merge the branch into the main branch
- Handle the worktree based on the “After merge” setting:
- Archive: Moves the worktree directory to
__archived/— the whole directory, uncommitted changes included. Its Git checkout, HEAD, reflog, and initialized submodules remain usable; it is hidden from the sidebar. A locked worktree is left untouched. - Delete: Removes the worktree and branch entirely. Anything not committed is gone
- Ask: Merge succeeds, then you choose what to do
- Archive: Moves the worktree directory to
The merge uses --no-edit for a clean fast-forward or merge commit. If conflicts are detected, TUICommander attempts git merge --abort and leaves the worktree intact. If that abort fails, the error message tells you the repository may still be conflicted and includes the manual abort command. For this explicit UI request, TUICommander allows a merge commit when histories diverge: it passes --no-ff when merge.ff is false, otherwise --ff. This policy overrides fast-forward flags in branch.<name>.mergeOptions; Git still interprets the other options, including commit messages. TUICommander does not parse those options.
Uncommitted work in the worktree
Before manual removal, the confirmation distinguishes a branch with no commits of its own from one whose commits were merged. It names live terminal sessions and counts uncommitted and untracked files. Confirming still allows removal; review the warnings before proceeding. Automatic PR-close deletion keeps a worktree with live sessions or local changes and logs why it was skipped.
Both Archive and Delete remove the worktree, so one-click cleanup asks before merging when the worktree is not known to be clean or has a live terminal session. The confirmation names the sessions and what happens to the files: archived files travel to __archived/, deleted files do not come back. If the check itself cannot run, cleanup stops. Post-merge cleanup uses the same review before moving or deleting the checkout.
A branch can be integrated even when its original commits are absent from
main: squash merges and rebased copies change commit IDs. TUICommander checks
patches, the result of a virtual merge, and revised copies with matching
subjects. MCP exposes the reason with repo branch_integration or
repo branch_integrations. A branch that only follows its base is in_sync,
not integrated: its query returns integrated: false and no merge proof. A content-based result still needs a recovery ref
at refs/archive/<branch> pointing to the current tip before safe branch
deletion; incomplete or uncertain changes remain protected. If a branch reflog
is empty or absent, its origin is unknown. The repository still loads, but that
branch has no merge proof and safe branch deletion is refused.
The automatic sweep never asks. It archives only a branch whose own commits are merged, when the worktree is clean and has no live sessions. An empty start commit is not proof of a merge: a fresh agent worktree stays available even before its session starts. Content comparisons require changes from the branch point; actual ancestry or a verified merged PR can still prove integration. The sweep keeps other worktrees and names the reason in the status line.
Removing a worktree without force also refuses uncommitted changes when the
branch will be kept, including changes inside submodules. It stops if a Git operation is in progress. If an archive
script adds a commit after the removal check, the worktree can be removed, but
the branch stays and the result warns that the branch changed.
The confirmation lists submodule commits absent from remote-tracking branches.
A changed checkout status, HEAD, or submodule ref after force confirmation stops removal
for a fresh review. The status check tracks which paths are dirty, not further
edits to a path that was already dirty. Initialized submodule refs, stash entries,
and reflog-only commits are preserved in the main checkout’s module repository
before removal. If the main checkout’s copy of a
submodule is uninitialized or points at the wrong Git repository, removal stops
and leaves the worktree available for recovery. If the checkout directory is already missing, the confirmation identifies the stale Git registration and needs no fabricated dirty-file fingerprint. Cleanup skips the archive script because its working directory is gone. A lock requires a separate override. TUICommander preserves registered submodule refs before pruning, including modules whose configured names differ from their checkout paths. Each destination must have one valid path in its owning main module’s .gitmodules; missing or malformed mappings stop cleanup and retain the registration.
If Git has already removed the registration but left a directory behind, cleanup still cancels any pending build-input warming before reporting a directory error.
Deinitialized submodules with retained Git history also block removal, even when their Git module name differs from the checkout path or they are nested.
When using Ask mode, the cleanup dialog detects uncommitted changes and auto-stashes them during the branch switch. An “Unstash after switch” checkbox lets you restore changes on the target branch. That stash covers the base repository; the warning under the worktree step is about the branch’s own directory, which is a different place.
Archive Script
A per-repo lifecycle hook that runs before a worktree is archived or deleted. Configure it in Settings → Repository → Scripts tab, or via .tuic.json (archive_script field).
- The script runs in the worktree directory that is about to be removed
- If the script exits with a non-zero code, the archive/delete operation is blocked and an error is shown
- Use cases: backing up local data, cleaning up resources, notifying external systems
- The script is invoked via the platform shell (
sh -con macOS/Linux,cmd /Con Windows)
Moving Terminals Between Worktrees
Right-click a terminal tab → Move to Worktree to move it to a different worktree. The terminal will cd into the target worktree path, and the tab automatically reassigns to the new branch in the sidebar.
Also available via Command Palette — type “move to worktree” to see available targets for the active terminal.
Removing Worktrees
- Sidebar
×button on a non-main branch — Removes worktree and branch entry - Right-click → Delete Worktree — Context menu option
- Both prompt for confirmation
The Archive workspace? dialog lists three safety checks: uncommitted files, commits absent from the named base branch, and open terminals or agents. Each check has a green pass or red fail mark. Failed checks show counts and explain what Delete would lose or interrupt. Unknown state never counts as a pass.
Cancel, Delete, and Archive remain visible. Archive moves the whole checkout into the archive pool and keeps its local branch and uncommitted changes. It does not merge unmerged commits. Delete removes the checkout and local branch; it is disabled unless every check passes. Submodule commits without a remote copy also block Delete. The backend repeats the checklist before deleting, so a stale dialog cannot authorize new dirty files, commits or sessions. The commit check uses actual containment in the default integration refs; a squash-equivalent branch can still have commits absent from those refs and must be archived instead. Enter selects Archive; Escape cancels. Explicit keep-branch removal and missing checkout registration cleanup retain their separate removal confirmations.
Cancelling or failing the initial confirmation keeps the workspace and its terminals. You can retry removal; duplicate requests for the same workspace remain serialized.
Removing a worktree:
- Closes all terminals associated with that branch
- Checks checkout and submodule state, restores owner write permission inside the worktree and owner search permission on directories before traversing them, then runs
git worktree removeto clean up; a clean populated submodule needs one--forceafter a fresh safety check. If permission repair fails, the checkout stays registered and the error names its path. If Git unregisters the checkout but leaves files behind, TUICommander finishes removing that known checkout before it can delete the branch. If that cleanup fails, the error names the remaining directory. - Removes the branch entry from the sidebar
- If branch deletion was requested, checks for unmerged commits before removing the worktree. An unmerged branch blocks a normal removal. A confirmed dirty-file removal can remove the checkout, but keeps an unmerged branch and reports a warning. Merge it first, or turn off Delete branch on remove to keep the branch.
- If Git rejects branch deletion after removal despite the preflight check, shows a status message that the worktree was removed and the branch was kept.
Immediately before removal, TUICommander refreshes the backend lifecycle verdict
for the exact workspace id. Dirty files require an explicit destructive
confirmation; Unknown blocks removal. Commits live in the parent object store,
and a clean worktree with unmerged commits is marked Unmerged in the sidebar.
The proof also accepts a tip contained in the main checkout’s current branch,
or a merged GitHub PR whose verified head contains the local tip after a squash.
An open or closed unmerged PR, or a PR head behind the local tip, is insufficient.
Turning off Delete branch on remove keeps the branch without needing merge
proof, while the clean-checkout and lock checks still apply.
For a local branch that has no worktree, agents can use MCP
repo action=branch_delete with the repository path and branch name. It
deletes only the local ref after proving its commits are in the checked-out
integration branch, including equivalent patches from a squash merge. A
checked-out, current, default, unmerged, or changed branch is kept; no remote
branch is deleted.
Worktree Manager Panel
Open the Worktree Manager with Cmd+Shift+W (or via the Command Palette → “Worktree Manager”). It shows a unified view of all worktrees across your repositories.
What It Shows
Each worktree row displays:
- Branch name and repository badge
- Lifecycle badges — dirty working-tree state and whether the worktree is
MergedorUnknown, from the same progressive refresh used by the sidebar - Dirty status — file additions/deletions, or “clean”
- PR state — open (with PR number), merged, or closed
- Last commit timestamp — relative time since last activity
- Main badge — marks the main branch (actions disabled)
Eligible orphan worktrees outside temporary roots (detached HEAD or deleted branch) appear at the bottom with a warning badge and a Prune button. Prune refuses a Git operation in progress and keeps detached commits that have no durable branch, tag, or other ref. Create a ref for that commit before retrying if you want to keep the commit and remove the checkout.
Filtering
- Repo pills — Click a repository name to filter by repo (appears when you have multiple repos)
- Text search — Type in the search field to filter branches by name
- Filters compose: selecting a repo and typing text shows only matching branches in that repo
Single-Row Actions
Each worktree row has action buttons (visible on the right):
>_— Open a terminal in the worktree directory✔— Merge the branch into main and archive (disabled for main branches)✕— Delete the worktree and branch (disabled for main branches)
Batch Operations
Select multiple worktrees using the checkboxes (shown when more than one selectable worktree exists). A batch bar appears with:
- Merge & Archive (N) — Merges and archives all selected branches
- Delete (N) — Deletes all selected worktrees
Use the Select All checkbox in the toolbar to toggle all non-main worktrees.
New worktrees share existing stories, plans, and ideas directories through symlinks only when the main checkout already ignores each store. TUICommander adds a root-anchored, symlink-compatible Git exclude when needed, so directory-only ignore patterns do not produce a dirty badge. An unignored store is not linked and produces a creation warning; its files remain visible to Git in the main checkout. Existing worktrees are not changed.
MCP Worktree Creation (AI Agents)
AI agents connected via MCP can create worktrees using repo action=worktree_create.
Because nothing enforces how an agent treats a workspace, the response also carries instructions stating that tracked changes were not carried over, identifying warmed build directories, and explaining that refs and objects are shared with the parent.
When TUICommander receives a worktree creation event while the active terminal is running an agent, the confirmation offers Open Worktree. Accepting selects an existing terminal in the new worktree or creates one when needed. The running agent stays in its original terminal, branch, and working directory; TUICommander does not relabel or interrupt it.
Claude Code — Agent Bridge
Claude Code cannot change its working directory mid-session. When CC creates a worktree via MCP, the response includes a cc_agent_hint field with:
worktree_path— Absolute path to the worktree directorysuggested_prompt— Instructions for spawning a subagent that works in the worktree using absolute paths
CC should spawn a subagent (Agent tool) with the suggested prompt. The subagent uses Read, Edit, Glob, Grep with absolute file paths and cd <path> && ... for shell commands.
Other MCP Clients
Non-Claude Code MCP clients receive the standard {worktree_path, branch} response without the cc_agent_hint field. These clients can change into the worktree directory directly.
External Worktree Detection
TUICommander monitors .git/worktrees/ for changes. Worktrees created outside the app (via CLI or other tools) are detected and appear in the sidebar after the next refresh.
If a session starts in a new sibling worktree before that refresh, TUICommander refreshes its registered repository and places the tab under the new worktree.
Branch Switching
Switching branches in TUICommander does not change the working directory of existing terminals. Each branch’s terminals stay in their worktree path.
If a branch changes inside an existing linked worktree, its terminal sessions remain open and the sidebar updates their workspace to the new branch. Removing or recycling a worktree closes only terminals whose current working directory is inside that checkout. A repo-root terminal is never closed merely because a stale sidebar row lists it. Creating or declaring a worktree does not move the caller’s tab unless its working directory is in that checkout. Reload and saved-tab restore also use the terminal’s working directory, not an old worktree declaration. If a saved tab belongs to another workspace, restoring it does not activate it in the selected workspace or retain it in that workspace’s pane layout. The selected workspace shows its own tabs or its normal empty state.
When you switch branches:
- Previous branch’s terminals are hidden (but remain alive)
- New branch’s terminals are shown
- If the new branch has no terminals, a fresh one is created
Force-deleting a branch preserves its tip at refs/archive/<branch>. It refuses a branch checked out in any worktree and never replaces a different existing archive: a reused branch name is archived as refs/archive/<branch>-<sha7>.
Worktree names that sanitize to an existing checkout name produce an error when they target a different branch. TUICommander keeps that checkout and its uncommitted files.
Automatic sidebar refreshes are spaced at least five seconds apart for each repository. Changes during that window are collected into one refresh at its end, so the final update is retained. Badges can lag by five seconds plus the time needed to read Git state.
Explicit repository additions, branch checkouts and merge cleanup refresh the affected repository immediately, while still waiting for any active refresh to finish.
Reuse of finished worktrees
A safe removal keeps a clean, integrated checkout in the archive area for reuse. A later worktree creation can reuse it under the new branch name without copying ignored build artifacts. Freshly created worktrees stay reserved even before a session starts. Dirty, unmerged, locked, and live worktrees are not reused. Proven copied files that Git still lists as untracked permit safe cleanup but prevent reuse; the new allocation must not inherit the old copy receipt.
The remove confirmation says so: for such a checkout it reads “Archive workspace?” with an Archive button and states that the local branch is kept. The archived checkout still holds the branch.
Detached checkouts
A checkout without a branch remains visible in the sidebar. Its row shows the directory name, short commit SHA and detached. The row is informational: it cannot select a branch or run branch actions. A repository header shows the detached count even when its rows are folded. Checkouts in TUIC’s configured recycling pool stay out of the active inventory. Checkouts archived by TUIC outside that pool also stay hidden, including after you change the storage setting. An unrelated folder named __archived does not hide worktrees.
Worktree discovery diagnostics
Missing or moved registrations appear as one compact row each: a warning icon, the worktree name and a short label (link broken or folder missing). The full path and guidance are in the tooltip. A link broken row (the folder exists but its .git pointer is dead) has a Repair button that runs git worktree repair <path> from the main checkout. A folder missing row has a Prune button; it asks for a second click to confirm, drops only the registration and never deletes files. A failed action shows its error under the row. Discovery never prunes automatically.
If git worktree add --force puts a branch in several checkouts, the lexicographically smallest path keeps the existing branch workspace. Other checkouts appear as read-only diagnostics. Use a distinct branch when you need an independent selectable workspace. Bisect and rebase keep the original branch identity when Git records it.
Unavailable detached registrations are excluded from automatic orphan cleanup in both Ask and On modes, including the Ask countdown. They remain repair diagnostics until restored or explicitly removed. Safe-only removal rechecks availability, so a directory moved after assessment cannot be pruned automatically. Explicit user-confirmed removal remains available.
Bare repository metadata does not appear as a missing checkout. Linked checkouts from a bare repository remain available; deleted or broken linked checkouts still show repair guidance.
Archived worktree retention
Set Archived worktree retention (days) in Settings → Git & GitHub → Worktree Defaults, or override it in the repository Worktree page. 0 is Off and is the global default. An empty repository field inherits the global setting (or .tuic.json value). The stored field is archive_retention_days.
Cleanup runs with the existing repository-refresh cleanup, even if automatic archive is off. It adds no timer. At N × 86400 elapsed seconds, a recorded archive becomes eligible. The archive operation writes Unix seconds, checkout path, branch and tip to tuic-archive.json in the checkout’s Git administration directory. Later writes and directory modification times do not reset this age. Existing archives without a valid record are kept, not assigned a guessed date.
Only registered, completed checkouts immediately inside __archived/, at their recorded path, can be deleted. Active checkouts outside this folder are never retention candidates. Locked archives, live sessions, changed tips, missing commit recovery refs, index flags that can hide local edits (skip-worktree or assume-unchanged), and failed Git safety checks are kept. A branch-tip archive ref does not recover uncommitted files: dirty archives are kept because Archive does not create a dirty-file recovery snapshot. Submodules can also cause Git to refuse removal. Cleanup does not force deletion and does not run the archive script again.
The status line names deleted archives and retained archives with their reasons. Removal also removes the corresponding Git worktree registration. refs/archive/<branch> (or its collision-safe SHA suffix) stays, so committed work remains recoverable with Git. If a parent archive ref blocks a nested branch name, a deterministic flat refs/tuic-archive/<sha256> fallback preserves that branch and tip instead. Retention never deletes local branches or archive refs.
Native workflow integration trials
The WF07 backend trial is disabled by default for each repository. Enable it only in an isolated trial clone until repository-specific parity approval. Integration and cleanup are separate: a merged story can retain proof debt or a workspace that needs attention. Cleanup keeps unknown or dirty work, checks successor/process ownership, and archives the exact branch tip before TUIC removes a clean workspace. This backend action does not add a sidebar click action. See Native integration.
Explicit bases in automation
For MCP repo action=worktree_create, set base_ref to a commit, branch or tag.
Check the returned base_commit before using the checkout as test evidence.
An invalid base fails without creating a branch or checkout. If the requested
branch already exists at a different commit, choose another branch name; TUIC
will not ignore the base or reset existing work.
GitHub Integration
TUICommander monitors your GitHub PRs and CI status automatically.
PR creation, issue creation, and review submission use the repository’s selected account over HTTP, including GitHub Enterprise. These writes do not require an installed gh executable.
Authentication
TUICommander needs a GitHub token to access PRs and CI status. You have two options:
Option 1: OAuth Login (Recommended)
- Open Settings > Git & GitHub
- Click “Login with GitHub”
- A code appears — it’s auto-copied to your clipboard
- Your browser opens GitHub’s authorization page
- Paste the code and authorize
- Done — the token is stored securely in your OS keyring
Settings shows the requested scopes before login, using the same scope list as the login request. This method automatically requests the correct scopes (repo and project) and works with private repositories and organization repos.
Option 2: Environment variable
Set GH_TOKEN or GITHUB_TOKEN before you start TUICommander. A macOS app started from the Dock or Finder does not see variables from your shell profile, so OAuth login is the practical choice there.
TUICommander does not read the gh CLI login. If you only signed in with gh auth login, the GitHub tab shows “Not connected” until you use OAuth login or set a token variable.
OAuth credentials show Logout. It removes the stored OAuth token and falls back to an environment token, if present. Environment credentials show Switch to OAuth and Disconnect. Disconnect stops using the default account until you log in again or restart the app; it does not remove your environment variables.
Token Priority
When multiple sources are available, TUICommander uses this priority:
GH_TOKENenvironment variableGITHUB_TOKENenvironment variable- OAuth token (from Settings login)
Multiple Accounts (github.com + GitHub Enterprise)
TUICommander is account-centric: you can monitor repos across several GitHub accounts at once — additional github.com logins and GitHub Enterprise Server (GHE) instances — and bind each repo to the account that should monitor it. If you only use one github.com account, nothing changes; skip this section.
Adding accounts
Open Settings > Git & GitHub > Additional GitHub Accounts. The account you logged in with above is your default.
- Another github.com account — click “Add another github.com account” and complete the device flow (same as the primary login).
- GitHub Enterprise Server — under “Add Enterprise account”, enter the host (e.g.
github.mycompany.com) and a Personal Access Token withreposcope, then click Add account. The PAT is validated against your GHE server and stored in the OS keyring. (GHE uses a PAT because there is no per-host OAuth App.)
Each account shows its login, avatar, and a source badge. Remove an account to delete its token, its repo bindings, and its cached state.
Binding repos to accounts
Open Settings > Git & GitHub > Repository Bindings. Each workspace repo shows how it resolves:
- Bound — the repo is monitored by the shown account. Click Unbind to detach it.
- Needs binding — the repo matches more than one account or GitHub remote. TUICommander does not guess
origin; pick the right account/remote from the chooser to bind it. - Needs account — a github.com repo with no account configured yet; add one first.
A repo with exactly one matching account/remote resolves automatically without a saved binding. Repository Bindings stays hidden in this single-account setup. A fork and an upstream repository on the same account still require a remote choice because they have different PRs and issues. Worktrees share their main checkout’s binding.
How multiple accounts behave
- Each account polls independently with its own rate-limit budget and circuit breaker, so a rate limit or auth failure on one account never stalls the others.
- Limitation: CI Auto-Heal (which shells out to
gh) is disabled for GHE-bound repos and shows a clear message. PRs, CI status, issues, merge, and approve all work against bound GHE repos.
Requirements
- GitHub authentication (see above)
- Repository with a GitHub remote
PR Monitoring
When you have a branch with an open pull request, the sidebar shows:
PR Badge
A colored badge next to the branch name showing the PR number:
| Color | State |
|---|---|
| Green | Open PR |
| Purple | Merged |
| Red | Closed |
| Gray/dim | Draft |
Click the PR badge to open the PR detail popover.
CI Ring
A circular indicator showing CI check status:
| Segment | Color | Meaning |
|---|---|---|
| Green arc | — | Passed checks |
| Red arc | — | Failed checks |
| Yellow arc | — | Pending checks |
The ring segments are proportional to the number of checks in each state. Click to see detailed CI check information.
Diff Stats
Per-branch addition/deletion counts shown as +N / -N next to the branch name.
PR Detail Popover
Click a PR badge or CI ring to open the detail popover. Shows:
- PR title and number with link to GitHub
- Author and timestamps (created, last updated)
- State indicators:
- Draft/Open/Merged/Closed
- Merge readiness (Ready to merge, Has conflicts, Behind base, Blocked)
- Review decision (Approved, Changes requested, Review required)
- CI check details — Individual check names and status
- Labels — With GitHub-matching colors
- Line changes — Total additions and deletions
- Commit count
- Comments and review threads — Opens this exact PR in Tasks, selects its provider account and scrolls to Comments. The unresolved-threads count is also a button for this route. Normal comments, review summaries and review threads stay in the existing Tasks detail. The first review-thread page loads automatically; use Load more comments for later pages.
If GitHub Work is not loaded, Comments on GitHub opens the PR conversation in your browser instead. The thread-count button uses the same fallback. In a Tasks PR detail, Open branch name returns to its existing sidebar branch/worktree. This action is absent if no matching workspace exists.
PR Notifications (Toolbar Bell)
Click a PR notification to open that PR’s comments and review threads in Tasks. The notification keeps its PR URL, so a later PR on the same branch does not change the destination. Native OS PR notices use the same route. If the provider is unavailable, the PR conversation opens on GitHub.
When any branch has a PR event that needs attention, a bell icon with a count badge appears in the toolbar.
Click the bell to see all active notifications in a popover list. Each notification shows the repo, branch, and event type.
Notification Types
| Type | Meaning |
|---|---|
| Merged | PR was merged |
| Closed | PR was closed without merge |
| Conflicts | Merge conflicts detected |
| CI Failed | One or more CI checks failed |
| Changes Req. | Reviewer requested changes |
| Ready | PR is ready to merge (all checks pass, approved) |
Interacting with Notifications
- Click a notification item — Opens the full PR detail popover for that branch
- Click the dismiss (x) button on an item — Dismiss that single notification
- Click “Dismiss All” — Clear all notifications at once
OS Notifications
While TUICommander is in the background, ready, CI failed, changes requested and merged transitions also raise an operating-system notification showing repo #number: title. On macOS, clicking it opens the PR on GitHub. The same event delivered twice within two minutes notifies once. Turn it off in Settings > Notifications > Pull Requests.
PR Badge on Sidebar Branches
Click the colored PR status badge on any branch in the sidebar to open the PR detail popover directly.
Polling
GitHub data is polled automatically:
- Active window: Every 60 seconds (backs off to 120 s when the rate-limit budget runs low, up to 300 s)
- Hidden window: Every 2 minutes (reduced to save API budget)
- API budget: one batched GraphQL query per repository per poll. Measured with
rateLimit(dryRun: true): 2 points for 1 repository and 6 for 6 (5 before the unresolved-thread count was added), i.e. about 360 points/hr for 6 repositories at 60 s (GitHub limit: 5,000/hr). Unresolved threads are read as a plainisResolvedflag (first 50 per PR); reading the thread comments in the batch would have cost 17 points for 1 repository and 51 for 6, so the bot/human split is fetched per PR, on demand, when the PR panel opens.
Polling starts automatically when a repository with a GitHub remote is active.
Readiness Verdict
The sidebar badge, the PR panel chip and the Ops dashboard all show one verdict, computed in a single function (src/utils/prReadiness.ts). First match wins: Draft, Merged, Closed, Conflicts, Checking (GitHub still computing mergeability), CI Failed, Changes Req., Comments (unresolved review threads), Review, CI Running, Ready (approved, mergeable, nothing outstanding), otherwise Open.
The PR panel also shows the number of unresolved review threads, split into human and bot threads (a bot is a GitHub App/bot author; the author of a thread is the author of its first comment). Counts cover the first 50 threads of a PR.
Merge State Classification
| State | Label | Meaning |
|---|---|---|
| MERGEABLE + CLEAN | Ready to merge | All checks pass, no conflicts |
| MERGEABLE + UNSTABLE | Checks failing | Mergeable but some checks fail |
| CONFLICTING | Has conflicts | Merge conflicts with base branch |
| BEHIND | Behind base | Base branch has newer commits |
| BLOCKED | Blocked | Branch protection prevents merge |
| DRAFT | Draft | PR is in draft state |
CI Auto-Heal
Actions log fetching uses the repository account on github.com or GitHub Enterprise and does not require the GitHub CLI. It keeps failure tails and stops the log sweep after 60 seconds.
Enable Auto-heal in a blocked PR’s detail popover to send failed GitHub Actions or configured CircleCI job logs to the agent terminal assigned to that branch. A completed failed job can trigger healing while other jobs in the same workflow are still running. The displayed three-attempt budget counts only prompts successfully delivered to the agent; log-fetch and terminal-delivery errors do not consume it.
Auto-heal reads failing checks directly from the selected or local head commit, including external CI links. It uses the repository’s GitHub account and reads every check page before discarding older reruns; the number of open PRs does not limit this lookup.
Set a read-only CircleCI token in Settings > Git & GitHub > CircleCI. The token is never shown again. The Log button on a failed CircleCI check also works for remote-only PRs.
Review State Classification
| Decision | Label |
|---|---|
| APPROVED | Approved |
| CHANGES_REQUESTED | Changes requested |
| REVIEW_REQUIRED | Review required |
Auto-Delete Branch on PR Close
When a PR is merged or closed on GitHub, TUICommander can automatically clean up the corresponding local branch. Configure per-repo in Settings > Repository Settings or set a global default in Settings > Git & GitHub > Pull Requests > Auto-Delete on PR Close.
| Mode | Behavior |
|---|---|
| Off (default) | No action taken |
| Ask | Shows a confirmation dialog before deleting |
| Auto | Deletes silently, only when a fresh inspection proves the branch merged and the checkout safe; otherwise keeps it and says why |
Safety guarantees:
- The default/main branch is never deleted
- A closed PR is not proof of a merge: a closed-unmerged PR keeps its branch in Auto mode
- Uncommitted or untracked files, unpushed submodule commits, live sessions and an unproven or unknown merge state keep the checkout; nothing is forced
- Ask mode re-inspects after you confirm and refuses to delete if the branch tip, local state or sessions changed while the dialog was open
- If a branch has a linked worktree, the worktree is removed first
Retry and Keep:
- A failed deletion (or an inspection that could not run) is retried up to three times (after 5 s, 30 s and 2 min), each time behind a fresh inspection; a successful deletion is never repeated
- Choosing Keep in the Ask dialog is remembered for that PR until you reset it; repeated notifications and a switch to Auto do not override it. The reset is shown on the sidebar row of a checkout marked Keep and only while Keep is set: compact rows show a reset icon, and rich rows show Reset Keep. It needs no restart. Pressing it makes the next PR notification for that checkout be handled again by the current Off/Ask/Auto setting (the hook’s
resetKeep(repoPath, prNumber)). Keep is held in memory only, so it also ends when TUIC quits - While the setting is Off, nothing is recorded, so enabling it later still handles the next notification for that PR
Remote-Only Pull Requests
When a branch exists only on the remote (not checked out locally) but has an open PR, it still appears in the sidebar with a PR badge. These “remote-only” PRs support inline accordion actions:
- Checkout — Creates a local tracking branch from the remote
- Create Worktree — Creates a worktree for the branch
PR Detail Popover Actions
Clicking the PR badge on any branch (local or remote-only) opens the detail popover. Available actions:
| Button | When Shown | What It Does |
|---|---|---|
| View Diff | Always | Opens PR diff in a dedicated panel tab |
| Merge | PR is open, approved, CI green | Merges via GitHub API (auto-detects allowed merge method). The merge is pinned to the head commit the panel showed: if the agent pushed since, GitHub refuses and the panel shows “PR head changed” — refresh and review before merging again |
| Approve | Remote-only PRs | Submits an approving review via GitHub API |
Post-Merge Cleanup
After merging a PR from the popover, a cleanup dialog appears with checkable steps:
- Switch to base branch — if the working directory has uncommitted changes, they are automatically stashed. An inline warning shows with an optional “Unstash after switch” checkbox
- Pull base branch — fast-forward only
- Delete local branch — closes terminals first, refuses to delete default branch
- Delete remote branch — gracefully handles “already deleted”
Steps execute sequentially via the Rust backend (not PTY — your terminal may be occupied by an AI agent). Each step shows live status: pending → running → success/error.
Dismiss & Show Dismissed
Remote-only PRs can be dismissed from the sidebar to reduce clutter. A “Show Dismissed” toggle in the sidebar reveals them again.
GitHub Issues
The GitHub panel shows issues alongside PRs in a unified view.
Issue Filter
Control which issues appear using the filter dropdown in Settings > Git & GitHub or directly in the panel:
| Filter | Shows |
|---|---|
| Assigned (default) | Issues assigned to you |
| Created | Issues you opened |
| Mentioned | Issues that mention you |
| All | All open issues in the repo |
| Disabled | Hides the issues section |
The filter setting persists across sessions.
Issue Details
Expand an issue to see:
- Labels with GitHub-matching colors
- Assignees and milestone
- Comment count and timestamps (created/updated)
Issue Actions
| Action | Description |
|---|---|
| Open in GitHub | Opens the issue in your browser |
| Close / Reopen | Changes issue state via GitHub API |
| Copy number | Copies #123 to clipboard |
PR Row Actions (panel)
Expand a PR in the GitHub panel for these actions, next to Checkout, Merge and Diff:
| Action | When Shown | What It Does |
|---|---|---|
| Update branch | PR is open and GitHub reports it behind its base | Merges the base branch into the PR branch, pinned to the head the panel showed (refuses with “PR head changed” if the agent pushed meanwhile). The merge commit lands on the remote: pull it in any local clone |
| Close | PR is open | Closes the PR without merging, after a confirmation |
| Copy ref | PR has a GitHub URL | Copies owner/repo#number for pasting into prompts |
Open PRs older than two weeks carry an age marker on the row: 2w, 1m, 3m or 6m, measured from the creation date.
PR Diff: collapsed files
In the PR diff tab, lockfiles (pnpm-lock.yaml, Cargo.lock, …), generated files (dist/, *.min.js, *.snap, *.pb.go, files marked linguist-generated in the repo’s .gitattributes) and test files (__tests__/, *.test.*, *_test.go, …) start collapsed. The header shows how many are collapsed; click a file header to expand it. .gitattributes is read from the local checkout, which stands in for the PR’s base when another branch is checked out.
Panel Keyboard Navigation
The GitHub panel is keyboard-navigable without ever moving focus off the panel itself:
| Key | Action |
|---|---|
| ↓ / ↑ | Move between rows, walking across the My Pull Requests, Pull Requests and Issues sections in order. Rows of a collapsed section are skipped. |
| Enter | Expand or collapse the highlighted row |
| Escape | Collapse an expanded issue, or close the panel when nothing is expanded |
Section collapse state is remembered per section and survives closing the panel and restarting the app (stored in the UI prefs alongside panel widths). A section that has never been toggled keeps its own default: PR sections start collapsed when empty, Issues starts open.
Troubleshooting
No PR data showing:
- Check Settings > Git & GitHub — the account must show as signed in
- Check repository has a GitHub remote (
git remote -v) - Check that the repository is bound to the intended account
Stale data:
- Click the refresh button or switch away and back to the branch
- Polling updates every 60 seconds automatically
Merged-PR evidence for worktree and local-branch cleanup uses the GitHub account and host selected for that repository. It no longer depends on the GitHub CLI login. If the complete PR history cannot be read, cleanup does not treat that lookup as proof that a branch was merged.
Tasks notifications
Settings → Notifications → Tasks has OS notifications for Tasks, off by default and independent of the existing PR notification preference. Failed checks on a linked GitHub PR use the existing PR notice once and name the linked Tasks item. Click the notice to open that PR’s Comments section in Tasks, or its GitHub conversation when the provider is not loaded.
Use Follow task in an item detail to follow comments locally; use Unfollow task to stop. Follow state and the policy are saved in the existing Tasks UI preferences. A first observation establishes a silent baseline. Existing visible detail refreshes (including its 60-second refresh) and provider-bridge detail reads compare authoritative comments; there is no extra background poller. Your own comment action advances the baseline silently. Native notices recheck the Tasks policy after permission is granted and retain the existing background-window policy; browser clients do not send native OS notices.
GitHub provides a full normal-comment count, so an increase is detected even beyond the first page. Jira and GitLab provide paged comment entries: newly observed comments notify when their creation time is newer than the prior baseline, or when a previously unseen comment ID shares its latest timestamp. Unloaded pages, unseen review sources and items that are not refreshed cannot produce a notice. Editing a comment or loading older history does not notify. No Linear provider is shipped, so it is not covered.
Existing GitHub logins with only read:project can read Projects but cannot move cards or edit project fields. Log in again from Settings → Git & GitHub to grant project read/write consent. Settings explains missing write consent without disconnecting your account. For external tokens, update the token’s project permissions; organization approval may also be required. Read-only boards keep their cards and show the permission message. PRs, issues, comments and the sidebar retain their existing access. After a project-specific write denial, grant access and reload Tasks. Credentials are not upgraded automatically.
Setup through Settings MCP
After you enable the Settings MCP tool in trusted UI, an assistant can discover the published GitHub owner actions. Cloud setup uses device login; you authenticate on GitHub, and the assistant follows the returned flow state and poll interval. Enterprise PAT setup verifies the host/account before storage. A pending or expired flow is not a connected account. Settings startup workflows documents list_accounts for stable account IDs and credential presence, plus /auth/source for current credential provenance. Enumeration never returns token values or proves a live account login.
Persistent PR visibility filters
Global pr_hide_drafts, pr_hide_conflicting and pr_hide_ci_failing values
persist in config.json and default to false (show all). Each repository stores
nullable overrides in repo-settings.json: null inherits the current global
value, true hides the matching PRs, and false explicitly shows them. Settings
owner transactions preserve unrelated fields, and settings refresh adopts owner
readback without saving it again. The Rust settings catalogue describes both scopes.
Troubleshoot repository access
Settings > Git & GitHub shows repository access failures by owner and account, with GitHub’s exact message. Reasons distinguish NOT_FOUND, FORBIDDEN and unknown responses without inferring organization policy from message wording.
For any github.com OAuth failure, select Grant or request organization access
to open the authorized TUICommander OAuth app page. This action is also available
for NOT_FOUND because pending organization approval can hide private repositories. After granting access, select Refresh status to clear NOT_FOUND retry
delays for all accounts, then wait for the next monitoring poll. Access denials do not require a new
login or a 24-hour wait. Only explicit NOT_FOUND responses keep the 24-hour retry
interval. GitHub can use this response for an inaccessible private repository too.
tuic CLI
The tuic command line tool lets you control TUICommander from the terminal. It combines an editor opener, editor-style integration, and tmux-style session management into a single binary.
Installation
From the app: Settings > General > TUIC CLI > Install TUIC CLI
First launch: TUICommander offers to install the CLI on first run.
From the CLI itself: tuic install-cli
The binary is installed to:
- macOS:
/usr/local/bin/tuic(requires admin password) - Linux:
/usr/local/bin/tuic(requires sudo) - Windows:
%LOCALAPPDATA%\Microsoft\WindowsApps\tuic.exe(no admin needed)
The CLI auto-updates silently when TUICommander starts — no manual update needed.
Install and update stage the new executable beside the installed path, then rename it into place. A running tuic process keeps its original executable; installing over a symlink replaces the link without changing its target.
The CLI status check probes the install directory with a temporary sibling file. It does not open the installed executable for writing: on macOS, even a write-open without changed bytes can invalidate its cached signature.
Opening Files and Repos
# Open a file (launches TUICommander if not running)
tuic file.rs
# Open at specific line and column
tuic file.rs:42
tuic file.rs:42:10
tuic open --goto file.rs:42
# Open the current directory as a repo (adds it to the sidebar and activates it)
tuic .
tuic /path/to/project
# Open with --wait (for use as $EDITOR)
tuic open --wait file.rs
Files open through the selected running server. An OS URL handler is not required.
A directory lands in the sidebar and becomes the active repo. tuic <dir> and tuic open <dir> call the selected running server over local IPC through MCP repo action=add; development builds need no registered OS URL handler. Registration is explicit and takes effect immediately, without a confirmation dialog or a connected desktop window. Reopening preserves existing workspaces, terminals, names and groups. Registration does not create a terminal; use tuic new for a shell. Server errors produce a nonzero exit code.
Temporary directories are refused
tuic <dir> registers the directory permanently — the sidebar keeps it across restarts. A temporary directory therefore becomes a row that points at something the operating system later deletes, and nothing records who added it. tuic refuses such a path instead:
$ tuic "$TMPDIR/scratch"
Refusing to register "/var/folders/.../T/scratch" as a repository: it is inside a
temporary directory, which the OS deletes while the sidebar entry stays behind forever.
For a shell there instead: tuic new /var/folders/.../T/scratch
A path is refused when it is at or below the temp root of the shell you run tuic from (TMPDIR on macOS and Linux, TEMP/TMP on Windows) or below /tmp. Running the check in the CLI rather than in the app is what makes a custom TMPDIR — for example the ~/Gits/.tmp this repository’s Rust suites use — count as temporary; the app process has a different one and cannot see yours.
Only registration is refused. tuic new <dir> still opens a shell in a temporary directory, because a session is disposable in the same way the directory is.
Using as $EDITOR
export EDITOR="tuic open --wait"
git commit # opens commit message in TUICommander
Session Management
These commands mirror tmux semantics:
# List all sessions (short IDs; --json for scripts)
tuic ls
tuic ls --json
# Create a new session
tuic new
tuic new -n "my-session"
tuic new -n "build" /path/to/repo
# Create a session and run something in it
tuic run pnpm dev
tuic run -n "tests" cargo nextest run
# Send input to a session
tuic send <id-or-name> "make test" Enter
# Capture session output
tuic capture <id-or-name>
tuic capture <id-or-name> -n 50 # last 50 lines
tuic capture <id-or-name> --format raw
`capture` supports `raw` and `text`; `--format log` is not supported by the
CLI and returns an error.
# Kill a session
tuic kill <id-or-name>
# Resize a session
tuic resize <id-or-name> 120x40
# Pause/resume output
tuic pause <id-or-name>
tuic resume <id-or-name>
Session targets are resolved by the server. Use the PTY ID, its stable
tuic_session, the terminal alias (for example tu-33), a unique short PTY-ID
prefix, or a unique display name; an ambiguous target is rejected rather than
guessed.
Sending keys
Each argument is either a key name or literal text — matched whole, never as a substring, so tuic send build "Enter the room" types the sentence instead of pressing Return mid-word. Adjacent literals are joined with a single space.
Key names: Enter, Space, Tab, Escape, BSpace, Up, Down, Left, Right, Home, End, PageUp, PageDown, and any C-<letter> (C-c, C-d, C-u, …).
Agent Orchestration
Generic MCP calls
Use tuic mcp <tool> [<json>|-] to call a native MCP tool over the local
socket. Omit the JSON argument for {}, or pass - to read a JSON object from
stdin. The tool’s text payload is printed unchanged with a trailing newline,
so it can be piped to jq:
tuic mcp session '{"action":"list"}' | jq length
tuic mcp agent '{"action":"wait","timeout_ms":8000}'
cat <<'JSON' | tuic mcp agent -
{"action":"send","to":"peer-id","message":"it's ready"}
JSON
tuic mcp init is not a tool: it prints the instructions the server returns from the MCP initialize handshake for the caller’s session (the same text an MCP client reads), for an agent whose MCP connection dropped.
Tool and protocol errors go to stderr with exit code 1. Invalid JSON or CLI
arguments exit 2 before connecting. Managed callers send $TUIC_SESSION for
peer binding; callers outside TUICommander register an external identity for
that invocation.
Workflow actions
tuic workflow [<json>|-] calls the grouped workflow MCP tool. Use a typed action envelope:
tuic workflow '{"action":"definition","input":{"action":"list_drafts"}}'
tuic workflow '{"action":"run","input":{"action":"get","run_id":"run-id"}}'
The other actions are proposal_create, report and launch, each with its typed payload under input. Proposal creation requires the run’s active bound coordinator and a stable proposalKey; retries return the same story. Ordinary story creation is not a substitute. Managed callers retain their caller binding. Stories, plans and Ideas are not workflow actions: MCP clients use the separate story tool, and tuic story still calls the shared story service with --project support; tuic automations still calls the separate scheduler and works when workflow is disabled. The old workflow MCP names are removed without aliases. Reconnect after installing the updated backend to discover the new tool.
Register an existing local directory directly through MCP:
tuic mcp repo '{"action":"add","path":"/absolute/path/to/project"}'
Both forms use the same backend registration operation. Git directories get a
workspace for their checked-out branch; plain directories get a shell workspace.
ui action=tab with a tuic://open-repo URL returns an error directing the caller
to repo action=add.
Detached commands
Run tuic bg <log> -- <cmd> [args...] from a managed terminal to return at
once while the command runs in a separate process group. The command’s stdout
and stderr append to <log>, after a header with the full command, and its exit
code is written to <log>.exit. When it finishes, tuic requests a
BG DONE exit=<code> log=<log> cmd=… wake for the originating session.
The cmd label contains only the first line and at most 120 Unicode characters,
including a final … when text is omitted. Read the log header for the full command. If that session is busy, the wake is queued
until it becomes idle. <log>.wake records the request outcome as JSON:
queued, retained, retrying, or uncertain, with tuic_session, the
completion text and the number of queue attempts. Launch captures a typed wake
origin from the host. If the host is unavailable at launch, the command still runs
but its completion is retained without an automatic wake. A host that predates
wake origins publishes no origin field; then the completion is queued as before,
without Escape revocation, until that host restarts. Escape revokes that origin: old results cannot start a new
turn, even after a later explicit request completes. Already queued explicit
requests remain valid. Logs and receipts remain available for inspection.
queued means the queue took the request, not that the agent later submitted it.
retained means no automatic wake is authorized; do not resend it through mail.
A transient socket or server error retries the same keyed queue request up to
six times with delays of 0.2–3.2 seconds (6.2 seconds total). A permanent error
retains the completion immediately. uncertain means a queue request may have
been accepted but its receipt was lost. There is no mail fallback that could
bypass Escape. Each IPC read has its own
three-second deadline, so a slow or unavailable server can extend the elapsed
time beyond the retry waiting period. The command works
on macOS, Linux, and Windows.
tuic bg "$HOME/Gits/.tmp/build.log" -- make check
The detached command does not inherit TUIC_SESSION or TUIC_PARENT. It is
not the foreground peer: TUIC_BG_COMMAND=1 marks the command tree as an
ancestry boundary, including when an agent scrubs its bridge environment. Its progress reports and agent hooks must not change
the foreground composer state. The runner retains the original caller identity
for completion queueing and mail. Socket, app-instance and other environment
settings remain inherited. A command that needs a peer identity must establish
its own binding instead of using the foreground caller.
On Windows, the detached runner does not inherit the launcher’s input or output pipes. Capturing the launcher output therefore returns before the background command completes.
Each background runner generates one completion key and reuses it on queue
retries. The backend remembers the last 128 accepted keys per live terminal,
so a lost reply does not enqueue the same completion again within that window.
A recognized acceptance remains queued in the wake file even after the queue
has drained. If every queue receipt is lost and mail also fails, the wake file
reports uncertain, not a proven delivery failure; inspect backend state before
retrying manually. uncertain also prevents automatic child closure.
If a BG DONE entry remains in the backend queue for 60 seconds, the backend
records one warning under source bg-wake. Read /logs?source=bg-wake on the
owning instance. Its JSON data reports the composer, question, uncertainty and
foreground gates, process-probe generations, and a fresh process tree for the
foreground group and matching detached runner. It records at most 128 process
rows, marks truncation, and distinguishes an unavailable inventory from an empty
tree. It excludes argv, prompt text and environment values. This warning uses
the normal bounded log ring, not durable delivery storage; collect it before
ring overflow or restart. It does not retry a possibly submitted message or
clear background_work.
TUIC_SESSION is required; without it, tuic bg exits 2 before starting a
command. The launcher prints the wake-status path and removes stale .exit
and .wake files before detaching. If no BG DONE arrives, inspect .exit
for command completion and .wake for both queue and mail failures. Both
errors are also appended to the log. Neither status file can start a new agent
turn while TUICommander is unavailable.
The instance config directory also holds bg-wakes/<TUIC_SESSION>.json. It is
marked retrying while a background command is active or its wake is being
retried, then records the final result. Automatic managed-child idle closure
reads this record and keeps a child open after a failed wake.
# Spawn an AI agent (the prompt is required — the agent starts on it)
tuic agent spawn claude "review the failing tests"
tuic agent spawn codex "add a changelog entry" --repo /path/to/repo
tuic agent spawn codex "review" --name reviewer --model gpt-5 --args exec --args --full-auto \
--cwd /path/to/repo --rows 40 --cols 120 --json
# List running agents
tuic agent ls
# Deliver a message to a registered peer's INBOX (peer registry)
tuic agent send <peer-uuid> "fix the tests"
# Type a prompt into an agent's TERMINAL and submit it (no peer routing)
tuic agent type <id-or-name> "fix the tests"
# Wait for mail or inspect peers without polling
tuic agent wait --timeout-ms 60000 --json
tuic agent inbox --json
tuic agent list-peers --path /path/to/repo --json
tuic agent stats --json
# Server-owned session state and output
tuic session status <id-or-name> --json
tuic session wait <id-or-name> --until idle --timeout-ms 60000 --json
tuic session output <id-or-name> --limit 50 --json
# Server-owned worktree lifecycle
tuic repo worktree-list /path/to/repo --json
tuic repo worktree-create /path/to/repo --branch feature/task --spawn-session --json
tuic repo worktree-remove /path/to/repo <branch> --json
agent wait and session wait size their IPC read timeout from --timeout-ms
(60 seconds by default) with a five-second transport margin. MCP worktree
creation and removal allow 305 seconds on Unix, four seconds beyond the server’s
301-second request limit. Other Unix CLI requests retain a three-second read
timeout, so a stalled app fails promptly. A timed-out MCP action may still
complete on the server; inspect its state before retrying.
The orchestration commands above call the same MCP tools as an agent. They use
the local mcp.sock transport and send $TUIC_SESSION as x-tuic-session, so
a child spawned from a managed terminal records that terminal as its parent.
Outside TUICommander, tuic prints one notice and registers a headerless
external MCP caller. That caller is the parent of a child it spawns, but its
identity lasts only for that tuic invocation, so a later tuic call cannot
read the mail the child sends back.
Use --json for the unmodified server payload. A server error is printed to
stderr and makes tuic exit non-zero.
Two delivery channels, chosen explicitly
tuic agent send and tuic agent type are not interchangeable, and neither
guesses which one you meant.
| Command | Route | Target | Use when |
|---|---|---|---|
tuic agent send | peer registry → recipient inbox | a registered peer’s tuic_session UUID | the recipient is an orchestrator or any peer, including one with no terminal of its own |
tuic agent type | PTY write | a session ID or name | you want the text to appear in a terminal and be submitted |
tuic send | PTY write | a session ID or name | raw keys, no agent framing (see Sending keys) |
tuic agent send is the CLI counterpart of the MCP agent action=send tool and
uses the same delivery path, so both report the same delivery_path and both
land the payload exactly once. It exits non-zero — with the registry’s own
message — when the recipient is not registered or the message is empty.
Acceptance is not delivery, and the output says which one you got:
Delivered to <peer> (sse_channel_and_inbox)
means something surfaced the message — a waiter, the SSE channel, or the recipient’s terminal. Whereas:
Buffered for <peer> (inbox_only) — unread until the recipient polls its inbox
warning: Recipient has NO terminal and no active wait: nothing will wake it. …
means the registry took the message but nothing will wake the recipient: it sits
unread until that peer calls agent action=wait/inbox. Both exit 0, because
the registry accepted the message in both cases — do not block on an answer
after a Buffered line. The CLI validates this current report contract through
message_id, delivered, and delivery_path; it does not require the removed
accepted compatibility field.
tuic agent type keeps the agent-safe framing: the text and the Enter are sent
as separate PTY writes, because a raw-mode Ink TUI treats a combined
text\r as a prefill and leaves it unsent. tuic send does not do this.
tuic agent send uses $TUIC_SESSION when it runs inside a TUICommander
session. Outside one, it registers a headerless external caller for the MCP
connection and prints a notice on stderr. It has no terminal, automatic wake-up,
or managed parent relationship; a spawned child cannot reply to it.
Calling an agent from a script
tuic notify <alias|name|session-id> <text|-> sends the text to the agent’s
inbox through the same registry path as tuic agent send; - reads the text
from stdin. An idle agent is woken, a working one gets a notice. Exit code 0
only when the message reached the agent. An unknown recipient, or a message
stored in the inbox that nothing surfaces, exits 1 with a message naming the
recipient. It needs no register step: outside a TUICommander session the CLI
registers an external caller by itself. An agent can write a script that ends
with tuic notify <its tuic_session> -, hand it to you to run, and receive the
result as mail. The launch rules and tuic mcp init tell agents so.
tmux Compatibility
tuic can act as a drop-in replacement for tmux. When invoked as tmux (via symlink), it translates tmux commands to TUICommander equivalents.
Setting Up the Alias
# Create tmux -> tuic symlink
tuic alias
# Remove the alias (restores original tmux if installed)
tuic alias --remove
Supported tmux Commands
When invoked as tmux, the following commands are supported:
| tmux Command | Behavior |
|---|---|
tmux | Create new session in cwd |
tmux new-session -s name | Create named session |
tmux list-sessions | List sessions |
tmux kill-session -t target | Kill session |
tmux kill-server | Kill all sessions |
tmux send-keys -t target "cmd" Enter | Send input |
tmux capture-pane -t target | Capture output |
tmux resize-pane -t target -x 120 -y 40 | Resize |
tmux attach-session | Focus TUICommander window |
tmux has-session -t target | Check if session exists (exit code) |
Key names are translated: Enter, Space, Tab, Escape, C-c, C-d, C-z, etc.
System Commands
# Check TUICommander status — version, session/agent counts, and which
# sessions are waiting on you right now
tuic status
# Install CLI to system PATH
tuic install-cli
tuic install-cli --path /custom/path
# Create/remove tmux alias
tuic alias
tuic alias --remove
Agent Hook Transport
# Run by the generated agent hooks on native Windows, not by hand
tuic agent-state state idle
tuic agent-state claude busy < event.json
tuic agent-state codex-notify -- <your notify argv> <payload>
agent-state builds the OSC 7770 frames of one hook event and posts them to
the TUIC session in TUIC_SESSION over the local IPC. It is inert without
TUIC_SESSION or a console, never fails its agent, and gives up after 5 s.
See AI Agents for the fallback and ordering rules.
IPC Architecture
The CLI communicates with TUICommander via IPC:
- macOS/Linux: Unix domain socket at
<platform config dir>/com.tuic.commander/mcp.sockfor the default instance. - Windows: Named pipe at
\\.\pipe\tuicommander-mcp(a named instance uses\\.\pipe\tuicommander-mcp-<instance id>)
Use tuic --instance <id> <command> or TUIC_APP_INSTANCE=<id> tuic <command>
to select the same namespace as tuic-remote --instance <id>. An explicit
--instance takes precedence over the environment. Invalid ids fail before any
connection. Named Unix sockets use the server’s short SHA-256-based name in the
server’s temp directory. The server also writes that socket path to mcp-socket
in the instance config directory, and the CLI uses it when the socket exists, so a
shell with a different TMPDIR (for example next to make agent-test) still
reaches the instance. When a named instance is not running, a command that would
start TUICommander fails with an error instead: the CLI starts only the default
app. The bridge accepts tuic-bridge --instance <id> and the same
environment variable; it searches only that instance’s alternative sockets.
On Unix, an explicit CLI --instance overrides both TUIC_APP_INSTANCE and
TUIC_SOCKET. When an inherited socket differs, the CLI prints the selected
socket on stderr. Without --instance, TUIC_SOCKET still overrides the
socket path, including an instance selected by TUIC_APP_INSTANCE. Background
runners inherit the resolved socket target. Windows retains the
existing named-pipe endpoint. The clients and server share instance validation,
config paths and IPC names through tuic-ipc; CLI and bridge also share HTTP
request and response framing.
If TUICommander is not running, tuic open and tuic new will launch it automatically.
Automations
tuic automations accepts a backend action JSON object. It uses the selected
instance’s MCP endpoint and the same validation, results and errors as HTTP/IPC.
tuic automations '{"action":"list"}'
tuic automations '{"action":"update","id":"review","enabled":false}'
tuic automations '{"action":"run_now","id":"review"}'
tuic automations '{"action":"list_runs","id":"review","limit":10}'
tuic --instance staging automations '{"action":"summary","window":"7d"}'
cat definition-action.json | tuic automations -
Actions: list, get, create, update, pause, resume, delete, run_now, run, list_runs,
summary, preview, preview_definition and preset. See the HTTP API Automations
table for the shared input/result shapes. Create and update accept a complete
definition; update also accepts id and enabled instead. Creation records the
bound caller session, including an external MCP identity when run outside TUIC.
Success prints JSON; backend rejection prints its exact message after tuic:
on stderr and exits 1. Invalid CLI JSON exits 2.
Automation templates (#1622-be11): the shared automation action accepts templates (catalogue) and template (draft). Draft inputs are template_id, repository, run_config and optional timezone (host local by default). Drafts have fresh ids and start disabled; no definition or run is created until an explicit create action. These actions match across HTTP, IPC, MCP and CLI.
Design Mode through MCP UI actions
Use tuic mcp ui '{"action":"design_start","session_id":"<terminal>","url":"http://localhost:3000"}' to start Design Mode. Browser commands use design_stop, design_reload, design_navigate, design_screenshot, design_errors or design_eval with repo_path from the lifecycle result; design_navigate also needs url, and design_eval needs script and accepts result_offset for the next result page. design_status lists bindings for an armed caller. Caller ownership and sidebar host consent still apply. The old tuic mcp design_mode entry is removed with no alias. Also replace literal task calls with tuic mcp agent task_get/task_cancel, and story/workflow_* calls with tuic workflow and its typed actions. Reconnect cached MCP clients and review external allow rules for the grouped domains.
Typed report example: tuic agent send <peer> "Ready for review" --report-state ready.
Use --report-state waiting --wait-for boss --question-json '<question object>'
for a structured question. tuic mcp agent '<JSON>' accepts the identical MCP
payload. Required message text and legacy mail behavior stay unchanged.
See typed reports.
Background command deadline
tuic bg runs a detached command with a finite deadline: one hour by default.
Set TUIC_BG_TIMEOUT_SECONDS before launch to choose 1 through 86400 seconds.
Invalid values refuse launch. The child command gets its own process group on
Unix; on Windows timeout stops the owned process tree. At the deadline the runner
stops that group/tree, waits for its child to exit, writes 124 to <log>.exit,
records background deadline exceeded in the log and sends the normal
BG DONE exit=124 wake. Other jobs and the caller remain running. Commands that
deliberately detach into a different Unix group are outside this group boundary.
Plugins
TUICommander has an Obsidian-style plugin system. Plugins can watch terminal output, push notifications to the Activity Center, render markdown panels, control PTY sessions, and more.
Installing Plugins
From the Community Registry
- Open Settings (
Cmd+,) → Plugins tab → Browse - Browse available plugins — each shows name, description, and author
- Click Install on any plugin
- The plugin is downloaded and activated immediately
An “Update available” badge appears when a newer version exists in the registry.
Registry plugins include file viewers such as DOCX Preview, which opens Word .docx/.dotx files from the File Browser as an HTML preview tab; XLSX Preview, which opens Excel and OpenDocument spreadsheets as sortable tables; and SQLite Viewer, which browses schema and indexes, filters and paginates rows, explains read-only queries, copies CSV, and explicitly edits primary-key tables for .db, .sqlite, .sqlite3, .db3, and .s3db files. SQLite Viewer bundles its JavaScript and WebAssembly engine, makes no CDN request, and releases its live database engine when the viewer tab closes. Stock sql.js cannot open SQLCipher-encrypted databases; the viewer reports that case instead of prompting for an unusable key.
From a ZIP File
- Open Settings → Plugins → Installed
- Click Install from file…
- Select a
.ziparchive containing the plugin
Via Deep Link
Click a link like tuic://install-plugin?url=https://example.com/plugin.zip — TUICommander shows a confirmation dialog, then downloads and installs the plugin. Only HTTPS URLs are accepted, plus plain http:// from localhost or a loopback address (for a ZIP you serve yourself); redirects to any other plaintext host are refused.
Manual Installation
Copy the plugin directory to:
- macOS:
~/Library/Application Support/com.tuic.commander/plugins/my-plugin/ - Linux:
~/.config/tuicommander/plugins/my-plugin/ - Windows:
%APPDATA%/com.tuic.commander/plugins/my-plugin/
A plugin directory contains at minimum manifest.json and main.js.
Managing Plugins
Loaded configurable plugins publish individual settings through a scoped settings service. Saved legacy configuration is retained and validated on load. Changes schedule a plugin reload; a stale revision or invalid batch writes nothing. Secret settings show only whether a value is set. Disabling/unloading removes the plugin settings from discovery.
Work-item provider data
GitHub Work, Jira and GitLab use Tasks-owned data/work-items.json for provider accounts. Configure these accounts from Tasks, not from a plugin Settings page. The reserved data/config.json requires a settings schema and must not be used for these accounts.
If an older GitHub Work installation reports Configurable plugin requires a settings schema, first install the app and plugin versions that use work-items.json. With the app stopped, back up the old data/config.json and move it to data/work-items.json in that plugin’s installed directory. Do not overwrite an existing destination or change the file contents. Restart the app and check that the plugin loads. This is a one-time operator action; the app does not read the old file as a fallback.
GitHub Work post-login verification
The account HTTP port, runtime catalog and account-scoped B6/B7 ports are already integrated. A recorded-fixture pass is not proof of desktop loading or a successful account login.
An operator can run a read-only check after login:
-
Start a separate desktop verification instance with
TUIC_APP_INSTANCE=github-work-check. Do this only when you can release the global dictation shortcut and microphone. An agent must not start a second desktop app. Do not use the production instance or its sessions. -
In that instance, install and enable GitHub Work. Complete GitHub device-flow login in Settings, with
repo projectconsent. Configure the account and repository in Tasks. An old authorization without Projects access needs new consent. -
Select an accessible issue URL, PR URL and Projects v2 node ID (
PVT_...). The project must have a single-select Status field. Confirm the verification instance’s HTTP port; it must not be9876. -
Set these non-secret values once in your shell:
export GH_WORK_CHECK_URL=http://127.0.0.1:9877 export GH_WORK_CHECK_ACCOUNT=github.com export GH_WORK_CHECK_ISSUE=https://github.com/OWNER/REPO/issues/NUMBER export GH_WORK_CHECK_PR=https://github.com/OWNER/REPO/pull/NUMBER export GH_WORK_CHECK_PROJECT=PVT_REPLACE_WITH_PROJECT_NODE_ID
After login and setup, the check is one command from the checkout:
node scripts/github-work-live-check.mjs "$GH_WORK_CHECK_URL" "$GH_WORK_CHECK_ACCOUNT" "$GH_WORK_CHECK_ISSUE" "$GH_WORK_CHECK_PR" "$GH_WORK_CHECK_PROJECT" --isolated-desktop
The explicit flag confirms that the selected port belongs to the isolated desktop; the script cannot identify an instance from its port alone. The script refuses port 9876 and non-loopback URLs. It does not start an app, inspect credential stores, authenticate or change GitHub data. It checks the real desktop plugin loaded state, then imports a fresh installed module graph and uses temporary local registrations with the real Rust account ports. This is not a second activation of the installed plugin. It reads search, issue/PR detail, bounded comment pages, duplicate candidates, B6 threads, B7 action state and Projects board/roadmap data. It allows at most 24 port calls and waits at most 90 seconds for its result. The report contains check names and counts, not response bodies or credentials. Exit 0 means these reads passed; exit 1 identifies the failed stage; exit 2 means invalid arguments. A timeout does not cancel an in-flight backend read.
This probe does not prove Tasks rendering, the actual Tasks registry’s unload cleanup, start-work delivery or live mutations. Those remain separate checks. Shut down only the verification instance when finished. Until the operator runs it, the account/desktop integration criterion remains unchecked.
Registered-provider desktop E2E
For an authorized agent-test-<name> desktop, use the Unix socket printed by
make agent-test AGENT_TEST_DRY_RUN=1. Install GitHub Work through the desktop
installer. Configure exactly one account with repository
sstraus/tuic-test-sandbox in its data/work-items.json. Complete that instance’s
Device Flow with the same account. Supply a sandbox issue with a comment and a
sandbox PR with a review thread:
node scripts/github-work-desktop-e2e.mjs "$GH_WORK_CHECK_SOCKET" sstraus 1 2 --isolated-desktop
This E2E uses the installed plugin’s existing registration and actual Tasks UI. It reads both items, opens their details, and pages PR comments into the B6 review thread. It also reads the B7 state through the production account-scoped IPC port. It does not replace modules, register a test host, or mock HTTP. It sends no GitHub mutations. Projects, start-work, unload cleanup, and B7 mutation behavior remain separate checks. The result contains check names, not private response bodies. The outer result deadline is 450 seconds.
Append --preflight-only to check plugin load, sandbox configuration and Tasks
mounting before login. A preflight success is not authenticated E2E evidence.
The socket must be below ~/Gits/.tuic/tuic-at/; there is no default-app target.
Stop the selected instance with the matching make agent-test-stop variables.
Provider closure prerequisites
A private headless backend and a worktree Vite frontend isolate backend state,
but the normal browser loader skips user plugins before discovery. They do not
provide an equivalent loaded-user-plugin E2E. Do not work around this by faking
Tauri globals, manually substituting a host, or mocking authenticated HTTP. An
agent must not start an ordinary second desktop app to bypass this limitation.
An explicitly authorized make agent-test instance is the isolated desktop
verification path; use a unique agent-test-<name> instance and port.
The remaining checks need operator input:
- GitHub Work integration: complete device-flow login for a test account with
repo project; configure its repository in Tasks; supply an accessible issue, PR and Projects v2 project. In an approved loaded-plugin runtime, run the read-only probe above and separately check the actual Tasks views. - GitHub create metadata E2E: authorize one issue creation in a named scratch repository. With the installed plugin loaded, open Tasks → New task, select Issue, confirm repository labels/milestones/assignees load, then submit the authorized issue and read back its repository and metadata. Record its URL. Discovery alone and the read-only probe do not prove issue creation.
- Jira recordings: authorize a test site/account and read-only collection of issue transitions, comment pages and agile board configuration with a multi-status column. Keep the observed 429/Retry-After boundary unverified until a real response is available; do not force a rate limit. Account verification and post-write ADF read-back remain separate boundaries; the latter needs explicit scratch-project write consent. The Jira fixture README lists recorded and synthetic evidence separately.
Enter credentials only through the core account login. Do not send them in chat, copy them from token stores, or commit them with fixtures. Until these prerequisites and the real-runtime checks are satisfied, keep the corresponding integration, recorded-fixture and create-E2E criteria unchecked.
Settings → Plugins → Installed
The Installed tab lists all installed plugins:
- Toggle switch — Enable or disable a plugin. Disabled plugins are not loaded but remain installed.
- Logs — Click to expand the plugin’s log viewer. Shows recent activity and errors (500-entry ring buffer).
- Uninstall — Remove the plugin directory (confirmation required).
Error count badges appear on plugins that have logged errors.
Preinstalled External Plugins
Plan Tracker and Stories Ticker are ordinary external plugins. TUICommander installs them once when upgrading from the compiled-in implementations, after which they can be disabled, uninstalled, or updated like any other plugin. An explicit uninstall is permanent; later launches do not recreate the plugin.
External plugins load in the desktop app. Browser/PWA mode does not execute locally installed plugin code, so these two integrations are unavailable there.
How Plugins Work
Plugins interact with the app through a PluginHost API organized in 4 capability tiers:
| Tier | Access | Examples |
|---|---|---|
| 1 | Always available | Watch terminal output, add Activity Center items, provide markdown content |
| 2 | Always available | Read repository list, active branch, terminal sessions (read-only) |
| 3 | Requires capability | Send input to terminals (pty:write — raw writePty or agent-aware sendAgentInput), open markdown panels (ui:markdown), play sounds (ui:sound), read/list/watch files (fs:read, fs:list, fs:watch) |
| 4 | Requires capability | Invoke whitelisted Tauri commands (invoke:read_file, invoke:list_markdown_files) |
Capabilities are declared in the plugin’s manifest.json. A plugin without pty:write cannot send input to your terminals.
Activity Center
The toolbar bell icon is the Activity Center. Plugins contribute sections and items here:
- Sections — Grouped headings (e.g., “ACTIVE PLAN”, “CI STATUS”)
- Items — Individual notifications with icon, title, subtitle
- Actions — Click an item to open its detail (usually a markdown panel), or dismiss it
The bell counts active, dismissible notifications. Static plugin status rows and dashboard launchers stay visible without adding to the badge.
Hot Reload
When you edit a plugin’s files, TUICommander detects the change and automatically reloads the plugin — no restart needed. Save main.js and see changes in seconds.
Example Plugins
TUICommander ships with example plugins in examples/plugins/:
| Plugin | What it does |
|---|---|
hello-world | Minimal example — watches terminal output, adds Activity Center items |
auto-confirm | Auto-responds to Y/N prompts in terminal |
ci-notifier | Sound notifications and markdown panels for CI events |
repo-dashboard | Reads repo state, generates dynamic markdown summaries |
report-watcher | Watches terminal for generated report files, shows them in Activity Center |
Writing Your Own Plugin
See the Plugin Authoring Guide for the full API reference, manifest format, capability details, structured event types, and testing patterns.
Troubleshooting
| Problem | Fix |
|---|---|
| Plugin not appearing | Check that manifest.json exists and id matches the directory name |
| “Requires app version X.Y.Z” | Update TUICommander or lower minAppVersion in the manifest |
| “Requires capability X” | Add the capability to the capabilities array in manifest.json |
| Changes not taking effect | Save the file again to trigger hot reload, or restart the app |
| Plugin errors | Check Settings → Plugins → Logs for the plugin’s error log |
For a module import failure, retain the error-level application log from source
plugin, including its data. It records the import URL, error name/message,
status when known, attempt number, document ID and load ID. A null status means
that the module loader did not expose a response status. An import failure is
retried after 1 second and then 3 seconds, with at most three attempts per load.
Success clears the load error through normal activation; a permanent failure stays
visible with the plugin enabled but unloaded. Disabling or reloading the plugin
retires pending import recovery. Validation and activation errors are not retried.
These waits do not time out a pending native import. The reported all-plugin boot
failure remains unattributed; a later successful startup does not establish its cause.
Repository-aware plugins discard scans started before a repository switch or unload. The MDKB status ticker refreshes when you select another repository. When MDKB reports that hook telemetry is disabled, its dashboard shows Hook telemetry is off instead of activity counts or timing metrics. Hooks can still run while telemetry is off. When telemetry is enabled but no hook events are recorded, the Hooks section shows No hook activity recorded.
Automatic retry and wakeup decisions are cancelled when the agent resumes work, user input or a dialog changes its state, the session closes, or the plugin unloads while the composer is being inspected.
CSV, DOCX and XLSX previews keep files from different repositories in separate panels, even when their file names match. Reopening the same file reuses its panel.
The community catalogue declares each shipped plugin’s permissions, agent targets, CLI binaries and minimum app version. Dashboard plugins need at least v1.0.3; MDKB and RTK dashboard lifetime handling needs v1.7.6. SQLite’s panel bundle keeps its ES2022 JavaScript target.
In the Tasks board, lane counts say how many cards are loaded. Select More in any lane to load the next board page across all lanes. Cards show assignees and labels. Select Move… for a destination menu; unavailable transitions are disabled. Use the arrow keys to navigate, Enter to move, or Escape to close. Scroll inside the menu to reach more destinations. After a move, page one refreshes while other loaded cards remain visible; reload to refresh later pages.
Remembered Tasks views
Tasks restores your selected source for each repository. Each provider account keeps its own List, Board or Roadmap choice and list group, sort, preset, search and filters. These choices survive closing Tasks and restarting the app. If a provider stops accepting a saved sort, Tasks retries the last accepted sort, then the provider default.
Tasks start-work template
Add .tuic-start-work.md beside .tuic.json in your repository root to customize
the brief sent by Tasks Start work. For example:
Work on {{key}}: {{title}}
Source: {{url}}
Read the repository instructions before making changes.
The file is read on each action. The three placeholders are replaced once; unknown placeholders remain literal. Without a template, Start work uses the item key, title and body as before. A template replaces that entire brief. Item control characters are removed before substitution. The delivered result retains the 12,000-character cap and untrusted-content wrapper. Read errors are shown before a worktree is created.
Jira query errors
In Tasks search, prefix a query with jql: to require JQL, or text: for
literal text. Jira parse errors stay visible with the input unchanged. A previous
result page remains marked as stale until a corrected query succeeds. Issue keys
and saved-filter predicates such as filter = 28712 keep their usual meaning.
Tasks small-list mode (#1851-7ade): when the provider reports at most 1,000 matches, Tasks collects the complete search/preset scope and uses the Rust projection for all-field sort, group and filter. A changed total, missing rows or a nonterminal cursor cannot establish completeness. Unknown totals and larger lists keep provider-supported server controls. No extra cache or persisted state is added.
GitHub Tasks boards (#1846-55d7): the optional provider listBoards(signal) port discovers the current user Projects v2 when Board opens. The existing picker selects a project; paging preserves project identities. Missing read:project stays visible instead of claiming there are no boards. Providers without discovery retain their configured boards. Discovery does not persist selections or write to GitHub.
Async plugin startup completes before the plugin is marked as loaded. Startup failures appear in the plugin error state and its log. Disabling or reloading a plugin cancels its startup lifetime and prevents late registrations from the old host.
Cancelling Jira URL resolution stops its in-flight HTTP requests. Plugins can also cancel their own HTTP requests; unloading a plugin cancels its active requests.
To let a plugin call a development service on your machine or LAN that its manifest does not list, add a URL pattern to plugin_http_destinations in config.json, for example ["http://192.168.1.20:3000/*"]. Use the same syntax as manifest allowedUrls. Every net:http plugin can then reach that service without an account. Only http and https work. Account credentials are never sent to these destinations unless they are under the account host. Edit the file with the app stopped, or use the configuration save API; a settings API write from an agent that adds a pattern needs your confirmation.
Jira and GitLab expose a default project in their schema-driven plugin settings page. Jira uses a project ID; GitLab accepts a project path or ID. A project saved for an account in Tasks setup takes precedence. The default applies after the plugin reloads; empty means no fallback project. Account bindings remain in data/work-items.json, while these defaults use the settings service in data/config.json.
Same-version updates
An Update badge can also mean that installed payload files differ from the
catalogue at the same version. User settings in data/ do not cause this badge.
The app computes installed identity when it discovers plugins; Refresh updates
the catalogue. Older catalogue entries without a payload digest use version-only
comparison. A newer locally installed version is not downgraded.
MCP Proxy Hub
TUICommander can act as a universal MCP (Model Context Protocol) proxy. Instead of configuring the same MCP servers in Claude Code, Cursor, and VS Code separately, you configure them once in TUICommander. All your AI clients connect to TUICommander’s single /mcp endpoint and get access to every upstream tool automatically.
How It Works
Claude Code ──┐
Cursor ───────┼──▶ TUICommander /mcp ──┬──▶ GitHub MCP
VS Code ──────┘ ├──▶ Filesystem MCP
└──▶ Any MCP server
When a tool call arrives at TUICommander’s MCP endpoint, it routes the request to the correct upstream server and returns the result. Upstream tools appear prefixed with the server name — for example, a tool called search_code from an upstream named github becomes github__search_code.
The MCP server must be running. Settings > MCP > HTTP API Server shows its status.
Adding an Upstream Server
Open Settings > MCP > Upstream MCP Servers. Click + (Add upstream server) and fill in:
HTTP Server
Use this for MCP servers that expose a Streamable HTTP endpoint.
| Field | Example | Notes |
|---|---|---|
| Name | github | Lowercase letters, digits, hyphens, underscores only |
| Type | HTTP | |
| URL | https://mcp.example.com/mcp | Must be http:// or https:// |
| Timeout | 30 | Seconds per request. 0 = no timeout |
| Enabled | On | Uncheck to disable without removing |
Stdio Server
Use this for locally installed MCP servers (npm packages, Python scripts, etc.) that communicate over stdin/stdout.
| Field | Example | Notes |
|---|---|---|
| Name | filesystem | Same naming rules as above |
| Type | Stdio | |
| Command | npx | Executable name or full path |
| Args | -y @modelcontextprotocol/server-filesystem | Space-separated |
| Env | ALLOWED_PATHS=/home/user | Optional extra environment variables |
| Enabled | On |
Click Save. TUICommander connects immediately — no restart required.
Server Names
The server name becomes the namespace prefix for all its tools. Choose names that are:
- Descriptive and short (
github,filesystem,db) - Lowercase only
- No spaces, dots, or capital letters — only
[a-z0-9_-] - Unique (no two servers can share a name)
Authentication
For HTTP upstream servers that require a Bearer token:
- Go to Settings > MCP > Upstream MCP Servers
- Find your server in the list
- Click the key icon next to it
- Enter your token
The token is stored in the OS keyring (Keychain on macOS, Credential Manager on Windows) — never in the config file.
To remove a credential, click the key icon and leave the field empty, then save.
Tool Filtering
You can restrict which tools from an upstream are exposed to downstream clients. Edit a server and set the filter:
Allow list — only these tools are exposed:
Mode: allow
Patterns: read_*, list_*, get_*
Deny list — all tools except these are exposed:
Mode: deny
Patterns: delete_*, rm, drop_*, exec_*
Patterns support a trailing * for prefix matching. Exact names also work. There is no other wildcard syntax.
Upstream Status
Each upstream server has a status indicator:
| Status | Meaning |
|---|---|
| Connecting | Handshake in progress |
| Ready | Connected, tools available |
| Circuit Open | Too many failures, retrying with backoff |
| Disabled | Disabled by you in config |
| Failed | Permanently failed — manual reconnect needed |
Circuit breaker: If an upstream fails 3 times consecutively, TUICommander stops sending requests to it briefly. Retries use exponential backoff starting at 1 second, capping at 60 seconds. After 10 retry cycles without recovery, the server is marked Failed.
To reconnect a Failed server, click Reconnect next to its name in the settings panel.
Health Checks
TUICommander probes every Ready upstream every 60 seconds to verify it is still responding. If a probe fails, the circuit breaker activates. If a Circuit Open server’s backoff has expired, the health check also attempts recovery.
Hot-Reload
Adding, removing, or changing upstream servers takes effect immediately when you click Save. TUICommander computes a diff and only reconnects servers that actually changed — unchanged servers are never interrupted.
Troubleshooting
The upstream shows “Failed”
- Check the server URL or command is correct.
- Verify the server process is running (for stdio servers).
- Check credentials are set if the server requires authentication.
- Click Reconnect to retry.
Tools are not appearing
- The upstream must be in
Readystatus for its tools to be included. - Check that a tool filter is not hiding the tools you expect.
- Reconnect and check the error log (Cmd+Shift+E) for initialization errors.
“Circular proxy” error
The HTTP URL you configured points to TUICommander’s own MCP port. This would create an infinite loop. Use a different URL or port.
“Invalid URL scheme” error
Only http:// and https:// URLs are accepted. Other schemes (ftp, file, javascript, etc.) are rejected for security.
Stdio server crashes immediately
- Confirm the command exists on PATH (or use the full absolute path).
- Check the
Argsfield for typos. - Use the error log (Cmd+Shift+E) to see the stderr output from the child process.
- Note: the server cannot be respawned more than once every 5 seconds (rate limit).
Credential not found
If the upstream returns 401 errors:
- Go to Settings > MCP > Upstream MCP Servers.
- Click the key icon for the server.
- Re-enter the Bearer token and save.
The credential lookup uses the server name as the keyring key. If you renamed the server, the old credential is no longer found — re-enter it under the new name.
Example: Connecting the MCP Filesystem Server
Install the server:
npm install -g @modelcontextprotocol/server-filesystem
Add it in Settings > MCP > Upstream MCP Servers:
- Name:
filesystem - Type: Stdio
- Command:
npx - Args:
-y @modelcontextprotocol/server-filesystem /path/to/allowed/dir
After saving, the tool filesystem__read_file (and others) will appear in your AI client’s tool list.
Example: Connecting a Remote HTTP MCP Server
- Name:
github - Type: HTTP
- URL:
https://api.example.com/mcp - Timeout: 30
Set the Bearer token via the key icon in settings. Tools appear as github__search_code, github__create_issue, etc.
Security Notes
- Config files (
mcp-upstreams.json) never contain credentials — only the upstream name is stored. Tokens live in the OS keyring only. - Stdio servers run with a sanitized environment. Your shell secrets (
ANTHROPIC_API_KEY,AWS_SECRET_ACCESS_KEY, etc.) are not inherited by spawned MCP processes. OnlyPATH,HOME,USER,LANG,LC_ALL,TMPDIR,TEMP,TMP,SHELL, andTERMare passed through. Add anything else explicitly in theEnvfield. - Self-referential HTTP URLs (pointing to TUIC’s own MCP port) are rejected to prevent circular proxying.
- Only
http://andhttps://URL schemes are accepted.
Remote Access
Headless GitHub monitoring
tuic-remote supports the same GitHub poller controls and repository status, PR and issue reads as the desktop server. Use /repo/github-poller/start and /repo/github-poller/stop over its Unix socket or authenticated HTTP API. Poller events reach /events without a WebView. GitHub account setup and mutation routes are not exposed by the headless router. A repository without a GitHub remote needs no GitHub credentials for a lifecycle check.
Access TUICommander from a browser on another device on your network.
Setup
- Open Settings (
Cmd+,) → Remote Access - Configure:
- Port — Default
9876(range 1024–65535) - Username — Basic Auth username
- Password — Basic Auth password (stored as a bcrypt hash, never in plaintext)
- Port — Default
- Enable remote access
Once enabled, the settings panel shows the access URL: http://<your-ip>:<port>
On macOS, TUICommander can use the installed Tailscale app when no tailscale
CLI is on its PATH, including launches from Finder. Status detection, peer lookup
and certificate requests always set TAILSCALE_BE_CLI=1 on the Tailscale child
process, including executables found on PATH that can be symlinks to the app.
You do not need to set this variable globally or launch TUICommander from a
terminal. The parent process environment does not change.
The Tailscale HTTPS status reports HTTPS active only while the server has loaded a certificate and its TLS listener is running. Tailscale’s HTTPS capability alone is not enough. If it says Running (HTTPS unavailable), enable Remote Access and select Recheck. If it remains unavailable, inspect the Tailscale certificate errors in the app logs. Connect URLs use HTTPS only while that listener is active.
The macOS app’s CLI runs in a filesystem sandbox. TUICommander reads certificate
and key PEM from its stdout instead of asking it to write into the caller’s
temporary directory; this avoids operation not permitted on certificate writes.
Connecting from Another Device
- Open a browser on any device on the same network
- Navigate to the URL shown in settings (e.g.,
http://192.168.1.42:9876) - Enter the username and password you configured
- TUICommander loads in the browser with full terminal access
QR Code
The settings panel shows a QR code for the access URL — scan it from a phone or tablet to connect quickly. The QR code uses your actual local IP address. It refreshes when the selected address, listener TLS state or port changes, or after you regenerate the access token. Unchanged status polls keep the current QR code.
The Remote Mobile Connection dialog shows the complete connection URL as selectable text. Use Copy URL to copy it; the action shows Copied after success.
If local IP discovery fails, the settings controls and QR dialog remain open. The network address area shows the error and a Retry action. Retry repeats address discovery without changing the saved remote-access configuration.
What Works Remotely
The browser client provides the same UI as the desktop app:
- Terminal sessions (via WebSocket streaming)
- Sidebar with repositories and branches
- Diff, Markdown, and File Browser panels
- Keyboard shortcuts
- Compose commands queued through the same agent idle gate as the desktop app; clearing the Compose queue leaves pending peer messages intact
- Notification sounds, including the distinct G4→G4→E5 Attention callback, through the browser audio fallback
The terminal stream is compressed over a remote link, and only over one. A
remote browser asks the daemon to deflate the WebSocket frames carrying the
terminal, which takes a repainting agent’s traffic to a few percent of its size —
measured at 5.8% over a real session. A browser on the same machine asks for
nothing and pays nothing, and a client reaching the daemon through an SSH tunnel
is compressed by the tunnel instead (see Compression under SSH Tunnels below),
never twice. Nothing to configure: the client decides from whether the session
belongs to a remote connection. An older browser that cannot inflate simply reads
the uncompressed stream, and so does a new browser talking to a daemon too old to
compress — the daemon has to accept the request on the handshake before the
browser uses it, so the two can never disagree about what is on the wire. The
exact framing is in
docs/api/http-api.md.
Security
- Authentication — QR URL token, session cookie or Basic Auth with bcrypt-hashed passwords. HTTP requires credentials even from this computer or the LAN; the old LAN authentication bypass no longer applies. Local CLI/MCP IPC remains available without HTTP credentials.
- Failed sign-ins — After 5 different wrong passwords from one address within 5 minutes (
auth_rate_limit_max,auth_rate_limit_window_secs), that address must wait until the window ends, even with the correct password. The login page shows the wait. To sign in at once, scan the QR code in Settings → Remote Access on the host computer; a QR sign-in also clears the lockout for that address. - Secret storage — Session tokens, relay bearer tokens, and push VAPID
private keys are stored in the OS keyring-backed credential vault; config
files and
/configresponses expose only non-secret settings and existence flags - Local network only — The server binds to your machine’s IP; it’s not exposed to the internet unless you configure port forwarding (don’t do this without a VPN)
- Browser request protection — The HTTP listener rejects foreign Origin headers and unknown Host names before authentication. Use its literal IP or detected Tailscale FQDN; browser/PWA requests from that same server and bundled/development WebViews remain supported. CORS does not allow arbitrary websites.
MCP HTTP Server
Separate from remote access, TUICommander runs an HTTP API server for AI tool integration:
- The server always listens on an IPC listener: Unix domain socket at
<config_dir>/mcp.sockon macOS/Linux, or named pipe\\.\pipe\tuicommander-mcpon Windows - AI agents connect via the
tuic-bridgesidecar binary, which translates MCP stdio transport to the IPC listener - Bridge configs are auto-installed on first launch for supported agents (Claude Code, Cursor, Windsurf, VS Code, Zed, Amp, Gemini, Codex, Grok, opencode, Droid, goose, pi) — and only for the ones present on the machine, so TUICommander never creates a config directory for a tool you do not have. On every subsequent launch, the bridge path is verified and updated if stale (from reinstalls, updates, or moves)
- The
mcp_server_enabledconfig key controls whether MCP protocol tools are exposed, not the server itself - Settings → MCP → HTTP API Server shows server status and active session count
- Local MCP callers submit one managed-agent command with
session action=submit; the same response reports child terminal movement or a precise timeout, so callers must not split text/Enter or poll afterward. Rawsession action=inputremains write-only. Mutating session actions, includingsubmit, agent spawn, launch and mail, are available to a remote MCP client that signs in with the URL token, session cookie or Basic Auth; a client without credentials gets none of them
The Unix socket is accessible only to the current user (filesystem permissions) and requires no authentication — it’s designed for local tool integration, not remote access.
Mobile Companion
TUICommander includes a phone-optimized interface for monitoring agents from your phone.
Accessing the Mobile UI
- Enable remote access (see Setup above)
- Navigate to
http://<your-ip>:<port>/mobilefrom your phone - Log in with your credentials
Opening / also offers the form login. iPad Safari selects the touch interface, including when it requests the desktop website with a Mac user agent. Desktop browsers keep the full interface. In that interface, Add Repository browses folders on the computer running TUICommander, starting at its home directory; it does not browse the device opening Safari.
At widths of 768 px or more, tap Markdown in the session top bar to open a desktop Markdown tab from the same repository. On phones, open More session actions → Markdown instead. The list refreshes in place when desktop tabs change; ordinary session polls do not reset it. Each absolute file path appears once; files in different worktrees stay separate.
The session actions menu scrolls within the available session area. Scroll down to reach Copy session ID and Terminate session. Claude/Codex account usage names the provider, plan and quota window, with the percentage used and reset time in your device’s local timezone. The desktop usage cards use the same descriptions.
After you tick Markdown checkboxes, save source edits, or add block comments, use Agent and Send to request changes. The session you opened Files from is selected when available; you can choose another agent in the same repository. A transient toast says whether the request was delivered now or queued for the agent’s next idle window. Commented blocks use the same amber highlight as desktop Markdown. Failed requests keep the changes available to send again.
In Sessions → New session, the Agent picker lists installed CLI agents from the shared registry, including ego. Git and direct API entries are excluded. The first installed agent is selected. Creation stays disabled while detection runs or when no agents are installed; detection failures show an error instead of a fallback list.
Add to Home Screen
The iOS PWA uses a non-overlay status bar. On the tested iPhone simulator, the previous translucent setting left a 62pt band outside the drawable content area; adding that height to the CSS shell only clipped the composer. The non-overlay setting removes the band while shell height and position continue to follow visualViewport.height and visualViewport.offsetTop. The CLI composer retains its compact 4px bottom padding; no extra safe-area gutter is added.
Existing iPhone Home Screen installs: remove the installed PWA and add it from Safari again after this update. iOS reads the status-bar setting at installation; a normal page reload does not update that installed setting. Physical iPhone confirmation is still pending. If the band remains after reinstallation, capture the device screen, iOS version, orientation and keyboard state before reloading.
The mobile UI supports PWA (Progressive Web App) installation:
- iOS Safari: Tap Share → “Add to Home Screen”
- Android Chrome: Tap the three-dot menu → “Add to Home screen”
The app launches in standalone mode (no browser chrome) for a native-like experience.
Historical title-fade report, before the non-overlay status-bar change. In the installed PWA the “TUICommander” title in the top bar may look soft or faded, strongest at the top edge. We attribute this to the iOS status-bar edge effect, not to the app. Evidence: in a 390x844 mobile emulation with a 62 px top safe-area inset, the computed styles of the title and every ancestor up to html have opacity: 1, and filter, backdrop-filter, text-shadow, mask-image and mix-blend-mode all none, so nothing in our CSS fades it. Limit: this is an inference from the absence of a CSS cause; no iPhone layer inspection was possible, so it is not confirmed on a device.
Long file paths in mobile CLI output wrap inline with the surrounding text and keep the line’s hanging indent. Tap a path to open it, or focus it and press Enter or Space.
At phone widths up to 430 px, the session header keeps CLI/Chat one tap away. Open More session actions for Start voice call / Stop voice call (with the same handset icon as the header) and session tasks. Tablet headers keep these controls directly in the bar. Tap the session name for details.
A choice answer stays bound to the terminal that showed the question, even if you leave the detail screen while its keys are being sent. A failed send shows an error and enables the choice buttons again. Send and Queue also keep their original terminal.
For Claude sessions on a phone, tap Chat in the session header. This switches the reading surface without closing the terminal or clearing its history; returning to CLI follows the latest output. Expand the tool activity and edit to read its Old and New text. Tab stops align at four spaces. Swipe the edit block sideways for long lines rather than wrapping coloured terminal rows. Switch back with CLI for permission prompts. Startup trust, external-file imports, permission prompts and selection lists keep their option rows and interaction footer. Edit excerpts are bounded to 20,000 characters per version; an ellipsis marks a truncated excerpt. A failed tool card describes a proposed edit, not a successful file change.
In a terminal, a down-arrow appears to the right of Send while CLI or Chat output is scrolled back. Tap it to return to the latest output. It does not send terminal input or cover the key-bar controls.
Paste an HTTP(S) link into either mobile composer to add a separating space before you continue typing. Text that ends in a link gets the same treatment. Existing whitespace is kept without adding another space. Other text and image pastes are unchanged.
Long session and file names use ellipsis inside their rows. Session badges, times and close controls keep their places; Progress text wraps within its sheet.
Both mobile composers use +, a text box with a microphone when browser speech is available, and Send. Tap + → Attach file to choose a file or Take photo to open the camera capture picker. In a terminal, the upload
inserts its @path into the draft; review the draft and tap Send when ready.
In mobile AI Chat, images join the image draft and other files appear as file
chips until Send. Android Chrome can also share a file into the installed PWA;
the shared file opens as an AI Chat draft.
The + menu also offers Queue in terminals, Commands (/) in agent terminals, and Park draft / Restore parked draft / Swap parked draft in AI Chat. Chat shows Queue and Stop while a turn is running. Terminal long-press on Send still opens Queue. In terminal CLI and Chat, a Queued list above the input shows the pending prompt text, including prompts queued in CLI or on desktop. Entries disappear when delivered. Tap Hide beside the queued count to hide the list without removing work. The count stays visible and updates; tap it or Show to reopen the list. When the queue empties, the next queued prompt opens the list again. Tap Cancel to remove one or Clear all to remove the listed user prompts. Server mail wakes and spawned task prompts do not appear in this mobile list or count and are not removed by these actions. Ordinary Send still submits now; switching to Chat does not change that. If a host returns queue data that is not an array, the mobile list stays empty and the session remains usable. Failed queue requests still show the existing retry alert, except an unsupported endpoint with no pending work. Terminal parking is not offered: the existing parked-draft store belongs to AI Chat. Tap outside the menu or press Escape to close it. Desktop AI Chat and Ctrl+S retain their controls.
iOS does not offer the installed web app in the share sheet: WebKit does not implement Web Share Target (WebKit bug 194593, status NEW, “Add support for Web Share Target API”; see Chrome’s Share Target guide for the standard). To send an image, PDF or text file from another iOS app instead:
- In the other app, tap Share → Save to Files and choose a folder.
- Open the TUIC web app, tap + → Attach file, and choose that file from Files. The file then reaches the draft as described above.
Attach file accepts only images, PDFs and text files; you cannot pick other file types from Files.
Receive and answer an agent’s question away from the desk
- On the Mac, enable Remote Access and Tailscale HTTPS in TUICommander
Settings. Connect both the Mac and phone to the same tailnet. Use the HTTPS
Tailscale URL shown in Settings; a plain LAN
http://URL cannot register a phone service worker for push. Do not expose the port to the public internet. - Open
<Tailscale HTTPS URL>/mobileon the phone and sign in. On iPhone, add it to the Home Screen, then launch that installed PWA. In mobile Settings, turn Push notifications on and grant notification permission. If it says Enabled for an old subscription, turn it off and back on to re-subscribe. - On the Mac, run an authenticated
POST /api/push/testagainst that HTTPS server.sentcounts accepted push-service requests, not notification display. A 404 means no subscription;stale_removedafter HTTP 410 means the phone must re-subscribe. A 503 means push is disabled or the VAPID key is unavailable. Confirm the notification actually appears on the phone. A 400 on subscribe means the phone’s browser uses a push service host that TUICommander does not know. In Settings → All Settings, add that host (for examplepush.example.net) to added providers (/services/push/added_providers), approve the confirmation, then subscribe again. HTTPS is still required. - If the agent was spawned by another agent, turn off Settings → Notifications → Silence subagent sounds and notifications on the host for this delivery check. This setting also controls mobile sounds and session Web Push; it defaults on. Have a managed agent report
progress type=blockedwith its question. After the desktop is unfocused, or the Mac has had no HID input for two minutes, the phone notification contains the question and opens that session. Type one answer and tap Send. The PWA waits for the same submission receipt assession action=submit; if the session closed or is busy, it keeps the draft for review instead of blindly retrying.
The question is encrypted to the phone’s Web Push subscription. It does not pass through TUICommander’s content-blind cloud relay. TUICommander sends at most one question or completion push per session every 30 seconds. Session notices use the session display name, or the agent and repository when no name is set. Progress notices show the progress message, not the tool arguments. Notifications from different sessions remain separate. A newer notification for one session can replace its earlier one; tapping either remaining session notification opens that session.
Reading and command size
Mobile Settings → Appearance has independent Terminal font and Chat font controls. They apply only to this browser or installed PWA. All assistant prose, including earlier explanatory blocks and the newest answer, uses the selected Chat size (14px by default). Tool metadata and code retain their semantic sizes. Changing Terminal font does not change Chat text or the command editor.
In terminal Chat, the answer Copy action has its own row below the message, so it does not cover text. The idle command editor, suggestion labels and special-key labels use 15px text with compact spacing. The editor retains 16px text while focused to keep its native input size at the iOS zoom threshold. Action hit targets remain at least 44px.
Keyboard correction
Mobile Settings → Input → Autocorrect and spellcheck is on by default. It enables autocorrect, spellcheck and sentence capitalization in the terminal prompt composer. Turn it off for literal command entry. The choice stays in this browser or installed PWA across reloads. File and code editors keep spellcheck off. Keyboard suggestions still depend on your phone keyboard settings.
Connection loss and recovery
If navigation cannot reach the server within five seconds, the service worker shows its cached connection-test landing instead of the cached app shell. The landing shows the server address, test state and last error. Retry Now tests immediately; automatic probes back off from five to 30 seconds. The probe checks both the server version and the original mobile address within one five-second deadline. It reopens that address, including its session deep link, only when both requests succeed. A failing mobile route keeps the landing visible even if the version endpoint is healthy. No network assets are needed to render this landing.
Inside the running app, a failed API read or a terminal stream that stays disconnected for five seconds shows a visible connection-test card with Retry now. Session health reads have a five-second deadline; other RPC calls keep their own deadlines. Tabs remain available, but their content stays hidden until the connection returns; mounted views and unsent drafts are retained. A successful automatic session poll or manual retry reloads failed view reads without restarting the app. A session that ends during a terminal handshake does not report a server outage. Failed reads do not mean that repositories or ego are unconfigured. Files retains the repository and subdirectory you tried to open if the first read fails. After a linked file opens successfully, later recoveries do not reload it over an unsaved edit. An authentication refusal shows Sign in instead of repeating network retries.
If terminal socket retries run out while the PWA is away, returning to the visible page starts a fresh stream for a session that still exists. Confirmed ended sessions are not reopened. Ordinary hide/show keeps the existing subscription and resumes its output cursor.
Automatic mobile resume diagnostics
The mobile app saves up to 30 recent lifecycle snapshots in per-tab
sessionStorage. Snapshots include visibility, pagehide/pageshow and their
persisted flags, freeze/resume, root child count, shell geometry, visual
viewport, CSS app height/top, and the mobile terminal connection phase. The
recorder does not depend on animation frames, reload the page, or change the UI.
It does not store terminal output, WebSocket URLs, query tokens or credentials.
On the next boot, a prior document without a clean pagehide, or one that ended
hidden, sends its saved trail automatically to the backend log ring as a warning
with source app and message Mobile previous document lifecycle trail.
A failed upload stays pending and retries on online/resume or another boot.
The pending report is removed after the log API acknowledges it. This is evidence
of the prior lifecycle, not proof of a crash: a normal reload after hiding can
also produce a report. Session storage does not survive every form of browser
storage eviction or a closed tab. No manual copy action is needed.
The existing Mobile resume has an empty or off-screen shell warning still
checks the resumed shell after an animation frame. A missing warning does not
prove that the document or compositor was healthy. The reported iPhone grey
screen still needs evidence from the failing device; these diagnostics do not
claim to fix it.
Temporary Send diagnostics
While investigating #2462-5839, the terminal composer can record one bounded
debug log per Send press with source mobile-send. It uses the existing
perfDebug gate: development builds default to on; release builds default to off.
To enable it on the affected phone, run
localStorage.setItem("tuic.perfDebug", "true") in that page’s Web Inspector,
then reload. Set the value to "false" and reload to stop capture. Enabling it
on the desktop does not enable it on the phone.
Read the host log with GET /logs?level=debug&source=mobile-send. Each summary
includes ordered pointer/touch/click timings, held/timer flags, whether send()
was called, and active element kind, visual viewport height/offset and Send bounds
at pointerdown and click. It never includes draft text, DOM text or session names.
The recorder retains at most 24 events per press, preserving the first and newest
events and reporting any dropped count. It emits after a 400 ms release/click
settling window, on the next press or unmount, or after a five-second deadline for
an abandoned press. This is diagnostic evidence, not a fix for the reported missed
taps. A deadline or truncated event sequence is not proof that no later click occurred.
Mobile Features
Tap the attachment icon to the left of the session input to choose a photo or file. The file name appears while uploading, then its path is added to the draft. Queue is unavailable until the upload finishes. Smaller mic and Send controls sit inside the input border on the right.
Hold Send with a finger or mouse, then select Queue to hold your current agent prompt until its next ready window. A normal tap still sends immediately. Queue clears the input after acceptance and shows a notice. If the result is uncertain, check the agent session before trying again. The pending list is shared by CLI and Chat. If an older host has no queue-read endpoint and there is no pending count or accepted local enqueue, the session does not show a queue error. Other read failures remain visible with Retry; a pending count or accepted local enqueue also keeps a missing-endpoint error visible.
- Sessions list — See all running agents with status (idle, busy, question, rate-limited, error). Tap the Working, Idle and Awaiting counters to filter by one or more states. Tap an active counter again to clear it; no active counters shows every session. Counts always include all sessions. A zero-count state shows an empty result. State filters combine with the search field and the Default/Recent sort menu.
- Return to latest output — Scroll back in a session’s CLI or Chat output to show the down-arrow at the right end of the key bar, above Send. Tap it to return to the bottom without sending terminal input. It hides when you reach the bottom, including by manual scrolling.
- Question cards — Single-choice, multiple-choice and free-text cards use the selected theme and open above the terminal key bar, leaving its keys available. Native ego selectors open automatically; use the header question action to hide or reopen them. If a typed reply requires an option selection, the question controls reopen and the draft stays editable. Free-text cards still open on request.
- Session detail — Opening an ego free-text question card preserves your unsent answer. Send submits the complete answer through the guarded human-reply path, whether the card is open or closed; a refused reply keeps the draft. Live output streaming, quick-reply chips (Yes/No/Enter/Ctrl-C), text input. The terminal keybar Ctrl button opens Ctrl+C, Ctrl+B, Ctrl+D and Ctrl+Enter. A choice sends once and closes; tap outside or press Escape to dismiss. Ctrl+C and Ctrl+D use danger colours. Ctrl+Enter is agent-aware: it submits in Claude Code, steers a busy turn in ego, and inserts a newline in Codex, OpenCode, Goose, Grok and pi. Other agents use documented or conservative fallback keys; ordinary Enter remains the submit key.
- Files — Browse a configured repository, view
.mdfiles as rendered Markdown or other text as plain text, and tap Edit to change and save source files up to 1 MB - Question banner — Instant notification when any agent needs input, with quick-reply buttons
- Activity feed — Chronological event feed grouped by time
- Progress — Select a project with journal entries to read its recent reports
- Remote sessions — Open live output and close a session on its connected owning machine from the same phone page
- Notification sounds — Audio alerts for questions, errors, completions, and rate limits
Tips
- Pull down on the sessions list to refresh
- The question banner appears on all screens — you don’t need to be on the sessions tab to respond
- Sound notifications can be toggled in the mobile Settings tab
SSH Tunnel Management
TUICommander can manage persistent SSH tunnels with automatic reconnection, port forwarding, and audit logging.
Creating a Tunnel Profile
- Turn on Experimental Features in Settings → General, then open the SSH Tunnels panel (command palette → “SSH Tunnels”)
- Click + New Tunnel to open the editor
- Configure:
- Name — A descriptive label (e.g., “prod-db-tunnel”)
- Host — Remote SSH host
- Port — SSH port (default 22)
- User — SSH username
- Identity File — Optional path to SSH private key (use the Browse button to select)
- Port Forwards — Local or remote port forwarding rules (e.g., local 8080 → remote 80). Local forwards target
remote_host/remote_port; Remote forwards targetlocal_host/local_port. The remote host is pre-populated from the tunnel host when adding a Local forward - Options — ServerAliveInterval (default 15s), ServerAliveCountMax (default 3), StrictHostKeyChecking (Yes or AcceptNew), Compression (default on)
- Save the profile
Compression is ssh -C on the tunnel channel, and it is on by default because
a tunnel usually carries a terminal stream, which deflates to a few percent of
itself. Turn it off for a tunnel to a machine on the same LAN, where the link is
fast and the CPU is the scarcer thing. Profiles written before this option existed
keep compressing.
Tunnel profiles are stored as TOML files. Global profiles live in <config_dir>/tunnels/ and are available across all repos. Per-repo profiles are stored in <repo>/.tuic/tunnels/ and override global profiles with the same ID.
A tunnel shows Connected only after SSH survives its initial 500 ms. With local forwards, every local port must also accept a TCP connection. If SSH exits first or a port does not start listening within 30 seconds, the tunnel reports the failure instead.
Auto-Connect
Enable Auto-Connect on a tunnel profile to have it start automatically when TUICommander launches. Useful for tunnels you always need (database access, internal services).
Toggle auto-connect in the tunnel editor — profiles marked with auto-connect are started during app hydration before you interact with the UI.
Statusbar Indicator
The status bar shows a shield icon for SSH tunnels:
- Grey shield — You have tunnel profiles configured but none are currently connected
- Green shield with badge — Shows the number of active tunnel connections
Click the shield to open the Tunnels Panel.
Command Palette
Open the command palette (Cmd+P / Ctrl+P) and type “tunnels” to toggle the Tunnels Panel.
Starting and Stopping Tunnels
- In the Tunnels Panel, click the Start button next to a profile to launch the SSH tunnel
- The TunnelStatusBadge shows the current state: Starting, Connected, Reconnecting, Stopped, or Error
- Click Stop to gracefully terminate the SSH process (SIGTERM with 5s grace period, then SIGKILL)
- On app exit, all active tunnels are automatically stopped — no orphaned SSH processes
SSH Agent Detection
TUICommander automatically detects your SSH agent and shows the agent type and loaded keys in the tunnel editor. Supported agents:
- 1Password — Detected via the 1Password SSH agent socket
- Secretive — Detected via the Secretive agent socket
- GPG Agent — Detected via gpg-agent socket
- Generic SSH Agent — Any other
SSH_AUTH_SOCKvalue
The key listing shows fingerprint, comment, and key type for each loaded key, helping you verify that the correct identity is available before connecting.
Automatic Reconnection
When a tunnel disconnects due to a network issue or timeout, the supervisor automatically reconnects with exponential backoff:
- Base delay: 1 second, doubling each attempt
- Maximum delay: 30 seconds
- Jitter: +/-25% to prevent thundering herd
- Maximum retries: 10 before giving up
- Backoff resets on successful connection
Non-retryable failures (authentication errors, host key mismatches) stop immediately without retry.
Audit Log
All tunnel events (start, connect, disconnect, error, retry, stop) are recorded in a SQLite database with WAL mode for performance. The audit log supports:
- Querying events by tunnel ID
- Querying events by time range
- Automatic rotation of old events (configurable retention period)
Exit Classification
The supervisor classifies SSH process exits to determine whether retry is appropriate:
| Exit Reason | Retryable | Description |
|---|---|---|
| AuthFailed | No | Permission denied or authentication failure |
| HostKeyMismatch | No | Remote host key changed |
| PortInUse | No | Local forwarding port already bound |
| ConnectionRefused | Yes | Remote host rejected the connection |
| NetworkDown | Yes | Network unreachable |
| Timeout | Yes | Connection timed out |
| UserKilled | No | Process terminated by user signal |
Remote Connection Manager
Remote connections let you manage tuic-remote daemons running on other machines. TUICommander routes API calls to the correct host based on which repo/session is active.
Adding an SSH Connection
- Open Settings → Remote Machines and click +
- Select SSH transport
- Type a host or choose Probe SSH hosts to see the hosts from your SSH config and whether each accepts a shell login
- Configure the port (default 22), user, and optional identity file
- Choose Never deploy, Deploy on connect, or Installed service, and set how many minutes an ephemeral daemon should survive with no client
- Set the remote daemon port (default 9877)
- Set the auth username and password the daemon was configured with
- Save, then click Connect
For an installed service, Connect waits for the SSH forwarding port and retries the daemon health check during startup before reporting it unavailable.
Adding a Direct Connection
- Open Settings → Remote Machines and click +
- Select Direct transport
- Enter the URL of the remote daemon (e.g.,
http://10.0.0.5:9877) - Set the auth username and password
- Save — health polling begins immediately
A URL that points back at the TUICommander you are configuring is refused with
“this very TUICommander instance — a machine cannot mirror itself”. The check
compares the instance_id in GET /health against this process’s own, so a
second daemon on the same machine (a different port) is still a valid peer.
Adding a Relay Connection
Use this when the remote machine accepts no inbound connection.
- On the remote machine run
tuic-remote --relay-pair <relay-url> --relay-register, or setTUIC_RELAY_TOKENinstead of--relay-register. Add--relay-out <file>to write the bundle to a private file. - Restart
tuic-remoteso it registers with the relay. - Copy the printed
tuic-pair-v1:bundle to this machine over a trusted channel. It holds the end-to-end secret. - Open Settings → Remote Machines, click +, and select Relay.
- Paste the bundle and save, then click Connect.
The relay publishes peer presence in admission order, before pending stats writes. Simultaneous daemon and desktop connections do not create duplicate attachment notifications.
If the status shows pairing_rejected, the daemon was paired again: import the new bundle. daemon_offline means the daemon is not connected to the relay. After link_lost or relay_unreachable TUICommander reconnects by itself. Running --relay-pair again replaces the pairing.
Connect or Install
Connect with Deploy on connect is the zero-setup path. If no compatible
daemon answers, TUICommander downloads the release asset matching the host,
caches it locally, copies it over the same SSH identity as the tunnel and starts
it on 127.0.0.1. The daemon keeps existing sessions alive for the configured
survive time after the last client leaves, then exits. A later Connect reuses a
matching binary already on the host and the pairing token in the local vault.
Install uses the same binary but registers a persistent user service. Linux
gets ~/.config/systemd/user/tuic-remote.service plus the mode-0600
~/.config/tuic/remote.env; macOS gets the mode-0600
~/Library/LaunchAgents/dev.tuicommander.remote.plist. The service starts at
login and restarts on failure, so later Connect operations only open the SSH
tunnel. Uninstall stops and removes the service files but leaves the cached
binary available for a future Connect.
Both paths place the executable and log under ~/.cache/tuic/. The ephemeral
path also uses tuic-remote.pid; deleting an on-connect machine sends a
best-effort stop, while deleting an installed connection deliberately leaves its
service alone. The daemon is launched with --no-agent-configs, so deploying it
does not rewrite the host’s Claude, Codex, or other agent configuration.
Update and restart a remote machine
When a connected daemon reports a different binary SHA-256 from the binary the
desktop would deploy, Remote out of date appears beside the connection.
Each connection has an Auto-update remote daemons option in Settings. It is
off by default. When enabled, a connection to a newer available build updates
automatically only if the daemon reports zero live PTY sessions. A daemon with
live sessions stays on its current build; Settings shows the session count and
offers the manual update. No update is queued. An automatic failure is shown
once for that selected build, without a retry on each reconnect.
The manual update button is disabled while an automatic update is running. The
backend rejects concurrent manual requests from IPC, HTTP, or MCP, and skips an
automatic update while a manual one is in progress. A stalled transfer reports
a timeout, after which connection checks resume.
For a connected Direct or SSH remote, Update & restart remote appears only
while the backend reports that the remote build is out of date. The action and
the warning use the same status flag. After an update, the desktop verifies the
selected build through /health and clears both without requiring a reconnect.
The preview reports the remote target and build, selected desktop build and source,
and the number of live PTY sessions. Confirming ends those sessions. The
desktop uses the matching release asset first; if that asset does not exist, a
locally built tuic-remote beside the desktop executable is used only when its
target triple matches the remote. A target mismatch names both targets; a
missing local binary reports its expected path.
For a development build, build the headless binary with
cargo build --bin tuic-remote --no-default-features from src-tauri when the
desktop-feature sibling is a stub. The preview names that cause and command.
Direct updates stream the binary over the authenticated connection. The daemon
accepts only the session cookie for binary and file uploads, and the update
client sends it in the Cookie header; credentials never appear in the upload
URL. A daemon from this release rejects an update from an older desktop with
401, and a newer desktop cannot update an older daemon that still expects the
URL token. Update desktop and daemon from the same release, or deploy the older
daemon over SSH. The daemon
verifies its target, size (512 MiB maximum), SHA-256 and confirmed session
count, stages it in its own install directory, then starts the new build. SSH
updates use the existing SCP deployment path. TUICommander waits for /health
to report the selected build after restart; the connection’s status polling
re-authenticates when the daemon mints a new token. A changed session count or
binary between preview and confirmation cancels the update. In-process update
on Windows is unavailable: a running .exe cannot be overwritten, and the
daemon answers 501.
An older daemon without /health.build is shown as out of date. Automatic
updates require a build identity, so this daemon needs one manual installation.
SSH can bootstrap it because the desktop probes the host target with uname; an older
Direct daemon has no update endpoint or reported target, so it needs one manual
installation of a compatible daemon before this action can update it.
Authentication
tuic-remote authenticates every TCP request. The headless build has no
loopback bypass and run_remote forces lan_auth_bypass off, so an SSH tunnel
does not make the daemon local: GET /health is the only unauthenticated route.
A connection without credentials therefore reaches /health and nothing else.
The password is kept in the OS credential vault, keyed by the connection’s UUID.
connections.json holds the username only, and neither the vault entry nor the
daemon’s token ever appears in GET /config. Deleting a connection deletes its
vault entry with it.
For a manually managed daemon, TUICommander trades the password for the daemon’s
session token over GET /api/auth/session-token (Basic Auth). For Connect and
Install, the vault pairing token is the daemon session token itself and is sent
to the launch process over SSH stdin, never in its command line. TUICommander
then puts the session token in the query
string of every call — HTTP, the terminal WebSocket and the /events SSE
stream alike. It has to be the query string: a WebSocket upgrade cannot carry an
Authorization header, and the daemon answers Access-Control-Allow-Origin: *,
which rules out credentialed cookies. The token lives in the daemon’s memory and
is never written to disk, so the client re-fetches it on every connect and after
a daemon restart.
Status tells the two failures apart:
| Status | What it means |
|---|---|
| Connected | A route behind the auth middleware answered 200 |
| Not authenticated | The daemon is reachable and /health answers, but the credentials were rejected. Fix the username or password — not the network |
| Error | The daemon is unreachable, or the tunnel failed |
An unauthenticated connection routes no traffic at all: no terminals, no repo
calls, no event bridge. /health passing is not evidence that anything else
will work, which is why it is not what the status is read from.
Where the connection runs
The connection itself — the health probe, the token exchange, the five-second status poll, the SSH tunnel — runs in the TUICommander backend, not in the window. Three consequences you can observe:
- Every client sees the same status. Connecting from the desktop app shows
up in a browser tab pointed at the same TUICommander, and the other way round.
The status is pushed as a
remote-connection-statusevent. - A daemon restart is recovered with the window closed. The poll notices the token it holds is no longer the daemon’s, re-authenticates once, and the connection stays Connected without anyone looking at it.
- Nothing is left behind. The SSH tunnel a connection needs is built in memory; it never appears as a saved profile in the Tunnels panel, and quitting the app cannot orphan one.
A remote tab behaves like a local one
While a connection is up, the backend follows the remote daemon’s own event stream and repeats every event locally under the same name. A session on the other machine therefore raises the same idle / busy dot, the same question badge, the same notification and the same queued-command gate as a session on this one — there is no separate remote code path to fall behind.
The remote sessions are listed beside the local ones, each tagged with the connection that owns it. Losing the connection announces them closed and drops them, so a badge cannot freeze on the last state the machine was in.
Project Progress for a remote repository is stored on its owning machine. New entries also reach the connected desktop window, so its Progress bell and dialog update without moving the journal to the local machine.
Remote Repositories and Terminals
Once a remote connection is configured:
- Add remote repo — Select a connection and browse from that machine’s home directory. If a directory cannot be read, the picker explains the error and still allows entering a path or moving to its parent. The repo appears in the sidebar with a remote badge
- Open terminal — Terminals on remote repos connect via WebSocket to the remote daemon. The desktop CSP explicitly allows
ws:andwss:through its permissivedefault-src: SSH usesws://127.0.0.1:<dynamic tunnel port>, and Direct uses the configured HTTP(S) host and port as WS(S). A failed launch displays its error in the terminal pane; a failed stream connection, a missing initial frame after 15 seconds, or an unreadable compressed frame shows a persistent error toast. The client retries the stream and replays the current viewport on reconnect; the toast remains until dismissed. An idle terminal whose viewport or explicit empty replay has arrived is not treated as stalled - Health monitoring — Connection health is polled periodically. Disconnected connections show a warning badge in the sidebar
Connections are stored in <config_dir>/connections.json with SSH and Direct transport types.
Remote agent notices
An agent’s MCP toast on a connected machine appears in the desktop notification
bell under Messages, with [connection name] before its title. It keeps the
requested level and sound. Open terminal switches to the originating remote
tab when it is still open; an unknown or closed session leaves focus unchanged.
Notices from a disconnected machine are not queued or replayed on reconnect.
Connections with the same display name retain separate notices. Malformed remote
notice text is discarded.
What runs on which machine
A call is routed by its own arguments, not by which panel made it. TUICommander asks the repository registry which machine owns the path (or, for a session, which machine owns the repo its tab was opened in) and sends the call there. A path that no registered repository owns is local, and so is every repository with no connection.
| Operation | Runs on |
|---|---|
| Git — status, diff, log, stage, commit, push, stashes, worktrees | the machine that holds the repo |
| Filesystem — browse, read, write, search, watch | the machine that holds the repo |
| Terminals — create, write, resize, close, and the output stream | the machine that holds the repo |
Repo change events (repo-changed) | the machine that holds the repo, over its own SSE stream |
Agent run configs (agents.json), the agent hook toggles, upstream MCP servers | the machine that holds the repo — they describe a machine, not this app |
| Settings, keybindings, themes, pane layout, notification config | always local — they describe this app, not a repo |
| The repository registry itself (add, remove, reorder, group) | always local — it is this machine’s list of machines |
| Native file pickers, window management, global hotkey, CLI install, dictation, plugin install | always local — they carry no repository path, so nothing routes them |
| mdkb code intelligence — outline, go to definition, references | local, and that is a gap (see below) |
Plugin filesystem watches (plugin_watch_path) | local, and that is a gap (see below) |
Those last two have no HTTP route at all, so they cannot be sent anywhere. Called with
a path inside a remote repository they run against the local machine — which does not
have that path — and log "<command>" has no remote route and ran on the local machine
once per command. Check it with GET http://localhost:9876/logs?source=network. The
mismatch is reported rather than silent, but the feature genuinely does not work on a
remote repository yet.
Open in app is routed: the IDE is launched on the machine that holds the file, which
is right for a second desktop and useless for a headless tuic-remote — nothing there
has a display to open it on.
Which config follows the repo, and which stays here
Two families, and the line between them is what the config describes.
Follows the repo — a machine owns it. claude, grok and codex are installed on
the box that runs them, with their own licences, their own paths and their own config
directories, so a run config naming a Mac path cannot describe a Linux daemon. A tab
opened on a remote repository launches with that machine’s agents.json: the command,
its arguments, its environment and the CC_ENV_FLAGS that reach the PTY. The same rule
covers the agent hook toggles (hook_instrumentation, native_status_signals) and the
upstream MCP servers, which are dialled by the backend that holds them.
Adding an upstream MCP server saves its configuration and credentials on the selected machine. A rejected duplicate name preserves that machine’s existing credentials. Use the existing server’s Edit form to replace a credential.
The frontend keeps one copy per machine, read the first time that machine is needed and
dropped whenever its connection changes state — a daemon that went away and came back may
have been reconfigured, or be a different box behind the same name. A local repository
costs no round trip at all: its config is read once at boot.
If a remote config cannot be read, the Agents tab shows the connection error and retries
on the next load. It does not save a fallback empty config over the remote file. A 404
for /config/agents means the remote daemon needs an update that includes this route.
Stays here — this app owns it. Theme, keybindings, pane layout, notification config and the repository registry describe this window on this desktop. None of them is ever sent to a daemon, including when every registered repository is remote.
Settings edits the machine you pick. The Agents tab and the upstream-MCP panel carry a machine selector; it defaults to the machine of the repository the settings nav is standing on, and an explicit pick overrides it, so a remote machine is editable from a local repo.
Authenticated Settings actions are available on the headless daemon through the same
POST /settings/action contract as the desktop server. The daemon also serves the
authenticated /config snapshot used to load and refresh browser Settings. Successful durable edits publish
settings-changed over SSE so connected Settings readers can refresh without saving.
Three things stay local even while a remote machine is selected, because they cannot work
anywhere else: installing or removing the TUIC MCP bridge (install_agent_mcp), opening an
agent’s config file in the editor, and the upstream OAuth flow — that one opens a browser
and listens on a loopback redirect, and a headless daemon has neither. Their controls are
hidden rather than shown pointing at the wrong machine.
A call on a repository whose machine is not connected fails with
Remote connection <id> not connected. It is never quietly answered by the local
backend — an answer about the wrong disk is worse than an error.
tuic-remote (Beta)
A standalone headless daemon for running TUICommander on a Linux server without a desktop environment. It exposes the same HTTP/WebSocket API as the desktop app’s remote access feature, but runs as an independent binary — no Tauri, no GUI.
Installation
Download the tuic-remote binary and the tuic-bridge binary for your
platform from the GitHub Releases
page. Both are published for every platform below. Tagged releases carry the
stable build; the rolling nightly
release carries the same four targets, rebuilt on every push to main.
| Platform | Daemon | MCP bridge |
|---|---|---|
| Linux x64 | tuic-remote-x86_64-unknown-linux-gnu | tuic-bridge-x86_64-unknown-linux-gnu |
| Linux ARM64 | tuic-remote-aarch64-unknown-linux-gnu | tuic-bridge-aarch64-unknown-linux-gnu |
| macOS ARM (Apple Silicon) | tuic-remote-aarch64-apple-darwin | tuic-bridge-aarch64-apple-darwin |
| Windows x64 | tuic-remote-x86_64-pc-windows-msvc.exe | tuic-bridge-x86_64-pc-windows-msvc.exe |
# Example: Linux x64
BASE=https://github.com/sstraus/tuicommander/releases/latest/download # nightly: .../releases/download/nightly
curl -fsSL -o tuic-remote "$BASE/tuic-remote-x86_64-unknown-linux-gnu"
curl -fsSL -o tuic-bridge "$BASE/tuic-bridge-x86_64-unknown-linux-gnu"
chmod +x tuic-remote tuic-bridge
Keep the two in the same directory, and keep those names. At startup the
daemon writes an MCP entry into the config of every agent installed on its
machine, and that entry names the bridge by the path it finds next to itself. A
daemon without tuic-bridge beside it configures agents to run a binary that is
not there; an agent then starts with no tuicommander tools at all — no
session, no repo, no progress, no peer mail.
The same miss silently strips ego’s tools: an AI Chat session granted by a
process that found no bridge gets an empty mcpServers, and the only symptom is
ego answering that it cannot see terminals or repositories. Since #809-724c the
process says so instead — one warn at startup naming every path it checked:
No tuic-bridge binary found, so ego sessions start with no MCP server and ego
cannot see terminals or repositories. Checked: /opt/tuic/tuic-bridge, tuic-bridge
Read it with curl 'http://127.0.0.1:9876/logs?level=warn'.
Setup
Set a password before first use. Omit --instance to use the existing default
TUICommander configuration and credential vault:
./tuic-remote --set-password
For an isolated daemon, pass the same named instance to password setup and every subsequent launch:
./tuic-remote --instance build-host --set-password
./tuic-remote --instance build-host
An instance ID is one lowercase ASCII DNS label: 1–63 characters, letters or
digits at both ends, with hyphens allowed internally. default is reserved;
omit the option to select the default instance. Invalid IDs fail before any
configuration or credentials are accessed.
The default instance keeps the platform paths listed in
Configuration and the existing OS
keyring entry. A named instance instead stores files in the corresponding
instances/<id>/ subdirectory and uses keyring service
tuicommander-instance-<id>, user vault. It starts empty: it never falls back
to, imports, changes, or deletes default or legacy files and credentials. The OS keyring remains the default in release builds. If a named instance’s
selected vault cannot be opened, the daemon exits before binding its network socket.
Mounted credentials without an OS keyring
For an unprivileged Linux daemon without a session bus, select a private JSON file explicitly. This option works in release builds and does not enable the debug credential store:
./tuic-remote --instance build-host --credential-file /run/secrets/tuic-vault.json --no-agent-configs
The file is a JSON object whose keys are vault slots and whose values are strings:
{"remote/session-token": "replace-with-a-private-random-token"}
Use that session token to authenticate protected HTTP requests. Keep the file private and mount it read-only if possible. The daemon reads it once before any credential access. A missing, unreadable or malformed file stops boot with a content-free diagnostic; there is no keyring or legacy-vault fallback, even for missing slots. The option does not put credentials in config JSON or logs.
This is a file-seeded process-local source: credential changes made through
APIs remain in memory, never update the selected file, and are lost on restart.
Other configuration changes can still be persisted normally. To rotate a token,
replace the mounted file and restart the daemon; live file changes do not reload
credentials. Each process reads its own snapshot. An automatic daemon relaunch
uses the startup executable path after binary replacement, retains the file
option and rereads the file; a service supervisor must retain it
in its launch command. Do not share a seed across instances unless they are meant
to share secrets. --set-password cannot be combined with this option; use a
seeded session token, or the default keyring source for durable password setup.
The desktop default is unchanged.
Automation that depends on this isolation contract must pin and verify the
digest of the release artifact it launches. Artifact verification belongs to
the consuming harness; tuic-remote does not expose a separate capability or
version endpoint for it.
Running
# Default port 9877
./tuic-remote
# Custom port
TUIC_PORT=8080 ./tuic-remote
# Named instance, with the same port override
TUIC_PORT=8080 ./tuic-remote --instance build-host
# Loopback-only ephemeral daemon with a 30-minute idle lifetime
TUIC_PAIRING_TOKEN=... ./tuic-remote --bind 127.0.0.1 \
--survive-secs 1800 --no-agent-configs
By default the daemon binds to 0.0.0.0:<port> and runs until signalled. The
desktop-managed form binds to loopback, skips agent config installation, writes
tuic-remote.pid in its config directory, and exits after the survive time with
no SSE or WebSocket clients. SIGINT, SIGTERM and SIGHUP all shut it down cleanly
and remove that pid file.
Cluster workers: leave host agent configs untouched
Start each cluster worker with --no-agent-configs when another TUICommander
process owns the same OS user’s agent integration, or when the worker must not
change that user’s agent configuration:
TUIC_PORT=9877 ./tuic-remote --no-agent-configs
The flag sets RemoteOptions.agent_configs to false. Without the flag, this
option defaults to true: startup can install or repair the TUICommander MCP
bridge entries in supported agents’ configuration files, including
~/.claude.json and ~/.codex/config.toml (or the selected agent config roots).
Those files belong to the OS user, not to a cluster task. Use the flag on every
worker launch that must preserve them; otherwise a worker that owns config repair
can redirect the user’s bridge entry to its own installation.
This flag skips only startup agent MCP config writes. It does not disable the
daemon’s MCP endpoint, local IPC listener, or normal writes to its own config
directory. A named --instance isolates daemon state but is not a substitute for
an explicit no-agent-config policy. If a worker needs to own agent integration,
give it a separate OS user and HOME rather than sharing those files with another
owner.
Workers that take work only from assignments
Start a worker with --no-automations when all its work must arrive through
assigned workflow runs:
TUIC_PORT=9877 ./tuic-remote --no-automations
The flag sets RemoteOptions.automations to false. The daemon then runs no
automation scheduler and no event intake: no schedule, labelled issue or
pull-request review starts a run or session, and a manual automation start is
refused with a message that names the flag. Steps of workflow runs started
through the workflow API keep running. On start, runs a previous process left
Reserved or Running are settled, and a completed event run still reports its
draft PR. Without the flag, automations run as before.
The daemon serves:
- The HTTP API (sessions, terminals, git, filesystem, agents)
- WebSocket terminal streaming
- MCP tool integration (for AI agents)
It does not serve the web UI: FRONTEND_DIST, serve_index and
serve_static are all #[cfg(feature = "desktop")] (mcp_http/static_files.rs)
and tuic-remote is built --no-default-features, so / has no route.
Point a desktop TUICommander at the daemon; a browser has nothing to load.
Every TCP request is authenticated — the headless build has no loopback bypass
and run_remote forces lan_auth_bypass off — so an SSH tunnel does not make
the daemon local. GET /health is the only unauthenticated route.
The daemon also opens a local IPC endpoint that is not on the network: a
Unix socket at <config dir>/mcp.sock, or the named pipe
\\.\pipe\tuicommander-mcp on Windows. That is how tuic-bridge reaches it —
an agent running on this machine starts the bridge as a child process and the
bridge speaks HTTP over that socket. It carries no authentication because the OS
user is the boundary; nothing outside the machine can open it.
What the daemon runs, and what it deliberately does not
The daemon is a whole machine, not a session server. It runs almost everything the desktop runs in the background:
| Runs on the daemon | Why it has to |
|---|---|
| Session state accumulator, ACP notice pump, tombstone sweeper | the sessions live here |
| Process snapshot refresher | agent session discovery reads argv and env off the processes on this machine; without it a tab cannot resume after a restart |
| Standby checker (Unix) | a remote client reports tab visibility, so an idle hidden session parks here exactly as it would on the desktop |
| Content index updater and boot pre-warm | see below |
| Tool search index updater | the daemon now serves MCP |
| Upstream MCP auto-connect and health checker | upstreams are per-machine configuration, so the machine that holds them connects them |
| CPU watchdog | the daemon is precisely where nobody is watching |
| Maintenance sweep (idle MCP sessions, expired auth rate limits, expired tasks) | the daemon authenticates every TCP request, so its rate-limit map grows with every port scanner that finds it |
| MCP config install for the agents on this machine | so an agent launched here has the tuicommander tools |
It deliberately does not run:
- The WebView recovery watchdog — there is no WebView, so there is no blank document to navigate back.
- The embedded assistant: knowledge persistence, the job scheduler and the watcher engine. Those are configured and read from the desktop UI, and the daemon’s router serves none of their routes, so a scheduler ticking here would run jobs nobody on this machine can create, inspect or stop.
Content search needs an index, and an index needs a warm. A cross-repo
search (/fs/search-content-all) skips any repo whose index is not resident and
starts no build of its own — the warm strategy owns scheduling. So the daemon
watches every registered repo and pre-warms indices at boot, following the same
index_strategy setting as the desktop: active_and_switch (the default) and
active_only warm the active repo, all_sequential warms every repo with the
active one first. Repos that are not yet indexed are reported back as pending
and indexing counts, not as an empty result — a single-repo search
(/fs/search-content) falls back to a full scan while its index builds, so it
answers correctly either way.
TLS
Configure TLS in the instance’s config.json under services.tls:
{
"services": {
"tls": {
"mode": "manual",
"cert_path": "/path/to/cert.pem",
"key_path": "/path/to/key.pem"
}
}
}
Manual mode serves HTTP and HTTPS on the same daemon TCP port, like desktop
remote access. HTTPS includes SSE and WebSocket (wss://) traffic; HTTP remains
available for local relay and SSH clients.
Missing or invalid PEM files stop startup before any listener binds; there is no
plaintext fallback. With mode: "off" (the default), the port serves plain HTTP.
Startup logs report the bound listener mode, and tls_active reflects the live
TLS listener rather than the presence of certificate configuration.
Differences from Desktop Remote Access
| Desktop Remote Access | tuic-remote | |
|---|---|---|
| Requires desktop app | Yes | No |
| Runs headless | No | Yes |
| Tauri dependency | Yes | No |
| Default port | 9876 | 9877 |
| LAN auth bypass | Disabled | Disabled |
| Signal handling | N/A | Graceful SIGINT/SIGTERM/SIGHUP |
| MCP bridge for local agents | Bundled sidecar | Downloaded next to the daemon |
| Embedded assistant (watchers, scheduler) | Yes | No |
Status
Beta — the core HTTP/WebSocket API is stable, but the standalone daemon is new and may have rough edges. Report issues on GitHub.
Remote host cards name DNS, refused connections, timeout, TLS, and authentication failures. A 403 Untrusted Host explains that the daemon rejected the host name, including when the response arrives in multiple HTTP chunks. This refusal stops automatic connection retries and removes the retry delay. An outdated daemon is a possible cause: install the current tuic-remote and restart its service, then press Connect. If the refusal persists, check the daemon’s trusted names. The card shows the last known tuic-remote version and warns when its semantic version is older than this client, including while reconnecting or in an error state. Connected daemons also retain the selected-asset SHA-256 update check. Version information comes from a successful /health.build response. The recorded older daemon returns only plain Untrusted Host on 403, with no version. If /health is refused before any successful observation, the version is unknown and the message describes an outdated daemon as a possible cause, not a confirmed diagnosis. No alternative Host or IP probe bypasses the refusal. The last health observation is held only in runtime memory; explicit disconnect, deletion or an app restart discards it. The cause remains visible until that attempt. Unchanged failure states produce no additional warnings. When a short name cannot resolve, a matching running Tailscale peer supplies its advertised full DNS name. Retryable failures show the automatic retry delay; active attempts clear the previous failure.
Troubleshooting
| Problem | Fix |
|---|---|
| Can’t connect from another device | Check that both devices are on the same network. Try pinging the host IP. |
| Connection refused | Verify the port isn’t blocked by a firewall. The settings panel includes a reachability check. |
| Authentication fails | Re-enter the password in settings — the stored bcrypt hash may be from a different password. |
| Terminals not responding | WebSocket connection may have dropped. Refresh the browser page. |
Private secret entry on a phone
A desktop secret request shows a full one-time URL in its private window. Open Open on a trusted browser or phone to select or copy the URL, open the link, or scan its QR code. The address uses the same network and HTTPS policy as Remote Mobile Connection. Both choose the first backend-ranked address: Tailscale with an active HTTPS listener, then Wi-Fi/LAN, then HTTP-only Tailscale, then another detected network address. Interface order breaks ties within each group. IPv6 literals use brackets. You can choose another address in Remote Access or the pairing dialog; detection does not guarantee that the phone can reach it. If no address is detected, the private form shows network setup guidance instead of a phone URL. If Remote Access is off, enable it in Settings and request a new form. Enter only the requested fields. Entry uses the existing server authentication and transport; use HTTPS to protect values in transit. No separate private listener is created. The headless daemon cannot originate requests in this slice. See Private secret forms.
Address remote terminals and peers from desktop MCP
Use session action=list to discover connected remote terminals. Their
connection_id identifies the saved remote connection. Pass that field with
session_id, or use the returned address, for output and semantic submit.
Use agent action=list_peers to find remote peer addresses, then send mail to
<connection_id>/<peer-id>. Replies to local/<peer-id> return through the
desktop hub. Daemons can also address peers on another configured connection.
All traffic follows the configured daemon connection and credentials.
Both desktop and daemon need a version supporting remote peer mail. Local daemon mail remains usable if the desktop disconnects. A cross-host error is explicit; a timeout with uncertain delivery is not permission to resend the body.
The read-only reproduction harness is scripts/test-remote-mcp.py. Run
python3 scripts/test-remote-mcp.py --connection <id> --session <alias-or-id>
against the desktop MCP. --exercise submits and sends mail and must target a
disposable idle agent; --second-connection and --second-session check a
remote-to-remote reply through the same hub.
For a local protocol fixture, build a test-support headless binary and run
python3 scripts/test-remote-mcp.py --fixture-bin <binary> --fixture-launcher scripts/run-remote-fixture.sh.
This launches three actual isolated daemons, exercises the hub MCP, remote-to-remote
mail and replies, semantic shell rejection, then verifies intrahost mail with the hub
stopped. It does not claim to test a real agent composer; use --exercise for that.
Connected daemon notices carry their host identity. MCP confirmation responses and ACP permission/elicitation answers return to that daemon; disconnected questions disappear without changing local connections. MCP confirmation dialogs appear on the desktop and close when another client answers. AI Chat shows remote questions separately, with their ACP connection identity. Completing an earlier answer preserves questions announced by newer notices. Remote GitHub transitions fetch PR data from the repository owner, notify once, and do not run local repository automation. GitHub polling also works on the headless daemon. MCP upstream health refreshes use a separate host snapshot rather than this machine’s editable configuration.
MCP terminal output can be read in retained pages without running a command again.
Follow the response’s continuation instructions and next_cursor while
has_more is true. Raw pages use byte positions; text pages use scrollback rows.
The same paging works through a connected remote daemon. Buffer eviction can
remove old output, and the response reports the resulting gap.
Remote desktop terminal tabs consume the daemon’s detected agent identity and OSC title updates, with the same custom-name and spawn-name protection as local tabs. Grid output streams over WebSocket; the text/log view batches rows at 200 ms. Loopback timings do not establish latency on an SSH or Tailscale link.
Claude session CLI / Chat
On a Claude session, select Chat in the session header to read the conversation. Use the same input below to reply. Select CLI for permission prompts or questions that are not in the transcript. If the backend cannot bind the transcript, the view returns to CLI and shows the reason. CLI returns to the latest output; its stream stays connected while Chat is open. Chat reads pause while the page is hidden.
Recovering a short Direct host name
If DNS cannot resolve a short Direct host name, TUIC checks the advertised Tailscale peers. With exactly one matching peer, it retries once with that peer’s full DNS name. Only the URL host changes; the scheme, port, path and TLS certificate checks stay unchanged. SSH aliases, IP addresses, full DNS names, and errors other than DNS failures do not use this fallback.
A successful recovery uses the resolved endpoint for the current session. Remote Machines shows the effective address and Save resolved address. Select that action to update the saved connection without disconnecting it. Leaving the action alone keeps the original saved address.
Remote Settings startup limits
The shared Settings HTTP endpoint and the MCP settings tool both accept local or authenticated callers: an authenticated remote MCP client can read, propose and confirm settings changes like a loopback one. Proposals stay bound to their MCP connection, the exact edit and a 300-second expiry, and each one still needs a human answer in the confirmation dialog. A local request does not implicitly target a remote daemon. Select the owner explicitly, keep its read revision, and never treat a remote invalidation cursor as a local CAS token. Startup workflows covers confirmation, device-login state and readback after uncertain or partial persistence. Secrets remain write-only.
Typed Ego startup login returns a session on the explicitly selected daemon. Open that session in the owning client’s terminal view to authenticate, then request status and refresh providers on that same daemon. Never read a local credential owner to infer the result of remote authentication.
Remote session closure
MCP session action=close accepts a remote connection_id or connection-qualified session reference. The host resolves aliases on the owning daemon and sends authenticated DELETE /sessions/{id}. The caller’s own PTY remains protected from self-close, and non-loopback MCP callers cannot invoke destructive close actions. A disconnected connection reports an error; it never falls back to a local session. HTTP DELETE and local MCP close use the same teardown, session-closed events and retained output tombstone. Repeating a close of a retained tombstone succeeds. Explicit close remains user-directed and is not limited to abandoned shells.
SSH Tunnel Management
Architecture
TunnelManager
└── TunnelSupervisor (per profile)
├── SSH child process (tokio::process::Command)
├── BackoffCalculator (reconnect timing)
├── ExitClassifier (stderr → ExitReason)
└── AuditLog (SQLite WAL)
The TunnelManager orchestrates multiple TunnelSupervisor instances, one per active tunnel profile. Each supervisor owns an SSH child process and runs a supervision loop:
- Validate the profile (fields, port ranges, duplicate bind ports)
- Check local port availability for all
-Lforwards - Spawn
sshwith constructed arguments (including agent forwarding ifSSH_AUTH_SOCKis found) - Require SSH to survive 500 ms and wait up to 30 seconds for every local
-Lforward to accept TCP connections; classify an SSH exit immediately - Mark as Connected and reset the backoff counter only after both checks pass (profiles without local forwards still require 500 ms survival)
- On process exit, classify the exit reason from stderr patterns and exit code
- If retryable, wait the backoff delay and loop; otherwise, stop
Tunnel starts claim a tokenized reservation before the first await. The
reservation is removed automatically if the start future fails or is cancelled,
but only when its token still owns the slot; a later start with the same profile
ID cannot be erased by an older cancelled future. Stop during startup removes
the reservation, prevents late supervisor publication, and suppresses the
Started audit record. Started is written only after the live handle is
published successfully.
Shutdown
TunnelSupervisor::stop() sends a signal via a oneshot channel. The supervision loop catches this at any tokio::select! point and performs graceful shutdown:
- Unix: the ssh child is spawned into its own process group (
Command::process_group(0)), and shutdown signals the whole group (kill(-pid, ...)), not just the direct child — SIGTERM first, wait up to 5 seconds, then SIGKILL to the group. A single-PID signal isn’t enough: a real leak was found where the ssh/fake-ssh process forked a further child that a single-PID SIGTERM never reached. Seegraceful_kill’s doc comment insupervisor.rs. - Windows:
taskkill /PID <id> /T /F(tree-kill) followed bychild.kill(). - Every kill path is followed by an explicit
child.wait()so the process is confirmed reaped, not just signaled —stop_and_wait/stop_and_take_task(below) depend on this to mean what they say.
stop()/shutdown_all() are fire-and-forget: they signal and return immediately, which is fine for a live, long-running app (the async cleanup finishes within a few seconds on the same runtime regardless of who’s watching). Where the caller needs actual confirmation the process died — because it’s about to disappear itself, or its own lifetime is too short to rely on “eventually” — use stop_and_wait(id) / shutdown_all_and_wait() instead, both bounded by GRACEFUL_SHUTDOWN_TIMEOUT (7s: the 5s SIGTERM grace period plus a scheduling/signal-delivery buffer) so neither can hang indefinitely.
Profile Configuration
Profiles are TOML files with this structure:
id = "550e8400-e29b-41d4-a716-446655440000"
name = "prod-db-tunnel"
host = "bastion.example.com"
port = 2222
user = "deploy"
identity_file = "/home/deploy/.ssh/id_ed25519"
auto_connect = true
[[forwards]]
type = "Local"
bind_port = 5432
remote_host = "db.internal"
remote_port = 5432
[[forwards]]
type = "Remote"
bind_port = 9090
local_host = "127.0.0.1"
local_port = 9090
[options]
server_alive_interval = 15
server_alive_count_max = 3
strict_host_key_checking = "Yes"
Storage Scopes
| Scope | Path | Precedence |
|---|---|---|
| Global | <config_dir>/tunnels/*.toml | Base |
| Per-repo | <repo>/.tuic/tunnels/*.toml | Overrides global (same ID) |
ProfileStore::load_all() merges both scopes, with per-repo profiles taking precedence.
Tunnel States
Starting ──────► Connected
│ │
│ ▼
│ Reconnecting ──► Connected (backoff reset)
│ │
│ ▼
▼ Stopped (max retries)
Error
│
▼
Stopped
| State | Meaning |
|---|---|
| Starting | SSH process is being spawned |
| Connected | SSH survived startup and every local forward accepts TCP connections |
| Reconnecting { attempt, reason } | Process exited with retryable reason; waiting backoff before retry |
| Stopped { reason } | Terminal state: user requested stop, max retries exceeded, or non-retryable exit |
| Error { message } | Validation failure or spawn error; no process was created |
Exponential Backoff
BackoffCalculator computes retry delays:
- Base: 1000ms
- Formula:
min(base * 2^attempt, 30000)+ jitter - Jitter: +/-25% of computed delay (uniform random)
- Floor: 100ms minimum delay
- Max retries: 10 (returns
Noneafter exhaustion) - Reset: called on successful connection (attempt counter returns to 0)
Example sequence (base values, before jitter): 1s, 2s, 4s, 8s, 16s, 30s, 30s, 30s, 30s, 30s
Exit Classification
classify_exit() inspects SSH stderr output first, then falls back to exit code:
| Pattern | ExitReason | Retryable |
|---|---|---|
| “Permission denied” / “Authentication failed” | AuthFailed | No |
| “Host key verification failed” / “REMOTE HOST IDENTIFICATION HAS CHANGED” | HostKeyMismatch | No |
| “Address already in use” / “Could not request local forwarding” | PortInUse | No |
| “Connection refused” | ConnectionRefused | Yes |
| “Network is unreachable” / “No route to host” | NetworkDown | Yes |
| “Connection timed out” | Timeout | Yes |
| Exit code 130 (SIGINT) / 137 (SIGKILL) | UserKilled | No |
Audit Logging
AuditLog uses SQLite with WAL journal mode for safe concurrent access.
Schema
CREATE TABLE tunnel_events (
id INTEGER PRIMARY KEY AUTOINCREMENT,
timestamp TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
tunnel_id TEXT NOT NULL,
kind TEXT NOT NULL,
detail TEXT NOT NULL DEFAULT '{}'
);
Indexed on tunnel_id and timestamp.
Event Kinds
Started, Connected, Disconnected, Error, Retry, Stopped
Operations
insert(tunnel_id, kind, detail)— Record an eventquery_by_tunnel(tunnel_id, limit)— Most recent N events for a tunnelquery_by_time_range(from, to)— Events within a time windowrotate(max_age_days)— Delete events older than N days
UI Components
TunnelsPanel
Main panel listing all tunnel profiles with:
- Profile name and host
- TunnelStatusBadge showing current state
- Start/Stop toggle button
- Edit button opening TunnelEditorModal
TunnelEditorModal
Form for creating and editing profiles:
- Name, host, port, user, identity file fields
- Port forwards list with add/remove and type-aware endpoint fields: Local forwards save
remote_host/remote_port, Remote forwards savelocal_host/local_port - Options section (keepalive, host key checking)
- Validation errors shown inline
TunnelStatusBadge
Color-coded status indicator:
- Green: Connected
- Blue (pulsing): Starting
- Orange: Reconnecting (shows attempt number)
- Red: Error
- Grey: Stopped
Integration with Remote Connection Manager
When creating an SSH remote connection (RemoteConnection with RemoteTransport::Ssh), a tunnel profile is automatically created to forward the daemon port. The tunnel supervisor manages the SSH connection, and the remote connection routes API calls through the forwarded port.
Module Map
| Module | Responsibility |
|---|---|
tunnels/profile.rs | Data model: TunnelProfile, ForwardSpec, ProfileOptions |
tunnels/command.rs | Build SSH command-line arguments from a profile |
tunnels/classifier.rs | Classify SSH exit reasons from stderr/exit code |
tunnels/agent.rs | Discover SSH_AUTH_SOCK for agent forwarding |
tunnels/port.rs | Check if a local TCP port is available |
tunnels/backoff.rs | Exponential backoff with jitter |
tunnels/audit.rs | SQLite audit log (WAL mode) |
tunnels/supervisor.rs | Per-tunnel supervision loop |
tunnels/storage.rs | TOML profile persistence (global + per-repo) |
tunnels/manager.rs | Orchestrate multiple supervisors |
tunnels/tauri_commands.rs | Tauri IPC command handlers (desktop) |
tunnels/commands.rs | HTTP command handlers (browser mode) |
Auto-Connect
Profiles with auto_connect: true are started automatically on app launch. The tunnel store’s hydrate() method loads all profiles, checks which are marked for auto-connect, and starts them if not already active. Hydration runs once and is guarded against duplicate calls.
The auto_connect field is persisted in the TOML profile:
auto_connect = true
SSH Agent Detection
detect_agent_type() inspects SSH_AUTH_SOCK to identify the running SSH agent:
Pattern in SSH_AUTH_SOCK | Detected Agent |
|---|---|
1password or 2BUA8C4S2C | 1Password |
secretive | Secretive |
gpg or gnupg | GPG Agent |
| (1Password socket exists but not active) | SSH Agent (1Password available) |
| (empty) | Not available |
| (other) | SSH Agent |
list_ssh_agent_keys() runs ssh-add -l to enumerate loaded keys, returning fingerprint, comment, and key type for each.
Orphan SSH Process Cleanup
When check_local_port() reports AddrInUse, the supervisor calls kill_ssh_on_port() before retrying:
lsof -ti tcp:<port> -sTCP:LISTENfinds PIDs listening on the portps -p <pid> -o comm=verifies each PID is ansshprocess- Only confirmed SSH processes receive
SIGTERM
This handles stale SSH tunnels left over from a previous app crash without killing unrelated processes.
check_local_port() also distinguishes PermissionDenied (ports below 1024 on macOS/Linux require root) from AddrInUse, providing specific error messages for each case.
Statusbar Shield
The status bar shows an SSH tunnel indicator:
- Grey shield — Tunnel profiles exist but none are currently connected
- Green shield with count badge — N tunnels are connected; the badge shows the count
Clicking the shield opens the Tunnels Panel.
Shutdown on Exit
When the app exits (RunEvent::Exit), TunnelManager::shutdown_all_and_wait() — not the fire-and-forget shutdown_all() — iterates all active supervisors, signals every one to stop concurrently, and waits (bounded by the same GRACEFUL_SHUTDOWN_TIMEOUT, shared across the whole batch rather than paid per tunnel) for confirmation that each one’s SSH process actually exited, before clearing the tunnel map. RunEvent::Exit blocks on this via tauri::async_runtime::block_on, the same way the design-mode and ACP shutdown steps in that same handler block on their own cleanup. This is load-bearing, not defensive: the fire-and-forget shutdown_all() only sends a signal and returns, and since the process is about to exit, nothing would otherwise be left running long enough to actually confirm the SSH child processes are gone — ensuring no orphaned SSH child processes survive after the app closes
Architecture Overview
Tech Stack
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | SolidJS + TypeScript | Reactive UI with fine-grained updates |
| Build | Vite + LightningCSS | Fast dev server, optimized CSS |
| Backend | Tauri (Rust) | Native APIs, PTY, git, system integration |
| Terminal | alacritty_terminal + canvas | Native VT engine with GPU-accelerated rendering |
| State | SolidJS reactive stores | Frontend state management |
| Persistence | JSON files via Rust | Platform-specific config directory |
| Testing | Vitest + SolidJS Testing Library (frontend), cargo nextest (backend) | ~5,700 frontend tests (vitest list) plus a comparable Rust suite (~4,800 #[test]/#[tokio::test] attributes under src-tauri/src) |
Hexagonal Architecture
The project follows hexagonal architecture with clear separation between layers:
┌──────────────────────────────────────────────┐
│ UI Layer │
│ SolidJS Components (render + user input) │
│ ┌──────┐ ┌───────┐ ┌─────────┐ ┌────────┐ │
│ │Sidebar│ │TabBar │ │Terminal │ │Settings│ │
│ └──┬───┘ └──┬────┘ └──┬──────┘ └──┬─────┘ │
├─────┼────────┼─────────┼───────────┼─────────┤
│ │ Application Layer (Hooks) │ │
│ ┌──┴────────┴─────────┴───────────┴──┐ │
│ │ useGitOps · usePty · useTerminals │ │
│ │ useGitHub · useDictation · etc. │ │
│ └──┬────────┬─────────┬─────────────┘ │
├─────┼────────┼─────────┼─────────────────────┤
│ │ State Layer (Stores) │ │
│ ┌──┴────────┴─────────┴──────┐ │
│ │ terminals · repositories │ │
│ │ settings · github · ui │ │
│ └──┬─────────────────────────┘ │
├─────┼────────────────────────────────────────┤
│ │ IPC / Transport Layer │
│ ┌──┴─────────────────────────────────┐ │
│ │ invoke.ts / transport.ts │ │
│ │ Tauri IPC (native) | HTTP (browser)│ │
│ └──┬─────────────────────────────────┘ │
├─────┼────────────────────────────────────────┤
│ │ Backend (Rust/Tauri) │
│ ┌──┴─────────────────────────────────┐ │
│ │ pty · git · github · config │ │
│ │ agent · worktree · dictation │ │
│ │ output_parser · error_classification│ │
│ └────────────────────────────────────┘ │
└──────────────────────────────────────────────┘
Design Principles
- Logic in Rust: All business logic, data transformation, and parsing implemented in the Rust backend. The frontend handles rendering and user interaction only.
- Cross-Platform: Targets macOS, Windows, and Linux. Uses Tauri cross-platform primitives.
- KISS/YAGNI: Minimal complexity, no premature abstractions.
- Dual Transport: Same app works as native Tauri desktop app or browser app via HTTP/WebSocket.
Directory Structure
src/
├── components/ # SolidJS UI components
│ ├── Terminal/ # Native terminal renderer (CanvasTerminal) with PTY integration
│ ├── Sidebar/ # Repository tree, branch list, CI rings
│ ├── TabBar/ # Terminal tabs with drag-to-reorder
│ ├── Toolbar/ # Window drag region, repo/branch display
│ ├── StatusBar/ # Status messages, zoom, dictation
│ ├── SettingsPanel/ # Tabbed settings (General, Agents, Services, etc.)
│ ├── GitPanel/ # Git panel (Changes, Log, Stashes)
│ ├── MarkdownPanel/ # Markdown file browser and renderer
│ ├── HelpPanel/ # Keyboard shortcuts documentation
│ ├── TaskQueuePanel/ # Agent task queue visualization
│ ├── PromptOverlay/ # Agent prompt interception UI
│ ├── PromptDrawer/ # Prompt library management
│ └── ui/ # Reusable UI primitives (CiRing, DiffViewer, etc.)
├── stores/ # Reactive state management
├── hooks/ # Business logic and side effects
├── utils/ # Pure utility functions
├── types/ # TypeScript type definitions
├── transport.ts # IPC abstraction (Tauri vs HTTP)
└── invoke.ts # Smart invoke wrapper
src-tauri/src/
├── lib.rs # App setup, plugin init, command registration
├── main.rs # Entry point
├── pty.rs # PTY session lifecycle
├── git.rs # Git cache and Tauri command adapters
├── github.rs # GitHub API and state adapters
├── config.rs # Configuration management
├── state.rs # Global state (sessions, buffers, metrics)
├── agent.rs # Agent binary detection and spawning
├── worktree.rs # Worktree config, events, and Tauri command adapters
├── prompt.rs # Prompt template processing
├── menu.rs # Native menu bar
├── mcp_http/ # HTTP/WebSocket + MCP server (routes split per area)
└── dictation/ # Voice application adapters
├── mod.rs # DictationState and domain re-exports
├── commands.rs # Tauri commands and event emission
├── browser.rs # Browser audio transport
├── adapters.rs # PTY delivery ports
├── model_download.rs # Whisper HTTP download
└── asset_download.rs # Speech asset HTTP download
src-tauri/crates/tuic-dictation/src/ # Audio, hands-free and speech domain
src-tauri/crates/ is a sibling of src-tauri/src/. tuic-core owns shared configuration and path utilities; tuic-terminal owns terminal parsing and buffers; tuic-git owns blocking Git reads, subprocesses, branch and worktree operations, artifact warming, and pure GitHub models and parsing. Root Git and GitHub adapters own Tokio scheduling, API clients, state, event emission, and Tauri commands.
Application Startup Flow
- Rust (
main.rs): Callstui_commander_lib::run() - Library (
lib.rs): CreatesAppState, loads config, spawns HTTP server if enabled, builds Tauri app with plugins, registers the Tauri command surface, and sets up the native menu - Frontend (
index.tsx): Mounts<App />component - App (
App.tsx): Initializes all hooks, callsinitApp()which hydrates stores from backend, detects binaries, sets up keyboard shortcuts, starts GitHub polling - Render: Full UI hierarchy with terminals, panels, overlays, and dialogs
Module Dependencies
App.tsx
├── useAppInit → hydrates all stores from Rust config
├── usePty → PTY session management via invoke()
├── useGitOperations → branch switching, worktree creation
├── useTerminalLifecycle → tab management, zoom, copy/paste
├── useKeyboardShortcuts → global keyboard handler
├── useGitHub → GitHub polling (uses githubStore)
├── useDictation → push-to-talk (uses dictationStore)
├── useQuickSwitcher → branch quick-switch UI
└── useSplitPanes → split terminal panes
Relay and Web Push cryptography
Relay AES-256-GCM and HKDF-SHA256 use ring. Web Push uses ring for
P-256 ephemeral ECDH, HKDF-SHA256, AES-128-GCM and ES256 VAPID signing.
The stored VAPID private key remains a base64url-encoded 32-byte scalar;
p256 derives its public point because ring requires both components when
loading a scalar. Push records retain the existing single-record framing,
exact record size, padding delimiter and HTTP headers. Fixed migration guards
pin the relay bytes, RFC8291 intermediate values and ciphertext, real push
request bodies, and stored-key VAPID verification with both implementations.
Data Flow
IPC Communication
TUICommander supports two IPC modes through a unified transport abstraction:
Tauri Mode (Native Desktop)
Frontend (SolidJS) ──invoke()──> Tauri IPC ──> Rust Command
Frontend (SolidJS) <──listen()── Tauri Events <── Rust emit()
- Zero-overhead RPC via
@tauri-apps/api/core.invoke() - Event subscription via
@tauri-apps/api/event.listen() - Used when running as native Tauri application
Browser Mode (HTTP/WebSocket)
Frontend (SolidJS) ──fetch()──> HTTP REST API ──> Rust Handler
Frontend (SolidJS) <──WebSocket── PTY Output Stream
- HTTP REST for all commands (mapped from Tauri command names)
- WebSocket for real-time PTY output streaming
- SSE for MCP JSON-RPC transport
- Used when running in browser via
pnpm dev
Transport Abstraction
src/invoke.ts provides invoke<T>(cmd, args) that resolves to the correct transport at module initialization:
// Zero overhead in Tauri - resolved once at import
const invoke = isTauri() ? tauriInvoke : httpInvoke;
src/transport.ts maps Tauri command names to HTTP endpoints:
mapCommandToHttp("get_repo_info", { path }) → GET /repo/info?path=...
mapCommandToHttp("create_pty", config) → POST /sessions
PTY Output Pipeline
Terminal output flows through multiple processing stages:
PTY Process (shell)
│
▼
Raw Bytes ──> Utf8ReadBuffer
│ (handles split multi-byte UTF-8 characters)
▼
UTF-8 String ──> EscapeAwareBuffer
│ (prevents splitting ANSI escape sequences)
▼
Safe String
├──> Ring Buffer (2 MB, for MCP access)
├──> WebSocket broadcast (for browser clients)
├──> Grid frame (alacritty_terminal) ──> Frontend: CanvasTerminal renders it
├──> OutputParser detects special events
│ (rate limits, PR URLs, progress, prompts)
└──> output_watchers.rs: assemble lines, clean, match plugin patterns
│
▼
Tauri Event ("pty-watcher-lines-{session_id}", {session_id, lines})
(browser: "watcher-lines" WS frame, "plugin-watcher-lines" SSE)
│
▼
pluginRegistry.handleWatcherLines() ──> OutputWatcher.onMatch()
Each PTY session has a dedicated reader thread (spawned in pty.rs) that reads from the PTY master fd in a loop.
State Management
Frontend Stores
SolidJS reactive stores hold all frontend state. Each store follows the pattern:
const [state, setState] = createStore<StoreType>(initialState);
// Public API exposed as object with methods
export const myStore = {
state, // Read-only reactive state
hydrate(), // Load from Rust backend
action(), // Modify state + persist to Rust
};
Store Dependency Graph
repositoriesStore ──references──> terminalsStore (terminal IDs per branch)
githubStore ──provides data to──> Sidebar (CI rings, PR badges), StatusBar (PR/CI badges)
settingsStore ──configures──> Terminal (font, theme, shell)
uiStore ──controls──> panel visibility, sidebar state
promptLibraryStore ──used by──> PromptDrawer, PromptOverlay
dictationStore ──manages──> dictation state, model downloads
notificationsStore ──plays──> sound alerts on terminal events
errorHandlingStore ──retries──> failed operations with backoff
statusBarTicker ──feeds──> StatusBar (rotating priority-based messages)
ideasStore ──provides──> IdeasPanel (ideas), StatusBar (badge count)
userActivityStore ──tracks──> StatusBar (merged PR grace period)
Persistence Flow
User Action
│
▼
Store.action()
├──> setState() (immediate reactive update)
└──> invoke("save_xxx_config", data) (async persist to Rust)
│
▼
Rust: save_json_config(filename, data)
│
▼
JSON file in platform config directory
Hydration Flow (App Startup)
useAppInit.initApp()
│
├──> repositoriesStore.hydrate() → load_repositories
├──> uiStore.hydrate() → load_ui_prefs
├──> settingsStore.hydrate() → load_app_config
├──> notificationsStore.hydrate() → load_notification_config
├──> repoSettingsStore.hydrate() → load_repo_settings
├──> repoDefaultsStore.hydrate() → load_repo_defaults
├──> promptLibraryStore.hydrate() → load_prompt_library
├──> ideasStore.hydrate() → load_notes
├──> keybindingsStore.hydrate() → load_keybindings
├──> agentConfigsStore.hydrate() → load_agents_config
└──> agentDetection.detectAll() → detect installed AI agents
Event System
Tauri Events (Backend → Frontend)
| Event | Payload | Source |
|---|---|---|
pty-watcher-lines-{session_id} | {session_id, lines} | PTY reader thread (plugin OutputWatchers) |
pty-exit-{session_id} | {session_id} | PTY child exit |
dictation-progress | {percent} | Model download |
menu-event | {id} | Native menu click |
Frontend Event Handling
Menu events are handled in App.tsx:
listen("menu-event", (event) => {
switch (event.payload.id) {
case "new-tab": handleNewTab(); break;
case "close-tab": closeTerminal(); break;
case "toggle-sidebar": uiStore.toggleSidebar(); break;
// ... 30+ menu actions
}
});
GitHub Polling
githubStore.startPolling()
│
▼
invoke("github_start_polling", {paths, issueFilter, prHideDrafts})
│
▼
Rust: github_poller loop (60s base, 120s when tab hidden,
300s max, exponential backoff on errors / rate limit)
│
├──> GraphQL batch query to GitHub API per repo
│
▼
Rust emits Tauri events (only when state changed since last poll):
├──> "github-pr-update" {repo_path, statuses}
├──> "github-issues-update" {repo_path, issues}
└──> "github-transition" — PR notifications on state changes
(merged, closed, blocked, ci_failed, changes_requested, ready)
│
▼
githubStore listen() handlers update store state
│
▼
Reactive updates to Sidebar CI rings, PR badges
PR State Filtering in StatusBar
The StatusBar applies lifecycle rules before displaying PR data:
githubStore.getBranchPrData(repoPath, branch)
│
├── state = CLOSED → never show (filtered out)
├── state = MERGED → show for 5 min of accumulated user activity, then hide
│ (userActivityStore tracks click/keydown events)
└── state = OPEN → show as-is (PR badge + CI badge)
Per-Repo Immediate Polls
On repo-changed events (git index/refs/HEAD changes), githubStore.pollRepo(path) triggers an immediate re-poll for that repo, debounced to 2 seconds to coalesce rapid git events.
Agent Usage Polling
Claude and Codex usage share one native feature slot managed by
src/features/agentUsage.ts. It follows the active terminal’s detected agent,
polls only that provider’s usage API, and labels every ticker result with its
provider so an asynchronous tab switch cannot render stale limits as the other
provider’s headroom.
initAgentUsage() (called from plugins/index.ts if not disabled)
│
active Claude/Codex tab change or every 5 min (API_POLL_MS)
│
▼
invoke("get_claude_usage_api" | "get_codex_usage_api")
│
▼
Rust: read the matching local provider credentials
→ HTTP GET to the provider usage endpoint
→ parse Claude or Codex rate-limit windows
│
▼
statusBarTicker.addMessage({
id: "claude-usage:rate",
pluginId: "claude-usage",
label: "Claude" | "Codex",
text: "5h: 42% · 7d: 18%",
priority: 10–90 (based on utilization),
onClick: openDashboard
})
│
▼
StatusBar renders ticker message
├── matching Claude/Codex label → absorbed into active agent badge
├── stale provider label on an agent tab → hidden until the new poll wins
└── non-agent tab → standalone ticker
Status Bar Ticker
The statusBarTicker store provides a priority-based rotating message system used by the shared Agent Usage feature and available to plugins via the ui:ticker capability.
statusBarTicker
│
├── Messages sorted by priority (descending)
├── Equal-priority messages rotate every 5s
├── Expired messages scavenged every 1s (TTL-based)
│
└── StatusBar rendering:
├── Agent badge absorbs a provider-matching Claude/Codex usage message
└── Standalone ticker for all other messages
Keyboard Shortcut Flow
KeyDown Event
│
▼
useKeyboardShortcuts (global listener)
│
├── Platform modifier detection (Cmd on macOS, Ctrl on Win/Linux)
├── Shortcut matching against registered handlers
│
▼
Handler execution (e.g., handleNewTab, toggleSidebar)
│
▼
Store updates → Reactive UI updates
Quick Switcher (held-key UI):
Cmd+Ctrl pressed (macOS) / Ctrl+Alt pressed (Win/Linux)
│
▼
Show branch overlay with numbered shortcuts
│
▼
Press 1-9 while holding modifier
│
▼
switchToBranchByIndex(index) → handleBranchSelect()
│
▼
Release modifier → hide overlay
State Management
Overview
State is split between the Rust backend (source of truth for persistence) and SolidJS frontend stores (reactive UI state).
Backend State (src-tauri/src/state.rs)
AppState
The central backend state, shared across all Tauri commands via State<'_, Arc<AppState>>:
AppState has 113 fields (state.rs:1328). The excerpt below is the PTY core
only — it is NOT the whole struct. Read state.rs for the rest; the remainder covers
the config cache, git/GitHub TTL caches, repo watchers, session states, MCP/agent
registries, worktree bookkeeping and the event bus.
#![allow(unused)]
fn main() {
pub struct AppState {
pub sessions: DashMap<String, Mutex<PtySession>>, // Active PTY sessions
pub(crate) data_dir: PathBuf, // Config/data directory
pub(crate) worktrees_dir: PathBuf, // Worktree storage path
pub(crate) metrics: SessionMetrics, // Atomic counters
pub output_buffers: DashMap<String, Mutex<OutputRingBuffer>>, // MCP output access
pub mcp_sessions: DashMap<String, McpSessionMeta>, // MCP Streamable HTTP sessions
pub ws_clients: DashMap<String, Vec<WsClientTx>>, // WebSocket clients per session
// ... 106 more fields
}
}
Concurrency model:
DashMapfor lock-free concurrent read/write of session mapsMutexfor interior mutability of individual PTY writers and buffersArc<AtomicBool>for pause/resume signaling per sessionAtomicUsizefor zero-overhead metrics counters
PtySession
#![allow(unused)]
fn main() {
pub type SharedPtyWriter = Arc<Mutex<Box<dyn Write + Send>>>;
pub struct PtySession {
pub writer: SharedPtyWriter, // Write to PTY (outside the session mutex)
pub master: Box<dyn MasterPty + Send>, // PTY master handle
pub(crate) _child: Box<dyn Child + Send + Sync>, // Child process
pub(crate) paused: Arc<AtomicBool>, // Pause flag
pub worktree: Option<WorktreeInfo>, // Associated worktree
pub cwd: Option<String>, // Working directory
pub display_name: Option<String>, // UI/agent/intent title
pub display_name_is_custom: bool, // Explicit user rename wins over OSC/intent
pub display_name_from_spawn: bool, // Named by agent spawn; OSC title must not replace it
pub is_remote: bool, // Created through HTTP/MCP, not the desktop UI
pub shell: String, // Resolved spawn command, kept for shell-family classification
}
}
writer is deliberately outside the session Mutex so a terminal-generated reply can
wait on an in-flight user write without blocking the reader thread.
SessionMetrics
Zero-overhead atomic counters:
#![allow(unused)]
fn main() {
pub(crate) struct SessionMetrics {
pub(crate) total_spawned: AtomicUsize,
pub(crate) failed_spawns: AtomicUsize,
pub(crate) active_sessions: AtomicUsize,
pub(crate) bytes_emitted: AtomicUsize,
pub(crate) pauses_triggered: AtomicUsize,
}
}
Buffer Types
| Buffer | Purpose | Capacity |
|---|---|---|
Utf8ReadBuffer | Accumulates bytes until valid UTF-8 boundary | Variable |
EscapeAwareBuffer | Holds incomplete ANSI escape sequences | Variable |
OutputRingBuffer | Circular buffer for MCP output access | 2 MB |
Constants
#![allow(unused)]
fn main() {
pub(crate) const MAX_CONCURRENT_SESSIONS: usize = 50;
pub(crate) const OUTPUT_RING_BUFFER_CAPACITY: usize = 2 * 1024 * 1024; // 2 MB
}
Frontend Stores
Store Pattern
All stores follow a consistent pattern:
// Internal reactive state
const [state, setState] = createStore<Type>(defaults);
// Exported as a module object
export const myStore = {
get state() { return state; }, // Read-only access
hydrate() { ... }, // Load from Rust
action() { ... }, // Mutate + persist
};
Store Registry
A subset — src/stores/ holds 60 store modules. The table covers the ones a
contributor meets first; it is not the full inventory.
| Store | File | Purpose | Persisted |
|---|---|---|---|
terminalsStore | terminals.ts | Terminal instances, active tab, split layout | Partial (IDs in repos) |
repositoriesStore | repositories.ts | Saved repos, branches, terminal associations, repo groups | repositories.json |
settingsStore | settings.ts | App settings (font, shell, IDE, theme, update channel) | config.json |
repoSettingsStore | repoSettings.ts | Per-repository settings (scripts, worktree) | repo-settings.json |
repoDefaultsStore | repoDefaults.ts | Default settings for new repositories | repo-defaults.json |
uiStore | ui.ts | Panel visibility, sidebar width | ui-prefs.json |
githubStore | github.ts | PR/CI data per branch, remote tracking (ahead/behind), PR state transitions | Not persisted |
promptLibraryStore | promptLibrary.ts | Prompt templates | prompt-library.json |
notificationsStore | notifications.ts | Notification preferences | notification-config.json |
dictationStore | dictation.ts | Dictation config and state | dictation-config.json |
errorLogStore | errorLog.ts | Error-log overlay open/closed | Not persisted |
rateLimitStore | ratelimit.ts | Active rate limits | Not persisted |
tasksStore | tasks.ts | Agent task queue | Not persisted |
promptStore | prompt.ts | Active prompt overlay state | Not persisted |
diffTabsStore | diffTabs.ts | Open diff tabs | Not persisted |
mdTabsStore | mdTabs.ts | Open markdown tabs and plugin panels | Not persisted |
ideasStore | ideas.ts | Ideas with repo tagging and used-at tracking | notes.json |
statusBarTicker | statusBarTicker.ts | Priority-based rotating status bar messages | Not persisted |
userActivityStore | userActivity.ts | Tracks last user click/keydown for activity-based timeouts | Not persisted |
updaterStore | updater.ts | App update state (check, download, install) | Not persisted |
keybindingsStore | keybindings.ts | Custom keyboard shortcut bindings | keybindings.json |
agentConfigsStore | agentConfigs.ts | Per-agent run configs and toggles | agents.json |
Key Store Relationships
repositoriesStore
│
├── BranchState.terminals: string[] ──references──> terminalsStore IDs
├── BranchState.worktreePath ──managed by──> worktree.rs
└── BranchState.additions/deletions ──from──> git.rs (get_diff_stats)
terminalsStore
│
├── TerminalData.sessionId ──maps to──> AppState.sessions key
├── TerminalData.agentType ──read by──> StatusBar (agent badge)
├── TerminalData.usageLimit ──read by──> StatusBar (usage display)
└── TabLayout.panes ──indexes into──> TerminalData[]
githubStore
│
├── Per-branch PR status ──from──> github.rs (get_repo_pr_statuses)
├── Per-repo remote status ──from──> github.rs (get_github_status)
├── CheckSummary ──drives──> CiRing component
└── PR state transitions ──emits to──> prNotificationsStore
statusBarTicker
│
├── TickerMessage[] ──rendered by──> StatusBar
├── Claude Usage messages ──from──> features/claudeUsage.ts (native)
└── Plugin messages ──from──> pluginRegistry (ui:ticker capability)
ideasStore
│
├── Note.repoPath ──filters by──> active repo
├── Note.usedAt ──marks when──> sent to terminal
└── filteredCount() ──drives──> StatusBar badge
settingsStore
│
├── font/theme ──configures──> Terminal component
├── shell ──passed to──> create_pty
├── ide ──used by──> open_in_app
└── updateChannel ──used by──> updaterStore
Debug Registry (MCP Introspection)
Stores self-register snapshot functions via src/stores/debugRegistry.ts. Snapshots are exposed on window.__TUIC__ and accessible through MCP debug(action=invoke_js).
| API | Returns |
|---|---|
__TUIC__.stores() | List of registered store names |
__TUIC__.store(name) | Snapshot of the named store |
Registered: github, globalWorkspace, keybindings, notes, paneLayout, repositories, settings, tasks, ui.
To register a new store, append at the bottom of the store file:
import { registerDebugSnapshot } from "./debugRegistry";
registerDebugSnapshot("name", () => ({ /* safe subset */ }));
Configuration Files
All config files are JSON, stored in the platform config directory:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/tuicommander/ |
| Linux | ~/.config/tuicommander/ |
| Windows | %APPDATA%/tuicommander/ |
Legacy path ~/.tuicommander/ is auto-migrated on first launch.
Config File Map
| File | Contents | Rust Type |
|---|---|---|
config.json | Shell, font, theme, MCP, remote access, update channel | AppConfig |
notification-config.json | Sound preferences, volume | NotificationConfig |
ui-prefs.json | Sidebar, error handling settings | UIPrefsConfig |
repo-settings.json | Per-repo scripts, worktree options | RepoSettingsMap |
repo-defaults.json | Default settings for new repos (base branch, scripts) | RepoDefaultsConfig |
repositories.json | Saved repos, branches, groups | serde_json::Value |
prompt-library.json | Prompt templates | PromptLibraryConfig |
dictation-config.json | Dictation on/off, hotkey, language, model | DictationConfig |
notes.json | Ideas/notes with repo tags and used-at timestamps | serde_json::Value |
keybindings.json | Custom keyboard shortcut overrides | serde_json::Value |
agents.json | Per-agent run configs and toggles | AgentsConfig |
claude-usage-cache.json | Incremental JSONL parse offsets for session stats | SessionStatsCache |
Terminal State Machine
Definitive reference for terminal activity states, notifications, and question detection.
State Variables
Each terminal has these reactive fields in terminalsStore:
| Field | Type | Default | Source of truth |
|---|---|---|---|
shellState | "busy" | "idle" | null | null | Rust (emitted as parsed event) |
awaitingInput | "question" | "error" | null | null | Frontend (from parsed events) |
awaitingInputConfident | boolean | false | Frontend (from Question event) |
activeSubTasks | number | 0 | Rust (parsed + stored per session) |
debouncedBusy | boolean | false | Frontend (derived from shellState with 2s hold) |
unseen | boolean | false | Frontend (set by fireCompletion, cleared on tab focus) |
agentType | AgentType | null | null | Frontend (from agent detection) |
agentState | "starting" | "working" | "awaiting_input" | "idle" | "completed" | null | null | Rust (session lifecycle snapshot) |
backgroundWork | boolean | false | Rust (session lifecycle snapshot) |
Rust-side per-session state:
| Field | Location | Purpose |
|---|---|---|
SilenceState.last_output_at | pty.rs | Timestamp of last real output (not mode-line ticks) |
SilenceState.last_chunk_at | pty.rs | Timestamp of last chunk of any kind (real or chrome-only). Used by backup idle timer to detect reader thread activity. |
SilenceState.last_status_line_at | pty.rs | Timestamp of last spinner/status-line |
SilenceState.pending_question_line | pty.rs | Candidate ?-ending line for silence detection |
SilenceState.output_chunks_after_question | pty.rs | Staleness counter: real-output chunks since last ? candidate |
SilenceState.question_already_emitted | pty.rs | Prevents re-emission of the same question |
SilenceState.suppress_echo_until | pty.rs | Deadline to ignore PTY echo of user-typed ? lines |
active_sub_tasks | AppState.session_states | Sub-agent count per session |
shell_states | AppState.shell_states | DashMap<String, AtomicU8>: 0=null/unobserved, 1=busy, 2=idle. Null is omitted on the wire and produces agent lifecycle starting; transitions use compare_exchange to prevent duplicate events when reader thread and silence timer race. |
last_output_ms | AppState.last_output_ms | Epoch ms of last real output (not chrome-only). Stamped only when !chrome_only. |
SessionState.background_work | AppState.session_states | Meaningful live agent descendant; persistent integration-helper subtrees are excluded, by name and by having started within 60s of the agent. Keeps task lifecycle working without changing terminal readiness. |
The Activity Dashboard uses an effective state rather than raw shellState: rate
limit/error/input take precedence; a ready composer is shown as Idle even when
the backend still tracks a long-lived background terminal. Otherwise lifecycle
starting/working (including backgroundWork) precedes completed, live shell
activity, and lifecycle or shell idle. Live shell busy intentionally overrides
a lagging lifecycle idle snapshot. The periodic session snapshot updates both lifecycle and shell state,
is serialized with a bounded native-IPC timeout, and records both the session
identity and shell-event revision at request start so a PTY event or session
replacement received while it is in flight wins.
A successful snapshot that omits a session marks its terminal exited and clears
its session and lifecycle fields; a transport failure leaves the existing state
untouched. The raw busy debounce is not a dashboard working signal, so a fresh
completed snapshot cannot remain working-styled or working-ordered; lifecycle
idle does so only when there is no newer live shell activity.
1. Tab Indicator — Visual Priority
The tab dot reflects the terminal’s highest-priority active state:
Priority State Color CSS var Condition
──────── ───── ───── ─────── ─────────
1 Error red --error awaitingInput == "error"
2 Question orange --attention awaitingInput == "question"
3 Busy blue ●̣ --activity debouncedBusy && !awaitingInput
4 Unseen purple --unseen unseen && !debouncedBusy && !awaitingInput
5 Done green --success shellState=="idle" && !unseen && !debouncedBusy && !awaitingInput
6 Idle gray (default) shellState==null or none of above
Error and Question have pulse animation. Busy has pulse animation. Unseen and Done are static.
Complete state combination matrix
Every valid combination of the 4 key fields and the resulting indicator:
awaitingInput debouncedBusy unseen shellState → Indicator
───────────── ───────────── ────── ────────── ──────────
"error" true any any → Error (red)
"error" false any any → Error (red)
"question" true any any → Question (orange)
"question" false any any → Question (orange)
null true any any → Busy (blue pulse)
null false true "idle" → Unseen (purple)
null false true null → Unseen (purple)
null false false "idle" → Done (green)
null false false "busy" → (transient: cooldown pending)
null false false null → Idle (gray)
Lifecycle of each indicator
┌──────────────────────── Error (red) ◄─── API error / agent crash
│ │
│ ┌──────────────────── Question (orange) ◄─── agent asks ?
│ │ │
│ │ ┌─────────────── Busy (blue) ◄─── real output detected
│ │ │ │
│ │ │ ┌────────── Unseen (purple) ◄─── completion fired,
│ │ │ │ │ user not watching
│ │ │ │ ┌───── Done (green) ◄─── user viewed unseen tab,
│ │ │ │ │ │ or short idle session
│ │ │ │ │ ┌─ Idle (gray) ◄─── no session / fresh
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
[ Higher priority wins when multiple states active ]
2. shellState — Derived in Rust
Rust is the single source of truth. The reader thread classifies every PTY chunk:
PTY chunk arrives in reader thread
│
▼
┌─────────────────────────────┐
│ Compute chrome_only: │
│ = no regex question found │
│ AND no ?-ending line │
│ AND changed_rows non-empty │
│ AND ALL changed rows pass │
│ is_chrome_row() (contain │
│ ⏵/›/✻/• markers) │
└─────────┬───────────────────┘
│
chrome_only?
╱ ╲
YES NO
│ │
▼ ▼
Mode-line tick Real output
(timer, spinner) (agent working)
│ │
│ ├── last_output_at = now
│ │
│ └── if shell_state ≠ busy:
│ emit ShellState { "busy" }
│ shell_state = busy
│
└── if shell_state == busy
AND last_output_at > threshold ago
(500ms for shell, 5s for agent sessions)
AND active_sub_tasks == 0
AND not in resize grace:
emit ShellState { "idle" }
shell_state = idle
A backup timer (the existing silence timer, 1s interval) also checks:
Silence timer (every 1s)
│
▼
reader thread active? ─── YES ──► skip
(last_chunk_at < 2s) (reader handles idle via !has_status_line guard)
│ NO
▼
shell_state == busy? ─── NO ──► skip
│ YES
▼
last_output_at > threshold ago? ─── NO ──► skip
(500ms shell / 2.5s agent)
│ YES
▼
active_sub_tasks == 0? ─── NO ──► skip
│ YES
▼
emit ShellState { "idle" }
shell_state = idle
This catches the case where NO chunks arrive at all (agent truly silent — reader
thread blocked on read()). When chrome-only chunks are arriving (mode-line timer
ticks), the reader thread is active and handles idle transitions correctly via its
own !has_status_line guard.
Session end
When the reader thread loop breaks (Ok(0)), Rust emits ShellState { "idle" } before
stopping, ensuring the frontend sees the final transition. The frontend then receives the
exit callback and sets sessionId = null.
Frontend consumption
pty-parsed event: ShellState { state }
│
▼
terminalsStore.update(id, { shellState: state })
│
▼
handleShellStateChange(prev, next) ← existing debounced busy logic
The frontend does NOT derive shellState from raw PTY data. handlePtyData updates
lastDataAt and the tab activity flag — but never touches shellState.
Transition table
| From | To | Trigger | Condition |
|---|---|---|---|
null | busy | First real output chunk | — |
busy | idle | Chrome-only chunk or silence timer | last_output_at > threshold (500ms shell / 2.5s agent) AND active_sub_tasks == 0 AND not resize grace |
idle | busy | Real output chunk | — |
busy | idle | Session ends (reader thread exit) | Always (cleanup) |
| any | null | Terminal removed from store | cleanup |
What does NOT cause transitions
| Event | Why it’s ignored |
|---|---|
Mode-line timer tick (✻ Cogitated 3m 47s) | Classified as chrome_only |
Status-line update (▶▶ ... 1 local agent) | Classified as chrome_only |
| ActiveSubtasks event | Updates counter, doesn’t produce real output |
| Resize redraw | Suppressed by resize grace (1s) |
3. debouncedBusy — Derived from shellState
Smoothed version with a 2-second hold to prevent flicker:
shellState events from Rust:
busy ─────────── idle ──── busy ─────── idle ──────────────────
│ │ │
debouncedBusy: │ │ │
true ──────────────┼─────────┼── true ────┼── true ──┐ false ──
│ │ │ │
└── 2s ───┘ └── 2s ───┘
cooldown cooldown
cancelled expires
| Event | debouncedBusy effect |
|---|---|
| shellState → busy | Immediately true. Cancel any running cooldown. Record busySince (first time only). |
| shellState → idle | Start 2s cooldown. If cooldown expires: set false, fire onBusyToIdle(id, duration). |
| shellState → busy during cooldown | Cancel cooldown. Stay true. Keep original busySince. |
onBusyToIdle fires exactly once per busy→idle cycle, after the 2s cooldown fully expires.
4. awaitingInput — Question and Error Detection
State diagram
Question event
(passes all guards)
┌──────┐ ┌──────────┐
│ null │────────────►│ question │
└──┬───┘ └─────┬────┘
│ │
│ ◄── clear triggers ──┘
│ (see table below)
│
│ Error event
│ (API error, agent crash)
│ ┌────────┐
└────────────────►│ error │
└───┬────┘
│
◄── clear triggers ──┘
(see table below)
Clear triggers
| Trigger | Clears “question”? | Clears “error”? | Why |
|---|---|---|---|
| StatusLine parsed event | Yes | Yes | Agent is working again (showing a task) |
| Progress parsed event | Yes | Yes | Agent is making progress |
User keystroke (terminal.onData) | Yes | Yes | User typed something — prompt answered |
| shellState idle → busy | Yes | No | Agent resumed real output (reliable post-refactor since mode-line ticks no longer cause idle→busy) |
| Process exit | Yes | Yes | Session over |
What does NOT clear awaitingInput
| Event | Why it doesn’t clear |
|---|---|
| shellState idle → busy | Clears "question" but not "error". API errors are persistent and need explicit agent activity (status-line) or process exit to clear. |
| Mode-line tick | Chrome-only output, not agent activity |
| activeSubTasks change | Sub-agent count changing doesn’t mean the main question was answered |
Notification sounds
Sounds play on transitions into a state, never on repeated sets or clearing:
getAwaitingInputSound(prev, current):
prev current sound
──── ─────── ─────
null → question → play "question"
null → error → play "error"
* → same → null (no sound)
* → null → null (clearing, no sound)
question→ error → play "error" (state changed)
error → question → play "question" (state changed)
5. unseen — Completion Visibility Tracking
unseen tracks whether the user has seen a completed task.
Lifecycle
┌─────────┐
fireCompletion() ──────────────────────►│ unseen │
(background tab, agent done) │ = true │
└────┬────┘
│
User clicks/switches to this tab ───────────►│
(setActive clears unseen) │
▼
┌─────────┐
│ unseen │
│ = false │
└─────────┘
What sets unseen
Only ONE place: App.tsx fireCompletion() sets unseen = true (along with activity = true).
What clears unseen
Only ONE place: terminalsStore.setActive(id) sets unseen = false.
Tab color transitions for unseen
Agent working Agent done User switches User switches
(background) (background) to other tab to THIS tab
│ │ │ │
▼ ▼ ▼ ▼
Blue ●̣ ───► Purple ● ────► Purple ● ────► Green ●
(busy) (unseen) (stays unseen) (done/idle)
6. activeSubTasks — Sub-agent Tracking
Parsed from the agent mode line by Rust OutputParser:
Mode line text Parsed count
────────────────────────────────────────── ────────────
"▶▶ bypass permissions on · 1 local agent" → 1
"▶▶ Reading files · 3 local agents" → 3
"▶▶ bypass permissions on" → 0
(no mode line) → unchanged
Stored in both Rust (AppState.active_sub_tasks) and frontend (terminalsStore).
Effects on other states
activeSubTasks
┌─────────────────────────────────────────────┐
│ │
▼ ▼
> 0 (agents running) == 0 (no agents)
┌────────────────────┐ ┌──────────────────┐
│ shellState: │ │ shellState: │
│ stays busy │ │ normal rules │
│ (idle blocked) │ │ (500ms timer) │
│ │ │ │
│ Question guard: │ │ Question guard: │
│ low-confidence │ │ passes through │
│ IGNORED │ │ │
│ │ │ │
│ Completion: │ │ Completion: │
│ SUPPRESSED │ │ normal rules │
└────────────────────┘ └──────────────────┘
Reset
| Event | Effect |
|---|---|
ActiveSubtasks { count: N } parsed event | Set to N |
UserInput parsed event | Reset to 0 (new agent cycle) |
| Process exit | Reset to 0 |
7. Completion Notification
Fires when an agent was busy for ≥5s then truly goes idle.
Two signals share one per-busy-cycle completion latch:
Path 1: Session exit (Terminal.tsx)
Process exits → reader thread ends → exit callback fires
│
├── terminal is active tab? → SKIP
├── cycle already notified? → SKIP
│
└── mark cycle notified → play("completion")
(does NOT set unseen — user may switch soon)
Path 2: Busy-to-idle (App.tsx) — sets unseen
onBusyToIdle(id, durationMs)
│
├── durationMs < 5s? ────────────────────── SKIP
├── terminal is active tab? ─────────────── SKIP
│
├── agentType set? ── YES ─► defer 10s ──► fireCompletion()
│ NO ──────► fireCompletion()
│
▼
fireCompletion()
│
├── cycle already notified? ───── SKIP (exit won the race)
├── terminal is active tab? ──── SKIP (user switched to it)
├── debouncedBusy still true? ── SKIP (went busy again)
├── terminal removed? ────────── SKIP
├── activeSubTasks > 0? ──────── SKIP (agents still running)
├── awaitingInput set? ────────── SKIP (question/error active)
│
▼
mark cycle notified
play("completion")
set unseen = true
→ tab turns purple (Unseen)
→ when user views: tab turns green (Done)
Sound deduplication
The first path to handle a busy cycle marks completionNotified. The other path
then exits without calling the notification manager. A subsequent idle→busy
transition resets the latch. This deduplicates an immediate process exit and a
delayed BUSY→IDLE callback even when they are more than the audio cooldown apart.
Timing under the new architecture
t=0 Agent starts working (real output) → shellState: busy
t=0..T Agent works. Mode-line ticks arrive but don't affect shellState.
t=T Agent stops real output. Mode-line may continue.
t=T+0.5 Shell session: Rust idle threshold (500ms) reached → shellState: idle
Agent session: still within 2.5s threshold → stays busy
(If sub_tasks > 0: stays busy regardless of threshold)
t=T+2.5 Shell: Cooldown expires → debouncedBusy: false → onBusyToIdle fires
Agent: Rust idle threshold (2.5s) reached → shellState: idle
t=T+4.5 Agent: Cooldown expires → debouncedBusy: false → onBusyToIdle fires
t=*+0 duration = T seconds. If T ≥ 5s and agentType:
→ defer 10s → fireCompletion
t=*+10 fireCompletion checks all guards → play("completion"), unseen=true
8. Question Detection Pipeline
Two layers: Rust detection → Frontend notification.
Rust: Two parallel detection strategies
┌─────────────────────────────────────────────────────────────────┐
│ READER THREAD (per chunk) │
│ │
│ PTY data → parse_clean_lines(changed_rows) → events[] │
│ │
│ ┌─ Strategy A: Regex (instant) ──────────────────────────────┐ │
│ │ parse_question() matches "Enter to select" │ │
│ │ → Question { confident: true } │ │
│ │ → emitted immediately in the events list │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Strategy B: Silence (delayed) ────────────────────────────┐ │
│ │ extract_question_line(changed_rows) │ │
│ │ → finds last line ending with '?' that passes │ │
│ │ is_plausible_question() filter │ │
│ │ → stored as pending_question_line in SilenceState │ │
│ │ → NOT emitted yet — waits for silence timer │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ on_chunk() updates SilenceState: │
│ - regex fired? → clear pending, mark emitted │
│ - echo suppress window? → ignore '?' line │
│ - same line already emitted? → ignore (repaint) │
│ - new '?' line? → set as pending candidate │
│ - real output after '?'? → increment staleness │
│ - mode-line tick? → do nothing │
│ - staleness > 10? → clear pending (agent kept working) │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ SILENCE TIMER (every 1s) │
│ │
│ is_silent()? │
│ ├── question_already_emitted? → skip │
│ ├── is_spinner_active()? → skip (status-line < 10s ago) │
│ └── last_output_at < 10s? → skip │
│ │
│ If silent (all three pass): │
│ │
│ ┌─ Strategy 1: Screen-based ────────────────────────────────┐ │
│ │ Read VT screen → extract_last_chat_line() │ │
│ │ → find line above prompt (❯, ›, >) │ │
│ │ → ends with '?' AND is_plausible_question()? │ │
│ │ → emit Question { confident: false } │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Strategy 2: Chunk-based fallback ────────────────────────┐ │
│ │ check_silence() → pending_question_line exists? │ │
│ │ AND not stale (≤ 10 real-output chunks after)? │ │
│ │ → verify_question_on_screen() (bottom 5 rows) │ │
│ │ → emit Question { confident: false } │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ If neither strategy finds a question: continue sleeping. │
└─────────────────────────────────────────────────────────────────┘
SilenceState update rules
| Chunk type | last_chunk_at | last_output_at | last_status_line_at | staleness counter | pending_question_line |
|---|---|---|---|---|---|
| Real output, no ‘?’ | Reset to now | Reset to now | — | +1 (if pending exists) | Cleared if >10 |
| Real output with ‘?’ | Reset to now | Reset to now | — | Reset to 0 | Set to new line |
| Real output + status-line | Reset to now | Reset to now | Reset to now | (per above rules) | (per above rules) |
| Mode-line tick only | Reset to now | Not reset | Not reset | Not incremented | Not affected |
| Regex question fired | Reset to now | Reset to now | — | Reset to 0 | Cleared (handled) |
Frontend: event handler + notification
pty-parsed: Question { prompt_text, confident }
│
▼
┌──────────────────────────────────────────────────┐
│ Guard: low-confidence question while agent busy │
│ │
│ NOT confident │
│ AND (shellState == "busy" │
│ OR activeSubTasks > 0)? │
│ │
│ YES → IGNORE (likely false positive) │
│ NO → continue │
└──────────────────┬───────────────────────────────┘
│
▼
setAwaitingInput(id, "question", confident)
│
▼
createEffect detects transition (null → "question")
│
▼
play("question")
9. Timing Constants
| Constant | Value | Location | Purpose |
|---|---|---|---|
| Shell idle threshold | 500ms | pty.rs (Rust) | Real output silence before idle (plain shell) |
| Agent idle threshold | 2.5s | pty.rs (Rust) | Real output silence before idle (agent sessions) |
| Debounce hold | 2s | terminals.ts | debouncedBusy hold after idle |
| Silence question threshold | 10s | pty.rs | Silence before ‘?’ line → question |
| Silence check interval | 1s | pty.rs | Timer thread wake frequency |
| Backup idle chunk threshold | 2s | pty.rs | Skip backup idle if any chunk arrived within this window |
| Stale question chunks | 10 | pty.rs | Real-output chunks before discarding ‘?’ candidate |
| Resize grace | 1s | pty.rs | Suppress all events after resize |
| Echo suppress window | 500ms | pty.rs | Ignore PTY echo of user-typed ‘?’ lines |
| Screen verify rows | 5 | pty.rs | Bottom N rows checked for screen verification |
| Completion threshold | 5s | App.tsx | Minimum busy duration for completion notification |
| Completion deferral | 10s | App.tsx | Extra wait for agent processes (sub-agents may still run) |
10. Scenarios
A: Agent asks “Procedo?” — no sub-agents
t=0 Agent outputs "Procedo?" (real output)
→ shellState: busy
→ pending_question_line = "Procedo?"
→ last_output_at = now
t=2.5 No more real output. Rust idle check:
last_output_at > 2.5s (agent threshold), active_sub_tasks=0
→ shellState: idle │ Tab: blue→(cooldown)
→ debouncedBusy cooldown starts (2s)
t=1-9 Mode-line ticks arrive (chrome_only=true)
→ shellState stays busy (agent threshold not reached)
→ pending_question_line preserved
t=4.5 Cooldown expires → debouncedBusy: false
→ onBusyToIdle fires (duration ~2.5s < 5s → no completion)
│ Tab: blue→green (Done)
t=10 Silence timer: is_silent()? YES
→ Strategy 1 or 2 finds "Procedo?"
→ emit Question { confident: false }
→ Frontend: guard passes (idle, subTasks=0)
→ awaitingInput = "question"
→ play("question") ✓
│ Tab: green→orange (Question)
t=??? User types response → UserInput event
→ clearAwaitingInput
│ Tab: orange→green (Done)
→ agent resumes → status-line → clearAwaitingInput (redundant, safe)
│ Tab: green→blue (Busy)
B: Agent asks “Procedo?” — sub-agents running
t=0 Agent outputs "Procedo?" while 2 sub-agents run
→ shellState: busy │ Tab: blue
→ pending_question_line = "Procedo?"
→ active_sub_tasks = 2
t=0.5+ No more real output but active_sub_tasks > 0
→ shellState stays busy (Rust: idle blocked)
t=10 Silence timer: is_silent()? YES
→ emit Question { confident: false }
→ Frontend: activeSubTasks=2 > 0, NOT confident → IGNORED
t=60 Last sub-agent finishes → ActiveSubtasks { count: 0 }
t=62.5 Rust: last_output_at > 2.5s (agent threshold), sub_tasks=0
→ shellState: idle │ Tab: blue→(cooldown)
t=64.5 Cooldown expires → onBusyToIdle(duration=60s)
→ ≥ 5s, agentType set → defer 10s
t=74.5 fireCompletion()
→ activeSubTasks=0, awaitingInput=null
→ play("completion") ✓, unseen=true
│ Tab: purple (Unseen)
User switches to tab → unseen cleared
│ Tab: purple→green (Done)
C: Ink menu — “Enter to select”
t=0 Agent renders Ink menu with "Enter to select" footer
→ parse_question() regex match (INK_FOOTER_RE)
→ emit Question { confident: true } immediately
→ SilenceState: pending cleared, question_already_emitted = true
t=0 Frontend: confident=true → guard skipped (always passes)
→ awaitingInput = "question"
→ play("question") ✓
│ Tab: orange (Question)
No 10s wait needed — instant detection.
D: False positive — agent discusses code with ‘?’
t=0 Agent outputs "// Should we use HashMap?"
→ is_plausible_question → false (starts with //)
→ NO candidate set
t=0 Agent outputs "Does this look right?"
→ is_plausible_question → true
→ pending_question_line = "Does this look right?"
t=0.1+ Agent continues with more real output (non-'?')
→ staleness +1, +2, ... +11 (> STALE_QUESTION_CHUNKS=10)
→ pending_question_line cleared
t=10+ Silence timer: pending is None → nothing emitted ✓
│ No false notification
E: Agent completes long task — no question
t=0 Agent starts working (real output)
→ shellState: busy │ Tab: blue
t=120 Agent finishes, goes to prompt. No more real output.
t=122.5 Rust: last_output_at > 2.5s (agent threshold), sub_tasks=0
→ shellState: idle │ Tab: blue→(cooldown)
t=124.5 Cooldown expires → onBusyToIdle(duration=120s)
→ ≥ 5s, agentType set → defer 10s
t=134.5 fireCompletion()
→ all guards pass
→ play("completion") ✓, unseen=true
│ Tab: purple (Unseen)
User switches to tab → unseen cleared
│ Tab: purple→green (Done)
F: User watches terminal — active tab
t=0 Agent working in active tab (user watching)
→ shellState: busy │ Tab: blue
t=60 Agent finishes → idle
t=62 onBusyToIdle fires
→ terminal IS active tab → SKIP
→ no sound, no unseen
│ Tab: blue→green (Done) — user was watching
G: Short command — under 5s
t=0 User runs `ls` → shellState: busy │ Tab: blue
t=0.1 Output finishes → idle
t=2.1 Cooldown expires → onBusyToIdle(duration=0.1s)
→ duration < 5s → SKIP
→ no sound, no unseen
│ Tab: blue→green (Done)
H: Process exits in background tab
t=0 Agent working in background tab
→ shellState: busy │ Tab: blue
t=60 Process exits → reader thread ends
→ Rust emits ShellState { "idle" }
→ Frontend exit callback:
sessionId = null, clearAwaitingInput
mark cycle notified, play("completion") [Path 1] ✓
t=62 Cooldown expires → onBusyToIdle(duration=60s)
→ fireCompletion [Path 2] sees cycle notified → SKIP
│ Tab remains Done
User switches to tab → unseen cleared
│ Tab: purple→green (Done)
I: Rate-limit detected
t=0 Agent output matches rate-limit pattern
→ RateLimit parsed event emitted
t=0 Frontend handler:
shellState == "busy"?
YES → IGNORE (false positive from streaming code)
NO → agentType set, not recently detected?
YES → play("warning") ✓, rateLimitStore updated
NO → SKIP (dedup)
J: Resize during question display
t=0 "Procedo?" visible on screen, awaitingInput = "question"
│ Tab: orange (Question)
t=X User resizes terminal pane
→ resize_pty called → SilenceState.on_resize()
→ Shell redraws visible output (real PTY output)
→ Rust: shellState → busy (real output)
t=X Resize grace active (1s):
→ All notification events SUPPRESSED (Question, RateLimit, ApiError)
→ "Procedo?" in redraw doesn't re-trigger question
t=X+1 Grace expires. awaitingInput still "question" (never cleared).
│ Tab stays orange ✓
K: Agent error (API error, stuck)
t=0 Agent output matches API error pattern
→ ApiError parsed event emitted
t=0 Frontend handler:
→ awaitingInput = "error"
→ play("error") ✓
│ Tab: red (Error)
User answers / agent retries → StatusLine event
→ clearAwaitingInput
│ Tab: red→blue (Busy)
L: Question then error (priority override)
t=0 Agent asks question → awaitingInput = "question"
│ Tab: orange (Question)
t=5 API error while question is pending
→ awaitingInput = "error" (overrides question)
→ play("error") ✓
│ Tab: orange→red (Error)
Agent recovers → StatusLine event
→ clearAwaitingInput
│ Tab: red→blue (Busy)
11. File Reference
| File | Responsibility |
|---|---|
src-tauri/src/pty.rs | SilenceState, spawn_silence_timer, shellState derivation, extract_question_line, verify_question_on_screen, extract_last_chat_line, spawn_reader_thread |
src-tauri/crates/tuic-terminal/src/output_parser.rs | parse_question (INK_FOOTER_RE), parse_active_subtasks, ParsedEvent enum |
src-tauri/src/state.rs | AppState (includes shell_state, active_sub_tasks maps) |
src/stores/terminals.ts | shellState, awaitingInput, debouncedBusy, handleShellStateChange, onBusyToIdle |
src/components/Terminal/Terminal.tsx | handlePtyData (grid frame render), pty-parsed event handler, process-exit completion fallback |
src/components/Terminal/awaitingInputSound.ts | getAwaitingInputSound edge detection |
src/hooks/useTerminalCompletionNotifications.ts | onBusyToIdle → completion notification with deferral, guards, and per-cycle latch |
src/stores/notifications.ts | play(), playQuestion(), playCompletion() etc. |
src/components/TabBar/TabBar.tsx | Tab indicator class priority logic |
src/components/TabBar/TabBar.module.css | Indicator colors and animations |
Acknowledge MCP Agent Submission in One Call
Status
Accepted for implementation on 2026-08-27.
Motivation
session action=input can write text and Enter in one request, but its
{"ok":true} response proves only that bytes were written to the PTY. A caller
that needs to hand a command to a managed Codex session must then infer whether
the raw-mode composer submitted it. Splitting text and Enter is worse: another
writer can intervene, and Codex can treat the Enter as a composer newline.
Decision
Add session action=submit for one non-empty managed-agent command. The action
claims a confirmed-idle, empty composer; writes the existing Ctrl-U, 50 ms gap, bracketed
paste, 50 ms gap, and CR sequence; advances the existing input FSM and turn
epoch; then waits internally for bounded post-Enter terminal movement. One MCP
response carries the submission id, write state, acknowledgement state, turn
epoch, composer state, retry safety, and observed output offset.
The action never queues. A pre-existing partial composer, confident interactive
question, unconfirmed/busy agent, older queued injection, missing observation
buffer, or lost claim rejects before the first byte. This preserves drafts,
interactive dialogs, and the existing shared FIFO. A peer arriving after the
claim sees BUSY and queues behind the submitted command; a peer that claims
first makes submit reject, so their PTY payloads cannot splice.
session action=input remains the raw input/key compatibility surface. It does
not gain receipt semantics. Slash commands, including /clear, use submit and
the same acknowledgement contract; readiness movement is evidence, not a
special success shortcut.
Why Existing Mechanisms Are Insufficient
ok:trueis write completion, not terminal acknowledgement.turn_epochand the clearedInputLineBufferare mutated by TUICommander’s own bookkeeping, so neither can prove that the child terminal reacted.session action=statusandoutputrequire a second client call and race with fast commands.- The deferred Compose/peer queue acknowledges acceptance into a FIFO, not submission of this command during this response.
Alternatives Considered
- Strengthen
inputwhen text and Enter are combined. Rejected becauseinputis an established raw terminal primitive whose callers also prefill composers and answer interactive dialogs. - Return success after advancing
turn_epoch. Rejected because that epoch is caused by local bookkeeping and would reproduce the false positive under a new field name. - Queue when the composer is busy. Rejected because acknowledgement would then outlive the bounded MCP request and reorder ownership with existing queued messages.
- Require a follow-up
statusoroutputcall. Rejected because the objective is one authoritative response and fast transitions can occur between calls.
Trade-offs
The receipt proves a completed PTY write plus independent post-Enter terminal movement; it does not prove that the application understood the command or that the requested work succeeded. The bounded wait adds up to three seconds by default to the MCP call and uses the existing raw-output offset and agent screen state as evidence. A terminal that reacts before the post-Enter boundary can produce a conservative timeout rather than a false acknowledgement.
Failure Semantics
Rejections and writes that provably never start are retry-safe. A partial write,
completed write without acknowledgement before the deadline, session exit, or
superseding turn is retry_safe:false: the caller must not replay automatically
because the command may already be active. Timeout reports write_state:complete
and acknowledged:false; it never reports application acceptance. Optional
timeout_ms is clamped to 250–10,000 ms, default 3,000 ms.
Lifecycle and Ownership
The PTY injection claim owns ordering from readiness check through the split write. The input FSM owns composer reconstruction, slash mode, prompt capture, and turn advancement. The raw-output ring and existing screen adapter own acknowledgement evidence. The MCP handler owns the bounded wait and receipt serialization. No durable submission registry is created: the receipt lives for one request, while ordinary per-session lifecycle state continues afterwards.
Ego issue triage: read-only execution boundary
Story: 2450-6845. Status: implemented.
Contract and executor selection
An admitted issue triage definition can select:
triage_executor: { "kind": "managed" }(the default): itsrun_confignames an external managed executor. Its absence of write tools and push credentials is operator-attested, not enforced by TUIC.triage_executor: { "kind": "ego", "provider_env": "OPENROUTER_API_KEY" }: TUIC enforces a data-only ACP launch with a cleared initial child environment. Ego enforces the exclusive read-only policy.provider_envis optional and accepts onlyOPENROUTER_API_KEY,OPENAI_API_KEY,ANTHROPIC_API_KEYorGEMINI_API_KEY. Only the selected provider variable is forwarded.
The ego executor uses the configured ego_executable, not run_config or the
AI Chat profile. Profiles are incompatible with ego’s exclusive policy. Keep
run_config nonblank for the stored definition schema; it is ignored by ego
triage. read_only_attested can be false for this executor. Only an admitted
triage run may use it; manual, scheduled and implementation launches cannot.
Native workflow import refuses this executor rather than silently replacing its
read-only guarantee with a different workflow.
Launch and authority
The exact process arguments are:
ego acp -C <workspace> --exclusive-read-only [--env-allow <provider_env>]
TUIC resolves the configured executable and uses Command::env_clear() before
spawn. It constructs the child environment from platform values plus, at most,
the selected provider variable. Platform values are PATH, HOME, EGO_HOME,
TMPDIR, TMP, TEMP, LANG, TZ, LC_*, certificate paths
(SSL_CERT_FILE, SSL_CERT_DIR), Windows user/system directories and macOS
__CF_USER_TEXT_ENCODING. Windows names compare without case. Proxy variables
are not forwarded. No GitHub token, SSH agent socket, git credential-helper
setting or TUIC peer/control-plane identity is forwarded. An absent provider
variable is not replaced with another provider’s credential. Ego may use its
own configured provider authentication; TUIC does not read a credential store.
The host’s dedicated ACP driver sends initialize (protocol version 1), then
session/new with cwd=<workspace> and mcpServers=[], then one
session/prompt containing the acceptance policy and issue title/body. Before
launch, the host fetches that issue using its own GitHub API, checks the workspace
remote against the admitted repository and compares the requirements digest. A
changed issue or missing admission digest fails closed, before ego is spawned.
It refuses every agent-to-host request, including filesystem, terminal and
permission requests. It does not register a terminal, managed peer or host MCP
server. Total protocol output is bounded to 4 MiB.
The generic ACP SDK launcher is deliberately not used for this executor: SDK 2.0.0 adds environment overrides but inherits the parent environment. An ego restart that clears inherited variables is too late to protect the initial child. Other ACP callers keep their existing behavior.
Ego story 950-32d4 (landed in a6b47016e) supplies the immutable
--exclusive-read-only policy: no native/MCP tools, hooks, skills or prompt
commands; incompatible profile/tool settings fail closed. Its ACP session
rejects nonempty mcpServers. Source: ego
docs/internals/950-acp-exclusive-readonly-design.md and
crates/ego-cli/src/exclusive_env.rs.
Decision and lifecycle
The evaluator returns only JSON with outcome (accepted, rejected or
needs_input) and a nonempty reason of at most 4000 bytes. TUIC accepts only
an ACP end_turn, validates the JSON, and records the decision internally for
the host-owned run. The evaluator receives no decision-reporting MCP tool and
no GitHub publication credentials. The existing host publisher alone can add a
comment or label, using the existing issue digest and publication ledger.
The run’s saved definition pins the executor and provider selection. Dispatch
rechecks the policy and definition; cancellation and policy withdrawal stop
the owned child. The definition’s maximum duration covers ACP startup and the
turn. Timeout is recorded as timed_out. Restart recovery never retries an
interrupted evaluator. Publication also checks the current executor selection.
The external managed executor and its caller-bound reporting path are unchanged.
Evidence and limits
The single launch regression uses the existing local ACP fixture executable.
It re-executes only its own test to seed fake GH_TOKEN, SSH_AUTH_SOCK,
GIT_CONFIG_COUNT, TUIC_SESSION and an unselected provider key in the actual
parent environment, without racing other tests through environment mutation.
The fixture requires the exact exclusive-policy/provider flags and empty MCP
session, checks that forbidden values are absent and the selected fake provider
value is present, and returns a structured decision. It makes no model call or
GitHub write. Ego’s own policy tests cover tool, hook and push refusal; TUIC does
not duplicate those tests.
The trusted ego executable, provider transport and the model’s decision quality remain assumptions. This policy is not operating-system isolation of the trusted ego executable. No credential store or keychain was read during implementation.
Agent UI Analysis — General Reference
Cross-agent reference for parsing AI agent terminal UIs in TUICommander.
Agent-specific layouts are documented in agents/<name>.md.
Scope
TUICommander supports multiple AI coding agents. Each has a unique terminal UI with different rendering approaches, chrome patterns, and interaction models. This document covers:
- Shared concepts and detection strategies
- Code architecture and known gaps
- Research methodology for ongoing verification
Agent-specific documents:
- Claude Code — Ink-based, ANSI cursor positioning
- Codex CLI — Ink-based, absolute positioning + scroll regions
- Gemini CLI — Ink-like, relative positioning + prompt box
- OpenCode — Bubble Tea full-screen TUI
- pi — full-frame snapshot adapter around a stable footer
Detection Strategy Per Agent
Each agent class requires a different parsing strategy:
| Agent | UI Type | Parsing Strategy | chrome.rs applies? |
|---|---|---|---|
| Claude Code | CLI inline (Ink) | Changed-rows delta analysis | Yes |
| Codex CLI | CLI inline (Ink) | Changed-rows delta analysis | Yes |
| OpenCode | Full-screen TUI (Bubble Tea) | Screen snapshot analysis | No (all rows are “chrome”) |
| Gemini CLI | CLI inline | Changed-rows delta analysis | Yes |
| pi | Full-screen TUI | Screen snapshot analysis | No (footer adapter) |
CLI inline agents (CC, Codex, Gemini) render output into the
terminal sequentially, with chrome at specific positions. chrome.rs
functions work for these — is_separator_line, is_prompt_line,
is_chrome_row classify individual rows.
Full-screen TUI agents (OpenCode, pi) take over the entire screen. Every row changes on every update, making delta analysis useless. These need screen-snapshot-based parsing: identify panels by position, extract text from known regions, detect state changes by content comparison.
Shared Concepts
Chrome Detection
“Chrome” = UI decoration rows that are NOT real agent output (separators, mode lines, status bars, spinners, menus). Correctly classifying chrome is critical for:
- Silence-based question detection: chrome-only chunks should not reset the silence timer or invalidate pending questions
- Shell state transitions: chrome-only output should not prevent BUSY → IDLE transitions
- Log trimming: chrome should be stripped from mobile logs and REST API responses
Prompt Line
The row where the user types input. Each agent uses a different character:
| Agent | Prompt char | Unicode |
|---|---|---|
| Claude Code | ❯ | U+276F |
| Codex CLI | › | U+203A |
| Gemini CLI | > | ASCII |
Separator Lines
Horizontal rules that delineate sections. Detected by a run of 4+
box-drawing characters (─ ━ ═ — ╌ ╍). Not all agents use separators.
| Agent | Uses separators | Style |
|---|---|---|
| Claude Code | Yes | ──── around prompt box |
| Codex CLI | Partially | ──── between tool output and summary only |
| Gemini CLI | No | — |
Interactive Menu Detection
All observed agent menus share the pattern Esc to in their footer:
| Footer variant | Agent / Context |
|---|---|
Esc to cancel · Tab to amend | CC permission prompt |
Enter to select · Tab/Arrow keys to navigate · Esc to cancel | CC custom Ink menu |
↑↓ to navigate · Enter to confirm · Esc to cancel | CC built-in (/mcp) |
Esc to cancel · r to cycle dates · ctrl+s to copy | CC built-in (/stats) |
←/→ tab to switch · ↓ to return · Esc to close | CC built-in (/status) |
Enter to select · ↑/↓ to navigate · Esc to cancel | CC Ink select |
esc again to edit previous message | Codex (after interrupt) |
Esc to is the most reliable cross-agent signal for “interactive menu active.”
OSC Sequences
Terminal escape sequences that carry structured metadata:
| Sequence | Purpose | Agent |
|---|---|---|
\033]777;notify;Claude Code;...\007 | User attention notification | CC |
\033]0;...\007 | Window title (task name + spinner) | CC, Codex |
\033]8;;url\007 | Hyperlink | CC |
\033]9;4;N;\007 | Progress notification | CC |
\033]10;?\033\\ | Query foreground color | Codex |
\033]11;?\033\\ | Query background color | Codex |
Code Architecture
Unified chrome.rs module
All chrome detection is centralized in src-tauri/crates/tuic-terminal/src/chrome.rs. The three
pipelines (pty.rs, session.rs, state.rs) all import from this single module:
src-tauri/crates/tuic-terminal/src/chrome.rs
├── is_separator_line() — run-of-4 box-drawing chars (─ ━ ═ — ╌ ╍)
├── is_prompt_line() — all agent prompt chars: ❯ › >
├── is_agent_prompt_row() — BARE prompt only (no echoed user message, no `> quote`)
├── is_chrome_row() — 10 marker chars + dingbat range + Codex • disambiguation
├── CHROME_SCAN_ROWS — single constant (15)
├── find_chrome_cutoff() — screen trim (transient: over-trim self-corrects next repaint)
└── find_scrollback_chrome_cutoff() — history trim (permanent: prompt anchor only)
| Pipeline | File | What it uses from chrome.rs |
|---|---|---|
| Changed-rows parser | pty.rs | is_chrome_row (for chrome_only), is_separator_line, is_prompt_line |
| Screen trim (REST) | session.rs | find_chrome_cutoff (replaces local trim_screen_chrome body) |
| Log trim (mobile) | state.rs | find_scrollback_chrome_cutoff via mark_agent_chrome |
Screen trim vs scrollback trim
The two cutoffs are deliberately different because the cost of a false positive is
different. The screen is re-rendered every frame, so an over-trim disappears on
the next repaint — find_chrome_cutoff can afford a separator-only anchor and the
loose is_prompt_line. Scrollback is permanent history, so
find_scrollback_chrome_cutoff anchors only on a bare prompt row:
- A standalone separator is not an anchor — markdown tables, progress bars and
Codex’s
└ ────dividers all carry box-drawing runs mid-output. - A prompt row carrying text is the agent echoing the user’s submitted message
(
❯ rename is broken,› riprendiamo) — that is the conversation, not chrome.
Scrollback classification also marks rather than deletes (LogLine::chrome);
readers skip flagged lines, so a misclassification hides text instead of destroying
it.
Parsing Functions
Chrome Detection (is_chrome_row) — chrome.rs
Classifies changed terminal rows as “UI decoration” vs “real agent output”.
Detected markers:
⏵(U+23F5) — CC mode-line prefix⏸(U+23F8) — CC plan mode prefix›(U+203A) — CC/Codex mode-line prefix·(U+00B7) — CC middle-dot spinner prefix▀(U+2580) — Gemini prompt box top border▄(U+2584) — Gemini prompt box bottom border█(U+2588) — Claude Code context bar■(U+25A0) — Codex interrupt marker•(U+2022) — Codex spinner (disambiguated:• Working= chrome,• Created= output)- U+2720–U+273F — CC spinner dingbats (✶✻✳✢ etc.)
Used by chrome_only calculation (pty.rs) which also considers has_status_line
from parse_status_line events (for Gemini braille spinners). Gates:
last_output_mstimestamp updatesSHELL_BUSY→SHELL_IDLEtransitionsSilenceState::on_chunk()
Gaps:
- No positional awareness — cannot use “last row = always chrome” heuristic
- A bare subprocess count (
1 shell, no⏵⏵) carries no chrome glyph, sois_chrome_rowreturns false for it —parse_active_subtasksstill reads the count via its bare-count path - User-defined status lines are only partially covered: a row with block glyphs
(
Context █░░░ 8%) is chrome, a plain one ([Opus 4.6 | Max] │ repo) is not. This is a classification gap only — no detection logic reads status-line content, andis_spinner_row’s leading-glyph rule keeps a HUD progress bar from faking liveness (#446-596f). See Claude Code § Status Lines.
Subprocess Count (parse_active_subtasks) — output_parser.rs:706
Extracts subprocess count from the mode line. Must handle:
- Old format:
⏵⏵ <mode> · N <type>— markers first, count last - New format:
N <type> · ⏵⏵ <mode>— count first, markers last - Count only:
N <type>— no markers at all (e.g.,1 shell) - Bare mode:
⏵⏵ <mode>— markers only, no count (count = 0)
All four formats are implemented: formats 1, 2 and 4 by the mode-marker path
(⏵⏵/›› anywhere on the row, count extracted from either side of the ·),
format 3 by the bare-count path, which is restricted to known subprocess types
(agents, shells, bash, background tasks) so ordinary numbers in output
cannot trigger it.
Question Detection (extract_last_chat_line) — pty.rs:207
Finds the last agent chat line above the prompt box:
- Scan from bottom, find prompt line (
❯,›,>) - Walk up past separators and empty lines
- First non-empty, non-separator line = last chat line
Robust: Does not depend on mode line format.
Test Expectations
Tests that hardcode specific bottom-zone layouts. Update these when adding new format support.
output_parser.rs — parse_active_subtasks tests
All use format: ⏵⏵|›› <mode> · N <type> (old format only)
test_active_subtasks_local_agents—›› bypass permissions on · 2 local agentstest_active_subtasks_single_bash—›› reading config files · 1 bashtest_active_subtasks_background_tasks—›› fixing tests · 3 background taskstest_active_subtasks_single_local_agent—›› writing code · 1 local agenttest_active_subtasks_bare_mode_line_resets_to_zero—›› bypass permissions ontest_active_subtasks_explicit_zero_count—›› finishing · 0 bashtest_active_subtasks_triangle_*— same patterns with⏵⏵prefix
pty.rs — extract_last_chat_line tests
test_extract_last_chat_line_standard_claude_code—⏵⏵ bypass permissions on (shift+tab to cycle)test_extract_last_chat_line_with_wiz_hud— 3 HUD lines + mode linetest_extract_last_chat_line_plan_mode—⏸ plan mode on (shift+tab to cycle)
pty.rs — is_chrome_row / chrome_only tests
test_chrome_only_single_statusline_row_is_chrome—⏵⏵ auto modetest_chrome_only_wrapped_statusline_is_chrome—⏵⏵ bypass permissions on+✻ timertest_chrome_only_subtasks_row_is_chrome—›› bypass permissions on · 1 local agent
Verification Methodology
These documents must be re-verified weekly (or after agent version updates) to catch layout changes before they break parsing.
Procedure 1: Capture current layout from live sessions
Use session action=list to find active sessions, then for each:
session action=output session_id=<id> limit=4000 → clean text
session action=output session_id=<id> limit=8000 format=raw → raw ANSI
Compare against documented layouts. Look for:
- Changed cursor-up distances (
\033[NA) → bottom zone height changed - New Unicode characters in mode/status lines → update
is_chrome_row - Changed OSC sequences → update notification detection
- New footer text → update question detection
Procedure 2: Trigger interactive menus
- Create a fresh session:
session action=create - Start agent in restricted mode (CC:
--permission-mode default, Codex:-a untrusted) - Request operations that trigger approval prompts
- Capture raw output — compare separators, colors, footers
- Cancel and clean up
Procedure 3: Audit parser compatibility
cd src-tauri && cargo test -- --test-threads=1 \
chrome_only \
active_subtasks \
extract_last_chat_line \
separator \
prompt_line \
question \
2>&1 | head -100
Research Techniques
- Raw ANSI capture via MCP:
session action=output format=rawreveals cursor positioning, colors, and OSC sequences invisible in clean output - Cursor-up distance as height probe:
\033[NAreveals bottom zone height - OSC sequence interception:
\033]777;notify;...and\033]0;...carry metadata - Color as semantic signal: RGB colors distinguish interactive vs chrome elements
- Forced state transitions: specific CLI flags surface all UI variants
- Screen clear detection:
\033[2J\033[3J\033[Hdistinguishes full-screen menus
Agent Detection Matrix
Standardized checklist for analyzing and onboarding new AI coding agent CLIs. Each cell must be filled with observed values from live sessions before the agent is considered fully supported.
Mobile question and choice contract (2026-09-29)
The mobile client renders the backend’s SessionState.choice_prompt and follows
its selection_mode for Claude. Codex’s existing Other notes path still has
a client-side special case. Only rows marked as captured below have a verified
end-to-end choice contract;
unknown forms stay as terminal output until they have a real capture and test.
| Registry type | Observed question or approval UI | Selection contract and evidence |
|---|---|---|
claude | Ink AskUserQuestion: title, numbered options separated by description rows, column-zero Enter to select footer | navigate-enter: arrows move the highlight, Enter submits, Esc cancels. Claude 2.1.280 capture src-tauri/src/fixtures/agent_prompts/claude-askuser-esc-20260929.tcap; the older permission menu is documented in Claude Code. |
codex | Queued request_user_input: title and numbered choices under • Queued follow-up inputs; a separate command approval panel exists | Numbered key for ordinary options; Other navigates to notes. Captures and limits in Codex. |
gemini | No interactive permission UI in the v0.34.0 workspace-restriction observation | No captured question-option contract; see Gemini CLI. |
opencode | Framed △ Permission required with inline Allow once / Allow always / Reject | Navigation and Enter shown in the footer, but no captured mobile option contract. See OpenCode. |
pi | Permission and menu screens are reported | Specific question rows and selection bytes not captured; see pi. |
amp, cursor, goose, grok, droid | No question-option capture in this repository | Unknown; no agent-specific mobile choice parser is enabled. |
git, api | Registry execution types, not a captured interactive agent dialog | No choice contract. |
The generic numbered confirmation parser remains available for agents with its
strict title and option shape. The Claude Ink parser is gated by agent_type
and the full-bleed footer so a quoted dialog in agent output cannot become a
clickable choice. A missing choice_prompt is not evidence that Yes/No is a
safe substitute for a multi-option question.
Detection Matrix
1. Identity & Rendering
| Property | Claude Code | Codex CLI | Gemini CLI | OpenCode |
|---|---|---|---|---|
| Version tested | v2.1.81 | v0.116.0+ (re-verified) | v0.34.0 | v1.2.20 |
| Date tested | 2026-03-21 | 2026-04-19 | 2026-03-22 | 2026-03-22 |
| Rendering engine | Ink (React) | Ink (React) | Ink-like (Node.js) | Bubble Tea (Go) |
| Cursor positioning | Relative (\033[NA]) | Absolute (\033[r;cH) | Relative (\033[1A]) | Absolute (\033[r;cH) |
| Scroll mechanism | \r\n padding | Scroll regions (\033[n;mr]) | \r\n padding | Full-screen redraw |
| Screen clear on menus | Sometimes (\033[2J) | No | No | Full-screen TUI |
| Parsing strategy | Changed-rows delta | Changed-rows delta | Changed-rows delta | Screen snapshot |
2. Prompt Line
| Property | Claude Code | Codex CLI | Gemini CLI | OpenCode |
|---|---|---|---|---|
| Prompt char | ❯ (U+276F) | › (U+203A, bold) | > (purple, rgb 215,175,255) | None (framed ┃ box) |
| Prompt background | None | Dark gray (rgb 57,57,57) | Dark gray (rgb 65,65,65) | Dark (rgb 30,30,30) |
| Prompt box border | ──── separators | Background color only | ▀▀▀ top / ▄▄▄ bottom | ┃╹▀ vertical frame |
| Ghost text style | dim cell attribute | \033[2m dim | Gray (rgb 175,175,175) | Gray placeholder |
| Multiline input | Enter = submit | Enter = newline | Enter = submit | Unknown |
3. Separator Lines
| Property | Claude Code | Codex CLI | Gemini CLI | OpenCode |
|---|---|---|---|---|
| Uses separators | Yes | Partially | Yes | No (uses ┃╹▀) |
| Separator chars | ─ (U+2500) | ─ (U+2500) | ─ (U+2500) | ┃ ╹ ▀ (vertical frame) |
| Separator color | Gray (rgb 136,136,136) | Standard | Dark gray (rgb 88,88,88) | N/A |
| Separator purpose | Frame prompt box | Between tool output & summary | Above prompt area | Prompt box border |
| Decorated separators | Yes (──── label ──) | No | No | N/A |
| Min run length | 4+ chars | Full width | Full width | N/A |
4. Status / Chrome Lines
| Property | Claude Code | Codex CLI | Gemini CLI | OpenCode |
|---|---|---|---|---|
| Mode line | ⏵⏵ <mode> (last row) | None | None | Mode in prompt box (Build/Plan) |
| Status line(s) | 0-N below separator | 1 line below prompt | 2-row status bar (4 columns) | Right panel (context, cost, LSP) |
| Status indent | 2 spaces (\033[2C) | 2 spaces | 1 space | N/A (panel layout) |
| Info line | None | None | Shift+Tab to accept edits + MCP/skills count | tab agents · ctrl+p commands |
| Subprocess count | In mode line | None | None | None (progress bar instead) |
5. Spinner / Working Indicators
| Property | Claude Code | Codex CLI | Gemini CLI | OpenCode |
|---|---|---|---|---|
| Spinner chars | ✶✻✳✢· (U+2720-273F) | • (U+2022) | ⠋⠙⠹⠸⠴⠦⠧⠇ (braille) | ■⬝ (progress bar) |
| Spinner color | White | Standard | Blue/green (varies) | Standard |
| Spinner position | Above separator | Inline with output | Below output, above separator | Footer row |
| Time display | (1m 32s) | (10s • esc to interrupt) | (esc to cancel, Ns) | None |
| Token display | ↓ 2.2k tokens | None | None | None |
| Tip text | Spinner verb names | None | Italic tips during spinner | None |
| Detected by | is_chrome_row ✓ | is_chrome_row ✓ | parse_status_line ✓ | detect_opencode_screen_activity ✓ (footer esc interrupt, not the bar glyphs) |
6. Interactive Menus
| Property | Claude Code | Codex CLI | Gemini CLI | OpenCode |
|---|---|---|---|---|
| Permission prompt | Multiselect (❯ 1. Yes) | Not observed (sandbox) | None (model-level refusal) | △ Permission required inline |
| Selection char | ❯ (blue) | Not observed | N/A | ⇆ select |
| Footer pattern | Esc to cancel/close | esc to interrupt | esc to cancel (in spinner) | enter confirm |
| OSC 777 notify | Yes — needs your permission (blocked, high-confidence); is waiting for your input (blocked picker OR 60s idle timer, low-confidence); needs your attention (ignored) | No | No | No |
| OSC 0 window title | Yes (task + spinner) | Yes | Yes (◇ Ready (workspace)) | No |
| Slash commands | /mcp, /stats, /status | /model, /mcp, /fast | /help, /settings, /model, /stats | None observed |
7. System Messages
| Property | Claude Code | Codex CLI | Gemini CLI | OpenCode |
|---|---|---|---|---|
| Output prefix | ⏺ (white/green/red) | • (U+2022) | ✦ (U+2726, purple) | None (inline in panel) |
| Tool call display | ⏺ + verb | • Ran <cmd> (shell), • Called + └ fn() (MCP) | ╭───╮ ✓ ToolName ╰───╯ box | → read / ← write |
| Warning prefix | N/A | ⚠ (U+26A0) | N/A | N/A |
| Error indicator | ⏺ (red) | ✗ or • …hook (failed) | ✦ + error text | ┃ Error: inline |
| Interrupt marker | N/A | ■ | Not observed | esc interrupt hint |
| Tool result | ⎿ (U+23BF) | └ (U+2514) tree connector | Inside ╭───╮ box | ▣ completion marker |
| Truncation | … +N lines | … +N lines (ctrl + t to view transcript) | Not observed | Not observed |
Trigger Procedures
How to force each UI state for analysis and testing.
Procedure A: Start agent in each permission mode
| Agent | Restricted mode | Permissive mode |
|---|---|---|
| Claude Code | claude --permission-mode default | claude --permission-mode bypassPermissions |
| Codex CLI | codex -a untrusted | codex (suggest mode, default) |
| Gemini CLI | gemini (default, workspace-restricted) | gemini --sandbox=false (unconfirmed) |
| OpenCode | Unknown | Unknown |
Procedure B: Trigger permission/approval prompt
| Agent | Action | Expected result |
|---|---|---|
| Claude Code (default mode) | “create a file /tmp/test.txt with hello” | Multiselect: Yes/Yes+allow/No |
| Codex CLI (untrusted) | Same | Not observed — auto-approves in sandbox |
| Gemini CLI | “create a file /tmp/test.txt with hello” | Text refusal (workspace restriction) |
| OpenCode | Access external directory | △ Permission required with Allow once / Allow always / Reject |
Procedure C: Trigger interactive menus
| Agent | Command | Expected result |
|---|---|---|
| Claude Code | /mcp | Server list with ❯ selection |
| Claude Code | /stats | Usage heatmap with date cycling |
| Claude Code | /status | Settings panel with search box |
| Codex CLI | /model | Model selector |
| Codex CLI | /mcp | MCP server list |
| Gemini CLI | /settings | Settings panel (unconfirmed) |
| Gemini CLI | /stats | Usage stats |
Procedure D: Observe working state
| Agent | Action | What to capture |
|---|---|---|
| Any | Send a complex multi-tool task | Spinner animation, cursor-up distance |
| Any | Send task during active subprocess | Subprocess count display |
| Any | Press Escape during work | Interrupt marker |
Procedure E: Capture raw ANSI
For each state above:
session action=output session_id=<id> limit=8000 format=raw
Look for:
- Cursor positioning:
\033[NA](relative up),\033[r;cH(absolute) - Colors:
\033[38;2;R;G;Bm(RGB foreground) - Background:
\033[48;2;R;G;Bm - Screen clear:
\033[2J - Scroll regions:
\033[n;mr - OSC sequences:
\033]777;...,\033]0;...,\033]8;...
Onboarding a New Agent
- Fill the detection matrix columns by running procedures A-E
- Create
docs/architecture/agents/<name>.mdwith observed layouts - Update
chrome.rsif new markers/chars are needed - Add test cases from real captured text
- Run
/agent-ui-auditskill to verify parser compatibility
Claude Code — UI Layout Reference
Agent-specific layout reference for Claude Code (Anthropic). See agent-ui-analysis.md for shared concepts.
Observed version: v2.1.81 (2026-03-21)
Rendering engine: Ink (React for terminals)
Rendering approach: ANSI relative cursor positioning (\033[NA, \033[1B)
AskUserQuestion update (Claude 2.1.280, 2026-09-29): The captured Ink dialog
shows Which color do you prefer?, numbered Red/Green/Blue choices, description
rows, Type something., Chat about this, and a column-zero Enter to select
footer. The highlighted ❯ 1. Red is an option, not the composer. Selection
uses arrows then Enter; the digit labels are not direct submit keys. The raw
capture and replay test live at
src-tauri/src/fixtures/agent_prompts/claude-askuser-esc-20260929.tcap.
Layout Anatomy (bottom → top)
[agent output / response text]
[empty line(s)]
✶ Undulating… (1m 32s · ↓ 2.2k tokens) (spinner — above separator, while working)
[empty line]
──────────────────────────────────── (upper separator, may contain label)
❯ [user input] (prompt line)
──────────────────────────────────── (lower separator)
[status line(s)] (0-N lines, indented 2 spaces)
[mode line] (last row, indented 2 spaces)
Real-world Examples (live sessions, 2026-03-21)
Standard idle — no subprocess
❯
──────────────────────────────────────────────────────────────────────────
[Opus 4.6 (1M context) | Max] │ tuicommander git:(main*)
Context █░░░░░░░░░ 8% $0 (~$2.97) │ Usage ⚠ (429)
⏵⏵ bypass permissions on (shift+tab to cycle)
With subprocess — new format (count left)
───────────────────────────────────────────────────────── extractor ──
❯
──────────────────────────────────────────────────────────────────────────
[Opus 4.6 (1M context) | Max] │ mdkb git:(feat/document-organizer*)
Context ░░░░░░░░░░ 4% $0 (~$79.88) │ Usage ⚠ (429)
1 shell · ⏵⏵ bypass permissions on
Subprocess only — no mode indicator
───────────────────────────────────────────────────────── extractor ──
❯
──────────────────────────────────────────────────────────────────────────
[Opus 4.6 (1M context) | Max] │ mdkb git:(feat/document-organizer*)
Context ░░░░░░░░░░ 4% $0 (~$79.81) │ Usage ⚠ (429)
1 shell
Default mode (no bypass) — single status line, no mode line
❯
───────────────────────────────────────────────────────────────────────────────
[Opus 4.6 (1M context) | Max] ░░░░░░░░░░ 3% | tuicommander git:(main*) |… ○ low · /ef…
Agent working — spinner above, no prompt box
⎿ $ ls -la /Users/stefano.straus/Documents/.mdkb/index.sqlite
✶ Undulating…
Separator Line
A row containing a run of 4+ box-drawing characters (─ ━ ═ — ╌ ╍).
May contain embedded labels:
────────────────────────────────────────────────────────────────────────────────
──────────────────────────────────────────────────────────────── extractor ──
──────── ■■■ Medium /model ────────
Spinner / Timer Lines (above upper separator)
✶ Undulating…
✻ Sautéed for 1m 19s
✳ Ideating… (1m 32s · ↓ 2.2k tokens)
✻ Sautéed for 2m 9s · 1 local agent still running
· Proofing… (1m 14s · ↓ 1.6k tokens)
Markers: ✶ (U+2736), ✻ (U+273B), ✳ (U+2733), ✢ (U+2722), · (U+00B7).
Detected by is_chrome_row (✻ check) and parse_status_line (dingbat range U+2720–U+273F).
Status Lines (between lower separator and mode line)
Zero or more lines. Content is arbitrary and agent-customizable.
Indented with 2 spaces (via \033[2C).
[Opus 4.6 (1M context) | Max] │ tuicommander git:(main*)
Context █░░░░░░░░░ 5% $0 (~$0.64) │ Usage ⚠ (429)
Or Wiz HUD:
[Opus 4.6 | Team] 54% | wiz-agents git:(main)
5h: 42% (3h) | 7d: 27% (2d)
✓ Edit ×7 | ✓ Bash ×5
Configured via ~/.claude/settings.json → statusLine, but rendered
through the PTY using ANSI cursor positioning. They appear as changed_rows
and pass through is_chrome_row.
Custom status lines are never a detection signal. Their content is
user-defined — the two blocks above are just two of countless possible layouts —
so nothing in the state machine reads them: no model name, no context
percentage, no cost, no usage counter is parsed from these rows. They matter in
exactly one direction, getting classified as chrome so they do not reset the
silence timer or stamp last_output_ms.
Coverage today (chrome.rs, asserted by status_line_not_chrome,
cc_status_context_bar, cc_wiz_hud_line):
| Row | is_chrome_row | Why |
|---|---|---|
Context █░░░░░░░░░ 8% $0 (~$2.97) │ Usage ⚠ (429) | yes | block glyphs █ / ░ |
[Opus 4.6 (1M context) | Max] │ repo git:(main*) | no | carries no chrome glyph — known gap |
5h: 42% (3h) | 7d: 27% (2d) | no | same gap |
A status line is also barred from proving the agent is alive: is_spinner_row
requires the spinner glyph to lead the row, so a HUD progress bar that ticks
every second cannot be read as a working spinner. That rule is the fix for the
regression that pinned Claude BUSY forever under a wiz status bar (#446-596f).
Mode Line (last row)
The final visible row. Always chrome. Indented with 2 spaces.
Observed variants
| Format | Example | Source |
|---|---|---|
| Mode only | ⏵⏵ bypass permissions on | test |
| Mode + hint | ⏵⏵ bypass permissions on (shift+tab to cycle) | live |
| Mode + subprocess (old) | ⏵⏵ bypass permissions on · 1 shell | test |
| Mode + subprocess (old, plural) | ⏵⏵ bypass permissions on · 2 local agents | test |
| Subprocess + mode (new) | 1 shell · ⏵⏵ bypass permissions on | live |
| Subprocess only | 1 shell | screenshot |
| Plan mode | ⏸ plan mode on (shift+tab to cycle) | test |
| Accept edits | ⏵⏵ accept edits on (shift+tab to cycle) | test |
| Auto mode | ⏵⏵ auto mode | test |
| Empty | `` | test |
| Absent (default mode) | N/A — no mode line at all | live |
Key markers
⏵⏵(U+23F5 x2) — current mode-line prefix››(U+203A x2) — older mode-line prefix⏸(U+23F8) — plan mode prefix·(U+00B7) — separator between mode and subprocess count
Subprocess types observed
shell / shells, local agent / local agents, bash, background tasks
Interactive Menus
Permission Prompt
Replaces the entire bottom zone when CC requests tool approval.
⏺ Write(/tmp/test-permission-prompt.txt)
────────────────────────────────────────── (BLUE separator, rgb 177,185,249)
Create file
../../../../../tmp/test-permission-prompt.txt
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ (dotted ╌ U+254C, rgb 80,80,80)
1 hello
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
Do you want to create test-permission-prompt.txt?
❯ 1. Yes (❯ colored BLUE, rgb 177,185,249)
2. Yes, allow all edits in tmp/ during this session (shift+tab)
3. No
Esc to cancel · Tab to amend
| Feature | Normal | Permission prompt |
|---|---|---|
| Top separator | Gray ─ (rgb 136,136,136) | Blue ─ (rgb 177,185,249) |
| Content separator | None | Dotted ╌ (U+254C) |
❯ char | Gray prompt | Blue selection (rgb 177,185,249) |
| Mode line | ⏵⏵/⏸ on last row | None |
| Last line | Mode indicator | Esc to cancel · Tab to amend |
Custom Ink Menu (e.g., /wiz:setup)
────────────────────────────────────── (dim gray separator, \033[2m)
← ☐ Essential ☐ Workflow ☐ Tools ✔ Submit →
Select essential components to install:
❯ 1. [ ] notifications (checkbox, ❯ blue)
...
────────────────────────────────────── (dim gray separator)
6. Chat about this
Enter to select · Tab/Arrow keys to navigate · Esc to cancel
May clear the entire screen (\033[2J\033[3J\033[H).
Built-in Menu (/mcp)
───────────────────────────────────── (blue separator, rgb 177,185,249)
Manage MCP servers
❯ tuicommander · ✔ connected
context7 · ✔ connected
mac · ✘ failed
※ Run claude --debug to see error logs
https://code.claude.com/docs/en/mcp for help (OSC 8 hyperlink)
↑↓ to navigate · Enter to confirm · Esc to cancel (italic, \033[3m)
Built-in (/stats)
───────────────────────────────────────────────────────────────────────
Overview Models
Mar Apr May Jun ... Mar
··········░·▓██▓█·
...
You've used ~29x more tokens than The Count of Monte Cristo
Esc to cancel · r to cycle dates · ctrl+s to copy
Built-in (/status)
───────────────────────────────────────────────────────────────────────
Status Config Usage
╭───────────────────────────────────────────────────────────────────╮
│ ⌕ Search settings... │
╰───────────────────────────────────────────────────────────────────╯
Auto-compact true
...
↓ 3 more below
←/→ tab to switch · ↓ to return · Esc to close
Uses box-drawing ╭╮╰╯│ for search box (not matched by is_separator_line).
OSC 777 Notifications
CC emits terminal notifications for user attention events:
\033]777;notify;Claude Code;Claude needs your permission to use Write\007
\033]777;notify;Claude Code;Claude Code needs your attention\007
All share the prefix \033]777;notify;Claude Code;.
Ink Rendering Mechanics
Spinner animation (above separator)
\033[8A ← cursor UP 8 rows (to spinner position)
✶ ← overwrite spinner character
\r\n × 7 ← 7 empty newlines back down to bottom
The cursor-up count equals the bottom zone height:
- 8 = bypass mode (spinner + empty + sep + prompt + sep + 2 status + mode)
- 6 = default mode (spinner + empty + sep + prompt + sep + 1 status, no mode)
- 10 = with subprocess in bypass mode
Full bottom zone redraw
\r\033[1B separator ────
\r\033[1B ❯ [input]
\r\033[1B separator ────
\r\n \033[2C [status line 1] ← 2C = cursor forward 2 = indent
\r\n \033[2C [status line 2]
\r\n \033[2C [mode line]
Key implications
- All bottom-zone rows transit the PTY as ANSI sequences
- The vt100 parser processes them into screen buffer rows
- Spinner updates touch the spinner row AND all rows below it, causing the entire bottom zone to appear as changed rows
- The 2-space indent on status/mode lines comes from
\033[2C
Codex CLI — UI Layout Reference
Agent-specific layout reference for Codex CLI (OpenAI). See agent-ui-analysis.md for shared concepts.
Observed version: v0.116.0 (2026-04-19), re-audited on v0.146.0 (2026-08-02)
Rendering engine: Ink (React for terminals)
Rendering approach: ANSI absolute positioning (\033[row;colH) + scroll regions
Layout Anatomy
Codex uses a fundamentally different approach from Claude Code:
- No separator-framed prompt box — uses background color instead
- Absolute cursor positioning —
\033[12;2H(row 12, col 2) - Terminal scroll regions —
\033[12;41rto define scrollable content area - Reverse index —
\033Mto scroll content upward
[agent output with • bullet prefix]
[empty line]
← dark background (rgb 57,57,57) starts here
› [user input] (prompt, bold ›, dark bg)
(dark bg continues)
(dark bg continues)
gpt-5.4 high · 100% left · ~/project (status line, dim, normal bg)
Real-world Examples (live session, 2026-03-21)
Startup banner
╭────────────────────────────────────────────╮
│ >_ OpenAI Codex (v0.116.0) │
│ │
│ model: gpt-5.4 high /model to change │
│ directory: ~/Gits/personal/tuicommander │
╰────────────────────────────────────────────╯
Tip: Use /mcp to list configured MCP tools.
Idle (waiting for input)
› Summarize recent commits (ghost text, dim)
gpt-5.4 high · 100% left · ~/Gits/personal/tuicommander
After tool execution (simple file create)
› create a file called /tmp/codex-test.txt with "hello"
• Creating /tmp/codex-test.txt with the requested contents.
• Added /tmp/codex-test.txt (+1 -0)
1 +hello
───────────────────────────────────────────────────────────────────────────────
• Created /tmp/codex-test.txt with hello.
› Summarize recent commits
gpt-5.4 high · 98% left · ~/Gits/personal/tuicommander
After tool execution (shell commands + MCP calls, 2026-04-19)
• PreToolUse hook (failed)
error: hook exited with code 127
• Ran git status --short
└ ?? .gitignore
?? .serena/
… +2 lines (ctrl + t to view transcript)
?? StepsWidgetDemo/
?? project.yml
• PostToolUse hook (failed)
error: hook exited with code 127
• Ran xcodegen generate
└ ⚙️ Generating plists...
⚙️ Generating project...
⚙️ Writing project...
Created project at /Users/.../StepsWidgetDemo.xcodeproj
• Ran xcodebuild -project StepsWidgetDemo.xcodeproj -scheme StepsWidgetDemo ...
└ 2026-04-19 22:27:42.803 xcodebuild[67191:4346310] DVTFilePathFSEvents: ...
… +109 lines (ctrl + t to view transcript)
** BUILD SUCCEEDED **
• Waited for background terminal
──────────────────────────────────────────────────────────────────────────────
• Il progetto compila. Prima di chiudere salvo ...
• Called
└ serena.write_memory({"memory_name":"project_overview","content":"..."})
Memory project_overview written.
• Working (4m 55s • esc to interrupt)
› Improve documentation in @filename
gpt-5.4 high · ~/Gits/personal/steps
Tool display patterns (v0.116.0+):
| Pattern | Meaning |
|---|---|
• Ran <command> | Shell command execution |
• Called + └ <fn>(...) | MCP/function call with args on next line |
• Added <path> (+N -M) | File created/modified with diff stats |
• Creating <path> | File operation in progress |
• Waited for background terminal | Background job completed |
• PreToolUse hook (failed) | Hook error (with error: detail below) |
• PostToolUse hook (failed) | Hook error (with error: detail below) |
… +N lines (ctrl + t to view transcript) | Truncated output (N lines hidden) |
└ (U+2514) | Tree connector for tool output/results |
After interrupt (Escape)
■ Conversation interrupted - tell the model what to do differently.
› Summarize recent commits
esc again to edit previous message
Key Differences from Claude Code
| Feature | Claude Code | Codex CLI |
|---|---|---|
| Prompt char | ❯ (U+276F) | › (U+203A, bold) |
| Prompt box | Separator-framed (────) | Background color (rgb 57,57,57) |
| Cursor positioning | Relative (\033[8A) | Absolute (\033[12;2H) |
| Scrolling | \r\n padding | Scroll regions (\033[12;41r) + reverse index (\033M) |
| Status line | Multi-line, indented 2sp | Single line, indented 2sp, dim |
| Mode line | ⏵⏵ bypass permissions on etc. | None observed |
| Separator usage | Around prompt box | Between tool output and summary |
| System messages | ⏺ prefix (white/green/red) | • prefix (bullet) |
| Warnings | N/A | ⚠ prefix (yellow) |
| Interrupt marker | N/A | ■ prefix |
| Ghost text | Via dim cell attribute | Via \033[2m dim |
| Submit key | Enter | Enter (but multiline: Enter = newline in prompt) |
Prompt Line
- Character:
›(U+203A) — bold\033[1m - Background: dark gray
rgb(57,57,57)—\033[48;2;57;57;57m - The prompt area spans multiple rows with dark background
- Ghost text (placeholder) shown in dim:
\033[2m
Multiline input: Codex supports multiline prompts where Enter adds a newline. Submit is also Enter (single line). This makes programmatic input tricky — sending text + Enter may add a newline instead of submitting.
Status Line
Single line below the prompt area, always present.
v0.146.0 (audited live 2026-08-02) — five ·-separated fields:
gpt-5.6-luna xhigh · ~/Gits/personal/tuicommander · main · Context 100% left · 260K window
Format: <model> <effort> · <directory> · <git branch> · Context <N>% left · <N>K window
Two changes since v0.116.0:
- A git branch field was added after the directory. It is the checked-out branch of the session cwd, so its presence and value both vary.
- The context gauge moved after the directory and gained the
Contextlabel plus a trailing<N>K windowfield:100% leftbecameContext 100% left · 260K window.
v0.116.0 (historical) — <model> <effort> · [<quota>% left ·] <directory>:
gpt-5.4 high · 100% left · ~/Gits/personal/tuicommander
gpt-5.4 high · ~/Gits/personal/steps
Rendered in dim (\033[2m) with normal background (not dark bg).
Detection is unaffected by this drift. detect_codex_screen_activity
(src-tauri/src/pty.rs) never reads the status line: it anchors on the lowest
› prompt row and looks for is_working_status_row in the six rows above it.
Both anchors are branch- and gauge-independent, which is why the shape can keep
moving without breaking busy/idle.
Separator Usage
Codex uses ──── separators differently from CC — they appear between
tool output and the agent’s summary response, not as a prompt box frame:
• Added /tmp/codex-test.txt (+1 -0)
1 +hello
───────────────────────────────────────────────────────────────────────────
• Created /tmp/codex-test.txt with hello.
Spinner
Codex uses • (U+2022) as a spinner/working indicator:
• Working (10s • esc to interrupt)
The • is already in is_chrome_row’s marker set.
OSC Sequences
\033]10;?\033\\ — query terminal foreground color
\033]11;?\033\\ — query terminal background color
\033]0;...\007 — window title updates
No \033]777;notify; observed — Codex does not emit terminal notifications
for approval prompts.
Animated OSC 0 title (v0.146.0, audited 2026-08-02)
While a turn is running Codex repaints the window title on every spinner frame, prefixing the cwd basename with a braille glyph:
\033]0;⠋ tuicommander\007 — U+280B
\033]0;⠙ tuicommander\007 — U+2819
\033]0;⠹ tuicommander\007 — U+2839
… ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏ — U+2838 U+283C U+2834 U+2826 U+2827 U+2807 U+280F
\033]0;tuicommander\007 — plain title, emitted once when the turn ends
A single 900-word turn produced 152 braille-prefixed titles and 2 plain ones (one at startup, one at turn end).
TUIC deliberately does not consume this for activity. The busy/idle
transition is owned solely by detect_codex_screen_activity. Reading the title
as a second source of the same transition would be a race, not a safety net:
two independent producers of one state edge cannot be ordered, so a late title
frame could reopen a turn the screen already closed (or the reverse). The screen
adapter stays the single writer; the title is documentation only.
Approval Modes
CLI flag: -a or --ask-for-approval <POLICY>
| Policy | Behavior |
|---|---|
untrusted | Sandbox commands (does NOT prompt for approval) |
on-failure | DEPRECATED — auto-run, ask only on failure |
on-request | Model decides when to ask |
never | Never ask |
Note: In untrusted mode, Codex auto-approves tool use within the
sandbox. No interactive approval prompt was observed. The approval UI
may only appear in specific edge cases or with on-request mode.
Slash Commands Observed
• Unrecognized command '/mode'. Type "/" for a list of supported commands.
Available: /model, /mcp, /fast, /feedback, /help, and others.
Not observed: /stats, /status (CC-specific).
Command Submission
Codex uses a raw-mode composer where a carriage return that arrives with the prompt payload, or too soon after it, can be interpreted as a newline instead of submitting the turn. Managed automation must use one atomic MCP call:
{
"action": "submit",
"session_id": "<session-id>",
"input": "/clear"
}
submit claims a confirmed-idle, empty managed-agent composer; holds the PTY
writer across Ctrl-U, a 50 ms gap, optional bracketed paste, the 50 ms scheduling gap, and
the final carriage return; advances the normal input FSM and turn epoch; then
waits internally for child terminal movement. The same response returns
submission_id, submitted, write_state, acknowledged, retry_safe,
turn_epoch, and composer_state plus the acknowledgement evidence or a
precise failure reason. No follow-up status or output poll is part of the
protocol.
Acknowledgement proves terminal movement after Enter, not that Codex understood
the command or completed the requested work. A completed write that produces no
movement before the bounded deadline returns ack_timeout and
retry_safe:false; automatic replay could duplicate an active command.
The action never queues. A partial composer, interactive dialog, busy or
unconfirmed agent, or older queued message rejects before writing. Once the
claim is held, a concurrent peer message queues behind the submission and
cannot splice into it. Slash commands such as /clear use the same contract.
session action=input remains the backward-compatible raw text/key surface.
Its { "ok": true } means PTY write only. Use it to prefill or answer
interactive controls; do not split command text and Enter into separate calls.
ask_user_question tool (proposed)
GitHub issue openai/codex#9926
proposes a tabbed questionnaire UI similar to Claude Code’s skill menus.
Currently available via request_user_input tool with collaboration_modes = true
in config, but only in plan mode (Shift+Tab).
Rendering Mechanics (raw ANSI)
Absolute positioning
\033[12;2H — cursor to row 12, col 2 (absolute)
\033[K — erase to end of line
Scroll regions
\033[12;41r — set scroll region rows 12-41
\033M — reverse index (scroll content up within region)
\033[r — reset scroll region
Prompt area rendering
\033[48;2;57;57;57m — dark background starts
\033[1m›\033[22m — bold › then unbold
\033[2m... — dim ghost text
\033[49m — background reset for status line
Unlike CC which uses relative cursor movement (\033[8A), Codex uses
absolute positioning. This means changed_rows detection works differently —
Codex updates specific rows by address rather than painting top-down.
Gemini CLI — UI Layout Reference
Agent-specific layout reference for Gemini CLI (Google). See agent-ui-analysis.md for shared concepts.
Observed version: v0.34.0 (2026-03-22)
Rendering engine: Ink-like (Node.js, ANSI relative positioning)
Rendering approach: ANSI relative cursor positioning (\033[1A, \033[2K, \033[G)
Layout Anatomy (bottom → top)
[agent output with ✦ prefix]
[suggest line]
? for shortcuts
───────────────────────────────── (separator, gray rgb 88,88,88)
Shift+Tab to accept edits 1 MCP server | 3 skills
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ (prompt box top, dark rgb 30,30,30 on bg 65,65,65)
> [user input] (prompt, purple >, ghost text gray)
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ (prompt box bottom)
workspace (/directory) branch sandbox /model
~/path main no sandbox Auto (Gemini 3)
Bottom zone = 8 rows: shortcuts hint, separator, info line, prompt box (3 rows), status labels, status values.
Real-world Examples (live session, 2026-03-22)
Startup banner
▝▜▄ Gemini CLI v0.34.0
▝▜▄
▗▟▀ Signed in with Google: user@example.com /auth
▝▀ Plan: Gemini Code Assist for individuals /upgrade
╭───────────────────────────────────────────────────────────────────────╮
│ We're making changes to Gemini CLI that may impact your workflow. │
│ What's Changing: ... │
│ Read more: https://goo.gle/geminicli-updates │
╰───────────────────────────────────────────────────────────────────────╯
Tips for getting started:
1. Create GEMINI.md files to customize your interactions
2. /help for more information
3. Ask coding questions, edit code or run commands
4. Be specific for the best results
- Geometric ASCII art logo:
▝▜▄/▗▟▀/▝▀ - Auth + plan info inline
- Notification box with
╭╮╰╯│border (like CC /status search box) - Numbered tips list
Idle (waiting for input)
? for shortcuts
─────────────────────────────────────────────────────────────────────────────────
Shift+Tab to accept edits 1 MCP server | 3 skills
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
> Type your message or @path/to/file
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀▀
workspace (/directory) branch sandbox /model
~/Gits/personal/tuicommander main no sandbox Auto (Gemini 3)
Working state (spinner)
✦ intent: read package.json version (package.json)
I will read the package.json file to find the project version.
⠴ Check tool-specific usage stats with /stats tools… (esc to cancel, 14s)
─────────────────────────────────────────────────────────────────────────────────
Shift+Tab to accept edits
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
> Type your message or @path/to/file
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀▀
workspace (/directory) branch sandbox /model
~/Gits/personal/tuicommander main no sandbox Auto (Gemini 3)
- Spinner line appears between agent output and separator
- Braille spinner + italic tip text +
(esc to cancel, Ns)timer - During work,
? for shortcutsdisappears, info line loses right-side text
Tool call (in response)
╭─────────────────────────────────────────────────────────────────────────╮
│ ✓ ReadFile package.json │
│ │
╰─────────────────────────────────────────────────────────────────────────╯
- Bordered box with
╭╮╰╯│(same chars as startup notification) ✓prefix for completed tool calls- Tool name + arguments inline
Agent response (completed)
✦ The version of this project is 0.9.5, as specified in the package.json file.
suggest: [ View CHANGELOG.md | Check README.md | List active sessions ]
✦(U+2726, purple rgb 215,175,255) prefix for agent outputsuggest:line follows response (TUICommander protocol)- No token/cost report
Out-of-workspace write rejection
✦ I am unable to create the file at /tmp/gemini-test.txt because it is outside
the allowed workspace directories. I can, however, create it within the
project directory or the project's temporary directory.
Would you like me to create it at ~/.gemini/tmp/tuicommander/gemini-test.txt?
- No interactive permission prompt — Gemini refuses with text explanation
- Workspace restriction enforced at model level, not via UI prompt
Prompt Line
- Character:
>(ASCII, colored purple rgb 215,175,255) - Background: dark gray
rgb(65,65,65)—\033[48;2;65;65;65m - Prompt box bordered by
▀▀▀(U+2580, upper half block) top and▄▄▄(U+2584, lower half block) bottom - Border colors: dark
rgb(30,30,30)foreground onrgb(65,65,65)background - Ghost text: gray
rgb(175,175,175)—Type your message or @path/to/file - Cursor shown with reverse video
\033[7m - Enter = submit (single line prompt)
Separator Line
Single horizontal rule above the prompt area:
─────────────────────────────────────────────────── (gray, rgb 88,88,88)
- Always present in idle and working states
- No decorated separators (no embedded labels)
- Uses
─(U+2500) — same char as CC and Codex
Spinner / Working Indicator
⠴ Check tool-specific usage stats with /stats tools… (esc to cancel, 14s)
⠋ Exclude specific tools from being used (settings.json)… (esc to cancel, 33s)
- Braille spinner:
⠋⠙⠹⠸⠴⠦⠧⠇(U+2800 range) - Color varies: blue
rgb(135,189,241), greenrgb(224,255,206)— colors shift during animation - Format:
⠋ <italic tip text>… (esc to cancel, Ns) - Tip text: italic (
\033[3m), shows contextual tips/suggestions during work - Timer:
(esc to cancel, Ns)in grayrgb(175,175,175) - Position: between agent output and separator (above bottom zone)
Already detected by parse_status_line via GEMINI_SPINNER_RE (braille range check).
Status Bar (bottom 2 rows)
Always visible. 4 columns with label/value pairs:
workspace (/directory) branch sandbox /model
~/Gits/personal/tuicommander main no sandbox Auto (Gemini 3)
- Labels: gray
rgb(175,175,175)—workspace (/directory),branch,sandbox,/model - Values: white
rgb(255,255,255)— path, branch name, sandbox status, model name - Sandbox warning: pink
rgb(255,135,175)whenno sandbox
Info Line (between separator and prompt box)
Shift+Tab to accept edits 1 MCP server | 3 skills
- Left:
Shift+Tab to accept edits(gray) - Right:
N MCP server | N skills(gray) — MCP and skill counts - Above the prompt box, below the separator
A second info hint ? for shortcuts appears right-aligned above the separator when idle.
Window Title (OSC 0)
\033]0;◇ Ready (tuicommander)\007
◇(U+25C7, white diamond) — state indicatorReady— current state(tuicommander)— workspace name- Updates on state changes
Detection Signals
Agent Identification
Gemini CLI vin startup banner- Geometric ASCII logo
▝▜▄ ✦(U+2726) output prefix- Braille spinner
⠋⠙⠹⠸⠴⠦⠧⠇ ? for shortcutshint line- OSC 0 with
◇diamond
Chrome Detection (is_chrome_row)
- Braille spinner chars — detected by
parse_status_lineviaGEMINI_SPINNER_RE - Separator
─────— detected byis_separator_line✓ - Prompt
>— detected byis_prompt_line✓ ▀▀▀/▄▄▄prompt box borders — NOT in chrome marker set- Status bar labels/values — NOT chrome markers
✦(U+2726) — NOT inis_chrome_rowmarker set
Subtask / Subprocess Count
None. Gemini CLI does not expose subprocess/subtask counts.
Tool calls shown inline in bordered boxes (╭───╮ ✓ ReadFile ╰───╯).
Permission / Approval
- No interactive permission UI — workspace restriction enforced at model level
- Out-of-scope writes rejected with text explanation
- No
Esc to cancelpermission footer - No OSC 777 notifications observed
Rendering Mechanics (raw ANSI)
Relative cursor positioning
\033[1A — cursor UP 1 row (repeated for multi-row updates)
\033[2K — erase entire line
\033[G — cursor to column 1
\033[4A — cursor UP 4 (bottom zone jump)
\033[4G — cursor to column 4
\033[4B — cursor DOWN 4 (back to bottom)
Uses \033[1A] repeated (like CC) rather than absolute \033[r;cH (like Codex/OpenCode).
Bottom zone updates use \033[4A...\033[4B pattern to jump up, redraw, jump back.
Prompt box rendering
\033[48;2;65;65;65m — dark gray background
\033[38;2;30;30;30m▀▀▀▀... — dark top border on gray bg
\033[38;2;215;175;255m> — purple prompt char
\033[7m \033[27m — cursor (reverse video block)
\033[38;2;175;175;175m... — gray ghost text
\033[38;2;30;30;30m▄▄▄▄... — dark bottom border
\033[49m — reset background
Color scheme
\033[38;2;215;175;255m — purple (prompt char >, output prefix ✦, file names)
\033[38;2;255;255;255m — white (agent text, status values)
\033[38;2;175;175;175m — gray (labels, hints, timer)
\033[38;2;88;88;88m — dark gray (separator ─────)
\033[38;2;255;135;175m — pink (sandbox warning)
\033[38;2;135;189;241m — blue (spinner, varies)
\033[38;2;224;255;206m — green (spinner, varies)
Spinner animation
\033[3m — italic on (for tip text)
\033[23m — italic off
Spinner updates use the same \033[1A]\033[2K] erase-and-redraw pattern as the bottom zone.
Implications for TUICommander
Parsing Strategy
Gemini CLI is a CLI inline agent — changed-rows delta analysis works. Similar to CC in rendering mechanics (relative cursor positioning).
Already Supported
- Braille spinner detected by
parse_status_lineviaGEMINI_SPINNER_RE - Separator
─────detected byis_separator_line - Prompt
>detected byis_prompt_line
Not Yet Supported
✦(U+2726) is the Gemini agent output prefix (NOT chrome — do not add tois_chrome_row)- Tool call boxes (
╭╮╰╯│) not classified as chrome ? for shortcutshint line not classified as chrome- Status bar labels (bottom 2 rows) have no chrome markers (but
find_chrome_cutofftrims them via separator anchor) - No sandbox/permission prompt detection needed (Gemini handles this at model level)
Now Supported (as of chrome.rs multi-agent update)
▀▀▀/▄▄▄prompt box borders detected as chrome viais_chrome_row- Braille spinner classified as chrome via
has_status_lineinchrome_onlycalculation find_chrome_cutoffcorrectly trims the full Gemini 8-row bottom zone- Separator
─────detected byis_separator_line - Prompt
>detected byis_prompt_line
OpenCode — UI Layout Reference
Agent-specific layout reference for OpenCode. See agent-ui-analysis.md for shared concepts.
Observed version: v1.2.20 (2026-03-22), re-audited on v1.18.5 (2026-08-02) Rendering engine: Bubble Tea (Go TUI framework) Rendering approach: Full-screen TUI, ANSI absolute positioning, mouse tracking
Key Difference from Other Agents
OpenCode is a full-screen TUI application, not a CLI that renders inline in the terminal like Claude Code or Codex. It takes over the entire terminal screen with its own layout, panels, and navigation. This means:
- The “bottom zone” concept from CC/Codex does not directly apply
- OpenCode manages its own screen regions (panels, status bar, prompt)
- Mouse tracking is enabled (
\033[?1000h,\033[?1003h,\033[?1006h) - It uses bracketed paste (
\033[?2004h) and focus events (\033[?1004h)
Observed States
Welcome Screen
Only shown on fresh start, before first message:
█▀▀█ █▀▀█ █▀▀█ █▀▀▄ █▀▀▀ █▀▀█ █▀▀█ █▀▀█
█ █ █ █ █▀▀▀ █ █ █ █ █ █ █ █▀▀▀
▀▀▀▀ █▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀
┃
┃ Ask anything... "What is the tech stack of this project?"
┃
┃ Build Claude Sonnet 4.5 lansweeper.ai
╹▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
tab agents ctrl+p commands
● Tip Set agent temperature from 0.0 (focused) to 1.0 (creative)
~/Gits/personal/tuicommander:main 1.2.20
Conversation (after first message) — two-panel layout
┃ what version is this project █ Project version inquiry
┃ █
█ Context
Leggo la versione del progetto... █ 20,192 tokens
█ 0% used
→ Read SPEC.md [limit=50] █ $0.00 spent
→ Read package.json [limit=20] █
→ Read src-tauri/tauri.conf.json [limit=30] █ LSP
█ LSPs will activate...
Questo progetto è alla versione 0.9.5... █
█
▣ Build · anthropic/claude-sonnet-4.5 · 10.2s █
█
┃
┃ Build Claude Sonnet 4.5 lansweeper.ai ~/path:main
╹▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
tab agents ctrl+p commands • OpenCode 1.2.20
Key elements:
- Left panel: conversation (messages, tool calls, results)
- Right panel: sidebar with
█border — title, context tokens, cost, LSP info - Prompt box: bottom, framed with
┃╹▀ - Model info: inside prompt box
Build Claude Sonnet 4.5 lansweeper.ai
Permission Prompt
┃ △ Permission required
┃ ← Access external directory /tmp
┃
┃ Patterns
┃
┃ - /tmp/*
┃
┃ ~/path:main
┃ Allow once Allow always Reject ctrl+f fullscreen ⇆ select enter confirm
┃ • OpenCode 1.2.20
Working State (during tool execution)
Footer changes to show progress bar and interrupt hint:
■■⬝⬝⬝⬝⬝⬝ esc interrupt tab agents ctrl+p commands • OpenCode 1.2.20
■(U+25A0) — completed steps⬝(U+2B1D) — remaining steps- Mode label may switch:
Build→Planin prompt box
Error State
┃ Error: Unable to connect. Is the computer able to access the url?
Errors displayed inline in the ┃ frame, same area as conversation.
Key elements:
△(U+25B3): permission required marker←: tool call prefix (Write direction)- 3 inline options:
Allow once Allow always Reject— not numbered, not multiselect - Footer:
ctrl+f fullscreen ⇆ select enter confirm ⇆(U+21C6): select/navigate hint- Pattern display: shows glob pattern (
/tmp/*) - Entire dialog inside
┃frame — prompt box expands to contain it
UI Element Reference
Prompt Frame
- Left border:
┃(U+2503, heavy vertical) - Bottom border:
╹▀▀▀▀...(U+2579 corner + U+2580 upper half blocks) - No
❯,›, or>prompt char - Model info inline:
Build Claude Sonnet 4.5 lansweeper.ai
Right Panel Border
█(U+2588, full block) — vertical border for sidebar▄(U+2584, lower half block) — top corner of sidebar
Tool Call Prefixes
→— Read operations (files read by the agent)←— Write operations (files written/modified by the agent)
Completion Marker
▣(U+25A3, white square with rounded corners) — marks completed tool calls- Format:
▣ Build · anthropic/claude-sonnet-4.5 · 10.2s
Tips
●(U+25CF) — orange marker (rgb 245,167,66)- Format:
● Tip <highlighted_word> <gray description>
Status Bar
- Left:
~/Gits/personal/tuicommander:main(path + branch) - Right:
1.2.20or• OpenCode 1.2.20
Navigation Hints
tab agents— switch to agents panelctrl+p commands— command palettectrl+f fullscreen— toggle fullscreen (in permission dialog)⇆ select— select between optionsenter confirm— confirm selection
Rendering Mechanics
Full-screen with background
\033[48;2;10;10;10m — near-black background fills entire screen
\033[48;2;30;30;30m — slightly lighter for input box
Absolute cursor positioning
\033[29;42H — cursor to row 29, col 42
Mouse tracking (enabled on startup)
\033[?1000h — normal mouse tracking
\033[?1002h — button-event tracking
\033[?1003h — all-motion tracking
\033[?1006h — SGR mouse mode
\033[?1004h — focus events
Kitty keyboard protocol
\033[?2026h / \033[?2026l — toggled very frequently (polling pattern)
Cursor
\033[1 q — blinking block cursor
\033[?25h — show cursor
\033[?25l — hide cursor (during redraws)
Color palette queries (on startup)
\033]4;0;?\007 through \033]4;15;?\007 — all 16 ANSI palette colors
\033]10;?\007 through \033]19;?\007 — foreground, background, etc.
Implications for TUICommander
Chrome Detection
OpenCode is a full-screen TUI — every row changes on every update. The
changed_rows / is_chrome_row approach does not work. Needs:
- Full-screen TUI detection mode (mouse tracking + full background = TUI)
- Screen-snapshot-based parsing instead of changed-row delta analysis
Prompt Detection
No standard prompt char (❯, ›, >). Would need to detect ┃ frame
or input box background color change.
Permission Detection
△ Permission requiredis a unique text signalAllow once Allow always Rejectfooter is unique to OpenCode- No OSC 777 notifications observed
Subtask / Subprocess Count
None. OpenCode does not expose subprocess/subtask counts. Instead:
- Tool calls shown inline in conversation panel (
→ Read,← Write) - Progress bar in footer:
⬝■■■■■■⬝(filled/empty squares) - Completion marker:
▣ Build · model · time
Working State
- Progress bar:
■■⬝⬝⬝⬝⬝⬝in footer row — graphical, not numeric - Mode label: changes from
BuildtoPlanin prompt box - Interrupt hint:
esc interruptin footer during work - No spinner chars — uses progress bar instead
Busy/idle detection (v1.18.5, 2026-08-02)
detect_opencode_screen_activity in src-tauri/src/pty.rs owns the transition. Neither
generic signal applies: OpenCode paints no prompt glyph, and is_spinner_row does not
recognise the ⬝/■ progress bar (deliberately — a leading ■ run is not a spinner). The
adapter therefore keys on the composer frame plus the status bar painted under it:
| Row | Idle | Working |
|---|---|---|
| frame | ┃ rows closed by ╹▀▀▀… | identical |
| status bar | /abs/path 18.1K (9%) ctrl+p commands | ⬝⬝⬝⬝⬝■■■ esc interrupt 18.1K (9%) ctrl+p commands |
- Working = a row below the frame-close row contains
esc interrupt. Verified live to hold for the whole turn, including a tool phase (⠼ sleep 20 && echo done) and at 62 columns, where the status bar drops fields but keeps both hints. - Ready = OpenCode frame present and no interrupt hint, and the status bar’s
ctrl+p commandshint is on screen. That last condition is what stops a half-painted frame from reading Ready mid-turn. - Unknown otherwise — notably a plain shell after OpenCode exits.
Without this adapter OSC 133 marked the long-lived opencode foreground command busy once
and nothing ever cleared it, so the session stayed busy for the whole process (#535-d4f5).
Status-bar drift since v1.2.20: the welcome screen still shows
tab agents ctrl+p commands plus a ~path:branch … <version> row, but once the first turn
has run the footer collapses into a single bottom row carrying the absolute cwd, a
N.NK (N%) context gauge and ctrl+p commands. tab agents and the • OpenCode X.Y.Z
version suffix are gone from that state — ctrl+p commands is the part present in every
state, which is why the adapter anchors on it.
Error Display
Errors shown inline in the ┃ frame:
┃ Error: Unable to connect. Is the computer able to access the url?
Agent Identification
OpenCode can be detected by:
- ASCII art banner with
OPENCODEtext on first screen ┃╹▀vertical frame chars- Mouse tracking enabled on startup
• OpenCode X.Y.Zin status bar
pi — UI layout and detection
Agent: pi (@earendil-works/pi-coding-agent).
Version audited: 0.83.0 · Date: 2026-08-02 · Theme: rose-pine-moon.
All values below were captured live from a real PTY session (raw ANSI), not inferred.
Identity & rendering
| Property | Value |
|---|---|
| Binary | pi (npm global; the executable on disk is the node interpreter) |
| Rendering engine | @earendil-works/pi-tui (own TUI lib — not Ink, not Bubble Tea) |
| Repaint style | Full-frame, wrapped in synchronized updates (\033[?2026h … \033[?2026l) |
| Screen clear | \033[2J\033[H\033[3J on startup repaint |
| Cursor positioning | Relative — \033[3A up / \033[3B down, then \033[1G, cursor hidden (\033[?25l) |
| Config dir | ~/.pi/agent/ |
| Sessions | ~/.pi/agent/sessions/<encoded-cwd>/<ISO-ts>_<uuid7>.jsonl |
Process identity gotcha. proc_pidpath() (macOS) and /proc/<pid>/comm (Linux) both return
the node interpreter for a pi session, not pi. Foreground-process classification therefore
falls back to argv[0] for known interpreters — see is_script_interpreter in pty.rs and
read_process_argv0 in tuic-core/src/process_env.rs. Without that fallback pi is invisible as an agent.
Bottom zone
Four rows, in this order, present in every state:
──────────────────────────────────────────── separator, RGB(196,167,231)
<composer> reverse-video cursor block + blanks
──────────────────────────────────────────── separator
~/Gits/personal/tuicommander (main) cwd + branch, RGB(110,106,134)
↑1.3k ↓1.8k R15k W6.0k CH88.5% $0.104 3.4%/272k (auto) (openai) gpt-5.6-sol • medium
- No prompt glyph. The composer is a bare reverse-video cell (
\033[7m \033[0m) followed by blanks.is_prompt_linematches nothing here — readiness cannot be prompt-based. - Status row is the reliable “this is a pi screen” marker: the context gauge
N%/Nkplus the•model separator. Seeis_pi_status_rowinpty.rs.
Working state
The composer row is replaced in place by an animated status row:
⠏ Working...
- Spinner: braille
⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏, RGB(196,167,231); label RGB(144,140,170). - Already matched by
chrome::is_spinner_row(braille range U+2800–U+28FF). - Separators, cwd row and status row stay on screen unchanged for the whole turn.
detect_pi_screen_activity therefore reads: spinner in the footer → Working; otherwise, status
row present → Ready; neither → Unknown.
OSC sequences
| Sequence | Notes |
|---|---|
\033]8;;\007 | Emitted after nearly every row (hyperlink reset) |
\033]0;<title>\007 | Only with the terminal-status-title extension installed |
The extension (~/.pi/agent/extensions/terminal-status-title.js) prefixes the title with a state
glyph, repainted every 120ms while working:
| Glyph | State | Source event |
|---|---|---|
○ (U+25CB) | idle | session_start |
⠋…⠏ braille | working | agent_start |
✓ (U+2713) | done | agent_end |
✗ (U+2717) | error | — |
TUIC does not derive activity from this title: the screen adapter already owns the
busy→idle transition, and a second path for the same transition is a race, not a safety net.
The title only feeds the tab name, and cleanOscTitle strips the glyph and the | separator
it sits on so every spinner frame collapses to one stable name (π | tuicommander).
Input
| Property | Value |
|---|---|
| Submit | Enter (verified live: text + \r submits) |
| Newline | shift+enter / ctrl+j |
| Clear to line start | ctrl+u (tui.editor.deleteToLineStart) |
| Interrupt | ctrl+c (app.clear) |
sendCommand’s agent path (Ctrl-U alone, 50ms gap, text, 50ms gap, separate \r) is correct for pi as-is —
ctrl+u is a real binding, so the prefix is consumed rather than echoed.
Not yet observed
Permission/approval prompts, interactive menus (pi config), and the session picker (--resume)
were not triggered during this audit. They are unaudited, not “absent” — trigger them before
relying on any assumption about their chrome.
Configuration
Codex global hook trust
The explicit global installer targets CODEX_HOME/hooks.json and its sibling
config.toml, with ~/.codex as the default. File state is not operational
state. agent_hook_codex_trust asks the installed CLI for current definitions,
keys and hashes, matches the exact TUIC command/event/matcher and execution
settings (including the statusMessage label TUICommander session, which is
what Codex /hooks shows instead of “Unnamed hook”), and writes only each matched trusted_hash through config/batchWrite.
The write uses the native user-layer version as a compare-and-swap precondition.
User-layer selection and write acknowledgements compare host paths, not string
spellings. Equivalent Windows separators and dot components identify the same
file; different files and profiles remain rejected.
Fresh hooks/list readback must retain the same key/hash and report trusted.
No local hash algorithm or trust-bypass option is used.
A process-local async mutex serializes Codex install, uninstall and status reads.
Other clients’ config edits cause a version conflict rather than replacement.
Status reads never write trust, and no trust cache can survive a definition edit.
Unavailable RPCs, profiles not matching the base config, disabled hooks, parse
errors and failed writes/readback produce reviewRequired; normal /hooks
review remains the recovery path. The base configuration is not evidence for
profile-specific hooks. Three RPC response waits are bounded to ten seconds
each; binary detection and lock admission are separate. Native fixture evidence
is in src-tauri/src/fixtures/codex_hook_trust/.
App config recovery and scrollback migration
config.json loads valid saved values even when another field has a wrong type
or enum value. Missing font family, font size or theme uses its current default.
Invalid nested service fields reset independently. Valid legacy service secrets
survive sibling recovery and migrate to the credential vault. Invalid arrays and dynamic
maps reset as one field. Existing serde missing-key migration and opt-in rules
remain unchanged. Unknown keys stay ignored and may disappear on a typed save.
Before recovered settings are written, the original file is moved to
config.corrupt-<uuid> using the existing five-backup retention policy. The
normal IPC and HTTP config response includes a read-only config_recovery
diagnostic with fields and backup_path. Settings startup uses the existing
warning toast and bell path to show these details once per recovery backup in
each store instance. Focus hydration does not repeat the warning. This diagnostic is never
persisted. Invalid JSON retains the whole-file corrupt backup/default behavior;
unreadable files are not renamed.
The scrollback_reflow_migrated marker enrolls old saved configurations once:
without the marker, reflow is enabled and the marker is persisted. Fresh defaults
and explicit saves already mark current intent. A later explicit false remains
false on subsequent loads.
Scoped plugin settings (#1785-c7a1)
Loaded plugins expose plugins.<id> descriptors through the Rust settings owner.
plugin_settings_action(pluginId, action) and POST /api/plugins/{id}/settings
share describe/get/set/reset/patch semantics. The backend fixes both the owner and
plugins/<id>/data/config.json; requests cannot choose a store, target or file.
Get requires explicit paths; writes require the last expectedRevision.
A configurable manifest declares settings: { schema, defaults }. The schema is
closed (additionalProperties: false), bounded to 128 annotated leaves, and uses
only the supported object, scalar and scalar-array constraints. Every leaf needs
x-setting sensitivity, apply mode, effect, operations and confirmationClass.
Opaque objects, unsupported constraints, missing metadata and secret defaults are
rejected. A plugin with an existing config file and no schema cannot load or write
that config. Other plugin data, including statistics, remains separate.
Core supplies typed migrations for build-cleaner, at-capacity-retry,
cache-keepalive, claude-wakeup and the Telegram notifier example. Registration
fills missing defaults without discarding saved values, validates the result and
atomically writes an owner-only config file (0600 on Unix). Existing bot tokens
remain available to the notifier’s private config reader; the settings service
returns only set/unset. Catalogue definitions, errors and reload events contain no
stored credentials. Plugin enablement stays in app.disabled_plugin_ids; native
agent usage has no private plugin store.
Patches validate the entire batch against current state under the shared config
and cross-process file locks. Stale revisions conflict, failed writes emit no
reload event, and unload removes descriptors and revokes retained owner handles.
After persistence, plugin-changed is dual-emitted to desktop and SSE so existing
unload/load callbacks reread config. applied: false reports scheduled reload,
not completed callback acknowledgement. Backend unregistration is awaited before
reload registration. General MCP settings publication remains a separate cutover.
Plugins can call host.settings({ action: "get", paths: ["/enabled"] }) and pass
the resulting revision to set/reset/patch. The host supplies its plugin ID.
Module: src-tauri/src/config.rs
Manages all application configuration as JSON files in the platform config directory.
Config Directory
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/com.tuic.commander/ |
| Linux | ~/.config/com.tuic.commander/ |
| Windows | %APPDATA%/com.tuic.commander/ |
Legacy paths {platform_config}/tuicommander/, {platform_config}/tui-commander/
and ~/.tuicommander/ are auto-migrated on first launch.
tuic-remote --instance <id> selects an isolated named namespace at process
bootstrap. Named files live below the platform path above at
instances/<id>/; the default instance keeps the paths in the table unchanged.
The ID is a 1–63 character lowercase ASCII DNS label (alphanumeric ends,
internal hyphens allowed), and default is reserved. A named instance never
runs the default or legacy file migrations and never falls back to those
locations when its own files are absent.
The desktop binary has no --instance flag of its own (Tauri’s own CLI/single-instance
plugin already owns argv there), but reuses the same AppInstance::named selection
via the TUIC_APP_INSTANCE env var, read once at the very top of run() in
lib.rs, before any config_dir() call. TUIC_APP_INSTANCE=<id> make dev (or any
debug/test launch) gets the same isolated instances/<id>/ namespace tuic-remote --instance <id> gets — an actual code-enforced boundary rather than a documented
risk, closing the gap in AGENTS.md’s “Isolation caveat” where a second debug
instance previously shared repositories.json with Boss’s production instance with
nothing but discipline preventing a throwaway test repo from being persisted there
(#763-d219). An invalid or already-selected id fails the process at startup rather
than silently falling back to the default instance.
make agent-test is the preset macOS agent verification target. It selects
instances/agent-test/ and loopback port 19876 with dedicated
AGENT_TEST_INSTANCE / AGENT_TEST_PORT variables, and uses a distinct executable
and Tauri identifier. It does not inherit the daily target’s TUIC_* settings.
Its dedicated entry point rejects default/empty instances, production port 9876,
release builds and dictation-enabled builds before reading configuration.
Runtime guards disable global input, Telegram, updater, global MCP writes and
global CLI installation/update/removal. Hook enable/disable requests are rejected
before saving instance flags or changing shared agent files. These are not merely
editable configuration defaults. See
Development Setup
for the resource audit, dry-run and stop commands.
make agent-test-github and make agent-test-github-stop reuse the persistent
agent-test-ghlive instance on port 19887 for authorized GitHub live checks.
They pin both values rather than inheriting a per-agent instance override. This
keeps the existing login available across worktrees and rebuilds without copying
credentials or changing generic verification defaults. Only one coordinated owner
may run this instance at a time. Its debug vault is stored in
~/.tuicommander-dev/instances/agent-test-ghlive/credentials.json; configuration
and account metadata stay in the platform config directory. Stop removes runtime
PID/FIFO files only. A different instance name selects a different vault, not a
fresh build of the same login. See the development guide’s
persistent login procedure.
Which target defaults to what is deliberate and guarded. make test is the
throwaway verification launch and defaults to instances/tuic-test/; make dev
is Boss’s daily driver and carries no instance, because switching it looks
exactly like every repository having vanished. That default is written
test: TUIC_APP_INSTANCE?=tuic-test — target-specific. A line-start
TUIC_APP_INSTANCE?=… is a global make variable however far down the file it
appears, reads identically, and has sent make dev to the empty test instance
twice; scripts/check-make-instance-scope.sh asks make -n what each target
actually expands, and runs from both make check and pre-commit. An
environment assignment still beats a target-specific ?=, so
TUIC_APP_INSTANCE=<id> make dev keeps working and make dev announces the
configuration directory it starts on — no check can see a developer’s shell.
The tuic CLI and tuic-bridge sidecar use the same immutable instance
selection through tuic-ipc. Both accept --instance <id>, which takes
precedence over TUIC_APP_INSTANCE. The CLI’s background runner inherits that
selection, so wake markers stay in the same instance directory. On Unix,
TUIC_SOCKET takes precedence over automatic endpoint resolution.
The credential namespace follows the same immutable selection. The default
vault remains keyring service tuicommander, user vault; a named instance
uses service tuicommander-instance-<id>, user vault. Named instances never
scan, import, modify, or delete default or legacy credential entries, including
the dynamic legacy MCP credential locations. Release tuic-remote probes a
named vault before binding its socket and exits on failure; it does not interpret
a keyring error as an empty vault or silently fall back to a file.
tuic-remote --credential-file <path> explicitly selects a read-once JSON vault
map instead: no OS keyring or legacy migration is used, including for missing
slots. Credential writes are process-local; the seed file is never modified.
Unreadable or malformed input stops startup before listeners bind, with no input
contents in the diagnostic. Rotate by replacing the file and restarting; API
credential edits do not survive restart. This selector is not a config JSON field
and does not change desktop defaults. See the remote-access guide for setup.
Debug builds retain the file-backed credential adapter, scoped below the selected instance directory.
Instance selection precedes --set-password, so password setup writes only to
the selected namespace.
TUIC_CAPTURE_DIR overrides only the raw PTY capture directory. Set it to an
absolute path before starting TUICommander to write .tcap files outside the
instance config directory. A relative value rejects capture activation; it
does not fall back to the default directory. GET /diagnostics/capture reports
the selected directory while recording.
Desktop verification may also set TUIC_PORT=<port> to choose the process-local
HTTP listener port without changing config.json; an occupied port still uses the
existing next-port retry.
For the default instance, debug and release builds share this one directory
— config_dir() never branches on cfg!(debug_assertions). The single-instance lock is release-only
(lib.rs, #[cfg(not(debug_assertions))]), so a make dev build runs happily
alongside the installed app, and both read and write the exact same
config.json, repositories.json, and every other file below. What makes that
safe is the locking model in ConfigFile<T> (see Core Functions): a
cross-process advisory file lock. Ordinary AppConfig, upstream MCP, and
repository writes additionally apply caller deltas to the latest value while
that lock is held, so independent edits from two processes compose instead of
becoming ordered whole-document overwrites. repositories.json used to be the
one exception, seeded into a separate ~/.tuicommander-dev/ directory on first
debug run; that seeding path is gone and it now lives here like everything
else (see below).
A Rust test can never name the real directory
In a cfg(test) build config_dir() returns the override set by
set_config_dir_override(dir) when one is in scope, and otherwise a safe,
process-scoped fallback under the OS temp directory
(test_fallback_config_dir, a OnceLock computed once per test process:
<temp_dir>/tuic-test-fallback-<pid>) — never the user’s platform config
directory, with or without an explicit override.
It used to fall back to the user’s platform directory instead, so a test that
forgot the override read and wrote Boss’s live config.json and
repositories.json in silence. That silence is what let fifteen tempfile
roots become permanent repository rows (#763-d219): the damage was
indistinguishable from normal operation until someone diffed the file.
A first fix made the no-override branch panic instead of falling back —
correct in isolation, but it reproducibly broke the full cargo nextest run --lib suite two different ways: (1) a #[should_panic] test exercising that
exact panic poisoned the guarding mutex on unwind (a temporary MutexGuard
was still alive through the panicking expression), and a later Drop call
locking the poisoned mutex aborted the whole process (SIGABRT) instead of
unwinding; and (2) any test that already held an explicit override (via an
isolated_config()-style helper) and then called a shared helper that also
tried to set one self-deadlocked, because the guarding mutex is not reentrant.
The silent process-scoped fallback removes both failure modes: nothing needs
the exclusive lock unless a test deliberately wants one, and dozens of
call chains that reach config_dir() without caring where it lives (most not
touching repositories.json at all) get a safe, stable-within-the-process
answer instead of a panic or a hang. config_dir_in_a_test_never_names_the_real_user_directory
and fallback_config_dir_is_never_the_real_directory (config.rs) prove the
fallback and the real directory can never coincide.
A thread-local fallback was considered and rejected: code under test that
offloads work to spawn_blocking (finalize_merged_worktree,
merge_and_archive_worktree) runs on a different OS thread than the test
itself, so a thread-local override set on the test’s thread would not be
visible there — reintroducing the same gap on a thread the test can’t reach.
without_config_dir_override() takes the same exclusive lock while
deliberately leaving the override unset — the one way to observe the fallback
branch without racing a concurrent test that did set an override. It is not an
escape hatch.
This guard covers unit tests only. Integration tests under src-tauri/tests/
compile the library without cfg(test), and make dev is not a test at all —
both isolate with TUIC_APP_INSTANCE=<id> as described above.
The plugins/ subdirectory holds external plugin packages. Version 2.0.0
externalizes Plan Tracker and Stories Ticker by seeding plugins/plan/ and
plugins/stories-ticker/ once. The root marker
.externalized-plan-stories-v1 records completion: existing packages are never
overwritten, and removing either seeded package after migration is permanent.
One runtime cache and one transient SSH socket support SSH-managed remote daemons:
remote-bin/<version>/tuic-remote-<target>stores a verified release asset after an atomic staging download. It contains executables, never credentials.~/.ssh/tuic-%Cis the hashed OpenSSH ControlMaster socket shared by TUIC’s tunnel, remote-command and SCP processes. Keeping it under the user’s short, access-controlled SSH directory avoids macOSApplication Supportspaces and keeps the expanded Unix socket path below the platform length limit. TUIC usesControlPersist=no: a live tunnel remains the reusable master, while a one-shot command cannot leave an unmonitored master behind.
Remote pairing tokens use the credential vault key
remote/connection/<uuid>/pairing-token; they never live in either directory or
in connections.json.
Each connection stores auto_update there. Missing values default to false.
Core Functions
Launch assets use temporary-file writes, fsync and atomic rename. On Unix,
claude.json is published as 0600 and codex-notify.sh as 0700: the script’s
execute permission is set before rename, so concurrent boots cannot expose a
non-executable notify script. Other config writes retain the 0600 default.
#![allow(unused)]
fn main() {
pub fn config_dir() -> PathBuf
pub fn load_json_config<T: DeserializeOwned + Default>(filename: &str) -> T
}
Config domains write through ConfigFile<T>:
#![allow(unused)]
fn main() {
impl<T: Serialize + DeserializeOwned + Default> ConfigFile<T> {
pub fn update<F: FnOnce(&mut T) -> bool>(&self, mutate: F) -> Result<(), String>
pub fn update_with<R, F>(&self, mutate: F) -> Result<R, String>
pub fn update_with_strict<R, F>(&self, mutate: F) -> Result<R, String>
pub fn save_delta(&self, base: &T, desired: &T) -> Result<(), String>
pub fn read_preserving_invalid(&self) -> Result<T, String>
// Available with the dictation feature or in tests:
pub fn save_delta_normalized(
&self, base: &T, desired: &T, recover_invalid: bool,
normalize: impl FnOnce(T) -> T,
) -> Result<(), String>
}
}
Two locks protect every write: an in-process CONFIG_WRITE_LOCK mutex, and a
cross-process advisory file lock (std::fs::File::lock() on a sibling
<file>.lock) that serializes writers across the debug/release instances that
now share one config dir. Interactive per-domain saves use save_delta: each
request carries the snapshot loaded by that client (base) and its edited document (config). The
server applies only the base-to-config changes to the latest locked file. Object
keys merge recursively, arrays replace as a unit, and JSON null deletes a key.
Null also deletes a key within a newly added nested object, so that key is not
persisted there.
Notes saves use update_with_strict with ID-keyed note deltas and refuse to
replace a corrupt file. Dictation uses save_delta_normalized to normalize the
latest document and apply the caller’s delta under both locks. If its strict read
fails, it writes the desired document only when recover_invalid is true;
otherwise it returns the error. A valid file saved meanwhile receives the delta.
Remote connection edits use the same JSON delta per connection id; they also
hold the shared file lock while reading and writing connections.json.
config.json (AppConfig) and mcp-upstreams.json also merge deltas under
the lock. repositories.json uses the ID-keyed optimistic delta protocol
documented below. See
2026-08-08-config-deltas-under-lock.md.
Corrupt File Handling
Strict loads attempt to rename a config file that does not parse to
<name>.corrupt-<uuid> before returning an error
(preserve_corrupt_config). The UUID is fresh per occurrence on purpose: a fixed
backup name would let a second corrupt load erase the document the first one
saved, which is the same data loss one step removed. Recovery is by hand.
After each successful rename, a best-effort cleanup keeps at most five backups
per config file, deleting the oldest ones first. The newly preserved backup
is always kept; another config file’s backups do not count toward this limit.
Two strict entry points reach it. load_json_config_strict refuses to return
Default for a broken file on the read side (notes.json, GH #107), and
update_with_strict does the same on the write side, so a read-modify-write
aborts instead of persisting Default over real data (repositories.json,
mcp-upstreams.json). Missing files still start from Default. Ordinary
update_with and save_delta use the non-strict loader, which logs read or parse
errors and returns defaults without moving the file aside.
read_preserving_invalid instead returns an error without moving invalid input,
so repeated safety checks cannot mistake quarantined data for an empty default.
config.json reaches neither, because load_app_config must return an
AppConfig and has no error channel to a caller. It preserves the file directly:
an unparseable config.json is moved aside and defaults are returned, so the
first-run branch that fills in a missing session token and VAPID key is free to
write a fresh document without destroying the old one. Only a parse failure
triggers the rename — an I/O error leaves the file alone, since the document may
be intact and only the read failed.
Config Files and Commands
Application Config (config.json)
Type: AppConfig
Frontend surfaces use the shared updateAppConfig() queue. Each save sends the
loaded snapshot and edited config; the queue keeps writes within one WebView in
order.
Ordinary saves merge under the cross-process lock; they do not replace the
document. IPC save_config/save_app_config, PUT /config, and MCP config
with action: "save" require { "base": <loaded AppConfig>, "config": <edited AppConfig> }. The backend computes that client’s changes before taking the
file lock. commit_config_save locks config.json, reloads and hydrates the
latest disk value, applies only those changes, persists it, and refreshes
state.config from the result. Objects merge key by key; arrays and scalars
replace wholesale (so an empty array still clears a list, null clears an
optional field, and "" still blanks a string).
This is not cosmetic: every field carries #[serde(default)], so deserializing a
partial body on its own reset the omitted ones — services.server.enabled defaults
to false, which is how a partial save used to switch remote access off on disk
while the already-bound listener kept serving, surfacing only at the next boot.
All three writers also share server_settings_changed and rebind the listener
through restart_after_server_settings_change when services.server.{enabled,port, ipv6_enabled} or services.auth.{username,password_hash} move, so the running
process can never serve a configuration the disk disagrees with.
commit_config_change itself bumps relay.config_revision after every write.
relay_client::supervise — spawned at boot whether or not the relay is enabled —
watches that counter and starts, stops or restarts the relay client when
services.relay.{enabled,url,token,session_id} move. The signal is raised at the
choke point rather than by each writer on purpose: a ConfigSaveEffects flag is
only actioned by the callers that remember it, and a relay toggle that silently
needs an app restart is what that costs.
| Field | Type | Default | Description |
|---|---|---|---|
shell | Option<String> | None | Shell override (platform default if None) |
font_family | String | "JetBrains Mono" | Terminal font family |
font_size | u16 | 14 | Terminal font size |
theme | String | "commander" | Terminal theme. An empty or unknown key falls back to commander (DEFAULT_THEME, src/stores/settings.ts) |
ide | String | "" | IDE for “Open in…” |
ego_executable | String | "" | Absolute path to the one ego binary this host may launch for ACP or read for terminal Chat transcript exports. Terminal Chat requires local transcript v1 support (ego export SESSION --format transcript --after SEQ). Read at each ACP connect or Chat binding, so a correction takes effect without a restart. Empty means ACP is not configured and terminal ego Chat is unavailable. No ACP command carries it: a connect supplies a working directory and nothing else, so no request can choose which binary runs. It is edited in Settings > General and written through save_config like any other field |
ai_chat_workspace | String | "" | Absolute directory every AI Chat conversation runs in. Empty means the home directory of the host that runs ego. A missing directory is created at connect; a relative path or an uncreatable one is refused with a message naming this setting. Conversations and peer identities are keyed by this path, so changing it starts from a fresh conversation list. Edited in Settings > General > AI Chat workspace, which refuses a non-absolute path |
ai_chat_master_prompt | String | "" | Additive instructions for new AI Chat conversations. Maximum 8192 UTF-8 bytes; NUL is rejected. Saved per conversation in ai_chat_launches.masterPrompt, including across reopen and fork. Empty omits the extra argument. New ego processes receive --append-system with a fixed heading and the literal text, not a file reference. Existing TUIC MCP rules remain unchanged. Shared ACP connections and unattended Smart Prompts, PR reviews, changelog generation and story drafting do not receive these instructions. This private setting is not logged. |
ego_profile | String | "" | Optional name of an ego user-config profile for AI Chat ACP launches. Empty omits --profile; a nonempty valid name adds --profile <name> after the repository root. Names with whitespace, control characters, a leading dash, or more than 64 UTF-8 bytes are refused before launch. TUICommander does not copy profile policy into ACP requests. When .tuic.json selects a repo profile, this explicit selection is also its non-relaxable ACP ceilingProfile. |
ai_chat_sessions | Map<String, String> | {} | Active ego session ID per canonical AI Chat workspace root, shared across devices. The backend selection API uses the locked config delta path; changed selections emit ai-chat-selection-changed over IPC and SSE. Reads restore the current selection after reconnect or restart. |
ai_chat_peer_ids | Map<String, String> | {} | Host-issued ACP orchestration peer UUID per canonical repository root. The backend persists it before launching ego and reuses it across reconnect and restart. It is not a PTY tab ID. |
default_font_size | u16 | 13 | Default font size for reset |
attachment_max_bytes | u64 | 26214400 (25 MiB) | Binary upload cap per file; must be positive. |
attachment_retention_days | u32 | 7 | Obsolete for uploads: attachment lifetime is now the session. This stored value has no effect on attachment cleanup. |
mcp_server_enabled | bool | true | Enable MCP HTTP server |
plugin_http_destinations | Vec<String> | [] | Owner URL patterns (manifest allowedUrls syntax) that every net:http plugin may reach without an account, localhost and LAN included. Only http/https; checked for the first URL and every redirect hop. Read on each request. An agent settings API write that adds a pattern needs confirmation. Account requests keep the account host rule (#2659-b083) |
mcp_port | u16 | 3845 | Fixed port for MCP server (0 = OS-assigned) |
mcp_capabilities | object | {denied:["diagnostics"],migration_unknown_tools:[]} | Native capability denials. Old disabled_native_tools migrates once; unknown names remain visible. Parent denials cover grouped actions; member denials remain scoped. Settings groups these keys by backend-owned domain, section and parent metadata; conditional availability is independent of denials. See MCP capability cutover documentation. |
collapse_tools | bool | false | Replace the full MCP tool list with 3 lazy-discovery meta-tools (search_tools, get_tool_schema, call_tool). Discovered native schemas are unchanged: managed commands still use one call_tool invocation of session action=submit and receive the bounded receipt in that response. Grok sessions use this surface automatically without changing the stored value — see mcp-http.md. Size figures for both surfaces, and how to reproduce them, are in Measuring the surfaces — the reduction is measured, never estimated |
services | ServicesConfig | {} | Nested remote-access config: server, auth, tls, relay, push (replaces the former flat remote_access_*/push_enabled/relay_enabled fields) |
Session attachment directories record their owner PID outside the granted directory. Startup cleanup preserves live or unknown owners and removes only provably dead owners; multiple processes may share the data directory safely.
Remote-access secrets under services are not persisted in plaintext
config.json: auth.session_token, relay.token, and
push.vapid_private_key live in the OS keyring-backed credential vault. The
JSON file keeps only the non-secret settings plus session_token_exists,
token_exists, and vapid_private_key_exists booleans for UI state.
services.push.added_providers (string[], default []) lists push service
hosts the owner added beyond the built-in Google, Mozilla, Windows and Apple
suffixes (#2668-aa16). An endpoint host matches an entry exactly or as a
subdomain: push.example.net accepts push.example.net and
updates.push.example.net, not evilpush.example.net or
push.example.net.evil.test. An entry is a bare DNS host with at least two
labels; the settings owner refuses URLs, wildcards, bare top-level domains and
empty labels with out_of_range, and an invalid entry in a hand-edited file
matches nothing. HTTPS stays required. The list is read at subscribe time and
again before each send, so removing a host stops delivery to its saved
subscriptions without deleting them. A settings-facade change needs the owner’s
confirmation, like the relay URL.
A vault read failure is never treated as “the secret is absent”: on error
hydrate_one_secret keeps the *_exists flag that config.json recorded, so a
momentarily locked keychain cannot flip the flag to false and make the next
save delete a live credential. Plaintext still found in config.json is moved
into the vault at load time and the file is rewritten immediately, so the
cleartext copy does not survive on disk.
| close_behavior | ask \| background \| quit | ask | Main-window close asks, hides visible windows, or quits. Ask offers Remember. Explicit Quit ignores this policy. |
| confirm_before_quit | bool | true | Confirm real quit when live terminal sessions exist; does not block Background |
| confirm_before_closing_tab | bool | true | Show tab close confirmation |
| copy_on_select | bool | true | Auto-copy terminal selection to clipboard |
| osc52_clipboard | bool | true | Honor OSC 52 clipboard-write sequences from terminal output (a notice shows on each write; disable to ignore them) |
| bell_style | String | "visual" | Terminal bell: “none”, “visual”, “sound”, “both” |
| disabled_agents | Vec<String> | [] | Agent IDs hidden from the Add menu |
| global_hotkey | Option<String> | null | OS-level window toggle hotkey combo |
| intent_tab_title | bool | true | Show agent intent as tab title |
| language | String | "en" | UI language code |
| max_tab_name_length | u32 | 25 | Max tab name display length |
| tab_cycling_all_types | bool | false | When true, next/prev-tab shortcuts cycle file/diff/markdown/editor tabs too (default cycles terminals only) |
| chat_mute_intermediate_text | bool | true | Chat (terminal Chat view, AI Chat, mobile) draws assistant text that a tool call follows in the same turn smaller and dimmer. The final text of a turn keeps the normal style. Applies immediately. |
| tab_tree_enabled | bool | false | Opt-in sidebar activity cards. false renders no activity caret, card, or nested agent/session rows. true lets every branch with an open terminal session expand its assigned sessions. Applies immediately; no restart is required. |
| defer_update_relaunch | bool | true | After an update installs, hold the app restart until no session is busy or awaiting input. The APP UPDATE notification shows the busy count and offers Restart now. false restarts as soon as the install ends. Applies immediately. |
| eager_resume_after_update | bool | true | After the app restarts for an update, resume every agent tab whose session id the agent confirmed on disk, on every branch (the resume command is typed at first shell idle). A branch with no such tab, and any unconfirmed tab, keep the lazy click-to-resume banner. Applies at the next update restart. |
| prevent_sleep_when_busy | bool | false | Prevent idle system sleep while backend-owned agent work remains live |
| suggest_followups | bool | true | Show suggest: follow-up actions |
| issue_filter | Option<String> | "assigned" | GitHub Issues filter: “assigned”, “created”, “mentioned”, “all”, “disabled” |
| experimental_features_enabled | bool | false | Opts in to the AI Chat panel shell and SSH Tunnels. It has no sub-flags: ai_chat_enabled, ai_triage_enabled and ai_watchers_enabled went with the embedded AI engine (#784-0aec). A config.json written before that upgrade still carries them and still loads — AppConfig has no deny_unknown_fields, and a_config_written_before_the_ai_engine_was_deleted_still_loads holds that open |
| auto_show_pr_popover | bool | true | Auto-show PR popover when switching to a branch with a PR |
| update_channel | String | "stable" ("beta" in beta builds) | Update channel: “stable”, “beta” or “nightly”; legacy stable choices migrate once on beta builds |
| inline_blame_enabled | bool | true | Show GitLens-style inline git blame on the code editor’s active line |
| show_block_timestamps | bool | true | Label each command block with its elapsed time while Ctrl+Cmd is held. Frontend-gated (painted by the renderer); stored here for persistence |
| show_scrollbar_marks | bool | true | Draw command-block marks on the terminal scrollbar. Frontend-gated, toggled from Settings > Terminal |
| block_folding_enabled | bool | true | Let the block-fold-toggle shortcut collapse a command block’s output. Frontend-gated. Blocks already folded stay folded when this is off |
| scrollback_reflow | bool | true | Re-wrap scrollback history on a column resize instead of truncating it. Backend-gated: AppState::new_vt_log_buffer applies it to a new grid and commit_config_change pushes a change to grids already open. Defaults true — including for a config.json written before the key existed — because the grid reflowed unconditionally before the flag had a consumer |
| index_strategy | String | "active_and_switch" | Which repos get a BM25 content index: "active_and_switch" (the boot repo plus every repo switched to), "active_only" (boot repo only), "all_sequential", "disabled". Read from the in-memory config on every switch and every RepoChanged — never load_app_config(), which takes a cross-process file lock |
| index_memory_budget_mb | usize | 256 | Approximate memory budget in MiB for resident content indices. The least recently used indices are evicted when the budget is exceeded. An evicted index is saved to <data_dir>/content-index/ and reloaded and checked against disk on its next use. A single oversized index can exceed the budget. Existing saved values are not changed. |
On macOS, the desktop process always opts out of App Nap, even while hidden and
with no busy agent. This process-lifetime activity permits idle system sleep;
prevent_sleep_when_busy controls the separate sleep assertion.
A dedicated backend thread reconciles this assertion once per second, independent
of WebView visibility or JavaScript execution. It uses live PTY ownership,
backend turn/background state, the existing process-tree helper exclusions,
detached tuic bg runner identity and managed keep_open holds. ACP active or
queued turns and live ACP keep_open peers also count. Unknown process inventory
fails closed for a live agent. Idle agents share one process inventory attempt
per five seconds, including failed attempts and legacy refresh calls. Acquisition
runs outside the native assertion lock. Backend work is still checked every second
and again before each native transition. A cached negative applies only to the
same PTY, managed identity, agent type, foreground root and turn; a new lifecycle,
in-flight query or observation at least five seconds old retains the hold until
a fresh inventory resolves it. A slow inventory query can therefore extend a
hold, not release it from stale evidence. Quiet descendants without a backend
work signal can take up to five seconds plus OS query time to be observed.
The assertion is retried after native acquisition failure. Display sleep remains allowed; the setting can release the assertion.
The remote daemon does not start the desktop host’s sleep-prevention owner.
The 2026-10-27 incident was a frontend busy-only policy gap, present since
fd75c1c524: a ready composer could release both TUIC assertions despite live
background work. At 21:19:21 the log shows TUIC releasing both its idle-system
and system-sleep assertions, then entering Idle Sleep on AC for 503 seconds.
A separate caffeinate -i assertion was not sufficient in that power state:
pmset -g log records DarkWake at 21:17:49 for 92 seconds, ending at 21:19:21.
The installed IOKit IOPMLib.h explicitly states that
kIOPMAssertPreventUserIdleSystemSleep has no effect in Dark Wake. Its presence
in the aggregate PrevIdle flags therefore does not prove effective inhibition.
TUIC’s release removed its separate PrevSleep flag while PrevIdle remained.
This explains why the idle assertion did not protect that DarkWake interval;
it does not prove a macOS assertion defect, nor guarantee protection against
explicit sleep, lid closure or critical power events. The native keepawake
assertion types are unchanged by this fix.
Hidden-idle
backend work can therefore use more energy than an App-Napped process. See the
controlled replay and its limits.
Content-index repository events share a 60-second cooldown after a build, an incremental update, or a completed unchanged-content validation. A no-op validation does not rebuild the search corpus. Snapshot restoration still reconciles disk state before publication.
Commands: load_app_config(), save_app_config(base, config)
Settings windows compare their current preferences with their own last successful
local snapshot before building this pair. Only locally changed fields are applied
to the freshly loaded base; unchanged store-owned fields keep the loaded values.
This prevents a stale window from expressing another window’s edits as unwanted
reversals. The backend delta and locking protocol is unchanged.
Every writer of config.json — IPC save_config, PUT /config, MCP
config action=save, session-token rotation, set_global_hotkey, the
disabled_mcp_agents toggle and the push auto-enable on first subscription —
goes through
config::commit_config_change, which holds one process-wide mutex across the
whole cache-delta → file-lock → latest-disk-read → delta-merge →
preserve-secrets → write → update-state.config sequence. The cross-process
file lock spans the authoritative disk read and write. This distinction matters:
locking whole-document saves merely orders lost updates, while applying the
delta after the locked read preserves unrelated fields written by another
debug or release process.
Rotation
(config::rotate_session_token, shared by the desktop command and
POST /auth/rotate-session-token) goes through the same path so the vault, the
file and state.config cannot disagree — previously the in-memory config kept
the pre-rotation token and the next unrelated save wrote it back.
The vault and config.json are one logical commit. Before changing any of the
three vault-backed fields, save_app_config snapshots their previous values.
If either a later vault operation or the atomic file replacement fails, all
three vault values are restored before the error returns; state.config and
the live authentication token are updated only after success. A rollback
failure is appended to the original persistence error instead of being hidden.
Individual credential set and delete operations also publish their
in-memory vault clone only after the OS keyring accepts it.
Routing every writer through it also guarantees the file is produced by
config_for_disk. A writer that serialized the config itself (the
disabled_mcp_agents toggle called save_json_config("config.json", ..))
skipped the stripping step and wrote the session token, relay token and VAPID
private key to disk in cleartext.
MCP Bridge Auto-Install
On launch agent_mcp::ensure_mcp_configs writes the tuicommander bridge
entry into each supported agent’s own MCP config only when a non-empty,
executable tuic-bridge is beside the running executable. Launches from a
temporary directory, App Translocation, a mounted volume or an AppImage mount
do not write agent configs. A test binary without that sidecar also leaves the
configs untouched. Launch-time installation and repair belong to the unnamed
default instance outside a linked Git worktree. Named instances and worktree
builds leave agent configs unchanged, including integrations disabled in the
default instance. Set TUIC_MCP_CONFIG_OWNER=1 on a launch only when that
instance is deliberately assigned ownership of global agent configs. Explicit
Install and Remove actions in Settings remain user-requested edits.
Each target uses the format its tool reads:
| Agent | Config file | Shape |
|---|---|---|
| Claude Code | ~/.claude.json | JSON mcpServers |
| Cursor | ~/.cursor/mcp.json | JSON mcpServers |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | JSON mcpServers |
| VS Code | <user dir>/mcp.json | JSON servers |
| Zed | ~/.config/zed/settings.json | JSON context_servers |
| Amp | ~/.config/amp/settings.json | JSON amp.mcpServers |
| Gemini CLI | ~/.gemini/settings.json | JSON mcpServers |
| Droid | ~/.factory/mcp.json | JSON mcpServers |
| opencode | ~/.config/opencode/opencode.json[c] | JSON mcp, {type:"local", command:[…]} |
| Codex | $CODEX_HOME/config.toml or ~/.codex/config.toml | TOML [mcp_servers] + env_vars allowlist |
| Grok | ~/.grok/config.toml | TOML [mcp_servers] |
| goose | ~/.config/goose/config.yaml | YAML extensions (ExtensionEntry) |
| pi | ~/.pi/agent/mcp.json | JSON mcpServers (pi-mcp-adapter extension) |
Codex filters the environment of its stdio MCP servers. Its TUIC entry forwards
TUIC_SESSION, TUIC_SOCKET, TUIC_APP_INSTANCE and TUIC_CONFIG_DIR from the
local process environment. Identity alone is not sufficient: without the endpoint
selectors, an agent launched by a named instance can connect its bridge to the
default instance. Installation repairs incomplete allowlists even when the bridge
command already matches. Existing variables and local-source object entries are
preserved; Grok does not receive the Codex-only allowlist.
A target is written only when it is installed. The writer creates every
missing parent directory, so an unconditional pass used to create ~/.cursor/,
~/.gemini/, ~/.config/amp/ and friends for tools the user never had —
which makes other software report Cursor or Windsurf as installed. Presence is
proven two ways, cheapest first:
- the config directory holds a file that is not the one we write (
.DS_Storeand stale*.tmpstaging files do not count), or - one of the target’s CLI binaries resolves via
cli::has_cli.
Claude’s config sits in $HOME, so it uses ~/.claude as its presence
directory instead of the config file’s parent. pi is stricter still: its MCP
support comes from the optional pi-mcp-adapter extension, which owns
~/.pi/agent/mcp.json — with no such file there is no adapter, so an
auto-written entry would configure nothing.
A target that already holds a tuicommander entry gets a path repair only when
its command is the bare tuic-bridge name or a broken absolute executable path.
Wrapper and templated commands, and HTTP entries with a URL or URI, belong to
the user and are left unchanged at launch. An explicit install rejects a custom
command or HTTP transport until the user removes that entry. An explicit
install may use the bare tuic-bridge name for a new entry when no bridge is
located; it reports an error rather than using that fallback to repair an
existing entry. A working absolute command is preserved. All target-presence
gates live in auto_install_allowed,
which only the launch pass consults: Settings → Agents installs on demand
through ensure_spec_entry directly, because pressing Install states that the
target is there — that is an explicit request, not a guess.
Shared settings files need an explicit install. Zed, Amp and Gemini keep
their MCP server list inside the settings.json that also holds every other
user preference, not a dedicated mcp.json. Those three carry
shared_settings_file: true and the launch pass never creates or edits them:
TUICommander being on the machine is not consent to rewrite the user’s editor
configuration. Settings → Agents installs them on request, and once installed
their missing or unusable bridge commands can be repaired like any other target.
get_agent_mcp_status returns
the flag so the UI can say why the entry is missing.
Never Reserializing a Third-Party Config
Configs that exist but do not parse are never overwritten (JSON, TOML and
YAML alike). Treating a parse failure as an empty document is what reduced a
user’s 400-line Zed settings.json to our single entry
(#115).
JSON targets are never reserialized as a whole. jsonc_edit
parses the document into a concrete syntax tree, splices exactly one member,
and prints it back, so text outside that member is byte-identical. This matters
three times over — serde_json rejects the comments and trailing commas Zed,
VS Code and opencode all document as supported; serde_json::Map is a
BTreeMap, so a round trip alphabetises the user’s keys; and
to_string_pretty discards their indentation.
Only the documented dialect is accepted. Comments and trailing commas parse;
single-quoted strings, unquoted keys and hexadecimal numbers do not, because a
file using them is one the owning tool cannot read either — writing it back as
if it were fine would be worse than refusing. TOML edits preserve comments and
formatting through toml_edit. Goose YAML edits splice the bridge command or
entry with the section’s indentation and compare the parsed document before
and after to verify that other extensions and fields remain unchanged;
unsupported YAML layouts are left untouched.
Existing config files are backed up once under TUICommander’s mcp-backups
directory before any edit. Atomic replacements preserve the file’s permissions
and follow config symlinks to their targets.
Guard rails around the write:
- The edited text is re-parsed and the member compared against what was requested before anything reaches disk.
- The first time we modify a file, its original is copied to
<config dir>/mcp-backups/<agent>-<filename>.orig. Written once and never overwritten — the state worth keeping is the one from before TUICommander ever touched it. It lives under our config directory rather than beside the original, where the owning tool might try to load or sync it. - An edit that changes nothing skips the write entirely, so an idempotent pass never moves the mtime of a file an editor is watching.
Removing Every Integration
remove_all_mcp_integrations drops the tuicommander entry from every target
that has one and adds them all to disabled_mcp_agents — without that the next
launch reinstalls them and the action does nothing. list_installed_mcp_integrations
backs the Settings → Agents panel that lists them. Uninstalling TUICommander
otherwise leaves a dangling tuic-bridge path in each client it ever
configured, and each one reports a broken MCP server on startup. One
unparseable config does not abort the sweep: the rest are still cleaned and the
failures are reported together.
Upstream MCP Config (mcp-upstreams.json)
Type: UpstreamMcpConfig
Interactive saves carry both the configuration the caller loaded (base) and
its desired config. The backend derives additions, intentional removals,
order changes, and per-server field deltas keyed by stable server ID, then
applies them to the latest document inside ConfigFile::update_with. A popup
toggle therefore changes only enabled; an OAuth/DCR auth record written after
the popup loaded is preserved. Removing a server or clearing an optional auth
field remains explicit and is not mistaken for an omitted/unchanged field.
Validation and the runtime registry diff use the exact merged pre/post values from the locked transaction. The lock is released before asynchronous reconnect work starts.
Header metadata uses an explicit empty array when no headers remain, so removing the last header stays a valid config delta. Authenticated HTTP upstreams cannot change origin in place. The locked save compares the latest prior entries by ID or credential-owning name, before persistence and activation, even if the request clears auth/header metadata. Use a separate upstream name for another provider. Same-origin path edits remain allowed.
Add-time secrets travel in an optional write-only credentials array on the save request. Under the same cross-process lock, the backend validates the merged config, creates only new vault entries, and persists the config. Failed saves roll back newly created secrets. An existing credential is never replaced by an add, even at the same origin; the standalone credential endpoint requires explicit replace: true for edits.
Commands: load_mcp_upstreams(), save_mcp_upstreams(base, config, credentials?)
Notification Config (notifications.json)
Type: NotificationConfig
| Field | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | Global enable |
volume | f64 | 0.5 | Volume (0.0-1.0) |
sounds.question | bool | true | Play on agent question |
sounds.error | bool | true | Play on error |
sounds.completion | bool | true | Play on completion |
sounds.warning | bool | true | Play on warning |
silence_remote_completions | bool | true | Mute sounds and OS notices for parented sessions; retain the completion-chime mute for unparented HTTP/MCP sessions |
toasts_in_bell | bool | true | Mirror every toast into the toolbar bell, under a MESSAGES section |
pr_native_notifications | bool | true | OS notification for PR ready / CI failed / changes requested / merged transitions |
Commands: load_notification_config(), save_notification_config(base, config)
Files the embedded AI engine owned (#784-0aec)
ai-chat-config.json, providers.json, ai-prompts.json, ai-watchers.json,
ai-cron.json and ai-chat-conversations/ are no longer read or written.
Nothing migrates or deletes them: a file left behind by an older version is
inert, and removing a user’s data on upgrade is a worse default than leaving it.
ai-sessions/<session_id>.json is also inert after #2115-1333 removed the write-only command knowledge store and its persistence task. Existing history files are not deleted or migrated.
UI Preferences (ui-prefs.json)
Type: UIPrefsConfig
The frontend initial sidebar and Settings navigation widths come from the Rust-generated settings catalogue. Explicit saved widths are not migrated.
| Field | Type | Default | Description |
|---|---|---|---|
sidebar_visible | bool | true | Sidebar visibility |
sidebar_width | u32 | 300 | Sidebar width in pixels |
diff_panel_visible | bool | false | Diff panel open |
markdown_panel_visible | bool | false | Markdown panel open |
notes_panel_visible | bool | false | Notes panel open |
file_browser_panel_visible | bool | false | File browser panel open |
plan_panel_visible | bool | false | Plan panel open |
git_panel_visible | bool | false | Git panel open |
outline_panel_visible | bool | false | Outline panel open |
references_panel_visible | bool | false | References panel open |
ai_chat_panel_visible | bool | false | AI chat panel open |
file_browser_view_mode | String | "tree" | File browser listing: flat or tree |
sidebar_density | String | "auto" | Sidebar layout: auto (rich for a short list or a finger), compact or rich |
mobile_theme | String | "commander" | Mobile PWA appearance (commander or vscode-light), separate from the desktop theme |
diff_panel_width | u32 | 400 | Diff panel width in pixels |
markdown_panel_width | u32 | 400 | Markdown panel width in pixels |
notes_panel_width | u32 | 350 | Notes panel width in pixels |
plan_panel_width | u32 | 350 | Plan panel width in pixels |
git_panel_width | u32 | 380 | Git panel width in pixels |
settings_nav_width | u32 | 232 | Settings nav column width in pixels |
settings_expert_mode | bool | false | Settings “expert mode”: off hides an expert control that is still at its default; on shows every control |
diff_view_mode | String | "split" | Diff viewer: split or unified |
detached_panels | HashMap<String, String> | {} | Panel id to detached window label |
tasks_view_preferences | HashMap<String, String> | {} | JSON-encoded Tasks source per repository and view/query intent per repository/provider/account; saved sort fallback, no result pages |
github_section_collapsed | HashMap<String, bool> | {} | Collapsed GitHub sections (my-prs, prs, issues); absent key means the section’s own default |
The eight *_panel_visible flags for markdown, file browser, git, outline,
references, AI chat, AI triage and notes are mutually exclusive — the
frontend opens one and closes the rest. The backend does not enforce that; it
stores whatever it is sent.
Every key the frontend sends must be declared here. Serde has no
deny_unknown_fields on this struct, so an undeclared key is dropped on the
way in without an error and load_ui_prefs can never return it. The panel
then looks like it saves and silently fails to survive a restart.
Commands: load_ui_prefs(), save_ui_prefs(base, config)
Repository Settings (repo-settings.json)
Type: RepoSettingsMap (HashMap of RepoSettingsEntry)
Per-repository fields:
| Field | Type | Default | Description |
|---|---|---|---|
path | String | – | Repository path |
display_name | String | – | Display name |
base_branch | String | "main" | Base branch for worktrees |
copy_ignored_files | bool | false | Copy .gitignored files to worktree |
copy_untracked_files | bool | false | Copy untracked files to worktree |
setup_script | String | "" | Script to run after worktree creation |
run_script | String | "" | Default run command |
auto_fetch_interval_minutes | u32 | 0 | Auto-fetch interval in minutes (0 = disabled) |
auto_delete_on_pr_close | AutoDeleteOnPrClose | "off" | Auto-delete branch when PR merged/closed (off/ask/auto) |
archive_script | String | "" | Script to run before archive/delete (non-zero exit blocks) |
dev_server_url | Option<String> | None | URL opened by Design Mode for this repository; when unset, opens about:blank. Stored locally and excluded from .tuic.json and repository defaults |
Commands: load_repo_settings(), save_repo_settings(base, config), check_has_custom_settings(path)
Story Backends (story-backends.json, story-connectors.json)
Optional machine-owned settings. Unbound projects use automatic native/Wiz
selection. story-backends.json holds explicit per-project overrides:
{"backend":"native"}, {"backend":"wiz-stories"}, or a legacy
{"command":"node","args":["/abs/adapter.mjs"]}. Invalid explicit settings
never fall back to automatic selection. Repository files cannot name commands.
The Stories header’s explicit approval action writes story-connectors.json.
It is a JSON object keyed by canonical installation path. Each approval records
installation (the same canonical path), script (the canonical connector entry),
digest (SHA-256 of the entry bytes), and version (the installed plugin version).
Approving one installation preserves the other approved installations. Approval
is global to this TUIC instance, not per repository. Installation updates need
renewed approval. Passive registry discovery is not approval. Connector approval
belongs to the machine hosting the project, including remote daemons.
See Story backend protocol for detection, trust,
status fields and the open-plan/execution guards.
Repository Defaults (repo-defaults.json)
Type: RepoDefaultsConfig
Default values applied to new repositories when no per-repo override exists.
| Field | Type | Default | Description |
|---|---|---|---|
base_branch | String | "automatic" | Default base branch |
copy_ignored_files | bool | false | Copy .gitignored files to worktree |
copy_untracked_files | bool | false | Copy untracked files to worktree |
setup_script | String | "" | Default setup script |
run_script | String | "" | Default run command |
archive_script | String | "" | Default archive script |
orphan_cleanup_countdown_seconds | u32 | 10 | Ask-dialog countdown for safe orphan worktrees; Expert Mode offers 5, 10, 20, or 30 seconds |
Commands: load_repo_defaults(), save_repo_defaults(base, config)
Repositories (repositories.json)
Explicit server registration (repo action=add, also used by CLI directory opens)
uses a strict locked read-modify-write. It adds only the canonical repository row,
its initial workspace and order entry, and selects it. Existing rows and unrelated
configuration survive repeated calls. Corrupt configuration aborts registration
and is moved to the existing repositories.corrupt-<uuid> recovery backup. Successful changes emit
repositories-changed to both transports.
Workspace removal also uses a strict locked update. It removes the old workspace
restore row, its saved terminals and peer placement declarations, and clears a
selection of that workspace. Sibling records and the main checkout remain intact.
A changed file emits repositories-changed before the removal lifecycle event,
so disconnected clients do not depend on a frontend save to retract stale paths.
Type: serde_json::Value (flexible persisted JSON, shape defined by frontend)
Stored in the shared config directory like every other file (see Config
Directory) — debug and release builds read and write the same
repositories.json. Every write uses a versioned delta inside the existing
save_repositories(config) argument:
{
"mutationVersion": 1,
"repos": [{ "id": "/repo", "before": {}, "after": {} }],
"groups": [{ "id": "group-id", "before": null, "after": {} }],
"repoOrder": { "before": [], "after": ["/repo"] },
"activeRepoPath": { "before": null, "after": "/repo" },
"groupOrder": { "before": [], "after": ["group-id"] }
}
before is the last value that client successfully loaded or persisted;
after is its intended value, and null in an ID-keyed mutation means absence
or deletion. The backend acquires the cross-process lock, strictly reloads the
latest document, and applies each repository/group mutation by ID. Mutations
to different IDs compose. Independent membership additions/removals in
repoOrder and groupOrder are three-way merged; incompatible reorders
conflict. Active-repository changes use the same before/after check.
A stale mutation of the same repository, group, active selection, or order is rejected with a deterministic conflict instead of overwriting the newer value.
Derived branch fields are exempt from that check. additions, deletions,
isMerged, lastActiveTerminal, lastCommitTs and lifecycleStatus
(DERIVED_BRANCH_FIELDS in config.rs) are a cache each client recomputes from
the repository itself, on
its own refresh cadence — two windows legitimately hold two different values at
the same instant, so comparing them turns every save into a conflict. Measured
2026-08-31: ego moved 331 → 357 additions in 70 seconds while 29 consecutive
saves were rejected, and unrelated intent — registering a repository — was
wedged behind a number nobody edited. The conflict check compares records with
those fields stripped; the “already applied” check stays exact, so a
derived-only update still persists and the cache keeps moving. Everything a
human sets (name, order, grouping, active branch) is still fully guarded, and
concurrent edits to the derived fields themselves resolve last-writer-wins.
IPC reports that error to the frontend, where it creates a user-visible Errors
badge; HTTP returns 409 Conflict. Malformed deltas return HTTP 400. A
versioned delta is required; unversioned whole-document bodies are rejected.
A successful write is announced, so the other clients converge instead of
colliding. One backend serves the desktop WebView, the browser and the PWA at
once, and each keeps its own before baseline. Until this event existed, a save
told the other clients nothing: their baseline stayed stale until a conflict
taught them otherwise, which is late — by then the two documents have already
diverged. Both save paths (save_repositories over IPC, PUT /config/repositories over HTTP) now call AppState::notify_repositories_changed(),
which dual-emits the payload-free repositories-changed event to the desktop
window and onto the /events SSE bus.
It fires only when the document actually moved:
save_repositories_request returns Ok(true) for a write and Ok(false) for a
delta already applied, so a no-op save does not wake every client. The payload is
empty by design — a receiver only needs “disk moved, re-read it”, and shipping
the document would copy the whole repository set to everyone on every save.
On the receiving side repositoriesStore re-reads repositories.json and adopts
a key only when it has no unsaved intent for it — when its live value still
equals its baseline. Adopted keys move in the store and in the baseline
together: those two are diffed against each other on every save, so refreshing
one alone would make the next diff revert what the other client just wrote. Two
keys are deliberately never adopted: activeRepoPath, because which repo a
window is looking at is per-window and a background event must not move the
user’s focus, and a repository whose disk record disappeared while it still holds
open terminals, because dropping it would orphan panes the user is looking at.
Keys this client did change are left untouched and still resolve through the
compare-and-swap rebase.
Four details make that gate hold up in practice:
- The “unsaved intent” test runs on an intent view, not the whole record.
repositoriesStoremirrors the backend’sDERIVED_BRANCH_FIELDS(plushadTerminals, which is session state that happens to be persisted) and normalizes both sides through the same migration passhydrateapplies. Without the first, a repo under active work drifts from its own baseline every few seconds viaupdateBranchStats, which saves nothing — and adoption would be refused for exactly the repos the user is working in. Without the second, a baseline read off disk before the migration defaults were added never matches the migrated store, and a record written by an older build is never adopted. - The live-terminal rule applies per branch, not only per repository. A repo record that survives on disk with one branch removed goes through the merge path, where the repo-level guard never runs; a branch this window still has a pane in is kept there instead.
- Every repo the store holds stays in
repoOrder. The order arrives from the client that did drop the repo, so a record kept for its live terminals would otherwise leave the sidebar while its panes keep running. Grouping is an overlay:getGroupedLayoutfilters grouped paths out ofrepoOrderat render time, so putting a repo back there is always safe. - Adoption waits for an in-flight save. A save ends by assigning the baseline it computed before it was sent, and nothing orders the broadcast against that save’s own reply — so an adoption landing inside the window would have its baseline overwritten while its store changes stay, which is the one state this whole path exists to prevent.
Version skew is the dangerous case, and it is one-sided. A backend from
before the delta protocol does not decode config at all — it stores it as the
whole document, so repositories.json becomes the delta envelope and every
repository is lost. This is not theoretical: make dev never hot-reloads Rust,
so a hot-reloaded frontend meeting a stale backend did exactly that on
2026-08-21. The old binary cannot be fixed retroactively, so the guard lives at
the read end: repositoriesStore.hydrate() treats a root mutationVersion, or
repos as an array, as a poisoned file — it logs a user-visible error, refuses
to hydrate, and leaves hydrated false so no save can run. That last part is
what makes a hand-restored backup stick; without it, the running app clobbers the
restored file within seconds.
repositories.json used to be the one file exempt from the (then-real)
debug/release split: it was seeded into a separate ~/.tuicommander-dev/
directory on first debug run so a dev instance wouldn’t start with an empty
repo list. That seeding path is gone now that both builds share one
directory for repositories.json and all other config domains covered by
this document. (~/.tuicommander-dev/ itself still exists for an unrelated
purpose — see crates/tuic-core/src/credentials.rs’s debug-only credential store.)
Commands: load_repositories(), save_repositories(config)
Stale-temp repository repair (#763-d219)
Live evidence: 15 hydrated repositories.json rows pointed at paths under macOS
temp roots or $HOME/Gits/.tmp that no longer existed on disk — throwaway shell
repos a prior session or agent worktree run created and never cleaned up. Each
was non-git, held exactly one shell-only workspace, and carried no terminals,
saved terminals, diffstat, commit, parent, or user metadata: a maximally
“empty” record, which is exactly why a missing path alone is not sufficient
evidence — a legitimate repository on an unmounted drive or a machine the user
switched away from looks identical on that one axis.
Classifier — classify_stale_temp_repo (config.rs), ALL of:
std::fs::metadata(path)returnsNotFound— the local path is proven not to exist. Permission and other I/O errors preserve the row because they do not prove absence.- The path falls under a recognized temp root (
recognized_temp_roots():std::env::temp_dir(),/tmp,/private/tmp,/var/folders,/private/var/folders,$HOME/Gits/.tmp). isGitRepois explicitlyfalse(never merely absent ortrue).- Exactly one workspace, and it is shell-only: no live or saved terminals, no last-active terminal, no diffstat/commit/merge state, no parent, no run command, no CI auto-heal.
- No user metadata on the repo record itself:
collapsed/parkedare their defaults (false), and noconnectionId/non-emptyinitials.
Any single failing check leaves the record untouched — this is an ALL-of test, not a heuristic score, so a legitimate offline/unmounted/renamed repository always survives.
Commands (IPC + GET/POST /config/repositories/stale-temp HTTP twin):
list_stale_temp_repository_candidates()— read-only preview; re-classifies the on-disk document fresh on every call, never a cached list.repair_stale_temp_repositories(paths)— the only mutating path, and the only place implicit or global deletion is refused: it takes the exact paths the user confirmed and re-validates every one of them against the classifier using the document as it stands on disk inside the same file lock as the write. If even one no longer classifies (reconnected, edited since the preview, or never stale to begin with), the entire request is rejected before anything is written — one versioned transactional delta, not a best-effort sweep. On success it writes an exact pre-repair backup torepositories.repair-backup-<UTC timestamp>.jsonin the config directory, then removes the validated rows fromrepos,repoOrder, every group’srepoOrder, and clearsactiveRepoPathif it pointed at a removed row — all insideConfigFile::update_with_strict’s file lock, then callsnotify_repositories_changed()likesave_repositories.
Why there is no separate restore-on-failure path: ConfigFile::write_atomic
(temp file + fsync + rename) already guarantees a failed write never partially
overwrites the live document — the original is simply untouched. The backup
file is therefore a human recovery artifact for undoing a repair that
succeeded but was unwanted, not a mechanism this code needs to invoke itself on
a write failure. Recorded as a deliberate design trade-off in story
763-d219’s worklog rather than layering a second, redundant recovery path on
top of a write that is already atomic.
Frontend: classified candidates are hidden from the sidebar’s normal repo
list (quarantined, never silently deleted) pending an explicit repair; see
repositoriesStore (refreshStaleTempCandidates/repairStaleTemp,
src/stores/repositories.ts) and the discoverable repair entry point — a red
flagged-repo icon with a count badge in the sidebar footer, opening
StaleTempRepairPopover (src/components/Sidebar/StaleTempRepairPopover.tsx),
next to the existing parked-repositories popover.
Prompt Library (prompt-library.json)
Type: PromptLibraryConfig
#![allow(unused)]
fn main() {
struct PromptEntry {
id: String,
label: String,
text: String,
pinned: bool,
}
}
Commands: load_prompt_library(), save_prompt_library(base, config)
Notes (notes.json)
Type: serde_json::Value with backend-owned keyed mutations. The legacy notes array and extra document fields remain compatible.
Commands: load_notes(), save_notes(base, config). Planner add_idea, list_ideas, and update_idea use the same ConfigFile strict locked writer. UI saves remove only ids present in their baseline and merge only changed fields of existing records; concurrent additions survive and deleted records are not resurrected. Other top-level fields retain merge-patch semantics. Invalid JSON fails rather than becoming an empty snapshot. Planner additions retain a source string and use the owning repository’s registered UI key as repoPath. Ideas reads and project mutations resolve filesystem-equivalent canonical paths, Windows extended/portable spellings and symlink aliases to that key. load_notes normalizes existing row paths in its response without rewriting the file. Paths with no matching registration remain unchanged; global Ideas stay global. Progress and story database project keys do not change. Successful mutation routes dual-emit ideas-changed; frontend reloads wait for queued local writes and never save a reload.
Keybindings (keybindings.json)
Wire type: array of typed {action: string, key: string | null} records. Null or an empty key disables an action. Rust validates unique bounded action IDs, bounded keys and modifier syntax. Any stable action string can round-trip, including unloaded plugin actions. Built-in action inventory is checked against keybindingDefaults.ts; dynamic choices explicitly report unavailable because plugin actions are frontend-registered and will bind in Step 9 UI parity.
The settings owner projects this array as /bindings/{action}/key, with stable-action create/remove operations. It preserves the file format. Both UI delta saves and settings transactions validate under the same ConfigFile lock before persistence.
Pane layout (pane-layout.json)
Rust validates the existing {root, groups, activeGroupId} document after merging each UI delta. Geometry uses leaf group IDs and horizontal/vertical branches. Maximum branch depth is 3; each branch has 2–20 children, matching positive ratios of at least 0.05 summing to 1. Duplicate or missing group references are rejected without writing.
The settings owner exposes /root as a structured bounded geometry value. Group IDs, tab membership, active tabs and active group are individually classified as runtime restoration state. They are not settings mutation paths; geometry edits preserve them and must reference the existing groups. No sidebar-click or drag/drop behavior changes.
Commands: load_keybindings(), save_keybindings(base, config)
Agents Config (agents.json)
The ego entry supports optional ego_mode (plan|default|edits|auto|yolo) and ego_sandbox (ro|workspace). Missing values add no flags. The shared Rust launch translator injects --mode and --sandbox for terminal and MCP launches (including run and resume), replacing corresponding raw overrides before --. Administrative subcommands (including mcp-server) and ACP are excluded. The prompt separator -- and its full suffix stay unchanged, even after a raw option without a value. An invalid saved ego choice is ignored for that field only; the valid sibling choice and other agents’ settings remain intact. These choices apply only to new launches and do not rewrite ego configuration.
agents.json stores launch_instructions: string as user additions at global and agent level. The composer emits enabled modules, global additions, then agent additions. Empty additions add nothing. launch_modules maps stable module IDs (markers, working_with_user, waiting, git_worktree, process_safety, children) to booleans; missing means enabled. Effective flags are global AND per-agent. launch_instructions_disabled suppresses modules and additions at either scope. launch_additions_migrated records the one-time conversion of legacy replacements: exact marker-default copies are removed, real custom text is retained, and empty replacements become explicit off. Migration runs inside the existing agents-file update lock. Root and child launch files are separate; only child files contain Children. See the user guide, “Launch Instructions”. When mdkb is on PATH or in a known install directory (stat-only check, cached per process, reset by write_files and by install_mdkb/uninstall_mdkb), launch_instructions::MDKB_RULE is emitted after the modules and before additions.
On Unix, the shared PATH shim consumes TUIC_CLAUDE_SETTINGS and adds Claude hook settings before instruction injection. Named commands, env prefixes and script wrappers use the same path; absolute-path manual commands bypass it. The variable is removed before agent exec so tool subprocesses do not inherit the implicit hook policy. Explicit settings, bare mode and administrative commands keep precedence.
Each agent entry may contain native_status_signals: boolean. For Claude and Codex, an absent value means true; false disables launch argument injection. hook_instrumentation controls only explicit global installation and remains off when absent.
Each agent entry may also contain prevent_alt_screen: boolean. An absent value means true. When true, TUIC uses a verified control where one exists: Claude’s environment variable, Codex and Grok’s --no-alt-screen, or OpenCode’s --mini. A false value suppresses TUIC’s screen control for that agent on new structured and shell launches. An agent without a verified control remains unaffected.
Claude, Codex and ego entries may contain skip_trust_dialog: boolean. An absent value means true. The setting applies only to MCP agent spawn: Codex receives a launch-only project trust override for the canonical working directory, including through custom launchers that forward arguments, while Claude’s first exact startup picker is answered through the managed PTY. An ego child receives --trust-workspace, which ego remembers for that workspace. A false value leaves the CLI’s normal trust question in place. TUICommander does not modify either CLI’s saved trust file.
Type: AgentsConfig
Per-agent run configurations (custom commands, arguments, model, environment variables).
Loading agents.json performs a locked, one-time Codex migration. A missing
Codex configuration gains an explicit default; an existing direct Codex default
(or the first configuration if none is marked default) gains
--dangerously-bypass-approvals-and-sandbox. Other configurations and wrapper
arguments are preserved. The codex-bypass-migrated stamp in the same config
directory prevents later loads from restoring a flag the user removed, even
after an older backend rewrites agents.json and drops unknown fields. The
codex_bypass_migrated field remains a serialization-compatible mirror. MCP launch composition
does not add that argument; the configuration owns the choice.
#![allow(unused)]
fn main() {
struct AgentRunConfig {
name: String,
command: String,
args: Vec<String>,
model: Option<String>, // MCP spawn default; the spawn parameter overrides it
env: HashMap<String, String>,
is_default: bool,
}
struct AgentSettings {
run_configs: Vec<AgentRunConfig>,
codex_bypass_migrated: bool, // one-time launch-argument migration
idle_close_minutes: u32, // default 15; 0 disables managed-child cleanup
prevent_alt_screen: Option<bool>, // absent = true
skip_trust_dialog: Option<bool>, // absent = true; MCP spawns only
}
struct AgentsConfig {
agents: HashMap<String, AgentSettings>,
}
}
Commands: load_agents_config(), save_agents_config(base, config)
The optional model field adds --model <value> when MCP agent spawn
selects the run config. A model passed on the spawn call overrides it. Existing
--model entries in args remain unchanged; they still conflict with an
explicit spawn model. Set the model in Settings > Agents when a run config needs
an overrideable default.
idle_close_minutes is per agent type. Only orchestrator-spawned children use it;
user-created terminals are never candidates. The idle window restarts on input,
output, mail, or agent-state changes. Unread mail, background work, a running
tuic bg job, a failed, uncertain or retrying background wake, and a per-session keep-open
mark prevent closure.
The latest background-wake status for each session is stored atomically at
<config_dir>/bg-wakes/<TUIC_SESSION>.json; a retrying, uncertain or failed status
keeps that managed child open.
This file belongs to a machine, not to the app. Every backend reads its own copy, and
the frontend keeps one per machine: a tab opened on a repository registered against a
remote connection launches with that connection’s agents.json, because the agent binary,
its paths and its config directory are on that box. Neither command carries a path or a
session, so the transport’s argument-driven routing cannot place them — the connection is
named explicitly (src/stores/agentConfigs.ts, agentConfigsFor / ensureAgentConfigs).
The cache is dropped on every connection status edge and refilled when the machine comes
up. set_agent_hook_instrumentation, set_agent_native_status_signals and the upstream
MCP config follow the same rule; install_agent_mcp, get_agent_config_path and the
upstream OAuth flow do not, having no HTTP route and nothing to open a browser with.
If a machine fails to load agents.json, its frontend store records the error and stays
unloaded so the next read can retry. The error names the connection and /config/agents
endpoint. Saves are refused until a load succeeds, preventing an empty fallback from
overwriting that machine’s config. A daemon that predates this route must be updated.
The families that stay local are the ones describing this app rather than a machine:
config.json, keybindings.json, the pane layout, the notification config and
repositories.json — the last definitionally so, since it is the list deciding which
repository maps to which machine.
The hands_free_listening boolean (default true; absent in older configs, which read as true) decides at arm time whether hands-free captures speech; false is a replies-only conversation. The hands_free_spoken_replies boolean defaults to true and persists on the server device. Turning it off cancels the current speech queue and keeps dictation armed.
Dictation Config (dictation-config.json)
Type: DictationConfig
Defined in the root src-tauri/src/config.rs and re-exported by the dictation command adapter. It is desktop-gated; the audio and speech domain lives in tuic-dictation.
| Field | Type | Default | Description |
|---|---|---|---|
enabled | bool | false | Dictation enabled |
hotkey | String | "F5" | Push-to-talk hotkey |
language | String | "auto" | Transcription language |
model | String | "large-v3-turbo" | Whisper model name |
auto_send | bool | true | Auto-submit after transcription |
Commands: get_dictation_config(), set_dictation_config(base, config)
Voice saves resolve legacy engine defaults on the latest locked document before applying the caller’s delta. This preserves an unchanged engine choice without clobbering another client’s explicit choice. Isolated speech-output agent-test instances force effective hands-free listening off even if the saved file enables it.
Config Defaults (read-only, no file)
Type: ConfigDefaults
Backs Settings “expert mode” (SPEC.md → Settings navigation): an expert
control compares its live value against the matching default here to decide
whether it is hidden (at default, basic mode) or shown (modified, or expert
mode on). Every field is that domain’s own Default::default() — the exact
value load_json_config falls back to when the file is missing — never a
second, hand-copied literal. A dedicated test
(config::tests::get_config_defaults_returns_each_domains_own_default) fails
if the command ever diverges from that source, and a second one
(assert_no_field_default_drift_except) fails if a struct’s own
#[serde(default = ...)] attributes drift from its impl Default — with a
documented exception list for fields that are deliberately asymmetric, e.g.
mcp_server_enabled (true for a brand-new install, false for an existing
config.json written before the field existed — see
app_config_serde_default_for_new_fields).
| Field | Type | Description |
|---|---|---|
app | AppConfig | AppConfig::default() |
notifications | NotificationConfig | NotificationConfig::default() |
agent_settings | AgentSettings | Default for one entry of AgentsConfig.agents — there is no single default for the map itself |
repo_defaults | RepoDefaultsConfig | RepoDefaultsConfig::default() — what a repo-defaults.json-less install loads |
agents | AgentsConfig | AgentsConfig::default() — AgentsConfig-level fields such as headless_agent and workflow_profile (run configuration name for workflow Agent steps) |
github_accounts | GitHubAccountRegistry | GitHubAccountRegistry::default() — { "accounts": [] }, the same shape as github_accounts.json; Settings shows the “Add another GitHub account” entry point in basic mode only when accounts exist |
launch_instructions | LaunchInstructionsDefaults | { default_text, required_markers, effective_text }: the composed global text, marker tokens recognized by TUIC, and per-agent effective text; {VER} is resolved to the running version |
dictation | DictationConfig | Desktop builds only — absent under --no-default-features (tuic-remote), where mod dictation does not compile and the route is not registered |
Fields marked skip_serializing_if = "Option::is_none" are omitted when
None (notifications.audio_device, agents.headless_agent, several
agent_settings fields). The payload keeps that attribute because it shapes
the config files; settingsExpert.ts reads a leaf missing from a present
object as the default null.
Command: get_config_defaults(preview?). HTTP: GET /config/defaults, or
POST /config/defaults with a read-only launch preview draft (see docs/api/http-api.md).
The launch_instructions section includes resolved default_text, required_markers
and an effective_text map keyed by agent. Settings sends its current agent edits
and local global marker flags for previews, so debounced saves do not leave the
preview behind. Remote previews use that machine’s saved global marker flags.
This request does not save config or rewrite launch files.
Cache Files
Claude Usage Cache (claude-usage-cache.json)
One app-owned watcher marks changed top-level JSONL transcripts dirty. Warm
refreshes enumerate membership but do not stat unchanged transcript history.
Specific-project scope resolves that project directly. A Modify(Any) event
for an existing directory does not mark unchanged transcripts dirty. File events
still update individual transcripts; directory creation/removal/rename and missing
directory paths retain full reconciliation. Refreshes share one scan gate;
watcher errors and overflow force reconciliation. A full metadata check
also runs after 30 minutes, or on every refresh if watching is unavailable.
Watcher delivery is asynchronous, so edits become visible after their event
arrives. The persisted parse-cache format does not change.
Module: src-tauri/src/claude_usage.rs
Persistent cache for incremental JSONL parsing of Claude session transcripts. Stored in the config directory. The cache maps project_slug -> (filename -> CachedFileStats) and tracks per-file byte offsets so only newly appended data is parsed on subsequent scans.
This is an internal cache file, not user-editable. It is automatically pruned when projects or session files are deleted.
The separate Anthropic rate-limit API cache is in memory only. Its responses and rate-limit backoff are keyed by the Claude session’s credential profile directory, so switching CLAUDE_CONFIG_DIR cannot reuse another account’s quota.
Repo-Local Config (.tuic.json)
Module: src-tauri/src/config.rs
A .tuic.json file in the repository root provides team-shareable settings. It is read-only from the app — teams edit it directly in their repo and commit it.
The Design Mode dev_server_url is deliberately absent from this format: a committed repository file cannot choose the browser destination on another user’s machine. Set it in the repository’s Scripts tab instead.
Precedence chain: .tuic.json > per-repo app settings (repo-settings.json) > global defaults (repo-defaults.json)
Type: RepoLocalConfig (all fields Option<T>, missing fields fall through to lower tiers)
| Field | Type | Description |
|---|---|---|
ego_profile | String | Ego profile for new ACP sessions in this workspace; bounded by the explicit machine ego_profile. Ego returns clamp warnings. Missing machine selection refuses the repo selection. |
base_branch | String | Base branch for worktrees |
copy_ignored_files | bool | Copy .gitignored files to worktree |
copy_untracked_files | bool | Copy untracked files to worktree |
setup_script | String | Script to run after worktree creation |
run_script | String | Default run command |
archive_script | String | Script to run before archive/delete |
worktree_storage | WorktreeStorage | Storage strategy (sibling/app-dir/inside-repo) |
delete_branch_on_remove | bool | Delete branch when removing worktree |
auto_archive_merged | bool | Auto-archive merged worktrees |
orphan_cleanup | OrphanCleanup | Orphan worktree handling |
pr_merge_strategy | MergeStrategy | PR merge method preference |
after_merge | WorktreeAfterMerge | Post-merge worktree action |
auto_delete_on_pr_close | AutoDeleteOnPrClose | Auto-delete on PR close |
Command: load_repo_local_config(repo_path) — returns RepoLocalConfig or null if file is missing or malformed.
Progress Storage (progress.sqlite3)
Module: src-tauri/src/progress/ (store.rs, ownership.rs, model.rs,
service.rs, flow.rs)
One append-only journal in one database, <config dir>/progress.sqlite3, with
project and nullable pty_id columns. Existing databases gain pty_id on
open; old rows keep NULL because their PTY cannot be reconstructed. A
project-wide query includes every PTY and the unattributed rows; a PTY query
selects one source. Nothing is written inside a repository — no .tuic
directory, no .git/info/exclude registration, no export lock, and so nothing
for the repository watcher or the content index to ignore.
Separate pty_views and project_views tables keep last-visit marks for each
PTY and the repository aggregate.
repo_watcher.rs asserts that: it snapshots the repository tree byte-for-byte
around a record/delete/mark-viewed cycle and requires it unchanged.
The optional list input progressOnly restricts the SQL kind predicate to intent, done and blocked before COUNT and LIMIT. It defaults to false, intersects with PTY/blocked filters, and leaves the journal and Flow unchanged.
Five entry kinds. done and blocked are reported by agents through the MCP
progress tool, the HTTP routes or the Tauri commands. intent is written by
TUIC from the agent’s intent: marker. delegated and message are written by
TUIC at agent action=spawn and agent action=send, with nullable
target_pty_id and target_name columns naming the other terminal. All three
host-written kinds are refused on every reporting path — they are observed, not
claimed.
Every journal insert redacts secret-shaped text and step fields before SQLite
stores them. Agent and target display names are also redacted and capped at 80
characters. Reads therefore return the stored redacted values in both the list
and Flow view.
A journal created before the hand-off kinds has a CHECK constraint that
refuses them. SQLite cannot alter a CHECK, so opening such a database copies
entries into a new table in one IMMEDIATE transaction. Ids are copied as
they are, and the high-water mark is carried over so a deleted newest id is
never issued again. The mark is the larger of the sqlite_sequence value and
the highest id present: the earliest journals used a bare INTEGER PRIMARY KEY
and have no sqlite_sequence table at all.
list skips a row whose kind this build does not know, with one warning,
instead of failing the whole read: debug and release builds share this file, so
a newer build’s kind must not blank an older build’s list. The repeated-intent:
check ignores delegated and message rows, so a hand-off between two
repaints of the same intent does not record it twice.
A terminal’s project is its cwd’s registered repository or, for a managed worktree outside the repository root, its registered workspace, which then resolves to the parent project.
Ownership resolution starts from an authoritative registered project and follows
recorded linked and nested workspace parent records, so a worktree’s entries land
in its parent project’s journal. It never uses the focused UI repository or a
bare CWD; unbound callers fail with project_required.
When parentRepoPath is absent or null, a linked-worktree registration’s Git common
directory identifies the main checkout as the inferred owner. Other registrations,
including absorbed submodules, keep their checkout path as the owner. Registering a linked
checkout separately can duplicate the shared workspace inventory without creating
an ownership cycle. Explicit parent paths still take precedence, and real parent
cycles fail with project_unavailable.
The schema is one entries table (rowid identity, ordering and cursor in one,
AUTOINCREMENT so a deleted id is never handed out again) plus a project_views
table holding the per-project last-visit timestamp. There is no revision, no
sequence, no collection state and no correction history: an entry is appended
once and either kept or deleted. list returns the newest 500 entries for one
project, newest first.
Each operation opens a fresh SQLite connection in WAL mode with a five-second busy timeout, leaving SQLite locking as the cross-thread and cross-process serialization boundary.
Collection is gated by progress_tracking: the global AppConfig flag ANDed
with the per-agent AgentSettings override, which defaults to on. Global off
also removes the progress tool from every agent’s tool list; a per-agent off
answers progress_tracking_disabled instead, because the tool index is built
once and has no session context.
Native Story Storage (stories.sqlite3)
Module: src-tauri/src/stories/ (model.rs, store.rs, store/records.rs,
store/transitions.rs)
Native plans and stories use <config dir>/stories.sqlite3 on the machine that
owns the project. The plan row links a project path to a source document; its
prose remains in that document. Story rows contain criteria, checked state,
dependencies, priority, origin, declared file scope, status, revision and an
optional manual session claim. No story database files are written to a
repository, and there is no import or export path.
Each story action opens one SQLite connection in WAL mode with a five-second busy
timeout and reuses it for the action’s reads and transaction. Schema setup runs
once at open. New databases are created at SQLite PRAGMA user_version = 1.
Version 0 is upgraded in place because its schema is compatible with version 1;
a database with a newer version is rejected rather than opened with an unknown
schema. Mutations use an immediate transaction and an expected story revision.
Dependency cycles, cross-plan dependencies and concurrent claims are rejected.
A story becomes ready when all dependencies are done. Plan state is derived from
stored story statuses rather than stored separately or decoded a second time
after a story list. A manual claim is released when its
terminal closes.
Workflow Definition Storage (workflows.sqlite3)
Module: src-tauri/src/workflows/ (definition.rs, store.rs, api.rs)
Project-scoped workflow drafts and immutable published revisions use <config dir>/workflows.sqlite3 on the owning machine. Draft edits use an expected revision. Publication validates graph structure and pinned story-template references in an immediate SQLite transaction. The two built-in templates are seeded atomically once per project. This database holds definitions only; run events and attempts belong to the workflow runtime.
Workflow Run Storage (workflow_runs.sqlite3)
Module: src-tauri/src/workflows/run/
Plan runs, their sequenced event history, idempotent command receipts, node attempts, story executions, and external effect intents use <config dir>/workflow_runs.sqlite3 on the owning machine. WAL and immediate write transactions keep each event and its projections together. The database is independent of terminal sessions and draft definitions; active runs pin published definition revisions.
Additional Commands
| Command | Module | Description |
|---|---|---|
hash_password(password) | lib.rs | Bcrypt hash for remote access authentication |
list_markdown_files(path) | lib.rs | List .md files in a directory |
read_file(path, file) | lib.rs | Read a file’s contents |
get_mcp_status() | lib.rs | Get MCP server status (enabled, port, connected clients) |
clear_caches() | lib.rs | Clear in-memory caches |
get_local_ip() | lib.rs | Get primary local IP address |
get_local_ips() | lib.rs | List all local network interfaces |
get_claude_usage_api() | claude_usage.rs | Fetch rate-limit usage from Anthropic OAuth API |
get_claude_usage_timeline(scope, days?) | claude_usage.rs | Get hourly token usage timeline from session transcripts |
get_claude_session_stats(scope) | claude_usage.rs | Scan JSONL transcripts for aggregated token/session stats |
get_claude_project_list() | claude_usage.rs | List Claude project slugs with session counts |
fetch_plugin_registry() | registry.rs | Fetch remote plugin registry index |
Workflow recovery boundaries
Runtime reconciliation refreshes integrated dependency projections without interrupting live attempts or marking their in-flight effects uncertain. The first workflow store open after a process restart uses a separate recovery path that interrupts old attempts and marks intended effects uncertain. A failed run is logged so other runs can recover, and its identifier remains pending for recovery on a later open or runtime reconciliation. Only runs captured at the first open are eligible for restart recovery; new live runs are never swept into retries. Startup dependency refresh still invokes Git; moving those probes outside write transactions requires the freshness contract tracked in story 959-c69c.
Telegram setup files
Telegram Settings uses ~/.config/tuic-telegram/: bot.token, allowed_chat_ids (positive private-chat IDs, one per line), and config.json (enabled, bot_alias). TUIC creates the directory as 0700 and files as 0600 on Unix, refuses secret-file symlinks, and atomically replaces files. A separate setup.lock serializes cross-process setup and pairing writes. No token is serialized by the read API.
The runtime keeps an opt-in snapshot and refreshes it on configuration or allowlist file events. Both configuration watchers also accept pathless lost-event rescan notifications before filtering access events or file names. Idle checks do not reopen those files. Setup and token changes use a nonrecursive file watcher instead of a one-second metadata poll. Actual send and delivery authorization still reads the current allowlist; a cached runtime opt-in is not an authorization grant. If a setup watcher cannot start, the adapter logs an error and waits for an explicit Settings change instead of polling.
pairing.json holds the one-use six-character code and its absolute ten-minute expiry under the same private permissions, so desktop setup and daemon polling share the authorization credential. A valid private-chat update consumes it; a wrong/expired code or /start grants nothing. An explicitly empty allowlist permits polling for pairing, but no outbound sends. A missing or malformed allowlist still fails closed. Enable/target/token changes restart the single daemon adapter; desktop never polls. Status keeps only connectivity, an error category and the last accepted message timestamp.
status.json shares safe daemon connectivity/error/timestamps with desktop Settings on the same host. A connection record older than one minute is shown as disconnected. The file contains no token or message text.
Per-conversation AI Chat launch authority
ai_chat_launches maps ego session ids to { executable, profile, workspace, peerId } objects (camelCase). Creation snapshots the selected overrides and defaults; reopen uses that saved object, including the peer identity. Writes use the locked configuration delta path. The global ego_executable, ego_profile, and ai_chat_workspace settings are unchanged.
Repository records may contain backend-authored declaredWorktrees, keyed by
the stable TUIC_SESSION. Values contain workspaceId, branch and
worktreePath. Caller-bound MCP declarations update this map through the
repository delta under the existing cross-process lock. Frontend saves retain
it. Existing saved terminal records are moved to the declared workspace without
changing their actual shell cwd. The association survives backend restart; it
does not turn an externally created worktree into a disposable PTY-owned one.
New workspace rows can omit savedTerminals until the first terminal snapshot.
Declaration leaves absent restore lists untouched while scanning; it creates an
array on the target only when moving a saved caller record.
Automation Definitions
The Rust definition store (automations/definitions.rs) uses the selected
instance’s automations.json. This is the storage foundation for the
Automations scheduler plan; scheduler
execution and public commands are not available in this step.
The version-1 document contains version, max_concurrent_runs (default 2)
and a definitions array (default empty). Missing files return these defaults
without creating a JSON document. Reading can create its directory and .lock
file. Edits use ConfigFile<T>::update_preserving_invalid: load fresh state under the
in-process and cross-process locks, mutate one id or the global limit, and
atomically persist. No-op edits do not rewrite the document.
Each definition stores:
| Field | Meaning |
|---|---|
id, name, prompt | Stable id, display name and literal agent prompt |
run_config, repository | Agent run-config name and repository workspace |
workspace | { "mode": "existing" } or { "mode": "new_per_run", "base_branch": "main" } |
cron, timezone | Five-field schedule text (empty for Once) and the per-automation IANA zone |
once_local | Optional ISO local date-time, for example 2099-10-09T10:00:00; mutually exclusive with nonempty cron |
enabled | Whether scheduled admission is enabled |
grace_secs, max_duration_secs | Positive grace and execution bounds in seconds |
overlap | "skip"; session reuse and queued overlap are unsupported |
precheck | Optional { "command": "...", "timeout_secs": 30 } |
Required strings must not be blank. Limits must be positive. Duplicate ids, identity changes, missing edit/delete targets and unsupported schema versions return errors before writing. Unknown fields, malformed JSON and semantic errors abort reads and edits without moving or replacing the live document. External editors do not take TUIC’s locks: a truncate/write save can expose incomplete JSON. Leaving its inode at the live path lets that save finish normally; a later normal read sees the completed document. No retry or cached default hides an invalid file. No independent unattended-permission flag exists: the run config owns permissions.
automations/schedule.rs validates exactly five Vixie fields, with day-of-month
and day-of-week OR semantics when both day fields are restricted. If either day
field starts with * (including */2), both day fields must match. An explicit
range such as 1-31/2 remains restricted. Seconds, years, shorthand macros and Quartz
extensions are rejected. Named months/weekdays, ranges, lists and steps are
supported. Patterns with no possible calendar occurrence return a bounded error;
croner 4.0.1 limits its search iterations and years (through year 5000).
At creation an omitted (empty internal) timezone is resolved with the operating system’s local IANA zone and persisted. Failure to discover a supported zone is an error, with no UTC fallback. Loads and edits require a valid stored zone; they never reinterpret missing zones using the current host. Schedule evaluation uses chrono-tz 0.10.4 and the stored zone. Next occurrences are strictly after the supplied UTC instant; latest-due occurrences include that instant and must be strictly after an optional scheduled cursor.
Fixed single wall-clock times skip spring gaps and run once, at the earlier fall-fold instant. Hourly/wildcard intervals retain both real fold occurrences. The wrapper filters croner’s shifted gap results rather than dispatching them. Backend hourly, daily, weekday and weekly presets validate their controls and produce cron text; custom cron uses the same validator. Preview returns 1–20 UTC occurrences with the cron and zone. These are Rust core functions; public HTTP/IPC commands arrive in plan Step 8. This core does not dispatch agents.
Once resolves its stored local date-time in the stored zone. Creation rejects instants at or before now and nonexistent spring-gap times. An ambiguous fold resolves to the earlier UTC instant. Loads retain elapsed Once definitions. The Rust schedule wrapper returns the sole instant before consumption, then no next/latest-due occurrence after the scheduled cursor reaches it. Preview returns at most that one future instant. A consumed Once definition is completed, remains stored, and can still be inspected; manual runs do not consume its schedule. Ledger reservation and the scheduler’s durable occurrence cursor prevent replay on restart and catch-up. Public views use this backend state in plan Step 8.
Automation run ledger
automations/store.rs stores execution history in the selected instance’s
automation_runs.sqlite3 (schema version 1). WAL and a five-second busy timeout
serialize reservations. A unique index on automation ID and UTC occurrence
prevents duplicate scheduled reservations; manual runs get separate UUIDs.
History stores a definition snapshot and survives definition deletion.
The runtime must acquire RunOwner before dispatch. Its adjacent .owner.lock
file stays on disk so every process locks the same inode. Reader handles cannot
reserve or mutate runs. Ownership acquisition interrupts all open records in one
transaction without retrying them. Reserved, prechecking, running and needs-you
are open; completed, failed, unknown, timed-out, interrupted and each skip reason
are final. The first final transition is immutable. Opening history does not
interrupt a live runtime. Unsupported schema versions fail closed.
Saved stdout, stderr and both precheck streams each retain at most 256 KiB at a UTF-8 boundary with a truncation flag. History is paginated newest first. Summary windows are elapsed UTC 24 hours and seven days, based on reservation time. Retention defaults to 90 days after finalization and never removes open records. Notification attempts are deduplicated by run, transition and channel and settle as confirmed or unknown independently of execution. Boot marks outstanding attempts unknown; it does not replay them. Saved output remains the canonical report. Scheduler boot is wired on desktop and headless hosts. Public execution transports remain pending; the existing MCP tool manages definitions only.
Precheck execution foundation
automations/precheck.rs runs a configured precheck in the dispatcher’s resolved
workspace through the same clean, non-interactive shell/environment policy as
Smart Prompts (sh -c, or cmd /D /S /C on Windows). Only exit code 0 admits
agent dispatch; nonzero exits, signals, timeouts and execution errors require
skipped_precheck. Spawn errors remain distinct from exit failures.
Each stream is drained independently and retained up to 256 KiB, with truncation
flags and elapsed milliseconds. The configured timeout starts after process
setup. Teardown kills the owned process group (Unix) or job (Windows), including
pipe-owning descendants; capture cleanup has a separate two-second bound and
reports incomplete capture as an error. Manual Run Now returns a persistable
bypassed outcome without spawning; no configured precheck returns
not_configured. Precheck output does not modify the prompt.
The shared automation runtime acquires the ledger owner lock on both desktop and headless boot. It reconciles open runs as interrupted without retrying, then admits only Once schedules on a 30-second tick. Recurring cron definitions remain stored but are not dispatched in phase 1.
Dispatch atomically claims a reservation before workspace or agent effects, then checks the definition again before the precheck and before launch. Deleted, paused scheduled runs and changed definitions fail without launching. Manual runs can use paused definitions and share the same overlap/concurrency limits. Existing mode uses the repository; new-per-run mode uses the shared workspace creator with the configured base branch, preserving workflow defaults.
The ledger saves precheck_outcome as not_configured, bypassed, or
executed with termination, capped stdout/stderr, truncation and duration.
Failed checks finalize as skipped_precheck without an agent. Successful checks
retain their evidence before launch; their stdout never changes the literal
prompt. The configured saved agent profile must exist; dispatch does not fall
back to another CLI. Workspace path/id and task/session ids are saved after
their effects, and errors finalize as failed. A child whose binding cannot be
saved is stopped through the managed session API. Completion and maximum-duration
handling remain a separate integration step; idle is not treated as success.
Automation definitions may contain created_by_session, the host-issued identity
of their creating agent. Older definitions omit it. Shared definition actions
ignore client-supplied creator provenance on creation and preserve the original
value on update. Pause and resume change only enabled under the definition lock.
Automation transport ownership
HTTP /automations/action and IPC automation_action use the instance-scoped
automations.json and automation_runs.sqlite3 through one Rust API. Per-id
create/update/delete and enabled-only updates use the existing definition lock;
run snapshots remain immutable across later edits and definition deletion.
A reader can inspect history without owning execution. Run Now requires this
process’s already-acquired runtime owner and never acquires a second owner or
forwards execution. The global concurrency default remains two. Summaries use
elapsed UTC 24h/7d windows; previews and next-run values use stored IANA zones
and the durable scheduled cursor. No new configuration setting is required.
Automation completion and deadlines
Runs persist their reservation deadline and dispatch start in the ledger. The
30-second runtime wake and PTY/progress events reconcile task, session and durable
progress records, including after broadcast lag. Idle alone leaves a run active;
reported completion or a known zero process exit confirms success. Failed tasks
and nonzero exits fail the run; missing or unverifiable completion becomes
unknown. A task completion with no known exit code does not prove success.
needs_you stays open and counts toward overlap, capacity and maximum duration.
The deadline includes dispatch and precheck time. Expiry stops only the session
bound to that run. Final output is bounded to 256 KiB; final states reject late
or duplicate evidence. Boot preserves final history and interrupts open runs
without retry. automation-run-changed is dual-emitted to desktop and SSE with
an identical { "run": ... } payload, including failure and needs-you transitions.
Rust settings catalogue foundation
settings::native::native_catalogue() derives descriptors from the native persisted
Rust types using schemars. Field-local x-setting annotations declare sensitivity,
apply timing, effects, operations and confirmation class. Traversal includes unset
optional fields and keyed record templates; missing metadata is an error. Each
non-setting runtime or migration field has an individual x-not-setting reason.
Secret and derived-secret descriptors contain no defaults or examples. The catalogue
performs no disk, credential, CLI or network reads. Voice definitions remain present
with unavailable status in builds without native dictation.
The checked-in src/generated/settingsCatalogue.ts is generated by the
settings::catalogue::tests::generated_typescript_matches_native_catalogue test with
TUIC_UPDATE_SETTINGS_CATALOGUE=1. Without that variable, the test rejects drift.
MCP settings, IPC settings_action and POST /settings/action share these definitions
and typed owner services. Existing UI-specific configuration routes remain available.
src-tauri/src/settings/inventory-gaps.json records untyped, external-owner,
credential and dynamic-choice gaps by store, pointer and assigned implementation
step. Inline schema gaps also join that ledger at registration. Tunnel forwards
are one atomic list setting at /profiles/{id}/forwards: get reads the list and
set replaces it completely. Each item must match ForwardSpec and pass the
existing profile validator. No record IDs or numeric-index edits are exposed;
the persisted tunnel TOML format is unchanged.
An ownerless gap fails registration. Catalogue::require_complete_inventory()
rejects every open gap before settings transactions or typed workflows.
Owner adapters must resolve their entries rather than reclassifying settings as
runtime exclusions. Plugin schema registration must also fail closed.
Internal settings transactions
Host policy and one-use approval (#1786-9cbd)
The shared service and registry accept a server-issued policy::Caller separately
from request JSON. Remote MCP mutations are refused; local MCP still requires the
tool to be enabled. HTTP retains local-or-authenticated access, and native IPC
retains OS-user trust. A peer registration grants no settings authority.
Ordinary settings commit immediately. The host-owned policy requires approval, for
an agent-written change that adds authority (never for narrowing, disabling, lowering a
timeout or a no-op, nor for the owner’s own Settings window, Caller::owner_ui), for
remote listener/auth/TLS/relay settings, the trusted Ego executable, custom launch
executables/arguments/enablement, tunnel port/auto-connect, and upstream stdio
execution selection (command, arguments, environment, directory, transport and
enablement), and owner-added push providers (services.push.added_providers,
#2668-aa16). Other Push/VAPID settings, outbound HTTP destinations and local MCP
controls do not inherit confirmation from the broader catalogue annotations.
Owners validate a proposed patch without writing. A protected edit returns
confirmation_required and an opaque proposalId; ui confirm displays a
backend-built diff through the existing desktop/browser/mobile dialog. Secret
fields remain write-only and are omitted from previews, replies and bounded audit
records. A model-supplied confirmed flag is rejected by the request schema.
After the human approves, the caller resubmits the identical request with the proposal ID through the service’s approval parameter. The grant is bound to the instance, transport/connection, target, revision and request content, and is consumed once. Refusal, cancellation, disconnect and the proposal’s absolute 300-second deadline revoke it, including while an approved write is queued for the owner. Commit consumes and revalidates the grant and latest revision under the owner lock; no owner or proposal lock spans the human wait. Audit retains at most 256 identifier/outcome records; at most 128 proposals may be pending.
This is the internal policy foundation. Publishing the replacement settings MCP, HTTP and IPC entry points is a separate cutover; the legacy config tool has not been replaced by this step.
settings::service::Service executes typed get/set/reset/per-store patch requests
against registered owner adapters. The request enum and operation enums reject
unknown fields; settings::request::request_schema() derives their action schema.
Requests explicitly identify the target and registered store. This foundation has
no IPC, HTTP or MCP registration yet; caller policy and the transport cutover are
separate work.
JSON pointers decode once. Leaves resolve against catalogue schemas, including unset optional fields and dynamic map keys. Record arrays use their declared stable key, never an array index. Batches have at most 128 operations and 256 KiB of operation JSON; duplicate operation identities are rejected. Types, enum values, numeric bounds and complete records are checked before the owner writes anything. Secret leaf replacement through ordinary set/reset is unavailable; credential actions belong to their owner adapters. Reads return secret presence only at this internal boundary; this does not select either pending reveal policy.
Every write requires the revision from an authoritative read. The owner compares it to the latest state while holding its existing process and file locks, then performs one atomic commit. Revisions include secret changes through a private process-salted digest; tokens expire on process restart and contain no readable secret material. Cross-process writes invalidate the reader’s token. Adapters must compute the returned revision after typed defaults/normalization so immediate readback agrees. Unrelated fields survive, and malformed files are never replaced by defaults.
The notifications, preferences, repositories, repository-defaults, repository-local, agents and voice adapters share
settings::config_file::ConfigFileStore for strict reads and locked commits.
Adapters supply normalization before canonical comparison and retain their own
runtime apply hooks. Upstreams and remote connections retain commit-specific
validation and pending effect records; app, Telegram and tunnels retain their
different persistence owners.
The repository-defaults adapter owns repo-defaults.json. One repository-local
owner serves all Target::Repository { id } requests through Store::resolve.
The id must be an existing repositories.json key naming a repository root;
requests cannot choose a filename. Resolution, reads and commits run off the async
executor, and apply uses the same request-scoped owner. Fixed-target adapters keep
the default exact-target check. Local patches preserve unknown team-owned keys,
reject symlinked data/lock files, and share the export writer’s file lock. Corrupt
local files block the operation and are preserved as recovery backups. repositories_registration remains an accepted inventory
gap: runtime identities and owner delta-save rules need a typed schema before cutover.
The AppConfig adapter retains vault rollback, cache updates, reflow, relay notices,
tool-list notices and listener restart requests. Runtime effects run after file
locks are released. Replies distinguish persisted data from applied effects;
scheduled desktop listener restarts remain applied:false pending readback, and a
headless listener change reports persisted-but-unavailable application instead of
claiming a live rebind. Username and password-hash edits do not require a listener
restart: Basic Auth and the login endpoint read the committed config on each
request, and credential changes invalidate cached authentication failures. These
credential-only commits report applied:true in desktop and headless builds.
Effect failure returns apply_failed, persisted:true and
recovery guidance; retrying the old mutation conflicts. Failed persistence updates
neither the cache nor effect subscribers. The later refresh step owns publication
of settings-changed events.
The legacy 24-hour session-duration migration persists the internal
session_duration_migrated marker once, including for other existing durations.
New saves mark the document current, so an explicit 86400-second duration survives
both transaction readback and ordinary config loads. The marker is excluded from
settings controls and cannot be edited through the catalogue.
Validation errors include schema-derived expected and allowed hints, never
rejected input values. Persisted effect failures return nextAction:"get" and the
committed revision: reread the affected paths rather than replaying the mutation.
Core provider accounts
accounts.json stores provider/site/account metadata only. The first read migrates github_accounts.json while preserving IDs; the old file is retained for recovery and a durable marker prevents re-import after removals. github_bindings.json remains the GitHub binding store. Tokens migrate atomically within the credential vault to account/{id}; env/CLI credentials remain ambient. Unknown registry, site and account fields are ignored so mixed-version builds can still load every account. Corrupt metadata is retained and blocks account writes. See Shared account registry for APIs, credential presence and partial cross-store recovery.
The internal GitHub settings adapter delegates account and credential mutations
to the shared account owner. It does not use ConfigFileStore to bypass account
verification or vault rules. Binding revisions are checked inside the GitHub
owner’s strict file update; account reads expose presence and runtime provenance.
See GitHub settings owner adapter.
Ego launch defaults through settings (#1775-330c)
ego_executable, ego_profile and ai_chat_workspace are app store fields owned
by AppSettingsStore; no separate launch adapter exists. Changes apply to later
ACP or PTY launches. Ego-owned defaults use the separate ego profile store and
the configured CLI; no Ego configuration files are edited. Machine targets select
the base user document, while profile targets must match the configured launch
profile. Managed model, roots, network and exec_paths patches use config snapshot
and config batch --if-revision; atomicity covers only that owner document.
Base-only auth headers and credential commands use typed write-only actions and
the same owner CAS. Owner-redacted values are never written back as secrets.
Capability inspection fails closed for older owners without conditional batches.
Repository start-work brief
Place .tuic-start-work.md in the repository root, next to .tuic.json. This
keeps the shared brief with the existing team configuration without embedding
Markdown in JSON. Tasks reads it for each Start work action through the backend’s
repo-contained, size-limited UTF-8 file reader.
Use {{key}}, {{url}} and {{title}}. Substitution runs once; unknown tokens
remain literal and a missing URL becomes empty text. Item controls are stripped
before substitution (TAB and LF remain). Without the file, the brief remains
key: title, a blank line and the item body. Invalid or inaccessible templates
fail the action. Delivery still caps the brief at 12,000 characters and encloses
it in the untrusted-content wrapper.
Repository child contract
Place .tuic-child-contract.md in the working directory of an orchestrating
agent, normally its repository root. Every managed child that agent spawns
receives the rendered file under ## Child Contract, before its task. The
reader and {{token}} rules are those of the start-work brief above. See
MCP & HTTP Server for the tokens.
One-time beta update-channel enrollment
On beta builds, loading an older config.json without the internal
beta_channel_migrated marker changes a saved stable channel to beta.
The existing locked load/save path persists the marker in that same file,
including when the saved channel is already beta or nightly. Later explicit
choices, including stable, survive restarts. Stable and nightly builds do not
run this migration. Fresh configs already carry the marker. It is not a setting
and cannot be edited through the settings catalogue.
Background window visibility
background.hide_dock_icon defaults to true. On macOS, background entry uses
Accessory activation policy when enabled; Show restores Regular policy. The
General page exposes this setting on macOS only. Other platforms retain the
field without changing their taskbar or launcher policy.
Background entry requests a persisted terminal snapshot from the main WebView
and waits up to two seconds for ack_background_snapshot. Failure or timeout is
logged and does not prevent hiding. Main, floating and visible panel windows
are hidden; Show restores only the panels that were visible before entry.
Desktop terminal visibility is saved separately from remote observations.
Every terminal WebSocket lane prevents standby for its session. An open SSE
event stream conservatively protects all sessions until that stream disconnects.
An observer that attaches after SIGSTOP wakes the terminal immediately.
Show restores the desktop visibility flags and wakes only terminals that become
visible; it does not resume every inactive tab.
MCP work-item writes
mcp_work_item_writes in config.json defaults to false, including when the field is absent in an older file. It permits only the repo work_item_act comment and transition operations. Reads need no opt-in. Use the existing configuration save surface to apply it live, or edit the file with the app stopped and restart. Supplying a flag in a work-item request cannot enable writes.
mcp_call_audit_enabled in config.json gates recording and display of the MCP call audit. Default true when built with debug assertions, false otherwise, including when the field is absent from an older file. Live: no restart.
mcp_usage_rollup_enabled in config.json gates the persistent daily MCP usage counts (#2808-5998). Default true in every build, including when the field is absent. Live: no restart. Data: mcp_usage.sqlite3, 90 days.
Background tray and menu-bar icon
background.tray_icon accepts always, background_only (default), and never. It applies live. Never restores a hidden desktop before removing the tray. Close configured as background minimizes when the tray is disabled, fails to build, or Linux has no registered StatusNotifier host. This keeps desktop session visibility intact. The Ask dialog omits Background when unavailable. Tray state and the first-entry notice are process-local, not persisted.
Background WebView unload
background.webview_unload_minutes defaults to 10 awake minutes; 0 keeps the hidden WebViews loaded. Changing it takes effect while hidden. Unload waits for a saved snapshot and defers during dictation or a close dialog. Rust PTYs, HTTP/MCP, Automations and remote terminal subscriptions continue. JavaScript plugins (including cache-keepalive, claude-wakeup and at-capacity-retry), sounds and updater checks pause until Show.
Show recreates the main window from Tauri configuration, restores window geometry through the window-state plugin and reconnects the saved tabs, split layout and live sessions created while unloaded. Suspended tabs remain suspended. The updater checks again when the frontend starts. Quit confirmation uses a native dialog while unloaded. ui MCP actions return {"error":"webview_unloaded"} immediately in that state. background-mode-changed is dual-emitted to desktop and SSE with {state:"hidden"|"unloaded"|"visible"}.
B0 measured WebContent exiting and about 1,090 MB released from a synthetic 1 GiB allocation on macOS. Actual TUIC workload savings, Windows and Linux are unmeasured. GPU and Networking processes may remain.
Rust-owned suspended tabs
suspended-sessions.json stores an object keyed by stable tuic_session, with agent type, cwd/worktree, agent session id, launch command, alias, pane slot, reason, name and shell. It uses the config directory (including instance isolation), strict loading, cross-process locking and atomic updates. A failed/corrupt write leaves the live PTY intact. Frontends restore these records independently of their tab snapshot; resume removes a record after PTY creation.
Plugin settings UI
Loaded plugins with registered settings appear under Settings > Integrations. Search includes their catalogue field labels. Unloading removes the page and search entries. Reads, revision-checked edits, resets and secret set/unset status use the scoped Rust settings service; the UI owns no second configuration store.
Settings owner cutover prerequisites (#1787-4778)
The owner gap ledger is empty. MCP settings replaces config without an alias.
The shared facade registers repository presentation, keybindings and pane geometry
owners and routes typed credential/workflow actions. A future gap blocks transactions
and workflows until its owner resolves it.
The connections settings owner retains each removed record until its apply phase.
Its removal callback receives that record, not only an id. Runtime teardown can
therefore stop an on-connect SSH daemon after connections.json no longer contains
its connection. Tunnel profile removal callbacks still receive profile ids.
The Ego owner registers without a configured executable. Each request resolves the
current launch profile and pins its executable, workspace and profile for that
operation. An unconfigured request is unavailable; changing launch configuration
allows subsequent requests without rebuilding the registry. The managed adapter
still excludes sandbox, mode, permissions.judge and exec.env.
GitHub account removal saves the removal of its repository bindings before deleting its credential and registry record. A bindings-save failure keeps the account and credential available for retry. A later account-removal failure can leave a valid, unbound account, but never a binding to an account that this operation deleted.
Automatic idle-agent hibernation
The backend checks unattended top-level agent tabs every five seconds. agents.hibernate_idle_minutes defaults to 60 awake minutes; zero disables the sweep. agents.hibernate_scope defaults to background_only; always also permits foreground hibernation. Both machine-owned controls are in Settings → Agents (Expert Mode).
Hibernation requires an idle agent and a verified resume session in its saved profile. Plain shells and agents without a verifiable resume session stay live. Unread peer mail, pending commands or background work, awaiting input, attached readers, keep-open tabs and open automation runs prevent hibernation. Managed children retain their separate idle-close policy. Sleep gaps longer than 30 seconds do not advance the idle clock.
The normal Rust suspension path persists reason: "idle_hibernate" before ending the PTY. Opening the tab, submitting input or sending peer mail uses the shared wake path. Storage or resume-verification failures leave the live session intact.
Tasks notice policy and per-item follow/comment baselines are JSON values in ui-prefs.json’s existing tasks_view_preferences map. Reserved keys are tasks:notification-policy and tasks:follow:<provider/account/item identity>. No new configuration file or provider polling is used. Missing policy means disabled. These are host UI preferences, not provider subscriptions.
MCP settings authority (#1787-4778)
settings_mcp_enabled defaults to false, independent of the legacy config tool state. Only trusted Settings UI enables it; it is excluded from the writable settings catalogue. It is the one switch for the MCP settings tool: settings is not a capability denial (#2655-a6d5). On load, a saved settings denial, or a document with no saved capability policy (the old default denied settings), turns the switch off and removes the denial; a save that writes a settings denial does the same. No legacy combination widens access. Diagnostics keeps its own denial and stays denied by default. App/owner adapters keep weak host references so the persistent facade cannot retain its AppState after shutdown.
Explicit settings choice discovery (#1908-c327)
The internal settings owner service accepts describe and refresh with an explicit target, store and 1–128 dynamic field paths. Describe reads cached choices only; it never enumerates hardware or refreshes a network catalogue. Refresh calls the registered owner. Each choice result includes its resolver, availability and values: null means unavailable, while [] means successful discovery with no options. Cache entries are scoped to the owner target and configuration revision. A failed refresh replaces stale success with unavailable status.
Notification output choices use the same bounded enumeration and {name, is_default} objects as the existing UI command. Discovery never saves notification configuration. This internal contract does not publish the later settings MCP/HTTP cutover.
Agent model settings support typed model edits without starting a CLI. Explicit
choice refresh probes only the addressed Claude run config with --help, using
its command and environment. Published aliases are suggestions, not account
entitlement or an exhaustive model list. Other CLIs and failed probes report
unavailable choices; typed edits remain supported. Describe never probes. Model
edits preserve sibling configs and the default selection and apply next session
(#1910-451e).
Telegram settings owner actions support write-only set_token/clear_token and stable positive add_chat/remove_chat IDs. Reads return token presence only. These actions use the existing private setup files and setup lock and never acquire the polling-owner lock. Token verification or final owner readback can fail after persistence: persisted:true requires owner readback before retry, including after a successful token clear or allowlist action.
Connection settings credential actions set/clear the password or pairing token for an existing immutable connection ID through the vault owner. Inputs are write-only; readback reports separate presence states, and vault read errors remain unavailable rather than unset. Failed writes leave the saved record and old credential reachable. A committed write followed by failed readback returns persisted:true; read presence before retrying. Successful writes invoke the runtime reconciliation callback without editing connection metadata.
App setting choices
Font families use the Rust-owned bundled-font option file shared with the UI; these are bundled woff2 families, not arbitrary host fonts. Themes reuse the Rust theme loader and retain custom theme IDs. IDE refresh reuses cross-platform installed-IDE discovery and returns the same value/label options used by the launcher. Catalogue construction and describe never run host probes. Explicit refresh runs discovery off the async executor and caches choices; unavailable discovery is distinct from a successful empty list. Font and IDE edits validate supported choices without launching a probe.
Voice settings choice owners (#1909-0d24)
The internal voice settings owner uses cache-only describe and explicit refresh for input devices, Whisper models, installed Pocket voices and Edge voices. Refresh reads the configured language through the strict voice file owner. Model options include installed/downloadable state; installed voice options retain their source. Input backend failure is unavailable, not a supported empty list. Edge refresh may fetch the service catalogue; describe never fetches or downloads.
VoiceAction provides typed assets, model download/delete, speech asset download/cancel/delete and voice import/delete. It delegates to the existing command owners and their allowlisted asset IDs, size validation and runtime locks. These are internal host methods for later transport publication, not an arbitrary command executor. Existing engine/language descriptors and runtime invalidation remain authoritative. Builds without dictation still describe unavailable voice fields.
The GitHub owner catalogue describes /accounts/{id}/credential as presence only
(set, unset, or unavailable). The snapshot retains secret.status for existing
consumers and adds the matching credential presence. Credential values are never
returned. Use the typed GitHub owner actions for cloud device login, enterprise
verification, rotation, clearing, and account removal; generic field writes do not
replace those owner operations.
The repositories_registration owner projects typed registered repository and group
settings from repositories.json. Locked edits preserve runtime workspace/tab restore
records, active selections, backend worktree placement, connection identity, and
unknown owner fields. Removing a registration never deletes a checkout or worktree.
Runtime fields have individual catalogue exclusions; presentation and ordering remain
settings. Reads include stored/effective values and source through the shared service.
The upstream credential owner describes auth/header presence separately from saved
references. Its input-only typed actions rotate bearer/header credentials, clear them,
or start the existing OAuth flow. Rotation replaces old OAuth material and cancels
pending flows for that upstream. Config and vault changes share the config owner lock;
a vault change followed by config/apply failure reports persisted: true with get
recovery. Bearer rotation validates the proposed config through the upstream owner
before writing the vault. An existing custom Authorization header conflicts with bearer
auth; rejection preserves the saved config and credentials. Only the changed enabled
upstream reconnects. No credential value is returned.
Settings change generations
The shared settings facade assigns a process-local monotonic generation after a durable transaction or owner workflow, including vault-only writes and persisted apply failures. It returns the generation in the receipt and dual-emits settings-changed with {section, generation, persisted, applied}. Existing AppConfig saves use the same publisher. The event contains no setting values, credential keys or secret-derived hashes. Owner CAS revisions retain their existing meaning; the generation is only an invalidation cursor and is not persisted.
Frontend readers subscribe once per window and reread their section through non-saving read/apply paths. They advance the acknowledged baseline together with the rendered state, retain dirty fields, report same-field conflicts, cancel obsolete queued writes and discard stale in-flight reads. Reconnect clears generation high-water marks and rereads active sections because a restarted process starts a new counter. Mirrored events retain their connection identity and cannot reload local-machine settings. Failed subscriptions and owner reads retry after one second, with exponential backoff capped at 30 seconds. Disposing a reader or disconnecting its owner cancels pending read retries. A failed subscription does not block initial owner reads. Repository refresh normalizes omitted optional keys before three-way adoption; a valid no-op field commit releases its draft. Desktop and HTTP connection/profile saves share state-bearing publication paths, including a persisted connection deletion whose credential cleanup fails. App-config no-op commits do not publish a generation.
Legacy desktop and HTTP save adapters for notifications, preferences, repository settings/defaults, prompts, agents, keybindings and pane layout use the same publisher without changing owner signatures. State-bearing registration, plugin and upstream save paths also publish. Legacy connection password writes, deployment pairing-token creation and deployment-mode updates also use state-bearing publication paths. Successful vault writes publish after persistence; an existing pairing token and a no-op deployment-mode update do not publish (#1989-22fe).
Managed launch journal
managed-launches.sqlite in the app data directory retains managed launch identities and request digests. It does not store prompt or environment bodies. Records remain as idempotency tombstones across process restarts; they do not imply the PTY survived. Use the same launch_id to inspect an old launch, never a new key to retry an uncertain creation.
Catalogue-backed Settings controls
Native Settings controls carry stable catalogue IDs. settingsCatalogue.ts is generated by the Rust catalogue test, not edited by hand. Shared selects consume Rust enum values; descriptor keys supply label/help lookup. The All settings inspector uses settings_action with explicit target, concrete JSON pointer and owner CAS revision. Each edit is one field, not a cross-store save. String arrays use typed rows; credentials and structured records retain domain workflows.
settingsControlExclusions.json records outside-catalogue controls. settingsCatalogueExclusions.json records per-ID read-only, derived, legacy and separately controlled fields. Source extraction checks both inventory directions, including platform/expert branches and finite sound rows. Runtime renderer tests check descriptor identities and callbacks. These checks do not establish live runtime convergence by themselves.
While a frontend keybinding sync lifetime is active, it publishes its current plugin action IDs through publish_plugin_keybinding_actions on settings_action. Registration, unload and reconnect update the process-local list; discovery combines it with built-ins. Before publication, choices are unavailable rather than falsely empty. Publishing does not save overrides or emit a durable settings change.
Startup owner boundaries
Settings startup workflows documents the published configuration/authentication boundary. App launch preferences select the configured Ego executable, profile and workspace; Ego owns its user/profile configuration. A GitHub environment, OAuth or PAT credential source is provenance, not a writable PAT field. A settings generation is not a CAS revision, and successful persistence is not proof that a runtime effect applied.
Settings startup publishes list_accounts for GitHub metadata/presence and Ego
begin_login/login_status. Ego login uses the configured executable/workspace
and base credential owner, never a caller-selected program or profile. Its
tracked terminal is human-operated; termination and handle expiry are not
credential success. See interactive login.
Persistent PR visibility filters
Global pr_hide_drafts, pr_hide_conflicting and pr_hide_ci_failing values
persist in config.json and default to false (show all). Each repository stores
nullable overrides in repo-settings.json: null inherits the current global
value, true hides the matching PRs, and false explicitly shows them. Settings
owner transactions preserve unrelated fields, and settings refresh adopts owner
readback without saving it again. The Rust settings catalogue describes both scopes.
Dictation correction Settings store
corrections is a machine-owned stable-key projection of TextCorrector’s
dictation-corrections.json map. /replacements has records {from,to}, keyed
by heard text, with revision-checked create, set and remove. The owner retains
the existing map serialization, strict file reads, advisory locking and atomic
replacement. Settings and the legacy map writers share that owner; successful
persistence precedes runtime adoption and value-free change publication. Builds
without native dictation publish unavailable descriptors rather than a second
file implementation. See dictation.
Legacy upstream settings invalidation
Legacy upstream credential save/delete uses the same state-bearing owner adapter for IPC and HTTP. It publishes only after the vault write succeeds. DCR metadata writes publish after strict config persistence. OAuth exchange, refresh and rejected-token cleanup carry weak host-scoped publication authority through the existing runtime owners; they do not retain AppState or use a global registry. A compound vault/config failure publishes an unapplied generation only after a vault write has persisted, including when subsequent config persistence fails and the owner attempts rollback. Hints carry only section, generation and persistence/apply flags, never credentials or credential-derived hashes.
Abandoned shells
Desktop sidebar session rows and mobile session cards mark a parentless plain shell as Abandoned after one idle hour and show its idle age. The five-second backend sweep requires a fresh OS process inventory: the PTY child must be an interactive shell with no child processes. An unknown inventory, script, foreground command, background child, detached TUIC job, managed identity, live child session, pending input or keep-open hold prevents closure. Unsupported or incomplete OS process observations fail closed.
Settings → Agents → Idle agent hibernation (Expert Mode) includes Close abandoned shells after (hours) (agents.abandoned_shell_hours). The machine-owned value defaults to 0 (off); whole hours from 1 to 65535 enable closure. Idle age is measured from the most recent input, output or semantic activity, including elapsed time while the machine sleeps. Closure rechecks the process inventory and activity at the destructive boundary, and uses the normal session close/tombstone path. The sweep can lag the threshold by one five-second tick. A remote daemon applies its own setting, not the desktop host’s value.
Native story ingest ledger
Schema v6 of stories.sqlite3 adds story_ingest, beside the app configuration,
not in a project. SQLite triggers update an independent revision, update time
and deletion tombstone in the same transaction as each story write or appended
note. Migration seeds existing stories and notes without changing their subject
revisions or documents. Post-commit wakes and a 30-second reconnect sweep feed
mdkb’s external.list, external.upsert and external.delete methods through
mdkb_client.rs. Only IDs in this instance’s ledger are owned. The projection
is optional and read-only; neither RPC failures nor daemon absence roll back
story mutations. No story mirror or new user configuration is created.
Archived worktree retention
archive_retention_days is a u32 in global repo defaults (default 0, Off), nullable in repository overrides and optional in .tuic.json. Explicit 0 overrides an enabled default. The backend resolves the same three-level precedence as the rendered settings. A positive value permits eligible archived checkout deletion during the existing repository refresh cleanup; it does not install a timer. See Worktrees for age and recovery rules.
Native notification bootstrap capability
The default desktop capability grants notification:allow-is-permission-granted
for the main, floating and panel windows. The notification plugin’s injected
initialization script probes this permission before application code runs.
Request-permission and notification-delivery grants do not authorize that probe.
Grok hook lifecycle coverage
The TUIC-owned Grok hooks register SessionStart, UserPromptSubmit, PreToolUse, permission_prompt Notification, PostToolUse, PostToolUseFailure, PermissionDenied, Stop, StopCancelled, StopFailure and SessionEnd. Installation and removal preserve sibling user hook files. Hooks run only with TUIC_SESSION and emit metadata to the terminal; no new application configuration keys are required.
The agent silence rule (every agent session; parent mail and nudge for managed PTYs only) reads TUIC_AGENT_STALL_MINUTES from the daemon environment (default 30 awake minutes; 0 disables). Detached CLI commands read TUIC_BG_TIMEOUT_SECONDS (default 3600; accepted range 1–86400) before launch. These environment settings do not change saved agent profiles.
Backend continuity and approval identity
A project without Wiz markers reports Plans and stories are stored in TUICommander. Create a plan to begin. This text names no internal tool. For a marked project, automatic detection retains native while native plans are open or pinned native executions are active. The header explains Native retained while …; this is not fallback after a failed Wiz connector. Expand backend details to choose Use TUIC native or Use automatic selection. Explicit Wiz cannot replace open native work, and selection changes cannot interrupt active executions. Registry scopes resolve local > project > user for the canonical owning project; remove duplicate winning-scope installations in the plugin manager if requested. Approval binds the displayed installation and entry/version identity. Dependencies are not fingerprinted. A changed entry/version between display and click requires refresh and a new approval. Active runs pin backend provenance in their existing snapshot: adapter identity, canonical approved installation and entry, and the approved entry/version generation. The Node runtime path is not part of this persistent identity, so a runtime path upgrade alone does not change the backend. Runtime trust checks still reject repository-owned Node executables; the process cache restarts when its command or runtime changes.
Active story runs admitted before pins existed resolve by the pre-pin rule: a legacy command binding, otherwise native. Overrides cannot be written while a run is active, so the current settings still answer it; an unpinned run on a project that has a backend override fails closed. Explicit cancellation remains available without reading the story backend. TUIC never cancels, restarts or reassigns runs automatically. No native or external records are migrated. Discovery overhead has not been measured; no cross-call discovery cache is used.
Worktree orphan cleanup and archive retention audit (story 2867-4336)
Audit of existing behaviour, 2026-11-07, against main 212ee260e4. Line numbers
refer to this branch. Read-only: no worktree was removed.
1. Inventory
Source: git worktree list --porcelain, the lock file under the common git dir,
git status --porcelain --untracked-files=all per checkout, and lsof -d cwd for
shells. TUIC’s HTTP routes need a session token and were not called; live agent
sessions are therefore from lsof, not from the session registry.
| Class | Count | Owner / proof |
|---|---|---|
| Linked, branch checked out | 6 | Branch name plus allocation marker; shells run in fix-2904-progress-track and test-2707-e2e-candidate |
Archived (__archived/) | 1 | feat-2539-chat-quote-reactions; dirty=1, so retention keeps it |
| Detached | 0 | — |
| Missing directory / prunable | 0 | — |
| Locked | 0 | — |
| Unregistered directory with shells | 0 now | lsof showed shell cwds in feat-tuic-w2, absent from git worktree list; the directory no longer exists on a re-check (a sibling session’s checkout was removed under live shells). Unknown ownership: cleanup never acts without a registration |
| Temporary (test) | 0 registered today | tuic_core::temp_paths::recognized_temp_roots (OS temp, /tmp, /var/folders, ~/Gits/.tmp) |
Name or age is never proof: detect_orphan_worktrees_blocking
(tuic-git/src/worktree.rs) decides by detached HEAD, location and branch
tips, not by name or mtime. A detached HEAD that still carries a non-default local
branch is not an orphan (non_default_local_branch_at_head).
2. Existing cleanup, retention, retry and restart behaviour
Orphan cleanup (orphanCleanup = off / ask / on)
- Scan:
assess_orphan_worktrees(:16555) lists detached checkouts outside temp roots whose directory exists. Missing directories are excluded (repair diagnostic, never swept). - Safe verdict
orphan_cleanup_safety(:16603): clean status incl. untracked and submodules, no skip-worktree / assume-unchanged, HEAD not the tip of a non-default local branch, HEAD reachable from a branch or remote ref. - App layer adds sessions:
orphan_cleanup_safety_with_sessions(src-tauri/src/worktree.rs:1748) rejects live and suspended tabs (live_sessions_in:228; unreadable suspended storage vetoes) and workflow run workspaces (guard_run_workspace_base). - Removal point
orphan_removal_guard(:1770) thenremove_orphan_worktree_internal(tuic-git:2769): refuses temp paths (refuse_temporary_orphan:16501), thenremove_worktree_internal_with_lock(:3014) re-checks main worktree, presence vs. confirmation, missing registration, unregistered directory without warm token, in-progress Git operation, detached HEAD without a durable ref, dirty files, submodule state, fingerprint, and a lock (single--forcenever overrides a lock). Every check runs again at removal, not only at assessment. - Frontend (
createRepositoryRefreshCoordinator.ts:651-808): safe orphans go without asking; unsafe ones go to the countdown dialog (ask) or only those with live sessions (on).
Retry and restart. There is no retry loop: each refresh tick reassesses from scratch, so the retry bound is one attempt per tick and the operation is idempotent (a removed checkout is simply absent next tick). Nothing about a pending removal is persisted. After restart the scan runs again and an unsafe orphan is asked about again; a safe one is removed again. This is safe: the verdict is recomputed from disk, not remembered.
Keep. Orphan Keep is session-scoped memory (keptOrphans, :655), bound to
dirty_fingerprint; it holds until the checkout changes, and is lost on restart
(the user is asked again; no data is touched without an answer). The backend
mirrors a Keep so other clients close their dialog (clear_orphan_cleanup_internal
:1937). Covered by orphanKeepFingerprintCritic.test.ts and
keeping_twice_stays_kept etc. (worktree.rs:2144).
Archive retention (archiveRetentionDays, 0 = off)
sweep_archived_worktrees (tuic-git:5439), run per refresh tick
(createRepositoryRefreshCoordinator.ts:495) through sweep_archive_retention_impl
(src-tauri/src/worktree.rs:640; the threshold comes from config, never the
caller). A candidate needs: registered, directly under __archived/, a recorded
tuic-archive.json at the canonical recorded path, allocation marker finished,
age past the threshold, no lock, no live session, no index flags, clean status
including ignored files, HEAD equal to the recorded tip, recovery ref still at the
tip. Removal is non-force, so Git re-checks dirt, locks and submodules at the
removal point. Retained archives return a reason (ArchiveRetentionReport.kept),
shown on the status line.
Retry and restart. The archive record and marker live in the git admin dir, so
they survive restart; ageing continues from archived_at. Each tick recomputes;
a refused removal is reported and tried again next tick (idempotent, no counter).
A legacy archive without a record is kept forever by design.
Recovery refs. preserve_archive_tip (:3856) writes refs/archive/<branch>
(or the flat fallback); retention never deletes refs or branches. Submodule refs
are preserved before removal (preserve_submodule_refs); a missing checkout’s
modules before its registration is dropped (preserve_missing_worktree_modules).
Archive-time dirty content is not snapshotted (DEFERRED 2026-10-29 in the sweep);
the archive keeps the whole directory and the sweep keeps any dirty archive, so
dirty content is retained, not copied.
Keep and retention. Keep (orphan dialog, and the PR-notification Keep of story
2895 in keptCheckouts.ts) governs whether TUIC acts on a checkout. A kept
checkout is never archived, so it is never a retention candidate; retention has no
Keep of its own and needs none.
Temporary test worktrees
Never orphan candidates (temporary_detached_worktrees_are_never_orphan_candidates) and never removable by cleanup, automatic or
confirmed (src-tauri/src/worktree.rs:3628). They stay registered until the
creator (a test teardown) removes them: TUIC cannot prove who owns a temp
checkout, and age or name is not proof. Missing temp checkouts keep their
registration for the same reason. Specified follow-up, not built: creators remove
their own worktree; a generic prune of temp registrations needs an ownership
record that does not exist today.
3. No-data-loss invariant
Before no-force removal of any orphan or archive, the removal point revalidates: exact checkout (registered path, canonical path equals record), tip and base (HEAD vs recorded tip; detached HEAD has a durable ref), dirty / untracked / submodule state and fingerprint, index-flagged hidden edits, sessions (live and suspended), locks, and an in-progress Git operation. Unknown ownership retains: no registration without a warm token, no readable archive record, unreadable suspended storage, or missing marker all refuse.
Gap found and fixed
Orphan assessment and removal used plain git status, which skips edits hidden by
skip-worktree / assume-unchanged. Such an orphan was judged safe and removed
with git worktree remove --force; only the archive sweep checked the index.
reject_index_flagged_files (tuic-git:5414) is now shared by the sweep,
orphan_cleanup_safety and the no-force branch of
remove_worktree_internal_with_lock.
Test: orphan_with_edits_hidden_by_index_flags_is_unsafe_and_never_removed
(catches: hidden local configuration deleted with a clean-looking orphan). It
failed before the fix (safe: true).
Open observations, not changed
- Ignored files (
.env, build output) are not checked by orphan removal; the archive sweep keeps them. Blocking on them would stop nearly every orphan from being swept. Needs a Boss decision; not built. - Orphan Keep is not persisted across restart (safe, re-asks).
- Merging remains manual; nothing here merges.
4. Test map
| Behaviour | Test |
|---|---|
| Every kind of unsaved work unsafe | orphan_assessment_is_unsafe_for_every_kind_of_unsaved_work |
| Hidden index-flag edits (new) | orphan_with_edits_hidden_by_index_flags_is_unsafe_and_never_removed |
| Detached HEAD without durable ref / in-progress op | orphan_removal_refuses_a_detached_commit_without_a_durable_ref, orphan_removal_refuses_an_in_progress_operation |
| Branch restored after discovery | automatic_orphan_removal_rechecks_a_branch_restored_after_discovery |
| Temporary worktree lifecycle | temporary_detached_worktrees_are_never_orphan_candidates, temporary_orphan_removal_refuses_automatic_and_confirmed_requests |
| Missing metadata | orphan_whose_directory_is_gone_requires_explicit_removal_to_drop_entry, orphan_whose_directory_is_gone_stays_out_of_fingerprint_cleanup |
| Retention age, ownership, availability, dirty, index flags | archive_retention_honors_age_and_keeps_unrecoverable_dirty_files, archive_retention_requires_recorded_ownership_and_availability, archive_retention_keeps_local_edits_hidden_by_skip_worktree |
| Keep | orphanKeepFingerprintCritic.test.ts, keeping_twice_stays_kept |
WF01 preservation baseline and shared contract
Baseline date: 2026-10-30. Story: 2508-3a15. This is a contract and source baseline, not an operational migration or a certificate of installed health. The approved implementation plan, section 2, remains the authority for later stories. This baseline does not activate a policy, scheduler, subscription, integration writer or provider action.
Frozen inputs
- Source pins and native test inventory records exact SHA-256, byte length and observed revision for the feature report, study register, approved plan, global policies, repository policies and current native workflow modules. Test names are source inventory, not a claim that they passed today.
- Feature report snapshot retains the original report, including its source-health qualifications and I1–I10. Its declared source revision differs from the later observed repository revision; both are retained.
- Preservation matrix binds every one of the report’s 105
capability IDs and all 42 screenshot feature IDs to the approved destination
and WF validation owner. Every row starts
required_not_operationally_verified. WF17 must add operational evidence before retirement; static coverage is not parity. Optional nodes cannot retire their retained deterministic tools. - Recorded native event streams come from the pre-change RunStore, not handwritten serialized model fixtures.
Source hashes pin observed bytes. A source path is not an import grant. Host
policies have an observation date rather than a fabricated Git revision. Their
bytes are retained in host-policies.txt. A later source change requires a new
baseline/import revision and an explicit comparison, not replacement of history.
Event upgrade and retained replay
Run-store layout 5 admits event contracts through version 3 and causes older binaries to refuse the database. This is a compatibility marker, not conversion of old events. Opening a database does not rewrite a run’s event contract.
| Contract | Retained semantics |
|---|---|
| 0 / absent field | Legacy snapshots remain readable and cancelable; no invented graph position or resume policy. |
| 1 | Existing record-only command behavior remains; graph events remain refused. |
| 2 | Retained serial graph transitions, exclusive Join, run-wide NeedsInput and explicit resume. New children of an old run remain contract 2. |
| 3 | The same serial semantics plus a graph-start contract pin. No Fork, all-Join, token ledger, Call or branch-local Ask is activated by WF01. |
| Newer / unsupported | Refuse start/replay/mutation rather than guess semantics. |
The immutable graph-start event stores the whole PublishedWorkflow. Contract 3
also stores {version:3,definitionSha256,policyImports}. The definition hash is
SHA-256 over serde JSON bytes of the typed publication, including project, ID,
revision, graph, prompts, closure and required checks. It is not a portable
cross-language canonical-JSON hash; producers and replay use the Rust codec.
The reducer verifies the pin at graph start and dispatches old serial transitions
through the retained implementation. Future token semantics must use a distinct
version branch, not reinterpret Join {}.
A new draft/publication cannot change an active run’s publication or check policy. There is no active-run upgrade API in WF01. A future migration must name run ID, expected sequence, old/new contract, old/new definition and policy digests, identity/receipt mapping, unsettled effects and stop/reconciliation proof. It must commit an explicit migration receipt before new semantics can execute. Draft save, publish, database open and daemon recovery are never implicit migration requests. Legacy work drains under its original owner. Unknown effects stay unknown.
Policy-import boundary
PolicyImport has exactly domain, source, revision and sha256.
Domains are global_routing, repository_gates and publication_authority.
Import source bytes/revisions, not mutable defaults or credentials.
- Global routing comes only from the named global orchestration authority. Repository templates and spawn wrappers do not override it. Missing exact approved model/profile is a visible block in the future imported-policy lane.
- Repository gates add the applicable project requirements: native versus rb proof, target/config/test scope, build admission/freeze, one mutation process, canonical Git writer, GUI/device isolation and owned-process cleanup. Conflicts need a named Boss exception; do not select the cheaper gate.
- Publication authority is separate from permission to run a workflow, integrate
or mark proof complete. It binds exact repository and actions. The approved
unattended-PR creation repository list is
[]; no repository is inferred from a local path. Push, merge, release and ready actions remain distinct grants.
WF01 new starts pin the existing native graph/check/closure policy. Their
policyImports is explicitly empty: global policy was not loaded or enforced
as a new runtime import. WF09 resolves/pins the complete transitive publication
and policy set; WF04/WF16A enforce effective launch/routing imports. This boundary
avoids claiming that today’s default-profile fallback already meets the future
exact-model contract. Importing source inventory is not permission to activate it.
Built-in updates offer a new draft/diff; customized definitions and active runs
are not overwritten. WF13/WF14 perform versioned, expected-revision settings
imports, disabled first; only WF17 can transfer a consumer after parity/approval.
Effect and receipt schemas
run/contracts.rs defines the active graph/policy pin shapes. The standalone
execution v1 JSON Schema defines typed adapter intents
and receipts without adding unused runtime effect types. It is a contract for
later adapters, not a new callable effect. Existing
EffectIntent, RunReceipt, CheckReceipt, IntegrationReceipt and
CanonicalReceipt keep their existing wire formats and state machines.
EffectIdentity: run, execution, activation, attempt, generation and effect IDs.ExecutionSubject: either an artifact ID/canonical repository key/commit/tree and requirements digest, or an external provider/resource ID/expected revision and exact payload/requirements digests. Workspace identity is separate from a machine path. Both intents and receipts identify their owning daemon.ExecutionEffect: schema version, identity, kind, payload-bound idempotency key, subject/workspace, explicit argv or prompt/profile or typed Tool payload digest, target requirements, resource keys, deadline, secret references, output schema and exact policy imports. There is no implicit shell; an explicit shell must be a visible, versioned command contract. No secret values enter the ledger.ExecutionReceipt: schema version and matching identity/payload/subject, executor identity/fence, exact target/toolchain, command/config/test-scope digest, logs/artifact digests, succeeded/failed/cancelled/unknown outcome, stop proof, matched-test count and usage receipt references. Missing usage is unknown, not zero. A Linux receipt cannot satisfy a native Mac proof requirement.
Adapters must validate supported schema versions and full identity/payload before execution or acceptance. Intent commits before any external effect. Same key and same payload returns the original receipt; a different payload fails. Lost replies use lookup, never blind retry. A terminal report is evidence, not acceptance. Cancellation requested differs from observed stop; expiry does not release a shared resource or authorize cleanup/replacement. Disconnection is unknown. Only the owning daemon selects successor edges. ACP identity is not a PTY.
Evidence acceptance additionally binds criterion/requirement revision, pre-fix commit for RED, clean source commit/tree, merge base/result, target/toolchain, command/config/test scope, independent reviewer and freshness inputs. Preserve REALITY/SYMPTOM/TEST-CHANGE and omissions at the story boundary. Nonempty intended scope with zero matched tests cannot pass. Integration, proof completion and release readiness are separate states. A pinned cohort cannot clear later debt; mutation reuse needs the entire requested universe and compatible evidence. These are WF05–WF08 validation obligations, not invented WF01 successful receipts.
Source-conflict decisions: I1–I10
These decisions select the import contract. They do not edit or retire sibling scripts, move live reports, install hooks, create backups or run a scheduler.
| Issue | Resolution for this baseline | Later verification owner |
|---|---|---|
| I1 stale critic text | Select critic-brief.sh and its active critic-brief.template.md, actual five-argument signature and FIX/STORY/ACCEPT policy. The unused briefs/critic.md is historical, not a merged instruction source. Keep strict required gates and no generic Proof filling. | WF06/WF16A audit callers before retirement. |
| I2 stale digest paths | Persistent bilingual repository reports are authoritative. Temp reports are not mobile delivery. Preserve/apply ticks and comments before any move; no live move here. | WF16C report/acknowledgment migration. |
| I3 unsafe cleanup/landing skill | TUIC worktree tracking, review, child-close ownership, integration/stop proof and preservation of unattributed dirt win over raw Git deletion/direct low-risk landing. No destructive action from the stale skill. | WF04/WF07/WF16A. |
| I4 competing routing/gates | Global ORCHESTRATION is the sole routing authority. Exact task authority and repository gates apply; no cheaper fallback or blended template. This task explicitly requires the two RED tests and same-call strict clippy. The older deferred-GREEN text is not a model/profile or gate override. | WF04/WF06/WF16A import/effective-policy comparison. |
| I5 combined countdown | Keep per-release counts, release work/Boss waits/next separation and one zero notification. The aggregate all: line is not imported as required presentation. | WF15/WF16C. |
| I6 mutation docs drift | Pin the current producer, fixture and e2e source; do not preserve a stale claim that they are absent. No live measurement pass and no deletion-only reuse bridge is inferred. | WF08/WF16A compatible evidence checks. |
| I7 compatibility helpers | Retain helpers until their target product behavior and actual callers are checked. An old replacement story number is not removal evidence. | WF16A and WF17 retirement gate. |
| I8 unequal CLI hooks | Record Claude/Codex source wiring separately; effective global/runtime and ego coverage are unknown. Unwired no-pkill/no-zsh-path source is not universal enforcement. | WF16A effective per-harness audit. |
| I9 installed health | Hook source, launchd/systemd files, model names and status-line settings do not establish installed/loaded/available health. Record unknown until read-only runtime/last-run evidence exists. | WF16A/WF16B; WF17 blocks relevant parity claims. |
| I10 registry sole copy | Preserve the existing registry, never replace it with historical tested rows. WF08 owns naming an operational backup/restore owner and SQLite-consistent backup procedure; owner/last backup remain unknown now. No sole-copy reliance or destructive cutover until verified. | WF08 backup/restore evidence before WF17. |
Verification record and limits
The two named RED tests failed on pre-change commit
0fd8fb21e23ac31a949ce560c6d9b4fff88f4e86 with test additions only:
old_exclusive_join_replays_without_parallel_wait reported version 2 instead of
3; draft_publish_does_not_repin_active_run reported missing contract metadata.
Both ran (zero matched tests was not treated as success). Their old behavior
assertions passed. Same-call cargo clippy -p tuicommander --all-targets -- -D warnings passed on rb. The log and captured fixture provenance are recorded in
the story worklog and fixture README. No Mac-native proof is claimed by that run.
The targeted final run covers workflow graph replay/publication consumers and
existing HTTP/service start parity. API commands/routes remain unchanged; the
snapshot gains an optional graph contract field. Old fixture JSON has no field
and round-trips without adding one. No JavaScript scheduler or transport-specific
policy is added. Full suites, mutation, coverage, live installation audit,
provider actions and operational migration belong to their later owners.
Final targeted evidence: 62 tests passed on rb, followed by strict all-targets
clippy with zero warnings. Log: /Users/stefano.straus/Gits/.tmp/wf01-final-fixed.log.
The earlier final attempt passed the same 62 tests but failed clippy on unused
future Rust schema types and one assertion lint. Moving unimplemented adapter
shapes to the standalone schema and correcting the assertion resolved those
failures; the repeated affected run passed. JSON syntax/local schema references,
source hashes and complete matrix IDs passed static checks. A JSON Schema
meta-schema validator was not installed, so no such validation pass is claimed.
Story backend protocol (version 1)
A repository can keep its plans and stories in an external backend. TUIC starts the backend’s adapter as a child process and talks to it with this protocol. The adapter owns story content. TUIC keeps execution state (claims, review and QA sub-states, receipts, transition history, idempotency keys) in its own SQLite store, keyed by adapter id and story id.
Code: src-tauri/src/story_adapter/ (mod.rs client and supervisor,
port.rs the StoryBackend adapter, binding.rs settings and watcher hook).
Reference adapter: scripts/story-adapter-reference/adapter.mjs.
Automatic selection and explicit bindings
Automatic selection first retains native while an unarchived, unfinished native plan or a
persisted active native execution exists. The header says Native retained while ….
This continuity rule runs before connector discovery and approval; it is not fallback
after connector failure. Otherwise, TUIC selects Wiz when passive project data contains a .wiz directory or a
recognized hashed Wiz story filename. A generic stories/ directory is not a
marker. Story-directory settings come from .claude/settings.local.json, then
global Claude settings, then stories; absolute paths and parent traversal are
rejected. Linked worktrees read the main checkout’s shared story store. Detection
reads data only and never runs a repository script.
The installed plugin registry (<CLAUDE_CONFIG_DIR or ~/.claude>/plugins/installed_plugins.json)
suggests the installation of wiz@lansweeper-tools. Applicable registry scopes use
local > project > user precedence; project/local entries must map to the canonical
owning project, and unrelated projects do not create ambiguity. Scope never approves
code. Multiple entries at the winning scope fail closed with instructions to select
one installation in the plugin manager, remove the duplicate, then refresh.
The Stories header shows the
resolved path. The user must select Approve installed Wiz connector once.
TUIC stores the resolved installation, script path, entry SHA-256 and version in
its machine-owned <config dir>/story-connectors.json. Approval pins the displayed entry/version, not the full dependency tree. It
applies to projects selecting that installation, not one repository. A changed installation, entry or version needs
new approval. After renewed approval, an entry/version change replaces the bound
process even when its executable arguments are unchanged. The approved connector is scripts/tuic-story-connector.js, launched
directly with an absolute Node runtime path and project cwd. Do not use wiz-run:
its synchronous timeout wrapper cannot host a long-lived connector.
An unmarked project uses TUIC native SQLite. After the native continuity rule, a detected Wiz project with a missing,
broken, ambiguous or unapproved connector stays unavailable; it never shows native
content instead. Explicit overrides remain in <config dir>/story-backends.json:
{
"/abs/native-project": {"backend": "native"},
"/abs/wiz-project": {"backend": "wiz-stories"},
"/abs/legacy-project": {"command": "node", "args": ["/abs/adapter.mjs"]}
}
Explicit overrides take precedence over detection. A malformed file or invalid
binding is an error, not automatic selection. Legacy commands remain explicitly
trusted machine settings; repository files cannot supply commands. A project
switches to an external backend only when no native plan is open (unarchived and
not done). A backend cannot change while an execution is running or paused, even after
restart with no bound process. The existing durable run snapshot pins
storyBackendIdentity at admission (native or command + approved generation).
Active snapshot project paths use the same canonical owning-project resolver as
story actions. A run admitted before pins existed resolves by the pre-pin rule: the
legacy command binding, otherwise native. Overrides cannot be written while a run is
active, so the current settings still answer it; a backend override on such a project
fails closed. TUIC never infers provenance from possibly colliding plan IDs.
Existing native records stay in SQLite. Desktop and headless use the same selector.
The shared story action backend_status returns {type:"backend_status",value:{ backend,label,provenance,reason,availability,installation,version,error,generation}} even
when the connector cannot initialize. provenance is automatic or explicit;
availability is available, approval_required or unavailable. This status
probe can initialize an already approved connector; passive detection itself does
not start a process. approve_connector {installation,expected_identity} is an explicit human UI
write, refused for managed actors and unauthenticated HTTP callers. It re-reads
the installation, registry version and entry digest to reject stale suggestions before
it saves approval; expected_identity is the displayed generation value. The shared
human-only set_backend {backend} action accepts native, automatic (remove the
override), or wiz-stories. The header offers native and automatic selection.
Explicit Wiz still refuses an open native plan; selection writes refuse active runs.
Legacy command-map entries continue to tolerate extra metadata keys.
The dialog performs one final status confirmation after content reads. A changed selection/generation clears the content and asks for refresh, not a retry loop. Selection/read overhead has not been benchmarked; no latency claim is made.
Wiz supplies its own plan projection. Protocol 1 has no wont_fix value; the Wiz
connector omits those stories. Wiz declares create_story=false because TUIC’s
protocol does not supply Wiz’s required story type. TUIC does not invent a type
or pretend that unsupported operations are available.
Mapping to the StoryBackend port
revision= a hash ofversion. A write compares the caller’s revision with the current record, then sends that record’sversionasexpected_version.- Status:
pending= backlog,ready,in_progress,blocked,complete= done. - Legacy aggregate (
set_fields:true)update_storybecomes oneapplyper change (set_fields,add_criterion,add_dependency,remove_dependency). The sequence is not atomic: a refusal leaves the earlier operations applied. Editing or removing a criterion, file scope, origin, type and risk are unsupported. - Unsupported: plan creation, plan edit, archive of plans and stories, note
receipts, unchecking or editing a criterion,
wont_fix.
Native workflow preparation boundary
Accepted issue preparation uses native transactional once-only plan creation and story creation with retained problem text. Native proposal identity and payload commit with the record; observation never creates a missing record. The issue URL remains within the 20,000-character problem cap even when the body is truncated. The version-1 external adapter does not gain new methods: these workflow capabilities refuse when its port does not implement them. An external-backend refusal never redirects creation to native SQLite.
Execution ledger
TUIC keeps execution state in its SQLite store, keyed by adapter id and story
id (external_story_execution, external_story_transitions; code:
story_adapter/execution.rs, stories/store/external_ledger.rs):
- Claim: the session that claimed the story.
- Review and QA: TUIC sub-states while the adapter reports
in_progress. The adapter never sees them. - Transition history: every TUIC transition with its command, actor and the adapter version it wrote.
- Integration receipt: the adapter version at a TUIC approval.
A transition writes the adapter first (criterion checks, then set_status),
then the ledger. The two writes are not one transaction: a ledger failure
leaves the adapter changed and the error says so. The story revision covers the
adapter version and the ledger row, so a sub-state change is also a new revision.
A story that the adapter reports complete without a receipt was completed
outside TUIC. The plan view marks it completedOutside. It releases no
dependent: a dependent that the adapter reports ready shows as backlog and
cannot be claimed or started until every dependency has a receipt.
GET /stories/capabilities?path=<project>(IPCstory_capabilities {project}) answers the adapter’s operations; the Plans and Stories window disables the rest. Withoutpathit answers the native descriptor.
Transport
- JSON-RPC 2.0. One JSON object per line (newline-delimited) on stdin and stdout.
- The adapter writes diagnostics to stderr only. TUIC logs stderr lines at debug level.
- One long-lived process for each bound repository. The working directory is the repository root.
- TUIC sends requests. The adapter sends responses and, optionally, the
changednotification. The adapter never sends requests.
Records
Every record carries an opaque version string. The adapter changes it when the
record changes. TUIC never parses it.
{"id": "p1", "version": "…", "title": "Release 2"}
{
"id": "s1", "version": "…", "plan_id": "p1", "title": "Fix login",
"status": "pending", "priority": 2, "problem": "…",
"criteria": [{"text": "RED: …", "checked": false}],
"dependencies": ["s0"],
"notes": [{"at": "2026-11-06T10:00:00Z", "text": "…"}]
}
status is one of pending, ready, in_progress, blocked, complete.
An adapter can add fields. TUIC ignores fields it does not know.
Methods
| Method | Params | Result |
|---|---|---|
initialize | {protocol, project_root} | {protocol, adapter: {id, version}, capabilities: {<method or op>: bool}, watch_paths?: [path]} |
list_plans | {} | {plans: [plan]} |
list_stories | {plan_id?} | {stories: [story]} |
get_story | {id} | story |
create_story | {fields} | story |
apply | {id, expected_version, op} | story |
append_note | {id, text} | story |
changes | {cursor} | {changed: [id], cursor} or {rescan_required: true, cursor} |
shutdown | {} | {}, then the adapter exits |
apply operations (op.kind): set_status {status}, check_criterion {index},
add_criterion {text}, add_dependency {id}, remove_dependency {id},
set_fields {title?, problem?, priority?}.
initialize must be the first request. TUIC refuses an adapter that answers a
different protocol.
capabilities keys are method names (create_story, append_note, …) and
apply operation names (set_status, …). A missing key means false. TUIC
disables the matching UI actions; unsupported server operations still refuse.
Optional protocol-1 set_title and set_priority flags each authorize exactly
one field in one atomic set_fields apply. Missing individual flags mean false.
Aggregate set_fields:true implies title, priority and problem support, including
combined metadata in a single apply; it does not imply support for TUIC-only
metadata (type, risk, origin, file scope). No protocol version bump is needed.
The TUIC capability descriptor retains operations.update_story unchanged:
native true, external apply && set_fields. Additive
operations.story_edits contains {title, priority, problem, criteria_add, single_change}. Native supports all four with single_change:false. External
mapping is title = apply && (set_fields || set_title), priority analogously,
problem = apply && set_fields, criteria_add = apply && add_criterion, and
single_change = !set_fields. Missing optional external keys grant nothing.
Older UI consumers without story_edits retain their existing aggregate behavior.
Restricted saves (single_change:true) accept exactly one supported title or
priority patch, or exactly one appended criterion preserving the entire existing
prefix. Unsupported metadata, editor dependencies, multiple metadata fields,
multiple additions and criterion edits/reorders/removals refuse before any apply;
unsupported fields refuse before the port reads content. Each successful save
sends exactly one ApplyOp, never a silent split. The editor disables unsupported
controls and enables Save only for one supported change, with a one-change hint.
Dedicated dependency methods keep their separate semantics. Native writes and
the existing non-atomic legacy aggregate apply sequence are unchanged.
watch_paths are absolute paths, or paths relative to the repository root. TUIC
watches them with its own watcher and calls changes when one changes. A
file-based adapter does not need a watcher of its own. The answer goes on the
event bus as stories-changed {repo_path, payload: {rescan, ids, error?}}
(SSE /events). The watch covers the repository tree only; a watch path
outside the repository is not observed. The watcher never starts an adapter.
Change detection
Correctness never depends on events:
- Every write carries
expected_version. The adapter refuses the write withconflictwhen the record changed. The adapter must make the check and the write one atomic step. - TUIC calls
changeswhen the watcher sees a change under a watch path, every 30 s for each running adapter, and before each decision of a workflow run on the project. Anullcursor asks for a baseline: the adapter answersrescan_requiredwith a current cursor. A cursor the adapter cannot use also getsrescan_required. - The
changed {ids}notification is a hint for latency only.
Errors
| Code | Name | Meaning |
|---|---|---|
-32001 | conflict | expected_version does not match the current record |
-32002 | refused | A backend rule refused the write; message is the reason |
-32003 | unsupported | The adapter does not support this operation |
-32004 | not_found | No record with this id |
-32601 | method not found | Treated as unsupported |
Supervision (TUIC side)
- A spawn failure, an
initializefailure, a process exit, or a request with no answer within the timeout makes the backendunavailable. TUIC stops the process and restarts it on a later call. The first restart is immediate; each further consecutive failure waits longer (1 s, doubled to 60 s at most). One answered request resets the backoff. - Each started process is a new generation. A cursor from an earlier generation
is answered with
rescan_required, because the adapter could have missed changes while it was down. - When the backend is unavailable, reads return
unavailable. A workflow run on the project pauses before its next decision with a cause that starts withstory backend unavailable. The daemon probes the backend every 10 s and resumes the run whenchangesanswers. Runs on a pull request or an issue do not wait. TUIC never reads or writes the native SQLite stories instead.
Trust
The adapter command is code that TUIC runs. It comes only from
story-backends.json in the TUIC configuration folder. No repository file can
name a command, so opening a repository never starts an adapter that the user
did not configure.
Known limits
- DEFERRED (2026-11-07): selection replacement in
binding.rscan hold the globalBOUNDlock while an adapter call runs, so a hanging adapter can stall other repos’ watcher callbacks for up to 30 s. Fix: clone theArcand cursor, drop the guard, then call. - DEFERRED (2026-11-07): a
story-backends.jsonkey that does not canonicalize (~/x, a typo, a relative path) is ignored and the project reads native stories. - A workflow run reads and moves stories through its project’s backend: the
StoryBackendport carries the engine transitions (begin, check, submit, approve, reopen, history). On an external backend they write the adapter and the ledger; dependency readiness needs no reconcile write, because it is derived from receipts on every read. - DEFERRED (2026-11-07): run story proposals (
create_story_once) on an external backend are refused: the ledger has no idempotency row for an adapter create yet. - DEFERRED (2026-11-07): after a lost response, an automatic run resumes its own criterion checks by comparing revisions in order. External revisions are hashes, so that resume is reliable for native stories only.
- DEFERRED (2026-11-07): release member reads and the issue hand-off plan still use the native store.
- DEFERRED (2026-11-07): closing a session releases its claim in the ledger only;
the adapter keeps
in_progress, because that path has no project. - DEFERRED (2026-11-07): the MCP story tool does not read capabilities. It refuses an unsupported action on an external project at call time only.
Adapter conformance runner
Run the portable protocol checks against the reference adapter:
scripts/with-test-tmp.sh node --test --test-concurrency=1 scripts/story-adapter-conformance/protocol.test.mjs
Set one JSON parameter, TUIC_STORY_ADAPTER_TEST_TARGET, to select another
adapter and its store-side fixture. Commands are argv arrays, never shell text:
{
"adapter": {"command": "node", "args": ["/absolute/wiz/scripts/tuic-story-connector.js"]},
"fixture": {"command": "node", "args": ["/absolute/wiz-repo/tests/fixtures/tuic-story-backend.cjs"]}
}
Run the same command with that environment variable. Without the parameter,
story-adapter-reference/adapter.mjs and fixture.mjs remain the default.
The runner starts real processes and creates one throwaway store per test
under TUIC_TEST_TMP_ROOT or this checkout’s .tmp/ directory. It does not
modify a configured repository or the daily TUIC store.
The fixture receives three additional arguments: <action> <root> <json>.
It writes one JSON result to stdout and uses the backend’s real store writer:
setup: initialize the empty root and create a pending P2 story titledSeed story, with problemA persisted story for protocol conformance, unchecked criteriafirst criterionandsecond criterion, and no notes or dependencies. Return{id, plan_id}. IDs and plan names belong to the fixture; no check assumess1ordefault.create: create a sibling story with the supplied fields; return{id, plan_id}.change: update the supplied storyidto the suppliedtitle, as a writer outside the adapter would. Return{}.prepare_complete: satisfy backend-specific prerequisites such as a work log and QA section forid, without checking criteria or changing its status. Return{}. The runner checks criteria through the adapter before this call.
Checks follow the adapter’s declared capabilities. Unsupported create and
optional field writes must answer unsupported or method-not-found without
mutation, rather than fail a reference-store assertion. Two optional capability
keys refine set_fields: set_fields_problem and set_fields_multiple. Declare
them true only when the adapter supports problem edits and one atomic write of
multiple fields, respectively. Missing keys mean false. The reference adapter
declares both true; adapters with a one-field CLI writer can declare both false.
The runner reports which unsupported branches it verified.
The Rust tests in story_adapter/ still cover TUIC client supervision, port
routing and the execution ledger with the reference store. They are distinct
from this adapter-independent stdio/store conformance runner. A passing protocol
run is not a claim that those Rust integration tests ran against another store.
The reference adapter and its fixture serialize writes with an exclusive store
lock, so two processes cannot both acknowledge writes from one expected version.
A lock timeout fails closed. After a writer crashes while holding the lock,
stop all writers before removing <store>.lock; the reference implementation
does not expire a lock by age, which could break a live writer’s atomicity.
Workflow definitions
The internal neutral runtime has a typed HTTP adapter with pinned installed connector contracts, separate network/write grants and bounded cursor results for collections. See HTTP connector contracts. Native host composes configured families and binds authenticated public callers before dispatch. Operational cutover remains staged. The installed Telegram connector adds typed send/update/reply operations through the existing worker and durable exact-revision callbacks.
Trusted public native starts and answers
Desktop IPC supplies authenticated Owner identity. HTTP supplies Owner only for loopback or verified user credentials; transport admission alone supplies none. MCP preserves the actual live managed peer as Agent, including ACP generation and unsettled-connection checks. Request JSON has no caller or capability field. The installed host captures the canonical checkout identity before persisting a new start and binds the same provider before wake. A staged candidate is allowed; review/commit services still check the exact parent/tree/diff. Coarse agent launch continues to require a clean baseline. Starts and exact retries serialize through the existing owner; a retry cannot replace the caller, workspace, captured rights or check definitions. Missing/revoked backend capability bindings fail closed.
Verification check names come only from published constant request bindings on
native.verification.run in the retained root/children, resolved by the installed
host. Dynamic check requests and names supplied only in start inputs are refused.
After restart, volatile native bindings require trusted backend rebind; no caller
metadata or grant registry is migrated into the run database.
Authenticated Owner may answer any bound native run. Agent may answer only its own run with both captured and current Operator authority. The ledger still checks the exact effect key, question revision and command sequence. Existing non-native host answers retain their behavior. HTTP/IPC/MCP wrappers share this backend boundary; live transport parity and operational cutover require their separate acceptance evidence.
Neutral workflow transport (015)
Desktop workflow_neutral_action {project, action}, HTTP
POST /workflows/neutral/action?path=<project> (body is the action), and MCP
workflow {"action":"neutral","input":<action>} call one backend service.
Replies are {type,value}. Neutral fields remain snake_case; no transport
converts mapping keys, result casing, unknown data or effect uncertainty.
MCP takes the project from its live managed PTY/ACP binding and requires a local
or authenticated caller. Request fields never grant service authority.
Actions: catalog, templates, create_draft, list_drafts, get_draft, update_draft,
validate, preview, publish, get_publication, clone_publication,
save_operation, save_preset, get_preset, start, inspect, events,
cancel, answer, start_delivery, delivery_runs. The MCP input schema derives from the same NeutralAction
used by HTTP and desktop. Internal effect observation/completion commands are
not public variants. Neutral triggers remain a 010 handoff; legacy bindings keep
their existing transports.
Plan and story delivery workflow
run/plan_delivery.rs builds this workflow only from neutral catalog nodes.
No legacy definition is converted. The first start_delivery {story, key}
installs it in the project: four saved script operations (delivery/implement,
delivery/verify, delivery/review, delivery/deliver), the published
subflow delivery-attempt (implement, verify, review) and the root draft
“Plan and story delivery”, which it publishes. The Designer edits that draft
like any other; an installed and published draft is never overwritten.
The root runs the attempt in a bounded loop (correction, three attempts).
The loop repeats while the pair {passed, approved} from the verification exit
status and the review verdict is one of the rejected pairs. The next attempt
receives the findings of the previous one. Only a complete loop reaches
deliver, which commits the workspace once and ends delivered. An exhausted,
unknown or failed loop ends blocked without a commit. The implementer and the
reviewer get the prompt on stdin of the instance command (default
ego run --sandbox workspace - and ego run --sandbox ro -; the reviewer
approves with APPROVE on its first line). The default verification command
is only git diff --check HEAD: set the project check command in the Designer.
Each implement step records the paths whose Git status or content changed
during its agent call; the loop carries their union. The deliver step stages
only those paths, so an untracked file that was there before the run stays out
of the commit.
The run input story is a backend snapshot of the story (id, title, problem,
criteria, plan). The request id is story-delivery:<story>:<key>;
delivery_runs {story} lists the story’s runs newest first with run_id,
key, status and bound. Plans and Stories shows them under the story.
Caller provenance is volatile. After a restart the native host has no binding
for a running run, so the actor waits (NeutralHost::bound) instead of failing
its next step. start_delivery with the same key re-issues the retained
request, rebinds the caller and wakes the run at its recorded position. A
settled effect is never invoked again; an effect without an observation
reconciles as uncertain.
Drafts wrap the existing NeutralDefinition with id, project, name,
revision, latest_published_revision and optional presentation editor.
Create takes name/definition/editor. Update additionally takes id and
expected_revision. editor has labels and presets string maps keyed by
control-node ID, both defaulting empty. Presentation is stored beside each
publication; definition hashes, pins and admission never read it. Publish
checks the draft revision inside the publication transaction, retains the
presentation atomically, and refuses unchanged republishing. Exact publication
read/clone preserve the internal subflow graph and immutable pins.
Catalog lists authoritative activity descriptors and pinned metanode publication
views. A production native adapter installs the same host Arc for authoring and
the existing execution owner. Without installation, catalog/publication/preview
and new execution refuse with native catalog not installed. Draft editing and
retained run inspection remain available. This transport is staged; it does not
replace the scheduler or activate operational cutover.
The installed NativeHost supplies the eight native descriptors and delegates
the closed set of script, HTTP, model, Jira, GitLab and Telegram adapters through
that same provider. Saved script and typed HTTP targets come from the existing
project reusable-operation store. Jira/GitLab descriptors require installed
plugin configuration matching core account metadata; GitLab additionally needs
the plugin’s service-observed resolvedProject {path,id} for its current path.
Discovery reads local metadata, never credentials or a remote project lookup.
Telegram requires its enabled configured alias. Model requests require the
configured absolute executable and exact nonempty profile; model and effort are
explicit request fields, with no fallback. Its literal request contains the
existing model request contract; tools retains exact bounded host operations,
and structured output is returned under the descriptor’s result object.
Absent configuration is omitted from the catalog. Unknown/changed adapters refuse dispatch. Authenticated owners may use installed configuration; agents need Operator in both their captured ceiling and current backend capability set for script/model/connector execution. HTTP and Jira/GitLab mutations also require the exact ledger write approval. Paid model calls require Operator without a separate per-call approval. Native Push authority stays separate. Current configuration and authority are rechecked immediately before delegation.
Validation returns {valid,diagnostics:[{path,code,message}]} with JSON Pointers
for incompatible data links. Preview takes definition/inputs/subject and returns
validation, per-activity inputs as existing Datum values, output schemas,
outcomes, optional pure effect preparation and an unavailable reason. Unknown
producer/scoped samples remain unknown. Preview performs bounded publication and
resolved-value checks, then prepares intent without requiring a run binding.
Its synthetic fence never invokes an effect or writes a run/receipt and supplies
no dispatch authority. A displayed unbound approval deadline is only intent;
runtime preparation retains the bound run’s actual deadline.
Start takes the exact NeutralStartRequest (publication, request_id, inputs,
subject and limits). Inspect takes run_id/after_sequence/limit (1..500), returning
{snapshot,events} from one retained read snapshot. Status is tagged type:
running, completed (outcome), cancelled, expired, limited (reason), failed
(diagnostic). Outputs, waits, failures, uncertainty, effect questions and nested
execution boundaries come from the retained owner. Events use the existing
NeutralEvent snake_case envelope. Cancel and answer require command_id and
expected_sequence; answer also binds the exact effect key and question revision.
Every committed neutral start/decision dual-emits the existing
workflow-run-changed invalidation: desktop and /events SSE receive
{repo_path,payload:{runId,sequence}}. Low-frequency invalidation reuses the
existing event bridge; no token stream or extra WS is needed. Clients re-read
inspect/events by sequence after notices and reconnect, including final results
or effect settlement after a run ended. A label or model selection is never an
approval. Backend/native providers retain current rights and original-effect
reconciliation responsibility.
Slice F exposes start_graph {target:{type:story|plan,id},expected_revision?,definition_id,definition_revision,request_id,limits?,secrets?} through the existing owning-daemon service. secrets is a map of environment names to values for the agent children of this run only (PTY spawn environment and ACP connection environment). The values stay in daemon memory: run state, events, receipts, prompts, the launch journal and logs hold the sorted names only (secret_names on the run snapshot). TUIC_SESSION and TUIC_PARENT are refused. Completion, cancellation and a daemon restart drop the binding; a later agent launch of a run whose binding is gone fails before spawn and pauses the run. Story starts require the current native revision and pin the selected publication; the request ID is bound to its payload. Omitted limits use Rust defaults. Public plan starts use the same graph-root entry point and slice E dispatch. The Plans and Stories dialog has no plan start control; its selector handles stories only. The workflow action=run MCP entry uses an inline schema generated from RunAction and the public RunCommand variants; it returns the same scoped snapshots and cursor-ordered events as IPC/HTTP. Run history shows pinned activations, decisions/evidence, repair counters, pause targets and complete event payloads across pages. Graph recovery uses resume_graph {execution_id,activation_id,resolution} after answering pending input; pause and cancel use the existing sequence-fenced commands. Legacy runs offer inspection and cancellation in the UI. No new persistence or client scheduler is added.
Workflow definitions are owned by a canonical project path and stored in workflows.sqlite3 under the TUICommander configuration directory. A definition has a mutable draft revision and immutable published revisions. Editing a draft uses an expected revision; publishing validates the graph, resolves pinned story-template revisions, and inserts a new published row in one SQLite transaction. A run must pin a published revision; this definition layer does not execute nodes.
Each definition has a closure policy. Existing records migrate to human, and new drafts default to human; this legacy policy name means an explicit approval transition, which may be performed by any trusted caller. update_closure edits a draft with an expected revision. automatic publishes only for a story delivery graph that has a Gate node whose pass edge leads to the Judge and a pinned evidencePolicy. No person moves an automatic story to Review: when the implementer reports completed and the story is still in progress at the reported revision, the run checks exactly the non-manual criteria that report proved and submits the story, as the managed actor workflow:<implementer attempt id> in the story transition history. It does this before the reviewer starts, so the review binds the submitted revision. A retried turn resumes a submission that a lost response interrupted only when every later story transition is that actor’s own criterion check. The run never checks a [MANUAL] criterion; such a story moves to QA, and the run pauses with Story <id> awaits manual QA before any reviewer starts. The Judge then closes the story only when the gate passes and the reviewer’s typed evidence validates (GREEN checks, REALITY); a story with a RED: criterion also needs RED proof. Under automatic closure the daemon, not the reviewer, runs the RED test: the reviewer’s RED command must extend a pinned requiredChecks command, and the daemon runs it in a detached checkout of the pre-fix commit. It records a durable RedReceiptRecorded receipt (argv, commit, tree, exit code, count of output lines naming the test, log digest). The Judge replaces the reviewer’s reported exit code, match count and log digest with the receipt; a missing receipt, a zero exit or no matching line leaves the story in Review. A failed gate or missing proof leaves the story in Review with the reason on the run. Published revisions retain their pinned closure policy.
A definition also pins requiredChecks: up to 16 check commands, each with a stable ID, an argv array, and a timeout of 1–600 seconds. update_checks edits the draft with an expected revision; publication stores the exact set on that immutable revision. Commands invoke executables directly, without a shell. execute_check runs a pinned check in the assigned, clean story worktree and appends a durable CheckRecorded event with command, exit code, branch ref, commit/tree digest, and duration. A failed command also receives a receipt, but it cannot authorize integration. A changed worktree or ref makes the receipt stale.
The graph contains stable node IDs and directed edges. Node kinds are Start, Agent, Create Stories, Story Dispatch, Judge, Gate, Pause, Loop, exclusive Join, Fork, all-Join, For each, If/else, Notify, and End. An Agent carries a role, prompt template, and a bounded list of supported capabilities. Story Dispatch is a plan-only node that pins a published story definition ID and revision in the same project. Create Stories is plan-only. Join is story-only, with at least two incoming branches. A Loop is the only source of a back edge and requires max_iterations from 1 through 100 plus repeat and exhausted edges. Judge requires yes, no, and uncertain; Gate requires pass and fail; Story Dispatch requires completed and blocked. Invalid references, duplicate or unreachable nodes, missing outcomes, and other cycles are rejected on publish. A node is reachable through an edge or as the resume_to target of a reachable Pause. The optional layout object maps node IDs to Designer canvas positions ({x, y}, unsigned 16-bit). It is omitted when empty and execution never reads it.
The first list or explicit seed action inserts Story delivery and Resolve plan once per project. The latter pins revision 1 of the former. Fresh story and plan seeds both pin the repository-integrity check (git fsck --connectivity-only --no-progress, 300-second timeout), so their drafts can be published and their runs perform deterministic final verification. Projects can replace this baseline with their own checks in a new revision; clearing every check still prevents executable publication. Both remain editable as drafts; a new published revision does not rewrite an older one.
Desktop IPC command workflow_definition_action and HTTP POST /workflows/definition/action?path=<project> call the same Rust service. Actions: seed_templates, create_draft, list_drafts, get_draft, update_draft, update_closure, update_checks, publish, get_published, save_file, load_file. The MCP workflow action=definition entry exposes the two file actions to the calling managed session’s project. update_closure and update_checks have no Designer control. The action is a JSON object tagged by action; replies are tagged { type, value }. The Plans and Stories dialog has a Designer tab for draft selection, pointer drag (mouse, pen, touch) or button-based node addition at canvas positions, Author presets, For each and Splitter regions, keyboard or pointer node moves, outcome-link editing, node inspection, saving and publishing. The backend remains the authority for graph validation at publication.
Structured script adapter (007-7ce3, staged)
The internal script activity contract uses the existing owned-process executor and neutral effect ledger. It validates a versioned fenced JSON result, keeps stderr separate, bounds execution/IO and retains mutation uncertainty across loss and cancellation. Custom descriptors remain generic catalog data. Production host installation, neutral public transports and Designer rendering remain their respective consumer stories.
Neutral execution ledger (004-2809, staged)
The internal neutral ledger records control decisions, prepared activity inputs and subject, validated immutable results, condition provenance, absolute wait deadlines, cancellation, duration expiry and activation-limit exhaustion. Commands use the same RuntimeOwner lock and RunStore writer transaction, with expected sequence and exact command-payload identity. Inspection replays retained events without the current catalog or a story backend; a duplicate command returns its original receipt projection. A completed result cannot be replaced, and a terminal run rejects late completion. Checked timestamp addition rejects overflow.
The authored owner integration adds collection item, fork branch and loop iteration fences, immutable settled scope outputs, and retained subflow frames. The existing actor selects the persisted contract before any legacy scheduler, backend gate, health check or effect path. Neutral restart enumeration shares the same owner and mailbox. Startup enumerates neutral identities without replaying all histories; each actor verifies its own run, so one corrupt payload does not block healthy recovery. Every ordinary actor return releases its mailbox entry. Only dispatched unresolved ancestor work consumes nested execution capacity; prepared siblings cannot block their active child frame. Storage errors leave the cursor retryable; only deterministic Step decision errors become run failures. Each actual invocation requires a current backend context and exact host registry, including resolved child arguments and non-amplifying subflow context derivation. No context or grant is stored in the event stream. Missing host services refuse execution rather than bypassing their invariants.
Run-store schema 21 prevents an older owner from ignoring execution decisions; existing rows are not migrated. Focused runtime validation passed, including corrupt-history isolation, contract-read error recovery, nested collection/subflow execution and refused SQLite-write retry. This internal integration does not enable a public neutral start or operational cutover. Preparation is not admission or a dispatch permit. A persisted dispatch claim is never automatically invoked again after restart. Full effect correlation, approval, uncertainty resolution and native stop/resource observation belong to 005; real native service adapters and freshness evidence remain required by 008.
Neutral run persistence (004-2809, staged)
The neutral runtime contract is under implementation, not an operational cutover.
Its internal start boundary belongs to the existing RuntimeOwner lock and
RunStore database. Run-store schema 20 adds neutral_workflow_runs and
neutral_workflow_events; it does not convert legacy runs or invent their
execution positions. Older builds must refuse this database version.
A start retains the verified root and descendant publication bodies, the union of exact descriptor bodies (including schemas and handler versions), inline configuration/prompt text, normalized typed inputs, optional subject, and generic activation/concurrency/duration limits. The first sequenced event is immutable and content-checked on inspection. No plan, story, review counter or compiler policy is needed. An exact project/request-ID retry returns its original run without consulting today’s catalog or handler registry; changed arguments refuse. The immediate transaction rechecks that identity before inserting the run/event.
The original 004A persistence slice did not dispatch activities or wake an actor, and stored no host context or grant. The subsequent 004D owner integration above now supplies control-flow routing, resolved per-activity admission, activation/attempt fences, durable scopes and restart-safe scheduling. Current authority and handler availability are checked at each actual host-port dispatch; retained bodies are never permits. No new IPC/HTTP/MCP start surface is exposed by this internal integration.
Legacy engine removed (3034-365e)
The role/kind graph engine, its definitions, runs, bindings, host routing policy,
migration converter and run history are deleted. Only the neutral engine and the
automations prompt scheduler remain. On the first start of this build each store
writes one backup next to itself (<file>.legacy-workflows.bak, SQLite
VACUUM INTO; automations.json.legacy-workflows.bak for the JSON file), then
drops the legacy data:
| Store | Removed | Kept |
|---|---|---|
workflows.sqlite3 | every workflow_* table and neutral_migration_conversions (user_version 1) | neutral drafts, publications, presets, reusable operations, neutral trigger bindings |
workflow_runs.sqlite3 | every workflow_* table and the commands, command_observations, command_resources journal (user_version 23) | neutral_* and native_* tables |
automation_runs.sqlite3 | review heads, event keys, event decisions and every run whose trigger is not scheduled or manual (user_version 2) | prompt schedule runs and their deliveries |
automations.json | pull_request_reviews, event_intake, triage_executor and the definitions only those engines could start | prompt schedules |
An existing backup is kept, so a later start never overwrites the state taken before the first removal. No live legacy run survives the upgrade.
Neutral reusable operation contracts (002-eeb6)
The internal catalog supports host-owned native descriptors and project-owned reusable script/subflow descriptors. Each descriptor declares its typed config, inputs, outputs, subject, named outcomes, exact handler name/version and execution policies. Instance configuration is data, not a second schema language.
WorkflowStore::save_reusable_operation appends immutable versions in the existing
workflow database. Creation expects version 0; updates name the current version
and insert its successor. Exact-version reads verify row/document identity,
content, target interface and current handler availability. Native descriptors
cannot be saved through this user-operation seam. Save also refuses an ID already
present in the supplied catalog; exact verified reads may reuse an identical
existing operation but reject a conflicting body.
The backend-owned HostRegistry binds exact handler versions to Script or Subflow
through register_reusable_handler. A descriptor cannot select an available
native, wrong-kind or unregistered handler version as a reusable target. Save,
read, project-catalog construction and publication/dispatch preflight enforce
that binding before invoking an adapter. This is a host routing invariant, not
permission supplied by descriptor capability strings or workflow JSON.
build_project_catalog combines the host catalog with verified stored operation
versions for one project. It refuses every ID collision with a host entry, loads
all operation descriptors before resolving child interfaces, and then verifies
their complete targets. Thus subflow dependencies need not follow row-sort order,
and old versions remain available for publication pins. It is an internal
store-backed consumer, not a public route, runtime adapter or plugin loader.
A script target contains the existing version 1 explicit shell invocation with a nonempty interpreter and inline source, each at most 32768 bytes and without NUL. Descriptor content pins cover the source. The exact trusted handler name/version is the handler pin; interpreter paths are not executable-byte attestations. External script/prompt asset resolution is not implemented by this contract.
A subflow target names an exact same-project publication revision and content hash. Its descriptor IO, subject and named outcomes must equal the child interface; explicit mappings remain a separate data-contract concern. Publication closure includes these target edges and checks every interface and pin, with the existing depth 8 and 32 expanded-edge limits. Later child revisions do not retarget an existing operation or publication. Neutral publication format 11 retains a required explicit control graph to the correlated fork/join scopes, return bindings, typed loop-carried results, bounded collections, named conditions, instance input bindings and declared outputs/outcomes. Earlier internal formats are refused, not migrated.
The output validator rejects unknown outcomes, missing required fields and wrong types. It does not run a process or advance a graph. Root dispatch preflight also refuses descriptor-backed subflows until child arguments can be resolved. Saved operations, presets and pins grant no permission. Runtime effect-boundary checks, script execution, Designer and transport authoring are not delivered by this internal slice. Explicit data projections are described below. Inline prompt text remains content-pinned; arbitrary handler interpretation of configuration strings is not proved safe by storage.
Neutral outcome control declarations (004-2809, staged)
control.nodes maps stable node IDs to start, end, activity, condition,
collection, fork, loop or timer-wait declarations. control.edges maps each
source node’s named outcomes to target node IDs. Publication and verified read
require exactly one start, reachable nodes, declared end outcomes, and a complete
acyclic ordinary graph. Repetition belongs only to declared bounded scopes.
Each instance and scope has exactly one control owner; a scoped body cannot also
be dispatched as an ordinary graph activity.
Activity ports come from the pinned descriptor, not a kernel business-outcome
switch. Conditions require true, false, and unknown edges. Collections and
forks require complete and blocked; loops require complete, exhausted,
unknown, and failed. A loop evaluates its declared condition after a
completed body traversal. Timer waits use the existing workflow duration ceiling:
1 through 604,800,000 milliseconds (seven days), with a next edge. The same
shared ceiling bounds neutral run duration; the existing duration limit in seconds
is unchanged. Values such as i64::MAX are not useful bounded waits and refuse
publication. Actual timer scheduling must also refuse absolute-deadline overflow
with checked arithmetic before persistence. End nodes name declared workflow outcomes and have no outgoing edge.
Missing or extra ports, unknown targets, ordinary cycles and omitted declarations
refuse publication.
These declarations are not a second scheduler or a dispatch permit. Actual same-owner traversal, resolved host admission, durable results/scopes/timers and restart fences remain under implementation in 004. Test-only data-contract fixtures author explicit control declarations before calling the same publication validator; no implicit graph or old-format runtime fallback exists in production.
Explicit scope output sources (004-2809, internal)
Publication format 11 adds scope_output { scope, field } to the ordinary data
source contract. Save and verified read derive scope schemas before checking
mappings, conditions and workflow returns. Collections expose integer counts,
state, and ordered items; forks expose state and a branches object of
arrival states; loops expose their declared typed carried fields. Unknown scopes,
unknown fields and incompatible types refuse. Collection sources and loop initial
bindings can read earlier scope results. Dependency checks expand a scope source
to every body producer, including all fork branches, so own-scope and cross-scope
cycles refuse. Only explicit loop result bindings cross an iteration boundary.
Resolution receives a separate immutable scope snapshot context, never synthetic activity outputs or root-input substitution. A scope with no settled snapshot is Unknown, not false or a default. An omitted optional carried field is Absent, not null. Settled collection items retain source order, state, named outcome, present output values and explicit absent field names. Failed and skipped items retain their diagnostic or reason instead of fabricated success output. Scope and underlying data provenance remain data, not authority. Pending collection or fork folds cannot produce a settled scope snapshot.
Nested projection and object sources (003 extension)
Two data sources compose native requests from runtime receipts. Bindings, loop and collection inputs, and conditions share them; there are no expressions, functions, defaults or arithmetic.
projection { from, pointer, value_type }reads an RFC 6901 pointer inside oneworkflow_input,activity_outputorscope_outputfield of type object or array. Nested values are opaque in the shallow schema, so the projection declares its type; publication checks it against the target like any other source. At run time a missing path is Absent (a required target then refuses), and a present value of another type is Unknown: a binding refuses and a condition decidesunknown. Provenance is the base field provenance.object { fields }builds an object from named member sources. An Unknown member makes the object Unknown, Absent members are omitted, and provenance is the union of member provenance.
Dependency, self-dependency and collection-body checks expand both variants to
their base sources. A loop result must still be a direct body output. The
variants are additive inside publication format 11: existing publications never
contain them and parse unchanged. Example: a condition compares
{"source":"projection","from":{"source":"activity_output","activity":1,"field":"receipt"},"pointer":"/assessment/decision/outcome","value_type":"string"}
with the constant "accepted". The Designer edits both variants as JSON.
These are source/schema/value contracts, not durable scheduling proof. The single run owner must still check current run/scope/generation and item activation/attempt before publishing a snapshot, persist it, and fence release across restart. Fork arrival-state projection does not invent activity outputs that the join fold has not retained. No runtime dispatch, migration, cutover or external effect is enabled by this slice.
Neutral input projection contracts (003-e678, internal)
A neutral definition may declare input_bindings, keyed by the instance ordinal
in its immutable published vector. Each target field explicitly selects a workflow
input, another instance output field, an explicit scope output field, or a JSON constant. This is a top-level
projection, not an expression language. Save and verified read reject unknown
source/target fields, missing activities, self references, incompatible types and
required targets without a guaranteed source/target default, and ordinary data
dependency cycles (including indirect cycles). Integer data may feed a
number field. Bindings and constants are covered by the publication content pin.
Resolution uses immutable producer snapshots, never completion order. A producer
without a result is unknown and cannot be replaced by a default. A completed
producer may omit an optional field (absent); a target default then applies. A
producer schema default does not guarantee an optional output at this snapshot
boundary, so it cannot satisfy a required target with no target-owned default.
Workflow input defaults are resolved before projection and do supply a guarantee.
Explicit JSON null and empty arrays remain present values: null is accepted only by an explicit null field type, never as an absent
required field, while an empty array remains empty. Null defaults are refused
because the current stored Option<Value> default field uses null for no default;
bind an explicit null instead. Projection
preserves supplied provenance and adds its declared source. Provenance is data,
not authority or evidence of a trusted source.
The root-only admission preflight resolves workflow/constant projections before calling host ports. Upstream-output projections remain unknown without producer results; it cannot admit them by reusing root arguments. This is not an executor, subflow invocation, collection scheduler or live authority proof. Concrete runtime snapshots, every-dispatch checks and sensitive sink admission remain required by 004/005/008. The 003 collection and structured-return contracts are pure data contracts, not proof of their runtime execution. No public route or Designer action is added here.
Closed typed conditions
Named condition contracts share the mapping sources and provenance. Publication
and verified read validate all source fields and operand types. The closed
operators are exists, compare (equal, less, less-or-equal, greater and
greater-or-equal) and array contains. Ordered comparisons accept numbers or
strings only. Scalar numeric comparisons preserve adjacent large integers rather
than rounding both through floating point; mixed integer/number comparisons
compare their numeric value. Other equalities use typed JSON structural equality.
Array membership does not coerce strings to numbers; its elements remain opaque
under the shallow array schema. No code/expression operator is accepted.
Evaluation returns true, false or unknown plus the union of input provenance.
exists is false for a known absent field, unknown for a pending producer, and
true for present null, false, an empty string or an empty collection. Other
operators return unknown for absent or pending operands, never false. Runtime
branch routing and unknown/error handling remain the responsibility of 004; these
internal contracts do not schedule any successor or confer authority.
Bounded collection contracts
Internal neutral definitions declare named collections. Each ForEach binds an
array from a workflow input, a constant or any activity output. It declares the
item type, body instance ordinal, distinct item/index input fields, positive
max_items and max_concurrency (not greater than max_items), empty-input
behavior (complete or blocked) and partial-failure policy (collect or
blocked). Publication checks the source type, constant items and limits, scoped
body ports, conflicting ordinary bindings and ordinary dependency cycles that
include collection sources. One body instance belongs to one collection scope.
Expansion validates the complete array before producing any items. Unknown, absent and null sources are not empty arrays. Duplicate values remain separate items, identified by run, scope, generation and source index. Item/index values retain source provenance. The execution owner must retain that immutable source snapshot across replay; a new traversal has a new generation.
Aggregation folds an immutable result snapshot into source order, never completion order. Pending, completed, failed and skipped items remain explicit. Optional omitted output fields remain absent, not null. Typed output/outcome validation rejects malformed completed items. Foreign run/scope/generation, duplicate item results and out-of-range indices refuse. A missing result leaves the aggregate pending. These are deterministic data contracts, not callback admission or a scheduler: durable activation/attempt fences and join release belong to the execution owner. No API pagination, external service execution or live authority has been proved by these contracts.
Typed loop state and structured returns
A loop contract declares its body instance, positive max_iterations, carried
object schema, initial projections and current-body result projections. Carried
fields are scoped body inputs; ordinary mappings cannot overwrite them. Initial
projections may read workflow data or earlier activity outputs, but not that
loop’s own body. Subsequent state projects only the current body’s outputs, with
required/type validation and provenance retention. State snapshots carry run,
scope, generation and completed-iteration identity. Zero denotes the initial
state; exceeding the declared bound refuses. Persistence, immutable per-iteration
output selection and traversal admission belong to the durable execution owner.
Workflow output_bindings explicitly project the declared structured output
schema. Publication rejects unknown/incompatible sources and unbound required
outputs. The same return resolver serves a root or reusable subflow and retains
field provenance. Data projections do not grant workspace, artifact or credential
rights; the trusted host must check actual references and inherited authority at
every dispatch. No native authority check is claimed by this data contract.
Explicit data references and child context
Typed fields may use workspace_reference, artifact_reference or
credential_reference. Their closed JSON values are respectively
{"reference":"workspace","id":"..."},
{"reference":"artifact","id":"...","revision":"..."} and
{"reference":"credential","id":"..."}. IDs and artifact revisions must be
nonempty. Extra fields (including embedded credential material) refuse. The
reference tag denotes an explicit typed reference, not a generic object cast.
The host resolves these opaque IDs through its existing services. Values and
provenance never establish current access or artifact freshness by themselves.
Reference defaults, constants, projections and returns use the same schema
checks. Only fields explicitly typed as references enter the host’s
ReferenceInputs; an opaque object does not implicitly select a workspace or
credential. This contract does not read any credential store or resolve secrets.
HostRegistry::subflow_context validates resolved inputs and the backend-owned
subflow handler kind, then asks the trusted parent context to derive a child
context. The default implementation refuses rather than silently sharing the
parent. Host implementations must not widen the parent’s effective authority.
Derivation is not a dispatch permit: the execution owner must still run current
host admission at every child dispatch, including actual reference/freshness and
sensitive-sink checks. These are internal interfaces; real native-authority and
revocation proof remains with the implementing adapters.
Neutral fork/join contracts and data demonstration
Named forks declare at least two distinct body instance ordinals, stable branch
names, required/optional outcome policy and positive max_concurrency not greater
than the branch count. A body may target a pinned reusable subflow. Body ownership
cannot overlap another collection, loop or fork scope. All iteration/fork scope
names are unique. Conditions retain their closed true/false/unknown decision
contract; an unknown predicate is never an implicit false branch.
A join snapshot names the exact run, scope, generation and each branch’s current
activation/attempt owner. Every branch must arrive, including optional branches;
required failure/cancellation/skip makes the settled result blocked. Optional
failure remains visible but does not change the configured required outcome.
Identical duplicate arrivals are idempotent; conflicting, foreign or stale
arrivals refuse. This pure fold does not persist or emit a release. The durable
owner must commit join release once across restart and fence callbacks before
invoking it. Named regressions include out-of-order aggregation and
stale_results_cannot_satisfy_a_later_join_snapshot; durable replay/duplicate-release
proof remains with the execution owner.
Settled collections expose typed total, completed, failed, skipped and
state summary fields with scope-result provenance. Pending collections cannot
produce final summaries. complete means all results are known, not that every
item succeeded; conditions can inspect failure counts. Full per-item results and
absent outputs remain in the aggregate rather than being replaced by counts.
data_contract_demo_tests composes a documented list-response projection, pinned
structured identity-subflow return, bounded per-item collection, source-order
aggregate and closed summary condition using real internal functions. The fixture
README records the official source and the failed public API probe. This proves
contract composition only: actual HTTP pagination, scheduler execution, current
native authority and integrated transport behavior remain mandatory in their
implementing layers. No live API or external-write success is claimed.
The current check_dispatch method is root/workflow-input-only preflight, not
per-activity resolved admission. It has no upstream-output or scoped activation
snapshot, so activity-output bindings and required item/index/carried inputs
refuse. Unbound, unscoped activity inputs retain the inherited root-field-name
identity compatibility; this is not explicit mapping proof. The execution owner
must validate each activity’s fully resolved arguments before every actual
dispatch rather than treat whole-publication preflight as an effect permit.
Collection ItemIdentity covers run/scope/generation/index, not activation/attempt;
the durable owner must fence each item’s current activation/attempt before
accepting its result. The fork snapshot’s stronger owner check does not supply
that missing collection runtime fence.
Neutral asynchronous effects and approvals (005)
The internal neutral host port now separates pure effect preparation from invocation, reconciliation and cancellation. The existing owner commits the exact retained publication, descriptor, configuration, resolved arguments, optional subject and full attempt/scope fence as an immutable effect intent. Its digest is the callback correlation. Intent and correlation commit before adapter entry; neither retained intent nor an approval replaces current host admission. Preparation must remain deterministic for the same resolved invocation, including the absolute approval deadline; resumed approval must not regenerate a relative-to-now deadline. Native provider installation and real authority/freshness evidence remain in 008. Public desktop/HTTP/MCP authoring and inspection remain in 015.
An adapter observation is pending with an immutable handle, completed with a schema-validated known result, or uncertain with a diagnostic. Stop evidence is separate. A transport error or invalid completion cannot prove that an external write failed. Such observations leave the effect uncertain, hold conflicting resources and do not supply graph output. Recovery observes the original handle or precommitted correlation; it never reinvokes the operation. An early callback cannot be overwritten by a later pending acknowledgment. Committed results are immutable, and foreign argument digests or attempt/generation fences are refused. A valid owned effect may settle after its graph frame has closed: its result and stop evidence release ownership without advancing or reopening that frame.
Questions bind the exact effect digest and a monotonically increasing revision. The first valid committed answer wins; an expired, stale or already answered question cannot grant approval. A declined or resolved attempt cannot be reopened by a question revision. An approved question that expires while waiting for a resource or dispatch slot fails that branch before adapter entry. Invalid initial host preparation also records a local failure so independent branches can proceed. A question waits only its own branch. Prepared, waiting and uncertain work does not occupy a dispatch permit, but actual calls still obey the scope/root concurrency limits. Independent read-only diagnosis may continue while conflicting mutations remain blocked.
Run-store schema22 adds only a transactionally maintained resource projection of this ledger. Trusted preparation supplies mutation classification and resolved resource keys. Native adapters retain their own permission and ownership checks; the projection is not a replacement sandbox or another queue. Mutation claims commit with dispatch and release only after a validated known result AND proven stop. Cancellation and run expiry can request stop but cannot prove rollback or release. Late stop/result observations remain inspectable on an ended run and cannot reopen its graph. Existing domain-shaped questions and the Git-specific command journal are not called as generic neutral services.
Neutral model ownership (006, implementation in progress)
The kernel can retain a host-pinned named-tool policy and bind the exact original model connection, session and generation to its parent effect. Each original tool call ID names one child effect in the same event ledger and resource projection. Intent commits before service entry; identical duplicates read that retained effect, while changed arguments, names or session generations are refused. The host rechecks current admission before entry. Tools have their own bounded call and concurrency limits and do not create graph activations. A validated parent response remains retained until every owned tool effect has a known stopped result. Recovery observes each effect identity separately, including children that share their parent’s graph-attempt fence.
Coarse workspace evidence captures the host-selected checkout, Git directory and clean baseline. Artifact evidence pins a clean descendant commit/tree and exact regular-file Git blob IDs. Path escapes, symlinks and uncommitted output refuse; an observational scope refuses Git-visible changes. These checks prove committed content, not interception of all shell writes, process termination or withholding credentials. The caller must establish original-process stop independently.
Exact profile/settings and restricted host MCP wiring are implemented internally; native provider installation and original provider-call continuation remain pending. Reopening a kernel tool record and reconciling its write is distinct from resuming the provider’s original open call. A new prompt or model-generated retry does not satisfy that requirement. Native service authority, public neutral transports and cutover remain 008, 015 and 019 respectively. No live model call or native privilege isolation is claimed.
The exact-request adapter now uses the existing ACP manager with a fresh,
per-connection MCP host and fixed --no-tools --no-hooks --bare launch flags.
Its strict request accepts an exact profile, model and effort, literal instructions
and context, the catalogue’s shallow object output schema, bounded context/output
bytes and a whole-request deadline. The only unavailable-model policy is fail;
unknown settings and policies refuse. Model and effort must both be acknowledged
after configuration before the kernel binds the session and sends one prompt.
Complete JSON output must satisfy the declared schema; fences, prefixes, malformed
or oversized output fail without another prompt. The adapter awaits owned ACP
shutdown but does not call transport settlement proof of OS/workspace termination.
The activity entry constructs the narrow host; ordinary ACP connections retain
their existing launch behavior and host catalogue. Original-call recovery remains
open and no provider is installed by this internal adapter.
The model activity entry now constructs its own scoped MCP host. tools/list
contains only the retained named descriptors and strict shallow input schemas;
tools/call never forwards to ordinary TUICommander MCP. Other methods and names,
missing/invalid lowercase SHA-256 tuic/call_id metadata, changed arguments and
stale ACP origins refuse. Correlation uses the stable ID emitted by the runtime’s
durable tool item; the host does not derive a fresh ID from RPC arrival order.
Every call enters the existing kernel effect/admission path and waits on owner
commit notifications for a validated, stopped result from that ledger. Pending
handles are not tool responses. Uncertain original effects return explicit errors
without redispatch.
After restart, the original tool effects reconcile first. Once every owned tool has a stopped, validated ledger result, the model parent can start a new exact configured ACP request containing its original context plus recorded call IDs, arguments, effect IDs and results. A durable continuation event fences the previous session and result digest before prompting; old callbacks cannot write through the replacement session. This closes the interrupted provider turn and continues with a new prompt, rather than resuming an open provider RPC (Boss, 2026-11-11, A2 option B). Active original connections, missing/uncertain results, expired/ended/cancelled parents, stale continuation commands and context overflow refuse. Cancellation never starts a recovery prompt. Named tool admission and run-wide call budgets persist across continuation; native authority is rechecked. This has owned-file/SQLite/ACP fixture evidence, without paid-provider proof.
The restricted coarse entry deterministically returns
restricted_execution_unavailable before any process or session launch. Existing
Git hooks/PATH shims cannot enforce direct privilege withholding. The entry has no
request validation or original-handle reconciliation because it cannot start a
process; native installation belongs to 008. Artifact helpers pin content only and
cannot establish process stop. Individual commit/push/API receipts require explicit
native service operations in 008. This unavailable entry and artifact evidence do
not claim that a confined coarse-agent execution implementation exists.
Installed Jira Cloud activities (011-2a30)
The internal JiraHost implements the existing neutral host port. It uses
plugin_http_fetch_impl and its account authentication, manifest consent,
destination checks and credential redaction. It adds no scheduler, credential
store, IPC command or HTTP route. Composition in 008, Designer authoring in 014
and public neutral transports in 015 remain separate work.
A backend-installed JiraBinding pins its site prefix, plugin, credential/account
reference, project ID and operation in the descriptor. Register each binding’s
descriptor with the catalog and install it under its exact handler in
JiraHost.bindings. The host supplies HttpAuthority; network and write grants
are separate and rechecked before dispatch. An instance cannot change the pinned
metadata. Project writes share one resource key, so issue keys and numeric IDs
cannot bypass mutual exclusion. Cancellation supplies no remote rollback proof.
Each descriptor accepts a request object, parsed as the closed JiraRequest
union; operation must match the installed descriptor. Results are closed
JiraResult values under result. An issue result includes an account-scoped
canonical numeric reference.id, issue key and authoritative fields.
Issue input references contain account and Jira ID or key; cross-account and
cross-project references fail before mutation. Authentication is never a graph
input. These are Jira Cloud REST v3 contracts, not a claim of Data Center parity.
| Operation | Request data | REST and result |
|---|---|---|
lookup | issue reference | GET issue; canonical issue result |
search | JQL predicate, nullable next_page_token, limit 1–100 | POST enhanced search/jql; installed project predicate, typed issues and nullable opaque next token |
create | issue_type_id, fields | Paginated create metadata, POST issue, GET canonical read-back |
update | issue, fields | GET editmeta, PUT settable fields, GET read-back |
comment | issue, plain-text body | POST ADF comment plus original-effect property; typed comment ID |
transitions | issue | GET current transitions with field metadata |
transition | issue, transition_id, target_status_id, fields | Current transition/required-field validation, POST transition, GET status/field read-back |
fields is a closed object: nullable summary, description, labels,
priority_id, assignee_account_id, and a custom map keyed by
customfield_<numeric id>. Omitted custom defaults to empty. Description/body
text becomes an ADF document; it is not interpreted as Markdown. Empty description
clears it. Custom values retain the tenant’s JSON shape and Jira validates those
values. Project/type come from installation/create data; status uses transitions.
Metadata enumerates allowed fields and required create/transition values. Search
returns one bounded page explicitly; callers may feed its next token to the next
activity. Repeated/oversized tokens fail. Metadata and comment observation are
bounded to 20 pages of 100; an exhausted bound is an error. Responses are bounded
to 1 MiB each. There is no extra request/value byte cap; the existing account
HTTP owner retains destination checks and Jira validates service limits.
No request retries automatically. HTTP 429 reports Retry-After without repeating
a possible write. HTTP 204 is a successful empty receipt, followed by authoritative
read-back where needed. Transport errors, unexpected responses or failed read-back
leave the original mutation uncertain in the existing neutral effect ledger.
ReadOnlyServiceObservation identifies service-specific reconciliation, not the
shared HTTP callback protocol. Recovery checks current network authority and
observes the original dispatched effect even when its write grant was revoked:
- Create includes
tuic-effect-<original effect digest>in labels. Reconciliation searches that label within the installed project, requires one match and verifies its label by issue read-back. Zero matches can mean search-index lag and never authorizes another create. Labels must be available in create metadata. - Comment includes the
tuic.workflow.effectproperty. Reconciliation collects numeric IDs from bounded GET comment pages, then reads their properties with POST/rest/api/3/comment/list?expand=properties. This documented POST reads existing comments; it never creates a replacement. Missing, foreign or duplicate IDs stay uncertain; a unique digest is required. - Update and transition observe the desired field values/status. A match proves the requested state, not historical attribution to this particular request. Numeric integer/double representations compare by value. Expanded option objects compare supplied id/value fields, and option arrays match one-to-one regardless of order; ordered document arrays keep their order. A missing or changed state stays uncertain; no PUT or transition is repeated.
classified_issue_create maps the existing typed GitHubIssue snapshot and a
classification-to-issue-type configuration into ordinary request data: title to
summary, source URL/number/classification to description, and labels to labels
with each whitespace character replaced by -. Unknown
classification fails. It does not depend on GitHub trigger binding code or create
a Story root, and classification grants no write authority.
Jira inventory and external evidence limits
The existing plugin owns lookup/detail, enhanced search, create fields/create,
edit-field/update, comment pagination/comment, transitions and Cloud ADF handling
(plugins/jira/{client,provider,query,fields,adf}.js). Rust cannot execute these JS
ports without another platform. The adapter reuses their REST contracts and the
existing Rust plugin/account client. The operation matrix and reuse decisions are
in the 011-2a30 worklog; no required Cloud operation was dropped.
Tests replay scrubbed real response bodies from
plugins/jira/fixtures/cloud.json (recorded 2026-10-27; method/path/status provenance
retained). Constructed faults/property/label/metadata cases are labeled as such.
Authoritative contract references, inspected 2026-11-11: Jira Cloud REST v3
issues,
enhanced search
and comments.
The earlier live plugin report proves the plugin
boundary at its recorded revision, not this new workflow adapter.
No credentials or live writes were supplied/authorized. Live acceptance requires an operator-authorized Cloud account/site, scratch project/type, metadata-required custom fields, and consent for create/update/comment/transition plus read-only lost-response recovery. Natural rate-limit behavior, marker persistence/search visibility, current permissions, tenant validation and the new adapter’s account binding remain explicit live validation gaps. Fixture success does not close them.
Internal GitLab connector slice (012-1981)
The installed gitlab v1 descriptors expose single issue/MR lookup, exact MR
diff_version, exact head pipeline, and a general review_note. Installation
pins the REST v4 root, numeric project and credential reference in the descriptor;
current host read/write grants remain separate. These are internal host adapters,
not new IPC endpoints or an activated trigger. Native composition and transport
publication belong to their respective rework stories.
Diff receipts verify head/base/start and refuse missing/collapsed/too-large file sets. Pipeline receipts check the current MR head pipeline ID and exact SHA/base; failed, canceled or skipped pipelines never return the successful outcome. Notes include the reviewed head/base and original effect digest. The service cannot atomically condition a general note on the current head; this is an artifact-bound comment, not MR approval. A lost response retains the original effect/resources and reconciliation never resends the note. No collection scan or latest-pipeline scheduler is introduced.
HTTP and GitLab clients share the same final settlement policy: an unsuccessful non-mutating read settles as a stopped, failed activity. A write error retains uncertainty because the service may already have committed it.
gitlab/event.rs normalizes issue/MR/pipeline snapshots with original delivery,
installed project and source generation independent of delivery or binding edits.
The installed schema maps these fields into the shared TriggerEvent contract;
the backend admit_gitlab_event facade forwards to neutral admission. The ingress
owner must authenticate the delivery first. Shared bindings own typed mapping,
revision/enablement, durable generation dedup and replay authority. Unknown
merge-base stays absent. See
src-tauri/fixtures/gitlab-workflow/README.md for recorded/documented provenance
and exact live validation gaps. Inline discussion publication and MR approval are
missing and not required by the selected flow.
Bounded correction composition (016-358f, phases A/B)
The internal CorrectionRegion::definition constructor lowers a selected pinned
subflow into an ordinary neutral loop. max_corrections excludes the initial
attempt: zero allows one body, two allow three. Checked addition rejects overflow.
The body contract has immutable context, pinned criteria and carried state inputs, optional
repeat, and an assessed outcome. It returns required state and optional
repeat. True requests another correction, false completes the assessment, and
absent takes the operator branch. Exhaustion also takes the operator branch;
known technical failure has its own exit. An assessment success is not permission
to publish or commit.
RuntimeOwner and RunStore remain the only execution authority. Committed loop admission consumes a correction before dispatch; a failed replacement worker does not refund it. Scope identity follows the retained metanode invocation, independent of worker, head and leaf attempt. Replayed commands return their retained result; old attempt fences cannot complete the replacement. Only the selected body repeats. Issue, workspace and PR creation stay in the parent graph before the metanode. The constructor cannot prove what an arbitrary user-authored body does internally; publication inspection and native service authority still apply to that body.
CorrectionPolicy::assess accepts typed artifact-bound receipts and findings.
Provider/resource/revision identifies a source observation independently of polling
or webhook delivery. A previously consumed batch supplies no new completion.
Each configured criterion needs one current result. Missing, contradictory or
ambiguous results, missing reasons and needs_decision route to operator.
Relevant correct findings or failed checks request correction;
ignore_with_reason retains the rationale and source. Mixed or stale artifact
batches wait for current evidence. advance_artifact clears current review/check
and approval data while preserving consumed sources and historical findings;
previous outputs remain in the event ledger. It never changes the loop budget.
Uncertain observations name the original effect for reconciliation and supply no
completed body or new correction. The existing neutral effect ledger retains
uncertain writes and prevents dependent advancement until observation settles.
The existing workflow_neutral_action exposes
correction_region {region:{selected,max_corrections,criteria:{criteria:[...]}}}.
It returns NeutralReply::CorrectionRegion(CorrectionRegionView) with the same
configuration and generated definition: the selected publication pin, immutable
criteria binding, required inputs/outputs, entry, internal graph and exits.
Normal draft validation/publication still applies. No transport is added.
Designer rendering remains a 014 gap: render this exact DTO, follow its selected
publication through get_publication, and inspect retained scope iteration minus
one for the consumed correction count.
The installed native.correction.assess activity implements the body assessment
contract. It accepts real stopped native.review.change effects from its own run
through 008’s committed-candidate observed_review service. It runs every captured
host-configured check through NativeContext::verify_observed; missing execution
or infrastructure failure cannot become a passing check. The declared criteria
must equal independent_review plus check:<id> for every captured check, and
its digest must match the carried artifact. Nonzero exit requests correction;
review findings request correction; uncertain review takes the operator branch.
The independent review service owns its fresh tool-less session. This adapter
never calls a model or supplies a passing verdict itself.
An artifact is a committed candidate head and tree against a recorded base. Review and checks cover that same candidate, and any tree/head mismatch refuses assessment. The retained 010 source intent pins PR head/base. A newer pending source generation invalidates old completion even before cancellation flush: the kernel fences result consumption in its event transaction. Late effect observations still record stop/receipt evidence and release ownership while refusing graph advancement. A refused old generation must restart through source admission; it cannot approve the new head. Within a retained invocation, changing the carried artifact invalidates evidence without changing its correction budget. No live provider, Designer rendering or scheduler cutover is asserted here.
Neutral trigger authoring uses the same action: trigger_schema {source,kind},
trigger_bindings, save_trigger_binding {expected_revision,draft},
enable_trigger_binding {id,expected_revision,enabled,acknowledged_overlaps} and
preview_trigger_mapping {draft,snapshot}. Schemas come from the installed
source match. Preview returns typed inputs, optional subject and overlapping
binding IDs with exact revisions. Enable requires that current overlap map.
replay_trigger {binding_id,resource,generation,replay_id} uses a string source
generation and requires backend-created owner authority after transport auth;
there is no request grant or replay-enable flag. Replay returns retained trigger
admissions through the existing runtime. Replay owner authentication is checked at the desktop IPC, HTTP or MCP
boundary before the shared service is invoked.
A source snapshot has no workspace reference. A subject field of type
workspace_reference that the mapping leaves unmapped gets the binding’s own
project ({"reference":"workspace","id":<project>}), so a GitHub binding can
start a workflow of native operations, which run only in their bound project.
templates returns the built-in neutral definitions
(src-tauri/src/workflows/templates/). Each has key, name, description,
editor and definition. The Designer opens one as a new unsaved draft; Save,
Publish and the trigger binding are the normal draft actions. The
github-issue-triage template reads the admitted issue (native.issue.read),
gives model.request the receipt text (the issue as JSON: repository, number,
title, body and label names), asks for post_comment and comment, and on true
posts the comment and adds the triaged label (native.issue.effect, each after
its exact approval). On false the run ends skipped and does not change the
issue. Each native.issue.effect approval names its action, the issue and the
content: the comment text or the label name. Bind it with event labeled and filter label for one label, or
events opened+labeled and filter labels for issues that carry the label.
The run’s own label write is a self event and starts no second run.
The github-pr-review template is described in
workflow-trigger-admission.md.
Saving or enabling a neutral binding returns its committed revision. The source poller reads current enabled bindings on its next existing poll cycle; the transport does not own a subscription refresh or start another polling loop.
Native operation provider (008)
Daemon startup installs one NativeHost through NeutralCatalogHost; authoring and execution use the same provider. The native catalog contains versioned workspace and artifact pins, named verification, exact-change review, story transition, commit and local bare repository push operations. Strict request types reject extra caller/capability or receipt fields. The backend binds a captured NativeContext to an existing run; workflow JSON cannot supply caller provenance. Missing bindings after restart refuse dispatch until a trusted backend rebinds the run. Project-only publication context grants no execution rights.
Each dispatch rechecks actual backend session capability state and inherited scope. Verification uses the existing named check runner. Story operations retain the selected backend’s revision/status/actor rules. Commit, push and story changes require separate exact ledger approvals and resource ownership; push additionally requires current Push authority under the captured ceiling. Commit binds the parent and staged tree, without staging or amend. It also requires a stopped, passing native review effect for the same caller/workspace/base/tree/diff digest. Review uses the native staged diff reader and no-tool ACP reviewer; binary or oversized diffs refuse. Push accepts one exact commit/branch ref and a canonical local bare repository, without force, tags or broad ref updates. Known refusals and uncertain native outcomes never become success receipts.
Public starts bind caller-to-run provenance before dispatch. Native GitHub publication requires separate destination/account/action approval. Sandbox evidence covers only its explicitly authorized private repository. Provider installation itself grants no publication authority and performs no migration.
The backend-only native caller is typed: authenticated Owner retains the existing owner authority; Agent carries a real capability-map key and keeps its captured ceiling with fresh revocation checks. Receipt identities distinguish those cases, and story transitions preserve the corresponding native actor. Capture accepts check names only. The installed NativeHost resolves them from backend-installed project verification configuration; unknown names refuse. Graph or transport command definitions never configure that registry. The shared provider bind_run hook refuses by default and NativeHost binds the exact persisted run without reinstalling a provider. Public transport integration remains015 responsibility.
Native GitHub publication
The typed publication.github request selects an account reference, repository, current commit/tree and one action: create a new branch, open a draft PR, comment, close PR, or delete a branch at the expected artifact. Every action requires its own exact ledger approval and current Push authority; authoring/start grants none. The native account resolver must match both the requested account and destination. Native Git uses literal HTTPS destinations, command-only child credentials, bounded execution and exact ref leases: creation cannot replace an existing branch and deletion cannot delete a ref changed to another commit. URL rewrite configuration refuses. API actions reuse the account-aware client and read back the provider objects. PR actions require the approved head artifact in the same repository. PR read-back treats a null body as empty only when the approved body is empty; a differing nonempty body still leaves the publication uncertain. Uncertain writes retain uncertainty; they are not replayed as new writes.
Live evidence is restricted to the explicitly authorized private sandbox test, ignored during unattended runs. It cleans its unique PR/branch even on failure and prints only provider object identifiers. Credentials never enter workflow JSON, receipts, command arguments or token files. Public caller integration remains015.
Recorded private sandbox evidence: the native test created PR8, read back its comment, closed the PR and verified its unique branch was deleted. This is native publication evidence, not public transport or live model-review proof.
Neutral source bindings (010-978f)
The source-neutral binding/preview/admission contract shares the existing run owner and effect ledger. See trigger admission for generation identity, overlap activation, owner replay and GitHub polling limits. Designer and transport consumers belong to 014/015.
Native correction observations
review.change accepts either the staged tree used by commit.create, or an
explicit committed candidate head against base. Both use the same retained
ownership and diff checks and pin the exact reviewed tree. Committed review
observations retain Pass, Findings or Uncertain; only Pass satisfies the staged
commit approval gate. An empty diff records Uncertain with no reviewer session.
Nonempty review uses a fresh tool-less ACP session; its session identifier is
inspection metadata and does not establish authority. The internal one-shot
session field is omitted from the public one-shot response.
Named verification returns a candidate-bound CheckReceipt even for a nonzero command exit. Infrastructure, interruption and changed artifacts refuse instead of becoming successful proof. Approval consumers must require zero explicitly; correction assessment can inspect failed checks and every captured check name.
Scoped roles and pinned story children (020-6471, 022-597e)
The installed configured catalog adds agent.role@1 (host.agent.role@1). It uses the existing mediated ACP adapter and named native tool ledger. Configuration pins role, the exact request profile/model/effort/literal prompt/report schema, runtime, and tools; inputs bind source: {origin, generation, commit, tree} and a workspace subject. Origin/generation are retained source data: the upstream domain adapter must verify their provider identity. They grant no rights. The actual Git artifact is checked before admission. Source PTY profiles require an explicit mediated translation; unavailable/mismatched profiles refuse with no launcher fallback. Reviewer and validator roles require fresh tool-less sessions; native exact-change review remains a separate service and its approval cannot be manufactured from a role report.
The host returns report: {effect, publication, role, source, observed_artifact, identity, report}. The effect contains run/execution/activation/attempt; identity comes from the observed ACP connection/session/generation. The payload is checked against the pinned report schema. native.agent.report.read@1 accepts {report: EffectKey, source} and resolves the stopped original effect in the same run, refusing foreign/stale sources, changed artifacts and incomplete/uncertain results. Current native authority remains mandatory for every tool. Model output cannot choose an ownership envelope or turn a report into publication consent.
save_child_dispatch accepts expected_version, an operation id, an exact publication: PublicationPin, and cohort: {plan, plan_revision, source, stories: [{id, revision}]}. It creates an immutable reusable operation through the existing save/catalog path, using the registered host.story.subflow@1 handler. The child interface must require the cohort and workspace and return receipt from native.story.cohort.observe@1, routing its completed/blocked outcomes directly. Admission checks the selected project’s real story backend, exact plan/source and each existing story revision. The input cohort must equal the saved snapshot; cross-project references cannot widen inherited scope.
Children run as pinned frames in the same run owner, retaining their transitive publications and typed mappings. They do not launch terminals or a second scheduler. The native observation retains its effect identity, ordered cohort and observed stories. It reports completed only when every selected story is Done; otherwise it reports blocked. Lost replies, cancellation, uncertain effects and resource retention use the existing effect ledger and frame joins. No new write is inferred from missing evidence. Ordered cohorts retain order as data; integration_barrier: not_attested and individually blocked integration_obligations (combined artifact, independent batch review and FIX re-entry) explicitly block any claim of combined-artifact critic, independent batch approval or FIX re-entry parity. Those obligations require their own configured graph and evidence.
Controlled implementer writes (2960-d562)
native.workspace.stage@1 is the only write path of a mediated implementer (Boss Q7=A). It is an installed, target-less native operation, so an agent.role binds it as an exact host tool in its ModelToolPolicy. The model gets no shell, PTY, process or broad filesystem privilege.
The request is {files: [{path, content}]}, where content: null deletes a tracked file. Paths are plain workspace-relative paths. The operation refuses an absolute path, .., a .git component, a backslash, a path through a symlink, a repeated path, more than 64 files and more than 4 MiB. It also refuses a workspace that already has unstaged or untracked changes, so foreign dirt is never staged or attributed. It writes and git adds (or git rms) exactly the listed files and returns {base, tree, paths}, where tree is the index tree. Staging is local and is not an approval-gated mutation; a lost reply is not repeated.
The native artifact is HEAD plus the exact index tree when the worktree equals the index and nothing is untracked. With a clean worktree this is the previous clean rule. The role report records the staged tree as observed_artifact, native.review.change {base, tree} reviews it, and native.commit.create commits it after its own exact approval. A later unstaged edit makes the artifact stale. Verification (native.verification.run) stays a separate step on the committed artifact, because the check runner still requires a clean worktree.
Owned native story proposals (021-6e1b)
native.story.create v1 accepts one closed request: review (approved scope
within the run), cap (0–100), proposal (stable key), and story (NewStory).
It requires exact current native effect approval and captured caller/workspace
ownership. The plan must belong to that workspace. It uses the project-selected
story backend’s existing proposal service, including external adapter creation.
The run ledger pins the first cap for each review and atomically reserves each proposal before creation. Reservations count even when the adapter outcome is unknown. Repeated proposals, changed caps and exhausted budgets refuse without another write. The receipt includes the backend story, responsible backend caller, review, proposal and original effect key. Responsibility records proposal ownership; it does not claim or assign the created story. Reconciliation retains the existing native unknown-effect policy; it never repeats creation. Review scope and cap are part of approved graph input, not authority inferred from model text. Coordinators and reviewers share this operation; migration must bind their original policy.
Optional source_story plus source_revision fences the source to the target
plan and current backend version. evidence retains bounded source references.
The full accepted request is included in the receipt. Reconciliation reads the
original reservation and backend proposal mapping without calling creation;
a missing mapping remains uncertain and requires explicit disposition.
Exact-head review publication (024-c9ee)
The existing native.publication.github v1 descriptor accepts the review
action with number, nonempty body and verdict (COMMENT, APPROVE, or
REQUEST_CHANGES). Existing account, workspace, artifact, current Push authority
and exact-effect approval checks apply. The adapter checks the open PR head,
sends the approved commit_id to pulls/{number}/reviews, reads the review back,
and checks the head again. A changed head or divergent read-back after POST is
uncertain, not success or permission to repeat publication. Receipts retain the
review id, URL, exact commit and action. This extends the existing descriptor;
no second GitHub transport or catalog operation is introduced.
Contract: the consumer observes an actual submitted review, not an issue comment.
Authoritative state is the existing effect ledger, native artifact and GitHub
review read-back. GitHub API access and review permission are external
prerequisites; own-PR approvals may be rejected by GitHub. The affected consumer
is pr_review; legacy migration remains separate. No live review proof is
claimed without command-scoped credentials and the authorized sandbox.
A review request also includes base and review (the retained native review
EffectKey in the same run). Its exact committed artifact, caller and workspace
must match, its independent reviewer session must exist, and its body must equal
the retained review body. APPROVE requires Pass; REQUEST_CHANGES requires Findings. The review.change and review.bounded receipts include their own effect key, so a graph binds the review into this action without caller-supplied keys; the consumer still checks the key against the retained effect.
mark_ready {number} separately verifies an open draft PR and read-back of the
same node id, head and non-draft state. Complete source-template graph conversion remains a migration obligation; these
native actions do not claim legacy template conversion.
A converted publication may retain source_intent (push, create_draft_pr,
mark_ready); admission rejects any mismatch with its explicit native action.
Existing requests without this optional field keep their behavior. Trigger-started
review/readiness effects resolve their source from the retained trigger request,
require the current resource-owning run and generation, and recheck before issuing
a success receipt. Receipts include source_generation when source-bound. A
changed source after publication is uncertain. The converter still owns building
complete graphs and supplying pinned target data; this native action grants none.
Source-bound issue operations (023-026f)
The native catalog includes native.issue.read and native.issue.effect version 1.
Both use the existing workspace subject and {request: ...} / {receipt: ...}
contract. Read derives the issue from the run’s retained trigger receipt and
resolves the workspace’s installed GitHub account. Its receipt contains the source
pin and current issue. Graph JSON and labels cannot create source ownership.
An issue effect selects one comment body or one additive label. The source pin contains the admission receipt, account, repository, issue number, generation and requirements digest. Each write rechecks the run-owned admission, current retained generation and live open issue requirements, then exact effect approval and current Push authority under the captured caller ceiling. Issue resources serialize writes across workspaces sharing an account/repository/number. A lost or malformed write reply remains uncertain; reconciliation never posts it again. This operation does not install an intake trigger or transfer ownership from the old scheduler.
native.issue.triage validates a stopped, scoped accepted/rejected/needs-input
report against the same source and exact profile/model/effort/instructions. It
re-reads requirements after evaluation. Policy labels and the NeedsInput comment
choice are retained with that verdict. Semantic issue.effect variants cover
rejection/question comments, accepted/rejected labels and original-child
evidence/status comments. These variants consume actual settled triage or child
receipts; labels or a caller-written verdict cannot replace that evidence.
native.issue.handoff accepts only an accepted triage effect from the same intake
and a child publication already in the retained project closure. It delegates to
one installed child owner keyed by the parent effect. Running children keep the
parent effect pending; observation/cancellation must return the same source,
triage, publication and child identity, without calling dispatch again.
The scoped evaluator and child owner enter through the backend-only
IssueServices port, receiving the retained native caller binding.
NativeHost::install installs the production owner. Its triage runs one turn
on the shared mediated model path (run_request, the path agent.role uses)
with the exact IssueProfile: the profile must equal the configured ego ACP
profile, and model, effort and instructions are pinned. The triage effect is
therefore prepared as a tool-less model parent (empty tool policy, no
resources), and its model session identity is bound to that effect. The
production owner never starts a child: handoff, observation and cancellation
refuse with a conversion blocker. Converted issue graphs compose
native.story.create and the pinned host.story.subflow child dispatch
directly. Tests may install a scripted owner to prove the original-child
lifecycle projection. The protocol fixture substitutes only the model process;
live model execution remains unproved.
Native GitHub publication keeps its approved literal HTTPS destination and token through command-scoped identity rewrites, overriding host-wide Git URL rewrites without modifying saved configuration. Competing exact rewrites refuse; artifact, approval and ref lease checks still apply.
Retained review and correction policy composition
native.review.bounded v1 pins {policy:{scope,evidence}} in activity config.
evidence uses the existing camelCase EvidencePolicy fields. Each nonempty native
review spends one durable run/scope admission immediately before the reviewer is
entered; lost replies cannot re-enter that effect. Policy-bound reviewer/validator
agent.role activities share that same budget and emit a retained exhaustion
marker before opening a replacement session. Separate native and role reviews
cost separate admissions. Restart, retry, new candidate and replacement identity
do not replenish maxReviews. Empty diffs supply no independent approval.
native.correction.policy.assess v1 consumes the existing context, criteria and
state plus the whole retained agent.role report output and optional original
story proposal effect keys. It resolves reports and proposals from stopped native
effects, checks the exact source generation/candidate/requirements, and classifies
findings as immediate correction, receipt-backed separate work, accepted risk with
reason, or operator decision. It retains the existing independent native review
and every host-configured verification floor. Model proof metadata cannot grant
RED, strict Clippy or native-target proof: such extra requirements remain operator
work until their owning proof bindings are supplied. accounting reports review
admissions, rejected reviews, corrections after the initial attempt, check attempts
and proposal effects separately. Exhaustion gives absent repeat, the ordinary
loop’s operator route; it never grants success or consent.
The shared correction_policy_region {region:{region,policy}} action inspects the
selected same-project publication and transitive pins, requires bound reviewer and
assessment policies, binds a source role output, rejects uncounted native reviews,
and refuses state outputs bypassing the assessment. It lowers through the existing
correction region: max_corrections equals maxRepairs, total body traversals are
N+1. Normal draft/publication admission, immutable prompts/handlers/subflow pins,
owned effects, cancellation and original-effect reconciliation still apply. This
is an additive backend contract, not template migration or deployment evidence.
Policy assessments journal each configured check admission and its actual receipt under the original assessment effect. Refresh/reopen reuses the retained receipt without another process; a missing reply is uncertain and requires original-attempt reconciliation. Check attempts include this journal and standalone native verification effects, independently of correction spending.
Operator decisions use the existing effect ledger and ordinary pinned edges; typed native bindings keep resume, closure, release consent and effect approval independent.
Directory-only scheduled text workflows
Scheduled neutral bindings reuse the automation tick and trigger receipts. The
installed model accepts literal text input; inbox.approval@1 waits for the
existing exact effect Answer and returns approved: true. These activities use
backend caller scope without requiring a Git checkout. Native repository
operations retain their Git scope requirement. See scheduled starts.
Ledger-selected neutral plan batches
The native story.batch.pending operation accepts {cohort, limit} (1-128)
and returns {cohort, members}. It selects only unstarted members of the same
retained run/plan cohort, or its armed FIX owner alone. Each member carries the
unchanged admission cohort and a current-revision single-story cohort for child
admission. The original effect retains its selection receipt for reconciliation.
The proposed seeded-plan composition configures a limit of eight, a sequential collection,
one pinned combined-artifact reviewer and an eight-round LoopContract; these
limits are not global engine rules. The verdict receipt includes repeat for
ordinary typed loop-carried data.
Internal structured script activity
The staged neutral adapter is run/neutral_script.rs. A trusted host registers
host.script@1 as a reusable Script handler with its own current admission
adapter. Registration describes availability; it grants no execution rights.
The installed native provider registers that handler and dispatches saved script
targets through the same owned-process adapter. A production script_descriptor
constructor and the protocol fixtures share policy/target construction. Caller
binding requires an authenticated owner or an agent with captured and current
Operator authority. Public starts bind that backend caller before dispatch. Existing Designer
forms are not changed by this adapter.
A custom activity uses an ordinary versioned ActivityDescriptor, with config,
input, optional subject and output schemas, named outcomes and supported
execution policies. ReusableTarget::Script pins the existing version 1 inline
interpreter/script invocation in that descriptor. Resolved inputs cannot select
another executable. This pins invocation bytes, not the installed interpreter’s
bytes or an external file’s future contents.
Configuration
The descriptor’s config schema declares a required object field script, often
with a default. Other config fields use the same generic schema. The script
object has these required fields; unknown fields are refused:
| Field | Contract |
|---|---|
version | 1 |
timeout_secs | 1–86400, covers owned process execution |
input_bytes | 1–1048576, bounds serialized request before entry |
stdout_bytes, stderr_bytes | 1–1048575 each; larger captures fail |
artifact_limit | 0–64 named artifact output references |
resources | Up to 16 resolved resource names, each at most 4096 bytes |
environment_refs, secret_refs | Combined maximum 32 environment-name-to-daemon-reference mappings; no literal values, no overlapping destinations |
mutation | Declares effect semantics, never a permission grant |
retry | "never"; no automatic replay or inferred idempotency |
reconciliation | {"type":"read_only"} or {"type":"manual","procedure":"…"}; mutations require a nonempty procedure and owned resources |
output | {"type":"structured"} or explicit {"type":"exit_status","outcome":"…"} |
The neutral ledger claims resources and applies concurrency limits. There is no second queue or scheduler. Resource limits here bound named claims and artifact references, not OS CPU/RAM quotas or a sandbox. The process executor retains at most 1 MiB per stream while draining it; the declared output budgets decide whether the result can be accepted, rather than stopping a pipe at that byte. The timeout stops the owned process tree. At most 1 MiB of serialized stdin and 2 MiB of captured stream bytes are retained before JSON parsing/redaction.
Environment references resolve immediately before entry and have nonempty values of at most 16384 bytes. The process starts with the command executor’s existing limited daemon environment, execution PATH and explicit references. Only resolved secret-reference values use the shared capture redactor; ordinary environment-reference values remain unchanged in results and diagnostics. Neither reference map places resolved values in requests. The host supplies the working directory and private input directory; graph inputs do not bind either path. The private stdin snapshot lives until stop and reap and is then removed.
Request and result
Stdin contains one UTF-8 JSON request:
{
"version": 1,
"identity": {
"fence": {
"run": "run-id", "execution": "execution-id",
"activation": 1, "attempt": 1, "scope": null
},
"digest": "retained-effect-digest"
},
"config": {},
"inputs": {},
"subject": null
}
The actual config includes the resolved script policy and descriptor defaults.
identity is the exact retained EffectKey, including a scoped fence when present.
The neutral owner commits preparation and dispatch before the process enters.
No script owns successor selection, retries, approval or the outer workflow.
Structured stdout contains exactly one result object:
{
"version": 1,
"identity": {
"fence": {
"run": "run-id", "execution": "execution-id",
"activation": 1, "attempt": 1, "scope": null
},
"digest": "retained-effect-digest"
},
"outcome": "ok",
"data": {"count": 7},
"artifacts": {
"report": {"reference": "artifact", "id": "report-id", "revision": "r1"}
}
}
Version and the full identity must match. Outcomes and output fields must be declared. Artifact entries are named output ports with typed artifact references; they cannot duplicate data fields. The merged fields pass the descriptor’s typed output schema before reaching NeutralExecution. JSON null, arrays and nested objects stay JSON values. Artifact reference syntax is checked; actual artifact existence/freshness remains the owning host service’s responsibility.
Exit zero with missing, malformed, foreign, wrong-shaped or oversized structured output is a protocol failure. Stderr remains a separate diagnostic string and is never parsed as result data. Explicit exit-status mode synthesizes an empty-data result for its declared outcome after exit zero; required outputs must therefore have defaults or be absent. It still enforces bounds and process stop.
Uncertainty and cancellation
For a read-only activity, rejected output or failed execution yields a failed activity. For a mutation, rejected/lost output, nonzero exit, timeout or cancelled execution yields uncertainty, with the actual stop flag recorded separately. A pre-entry refusal can prove no process started and is a known failed activity. A failure of owned process-tree stop is uncertain even for a read-only command.
Reconciliation only inspects retained observation/identity and returns the original correlation plus the declared procedure. It never invokes the script. Without original completion evidence, manual effect reconciliation is required; no adapter automatically retries or claims rollback. Cancellation signals the existing per-effect owned-process registry; signalling alone is not stop proof. The original worker independently reports stop when the executor returns. Uncertain mutations retain the neutral ledger’s conflicting resource claims even when the process is stopped. No process-local handle is used as restart proof.
The published descriptor is renderer input through the generic catalog contract. Designer visual proof for a custom script is inherited by story 014-5d73, which owns neutral catalog rendering. This adapter does not add a per-script form or a kernel node kind.
Renderer handoff: the captured custom descriptor
comes from the published backend serializer. The targeted Rust test
published_custom_script_descriptor_matches_shared_renderer_fixture checks
that its complete wire value still matches. Capture provenance accompanies the
fixture. Story 014 owns its rendering and visual verification.
Telegram workflow connector (013-66b3)
The installed Telegram host provides version-1 telegram.send, telegram.update
and telegram.reply descriptors. telegram_host(bot_alias) returns the host and
its descriptors map. Host composition registers these pins and handlers with the
same neutral owner. Installation remains with 008; public execution remains with
015. This slice does not enable a new public command or change the peer tool.
Support inventory
| Operation | Existing integration | Workflow delivery |
|---|---|---|
| Notification | Peer and automation sendMessage through Outbound | One bounded send, retained notification/effect and message reference |
| Text update | BotApi request client; no installed workflow activity | editMessageText for exact bot/chat/message, with keyboard replacement |
| Message reply | Volatile peer/request correlation | sendMessage with exact reply_parameters, no fallback to unrelated send |
| Button decision | Current message handles, native peer mail | Durable action reference and exact effect/question answer transaction |
| Callback acknowledgment | answerCallbackQuery through Outbound | Same client, once after the durable decision |
| Authentication and polling | Existing Telegram configuration and sole polling owner | Reused; no workflow token value, second poller or credential store |
| Uncertain send | Existing automation claim | Neutral effect remains uncertain; no send replay |
Typed values and ownership
Inputs are chat (private chat integer), text (1..4096 UTF-16 units), optional
message and actions (default empty). A message is
{bot, chat, message}. Send requires no message; update and reply require one for
the same bot and chat. Output notification is {effect, message} with the exact
precommitted send EffectKey and the returned message reference. Long text fails
before the request; one activity never becomes several partly delivered sends.
Each action is {effect, revision, approved, label}. effect is the full target
EffectKey, including its attempt fence and invocation/preparation digest. It binds
resolved arguments and subject. The target can be a different run: an operator
notification can be composed after an existing wait is prepared. The host that
creates that notification obtains references from the retained wait; text or a
model label does not create approval authority.
Connector metadata pins the bot alias, operation, credential reference and resource schema with the descriptor. Instances cannot replace it. Current bot configuration and authorized chat are checked during admission and again by the existing serialized Telegram worker before its BotApi call. The resource key serializes workflow mutations per bot/chat. The token stays in the existing private Telegram configuration and is read only by BotApi.
Durable callbacks
Callback data is 63 ASCII bytes: a notification-run UUID and a 112-bit digest of that run, the full target EffectKey, question revision and boolean decision. The full action is retained in the send invocation, not in a callback database. On input the current Telegram worker checks its existing private-chat authorization, sender, accessible message and callback ID. It routes workflow callbacks before volatile peer selection, then the current workflow owner replays the notification run and checks its committed message receipt. It answers the target via the same EffectCommand::Answer transaction as other approval consumers.
Wrong bot/chat/message, stale revisions, changed arguments/subject and duplicate answers do not select a new wait. Deadlines and competing answers remain guarded by the shared owner transaction. Restart needs the ledger and existing Telegram configuration; no live peer, PTY or agent registration is required. Receipt loss blocks the decision rather than guessing which message was sent. Undecidable taps are consumed as rejected, with best-effort acknowledgment when current Telegram configuration permits it. Missing executor/receipt, invalid policy and ack failures cannot poison the polling cursor or starve later messages. Acknowledgment failure does not undo or repeat consent.
External assumptions and validation gaps
Contract: Telegram Bot API, version 10.4
(2026-11-09), retrieved 2026-11-11: sendMessage, editMessageText,
ReplyParameters, Message, CallbackQuery, InlineKeyboardButton and
answerCallbackQuery. The fixture telegram/fixtures/workflow-contract.json
contains synthetic schema examples with provenance. It is not a live capture.
The existing public webhook fixture retains its separate recorded provenance.
The API supplies no idempotent send key or general getMessage lookup. After a
lost acknowledgment, recovery retains uncertainty and performs no network call.
A retained original-service receipt/operator investigation is required; retrying a
run is not evidence that the first send failed. Rate limits and protocol errors
also never cause this adapter to resend.
No bot token, authorized destination or permission for external writes was supplied. Live send/update/reply, callback acknowledgment, real-client rendering and a real restart remain unverified. They require Boss to configure a bot and private chat, authorize the test, install the composed host, then check one send, one edit, one reply and one exact question before and after restart. No synthetic response is claimed as success against Telegram.
PTY Management
Claude restore and terminal launch preparation reuse the structured launch status-settings builder (agent_hook_launch::augment_launch). session_resume::prepare_shell_launch_args decodes retained Claude shell words for option detection, preserves their original shell spelling, and quotes only appended hook argv, including the generated settings path; both resume and the terminal-preparation IPC/HTTP command use this boundary. Absolute discovered executables therefore do not depend on the interactive shell function for state hooks. Explicit settings, --bare, administrative verbs and the native-status opt-out remain authoritative (#2858-2b1c).
Codex trusted native tool receipts use codex-tool OSC frames scoped to the existing exact session binding and current turn. Tool activity preserves open human waits; native user-input questions use the shared parsed-question accumulator and both existing desktop and HTTP/WS event paths. Matching results and terminal lifecycle events retract native question waits. Permission ownership remains outside this adapter until the CLI exposes it (#2695-41da).
Question text recovery (#2633-cbd3): agent_question::enrich runs in session_state_with_shell only while awaiting_input is already set for a Claude or Codex terminal. The PTY reader publishes the hook owner’s open request id as SessionState.wait_request (never serialized). A hook question that carried text keeps it. Otherwise chat_view::transcript_question tails the exact transcript (Claude <config>/sessions/<pid>.json, Codex validated hook binding; never the newest-file heuristic) into a bounded ledger. Claude counts only user/assistant rows of its own sessionId, because the api-request-blob row replays an answered call. Codex reads request_user_input function_call and function_call_output rows and the task_started/task_complete/turn_aborted markers. Settled ids never reopen; two open calls without a request id give nothing. ChatViews::invalidate (binding revocation, exit) drops the ledger. The source adds no awaiting signal and no retraction path.
Structured question cards (#2634-ea5b): the hook owners keep the normalized payload of the request they hold open (agent_hook_payload::QuestionCard): ClaudeHooks for AskUserQuestion/ExitPlanMode, CodexTools for request_user_input, and pty/ego_events.rs for ego OSC 7770;agent-event=<base64> modal_open frames (version 1, 16 KiB cap, current native session only; ego coarse state= frames stay the wait authority). ChunkProcessor::publish_wait writes wait_request and wait_card (both serde skip) on change. agent_hook_payload::apply in session_state_with_shell copies the card to the serialized question_card only while awaiting_input and wait_request == card.request_id; it sets question_text from the card when no screen dialog exists and otherwise adds header, question_index, question_count and missing option hints to choice_prompt. Native keys stay screen-derived. Retraction: PostToolUse, the decline screen (now also User rejected Claude's plan, which calls ClaudeHooks::settle_question), Claude state=idle, ego modal_end/turn_end/session_end, OSC 133 A (shell return) and the existing awaiting clears, which also drop wait_card. Retired ids never reopen. Fixtures: fixtures/agent_hook_payload/ (native hook stdin) and fixtures/agent_prompts/*-2634.tcap.
Tool readout (#2636-5551): each native owner keeps an agent_tool_readout::ToolReadout of its live calls by native id — ClaudeHooks (PreToolUse tool_name; PostToolUse/PostToolUseFailure end), CodexTools (bound turn only), GrokHooks (camelCase toolName; post/failure/permission_denied end), EgoEvents (tool_start data.label; tool_end). Pi and OpenCode write OSC 7770;agent-tool=<TUIC_SESSION>:<base64 {"event":"start"|"end","id","name"}> from the managed extension/plugin; ChunkProcessor.agent_tools takes it only for agent type pi/opencode and the matching owner. An end removes only its own id and retires it, so a late end or a repeated start cannot change a newer call. Coarse state=idle|prompt (retire_tools), turn/session end, interrupt and OSC 133 A clear all. Labels drop control characters, collapse whitespace and keep 64 characters; at most 16 live calls per owner. ChunkProcessor::publish_tool emits tool-activity {name} only on change; the accumulator sets SessionState.current_tool, which PtyExit clears and session_state_with_shell hides while the shell is idle. Metadata only: it never changes shell or agent state. Fixtures: fixtures/agent_tool_readout/ (ego 0.4.3 frames).
Pi event channel (#2994-a1d0): the managed Pi extension also writes OSC 7770;pi-event=<TUIC_SESSION>:<base64 JSON {"kind":…}>. It is a generic typed channel: each kind is one kind of pi data, and TUIC ignores a kind it does not know. ChunkProcessor passes it to provider_quota::pi::receive_event only for agent type pi and the matching owner; frames above 8 KiB are dropped. The first kind, provider_response, carries provider (ctx.model.provider), status, headers and the agent_dir/home that name the pi credential. Both sides keep only provider_quota::pi::QUOTA_HEADERS (an allow-list; the extension source is generated from it) with values of at most 64 characters, so no auth header can cross. The frame binds the session to pi:<provider>:<agent dir> and stores the windows as a passive quota. Metadata only: it never changes shell or agent state. Fixture: fixtures/agent_prompts/pi-provider-response-2994.osc.
Terminal protocol replies
The backend answers terminal queries through the session’s shared PTY writer.
On Unix it checks live ICANON on the PTY master before writing: canonical
input would echo the reply and hold it until a newline. Replies seen in that
mode stay in a session FIFO instead of being discarded. While replies remain
queued, the frame ticker retries them every 16 ms before its dirty-frame and
subscriber checks, so a child that silently switches to raw mode can receive
them in a hidden terminal. With no pending reply or other work, it parks.
The interval is a scheduling target, not a wall-clock guarantee. New replies
drain behind older replies under the same queue lock. Closing the session
discards its queue. Cbreak mode remains readable even with ECHO set.
This retry starts after query parsing. A query held by secret-prefix masking has not reached this queue; that separate delay is tracked in story 2681-9810.
Stable TUIC_SESSION identities are attached at spawn. If the live association
is missing when a bridge reconnects, MCP identity attachment repairs it from
one uniquely matching foreground process environment. Session-list consumers
use the repaired association for parent-child routing; they do not infer it
from terminal names or working directories.
On Unix, spawn binding also sets TUIC_SOCKET to the socket recorded after
this server binds its IPC listener. Named instances, the default instance, and
collision fallback sockets use this same path, so child agent bridges reach
the spawning server even when the parent environment names another socket.
Before the listener binds, no socket override is injected. Windows continues
to use the shared named-pipe transport.
Module: src-tauri/src/pty.rs
Manages pseudo-terminal sessions for all terminal tabs in the application.
Final provider failures
ApiError accumulates in SessionState.last_error, independent of question/awaiting state. Idle and completion output do not retract it. Both desktop and browser snapshot consumers render this value as Error. Native ego final-failure notifications are lifecycle receipts and bypass startup/resize history suppression; provider recovery snapshots remain presentation-only. See Output parser for source-backed formats and retry policy.
Frame receipts and shared IPC delays
Each session has its own frame ticker and desktop receipt gate. A closed gate stops ordinary desktop frames for that session, not another session’s input or frames. Browser grid watchers have independent delivery even when the desktop gate is closed. The visible frontend acknowledges receipt before decoding and schedules canvas painting separately; an acknowledgement is not a paint receipt.
The 500 ms gate warning reports a missing receipt, not its cause. Delayed WebView callbacks, IPC dispatch or acknowledgement delivery can all leave the gate closed. Native IPC dispatch is shared across sessions: blocking filesystem work there can delay their input dispatch and frame receipts together. Agent session discovery therefore uses the blocking pool on both IPC and HTTP. See Command threading for the retained sample and regression evidence. This does not establish native keyboard-to-paint timing or attribute every historical stall.
Bounded input and teardown
Raw desktop, HTTP, WebSocket and MCP input runs on the blocking pool. The caller waits at most two seconds, then receives an uncertain-delivery error (WebSocket input closes its connection). A kernel write already in progress can still complete; do not retry it automatically. Closing the session remains available.
Close never takes the PTY writer mutex or writes Ctrl-C into a potentially full
terminal. On Unix it signals the owned foreground process group with SIGINT,
then retains the 100ms grace and 100ms force-kill wait. On Windows it terminates
the owned child because ConPTY has no portable out-of-band Ctrl-C operation.
All three exit waits share the same bounded poller. If the OS cannot supply the
child status, the poller logs the error and returns instead of retrying forever.
For example, ECHILD after another waiter reaps a child cannot block the
sequential desktop quit cleanup. Teardown does not invent an exit code when the
status is unavailable.
Identity loss during replacement
A restored tab reuses its saved tuicSession. If reconnect falls back to a
fresh PTY while the original remains alive, bind_pty_identity assigns that
identity to the replacement. Closing the replacement removes the sole binding;
the original process still carries TUIC_SESSION, but its session row has none.
The next MCP attachment repairs this association from the surviving process.
replacement_pty_cleanup_reconnect_restores_surviving_parent_identity reproduces
this lifecycle through spawn binding, cleanup, reconnect and session publication.
It fails on the pre-repair revision 1137eeb6f. This proves a reachable removal
path, not that this sequence caused the historical incident in story 1673.
Agent return to the shell
The backend foreground observation transition owns exit cleanup for desktop,
browser and headless clients. When an observed agent identity is revoked, it
clears agent_intent and current_task. If the agent left the alternate screen
active, the same transition flushes buffered synchronized output and restores the
primary grid with display-only exit sequences. It marks the frame ticker dirty;
HTTP terminal-line reads use the restored grid without a mounted desktop view.
No recovery sequence is written to PTY stdin. A stale foreground observation,
an unobserved startup preset, or a temporary helper does not trigger cleanup.
HTTP log snapshots and log-WebSocket polls apply agent screen trimming and
input_line extraction only while the shared session state has an active agent
identity. After confirmed shell return, retained agent rows are history: they
cannot hide newer shell output or populate the mobile composer. Both transports
use the same screen projection; no second terminal emulator is involved.
Session Lifecycle
create_pty() / create_pty_with_worktree()
│
├── Resolve shell (platform default or user override)
├── Build shell command via portable-pty CommandBuilder
├── Spawn PTY pair (master + child process)
├── Store PtySession in AppState.sessions (DashMap)
├── Create OutputRingBuffer for MCP access
├── Spawn reader thread (background, non-blocking)
│
▼
Session Active: write_pty() / resize_pty() / pause_pty() / resume_pty()
│
▼
close_pty(cleanup_worktree)
├── Remove session from DashMap
├── Kill child process
├── Remove output buffer
└── Optionally remove associated git worktree
The lossless session-state queue captures whether each PTY event belongs to a
parented session before live teardown removes session_parent. Question and
exit Web Push use that captured ancestry and the current host notification
setting. Muted events do not reserve the per-session push budget. This metadata
is internal to the queue; IPC, SSE and WebSocket event payloads stay unchanged.
Each session may also carry an orchestrator-owned pty_description, separate
from the last user prompt captured by input-line bookkeeping. MCP spawn and
input actions update it through pty-description-changed; desktop and browser
clients render it together with the last prompt above the terminal.
The idle-close task considers only managed child PTYs with an idle or completed
agent state. After the configured per-agent delay it sends the parent an
idle_timeout lifecycle notice and closes through the normal session-close
path without removing the worktree. Activity restarts the window; unread mail,
background work, a live detached runner, a failed background wake, and keep-open
disable closure while they remain present.
The five-second idle sweep reads in-memory state first and requests a process
inventory only when an eligible child’s delay has expired. A failed inventory
defers closure; a panicking sweep logs the error and restarts its timer state on
the next tick.
Tauri Commands
Session Creation
| Command | Description |
|---|---|
create_pty(config: PtyConfig) | Spawn a new PTY session. Returns session ID. |
create_pty_with_worktree(pty_config, worktree_config) | Create worktree + spawn PTY in it. Returns WorktreeResult. |
Production spawn sites share pty::spawn_pty_pair_with_retry and its async
wrapper. Only explicitly classified PTY allocation failures (for example OS
resource exhaustion or an interrupted/would-block allocation) receive the
bounded three-attempt, 100/200 ms backoff. Once a PTY pair exists, command spawn
runs exactly once: invalid binaries, cwd, and permission failures return
immediately. Async Tauri and HTTP entry points run allocation and backoff on
Tokio’s blocking pool; synchronous internal callers retain the same bounded
policy. Each site still owns its justified command/env/dimension assembly.
The HTTP session spawn checks a supplied cwd before PTY allocation: on some
platforms the PTY library returns a session even when the child later fails to
enter the directory, leaving a blank terminal. A missing or non-directory cwd
returns 400 and does not enter the session map.
Session Control
Session removal polls the child once and releases the PTY handles immediately.
If the child has not terminated yet, a separate waiter owns its child handle
until wait() reaps it, without holding session or map locks. Reader EOF does
not settle a managed task before that wait returns: the waiter publishes the
actual exit code (or 128 + signal) to the task and parent exit notification.
Only an observed zero exit completes a task; an unavailable status fails it.
The task and parent link are registered before its reader starts.
Ordinary post-mortem buffers expire through the five-minute tombstone sweeper.
A pending exit wait or an unexpired managed task keeps its diagnostics readable
through session action=output. Managed diagnostics use the existing 24-hour,
process-local task collection window, even if the parent reads them earlier.
On Linux with glibc, releasing terminal payloads also calls malloc_trim(0)
after the owners and map guards are dropped. The expiry sweeper trims once per
batch that actually releases payloads. This returns unused scrollback pages
that glibc thread arenas otherwise keep resident, without changing live grids
or the process-wide arena limit. Other platforms and libcs keep their allocator
behavior.
| Command | Description |
|---|---|
write_pty(session_id, data) | Write data (user input) to the PTY. Raises the calling thread to QOS_CLASS_USER_INTERACTIVE on macOS for the duration of the write and restores the previous class on the way out, so a keystroke is not scheduled behind background work on a pool thread TUIC only borrowed. |
resize_pty(session_id, rows, cols) | Resize the PTY terminal dimensions. async: the reflow it triggers is proportional to scrollback and runs on the blocking pool (resize_session_off_thread), never on the IPC thread. The HTTP route takes the same path. Several viewers share one PTY and the last resize wins. Each change is logged at debug level as PTY resize applied with origin (ipc, http, mcp), the previous size and child_rows/child_cols (TIOCGWINSZ on the master, the size the child reads; on Windows ConPTY it is the cached size that was just set). A same-size request logs PTY resize no-op. The frontend logs every request as the diagnostic entry resize_pty request <caller> <rows>x<cols> with the viewer and the measured box, only while perfDebug is on. |
pause_pty(session_id) | Pause the reader thread (stops output emission). |
resume_pty(session_id) | Resume the reader thread. |
close_pty(session_id, cleanup_worktree) | Close PTY and optionally remove worktree. |
Monitoring
Foreground-agent exit or an observed agent-type change also retires the terminal’s volatile Telegram registration lifetime synchronously. A restarted agent using the same terminal and MCP identity must opt in again, even if the Telegram worker was busy during the transition. Unrecognized non-shell probes retain the previous identity and do not revoke registration.
| Command | Description |
|---|---|
get_orchestrator_stats() | Active/max/available session counts. |
get_session_metrics() | Total spawned, failed, bytes emitted, pauses. |
can_spawn_session() | Check if under MAX_CONCURRENT_SESSIONS (50). |
list_active_sessions() | List all sessions with cwd and worktree info. |
list_worktrees() | List all managed worktrees. |
get_process_stats() | CPU% and RSS for TUIC + all child process trees (desktop Tauri command). |
collect_process_stats(state) | Same logic, callable from HTTP routes and MCP tools. |
Reader Thread
Each session spawns a dedicated reader thread that reads from the PTY master fd:
#![allow(unused)]
fn main() {
spawn_reader_thread(reader, paused, session_id, state, tuic_session)
}
Readers without an explicit identity resolve it from the live PTY binding before
processing output. This includes HTTP agent spawns, MCP agent spawns and generic
HTTP shell sessions. The identity matches the inherited TUIC_SESSION and the
session-created event, including a restored identity that differs from the PTY
key. Native Codex hook ownership checks remain exact; an unbound reader does not
accept a self-announced owner.
Processing pipeline per read:
- Read raw bytes from PTY master (up to 64KB buffer for natural burst batching)
- Strip Kitty keyboard protocol sequences (non-printable noise for consumers)
- Push through
Utf8ReadBuffer— accumulates bytes until valid UTF-8 boundary, returns safe string - Push through
EscapeAwareBuffer— holds incomplete ANSI escape sequences (CSI, OSC, etc.) - Feed into
VtLogBufferfor VT100-aware changed-row parsing and primary-screen log extraction (mobile/MCP consumers) - Write to
OutputRingBuffer(2 MB circular buffer for MCP access —OUTPUT_RING_BUFFER_CAPACITY) - Serialize parsed events once with
serde_json::to_value— reused for both Tauri IPC and event bus (avoids double serialization) - Broadcast to WebSocket clients (if any connected)
- Assemble the lines of the chunk and match them against the compiled plugin OutputWatchers (
crates/tuic-terminal/src/output_watchers.rs), then emitpty-watcher-lines-{session_id}with the batch — see Plugin OutputWatcher matching below. No raw-output Tauri event is emitted any more: the desktop canvas renders from grid frames, and the assembled lines are the only text the WebView needs. (The rawoutputframe of step 8 is unaffected — it is fed from the output ring buffer to raw-mode WebSocket clients.)
Ego’s parser cutoff and readiness adapter share the native status/composer recognizer. An output insertion can overwrite that pair before ego repaints it; no historical submitted prompt or transcript separator substitutes for it. This keeps a second soft-wrapped intent in the same existing Intent event path.
The intent path reconstructs soft-wrapped grid rows up to the parser’s character budget, then reads hard-wrap continuations only above the input-box chrome cutoff. A capped history scroll keeps the open intent’s anchor stable; repainting its unchanged anchor does not close it as replaced prose.
For a managed Claude child with workspace trust acceptance enabled, the rendered screen is also checked for its exact startup safety question, both choices, and No, exit selected above Yes, I trust this folder, as recorded in the Claude startup capture. Only then does the reader send Down followed by Enter under the PTY writer lock, once for that session. Other dialogs and user-opened terminals are never answered by this path; session cleanup removes an unused allowance.
The same per-session policy (managed_first_run) covers every managed child: an agent spawn child and a workflow-launched agent use one spawn path. A managed Claude child also answers the external CLAUDE.md imports dialog with its default No, disable external imports (Enter), once. A first-run dialog that TUIC does not answer (its Enter to confirm · Esc to cancel footer is the last row, and it is not a known dialog with its default selection, or trust acceptance is off) sets awaiting_input with the dialog text. The parent receives the usual awaiting_input notice with that text, and a workflow run shows its awaiting-input incident. Recorded in claude-first-run-3017.tcap (Claude Code 2.1.322).
Pause behavior: When paused flag is set (AtomicBool), the reader thread sleeps in 10 ms slices instead of reading. This prevents output flooding during background operations.
Exit detection: When the read returns 0 bytes or an error, the thread:
- Flushes remaining buffered data
- Emits
pty-exitevent with exit code - Removes session from
AppState.sessions - Updates metrics (decrement
active_sessions)
Plugin OutputWatcher matching
Plugin OutputWatcher patterns are matched on the reader thread instead of the WebView
main thread. Each frontend pushes its whole watcher set through
set_plugin_output_watchers (HTTP: POST /api/plugins/output-watchers) with its
client_id and a monotonic seq; plugins.rs compiles it into
AppState.plugin_output_watchers (OutputWatcherRegistry, one set per client, at most
8, least recently synced evicted). A stale seq answers applied: false and changes
nothing — including for a client whose current set is empty, whose record is parked
rather than removed so that a delayed older sync cannot resurrect a disposed set.
Tauri IPC registrations also carry their WebView label. A document navigation or
window destruction removes that WebView’s sets before a replacement document
registers; browser clients remain independent and use the bounded eviction path.
The frontend re-syncs every 30 s while it holds any watcher. Rust is the only source of lines, so a client the backend does not know about is blind with no local symptom, and two paths lead there without raising an event: the sync failed, or the client bound evicted a live set (reloading a browser tab leaves its old id behind — no disconnect reaches the PTY reader). The heartbeat is both the recovery and the liveness signal eviction ranks by. It stops when the last watcher is disposed.
Rust is the only line assembler. The WebView reassembles nothing. Per chunk,
assemble_watcher_lines():
- Takes one read lock for the whole chunk, so the compiled set and its “I still need every line” answer come from the same snapshot.
- When no watcher is registered at all (
is_idle), feeds the chunk toStreamLines::push_discardingand returns. The pending partial line still has to be tracked: a watcher that registers mid-line must see that line whole. - Otherwise reassembles complete lines with
StreamLines(trailing\rtrimmed, the partial line held until the newline arrives). A pending line that passesMAX_PENDING_LINE(256 KB) without a newline is dropped whole, with one warning per physical line, and so is the rest of it up to its closing newline. Continuation bytes are discarded without buffering or warning again, including while no watcher is registered. Cursor-addressed TUI animations can exceed this cap across many small PTY reads without any LF; screen rows and read boundaries are not stream line boundaries: a producer that never emits\n(a redrawing progress bar) must not grow the buffer without bound, and keeping the tail instead was worse than dropping —/^x+$/fires on a truncatedyxxx…, a line that was never on the wire. Both engines would agree on that fabricated text, so the frontend filter cannot catch it. - Cleans each line with
clean_line(), a port ofsrc/utils/stripAnsi.tsplus a backtick strip. Both sides must match on exactly the same text. - Keeps a line when a compiled pattern matched it. While some registered pattern could not be compiled (
needs_all_lines), every assembled line is kept instead, because the WebView has to scan them itself. - Batches the kept lines in
WatcherLineBatcherand emitspty-watcher-lines-{session_id}(desktop) plus thePluginWatcherLinesbus event (browser:watcher-linesWS frame on/sessions/:id/streamin both?format=gridand raw mode —?format=log|textdelegates to a separate handler that does not carry it — plusplugin-watcher-linesSSE) with{session_id, lines}. Each line is{text, matched_ids}, wherematched_idsare qualifiedclient_id/watcher_id. The frontend runs the real JSRegExpontextto build theRegExpExecArraythe plugin API promises.
Batching is throttled but lossless. One event per WATCHER_LINE_WINDOW (100 ms),
because each event is deserialized and dispatched on the WebView main thread and
per-chunk emission starved keydown under an output flood. Lines inside a window are
concatenated in order, never dropped — dropping was the original bug: with an assembler
on each side, a dropped chunk spliced the tail of one chunk onto the head of a later one
and reported a line that was never on the wire. A batch that reaches
WATCHER_BATCH_CAP (256 KB of text) is emitted early rather than growing. The frame
ticker drains a due tail, because read() blocks and the last line of a burst would
otherwise wait for output that may never arrive. Teardown has exactly one drain, the
reader’s EOF path, which assembles the flush_eof remainder and then takes the batch
unconditionally; both the ticker and the reader emit while holding the batcher lock, so
an older tail can never overtake a newer batch. The EOF drain also flushes the
assembler’s unterminated tail (StreamLines::flush) — a command that exits without a
final newline (printf DONE) still put that line on the wire.
Losslessness is a property of the assembler and the batcher, not of delivery. The
Tauri event and the per-session WS frame are live-only and never replayed: output a
session produces before its terminal installs the listener (or during a WS reconnect
gap) reaches no watcher, and a browser client whose socket stalls past the broadcast
capacity gets Lagged and skips those batches. Every live event on this bus behaves the
same way; the 100 ms window keeps the rate at ~10 events/s, which is what makes the lag
case remote rather than routine.
OutputWatcherRegistry::sync returns the ids of the patterns the regex crate cannot
express — lookaround, backreferences, and a negated class escape inside a character
class ([\D.]). Those are not compiled to something different: they are reported
back and stay on the frontend path. to_portable_pattern rewrites the escapes whose
Rust meaning is narrower than the ECMAScript one (\d \D \w \W \s \S to explicit ASCII
sets wrapped in (?-i:…) so an i flag cannot case-fold a negated set and exclude what
the fold pulled in, \b/\B to (?-u:\b)/(?-u:\B)), because the invariant is Rust
may over-match, never under-match: the frontend re-runs the real RegExp and filters a
false positive, while a false negative is invisible and permanent. The same invariant
covers the m flag from the other side: ECMAScript anchors ^/$ at every
LineTerminator, CR and U+2028/U+2029 included, so an m-flagged pattern is also tried
against each of those segments of the line. RegexBuilder::multi_line knows LF only, and
a cleaned line can carry a bare CR.
Frame Emission Pipeline
Frame emission is decoupled from PTY reading via a per-session frame ticker thread (display-link style pacing):
- Reader thread: processes PTY data into the alacritty VT grid, sets a
grid_frame_dirtyAtomicBool flag - Ticker thread: while work is pending, on its 16ms maintenance tick or a bounded input wake, checks the dirty flag → if set, serializes dirty rows via
serialize_dirty_rows()→ sends frame viasend_grid_frame()(respects theGridGatebackpressure). With no dirty frame, buffered synchronized update, queued reply, watcher-line tail, or priority retry, it parks without a timer. The PTY reader and other dirty-frame producers unpark it; the first ordinary frame retains the 16ms coalescing interval. - Frontend: coalesces paint triggers via
requestAnimationFrame(~60fps) - Ack handler: credits the gate; the ticker sends any dirty rows accumulated while the prior frame was in flight
Bounded input priority. Desktop and HTTP/PWA input arm a 100ms window before writing to the PTY. Only output applied by the reader after that input can wake the same ticker early. A priority frame waits at least 8ms after the previous frame; at most four priority bypasses are allowed in any rolling 100ms, even if input continues. If newer reader output arrives during a send, send accounting retains its retry on this same ticker, with the same spacing, quota and expiry. Other output retains the sustained-animation 33ms floor and the typing-under-saturation 50ms floor. The desktop receipt gate, synchronized output buffering and frame ordering remain in force. Receipts only release the gate; they do not mark the terminal dirty. Real damage and repair debt remain pending while the desktop is paused. Recovery sends one private full frame to desktop and publishes the matching delta only to browsers. It does not offer that delta to desktop again or recreate the debt. Browsers retain their ordinary delta stream. These changes remove idle frame feedback, not the deliberate input budget or rate floors; native echo measurements still exceed one frame at p95 (story 2040-16b2). A generic PTY stream does not identify application echo: the second credit can serve later output if unrelated post-input output used the first. This is not a guarantee that every transient glyph survives viewport scrolling or that native compositor presentation meets a deadline.
Cell text fidelity. Text extraction and binary serialization retain each
cell’s base scalar plus its zero-width scalars. A separately received combining
mark damages the cell it modifies, for both parse-side row snapshots and render
frames. Live/full frames and styled-row fetches share the optional sparse
TCX1 trailer;
the fixed cell core stays 11 bytes. The fork’s existing nine-mark bound remains.
Search matches exact stored codepoints; buffer-search results use UTF-16 string
offsets, while terminal highlight coordinates remain grid columns.
Delivery gate (grid_gate.rs and grid_watch.rs). A frame is a delta, so a dropped one strands
rows that exist nowhere else. Both transports are guarded, and both count rather
than flag:
- Desktop.
GridGateholdssentandackedcounters; the frontend echoes its total receipt count inack_terminal_frame { received }. The gate is open only when the echo has caught up. The counters exist because a bare boolean could not tell a fresh ack from a late one: after the ticker gave a frame up for lost (MAX_IN_FLIGHT_MS= 500 ms,abandon()) and sent the next, the late ack reopened the gate and a third frame went out at once — a burst at exactly the moment the frontend was proven to be behind. Each gate also carries anepoch, returned bysubscribe_terminal_gridand echoed onack_terminal_frame/unsubscribe_terminal_grid. A remount subscribes before the outgoing instance tears down, so the backend receives the dead instance’s calls against the new gate: without the epoch its late ack credits frames the new terminal never received, and its late unsubscribe deletes the live channel and leaves a mounted terminal blank. Each channel records the subscribing WebView label and epoch. On navigation or window destruction, only that WebView’s channels and matching gates are removed. A main-window reload therefore leaves a floating terminal’s channel live. The frame ticker sees no desktop subscriber for an unmounted terminal; a newly mounted terminal installs a fresh channel and gate. - Browser/WS. The
watchchannel keeps only the newest value, so a slow client silently skips frames. Frames carry a Rust-internalseq(GridWatchFrame); when the reader sees a gap it re-serializes the whole grid instead of forwarding a delta onto a row map with holes in it. The sequence never reaches the wire — the frame format is unchanged. - Hidden terminals decode each frame (the bell rides in the header) but ack on a 400 ms trailing timer, below the ticker’s deadline: a background tab drops to ~2 frames/s without making the ticker’s stuck-frontend warning fire.
Coalesced scroll (pending_scroll). The wheel and the scrollbar drag do not
take the vt lock: terminal_scroll_to_offset — the Tauri command and the
POST /sessions/{id}/terminal/scroll-to-offset route alike — stores the absolute
display offset in a per-session AtomicI64 and marks the grid dirty. The ticker
consumes it (take_pending_scroll) under the lock it already holds, so a burst of
wheel events costs one grid move, latest wins, and scrolling never contends with
the PTY output processor.
The entry is created by spawn_reader_thread — the one funnel every session
creation path shares — and dropped by remove_live_session_state. It belongs to
the session, not to a subscriber: when subscribe_terminal_grid owned it, a
session only a browser had ever rendered had nowhere to record a scroll, and
closing the desktop terminal disabled scrolling for an attached browser. For the
same reason the ticker applies a pending target even when nobody is subscribed —
/terminal/scroll-info and the row reads answer from the display offset, so a
target dropped there would disagree with every later read of the session.
Frames and styled-row chunks cross the desktop IPC as raw bytes
(tauri::ipc::Channel<tauri::ipc::Response>, tauri::ipc::Response). A bare
Vec<u8> takes Tauri’s blanket IpcResponse impl and is serialized as a JSON
array of decimal numbers — ~250 KB of string per 110 KB frame, plus an extra IPC
round trip. The HTTP twin (/sessions/{id}/terminal/styled-rows) answers
application/octet-stream for the same reason.
This coalesces rapid writes (e.g. spinner CR+erase+rewrite within 16ms) into a single frame, eliminating flicker from intermediate erase states. The ticker exits when the reader’s running flag clears, with a final flush to avoid losing the last frame.
Synchronized output (DEC mode 2026). TUIC advertises Sy in the spoofed TERM_FEATURES, so agents — Codex in particular — wrap each repaint in ESC[?2026h … ESC[?2026l. The vendored VTE buffers those bytes and applies them atomically on ESU, but its 150ms SYNC_UPDATE_TIMEOUT is passive: it records a deadline and never fires. The embedder must enforce it, and the ticker is the only wakeup that can — by definition no further PTY bytes are coming.
The ticker therefore checks the deadline before the non-dirty early return, via flush_sync_timeout_if_needed() on VtLogBuffer. Three details are load-bearing:
- A per-session
sync_update_activeAtomicBool, published by the reader after eachprocess(), keeps the 16ms maintenance tick active until the update ends or expires. It mirrors real parser state, so a nested BSU (which re-arms the deadline rather than closing the update) keeps it set. - A timeout flush bypasses
grid_send_min_interval_ms(). A protocol deadline is not animation; throttling it back a tick defeats the purpose. - Teardown calls
force_stop_sync_if_buffered()before the final serialize — session exit is the other “no more bytes arrive” case, and without it buffered output dies with the session.
Without this enforcement a single BSU whose ESU is delayed or lost freezes the tab indefinitely: content buffers invisibly and only a later ESU releases it. That was the cause of Codex streaming appearing to eat text and then dump it all at once, and it made any binary containing the BSU bytes a permanent tab wedge.
Headless Reader Thread
Foreground agent detection is shared by the desktop command, HTTP foreground endpoint and backend silence timer. Spawn records the root role explicitly: shell PTYs use Shell; direct IPC, HTTP and MCP agent spawns use DirectProgram. On macOS and Linux, the retained child PID and PTY foreground process group identify the owning root without a shell-name list. In a shell PTY, returning to that root revokes an observed identity only when its current image is not a supported agent. A shell can exec into an agent without changing its PID: detection classifies the current root image rather than assuming its spawn role still describes the executable. An agent exec at the root ends the session when it exits; it does not return to an owning shell. A script wrapper named bash is a different foreground group and counts as observed. Unknown wrappers can retain a run-config preset; a startup helper such as direnv/nvm may therefore disarm the preset early, an intentional fail-closed trade-off. Before any child is observed, the startup preset remains armed.
A direct agent has no shell to return to. Its identity remains valid while its root lives; a foreground child (including a nested shell, git or an editor) holds unattended submit and mail wake until the root regains the foreground. Missing root role, PID or foreground evidence also holds input. Mirrors without the owning daemon’s answer never infer a role. A different discovered agent drops preset provenance. Creation seeds provenance synchronously; delayed lifecycle events cannot re-arm an observed identity.
OS samples receive a generation under the session lock. Older samples cannot overwrite a newer identity or foreground-input hold; screen reclassification also verifies ownership of its generation. Pending shell-exit recovery can finish after a newer observation if both observations still identify no agent; it remains pinned against a newly discovered live agent. Identity changes reclassify the existing terminal screen so a quiet composer does not retain a shell-era cache. The refresh return value is the effective foreground detection, which can differ from the retained startup preset; lifecycle consumers read stored state.
The output reader checks the grid’s alternate-screen state for agent sessions. On the first entry per session, it logs a warning with the agent type and detected CLI version. This catches agent versions or launch paths that bypass the native-scrollback launch defaults without spamming on repaints.
PTY identity applies Claude’s primary-screen environment control only while that agent’s prevent_alt_screen setting is enabled. apply_agent_screen_env covers IPC, HTTP and MCP spawns before explicit caller environment values are installed. Rust also probes Codex, Grok and OpenCode when creating a shell PTY and exports supported flags and Codex’s exec exclusion into its environment. OpenCode wrappers apply --mini only to the interactive TUI: recorded subcommands and aliases bypass it, including after root options. Option values and project paths retain the interactive policy. Goose wrappers omit TUIC session naming for --no-session, --name NAME, --name=NAME, -n NAME, -nNAME, --path PATH, --path=PATH, --resume or -r. The zsh, bash and fish wrappers apply those values to manually typed agent commands; command <agent> bypasses them. The same Rust policy builds structured launch arguments, with a bounded CLI help probe that retries inconclusive checks.
Grid WebSocket attachment sends the existing viewport as a full frame, including history metadata, without waiting for new PTY output. If a live grid watch has no available frame, the server sends {"type":"grid-replay-empty"} so an idle empty session completes replay explicitly. The client bounds initial replay to 15 seconds and reconnects with a persistent error toast when replay stalls or decoding fails. Healthy idle sessions have no subsequent-output deadline.
spawn_headless_reader_thread() — used for HTTP-created sessions (no Tauri app handle). Same pipeline but skips Tauri event emission; only writes to ring buffer and WebSocket. Includes extract_question_line() for silence-based question detection, session lifecycle events (session-created, session-closed), and full output parser integration.
Generic HTTP sessions (POST /sessions) and native MCP/HTTP agent spawns publish
the backend-bound tuic_session in session-created, matching SSE and session-list
rows. Generic sessions without a requested identity use their bound PTY key. Live tabs use that identity
to match worktree declarations without changing the process cwd. Unbound sessions
publish a null identity. All three native producers share the emission boundary.
Named agent sessions propagate their stable display_name through the
session-created event. That launch label is a replaceable base title: OSC and
structured intent titles may update it. An independent
display_name_is_custom flag protects only an explicit user rename and survives
frontend reconnection. display_name_from_spawn records that agent action=spawn
named the session, so a reloaded tab still refuses the agent’s OSC 0/2 title; a
non-custom set_session_name (an OSC or intent title synced back) keeps it, and
only a user rename clears it. Session snapshots also carry is_remote, so reconnecting
an HTTP/MCP-created PTY does not lose orchestration-only notification muting.
Shell Resolution
#![allow(unused)]
fn main() {
pub(crate) fn resolve_shell(override_shell: Option<String>) -> String
}
Priority:
- User override from settings (
override_shell) - Platform default via
default_shell()
Platform defaults:
- macOS:
/bin/zsh - Linux:
$SHELLenvironment variable, fallback/bin/bash - Windows:
powershell.exe
Buffer Types
Utf8ReadBuffer
Handles the case where a multi-byte UTF-8 character (e.g., emoji, CJK) is split across two reads:
#![allow(unused)]
fn main() {
impl Utf8ReadBuffer {
fn push(&mut self, new_bytes: &[u8]) -> String // Returns valid UTF-8, keeps remainder
fn flush(&mut self) -> String // Force-flush (lossy conversion)
}
}
EscapeAwareBuffer
Prevents ANSI escape sequences from being split between two emissions. Detects incomplete CSI (\x1b[...), OSC (\x1b]...), and other escape sequences:
#![allow(unused)]
fn main() {
impl EscapeAwareBuffer {
fn push(&mut self, input: &str) -> String // Returns safe-to-emit portion
fn flush(&mut self) -> String // Force-flush buffered escapes
}
}
OutputRingBuffer
Fixed-capacity circular buffer (2 MB, OUTPUT_RING_BUFFER_CAPACITY) that stores recent output for MCP access:
#![allow(unused)]
fn main() {
impl OutputRingBuffer {
fn write(&mut self, data: &[u8]) // Append data
fn read_last(&self, limit: usize) -> (Vec<u8>, u64) // Read last N bytes
}
}
VtLogBuffer
Module: src-tauri/crates/tuic-terminal/src/vt_log.rs
VT100-aware extractor that captures clean log lines from PTY output. Designed for mobile/browser clients that need readable text without ANSI noise or TUI screen garbage.
An open Claude Ink choice dialog is retained in the mobile screen payload;
its highlighted ❯ N. option row must not act as a composer cutoff. The
agent-specific choice parser publishes its navigation contract through
SessionState.choice_prompt.selection_mode.
The HTTP and log-WebSocket screen trim also retains an active Claude /resume
modal, including populated and no-match search states. Its title, search field,
and final search/cancel footer identify the presentation boundary. Search-box
borders and the selected session are not composer chrome. This exception does
not change the shared bottom-zone cutoff used by output and state parsers.
A retained modal above a later ready composer does not disable normal trimming.
#![allow(unused)]
fn main() {
impl VtLogBuffer {
fn new(rows: u16, cols: u16, capacity: usize) -> Self // Create with terminal size
fn process(&mut self, data: &[u8]) -> Vec<ChangedRow> // Feed raw PTY bytes, return changed rows
fn resize(&mut self, rows: u16, cols: u16) // Update terminal dimensions
fn screen_rows(&self) -> Vec<String> // Current VT100 screen content (for slash menu detection)
fn screen_log_lines(&self) -> Vec<LogLine> // Styled screen rows for mobile/REST (structural tokens stripped)
fn lines_since_owned(&self, offset: usize, limit: usize) -> (Vec<LogLine>, usize) // Paginated reads (absolute offset, structural tokens stripped, chrome lines skipped)
fn total_lines(&self) -> usize // Monotonic counter (never decreases on eviction)
fn oldest_offset(&self) -> usize // Absolute offset of oldest retained line
}
}
ChangedRow — describes a row that changed between two process() calls:
#![allow(unused)]
fn main() {
struct ChangedRow {
row_index: usize, // 0-based row in the VT100 screen
text: String, // Clean text content (no ANSI)
}
}
How it works:
- Owns the session’s
TerminalGrid, backed by Alacritty (initialized at the PTY spawn rows and columns); the same grid supplies rendered frames, scrollback, copy and search - On each
process()call, compares current screen rows against previous snapshot - Newly scrolled primary-history rows are extracted into the separate
LogLinelog. The extraction cursor uses the primary grid origin (total_scrolled), including evicted rows; bounded history length stops at 10,000 and would otherwise freeze this log while the live screen keeps changing - Separate alternate-screen contracts: changed rows are still returned while a TUI app owns the alternate screen, so status/intent/question parsers keep working. Durable log extraction reads only primary-screen history, so fullscreen repaint noise never reaches mobile/MCP logs
- The grid retains 10,000 history rows per screen; the separate log is bounded by
VT_LOG_BUFFER_CAPACITY(10,000 lines). Oldest entries are dropped when each buffer is full. The grid history cannot be reduced as an independent log scratch buffer - Monotonic cursor:
total_lines()returns a monotonically increasing count of all lines ever pushed (not the current buffer length). Clients use this as a stable cursor for paginated reads vialines_since_owned(offset, limit). If a client’s saved offset falls in the evicted range, it is clamped tooldest_offset()
Resize: The first resize seeds its no-op guard from master.get_size(), not the grid, so a grid-only match cannot suppress a required kernel resize. When the PTY is resized, VtLogBuffer.resize() keeps the parser in sync and clears the previous-row snapshot (avoids false scroll detection after resize). If an alternate-screen app is active, the durable-log cursor is synchronized against the inactive primary grid, not the unrelated alternate history; normal shell capture therefore resumes on the first line after exit.
Each session gets its own VtLogBuffer stored in AppState.vt_log_buffers: DashMap<String, Mutex<VtLogBuffer>>.
Selection extraction
TerminalGrid::get_selection_text() reads grid-relative scrollback coordinates, skips wide-character spacer cells, removes row padding, and joins rows carrying Alacritty’s WRAPLINE flag so a visual wrap does not become a newline. Before returning clipboard text, it removes only contiguous multi-line Claude visual gutters with the exact NBSP NBSP ▎ prefix. A lone marker, ASCII-indented block character, and non-breaking spaces inside the selected content remain unchanged.
Desktop and HTTP selection requests may carry the displayed frame’s
historyBase alongside those row coordinates. The shared backend read rebases
them under the grid lock, preventing output-driven history eviction between
frame delivery and copying from silently selecting another row. Requests whose
endpoints have been evicted are rejected. The frontend retains selection in
eviction-stable coordinates (historyBase + grid-relative row); legacy callers
without a history snapshot continue to address the current retained grid.
OSC 7 CWD Tracking
Shells that emit OSC 7 (\x1b]7;file://hostname/path\x07) report the current working directory after each command. TUICommander uses this to keep the Rust-side PtySession.cwd in sync:
- Backend handler: the VT parser surfaces
TermEvent::Osc7(url), andparse_osc7_cwd()decodes thefile://URL (pty.rs). - Session update:
PtySession.cwdis written on the Rust side directly — the frontend is not in this path and has no IPC command to call. - Push to clients: the new cwd is dual-emitted as
pty-cwd-{session_id}(desktop) andAppEvent::PtyCwd(bus → SSE/WS), both carrying{ cwd }soCanvasTerminalneeds no per-transport branch. The frontend updatesterminalsStorefrom that event and re-runsreconcileTerminalOwnership. - Restart recovery: The persisted cwd is used during session restore so reopened terminals start in the correct directory.
- Worktree reassignment: When the cwd changes to a path inside a different worktree, the terminal tab is reassigned to the corresponding branch in the sidebar.
Shell Environment Variables
build_shell_command() sets these environment variables for spawned PTY sessions:
| Variable | Value | Purpose |
|---|---|---|
COLORTERM | truecolor | Advertise 24-bit color support |
KITTY_WINDOW_ID | 1 | Signal kitty keyboard protocol support for heuristic detection by Ink-based agents |
TERM_PROGRAM | ghostty | Satisfy Claude Code’s terminal allow-list for kitty protocol; also prevents macOS /etc/zshrc from sourcing zshrc_Apple_Terminal |
TERM_PROGRAM_VERSION | 3.0.0 | Passes Claude Code’s version gate (rejects ^[0-2]\.) |
Additionally, CLAUDECODE is removed from the environment (env_remove) to prevent nested-session detection when TUICommander itself runs inside a Claude Code session. NO_COLOR is also removed from every PTY command immediately after construction because it may belong to a Codex parent that launched TUICommander, not to the independent child session. This does not force application color or override explicit command flags; a deliberate per-agent environment may restore NO_COLOR after sanitization.
The same PTY command sanitizer removes Cargo package and executable metadata (CARGO, CARGO_MANIFEST_*, CARGO_PKG_*, CARGO_BIN_NAME, CARGO_BIN_EXE_*, CARGO_CRATE_NAME, CARGO_PRIMARY_PACKAGE, CARGO_FEATURE_*, CARGO_CFG_*), build paths and jobserver state (CARGO_TARGET_DIR, CARGO_TARGET_TMPDIR, OUT_DIR, CARGO_MAKEFLAGS), build settings (CARGO_INCREMENTAL, CARGO_ENCODED_RUSTFLAGS, RUSTFLAGS, RUSTC, RUSTC_LINKER, RUSTC_WRAPPER, RUSTC_WORKSPACE_WRAPPER, RUSTDOC, HOST_CC, HOST_CXX, HOST, TARGET, PROFILE, NUM_JOBS, OPT_LEVEL, DEBUG), build-script dependency metadata (DEP_*), and all MBX_* keys inherited from TUICommander’s Cargo/mbx development launch. It also removes rustup proxy state (RUSTUP_TOOLCHAIN, RUSTUP_TOOLCHAIN_SOURCE, RUST_RECURSION_COUNT) so the next repository can select its own toolchain. Those values describe the TUIC build, not the repository opened in the PTY. User preferences such as RUSTUP_HOME, CARGO_HOME, RUST_LOG, RUST_BACKTRACE, CARGO_TERM_COLOR, CARGO_TERM_PROGRESS_WHEN and CARGO_TERM_PROGRESS_WIDTH remain inherited; explicit per-agent or run-config environment values applied after sanitization can restore any removed key when requested.
Child Process Priority
Each spawned shell is given a lower scheduling priority right after spawn
(lower_pty_child_priority()), so heavy workloads run inside a pane (cargo build, bundlers, test runners) yield CPU to TUIC’s own render loop and the rest
of the system. A child inherits the parent’s priority at fork time, so every
process the shell later spawns is deprioritized too. The effect only bites under
contention — an idle machine still runs the build at full speed.
| Platform | Mechanism | Default |
|---|---|---|
| macOS / Linux | setpriority(PRIO_PROCESS, …) | nice +10, override via TUIC_PTY_NICE |
| Windows | SetPriorityClass(BELOW_NORMAL_PRIORITY_CLASS) | fixed |
Validated on an M4 Max under 14-core saturation: TUIC’s UI goes from frozen
(nice 0) to responsive (nice +10). BELOW_NORMAL (not IDLE_PRIORITY_CLASS) is
the Windows analog — IDLE only runs when the whole system is idle, the
equivalent of macOS QoS-background, which would make builds crawl.
macOS Thread QoS Elevation
On macOS, the PTY reader thread, the frame ticker, and the keystroke-write thread are all raised to QOS_CLASS_USER_INTERACTIVE via pthread_set_qos_class_self_np (raise_thread_for_interactive_io() in src-tauri/src/pty.rs, thread_qos module). This is complementary to the child-process renice: on Apple Silicon the scheduler is QoS-band driven — nice only reorders threads within a band. Without this elevation, TUIC’s interactive-path threads ran in the default QoS band alongside compiler worker threads, causing input latency under heavy builds. Raising to USER_INTERACTIVE puts the interactive path in a higher scheduler band. macOS-only; a no-op on Linux/Windows.
Session Conflict Flag File
When an agent reports a session conflict (session already in use or not found), TUICommander handles it via a flag-file mechanism instead of writing directly to the PTY.
Flow:
- The output parser detects a session conflict message (
ParsedEvent::AgentSessionConflict) ChunkProcessorcallsmark_session_conflict(), which creates a flag file namedno-session-inject.<TUIC_SESSION>in the app config directory- Shell wrapper functions (zsh, bash, fish) check for this flag file before injecting
--session-id $TUIC_SESSION - If the flag file exists, the wrapper skips session-id injection, allowing the agent to start a fresh session
This replaced the previous maybe_reset_tuic_session approach, which wrote export TUIC_SESSION=... directly to the PTY. Direct PTY writes could corrupt TUI output (e.g., Ink-based agents in raw mode). The flag-file approach is safe because it uses the filesystem as a side-channel — no bytes are injected into the terminal stream.
A debounce (last_session_conflict_mark) prevents creating multiple flag files within a short window for the same session.
Ctrl-U Prefix Handling
Single-key PTY writes that should clear the current input line prepend \x15 (Ctrl-U) on POSIX shells. The selection is shell-family aware, not host-platform aware: the detected shell (bash/zsh/fish → POSIX, powershell/cmd → Windows) drives the choice. Mixing PowerShell on macOS or a POSIX shell via WSL/MSYS now behaves correctly. Native Windows shells skip the prefix entirely to avoid inserting a literal ^U.
Frontend input helpers route through src/utils/sendCommand.ts:
sendCommand(fn, text)— full command:Ctrl-U(family-gated) + text +\r. With an agent attached, Ctrl-U precedes text by 50 ms. Enter follows text by 200 ms for Codex and 50 ms for other known agents. If the type is unknown but a non-shell process owns the foreground, the frontend uses agent framing and the 200 ms gap; a failed foreground probe keeps shell framing and delays Enter. Claude Code strips a Ctrl-U inside a long pasted text; Codex suppresses Enter for 120 ms after a paste burst.sendPtyKey(fn, key)— pass-through single key/escape sequence. No prefix, no trailing CR. Use forChoicePromptoption keys, TUI app navigation, and any raw-stdin interaction.
agentInputPayload and Rust’s agent submission profile frame Claude text above
500 UTF-8 bytes as bracketed paste. This prevents Claude Code 2.1.311 from
losing the first read of a long plain input burst. Review-only dictation uses
the same encoding without Ctrl-U or Enter, so it appends without clearing a
draft. Codex keeps its existing 500-character threshold; short dialog replies
and unverified agents keep their existing input semantics.
Never write text + "\r" directly to a PTY — see AGENTS.md.
OSC 133 Semantic Prompts
When the shell emits OSC 133 markers (modern bash/zsh/fish with the integration enabled), the reader updates shell activity and terminal command blocks:
| Marker | Meaning |
|---|---|
OSC 133;A | Prompt start — delimits a new prompt line |
OSC 133;B | Command start — the user has pressed Enter, command is about to run |
OSC 133;C | Command output start |
OSC 133;D[;exit_code] | Command completed with the given exit code |
ChunkProcessor.handle_osc133_event applies prompt-start (idle) and output-start (busy) activity transitions. Command completion still supplies block exit status; it does not close activity before the next prompt. has_osc133_integration records whether shell markers have been observed.
The former command knowledge store had no reader and was removed in #2115-1333, including inferred outcomes and the periodic disk flush. Existing history files remain untouched.
TUI Application Detection
src-tauri/src/ai_agent/tui_detect.rs tracks alternate-screen enter (ESC[?1049h) and leave (ESC[?1049l) to classify the terminal as:
#![allow(unused)]
fn main() {
enum TerminalMode {
Shell,
FullscreenTui { app_hint: Option<String>, depth: u8 },
}
}
depth is a counter for nested alt-screen pushes (e.g. less invoked from inside vim). Known app hints — matched heuristically from nearby screen rows — include vim, nvim, htop, btop, lazygit, less, tmux, claude, and others. The mode is surfaced on SessionState.terminal_mode. The PTY processor uses it to distinguish a shell-level agent-session conflict from text displayed inside a TUI. Primary-screen mouse reporting also classifies inline TUIs without overriding alternate-screen nesting.
Output watchers receive the original cleaned stream. The removed xterm-era cursor-home/cursor-up clear injection never fed the canvas grid and is no longer applied to watcher input.
Silence-Based Question Detection
The reader thread tracks output silence to detect unanswered agent prompts. When the terminal stops producing output for 10 seconds after a line ending with ? is detected, the session is treated as waiting for input. This complements the instant pattern-based detection in the output parser and catches generic questions that would cause too many false positives if detected immediately (e.g., streaming fragments like “ad?”, “swap?”).
Question extraction: extract_question_line() scans changed rows for a candidate, excluding suggest: [ … ] protocol rows and their wrapped continuations even when an item ends in ?. A visible input-box anchor makes chat order authoritative: only the latest chat content above the current prompt may become a question. The changed-row fallback is used only when no prompt anchor is available. This prevents scroll/repaint from resurrecting a question retained above a later answer or completion. Question events carry the input turn_epoch, and the state accumulator rejects an event produced by an older turn.
Codex approval cancellation: An Action Required title raises a confident question. If Codex then paints You canceled the request after that approval, shows its ready or interrupted composer, and drops the title, the PTY reader clears the matching question. The clear carries the originating question text and turn epoch; an older cancellation in scrollback or a newer, different question cannot clear the current wait.
Echo suppression: When the user submits a line — including bare Enter — the shared desktop/HTTP bookkeeping advances the turn, clears the current wait, and activates a 500ms suppression window (suppress_user_input). During this window, matching PTY echo is ignored for question detection.
Single threshold: All silence-based questions use a uniform 10-second timeout regardless of whether new output has arrived since the question was detected.
Shell State (Busy/Idle) Detection
The backend combines explicit lifecycle markers, agent-specific screen evidence,
real output, and silence to emit ShellState events (busy/idle). Rust is the
single source of truth — the frontend does not derive activity from raw PTY data.
Before the first lifecycle observation, shell state is absent and detected-agent
state is starting; the internal null sentinel is never serialized as idle.
PTY lifecycle events update the authoritative SessionState through a lossless
single-consumer lane. The global broadcast bus remains the live SSE/WS transport,
where slow consumers may reconnect after lag, but a dropped broadcast copy cannot
strand the sticky awaiting/idle state.
Transitions:
- Completed turns: A protocol idle marker survives ordinary output, decorative animation, and subsequent ready-screen timer ticks. Activity metadata must not clear idle evidence before
record_busycompares ranks. New submitted input or accepted semantic working evidence can reopen the turn. - Explicit markers: OSC 133 shell markers and OSC 7770 agent hooks transition immediately. Output silence cannot override an observed hook
busy; it ends on hookidle, a confirmed interruption, process exit, or a stable ready composer after the submitted turn produced real activity. The last path recovers safely when an idle hook is missed without letting the previous turn’s composer cancel a fresh submission. A Claude submission following a hook idle also returns to idle after five minutes with no output or subsequent busy hook when a transcript view hides the composer. - → busy: A submitted agent prompt, real output, an animated spinner, or an agent-specific
Workingscreen transitions via atomic CAS (try_shell_transition). Every successful CAS writes aShell state →trace, including injection claims and rollbacks. Positive screen evidence is evaluated even while the stored state is idle, so false-idle is self-healing. - → idle: The 1s silence timer is the sole heuristic idle path. Plain shells use 500ms; agents use 2.5s and must have no active sub-tasks. Agents with ready-screen adapters require the ready prompt to remain stable for 1.5s.
- Interrupts: Ctrl-C and bare Escape record
interrupt pendingbut never force idle. Idle follows only after an interrupted/ready screen, explicit Stop, or process exit. - Nested prompts (plain shells only): an interactive subshell —
sh,bash -l,su,sudo su— is one OSC 133 command that never ends, because the inner shell has no integration of its own and so never emits the closing marker. The outer shell stayed latchedbusyfor the subshell’s whole life while the user looked at an idle prompt. A plain shell (noagent_type) that has been silent for 3s therefore has its foreground process group inspected: if that group and everything under it are shells and privilege wrappers, the explicit busy marker is overruled and the silence path may idle it. Any non-shell descendant (ddundersudo, a-cscript) keeps it busy, and the reader still relatches busy on the next byte of output, so this only ever moves an idle prompt. Agents are excluded — their ready-screen adapters already own this. The probe reads the app-wide process snapshot, whose 1s refresher now counts these sessions as demand.
Goose appends its reply below the submitted > prompt, so the reader does not apply the fixed input-area chrome cutoff to Goose. Its reply supplies the real activity required to release user-submit busy at a stable Ready composer. Protocol ranks and hook-held turns keep their existing rules (#1812-022d).
Movement is the default busy signal (#446-596f): “if the text above the input area moves, the agent is active.” Post-cutoff changed_rows are text-equality diffed (TerminalGrid::process), so a byte-identical repaint produces no ChangedRow. Static completed summaries, hints, HUD bars, and banner art are inert. Spinner rows among the changed rows additionally refresh last_output_ms while they animate. Claude and Codex have narrowly scoped semantic presence exceptions described below because current versions can freeze a valid active status while a child or blocking hook runs.
Agent screen adapters: Gemini remains prompt-based (Ready or Unknown). Gemini and Codex accept composers only in the current bottom chrome zone (or the final three rows when no input box can be identified), so a historical submitted prompt or markdown quote cannot report Ready. Codex detects Working/Ready/Interrupted from its semantic status near that current composer; both › and the newer » composer glyph are accepted. Claude treats only a spinner-prefixed phase containing an ellipsis and parenthesized progress as Working; this outranks the empty ❯ composer that current Claude versions leave visible during long tools. Completed summaries such as ✻ Sautéed for 1m 25s remain Ready. If Claude emits a premature Stop/suggest before a blocking Stop hook, a live phase marker reopens that turn and clears the stale completion suggestions. Grok similarly keeps its ❯ composer visible during a turn: a leading Braille spinner in its bottom status row is Working, and the stable composer becomes Ready only after that row disappears. These adapters repair the shell’s long-lived OSC 133 busy marker even when native hooks are unavailable or disabled.
Signal precedence and confirmation: Explicit hook busy > current Claude/Codex/Grok semantic Working marker > movement (real output / animated spinner) > silence. A ready prompt visible from the previous turn cannot cancel a newly submitted prompt until real activity has been observed; after activity, a stable ready composer can repair a missed hook idle. A current-turn completion marker prevents a stale static Codex Working row from relatching BUSY; movement of that exact semantic row can reopen a Codex internal continuation that starts without PTY input. Claude’s current live phase marker can supersede a premature completion from a blocking Stop hook. That reopen is provisional when TUIC’s own Stop hook was the last protocol fact (#2837-df6a): Claude keeps its spinner row (running Stop hooks… n/7) on screen until its last Stop hook returns, so every Claude turn end reopens. For Claude only, once the timer sees no Working row and no newer hook, submitted line or busy evidence, it restores the Protocol hook-idle. Codex internal continuations do not use this recovery: their semantic Working movement can reopen a completed turn, but an Unknown screen must not restore its previous completion. Confirmation then does not depend on a composer the Ready adapter can read, and status-line repaints cannot demote it to Silence rank. A tool-using continuation still reports state=busy from PreToolUse; a text-only one ends with another Stop hook. A pending process probe or confirmed meaningful descendant still owns the task lifecycle. Hook-based question suppression activates only after an OSC 7770 state marker is actually received.
Native v2 plugin lifecycle: OpenCode 2.2.3 uses the managed default {id, setup} plugin and context.event.subscribe(). Only a TUIC private --standalone launch (native server --stdio) may emit to its controlling tty; a shared service stays inactive. Native session/request sets keep a form or permission wait across unrelated activity and duplicate replies. Matching answer/cancel/reject restores current execution activity. Execution settlement, session deletion and location/plugin shutdown retire the owned waits. The existing OSC 7770 consumer and state accumulator remain unchanged.
Ego native approval lifecycle: Each empty-title OSC 7770 awaiting marker is authoritative independently of selector repaint bookkeeping. A hard-wrapped MCP approval may not yet have a parsed title when its marker arrives. Screen-text dedup must not swallow the next marker after protocol busy clears the prior wait. The full-screen approval parser joins contiguous hard title rows before Risk: and publishes the native controls through the shared session-state accumulator.
Question lifetime on agent exit: when an accepted foreground observation revokes an observed agent identity on confirmed shell return, it queues protocol-question-cleared through the lossless session-state reducer. This clears confident awaiting state, question text, choice controls and ranked awaiting evidence before any new shell input. The clear carries the current turn epoch so delayed exit processing cannot clear a later submitted turn. Reader admission of agent-owned Question/ChoicePrompt events holds the same session identity lock through enqueue and rejects a revoked or replaced cached identity. Thus an in-flight final repaint cannot enqueue a new wait after exit withdrawal. Unknown helpers, stale observations and startup presets do not trigger this withdrawal. claude-await-exit-before-input-1985.tcap covers the real question and exit with no subsequent input.
Post-exit dialog history: full-screen Ink dialog recovery and silence-timer chat-question heuristics require an active agent identity. A shell can retain the old footer above its prompt after an agent exits; shell output must not turn those historical rows into a new confident question. claude-question-exit-2091.tcap and its accumulator replay cover the real question, exit and successful shell command.
OSC 777 notification classification: OSC 777 notify is a desktop-notification transport, not an awaiting-state protocol. Raw-stream parsing promotes only unambiguous permission or approval wording (needs your permission, approval required) to a confident question. Claude’s is waiting for your input body also arrives after a normal reply at the ready composer; promoting it flashed Waiting input until the silence timer retracted it. Ink pickers use their visible footer and full-screen presence recovery, including hook-instrumented sessions. A debug trace at the session-state setter records the confidence, turn epoch, hook configuration and whether a generic Claude notification reached it, without logging the question text.
State-regression capture: Enable POST /diagnostics/capture before reproducing ({"enabled":true,"session_id":"<id>"}), stop it afterward, and copy the exact <config dir>/captures/<id>.tcap file into src-tauri/src/fixtures/agent_prompts/. Set TUIC_CAPTURE_DIR to an absolute path before launch when captures must go elsewhere; a relative value rejects activation. GET /diagnostics/capture reports the selected directory and bytes written. The desktop equivalents are the get_pty_capture / set_pty_capture commands, surfaced as Capture Session in the tab context menu whenever isPerfDebug() is on (dev by default). TUICCAP2 records the initial terminal rows/columns and preserves input/output ordering, original chunk boundaries, and monotonic timestamps. The decoder still accepts geometry-less TUICCAP1 and legacy output-only .raw fixtures; replay code must provide independently observed dimensions for those files. Do not build fixtures from /sessions/:id/output: the bounded ring can overwrite the signal and its JSON string is lossy UTF-8.
Reading a corpus back: detection_over_capture_corpus (ignored test in pty.rs) replays every capture in a directory through the production composition and reports, per file, the event kinds produced, whether an awaiting badge was left set at the end, and how often find_chrome_cutoff found no anchor — the fail-open branch, where no trim happens and every status-line row reaches every parser.
TUIC_CAPTURE_CORPUS="$HOME/Library/Application Support/com.tuic.commander/captures" \
cargo test -p tuicommander detection_over_capture_corpus -- --ignored --nocapture
Captures hold real session content and are not committed; the harness measures them in place. Replay fidelity is bounded by the fixed 41×128 grid it reconstructs — a session recorded at another width wraps differently, which moves chrome detection.
Ego startup readiness uses the same native-composer locator as chrome trimming.
It accepts the legacy context/trust status and the current ten-cell context bar
with a trust field. An empty column-zero composer must remain stable for the
existing readiness debounce before queued initial prompts or mail can be typed;
a draft, working status, or modal content does not grant startup readiness.
The recorded ego 0.4.7 startup boundary is ego-startup-2948.tcap.
Safety consumers: For agents with a verified screen adapter, peer-message injection and Unix auto-standby require confirmed idle (explicit Stop/OSC or stable ready screen). A silence-only idle can update the cosmetic state but cannot type into or SIGSTOP a potentially working agent. Agents without an adapter retain the legacy heuristic behavior until their UI is characterized.
Task lifecycle is separate from shell activity: shell_state=idle means the
PTY is quiet; it does not prove that the assigned task finished. An agent’s
suggest: [ ... ] marker explicitly closes the current task epoch and produces
agent_state=completed plus a state_change: completed parent notification.
A refused turn (OSC 7770 state=error) produces agent_state=error and a
state_change: error parent notification that carries the agent’s error
message, never idle. A refused child holds no running turn: owned close may
stop it.
Likewise, a visible ready composer may coexist with an autonomous background
command. While a meaningful descendant of the agent is alive, session state
reports background_work=true and keeps agent_state=working; shell_state
remains idle because terminal input readiness is a separate fact.
Ego is turn-scoped: once its shell state is idle, a descendant or pending
process probe does not promote agent_state to working. Its OSC 7770 idle
signal ends the active turn even while a background job waits. The shared
snapshot keeps background_work and probe metadata for suspend and standby
safety. Desktop, mobile, and agent ls read this same derived lifecycle state.
A descendant is excluded from that judgement two ways. By name: the persistent
integration helpers (mdkb, tuic-bridge, and node_repl) and Claude’s
standalone timed caffeinate -i -t <seconds> assertion. Unix classification
checks both comm and the authoritative argv path from unlimited-width ps
output; a caffeinate invocation that wraps a command remains meaningful
background work. And by age: a descendant that started within
AGENT_STARTUP_WINDOW_SECS (60s) of the agent itself is session plumbing
whatever it is called.
The startup window exists because the name list cannot be completed.
codex-code-mode-host arrived with Codex 0.149.0, and an MCP server started
through npm exec reports as npm — a name that must keep meaning work,
because a turn also runs npm. Measured on a live 14-session instance on
2026-08-23, every agent owned at least one such daemon, so background_work was
a constant true and no session could ever leave working. In the same
snapshot every daemon appeared within 18s of its agent while work spawned by a
turn was hundreds of seconds younger, which is the gap the window sits in.
Ages come from the etime column of the shared ps snapshot. Where the
platform cannot supply one — Windows PROCESSENTRY32 carries no creation
time — the window is skipped and the name list is the only rule, which errs
toward reporting work rather than hiding it. Parent idle lifecycle mail is
deferred until the real descendant exits, while confirmed-ready message
delivery keeps using the terminal-readiness gate. The first confirmed-ready
observation and every explicit agent IDLE marker arm a generation boundary:
idle/completed lifecycle output waits until a process snapshot newer than that
observation or marker has been reconciled. Fresh working evidence starts a new
readiness episode even within the same task epoch: it invalidates only the
satisfied or pending snapshot boundary, so the next ready observation must
reconcile a newer snapshot while preserving tracked background work and the
snapshot generation. That reconciliation is also an authoritative idle edge for
the session itself: if a registered orchestrator accumulated inbox mail while
the probe still reported it as working, settling the probe reevaluates the
pending payload-free inbox wake immediately. It does not wait for a later child
lifecycle event, and the child payload remains in the inbox. A new idle edge or
first confirmed Ready observation grants a fresh mail-wake attempt budget.
Later stable Ready ticks may chase outstanding mail within that budget, but do
not reset it. A wake blocked before writing any bytes, such as by a retained
user draft, exhausts the budget until new idle evidence arrives. Queued user
commands still use the stable Ready level to retry their existing guarded flush. One app-wide process snapshot is collected at most once
per second on Tokio’s
blocking pool and shared by every session. The refresher runs only while a
ready probe or tracked background process needs it, skips missed interval ticks,
and stops scanning stable idle sessions. Enumeration or parse failures preserve
the prior background_work value. On Windows, where Toolhelp does not provide
command lines, generic node.exe processes are kept as meaningful work rather
than guessed to be node_repl helpers.
Submitting new user or PTY-injected peer input starts a new task epoch immediately,
clearing the prior completion marker and its stale suggested actions before new output arrives.
Claude channel and inbox delivery do not claim a submitted turn; the channel is used only
inside an already working turn. Idle or completed managed composers take the PTY submission
path, and lifecycle changes only after that input or normal activity evidence. Idle
CAS and parent lifecycle notification share the same per-session lifecycle lock;
submitted epoch mutation and its IDLE-to-BUSY transition hold that lock as one
critical section, so a new turn cannot inherit a stale idle notification. The
authoritative parent inbox enqueue occurs under the child lock; parent terminal
wake/dispatch runs only after release, avoiding cross-session lock ordering. A
queued BUSY-to-IDLE transition also carries the task epoch observed before it
waited for the lock and is discarded if a new submitted turn won first.
Without a fresh marker the new task epoch returns to idle, not completed.
Transactional peer injection: Reserving an idle composer creates an ownership token before the PTY write. A failure proven to occur before any byte was written rolls the synthetic BUSY state back to the prior confirmed IDLE state and keeps the message queued. Once any byte may have escaped, failure is delivery_uncertain: the session remains conservatively BUSY, the authoritative inbox remains readable, and TUIC does not automatically retry into the terminal. A queued injection waits up to six seconds for Codex and Claude and one second for other agents after Enter for child output plus an agent hook, a new Working screen, or (for Gemini) the ready prompt disappearing. Codex’s stop hook delayed its accepted turn’s Working repaint by four seconds; a live Claude notice took 3.8 seconds to leave Claude’s internal queue after Enter. A Working screen already present before Enter cannot confirm the new turn: the rb-tool capture showed cursor updates while the queued wake remained in a Codex composer until a manual Enter. A Ready-to-Working transition in output after Enter does confirm it, even if the pre-write screen classification was stale. A silent or unrecognised composer reports delivery_uncertain and emits an error toast to desktop and browser clients. The toast tells the user to inspect the transcript and composer, and to press Enter once only if the text remains. Further queued entries wait until a human submission or later activity resolves the uncertainty. Enter alone never proves submission. Real output, a Working screen, or an explicit state marker invalidates rollback ownership so a late error cannot erase genuine activity. Amp, Cursor, and Droid retain the previous PTY-write result because they have neither verified screen adapters nor hook support; they need live captures before semantic confirmation can be enabled. session status exposes the additive delivery_uncertain flag.
Queued confirmation waits run per session so a silent agent does not block other sessions or ordered lifecycle notices on the global injection worker. Each idle edge with a nonempty queue can start a worker; there is no global thread cap. A blocked claim returns promptly, and an active acknowledgement wait lasts at most six seconds for Codex or Claude or one second for other agents. The HTTP queue handler runs the blocking delivery on Tokio’s blocking pool. If an agent remains silent with no human input after uncertain delivery, the uncertainty flag and later queued entries remain held until activity or a human submission supplies new evidence.
Atomic MCP submission reuses the same claim: session action=submit first
requires a confirmed-idle managed agent, an empty composer, no confident
dialog, and an empty shared injection FIFO. It never adds itself to that FIFO.
The claim marks the session BUSY before any bytes; one PTY writer guard then
spans Ctrl-U, a 50 ms gap, the text in optional bracketed paste, a second
gap (200 ms for Codex or an undetected agent type, 50 ms for known other agents), and CR, so
neither raw input nor a peer can splice the command. A peer arriving after the
claim queues; a peer that claims first makes submission reject.
Ego composer recovery state map
| Input or event | Composer state and authority |
|---|---|
| Desktop raw input, HTTP/WebSocket/MCP input, paste and native answer keys | Input bookkeeping stamps monotonic input time and feeds InputLineBuffer. Unsubmitted text blocks managed input. |
| Direct submit, queued user command, automated notice/wake and keepalive | The shared claim checks idle, foreground ownership, dialogs, uncertainty and draft state before writing. Accepted payload plus CR advances the submitted turn. |
| Explicit draft-to-queue transfer | Requires the expected draft and input transaction; only this explicit user operation may clear that retained draft with Ctrl-U. |
| Reader-originated child output | Only a change to the visible native composer row counts as composer paint. Status/output rows alone do not prove the draft was consumed. |
| Cursor-only bytes, OSC title-only bytes, local cursor restoration and local screen repair | Not composer paint. They cannot authorize recovery, even after an idle clock repair. |
| Resize, sleep/wake repair or wall-clock step | Not child paint. Resize invalidates paint evidence; repaired clocks are rejection gates only. |
For ego, recovery may reset stale write-side text only after a reader-originated change to the current visible native composer row, ordered strictly after the last input in one monotonic clock domain. The native adapter must still report an empty Ready composer, and output must remain quiet for 1.5 seconds. The editor resets only if its input stamp is unchanged under its mutex; the claim rechecks this gate. Retained/wrapped drafts, modal controls, unknown screens and old empty screens fail closed. Other agents keep their tracked-editor gate.
Dropping phantom tracking without Ctrl-U is not a safe substitute: the next payload could append to an unpainted real draft. Recovery therefore does not write anything without composer paint evidence. The normal managed submission may send its existing Ctrl-U prefix only after the shared empty-composer claim; recovery itself never sends Ctrl-U. In the worst case, one unpainted character plus any number of cursor/title updates still blocks all managed payload bytes. A genuine discard that produces no visible composer-row change also stays blocked rather than risking a real draft.
Already accepted commands and wakes retry on confirmed idle, including stable
Ready observations after the idle edge. A rejected submit is not queued and
must be retried by its caller only when retry_safe is true.
Foreground detection warns once per session when a non-shell process has no recognized agent type or run-config fallback. Such a session retains the safe 200 ms Enter gap during managed injection.
After a complete write, the existing input bookkeeping records the original
text and CR, clears slash mode, and advances turn_epoch once. The MCP handler
waits up to a bounded deadline for OutputRingBuffer.total_written to move past
the pre-Enter offset and labels the existing agent screen state when available.
Local composer clearing, epoch mutation, and the PTY write itself cannot satisfy
that acknowledgement. Movement proves the child terminal reacted, not that the
application understood the command. A complete or uncertain write is never
automatically retryable; only rejection/no-byte failure is.
Direct submit and queued user commands can answer an idle progress-blocked
conversational wait. A direct answer does not flush automated notices into that
wait. Ranked native dialog ownership still wins over a later progress report;
selectors, approvals and free-text modal questions remain protected.
Mobile Queue supplies expectedDraft to validate the live InputLineBuffer before a server-side Ctrl-U and enqueue on this same FIFO. Preflight rejections leave the draft untouched. A write failure may have cleared it already; the caller reports uncertainty and does not retry automatically. Concurrent producers are not transactionally isolated.
Session Chat busy Send uses this FIFO, not the native CLI queue. Its Pending bubbles use the backend entry id. Chat Send now and Compose Steer call send_queued_agent_command_now / POST /sessions/:id/queue/:command_id/send-now. They transfer the selected entry out of the FIFO and reserve the next ready composer, so neither an older queued notice nor a mail wake can take it. The shared forced-steer flow sends Escape to a working Claude Code, Codex or ego, waits up to ten seconds for independently confirmed idle, then submits the full owner text with a separate Enter. It never sends Ctrl+B or plain Enter into a busy composer. This also interrupts a running Stop hook instead of waiting for its next natural tool boundary. An idle agent needs no Escape. An absent id returns false without typing. A concurrent steer is refused; raw human input remains available during the wait. Dialogs, drafts, unsupported agents and uncertain writes fail closed. An unwritten queued prompt is restored on refusal; ambiguous payload writes are never requeued. send_now is interrupt for every supported harness and absent otherwise.
User-composed commands share that gate: the Compose panel’s enqueue action
(enqueue_agent_command / POST /sessions/:id/queue) appends to the same
typed pending_injections FIFO as peer delivery rather than writing to the PTY,
so a command typed by the user cannot steer a turn in progress. It is appended
and then flushed, never handed straight to deliver_message_to_pty: injecting
ahead of any accepted peer message or user command would reorder delivery. Each
flush pops one entry and leaves the session BUSY, so the queue drains one item per
idle window in global acceptance order. state.queued_commands,
list_queued_agent_commands, remove_queued_agent_command and
clear_queued_agent_commands cover every parked entry, including server wakes;
clear removes the whole pending queue. Each user command
carries a process-unique id so the Compose panel can delete a single entry —
a queue position would shift under the caller as the FIFO drains.
A queued user command at the FIFO head can answer an idle session’s
progress-blocked wait. The gate reads the ranked awaiting source; native
questions and approval dialogs still block delivery. The accumulator does not
let a late blocked progress report replace a native dialog’s awaiting source.
Server-authored notices
and initial prompts cannot use this exception or be overtaken. Confirmed idle,
foreground ownership, an empty composer and certain delivery remain required.
Successful submission emits progress-superseded, which retracts only a
progress-owned wait, not a native dialog that replaced it.
Queue requests may include idempotencyKey. A per-PTY bounded recent-key set
reserves acceptance atomically with FIFO append, before the blocking flush. The
last 128 keys survive drain and cancellation and are removed with the PTY;
backend restart also clears them. Duplicate requests do not flush or append.
Both HTTP and desktop IPC return accepted, typed and current queued;
a recognized retry can be accepted even with an empty queue and no new typing.
Each nonempty flush attempt emits one queue delivery attempt tracing record with
the session id, agent and shell states at the attempt, queued counts before and
after, whether text reached the composer, whether submission was confirmed, and
whether Enter was sent separately. An uncertain delivery reports uncertain fields
rather than claiming a completed submission; command text is never logged.
Deferred attempts include defer_reason (unavailable agent, shell busy,
unconfirmed idle, confident question, partial composer, or a lost claim). If a
Ready screen becomes confirmed after silence already marked the shell idle, the
timer retries this same guarded flush without waiting for another shell
transition; a debug record names that ordering and the pending queue depth.
Status line ticks: Animated spinner repaint evidence refreshes both shell activity and SilenceState, preventing low-confidence question/tool-error events from contradicting a busy tab. Static mode/footer rows remain chrome only and do not prove activity.
Status line dedup is per turn: ChunkProcessor.last_status_task keys its dedup on (turn_epoch, task_name), so a spinner rotation inside one turn stays suppressed while the first status line of a new turn always re-emits. The epoch must stay in the key because an agent may name every turn identically — Codex always reports Working. A session-lifetime dedup swallowed every turn after the first, and since the status-line event is the only thing that clears the previous turn’s suggested_actions (which session_state_with_shell reads as a completion marker), the session reported a busy agent as completed/idle permanently.
Agent detection: detectAgentForTerminal() fires on shell-state transitions (immediate on idle, 500ms debounce on busy). A 30s fallback poll catches cold starts. This replaces the previous 3s polling interval, reducing syscalls ~30x.
Amber Tab Styling
Sessions created via HTTP/MCP (remote sessions) are flagged with isRemote. The tab bar applies an amber gradient background and amber bottom border (rgba(251, 191, 36, ...)) to visually distinguish remote-created sessions from locally spawned ones.
Concurrency
- Sessions stored in
DashMap<String, Mutex<PtySession>>for lock-free concurrent access - Each session’s writer has its own shared
Mutex, independent from thePtySessionmetadata lock. User input, HTTP/WebSocket input, agent injection, and terminal-generated protocol replies all serialize through that writer. A reader may therefore wait for an in-flight write without blocking PTY draining, and mandatory device/kitty query replies are never dropped merely because session metadata is contended. - Reader thread holds
Arc<AtomicBool>for pause signaling - Metrics use
AtomicUsizefor zero-overhead counting
Claude transcript discovery, session verification, project-directory lookup and subagent paths share the Claude project-path encoder. It replaces every non-ASCII-alphanumeric character with -, including Windows drive colons, spaces, Unix dots and underscores. Claude’s hashed suffix for paths whose encoded slug exceeds 200 characters remains unsupported.
Stored terminal marker coordinates
OSC 133 command boundaries and OSC 7770 prompt rows are eviction-stable all-time rows. The PTY reader forwards these coordinates unchanged on IPC and HTTP/WS; it must not add the end-of-chunk history base.
Claude launch settings apply to prompt and option-first launches. Shell wrappers use backend-captured installed CLI help to recognise subcommands and aliases, without probing again at launch. Help is unavailable unless its Commands: section has parseable command rows; empty, whitespace-only or truncated help therefore uses the complete recorded Claude help, including auth and advertised aliases. Rust publishes this fallback to the shell environment; generated wrappers also embed it for an unusable cached value. No separate fallback verb list is maintained. The exact hidden remote-control command also bypasses settings because its reported CLI refusal confirms that requirement. Hyphenated prompts retain settings. Explicit settings and bare mode remain authoritative.
Headless PTY registration uses the requested terminal geometry without a minimum VT width. A same-size resize preserves that width.
MCP retained-output pages use VtLogBuffer::lines_since_logical source-row
start/end positions, including omitted chrome slots. The end is a page boundary,
not the total scrollback size. Logical wrap lines stay whole; raw pages use the
existing output ring and original-byte cursors. See MCP output paging.
Grok transcript Chat view
A Grok terminal is tailed through the same chat_view::View, with GrokAdapter
(chat_view/grok.rs) reading ~/.grok/sessions/<cwd>/<id>/chat_history.jsonl.
updates.jsonl is not read: it carries no user turns. A human prompt is a
user row with prompt_index and no synthetic_reason, unwrapped from
<user_query>; context, reminders, hook feedback and task notices are dropped,
compaction_meta becomes a notice card. Reasoning summaries become thoughts,
tool calls and results become folded cards (orphan results dropped), and
server-side backend_tool_call rows become finished cards. The binding is
agent_session::grok_chat_history_for_pid: a unique active_sessions.json
entry must match the terminal’s cwd and PID. On Unix, a live native child in the
terminal’s foreground process group also matches: the supported npm Node
launcher owns that group but Grok registers the native child’s PID. Multiple
matching registrations fail closed. The session directory must exist. The newest-session fallback of discover_grok_session never feeds
Chat; without an exact entry the snapshot answers not_bound. A tab whose agent
changes between Claude and Grok restarts the view. Fixture:
fixtures/chat_view/grok_chat_history.jsonl (real rows, payloads replaced).
Claude transcript Chat view
Claude Edit inputs with string file_path, old_string and new_string
project to ACP diff content. Old/new excerpts use the redacted 20,000-character
text budget rather than the 1,000-character raw-input budget. The adapter keeps
that bounded content with the pending tool ID and includes it again with the
result, because ACP tool content updates replace the previous content. Missing
fields and non-Edit calls retain their existing projection. Tool status remains
authoritative: diff content alone does not mean that the edit succeeded.
chat_view::View::advance reads complete JSONL rows through transcript_tail,
projects them with ClaudeAdapter, and retains a bounded ACP update log. Each
view retains an open file-identity handle: replacing a JSONL at the same path
resets the conversation even when the replacement is as large as the old file.
The existing one-second ticker emits wake events; snapshot reads keep it alive.
Binding discovery and its ten-second recheck require the parent JSONL, without
requiring a subagents directory. Each frontend watch owns its cursor; delayed
listener cleanup and snapshot replies from an earlier mount cannot clear or
replace the current Chat conversation.
Ticker stops log a WARN with the terminal ID and reason, and failed frontend
refreshes log a WARN before retrying on the next wake or existing keepalive. It
recognizes older prompt-ID rows without origin, excludes harness command echoes
and sidechains, and preserves image/PDF result markers and model fallback cards.
Recorded sanitized cases and the last-30-days schema counts are in
fixtures/chat_view/recorded.
The opt-in disk_ticker_http_store_browser_follow_proof test runs the real
snapshot/SSE routes against two fixture-bound disk transcripts, and renders the
production store and Chat component through worktree Vite. It covers appends,
same-path replacement, a new JSONL binding and a CLI/Chat remount. Set
TUIC_CHAT_FOLLOW_PROOF_DIR to a directory under the worktree and run it with
--run-ignored all; the installed stealth browser wrapper is required. Binding
discovery itself is outside this fixture. Screenshots and proof.json stay in
the specified evidence directory.
The opt-in view_real_transcript_throughput measurement reads an authorized local
file at runtime through the same path, reporting both the 2 MiB attach and full
parse times plus process peak RSS. Raw transcripts are never committed.
The recorded chunk-path parity gate covers all .tcap captures under src-tauri/,
including captures in terminal crates. See Recorded replay oracle
for scope, first-difference diagnostics and the explicit regeneration command.
Bound Telegram interruption
The Telegram daemon arms a draft ownership token in SessionState under the
session writer mutex. Raw desktop/HTTP input, atomic input pairs, managed agent
submissions, trust answers and retained-composer Enter retries retire that token
before writing bytes. Retirement records the current epoch, so a delayed draft
cannot rearm it before native submission bookkeeping establishes a new turn.
Terminal protocol replies leave it intact. Stop consumes
the current draft, then checks the token, peer mapping and turn epoch under the
same writer mutex. It writes one Escape without feeding the input line editor.
SilenceState is released before the native write; synchronous captured output
can therefore traverse the normal chunk processor. Input bookkeeping remains
post-write and keeps its existing per-request boundaries.
Remote terminal metadata
Desktop terminals owned by a remote connection subscribe to that daemon’s
/sessions/{id}/stream WebSocket for parsed events, activity, title and exit.
Local desktop terminals retain IPC subscriptions. OSC 0/2 titles and resets
are dual-emitted: pty-title-{id} carries the text on IPC, while PtyTitle
reaches the per-session socket and /events (pty-title, {session_id,title}).
A reset carries an empty string. Titles do not change semantic session activity
and bypass the lossless state queue. Authoritative lifecycle snapshots and pushes
apply agent_type immediately, including removal when the shell returns; the
30-second foreground probe remains a recovery/discovery path.
History-anchored viewport scrolling
Coalesced scrolling uses one atomic latest-wins slot for both transports. terminal_scroll_to_anchor encodes an all-time row anchor in that slot; the ticker resolves it under the VT lock after pending output. Null follows output. Evicted anchors clamp to the oldest retained row. Offset commands share the slot, so mixed clients retain request order.
Codex rollout discovery
Heuristic Codex session discovery shares a watched candidate index per CODEX_HOME
(up to 16 stores). It scans only today’s and yesterday’s rollout directories on
initialization. Later lookups use the index; file events refresh changed rollout
paths. Date changes, directory creation/removal/rename events and lost-event
notifications rebuild the recent-day snapshot. A Modify(Any) notification
for an existing directory does not invalidate file candidates; Windows reports
these notifications for directory metadata too. Missing directory paths still
trigger recovery. Watches cover only the recent day trees and their shallow
parent boundaries, not the lifetime session tree. Watch failure falls back to
fresh recent-day scans rather than serving stale entries. A replaced watched day or parent directory invalidates the index so the next lookup re-arms its watches, even when the date paths do not change.
Candidates still require a readable recorded cwd, an age of at most five minutes and an unclaimed session ID. Age and claimed IDs are checked for each lookup. Replacement and deletion events revoke prior candidates. This optimization does not make heuristic discovery an exact PID binding or change native Chat binding.
Codex Chat: exact native hook binding
The Rust chat_view::codex::CodexAdapter maps Codex 0.162.1
event_msg.item_completed records to the same ACP updates as the Claude adapter.
It retains completed user/assistant text, reasoning summaries, command executions
and MCP tool calls. Tool cards include a main-argument title, bounded rawInput,
final status and bounded output. Shared Claude redaction and truncation rules apply.
response_item duplicates, unfinished tools and hook instructions are ignored.
Unknown row/item kinds and malformed JSON are counted without stopping later rows.
The shared tail/log has an adapter dispatch seam and preserves its parser on reset.
Codex Chat accepts only native SessionStart/UserPromptSubmit evidence. The
existing managed Codex hook base64-encodes its JSON stdin on OSC 7770 as
codex-session=<TUIC_SESSION>:<payload>. The terminal reader checks its own
inherited TUIC UUID and stores the thread id, rollout path, cwd and foreground
PID in live session state. Every Chat read validates that PID is still live,
the hook/terminal/rollout cwd agree, and the first session_meta.payload.id
exactly matches the native thread id. Header reads are bounded to 64 KiB.
No directory scan or newest-file fallback participates in this binding.
Thread replacement discards the cached conversation. Shell return, foreground
agent change and PTY exit revoke identity; a changed/dead PID also fails each
read and lifecycle snapshot immediately. IPC and HTTP/SSE publish only validated
codex_binding: { session_id }; absence retracts frontend exactness. Native
evidence is live state, not a persisted proof that can survive process exit.
The normal persisted agentSessionId remains available for resume.
Codex 0.162.1 was verified with an isolated CODEX_HOME, inherited TUIC_SESSION and a native SessionStart hook that cancelled before inference: no model request was made. Native hooks must be installed/updated through the existing global hook installer, enabled and trusted by Codex. Launch-scoped turn-complete notify alone does not establish identity. Unsupported versions, missing/untrusted hooks, Windows (the existing tty hook transport is Unix-only), and remote terminals keep Codex Chat unavailable. TUIC never bypasses native hook trust.
Session attachments live in the app data directory, keyed by the runtime PTY id.
bind_pty_identity provisions the directory and shell grant environment; structured
launches pass the same directory through agent_hook_launch::launch_args.
cleanup_session and tombstone_transient_cleanup remove it at the existing close,
kill and exit boundaries. AppState::new sweeps session directories only when their recorded
owner PID is provably dead. Live, reused and unknown PIDs are preserved across
concurrent instances. The owner marker sits outside the granted directory. No cleanup visits a repository directory. Resumed tabs use
new runtime PTY ids, so their read grants point to fresh storage.
Suggest choices are published once when the agent is ready, including while background descendants keep the shell busy. The completion lifecycle event still waits for an idle shell and settled background work; publishing choices does not release that gate.
Pending follow-up choices survive a working spinner until they are published, including a Stop-hook repaint after Claude has already emitted its idle hook. Reopening working state retracts completion but retains undelivered choices for the same input epoch; published choices and choices from a submitted previous turn are discarded. While the shell is busy, public Claude session snapshots use that same settled-completion predicate, so a retained final marker does not report completed/idle during active Claude Stop hooks. A final suggest: marker may share a Claude redraw with its spinner; this is not a new turn. Working evidence can still reopen an idle or delivered completion (including a blocking Stop hook or a Codex internal continuation).
Background desktop visibility and remote observers
Background mode saves desktop visibility, then clears it while the windows are hidden. All terminal WebSocket formats hold a session observation guard; SSE holds an all-session guard because its event stream is not session-scoped. The standby final eligibility check shares the visibility lock with observer attach: a client either prevents SIGSTOP or wakes the already parked process. The final check also reads current session visibility under that lock, so Show invalidates a standby tick selected while the desktop was hidden. Disconnect releases only that observer and starts a full standby-timeout grace window. HTTP output reads and input also reset remote activity and wake a parked session under the same visibility lock. Desktop raw input uses that same activity and wake path before writing bytes, so an already parked shell can recover even without another tab-visibility transition. Recent user input blocks standby even if the parsed shell idle timestamp is older. These activity clocks do not change the agent’s semantic busy/idle state. Showing the desktop restores saved visibility and SIGCONTs only terminals that are visible again.
Standby only stops a foreground group whose pgid equals the PTY child’s PID.
An agent launched as a separate foreground job under an interactive shell stays
running: SIGSTOP would let the shell reclaim the terminal, and SIGCONT cannot
restore the job’s foreground ownership. Eligible groups are recorded by exact
pgid in standby_sessions; wake never recomputes the current foreground group.
A failed SIGCONT retains the record for retry.
Rust-owned suspended tabs
Rust owns tab suspension in suspended_sessions.rs. It checks the current parsed/shell state, persists a record keyed by stable TUIC identity before closing the PTY, and dual-emits session-suspended before EOF. session_resume.rs verifies the agent store using the saved launch environment. Its host-shell decoder preserves Windows path backslashes and decodes the same quotes and cmd escapes that the launch writer emits, so a quoted profile directory selects the original session store. Resume creates the replacement PTY in Rust and the frontend attaches its returned id. No WebView response is needed; working agents, busy shells, unanswered input and queued commands remain refused. A current-turn pending descendant probe also refuses suspension directly, even when an ego turn is displayed as idle and background_work is false.
Each Resume allocates a fresh PTY key and binds the saved TUIC identity before spawning the child. Exit tombstones and delayed cleanup belong to the previous PTY. Suspended-session RPC callers supply top-level session/repository/cwd ownership context, so remote operations stay on the owning daemon even after suspension clears the live session id.
Shared session wake
session_wake::ensure_live checks the live identity map under the suspend lock. Live standby sessions receive SIGCONT; retained sessions resume from the durable record with the same TUIC identity. Concurrent callers receive the same PTY. Creation or storage failure returns a reason and retains the record. Submit uses the existing pending-injection ready gate; mail remains in the inbox and queues only a payload-free wake notice.
Backend wake creation events include tuic_session alongside the fresh PTY id. Clients reattach the existing suspended tab by that identity; cwd never identifies a tab. Retained aliases resolve to the saved peer identity before mail validation.
Guarded plugin submissions
send_agent_input_if_empty_blocking reserves a per-session reentrant input transaction across readiness/draft checks, the existing agent submission writer, and input bookkeeping. Desktop raw input and HTTP/WS raw input hold the same transaction through bookkeeping, so typing before a guarded send prevents it; typing during either scheduling gap waits until after Enter and remains a draft. The lock is reentrant because bookkeeping can synchronously enter another input helper. The ordinary explicit plugin reply path is unchanged.
Automatic idle-agent hibernation
The backend checks unattended top-level agent tabs every five seconds. agents.hibernate_idle_minutes defaults to 60 awake minutes; zero disables the sweep. agents.hibernate_scope defaults to background_only; always also permits foreground hibernation. Both machine-owned controls are in Settings → Agents (Expert Mode).
Hibernation requires an idle agent and a verified resume session in its saved profile. Plain shells and agents without a verifiable resume session stay live. Unread peer mail, pending commands or background work, awaiting input, attached readers, keep-open tabs (whether addressed by their live PTY or durable peer identity) and open automation runs prevent hibernation. Managed children retain their separate idle-close policy. Sleep gaps longer than 30 seconds do not advance the idle clock.
The normal Rust suspension path persists reason: "idle_hibernate" before ending the PTY. Opening the tab, submitting input or sending peer mail uses the shared wake path. Storage or resume-verification failures leave the live session intact.
Desktop visibility and frame timeout recovery
Hidden desktop subscriptions receive no grid frames. The backend retains the authoritative grid and scroll position; showing a viewport requests a full frame. The desktop transport serializes epoch-scoped visibility publications so a delayed hide cannot overwrite a newer show. It requests the show frame only after publishing visibility; the canvas owns that request only for WebSocket transports. Bell events are emitted by the PTY reader through desktop session events and HTTP SSE/WebSocket events, independently of grid serialization. Repeated BEL bytes in one processed chunk coalesce into one session bell. History-base metadata refreshes with the show frame. Browser/PWA grid watchers remain independent, and backend activity/question parsing keeps running.
For a visible desktop, three abandoned frames without real receipt progress pause ordinary delivery until a new receipt or explicit full-frame request. Synthetic abandonment does not count as receipt progress. A frame timeout alone does not prove a frontend heartbeat failure.
Native ego OSC 7770 ego-recovery snapshots are validated at the PTY boundary
and accumulated as SessionState.provider_recovery. The existing desktop and
SSE session-state-changed snapshot carries the same object on both transports.
The parent lifecycle inbox receives entry/exit notices. MCP session force_retry,
desktop force_retry_provider_recovery_command, and HTTP POST /sessions/{id}/force-retry
share one backend transaction. It
requires an ego recovery snapshot and an empty tracked composer, holds the input
transaction, and uses the normal agent-aware command writer to submit /retry
once (no automatic retry or queue). See output-parser.md for the wire contract.
Native ego agent-event verbs
ego 0.4.3 writes ESC ] 7770 ; agent-event=<base64 JSON> ESC \ beside its coarse
state frames (contract: ego docs/internals/terminal-agent-events.md). The
single consumer is pty/ego_events.rs (EgoEvents). It runs for agent_type == "ego" and also while agent_type is still unknown, because a plain shell tab
learns it only on the 1 s silence tick. It accepts version 1 envelopes for agent
ego, at most 16 KiB decoded, and ignores anything else without touching state.
Frames before session_start are ignored: the contract makes it the header of
every stream and describes no mid-stream attach.
| Event | Effect on the accumulator |
|---|---|
session_start / session_end | Settle the modal, end all tools, forget turn, children and outcome. |
turn_start | Opens the turn; forgets its children and the last outcome. |
tool_start / tool_end | Tool readout (tool-activity, see above). |
child_start / child_activity / child_end | Adds / relabels / removes a child of the current turn by id (duplicates ignored, at most 64). |
modal_open / modal_end | Names the open wait; only the matching id settles it; a settled id never opens again. |
turn_end | Records data.outcome and ends the turn, its children, tools and modal. Late frames of that turn are ignored. |
ChunkProcessor::publish_ego_turn emits child-activity {children} and
turn-outcome {outcome} only on change; the accumulator stores them as
SessionState.native_children and native_turn_outcome, which PtyExit
clears. They are descriptive only: busy, idle and awaiting still come from the
coarse state frames, so a modal_open alone never raises awaiting. Replay
evidence: six real 0.4.3 captures under
src/fixtures/agent_prompts/ego-native-0.4.3-*.pty.
ego transcript Chat view
The export reader checks the child exit status before reporting an absent header.
An incompatible executable that refuses --after returns an export failure with
its configured path and status, not a misleading transcript-format error. A
successful empty export still reports the missing v1 header.
The foreground ego PID first resolves through the process-owned
EGO_HOME/pids/<pid>.json. The indexed UUID must have a held writer lease
with the same PID under EGO_HOME/sessions. A corrupt, mismatched or unlocked
index target fails closed; only an absent index uses the legacy lease scan.
The root/PID cache still validates held leases for older ego versions.
No newest-file fallback is used. A failed environment read
fails closed rather than selecting the host’s default ego store. The configured
absolute ego executable reads the bound session through the published local
transcript v1 command, ego export SESSION --format transcript --after SEQ.
No private event-log layout is consumed. Missing binding or an unreadable export
is returned as not_bound so both frontend hosts retain the reason.
chat_view::View::advance invokes this incremental source from the existing
ticker. It checks the header version/session before accepting records, bounds
each record to one MiB and each export to ten seconds, and keeps the existing
2000-entry/four-MiB view log. Session-local sequence gaps are valid. Completed
messages are authoritative; preview deltas are omitted to avoid duplicate full
answers. Tool starts/results share their item ID. Goal continuations and
compaction checkpoints are notices rather than human input. Rebinding after
compaction resets the shared epoch and adapter cursor. No separate follow
process, channel, ACP connection or browser event stream is added.
The real CLI loopback recording and provenance are in
fixtures/chat_view/ego/README.md. This requires an ego version with the published
transcript v1 contract; older executables return an unavailable reason.
Exact soft-wrap text boundaries
Grid text and styled log extraction preserve trailing cells on WRAPLINE rows. Those spaces are source content, not padding. MCP text output concatenates these rows without inserting a separator. Styled HTTP, WebSocket and IPC log rows include wrapped: boolean; a finalized row can still continue into the current screen. Only non-wrapped row tails are trimmed.
Slash-menu replacement and retraction
The chunk processor parses the current screen while the input FSM is in slash
mode. A single filtered command is a valid menu. A previously published menu
gets one empty SlashMenu event when the menu disappears or slash mode ends,
so the shared session state cannot retain an older list. Empty-menu retraction
is not emitted repeatedly during busy output. No mobile-only filter is used.
Overdue background wake evidence
The process snapshot refresher checks queued BG DONE user-command entries once
per second on its blocking worker. After 60 seconds in the queue, each entry
claims one diagnostic report. The report uses source bg-wake in the normal
bounded application log ring. It snapshots all injection gates, the cached
screen activity, background-work/probe state, and a fresh OS process inventory.
No extra enumeration occurs when no BG DONE entry is overdue. An overdue batch
shares one fresh enumeration. Relevant foreground and detached-runner trees
are limited to 128 rows per session, with a total and truncation flag. Process
rows contain only PID, parent PID, executable basename (64 characters), age and
a matching-runner flag. Queue text, argv and environment are not logged.
This observer is independent of busy/idle edges. It does not change queue order,
claims, retry rules or process reconciliation. A queued CLI receipt remains
an acceptance receipt even after delivery. Missing inventory is reported as
unavailable, never as proof that work stopped.
Abandoned shells
Desktop sidebar session rows and mobile session cards mark a parentless plain shell as Abandoned after one idle hour and show its idle age. The five-second backend sweep requires a fresh OS process inventory: the PTY child must be an interactive shell with no child processes. An unknown inventory, script, foreground command, background child, detached TUIC job, managed identity, live child session, pending input or keep-open hold prevents closure. Unsupported or incomplete OS process observations fail closed.
Settings → Agents → Idle agent hibernation (Expert Mode) includes Close abandoned shells after (hours) (agents.abandoned_shell_hours). The machine-owned value defaults to 0 (off); whole hours from 1 to 65535 enable closure. Idle age is measured from the most recent input, output or semantic activity, including elapsed time while the machine sleeps. Closure rechecks the process inventory and activity at the destructive boundary, and uses the normal session close/tombstone path. The sweep can lag the threshold by one five-second tick. A remote daemon applies its own setting, not the desktop host’s value.
Session usage identity
The mobile overflow uses session_usage.rs, not parsed warning percentages or
user-configured terminal chrome. Claude reuses the live profile resolver and
cache with primary OAuth GET only. Codex reads live process HOME/CODEX_HOME
and profile flags, rejecting unbound configuration overrides and local-provider
modes. Codex root profile flags precede the App Server subcommand. ego requires
the existing exact PID/session binding, the terminal executable (or normal agent
binary discovery), the manifest workspace and the actual store. AI Chat ACP
executable configuration is not required. Explicit CLI store
overrides remain unavailable rather than guessed. Its usage --json output is
capped at 4 MiB and 25 seconds. The status-bar badge and session details share
one identity-bound raw report cached for 30 seconds; formatting remains separate.
Both consumers recheck the live binding after every read, including cache hits,
and the 30-second deadline includes the single-flight lock and reader queue. Codex snapshots are cached for five minutes. Cache entries are
bounded to 32, with per-identity single flight and two concurrent CLI reads.
Cached fallback after a transient failure is limited to 30 minutes; session details
mark it stale. The compact ego badge retains its existing text format.
Claude cache fallback retains its existing age policy and is explicitly stale.
Secret output ingestion
ChunkProcessor masks known values and spawn-bound task secrets before feeding
bytes to the grid, output ring, WS broadcast or tcap recorder. The reader uses
the same sanitized chunk for output watchers and scoped diagnostic byte rings;
ordinary sessions keep their pre-transform flight recorder. A zeroizing stream
carry withholds possible split-value prefixes. Terminal queries end the current token:
a complete known value is masked, while an unresolved prefix is released before
the query so cursor replies include preceding text. This assumes producers query
between tokens, never inside a secret. Non-query controls (including SGR and OSC
metadata) and plain read boundaries remain transparent to secret matching.
Teardown removes the session’s mask material, while retained terminal output is already sanitized. Task TTL
revokes new environment injection, not an active session’s masks.
EOF escape-buffer residue goes through the same ChunkProcessor sanitizer before
ring, WS, history, capture and watcher publication. Embedded base64 credentials
use bounded aligned representations, including shared boundary-character bits,
so arbitrary read splits do not lose decoding context. Retained overlap bytes
keep their existing redaction marks while remaining available for future matches.
Pi managed extension lifecycle
agent_hook_pi owns a first-line-marked extensions/tuic.ts under the Pi agent directory. Lifecycle callbacks and paired extension UI promises emit ordinary OSC 7770 state frames to the controlling terminal. A modal owner survives tool callbacks; a finally path returns to current activity, and shutdown invalidates old owners. Both desktop and HTTP/SSE render the normal session accumulator. The native pi-extension-modals-2629.tcap fixture records geometry, input/output directions and original chunks from Pi 0.84.2. Replay tests include adjacent immediate-failure records coalesced into one read.
Grok native hook receipts
ChunkProcessor correlates owner-scoped OSC 7770;grok-hook=<TUIC_SESSION>:<base64 JSON> receipts by native session, prompt and tool request. Once native receipts are active, imported coarse Grok state hooks cannot settle or rearm a permission wait. The shared parsed events and desktop/HTTP event paths remain the transport contract. PTY and ACP routing remain separate; this decoder handles only Grok PTY output.
Codex global hook trust is setup state, not a parsed terminal wait. Native
hooks/list verification can report reviewRequired in Settings without
emitting awaiting/busy/idle. Launch-scoped status notifications, PTY event
accumulation and ego PTY/ACP request ownership are unchanged.
Native Windows hook availability
Native Windows does not install or inject TUIC’s external POSIX status hooks. Hook state returns unsupported, and hook/status setters reject changes before writing preferences or user hook files. Saved preferences and existing hooks remain intact. Settings hides these controls based on the owning backend response, including remote machines. External agents retain heuristic detection; ego keeps native PTY OSC signals and its separate ACP path.
Claude permission hook ownership
Claude launch and installed hooks carry native stdin as base64 JSON: OSC 7770;claude-hook=<TUIC_SESSION>:<hook pid>:<base64> ST, then OSC 7770;claude-hook=<TUIC_SESSION>:<hook pid>: ST ends the receipt; the hook pid keeps concurrent hooks apart. Like every generated hook (Claude, Gemini, Codex and its notify script, Grok), the hook posts its frames to POST /sessions/$TUIC_SESSION/hook on the local socket $TUIC_SOCKET (#2749-bee7). The route feeds them to the session’s PTY reader between two reads, so they never share the tty with the agent redraw and never reach the grid. The reader keeps at most 1 MB of base64 for each receipt and drops a tool_input over 16 KB. When the socket is missing, the HTTP client is missing or TUIC refuses the post, the hook falls back to the tty: frames of at most 768 base64 bytes, each a separate printf, because sh printf writes in 1024-byte pieces and a redraw escape cut one large frame (#2747-636f). A fallback receipt over 32 KB of base64 is not sent, because a macOS pty writer sleeps mid-write under backpressure and another writer gets in. A client timeout does not fall back, because TUIC may have processed the frames already. The reader accepts the frames only for the owning Claude terminal. UserPromptSubmit scopes pending tools by native session and prompt; PermissionRequest matches tool name/input to an unresolved PreToolUse, because the recorded CLI omits the request’s tool id. Only Notification(permission_prompt) can create this wait. Broad tool success/failure clears its matching owner. Other tool activity cannot clear an open permission, question, plan or elicitation dialog.
On POSIX hosts the generated claude.json also sets statusLine to agent-hooks/claude-statusline.sh, with only type and command, so the user’s padding and refreshInterval still apply (Claude merges the object field by field; spike S5 in quota-source-spikes.md). The relay posts the status line stdin, with CLAUDE_CONFIG_DIR and HOME as x-claude-config-dir / x-home, to POST /sessions/$TUIC_SESSION/claude-status-line on the local socket. TUIC stores the rate_limits.five_hour / seven_day windows for that credential, which the claude-code quota owner returns from observed(), and answers with the user’s own command: the first statusLine.command of <project>/.claude/settings.local.json, <project>/.claude/settings.json, <config dir>/settings.json. The relay runs it under /bin/sh with the same stdin and prints its output. A repeated identical payload keeps its first arrival time. Without a socket answer the relay prints nothing. Windows does not get the relay.
The Claude permission adapter joins wrapped option labels beneath the exact permission heading and footer. The normal native choice-input path then clears accepted, refused and cancelled permissions even when the CLI emits no post-tool hook. Prompt submission, Stop, StopFailure, SessionEnd and confirmed foreground exit retain their existing retraction paths. Duplicate completed tools cannot recreate a request. Bookkeeping retains at most 64 pending and 64 retired tool ids; stored tool input is capped at 16 KiB. The lifecycle envelope is capped at 1 MiB encoded. Invalid/oversized receipts leave screen recovery available. Both desktop and HTTP/SSE clients consume the existing session-state accumulator; no transport fields change. Native ego PTY OSC and AI Chat ACP owners remain separate and unchanged.
A resolved native choice hands its answer from input bookkeeping to the reader through SilenceState. The reader retires the permission owner before another native request, even when the accepted tool is still running; partial wizard answers keep their question owner.
Silent managed PTYs receive an additive stalled inventory flag and one parent mail per silence episode; the same sweep nudges the worker once and never stops the PTY: the stop is an explicit parent decision. A BLOCKED hold is exempt; the notice reports running background work. See silence policy. Detached CLI job deadlines stop only their own command group/tree; see CLI deadlines.
AI Chat busy, awaiting and idle state is not parsed from terminal output. It is derived in Rust from the ACP turn, open seats, tool calls and ego child frames (src-tauri/src/acp/activity.rs) and never enters ParsedEvent or the PTY session-state accumulator (#2637-c6d3).
Forced-kill exit status
When a session is removed for an immediate kill, teardown records an exit-code
fallback before the reader can publish the exit event. Unix uses 128 + SIGKILL
(137). Windows uses 1, the termination code passed by portable-pty to
TerminateProcess. The reaped child status replaces this fallback when available.
Output Parser
Module: src-tauri/crates/tuic-terminal/src/output_parser.rs
Parses terminal output to detect structured events: rate limits, status lines, PR URLs, and progress indicators.
For mobile choices, choice-prompt includes an optional selection_mode.
The Claude-specific Ink AskUserQuestion parser requires a full-bleed
Enter to select footer and reads numbered options across description rows;
it emits navigate-enter, so the client sends arrow keys followed by Enter.
Other numbered confirmations retain their existing key selection path. The
screen trim keeps an open Ink dialog intact because its highlighted option
also begins with the composer glyph ❯.
Terminal-grid row snapshots retain the base character and all stored zero-width characters. A combining mark received in a later PTY chunk marks its base cell dirty, so changed-row consumers receive the updated text. This preserves the stored sequence without normalizing it or changing parser matching rules.
A Codex interrupt banner beside the live composer can close native busy only while a host-requested interrupt is pending. The existing interrupted-screen transition retires native busy as well as shell busy; historical banners and still-working screens do not override native activity (#2961-8724).
Usage
#![allow(unused)]
fn main() {
let parser = OutputParser::new();
let events: Vec<ParsedEvent> = parser.parse(terminal_output);
}
ParsedEvent Variants
RateLimit
Detected when terminal output matches known rate limit patterns from AI agents:
#![allow(unused)]
fn main() {
ParsedEvent::RateLimit {
pattern_name: String, // e.g., "claude_rate_limit"
matched_text: String, // The matched text
retry_after_ms: Option<u64>, // Parsed retry delay
}
}
StatusLine
Agent status output (e.g., token usage, timing):
#![allow(unused)]
fn main() {
ParsedEvent::StatusLine {
task_name: String,
full_line: String,
time_info: Option<String>,
token_info: Option<String>,
}
}
PrUrl
Pull request URL detected in output:
#![allow(unused)]
fn main() {
ParsedEvent::PrUrl {
number: u32, // PR number
url: String, // Full URL
platform: String, // "github", "gitlab", etc.
}
}
Progress
OSC 9;4 progress indicator:
#![allow(unused)]
fn main() {
ParsedEvent::Progress {
state: u8, // 0=remove, 1=set, 2=error, 3=indeterminate, 4=warning
value: u8, // 0-100 progress percentage
}
}
Question
Agent is waiting for user input (question, confirmation, menu choice):
#![allow(unused)]
fn main() {
ParsedEvent::Question {
prompt_text: String, // The detected prompt line
confident: bool, // Protocol-backed signals are high-confidence
}
}
The emitted JSON also carries the internal _turn_epoch. The authoritative
session reducer ignores question and retraction events from an older input turn.
Question events have two sources:
-
Response-required OSC 777 notifications are parsed from the raw PTY byte stream before VT rendering consumes the escape sequence. Only explicit permission or approval wording is accepted. Generic desktop notifications such as
Claude Code needs your attentionandClaude is waiting for your inputdo not prove that the composer awaits a response; the latter also follows an ordinary completed turn and caused a transient false badge.Every qualifying notification in a raw chunk is retained in stream order; a later OSC sequence cannot overwrite an earlier approval request merely because both arrived in one OS read.
Body Confidence Why needs your permission,approval requiredhigh A request with one reading. Cleared by the answer. is waiting for your inputignored The ready composer can produce the same notification. A visible Ink footer or choice prompt supplies the picker signal. A high-confidence question is retracted by nothing but real user input; the generic body once latched the badge on a session that had finished 17h earlier (observed 2026-08-11).
-
Screen-verified silence detection handles rendered questions (all instant regex patterns were removed due to false positives from Ink agent streaming):
extract_question_line()scans changed terminal rows for?-ending lines, applying content filters to reject code comments (//), markdown headers (#), diff context (+/-), code syntax (->,=>,::,)?), and wrappedsuggest: [ … ]protocol itemsSilenceStatestores the candidate and starts a 10s silence timer- When the timer fires, a visible input box restricts detection to the latest chat content above that prompt; only an unanchored screen may use the bounded changed-row fallback
- If verified, emits
ParsedEvent::Question { confident: false }
- The Ink dialog footer (
Enter to select · …) is the one surviving instant pattern, and it emitsconfident: true. It is matched at column 0 of the rendered row, not of the trimmed text, byis_ink_dialog_footer_row(). A dialog is drawn full-bleed by the TUI, while everything an agent streams — prose, code blocks, a screen it read and quoted back — is indented inside the agent’s own frame. That indentation is the only difference between the footer and a copy of it: the text is otherwise identical byte for byte. Anchoring on the trimmed row let an agent that pasted another session’s screen latchquestion_confidenton its own tab, which nothing retracts, so the tab claimed the agent was blocked on the user for the rest of the turn while it worked (observed 2026-08-30).ink_dialog_footer(), which reads the same row off the full screen as a level forrearm_awaiting_for_open_dialog, shares the same predicate on purpose — the two must never disagree about what a footer is.
Guards against false positives:
- Spinner suppression: If a status-line event was seen within the last 10s, detection is suppressed
- Staleness counter: If >10 non-
?output chunks arrived after the candidate, it’s considered stale - Screen verification: Candidate must still be among the last 5 visible lines at fire time
- User echo suppression: 500ms window after user input ignores PTY echo of typed text
- Resize grace: 1s suppression after terminal resize to avoid re-detection of redrawn content
The managed native v2 plugin translates recorded OpenCode 2.2.3 form.created and permission.asked events to OSC 7770 awaiting. Matching form.replied, form.cancelled and permission.replied events restore current busy/idle activity, not activity saved when the prompt opened. Execution settlement and session/location/plugin teardown clear owned waits. This uses the existing OSC/state accumulator, not a new text parser; shared native background servers remain inactive because they do not own one TUIC terminal.
Hook-instrumented agents report explicit question-tool waits through OSC 7770
state=awaiting. Plan and skill Ink pickers are detected by their rendered
footer, including the full-screen presence recovery when a hook does not fire.
OSC 777 desktop notifications bypass heuristic-question suppression only for
unambiguous permission or approval wording. Claude’s generic is waiting for your input body also appears after a completed turn at the ready composer, so
it cannot set awaiting by itself.
The full-screen Ink-footer recovery requires an active agent identity: retained dialog rows above a returned shell prompt do not establish a wait. Silence-timer chat-question heuristics enforce the same identity boundary, so a retained title cannot restore a low-confidence wait later. It also applies with hooks enabled. A later busy hook can clear awaiting while the dialog is still open. Before recovery, the reader evaluates the last pending Question/UserInput event in the current chunk: a Question followed by UserInput is a clear, not an existing question. An already-active badge or pending question suppresses duplicate recovery; indented quoted footers remain excluded. Once the dialog closes, normal user input and protocol transitions clear the badge.
QuestionCleared
The retraction of a low-confidence Question. It carries no payload:
#![allow(unused)]
fn main() {
ParsedEvent::QuestionCleared // wire type: "question-cleared"
}
Emitted by the silence timer in pty.rs, never by a parser: it means “the
screen is quiet and the tracked question is no longer the current chat prompt”.
Retraction runs independently from the one-shot emission gate. Bare Enter now
produces the same user-input clear and turn transition as every other input
transport; retraction remains the backstop when output changes without input.
emit_question_cleared_if_stale() fires only when awaiting_input && !question_confident && choice_prompt.is_none(), and the state.rs arm
re-checks question_confident before clearing. Confident questions stay sticky
on purpose: grok repaints while it waits, so absence from the current screen is
not proof that it was answered.
Claude can dismiss AskUserQuestion with a bare Esc, which produces no typed
line. When the new output contains User declined to answer questions and the
full screen has returned to the ready composer without an open Ink dialog,
pty.rs emits protocol-question-cleared with the expected question text and
turn epoch. A still-open dialog or a new question in that output chunk remains
awaiting; the reducer checks the expected text and epoch before applying the
clear. Claude can leave an old footer below the ready composer. A choice-clear
event permits recovery when the choice parser no longer finds the dialog. The
same transition retires the native tool and wait records and publishes the new
tool value.
A progress type=blocked report from an agent with a live PTY emits a
confident question with source: "progress-blocked", and the reducer records
that source on the awaiting evidence. When the same PTY later reports done, or
journals a delegated hand-off, emit_progress_entry emits
progress-superseded for that PTY. A successfully submitted queued user command
also emits this event: an idle progress wait accepts the user’s queued answer,
while native dialogs still own their controls. A late blocked report cannot
replace existing confident native awaiting evidence. The reducer clears the badge only when the
current awaiting evidence still has the progress-blocked source: a dialog, a
choice prompt or another confident question records a different source and
stays awaiting. A new blocked report replaces the question text.
Raw Capture Regression Fixtures
Agent-state failures must be captured from the raw PTY stream before analysis.
Enable POST /diagnostics/capture before reproducing, stop it afterward, then
copy the reported capture file (under <config dir>/captures/ by default, or
under the absolute TUIC_CAPTURE_DIR override) into
src-tauri/src/fixtures/agent_prompts/. /sessions/:id/output is not a fixture
source: it is a rendered, bounded ring snapshot and can lose one-shot escape
sequences. TUICCAP2 fixtures preserve the initial terminal geometry,
input/output direction, original chunk boundaries, ordering, and monotonic
timestamps. The decoder still accepts geometry-less TUICCAP1 and output-only
.raw; their replay must supply independently observed dimensions. Replay also applies the production chrome
cutoff before the rendered-row parser and hook suppression.
Output-only fixtures cannot express a missing input-side CLEAR. Framed .tcap
fixtures can reconstruct submitted lines, while the Awaiting RETRACTION block
still drives the real event-bus accumulator and asserts SessionState directly.
src-tauri/src/fixtures/agent_prompts/scenario-matrix.json is the coverage
contract derived from the local Claude and Codex transcript corpora. Histories
contribute semantic shapes (question tools, lifecycle start/complete/abort), not
terminal bytes. Each scenario therefore identifies whether its evidence is a
real raw fixture, a controlled capture template, a runtime regression, or a
synthetic concurrency/state case. A test enforces unique IDs, Claude and Codex
coverage, fixture existence, and the invariant that every state SET declares at
least one CLEAR path.
ApiError
API errors from agents and providers (5xx server errors, auth failures):
#![allow(unused)]
fn main() {
ParsedEvent::ApiError {
pattern_name: String, // e.g., "claude-api-error", "openai-server-error"
matched_text: String, // The matched text
error_kind: String, // "server", "auth", or "unknown"
}
}
Detects errors from two tiers:
- Agent-specific: Claude Code, Codex CLI, Gemini CLI, Copilot CLI (note: the generic “request failed unexpectedly” pattern was removed from Copilot detection due to false positives on Claude Code output)
- Provider-level: OpenAI, Anthropic, Google, OpenRouter, MiniMax JSON error structures
Claude Code has two 5xx renderings and both are covered. claude-api-error matches
the JSON body ("type":"api_error"); claude-server-error-friendly matches the
prose-only form (API Error: 500 Internal server error. This is a server-side issue…),
anchored on the status code because the prose wraps at the terminal width and rendered
rows are joined with \n. The friendly pattern requires a letter after the code, so
the JSON variants above it keep priority and API Error: 529 stays a rate limit.
Final failures and native retries (2335-9c03)
A final API failure sets SessionState.last_error. Desktop, browser and mobile
clients retain the red Error indicator through idle and completion output. The
desktop snapshot adapter maps last_error to awaitingInput: "error"; the
question flag is a different state. Previously that adapter ignored last_error
and replaced a parsed error with null on the next snapshot, so even matched
failures became green. Plain busy repaints and submitted continue input do not
clear an error. A working status row or native OSC 7770 state=busy clears the backend error; a subsequent
successful idle turn therefore returns to Done.
The backend owns the retry (src-tauri/src/api_retry.rs: budget, timer, Ink-safe
submit), so sessions without a mounted Terminal (mobile companion, headless) retry
too; the frontend only shows the red state and the tip. One owner means no double
submit. The timer fires only if its arming is still current. A shell that still reads
busy is rechecked every 5s instead of dropping the attempt; an idle shell gets
continue.
error_kind: "server" enables TUIC auto-retry when the agent’s
auto_retry_on_error setting is true (default false). Backoff is 5s, 15s and 30s,
with at most three injected continue commands. The red indicator remains until
the backend observes recovery: an idle agent after injection is still failed.
Working rows cancel a pending injection but do not reset its attempt budget.
Only a recovered idle turn resets that budget. Authentication failures do not
retry. Native harness retry output is not a final failure.
Native Claude transport/auth and Codex stream errors match short anchored
failure prefixes, not the complete English sentence. Rendered physical rows are
joined with newlines, so a narrow pane can split the remaining sentence.
Claude’s friendly auth/transport signatures accept an unadorned row with at
most two leading spaces or an assistant ⏺ bullet. A tool receipt ⎿, a
tab-indented row, or a continuation with four or more spaces quotes another
process and cannot set an agent failure. The recorded expanded tool transcript
claude-tool-auth-output-2429.tcap covers archived auth and transport diagnostics
through the production event/state accumulator after startup grace.
Codex still requires its final
■ marker, and retry-exhaustion status separators accept wrapped whitespace.
claude-wrapped-provider-failure-2335.tcap records a real 40-column Claude
connection failure, including a wrap inside Connection to the API was lost.
The source-backed inventory tests also exercise 36-, 40- and 128-column rows.
The accumulator inventory test sends those formats through the real VT,
ChunkProcessor and session reducer, then checks last_error after native
idle. JSON matches retain the native API Error heading when it precedes the
error discriminator, so a wrapped error key is not mistaken for a Rust raw
string. Legacy Codex retry-exhaustion separators accept wrapped whitespace.
Native retry and quoted-source negatives remain separate from final failures.
The inventory below quotes source literals. Braced fields are formatter
parameters, not invented captured transcripts. Pattern names refer to
build_api_error_patterns, except for the raw ego OSC consumer.
| Harness and outcome | Source output / boundary | TUIC detection |
|---|---|---|
| Claude: interrupted response | API Error: Connection lost mid-response. The response above may be incomplete.; API Error: Connection lost before a response was produced. Try again. | claude-transport-error |
| Claude: stalled response | API Error: The response stopped arriving. The response above may be incomplete.; API Error: The response stalled before a response was produced. Try again. | claude-transport-error |
| Claude: broken stream | API Error: Server error mid-response. The response above may be incomplete.; API Error: Part of the response never arrived. The response above may be incomplete.; API Error: The response stream was malformed. The response above may be incomplete.; the last two also have and no response was produced. Try again. variants | claude-transport-error |
| Claude: timeout and connection refusal | API Error: Request timed out or API Error: Request timed out. Check your internet connection and proxy settings; API Error: Connection dropped ({code}); API Error: Connection refused — a firewall or proxy may be blocking it ({code}); API Error: Unable to connect to API. Check your internet connection | claude-transport-error |
| Claude: 5xx after native retry | API Error: {formatted_error}. This is a server-side issue, usually temporary — try again in a moment.{status_link}; JSON variant contains "type":"api_error" | Existing claude-server-error-friendly for a status-prefixed formatter, or claude-api-error for JSON |
| Claude: authentication refusal | Invalid API key · Fix external API key; Invalid auth token · Fix external auth token; Authentication required · Sign in again to continue; JSON contains "type":"authentication_error" | claude-auth-friendly / existing claude-auth-error |
| Codex: final stream or timeout failure | ■ stream disconnected before completion: {cause}; ■ request timed out | codex-native-transport |
| Codex: retry exhaustion / 5xx | ■ exceeded retry limit, last status: {status}{request_id}; ■ unexpected status {status}: {body} (5xx) | codex-native-transport; legacy stream error: exceeded retry limit, last status: ... remains supported |
| Codex: auth refusal | ■ unexpected status {status}: {body} or ■ exceeded retry limit, last status: {status}{request_id} with 401/403 | codex-native-auth |
| Codex: intermediate retry | ErrorNotification.will_retry=true calls on_stream_error and updates the status indicator; it does not create the ■ history cell | No new error match for the status-indicator text |
| ego: final connection loss, timeout, 5xx or auth | OSC 777 notify;εgo;{cause}; review the output, then send a new prompt to continue, followed by OSC 7770 state=idle | ego-provider-failure; HTTP 401/403 causes classify as auth, others as server |
| ego: startup auth refusal | εgo: the provider returned HTTP {status}: {cause} with 401/403 | ego-startup-auth |
| ego: intermediate retry | OSC 7770 ego-recovery={...} (waiting / retrying), then clear | Existing provider-recovery overlay, not ApiError |
| ego: turn refused by its own request (preflight gap) | OSC 7770 error={message} (; sent as ,), then state=error, on every refused turn; a bare state=error keeps the last message | Not ApiError: the PTY reader sets last_error and the agent_state=error input before the idle edge. Peer mail wakes, notices, orchestrator wakes, MCP agent submits, guarded automated input and API auto-retry type nothing until a submitted user line or native busy/prompt. Human replies and queued Compose commands still pass. busy clears last_error (#3011-1784) |
Sources:
- Installed Claude Code 2.1.308 bundled JavaScript, executable SHA-256
ca923c86ac84b30574a82331a05b6e066c27477a926ceaffe46a845a33e4dd37.Dl="API Error"at byte 219998177; connection formatterr_eat 220003416; auth literals at 227898061; final error branches at 227926000–227929700;responseUnfinished/ final stream error branch at 229217650–229219150. These are source excerpts, not live captures. The reported connection-loss example also comes verbatim from Boss’s screenshot in story 2335-9c03. - Codex installed version 0.163.0, upstream tag
rust-v0.163.0:
codex-rs/protocol/src/error.rs(CodexErrorDetails,UnexpectedResponseError::fmt,RetryLimitReachedError::fmt);tui/src/chatwidget/protocol.rs(ServerNotification::Error,will_retry);tui/src/chatwidget/streaming.rs(on_stream_error);tui/src/chatwidget/turn_runtime.rs(on_error);tui/src/history_cell/notices.rs(new_error_eventcreates■ {message}). The structured error notification is more precise, but belongs to Codex’s app-server protocol, not TUIC’s PTY transport. No ACP/app-server fallback is attached to a PTY session. The native final-error glyph supplies that boundary. - ego HEAD
52d1746ee981cf06e3352ba84917535c01df951c:crates/ego-cli/src/output.rs(ProviderTurnNotices::observe) emits the final suffix only forTurnCompleted { ok: false, exit_reason: Provider }.run/interactive_driver.rs(Announce::signal) sends failed progress, notification and idle.crates/ego-ai/src/wire/mod.rsformats HTTP errors; the wire modules provide stream causes. The capturedego-provider-failure-2335.tcapand its provenance file retain a real loopback-induced truncated response from installed ego 0.1.4. The raw native final receipt bypasses startup/resize screen-history suppression; ordinary error-looking screen text still uses that suppression.
Gemini’s existing API Error: got status: UNAVAILABLE / INTERNAL, Copilot’s
Failed to get copilot token / expired-token match, and provider JSON patterns
remain unchanged. Grok has no new harness-specific terminal error pattern in
this change; it retains the provider-level JSON path. These existing patterns
are not a verified inventory of every current Gemini, Grok or Copilot failure
format. No missing format is inferred from another harness’s wording. All new
text patterns have negative tests for normal prose that quotes the same words;
only the raw native ego notification can promote its final suffix without a
screen-text match. Remote-tab tint does not override an awaiting Error or question dot.
Intent
Agent-declared intent — what the LLM is currently working on:
#![allow(unused)]
fn main() {
ParsedEvent::Intent {
text: String, // Short action description
title: Option<String>, // Optional tab title from (parenthesized) suffix
}
}
Detected as a plain-prefix token at the start of a row: intent: <text> (<title>), optionally behind an agent bullet glyph or the wrap indent. The intent anchor grammar is stored in
crates/tuic-terminal/src/intent_marker.json and consumed by both Rust capture
and the frontend tint classifier. All agent types use this grammar.
A missing newline before 💬 is recovered only when that marker follows a
closed (title), with optional horizontal whitespace. The shared grammar bounds
the intent before the answer; parentheses inside the answer cannot replace the
title. splitIntentAnswer supplies the same boundary to terminal overlays,
marker projection, answers-only extraction, mobile output and Chat projection.
The intent tint ends at its title and the answer gutter starts at the recovered
marker. A bubble inside an untitled intent or before its title stays literal.
A second bubble inside the recovered answer stays text, not a new row.
Ego chrome is bounded by its native status-row/composer pair, shared with the
ready-screen adapter. A historical submitted > prompt or transcript separator
is not a live composer. When a soft-wrapped response temporarily overwrites the
old composer before its repaint, the response remains eligible for parsing;
the next intent updates both session state and the tab-title event.
AI Chat receives ACP markdown chunks in both desktop and browser mode, without
terminal rows or wrap metadata. protocolText.ts interprets the joined answer
for that UI: it removes the connection acknowledgement, presents anchored
intent: as status, and exposes bounded bracketed suggest: items as replies.
It takes the title from the consecutive parenthesized marker prefix, preserving
parenthesized descriptions and same-line reply text, including replies ending in
parentheses. Ambiguous unbalanced or nested markers remain literal body text.
It leaves fenced or indented code and prose mentions literal. This is a separate
logical-line projection of the terminal grammar: reusing the Rust VT parser here would require
a new backend ACP projection and wire contract, including HTTP/IPC parity.
AI Chat busy, awaiting and idle state is not parsed from terminal output. It is derived in Rust from the ACP turn, open seats, tool calls and ego child frames (src-tauri/src/acp/activity.rs) and never enters ParsedEvent or the PTY session-state accumulator (#2637-c6d3).
Answer rendering is shared by the grid and Chat through answerExtent in suggestOverlay.ts. Adjacent answer markers extend one region across blank rows; non-answer output and prompt rows still end it. The renderer blanks marker cells without changing parsed or copied text. Fenced examples keep literal markers.
Two shapes the row-anchored regex cannot read on its own, both rejoined before it runs:
- After the ack sentence. The protocol puts the ack and the first
intent:in the same message by construction, so an agent that writes them as one sentence run leaves the token mid-row.ACK_SENTENCE_PREFIXallows that one sentence and nothing else — any other leading prose is still rejected, soThe intent: of this codestays prose. - Wrapped across physical rows.
suggest:is bounded by its closing];intent:has no terminator, so the regex$cuts the token at the wrap and drops the(title)— the tab title — with it.dewrap_intent_continuationrejoins indented rows only when the preceding row plus the next word would exceed the terminal width. The parser’s 2048-character budget also bounds soft-wrap traversal, allowing a 12-row intent in a narrow pane. The input-box chrome cutoff bounds continuation reads. Blank rows, bullets, prompt and chrome glyphs, and a closed(title)stop the join. Closing a title-less intent removes an unfinished(title fragment.
The PTY reader retains one open intent per session while a TUI redraws growing
prefixes. It reconstructs soft-wrapped grid lines and joins width-verified
hard-wrap rows before parsing. It reads continuation rows lazily and caches
each anchor for one reader tick, so a repaint below an intent does not
repeatedly scan the same grid rows. The grid reconstruction budget matches
the parser’s 2048-character candidate budget, including UTF-8 and terminal
padding. Long intent text is redacted and truncated to the Progress journal
limit, while the parsed event keeps the full text. An unfinished ( suffix
is recorded as titleless text when a different intent replaces it. The reader
journals on a closed (title), a VTE hard
line break that did not grow the candidate, subsequent prose below the line,
replacement of the line, or an idle turn boundary after output has gone quiet.
Cursor moves, carriage returns, and growing Ink frame repaints do not close an
intent. A repaint that keeps the anchor line while temporarily replacing its
continuation also keeps the open candidate until the completed marker arrives.
A pending intent is flushed when its session is removed. Repainting the
last recorded value adds no journal row; a different intervening intent lets
the earlier value be recorded again.
Agents receive this instruction automatically via MCP init. To use manually without MCP, add to CLAUDE.md or equivalent:
## Intent Declaration
At the start of every user task and each distinct material work phase, emit on its own line:
intent: <action, present tense, <60 chars> (<tab title, max 3 words>)
Example: `intent: Reading auth module for token flow (Auth review)`
The terminal Context bar shows intent separately from the orchestrator assignment and user prompt. The activity dashboard also shows intent (crosshair icon) when available, falling back to user prompt (speech bubble) otherwise.
The frontend also reconciles agent_intent and last_prompt from authoritative
session snapshots, both during catch-up and on session-state-changed. Captured
context therefore does not depend on receiving the original parsed event. The
last substantial prompt still requires at least ten whitespace-separated words;
shorter submissions leave the previous qualifying prompt in place.
Colorization: colorize_intent() wraps intent text in \x1b[2;33m (dim yellow) for the terminal output stream. The optional (title) suffix is stripped from the display. Colorization is agent-gated to prevent false positives.
PWA/REST stripping: LogLine::strip_structural_tokens() removes intent: / suggest: plain-prefix tokens from log line spans before serving to mobile/browser clients. It delegates to output_parser::strip_plain_prefix_tokens, which is built from the same bullet class and ack prefix the parser anchors on — a second copy of the grammar lived in vt_log.rs and drifted, so Codex-bulleted tokens were parsed by TUIC and then shown to the user anyway. The ack sentence is kept; only the marker behind it is removed.
Active subtask detection: The output parser recognizes ⏵⏵ (U+23F5) and ›› (U+203A) mode-line prefixes as active subtask indicators. The active_sub_tasks count is tracked in SessionState and used to suppress premature completion notifications.
PlanFile
Plan file path detected in agent output:
#![allow(unused)]
fn main() {
ParsedEvent::PlanFile {
path: String, // Absolute path to the plan file
}
}
Suggest
Agent-proposed follow-up actions:
#![allow(unused)]
fn main() {
ParsedEvent::Suggest {
items: Vec<String>, // e.g., ["Run tests", "Review diff", "Deploy"]
}
}
Detected as a plain-prefix token at column 0: suggest: [ A | B | C ].
Keyword rejoin (narrow panes): in a narrow pane the wrap can fall inside the keyword itself, so dewrap_suggest_keyword rejoins every split position (s\nuggest: … suggest\n:) before the regex runs. The tail is accepted behind the agent’s own hanging wrap indent — Codex soft-wraps its output with two leading spaces and emits • suggest / : [ … ], verified live at 9 columns — while the head must still start at column 0, optionally after whitespace or an agent bullet, so prose ending in a partial word is never rewritten. The rejoin buffer is allocated only when a match qualifies: the scan keys on prefix + newline, which any line ending in s hits, and ordinary chunks must stay on the Cow::Borrowed path.
Colon-alone rows: at the narrowest widths the bullet plus suggest fills the row on its own, so the continuation row carries only : and the bracket body starts a row later (• suggest / : / [ A, captured live at 9 columns). The keyword rejoin then produces a suggest: with nothing after it, so dewrap_suggest_content matches a trailing whitespace run of [\t ]*, not [\t ]+ — the pull to the next row must not require a space that this shape never has. The column-0 anchor, the bracket body and the 2–4 item count remain the guards that keep prose out.
One bounded logical line may soft-wrap across terminal rows and may begin with any parser-supported agent bullet (●, ⏺, •, or ◦), but the bracketed content may not contain a nested [/]. The closing bracket must be at or before the cursor; cells to the right of the cursor are ignored so stale content left by a carriage-return overwrite cannot complete a partial token. Reconstruction follows at most four soft-wrap transitions and 512 bytes. If those bounds or cursor metadata prevent reconstruction, the cursor-row structural candidate is rejected rather than parsed from rendered cells. Items are pipe-delimited (2–4 per the protocol). Parsing is agent-gated; the raw token is stripped from the log delivered to PWA/REST consumers by strip_structural_tokens, and concealed on the desktop canvas by the frontend overlay.
Mobile wrapped-token masking: both screen and scrollback log reads run vt_log::strip_structural_blocks before delivery. It uses output_parser::suggest_tail_rows to remove continuation rows only when a bracketed token closes within the parser’s wrap bound; blank rows, nested brackets and new protocol tokens stop the scan. An unclosed token does not consume unrelated output. Suggestion chips share the Rust parser across desktop and mobile; desktop canvas masking remains in suggestOverlay.ts, separate from the mobile log filter (#1380-05d8).
Selection lifecycle: mobile consumes the displayed chip list before starting
its asynchronous PTY writes, matching desktop’s immediate local dismissal.
Snapshots that retain the same session and items cannot restore that picked
list, even when unrelated parsed activity changes the activity timestamp. A
removed or replaced backend list re-arms the chips; identical labels can appear
again after the backend submission clear. Exhausted write retries use the
existing mobile send-failure toast instead of silently hiding an unsent choice.
Both clients retain the existing shared record_submitted_line →
note_submitted_input backend path: Enter clears the known agent’s suggestions
and advances its turn epoch, so a subsequent poll reads the cleared state.
No separate mobile backend clear endpoint is used. Claude suggestion parsing
ignores markers above the latest submitted prompt in the current screen, not
just markers inside the live input box. Full-screen history repaints cannot
restore a consumed list after fresh working evidence re-arms parser dedup.
When a repaint contains several complete markers, the lowest marker wins;
bounded bracket dewrapping also targets that latest marker.
UsageLimit
Claude Code usage limit percentage:
#![allow(unused)]
fn main() {
ParsedEvent::UsageLimit {
percentage: u8, // 0-100
limit_type: String, // "weekly" or "session"
}
}
Detected via regex matching "You've used X% of your weekly/session limit". Supports both ASCII and Unicode smart-quote apostrophes (' and \u{2019}).
UsageExhausted
Claude Code usage fully exhausted (no remaining quota):
#![allow(unused)]
fn main() {
ParsedEvent::UsageExhausted {
reset_time: Option<String>, // Raw text, e.g. "8pm (Europe/Madrid)"
}
}
Detected via "out of (extra) usage" pattern. The optional reset_time is extracted from "· resets <text>" suffix. The raw string is passed to plugins for scheduling; no timezone parsing is done in Rust.
ActiveSubtasks
Agent sub-task indicator from ›› task · N local agents mode-line:
#![allow(unused)]
fn main() {
ParsedEvent::ActiveSubtasks {
count: u32, // Number of active sub-tasks (0 = all finished)
task_type: String, // "local agents", "bash", "background tasks", etc.
}
}
ShellState
Shell activity state derived from PTY output timing:
#![allow(unused)]
fn main() {
ParsedEvent::ShellState {
state: String, // "busy" | "idle"
}
}
Emitted by the reader thread on real-output→busy and idle transitions. The frontend consumes this instead of deriving busy/idle from raw PTY data. See docs/backend/pty.md for idle detection details.
The backend foreground probe enables agent parsing for hand-launched agents in both desktop and headless sessions. HTTP foreground queries update the same stored identity. Screen activity cached before identity discovery is reclassified when that identity changes.
Goose replies are append-only below the submitted prompt. The PTY reader preserves those changed rows instead of trimming them as fixed composer chrome. This lets the reply prove consumption before a stable Ready screen closes the submitted turn; no protocol-stale timeout is needed (#1812-022d).
Ordinary output and spinner repaints cannot override a protocol idle marker. The reader preserves that evidence until the ranked busy decision, and the ready-screen timer preserves its rank. A new submission or accepted semantic working marker can start activity again.
session action=submit uses these existing agent screen adapters only to label
an acknowledgement after the raw child-output ring moves beyond its pre-Enter
offset (working_screen, ready_screen, interrupted_screen, or the generic
terminal_output). It does not add a parsed event or a second lifecycle state
machine. The output movement is independent of local input bookkeeping and is
therefore a valid terminal receipt, but it is not semantic application
acceptance.
AgentSessionConflict
Claude Code startup session-id failure:
#![allow(unused)]
fn main() {
ParsedEvent::AgentSessionConflict {
matched_text: String,
kind: String, // "in-use" | "not-found"
}
}
Fired when the PTY emits either:
Session ID <uuid> is already in use.— the injected--session-idcollides with a live process or stale lock.No conversation found with session ID: <uuid>— a--resume <uuid>pointed at a missing session file (usually wrong config dir, e.g. runningcwhere the session lives underc2’s~/.claude-private).
Auto-reset behaviour: on this event the reader thread writes a fresh export TUIC_SESSION=<new-uuid> (or set -gx under fish) into the PTY so the shell wrapper’s --session-id auto-injection stops wedging the tab on the stale id. Guarded by a 3-second cooldown — Claude prints the error line several times as it exits, but only the first fires the reset. The frontend raises a warn toast so the user knows what happened.
ChoicePrompt
Numbered confirmation / multiple-choice menu rendered by Claude Code (Esc to cancel · Tab to amend) or an opened Codex request_user_input panel (enter submit ⌃] skip ⇧→ main prompt):
#![allow(unused)]
fn main() {
ParsedEvent::ChoicePrompt {
title: String, // The question above the options
options: Vec<ChoiceOption>, // { index, label, destructive }
dismiss_key: Option<String>, // e.g. "cancel"
amend_key: Option<String>, // e.g. "amend"
}
}
Detection:
- Footer match extracts
dismiss_key/amend_keyfromEsc to <word>/Tab to <word>(or locale equivalents). - Codex enforced command approval requires the exact
Press enter to confirm or esc to cancelfooter andWould you like to run the following command?title. Command metadata between title and options is not part of the question. Captured numeric refusal submits immediately, despite the footer wording; Escape cancels. An unanswered native approval with active controls rejects a delayed OSC 7770 idle completion while that exact dialog is still on screen. Real answer input retires the controls, so subsequent completion remains valid. The original 0.163.0 failure and its three-minute mobile subscription are recorded incodex-enforced-hook-idle-2075.tcap. - Codex panel requires its
Queued follow-up inputsheading near the question. The numbered option key submits immediately;Ctrl+]skips andShift+Rightreturns to the main prompt. The heading guard keeps a quoted menu from becoming an interactive choice. This supports the installed Codex 0.162.1 format, including imperative titles such asPick a color.; the older footer is not supported. - Option regex
^\s*(?:[❯›>]\s*)?(\d+)[.)]\s+(.+?)\s*$— numbered items, optional cursor marker (❯,›,>). - Title heuristics walk up past blank rows and require either a
?suffix or a verb prefix (do you want,proceed,continue,should i,confirm,apply,allow) to avoid matching Markdown numbered lists. - Minimum two options required to reduce false positives.
Destructive flag: labels matching "no", "cancel", "reject", "abort", "deny", or the prefixes "don't" / "do not" are flagged so the PWA overlay and plugins can style them as destructive.
Claude native titles: parse_claude_ask_user_question uses the nearest nonblank title row above option 1 of the active form, not a question-mark suffix. Imperative titles such as Pick a colour export the same ordered choices and navigate-enter contract as question-mark titles. The column-zero Ink footer remains mandatory outside the Submit review; indented quoted footers do not establish a form. The authentic claude-imperative-title-2074.tcap captures the title, option descriptions, native Green answer and return to the composer.
Claude multi-question forms: every tab (← ☒ Lista ☐ Branch ✔ Submit →) parses as its own prompt. The closing Submit review has no Enter to select footer, so parse_claude_ask_user_question anchors on the column-zero tab bar and ends at the next separator row (claude-askuser-multi-question-20261012.tcap). The mobile choice buttons re-arm whenever the prompt title or labels change, not only when the prompt disappears.
Flow: the payload is stored on SessionState.choice_prompt and dispatched via pluginRegistry.dispatchStructuredEvent("choice-prompt", …). Animated status-line updates preserve the prompt and its awaiting_input lifecycle; resolution, disappearance, replacement, and PTY exit clear it. A disappearing or resolved dialog emits choice-cleared so frontend and plugin consumers do not retain stale state. Single-key replies should go through sendPtyKey() in src/utils/sendCommand.ts, never raw text + \r.
The mobile session header opens a queued Codex question with Shift+Left. Before it opens, Codex exposes a waiting signal but not the option labels; after the panel renders, ChoicePrompt supplies the title and options to the session list and detail overlay. A free-form answer goes to the opened panel’s PTY composer, not the atomic idle-agent submission route.
Observed Codex prompt forms and evidence:
| Form | Live evidence | TUIC path |
|---|---|---|
request_user_input choices and Other | codex-native-question-2026.tcap; captured_codex_0162_question_reaches_answer_controls replays input/output through the real accumulator | A queued waiting signal appears first. Shift+Left opens the panel; parse_choice_prompt recognizes its Queued follow-up inputs heading, title, numbered options, and ⌃] / ⇧→ footer. |
| Command approval | codex-0.157.1-approval-cancel.tcap; codex_canceled_approval_capture_clears_the_waiting_badge replays an Action Required approval and Esc cancellation | The approval title sets the waiting question; the current screen and cancellation logic in pty.rs clear it when Codex returns to its composer. This capture does not establish that the approval uses the queued follow-up panel. |
The distinct /plan form uses Question N/M (K unanswered) above the title and
tab to add notes | enter to submit answer | esc to interrupt below its options.
The footer can also use three native rows (tab, enter, esc), with an optional
option N/M | prefix on the notes row. Both anchors and contiguous keys starting
at 1 are required. Only the complete final footer enables continuation rows;
wrapped answers and descriptions keep their separate native columns. Descriptions in the
second column become option hints, not answer labels. Numeric answers submit
immediately; Tab opens notes and Escape interrupts. The retained real PTY bytes
are in codex-plan-question-20261019.json; this retained snapshot has no original
geometry/timing. A fresh isolated headless recording,
codex-plan-question-20261019-real.tcap, preserves real 41×128 geometry and
ordered input/output. Parser and shared-accumulator regressions replay the open
question before its recorded Ctrl+C. Neither fixture proves authenticated mobile
rendering. codex-first-plan-narrow-2094.tcap records the first Codex
0.163.0 question at 41×36: the narrow layout changes the footer and wraps both
option columns. The shared accumulator regression asserts Input state and all
four clean labels from those ordered chunks. Resizing the same unanswered live
question to 128 columns exported controls without a new question, which isolates
one failure to layout recognition. The same capture also includes a delayed
state=idle after the question opens. The completion guard applies to the same
active native dialog, not only enforced command approvals; answer input still
retires its controls and permits normal completion.
Codex 0.162.1 accepts /plan <question prompt> in one submission.
Grok native questions and enforced approvals
Grok Build 1.0.62 Ask forms use framed radio rows such as 1 (○) Red, with a Waiting on answers for header and a final z free-text option. Labels and aligned descriptions are exported separately. Numeric keys answer immediately, without Enter. Mobile sends only the selected native key, including z, so it does not submit the newly opened custom-answer composer. Selecting z retires the buttons and keeps a confident text-only question until the text is submitted.
The default-mode enforced command approval is a different radio form: a framed › title, │ command, narrow-scope/edit-pattern controls, and five numeric options. Its selected radio mark is preserved. The captured 4 refuses immediately without Enter; this is not a model permission question. Both forms must be the last content on screen, so answered history below a newer composer cannot restore controls. Existing Action Required title detection remains unchanged.
Evidence: grok-native-colour-2027.tcap, grok-native-permission-2027.tcap, and grok-enforced-approval-2027.tcap, replayed through the real accumulator. The short approval capture contains its refusal and settlement; the longer Ask captures reached the tap cap after input because of repeated Kitty image-delete output, as documented in their provenance.
SlashMenu
Slash command menu detected from VT100 screen rows:
#![allow(unused)]
fn main() {
ParsedEvent::SlashMenu {
items: Vec<SlashMenuItem>, // { command, highlighted }
}
}
Detected by parse_slash_menu() only when the input FSM has slash_mode active. It scans the bottom screen rows for consecutive /command patterns, including a single filtered result. The ❯ prefix marks the highlighted item. When the current screen no longer contains a menu, the PTY processor emits one empty SlashMenu to retract the cached list. Exact ego commands close completion without submitting a line; they must not leave the previous list visible.
VT100-Aware Parsing
parse_clean_lines(rows: &[ChangedRow]) -> Vec<ParsedEvent>
Primary entry point for VT100-aware parsing. Accepts ChangedRow vectors from VtLogBuffer.process() — each row contains clean text extracted from the VT100 screen emulator. This replaces the legacy ANSI-stripping pipeline for mobile/MCP consumers.
ChangedRow production remains active on both the primary and alternate screens. This is intentional: fullscreen agents still emit lifecycle, intent, suggestion, and question surfaces that the parser must observe. It is independent from VtLogBuffer’s durable log, which reads only primary-screen scrollback. Enabling alternate-screen history therefore makes the UI scrollable without feeding repeated fullscreen snapshots into persistent logs.
parse_slash_menu(screen_rows: &[String]) -> Option<ParsedEvent>
Scans screen bottom rows (from VtLogBuffer) for slash command menus. Only called when slash_mode is active (user typed /). Returns SlashMenu with all detected commands, including one result. None means no menu on the current screen; the caller retracts any previously published menu. The real ego-slash-filter-2030.tcap covers broad completion, /go → /goal, exact-command closure and unmatched input.
Pattern Detection
The parser uses regex patterns to detect:
- Rate limit messages from Claude, Codex, OpenCode, Gemini, Codex
- Questions and interactive prompts (hardcoded, Y/N, inquirer, Ink menus, generic
?lines) - API errors from agents and API providers (5xx, auth failures)
- GitHub/GitLab PR URLs in
gh pr createoutput - OSC 9;4 terminal progress sequences
- Agent status lines with timing/token info (see below)
Patterns are compiled once at OutputParser::new() and reused across calls.
False-Positive Guards
Two guard functions prevent false-positive detection when agents read or display source code, diffs, or documentation containing error-like or question-like patterns:
line_is_source_code(line)— Returnstruefor lines that look like source code rather than real errors. Detects: Rust raw string literals (r"...",r#"..."#), line comments (//,#), function/const/let declarations, indented code with string delimiters (4+ leading spaces), markdown fences (```), bullet points (-,*), and markdown tables (| ... |).line_is_diff_or_code_context(raw_line, trimmed)— Returnstruefor lines that look like diff output or code listings. Detects: unified diff lines (+,-prefixes), line-number prefixed code (462 -...), Claude Code diff summary blocks (⏺⎿), and diff summary lines (Added16lines).
Both guards are applied to rate limit, API error, and question pattern matches before emitting events.
ANSI Pre-Processing
The strip_ansi() function pre-processes CUF (Cursor Forward, \x1b[nC) escape sequences by replacing them with the equivalent number of spaces before stripping all ANSI escapes. Without this, strip-ansi-escapes silently drops cursor movement sequences and would concatenate surrounding text (e.g., "hello\x1b[3Cworld" would become "helloworld" instead of "hello world").
Status Line Detection by Agent
| Agent | Pattern | Example |
|---|---|---|
| Claude Code | ·/✢/✳/✶/✻/✽/* + ellipsis | ✢Reading files… (12s) or · Considering… |
| Codex CLI | Bullet •/◦ + task + parenthesized time | • Working (4m 55s • esc to interrupt) |
| Copilot CLI | ∴/●/○ + task + dots/ellipsis | ∴ Thinking… or ● Read file... |
| Gemini CLI | Braille spinner ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ + phrase | ⠋ Analyzing your codebase |
| Amazon Q | Braille spinner + task + ASCII dots | ⠹ Thinking... |
| Cline | Braille spinner + mode + optional timer | ⠙ Planning (45s · esc to interrupt) |
| Generic | [Running] prefix | [Running] npm test |
Hook-Instrumented Session Suppression
Native turn authority starts only after the foreground agent actually emits OSC 7770 busy (including prompt). A legacy completion-only notifier supplies no busy half of that protocol and keeps its working adapter. Configuration intent is not proof of delivery. Before that receipt, and for agents without native signals, the existing screen, process and silence adapters remain available.
After a native receipt, busy/idle/awaiting belongs to the native producer. A retained Working row, Ready screen, OSC 133 shell marker, timer, suggestion or process descendant cannot override it. Real foreground exit retires that native authority before another agent uses the terminal. Native dialog metadata still controls the question card; it is not an alternative turn detector.
Ego keeps emitting busy after a parent model turn if its own journal has an unsettled subagent or detached exec. The final settlement/continuation emits idle through the existing OSC contract. Delegation outside ego creates no owned work. There is no new OSC state or TUIC consumer. Process ownership remains stored for suspend safety, but native session snapshots and stage do not promote it into model activity. Suggestions are next actions, not a stronger completion receipt than native busy. One internal ownership enum distinguishes unseen, completion-only, native busy and native idle, replacing a receipt flag, latest-hook value and screen-reopen flag. A completion-only notifier retains the legacy five-minute recovery of an unconsumed submission in an unreadable transcript; native busy/idle never use that timer. This is internal receipt ownership, not a new protocol state.
Enter delivery can temporarily claim the internal shell atomic as busy. That claim is not model activity: native snapshots still project the delivered native state. A local command that starts no model turn can release the transport claim on a stable empty composer, restoring the already-known native idle. This does not create a model completion or parent lifecycle notification. Native busy is never released by that transport recovery.
This removes native screen reopen and its idle-restoration bookkeeping, plus
native timer/process state arbitration. Non-native screen reopen and ranking
remain unchanged. See docs/internals/2026-11-09-agent-state-2930-analysis.md.
Slash-menu parsing is gated by the input FSM’s slash mode and intentionally does not emit a per-chunk debug record. Sustained output with a stale slash flag previously produced thousands of identical application-log writes in seconds.
Shared ANSI stripping
tuic-ansi uses the workspace’s patched VTE 0.15 parser to strip escape
sequences from plain log text. GitHub CI log sanitization and the test-only
OutputParser::parse adapter use it. It preserves printable UTF-8 and
linefeeds, and discards other executed controls, matching the previous
strip-ansi-escapes policy. The workspace no longer compiles VTE 0.14.
Stored terminal marker coordinates
A hook-generated UserInput.line is an all-time terminal row captured by the OSC 7770 handler. Keystroke-reconstructed events keep line = -1. Consumers discard evicted hook rows instead of rebasing stored rows with a newer origin.
AI Chat also preserves reply text that immediately follows a parenthesized intent title on the same line. Untitled intent lines keep their existing status behavior; code examples are left intact.
Recorded replay oracle
Run scripts/replay-oracle.sh verify to compare every .tcap under src-tauri/
(including terminal-crate captures) with src-tauri/src/fixtures/replay_oracle/.
The replay uses the production chunk processor, UTF-8 and escape buffers,
Kitty stripping, recorded initial geometry, and the production session-state
accumulator. It records ordered parsed payloads and state/awaiting/question
snapshots after each output record, plus final ring length. Input records and
capture elapsed times are not executed: this is a chunk-path parity oracle,
not an end-to-end agent or silence-timer simulation. Legacy captures without
geometry use the existing replay default of 41 rows and 128 columns.
mail.jsonl records a scripted scenario using the production send/inbox handler
and wake gate: paginated reads, wake coalescing and rearming after consumption.
Its callback records transport acceptance; it does not claim native PTY delivery.
Random message IDs and wall-clock cursors are projected to message positions.
Normal tests are read-only and report the first differing event, including
missing or extra events. To accept an intentional change, explicitly run
scripts/replay-oracle.sh regenerate, review the JSONL diff, and commit it with
the change. Add/stage a capture before regeneration so Git includes it in the
corpus; an unknown agent filename requires an explicit replay mapping.
Real agent scenario captures
Use scripts/agent_capture/run.py to record installed CLI scenarios in an isolated
headless debug daemon. See the driver guide
for prompt/question/approval/wait/interrupt steps, authentication prerequisites,
and promotion. .scenario.json companions specify ordered expected states;
replay_oracle_all_committed_tcap_preserves_chunk_decisions replays recorded input
through the production input bookkeeping for scenario captures and enforces them in
addition to the 1342 golden trace. Failed or absent agents remain unverified;
no synthetic external transcripts substitute for captures.
OSC 0/2 title notifications use the terminal event path (PtyTitle), separately
from parsed lifecycle events. Desktop remote tabs consume parsed events on the
owning daemon’s WebSocket instead of subscribing to local IPC. Identity comes
from the authoritative backend agent_type, not from a title heuristic.
History-anchored viewport scrolling
Viewport scroll requests do not alter parsed output. History-anchored scrolling resolves the requested all-time row after output processing, under the same VT lock; capped history clamps an evicted anchor to the oldest retained row.
ego empty-composer recovery (1957)
ego PTY sessions have a recorded native screen adapter. An empty column-zero
> composer directly below the model/context/trust status row is Ready. The
native rotating Working row reports activity. Retained or wrapped text,
modal rows, and unrecognized layouts do not prove readiness.
An ordinary uncertain injection is not replayed. For ego only, a fresh empty composer repaint after uncertainty was recorded can clear the latch after the normal 1.5-second stable-screen confirmation. A pre-write cached screen cannot clear it. The foreground/background-work probe remains a separate idle gate. Once idle, the existing queue flush can deliver the next queued command or BG wake. Other agents retain their existing uncertain-write recovery contracts.
ego terminal questions
The terminal ego CLI reports human-question waits with OSC 7770 awaiting and resumes busy after settlement. TUIC recognizes ego selectors by their exact single-choice or multiple-choice footer and a highlighted numbered option. Footer matching ignores whitespace so a narrow terminal can wrap in the middle of a word. The complete footer must end the active surface: only blank rows may follow it. Answered selectors retained above newer output, a spinner or a composer do not establish a question. A real 12-row ego capture covers the answered selector and next ordinary submission. Single-choice uses navigate-enter; multiple-choice uses toggle-enter, preserves the visible [ ]/[x] marks, and submits only on explicit Enter. Changed checkbox labels update the existing choice state. After protocol busy clears an answered ego selector, repainting the same retained title and options cannot re-arm it without a fresh native wait. A different signature or disappearance followed by a new dialog remains detectable. During a confident ego wait, a free-text modal above an empty > row supplies the question text without creating numbered choices. An empty composer alone never establishes a question, and a busy spinner is rejected. Desktop and mobile read the same accumulated state; mobile opens the full question card on demand and uses the existing composer for free-text replies. The recorded 1973 captures cover each form at 120 and 44 columns. A fresh-session output-ring export also covers startup/help rows contiguous with the free-text modal. Free-text extraction stops at the nearest blank, separator, startup banner or shortcut-help row, preserving wrapped question rows below it. Opening the mobile card does not change the explicit human-reply transport or stream the draft into the PTY.
Selector and free-text title extraction share boundaries at εgo: diagnostics, submitted composer rows and native working rows. Wrapped question text below the boundary remains intact. Default-mode CLI approvals use a separate strict surface: an Allow …? title, a Risk: row and the native y/a/n/e/d controls. Refusing with n replaces the buttons with the CLI explanation prompt; Enter then settles the wait. Real captures cover selector titles and the refusal path, not edit/details or persistent approval actions.
Default-mode approval titles can contain explicit CRLF continuation rows. The parser joins the contiguous Allow title immediately before Risk: without crossing a question boundary, and still requires the exact native controls. Each empty-title ego OSC awaiting marker establishes a fresh wait; content dedup must not depend on whether an earlier approval produced a choice prompt or changed rows. The ego-mcp-questions-2088-2089.tcap recording covers three MCP approvals, including both bare-key and key-plus-Enter answers.
Approval controls can span more than two physical rows, including explicit newlines inside a remembered-rule label. The parser finds the last Risk: row and reads the complete footer below it, instead of assuming a fixed height. It still requires the ordered y/a/n/e/d controls and a final [d] details control, so newer output after an approval does not expose historical buttons. ego-wrapped-approval-2102.tcap records a wrapped printf approval answered through the mobile question card, followed by native busy and successful command output.
Ego enforced-approval buttons also send only their native key. In particular, n opens the refusal explanation without an appended Enter that would immediately settle it.
Selector and free-text title extraction share the same boundary rules. In addition to native diagnostics, working/composer and help rows, TUIC connection acknowledgements, column-zero intent: rows and ego finished-tool outcome rows (✓ / ✗) end preceding output. A contiguous receipt must not become part of the next question. The unchanged ego-mcp-questions-2088-2089.tcap records a successful MCP receipt directly above Pick a colour?; its accumulator replay checks both choice_prompt.title and question_text. Wrapped genuine question rows remain part of the title.
ego terminal provider recovery (1902)
The existing OSC 7770 consumer accepts the following UTF-8 byte frames (the
notation ESC means byte 0x1b, BEL means 0x07):
ESC ]7770;ego-recovery={"phase":"waiting","next_attempt_ms":1792100000000,"attempt":3} BEL
ESC ]7770;ego-recovery={"phase":"retrying","next_attempt_ms":null,"attempt":4} BEL
ESC ]7770;ego-recovery=clear BEL
ESC \ is also a valid terminator. The value is compact JSON, not base64.
Only detected ego PTY sessions accept this status. The value is at most 256
UTF-8 bytes. The object has exactly these fields: phase is waiting or
retrying; attempt is an integer in 1..=4294967295; next_attempt_ms is
an integer Unix epoch millisecond timestamp in 0..=8640000000000000 for
waiting, and must be null for retrying. Unknown fields, invalid values,
and oversized payloads are ignored without changing the previous snapshot.
The producer sends a complete snapshot whenever its recovery phase, attempt,
or next attempt changes. clear explicitly removes recovery. Busy/idle
OSC 7770 state markers and shell OSC 133 A also remove recovery, so a stale
provider outage cannot survive resumed work or return to the shell. These
lifecycle markers emit a clear only while recovery is active, including a
snapshot earlier in the same chunk. A stream without a recovery frame emits no
recovery events merely because its shell or agent changes state.
Recovery is a presentation overlay on the running turn, not an idle/awaiting
signal. Consumers show the phase, attempt, next attempt time and a countdown;
a countdown reaching zero does not invent a successful recovery. Force retry
submits /retry once to that same PTY through the normal agent-aware command
submission path. It does not attach ACP or launch another ego process.
Codex native session identity
Codex native codex-tool=<TUIC_SESSION>:<base64 JSON> frames carry tool and interruption/session-end receipts. The receipt decoder applies no additional size limit, so large tool results and submitted prompts preserve activity; only the bound native session and current prompt turn are accepted. PreToolUse/PostToolUse restore busy without clearing an existing wait. The native request_user_input start enters the existing confident Question event path with question text; only its matching result clears that wait. Prompt, stop, interruption and exit also retire it. Screen parsing supplies native answer keys rather than inventing a numeric mapping from JSON options. PermissionRequest is neither installed nor consumed (#2695-41da).
The existing OSC 7770 consumer accepts codex-session=<TUIC_SESSION>:<base64>
from managed native SessionStart/UserPromptSubmit hooks. JSON carries
session_id, transcript_path, cwd and hook_event_name; encoded payloads
above 32 KiB and foreign TUIC UUIDs are rejected. codex_binding.rs validates
live foreground ownership and the rollout header before Chat or lifecycle
snapshots expose exactness. Ordinary text and heuristic discovery cannot bind
Codex Chat. Shell OSC 133 A revokes the binding.
The recovery event is provider-recovery with a recovery object or null.
It is delivered in original OSC order, including clears in the same chunk.
SessionState.provider_recovery is the durable per-session presentation value;
repeat snapshots do not generate additional parent entry notices. The existing
session-state stream carries updates to desktop and browser consumers.
Tool readout (tool-activity)
tool-activity with name (string or null) carries the newest live native
tool of the session. It is not parsed from screen text: native hook receipts,
ego agent-event frames and the agent-tool=<TUIC_SESSION>:<base64> verb of
the managed Pi extension and OpenCode plugin feed it (see backend/pty.md).
It is emitted only when the value changes, and it never sets busy, idle or
awaiting. The accumulator writes SessionState.current_tool.
Ego turn readout (child-activity, turn-outcome)
child-activity with children (array of labels, empty when none) and
turn-outcome with outcome (string or null) come only from ego agent-event
frames (see backend/pty.md). Each is emitted only when its value changes and
never sets busy, idle or awaiting. The accumulator writes
SessionState.native_children and native_turn_outcome; PtyExit clears both.
Ego selector row boundaries
Before parsing an ego question, the PTY reader concatenates rows linked by the grid WRAPLINE flag. It preserves original spaces and adds none inside words. Hard line breaks still separate the title, numbered options and footer. Footer recognition remains in the ego parser; it does not infer prose boundaries from row length.
Mobile intent presentation
The log serializer keeps intent: text and its styled spans in history and screen output. Only suggest: source markers are stripped for the suggestion-chip UI. Mobile CLI rejoins the terminal soft-wrap boundaries and applies the desktop intent tint to the complete logical line. State/title parsing is unchanged.
PTY intent title closure
The shared intent_marker.json grammar defines the intent anchor and title
boundary for Rust capture and desktop/mobile tinting. The last complete, non-nested
parenthesis group on the logical row is the title. Its closing parenthesis ends
the intent even when ordinary prose follows without whitespace. Earlier
parenthesis groups remain in the description. An unfinished later opening
parenthesis keeps the title incomplete, so a repaint or hard-wrapped title is
not replaced by an earlier aside. Desktop tinting resolves the complete
soft-wrapped logical line before mapping the boundary back to physical cells.
Title-less rows keep their existing hard-break completion behavior.
Vite watches the shared grammar and its parent directories even though other Rust sources remain excluded from frontend hot reload. A grammar edit must invalidate its imported JSON module together with the frontend classifier; otherwise a cached grammar can omit new fields and abort viewport marker planning.
The parser does not remove terminal bytes. Desktop tint stops at the closing
cell, including when the title wraps; mobile keeps trailing spans and links outside
the tint. The CONTEXT header receives only the parsed description. Source evidence
for 2060-0ebe is the recorded ego assistant message in ego-intent-2060.json:
the model itself emitted )Criteri, not two lines joined by the terminal renderer.
Clipped Claude questions
A native column-zero scroll arrow on a numbered option, together with the Ink
footer, identifies a clipped AskUserQuestion. A numbering gap before the separate
5. Chat about this row also identifies clipping when the scroll arrow disappears
at the last visible answer. Generic numbering gaps still fail closed. The parser exports navigate-only
with ↑ (previous option), ↓ (next option), and ↵ (select highlighted option).
These are native navigation controls, not a partial list presented as complete.
Clients send exactly one corresponding arrow or Enter key; navigation does not
clear awaiting. No hidden option label or cursor offset is inferred. A complete
form keeps its existing ordered navigate-enter choices. The geometry-preserving
claude-narrow-2093.tcap fixture records the original narrow failure.
ego startup project trust (2461)
The native project-trust modal is a confident text question, not a numbered
selector. Recognition requires the native refusal
explanation, and a final active Trust project files in …? [y/N] prompt.
The parser joins ego’s hard-wrapped path rows as well as terminal soft wraps.
Answered prompts and retained prompts above newer output do not match.
The existing mobile key bar sends y or n followed by Enter for ego.
ego-trust-2461.tcap records ego 0.4.0 at 24 rows by 48 columns in an isolated
untrusted scratch workspace. The PTY replay checks shared session state.
ego-trust-short-2461.tcap records the 12-row boundary: the offer heading has
scrolled off-screen, but the refusal explanation and active question remain.
The heading is not required for detection.
Claude option previews
Claude AskUserQuestion preview forms render a bordered pane beside the numbered
answers. Parse its rectangle before the answer rows. Locate and split each row
at terminal-cell columns, not character offsets: wide glyphs and combining marks
in a label must not shift the preview boundary. Join left-column label
continuations, including (Recommended), without merging pane borders or text.
The same rectangle extraction accepts a pane below the options. The selected
option carries the pane text in its existing multiline hint; no wire field is
added. The native question tab row stays in the title, and the unnumbered
Chat about this action follows the numbered choices in navigation order.
Desktop PTY Chat and mobile share ChoicePromptOverlay: multiline hints use a
monospace block, while ordinary keyboard hints remain inline.
Pi extension modal frames
The managed Pi extension emits OSC 7770 coarse state from Pi 0.84.2 lifecycle callbacks. Its shared public UI context wraps select, confirm, input, editor and custom with token-owned waits and finally retraction. Tool callbacks update underlying activity without publishing busy through an open modal. Session shutdown invalidates old promise owners. No native ui_prompt_start event is assumed. Empty native awaiting titles are lifecycle markers, not rendered text, and are never suppressed by question repaint deduplication. Accepted idle also appends an ordered clear event: awaiting and immediate idle may arrive in one PTY read before the accumulator has applied the wait. The existing unanswered-native-dialog idle guard still runs before this clear.
Grok native receipt correlation
The PTY adapter handles grok-hook receipts before publishing shared state events. It accepts at most 1 MiB of encoded payload, bounds correlation identifiers to 256 bytes and retains at most 64 pending requests. Child and wrong-owner events are ignored. A permission notification lacks a tool identifier, so it binds to the newest unanswered PreToolUse in the current native session and turn. Matching success/failure/denial clears it; prompt replacement and all stop/exit outcomes clear pending requests. Late cancellation with an older prompt ID is ignored. Idle/task-complete notifications never request human input. Arguments and tool results are not published in parsed state events.
Strict native Ask selectors and their text-only continuation remain independent of permission-hook ownership. Grok 1.0.70 reports Ask attention as elicitation_dialog, not permission_prompt (grok-hook-ask-2624.tcap). Native permission/history gating must not suppress these strict Ask forms. The strict form accepts the installed version’s complete navigation and submit/back footer, but not arbitrary output after a retained form.
After SessionEnd, a UserPromptSubmit with a new prompt ID reopens the same native session, including resumed conversations without OSC 133 shell integration. Replayed old submits and old-prompt completions do not reopen or close the resumed turn.
Codex global hook trust is setup state, not a parsed terminal wait. Native
hooks/list verification can report reviewRequired in Settings without
emitting awaiting/busy/idle. Launch-scoped status notifications, PTY event
accumulation and ego PTY/ACP request ownership are unchanged.
Windows hook fallback
Native Windows does not install or inject TUIC’s external POSIX status hooks. Hook state returns unsupported, and hook/status setters reject changes before writing preferences or user hook files. Saved preferences and existing hooks remain intact. Settings hides these controls based on the owning backend response, including remote machines. External agents retain heuristic detection; ego keeps native PTY OSC signals and its separate ACP path.
Agent State Detection Rules
These rules moved here from AGENTS.md to keep that file inside the
32,768-byte project-instruction budget. They stay binding for every agent;
AGENTS.md keeps a summary and a link to this page.
The bottom zone is not agent output — never parse it
Below an agent’s input box sits a status line the user configures: a Claude
Code statusLine command, a HUD plugin, a shell theme. Its height, glyphs and
wording are arbitrary, differ per install, and it may be absent entirely.
✻ Simmering… (5m 48s · ↓ 20.7k tokens) ← agent output. Parse this.
─────────────────────────────────────────
❯ ← input box (2 rows)
─────────────────────────────────────────
[Opus 5 (1M) | Team] ██░░ 22% | 📚 8 ← user's status line, ANY height.
5h: 0% | 7d: 2% | $15.48 | 📅 $136.41 Ignore all of it.
◐ Bash: cargo test | ✓ Bash ×14
⏵⏵ bypass permissions on (shift+tab) ← agent chrome. Also ignore.
Rule: nothing at or below the input box may reach a parser. Whatever is down
there is coincidence — a path reads as a plan file, a ? as a question, a
numbered list as a choice prompt, $15.48 as a token count. The agent’s own
spinner sits above the input box, so trimming costs no signal.
Enforced by chrome::find_chrome_cutoff, applied to changed rows in pty.rs
before parse_clean_lines. It anchors on the input box and extends upward past
its padding. The unwindowed fallback accepts either a strict empty prompt or a
separator followed within four rows by a prompt; the latter preserves a draft
in a non-empty input box above an arbitrarily tall HUD without treating a lone
separator or markdown quote as chrome.
When you touch that cutoff, the failure mode to fear is failing open: no
anchor found returns None, and None means no trim, so every status-line row
reaches every parser. That is exactly what happened with a status line taller
than CHROME_SCAN_ROWS — silent and total. Hence the unwindowed fallback to the
lowest empty prompt row (lowest_input_box_row). Never widen the loose
is_prompt_line search: unwindowed it matches a markdown blockquote.
Deliberate exceptions — these read the full screen on purpose:
| Site | Why |
|---|---|
parse_slash_menu | Claude Code v2.1+ renders autocomplete items below the prompt chrome |
parse_choice_prompt | scans bottom-up for a strict dialog shape (title + ≥2 numbered options) |
question dedup screen-absence check (pty.rs) | asks “is this prompt still visible anywhere”, not “is this content” |
Agent state detection — capture before you theorise
Working / idle / awaiting is decided from bytes an agent writes once, and
nothing retains them in the shape the decision saw. The ring holds 2 MB
(OUTPUT_RING_BUFFER_CAPACITY) and the VT log 10.000 lines
(VT_LOG_BUFFER_CAPACITY), so a busy agent still rolls past both, and what
survives is rendered rows rather than the chunk boundaries and timing the
detector actually read. Do not reason about the code first — record the stream,
then replay it.
(The 8192 that looks like a ring size is the default byte limit of
GET /sessions/{id}/output, mcp_http/session.rs:460 — a page size, not a
retention bound.)
curl -X POST localhost:9876/diagnostics/capture -H 'content-type: application/json' \
-d '{"enabled":true}' # every session
-d '{"enabled":true,"session_id":"<id>"}' # one session
curl localhost:9876/diagnostics/capture # state + bytes written per session
Captures land in <config dir>/captures/<session-id>.tcap, capped at 512 KB each. TUICCAP2 preserves the initial terminal rows/columns plus output/input direction, original chunk boundaries, ordering, and monotonic timestamps. The decoder remains backward-compatible with geometry-less TUICCAP1 and legacy output-only .raw fixtures; a faithful replay of either old format must supply the observed geometry explicitly rather than silently assuming 41x128.
Off by default (one relaxed atomic load per chunk when off) — code in
src-tauri/src/pty_capture.rs.
A reproduced failure becomes a fixture, always. Drop the .tcap in
src-tauri/src/fixtures/agent_prompts/ and add a case to the
Awaiting-signal fixtures block in pty/tests.rs: it replays the capture
through raw_stream_events + parse_clean_lines + suppress_heuristic_question
— the same composition production runs, shared on purpose so a test can never
assert against a pipeline that does not exist. Unit tests on the individual
parsers were never the gap; the pipeline around them was.
That rule is mechanical, not honour-system. scripts/hooks/pre-commit
(installed by make hooks / make dev) blocks a commit that changes detection
logic without staging anything under src-tauri/src/fixtures/agent_prompts/.
It is deliberately narrow — only added/removed lines count, comments and blank
lines are stripped, and outside chrome.rs (detection end to end) a detection
symbol must be named by a changed line or by the hunk’s enclosing function.
Touching pty.rs is not the trigger; touching awaiting_input, or any line
inside suppress_heuristic_question, is. Replayed over the last 120 commits
that touch a gated file it fired on 24 — every fix(agent-state): among them.
The same hook refuses a staged .tcap whose replay-oracle capture or
corpus.jsonl entry is missing; scripts/replay-oracle.sh regenerate writes them.
The gate ignores formatting-only hunks (rustfmt reflow, trailing commas), pure
block moves, and plain reads of .awaiting_input / .question_confident /
.question_text (consumers such as push scheduling). If it still fires, the edit
probably does change detection: record the capture.
TUIC_SKIP_FIXTURE_GATE=1 is allowed only when no capture can apply: a rename
or refactor whose behaviour the existing fixtures already replay unchanged.
Never for a fix, and never to save time. Put the reason in the commit message
as a trailer, because the env var leaves no trace:
Fixture-Gate-Skip: <why no detection behaviour changed>
TUIC_SKIP_FIXTURE_GATE=1 git commit ... # never --no-verify: it also skips the Makefile gate
The orchestrator landing check will run scripts/hooks/report-fixture-gate-skips.sh <range>
and report every commit that carries the trailer (orchestrator story pending; it does not run yet).
Three signals report awaiting, and they are not interchangeable:
| Signal | Source | Applies to |
|---|---|---|
OSC 7770 state=awaiting | TUIC hook | hook-instrumented agents, only on PreToolUse(AskUserQuestion) |
OSC 777 notify | agent’s own desktop notification | unambiguous needs your permission / approval required wording only; Claude’s generic is waiting for your input also follows an ordinary completed turn and never sets awaiting |
Enter to select footer | rendered screen | Ink dialogs, including hook-instrumented sessions through the full-screen presence recovery; the changed-row parser’s heuristic copy is suppressed for hooked agents |
Busy/idle evidence is ranked within one submitted-turn epoch. Lower-ranked
evidence never closes a turn held busy by a protocol signal, and the same rule
protects protocol-ranked awaiting state from the question-cleared screen
backstop. After a foreground agent delivers native busy, only that producer decides
busy/idle; screens, timers, shell OSC 133 and descendants cannot override it.
Configuration alone does not select this rule. Agents without a delivered native
busy keep the screen/process/silence fallback; a completion-only notifier does
not establish a complete turn source. Foreground identity withdrawal
retires native authority. Ego includes its owned children and background execs in
its coarse busy signal, so for ego its agent-event turn frames own busy and idle
once session_start is seen: turn_start is busy, turn_end is idle. A coarse
busy outside a turn is owned work: agent_state working with background_work,
while mail, submit and the queue reach the idle composer (#3064-3141).
| Rank | What it knows | Recorded by |
|---|---|---|
Silence | nothing moved for a while | the silence timer |
Screen | what the rendered screen currently looks like | ready/working screen adapters, and OSC 133 — see below |
Process | the process itself changed | protocol-stale only, today (#771-4733) |
Protocol | this turn began or ended | OSC 7770 state=, Codex notify turn-complete, a submitted line on a ready-adapter agent |
Rank is about what a signal knows, not how it travelled. Arriving in an escape
sequence does not make something Protocol rank. OSC 133 is the worked example
and the mistake to not repeat: it is shell integration, so 133;C fires when a
foreground command starts and 133;D when it exits — on a long-lived TUI agent,
once at launch and once at death. It cannot tell one turn from the next, so it
records at Screen rank and a stable Ready screen is allowed to close it.
Ranking it Protocol strands the tab BUSY for the agent’s whole lifetime, which
is issue #535-d4f5.
That distinction is easy to lose because SilenceState::explicit_busy() accepts
osc133-busy alongside hook-busy. It is a provenance predicate — an
explicit marker set this, rather than inferred screen/activity — and deliberately
not a rank predicate; its sources do not share a rank. Anything deciding
whether evidence may hold a turn reads evidence.busy.rank. Reading
explicit_busy() instead is exactly how a past commit came to widen the
note_ready_screen guard and then invert one of three byte-identical tests to
match (#745-8ff1). A SilenceState carries no agent type, so the three
*_recovers_long_lived_shell_busy tests must always agree; if one of them is
red, making the trio disagree is never the fix.
The footer regex anchors at column 0 of the rendered row, never the trimmed
text (is_ink_dialog_footer_row). A dialog is drawn full-bleed; everything an
agent streams is indented inside its own frame, so the indentation is the whole
difference between the footer and an agent quoting it. Trim first and an agent
that pastes a screen it just read marks itself awaiting, confidently, with
nothing to retract it.
A hook-instrumented agent showing a picker that is not AskUserQuestion (plan
pickers, skill menus, anything with Type something / Chat about this) uses
the open Ink footer’s full-screen presence recovery. The generic OSC 777
notification is insufficient evidence: it also arrives after normal prose at
the ready composer. Unambiguous permission notifications remain raw-stream
signals because the VT parser consumes escape sequences before clean-row parsing.
Uncertain ego injection recovery uses the native empty-composer adapter, not
silence alone. Only a post-uncertainty repaint followed by 1.5 seconds of stable
Ready may clear the uncertainty flag. Retained or wrapped drafts and modal rows
fail closed. The foreground probe still gates idle; recovery never requeues the
uncertain payload, but normal idle flush can deliver the next queued BG wake.
The adapter shapes are recorded in ego-composer-1957*.tcap.
Ego selector recovery accepts both single-answer and checkbox footers, including mid-word terminal wrapping. The complete footer must be the last nonblank content: answered selector history above newer output or a composer must never re-arm awaiting. Checkbox state uses toggle-enter and changes only on a toggle; Enter or Escape settles the dialog. Free-text modal text enriches an existing confident ego wait, never a ready composer. The mobile header question action supports all three forms.
Ego empty-title native awaiting markers are lifecycle events, not screen text: never deduplicate them through selector repaint state. MCP approval titles can contain explicit CRLF continuation rows before Risk:; preserve the complete contiguous Allow …? title and the exact native controls.
Ego selector and free-text titles share diagnostic, working-row and submitted-composer boundaries. Default-mode approvals require the native Allow/Risk/y-a-n-e-d shape; n replaces choices with the refusal explanation prompt, and Enter settles it. Approval footer height is variable: read all rows after the last Risk anchor, require ordered native keys and the final details control, and reject retained approvals above newer output (ego-wrapped-approval-2102.tcap).
Codex native question parsing targets installed 0.162.1: ⌃] / ⇧→ footer, Shift+Left to open, immediate numeric answers. The queued-panel heading is required; imperative titles are accepted only behind that exact panel shape. Enforced command approvals instead require their exact confirm/cancel footer and command question title; numeric refusal submits immediately. While the same native dialog and its unanswered controls remain active, a delayed idle hook cannot retract the approval or a /plan question. Answer input or a departed dialog permits normal completion. The distinct /plan question requires its Question counter and exact tab/enter/esc footer, either one wide row or three narrow rows. Narrow answer and description continuations stay in their native columns; second-column descriptions become hints, not answer labels (codex-first-plan-narrow-2094.tcap).
Grok native radio forms require a strict framed Ask or enforced-approval shape. Ask ends with z and a waiting header; enforced approvals carry title, command and scope controls. Numeric keys answer immediately. Selecting z retires choice buttons before publishing a text-only wait.
Every signal that sets awaiting needs a path that clears it. The badge is
SessionState.awaiting_input, not an event, and it is sticky by construction —
whatever sets it owns nothing until something retracts it. These paths clear it:
| Clear | Fires on | Misses when |
|---|---|---|
user-input | a non-empty typed line | the answer is a bare Enter |
status-line | a parsed busy tick (low-confidence only) | busy is inferred from screen movement |
resolve_choice_prompt_input | an option keypress | no choice_prompt was ever set |
question-cleared | silence timer sees the question gone from the screen | — (the backstop; low-confidence only) |
protocol-question-cleared | Claude renders User declined to answer questions after Esc and returns to a ready composer; or an accepted foreground observation revokes the agent on confirmed shell return | cancellation requires the matching dialog; exit withdrawal is turn-epoch scoped and does not fire for unknown helpers, stale samples or an unobserved startup preset |
progress-superseded | the same PTY reports progress done, journals a delegated hand-off, or successfully receives a queued user reply after a progress blocked | a dialog or any other confident question replaced the blocked one — only source=progress-blocked evidence clears |
question-cleared is the backstop that catches the rest. It never touches a
confident question: grok repaints while it waits, so “not on screen this tick”
is not proof of an answer.
Dialog recovery requires an active agent identity. After foreground observation returns to the shell, a retained Ink footer or question title above its prompt is history, not a live dialog. Both full-screen recovery and silence-timer chat heuristics require that identity. Never re-arm awaiting from shell output just because that footer remains visible (claude-question-exit-2091.tcap).
The mirror failure is a SET that never comes back. A multi-question
AskUserQuestion answers one sub-question at a time; each repaints its title and
options while the Enter to select footer stays byte-identical. The changed-rows
parser needs a row to change, so sub-questions 2+ produce no signal at all and
the tab reads “working” while the agent waits. rearm_awaiting_for_open_dialog
(pty.rs) closes it by reading that footer off the full screen as a presence
level, not an edge, and re-arming only when the badge is off — one event per
spurious clear, never one per repaint. Do not extend it to parse the title,
options or the ⊠ … ✓ Submit tab bar: those all move as the wizard advances,
which is precisely why the footer is the key.
Legacy output-only .raw fixtures cannot reproduce a latched badge. New
.tcap captures include user input and can replay SET/CLEAR ordering, but the
Awaiting RETRACTION block must still drive the real event-bus accumulator and
assert SessionState — the thing a tab actually renders.
Do not exclude hook-instrumented sessions from dialog recovery. A retained
PTY capture on 2026-09-21 showed state=awaiting, then fifteen state=busy
markers, then an open dialog while the session reported working. Recovery must
use the last pending Question/UserInput event in a chunk, not the presence of
any Question: a later clear supersedes it. Keep the column-0 footer anchor and
the guards against an existing badge, choice prompt, or pending question.
Agent Session Management
These rules moved here from AGENTS.md to keep that file inside the
32,768-byte project-instruction budget. They stay binding for every agent;
AGENTS.md keeps a summary and a link to this page.
Agent Session Management
TUIC tracks each agent’s session ID for resume-after-restart. Two strategies coexist:
Discovery-based (Claude, Gemini, Codex, Grok). TUIC does NOT inject --session-id at launch — the agent creates its own ID. TUIC discovers the active session and re-checks it on every idle↔busy transition and every 30s poll, so an agent that starts a replacement session is picked up. Resume uses agentSessionId (disk-discovered), not tuicSession.
Discovery has two tiers, and the difference is not cosmetic:
| Tier | Agents | Source |
|---|---|---|
| Exact | Claude, grok | the agent’s own pid→session registry: $CLAUDE_CONFIG_DIR/sessions/<pid>.json, ~/.grok/active_sessions.json. get_session_leaf_pid returns the agent’s pid (verified: it stays the agent even while a tool subprocess runs) |
| Heuristic | Gemini, Codex, and any Claude/grok too old to publish a registry | newest unclaimed session file under the project dir |
The heuristic is not a binding, and no amount of tuning makes it one. N agent tabs in one folder all scan the same directory, so whichever tab polls first takes the newest file regardless of whose it is; the rest take another tab’s session or nothing. claimed_ids only stops two tabs holding the same id — it cannot tell whose is whose. That is issue #119: measured on a live instance, 3 of 6 Claude tabs held no id and one held a different tab’s, so every tab resumed with claude --continue into the same conversation.
Finding the id is only half of a resume — the other half is which store holds it. A shell alias is expanded before exec, so a run config that reads c2 with an empty env is not what runs: the process is claude --dangerously-skip-permissions under CLAUDE_CONFIG_DIR=~/.claude-private, and TUIC never sees the assignment. While the agent lives, discovery reads argv and env off the process and rebuilds the real command into agentLaunchCommand; at restore time the pid is gone and that string is the only record left. Do not re-derive the config dir from the run config: c and c2 differ only in an env var neither one declares, so the default config verifies an id in ~/.claude and then sends --resume to a binary that reads ~/.claude-private — Claude answers No conversation found with session ID, and the transcript is sitting untouched in the other directory.
So when you add a discovery-based agent, look for a pid registry first. Codex 0.153 has none — session_index.jsonl carries only id/name/updated_at, the rollout session_meta has no pid, and there is no --session-id flag — so it stays heuristic on purpose, cwd-scoped by the rollout’s recorded cwd. Gemini is worse and knowingly so: its scan visits every project’s chats/ dir, so it is not even cwd-scoped (see the DEFERRED note on discover_gemini_session). Do not close either gap by guessing a path-hashing scheme — verify against a real install.
Forced injection (Goose). Shell wrapper injects --name $TUIC_SESSION into goose session/run commands. The TUIC tab UUID IS the goose session name. Discovery returns None (SQLite storage, no filesystem scan). Resume uses tuicSession.
No session tracking (Amp, Cursor, Droid, OpenCode, pi). Either no local session files, cloud-only, or no UUID-based resume. TUIC_SESSION env var is available but unused.
When adding a new agent: choose discovery-based if the agent writes session files to disk (add sessionDiscovery to agents.ts and a Rust discover_*_session to agent_session.rs). Choose forced injection only when discovery is impossible (e.g., SQLite-only storage).
All of the above describes the PTY transport. The AI Chat ego uses ACP and is not an AgentType. Read SPEC.md → “PTY versus ACP routing” before wiring either transport: a session has exactly one transport, with no fallback.
ego has three distinct faces: standalone CLI outside TUIC; AI Chat over ACP as an orchestration peer with a host-issued, durable TUIC_SESSION but no tab, PTY or terminal parser; and a separately launched terminal CLI over PTY, which may have an AgentType. The ACP peer reaches terminals and repositories through TUIC’s MCP bridge. Its peer identity permits mail and child-parent routing, but does not turn the AI Chat conversation into a terminal or place it in tab routing, split panes or PTY agent-state detection.
Runtime Diagnostics
These rules moved here from AGENTS.md to keep that file inside the
32,768-byte project-instruction budget. They stay binding for every agent;
AGENTS.md keeps a summary and a link to this page.
Diagnostics
Runtime diagnostics for debugging performance issues. Code: src-tauri/src/cpu_watchdog.rs.
Always on (zero overhead when idle):
- CPU spike detection via
getrusage(RUSAGE_SELF)— only the TUIC process, not PTY children - Logs
CPU SPIKEwarning when >80% for 10+ consecutive seconds with full snapshot - Sleep/wake detection — skips stale ticks after lid close/open
Diagnostic mode (toggle at runtime):
# Enable diagnostic mode
curl -X POST http://localhost:9876/diagnostics -d '{"enabled":true}' -H 'Content-Type: application/json'
# Check status
curl http://localhost:9876/diagnostics
# Read diagnostic logs
curl 'http://localhost:9876/logs?source=diagnostics'
When enabled, emits health snapshots every 30s and alerts on FD/thread growth trends. Each snapshot includes: CPU% (TUIC-self only, via RUSAGE_SELF), children_cpu (aggregate %cpu of PTY children + hottest child — the spike trigger deliberately ignores children, so this is the only place a hot cargo/agent surfaces when TUIC itself is calm), thread count, FD count, PTY session count, content index build state, semaphore permits, sessions with grid frames outstanding (GridGate), event bus subscriber count, head_emits_suppressed (repo-watcher head-changed emits skipped by the resolved-HEAD-target guard — a high/climbing value signals a filesystem-event storm, issue #82).
Frontend liveness (always on, desktop only): the WebView beats every 5s from its main thread (frontendHeartbeat.ts → frontend_heartbeat → frontend_liveness.rs); after six missed beats the diagnostics thread logs once:
Frontend unresponsive: no heartbeat for 30s — the WebView main thread is blocked or gone.
Whole-process silence is not proof of a frontend-only block. On 2026-10-20 an occluded agent-test instance without a power assertion showed a 41.6 s callback gap, 40 s backend-log silence, Sleep-wake detected lines, ~100 threads at priority 4, and a sync IPC command sampled in rename(2) over the gap. Historical attribution remains open. A controlled replay with normal-priority CPU contention reproduced a 36.753 s callback gap; adding the app_nap.rs process-lifetime activity alone reduced the maximum to 2.561 s. Independent backend requests still completed in that RED, so it does not reproduce the original backend outage. See scripts/stall-workload/OCCLUDED-RESULTS.md (story 1638-c94c).
Persistent stall evidence: selected numeric slow-event metadata survives ring overflow and graceful restart in a bounded journal. See docs/backend/stall-journal.md for retention, replay inputs and limits; this is not proof of historical stall attribution.
Lost document (always on, desktop only): a second, different white screen. The webview-recovery thread reads the main frame’s URL every 15s (webview_recovery.rs); anything on the about: scheme means the app is no longer in the DOM, and it navigates back to the last healthy URL by itself, logging once. This is not the heartbeat’s job and the heartbeat cannot see it: the app is gone rather than blocked, so it never beats from the blank document, and “never beat” is deliberately silent (tuic-remote has no WebView).
Observed twice on 2026-09-08, both times after the Mac went to standby with the display off: the main frame came back on about:srcdoc holding <html><body></body></html>, while the WebContent process was alive throughout (so it is not the about:blank WebContent-crash case) — under the memory-pressure sweep macOS runs while asleep.
Recover manually without losing PTY sessions — they live in the backend, not the WebView:
curl -X POST http://localhost:9876/debug/reload_webview # navigates back to the app
That endpoint navigates; it must never go back to reload(). There is no URL behind about:srcdoc to reload, so the reload version answered {"ok":true} and left the window white for an hour.
Memory: GET /diagnostics/memory names which structure is holding the process’s footprint — entry counts for every map that grows with sessions, clients or repos, measured bytes for the four that hold payloads, sorted biggest first, plus phys_footprint_bytes (resident plus compressed; ps RSS read 0.52 GB while the process held 40 GB). Exists because on 2026-09-08 the backend reached 40.7 GB and could not be asked what it was holding: leaks found only 47 MB unreferenced, so it is live, reachable state — but a 40 GB process is not debuggable and every candidate had to be excluded by reading code. accounted_bytes far below the footprint means the growth is outside AppState.
Two traps this exists to close. grid frame gate stuck is not a frontend-liveness signal — a hidden terminal deliberately never acks (CanvasTerminal.onFrame), so it fires constantly in normal operation; reading it as “the WebView is wedged” is a false positive on every backgrounded tab. And freezeDetector.ts cannot report a block that never ends, because its setInterval runs on the thread it watches — which is why a five-hour white screen on 2026-09-08 left no frontend log at all and had to be diagnosed from the absence of lines. /debug/invoke_js is useless in that state for the same reason: it needs the stuck thread to run the script.
When to enable: Boss reports sluggishness, CPU spikes, or UI freezes. Enable it, reproduce the issue, then check the logs. The snapshot at the time of the spike tells you what subsystem is overloaded.
Known past failure patterns this catches:
- IPC flush loop (ack_terminal_frame sending frames in ack path → 240+ IPC/sec)
- Content index build saturating CPU on large repos
- grid frames outstanding on a session (WebView JS thread blocked)
- FD/thread leak (progressive growth without cleanup)
- Sleep/wake false idle cascades (tokio timers firing stale)
Error Classification
Module: src-tauri/crates/tuic-core/src/error_classification.rs
Classifies terminal error messages and calculates exponential backoff delays for retry logic.
Tauri Commands
| Command | Signature | Description |
|---|---|---|
classify_error_message | (message: String) -> String | Classify error type |
calculate_backoff_delay_cmd | (retry_count, base_delay_ms, max_delay_ms, backoff_multiplier) -> f64 | Calculate backoff delay |
Error Categories
classify_error(message) returns one of:
| Category | Description | Examples |
|---|---|---|
"transient" | Temporary, retry-safe | Network timeout, connection reset, rate limit |
"server" | API server-side error | 5xx responses, service unavailable, auth failures from providers |
"permanent" | Will not resolve with retry | Auth failure, not found, invalid input |
"unknown" | Unclassified | Default for unrecognized patterns |
Backoff Calculation
#![allow(unused)]
fn main() {
pub fn calculate_backoff_delay(
retry_count: u32,
base_delay_ms: f64,
max_delay_ms: f64,
backoff_multiplier: f64,
) -> f64
}
Formula: min(base_delay_ms * backoff_multiplier^retry_count, max_delay_ms)
Typical usage:
base_delay_ms: 1000 (1 second)max_delay_ms: 30000 (30 seconds)backoff_multiplier: 2.0 (double each retry)
Result sequence: 1s → 2s → 4s → 8s → 16s → 30s → 30s → …
Frontend Integration
The errorHandlingStore calls these Rust functions to classify errors detected in terminal output and calculate retry delays. The store manages active retries and respects the user’s configured strategy (retry, ignore, or manual).
Git Operations
Terminal placement uses a valid caller-bound declaredWorktrees association when
one exists, otherwise reported cwd. Creating a checkout through git -C does not
move the caller’s process or its tab into that checkout. An explicit declaration
moves only its tab; saved-terminal restoration, reconnect and OSC 7 retain that
placement without changing shell cwd. Legacy placementPath alone is not authority.
Modules: src-tauri/crates/tuic-git/src/{git,git_cli,git_graph,git_locks,git_reads,worktree,cow}.rs (domain), src-tauri/src/{git,git_graph,worktree}.rs (app adapters)
The tuic-git crate owns Git subprocesses, reads, branch operations, worktree operations, and artifact warming. It depends on tuic-core for path spelling. The root app retains Tokio scheduling, AppState caches, configuration lookup, Tauri commands, and event emission; its adapters re-export the moved domain items at their former crate paths. The domain crate has no normal Tokio or Tauri dependency. The root worktree.rs adapter also fetches complete, paginated merged GitHub PR evidence over account-aware HTTP GraphQL and passes the response to tuic-git for SHA and ancestry verification. Workspace removal and MCP branch_delete both use that boundary.
Workflow launch uses validate_branch_worktree_path: the canonical path must identify a registered isolated branch checkout outside the archive pool, with no Git operation in progress. Detached-orphan removal uses the separate validate_worktree_path guard, which continues to refuse attached branch checkouts. Launch authorization never grants removal permission (#1883-eba0).
Worktree allocation finds registrations under git rev-parse --git-common-dir, resolved from the base repository. This supports normal, bare and linked-worktree bases. Each registration must still match the requested checkout path before TUIC writes its allocation marker; foreign and unregistered checkouts remain rejected.
Orphan scans and orphan removal share the temporary-path policy in
tuic_core::temp_paths. OS/environment temp roots, ~/Gits/.tmp and Unix
/tmp, /private/tmp, /var/folders, /private/var/folders are excluded
before per-checkout assessment. Component matching checks registered and resolved
paths, including existing ancestors of missing checkouts. The path validator and
low-level orphan remover recheck the exclusion, so stale or confirmed requests
cannot remove temporary detached checkouts. Detached sidebar inventory is
independent: it can display these checkouts without authorizing cleanup.
Worktree removal verifies checkout and submodule safety before asking Git to unregister it. Git can return Directory not empty after removing the registration and some files. In that state, the removal call finishes deleting the known checkout directory and only then compares and deletes the branch ref. A failed cleanup reports the remaining path; an unregistered directory without TUIC ownership evidence is never recursively deleted.
Git writes are performed by shelling out to the git CLI via the unified git_cli module. Git reads go through the reversible GitReads port (see below), which serves some ops from in-process gix and the rest from the same CLI. The git_cli::git_cmd(path) builder provides consistent error handling, binary resolution, and credential prompt suppression across all callsites.
Windows checkout comparisons use tuic-core::path_spelling::portable_spelling: native and verbatim paths match Git’s forward-slash paths. Unix backslashes remain literal filename bytes. Worktree creation passes its destination to Git in this same portable spelling, including the retry for an existing branch; filesystem state retains native paths. Git subprocesses enable core.longpaths on Windows, including deep submodule preservation refs. Worktree scripts use the same enriched PATH as Git subprocesses; the Windows search includes the standard Git installation and its .exe filename. Hook PATH entries use native Windows separators, put the resolved Git directory first, and remove case-insensitive duplicates. The hook keeps whole directories in precedence order up to cmd.exe’s 8191 UTF-16-unit environment-value limit; later directories beyond that limit are omitted.
When Git Bash resolves Git for Windows’ internal ucrt64/bin/git.exe or
mingw64/bin/git.exe, worktree scripts put that installation’s cmd/git.exe
launcher first instead. The launcher initializes its own runtime environment.
Custom executables and installations without that launcher keep their selected
path. The bounded hook PATH and user script remain unchanged.
Fresh workspace safety reads share one porcelain status and HEAD between the
dirty count, fingerprint and merge classification. A live staged-index scan
checks for mode 160000 before running recursive submodule status. A checkout
without gitlinks has an empty submodule contribution to the same fingerprint;
real gitlinks still use Git’s recursive status and recovery inventory. The absence
of .gitmodules alone never permits skipping that inventory.
Worktree creation resolves an explicit start ref to a commit before mutation.
The original ref retains Git upstream tracking. The branch-collision retry may reuse an
existing branch only when its tip matches the explicit base; it never resets that
branch. Requests without an explicit base keep the existing-branch fallback.
The app adapters capture base_commit from the allocated checkout before setup
scripts run and return it over IPC, HTTP and MCP.
Async Execution & Caching
The root Git adapters run blocking domain operations inside tokio::task::spawn_blocking; the domain crate does not own a runtime. All Tauri git commands are async and run git subprocesses inside tokio::task::spawn_blocking. This prevents blocking Tokio worker threads during I/O-heavy operations like git diff, git log, or git fetch.
Git data is cached with a 60s TTL in GitCacheState (state.rs), one moka::sync::Cache<String, Arc<T>> per result type keyed by repo path. moka’s get_with/try_get_with coalesce concurrent identical loads to a single computation — replacing the previous hand-rolled DashMap<String,(T,Instant)> whose check-then-compute-then-set pattern had a TOCTOU race that let a repo-changed burst fan out N duplicate computes. sync::Cache is used (not future::Cache) because every loader is blocking git work run on the blocking pool; the sync *_cached helpers keep working without async (git.rs::cached_get/cached_try wrap the pattern). github_repo_cooldown stays a plain DashMap — it is a cooldown set, not a TTL value cache.
The shared worktree inventory resolves the canonical repository and archive pool only inside its cache loader. Worktree-storage override lookup tries the exact repository key first, then compares portable Windows spellings, so a canonical verbatim root and a registered drive path select the same override. Async refresh and synchronous MCP cache hits do not reload storage settings. After a durable repositories or repo-defaults save, the shared Settings publication seam compares storage defaults and normalized overrides with its last snapshot. A storage change invalidates the inventory and dependent diff-stat caches; unrelated edits and unchanged storage settings retain them. Invalidation is conservative across repositories (at most 256 entries per cache), not a per-repository settings scan on each hit.
The repo_watcher (FSEvents on macOS, inotify on Linux) monitors the working tree with per-category debounce (Git/WorkTree/Config) and invalidates aggregate repository caches on file system changes (which also clears the prompt var_cache for the repo), so git data refreshes immediately instead of waiting for TTL expiry. On macOS/Windows it registers a single recursive watch (near-zero cost at the OS level); on Linux it splits into pruned non-recursive watches over the working tree (skipping ALWAYS_EXCLUDED_DIRS and gitignored paths, adding watches for newly created dirs from the event callback) plus targeted .git watches (root non-recursive for HEAD/index/sentinels, refs and worktrees recursive — never objects/logs), because a recursive inotify watch would walk and watch every subtree (node_modules, target, .git/objects) and flood the callback (issue #82). Each linked worktree gets its own watch: its working tree usually lives outside the repo root (the Sibling/AppDir storage strategies), so the root’s watch never sees it, and the git-state fingerprint is computed from the main checkout’s index + porcelain status, so a worktree-local edit leaves it identical and the emit is suppressed. Without those watches an agent editing a worktree produced no event at all and the branch’s sidebar diff badge stayed stale until the user selected the branch. The roots come from .git/worktrees/*/gitdir (linked_worktree_roots) and are re-synced by sync_worktree_watches on every git-state change — worktree add/remove is part of the fingerprint, so it always rides an emit and needs no watcher restart. classify_path matches worktree roots before the repo root, so a worktree stored inside the repo (.worktrees/, .claude/worktrees/ — usually gitignored) is not dropped as noise. The watcher respects .gitignore rules and hot-reloads them when .gitignore is modified. The 60s TTL serves as a safety net for missed watcher events. Most IPC calls for git data hit the cache (~0.2ms) instead of spawning a git subprocess (~20-30ms).
Sidebar monitoring: get_repo_diff_stats uses the same single-flight repository cache for progressive loading and get_repo_summary. Working-tree events invalidate it, so dirty badges read current checkout state. Monitoring derives unstaged line totals and porcelain dirty records from one gix status traversal per checkout. Untracked files affect dirty count only. A status-entry error retains partial diff totals but sends dirty counting through its fresh CLI fallback. Monitoring counts porcelain dirty records through gix (staged plus unstaged modifications to one tracked path count once; untracked records count separately, including a file also staged for deletion); sparse checkouts and submodules retain the existing CLI fallback. It does not compute the removal fingerprint or recursive submodule recovery inventory. Cleanup and removal continue to call the fresh lifecycle preflight. A bounded monitoring-only cache retains each successful checkout diff/dirty pair for at most five minutes on macOS/Windows, only after complete recursive watches are armed. Raw callbacks invalidate the owning checkout before ignore filters; linked admin index/HEAD events use the checkout’s resolved Git directory. Generation checks reject results superseded during a scan. Windows Modify(Any) notifications on existing mapped directories under the common .git or below checkout roots preserve status snapshots and watch authority: recursive child file/index/ref/config events carry the actual changes, including tracked files in ignored-looking directories. Checkout roots and unmapped paths retain conservative identity handling. Directory create/remove/rename, missing paths, and rescan still revoke trust where required. Normal linked-worktree inventory growth does not revoke existing watches, including when the bounded cache has evicted the main entry; the new checkout starts fresh and gets reuse only after its own watch is armed. Config, attributes, excludes and index/HEAD metadata signatures cover dependencies outside working-tree events. Watch loss, root replacement, stop and partial registration disable reuse until watches are re-established. Linux keeps fresh status reads because its pruned watches can omit tracked files in ignored/excluded directories. Sparse/submodule and failed status reads never reuse snapshots. Explicit Git operations invalidate their checkout; broad watcher refreshes preserve unchanged siblings. The fingerprint’s main-checkout CLI status uses --no-optional-locks to avoid optional index writes.
PR proof is reapplied on each repository stats refresh and is not stored in the ref-keyed local integration cache, so an upstream lookup can recover without local refs moving.
A sidebar refresh uses monitoring_ref_keys to share one ref snapshot. The cold read enumerates refs once; later reads retain ref targets and reflog hashes. A complete main-checkout watcher forwards changed paths to this snapshot, so a branch-only event refreshes that ref and its own reflog without probing sibling signatures. Watch startup uses signature validation until a delivered event confirms the stream is live. Watch errors, incomplete watches and standalone callers use mtime/size signatures; changed loose refs are resolved individually, while a changed packed-ref file rebuilds the shared targets. Unchanged HEAD/config and reflog contents are not reopened. Directory-level events conservatively validate signatures. A sibling branch tip is not part of another branch’s key. All remote refs remain dependencies because any remote may prove containment. Repository handles come from the shared gix handle cache. This does not cache dirty-state scans or the worktree inventory across refreshes. The existing per-repository coordinator keeps one active refresh and one pending trailing request; Git events use the existing 500 ms debounce. A pending shared-ref/configuration or linked-HEAD change bypasses the base-checkout fingerprint, which cannot observe a sibling commit. Other no-op Git events retain the fingerprint guard.
Workspace id lookup for lifecycle inspection and removal uses the same fresh GitReads.worktree_inventory as sidebar discovery, not a second porcelain-derived identity map. This preserves literal symbolic branch names from checkout HEAD. Removal can also resolve missing registrations and pooled checkouts. Branch compare-and-delete does not dereference symbolic refs, so removing an alias never deletes its target.
Worktree inventory reuses its root repository handle and reads each checkout’s admin HEAD directly. It does not open a full repository for the main checkout or each linked checkout. Detached rebase checkouts still recover their branch from Git’s operation files; missing and archived checkouts remain excluded.
Dirty-state and lifecycle monitoring also reuse cached gix handles. The handle cache checks configuration mtime/size signatures before reuse, including loaded sources, standard user configuration, explicit includes and worktree configuration. A changed signature reopens the handle; unchanged checks do not reopen Git configuration. Branch-conditional includes also track symbolic HEAD. A configuration source modified during loading prevents reuse of that snapshot.
Merged classifications have a separate bounded cache keyed by repository refs, symbolic HEAD, Git configuration and branch reflogs. File saves and the repository cache TTL do not rerun cherry, integration history or merge-tree; moving a ref recomputes classification. This eliminates the integration-process fan-out across active worktrees. Git subprocess counts for unsupported gix checkouts remain dependent on the fallback reads.
Watcher-miss observability: each cache’s moka eviction listener increments a shared ttl_fallbacks counter only on RemovalCause::Expired (TTL aged out without the watcher invalidating first) — explicit invalidations do not count. A rising counter means the watcher likely missed events; it is surfaced in the cpu_watchdog HEALTH/CPU-SPIKE snapshots as git_cache_ttl_fallbacks.
Internal callers that need synchronous access use _impl suffixes (e.g. get_diff_stats_impl) to avoid double spawn_blocking nesting.
GitReads Port (gix migration)
Read operations go through a reversible GitReads port (src-tauri/crates/tuic-git/src/git_reads.rs) so individual ops can be served by in-process gix (gitoxide 0.89) instead of shelling out, removing the process spawn + FD + stdout-parse cost on hot paths. CliGitReads delegates to the existing git_cmd-based functions; GixGitReads implements the same trait with a moka handle cache (ThreadSafeRepository per path → thread-local Repository per call). GitReadsRouter (the global git_reads()) dispatches each op to its backend via a per-op PerOpBackend.
An op is flipped to gix only behind a byte-for-byte parity (“shootout”) test comparing gix output to the CLI on a fixture repo. Where gix cannot match git’s exact output, the adapter retains its CLI fallback.
| Op | Backend | Notes |
|---|---|---|
branches_detail | gix | references() → shorten / peel / committer ISO8601 / author / summary / upstream. ahead/behind via the ahead_behind backend. |
ahead_behind | gix | rev_parse_single, then identical tips short-circuit to (0, 0) with no walk; otherwise two with_hidden revwalks (counts are order-independent; handles no-common-ancestor). branches_detail asks this once per branch, and a branch level with its upstream is the common case, so the short-circuit is what keeps that fan-out off O(branches x history). |
worktree_paths | gix | worktrees() + main worktree; paths canonicalized to match git worktree list real paths. Warm status is attached after backend selection so CLI and gix return the same checkout data. |
blame | gix | blame_file(); renamed-history files fall back to CLI (gix blame lacks -C/-M rename following). |
commit_log, graph_commits | gix | gix has no built-in topo sort, so gix_topo_order reproduces git log --topo-order (Kahn seeded by commit-date) and gix_decorations reproduces %D byte-for-byte (reverse-refname order, tag: prefix, HEAD -> branch). author_date UTC is normalized to git’s Z. |
status_counts | gix | repo.status() items mapped to staged/changed counts (TreeIndex = staged; IndexWorktree Change/IntentToAdd/untracked/conflict = changed; NeedsUpdate skipped). sparse-checkout / submodule → CLI fallback. |
diff_stats | gix (worktree) | unstaged worktree-vs-index --shortstat via per-blob imara (Myers + slider), binary excluded. Staged (--cached) and commit (hash^..hash) modes → CLI; sparse/submodule/error → CLI. |
All 8 read ops are served by gix, each gated by a byte-for-byte shootout test; the gix adapters fall back to the CLI internally for their unsupported edge cases (sparse/submodule, renamed-history blame, staged/commit diff). Backend::Cli is retained in PerOpBackend as a per-op rollback lever. The lever is temporary: after 2026-12-05, if the shootout tests have stayed green and no op has been rolled back, Backend::Cli and its router arms are deleted (CliGitReads itself stays — the gix fallbacks and the shootout tests both use it).
The 0.85 → 0.89 dependency migration retains these operations, features and fallbacks. The cached repository-open error uses the unified gix::Error type. Upstream raises its minimum Rust version to 1.88, below this repository’s CI compiler. Repository, status, blame and worktree facade calls keep the same inputs; worktree proxy paths are now anchored to the repository’s opening directory. The existing CLI parity tests remain the behavior contract on macOS, Linux and Windows.
The displayed unified diff/patch (get_git_diff), stash, reflog, and all writes/auth stay on the CLI permanently — they are not part of the port. The gix dependency uses default-features = false with only ["sha1","revision","status","blame","blob-diff","dirwalk","parallel"] (pure Rust, no C toolchain).
Monitoring Git Concurrency
Background repo-monitoring refreshes — get_repo_summary_impl, get_repo_structure_impl, and get_repo_diff_stats_impl — each fan out git subprocesses (worktree-list, branch --merged, per-worktree diffs). On a repo-changed burst across many registered repos this is unbounded and can spike concurrent git pipes past the OS file-descriptor limit (EMFILE) while flooding the main thread with IPC.
Each of these entry points acquires one permit from AppState.monitoring_git_sem (MONITORING_GIT_CONCURRENCY = 8) for the whole refresh, capping concurrent background refreshes to 8. Gating is per-function (not per-spawn) and deadlock-free because these entry points never call each other. Operational git (commit/push/stage/checkout/diff-on-click) is never gated — only monitoring work is throttled.
Subprocess Helper (git_cli.rs)
Every git subprocess invocation goes through git_cmd(cwd: &Path) -> GitCmd. The builder provides three execution modes:
| Method | Use Case |
|---|---|
run() | Strict — returns Err(GitError) on non-zero exit |
run_silent() | Optional — returns None on any error |
run_raw() | Full control — returns raw Output regardless of exit code |
GitError implements Into<String> for seamless use in Tauri command returns.
Deadlines
.timeout(Duration) kills the invocation when it outlives the deadline and returns
GitError::TimedOut (run_silent() turns that into None, with a warning). Without
it a git call waits forever, which is right for the local reads that dominate this
module and wrong for anything that can block on something outside this machine —
a network fetch, or a user-supplied setup script.
The deadline path pipes stdout/stderr, nulls stdin (matching Command::output(), so a
child cannot park on a read of the app’s own stdin) and drains the pipes on two reader
threads, so a child that fills a pipe buffer cannot deadlock against our own wait. On
timeout the child is killed and reaped (no zombie), but the reader threads are
deliberately not joined: a killed git can leave a grandchild (credential helper,
core.askpass) holding the write end open, and joining would reintroduce the unbounded
wait the deadline exists to prevent.
Two deadlines are in force:
| Constant | Value | Applies to |
|---|---|---|
git_cli::FETCH_TIMEOUT | 180s | Every git fetch: conflict_assist.rs (base refspec + PR head), github.rs local_pr_diff (base, refs/pull/N/head, head fallback), worktree.rs fetch_if_remote |
worktree::SCRIPT_TIMEOUT | 900s | The user’s worktree setup and archive/delete scripts, via run_shell_script |
Both are deliberately generous. A fetch is the only git call that waits on something
off this machine (GIT_TERMINAL_PROMPT=0 stops git’s own prompt but not a blocking
credential.helper, a half-open TCP connection or a wedged mount); 180s clears a
dual-stack connect timeout, so an unreachable host still reports git’s own error rather
than ours, and leaves room for a large branch delta on a slow link. The script deadline
is not there to bound how long a build may take — 900s sits above any plausible
cold-cache install-and-build — but to end the script that will never finish. Killing
work that would have succeeded is a worse outcome than waiting for it.
Stale index.lock reclaim
git_cmd() reclaims a .git/index.lock left by a crashed process, gated by two
independent checks — age and ownership:
- Age (
is_index_lock_stale): a 0-byte lock is stale after 5s (git crashed before writing the new index); a non-empty one after 30s (index written, rename never happened). - Ownership (
probe_index_lock_owner):lsof -w -t -- <lock>. If any live process still holds the lock open, it is kept whatever its age. Age alone cannot tell a crashed git from a merely slow one, and on a large monorepo anadd/stashindex write can outrun the threshold — deleting the lock under it corrupts the index.
The lock is located through resolve_git_dir(), not by joining .git to the cwd. In
a linked worktree .git is a file holding gitdir: <path>, so the naive join
traverses a file and the sweep returned before looking at anything — inert in every
worktree, which is where most of TUIC’s work happens.
The lsof fork happens only for a lock the age rule has already condemned, never on
the hot path of an ordinary git call, and it carries a 2s deadline of its own — it
runs inside git_cmd, so an lsof stuck on a wedged network mount would otherwise
wedge every git call in the app.
The probe answers with a LockOwnership: HeldBy(pids) keeps the lock, Unowned is
the only outcome that licenses a delete, and Unknown carries why it has no
answer — Unavailable (no lsof, exec refused, an lsof that ran and failed,
non-unix) or DeadlineExceeded (installed, working, slower than the deadline).
classify_owner_probe reads that answer from stdout and stderr, never the exit
code. Measured on macOS lsof 4.91, “nobody has this file open” and “lsof could not
stat the path” both exit 1 with empty stdout; only stderr separates them, and -w
does not hide it (it silences warnings, not status errors). So: PIDs win outright — a
complaint never outranks an answer, and HeldBy is the safe direction; otherwise a
non-empty stderr is a probe that ran and failed, which is Unknown; silence with no
PIDs is the real “no match”. Letting a failed probe land in Unowned would be a
fail-open with no log and no name, which is the failure this whole enum exists to
prevent.
Both Unknown arms fail closed (Boss’s decision, 2026-09-07, #694-4fcc): with no
answer the lock is kept, logged at warn. The two costs are not symmetric — a
stranded repo is recoverable by hand, a corrupted index is not — and the age rule
alone cannot tell a crashed git from a merely slow one. Measured lsof latency on
this hardware ranges 0.32s–3.7s against a 2s deadline, so DeadlineExceeded is a
routine outcome, not an exotic one; treating it as permission to delete was the
sharpest edge of the old policy.
“Kept” is not “kept forever”. The escape hatch is a second, much stronger rule for a
lock no probe can adjudicate: age at UNADJUDICATED_LOCK_STALE_SECS (1 hour),
far above the 30s ordinary threshold. The hazard fail-closed guards against is a git
that is merely slow, and the slowest legitimate index write is seconds — a process
holding index.lock for an hour is dead, not slow. This matters most exactly where
the probe can never work: on a host with no lsof, Unavailable is permanent, and
without the hatch a crash-orphaned lock would outlive the process that left it and
nothing could ever clear it. Evidence still outranks age at every age — HeldBy
returns before the hatch is considered.
On Windows there is no probe at all (Unavailable always), so an index.lock is now
reclaimed only via the hatch. That is safe rather than merely tolerable: Windows
refuses to unlink a file another process holds open, so the OS enforces the same rule
the probe does on unix.
Copy provenance and cleanup
Warming can select an ignored directory in the source that is not ignored on an
older destination branch. Those copied files then look like new untracked work.
copy_provenance.rs snapshots their regular-file SHA-256 hashes before copying,
checks both copies after copying, and atomically stores a receipt in the linked
checkout’s Git administrative directory. The receipt binds the source and
checkout paths and the Git administrative identity. Registered archive moves keep
that identity; a new registration cannot reuse another checkout’s receipt. It is not stored in the working tree and does not change Git’s
index or ignore rules. Existing destinations and symlinks do not receive proof.
Ignored destination caches keep normal Git semantics and are not hashed or added
to the receipt. The existing copy settings do not change this selection path.
Fresh lifecycle inspection and final no-force removal use the same classification. Only a non-ignored untracked file with matching receipt, current source and current destination hashes is an unchanged copy. Modified, missing, symlinked, unreadable, source-changed and new payload files still block cleanup. A failed or partial copy cannot publish proof for different bytes. A missing receipt never grants an exemption; a malformed or unreadable receipt makes safety unknown. There is no standalone file-deletion pass: the existing removal path still requires commit integration, exact checkout identity, no live or suspended users, lock handling, submodule preservation and its final fresh checks. Warming and removal retain the existing warm lock and cancellation token.
Removal previews include copied_files with a path and classification. Untracked
files in an older checkout without a receipt use uncertain-no-copy-proof.
Equality with today’s source does not establish historical origin. Inspection
never writes a receipt or deletes legacy files. Copy proof is deliberately not
reconstructed from a later source comparison.
Linked-worktree warming (cow.rs)
Every managed workspace is a linked Git worktree. After Git creates the clean
checkout, cow.rs asks Git for ignored directories and copy-on-write copies
those directories from the parent. It excludes every .tmp or .mdkb path component,
tracked paths, ignored files, nested repositories, and any directory containing
the destination. Tauri bundle.externalBin entries additionally select their
target-triple sidecar files by configuration, rather than by hard-coded names.
Each sidecar copy lands only in a new worktree path; clonefile creates a separate inode, and warming skips an existing destination. The source executable is never opened for writing by this path.
Submodules initialise from the parent checkout first (with the configured remote
as fallback), so unpublished pinned objects remain usable; failures are returned
as workspace warnings.
HTTP, MCP, and desktop IPC creation return while copy-on-write warming is pending. Their
instructions say to wait before running a build; GET /worktrees/paths?path=<repo>
and IPC get_worktree_paths report each workspace’s warm_artifacts.status
(pending, done, or failed). HTTP and MCP run a configured setup script
before warming. Desktop IPC currently starts warming before its frontend setup
script, so those two operations can overlap. Pending is recorded before
the setup script starts. If creation is cancelled during setup, the status
becomes failed instead of remaining pending. Removing or archiving a
worktree waits for an active copy, clears its warm state, and prevents a queued
copy from recreating the old path. Before Git removes a worktree, the removal
path restores owner write permission only inside that checkout, plus owner
search permission on directories before descending into them. This lets Git
remove ignored directories with modes such as 0644 without leaving a
half-deleted, unregistered worktree. Symlinks are not followed, and unreadable
directories still stop preparation before Git unregisters the checkout. A leftover path without Git registration is
reported with its path instead of being treated as a successful removal.
If Git has already unregistered a checkout but its directory remains, removal still clears a pending warm token before attempting directory cleanup. A path without a Git registration or a TUIC warm token is left untouched.
Archiving refuses a locked or missing checkout before moving it. It renames the
checkout into __archived, runs git worktree repair, and repairs initialized
submodule gitfiles and core.worktree paths. The Git administration directory,
HEAD, and reflogs remain registered; the workspace mapper hides archived paths
from active UI listings. A repair failure rolls the checkout back to its old
path. Allocation or rename-journal failures also restore the original path and
allocation state. The archive path is never unlocked and never pruned.
Orphan pruning accepts only a registered detached linked checkout with no Git
operation in progress. Immediately before removal it checks detached HEAD
reachability against all durable refs with git for-each-ref --contains; a
commit reachable only from the worktree HEAD/reflog is kept for recovery.
The Ask-mode cleanup dialog uses a separate automatic-removal assessment: tracked and untracked changes, and commits reachable only from tags, make the checkout unsafe for the countdown. Ignored files are allowed. The same check runs again for an agent’s remove answer and immediately before an automatic removal; the dialog lists each unsafe reason.
Non-force removal first requires a clean checkout and submodules, no Git
operation in progress, and a HEAD matching the captured branch tip. Git needs
one --force to remove a populated submodule even when it is clean; TUICommander
uses it only after checking submodule status and rechecking dirtiness immediately
before removal. A separate, confirmed lock override bypasses the lock during
removal; dirty-file force alone does not bypass a lock. Before removal, every
initialized submodule’s HEAD and refs are copied into preserved refs in the
main checkout’s module repository under a unique namespace. Before fetching,
the destination must resolve as that initialized module’s Git root inside the
main checkout, with a Git directory distinct from the superproject’s. An
uninitialized module or a misplaced .git file stops removal without deleting
the source checkout. Every stash and
reflog tip also gets a durable preserved ref, including older stash entries and
commits that have fallen off a branch. A missing checkout’s module bundle
includes reflog objects before Git removes its registration. Missing-checkout
module destinations are resolved from each owning main module’s .gitmodules
name-to-path mapping, including nested modules. Missing, duplicate, empty, absolute,
or parent-traversing paths stop cleanup before pruning; admin names are not a fallback. If preservation
fails, removal stops. For a deinitialized module, the leftover Git directory is
located by its configured .gitmodules name, including nested names that
differ from checkout paths; any retained admin state stops removal. The checkout is checked again after preservation,
immediately before Git removes it. Removing one checkout does not prune unrelated missing worktree registrations. A missing registered checkout requires force confirmation before preserving module refs and pruning its registration; a lock still needs a separate override. The normal workspace list hides missing checkouts. An
uninitialized submodule without Git state is safe to remove. The lifecycle preflight identifies a missing registered checkout explicitly; desktop and HTTP removal require a separate missing-checkout confirmation and recheck that the directory has not reappeared. Force confirmation
can carry a fingerprint of checkout status per path, HEAD, and submodule refs, rechecked
under the removal lock. The status portion records Git’s per-path porcelain
entries, not the contents of a file that was already dirty. Branch deletion in
either mode uses the captured OID in a compare-and-delete operation. If proof
fails or the branch moves, removal reports a warning and keeps the ref. For
branch deletion, it checks the default branch’s ancestry. A clean branch
whose commits were squash- or rebase-merged can also pass when git cherry
reports no unique patches. git cherry and context-free twin comparisons do not cover merge resolution
changes; a virtual no-op merge can cover the final tree instead. Content-based
proofs require a nonempty delta from the merge base. An empty start commit alone
is not integration evidence, even when a virtual merge leaves the default tree
unchanged. Actual ancestry and verified merged-PR evidence still apply. The removal
result names the matching rule.
Default-branch resolution uses only verified local Git refs, without a fetch:
the main checkout branch’s explicit branch.<name>.tuicommander-base, then
local main, then local master, then origin/HEAD (local branch when present,
otherwise the remote-tracking ref), then the main checkout’s attached HEAD branch. A linked
checkout never supplies the fallback HEAD. If none resolves to a commit,
lifecycle inspection blocks removal with an actionable reason; the sidebar
shows No base branch, with the full reason in its tooltip. Each branch-name
tooltip includes the status diagnostic once. Main checkouts do not show removal
warnings, because the sidebar cannot remove them.
The checked-out main worktree branch is another integration target: if it
contains the candidate tip, removal records integration_ancestry even when
the remote default branch is behind. Otherwise, a merged GitHub PR can prove
a squash merge when its fetched head contains the local tip. Open or closed
unmerged PRs, mismatched heads, and unavailable API data never prove deletion.
The request uses the repository-bound GitHub account and host. An incomplete
pagination read is unknown and is not cached; monitoring reuses definitive
answers for 300 seconds, while removal always asks again.
MCP worktree listing uses local monitoring proofs keyed by current refs without
resolving the full worktree inventory again for each entry. It reads GitHub proof
from the existing definitive-answer cache only; a miss stays locally unproven and
never starts network I/O. Background monitoring may populate the cache, while
destructive preflights still ask freshly. Its dirt,
fingerprint and submodule fields are still inspected freshly. A checkout HEAD
that differs from its branch ref bypasses the proof cache; destructive lifecycle
preflights always bypass it.
MCP branch_integrations and branch_integration, the branch panel’s merged
set, and workspace lifecycle share classify_branch_merge in tuic-git.
Ancestry, base, reflog, branch-config, subject, changed-path and remote-containment
reads run in process (gix). Only a branch that no ancestry proof settles runs the
content heuristics. They first ask for the Git facts they need; the classifier then
fetches them for all pending branches at once: one merge-tree --stdin, one
diff-tree | patch-id --stable (the git cherry comparison) and one zero-context
diff-tree --stdin. The process count does not grow with the branch count (#3024-58fe).
A merge that must merge a submodule pointer runs in its own merge-tree process,
because merge-tree --stdin (Git 2.54, 2.56) crashes on the next merge and loses every
result; a failed shared run is retried one pair per process. The in-process work
still takes seconds over hundreds of branches (19.6 s for 759 local branches of this
repository on 2026-11-13), so branches_detail
carries no merged flag; the branch panel requests get_merged_branches (every local
branch) after the list renders. get_repo_structure classifies only the checked-out
workspace branches (get_merged_workspace_branches_impl, its own cache), so a restart
does not run the heuristics over every local branch (#3021-3a69).
An empty or absent branch reflog is normal after expiry or when reflogs are disabled.
The classifier returns unknown without an error or merge proof for that branch;
repository structure and sibling branch classifications still load on repeated
refreshes. This verdict does not authorize branch deletion.
The integration query does not treat in_sync as merged and supplies no proof
for it. Explicitly finished empty checkouts can still be recycled; that marker
is allocation consent, not merge evidence. Orphan discovery excludes detached
checkouts whose HEAD is the tip of a non-default local branch. Detection fails
closed if Git cannot inspect that tip or the branch refs. Automatic-removal
safety repeats the same exclusion against current refs, so a branch restored
after discovery protects its checkout from a stale cleanup proposal.
The classifier also recognises clean virtual merges whose tree equals the
default target, and exact same-subject twin patches with unchanged added and
removed lines. A squash message is corroborating evidence only. The
content_superset heuristic requires an exact-tip archive before deletion;
worktree removal rechecks it after the archive hook. Safe branch-panel
deletion uses this classifier and compare-and-delete instead of Git’s
upstream-dependent branch -d. Explicit force deletion retains branch -D.
The integration tests cover ancestry, patch equivalence, no-op merges,
thresholds and known limits.
Keeping the branch skips branch-deletion proof while retaining dirty-work, submodule, operation, and lock checks.
MCP repo action=branch_delete applies the same merge classification to a
local branch with no checkout. It refuses the current and default branches,
checks every worktree record, and accepts ancestry in the checked-out
integration branch or patch equivalence against that branch when GitHub PR
proof is unavailable. The ref is removed with its captured OID as the expected
old value, so an advanced branch remains intact. Remote refs are untouched.
For archived deletion, the domain result captures the exact primary or
tip-suffixed archive ref before deleting the branch; MCP returns that ref so
restoring it recovers the deleted tip.
probe_cow_support performs a real copy against the source/destination pair so
an unsupported filesystem produces one warning instead of one failure per
ignored directory. The probe and copy primitive share COW_COPY_FLAGS (macOS
cp -c, then GNU cp --reflink=always); neither may silently fall back to a
byte-for-byte recursive copy. Warming is best-effort: failure leaves a complete,
valid, cold linked worktree.
After each copy, warming adds owner write permission to cloned files and
directories. It does not follow symlinks or change the source checkout, so
sealed ignored evidence remains available and the new worktree stays removable.
Shared-store linking checks the main checkout with git check-ignore before adding a root-anchored entry to the common info/exclude. This file is shared by all worktrees: adding an entry is safe only for a store the main checkout already ignores. Stores not ignored there are skipped with a warning. A worktree-local negation also prevents linking. Existing paths are never replaced. No extensions.worktreeConfig or core.excludesFile configuration is changed.
Tauri Commands
Repository Info
| Command | Signature | Description |
|---|---|---|
get_repo_info | (path: String) -> RepoInfo | Get repo name, branch, status, initials |
get_git_branches | (path: String) -> Vec<Value> | List all branches (sorted by rules below) |
check_is_main_branch | (branch: String) -> bool | Check if branch is main/master/develop/trunk |
get_initials | (name: String) -> String | Generate 2-char initials from repo name |
Diff Operations
| Command | Signature | Description |
|---|---|---|
get_git_diff | (path: String) -> String | Full git diff (staged + unstaged) |
get_diff_stats | (path: String) -> DiffStats | Addition/deletion counts |
get_changed_files | (path: String) -> Vec<ChangedFile> | List changed files with per-file stats (single subprocess call) |
get_file_diff | (path: String, file: String) -> String | Diff for a single file |
Repository Summary
| Command | Signature | Description |
|---|---|---|
get_repo_summary | (repo_path: String) -> RepoSummary | Aggregate snapshot: worktree paths, merged branches, diff stats, timestamps, workspace lifecycle |
get_repo_structure | (repo_path: String) -> RepoStructure | Fast: worktree paths + merged branches only |
get_repo_diff_stats | (repo_path: String) -> RepoDiffStats | Slow: per-worktree diff stats, last commit timestamps, and workspace-id lifecycle verdicts |
Lifecycle is backend-authored from the exact checkout HEAD. Linked worktrees
report dirty state, default-branch ancestry, and removal safety. Any failed check
serializes as unknown, never as clean or safe.
When branch deletion is requested, worktree removal checks this verdict before
touching the checkout. Without force, an unmerged branch or unknown verdict
stops the combined operation and leaves the worktree in place. With force,
removal may discard dirty checkout files, but an unmerged branch is retained
with a warning.
The shared classifier also reports pushed_unmerged when the exact tip is reachable from any remote-tracking ref, regardless of branch name or configured upstream. branch_integration.proof and the removal result name the containing refs/remotes/<remote>/<branch> ref. Lifecycle, workspace-list and sidebar monitoring reuse this classifier; the monitoring key includes all remote-tracking refs so a fetch invalidates stale verdicts. This permits worktree removal with local branch deletion, while standalone integrated-branch deletion keeps its existing merge/archive policy.
Removal captures the containing remote ref and its OID after the cleanup script. One git update-ref --stdin transaction verifies that proof OID and compare-deletes the captured local branch tip under the same ref locks. If cleanup prunes the proof or a concurrent fetch replaces or conflicts with it, the checkout is removed but the local branch is preserved, and the result includes a branch-deletion warning.
When removal would delete an unmerged branch, the error card offers Remove worktree, keep branch. The action reruns lifecycle checks and confirmation with branch deletion disabled for that removal only; the repository setting stays unchanged.
The frontend uses get_repo_structure (Phase 1) and get_repo_diff_stats (Phase 2) for progressive loading — UI rows appear immediately, stats fill in later. Refresh is single-flight per repository, with at least five seconds between automatic refresh starts. Requests inside that window join one trailing refresh at the window end, which reads the latest state. Requests during an active pass request one subsequent pass; repositories have independent windows. Explicit repository additions, branch checkouts and merge cleanup refreshes bypass the waiting window for the affected repository while preserving single-flight reads. Sidebar badges can lag by up to five seconds plus the backend read duration. This guarantees that sustained filesystem events cannot repeatedly cancel Phase 1 and leave deleted worktrees in the persisted sidebar cache. get_repo_summary remains for backward compatibility.
Branch Operations
| Command | Signature | Description |
|---|---|---|
rename_branch | (path, old_name, new_name) -> () | Rename a branch |
update_from_base | (path, branch, strategy?) -> String | Fetch base ref (if remote) and rebase or merge the branch onto it. On conflict, reports (aborted) only after git rebase/merge --abort succeeds; if abort fails, the error says the repo may still be conflicted and includes the manual abort command. |
start_conflict_assist | (repo_path, pr_number) -> ConflictAssistResult | Creates a PR-head worktree and rebases it. A conflict-free result is clean only after a successful origin refresh; stale tracking or local fallback results are clean_unverified with base_source and base_warning. |
get_branch_base | (path, branch) -> Option<String> | Read stored base ref from git config branch.<name>.tuicommander-base |
git_apply_reverse_patch | (path, patch) -> () | Apply a reverse patch for hunk/line-level restore |
Data Types
RepoInfo
#![allow(unused)]
fn main() {
struct RepoInfo {
path: String, // Repository path
name: String, // Repository name (from directory)
initials: String, // 2-char initials (e.g., "TC" for tuicommander)
branch: String, // Current branch name
status: String, // "clean", "dirty", or "conflict"
is_git_repo: bool, // Whether path is a git repository
}
}
status is the same verdict the git panel shows: get_repo_info_impl reads it
from git_reads().status_counts(), so the repo badge no longer forks a
git status --porcelain of its own beside the panel’s --porcelain=v2 read. One
status source per repo, one set of semantics (status_counts_from_porcelain_v2 in
git.rs): conflict when a porcelain-v2 u (unmerged) record is present, dirty
when anything is staged or changed, clean otherwise. Codes are read positionally,
so a file named UUID.md does not mark the repository as conflicted.
A repo git cannot read reports unknown, never clean — a green tick on an
unreadable repo is a silent failure.
Still separate: the repo watcher’s git-state fingerprint (repo_watcher.rs)
runs its own status --porcelain v1, and get_working_tree_status runs its own
--porcelain=v2 --branch --show-stash because it needs the per-file entries that
StatusCounts discards.
DiffStats
#![allow(unused)]
fn main() {
struct DiffStats {
additions: i32,
deletions: i32,
}
}
ChangedFile
#![allow(unused)]
fn main() {
struct ChangedFile {
path: String, // Relative file path
status: String, // "M" (modified), "A" (added), "D" (deleted), etc.
additions: u32, // Lines added
deletions: u32, // Lines deleted
}
}
RepoStructure
#![allow(unused)]
fn main() {
struct RepoStructure {
worktree_paths: HashMap<String, String>, // branch → worktree path
merged_branches: Vec<String>, // workspace branches merged into default
}
}
RepoDiffStats
#![allow(unused)]
fn main() {
struct RepoDiffStats {
diff_stats: HashMap<String, DiffStats>, // worktree_path → additions/deletions
last_commit_ts: HashMap<String, Option<i64>>, // branch → unix timestamp (seconds)
}
}
Utility Functions
get_repo_initials(name: &str) -> String
Generates 2-character initials from a repository name:
- Split on hyphens, underscores, dots, spaces
- If multiple words: first letter of first two words (e.g., “tuicommander” → “TC”)
- If single word: first two letters (e.g., “react” → “RE”)
- Always uppercase
is_main_branch(branch_name: &str) -> bool
Returns true for: main, master, develop, trunk, dev.
sort_branches(branches: &mut [Value])
Sorts branches by priority:
- Currently active branch (always first)
- Main branches (main, master, develop)
- Open PR branches (alphabetical)
- Feature branches without PRs (alphabetical)
- Merged/closed PR branches (alphabetical, always last)
Workflow integration receipts
The workflow service checks both merge parents and compares the canonical merge tree with git merge-tree --write-tree for those exact parents before running pinned post-integration checks. A merge that adds unrelated content or drops checked source changes cannot receive an integration receipt. This verification requires Git >= 2.38; older installations receive an explicit version requirement. A conflicted merge is rejected with an explicit request for human review or a separately verified artifact; the current receipt path does not grant either exception.
The run_git_command IPC command and /repo/run-git HTTP route share one argument policy, checked before Git starts. The first argument must be an allowlisted subcommand, so global options such as -c or --exec-path cannot precede it. After the subcommand, normal Git options are accepted (for example log --oneline, push --force-with-lease); each argument stays one argv entry and -- ends option parsing as in Git. Generic branch deletion (-d, -D, --delete and its abbreviations, short clusters such as -fd) is refused: branch deletion goes through the dedicated owner described below, and worktree is not allowlisted. On TCP listeners the HTTP route also requires authentication and a trusted origin; the local socket transport relies on the OS user. Network commands share the 180 s FETCH_TIMEOUT.
Force branch deletion first preserves the exact tip at refs/archive/<branch> and uses an expected-old-tip ref deletion. If refs/archive/<branch> already holds a different tip, the tip is archived at refs/archive/<branch>-<sha7> instead; an archive already at the same tip is reused. A checkout of the branch refuses deletion.
Stale creation recovery deletes only unregistered directories without a Git checkout. A sanitized-name collision with a registered worktree fails, preserving clean, dirty, and detached checkouts. Plain orphan directories can be recreated as worktrees.
The changed-file diff adapter reads raw status and numstat together with NUL delimiters. This keeps one Git subprocess per request while returning actual line counts and literal rename destinations for working-tree, staged and commit scopes.
Working-tree changed-file listings read untracked names with
git ls-files --others --exclude-standard -z. Nonempty NUL records are
used literally, including tabs, newlines and boundary spaces, so line counts
and file-diff consumers open the actual file. Staged and committed scopes
do not include untracked files.
Automation worktree cleanup (#1623-8b2a): Automation runs retain automation/run IDs and the exact created workspace path and ID in their saved snapshot, including after definition deletion. Worktree cleanup is explicit and limited to final runs. The backend resolves the saved identity and rechecks shared Git integration/archive proof, dirt, submodule commits and live sessions; it never forces removal or closes sessions. Shared automation_action actions worktree_preview and cleanup_worktree accept a saved run id on IPC, HTTP, MCP and CLI.
Finished checkout recycling
Workspace creation writes a durable reserved allocation marker in the linked checkout
Git administration directory before it returns. Only explicit archive or safe removal
writes finished; merged ancestry or missing sessions alone does not release a checkout.
Creation can rename and reuse a finished checkout from the same repository when Git
proves it clean and integrated, with no unpushed submodule commits, lock, operation,
pending warm, or live session. Recycling uses ordinary Git cleanliness, not the
copy-proof cleanup exemption: non-ignored copied payloads prevent reuse so the next
allocation cannot inherit their receipt. Ignored artifacts stay in place. Git registration and
submodule paths are repaired. The old workspace removal event precedes the new creation
event. A durable tuic-worktree-renames.jsonl journal lets external registry consumers
reconcile paths. Each record, including its newline, is serialized before the
append so parallel archive workers do not interleave JSON fragments. Allocation uses a blocking OS file lock in the Git common directory;
concurrent creates wait, and a process exit releases the lock. A failed recycle restores
the old checkout path, registration, branch and finished allocation state before returning
the error. Live sessions prevent recycling; fingerprint-confirmed forced deletion keeps
the existing deletion contract.
The existing removal/creation events are the frontend rename boundary; clients do not
need a separate worktree_rename response listener. The shared backend removal
notification retracts restore rows and declarations in the locked repository file,
even with no connected frontend. It announces the changed repository snapshot.
Frontend removal retracts saved peer placement declarations together with the old
sidebar workspace. Live PTY working
directories do not move with sidebar placement. The allocation guard excludes live
sessions rooted in the candidate checkout or its descendants.
Suspended checkout ownership uses the durable suspended-sessions.json records,
not just live PTYs. Both cwd descendants and worktree placement hold the checkout.
Shared allocation skips these users; removal, archive, branch deletion and orphan
cleanup refuse them even after force or session confirmation. Storage read errors
fail closed. Lifecycle removal retires matching core worktree bell offers.
Worktree removal and terminal ownership
Frontend removal events, post-merge cleanup and refresh pruning share cwd-based terminal cleanup. Workspace terminal arrays are a display index, not authority to close a PTY. The cleanup reads each terminal’s current reported cwd immediately before closing it and uses directory-boundary, separator-independent containment. Missing cwd is not permission to close. Surviving tabs from a removed row are reconciled to their cwd workspace or parked in the Global Workspace.
Creation alone remains cwd-based. Explicit caller declarations override cwd only for display placement, never terminal cleanup. A declaration must match an existing workspace id and checkout path; removal retracts it. An undeclared repo-root session waits for the root workspace to be discovered rather than joining the selected linked worktree.
Explicit worktree removal uses the same current-cwd terminal cleanup as removal events and refresh. Sidebar membership does not authorize closing a PTY. Tabs outside the removed checkout are rehomed after successful removal.
Checkout discovery inventory
CLI and Gix return branch-addressed worktree_paths plus a separate detached_worktrees list. Detached records contain the path, full HEAD SHA, seven-character short_head, directory name and state: "detached". They do not create workspace IDs. The root adapter supplies the effective configured worktree base’s __archived pool. Live discovery also hides checkouts directly under another __archived directory when their Git administration directory contains TUIC’s finished allocation marker. This keeps externally created and former-storage archives hidden after a storage change without hiding unrelated directories with that name. Unfiltered inventory still includes archives for removal. Gix resolves the common Git directory before finding the main checkout. CLI discovery reads NUL-delimited git worktree list --porcelain -z, so newline paths remain intact.
Worktree discovery diagnostics
The additive inventory also returns worktree_diagnostics records with path, nullable branch, state (missing or duplicate_branch), and guidance. Bare repository metadata is not a checkout and does not produce a missing-checkout diagnostic, including when inventory starts from a linked checkout backed by a bare common directory. Missing or broken checkouts never enter the selectable map. Discovery does not prune registrations. A forced duplicate branch keeps one deterministic primary checkout (lexicographically smallest path); additional paths become read-only diagnostics. Legacy lifecycle resolution uses the same primary ordering so an action does not target a different duplicate. Workspace IDs do not change.
Synchronous and asynchronous inventory cache loaders retain only successful reads. MCP repository listings report worktree_error on discovery failure; ACP workspace snapshots report worktreeError. Bisect recovers BISECT_START only when it resolves to an existing local branch. Rebase recovery uses the shared Git directory resolver, including relative gitdir paths and the main checkout.
Unavailable detached registrations are excluded from automatic orphan cleanup in both Ask and On modes, including the Ask countdown. They remain repair diagnostics until restored or explicitly removed. Safe-only removal rechecks availability, so a directory moved after assessment cannot be pruned automatically. Explicit user-confirmed removal remains available.
Archive workspace checklist
The fresh removal preview includes archive_checklist: pass/fail labels, the
Delete verdict and action explanations. It reuses lifecycle dirt, merge proof,
submodule hazards and live-cwd ownership. A default-integration-ref rev-list
adds the missing commit count. Unknown inspection never passes. Permanent Delete
recomputes the same verdict before mutation. Explicit Archive uses the existing
fingerprint-confirmed finalization path and retains dirty files and unmerged refs.
Archived checkout retention
tuic_git::worktree::archive_worktree records archive Unix seconds and the exact canonical checkout path/branch/tip in the per-checkout Git admin tuic-archive.json, after the archive script and move. It also preserves the tip in refs/archive/. The app resolves archive_retention_days from repository override → .tuic.json → global default (0/Off), then calls the domain sweep during repository refresh. The sweep and recycling share the allocation lock. Only finished, registered immediate __archived children with matching metadata qualify; legacy records fail closed. A fake clock drives real Git boundary tests. Non-force git worktree remove rechecks safety and removes registration without pruning unrelated entries. Dirty files, live sessions, locks and changed recovery evidence prevent removal.
WF07 adds an opt-in typed native integration saga. It checks a pinned two-parent merge object before publishing it, serializes by canonical Git common directory, and keeps proof debt and cleanup independent. Exact-tip archives and TUIC non-force removal protect source workspaces. See Native integration for rollout, conflict and recovery rules.
Unrelated branch histories
The integration classifier checks for a common ancestor before computing a
branch delta. A git merge-base exit status of 1 means that the two histories
are unrelated. It supplies no content-integration proof, but does not fail the
repository’s merged-branch inventory. Other Git failures still propagate.
If no default candidate shares an ancestor, branch queries and workspace lifecycle/monitoring return commit_status: "unrelated_history", even without a reflog. This is a successful classification, not a refresh error, and cached PR metadata cannot turn it into merged work. Compact and rich sidebar rows show Unrelated history. Worktree removal must keep its branch; standalone branch deletion requires an existing exact-tip archive. A candidate with shared ancestry still permits normal integration proofs.
Native worktree recycling measurement — 1705-67b3
Measured on macOS on 2026-10-14 with source commit ed856e5f0392.
The coordinator explicitly authorized one native headless build after the existing
tuic-remote was found to be a desktop-feature stub.
Method
- Build: mbx shim through
build-slot.sh cargo build --manifest-path src-tauri/Cargo.toml --bin tuic-remote --no-default-features.mbx doctor: zero failures. Build: 3m34s, 453 hits and 122 misses. - Start only the headless binary with a unique loopback port and named instance,
--no-agent-configs, isolated HOME and TMPDIR under~/Gits/.tmp/feat-1705r-native. No desktop process was launched or restarted. The owned daemon PID was terminated and awaited infinally. - Scratch Git repository: 101 tracked files; one finished checkout with 1,000 ignored cache files (1,024,000 bytes). Source and ignored-file contents are synthetic local fixtures, not a copy of the production repository.
- Seed one checkout, wait for warming, add ignored files, then safely remove/archive it. Measure 15 serial
POST /worktreesresponses: pilot 3, main 10, completion 2. Safely remove/archive each checkout between creations so the next create recycles it. No agent PTYs were spawned. - Every response had
worktree_rename; the old path disappeared, branch HEAD matched repository HEAD, and the ignored artifact inode stayed identical. - Authenticate once with fixture-only Basic credentials, then use the issued session cookie. An earlier run repeated bcrypt Basic authentication per request; it is excluded from the final timings (15 creates, 15.173 s total) because it measured avoidable authentication work too.
- Sample
ps -axo pid=,pcpu=,comm=every 100 ms around the create/archive run. Sum matchingwdavdaemonprocesses andfseventsdseparately per sample.ps %cpuis a rolling process average, not interval CPU or CPU attributable to this benchmark. The host had other work. Sampling includes archive operations between creates.
The script and raw final results are adjacent: worktree-recycling-1705-native.py
and worktree-recycling-1705-native.json. The script uses an isolated scratch
root; remove that task-owned root before a repeated run. Its fixture credentials
are not production secrets.
Results
15 of 15 recycled creations succeeded. Total HTTP create wall time: 10.801823 s. Median: 0.701350 s; minimum: 0.621877 s; maximum: 0.888786 s.
| Creation | Seconds |
|---|---|
| pilot-0 | 0.621877 |
| pilot-1 | 0.749290 |
| pilot-2 | 0.881157 |
| main-0 | 0.690551 |
| main-1 | 0.758963 |
| main-2 | 0.701350 |
| main-3 | 0.705567 |
| main-4 | 0.661313 |
| main-5 | 0.791435 |
| main-6 | 0.721188 |
| main-7 | 0.652631 |
| main-8 | 0.652088 |
| main-9 | 0.646087 |
| completion-0 | 0.888786 |
| completion-1 | 0.679540 |
153 CPU samples over 25.655 s:
| Process family | Minimum % | Mean % | Peak % |
|---|---|---|---|
| wdavdaemon, summed | 68.5 | 144.116 | 284.4 |
| fseventsd | 0.1 | 5.203 | 19.1 |
Baseline comparison and limits
The orchestrator report 2026-10-10-ego-swarm-benchmark.md reports a
18:25–18:31 window for 15 full production worktree spawns, three failures,
Defender peak 277% and fseventsd peak 32%. Each production checkout held
approximately 5.4 GB, including a large untracked directory and ignored artifacts.
The baseline does not give per-create wall times, and its initial CPU sampler was
incorrect; some peaks came from later or manual samples.
This scratch-repository run is not a matched before/after experiment: it is serial, uses a much smaller fixture, has no agent launches, and observes shared-host CPU. It proves native API recycling succeeds and retains ignored inodes; it does not prove a production throughput speedup or reduced Defender CPU. In fact the observed Defender peak here was higher than the reported baseline. fseventsd’s observed peak was lower, but attribution and workload differences prevent a causal claim. No settings, exclusions, cache, or production checkout were changed.
GitHub Integration
Modules: src-tauri/crates/tuic-git/src/{github,github_account,github_auth,github_poller,circleci,pr_review,changelog,github_debug}.rs contains GitHub data types and pure decisions. The matching modules under src-tauri/src/ keep API clients, credential and config storage, polling, event emission, ego calls, and Tauri commands; they re-export the domain items at their existing paths.
Integrates with GitHub via GraphQL API for PR status, CI checks, and batch queries. Supports OAuth Device Flow login as an alternative to environment tokens, plus multiple accounts (additional github.com logins and GitHub Enterprise Server) with per-repo bindings.
The batch PR query fetches the 10 most recently updated closed PRs in a separate connection so the poller can detect an open-to-closed transition without reducing the open PR limit. An active PR takes precedence when both connections contain the same branch.
Worktree deletion has a fail-closed, account-aware HTTP GraphQL proof through
RepoApi::resolve and graphql_pages. It uses the repository binding and host,
the shared HTTP client, and account-scoped breaker/rate-limit accounting.
Pagination must finish within 100 pages; errors, malformed page info, and repeated
cursors leave the lookup unknown and uncached. Synchronous Git callbacks bridge
through the Tokio runtime only from blocking tasks. When Git
ancestry does not reach the default or checked-out integration branch, it reads
merged PRs for the worktree branch and accepts one only when its recorded head
contains the local tip. Missing heads are fetched from refs/pull/N/head and
checked against the API SHA before ancestry is trusted. An API/auth/fetch
failure leaves the branch unproved; patch-equivalence remains a local fallback.
The MCP local-branch deletion action uses the same merged-PR evidence when a
branch has no worktree.
REST requests use github::github_rest_request with the host and token selected by
resolve_repo_for_rest (registry and per-repo binding) or by the account identity
flow. The builder pins User-Agent: TUICommander, the requested Accept media type,
and X-GitHub-Api-Version: 2022-11-28. GraphQL uses the same User-Agent. Each caller
keeps its status/error wording and existing circuit-breaker handling. A production
source guard (production_code_spawns_no_gh) fails when production code spawns gh; its allowlist is empty.
PR creation, issue creation, and review submission use account-aware RepoApi::rest
POST requests to pulls, issues, and pulls/{number}/reviews. The repository
binding selects the host and token, including GitHub Enterprise. These writes no
longer require the gh executable or pass tokens to child processes. Review inline
comments retain their side (default RIGHT). REST errors retain the HTTP status
and response body as GitHub API failed ({status}): {body}. IPC and HTTP request
and response shapes are unchanged.
Multi-Account Model (github_account.rs)
The integration is account-centric: the primary key is a stable GitHubAccountId, not the host. This keeps github.com behaving exactly as before behind an “ambient default” account while enabling additional accounts.
GitHubHost— canonical (lowercased, validated) host.is_cloud()→ github.com;graphql_url()/rest_base()returnapi.github.com(+/graphql) for cloud andhttps://{host}/api/graphql/https://{host}/api/v3for GHE.is_ambient_default()routes the global-vs-per-account branch points.- Account kinds —
GithubComOAuth/GithubComEnv/GithubComGhCli(the ambient default, existing auth chain), additional named github.com accounts, andGhePat(GitHub Enterprise Server via pasted PAT). - Credential storage — github.com keeps
Credential::GithubOauthToken(github/oauth-token) unchanged; per-account PATs useCredential::GithubToken(account_id)→github/account/{id}/token. - Repo bindings —
{repo_path → account_id, owner, repo, remote_name}persisted per canonical repo root (worktrees resolve to the main root).resolve_repo_account(repo_path)returnsRepoResolution::{Bound | NeedsBind(candidates) | NeedsAccount | Unmonitored}— binding-first, a single candidate returnsBoundwithout persisting a binding, and multiple candidates returnNeedsBindfor every consumer (never a silentoriginpick). Fork and upstream remotes on the same account still identify different repositories and require a remote choice. - Concurrent saves — Binding maps use
ConfigFile::save_delta, so changes to different repositories compose. Account additions and removals mutate the latest registry underConfigFile::update_with; the on-disk array is never replaced from a stale account snapshot. - Per-account isolation (hybrid) — github.com keeps the global breaker/viewer/rate/cooldown fields byte-for-byte; GHE accounts get isolated
ghe_state: DashMap<AccountId, GheAccountState>. The poller groups repos by resolved account and runs one batch per account, so a fault on one never opens another’s breaker. Cooldown keys:owner/repo(cloud, unchanged) vs{account_id}:owner/repo(GHE). - CI logs — github.com and GitHub Enterprise use the repo-resolved account token and REST host. Actions runs, jobs and logs use the account circuit breaker. Log redirects remove bearer credentials when the storage host changes.
Multi-account commands
Create Enterprise accounts through the core account manager and enter PATs through account_secret_form. The legacy PAT add command and POST /github/accounts route are removed; GET /github/accounts remains available.
| Command | Signature | Description |
|---|---|---|
github_list_accounts | () -> Vec<GitHubAccount> | Additional accounts beyond the ambient github.com default |
github_remove_account | (id: String) -> () | Cascade-remove token + record + bindings + per-account caches |
github_bind_repo | (repo_path, account_id, remote_name) -> () | Persist a repo→account binding |
github_unbind_repo | (repo_path: String) -> () | Remove a repo binding |
github_list_bindings | () -> Vec<Binding> | All persisted repo→account bindings |
github_resolve_repo | (repo_path: String) -> RepoResolutionDto | bound / needs-bind / needs-account / unmonitored + candidates |
Token Resolution
Priority order (first non-empty wins) for the ambient github.com account:
GH_TOKENenvironment variableGITHUB_TOKENenvironment variable- OAuth keyring token (
github_auth.rs— stored in OS keyring viakeyringcrate)
The active token source is tracked in AppState.github.token_source as a TokenSource enum (Env, OAuth, Pat, None), serialized as env, oauth, pat, none in both transports. resolve_token_for_account(&GitHubAccount) runs this exact chain for github.com and returns the vault PAT (TokenSource::Pat) for GHE accounts.
An explicit disconnect is held in runtime state under the token lock. Status refresh, GraphQL lazy resolution, deferred probes and in-flight fallback writes cannot reconnect the ambient account. A successful primary device-flow login re-enables it; named accounts stay independent.
Tauri Commands — Authentication (github_auth.rs)
| Command | Signature | Description |
|---|---|---|
github_start_login | () -> DeviceCodeResponse | Start OAuth Device Flow, returns user code |
github_poll_login | (device_code: String) -> PollResult | Poll for token, saves to keyring on success |
github_logout | () -> () | Delete OAuth token from keyring, fall back to environment tokens |
github_auth_status | () -> AuthStatus | Current auth status with login, avatar, source |
github_disconnect | () -> () | Delete the ambient OAuth token and disable ambient runtime credential resolution until device-flow login or restart; environment variables remain unchanged |
github_diagnostics | () -> Value | Diagnostics: token sources, scopes, API connectivity |
Tauri Commands — GitHub Data (github.rs)
| Command | Signature | Description |
|---|---|---|
get_github_status | (path: String) -> GitHubStatus | Remote presence, current branch, ahead/behind counts |
get_ci_checks | (path: String, pr_number: i64) -> Vec<Value> | Detailed CI check list for one PR |
get_pr_review_threads | (path: String, pr_number: i64) -> ReviewThreadCounts | Unresolved review threads of one PR, bot vs human vs ego (GraphQL, 1 point per page). Ego threads start with a comment that holds review_bots::EGO_MARKER. The batch poll only carries BranchPrStatus.unresolved_threads |
get_repo_pr_statuses | (path: String, include_merged: Option<bool>) -> Vec<BranchPrStatus> | PR status for every branch of one repo (TTL-cached unless include_merged) |
approve_pr | (repo_path: String, pr_number: i64) -> () | Submit approving review via the REST reviews endpoint |
update_pr_branch | (repo_path: String, pr_number: i64, expected_head_sha: String) -> () | Merge the base branch into the PR branch (REST PUT /pulls/{n}/update-branch, same operation as GraphQL updatePullRequestBranch), pinned to the head the UI showed; 422 head mismatch → PR head changed |
close_pr | (repo_path: String, pr_number: i64) -> () | Close a PR without merging (REST PATCH /pulls/{n} state=closed) |
get_all_pr_statuses | (paths: Vec<String>, include_merged: bool) -> HashMap<String, Vec<BranchPrStatus>> | Batch PR status across many repos in one GraphQL call |
get_pr_diff | (repo_path: String, pr_number: i64) -> PrDiff {diff, headSha} | Get PR diff content and the head commit it was read at (head read before and after the diff; a push in between is an error); falls back to a local-clone git diff when GitHub rejects oversized diffs |
merge_pr_via_github | (repo_path: String, pr_number: i64, merge_method: String, expected_head_sha: String) -> String | Merge PR via GitHub API, pinned to the reviewed head (409 → PR head changed) |
fetch_ci_failure_logs | (repo_path: String, branch: String, check_url?: String, head_sha?: String) -> String | Fetch failure logs for the local branch head during auto-heal or for a selected check at the PR head SHA |
create_issue_from_proposal | (repo_path: String, proposal: ImprovementProposal) -> CreatedIssue | Explicit issue creation from a proposal; scan never creates issues automatically |
Failing checks for auto-heal
Failing checks are read from the exact commit’s statusCheckRollup.contexts,
through RepoApi::resolve and account-bound GraphQL with breaker accounting.
The lookup does not search open PRs. It combines up to 100 pages before keeping
the newest check per name, then returns failed CheckRuns and external
StatusContexts with their detail links. An incomplete response is an error;
a commit with a null rollup has no checks. CI job log retrieval remains a
separate operation.
Circuit breaker coverage
Every call out to GitHub goes through the account’s circuit breaker:
GraphQL via graphql_with_retry, PR/issue/review writes via RepoApi::rest, and direct
REST via send_rest_with_breaker (close/reopen issue, merge PR, approve PR,
fetch_github_json, PR diff, PR refs). The availability breaker counts transport
errors and 5xx responses, not deterministic 4xx caller outcomes such as a
missing issue, merge conflict, validation failure, or permission denial. Rate
limits use their separate backoff: 429, primary-limit 403 headers,
retry-after, or a secondary/abuse-limit message in an otherwise ambiguous
403 body. Non-rate-limit bodies remain available to caller-specific error
formatting.
Cached viewer login
state.github_viewer_login backs author:@me in the viewer-PR search and the
assignee/creator/mentioned issue filters. It is dropped by
github::invalidate_viewer_login on logout, disconnect and a successful device-flow
login — without that, switching accounts kept showing the previous account’s PRs
and issues for the rest of the session. Named accounts cache their own login in
ghe_state and are deliberately untouched by that invalidation.
Tauri Commands — Polling (github_poller.rs)
| Command | Signature | Description |
|---|---|---|
github_start_polling | (paths: Vec<String>, issue_filter: String, pr_hide_drafts: bool) -> () | Start/reconfigure the background poller |
github_stop_polling | () -> () | Stop the poller task |
github_set_visibility | (visible: bool) -> () | Switch between the visible and hidden poll intervals |
github_poll_repo | (path: String) -> () | Request a debounced one-off poll of a single repo |
github_update_paths | (paths: Vec<String>) -> () | Replace the polled repo set |
github_set_issue_filter | (filter: String) -> () | Change the issue filter mode live |
github_set_pr_hide_drafts | (hide: bool) -> () | Toggle draft-PR filtering live |
Frontend startup and repository add, remove, park/unpark, and disk adoption use
services/githubPollingPaths.ts to group active paths by connection owner. Local
polling receives only local paths; connected daemons receive only their own paths.
An empty local set clears local polling. Removing or parking an owner’s last active
repository sends an empty path set to that owner. Disconnected owners are skipped.
The diagnostics repos_monitored gauge counts repository paths with successful
PR snapshots in the running poller’s transition history, including empty snapshots.
It does not count entries in the TTL query cache. Cache expiry and failed poll ticks
do not remove monitoring identity. Removing a configured path drops its transition
and change-detection history and queued on-demand requests. Late on-demand requests
for unconfigured paths are ignored, so completed asynchronous actions cannot restore
a retired monitor. Stopping the poller resets the gauge to zero. A new
poller starts with no successful snapshots, even if old query payloads remain cached.
For the distinction between configured paths, successful monitoring history, and rendered sidebar data, see the 2336 investigation. It records why the old TTL-cache gauge could report zero without deregistration and which observations are still required to prove the historical empty sidebar.
Data Types
GitHubStatus
#![allow(unused)]
fn main() {
struct GitHubStatus {
has_remote: bool,
current_branch: String,
ahead: i32,
behind: i32,
}
}
PR and CI data are not on this type. They arrive through BranchPrStatus, which
the batch endpoints return per branch.
BranchPrStatus (Batch Endpoint)
Full PR data for a single branch, returned by get_repo_pr_statuses:
#![allow(unused)]
fn main() {
struct BranchPrStatus {
branch: String,
number: i32,
title: String,
state: String,
url: String,
additions: i32,
deletions: i32,
checks: CheckSummary, // passed/failed/pending/total
author: String,
commits: i32,
mergeable: String, // "MERGEABLE", "CONFLICTING", "UNKNOWN"
merge_state_status: String, // "CLEAN", "DIRTY", "BEHIND", etc.
review_decision: String, // "APPROVED", "CHANGES_REQUESTED", etc.
viewer_did_approve: bool, // Viewer's own latest review is APPROVED
labels: Vec<PrLabel>, // Labels with pre-computed colors
is_draft: bool,
base_ref_name: String,
head_ref_oid: String,
created_at: String,
updated_at: String,
merge_state_label: Option<StateLabel>, // Pre-classified display label
conflict_state: ConflictState, // The single conflict verdict both surfaces render
review_state_label: Option<StateLabel>, // Pre-classified display label
merge_commit_allowed: bool, // Repo-level merge settings
squash_merge_allowed: bool,
rebase_merge_allowed: bool,
}
}
PrLabel
#![allow(unused)]
fn main() {
struct PrLabel {
name: String,
color: String, // Hex color from GitHub
text_color: String, // Computed: black or white based on luminance
background_color: String, // Computed: hex_to_rgba with alpha
}
}
CheckSummary
#![allow(unused)]
fn main() {
struct CheckSummary {
passed: u32,
failed: u32,
pending: u32,
total: u32,
}
}
StateLabel
#![allow(unused)]
fn main() {
struct StateLabel {
label: String, // Human-readable text (e.g., "Approved", "Behind")
css_class: String, // CSS class for styling
}
}
Utility Functions
parse_pr_node(v: &serde_json::Value) -> Option<BranchPrStatus>
Parses one PR node out of the batched GraphQL response and enriches it with computed fields (merge state classification, conflict verdict, review state classification, label colors).
classify_merge_state(mergeable: Option<&str>, merge_state_status: Option<&str>) -> Option<StateLabel>
Delegates the conflict question to classify_conflict_state first, then maps the
merge state to a display label:
| Condition | Label | CSS Class |
|---|---|---|
ConflictState::Conflicting | Conflicts | conflicting |
ConflictState::Checking | (no chip — GitHub is still recomputing) | — |
| CLEAN | Ready to merge | clean |
| BEHIND | Behind base | behind |
| BLOCKED | Blocked | blocked |
| UNSTABLE | Unstable | blocked |
| DRAFT | Draft | behind |
| DIRTY | Conflicts | conflicting |
| UNKNOWN, HAS_HOOKS | (no chip) | — |
classify_review_state(review_decision: Option<&str>) -> Option<StateLabel>
| review_decision | Label | CSS Class |
|---|---|---|
| APPROVED | Approved | approved |
| CHANGES_REQUESTED | Changes requested | changes-requested |
| REVIEW_REQUIRED | Review required | review-required |
hex_to_rgba(hex: &str, alpha: f64) -> String
Converts a bare 6-char hex color (e.g. "ff0000", no leading # — that is what
GitHub’s label API returns) to an rgba string (e.g. "rgba(255, 0, 0, 0.5)"). Invalid
input parses as (0, 0, 0).
is_light_color(hex: &str) -> bool
Computes BT.601 luma ((r*299 + g*587 + b*114) / 1000 > 128) on the same bare hex to
decide whether a label needs dark text.
Tauri Commands — Issues
| Command | Signature | Description |
|---|---|---|
get_all_issues | (paths: Vec<String>, filter_mode: String) -> HashMap<String, Vec<GitHubIssue>> | Fetch issues for multiple repos in one batched GraphQL call |
close_issue | (repo_path: String, issue_number: i64) -> () | Close an issue via the REST issues endpoint |
reopen_issue | (repo_path: String, issue_number: i64) -> () | Reopen a closed issue via the REST issues endpoint |
GitHubIssue
#![allow(unused)]
fn main() {
struct GitHubIssue {
number: i32,
title: String,
state: String, // "OPEN", "CLOSED"
url: String,
created_at: String,
updated_at: String,
author: String,
labels: Vec<PrLabel>, // Reuses PrLabel with computed colors
assignees: Vec<String>,
milestone: Option<String>,
comments_count: i32,
}
}
Issue Filter Modes
The filter_mode parameter controls which issues are fetched. It is applied as a
GraphQL filterBy argument (issues_filter_clause), not a Search API qualifier:
| filter_mode | GraphQL filterBy | Description |
|---|---|---|
assigned | { assignee: "{viewer}" } | Issues assigned to the authenticated user |
created | { createdBy: "{viewer}" } | Issues created by the authenticated user |
mentioned | { mentioned: "{viewer}" } | Issues mentioning the authenticated user |
all | (none) | All open issues in the repo |
disabled | (issues sub-selection omitted) | Issue fetching disabled — get_all_batch_impl drops the whole section |
Issue Query Construction
build_multi_repo_issues_query builds one aliased repository(owner:, name:) block
per repo, each embedding an issues(first: 30, states: [OPEN], orderBy: UPDATED_AT DESC) sub-selection. It uses repository().issues() rather than search() because it
costs fewer GraphQL points. Results are parsed via parse_issue_node, which extracts
labels with hex_to_rgba color computation (same opacity constant
LABEL_BG_OPACITY = 0.7 as PRs).
GraphQL Batching
get_repo_pr_statuses reuses the multi-repo query builder (build_multi_repo_pr_query)
and sends it through graphql_with_retry — one GraphQL call returns every branch with
PR data. gh pr list is used only as the parity oracle in tests.
Polling budget: github_poller.rs batches all polled repos into one GraphQL
call per tick, so the cost does not scale with repo count. Intervals: BASE_INTERVAL
60 s when visible, HIDDEN_INTERVAL 120 s when hidden, backing off to MAX_INTERVAL
300 s on failures or a critically low rate budget.
PR Approval & Merge
approve_pr
POST {rest_base}/repos/{owner}/{repo}/pulls/{n}/reviews with {"event": "APPROVE"},
sent through send_rest_with_breaker. Used by the remote-only PR popover.
PR Diff Fetching
PR diff reads use the GitHub REST diff representation first. If GitHub returns the oversized-diff 406 Not Acceptable response, the backend fetches the PR refs into the local clone and returns a local git diff base...head unified diff instead, so AI Review can still run on PRs that exceed GitHub’s rendered diff file cap.
CI Auto-Heal (fetch_ci_failure_logs)
Actions logs use REST runs filtered by head_sha, then jobs with filter=latest.
Each list has a ten-page cap (100 entries per page). A run with unavailable or
incomplete jobs is skipped. Downloads retain only the last 4,000 bytes per job,
with at most 100 job logs retained; output is sanitized before agent use.
One 60-second async deadline covers the sweep and any external CI downloads.
Only local Git head resolution uses a blocking worker; HTTP work is cancellable.
Resolves the local branch head for auto-heal, or uses the supplied PR head SHA for a selected check, then lists matching workflow runs, inspects their jobs, and downloads logs for every completed failed job through the GitHub Actions jobs API. Job-level retrieval works while sibling jobs are still running, before the containing workflow has a final failure conclusion. Used by the CI auto-heal hook (useCiHeal) to inject failure context into agent terminals for automatic fix cycles (up to 3 delivered attempts per cycle).
GitHub Actions jobs are downloaded through GitHub’s jobs API. CircleCI checks are selected from a PR whose head SHA matches the local branch for auto-heal or the supplied PR head SHA for a selected check, including remote-only PRs, restricted to the repository’s GitHub owner/repository, and fetched only when a CircleCI token is configured. A selected CircleCI check takes precedence over failed GitHub Actions jobs; an unselected auto-heal request keeps GitHub Actions priority. Every gh and git process on this path has a 30-second deadline; a timeout returns an error and auto-heal clears its in-flight state. The CircleCI job’s vcs_revision must match that SHA. CircleCI API and action-log requests never follow redirects; pre-signed action-log downloads accept only Amazon S3 HTTPS hosts and do not receive that token. The JSON action output is parsed as a stream, retaining at most 64 KiB of recent message text before the shared sanitiser and 4,000-character output limit; a 16 MiB download ceiling bounds transient parser memory. Other external providers return a clear error naming the checks instead of the misleading “no jobs found”. The auto-heal hook surfaces that message as a warn toast and does not consume an attempt (attempts increment only after a fix prompt is delivered).
Stale PR Filtering
When include_merged is true, get_repo_pr_statuses includes recently merged PRs. Stale merged PRs are filtered: if a branch has been recreated after a PR was merged (detected via branch creation timestamp vs PR merge timestamp), the old merged PR is excluded to prevent ghost badges.
Browser add-account polling uses POST /github/accounts/poll and the same github_poll_add_account_impl as desktop IPC. Success persists a named account without replacing the default runtime token. Default login continues to use POST /github/auth/poll.
Line review backend
The additive github_review_threads API reads paginated line threads with current/original line, diff side, resolved and outdated state, plus paginated replies. The existing get_pr_review_threads badge-count API is unchanged. Resolve/unresolve returns the confirmed GitHub thread; reply returns the posted comment. Draft submission checks the reviewed head against GitHub and posts through the existing review body builder/parser with commit_id pinned. A moved head returns review-head-changed; refresh before resubmitting. All calls resolve the repository account and use its host, token and circuit breaker.
PR action backend
github_pr_actions exposes auto-merge enable/disable, merge queue enqueue/dequeue/state and failed-job reruns. merge_or_enqueue_pr reads the PR’s isMergeQueueEnabled field and enqueues when the base branch has a merge queue; otherwise it merges with a pinned REST SHA. A missing or non-boolean queue-policy field stops the write. Queue entry and auto-merge enable mutations carry expectedHeadOid. Failed reruns use the Actions rerun-failed-jobs endpoint, which also reruns dependent jobs. The legacy review post and draft API both reject REQUEST_CHANGES with an empty body before account/network work. These additive commands require frontend consumers to opt in; the existing merge command is unchanged.
Shared account registry
Core owns provider sites and accounts in accounts.json. Tokens are stored only
in the instance credential vault under account/{id}. Reads return account
metadata and secret: {status: "set" | "unset" | "unavailable"}. Persisted registry, site and account records tolerate unknown fields from newer builds. Vault errors
are unavailable, never an absent credential. No account action reveals tokens.
account_action (IPC) and POST /accounts/action (HTTP) call the same Rust owner
service. IPC takes {request: <action>}; HTTP takes the action directly. HTTP
uses the loopback-or-authenticated route guard on both routers. TCP listeners
additionally require transport authentication, including loopback requests. The future Settings MCP adapter uses this service; this change
does not add an unrestricted plugin invoke grant or a standalone MCP tool.
| Action | Input | Reply |
|---|---|---|
list | Optional provider | AccountView array |
list_sites | Optional provider | Site array |
add | account: {provider, host, kind, label, username?}, token | Verified AccountView |
test | id | Verified AccountView |
remove | id | {removed:true}; rejects the durable github.com default |
add_site | provider, host, label | Site |
remove_site | Site id | {removed:true}; removes its accounts, credentials and GitHub bindings; rejects the default github.com site before any removal |
set_secret | id, token | Verified AccountView; token/basic accounts only |
clear_secret | id | {cleared:true}; retains account metadata |
set_label | id, label | {updated:true}; renames an account |
set_site_label | id, label | {updated:true}; renames a site |
AccountView fields: id, provider, site_id, host, kind, label, login,
username, created_at, auth_source, secret. Site fields: id, provider,
host, label. IDs are stable; new non-GitHub accounts receive UUIDs. Multiple
accounts may share one provider/site. Site URLs include their HTTP(S) origin and
optional context path; userinfo, query strings, fragments and traversal are
rejected. Verification uses a 30-second deadline, a 64 KiB response cap, no
redirects, and returns only a selected viewer identity. Error bodies are never
returned. Tests use a controlled protocol server, not live Jira/GitLab credentials.
Core registers GitHub and reuses its provider. Cloud login still requires device
flow; PAT input cannot bypass it. Non-core ProviderDescriptor registration is
restricted to bearer and basic token authentication. A descriptor declares
id, label, kinds, and verify: {path, login_pointer}. The trusted manifest
adapter calls accounts::register_provider(owner, descriptor); unload calls
unregister_providers(owner). Unload retains persisted accounts and credentials.
Verification of an unloaded provider returns unavailable; metadata remains readable.
Plugin manifest wiring and authenticated plugin HTTP requests are delivered by
the host-API stream, not this registry change.
Native secret-entry integration is separate. Its sink calls
accounts::add_account(NewAccount, token) directly. The core Settings control
must not collect or forward token values through plugin JavaScript. This change
provides the write-only service/input transport; it does not claim native
secret-entry privacy before that sink is integrated.
accounts::catalogue_schema() returns an inline Rust schema without reading
files, credentials or providers. The logical token leaf has secret sensitivity,
no default or examples, and get/set_secret/clear_secret operations. Get is
presence-only. Catalogue aggregate registration is a serial Settings integration
step after the accounts module lands; the module does not edit the shared catalogue.
GitHub migration and recovery
The first registry operation imports all github_accounts.json entries with
unchanged account IDs, hosts, login and auth provenance. The implicit
github.com record still resolves the existing env → OAuth vault chain;
env tokens are not copied into the vault. The legacy metadata file is retained
for recovery and is not re-imported after the migration marker is committed.
github_bindings.json stays authoritative, so existing repo bindings remain valid.
All GitHub registry writers now use the shared registry.
On vault load, github/oauth-token and github/account/{id}/token migrate to
account/{id} in one persisted blob. Existing canonical credentials win. Old
copies disappear only after persistence succeeds; a failed migration can retry.
GitHub credential enum variants address the same canonical slots, including OAuth
login/logout and per-account token resolution. OAuth replies and Debug output
omit access_token.
Metadata updates use the existing cross-process ConfigFile lock and atomic file
replacement. Corrupt account metadata is rejected and retained for operator
repair. Vault and metadata are separate stores: a vault change followed by a
metadata persistence failure may leave a credential phase committed. An operation
error is not a guarantee of cross-store rollback; inspect presence and retry the
owner action after repairing storage. Site removal can stop after removing some
accounts if a later credential/binding operation fails; retry the site action.
Rust changes load only after Boss manually restarts make dev or installs a
make build; this work does not launch or restart the app.
Private account token sink
Enterprise PAT entry in Settings launches account_secret_form with account
metadata only. The private native form sends its one-time nonce and token to
Rust; the account sink calls accounts::add_account or accounts::set_secret.
The token never enters Settings state or the general secret-command environment.
Provider validation precedes persistence. Decline or close before submission
writes no account or credential. After Submit is accepted, verification and storage
finish even if the window closes; a consumed nonce cannot be replayed. Rotation
invalidates the same GitHub Enterprise runtime cache as the account owner API.
Native inspection remains blocked until the private window is destroyed.
GitHub OAuth device flow requests repo project (repository access and Projects v2 read/write). The request builder and the Settings permission text read the same value from src/data/github-oauth-scopes.txt (Rust include_str! and Vite raw import). Existing account tokens retain their previous scopes until the user signs in again. GitHub Projects v2 permission failures retain the API error, including INSUFFICIENT_SCOPES; they are not empty boards. Settings offers re-login when a known OAuth scope list lacks project. The github-work provider reads x-oauth-scopes from account-scoped HTTP responses: a known list without project makes Projects fields read-only and removes legal board moves. The board retains its cards and shows writeDisabledReason. A mutation authorization denial is remembered only for that project until Tasks reloads. Repository PRs, issues, comments and monitoring are not disabled. Missing or empty scope headers do not imply denial for fine-grained or App tokens. GitHub’s Projects API authentication guide limits read:project to queries and requires project for mutations such as updateProjectV2ItemFieldValue.
GitHub settings owner adapter
settings/accounts.rs provides an internal typed GithubSettings read/perform
boundary. action_schema() derives its action DTO schema. Account creation,
credential replacement/clearing, labels and removal use accounts::execute;
Enterprise PAT creation keeps the owner’s /user identity verification. Cloud
PATs cannot replace default or named OAuth credentials. Removal also removes
bindings, per-account caches and cooldowns; corrupt bindings stop removal before
credentials or metadata are deleted.
Snapshots return credential presence (set, unset, or unavailable) and the
ambient runtime token source. Reads do not resolve ambient credentials or refresh
GitHub over the network. They do not invent a stored account for an external
credential source. GitHub display preferences remain in the existing preferences
and repository settings adapters.
Cloud login uses begin_cloud_login, cloud_login_status and
complete_cloud_login. Begin returns an opaque flowId, human verification URI
and user code. The backend retains the device credential, enforces expiry and
poll intervals, increases intervals on slow-down, and prevents duplicate exchanges.
Default and additional-account completion call their existing GitHub auth owners.
Token/provider error bodies and token scopes never enter adapter replies.
Binding actions require expectedRevision from the snapshot’s bindingsRevision.
The GitHub owner checks it under the cross-process binding file lock, accepts only
registered repositories, derives owner/repo from the chosen remote, and rejects a
remote whose host differs from the account. Successful mutations include immediate
owner readback; binding no-ops report persisted:false.
This step adds no MCP, HTTP or IPC endpoint. Transport publication and settings change events remain the shared cutover and refresh work. Real provider login and Enterprise identity checks need an authenticated manual verification after that wiring; the isolated adapter tests do not access production credentials.
Linked Tasks check failures reuse ci_failed PR transitions and the existing native notice service. A separate default-off Tasks UI preference selects a single task-labelled notice, independent of the default-on PR preference. No extra GitHub poller is introduced.
Account-scoped GitHub review and action ports
host.githubReviewThreads(account, reference, after) returns the core B6 review
thread page, including head SHA, bot authors and parsed findings.
host.githubPrAction(account, reference, request) calls core B7 policy.
Both require net:http and an on-disk manifest declaring providers: ["github"].
The reference must identify a GitHub pull request in the selected account. Core
loads that exact account credential, never a local repository default. Cross-account
references fail before credential lookup. No token is returned to the plugin.
Requests use action: state, auto_merge (enabled, optional mergeMethod,
expectedHeadSha), queue (enqueued, optional expectedHeadSha), merge
(mergeMethod, expectedHeadSha), rerun (runId), or review (draft with
headSha, body, event, comments). Existing core reviewed-head validation,
merge queue policy and shared request budgets apply unchanged. The desktop command
plugin_github_action and POST /api/plugins/{plugin_id}/github accept identical
{account, reference, request} payloads (IPC also supplies pluginId).
The GitHub Work runtime binds both ports when it registers each configured account.
No live write or desktop-load verification is implied by recorded-fixture tests.
Device-login invalidation (#1787-4778)
Logout and disconnect advance the GitHub login generation. Settings device flows retain their creation generation; an older flow expires instead of completing. Credential activation and logout share an async serialization lock, so a token response racing logout cannot restore credentials after logout completes.
Settings startup workflows
The Settings facade delegates device flow, Enterprise verification, account cleanup and registered-repository bindings to the GitHub owners. Startup workflows records poll/status semantics, binding revisions, write-only credentials and typed list_accounts discovery of account metadata/presence. An adapter-level owner snapshot alone does not prove the same information is reachable through the published Settings schema.
Persistent PR visibility filters
Global pr_hide_drafts, pr_hide_conflicting and pr_hide_ci_failing values
persist in config.json and default to false (show all). Each repository stores
nullable overrides in repo-settings.json: null inherits the current global
value, true hides the matching PRs, and false explicitly shows them. Settings
owner transactions preserve unrelated fields, and settings refresh adopts owner
readback without saving it again. The Rust settings catalogue describes both scopes.
Repository access diagnostics
The unified batch poll preserves errors[].path, type and the exact message
per repository alias, including nested-field errors. Only a root-level explicit
NOT_FOUND enters the account-scoped 24-hour exclusion. FORBIDDEN and unexplained
nulls remain eligible for the next normal poll, and a successful poll clears the
failure. A NOT_FOUND can mean a repository is not visible to the token; it does
not prove that the repository was deleted.
github_diagnostics (IPC and HTTP) retains repos_not_found and adds
repo_access_errors, grouped by account, host and owner. Each repository carries
repo, reason and message. Reasons are not_found, forbidden and
unknown; message wording does not infer organization policy or SSO.
Every github.com OAuth group offers the app’s authorized-app page, including
NOT_FOUND groups because GitHub can hide private repositories until org approval.
Settings renders these backend groups without reclassifying them. Refresh status clears the NOT_FOUND retry cache for all accounts through an
explicit mutation, then reads diagnostics. Opening Settings and ordinary GET
diagnostics remain read-only. Refresh does not log in, grant access, reset rate
limits or bypass the monitoring cadence; the next poll retries the repositories.
Partial-response regression evidence
BatchPoll does not select Projects fields. Routine PR and issue monitoring does not require Projects access. The generated-query regression checks this boundary for every issue filter and PR visibility combination.
fixtures/github-partial-monitoring-2336.json records a real GitHub GraphQL
response with an accessible repository and a NOT_FOUND sibling. The replay
passes through graphql_request and the same response-adoption function used by
poll_one_account, and checks both PR and issue output. The fixture records its
request, timestamp and source; it contains no headers or credentials. It is not
a recorded missing-scope or organization-policy response.
Machine-owned issue intake
The automation runtime retains every resolved allowlist entry and logs each missing or ambiguous registration separately. A bad entry does not clear valid intake paths.
The shared poller keeps intake and client issue delivery separate. For an intake path, the initial GraphQL request includes an intakeIssues: issues(...) selection filtered by the configured intake label and the normal client-filtered issues(...) selection. Intake requests 100 labelled open issues per page and follows pageInfo.endCursor until hasNextPage is false. Extra requests fetch only that repository’s remaining intake pages; there is no overall issue-count cap. An incomplete or invalid page fails the poll instead of publishing a partial snapshot. The server label predicate establishes eligibility even if the label is outside the first ten display labels returned on a node.
GitHub applies assigned, created and mentioned client predicates with the resolved account viewer. The client connection keeps its existing 30-node bound and never adopts the intake selection. Disabled client issues publish an empty client snapshot. Complete intake snapshots use an internal event consumed only by the automation runtime and excluded from SSE; desktop and SSE receive the same filtered client snapshot. The runtime retains the full eligible set for capacity retries, and the run store still deduplicates event keys.
Host-owned issue triage publication (#2324-424d)
When triage is configured, intake fetches every page of open issues without the
intake label filter. Each issue’s label connection is also paginated to completion,
including ordinary repositories in a mixed intake batch. Missing pages or invalid
cursors fail the poll rather than publish incomplete label membership. The normal
client issue filter remains separate. Issue nodes
include authorAssociation; only OWNER/MEMBER/COLLABORATOR can start triage or
implementation in an opted-in repository. The host publishes immutable decisions
through the existing account-bound REST adapter: POST issues/{number}/comments
for a rejection reason, then POST issues/{number}/labels for the rejection label;
acceptance posts only the intake label. The current policy, allowlist and resolved
workspace remote are checked again before publication. Requests have durable
at-most-once claims; a missing/ambiguous response is unknown, not permission to
repeat. No issue is automatically closed or merged. The evaluator’s read-only
profile is operator-attested, not credential-isolated by TUIC.
Auto-fix prompts sanitize issue titles, bodies, authors and comment bodies with the CI-log sanitizer before display or terminal submission. Terminal control sequences are removed; tabs and newlines remain. The dependency audit workflow requests plain cargo-audit output with --color never.
Neutral source trigger admission
Bindings select an exact neutral publication without a WorkflowKind restriction. GitHub repository prefixes save as github:<lowercase owner/repository>/, including the boundary slash; malformed or deeper prefixes are rejected.
Each has a stable id, source/kind, resource prefix, enabled revision, selected
events, typed input/subject mapping, optional value filters and ignored actors.
Several matching bindings each run independently. Changes save disabled;
activation requires valid mappings and acknowledgement of every current overlap
by id and revision. Overlap is conservative across intersecting resource prefixes
and events. Scalars compare by equality; an array field matches a required member.
TriggerSource and trigger_schema(source, kind) are a closed installed-source
match. The schema supplied with an event must equal that installed schema.
Graph/client JSON supplies neither a catalog nor replay authority. The 015 single
neutral action exposes schema, binding CRUD/activation, mapping preview and replay;
014 consumes these contracts for the Designer. The backend preview returns typed
workflow inputs/subject and overlap revisions. No separate trigger transport exists.
WorkflowStore owns binding/publication metadata. RuntimeOwner owns admission and starts through the existing neutral run ledger. RunStore retains normalized source state, immutable event/start intents, binding receipts and active/pending resource identities. Deduplication is binding + resource + source generation; delivery id and workflow revision do not mint another event. A crash between intent and run linking retries the exact retained request and publication. Explicit replay requires authenticated owner authority for the same project, uses the retained snapshot/start request and deduplicates its explicit replay id.
One execution per binding/resource remains active. A newer relevant generation
cancels the superseded graph frame, retains original effects for reconciliation,
and coalesces pending work to the latest snapshot. No replacement starts while
any dispatched owned effect lacks completion and stop evidence. The existing
actor/effect service remains the only executor; no trigger worker can replay an
uncertain operation. Service adapters still check current subject and grants:
GitHub review publication probes exact head/base and posts with commit_id;
lost-response recovery only looks up the original receipt.
GitHub uses the existing poller and account-aware PrApi/RepoApi client. Neutral subscriptions are independent of legacy subscriptions. The consumer re-reads full open-list payloads, including exact PR head/base SHAs. Individual GETs are limited to previously known open resources absent from the complete list. Failed individual reads warn without blocking later resources. Confirmed 404/410 or a transferred response with a different resource number retires that polling candidate; timeouts, 5xx, rate limits and other ambiguous errors preserve it for retry. Retained source generations remain intact. Complete open issue/PR discovery is bounded to ten pages of 100; excess or malformed data refuses admission. Known closed resources leave future poll candidates. A missing installed native catalog produces a diagnostic refusal. No public webhook endpoint is added.
Issue generations follow relevant title/body material, lifecycle and explicit label admission epochs. Comment counts and observed timestamps alone do not start work. PR generations follow lifecycle and exact head/base, not CI-only updates. Polls do not prove who caused an update; actor stays absent. Configured actor filters are optional. Self-event suppression requires the exact binding’s own label-write claim and exact normalized resource/generation; a shared bot account alone suppresses nothing. A native issue label write claims the next generation of its admitted issue before the POST; the poll that sees only the claimed labels added records the self event for that binding. Any other change in the same generation is not suppressed.
The documented fixtures and version notes live in
src-tauri/src/workflows/fixtures.
They are API-contract evidence, not live account validation. Story 018 separately
records authorized sandbox source/connector checks and their failures; a fixture
pass cannot substitute for that evidence. After integration a manual make dev
restart or make build is required to load Rust changes; no restart was performed.
Native provider installation and the Designer visual consumer retain their
respective owner evidence requirements.
GitHub enablement establishes an activation cut on the next complete source poll. Until that baseline completes, automatic and manual source admission is held. The existing RunStore retains each current resource/generation and its typed pinned start request with baseline disposition, without queuing an execution; only then is the binding’s enabled revision marked ready. Empty repositories also complete this cut. Each later new or re-enabled binding establishes its own cut. Resources created or changed before this first complete poll are baseline. Later relevant generations admit normally. Baseline intents remain available to the authenticated-owner replay path, including a resource whose present action is not among automatic event selectors. This does not grant automatic replay.
Unchanged source observations emit no new normalized event. The durable source outbox retains its current event for recovery if a crash separates normalization from admission. Binding receipts distinguish a captured baseline from later pending/started work; retrying baseline capture cannot enqueue historical work. The activation marker is persisted last, after all baseline intents, so an incomplete capture remains inactive across a restart.
An enabled neutral GitHub issue binding explicitly requests issue intake for its named repository, alongside existing legacy and native issue sources. No legacy source configuration is required for a neutral binding. Poll batches group by account and requested intake label, so an enabled binding cannot fetch intake issues from a sibling or unrelated repository. With no enabled binding or source setting, no issue intake subscription/fetch is created. Independent PR/sidebar requests continue to use their own existing polling paths.
Activation/listing may expose optional refusal_reason for a real source
configuration failure. An absent legacy source is not a refusal. This diagnostic
neither changes requested enablement nor writes intake configuration.
Scheduled neutral starts
A binding with source: "scheduled", kind: "schedule", resource
"schedule:<binding id>" and event ["due"] carries
schedule: {"cron":"0 9 * * *","timezone":"UTC","text":"Review the summary"}.
text (string) and occurrence_ms (integer) are its installed mapping schema.
The existing automation runtime supplies the same 30-second tick and timezone-aware
schedule parser; there is no additional timer or legacy Story/check dependency.
A wake considers the latest due cron occurrence, rather than replaying missed
intermediate occurrences. The enabled binding revision and UTC occurrence form
its generation, retained with the exact publication/start request in the ordinary
trigger ledger. Retries reuse the occurrence’s run. A different binding uses an
exact schedule resource match, never a neighboring id’s prefix.
Backend source admission captures Owner provenance and binds it before waking
an actor. Text/model, HTTP and local approval workflows can use a plain directory;
native repository operations still require the captured exact Git workspace.
model.request@1 accepts optional literal text, appended to its configured
request context and checked against the same byte bound. inbox.approval@1 takes
bounded nonempty text and optional details (shown below the text, cut at
8 KiB) and waits in the existing retained effect inbox. The
existing exact Answer action resolves it; an affirmative answer returns
approved: true. No Telegram account or separate approval transport is involved.
GitHub pull request review
The built-in github-pr-review template (templates action,
src-tauri/src/workflows/templates/github-pr-review.json) is built only from
catalog activities. Set the model profile, model and effort of both model
activities in the Designer, publish, then enable a pull_request binding for
the repository (events opened, reopened, updated) that maps repository,
number, head and base.
The graph is: github/pull_request.snapshot@1 captures the open PR at the exact
head/base and the base…head patch (outcome stale when the PR moved or closed);
a fork runs a review model and a verification model in parallel; a condition
checks passed; a failed verification asks the operator through
inbox.approval@1, with the verification summary as the question details; github/pull_request.review@1 publishes one review.
The review operation reads the PR again and returns stale without a write when
the head, base or state changed. It posts with commit_id set to the captured
head and reads the review back. The body carries a tuic-effect marker with the
effect digest; reconciliation looks up that marker and never posts again. A
complete review list without the marker is a definite failure. The project
path selects the account and repository through the existing PR client; a
workflow repository that differs from the project repository fails before any
request. The review asks no extra question: the graph decides when the operator
answers.
Overlap, deduplication and self-event filtering come from the ordinary trigger ledger above: a newer head supersedes the active run, a repeated poll of the same head is the same generation, and a published review changes neither head, base nor state, so it starts no run.
Typed workflow HTTP and installed connectors
Story 009-e32f supplies an internal NeutralHost adapter, now delegated by the
installed native provider. Public starts bind authenticated backend callers before dispatch.
It uses the existing plugin
HTTP client and neutral effect ledger, with no second scheduler or credential
store. It adds no IPC command or HTTP route.
ConnectorContract is shared metadata for installed HTTP, client and tool-backed
operations: credential reference, resource schema, cursor pagination, rate-limit
handling, callback correlation and reconciliation. HttpConnector::new includes
the entire binding in the descriptor’s connector schema default for installed
descriptors, or in a saved ReusableTarget::Http {connector,plugin,base}. The
existing reusable-operation store validates saved bindings through that same
constructor and preserves immutable versions; it adds no connector store. Bases
must be credential-free HTTP(S) URLs ending in /. Catalog pins
therefore retain the plugin identity, base URL and contract. An instance cannot override this metadata. The current backend supplies
separate connector network and write grants from the native caller’s current and
captured authority; serialized requirements grant nothing. External writes also
require an exact ledger approval through the installed native provider.
An instance config has a request object with method, endpoint, path,
query, headers, body, response and max_response_bytes. The endpoint is
a literal under the installed base, without user information, query or fragment.
GET, HEAD and OPTIONS are read-only; every other method is a write. Publication checks
known fields and current grants. Dispatch checks resolved inputs and grants again,
including immediately before client entry. Resource-schema values become effect
ownership keys; absent schemas serialize writes at connector scope.
Path segments, query values, safe headers and JSON bodies accept either
{"source":"literal","value":...} or
{"source":"input","field":"initial","max_bytes":256}. The shared bounded
value contract also fits data argv slots of an installed client; it provides no
executable selection or process launcher. Dynamic values cannot select methods,
destinations, credentials, header names, executables or write grants. Path segments
are encoded individually; dot traversal is refused. Header slots accept Accept,
Content-Type, conditional headers and X-* names. Header names are checked syntactically without credential-name heuristics. Credentials use only an installed typed
credential reference; the existing account client loads and redacts them and
checks their actual destination on requests and redirects.
response maps output names to JSON pointers. The ordinary descriptor schema
validates mapped values before completion. Empty successful response bodies map to JSON null before output mapping, supporting 204 and HEAD. Cursor pagination names the items and
next-cursor pointers, query parameter, array output and page/item bounds. Missing,
null or empty cursors terminate. Repeated or malformed cursors, exhausted bounds,
invalid JSON and wrong output types fail rather than return a truncated success.
The cumulative byte limit covers all pages. Only nonmutating operations paginate.
The resulting typed array carries activity-output provenance into 003-e678
ForEach expansion and retains source order.
No request is automatically retried. HTTP 429 retains a numeric Retry-After hint;
a mutating request stays uncertain. Other write failures also retain uncertainty. Failed reads (status, transport, parsing, bounds or output validation) complete as failed activities with stopped ownership.
HTTP 202 retains the original effect digest as the pending handle when callback
reconciliation is declared, otherwise it stays uncertain. An installed correlation
header carries that precommitted digest. Callback ingestion must use the existing
fenced EffectCommand::Observe with the original effect key. Recovery does not
issue a probe or replacement write; resources stay held without completion and
stop evidence. The adapter cannot infer remote stop from local cancellation.
Recorded contract and evidence limits
The targeted tests use the real installed HTTP client against a local HTTP/1.1
JSON contract responder. Its documented contract is synchronous 200 JSON results,
cursor pages {"items":[...],"next":"cursor"|null}, asynchronous 202, and 429
with numeric Retry-After. Tests record actual request bytes and inspect retained
effect/run outputs, rather than fabricate a successful client return.
This contract is not evidence about any external provider. No service endpoint or credentials were supplied for live external checks. Before installing a provider binding, its owner must record that service’s response, pagination, mutation, callback authentication and reconciliation semantics and verify the account destination. No live external write, app restart or public cutover was performed.
MCP & HTTP Server
Headless GitHub monitoring
Both routers mount one shared GitHub monitoring surface: poller start/stop, visibility, immediate poll, path updates, issue filter and API-debug controls; repository status (/repo/github), PR snapshots (/repo/prs, /repo/prs/batch) and issues (/repo/issues). The poller does not require an AppHandle. It publishes through the event bus and /events SSE without a window. TCP keeps the existing authentication and request-boundary middleware; the trusted Unix socket uses the local router. GitHub account/auth, mutation and AI routes stay outside this shared surface. A credential-free no-remote smoke proves transport and lifecycle, not authenticated GitHub fetching.
Planner Ideas use the same StoryAction envelope as plans and stories: add_idea {text,source?}, list_ideas, and update_idea {idea_id,text}. IPC story_action_command, HTTP POST /stories/action?path=<project> ({action:<StoryAction>,sessionId?:string}), CLI tuic story, and MCP workflow action=story input=<StoryAction> share the Rust owner. Add/update return {type:"idea",value:<camelCase Idea>}; list returns {type:"ideas",value:[...]}. The project sets repoPath; list also includes global Ideas, while update requires project ownership. Source defaults to the bound session id or local-api. Text is trimmed to a nonblank maximum of 16000 characters; source is nonblank with a maximum of 256. Writes use the strict locked notes.json owner and publish payload-free ideas-changed on desktop and /events SSE. UI save_notes(base,config) / PUT /config/notes applies per-id and per-field intent instead of replacing stale arrays. See Ideas through the planner.
Native plans have a stored revision. update_plan takes plan_id, expected_revision, and patch with optional title and source. At least one field is required. The shared service validates both fields and commits them with one revision increment in one transaction; stale revisions leave the plan unchanged. Existing records start at revision 1. A metadata change changes the workflow planning and verification fingerprints, including plans with no stories. Source prose stays in the external document; the update does not move or rewrite that file. Source-changing edits are refused with a user error while a plan coordinator/planner attempt is running, including an unbound attempt or a paused run. Finish the coordinator or cancel its run first. Title-only and unchanged-source edits remain allowed. The same action is available through MCP, HTTP, desktop IPC, and tuic story.
The compact ui description includes design_start, design_stop, design_status,
design_reload, design_navigate, design_screenshot, design_errors and
design_eval. ui action=help retains their full usage guidance together with
the panel, notification and confirmation guide. Design actions keep the existing
caller/repository checks, sidebar host consent and saved design_mode denials.
Scoped plugin settings
The plugin settings IPC command and POST /api/plugins/{id}/settings dispatch to the same scoped Rust owner. Catalogue descriptors contain no stored values; secrets read as set/unset. plugin-changed carries only plugin IDs over desktop and SSE after a durable commit, scheduling existing reload callbacks. This adapter does not publish the general settings MCP tool.
Slice F exposes start_graph {target:{type:story|plan,id},expected_revision?,definition_id,definition_revision,request_id,limits?,secrets?} through the existing owning-daemon service. secrets is a map of environment names to values for the agent children of this run only (PTY spawn environment and ACP connection environment). The values stay in daemon memory: run state, events, receipts, prompts, the launch journal and logs hold the sorted names only (secret_names on the run snapshot). TUIC_SESSION and TUIC_PARENT are refused. Completion, cancellation and a daemon restart drop the binding; a later agent launch of a run whose binding is gone fails before spawn and pauses the run. Story starts require the current native revision and pin the selected publication; the request ID is bound to its payload. Omitted limits use Rust defaults. Plan dispatch remains unavailable in this build and its start control says so. The workflow action=run MCP entry validates against a private schema generated from RunAction and the public RunCommand variants; it returns the same scoped snapshots and cursor-ordered events as IPC/HTTP. Run history shows pinned activations, decisions/evidence, repair counters, pause targets and complete event payloads across pages. Graph recovery uses resume_graph {execution_id,activation_id,resolution} after answering pending input; pause and cancel use the existing sequence-fenced commands. Legacy runs offer inspection and cancellation in the UI. No new persistence or client scheduler is added.
Explicit repository registration
repo action=add requires an absolute local directory path. It resolves the
canonical path, reads real repository metadata, and persists and activates a Git
or shell workspace under the repositories file lock. Repeat calls preserve the
existing repository and terminal state. The backend broadcasts
repositories-changed to desktop and SSE consumers after a change, then starts
the repository watcher. A watcher failure returns a warning alongside successful
registration; invalid paths and persistence failures return an error.
The CLI’s directory opener calls this same MCP operation over its selected local
IPC endpoint, including named instances and TUIC_SOCKET. No OS deep-link handler
or active frontend is required. ui tab accepts the native tuic://open and
tuic://edit content schemes; other tuic:// actions return an error. Use
repo action=add for tuic://open-repo intent.
Browser shell authentication
Unauthenticated HTML navigation to / and /mobile redirects to the existing /mobile/login form when a password is configured. The login handler permits root or mobile app destinations only. API authentication and non-HTML 401 responses are unchanged. The desktop entry checks touch-capable iPad/Mac user agents and selects /mobile before mounting the desktop app; native WebViews and standalone secret forms keep their own entry.
Remote file copies
The shared filesystem router exposes streamed /fs/upload-copy on the daemon through existing authentication. Sender-side fs_transfer_remote_paths coordination is desktop IPC only and intentionally unmapped: data leaves the machine, Finder source paths cannot be gated to registered roots, and HTTP token holders must not trigger exfiltration. There is no /fs/transfer-remote HTTP route. The receiver resolves registered repository roots through cap-std directory handles, validates archive paths, rejects links, bounds bytes/entries/concurrency, and publishes the staged top-level source with an atomic no-replace rename. Uploads use the existing session-cookie header, a 30-second chunk idle deadline (exempt from the global response deadline), and hold their concurrency permit through blocking extraction. Daemon startup sweeps abandoned upload staging inside registered roots without following symlink directories. Cleanup restores owner directory access only inside disposable staging when restrictive tar modes would prevent removal; published permissions remain unchanged. This path uses neither SSH nor shell commands. See the filesystem HTTP API for the wire contract.
Open desktop Markdown tabs
GET /repo/open-markdown-tabs?cwd=<session-directory> returns file-tab metadata
for the deepest registered repository or workspace containing the directory.
It uses the existing remote authentication middleware and returns 403 for an
unregistered directory. No file contents are returned.
The desktop publishes through sync_open_markdown_tabs; its HTTP twin is
PUT /config/open-markdown-tabs, restricted to loopback. Rust stores a temporary
snapshot and emits open-markdown-tabs-changed on desktop IPC and SSE whenever
it changes. Mobile clients refetch after invalidation or reconnect. Saved pane
layouts contain only tab IDs/types and cannot supply these file paths.
CI logs
Use HTTP GET /repo/ci-failure-logs with repoPath and branch to fetch logs
for the local branch head. For a remote-only PR or a particular CircleCI check,
use the same route with checkUrl and headSha, or the
fetch_ci_failure_logs Tauri command with check_url and head_sha. Both
verify the selected check against that PR head.
Native stories
Native stories expose qa for work that waits on manual checks. A criterion starts with [MANUAL], or is marked through set_criterion_manual {index,manual}. Active work automatically enters QA when all unchecked criteria are manual; submit_qa explicitly requests that state. reject_qa returns QA to In progress; approve requires every criterion checked. QA keeps plans Active and dependencies blocked. All transitions retain expected-revision checks. See the native stories guide.
Reversible native record archival
All native story transports share archive_story, unarchive_story, archive_plan, and unarchive_plan. Story actions take story_id; plan actions take plan_id. Each requires expected_revision and returns the updated record with its incremented revision and archived flag. Stale revisions fail without a write. Archival preserves status, criteria, dependencies, and child archive flags; it never deletes records or cascades to children.
list_plans and list_stories default to archived: false. Set archived: true to select archived records. The story filter combines with the other filters and is bound into pagination cursors. filtered_plan_view also accepts camel-case filter.archived (default false), which selects archived list ids and board columns without changing the active-plan state calculation. Direct reads remain available. Default plan views and workflow dispatch omit archived stories; archived plans and stories cannot start manual or workflow work. Restore the parent plan before starting its stories.
Both archive and restore refuse claimed stories and plans that contain a claimed story. Story archival also refuses any prerequisite that is not Done while an open dependent references it, including inside an archived plan. The refusal lists the dependent IDs and leaves the record and history unchanged. WontFix does not satisfy dependencies. Done prerequisites and unresolved stories with only closed dependents remain archivable. Adding a dependency to an archived unresolved story requires restoring it first; both dependency editors enforce this rule. Whole-plan archival does not change dependency readiness. An active or paused plan-root workflow owns the plan’s story set. A story-root workflow owns its target and execution stories, not unrelated siblings. Cleanup of an owned story or its parent plan is refused until the run ends. The workflow writer lock remains held through the archive transaction, so a concurrent run cannot start between the ownership check and the write.
story_archive_history (story_id) and plan_archive_history (plan_id) return {type:"archive_history",value:[{revision,archived,actor}]} in revision order. Events commit atomically with the record and retain caller provenance. Existing status transition history remains separate. Consecutive archive-only revisions preserve accepted-work integration receipts; a work change or a moved canonical Git ref still invalidates them. Example: tuic story '{"action":"archive_story","story_id":"<id>","expected_revision":1}' --project /absolute/project.
The native story MCP tool takes one StoryAction as its arguments, for example { action: "list_plans" }; there is no input envelope. It resolves the owning project and live PTY from the bound MCP caller; caller-supplied project and session IDs are ignored. The shared Rust story service enforces revision and project checks. list_plan_sources discovers Markdown plans in the project’s plans/ and .claude/plans/ roots; add_plan_source derives a title from the selected document and reuses an existing record for that source. The dialog calls the same actions, so agents and users see one discovery result. Any trusted caller may remove a direct WontFix prerequisite from a Backlog story with its current revision. The plan_view action returns Rust-derived story abandonment and cancellation summary without storing those projections. The HTTP route /stories/action and desktop command story_action_command use the same service. tuic story '<JSON action>' [--project PATH] [--session-id PTY] provides a local CLI path. The first native slice does not include story import/export.
add_plan_source reuses an active plan with the same source. If only an archived plan matches, it returns an error that identifies the plan and gives explicit restore instructions; it does not create another record or change archive state.
A missing native story ID shaped like a Wiz ID (decimal number, hyphen, four hexadecimal digits) reports that Wiz stories live in stories/*.md. Other missing IDs keep the native not-found error.
GET /stories/capabilities mirrors the desktop story_capabilities probe. It returns the static story capability descriptor ({"backend":"native","operations":{...}}, one boolean per operation) without opening the story database; the dialog uses it to distinguish an outdated backend from an action error.
HTTP’s access marker does not prove human identity, because loopback requests also receive it; an HTTP action without sessionId records local_api provenance, including for approval. A managed session that claimed a story cannot approve that story; an independent reviewer session can approve after checking its criteria. Desktop and browser clients can approve through the shared story service.
The workflow MCP tool exposes definition, run, proposal_create, report and launch. Use the separate story tool for stories, plans and Ideas. The workflow advertisement lists actions and a generic input object to fit the 16,384-byte discovery budget. The server retains the full generated typed schema privately and validates it before dispatch; invalid calls return field violations. workflow action=help returns type notes. Capability filtering removes denied actions before advertisement. The dispatcher retains the existing project, revision, ownership and local-launch checks.
The catalogue cutover removes the old workflow_* tool names without aliases. Saved member denials migrate to action capabilities and still hide and deny those grouped actions. Disabling workflow hides and denies the grouped entry, not the separate story tool or the automations scheduler. External policy rules need review: the workflow name covers all five actions.
The story split (#2804-6bd7) is a second breaking cutover with no alias: workflow action=story is refused before effects with code=invalid_arguments. Call story action=<StoryAction tag> with the former input fields at the top level. The story capability gates the tool; a saved workflow.story denial migrates to story at config load, so no saved denial widens. A saved denial of the whole workflow domain no longer covers stories: deny story as well if that was the intent.
workflow action=launch takes {input:{runId,attemptId,worktreePath,agentType,skills?,feedback?}} from a bound local managed PTY. The worktree must be a registered branch checkout of the project, outside the archive pool, and cannot be the main checkout or have a Git operation in progress. Launch validation is separate from detached-orphan removal, which still refuses attached branch checkouts. Plan attempts use the caller’s isolated worktree; story attempts require that run’s active coordinator and bind a distinct registered worktree to the story before worker spawn. It renders the pinned prompt in Rust, reserves the spawn effect, launches through the existing managed-agent path, and binds the returned session and task handle to the durable attempt. A story worker requires the caller to own the run’s active coordinator attempt. workflow action=report takes {input:AttemptReport} with contractVersion, runId, storyId, storyRevision, attemptId, generation, outcome, summary, criterionResults, and evidence. The server derives the reporting PTY and project from the MCP connection, validates attempt ownership and revision, and records an idempotent run event. Plan-agent reports use storyId=planId, storyRevision=0, and no criterion results. Generic agent send and process exit are observations, never semantic completion reports.
For workflow action=report, a needs_input outcome requires inputRequest {question,options}. A completed reviewer report requires review {decision,artifactDigest,findings} with criterion-indexed findings. These fields are durable evidence; they do not promote a story to Done. After a committed story report, the active coordinator’s inbox receives a workflow_event cursor with runId, storyId and sequence; the coordinator replays the run log rather than treating mail as an outcome.
workflow action=proposal_create takes {input:{runId,proposalKey,story}} from the active bound plan coordinator. The story belongs to the run’s plan and uses a plan_step origin. A proposal key is durable across retries: the same payload returns the same story, while a changed payload is rejected. The run records a bounded CreateStory effect before the story transaction and its outcome afterward.
list_stories shares optional top-level state, priority, story_type, limit (1–100), and cursor across all transports. Without a limit it returns every matching story; limited responses retain the value array and add next_cursor only when more matches remain. Cursors require a limit and the same plan/filters. See the HTTP API for bounds and live-read semantics.
project_story_view takes archived_plans (default false) and a camel-case filter with the same fields and defaults as filtered_plan_view. It returns {type:"project_story_view",value:{stories,visibleStoryIds,columns}} across every plan in the envelope project and selected plan archive scope. archived_plans:true selects archived plans only; filter.archived:true independently selects archived stories. Full records remain available for detail and dependency reads; only display ids and columns are filtered. The reply has no combined plan state. The shared StoryAction service exposes this action through IPC, HTTP, MCP and CLI.
filtered_plan_view uses the same service on IPC, HTTP, MCP, and CLI. It takes plan_id and filter (camel-case visibility, storyType, untypedOnly), and returns the full plan with filtered list ids and per-status board ids. Optional storyType on create input and persisted stories is feature, fix, refactor, chore, or task; omitted types stay untyped. See the HTTP API for defaults and combined-filter rules.
update_story takes story_id, expected_revision, and a camel-case patch. Omitted fields stay unchanged. The patch accepts title, priority (1–3), fileScope, origin (including a plan step), nullable storyType (feature, fix, refactor, chore, task), optional problem and risk (low, medium, high), ordered criteria, and the final dependencies set. Null clears storyType, problem or risk; old story records default both to absent. Unknown fields, invalid values, cross-plan dependencies, duplicates, cycles and stale revisions are rejected without partial story writes. Only unclaimed Backlog/Ready stories without active or paused workflow ownership can be amended. Unique byte-identical criteria retain their checks after reorder; changed, new or ambiguous duplicate criteria become unchecked. A priority-only patch preserves all checks. Dependency changes recompute readiness. Planning and execution fingerprints include the amended requirements/revision, so existing evidence cannot certify changed work.
Project Progress reporting
The compact progress native tool is available directly in classic and
every collapsed discovery (Grok, ego), and through the meta-tool index, unless disabled by
mcp_capabilities.denied or by the global progress_tracking flag. It takes
{ type, text, step? } with type restricted to done or blocked, derives
the project and the reporting agent from the caller, appends to the shared
journal, and then dual-emits progress-recorded. A per-agent
progress_tracking: false answers progress_tracking_disabled instead of
hiding the tool — the tool index is global and has no session context.
Managed children (a bound peer with a session_parent entry) cannot report
through progress. The handler refuses the call before journal writes, user
notifications, or waiting-state changes, and returns agent action=send guidance
with the actual parent id. Both direct and collapsed calls use this handler.
MCP instructions and native launch guidance tell children to mail their parent;
root and unbound callers keep the existing reporting behavior. Refusal is explicit
rather than automatic mail forwarding, so progress does not become a second
mail API.
The journal’s third kind, intent, is written by TUIC from the agent’s
intent: marker in pty.rs. An agent that reports one is refused: the point of
the kind is that it is observed rather than claimed.
The repo tool exposes exactly one progress action, progress_list. Reading
back is occasionally useful to an agent; pausing, clearing, correcting and
exporting are the reader’s business and cost instruction budget in every
initialize.
repo action=progress_list takes path and optional input with blockedOnly,
ptyId, limit and cursor. The default page has 8 entries; limit is
clamped to 1–100. Entries are newest first. The response includes total
(matching entries before the cursor) and nextCursor (null on the final
page). Pass nextCursor as the next request’s cursor to read the entire
journal without overlap. Filters apply before paging. Desktop progress_list
and HTTP POST /progress/list?path=… use the same input and response.
Module: src-tauri/src/mcp_http/mod.rs
Optional HTTP/WebSocket server that exposes all Tauri commands as REST endpoints. Enables browser-mode operation and MCP (Model Context Protocol) integration for external AI tools.
Installed bridge lifetime
The primary instance installs the adjacent tuic-bridge into
<config_dir>/mcp-bridge/<sha256>/tuic-bridge (.exe on Windows) before updating
agent MCP configs, only when an eligible integration needs repair. Publication
uses a temporary file in the destination directory and atomic rename, with
executable permissions set before publication. The source is hashed before copying;
both the copy and a second source read must match before publication. Identical
bytes reuse the existing file. Different builds get separate revision directories;
old revisions remain available to running agents and saved config commands.
Cargo target cleanup, mbx view refreshes and app upgrades therefore cannot remove
the configured executable. Failed installation leaves agent configs unchanged.
Publication and app startup exec-probe every installed bridge revision, the
tuic CLI and the tuic-bridge, tuic and tuic-remote beside the running
executable. macOS kills a new exec whose cached code-signature check failed
(SIGKILL, “Code Signature Invalid”) after an outside tool, such as a
compressing backup app, rewrote the file’s metadata; running processes survive,
so only the next MCP session fails. A probe that ends by signal or exit 137 makes
TUIC replace the file with a byte-identical copy on a new inode and log one
warning (source = "exec_probe"). A healthy file is never rewritten.
Startup migrates TUIC bridge commands from cargo/mbx targets and its installed
revision directory, while preserving custom working commands and transports.
Claude migration covers ~/.claude.json, an existing
~/.claude-private/.claude.json, inherited CLAUDE_CONFIG_DIR, and the Claude
agent’s environment flags and saved run-config environment roots. Override roots
use <CLAUDE_CONFIG_DIR>/.claude.json; canonical paths are deduplicated. Relative
overrides cannot be resolved before a launch working directory is known and emit
a warning. Disabled integrations and custom transports remain unchanged. A missing
or non-executable configured absolute bridge command emits a warning naming the
config and command even when no adjacent bridge is available to repair it.
Secondary-instance ownership rules still apply. An explicit Settings > Agents
Install can install under user authority. Manual setup snippets only inspect
installed copies and never create them; without a copy they report the bare
tuic-bridge command. Revision cleanup is deferred until every agent config root,
including profiles used only by external shell launchers, can be discovered.
Activation
The server has two independent listeners:
- IPC listener (always started): On macOS/Linux, listens at
<config_dir>/mcp.sockfor the default instance. Named instances use a deterministic short socket name in the OS temp directory because macOS limits Unix socket paths to 104 bytes. On Windows, listens on\\.\pipe\tuicommander-mcp(named pipe); a named instance appends-<instance id>. No authentication — used by the localtuic-bridgesidecar. - TCP listener (opt-in): Only starts when remote access is enabled. Binds to
0.0.0.0:<port>(port fromservices.server) with Basic Auth.
The shared tuic-ipc crate owns AppInstance, endpoint naming and HTTP
framing. Informational responses (1xx except 101) are skipped until the final
response arrives. More than 32 interim replies per response, or a status/header
section above 64 KiB including its terminator, returns an invalid-data error.
These limits persist across reads; response bodies are not subject to the header
limit. Status 101, 204 and 304 responses finish at the header
terminator regardless of Content-Length or Transfer-Encoding (RFC 9112 §6.3).
The clients do not issue HEAD requests.
The server reuses its short named socket path; CLI and bridge select it
with --instance <id> or TUIC_APP_INSTANCE. An explicit Unix TUIC_SOCKET
wins. Bridge fallback discovery stays within the selected instance’s socket
prefix, so an unavailable named instance cannot fall through to the default
instance. Sync CLI and async bridge adapters retain their separate I/O and timeout
policies. Both finish length-delimited responses without waiting for EOF and
decode chunked bodies before converting UTF-8.
The mcp_server_enabled config flag controls whether the /mcp protocol route is active (MCP tool discovery and invocation), not whether the server itself starts. The HTTP API endpoints (sessions, git, config, etc.) are always available on the IPC listener.
The daemon’s POST /remote/update handler requires the current session token
in a tui-session cookie. Basic Auth alone does not authorize executable
replacement. /fs/upload-copy also authenticates by cookie (or Basic Auth)
through the shared middleware. A ?token= query is ignored on both routes, so
a query-only request answers 401. QR pairing and WebSocket/SSE query
authentication are unchanged.
Release boundary (step 2 of the two-release upload-token migration): the release
before this one accepts cookie or query on these routes (step 1); this release
removes the query form and sends the cookie from the update client. Clients of
the earlier release that still send ?token= get 401 and must be updated.
The local IPC listener is independent from the Remote Access TCP toggle. Turning remote access on or off only starts or stops the authenticated TCP listener; it does not disable the MCP socket or the local MCP route. Lifecycle logs state whether a transition affects TCP or the always-on IPC listener.
For isolated desktop verification, TUIC_PORT=<port> overrides the configured TCP
port for the process without persisting the value. The normal startup retry still
tries the next two ports when the selected port is occupied.
Configuration via Settings > MCP and Settings > Remote Access, or config.json:
{
"mcp_server_enabled": true,
"mcp_port": 3845
}
On startup, the server:
- Binds the IPC listener: Unix socket at the instance-specific path described above (macOS/Linux) or named pipe
\\.\pipe\tuicommander-mcp(Windows;-<instance id>is appended for a named instance) - If remote access is enabled, binds a TCP listener on the configured port
- Starts Axum HTTP server on a background tokio thread
- Enables CORS for browser mode
- Spawns MCP session reaper (evicts stale sessions after 1h TTL; see Identity outlives its transport)
- Spawns upstream health checker for proxied MCP servers
Unix Socket Lifecycle (macOS/Linux)
The Unix socket is managed with two safety layers to survive crashes and rapid restarts:
| Layer | Mechanism | Purpose |
|---|---|---|
| Retry bind | 3 attempts × 100 ms, each removes stale file before trying | A crashed previous run leaves a dead socket file that blocks bind(2) — retrying clears it |
| Real liveness check | UnixStream::connect() in get_mcp_status | file.exists() returns true for stale sockets; only a real connect reveals whether the server is alive |
Why this matters for AI tool integrations: The tuic-bridge sidecar connects via the Unix socket to expose TUICommander tools to Claude Code. If the socket is stale (app crashed, Tauri force-quit), the bridge cannot connect and returns tools: [], silently disabling all MCP tools in the agent session. The retry bind ensures the socket is always valid on restart; the real liveness check ensures the UI accurately reports the server state.
Server Limits
Both build_router and build_remote_router pass their assembled routes through
with_server_limits (mcp_http/mod.rs), which applies two bounds:
| Limit | Value | Response | Why |
|---|---|---|---|
| Response timeout middleware | REQUEST_TIMEOUT = 301 s | 408 Request Timeout | A wedged handler otherwise holds its connection forever. 301 s includes warming a linked worktree with large ignored build artifacts and remains far below “never” |
DefaultBodyLimit | MAX_BODY_BYTES = 2 MB, with route-scoped exceptions: ACP prompt, voice import, and the editor saves /fs/write and /fs/write-external (2 × 250 MiB + 64 KiB, JSON escaping can double the text) | 413 Payload Too Large | Bounds buffered JSON request bodies |
301 s, not 300 s — the layer must outlast every deadline it wraps.
ui action=confirm’s own answer window (CONFIRM_TIMEOUT, mcp_transport.rs)
used to be 300 s too, an exact tie this outer TimeoutLayer could win: it drops
the handler’s future on expiry, so a win here meant a bare 408 instead of the
handler’s own {confirmed:false, reason:"no answer within 300s"} body, and the
dropped future skipped the handler’s own cleanup — confirm_responses leaked
the entry and no McpConfirmResolved event told any client to drop the dialog
(#760-c29f). REQUEST_TIMEOUT is now a deliberate 1 s above CONFIRM_TIMEOUT,
which stays itself 4 s under the local bridge’s 305 s wait for a confirm or a
long workspace op (see below) — three layers, each strictly larger than the
one it wraps, pinned by
mcp_transport::tests::request_timeout_beats_every_in_handler_deadline and
server_limits’s confirm_left_unanswered_resolves_clean_through_the_real_server_stack.
The timeout does not apply to streaming. tower_http’s ResponseFuture races
its sleep only against the future that produces the Response; once headers are
returned the timeout is dropped and the body streams unwatched. Sse and
WebSocketUpgrade both return immediately, so neither /events nor a PTY socket
can be cut off mid-stream. server_limits_do_not_cut_off_a_long_lived_stream
pins this — if anyone swaps in a layer that wraps the response body, it fails.
MAX_BODY_BYTES is deliberately equal to axum’s own DefaultBodyLimit default,
so stating it explicitly changes no behaviour. The value is that the bound is now
asserted: a DefaultBodyLimit::disable() added outside this layer, or an axum
release that drifts its default upward, fails a test instead of silently
uncapping the server.
REST API Endpoints
Session Management
HTTP and MCP agent readers resolve their inherited TUIC_SESSION from the live
PTY identity binding when no explicit reader identity is supplied. Generic HTTP
shell readers use the same boundary. This lets native Codex hooks bind their exact
Chat transcript without relaxing foreign-owner, live-PID, rollout-id or cwd checks.
HTTP/IPC and MCP session lists copy PTY metadata and release the PTY mutex and
map guard before validating native bindings. Validation probes the live PTY again;
keeping the row lock during that probe would deadlock a bound Codex terminal.
| Method | Path | Description |
|---|---|---|
GET | /sessions | List active PTY sessions |
POST | /sessions | Create new PTY session |
POST | /sessions/:id/write | Write data to session |
POST | /sessions/:id/resize | Resize session terminal |
GET | /sessions/:id/output | Read session output (ring buffer) |
GET | /sessions/:id/shell-family | Shell classification (posix/windows-native/unknown, or null) so the client picks the right control sequences |
POST | /sessions/:id/pause | Pause session output |
POST | /sessions/:id/resume | Resume session output |
DELETE | /sessions/:id | Close session |
Design Mode
The extension launcher publishes its command queue before starting the dedicated browser, then awaits a request-id-matched ready reply identifying the launched tab. It retains an owned process controller after acknowledgment; Stop kills and reaps only that child. A failed startup closes its own launch. Native disconnect closes the queue and wakes both agent waiters and the outstanding extension poll. The worker replies before optional action-history persistence and exposes receive-loop errors in its connection status. MCP Design Mode command reads have a 15 s transport budget around the 10 s browser deadline; acknowledged start has 30 s.
| Method | Path | Description |
|---|---|---|
POST | /design-mode/start | Start/rebind the dedicated Edge/Chrome profile ({sessionId, browser?}) |
POST | /design-mode/stop | Stop inspection for a repository ({repoPath}) |
POST | /design-mode/reload | Ask the armed browser to reload the reviewed tab once ({repoPath}) |
POST | /design-mode/navigate | Ask the armed browser to open a localhost URL in the reviewed tab once ({repoPath, url}) |
GET | /design-mode | Read the array of per-repository Design Mode statuses |
POST | /design-mode/extension | Versioned native-host pick, send, discovery and configured server-start operations |
The chosen browser opens on the host running TUICommander, including when a
remote browser initiates the request. design-mode-changed is dual-emitted to
the desktop window and /events SSE with {repo_path, session_id, status};
status is armed or stopped. See the HTTP API
for the request bodies and the user guide for
the workflow.
Monitoring
| Method | Path | Description |
|---|---|---|
GET | /health | Health check, including running build version, target and SHA-256 |
GET | /stats | Orchestrator stats (active/max/available) |
GET | /metrics | Session metrics (spawned, failed, bytes) |
GET | /process/stats | CPU% and RSS memory for TUIC and all child process trees |
GET | /process/monitor | Self-contained HTML dashboard for process metrics (for remote/PWA/mobile) |
The /agents/map routes and their HTML page were removed on 2026-09-23. The
Progress Flow view (POST /progress/flow, POST /progress/flow/detail)
replaced them and reuses how they read subagents:
Subagents are read from their own transcripts. Claude records an Agent
spawn in the parent transcript but writes the subagent’s turns to
<config>/projects/<cwd-slug>/<uuid>/subagents/agent-<id>.jsonl — measured over
582 real transcripts: 833 spawns and zero isSidechain:true rows in any parent
file. The parent transcript supplies the Agent call’s timestamp and prompt; a
subagent whose join fails still renders from its own file, with its own first
message standing in for the prompt. The teammate join compares the prompt with
the decoded first message, because the raw JSON line escapes every newline.
The report is the subagent’s last reply; tool results are never kept.
/progress/flow/detail takes a PTY id looked up in AppState and an agent id
compared against the subagents listed on disk — never a path. Every path
component comes from the session’s cwd, the agent process’s
CLAUDE_CONFIG_DIR and the session uuid Claude published. Only sessions TUIC
has identified as claude are read: Claude discovery falls back to “newest
unclaimed session file under the project dir”, so asking it about a shell tab
would hand that session another tab’s transcript (issue #119).
Both files are read through per-path byte cursors held in
AppState.subagent_map_cache, so a refresh parses only what was appended — the
biggest parent transcript on the development machine is 31 MB. Tool activity
is a count (at most 32 distinct names per subagent, the rest counted as
other).
Git Operations
| Method | Path | Description |
|---|---|---|
GET | /repo/info?path= | Get repository info |
GET | /repo/diff?path=&scope= | Get git diff (optional scope) |
GET | /repo/diff-stats?path=&scope= | Get diff stats (optional scope) |
GET | /repo/files?path=&scope= | List changed files (optional scope) |
GET | /repo/branches?path= | List git branches |
GET | /repo/github-status?path= | Get GitHub status |
GET | /repo/pr-statuses?path= | Get batch PR statuses |
GET | /repo/ci-checks?path= | Get CI check details |
POST | /repo/create-pr | Create a PR (gh wrapper, UI-gated) |
POST | /repo/create-issue | Create an issue (gh wrapper, UI-gated) |
POST | /repo/post-pr-review | Post a PR review with inline comments |
GET | /repo/merged-prs?path=&sinceTag= | Merged PRs via GraphQL |
POST | /repo/conflict-assist | Worktree + rebase; reports verified/unverified clean or conflicts, base source, warning, and agent prompt |
Configuration
| Method | Path | Description |
|---|---|---|
GET | /config | Get app config |
PUT | /config | Save app config |
POST | /auth/hash-password | Hash password for remote access |
GET /config redact remote-access secrets:
services.auth.password_hash, services.auth.session_token,
services.relay.token, and services.push.vapid_private_key. The config shape
exposes only the corresponding *_exists booleans for secret presence.
PUT /config require { base, config }, where
base is the caller’s loaded snapshot and config is its edited document.
The backend applies only the base-to-config changes to the latest locked file;
unchanged fields keep concurrent edits. Both also share server_settings_changed with
the IPC save_config and rebind the listener through
restart_after_server_settings_change, so no transport can leave the process
serving a configuration the disk disagrees with. See
config.md for the merge semantics.
Agents
| Method | Path | Description |
|---|---|---|
GET | /agents/detect | Detect installed agents and IDEs |
POST | /agents/detect-all | Batch-detect the named binaries in parallel, path only (no version lookup) |
POST | /agents/open-in-app | Open a path in an IDE, terminal or file manager (optional line/col) |
Plugins
| Method | Path | Description |
|---|---|---|
GET | /plugins/docs | Plugin development guide (AI-optimized reference) |
GET | /api/plugins/:plugin_id/data/*path | Read plugin data file (JSON or plain text) |
POST | /api/plugins/output-watchers | Replace the OutputWatcher set of one frontend (client_id + seq + patterns) — what the PTY reader matches lines against. Returns {applied, rejected}; a rejected id keeps matching in the WebView. Not :plugin_id-scoped — one frontend owns one set for all its plugins |
Worktrees
| Method | Path | Description |
|---|---|---|
POST | /worktrees | Create worktree |
DELETE | /worktrees | Remove worktree |
GET | /worktrees/paths?path= | Get linked-worktree paths for a repo, keyed by workspace id and carrying kind |
GET | /worktrees/lifecycle?repoPath=&workspaceId= | Fresh dirty/commit/removal-safety verdict for one exact workspace; unknown fails closed |
POST | /worktrees/run-script | Run a setup script in a directory; returns exit code and captured output |
Dictation and Desktop Integration
Desktop-only — audio capture, the whisper model, the relay client and the updater
are all gated on the desktop feature, so build_remote_router serves none of
these. Handlers live in mcp_http/dictation_routes.rs and
mcp_http/system_routes.rs; each answers exactly what its Tauri twin resolves to,
so src/stores/dictation.ts and src/notifications.ts work unchanged on both
transports. Full request/response shapes: docs/api/http-api.md.
| Method | Path | Description |
|---|---|---|
GET | /dictation/status | Model + recording status |
GET | /dictation/models | Whisper models with download state |
POST | /dictation/models/download | Download a whisper model |
POST | /dictation/models/delete | Delete a downloaded model |
GET | /dictation/speech/assets | Speech languages and the ONNX runtime, with install state |
POST | /dictation/speech/assets/download | Download and verify an asset from the pinned catalogue |
POST | /dictation/speech/assets/cancel | Abandon a download in flight |
POST | /dictation/speech/assets/delete | Unload the engine and remove the files |
POST | /dictation/start | Start recording |
POST | /dictation/stop | Stop recording and transcribe |
GET/PUT | /dictation/corrections | Read/replace the text-correction map |
GET | /dictation/devices | List audio input devices |
POST | /dictation/inject | Apply corrections and inject text into the active terminal |
GET/PUT | /dictation/config | Read/save the dictation config |
GET | /system/relay-status | Cloud relay connection status |
POST | /system/notification-sound | Play a notification sound on a chosen output device |
GET | /system/check-update?channel= | Check a beta/nightly channel for updates (hardcoded URLs) |
ACP (ego)
Shared routes, not desktop-only: driving ego from a phone is the point of the
client. Full request/response shapes in docs/api/http-api.md.
| Method | Path | Description |
|---|---|---|
GET | /acp/workspace | The AI Chat workspace root (acp_workspace_root) |
POST | /acp/connections | Launch the configured ego and initialize |
GET DELETE | /acp/connections/:id | Snapshot / disconnect |
POST | /acp/connections/:id/kill | Kill the child |
POST | /acp/connections/:id/reconnect | Settle and start a new generation |
GET | /acp/connections/:id/stream?after= | WebSocket: the connection’s ordered frames |
GET | /acp/connections/:id/events?after=&limit=&maxBytes= | One bounded page of the same frames, with a next cursor |
GET POST | /acp/connections/:id/sessions | List / create |
POST | /acp/connections/:cid/sessions/:sid/{load,resume,fork,close} | Attach / detach |
DELETE | /acp/connections/:cid/sessions/:sid | Delete for good |
POST | /acp/connections/:cid/sessions/:sid/{prompt,cancel,config} | Run a turn, stop it, set an option |
POST | /acp/connections/:cid/sessions/:sid/{pause,resume-turn,compact} | ego’s own extensions |
GET | /acp/connections/:id/interactions | Questions waiting on a person |
POST | /acp/connections/:cid/{permissions,elicitations}/:rid/response | Answer one |
Only the two routes that launch a process — POST /acp/connections and
.../reconnect — take the loopback-or-authenticated guard. The rest need a
connection id one of those two handed out. The executable is never in a request
body; it is the ego_executable setting, read per call.
Streaming
WebSocket (/sessions/:id/stream)
Real-time PTY output streaming per session. Connects to the session’s broadcast channel.
Client ──WebSocket──> /sessions/{session_id}/stream
Server pushes PTY output as text frames
Session Lifecycle Events
When sessions are created or closed (via HTTP, MCP, or PTY exit), the server broadcasts events through the SSE event bus:
session-created— Emitted when a new PTY session is created (both local and MCP-spawned). Carriessession_id,cwd,agent_type, the optional stabledisplay_name, andparent_session(the spawning agent’s$TUIC_SESSION, present only foragent action=spawnby a caller with a registered identity — apending-mcp:placeholder is never published; the UI marks such tabs with a shared robot icon). Frontend uses this to auto-add remote tabs; a spawn-assigned name is stored as a custom name (display_name_is_custom), likesession rename is_custom=true: neither anintent:title nor an agent’s OSC 0/2 title replaces it, only a user rename does, while session-list snapshots carry independentdisplay_name_is_custom,display_name_from_spawnandis_remoteflags, plusparent_sessionand the livetuic_sessionbound to each PTY, for reconnect and parent-name resolution.term-alias-assigned— Emitted when a session receives its human-friendly alias. Carriessession_idandalias. Published aftersession-createdon the bus, and also as a desktop window event. Frontend uses this to update tab tooltips; it fires once, so after a reload the alias comes from the session list (aliasonGET /sessions/list_active_sessions).session-renamed— Emitted when MCPsession action=renamechanges a tab’s display name. Carriessession_id,nameandis_custom. The desktop and browser UIs update the tab bar and sidebar from it. The name must be one line of at most 256 characters without control characters.session-suspend-requested— Emitted when MCPsession action=suspendpassed the busy check. Carriessession_idandrequest_id. The UI ends that tab’s PTY and keeps the tab suspended.session-closed— Emitted when a session exits. Carriessession_id. Frontend uses this for cleanup.
These events are available on the SSE /events stream used by the mobile PWA and any connected WebSocket clients.
stories-changed {repo_path,payload:{rescan,ids,error?}} reports the changes answer of a project’s external story adapter after the repo watcher saw a change under its watch_paths (docs/backend/story-backend-protocol.md). rescan: true means reread every story.
ACP stream (/acp/connections/:id/stream)
The browser half of the desktop acp_subscribe Channel, carrying identical
frames. ?after= resumes from a sequence; a cursor the journal has dropped is
refused with 410 stream_gap before the upgrade rather than by opening and
closing a socket. A gap frame is terminal — recovery is a fresh connection and
session/load, because the missing frames exist nowhere in this client.
pump reads the next frame only after the socket took the previous one, so a
stalled client holds no queue in TUIC: a reader that lags the 256-event live
buffer resumes from the 1024-event journal, and one that falls behind the
journal receives the gap.
Turn frames never ride /events. What does is one low-frequency
acp-notice per connection — ready, settled, interaction_pending,
interaction_settled, card — naming the connection, generation and sequence, plus
the session and request id when it has them. It is a wake signal: react to it
by reading the snapshot, the interactions list, or the stream from the sequence
it names.
Streamable HTTP (POST /mcp)
MCP Streamable HTTP transport, serving two lifecycles on one endpoint:
Client ──POST──> /mcp (JSON-RPC request, response in body)
Client ──GET───> /mcp (SSE stream for server notifications, requires Mcp-Session-Id header)
Client ──DELETE─> /mcp (end session, pass Mcp-Session-Id header)
Legacy (2025-11-25) — initialize. It negotiates the revision: it echoes
params.protocolVersion when that value is one of 2026-07-28, 2025-11-25
or 2025-03-26, and answers 2025-11-25 for anything else or for a request
that names no version. A missing MCP-Protocol-Version request header remains
accepted for older clients; tuic-bridge supplies the version carried by each
proxied stdio request and falls back to 2025-11-25 when the request carries
none.
Modern (2026-07-28, SEP-2549) — server/discover. One stateless request,
no initialize, no mcp-session-id minted or required. The result carries
resultType: "complete", the full supportedVersions list, the same
capabilities the legacy handshake declares (tools.listChanged plus
experimental.claude/channel), the server instructions, ttlMs: 0 and
cacheScope: "private", with _meta."io.modelcontextprotocol/serverInfo"
naming the server. ego is the client this exists for: it pins the revision as
a const, sends only server/discover, and treats a JSON-RPC error as a hard
failure — so the previous method-not-found meant zero TUIC tools reached it and
session/new was refused.
A stateless client has no handshake to record its identity in, so it sends it on
every request in params._meta."io.modelcontextprotocol/clientInfo".
tools/list reads that name when there is no protocol session to read it from,
which is what keeps collapsing and lazy discovery working on the new lifecycle.
On 2026-07-28 a list result is a cache entry, not a bare array. tools/list
adds resultType: "complete", ttlMs: 0 and cacheScope: "private" — the same
three fields server/discover carries, and for the same reason: the tool surface
moves with upstream connects and config toggles, so none of it is cacheable. The
revision is re-read per request (MCP-Protocol-Version header, else the
params._meta."io.modelcontextprotocol/protocolVersion" key) because there is no
session to remember it in, and the fields are withheld from a legacy client,
which has neither the fields nor a reader for them.
Completed tools/call responses, including tool-level errors, carry
resultType: "complete" on 2026-07-28 requests. They do not carry ttlMs or
cacheScope: tool calls are not cache entries. The legacy result shape remains
content plus isError; a proxied upstream result keeps its other fields.
When the stdio bridge is temporarily disconnected, its local tools/call
error carries the same discriminator. Its offline tools/list result carries
the complete, private, zero-TTL cache envelope for current requests. Legacy
offline responses keep their previous shape.
Not schema tidiness: ego enforces all three before it admits a server. Measured
2026-09-19 against real ego 0.1.0 (#783-3c1b) — server/discover answered,
tools/list answered with the whole catalogue, and session/new still failed
with the supplied MCP servers could not be admitted, because the result carried
tools and nothing else. Injecting the three fields in a proxy, changing nothing
else, opened the session.
ego therefore gets the collapsed catalogue whatever collapse_tools says
(client_requires_meta_tools), for a different reason than grok’s __
delimiter limit: ego captures one immutable catalogue per generation and ships
every definition on every model call, while /mcp proxies 200+ upstream tools
on a normal day. Measured 2026-09-13 at 190 tools: 35.104 tokens per turn
against 615 collapsed, and flat as upstreams grow. Nothing is unreachable —
every native and upstream tool is still callable through call_tool, and
progress stays directly callable — the cost is one extra round trip before
the first use of an unfamiliar tool.
The handshake declares tools.listChanged (plus experimental.claude/channel).
The GET /mcp SSE stream emits notifications/tools/list_changed when the
upstream set changes, and a client may ignore a notification for a capability
the server never advertised.
tools/call does not require Mcp-Session-Id. Identity is resolved per call
rather than demanded up front. A caller that sends the header gets its protocol
session refreshed — a stale id (app restart, or a long-lived client like Claude Code
that lost its session) auto-recovers instead of erroring. A caller that sends none is
served anyway: most tools need no caller identity at all, so a plain curl against
POST /mcp now works.
Every initialize is logged. source = "mcp_initialize", one record per
handshake, with event naming how the client arrived:
event | Meaning |
|---|---|
fresh | No session id presented — first contact |
resumed | Presented an id we still hold — the same connection continuing |
reconnected | Presented an id we no longer hold (reaped by the idle sweep, or lost with a restart). The stale id is in presented_session; a new one was minted |
reconnected is the record behind an agent announcing “TUICommander is back”.
Before it existed, that arrival was indistinguishable from fresh: both silently
received a new UUID, and the only nearby log — Reclaimed stale MCP peer binding during initialize — fires only when a prior peer binding still exists, which a
reaped session no longer has. Claims about the connection dropping were therefore
confirmable but never refutable.
Successful stale peer-binding recovery during initialize or explicit registration logs at info. A rejected takeover of a live peer identity remains a warning.
The identity-scoped actions (agent action=register|send|inbox|wait) still refuse
without a protocol session — but each refuses on its own, with the concrete next step
(initialize, or agent action=register) that the previous blanket -32600 never
gave the caller. Making identity itself independent of the protocol session is a
separate step (Phase E of the dual-era plan); an x-tuic-session header binds a TUIC
identity to an existing mcp-session-id, it does not substitute for one.
GET /mcp and DELETE /mcp still require the header — both are bound to a specific
protocol session, and GET answers 401 without it.
The GET /mcp SSE stream emits notifications/tools/list_changed whenever the available tool set changes (e.g., native tools are enabled/disabled via config, or upstream MCP servers connect/disconnect). The bridge sidecar subscribes to this stream and forwards the notification to the AI agent.
A session may briefly hold two GET /mcp streams: a reconnect can be accepted while
the stream it replaces is still half-open. Each stream takes a generation on the
session and its teardown releases the session — the has_sse_stream flag and the
per-session messaging sender — only while it still holds that generation. An
unconditional release let the older stream’s drop remove the sender its own
replacement had just subscribed to, closing the new stream immediately.
Three details in that guard are easy to get wrong:
- Generations come from one process-wide counter, never per session. A
DELETE /mcpcan retire a session id while its stream is still draining, and the nextGETauto-recovers that id from scratch — a per-session counter would restart and reissue a number the half-open stream still holds. - The teardown holds the
mcp_sessionsentry across the channel removal, andmcp_getholds it across its subscribe. Split apart, a superseded stream can pass its generation check and then remove the sender after the replacement subscribed. Lock order ismcp_sessions→messaging_channels; nothing may hold amessaging_channelsreference while takingmcp_sessions. - That hold is taken with
entry, notget_mut, because the absent case needs it too. WhenDELETEor the reaper has already retired the id there is no generation to compare and teardown removes the channel outright;get_mutreturningNonereleases the shard before that removal, and a reconnect landing in the window recreates the session, subscribes, and then loses its brand-new sender to the older stream’s drop. Onlyentrykeeps the shard locked over a key that is not there.
The bridge uses the standard MCP ping request for its three-second liveness check. This keeps health traffic constant-size as terminal count grows; it does not rebuild or serialize the complete tool catalog. If IPC is reachable but /mcp is unavailable, the bridge reports that the MCP endpoint is unavailable instead of incorrectly claiming the desktop process is not running.
The bridge retains the downstream client’s last initialize request and replays
it internally after reconnecting to a restarted TUIC process. This restores
session-scoped metadata such as Grok compatibility mode without sending a
second initialize response to the client.
While the endpoint is unreachable, the handshake methods (initialize,
server/discover, ping) wait up to 3 s for it through one path. If it is
still unreachable, initialize gets the local minimal result, and every other
method without a local answer gets the transient error -32000 “TUICommander MCP
is unavailable”. tools/list (empty) and tools/call (error result) answer at
once. The bridge never answers -32601 offline: a client reads that as a server
without the method and drops TUIC (#3044-ddeb).
On reconnect, a peer may reclaim its stable TUIC identity after the prior MCP protocol session has no live SSE subscriber and has missed the bridge activity grace period. The takeover retires the old forward and reverse routing entries atomically.
When the asserted identity has no live PTY binding, the first MCP request also
checks the foreground processes of local terminals. Exactly one process whose
actual TUIC_SESSION matches the header restores that terminal association.
This repairs a missing restore-time binding even when the MCP route already
exists, so session lists publish the parent’s identity and mobile can nest its
children. Existing live bindings stay intact; unrelated or ambiguous matches
remain terminal-less. ACP conversation identities do not acquire a terminal.
On normal stdio EOF, the bridge sends DELETE /mcp after its in-flight requests settle, releasing that protocol session immediately. Each fresh initialize for an existing x-tuic-session identity also retires protocol metadata, routes, and message channels of stale sibling sessions left by abrupt exits. Subscribed and recently active siblings remain intact. Sessions without a stable identity still use the hourly maintenance sweep after an abrupt exit.
After a failed upstream initialize, the bridge waits before trying again. The pause starts at one second, doubles up to eight seconds on consecutive failures, and resets after a successful connection. Request-triggered, downstream initialize, and background retries share this limit within one bridge process.
A currently subscribed or recently active owner is never replaced — but it can be joined. One PTY may hold more than one bridge (Codex opens two). They usually inherit the same $TUIC_SESSION and assert the same x-tuic-session. Only a process that inherited that PTY’s environment can assert it, so a second asserting bridge is a sibling, not a claimant: it is added to the identity’s routing (mcp_to_session plus the session_to_mcp list) while the live owner keeps delivery ownership. Ownership stays put on purpose — two live siblings that traded it on every request would flip the delivery channel back and forth. The inbox is keyed by the PTY identity, so both bridges read the same mail. agent action=register from a joined sibling is a rename, not a takeover; a protocol session with neither the header nor an existing route is still refused with “already registered to another active MCP session” (throttled to one WARN per claimant pair). Ending one co-owner’s protocol session drops only its own routes and promotes a survivor to delivery owner; the peer entry, inbox and orchestrator role are torn down only when the last co-owner goes.
If a second bridge in the same live PTY asserts a different UUID (the persisted
tab UUID versus the PTY key), initialize joins the first registered peer’s
mailbox. register from that bridge keeps the shared identity. Both asserted
UUIDs still resolve through the PTY for agent send, but list_peers exposes
one recipient and both MCP connections read the same inbox. This coalescing
requires the same live PTY; peers on different PTYs remain separate.
Blocking tool actions run off the runtime worker. Dispatch is action-aware:
session create/input/close/kill/resize, agent spawn/send, and config
writes use run_blocking_handler (tokio::task::spawn_blocking) because they may
sleep, spawn processes, write PTYs, or touch disk. Common read-only actions such
as session list/output/status and agent list_peers/inbox execute
inline without cloning their JSON payload or scheduling blocking-pool work.
Async waits remain on their event-driven async handlers. A panicking blocking
handler becomes a tool error rather than killing the request task; POST /mcp
does not add another blanket wrapper.
Native argument repair contract (#2007-59f6)
Native argument contracts are enforced before dispatch, both for direct tools
and call_tool, on HTTP and MCP-over-ACP. The server keeps the complete private
JSON Schema, including action-dependent requirements (for example ui tab needs
id, title, and exactly one of html/url). Validation cannot fetch external
schema references.
Advertised inputSchema objects have no root oneOf, anyOf, or allOf:
Anthropic tool clients reject that shape. Full listing, lazy search, and exact
schema lookup publish the same flat action enum and properties. Conditional
requirements are in description text; nested parameter alternatives use anyOf.
The private validator still enforces exclusive alternatives and required fields
before any effect starts, including grouped workflow actions and agent task handles.
Static rejection returns a tool error with:
code: "invalid_arguments",outcome: "rejected",effect: "not_started";retryable: false: do not repeat unchanged arguments;repair.retry_after_correction: true: a corrected request may be submitted;- at most 16
violations, each with JSON-pointerpath,schema_path, the schemaconstraint(limit, required fields or allowed values), and a masked explanation. Input values are not copied into repair errors.
This is not auto-retry advice for permission, configuration or safety refusals. Those remain existing refusals, without the static repair marker. Runtime preconditions and authorization remain the handler’s responsibility; a valid schema never grants access or proves an effect completed.
Progress text permits 1..500 Unicode scalar values before trimming, not UTF-8
bytes, UTF-16 units, or grapheme clusters; whitespace-only text is invalid.
The shared Progress model enforces the same raw length for HTTP /progress/report
and IPC report_progress_event, which retain their typed transport errors.
src-tauri/src/mcp_http/fixtures/action-input-contract-2007.json is a local
consumer contract fixture, not a captured client trace. It covers the audit’s
582/543/502-character retries, the valid boundary, emoji and combining scalars,
missing titles/text/paths, and an invented action. Ego must validate its admitted
schema against these cases without a server round trip; that cross-repository
consumer integration is not proven by TUIC’s tests.
On-demand native tool guidance
The compact automations guide includes profiles to discover saved run profile
names; its full help and Settings description retain this guidance.
session, agent, repo, ui, voice, telegram and automations advertise
compact agent-facing descriptions with every action and the hard constraints.
Call the same tool with {"action":"help"} for its complete usage guide in the
description response field. Help retains all displaced rules, examples and
response details. It does not perform the requested operational action.
The normal disabled-tool and conditional-owner gates apply to help too.
Argument schemas and pre-dispatch validation remain authoritative; discovery
continues to publish flat client-compatible schemas. Other already compact
native tools are unchanged, including the directly loaded progress primitive.
Settings summaries and tooltip copy do not change. Reconnect cached MCP clients
after loading this backend build to obtain the updated catalogue.
Lazy Tool Discovery (collapse_tools)
When collapse_tools: true in config.json (or via Settings > MCP > TUIC Tools > “Collapse tools”), the server replaces the full tool list in tools/list with three meta-tools (the Speakeasy pattern) plus the compact progress tool when enabled:
| Meta-tool | Purpose |
|---|---|
search_tools | BM25 search over the full native + upstream tool corpus; returns name/summary pairs, an opaque catalogue_generation, and an optional complete top_schema |
get_tool_schema | Returns the full {name, description, inputSchema} for a specific tool |
call_tool | Dispatches to the named tool — routes to the native handler or proxy_tool_call for {upstream}__{tool} names |
Search grammar is server-owned. Plain words rank names and descriptions with BM25. Each +term is a required, case-insensitive substring of the tool name (including any upstream or server alias prefix); several required terms use AND. Remaining plain words rank the matching names but do not exclude them. Filtering happens before the result limit, and a required term with no name match returns no results. select:<name> selects one exact catalogue name without ranked fallback.
Rationale, measured 2026-09-13 on the running desktop instance with 190 tools connected (see Measuring the surfaces for the method): the full list is 154,117 bytes / 35,104 tokens in every agent turn, against 2,810 bytes / 615 tokens for the collapsed surface — which does not grow with the upstream count, because the upstream tools are no longer in the list. The agent fetches other schemas on demand. progress stays direct so routine reporting needs no search/schema preflight. Toggling collapse_tools fires notifications/tools/list_changed so connected clients refresh their tool cache.
TUIC also selects this three-tool surface automatically for two clients
(client_requires_meta_tools), for two unrelated reasons. The selection is
per-client: it does not change collapse_tools or the surface returned to
anyone else.
- Grok (
clientInfo.namestarts withgrok-shell-) accepts only one__namespace delimiter in a qualified MCP tool name, so it otherwise discards proxied names such astuicommander__upstream__tool. The meta-tools keep the upstream identifier in thecall_toolargument instead of the qualified id. Session-local, read frominitialize. - ego (
clientInfo.nameisego) pays for the catalogue on every model call — one immutable tool list per generation, every definition sent with every request — so the numbers above are its per-turn cost, not a one-off. ego is stateless, so the name is read from each request’s_metarather than from a handshake.
A request that names a client in _meta decides the surface by itself; the
session’s remembered flag is the fallback for a legacy client that named itself
once at initialize. The precedence runs that way because ego reaches /mcp
through tuic-bridge, which opened the transport session under its own name:
preferring the session made server/discover advertise the collapsed surface and
the very next tools/list deliver the full one, for the identical request.
Schema admission and reuse (#2013-73f9). Search includes the complete definition of
its first visible match when the serialized UTF-8 JSON fits schema_byte_budget
(default 16384 bytes, maximum 65536; 0 disables inline schemas). The budget applies
to the definition, not the whole search response. Oversized schemas are omitted,
never truncated; select a result and fetch it with get_tool_schema instead.
A client can admit top_schema directly and call the tool without a second
schema-fetch hop. Reuse an admitted definition until notifications/tools/list_changed
or a different catalogue_generation. The generation is a content digest of the
search corpus, not an authorization token. An unchanged rebuild keeps it stable.
HTTP SSE and MCP-over-ACP refresh the index before forwarding invalidation, including
lag recovery. Dispatch still checks live permissions and visibility; a cached schema
never grants access. Clients must implement admission and invalidation themselves;
server tests are not evidence of a real ego client’s hop reduction.
Filter enforcement. Both search_tools and call_tool re-apply the safety filters that the full listing would apply: mcp_capabilities.denied is checked up-front in handle_call_tool, and upstream allow/deny filters are enforced at both enumeration time (aggregated_tools) and dispatch time (proxy_tool_call). This is critical under collapse mode: discovery no longer gates dispatch, so an agent that knows a filtered tool name cannot bypass the filter by calling call_tool directly. search_tools and get_tool_schema also reject meta-tool names, and call_tool refuses to recurse into itself.
The BM25 index lives in AppState::tool_search_index (parking_lot::RwLock<ToolSearchIndex>, backed by src-tauri/src/tool_search.rs). A background task subscribes to the mcp_tools_changed broadcast and rebuilds the index whenever the tool set changes (upstream connect/disconnect, mcp_capabilities.denied edit, collapse_tools toggle).
The MCP instructions string returned by initialize (build_mcp_instructions) swaps to a “lazy discovery” guide when collapse_tools: true or the connecting Grok session requires compatibility mode, so agents know to call search_tools first rather than looking for a flat tool table.
The initialize instructions carry no repository paths. The ## Repos section is one line: the repository count, the count per group and per remote connection, and the repo action=list call (the call_tool form when tools are collapsed). repo action=list returns each repository with its group and, for a repository on a remote connection, connection_id; local rows have no connection_id. The ## What TUIC gives you section names the native tools registered on that install by purpose (reach the user, drive the platform, other) and the connected upstream servers with their tool counts and how to discover those tools (ToolSearch for Claude Code, search_tools when collapsed). It names only tools that tools/list serves and is omitted when there are none. The suggest: marker is omitted for a spawned child (an MCP session bound to a peer with a parent session); root sessions keep it. Upstream servers have no description field in their configuration, so only names are listed.
Instruction stability contract. Terminal sessions and peer inventory never appear in
initialize instructions: opening, closing, renaming or moving a terminal, or
registering/removing a peer, must not change their bytes for the same caller and
configuration. Read session action=list for current terminal ids, paths and
worktree branches. Read agent action=list_peers for current peers; its peers
array gives the current count. This keeps live inventory out of clients’ cached
system prefixes; it does not claim a provider cache hit.
The fields retained in instructions are the application version, caller-specific protocol/launch guidance and marker settings, tool-discovery mode, registered native tool names, available upstream server names and tool counts, and configured repository totals/groups/remote-connection counts. These describe the installed protocol, caller policy or tool/configuration surface, not terminal activity. Configuration edits, application upgrades, caller identity/parentage changes and upstream capability/availability changes can still change that surface; the contract is not a permanent snapshot of tool capabilities.
All instruction surfaces share render_mcp_instructions: HTTP POST /mcp
initialize uses build_mcp_instructions_for_session; modern server/discover
uses build_mcp_instructions_for_mode; GET /mcp/instructions uses
build_mcp_instructions. The IPC listener serves the same build_router routes
on Unix sockets and Windows named pipes, and tuic mcp initializes that server
through IPC. There is no separate CLI instruction renderer.
The TUIC connection acknowledgment in those instructions is emitted exactly once per MCP connection or reconnect, never once per conversational turn. TUIC protocol context remains in initialize instructions and native core-tool descriptions only; upstream tool descriptions are preserved instead of receiving a repeated TUIC preamble.
When intent markers are enabled for the connecting agent, initialize instructions require intent: on its own line, at the start of every user task and on material phase changes. “On its own line” is in the instruction because the ack sentence is required to open that same first message: an agent that runs the two together leaves the token mid-row, where the parser has to reach for it (see docs/backend/output-parser.md → Intent). The backend stores that dynamic intent independently from the spawn-time PTY description and the last submitted prompt.
Two instruction surfaces, and which one owns a rule
Initialize instruction prose stays within 1,728-byte classic and 1,792-byte collapsed empty-state budgets. The cross-client delegation rule adds one short fallback line for clients without a launch channel; other sections do not grow. Compact wording preserves the answer marker, urgent mail and progress reporting rules. The answer marker can start a row or the text of a Markdown list item; status, tool and hook/task notices stay excluded.
TUIC supplies protocol instructions and tool descriptions on different wire surfaces. Client receipt does not prove that the model can read either surface on its first turn. Deferred tool discovery can expose them later.
| Surface | Transport receipt | Model visibility | Owns |
|---|---|---|---|
initialize.instructions (render_mcp_instructions) | Returned in the initialize response | Harness-dependent: Claude exposes a bounded system block; Codex exposes namespace metadata after discovery in the measured mode | Wire protocol markers, a capability map, cross-tool rules, configuration/capability summaries |
tool description (native_tool_definitions) | Returned for advertised tools on tools/list | May be deferred by the harness; in Speakeasy mode native descriptions arrive through discovery | That tool’s actions, arguments and semantics |
Pinned canary evidence (2026-10-04). Claude Code 2.1.286, with
claude-sonnet-5-5, exposes server instructions even when tool descriptions are
deferred. Its default instruction cap is 2,048 characters: the 1,024- and
2,048-byte ASCII controls cite START/MIDDLE/END; the 4,096–32,768-byte controls
cite START only (CLAUDE_DEFAULT_*). The unused probe description is absent
until tool loading. Disabling tool search exposes that description but does not
remove the instruction cap. CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH=65536
exposes all three instruction canaries at 32,768 bytes
(CLAUDE_MAX_OVERRIDE_32768).
Codex CLI 0.160.0, with gpt-6-luna, receives the instructions, but its
initial no-tool turns cite NONE at all six tested sizes. After metadata
discovery, it cites the instruction START/MIDDLE/END and description token at
1,024, 4,096 and 32,768 bytes (CODEX_SEARCH_*, including
CODEX_SEARCH_32768.stdout). Thus the field is not universally discarded, and
post-discovery visibility does not establish first-turn visibility.
The harness report at
~/Gits/personal/orchestrator/reports/tuicommander/2026-10-04-mcp-instructions-harnesses.md
records versions, controls and limits; its raw canary evidence is under
~/Gits/.tmp/mcp-canary/ (including CLAUDE_DEFAULT_2048.stdout). Speakeasy
advertises meta-tool descriptions first; native agent, repo and session
semantics require discovery. A description fallback therefore cannot guarantee
that startup rules prevent an earlier shell action. Actual within-process
reconnects and untested harness versions remain unmeasured.
Instruction files are a separate surface. The
rules-file study at ~/Gits/.tmp/rules-file-study/result.md measures Claude
@file expansion, literal unexpanded @file lines in Codex AGENTS.md, and
explicit ego --instructions FILE loading in headless mode. Do not treat a
file reference, MCP receipt, or parent context as proof of child or lifecycle
visibility. The studies do not change TUIC’s launch behavior.
The rule that follows: a statement a tool description carries is not repeated in
the instructions. A client reading both paid for it twice, and — worse — a
client that loaded only descriptions could otherwise go without that rule. That is the direction
story 078-8b2e set, and instructions_do_not_repeat_what_tool_descriptions_already_say
now enforces it in both directions, asserting the removal and the surviving
copy. Three things moved out of the instructions this way: the per-tool
catalogue (tools/list already carries it in the same turn), the ## Workflow
section (the agent description’s five-line primer restated), and the
**UI feedback:** line (the ui description’s Use: block restated). The
orchestrator role and its mail_wake contract moved into the agent
description, where a headerless caller can actually find them.
Two rules stay in the instructions on purpose and are not duplication:
- Worktrees — it forbids
git worktree add/remove, a tool that is not ours. No TUIC tool description is a reliable place to ban a shell command. - Submit — it spans two calls (text, then Enter) and a polling loop, so it
belongs to no single action. Agents split submits until this line existed; it
is pinned byte-exact in both modes by
initialize_instructions_pin_the_one_call_submit_rule_in_both_modes.
There is no “full prompt” mode on the server and none is planned: the long-form operator guidance lives in this document, which is the optional surface a human opts into, not a per-turn cost every agent pays.
Measuring the surfaces
mcp_instruction_surface_bytes_stay_within_budget measures every surface a
client receives and asserts a ceiling on each. It is reproducible because
nothing in it reads the host: render_mcp_instructions takes an explicit
InstructionContext (repos, sessions, peer count) instead of reading the user’s
repositories.json and live PTY map, and spawn_response renders from fixed
ids instead of a launched process.
# byte counts + the dump
TUIC_MCP_SURFACE_DUMP=$PWD/.tmp/mcp-surface.json \
cargo nextest run --lib -E 'test(mcp_instruction_surface_bytes)'
# token counts from the same dump
python3 -m venv /tmp/tokvenv && /tmp/tokvenv/bin/pip install tiktoken
/tmp/tokvenv/bin/python - <<'EOF'
import json, tiktoken
enc = tiktoken.get_encoding("o200k_base")
for k, v in json.load(open(".tmp/mcp-surface.json")).items():
print("%-34s %7d bytes %7d tokens" % (k, len(v.encode()), len(enc.encode(v))))
EOF
Tokenizer: tiktoken 0.14.0, encoding o200k_base. It is a GPT tokenizer and
therefore a proxy — Anthropic publishes no offline tokenizer, so a Claude token
count cannot be produced here. Bytes are exact; treat the token column as an
order-of-magnitude figure and never quote it as a Claude cost.
Deployed baseline — measured 2026-09-13 against the running desktop instance
(TUICommander v1.7.7, GET /mcp/instructions and POST /mcp tools/list on
localhost:9876), 16 repos, 28 sessions, 26 peers, 2 upstream servers:
| Surface | Bytes | Tokens (o200k_base) |
|---|---|---|
| instructions, static prose | 3,525 | 891 |
| instructions, dynamic repos + sessions | 3,057 | 1,178 |
| instructions, total | 6,582 | 2,069 |
tools/list, 190 tools | 154,117 | 35,104 |
tools/list, 6 native tools only | 21,990 | 5,127 |
Two things that baseline settles. The ~35k tokens figure quoted for the
uncollapsed tool list is real, not folklore — 35,104 measured. And the static
prose is not where the instructions grew: at 891 tokens it still fits the
1,000-token budget story 1179-1cf9 set, while the dynamic repo/session block
that no deduplication can touch is now the larger half at 1,178. Read any
claimed saving against that split before believing it.
Checkout measurement, before and after the deduplication — same fixture both
sides (test_state, which leaves mcp_capabilities.denied empty, so its classic
figure covers all nine native tools where production hides config and debug);
.empty is zero repos/sessions/peers, .loaded is 8 repos, 12 sessions, 6 peers:
| Surface | Before (B) | After (B) | Δ | After (tokens) |
|---|---|---|---|---|
| instructions, classic, empty | 3,510 | 1,373 | −2,137 | 334 |
| instructions, classic, loaded | 4,497 | 2,445 | −2,052 | 738 |
| instructions, collapsed, empty | 2,300 | 1,417 | −883 | 345 |
| instructions, collapsed, loaded | 3,287 | 2,489 | −798 | 749 |
schema.repo | 2,626 | 4,075 | +1,449 | 899 |
schema.agent | 6,721 | 7,013 | +292 | 1,627 |
schema.ui | 3,444 | 3,689 | +245 | 889 |
schema.session | 5,105 | 5,105 | 0 | 1,219 |
response.register | 2,882 | 2,882 | 0 | 668 |
response.spawn | 815 | 815 | 0 | 244 |
tools/list, classic | 22,423 | 24,409 | +1,986 | 5,685 |
tools/list, collapsed | 2,377 | 2,758 | +381 | 603 |
And the number that actually matters — instructions plus tools/list, which is
what one connection pays:
| Mode | Before | After | Net |
|---|---|---|---|
| classic | 25,933 B | 25,782 B | −151 B (−0.6%) |
| collapsed | 4,677 B | 4,175 B | −502 B (−10.7%) |
Read that honestly. The deduplication removed 2,137 bytes of prose from the
classic instructions, and about 590 of those bytes did not disappear — they moved
into the agent and ui descriptions, where clients ignoring instructions can
finally see them. Against that, the same change added 1,449 bytes to the
repo description for nine progress_* actions that were advertised and
undocumented. Netting the two leaves classic essentially flat.
So: the story’s saving is real but it is not a size saving in classic mode. What
it bought is that every rule now has exactly one owner, and that owner is the
surface every client receives. Collapsed mode, where tools/list is four tools
instead of nine, keeps a measurable 10.7%.
MCP Native Tools
Native tools are organized by domain. Settings access and diagnostics are disabled by default via capability denials; listing, search, schema lookup and dispatch respect this filter in both full and collapsed mode. The enabled progress tool is additionally kept on the direct collapsed surface.
The payload measurements above predate voice and are left as recorded: they
say what was measured, not what the list costs today.
| Tool | Actions | Default |
|---|---|---|
session | list, create, submit, input, output, status, wait, resize, rename, close, kill, pause, resume | Enabled |
agent | spawn, wait, register, list_peers, send, inbox, subscribe, ack, unsubscribe, task_get, task_cancel | Enabled |
remote | preview, update | Only with a connected remote server |
repo | list, active, status, branch_integrations, branch_integration, worktree_list, worktree_lifecycle, worktree_create, worktree_remove, orphan_cleanup_answer, branch_delete, progress_list, get_settings, set_settings | Enabled |
progress | (no actions — appends one done or blocked entry) | Enabled, unless progress_tracking is off |
ui | tab, toast, confirm, screenshot, design_start/stop/status/reload/navigate/screenshot/errors/eval | Enabled |
story | StoryAction tags: plans, stories, Ideas, notes, dependencies, transitions (story action=list_plans) | Enabled |
workflow | definition, run, proposal_create, report, launch | Enabled; listed only when used (below) |
automations | Scheduled definitions and runs | Enabled; listed only when used (below) |
plugin_dev_guide | (no actions — returns guide text) | Enabled |
voice | speak, stop, status | Only with voice configured |
telegram | register, unregister, begin, activity, finish, send | Only with Telegram configured |
settings | describe, get, set, reset, patch, perform, refresh | Disabled; trusted UI opt-in required |
debug | agent_detection, logs, sessions, invoke_js, help | Disabled |
agent surface by caller role (#2805-4ee2)
tools/list, get_tool_schema and the initialize instructions give each caller
one of three agent tools. A managed child has register, list_peers,
send, inbox, wait and help. An agent adds spawn and the task_get/
task_cancel of its own spawns. The orchestrator keeps every action,
including launch and subscribe/ack/unsubscribe.
- Role source. A caller is a managed child when its MCP origin session has a
session_parententry and its spawn-fixed capability set lackschildren(or it has no set). A child grantedchildrenis an agent. Any other bound caller is the orchestrator when it is inorchestrator_peers(it registered withorchestrator=true), else an agent. A caller with no registered identity keeps every action. The parent link is read first, so a child that registersorchestrator=truestays a child. No argument, mail or client name is read (mcp_http/caller_role.rs). - One schema source. The child definition is derived from the one generated
definition: action enum, fields (per-action ownership table
AGENT_ACTION_FIELDS), action conditions and per-action description segments are filtered.every_agent_field_has_an_owning_actionfails when a new field has no owning action. - Dispatch. The capability gate runs first and adds
roleto its refusal for a child. Then any other hidden action (aninbox/waitwithsubscription_idcounts assubscribe) returns{code: "role_denied", role: "managed_child"|"agent", effect: "not_started", retryable: false}with an error that names the role and tells the caller to report BLOCKED to its parent or orchestrator. - Instructions. A child and an agent each get one line that names the missing actions and the BLOCKED report. The orchestrator gets the delegation line.
- Size. Measured 2026-11-04 by
mcp_instruction_surface_bytes_stay_within_budget: the full advertisedagentdefinition is 16,336 bytes, the managed-child definition 7,968 bytes (ceiling 8,000). - Not scoped. The HTTP
/agents/*routes are not scoped per role.search_toolsfilters the shared index and takes a nativetop_schemafrom the caller’s own catalogue. The role is a surface boundary, not a security one: a root agent can register itself as orchestrator.
workflow and automations listed by state (#2807-f698)
tools/list, search_tools, get_tool_schema and the initialize instructions
list workflow only when the caller’s project uses workflows, and automations
only when an automation exists. This gates discovery only: a call still passes
the usual configuration gates.
- Workflow usage. The project has a user-made definition
(
builtin_key IS NULL, for example a copy of a template) or a running or paused run. Built-in templates do not count: listing drafts seeds them already published, and the seed migration republishes them without a user edit. A run of a built-in counts while it is active. - Project. The caller’s origin PTY working directory, else its AI Chat (ACP)
binding root, else its MCP roots path, resolved to the registered repository and then to the owning project:
the key the workflow stores use. A caller without a project does not see
workflow. - Automations usage.
automations.jsonholds at least one definition. - Orchestrator. A peer registered with
agent register orchestrator=true(orchestrator_peers) sees both tools; registering or clearing the role sendstools_changed. - Change signal.
tools/listreads a cached usage (McpState.tool_usage). It is recomputed at startup, after every workflow definition action and automation API action, and on everyWorkflowRunChangedorAutomationRunChangedevent. A changed usage sendstools_changed, which emitsnotifications/tools/list_changedand rebuilds the search index. - Reconnect. Claude Code ignores
notifications/tools/list_changed(anthropics/claude-code#4118), so a Claude Code session sees a newly listed tool after an MCP reconnect. The instructions say this in one line when a tool is hidden (tool_usage::HIDDEN_LINE).
Capability cutover and client migration
mcp_capabilities is the persisted policy object. denied defaults to ["diagnostics"]. Settings access has one switch, the host-only settings_mcp_enabled opt-in; settings is not a capability, and a legacy settings denial migrates to that switch turned off. Parent capabilities deny every action in their domain; member capabilities deny only their actions. Listing, search, exact schema lookup and direct/meta dispatch apply the same live policy, including before the search index refreshes.
On the first load, disabled_native_tools migrates to this object and is removed on save. Mappings: task → agent_tasks; story → story; workflow_run → workflow.run; workflow_story_create → workflow.proposals; workflow_report → workflow.reports; workflow_launch → workflow.launch; design_mode → design; debug → diagnostics; remote → remote_deployment; plugin_dev_guide → plugin_reference. Other current tool names map to the same-named capability. An old parent denial still denies all grouped actions. Unknown names are logged and retained in migration_unknown_tools; Settings displays them for review. They are not silently dropped.
Breaking change: retired MCP names have no aliases. Use agent action=task_get/task_cancel, story action=<StoryAction tag>, workflow action=definition/run/proposal_create/report/launch (retain the generated input object), and ui action=design_*. Reconnect cached clients and update literal CLI calls and external allow rules. Existing agent, story, workflow and ui allow rules now cover their grouped actions; review that scope explicitly. HTTP/IPC service routes and tuic story do not change. Unknown external callers cannot be migrated automatically.
Compact tools/list measurement (2026-10-20, serialized tools array only; no JSON-RPC envelope):
| Mode | Before (c79f74bfe3) | After cutover | Change |
|---|---|---|---|
| Classic | 92,781 bytes | 73,435 bytes | −19,346 bytes (20.9%) |
| Collapsed | 3,581 bytes | 3,581 bytes | Unchanged |
Both runs use zero upstreams, Settings enabled and optional owners unconfigured. The regression test capability_cutover_rejects_retired_names_and_measures_catalogue prints these compact byte counts and rejects every retired name. These are byte measurements, not token estimates or a complete configured-owner inventory.
Settings reads native_capabilities from get_mcp_status / GET /mcp/status; each entry has name, title, description and optional. The six optional switches are Secrets, Telegram, Settings access, Diagnostics / JS inspection, Remote daemon deployment and Progress tracking. Additional restrictions contain core domains and migrated member capabilities. The unfiltered native_tools reference inventory remains available separately. Disabled and unavailable capabilities remain configurable; upstream policy, trusted Settings opt-in, Design Mode host grants, voice binding and deployment consent remain separate.
Native MCP inputs use path for a repository root in agent register/list_peers and repo, and branch for repo worktree_lifecycle/worktree_remove. The old project and workspace_id input names are rejected. The shared worktree_create response still includes workspace_id alongside branch for HTTP parity. spawn_session=true on worktree creation starts a bare shell PTY; spawn an agent separately when one is needed.
repo action=get_settings path=<repo> returns settings (the repository’s own
entry from repo-settings.json; null means inherit) and effective (own value,
else the global repo default). repo action=set_settings path=<repo> settings={...} changes only the named keys (null restores the inherited default)
and saves through the same delta save as PUT /config/repo-settings. Values are
validated by that entry’s schema; unknown keys and path are refused.
repo action=orphan_cleanup_answer path=<repo> decision=remove|keep answers the
currently open orphan cleanup dialog. A remove answer rechecks every pending
worktree for tracked or untracked changes, a HEAD reachable from a branch and
live sessions inside it; an unsafe or stale request is refused. The frontend consumes the answer and
closes the dialog before removal.
Conditional native tools
remote, voice and telegram use one shared availability predicate for
classic listing, lazy search, exact schema lookup and direct or call_tool
dispatch. A known name does not bypass a missing condition. Explicit native
config denials still take precedence.
remote: at least oneRemoteRuntimeentry hasRemoteStatus::Connected. Saved records, connecting tunnels, failed authentication and health-only probes do not count. Preview digests and session-loss confirmation stay in the deployment owner and are not relaxed by this condition.voice: the persisteddictation-config.jsonparses asDictationConfigwith bothenabledandhands_free_spoken_repliestrue. A missing or corrupt document is not configured. Engine selection is not the opt-in: an unset engine resolves to Edge. This does not require an armed conversation or probe the microphone, speech model or network.telegram: the private setup config hasenabled=trueand a nonemptybot_alias, and the privatebot.tokenfile exists. Discovery checks only credential-file availability, never its contents. Network connectivity, chat selection and agent registration remain separate runtime checks.
Remote connected-set transitions and successful voice/Telegram owner setting
changes send notifications/tools/list_changed through the existing HTTP SSE,
bridge and ACP notification paths. The Telegram polling owner also observes
cross-process setup revisions. Clients that ignore catalogue notifications
must reconnect after a condition changes. The Settings tool inventory remains
unfiltered so users can inspect and enable optional capabilities.
A configured voice can still answer available: false with a runtime reason.
A build without audio retains that answer after checking terminal binding;
an unbound connection is refused before it can receive voice status.
Every action is bound to the calling terminal: resolve_mcp_origin_session
maps mcp-session-id onto a TUIC session, and that session must be the one
hands-free is armed for. A connection with no TUIC session is refused outright
rather than falling back to the user’s own control surface. status checks the
binding too — the fields alone say what somebody else’s conversation is doing.
Because handle_call_tool preserves addr and mcp_session_id, the direct and
collapsed paths reach the same handler with the same identity;
voice_binds_to_the_calling_terminal_on_the_direct_and_collapsed_paths asserts
both produce byte-identical answers, bound and unbound.
The schema takes action, text, turn and utterance_id — no language and
no voice, and a_model_cannot_choose_the_language_or_the_voice_it_is_spoken_in
pins that list. Both come from the conversation: the dictation language when it
names one, and what Whisper detected under auto, reported as
status.language. A model that could pass either would be a second source, and
the two would disagree the first time the user switched languages. The
description says so as well as the schema preventing it, because a model that is
merely blocked writes its reply in English and wonders why it sounds Italian.
The description also places the two mode notices the model will receive
(MODE_ENTRY_HINT and MODE_EXIT_HINT, see
dictation.md). They
arrive as ordinary terminal input, indistinguishable from something the user
typed, so the tool says whose they are and that the end notice is final —
otherwise a model can answer “hands-free voice is off” instead of obeying it. It
also says the user can turn them off, so their absence is not evidence that
nothing is armed; action=status is.
the_voice_tool_places_the_notices_the_model_will_receive pins both sentences.
This table is generated from the same *_ACTIONS constants the schemas use, and
every_documented_action_constant_matches_schema_and_description keeps the three
in step: the constant, the action enum in the schema, and a documenting line in
the tool’s own description. It is the gate that closed the gap where REPO_ACTIONS
and the repo schema both advertised nine progress_* actions that the
description body never mentioned — invisible to any client reading descriptions
alone. debug is the single exemption: its description points at action=help,
which returns the full usage guide.
Send to the coordinator without discovery
Use agent action=send to=orchestrator message=<text> without list_peers.
The reserved address selects registered orchestrator=true peers in the caller’s
managed parent chain. If that chain has no role, it selects a unique registered
orchestrator with the caller’s registered path; an unset caller path considers
all registered roles on this server. No match or multiple matches returns an
explicit error; ambiguity lists UUIDs for an explicit send. Display names do not
claim the role address. Other recipient addresses keep their existing behavior.
The compact tool description and full agent action=help guide put this address
in their first line, so one search_tools response with top_schema followed by
one send is enough. Registration declares the role; spawning does not infer it.
One session, three addresses
Every action that takes a session_id — and agent action=send’s to — accepts any
of three names for the same terminal: the PTY id the server minted, the
tuic_session the tab persists across restarts, and the repo-derived alias
(tu-1). AppState::resolve_session_ref maps the first two forms onto the live PTY
id and AppState::resolve_peer_ref maps any of them back onto the peer identity that
owns that terminal, so a model never has to remember which of the three it was handed.
Resolution deliberately falls through instead of failing. A reference that matches
nothing is passed to the action unchanged, because a session whose process has exited
leaves its output buffers behind while its registry entry is gone: hard-erroring on an
unresolvable reference would break session action=output on exactly the session an
orchestrator most needs to read. The action that owns the reference still reports
Unknown session when it genuinely needs a live one.
ui action=confirm blocks only its requesting tool call while the native dialog
is open. The dialog runs on the blocking pool, so an unanswered confirmation
cannot occupy the async MCP workers serving other agents and sessions. The
stdio-to-IPC bridge gives this call 305 seconds: the confirm handler’s own
300-second answer window plus five seconds for response framing and scheduler
latency. That 305 s is bridge-side slack only — the operation itself is still
bounded by the server’s own 301-second REQUEST_TIMEOUT (see “Server Limits”
above), which is what actually resolves the call before the bridge’s wait would
matter.
ui action=toast sound. sound accepts true/false or a notification-sound
name: question, completion, error, warning, info, attention. true
resolves from level (info→info, warn→warning, error→error); a name overrides it.
attention is a triangular G4→G4→E5 callback meant for an agent working
unattended that is blocked on the user: two quick knocks followed by a longer
rise. An unknown name is an error, never a silently silent toast. The backend
resolves the name before emitting, so the toast event carries a concrete sound
and every client plays it through the user’s notification settings (volume,
output device, per-sound mutes) rather than inventing a tone. The event is
dual-emitted — Tauri emit for the desktop WebView and the event bus for
SSE clients; a bus-only send never reaches the desktop, which has no bus→window
forwarder.
ui action=toast urgency. urgency accepts normal (default) or urgent, the same names as agent action=send. Other values are rejected; the value rides the mcp-toast event on both transports. MCP toast notices show a transient card only while their origin terminal tab is active. Settings → Notifications → Show cards from the active terminal defaults on and is saved per client; turning it off restores urgent-only cards. Urgent notices always show a card, and notices without an origin session remain bell-only unless urgent.
The toast also resolves the calling MCP session to its peer project, PTY cwd, or
session repository metadata (in that order). The resulting origin_repo_path is
dual-emitted with the toast so clients can show its source and scope retained
bell history to the repository that raised it. Callers do not provide this field.
Alongside it the toast carries origin_session_id, the caller’s TUIC session,
taken from the same lookup. A repo holds many tabs, so the path alone cannot
navigate: this is what lets a client focus the terminal that actually raised the
toast when the user clicks it. It is absent for a caller that is not bound to a
PTY — an unbound caller gets no id rather than a guessed one, because a wrong id
would send the click to somebody else’s terminal.
Native responses omit optional values when they are unavailable. In particular,
session action=output includes exit_code only after an exit status is known, and
a session that TUIC kills or closes reports 128 + signal (for example 137), and its
exited state change and session action=wait until=exited also carry exit_reason
(kill_requested, idle_close, …); blocking wait timeouts return only the condition state without a repeated follow-up hint.
Native tool values are wrapped as compact JSON text in the MCP content envelope.
A proxied upstream value that is already a valid MCP CallToolResult object (an object
with a content array) instead becomes the JSON-RPC result directly, preserving its
content, isError, structuredContent, and any extension fields without mutation.
This applies both to direct {upstream}__{tool} calls and to the collapsed call_tool
meta-path. A malformed upstream value falls back to the native compact JSON text
envelope so the response remains protocol-valid and inspectable.
Agent task actions — long-running orchestration past the 300s ceiling
agent action=wait and session action=wait are server-side blocking long-polls
clamped to WAIT_MAX_MS (300 000 ms). An orchestrator supervising a peer that works
longer than five minutes cannot hold one open, and a client that drops mid-wait loses
the outcome entirely.
agent action=spawn therefore also returns a task handle:
{ "session_id": "…", "task_id": "…", "poll_interval_ms": 1000, "…": "…" }
The handle is polled with agent action=task_get instead of holding a wait open. This is
purely additive — every field a pre-task client already read keeps its name and type,
and a client that ignores task_id behaves exactly as before.
The retired task tool has no alias. Its saved denials migrate to agent_tasks,
which blocks agent task_get/task_cancel; disabling agent blocks all of its actions.
The grouped actions use the existing task handler and registry.
Lifecycle. A task is created working once the PTY is live (a refused or failed
spawn leaves none). Registration precedes reader startup, so an immediate exit
cannot outrun its task or parent link. Reader EOF releases terminal resources,
but the child wait owns settlement: only an observed zero exit completes the
task. Nonzero or unavailable status fails it. Both outcomes carry
result = {session_id, exit_code}; a failure also carries error_detail.
Signals use shell convention (128 + signal). Final terminal output remains
readable with session action=output within the existing 24-hour task collection
window, not just the ordinary five-minute terminal tombstone window.
| Status | Meaning |
|---|---|
working | The agent is running |
input_required | Waiting on input; still live |
completed / failed / cancelled | Terminal and immutable — never change again |
The vocabulary is the MCP 2026-07-28 Tasks vocabulary from day one, so the standard
tasks/* front door stays a serialization change rather than a semantic remap.
agent action=task_get returns {task_id, status, status_message?, result?, error_detail?, poll_interval_ms}, absent optional fields omitted. A failed task reports its reason in
error_detail, not error — a top-level error always means the call itself failed,
so reusing it would make a successful poll look like a broken one.
agent action=task_cancel marks the task cancelled and does not kill the agent
(session action=kill does that). Cancelling an already-finished task is not an error:
it reports the state that stands with cancelled: false, so a cancel racing the agent’s
exit never looks like a failure. Because terminal states are immutable, a cancel that
lands first is never overwritten by the later exit.
Ownership. A task_id is a capability over a spawned agent, so ownership is checked
before any state is returned or mutated: one agent cannot inspect or cancel another’s
children. A caller that spawned before registering is stamped with its pending id and
still reaches the handle after it auto-binds a TUIC identity. cancel additionally
re-checks the same owner guard as agent spawn (loopback or verified credentials); get is read-only monitoring and
stays open to authenticated remote clients.
Retention. Tasks live in memory for 24 h and are reaped by the existing
mcp_sessions reaper, not a separate timer. They are deliberately not persisted: the
case this exists for is a client restart, which the TUIC process outlives. Disk would
only cover a TUIC restart — and that tears down every PTY, so a recovered working task
would describe an agent that no longer exists.
ui tool — tab URL schemes
The url param of action=tab supports three schemes:
| Scheme | Behaviour |
|---|---|
http(s):// | Loaded directly in a sandboxed iframe; external HTTPS and localhost HTTP use the permissive default-src CSP. |
file:// | Read via IPC and rendered as inline HTML in a sandboxed iframe |
tuic://edit/<path>?line=N | Opens a native code-editor tab at the given file and line. Absolute paths require a // prefix: tuic://edit//Users/x/file.rs?line=42. Relative paths resolve against the active repo root. |
tuic://open/<path> | Opens a native markdown/preview tab |
Site X-Frame-Options and CSP frame-ancestors still apply. There is no per-directive CSP, including frame-src; http: and asset: in default-src preserve localhost wildcard ports and asset frames.
Custom URL schemes (vscode://, x-devonthink://, etc.) do not work inside iframes and must not be used with action=tab.
One tool family, and why the second one went
TUICommander exposes one MCP tool family: session, agent, repo,
workflow, automations, remote, secret, progress, ui, plugin_dev_guide,
voice, settings, debug. Few tools,
many actions.
It used to expose a second — 13 flat ai_terminal_* tools behind the
ai_terminal_mcp_enabled flag. They overlapped this family without being
equivalent, so a model that saw both had to guess, and paid for both catalogues
on every turn. Six of the 13 needed a per-session filesystem sandbox only the
embedded agent loop creates, so they refused every external caller before
dispatch. Deleted in story 789-f6ed; the tool-by-tool comparison behind it is
plans/ego-integration/archive/tool-family-comparison.md. The embedded agent loop that
created those sandboxes is itself gone (#784-0aec).
The surviving tool names are a public contract. They appear in users’ ego
rule files (allow 'tool(tuicommander/session)'), so renaming one silently
stops a user’s policy from matching — the call starts prompting, or stops. The
contract covers the tool names and the MCP server name. It does not cover
the action strings inside them: ego matches an action as an opaque argument, so
an action may still be added or renamed under the normal deprecation rules.
The three gates the deleted family carried, and where each landed:
| Gate | Outcome |
|---|---|
| Secret redaction on screen reads | Preserved, and widened. redact_secrets moved out of the condemned ai_agent module into crate::redaction and is now applied in session action=output — the screen read every client uses, Claude Code included, which never had it |
| Concurrent-writer interlock | Retired. Its only producer was conversation_engine::ACTIVE_CONVERSATIONS, i.e. the embedded agent loop. session action=submit guards more, not less: it refuses on session_not_found, not_managed_agent, partial_composer, awaiting_input, agent_not_ready and queued_commands_pending before touching the PTY. session action=input stays raw and unguarded, as it always was |
| Mandatory write confirmation (native dialog) | Deliberately dropped. AGENTS.md → Security Scope names agents driving TUIs a feature, not a risk to gate. A blocking native dialog is also unanswerable by a remote client — the exact defect that moved ui action=confirm onto the mcp-confirm event. A caller that wants a human gate calls ui action=confirm, which any client can answer |
Two capabilities have no replacement and were not reinstated: wait_for’s regex
and stability wait (poll session action=output with since_cursor instead),
and get_context’s compact summary.
Session aliases — Every action that accepts a session_id also accepts a
human-friendly alias (e.g. tu-1). Aliases are auto-assigned from the repo
directory name: a multi-word name contributes the first character of each
segment, a single word its first two characters (tuicommander -> tu), plus a
per-repo counter. session action=list includes the alias field.
An alias survives an app restart. The frontend persists it with the rest of the tab
state and replays it at create time; the backend reserves the requested alias when it
still has the <prefix>-<number> shape and no live session holds it, and raises the
per-prefix counter past it so the next auto-assignment cannot collide. A restored alias
is untrusted input, so a malformed or already-taken value is dropped and the session
gets a freshly minted alias instead.
MCP Tool: debug — invoke_js and the Debug Registry
invoke_js executes JavaScript in the WebView. Local IPC callers and token-authenticated TCP callers (for example the owner’s phone) can use it; the auth middleware and the Host/Origin boundary still refuse unauthenticated and foreign-site requests. It refuses while a private secret form is open. Results are logged with source='eval_js' and read via debug(action='logs', source='eval_js', limit=1).
POST /debug/reload_webview accepts local IPC callers and token-authenticated TCP callers, so the owner’s phone can recover a blank or blocked desktop window. It logs the caller address before asking the native WebView to navigate to its last healthy URL; only the bundled app origin or configured development origin can replace that saved URL. The navigation log names the http_route trigger, action, URL, and success state. The recovery thread and page-load hook use the same navigation path with their own trigger names.
window.__TUIC__ bridge — runtime introspection API:
| Method | Description |
|---|---|
stores() | List all registered store snapshot names |
store(name) | Get a store snapshot by name |
plugins() | All plugin states (legacy) |
plugin(id) | Single plugin state with manifest (legacy) |
pluginLogs(id, limit?) | Plugin log entries (legacy) |
terminals() | All terminal states (legacy) |
terminal(id) | Single terminal state (legacy) |
agentTypeForSession(sid) | Agent type lookup (legacy) |
activity() | Activity center sections/items (legacy) |
logs(limit?) | App log entries (legacy) |
Registered stores (via debug registry): github, globalWorkspace, keybindings, notes, paneLayout, repositories, settings, tasks, ui. New stores self-register — see src/stores/debugRegistry.ts.
Adding a new store snapshot — 2 lines at the end of the store file:
import { registerDebugSnapshot } from "./debugRegistry";
registerDebugSnapshot("storeName", () => ({ /* fields to expose */ }));
MCP Tool: session Atomic Submission
session action=submit session_id=<id> input=<command> is the managed-agent
command surface. It accepts only a confirmed-idle agent with an empty composer,
never queues, and keeps the PTY writer locked across Ctrl-U, a 50 ms gap, the
text (bracketed paste for multiline input), a second 50 ms raw-mode scheduling
gap, and Enter. Ctrl-U travels alone because Claude Code strips it from a long
text it treats as a paste and then refuses the Enter. The existing
InputLineBuffer, slash-mode tracking, submitted-input lifecycle, and
turn_epoch advance exactly once after the full write.
An ego empty composer painted after the last edit and quiet for 1.5 seconds
supersedes stale tracked input. Retained drafts and pre-edit screens still block.
Full local session action=list rows include queued_commands when entries
are parked, including server wakes, and queue_blocker when a current composer
gate prevents delivery. Ready observations retry existing queues and mail wakes;
rejected submits are never silently added to a queue.
session action=suspend session_id=<id> asks the UI to end a tab’s PTY and agent
while keeping the tab restorable like after a restart (the user resumes it from
the tab). It is refused with Cannot suspend: <reason> while the agent is
working, a question awaits input, compose commands are queued or a plain shell is
busy, for a session that already exited, and for the caller’s own session. The tab
performs the suspend after the session-suspend-requested event and answers through
session_suspend_response (POST /mcp/suspend-response, {request_id, ok, reason});
the MCP call returns that verdict: {ok:true}, or Cannot suspend: <reason> when the
tab refuses. It returns an error when no UI is attached (headless with no open event
stream) and when no tab answers within 20 s. Localhost clients only.
session action=keep_open session_id=<id> enabled=<bool> controls automatic
idle closure for a managed child. agent action=spawn keep_open=true sets the
same mark at creation, and agent action=send keep_open=<bool> changes it while
delivering a message. These actions reject a user-created session.
A terminal create may supply tuic_session and restored. HTTP accepts restored=true only once for an identity in the saved terminal snapshot captured at backend start; a new identity gets an uncapped root marker before launch. Resume a suspended session through its wake path. Creating a new worktree does not accept a restore claim.
agent action=spawn capabilities=[...] fixes the new agent’s capability set
(land, push, tag, children, progress, operator); a child defaults to none and a
capped spawner grants only what it holds. mcp_transport.rs refuses
agent spawn|launch, workflow launch (children), progress, and automation cutover, rollback and reconciliation (operator) outside the
caller’s set through capability_gate.rs with code: "capability_denied", and
mails the parent once per capability. The set lives in
AppState::agent_capabilities, written only by spawn; TUIC_CAPABILITIES
carries it to git for the pre-push hook. For a capped agent
agent_capabilities::apply_git_shim also sets core.hooksPath through
GIT_CONFIG_* to TUIC hooks that refuse a push outside the set and then run the
repository’s own hook (this survives login shells that reorder PATH), and puts
a git shim first on PATH for the --no-verify case (a login shell can move
it behind /usr/bin). See
Agent capabilities.
The handler then waits internally for child output beyond the offset captured immediately before Enter. One response returns:
| Field | Meaning |
|---|---|
submission_id | UUID for this call |
submitted / write_state | Whether the complete framed write finished; uncertain means retry may duplicate bytes |
acknowledged | Child terminal output moved after Enter |
retry_safe | True only when no byte was written |
turn_epoch | Epoch advanced by the shared input FSM |
composer_state | Composer safety verdict: cleared, partial, empty, or unknown; normally from InputLineBuffer, with fresh, settled native ego empty-screen reconciliation |
acknowledgement / reason | Terminal-movement evidence or the precise rejection/timeout |
detail | For pre-write rejections, a human-readable cause and corrective action; unknown agent identity includes the current foreground process |
Direct submits may answer an idle conversational question, including a
progress blocked report. That report is not a native dialog: its ranked
progress-blocked ownership permits an explicit command while server notices
remain parked. Ordinary low-confidence prose questions also permit submit.
Native selectors, approvals and free-text dialogs still return awaiting_input;
these refusals include prompt_kind (choice, approval, free_text, or
question). Explicit human replies retain their separate busy-dialog path.
The acknowledgement does not claim semantic application acceptance or task
success. Default acknowledgement timeout is 3,000 ms; callers may request
timeout_ms, clamped to 250–10,000 ms. ack_timeout, session exit after a
complete write, a superseding epoch, and an uncertain write all set
retry_safe:false. Partial composers, confident dialogs, busy/unconfirmed
agents, and older queued commands reject before the first byte. A peer that
arrives after the claim queues behind it; a peer that wins first makes submit
reject. Slash commands, including /clear, follow the same receipt contract.
session action=input remains the write-only compatibility surface. For an
identified agent, text with special_key=enter holds one PTY writer lock and
separates the text and CR with the agent Enter gap; Codex/OpenCode also use
the managed injection framing. Shell sessions and other keys retain raw pair
writes. Its ok:true proves PTY write only; it may prefill a composer or send an interactive key and
never returns a submission receipt. Never split command text and Enter across
two calls.
MCP Tool: session Output
The session tool’s action=output strips ANSI escape codes by default, returning clean text suitable for AI consumption. Pass format="raw" to preserve escape sequences (e.g. for terminal rendering). For managed peers, task results travel through agent action=send; raw session output is only the anomaly fallback when a child failed to send its result. The action=list response includes per session: foreground_process, shell_state, agent_state, tuic_session, and is_caller. is_caller=true identifies the managed PTY that owns the current MCP connection so an orchestrator does not close itself; it compares the caller’s identity against the PTY that identity is bound to, not against the PTY id. tuic_session is the stable identity the tab persists, so a caller can address a session across restarts. child_pid and foreground_pgid are no longer serialized — no MCP action accepts a raw pid, so they only enlarged every list response. background_work and standby appear only when true. Optional values such as alias, display name, cwd, worktree data, process identity, and agent state are omitted when absent rather than serialized as null; status follows the same omission rule.
Global overview: session action=list — one call; no per-session status fan-out.
shell_state is observed PTY activity (busy or idle); it is omitted before
the first lifecycle observation rather than treating a newly spawned agent as
idle. It is not task completion.
For detected agents, agent_state is starting, working, awaiting_input,
idle, completed, or error. error means the agent refused its last turn
(OSC 7770 state=error); automated submits are rejected with agent_error
until a submitted user line or native busy/prompt. background_work=true keeps agent_state=working while
a meaningful agent descendant is alive even when shell_state=idle and the
composer is ready; persistent integration helpers are excluded. Completion
requires the explicit end-of-task
suggest: [ ... ] protocol marker. A quiet ready prompt without that marker
remains idle. Spawned-agent lifecycle mail uses completed for the same
marker and reserves idle for an unclassified ready state.
| Param | Default | Description |
|---|---|---|
limit | 50 | Max scrollback rows, or source bytes for raw output. Whole logical lines and UTF-8 codepoints can extend a page beyond the limit |
format | (text) | "raw" preserves ANSI escape codes |
since_cursor | (none) | Forward page from a previous cursor (text: scrollback rows; raw: source bytes) |
from_line | (none) | Absolute text scrollback row; omit to read the tail |
from_byte | (none) | Absolute raw source-byte offset; omit to read the tail |
session action=input and HTTP POST /sessions/:id/write share the same raw PTY
bookkeeping: each write stamps last_input_ms and feeds the InputLineBuffer
so slash-mode tracking stays identical for MCP and remote web clients. When a
combined text + Enter request targets a prefill-only agent such as Codex or
OpenCode, MCP uses the legacy framed injection sequence (Ctrl-U, bracketed paste
for multiline text, a flushed scheduling gap, then CR). Other text/key pairs,
including Claude’s established input path, retain raw pair semantics. This
legacy combined form remains write-only; new managed automation uses
action=submit for the bounded receipt.
Orchestrated PTYs accept an optional pty_description field on
session action=submit and session action=input. It is independent from
last_prompt: the former is a
short description of the assigned work written by the orchestrator, while the
latter is the last substantial user prompt submitted to the agent. Omit the
field to keep the current description; pass a string to replace it, or null
/ an empty string to clear it. agent action=spawn accepts the same field for
the initial task. Updates are emitted as pty-description-changed over both
Tauri events and /events SSE.
Delta reads: The non-raw output path returns a cursor field (monotonic scrollback position). Pass since_cursor on subsequent calls to receive only new lines since that position, avoiding full re-reads. The total_written field is kept alongside cursor for backwards compatibility. When since_cursor is provided, screen rows are excluded — only scrollback log lines are returned.
Retained-output paging: Every window reports start_offset, oldest_offset,
has_more, next_cursor (null at the end), and truncated. A truncated response
includes continuation with the exact session action=output request for the
next page, or for older retained output when the default tail omitted history.
For text, start with from_line=oldest_offset and follow from_line=next_cursor.
The legacy absolute/tail cursor remains the total scrollback position; use
next_cursor, not that snapshot cursor, to page. Delta cursor stops at the
returned page boundary. For raw output, start with format=raw, from_byte=oldest_offset and follow from_byte=next_cursor; since_cursor also
accepts source-byte positions. Raw cursor is the returned page end and
total_written is the total original byte count, independent of redaction.
Explicit raw pages mask sensitive bytes with * using the complete retained
ring and terminal context before slicing, so even one-byte pages cannot
reconstruct a secret. Clean absolute and delta pages also discover secrets from the retained terminal
context, so a page containing only a multiline private key body stays masked,
including when its footer is still on screen and its header is in scrollback.
Tail snapshots retain the existing [REDACTED] format.
Owner literal reads (#2643-6b38): literal=true skips secret-shaped
pattern masking only when the owner granted literal reads for that PTY session
in the desktop tab context menu (set_terminal_literal_reads, IPC only). Every
response reports literal. Without the grant the argument is ignored. Literal
reads still mask registered and session-scoped secret values; raw pages mask
them over the whole ring before slicing. A byte-budget continuation of a
literal snapshot fails after the grant is revoked. GET /sessions/{id}/output
with format=mcp|mcp_raw and remote connections forward literal; the remote
host applies its own grant. Default reads, captures and persisted data are not
changed.
UTF-8 starts round down and ends extend to whole codepoints. Invalid PTY bytes
use lossy decoding without changing source-byte cursors. data_length counts
returned UTF-8 bytes, which can differ from the source range.
Buffers remain the only output store: text retains its configured scrollback;
raw retains up to 2 MiB. Output appended after a read is available on later
pages; this is not a frozen snapshot. A cursor older than oldest_offset starts
at the oldest retained position and adds missed_count (rows or source bytes).
Evicted output cannot be fetched. Exhausted/future offsets return an empty page.
The HTTP format=mcp|mcp_raw and remote MCP proxy use this same serializer.
Remote continuation notes also name the required connection_id.
MCP Tool: repo — Worktree Create (Claude Code Agent Hint)
MCP repo action=worktree_create uses the same creation path as HTTP
POST /worktrees, including base_repo validation, stale-worktree recovery,
cache invalidation, worktree-created SSE/Tauri events, setup-script result
reporting, and best-effort copy-on-write warming of Git-ignored directories.
Every created workspace is a linked worktree: Git refs and objects remain
shared with the parent, while instructions.warm_artifacts.warmed_directories
reports how many ignored directories arrived warm. Parent tracked changes are
not copied. See docs/api/http-api.md § Create Worktree; both transports call
the same shared core.
base_ref accepts a commit, branch or tag. An invalid ref fails before checkout
creation. An existing branch at another commit is a conflict, not a fallback.
The HTTP, MCP and desktop creation responses include base_commit, captured
from the allocated checkout before setup scripts run. spawn_session=true
starts its PTY only after this allocation succeeds; it cannot bypass a base error.
Connected daemons run this same handler on the repository-owning machine.
The lifecycle event includes creator_session resolved from the MCP binding,
never from a caller-supplied session id, and the requested spawn_session flag.
Without a spawn request, the same-repository creator is reconciled from its
reported cwd. A root coordinator does not move into a worktree merely because it
created it. Other tabs and the active workspace selection stay in place.
When the MCP client identifies as Claude Code (detected via clientInfo.name at initialize time), the repo action=worktree_create response includes an additional cc_agent_hint field:
{
"worktree_path": "/path/to/repo__wt/feature-branch",
"branch": "feature-branch",
"cc_agent_hint": {
"worktree_path": "/path/to/repo__wt/feature-branch",
"suggested_prompt": "Work in the worktree at `/path/...`. Use absolute paths for ALL file operations..."
}
}
This works around Claude Code’s inability to change its working directory mid-session. The hint tells CC to spawn a subagent that uses absolute paths for all file operations (Read, Edit, Glob, Grep) and cd <path> && ... for shell commands.
Non-Claude Code MCP clients do not receive this field.
The Git and worktrees launch module tells launch-capable agents to delegate or
parallelize through TUIC agent action=spawn/launch, never client-native
subagents such as Claude Code Agent/Task. The Claude Code cc_agent_hint path
above remains the CC-only exception for a single isolated worktree task. Clients
without a launch instruction channel receive the consistent delegation rule in
the cached MCP initialize prefix instead; launch-capable clients do not receive
a second copy through MCP.
MCP Tool: repo — Worktree List
MCP repo action=worktree_list returns each worktree’s branch, path,
kind, optional warm_artifacts, and lifecycle_status. lifecycle_status
uses the same classifier as the sidebar and repo action=worktree_lifecycle.
Inventory and per-checkout inspection run on the blocking pool. Listing reuses
its inventory and the sidebar’s ref-keyed integration proofs and cached GitHub
answers, instead of repeating unchanged integration subprocesses for every
checkout. GitHub evidence is cache-only on this request: a cache miss keeps the
conservative local classification, and normal monitoring can populate the existing
definitive-answer cache. Listing never starts a GitHub network lookup; this avoids
waiting on API pagination behind the native CLI response deadline. Fresh Git and
filesystem inspection can still take time, so this is not a hard wall-clock bound.
Dirt, fingerprints and submodule commit counts remain fresh; the
response fields are unchanged. If checkout HEAD differs from its branch ref,
listing classifies that HEAD freshly. Removal preflights remain uncached:
{
"feature-branch": {
"branch": "feature-branch",
"path": "/path/to/repo__wt/feature-branch",
"kind": "worktree",
"lifecycle_status": {
"dirty_files": 0,
"missing_checkout": false,
"commit_status": "merged",
"removal_safety": "safe"
}
}
}
commit_status is one of merged, unmerged, in_sync, or unknown.
removal_safety is one of safe, requires_force, or unknown. Both fall
back to unknown if inspection fails (lifecycle_status.error is set in that
case). This makes the same merged/dirty verdict worktree_lifecycle answers
per-branch available for every worktree in one call, so a caller does not
need to recompute merge state with its own git script.
MCP Tool: repo — Worktree Remove
MCP repo action=worktree_remove returns { "ok": true, "warnings": [...] } on full success. The warnings come from the same removal preview as desktop and HTTP, including branch history, live sessions, and local file counts. It
runs on the blocking pool and the local MCP bridge allows up to 305 seconds for
the response, covering linked worktrees with large ignored build artifacts.
Non-forced removal refuses staged, unstaged, or untracked work. The optional
MCP force boolean defaults to false; true is the explicit,
confirmation-gated authority to discard that worktree-only state. It does not
override a worktree lock or authorize deletion of unmerged commits. The
optional delete_branch flag defaults to true for a normal removal and
false when force=true; an explicit delete_branch=true still runs the
branch safety proof and may return a branch-retained warning. Unlocking a
locked worktree requires the separate override_lock=true flag and user
confirmation. Only an explicit lock override sends Git two --force flags.
Use repo action=worktree_lifecycle to obtain the fresh verdict and commit counts. The required expected_fingerprint binds force to that lifecycle snapshot; a
changed checkout status, HEAD, or submodule ref then stops removal. Initialized
submodule refs are preserved before Git removes the worktree.
When delete_branch=true and safe branch
deletion fails after a linked worktree is removed, the action still succeeds
with branch_delete_warning populated so clients can report that the worktree
was removed but the branch was kept.
MCP Tool: repo — Branch Integration Proofs
repo action=branch_integrations path=<repo> returns an array for all local
branches, including branches without a worktree. repo action=branch_integration path=<repo> branch=<name> returns one entry. Each includes:
branch,tip,default_branch,commit_status,integrated, andproof;archive_required,archived, andarchive_ref(refs/archive/<branch>);worktree_paths(including the main checkout when applicable), anderrorwhen classification cannot establish a verdict.
Proofs use the same classifier as workspace lifecycle, sidebar refresh, branch
panel and safe deletion. ancestry, integration_ancestry, patch_equivalence,
noop_merge, and squash_message are structural evidence. A squash message
must list every branch subject, either directly or as GitHub * subject
bullets, and a clean virtual merge must also leave the target tree unchanged.
github_pr retains the verified fetched-head proof. The in_sync status means
no own commits need integrating; it returns integrated: false and proof: null,
not a positive merge proof. The UI still excludes same-tip branches from its
merged list.
content_superset is a heuristic: exact same-subject twin patches ignoring
only context and hunk coordinates, or 100% of added lines present with their
multiplicity in the same regular files at the target tip. The latter rejects
deletions, changed modes, binary files and incomplete final lines. Neither
subject matches alone nor a partial percentage proves integration. An archive
at the exact current tip is required before deleting a branch with this proof.
integrated does not mean a checked-out or protected branch can be deleted.
Unknown verdicts never authorize deletion. The query itself changes no refs,
index or working files; Git virtual merges may write unreachable Git objects.
Cleanup tools must query this MCP surface instead of duplicating Git checks. Refresh the query after archiving; deletion performs a fresh safety check.
MCP Tool: repo — Local Branch Delete
repo action=branch_delete takes path and branch and returns
{ "ok": true, "proof": "..." } on success. It deletes only the local branch
ref; it does not remove a worktree or touch a remote ref. The branch must be
absent from every checkout and must not be the current integration or default
branch. The shared integration proofs described above apply. Content-based proofs
require an archive ref at the current tip (the primary refs/archive/<branch>
or its tip-suffixed variant). When the proof is archived, the response also
includes archive_ref, captured before deletion and naming the ref that holds
the deleted tip. An archived unmerged tip
also remains deletable through the existing archived recovery rule; that
does not change its integration verdict. Merge resolution changes are never
proved by git cherry or a same-subject twin comparison alone. The final
delete compares the ref against the proved tip and refuses a moved ref.
Upstream MCP Proxy
TUICommander can proxy upstream MCP servers (stdio or HTTP) and aggregate their tools into its own tools/list response. Configuration lives in mcp-upstreams.json.
Upstream configuration save contract
IPC save_mcp_upstreams and HTTP PUT /mcp/upstreams both accept
{ base, config, credentials? }: the snapshot the caller loaded, its desired result, and optional write-only secrets for newly added servers. The
backend indexes servers by stable id, derives the semantic base-to-desired
delta, and applies that delta to the latest on-disk configuration inside the
cross-process ConfigFile lock. It validates and atomically persists the merged
result while still holding that lock instead of replacing the file with a stale
UI snapshot.
Add-time credentials identify their new server by server_id. The locked merged config is validated before any vault writes. Existing vault entries are never overwritten by an add; failed partial writes or config persistence roll back new entries. The standalone credential endpoint defaults to refusing replacement and accepts replace: true for an explicit edit.
Absence has explicit semantics relative to base: omitting a former server from
config removes that ID, and omitting its former optional auth field clears
the auth value. Unchanged fields are not part of the delta, so concurrent edits
survive; in particular, a stale UI save cannot erase OAuth/DCR auth written
concurrently for an otherwise unchanged upstream. Concurrently added servers
also survive unless the caller independently adds the same ID, which is rejected
as a conflict.
Bearer, OAuth and secret-header vault entries store the intended MCP origin with the secret in one write. The HTTP credential resolver checks that binding before every request and before OAuth refresh; a mismatch sends no request and reports an origin error. Entries saved before origin binding require re-saving or authorization. Config saves cannot rebind existing credentials, even if auth metadata is cleared or an ID is replaced. The Settings form keeps its early origin-change rejection for a clear message: add an upstream with a different name for a different provider. Same-origin path edits retain auth metadata. OAuth refresh preserves the MCP origin captured at authorization, independently of the authorization server and RFC 8707 resource URLs.
Persistence returns the exact configuration immediately before and after the
locked mutation. Once the lock is released, apply_config_diff uses that exact
pair to disconnect removed or changed upstreams and connect added or changed
ones, so the live registry hot-reloads precisely what the atomic write changed.
The desktop boot thread owns the always-on Unix-socket/named-pipe listener and its one-time background tasks for the lifetime of the process. A configuration save may stop and replace the TCP listener, but the boot runtime remains parked after that shutdown so dropping it cannot silently kill local bridge IPC.
PTY children receive TUIC_SOCKET from the server’s actual bound Unix socket
path. This includes named tuic-remote --instance sockets and collision
fallbacks. tuic-bridge honors this environment override before instance-based
socket discovery, keeping child MCP calls on the spawning server.
Stdio transport
StdioMcpClient spawns a child process and communicates via newline-delimited JSON-RPC over stdin/stdout. The handshake is: initialize → notifications/initialized → tools/list.
RPC id-matching. The rpc() method matches responses by JSON-RPC id, skipping any server notifications (messages without an id field) that arrive between request and response. This prevents silent “0 tools” when a server emits notifications/tools/list_changed or log messages during the handshake.
Health recovery. Two consecutive failed tools/list health RPCs retire a live but unresponsive child. A successful health RPC resets this failure streak. The next scheduled health probe spawns and initializes a replacement under the existing five-second minimum respawn interval. An ordinary tools/call reply timeout does not count toward this policy, kill the child, cancel the action or retry it: its external outcome remains unknown. Monotonically increasing request IDs keep late replies isolated. A write timeout still tears down the child because the request frame may be partial.
Tilde expansion. All user-supplied paths (command, args, cwd) are expanded via crate::cli::expand_tilde() before being passed to std::process::Command. This applies globally across the codebase — PTY, agent spawn, headless prompts, worktree scripts, plugin exec, and file validation all expand ~ to $HOME.
HTTP transport
HttpMcpClient communicates via Streamable HTTP (POST to the server URL, mcp-session-id header for session affinity).
Bearer credential generations. resolve_bearer() re-reads the credential on
every request attempt so a completed re-authorization takes effect immediately;
the credential vault already caches the decrypted value process-wide, so this
does not repeat the OS keychain prompt. A 401 recovery passes the exact bearer
rejected by the server into the serialized refresh check. If storage now holds a
different valid generation, that credential is retried as-is; only the rejected
or invalid generation is refreshed at the authorization server.
Health checker
A background task runs every 60s (HEALTH_CHECK_INTERVAL) and calls tools/list on every Ready upstream. Failures feed a circuit breaker (3 consecutive failures → backoff starting at 1s, capped at 60s, max 5 retries before permanent Failed). Recovery from CircuitOpen, Connecting, or Failed is attempted on each tick.
Diagnostics
Both transports log warn! when tools/list returns a response without result.tools — making “0 tools” diagnosable instead of silent.
OAuth 2.1 Upstream Authentication
When an upstream MCP server requires OAuth instead of a static Bearer token, TUICommander runs a full RFC 9728 (Protected Resource Metadata) + RFC 8414 (Authorization Server Discovery) flow with PKCE S256.
Configuration
UpstreamMcpServer.auth is an enum:
#![allow(unused)]
fn main() {
enum UpstreamAuth {
Bearer { token: String },
OAuth2 {
client_id: String,
scopes: Vec<String>,
authorization_endpoint: Option<String>, // None → discover
token_endpoint: Option<String>, // None → discover
},
}
}
Missing endpoints trigger metadata discovery: the proxy issues an unauthenticated probe, follows the WWW-Authenticate: Bearer resource_metadata=<url> challenge to fetch ProtectedResourceMetadata, then resolves the authorization server’s .well-known/oauth-authorization-server (falling back to OIDC .well-known/openid-configuration when required).
Error → flow transition
src-tauri/src/mcp_proxy/http_client.rs emits a typed error:
#![allow(unused)]
fn main() {
enum UpstreamError {
NeedsOAuth { www_authenticate: String },
AuthFailed,
Other(String),
}
}
A NeedsOAuth on any request transitions the upstream registry to needs_auth. The MCP page in Settings (Upstream MCP Servers) surfaces an Authorize button that calls start_mcp_upstream_oauth. Auto-triggered OAuth is gated behind explicit user consent (the confirm dialog shows the AS origin so the user can refuse an Authorization Server mix-up attempt).
Off-domain authorization servers are never blocked. MCP gateways, corporate proxies and hosted IdP tenants routinely serve AS metadata whose issuer and endpoints point at a different registrable domain than the MCP server — RFC 8414 §3.3 says the issuer must match the discovery URL, but refusing on that basis makes legitimate servers unusable. Discovery logs a warning on an issuer mismatch and continues; start_mcp_upstream_oauth returns cross_domain_as: true when the AS is off-domain, and the consent dialog switches to a warning kind naming the origin. The decision belongs to the user, not to a hard-coded gate.
Flow
-
Start —
start_mcp_upstream_oauth(name)generates a PKCE verifier/challenge (S256), mints an opaquestate, records the pending flow in a DashMap keyed by state, and returns the authorization URL + AS origin. The upstream moves toauthenticatingonly after the flow is recorded — the status must never claim “Awaiting authorization…” for a flow that does not exist.Flows are not serialized. Each one owns its
statenonce, PKCE verifier and callback port, so concurrent authorizations share nothing. An earlier design held a single-permit semaphore for the whole browser round-trip: a second Authorize click then blocked insidestart_flowfor the full 5-minute timeout with no browser, no dialog and no error, andcancel_mcp_upstream_oauthcould not release it because the queued flow had never reached the pending map. Do not reintroduce a shared permit here. -
Consent UI — The frontend opens the URL via
tauri-plugin-openerafter user approval. The status bar and the Settings MCP page show “Awaiting authorization…”. -
Callback — The AS redirects to
tuic://oauth-callback?code=…&state=…. The OS routes the deep link to the desktop app (src-tauri/src/mcp_oauth/mod.rs—DEEP_LINK_SCHEME = "tuic://oauth-callback"). The deep-link handler callsmcp_oauth_callback(code, oauth_state). -
Exchange —
TokenManagerposts code + PKCE verifier to the token endpoint, receives{ access_token, refresh_token?, expires_in? }, serializes intoOAuthTokenSet, persists to the OS keyring (mcp_upstream_credentials.rs— structured JSON format with"type": "oauth2"), and transitions upstream toconnecting. -
Refresh —
TokenManageris shared across everyHttpMcpClientrefresh path (unified per upstream); a semaphore serializes concurrent refresh attempts to defeat thundering-herd.expires_atuses a 60 s margin;Nonemeans “no known expiry — do not treat as expired”. A 401 recovery carries the exact bearer rejected by the server into the serialized refresh check. If an authorization exchange wrote a different valid credential between the request and recovery, that generation is retried as-is instead of being immediately refreshed or rotated; only the still-rejected or an invalid generation reaches the token endpoint.
Callback server lifetime
The localhost callback server outlives the flow it serves — flow timeout plus a 120 s grace period (CALLBACK_SERVER_GRACE in mcp_oauth/commands.rs). A successful callback still closes it promptly, 2 s after the response is served.
It used to shut down as soon as the flow left the pending map. A user who spent more than five minutes at the identity provider — MFA, password manager, account picker — then redirected back to a closed port and got the browser’s own “can’t connect to the server” page, with nothing saying the request had expired. Outliving the flow means handle_callback can answer a late redirect with a page naming the reason and the retry step.
Expiry sweep
A background sweep (spawn_cleanup_task) drops pending flows past the 5-minute timeout and returns each one’s upstream name so the registry can rollback_authenticating it back to needs_auth. Without that rollback an abandoned flow left its upstream on authenticating permanently, with no path to a retryable state.
Cancel
cancel_mcp_upstream_oauth(name) drops the pending flow entry and resets the upstream status to whatever it was before the attempt (disconnected / failed / ready).
Deep-link scheme
| Scheme | Purpose |
|---|---|
tuic://oauth-callback?code=…&state=… | OAuth 2.1 authorization code return path for upstream MCP servers |
Registered at boot via Tauri’s single-instance + deep-link plugins. The frontend listener routes callbacks to mcp_oauth_callback without exposing the code to the WebView console.
Threat model
OAuth callbacks arrive on a loopback HTTP server bound to 127.0.0.1:0 (OS-assigned port), spawned per flow by start_mcp_upstream_oauth; the tuic:// deep link is the manual fallback. Neither path is reachable from the network, so there is no adversary position from which a remote attacker can probe the pending-flow map, and state comparison uses a direct DashMap lookup (no constant-time compare).
Inter-Agent Messaging
The agent tool’s messaging actions (register, list_peers, send, inbox) enable coordination between multiple AI agents connected to TUICommander.
There is no separate swarm action; orchestration composes the agent and session primitives.
For agent action=spawn, prompt is always delivered. The per-agent
prevent_alt_screen setting controls the screen flag on every launch path,
including MCP spawn; there is no per-spawn screen override. MCP spawn rejects
the removed allow_alt_screen and allowAltScreen parameters.
skip_trust_dialog defaults to true for Claude and Codex MCP children. It is a per-agent setting, not an MCP parameter. Codex receives -c projects."<canonical cwd>".trust_level="trusted" for this launch, including when a custom launcher forwards its arguments; Claude’s managed PTY answers only its exact startup trust question while No, exit remains selected. An ego child receives --trust-workspace (ego remembers that answer for the workspace). User-opened terminals and saved CLI trust files are unaffected.
An ego MCP child also receives --mcp @<attachment dir>/ego-tuic-mcp.json: one ego invocation-scoped stdio server named tuicommander that runs tuic-bridge, with the TUIC_SESSION, TUIC_SOCKET, TUIC_APP_INSTANCE and TUIC_CONFIG_DIR variables that the child environment holds. The same launch also receives --mcp-only (ego 0.4.11 and later), so the enabled MCP servers of the owner’s ego configuration stay detached: a configured TUICommander server would publish the same tool names and reach the owner’s app instead of the instance that spawned the child. A caller that passes its own --mcp or trust option keeps it; a wrapper binary (not named ego) and ego’s non-run verbs receive neither option. Without a tuic-bridge binary the child starts with no TUICommander server, and a warning is logged.
Child contract. When the caller is a registered peer, TUICommander reads .tuic-child-contract.md from the caller’s PTY working directory (normally its repository root) and inserts it as ## Child Contract between the multi-agent context and ## Your Task. Every host (ego, Codex, Claude) then gives its children the same rules, however short its own brief is. The file uses the .tuic-start-work.md rules: it must stay inside that directory, {{token}} substitution runs once and unknown tokens stay literal. Tokens: {{name}}, {{session_id}}, {{parent}}, {{cwd}} (the child’s), {{agent_type}}, {{model}} (empty when unknown). Without the file the prompt is unchanged; an unreadable file or a link out of the directory fails the spawn before any process starts.
Caller-supplied args that contain {prompt} remain authoritative and receive direct substitution.
Flags-only args keep their order; normal CLIs receive the prompt as the final
positional argument, while prefill-only interactive TUIs receive it through the
deferred PTY-injection path after their ready prompt appears.
Configured run-config argv retains its established authoritative behavior:
{prompt} is substituted where authored, otherwise the prompt is appended as
the final positional argument rather than converted to deferred PTY delivery.
Structured model is composed with args; a matching run config can supply a
default model, overridden by the spawn parameter. Existing --model in
run-config args stays authoritative and conflicts with an explicit model
parameter. Literal codex selects the persisted default run configuration,
including its editable approval-bypass argument. Only direct interactive Codex
defaults defer the task through PTY injection; wrappers and subcommands retain
run-config positional or placeholder task delivery. A Codex exec, e, or
review subcommand is recognized only as the first positional argument before
--, after skipping root options and their values. Profiles or models named
review, exec, or e keep interactive task submission. Direct executable identity
also selects Codex parser state when agent_type is omitted or disagrees.
Composition never restores a removed bypass. Wrapper configs receive
launch_warning because TUIC cannot validate their internal Codex flags.
The optional env map uses the same field name and string values as HTTP
POST /sessions/agent and desktop IPC spawn. Its values override run-config
environment values. TUIC applies TUIC_SESSION and TUIC_PARENT afterward,
so callers cannot replace peer identity. Environment values are redacted from
spawn logs.
Managed Claude peers default to CLAUDE_CODE_TMPDIR=$HOME/Gits/.tmp/claude/; TUIC creates this directory before spawn and preserves an explicit inherited, run-config or caller value.
name optionally assigns a non-empty peer and PTY display name at spawn time, pinned against later intent: and OSC titles.
The parent-assigned name is stored before prompt delivery, returned in the spawn
response, exposed as name by agent action=list_peers and as display_name
by session action=list, and preserved when the child later auto-binds its MCP
connection. This avoids making identity depend on the child successfully
executing a registration instruction in its initial prompt.
The session list’s alias remains a separate repo-derived short address and is
not replaced by the display name.
The optional pty_description field on agent action=spawn populates the
orchestrator-owned task description shown above the PTY. When the caller’s
orchestration schema cannot supply that field, spawn derives display-only
metadata from the normalized task prompt (capped at 160 characters); an
explicit string still wins, while null or an empty string explicitly keeps
the new PTY descriptionless. The inference never changes prompt delivery or
agent-specific launch semantics. Later session action=input calls may update
the same field without adding another command to the MCP surface.
Every managed child is registered server-side and receives an inbox immediately,
even when the caller has no bound peer identity. Spawn binds the child’s PTY
to its own $TUIC_SESSION, so session-list rows show the child identity before
its first MCP connection or register call. A registered parent additionally
creates the bidirectional relationship: the child prompt receives its parent ID
and send instruction, while the spawn response returns parent_session_id. An
unregistered caller gets no parent_session_id and a warning instead of a false
two-way guarantee. communication_ready, send_to and peer_registered are gone:
the first two restated parent_session_id, and the third restated that TUIC always
registers a managed child.
The spawn still records the caller’s MCP session as a pending parent: a later
register call links existing children to the stable parent UUID and migrates
any lifecycle notifications emitted before registration.
Deferred initial prompts use a one-shot internal watchdog. Successful PTY
submission removes the marker silently. A prompt still pending after 30 seconds
emits one prompt_delivery_failed message to the parent (retrying: true). A
later confirmed submission sends prompt_delivered. A submission that was typed
but not confirmed on screen also removes the marker, because the prompt is never
typed twice; after a warning it sends prompt_unconfirmed (retrying: false).
There is no delivery polling or public delivery-state machine.
Ordinary managed-agent PTY injection is allowed only when the recipient is idle, its composer buffer is empty, and no confident question or approval is active. Busy workers and recipients with partially typed input keep the message queued. Clearing or submitting the composer rechecks the queue.
An orchestrator role is declared explicitly with
agent action=register orchestrator=true and removed with orchestrator=false; spawning a child never
infers or permanently grants the role. The declaration is returned by register
and list_peers. A list_peers entry carries tuic_session, name,
orchestrator and is_caller (true only on the row of the calling session, as in
session action=list; a hub-linked daemon marks no row), plus alias and session_id when the peer owns a live terminal —
the two fields that make an answer from list_peers directly usable as a to or a
session_id. registered_at and mail_wake are no longer per-entry, and the
top-level count is gone: the array’s own length already reports it. Its routing is intentionally stricter: every peer and
child-lifecycle message remains in the authoritative inbox, and peer payloads
never enter its channel, active turn, pending-injection queue, or composer. An
active agent wait owns delivery and suppresses terminal wake. Without a waiter,
canonical idle or completed lifecycle may submit the payload-free notification
[TUIC] message available — read it with: agent action=inbox. A derived working
state may submit the same notice only when the existing composer-safety gate proves
the shell is idle, readiness is confirmed, and no question or partial input owns the
composer. This covers reconciled background descendants without weakening the
gate for an active turn. A pending process probe still waits for its existing
settlement retry before a wake is eligible.
One exception, and it is narrow: when every message in the reserved window is a
server-authored lifecycle notification (tuic-auto-*), the notice types those
events instead of pointing at them — [TUIC] child agent 8c261794 is now idle; child agent 8c261794 exited (exit 0) — and acknowledges its own window, so the
orchestrator owes no inbox call for it (delivery_path
lifecycle_summary_and_inbox). A lifecycle payload is a state name generated by
TUICommander itself, so this exposes nothing a peer authored. A single peer
message in the window disqualifies the whole group back to the generic notice:
a partial summary would satisfy the reader and silently bury the rest. The
summary also falls back when it would exceed 240 characters. Mail that coalesces
while the summary is being typed falls outside the acknowledged window and
earns its own notice. Busy or otherwise non-quiescent working sessions,
awaiting-input, starting, missing, and unknown state fail closed to inbox-only.
Mail received while working remains eligible and is re-evaluated at the next
authoritative idle/completed transition. One pending wake covers later unread
mail through its logical inbox cursor. Inbox and successful wait observations
acknowledge the same cursor atomically with their snapshot, including an empty
snapshot, so a read cannot race a delayed wake assignment. A generic notice never
hides the underlying payload from a later wait. PTY I/O happens outside the
delivery gate. An ambiguous payload-free notice expires after five seconds and
may be retried once after the managed lifecycle reconfirms readiness. A second
uncertain result exhausts that unread-mail group’s wake budget: later expiry or
idle/completed reevaluations, including newly coalesced mail, remain inbox-only
until a successful inbox or wait observation acknowledges the group. An attempt
that writes no bytes remains NotStarted and does not enter an automatic retry
loop: it exhausts the budget for that lifecycle, so nothing reclaims a composer
that just refused the claim. A new BUSY→IDLE edge re-arms the budget before it
chases the outstanding notice, because the lifecycle that refused is not the one
being retried — without that, one draft in the composer, one open question or one
unconfirmed idle would silence the wake for the rest of the session and the mail
would never be announced. A notice already in flight keeps its attempt; the
re-arm cannot take it.
register also returns mail_wake. Its only current non-none
value is managed_pty_lifecycle, derived from a live TUIC-managed PTY rather than
claimed by the caller. Headerless/external orchestrators have a mailbox and MCP/SSE
transport but no authoritative model lifecycle or host wake adapter capable of
starting a turn, so they honestly report mail_wake: "none" and must use
agent wait/inbox. MCP activity and SSE presence are not treated as idle proof.
The final injection decision atomically claims idle -> busy, closing the race
between observing a ready screen and writing to the PTY. Idle is published before
the queued-message flush, and each idle transition submits at most one queued
message; remaining messages wait for later turns. This keeps backend state and UI
events ordered and prevents lifecycle reports from overwriting an active composer.
Peer messages and Compose commands occupy one typed FIFO, so neither producer can
overtake an earlier accepted entry. The Compose queue count and clear operations
select only user-command entries; clearing them retains peer messages and their
relative order.
Raw PTY Capture Diagnostics
POST /diagnostics/capture controls the off-by-default raw-stream tap used for
agent-state regression evidence. { "enabled": true, "session_id": "<id>" }
records one session; omitting session_id records all sessions, and
{ "enabled": false } stops it. GET /diagnostics/capture returns the active
filter, output directory, and byte count per opened session. A new enable starts
fresh files, and each <config dir>/captures/<session-id>.tcap file is capped at
512 KiB. Records preserve direction, original read/write boundaries and monotonic
timestamps; legacy .raw fixtures remain readable as output-only captures.
Set TUIC_CAPTURE_DIR to an absolute path before starting the server to place
captures there instead. A relative value rejects activation with an error
field and leaves capture disabled.
Capture must be enabled before reproduction. /sessions/:id/output is not a
fixture-acquisition fallback: its bounded ring can lose a one-shot marker and its
JSON string is lossy UTF-8. Negative and positive captures belong in
src-tauri/src/fixtures/agent_prompts/ and are replayed through the same raw plus
rendered-row composition as the reader thread.
The stdio bridge reads each IPC HTTP response through its declared
Content-Length rather than waiting for connection EOF. A single transport error
does not discard the current MCP identity; subsequent authenticated calls refresh
the session-to-terminal binding. Ordinary calls keep a ten-second read deadline;
direct and collapsed wait calls derive it from the clamped requested timeout plus
a five-second transport margin.
Focused ui action=tab requests using tuic://open or tuic://edit switch to
the registered repository that owns an absolute target path before activating
the native file tab. This keeps repo-scoped tabs visible in the tab bar instead
of rendering their content under an unrelated active repository. Background
requests (focus=false) do not change repository context.
Absolute files outside a registered repository and HTML/URL tabs use the MCP
caller’s registered repository as their tab scope, even when another repository
is visible. A focused request switches to that repository; focus=false
preserves the visible repository. If the caller has no registered repository,
these tabs fall back to the currently active repository.
These tabs remain in the existing tab stores while another repository is
selected. Unpinned tabs reappear when the opening repository is selected again;
pinned MCP tabs remain visible across repositories. Unpinning restores the
opening repository scope.
Native Markdown tabs opened through ui action=tab survive UI document reloads
within the same window, including native recovery without a working unload
handler. The frontend snapshots tab changes synchronously and restores their
target, scope, pin state and selected tab from session storage; reopening the
same MCP id updates that tab.
Closed tabs are not restored. This does not persist tabs across app restarts.
Native file tabs use the MCP id as their identity, so distinct ids do not
collapse onto one file-path tab and repeating an id updates its target. The tab
bar also keeps repo-scoped tabs visible when a repository has no active workspace.
Protocol
-
Auto-identity (no call needed): TUICommander’s Codex MCP entry explicitly whitelists
TUIC_SESSIONthroughenv_vars; other supported clients inherit it from the agent PTY.tuic-bridgesends the value as thex-tuic-sessionheader on the initializePOST /mcp. The server validates the UUID and binds the MCP session to that tuic session (apply_initialize_identity→ the shared locked live-owner policy), auto-registering the peer.agent action=registerbecomes an optional rename. A client that scrubs the bridge’s environment (ego launches stdio MCP servers with only its config’sinherit_env) sends no header; on initialize the server then walks thex-tuic-client-pidancestry for the nearest process holding a well-formedTUIC_SESSION(identity_from_client_ancestry) and binds that. An ancestry process markedTUIC_BG_COMMAND=1orTUIC_CONTEXT_ISOLATED=1stops recovery before its identity is read. The latter is set by the Unix shim for independent redirected ego advisors, whose inheritedTUIC_SESSIONis removed. It remains on the advisor even if the advisor scrubs the bridge environment. An asserted header always wins. The same MCP session may refresh its binding, and a fresh session may reclaim a stale owner; a subscribed or recently active owner is not replaced but is joined, so a second bridge in the same PTY becomes routable instead of being locked out. An existing peer’s display name is preserved. The bridge’s eager initialize and the downstream client’s proxied initialize reuse the same existingmcp-session-id; this prevents the bridge’s own live SSE stream from being mistaken for a competing identity owner. External bridges without$TUIC_SESSIONare not auto-bound at initialize. -
Register: optional rename/project/role update for an auto-bound peer. Pass
orchestrator=trueto declare the role orfalseto remove it; omission preserves the current declaration. A headerless external caller may omittuic_session; the server generates an MCP-scoped UUID that remains stable for that connection and does not create a PTY. Supplying an explicit UUID preserves identity across reconnects and retains the live-owner takeover guard, which now refuses only callers that hold no route to the identity — a bridge already joined to it is renaming, not taking over. When the announced UUID differs from the one already bound to the MCP session, the two are ranked by whether they resolve to a live PTY rather than merely compared: an identity backed by a terminal outranks one that is not. A caller that registered an invented UUID may therefore repair itself by announcing its real$TUIC_SESSION, while the reverse — wandering off a terminal-backed identity onto a fabricated one — is refused with an error naming the identity to use. Two identities that both lack a terminal keep the original “already bound to a different peer identity” rejection. A repaired identity carries over any mail buffered under the abandoned one and retires it, solist_peersstops advertising an address that can never be reached. The retire and the recipient check insidesendshare one identity lock, so a message aimed at the abandoned identity either arrives before the retire and is carried over with the rest of the inbox, or arrives after it and is refused with “is not registered” — it is never buffered under an address that is deleted a moment later.That carry-over only has an implicit trigger when the same protocol session rebinds. A caller that reconnects and registers a brand-new UUID arrives with no link to its old identity, so it must name it:
register replaces=<old_uuid>. Identity is never inferred from a name or project — it decides who may read whose mail. The response reports the outcome instead of staying silent:superseded_identityplusmail_migrated, and — when the superseded identity still owns a live PTY —mail_strandedand anidentity_warning. That last case deliberately moves nothing: an identity with a terminal is a reachable peer, and taking its inbox would strand a working agent. -
Discover:
agent action=list_peersreturns all registered peers (filterable by path). -
Send:
agent action=send to=<address> message="..."buffers to the recipient’s inbox.totakes the peer’stuic_session, its registeredname(aslist_peersprints it; two peers with one name are refused with the candidates), the id of the PTY it runs in, or that terminal’s alias.deliveredis the verdict anddelivery_pathis the single source of truth for the route and distinguishes SSE, terminal-or-queued, waiter, subscribed ACP inbox resource, generic/coalesced orchestrator wake, and inbox-only delivery. It replaceddelivered_via_channelon this response, which reported only the SSE sub-route yet read as a delivery verdict —falsenext to adelivered:trueand a confirmingdelivery_pathwas pure ambiguity. The field remains on the storedAgentMessageas in-memory forensics but is#[serde(skip)]— it reaches no MCP response at all, includinginbox/wait. Emitting it to the recipient repeated the same trap: it isfalseprecisely when a waiter or the terminal carried the message, and the recipient reading it is already holding the message it describes. The route isdelivery_pathfor the sender and theagent_msgtracing line for the operator. When the recipient is a real managed PTY,recipient_statecontains only its currentshell_stateandagent_state; external generated peers omitrecipient_state. -
Receive — the following paths surface buffered mail:
- Forced steer:
agent action=send urgency="urgent"(interruptis an alias) buffers the body first, then uses the same flow as Chat Send now and Compose Steer. A safe working Claude Code, Codex or ego receives Escape; TUIC reserves the next ready composer against FIFO drains and mail wakes, waits up to 10 seconds for independently confirmed idle, then submits the full body. An idle session skips Escape. This applies to registered orchestrators and running Stop hooks. Dialogs, drafts, an unknown owner or uncertain prior input block delivery; a dialog or draft appearing during cancellation aborts it. Refused forcing stays inbox-only, never ordinary busy Enter or a queued wake.urgent_deliveredandinterrupt_deliveredreport a written input, not model action; failure includes both fallback reasons.delivery_path=interrupt_payload_and_inboxidentifies full-text delivery. An active waiter can own the body without interruption. Ambiguous payload writes never replay. Interrupted tools can leave partial work or running children; this is not a process-tree kill. - Channel push:
notifications/claude/channelis available to external Claude Code clients with an active SSE stream and no managed PTY. It is a best-effort notification; the inbox remains authoritative. - ACP inbox resource: a terminal-less peer with a live MCP-over-ACP connection subscribed to
tuic://inboxreceivesnotifications/resources/updatedand can read its mail. Normal and urgentagent sendreportdelivered=trueanddelivery_path=acp_inbox_resourcewhen no waiter or other route owns the message; urgent send also reportsurgent_delivered=true. This includes peers registered as orchestrators. After disconnect or without the subscription, the response reportsinbox_onlyunless another route owns the message. An idle ego may also be woken by the ACP host. - Normal PTY notice: an ordinary managed agent receives a payload-free
agent action=inboxnotice when its composer is safe, or on its next safe idle transition. A busy turn, question, or partial draft is left untouched. Managed Claude peers use this path even with an active SSE stream, because a channel push during one turn cannot start a later turn for unread mail. An idle/completed orchestrator receives the coalesced inbox wake described above; so does a confirmed-ready, empty composer whose task state remains working only because of background work. A busy, questioning, or partially typed orchestrator is never queued or steered by normal mail. - Inbox poll:
agent action=inbox— always the authoritative store.
- Forced steer:
-
Wait (prefer over polling):
agent action=waitblocks until new mail;session action=wait session_id=<id> until=idle|exitedblocks on a peer’s lifecycle. The default is 60 seconds and the advertised cap is 300000 ms — a request at or above that runs as 295000 ms. The 5-second margin exists because a client aborts its owntools/callon its own deadline, and at least one shipping client (Codex) uses exactly 300s: a wait running the full cap would answer right on that deadline and return a client-side error instead of{timed_out:true}, making the advertised maximum unusable. The clamp is deliberately client-agnostic — a per-client table would need maintaining against every client release, and ending 5s early is invisible to the caller. Agent-wait success preserves{met,timed_out,new_messages}and directly includes every retained fresh message (up to the 100-message inbox capacity) plusnext_since, in chronological order. Per-recipient logical unix-millisecond cursors make equal-clock-millisecond bursts safe.The cursor is kept server-side.
sinceis optional on bothwaitandinbox: omitting it resumes from the caller’s stored read position (agent_read_cursor), passing it overrides, andsince=0stays the deliberate “replay everything” escape hatch — a replay never rewinds the stored cursor.next_sinceis now returned on every response, timeout included, falling back to the stored position when the batch is empty. Previously it was omitted whenever there were no messages, which left a timed-out waiter withsince=0as its only recoverable value and made it reload the whole history on the next call. Wait never consumes the authoritative inbox; unread FIFO evictions are reported bymissed_counton inbox reads. Both wait actions sleep on inbox or per-session lifecycle events; they do not run an internal polling loop.session action=waitresolves in three steps, in this order:- Already met? Answer straight away.
until=exitedreads the exit-code tombstone, which outlives the session:mark_session_exitedrecords the exit code and then drops thesessionsentry, so a just-reaped child satisfies the wait while failing the liveness check below. Checking liveness first turned the one outcomeuntil=exitedexists to report intoUnknown session. This step subscribes to nothing. - Live session? Otherwise
session_idis validated against the live session registry and an id that is not a real session gets{"error": "Unknown session …"}immediately — subscribing creates the per-session broadcast channel for whatever id it is given, and teardown only reaps ids that were real sessions. - Subscribe, then re-read state, so a transition landing between step 1 and the subscription is still seen and no wake is lost.
- Already met? Answer straight away.
Low-risk response compaction also omits an absent peer path from list_peers and an absent
parent_session_id from standalone spawn responses. Proxied upstream tool payloads are unchanged.
Blocking waits and terminal wake-up use a per-recipient delivery lease. Each
message is atomically assigned to at most one wake-up owner: an active waiter,
or PTY delivery. An external-client channel push does not take the lease: it is a best-effort
notification, so the message stays available and a later
agent action=wait or inbox returns it once more. Dedupe on
meta.message_id. The deadline path performs its final inbox check while
releasing the lease, and cancellation hands unobserved waiter-owned messages
back to terminal delivery. This removes both duplicate inbox+terminal turns and
the missed-wake race at the wait timeout boundary; inbox visibility itself is
unchanged and remains backward compatible.
If a terminal-owned message cannot be delivered before a PTY disappears, the
server re-queues that same message with a fresh logical cursor while preserving
its meta.message_id. This lets a later omitted-since wait recover it even if
it had already returned newer mail; recipients deduplicate the replay by
meta.message_id.
The inbox retains up to 100 messages per recipient. A new server-authored
lifecycle notice replaces the older notice for the same child and type, except
an awaiting_input state change: each separate question stays available to the
parent. The newest coalesced state stays at the end of the inbox, and replacement
does not increase missed_count. Other messages keep FIFO order. Every send
succeeds once the recipient is valid; at capacity without a matching notice,
the oldest retained message is evicted. missed_count on the next inbox read
reports evictions of unread mail; replacement and reclaiming mail already read
do not increase it.
An inbox read returns the oldest messages after since first. With no limit,
it returns all retained fresh mail (up to 100). With limit, the server clamps
the page size to 1–100 and returns has_more=true while newer unread mail
remains. next_since advances only through the returned page; omit since on
the next call to continue from the stored cursor, or pass next_since explicitly.
Reading a queued terminal message settles its delivery claim; when no pending
terminal-owned mail remains, the queued generic wake is removed. Delayed
terminal handoffs and queue retries recheck that same ownership before injecting
a generic notice. A read therefore also cancels a wake recreated after queue
cleanup; older unread terminal-owned mail still keeps its wake when an explicit
cursor skips it. An evicted
message also releases its delivery claim and any urgent notice reservation that
no longer covers retained mail.
The server never infers orchestrator role from child spawn, peer name, prompt, MCP activity, or SSE presence. Registration is the sole declaration seam. Wake capability remains server-derived: without a live managed PTY and its canonical lifecycle, an explicitly declared external orchestrator is inbox/wait-only.
Spawned peers additionally auto-post a state_change (idle / completed / exited) to the
parent’s inbox. They use the same waiter-or-generic-wake orchestrator routing and never inject the
state payload into the parent composer. These notifications carry state only, never task
output. Each child must send its result or blocker with agent action=send; session action=output
is reserved for diagnosing the anomaly where that result message never arrived.
Channel Push Delivery
An external Claude Code client with an active SSE stream (GET /mcp) receives notifications/claude/channel JSON-RPC notifications. A managed peer with a PTY uses the payload-free terminal wake, including when it is working. Registered orchestrators also keep peer payloads in the inbox. For messages over 200 bytes, the SSE params.content is a pointer under 300 bytes: the same inbox wake line as a PTY peer, followed by the validated sender UUID, message ID, byte count, and up to 80 UTF-8 bytes from the first line with control characters removed. The full body remains in the inbox. Messages of 200 bytes or less may be sent inline. The peer-controlled display name is never used in SSE notice text:
A channel notification is transport delivery, not proof that the recipient read the message. It stays unowned in the delivery lease, so the recipient’s next agent action=wait still returns it. Managed peers instead reserve a terminal wake until the inbox read cursor passes the message; the notice never contains peer payload text.
{
"jsonrpc": "2.0",
"method": "notifications/claude/channel",
"params": {
"content": "[TUIC] message available — read it with: agent action=inbox\nfrom 550e8400-e29b-41d4-a716-446655440a01 id 076546d8-80b0-4fa1-965f-1e31366e3506 10240 bytes: Large report",
"meta": { "from_tuic_session": "550e8400-e29b-41d4-a716-446655440a01", "message_id": "076546d8-80b0-4fa1-965f-1e31366e3506" }
}
}
This requires the client to be launched with --dangerously-load-development-channels server:tuicommander. The server declares experimental.claude/channel in its capabilities. Spawned Claude Code agents get this flag automatically.
Limits
- Max message size: 64 KB
- Inbox capacity: 100 messages per agent (FIFO eviction; sends remain accepted)
- Peer registrations cleaned up on MCP session delete and TTL reap, except where the identity is still addressable — see below
Identity outlives its transport
The 1h TTL reaper evicts an MCP protocol session nobody has used for an hour. A
peer identity is a different thing: it is the address other agents send to,
and refresh_mcp_session re-asserts it on the owner’s next request. The reaper
rechecks last_activity before deleting each selected session. That check and
route cleanup share the identity lock with a refresh that must recreate missing
metadata; a session refreshed after the sweep’s snapshot remains intact.
When a session is reaped, the server also drops its routing entry, reverse
route, and message broadcast sender; if another bridge still serves the
identity, it becomes the delivery owner. These small per-session allocations
must not survive a reap.
They do not account for the 27.3 GB malloc growth observed during the 2026-09-28
initialize storm; that allocation source and its triggering ego operation loop
remain under investigation. The reaper used to delete both session and identity
together, which broke agents that were still running:
last_activity only moves on an MCP request, so an agent that spends more than
an hour on one turn without calling a TUIC tool had its address deleted while it
was mid-turn. Its children’s handoffs then failed with Recipient '<uuid>' is not registered, and for a headerless caller that failure is permanent — re-register
mints a fresh UUID and nothing tells the child what it is.
The reaper therefore keeps an identity that is still addressable:
- it owns a live PTY (
live_pty_for_peer), or - a live session still records it as its parent (
session_parent).
Both are bounded by live sessions, so retention cannot grow without bound; an
identity with neither is genuinely unreachable and is still evicted. The
retained ids are logged at info on each reap. The rule is
AppState::peer_identity_is_reapable, applied by
evict_peers_for_reaped_mcp_session.
Authentication
When remote access is enabled:
- Basic Auth with username/password
- Password stored as bcrypt hash in config
- Session token, relay token, and VAPID private key stored in the OS keyring-backed credential vault
- Applied to all endpoints
- Mobile app: unauthenticated page navigations redirect to
/mobile/login, which posts toPOST /auth/login(same rate limit and bcrypt admission as Basic); cookie is sliding, 30 days by default — seedocs/api/http-api.md“Authentication”
When MCP-only (localhost):
- No authentication required
- Localhost binding only
Security Model
- Default: Local IPC (Unix socket or Windows named pipe), with filesystem/user access controls and no HTTP credentials. The TCP listener is opt-in.
- HTTP authentication: Every protected TCP request needs the existing URL token, session cookie or Basic Auth, including loopback and LAN clients. The legacy
lan_auth_bypasspreference no longer bypasses HTTP authentication. Login assets and CORS preflight are public; the headless health probe remains public. - Request boundary: Before authentication, every TCP request validates one Host authority (localhost, loopback/private literal IP, actual local interface IP, or the detected Tailscale FQDN). Missing, duplicate or foreign Host is rejected with 403. An Origin must be an exact bundled WebView/Vite origin or the HTTP/HTTPS origin of that validated Host. Foreign and opaque origins are rejected with 403 even with valid credentials. Cross-site browser requests are refused except from the explicit bundled/development origins. CORS uses the same origin policy and never a wildcard. Native clients without Origin still authenticate. Daemon Tailscale detection refreshes every 30 seconds through the desktop’s shared state-publication path; the Host guard reads the current state for every request, so late startup, node renames and daemon stops update trust without a server restart. With detection completing within its 500 ms budget, acceptance after Tailscale becomes ready takes at most 30.5 seconds (plus scheduler delay). A timed-out detection publishes an unavailable state and retries on the next cycle; repeated CLI failure/timeouts cannot guarantee acceptance. Daemon TLS remains controlled by its explicit manual/off configuration.
- Compression: Gzip and Brotli via
CompressionLayer(responses >860 bytes, auto-negotiated). SSE and WebSocket excluded byDefaultPredicate - No TLS: Intended for local network use; use SSH tunnel for remote
- Owner authority for session and agent actions: A loopback caller (including local IPC) or a caller with verified credentials (URL token, session cookie or Basic Auth) is the owner. The owner may use the mutating
sessionactions (create,input,submit,force_retry,kill,close,pause,resume,resize,rename,suspend) and theagentactionsspawn,launch,task_cancel,register,list_peers,send,inbox,wait,subscribe,ack,unsubscribe, plusworkflow action=launch(Boss decision 2026-11-01). A non-loopback request without verified credentials gets the old refusal; the legacy LAN bypass, a forged header or a body field never grants it. Capabilities, child-parent ownership of tasks and launches, and PTY versus ACP identities still apply.ui confirm/screenshot,debugand MCP settings mutations stay loopback-only - Remote
/fs/read-editor*cap: Remote clients receive the standard 10 MB file-read cap on/fs/read-editorand/fs/read-editor-external, not the 250 MB local cap (MAX_EDITOR_LARGE_FILE_SIZE). The local (loopback) router routes these paths to the large-cap handler; the remote router routes them to the standard-cap handler to avoid OOM/latency over metered links (seebuild_remote_routerinsrc-tauri/src/mcp_http/mod.rs). On request (offset/lengthquery) both routers instead return one bounded page (at most 1 MiB raw) for files up to the 250 MB editor limit, so a phone opens a large file page by page while server memory stays bounded - Markdown link resolution parity:
POST /fs/resolve-markdown-linkand theresolve_markdown_linkTauri command call the same Rust resolver. It returns only target metadata, returns UNC paths asexternaltargets before probing, and preserves local symlink targets outside the registered root. - Mobile Markdown images:
GET /fs/markdown-image?repoPath=...&file=...serves image files up to 10 MiB through the shared authenticated router. It canonicalizes the selected repository and requested file, then refuses a file outside that repository, including escapes through symlinks. - Traversal gate on absolute-path fs routes:
/fs/read-external,/fs/read-editor-external,/fs/write-external,/fs/copy-abs,/fs/move-absand/fs/transfer(itsdestDir) sharedeny_unless_in_roots, which rejects.., NUL and relative paths before the lexicalPath::starts_withcontainment check. Without that first layer,/repo/../../etc/passwdpasses containment by components while the OS resolves it outside the repo. These routes are inshared_routes(), so they are reachable from the remote router too. Paths are intentionally not canonicalized — symlinks placed inside a registered repo are an accepted design decision - Anti-hijack guard on
agent register: A caller that is neither loopback nor credential-verified cannot register as an existing live TUIC session —register,list_peers,sendandinboxneed the same owner authority, which prevents an unauthenticated client from injecting messages into another agent’s context (seemcp_transport.rs)
Browser Mode Integration
The frontend’s transport.ts maps all Tauri commands to HTTP endpoints:
// In browser mode:
invoke("create_pty", { config }) → POST /sessions { config }
invoke("get_repo_info", { path }) → GET /repo/info?path=...
PTY output in browser mode uses WebSocket instead of Tauri events.
Mobile Transport
The mobile companion UI (/mobile) uses the same HTTP/WebSocket infrastructure as the desktop browser mode:
- Session polling:
GET /sessionsevery 3s, enriched withSessionState(question, rate-limit, busy, agent type) - Real-time events: SSE via
GET /eventsfor session create/close notifications - Live output: WebSocket to
/sessions/{id}/streamwith JSON framing (output,parsed,exit) - Input:
POST /sessions/{id}/writesends text to PTY (used by quick-reply chips and command input) - History:
GET /sessions/{id}/output?format=textfetches initial ANSI-stripped output buffer - Mirrored sessions: the desktop server routes session-scoped HTTP calls and WebSockets to the connected owning daemon. It replaces the phone’s credential with the owner connection token and returns 503 when that connection is unavailable. The daemon itself serves only local PTYs.
- Progress projects: authenticated
GET /progress/projectsreads the local journal’s project names for the phone’s selector. - Activity:
GET /config/activityreturns the persisted array; the Activity tab hydrates that array when opened.
The mobile entry point shares transport.ts and invoke.ts with the desktop — no mobile-specific transport code.
Secret form security boundary
secret supports request, run and remove; no action reads values. The
backend owns the zeroizing store and process spawn. Values are shared by name
across that backend’s callers, not keyed by MCP connection or TUIC session;
MCP disconnect/reconnect leaves them intact. remove returns the requested
names and status: "removed" after idempotent deletion, even for absent names.
Older builds returned missing to describe the post-deletion state, not a lookup
failure. run still returns missing when a requested value is unavailable.
Native-window bootstrap
privately distributes a per-form capability. Browser entry uses
/index.html#/secret-form?nonce=<capability> on the existing application router,
with the same authentication and transport policy. Requests require a desktop
host. There is no separate server, TLS detection or origin isolation: an
application-origin service worker can observe entry, and HTTP is not restricted
to loopback by this feature. Boss accepted these limits on 2026-10-03.
One shared pre-call gate classifies each operation while a form is open
(secret_inspection_tool). It blocks ui and debug actions other than
ui toast/confirm/help and debug agent_detection/sessions/help, and direct or
call_tool-wrapped upstream calls unless the upstream is HTTP on a public host
(stdio, loopback, private, link-local, .local, single-label and unknown
upstreams are blocked). Results
of already-running inspection calls are not withheld. The HTTP debug-JS handler
also checks the form gate. The form mounts through the common frontend entry
without starting App/debug/logging/terminal initialization. Run captures pipes,
caps output and masks before serialization; it never writes raw output to
logging or PTY paths. Consent templates match exact argv, names and directory.
Configured remote MCP ownership
The desktop’s native MCP session list includes the Rust remote mirror. Remote rows carry
connection_id and address (connection_id/session_id). Session output and submit
resolve that owner and use its configured HTTP URL and token. Output uses the daemon’s
native MCP cursor, redaction and exited-session contract through format=mcp or
format=mcp_raw; submit uses the authenticated semantic submit endpoint.
Peer discovery includes local and connected remote registries. Use a returned peer
address, or pass connection_id with to. local/id addresses the desktop.
The desktop opens an authenticated /mcp/peer WebSocket to each configured daemon.
This duplex mail link carries register, list_peers, send, inbox and wait only; process
creation is excluded. A daemon sends to the desktop or another daemon through the hub.
The authenticated link determines sender provenance. Destination delivery reuses native
inbox and wake handling, preserving the message body in the inbox.
Local mail survives hub loss. Cross-host failure names the connection; uncertain acknowledgements must not be retried blindly. Lifecycle mail retains its message identity in the bounded native outbox until acknowledged. Reconnect retries those notices without duplicating an already retained destination message.
Peer handshakes serialize per configured connection, so a mute daemon cannot hold mail calls to another host behind its network deadline. Session targets reject empty ids/prefixes before owner selection. Forwarded notice deduplication survives inbox reads: each registered recipient keeps a FIFO ring of the last 100 forwarded message ids and fingerprints, shared across senders, without retaining message bodies. A retained id with a different sender or body is rejected as an identity collision. Recipient unregister removes that recipient’s ring; sender retirement does not. Beyond the last 100 ids, a retry may be delivered twice, including when another sender’s burst pushes its id out of the ring. There are no global budgets, host quotas or sender eviction rules.
Disconnect retires that host’s existing shadows synchronously, independently of a pending handshake or a later reconnect generation. The registered-recipient check and enqueue remain atomic with recipient retirement. This is a bounded replay horizon, not unbounded or restart-persistent exactly-once delivery.
Telegram adapter groundwork
The headless telegram tool exposes register, unregister, begin, activity, finish and send through the normal MCP registry and dispatch. Registration uses the caller’s MCP-bound TUIC identity, replaces the previous agent with one native mail and is never persisted. MCP session end, PTY close or foreground-agent exit retires it. Without an explicit owner, the latest-connected live AI Chat peer is the fallback for inbound text and may use the reply tools. Explicit registration always wins. Connecting another AI Chat changes only future inbound delivery; existing requests keep their original reply peer. Request-specific reply tools require that peer’s MCP binding. Explicit registration takeover revokes pending requests. Other callers must register before outbound actions. Authorized text with neither a registered owner nor a live AI Chat peer gets “No agent is listening. Ask an agent in TUICommander to register for Telegram.” and is dropped; strangers stay silent. Native stable-ID inbox/wake delivery remains authoritative. See the Telegram design.
Native remote health, authentication, session-list, and SSE clients strip request URLs from reqwest errors before publishing them. Token-authenticated native HTTP requests send the existing tui-session cookie header rather than a query token; browser WebSocket query authentication is unchanged.
Workflow operator authority is selected by the host: verified HTTP credentials grant Human, unauthenticated loopback grants LocalApi. Request JSON cannot select the actor. Workflow policy writes and human decisions, plus administrative story transitions, require Human authority.
The daemon executor now owns recovery and duration timers under an OS run-database lock. Reads never recover live work, and a non-owner daemon refuses run mutations. Graph resume uses resume_graph {execution_id,activation_id,resolution} with an explicit pending activation; status-only resume cannot bypass graph position. Graph start controls, Agent effects and delivery policy remain unavailable until their later slices.
Launch receipt read
GET /sessions/{id}/prompt-receipt returns the same live receipt as desktop get_prompt_receipt. MCP initialize captures the served instructions after peer auto-binding. Protocol metadata retains bounded responses during PTY registration; PTY metadata retains its copy after protocol reaping. Sessions without a captured launch brief still retain served MCP instructions and show an explicit launch-unavailable section. No additional store or settings reconstruction is used. See HTTP API.
Inbox consumption audit
Every successful agent action=inbox read emits an INFO tracing event with source="agent_msg", event="inbox_read", caller_session_id (the MCP protocol session), caller_peer_id (the bound TUIC peer), inbox_owner (that peer), and message_ids (a JSON array of returned ids). Empty reads emit an empty array. No message bodies are logged. The audit does not grant access to another peer’s inbox: caller and owner remain bound by MCP registration. Read /logs?source=agent_msg&level=info and filter event=inbox_read.
Conversation-specific launch is available through POST /acp/chat/open; see the HTTP API guide. It creates an ACP peer, without a terminal tab.
Agent-declared worktree placement
An agent that uses git -C or tools without changing shell cwd can declare an
existing linked worktree with:
session action=declare_worktree worktree_path=/absolute/path/to/worktree
The authenticated MCP binding identifies the caller’s live PTY. Omit
session_id; a foreign session target is rejected. The backend resolves the
repository from the immutable launch directory and discovers current worktrees
from Git. The main checkout, unknown paths and worktrees owned by another
repository are rejected before any configuration or placement changes. External
worktrees are discovered without recreating or deleting them.
The response and session-worktree-declared event use the worktree lifecycle
payload, with creator_session naming the caller and spawn_session=false.
Only the caller’s tab moves to the declared workspace, without changing shell cwd.
Sibling tabs and an inactive selection stay unchanged. If the caller is active,
its selected workspace follows the same tab. Retrying the declaration is idempotent.
The stable TUIC_SESSION association is stored in the owning repository’s
declaredWorktrees map using the existing locked repository delta. Any saved
caller snapshot moves to the target workspace; sibling snapshots are preserved.
After a restart or WebView reconnect, HTTP GET /sessions and IPC
list_active_sessions return the declared worktree_path and worktree_branch
while cwd remains the reported shell directory. The frontend restores tab
placement from the persisted stable TUIC_SESSION declaration across registered
repositories, independent of the current cwd-derived owner, when its workspace id
and checkout path still match. Declaration does not acquire
worktree cleanup ownership.
A concurrent repository edit can return a configuration conflict; retry the
declaration after refreshing rather than overwriting that edit.
The association owns display placement during later shell cwd notifications, reconnect and saved-tab restore. A removed or replaced checkout invalidates it. Worktree removal checks each terminal’s current cwd, not its declaration or sidebar membership.
Intentional request transport exception: declare_worktree is an MCP-only
action, callable over the existing HTTP POST /mcp route with a bound caller.
There is no Tauri command or COMMAND_TABLE entry: window IPC has no managed
agent caller binding. Its push event is dual-emitted over Tauri and /events SSE,
and session-list response fields are identical over IPC and HTTP. Schema and
serialization regressions cover these shared contracts.
MCP Tool: automations
Saved run configurations are validated against the same named-profile lookup used
by the runner. Names are case-insensitive; a bare agent type such as claude
is not a saved profile unless a profile has that name. Create, definition
updates and re-enabling reject an unresolved name with a repair hint listing
valid saved profiles. Existing list rows retain invalid definitions, but expose
run_config_error and return next_run_ms: null until repaired. A profile can
be removed after saving; launch checks it again and records a failed run.
Unknown runs send the bound creator one automation_run_unknown message with
session_id and last_error, claimed under the same owner channel.
Failed runs send the bound creator one automation_run_failed inbox message
with run/definition ids and reason, including pre-spawn failures. The existing
peer mail route supplies payload-free wakes; SQLite claims the owner channel
before delivery, so repeated publication and restarts do not resend it. A
missing creator registration leaves delivery unconfirmed; bell behavior stays
unchanged for definitions without a creator.
The native automations tool accepts the same top-level action object as
automation_action IPC and the input in POST /automations/action.
Actions include list, get, create, update, pause, resume, delete,
run_now, run, list_runs, summary, preview, preview_definition and preset.
See the HTTP API Automations table for fields and results. List returns rows
with definition, next_run_ms and last_status; create/update return the saved
definition. Update accepts a full definition (optional id), or id and enabled.
Errors use { "error": "..." } with the identical backend validation text.
A bound agent can create a one-shot in one call:
{"action":"create","definition":{"name":"Recheck","prompt":"Check again","in_secs":3600,"run_config":"Your saved profile"}}
The host resolves the elapsed delay from its own UTC clock. It defaults repository
from this caller’s live cwd, ACP root or registered project, never another tab.
run_config must be explicit: current caller metadata does not retain the actual
saved account/model profile. The host never substitutes the agent type’s default
profile. An omitted profile returns {error,code:"caller_profile_unresolved",field:"run_config"}.
Generated IDs combine the name with a SHA-256 hash of caller identity and the
original request before defaults and clock resolution. Repeating that request
returns the first saved occurrence, including when caller cwd has changed or is
no longer available. Concurrent retries share one locked insertion. To create a
separate identical reminder, supply a new explicit id. Explicit-ID duplicates
still fail. Other defaults are existing workspace,
enabled=true, grace_secs=43200, overlap=skip and max_duration_secs=3600.
Create returns the saved fields plus next_run_ms and the resolved
once_local/timezone; no date, list or get call is needed. in_secs must be a
positive integer and cannot accompany cron or once_local. The stored once_at
preserves the exact UTC instant across DST folds. Preserve it for unchanged
schedule edits, or clear it when changing the schedule. Computed next_run_ms is
read-only and is ignored when a reply is passed to update or preview. The MCP
schema declares this field as a read-only nullable integer so a saved reply also
passes the closed-object update/definition-preview property boundary.
MCP creation requires a bound agent session. The host sets created_by_session;
input cannot impersonate a creator, and updates preserve the original creator.
Pause/resume edit only enabled under the store lock. Deleting a definition
retains run history. run_now uses the same runtime owner and refusal rules as
HTTP/IPC. All adapters call automations::api; MCP does not parse a second
action enum or implement scheduler logic. The MCP endpoint is POST /mcp.
tuic automations '<action JSON>' (or tuic automations - for stdin) forwards
unchanged arguments over HTTP-over-IPC MCP into this same API. CLI failures
print the backend message on stderr and exit nonzero; successes print JSON.
Automation HTTP/IPC adapter
The shared desktop/headless router exposes POST /automations/action with
{input:{action:...}}. automations::api::execute is also the Tauri command
implementation; stores, schedule rules, aggregates and execution ownership stay
in Rust. COMMAND_TABLE.automation_action maps the same input without renaming
fields. Route snapshots and registered-route PATCH probes cover this route.
MCP and CLI use this same action parser, runtime owner and result contract.
HTTP and MCP/CLI validate static automation inputs with the same advertised
schema before dispatch. HTTP returns status 400 with the identical structured
invalid_arguments payload, including bounded, value-masked violations and
effect=not_started. Semantic application error messages still match IPC
rejections and MCP/CLI errors; IPC retains its string-error signature.
MCP additionally requires a bound creator identity for creation.
Automation precheck context (#1631-45bf): definitions can opt in with
precheck.inject_output: true (default false). Proceeding checks prefix the
literal prompt with delimited, escaped untrusted stdout capped at 16 KiB;
truncation is marked and stderr is excluded. Empty output and manual bypasses
inject nothing. The run ledger records precheck_context: {injected, bytes} for
the prepared launch prompt, counting escaped stdout bytes before framing/marker.
PR line review routes (/repo/pr-line-threads, /repo/pr-open-threads, /repo/pr-thread-comments, /repo/pr-thread-resolved, /repo/pr-thread-reply, /repo/pr-draft-review) share account resolution and backend behavior with their desktop commands.
The PR action routes (/repo/pr-action-state, /repo/pr-auto-merge, /repo/pr-merge-queue, /repo/pr-merge-or-enqueue, /repo/pr-rerun-failed) share account-aware backend logic with IPC. Successful rerun means accepted, not completed.
Core accounts owner surface
IPC account_action and HTTP POST /accounts/action share one Rust service and presence-only replies. Both HTTP routers require loopback or authenticated API access. The Settings MCP adapter can consume the owner service/schema after integration; account actions are not a new standalone MCP tool or an unrestricted plugin invoke grant. See Shared account registry.
Automation worktree cleanup (#1623-8b2a): Automation runs retain automation/run IDs and the exact created workspace path and ID in their saved snapshot, including after definition deletion. Worktree cleanup is explicit and limited to final runs. The backend resolves the saved identity and rechecks shared Git integration/archive proof, dirt, submodule commits and live sessions; it never forces removal or closes sessions. Shared automation_action actions worktree_preview and cleanup_worktree accept a saved run id on IPC, HTTP, MCP and CLI.
Automation templates (#1622-be11): the shared automation action accepts
templates (catalogue) and template (draft). Draft inputs are template_id,
repository, run_config and optional timezone (host local by default).
Drafts have fresh ids and start disabled; no definition or run is created until
an explicit create action. These actions match across HTTP, IPC, MCP and CLI.
Design Mode lifecycle tool
The ui tool exposes design_start, design_stop, design_status, design_reload, design_navigate, design_screenshot, design_errors and design_eval. These actions delegate to the existing Design Mode owner: the caller must own the armed repository for browser commands, remote hosts and JavaScript require the sidebar host consent. A saved design_mode denial migrates to the design capability and still blocks these actions; disabling ui blocks all UI actions. The separate design_mode tool is removed without an alias. Start accepts session_id, optional browser (chrome or edge) and optional absolute HTTP(S) url. Session references resolve like the session tool. Stop accepts repo_path from start/status. Reload takes the same repo_path and bumps a per-repository reload sequence; the extension reloads the reviewed tab once on its next heartbeat. Navigate takes repo_path and url (HTTP(S) on localhost, 127.0.0.1 or [::1], no credentials); the heartbeat reply then carries navigate: {seq, url} and the extension opens the URL in the reviewed tab once per sequence. The sequence survives a re-arm but the URL does not, so a new Start never replays an old navigation. Reload and navigate answer “Design Mode is not running for this repository” when nothing is armed. The extension posts heartbeat to /design-mode/extension every 5 s (reply {armed, reloadSeq, navigate?}); an armed mode is stopped 60 s after the last heartbeat, or 10 min after Start when none arrived. The adapter uses the same lifecycle core as HTTP and IPC; headless builds return an explicit desktop-host-required error. URL-aware start is the default coordinator path for layout work.
The GitHub settings owner adapter supplies typed device-login, Enterprise account, credential, label and binding actions for the later settings transport cutover. It is an internal service boundary; this adapter step registers no new MCP tool, HTTP route or IPC command. Its reads and results contain credential presence only.
Internal Ego settings adapters (#1775-330c)
settings::ego::EgoSettingsStore targets profile with the configured profile ID,
or machine for the user base. It captures trusted executable, workspace and
profile together per operation, clears ambient EGO_PROFILE, and invokes only
config capabilities/snapshot/batch, models --json without refresh, and auth status.
The model slug selects the provider. Managed DTOs discard unknown owner fields;
credential type/expiry and process diagnostics never enter settings replies,
effects or audit data. Credentials are read-only set/unset markers.
Managed keys (model, roots, network, exec_paths) are atomic leaves.
Null/reset sends an owner unset; explicit empty arrays stay explicit. A patch is
one config batch --if-revision against the opaque revision from config snapshot.
This protects against external CLI writers as well as host requests. Atomicity is
limited to the selected Ego user document, never other settings stores. Owners
without advertised atomic batch and compare-and-swap support fail closed.
Base-only provider headers and credential commands have typed write-only auth
actions (EgoAuthAction) and presence-only catalogue fields. Auth actions always
select the base owner, independent of the launch profile. Profile-target reads
of these machine-owned auth paths return not_found, not a false unset status. No read executes a
credential command or attempts to recover an owner-redacted value. Failed
readback after a successful write reports persisted: true and nextAction: get.
Launch defaults (ego_executable, ego_profile, ai_chat_workspace) stay in the
app store and its AppSettingsStore owner. The adapter is internal; settings
transport registration and executable confirmation belong to later plan steps.
The Providers tab shows the base model when the configured profile has none, as
Ego resolves it, and creates a missing AI Chat workspace like ACP does. Existing Ego IPC/HTTP commands retain
identical shapes; model reads/writes now honor configured profile/workspace.
Tasks brief preparation uses POST /tasks/start-work-prompt, the HTTP twin of
build_start_work_prompt. Both accept repoPath and input with key, nullable
URL, title and body. The shared Rust implementation reads the repo-contained
.tuic-start-work.md and sanitizes item fields before substitution. The frontend
passes the result to the provider; host delivery still wraps and caps it.
Tasks items through the repo tool
repo action=work_item reads the item linked to the caller’s current Git worktree branch in workitem_links.json, searching all registered paths sharing its canonical repository root. Explicit targets are reference: {providerId, accountId, id}, url, or key with provider_id and account_id. URL lookup uses registered plugin resolvers. Key lookup uses the selected provider’s search and requires an exact key match; repeated cursors and ambiguous matches fail. Use a reference or URL when the provider cannot find a key through search.
The response has content, with a JSON detail inside <untrusted-content source="work item"> and its closing tag. Detail includes the first comments page. Pass cursor from comments.nextCursor to read the next comments page, with limit (1–100, default 50). All provider text, including metadata, stays inside the block. JSON escapes angle brackets so item text cannot forge a closing tag.
repo action=work_item_act accepts the same target and operation: {kind: "comment" | "transition", value: string}. Transitions use provider action IDs. Writes fail before provider dispatch unless mcp_work_item_writes is true; it defaults to false. The setting is checked again before a frontend claims the write. An action result contains the updated detail in the same block.
Rust owns target selection, input/reply validation and opt-in. A typed work-item-provider-request event reaches the existing frontend registry through desktop events and SSE. The frontend atomically claims a request with work_item_provider_bridge, calls the existing provider port and completes the reply. Multiple clients cannot dispatch the same request twice. Claims and completions have matching IPC and HTTP transports (POST /work-items/provider-bridge). A running frontend with the provider loaded is required; a headless daemon alone has no JS providers. Requests time out after 30 seconds. A dispatched write may have completed when the reply times out: read before retrying.
Credentials stay in Rust’s existing account-authenticated HTTP path, which redacts raw tokens and Basic encodings before provider JavaScript receives a response. MCP accepts only the Tasks DTOs and suppresses raw provider errors; it never serializes account objects or configuration.
Background tray and menu-bar icon
The desktop close-dialog event and its SSE copy include background_available: boolean. The desktop Ask dialog uses it to omit Background when the tray is disabled or unavailable. Browser clients continue to ignore native close prompts; tray actions add no public request surface.
When the desktop WebViews are deliberately unloaded in background mode, ui actions return {"error":"webview_unloaded"} immediately. This does not affect PTYs or remote terminal streams. SSE emits background-mode-changed with state equal to hidden, unloaded or visible.
Design Mode captures accept per-call format (webp by default or png),
quality (WebP 1–100, default 25) and optional max_long_edge (positive pixels,
downsize only). Use WebP for text/layout, quality 50+ for small glyphs/icons, or
PNG for pixel-exact detail. Responses report path, format, quality (null for PNG),
bytes and media type; MCP sends a correctly typed image block. Token cost follows
pixel dimensions, not file format or bytes (Claude: about 1,296 tokens per
megapixel, capped at 1,568 standard / 4,784 high-res). HTTP/IPC use the same
screenshot fields in args; no user setting is added.
Design Mode browser commands (navigate, reload, screenshot, errors, eval)
return correlated native-port results with a ten-second timeout. Direct MCP tool
lists, meta search and schema lookup filter Design Mode by the armed terminal
session; cached-tool dispatch checks the caller and repository again. Start remains
callable by its known tool name before arming. Arm/Stop broadcasts
notifications/tools/list_changed; live client refresh remains a verification item.
Settings proposal confirmation (#1786-9cbd)
ui(action=confirm, proposalId=...) accepts an opaque proposal from the shared
settings service. The host supplies the title and redacted diff; supplied
title, message and confirmed cannot approve or replace it. The existing
mcp-confirm event reaches desktop and SSE clients, and the existing human
response endpoint/IPC command settles the first answer. A pending dialog uses the
remaining portion of the proposal’s absolute 300-second lifetime. Cancelling its
handler dismisses the question and revokes the proposal. Ending an MCP protocol
session revokes its proposals and grants. Headerless confirmation requires a
server-issued connection identity.
The service boundary rejects remote MCP writes regardless of peer registration. Local MCP enablement, HTTP local-or-authenticated access and native OS-user trust remain distinct host-issued contexts. The replacement settings tool and HTTP/IPC routes are not published by the policy foundation; cutover wires those contexts into the same service rather than duplicating policy.
Durable session wake is shared by MCP submit and peer mail, IPC resume_session, and authenticated/local POST /sessions/wake. MCP list/status include retained tabs as state:"hibernated". Mail remains durable in the inbox if wake fails; the response includes resume_error.
Account-scoped GitHub review and action ports
host.githubReviewThreads(account, reference, after) returns the core B6 review
thread page, including head SHA, bot authors and parsed findings.
host.githubPrAction(account, reference, request) calls core B7 policy.
Both require net:http and an on-disk manifest declaring providers: ["github"].
The reference must identify a GitHub pull request in the selected account. Core
loads that exact account credential, never a local repository default. Cross-account
references fail before credential lookup. No token is returned to the plugin.
Requests use action: state, auto_merge (enabled, optional mergeMethod,
expectedHeadSha), queue (enqueued, optional expectedHeadSha), merge
(mergeMethod, expectedHeadSha), rerun (runId), or review (draft with
headSha, body, event, comments). Existing core reviewed-head validation,
merge queue policy and shared request budgets apply unchanged. The desktop command
plugin_github_action and POST /api/plugins/{plugin_id}/github accept identical
{account, reference, request} payloads (IPC also supplies pluginId).
The GitHub Work runtime binds both ports when it registers each configured account.
No live write or desktop-load verification is implied by recorded-fixture tests.
Settings cutover (#1787-4778)
GET /config and PUT /config are registered once in shared_routes() for browser Settings hydration, non-saving refresh and legacy owner saves. Their authentication and secret-redacted readback are unchanged.
POST /settings/action is registered once in shared_routes(), so desktop and headless daemons use the same handler, authentication policy and value-free Settings event publisher. Upstream OAuth startup requires a desktop host; the headless owner returns unavailable before upstream lookup or network access.
settings replaces the removed MCP config tool without an alias. Its schema is generated from Rust action DTOs. settings_action(request) and POST /settings/action use the same envelope and owner services. Describe has optional area/store/id filters and cursor pagination (1–128 fields). Reads and edits use an explicit target; edits require expectedRevision. Prompts remain available through the stable-ID prompts store; get /prompts lists id/label/text/pinned records, while keyed leaf reads and create/remove patches retain stable identities. Typed workflows use perform with an explicit machine target and a store-selected operation DTO for github_accounts, ego (also expectedRevision), upstreams, connections, circleci, telegram and voice in dictation builds. Targeted describe/refresh uses target/store/paths through the registered owner resolver. Connection credential reads use /{id}/credential and return separate password/pairingToken/relayPairing presence; the set_relay_pairing action stores the bundle printed by tuic-remote --relay-pair after parsing it (an unparsable bundle is out_of_range). Credential writes retire only that runtime and reconnect it only when it was active; an explicit later disconnect retires the queued reconnect. Explicit refresh for ego refreshes the configured owner’s provider catalogue; describe never performs a network refresh.
MCP access requires settings_mcp_enabled, enabled only by trusted UI; legacy config enablement grants no settings authority. MCP, like HTTP, accepts local or authenticated callers: the TCP listener always runs Basic Auth, and the Unix socket and named pipe serve only local clients. IPC retains native host trust. Exposure proposals use ui confirm proposalId and an exact replay with approval; the proposal is one-use and bound to the MCP connection, the edit fingerprint and its expiry. ui confirm also accepts authenticated remote callers. Secrets remain write-only. Owner transactions and perform remain unavailable while the native inventory gap ledger is nonempty; describe reports inventoryComplete.
Gated HTTP and IPC edits return confirmation_required with proposalId and do not write.
Confirmation applies only when a change adds authority: enabling or widening a listener, loosening authentication, replacing TLS material or weakening TLS, enabling the relay or changing its destination, adding or replacing an executable, launcher argument or stdio upstream command, and adding a tunnel forward or auto-connect. Narrowing, disabling, lowering a timeout and no-op edits apply directly. The owner’s own Settings window (the native settings_action command) applies every edit directly; HTTP, MCP and other native callers get the proposal flow. No request field can claim owner-window intent.
Replay the exact original edit with approval: "<proposalId>" and confirm: true.
The same request opens the existing all-client human confirmation dialog, waits for the
answer, and, only after approval, commits the exact edit under its original caller.
A decline, expiry, changed edit, caller mismatch or reused approval cannot commit.
HTTP proposal identity uses the source IP, not the ephemeral TCP port; every request
still requires local or authenticated access. MCP callers can continue to use
ui action=confirm proposalId=... followed by an exact replay with approval.
Tunnel forward lists, including empty replacements, require confirmation like tunnel ports.
Plugin HTTP fetch and cancel routes use the shared plugin_http implementation. The optional requestId is scoped to the plugin; cancellation drops the entire request future, including authentication preparation, headers and streamed response body.
session action=force_retry is a blocking terminal control for a loopback or credential-verified caller.
It resolves the normal session address, requires a live ego recovery snapshot
and an empty tracked composer, serializes input and submits /retry once via
the standard agent writer. It does not queue or attach ACP. Remote-qualified MCP
session control remains limited to the existing supported remote actions; the
browser status-bar control uses its owning daemon’s normal PTY write transport.
Telegram request streaming (1959-162a)
Telegram replies now use TUIC-driven receipt (👀), working (👨💻), waiting (🤔), answered (👍) and failed (👎) reactions. An ephemeral native draft shows Italian status lines or unapproved agent previews; it refreshes while work continues and the final reply replaces it. Acknowledgement of work requires inbox Read and a new recipient turn. PTY intent/activity and AI Chat assistant chunks share request correlation; finish remains authoritative after draft retirement. Telegram-mail-woken AI Chat turns automatically send their settled assistant text if finish has not answered. Queue and no-reply notices occur at ten minutes and sixty seconds after Read respectively. Restart keeps no request history. Phone rendering requires a live check after the backend restart.
Settings startup contract
See Settings startup workflows for discovery, target/revision ownership, device-login intervals, human confirmation and partial-persistence recovery. Native inventoryComplete does not prove schema-only authentication onboarding or UI parity. Typed list_accounts and Ego begin_login/login_status use the same owner facade. Login launches the configured process directly in a tracked human terminal, not an arbitrary-command or ACP fallback; status separates process lifetime from credential readback.
CircleCI credential settings (#1991-bd88)
The machine-scoped circleci.token descriptor is write-only. Read
{action:"get",target:{kind:"machine"},store:"circleci",paths:["/token"]}
through MCP settings, IPC settings_action, or HTTP POST /settings/action.
Readback returns only stored.status and effective.status: set, unset, or
unavailable. It describes the stored TUIC token, not environment or CLI fallbacks.
Use {action:"perform",target:{kind:"machine"},store:"circleci",operation:{action:"set_token",token:"..."}}
or operation:{action:"clear_token"}. Both actions use the existing CircleCI
owner; replies contain only token presence. Clearing the stored token does not
remove CIRCLE_TOKEN or the CircleCI CLI configuration. The Git & GitHub page
continues to show the effective token source. No transport returns the token.
Machine launch instruction previews
GET /config/defaults and POST /config/defaults are shared machine routes on
both the desktop server and tuic-remote. The POST previews draft agent settings
without saving them and uses the same authentication as other machine config routes.
Launch-capable Claude, Codex, Grok, OpenCode, Goose, pi and ego clients receive playbook obligations from generated launch files, not again from MCP initialize instructions. MCP keeps tool discovery and live repository/session/peer state. Unrecognized clients retain the existing MCP marker, submit, worktree and progress fallback.
Idempotent managed launch
Prefer agent action=launch for a managed worker that needs a selected/new workspace and a durable retry identity. One request composes worktree allocation, named spawn, parent linkage and keep-open policy; unkeyed spawn remains compatible. The shared Rust boundary also serves POST /agents/launch and managed_agent_launch IPC. See the wire contract. Read by launch_id without sending a new prompt.
A SQLite journal reserves identity before side effects and uses revision compare-and-swap to prevent concurrent checkpoint owners from both creating resources. An app-scoped async mutex serializes launch mutations; filesystem/process work remains on the existing allocation/spawn paths. A lost reply reuses the child. An uncertain interrupted side effect blocks instead of retrying or changing checkout. Native session/prompt state determines delivery and readiness, never output movement alone. The existing spawn name pinning and managed idle-close exemption are reused. Routing, account choice and local brief rules are not TUIC policy.
Native automation and workflow run bindings also use this transaction through managed_launch: automation run IDs and workflow attempt IDs provide stable keys, with an in-process run-owner scope when no peer parent exists. No synthetic peer is registered. Run-owned children use the same pinned-name and explicit keep-open path as MCP children; the existing run controller still owns cancellation and completion. The unkeyed public spawn compatibility action continues to use the same low-level PTY spawn implementation. The existing 30-second deferred-prompt watchdog also applies to parentless run-owned children: a timeout reports blocked, retains the queued prompt and never creates a replacement.
Compact inventories and byte-bounded response snapshots
session action=list session_id=<address> resolves one session through the same
address resolver as other session actions. agent action=list_peers to=<address>
uses the send recipient resolver; connection_id or connection/peer selects a
remote owner. Missing or ambiguous targets return errors, not empty success.
Both inventories accept compact=true. Rows keep identity/address fields,
state, activity_age_ms, and omitted_fields. Unknown state is "unknown";
unknown activity age is null, never zero. The omitted-field list names removed
fields. A failed remote inventory remains an error or connection_errors, not
proof that no peers exist. Activity age comes from the backend session snapshot;
a peer without a live terminal has unknown state and age.
For agent action=inbox and session action=output, set
byte_budget=4096 (integer range 1024–65536) to request an immutable snapshot:
{"encoding":"json-text","chunk":"...","offset":0,"total_bytes":49162,"continuation":"opaque token","omitted_fields":[],"expires_after_seconds":300}
The budget counts UTF-8 bytes of the compact JSON page object, including its
escaped chunk and all page-envelope fields. It excludes JSON-RPC, MCP content
blocks, HTTP headers, and transport framing. Even one oversized item is split;
UTF-8 codepoints stay whole. Concatenate decoded chunk strings in page order,
then parse the resulting JSON to obtain the original response. No fields or
retained text are removed. total_bytes and offset refer to that reconstructed
JSON text, not the escaped page object. continuation=null marks the final page.
Repeat the same action, target and connection with the returned continuation.
A continuation defaults to a 4096-byte budget if byte_budget is omitted. Tokens
are bound to the inbox owner or output caller and operation/target; changed
window arguments do not recapture the snapshot. Repeating a page is safe.
Snapshots expire 300 seconds after capture, on restart, or when the shared cache
needs space (128 snapshots, 32 MiB of serialized snapshot text). Invalid,
foreign, expired or evicted tokens fail explicitly with restart_required when
applicable. Start a new read; do not treat the error as an empty result.
The inbox read cursor advances only when the final chunk is returned. A partial
or abandoned read does not consume mail or its eviction count. Final-page replay
does not acknowledge later evictions again. Explicit since=0 remains replay,
and cursor advancement remains monotonic. Concurrent new mail stays unread;
concurrent terminal output does not alter an existing snapshot. Inbox retention
loss is still reported as missed_count; expired terminal retention is still
reported by the existing output-window metadata. A captured snapshot remains
readable even if its source ring rolls over. The byte bound cannot recover data
already lost before capture.
Without byte_budget or a token, existing response shapes and cursor behavior
stay unchanged. Errors remain errors; an error detail that itself exceeds the
budget becomes response_error_exceeds_byte_budget with an explicit omission.
The shared native handlers own validation and paging. MCP, the IPC MCP bridge,
and HTTP format=mcp|mcp_raw use those handlers; the remote output proxy forwards
byte budgets and tokens without rewriting the bounded envelope.
Fixture provenance: src-tauri/src/fixtures/mcp-output-2005.txt captures the
49,162-byte response cited in the 2026-10-17 MCP usage audit, coordinator transcript
result line 168437. It is historical terminal text, not a current-state assertion.
src-tauri/src/fixtures/mcp-inbox-2005.txt captures the audit’s 49,609-byte inbox
response, private TUIC transcript result line 3239. The regression also covers
multibyte and escaped oversized inbox content.
Review clarifications: loss watermarks, wait and local continuation scope
All inbox readers use one delivery-gate acknowledgement boundary. A captured byte snapshot records the monotonic eviction watermark at capture time. Final completion acknowledges only the previously unacknowledged part of that range. Two overlapping snapshots cannot subtract the same historical missed count from later losses. An ordinary inbox read advances that same watermark; there is no separate byte-page read cursor or client acknowledgement protocol.
agent action=wait is not byte-bounded. Supplying byte_budget or
continuation to wait returns wait_byte_budget_unsupported before registering
a waiter or consuming mail. Use byte-budgeted inbox reads for bounded payloads.
The existing wait claims and acknowledges mail before its response is returned.
Adding deferred completion to it would create another acknowledgement model;
wait paging must instead use the shared subscription/ack reconciliation tracked
by #2004-4760. This story does not claim to reduce the audit’s 14,763-byte wait
response maximum.
A daemon must support the byte-page envelope to serve a byte-budgeted remote
output request. The desktop proxy rejects unpaged legacy-daemon responses and
pages that exceed the requested compact-JSON budget. It does not pass through
an oversized legacy body merely because exited is present. Update an
incompatible daemon; do not retry without a budget unless unbounded output is
actually desired.
Full session inventory exposes known last_activity_ms from the backend
snapshot. Compact projection derives activity_age_ms from that timestamp;
a missing or zero timestamp remains unknown. An exact registered local peer
name is resolved before interpreting a slash as a connection qualifier. With
an explicit connection selected, a daemon-local slash-containing name remains
a name unless it carries that same connection prefix.
Inbox tokens are scoped to the bound peer identity. Local native MCP output tokens
are scoped to their MCP session and target; proxied remote output uses the
owning daemon’s HTTP scope. HTTP MCP-compatible output and the
IPC MCP passthrough intentionally share the local ipc continuation scope for
the same target: either local-user transport can resume a token issued by the
other. Tokens are opaque snapshot references, not authorization credentials;
normal endpoint admission and the local OS-user trust boundary still apply.
Frame workload dump
The debug action=frame_workload_dump (local or token-authenticated callers) schedules the enabled frontend recorder dump. Like invoke_js, read eval_js logs for completion; submission does not prove frontend liveness. POST /debug/frame-workload and desktop save_frame_workload share the bounded writer. See stall evidence.
Persistent usage rollup (#2808-5998)
Separate from the call audit and independent of mcp_call_audit_enabled. Gated by mcp_usage_rollup_enabled (default true in every build; Settings > MCP > Usage). tools/call and tools/list ingress add counts to an in-memory sum; it is written to mcp_usage.sqlite3 in the app config directory (beside progress.sqlite3) when 30 seconds have passed since the last write, and before every read. A crash loses at most that interval.
Table mcp_usage_daily, one row per UTC day x client (claude, codex, ego, grok, other) x role (orchestrator, agent, managed_child, from caller_role; rows before 2026-11-07 say spawner) x tool x action: calls, app_errors (application errors, not counting rejections), invalid_arguments (replies with code=invalid_arguments), bytes_hist (24 power-of-two buckets of text reply bytes), bytes_max, catalogue_bytes (tools/list replies under tool tools/list, plus search_tools and get_tool_schema replies). p50 and p95 are the upper bound of the bucket that holds the rank, never above bytes_max: an estimate within a factor of two. Tool and action come from the native catalogue or a connected upstream; an unrecognized tool name is stored as opaque with no digest. Arguments, reply bodies, error text, session ids and peer names are never stored. Rows older than 90 days are deleted at each write. Size (estimate, not measured on a live instance): about 150 bytes per row and at most a few hundred rows per day, so under 100 KB per day and under 10 MB at 90 days.
GET /mcp/usage (IPC get_mcp_usage) returns the last 7 days grouped per role, then per tool action (clients and days merged): {"enabled":true,"days":7,"roles":[{"role","calls","application_errors","invalid_arguments","catalogue_bytes","actions":[{"tool","action","calls","application_errors","invalid_arguments","response_bytes_p50","response_bytes_p95","response_bytes_max","catalogue_bytes"}]}]}. While the setting is off it returns {"enabled":false,"days":7,"roles":[]} and records nothing; stored rows stay until they age out.
Runtime call outcome audit (#2010-30a7)
Gated by the persisted mcp_call_audit_enabled setting (#2136-dc79): default false in release builds, true when cfg!(debug_assertions). While off, tools/call ingress records nothing and GET /mcp/audit (IPC get_mcp_audit) returns {"enabled":false,"records":[]}; retained rows are not returned. Each row also carries outcome (replied, error, cancelled), which describes the reply, never the effect. Settings > MCP > Call audit shows the rows; it fetches on open and on Refresh only.
GET /mcp/audit returns at most 100 newest completed/cancelled tools/call
observations from an instance-local 1024-record memory ring. retained, evicted,
capacity and limit describe retention. Restart clears the ring. HTTP and ACP
both enter mcp_post, so a collapsed call is one runtime ingress record, not an
extra inferred hop. Existing inbox-read audit records are unchanged.
Each row has a server call_id, optional UUID client_call_id and
parent_operation_id, catalogue-recognized native, discovery or connected-upstream operation, optional resolved
target (kind, id, name), optional SHA-256 target_digest, start time, response_text_bytes, application_error,
transport_error and effect. Unrecognized tool names are digested. Known runtime session/peer identities may be retained; arbitrary target arguments are not. Arguments,
response bodies, arbitrary metadata and error messages are never retained.
The target digest covers the first string target among to, session_id, path,
worktree_path, id, including the field name and a NUL separator. It is a grouping
key, not authorization or anonymization against a known-value dictionary.
Clients may supply UUIDs in params._meta["tuic/call_id"] and
params._meta["tuic/parent_operation_id"]; invalid values are omitted. Use a new
call UUID per attempt and a common parent UUID for one intent. Different target
hashes in a batch are distinct operations, not evidence of retries. Neither a
shared parent nor a repeated target proves an attempt is a retry.
Text cost is the sum of UTF-8 byte lengths of top-level MCP content blocks whose
type is text, after response formatting. It excludes JSON escaping, envelopes,
resources, images and transport overhead. A native error:null is not an
application error; upstream isError is preserved. Error text is not copied.
Effects classify the handler observation: read_only for a recognized read-only action,
completed for a successful handler return, failed for an application-error reply,
and not_started for an explicit preflight refusal, including private-secret-form
inspection refusals on native, direct-upstream and wrapped-upstream calls. Explicit handler effect contracts
remain authoritative. completed does not mean a submitted command finished, queued
speech was heard, a remote job finished, or the client received the reply. Native
handler interruption and upstream failures after dispatch remain unknown; the
proxy carries a typed effect so pre-send policy/configuration refusals are not confused
with a lost upstream reply. No classification parses error prose.
A cancelled dispatch has unknown application outcome, no observed response bytes,
transport_error=cancelled_before_reply and unknown effect. A constructed reply
has transport_error=unobserved_after_reply_construction: this does not prove
client delivery or absence of a lost reply, and is never rollback evidence.
The projection counts actual MCP ingress, not all Codex model custom calls. Client-side correlation/captured traces are needed to identify Codex attempts that never reached MCP or whose replies were lost. Do not evaluate transcript JavaScript to derive call counts. No OTel exporter is enabled by this feature.
The partial live recording records a real ego-selected call with a server-retained client UUID, an application refusal, and a client disconnect over local IPC. It excludes response bodies and does not complete the four-outcome fixture: real client permission denial and rendering success still require recording. A successful speech-status read is not rendering evidence.
Managed stateless reconnect context (#2008-5317)
A modern tools/call without mcp-session-id can recover mail/project routing
from an exact host-issued x-tuic-session only when that peer has a live PTY or
ACP root. The internal managed-call:<peer> routing key is not a wire protocol
session: the response does not introduce a legacy session header. Existing
binding ownership, sibling-bridge policy and replacement migration remain the
only identity mutation seams. Project resolution still follows the live binding;
it never uses the focused repository, a display name or an invented path.
An unknown/headerless peer receives code=identity_context_required,
effect=not_started, retryable=false and bounded repair guidance. Managed
callers must reconnect using host context; external callers initialize and then
register on that protocol session. repair.max_attempts=1 and
retry_after_context_change=true prohibit an unchanged retry policy; the client
must enforce that bound. Server diagnostics alone do not prove ego compliance.
An external caller without a project still receives the Progress core’s explicit
project_required error, never a guessed project.
Durable independent mail subscriptions
agent action=subscribe subscription_id=pump filter=actionable creates a reader
owned by the bound peer identity. Repeating it resumes the same reader. Use a
separate ID for each pump or watcher. The filter is immutable: actionable
(default) excludes routine TUIC lifecycle/idle notices; all includes them;
exit selects exits, including failed exits; failure selects nonzero exits
and prompt-delivery failures. Peer messages, including BLOCKED and RESULT,
remain actionable regardless of their wording. Unknown system notices fail open
as actionable. No model-side lifecycle classification is needed.
Read with agent action=inbox|wait subscription_id=pump [limit=1..100].
The reply contains messages, count, cursor, acknowledged_cursor,
missed_count, and has_more. A filtered wait returns only for matching mail
or matching retention loss. Routine traffic does not end the wait. For a
continuous background consumer, use the HTTP event stream below or subscribe
to the ACP resource; the consumer does not need a model-driven wait loop.
Subscription batches do not use the legacy byte pager: byte_budget and
continuation are rejected before either reader is consumed. Use has_more
after explicit ACK to request the next bounded batch. Wait retains its separate
lease path and also rejects byte paging.
After processing a batch, call agent action=ack subscription_id=pump cursor=<returned cursor>. Reads do not acknowledge. A pending batch’s message
range is frozen until acknowledgement, so a retry cannot expand it to include
new results. A changed limit takes effect after the pending batch is acknowledged. Acknowledgement is durable and idempotent. Read again after ack
when has_more is true. A reconnect under the same peer identity and reader ID
resumes after its acknowledged cursor. Reclaim the same explicit peer UUID when
registering a new headerless MCP connection. Changing UUID does not migrate
subscription cursors; legacy replaces still migrates the legacy inbox only.
Delivery is at least once until acknowledgement, not exactly-once execution. If processing succeeds but ack does not reach the server, the retained batch is replayed. Deduplicate external effects by message ID. Acknowledged results do not replay. Concurrent readers must use distinct subscription IDs; sharing an ID means sharing its acknowledgement. Subscriptions never acknowledge another subscriber or advance the legacy inbox cursor. Explicit subscription ACKs mark exact matching live message IDs as observed under the same recipient delivery gate as legacy snapshot ACKs. This prevents a later FIFO eviction from counting already-delivered mail as lost. It does not acknowledge the legacy loss watermark; only the legacy snapshot ACK settles that snapshot’s loss count. Filtered gaps remain unobserved and cannot clear unrelated wake evidence.
The SQLite journal (<config dir>/mail-subscriptions.db, with WAL sidecars)
retains the newest 1000 messages per recipient across process restart. This
is a message-count bound, not a byte budget or an unlimited result archive.
Every common inbox insertion is journaled before its change notification,
including forwarded peer mail. Retention is independent of the legacy
100-message FIFO and lifecycle coalescing. missed_count counts matching
unacknowledged events evicted since the reader started or last acknowledged the
gap. Filtered routine evictions do not wake an actionable reader. A new reader
starts at the oldest retained position and does not claim historical losses
before its creation. Acknowledging the returned gap cursor clears the reported
loss. Loss accounting can be conservative when an ACK is delayed until its
offered batch is below the retention floor: already-processed evictions can
remain in missed_count until a later gap ACK clears the aggregate. This does
not discard additional mail. A journal append failure is logged and makes subscription reads fail
explicitly for the lifetime of that process rather than claiming an empty inbox.
Legacy in-memory mail delivery remains available.
Each peer may keep 32 reader IDs (1–64 ASCII letters, digits, _ or -).
agent action=unsubscribe subscription_id=pump removes a reader, not retained
mail. The journal and cursors are not removed by MCP disconnect or peer
retirement. Legacy calls without subscription_id retain their existing
since/next_since semantics and notifications; since is rejected for a
subscription. No new Tauri command is needed: peer actions still require the
MCP identity binding, including calls through the IPC MCP bridge.
Continuous HTTP and ACP notifications
POST /agent/subscriptions/action: accepts the samesubscribe,inbox,ack, andunsubscribepayload as the agent tool.GET /agent/subscriptions/{id}/events: SSEmailevents carry bounded batches withid: <cursor>; keep-alive comments carry no mail. A connection emits an unacknowledged batch once. Ack through the action endpoint advances it to the next batch. Reconnect replays an unacknowledged retained batch.Last-Event-IDdoes not acknowledge processing; only explicit ack does. Stream errors emitevent: errorand close. Both endpoints require a loopback or credential-verified caller, an enabledagenttool, andMcp-Session-Idbound to the reader’s peer. Body fields cannot select another peer. They use the same service and validation as MCP tools.- On MCP over ACP, subscribe/read resource
tuic://inbox/subscriptions/<id>after creating the reader. It sendsnotifications/resources/updatedonly for a new actionable batch cursor or a journal error. It also filters the idle-ego wake; routine traffic sends neither a resource update nor a wake. Ack uses the agent tool. The wake cursor is consumed only after a turn is accepted; a busy/skipped attempt stays eligible when later mail arrives at the same frozen cursor. Selecting a durable inbox resource replaces the legacy inbox as the idle-wake source on that ACP connection. Explicitly subscribing totuic://inboxstill requests its legacy unfiltered resource notifications. - HTTP MCP
/mcp, its SSE/streamable response transport, and the local IPC MCP bridge expose the same agent actions. The new HTTP SSE endpoint supplies continuous durable-mail notifications; ordinary GET/mcpand the legacytuic://inboxresource are not silently reinterpreted as filtered readers.
Controlled replay fixture: the audit’s four captured idle notifications yield four legacy lifecycle deliveries and zero actionable deliveries. A subsequent RESULT produces one matching batch per independent acknowledged reader. This measurement is not a claim about product-wide token or latency savings.
session action=input also accepts only pty_description (string or null).
This updates or clears the context-bar description without sending PTY bytes.
Managed agent action=launch uses the same private pre-dispatch static contract as other native actions. Discovery describes the disjoint receipt-read and creation forms, workspace alternatives, and nested spawn argument types; the server enforces exclusivity. Invalid calls return structured invalid_arguments with effect=not_started before the launch journal or PTY is touched.
Client tool identity
Server instructions use TUIC protocol names as shorthand. Claude Code exposes the configured tuicommander server tool as mcp__tuicommander__agent; Codex 0.163.0 exposes namespace member mcp__tuicommander.agent. A different configured server alias changes that prefix. These are not the client native Agent tool. Use the actual exposed schema; a bare tool_name=agent is valid inside TUIC lazy call_tool, not as a guessed direct client call.
The recorded client names and localhost-only capture script are in src-tauri/src/mcp_http/fixtures/tool-names-2108.*. The probe advertises one MCP tool and captures only outgoing tool names, with isolated homes and dummy keys; it rejects the model request without a vendor call. This records client qualification, not a production TUIC server handshake.
Remote session closure
MCP session action=close accepts a remote connection_id or connection-qualified session reference. The host resolves aliases on the owning daemon and sends authenticated DELETE /sessions/{id}. The caller’s own PTY remains protected from self-close, and non-loopback MCP callers cannot invoke destructive close actions. A disconnected connection reports an error; it never falls back to a local session. HTTP DELETE and local MCP close use the same teardown, session-closed events and retained output tombstone. Repeating a close of a retained tombstone succeeds. Explicit close remains user-directed and is not limited to abandoned shells.
Detached command identity boundary
Native tuic bg removes TUIC_SESSION and TUIC_PARENT from the command
environment and sets TUIC_BG_COMMAND=1. Headerless MCP identity recovery
checks each process up to its 16-hop bound and stops at this marker before
reading an identity or reaching the foreground runner. This also covers a
bridge whose agent removed the marker from the bridge environment. Ordinary
foreground ego ancestry recovery and explicit identity headers are unchanged.
The detached runner keeps its caller identity and launch-time completion origin
for typed completion queueing. A native user stop revokes that origin at the
serialized PTY writer boundary, before any late completion can write. Stale
completions remain in the runner log and receipt and never fall back to mail.
This is an identity boundary, not a security sandbox or a delivery-policy bypass.
Session usage reads
GET /sessions/{id}/usage and get_session_usage share session_usage.rs.
The owner check precedes all local process/cache/provider reads. Connected
remote PTYs forward to the owning daemon; an absent/failed route returns
remote session unavailability. No local-account fallback is allowed. The
frontend transport table also supports the normal session-owner routing.
TLS readiness
get_mcp_status and GET /mcp/status expose tls_active. The loaded dual-protocol
serving task owns a strong lifetime token; AppState holds only a weak token.
Provisioning failure, no TCP listener, task completion, and cancellation do not
leave HTTPS active. Replacing the token prevents an old task’s exit from clearing
a replacement listener. Tailscale detection retains its separate capability
state for provisioning and Host trust. Settings and connect URLs use live TLS
readiness, not that capability. The CLI provisioning fallback reads each PEM
stream from stdout, because the sandboxed macOS app CLI cannot write into the
caller’s temporary directory.
Append-only story notes
add_note and list_notes use the same shared story service on all transports. Notes retain backend actor/time and the subject revision without advancing it. Optional {runId, commandId} receipt references are validated against the same project and plan. See Native stories in the HTTP API for fields, replies, bounds, and append-only semantics.
Headless manual TLS listener
run_remote() validates services.tls before starting listeners. Manual mode
uses the same axum-server/rustls dual-protocol acceptor as desktop remote access.
HTTP responses, SSE and WebSocket upgrades share one HTTP+HTTPS TCP listener,
preserving local relay and SSH HTTP clients; TLS off uses the plain acceptor. The
tls_listener weak lifetime is published only after TLS listener setup and
expires on shutdown, cancellation or serving failure. Invalid PEM is fatal.
Shared AI Chat selection
GET /acp/chat/selection returns { workspace, sessionId, replacing } for the host-configured canonical AI Chat workspace (sessionId is nullable). replacing names the conversation that sessionId continues while the selection is a compaction successor, else null; a follower replaces that tab in place. The link is held in memory and is not persisted. PUT /acp/chat/selection accepts { sessionId: string | null, replacing?: string | null } and requires local or authenticated access. It persists through the shared config delta writer. Last committed selection wins. Changes, including config deletion cleanup, dual-emit payload-free ai-chat-selection-changed on desktop IPC and /events SSE. Clients reread on this event and on reconnect; adopting a snapshot does not write it back. Repository focus and session CLI | Chat remain per device.
Story request drafts
The guarded ACP sub-router exposes POST /acp/one-shot/prepare,
POST /acp/one-shot/{request_id}/cancel and POST /acp/story-draft.
These match the desktop prepare, cancel and generation commands. Rust validates
model output before returning an editable draft. Generation has no store access.
The existing story action accepts an optional reviewed problem beside input
and persists it atomically with creation; MCP and CLI use that same service.
ACP connection launch environment
POST /acp/connections and acp_connect accept the same optional string-map
env. The manager passes it directly to the child configuration, before the
host-issued peer identity, and does not retain it. Supplied env on an existing
live peer is refused with disconnect-first guidance; an omitted env keeps
normal adoption. Reconnect drops the previous overrides. Request diagnostics
redact values, and connection snapshots contain no launch environment.
Task-scoped secrets
secret put stores write-only name/value arrays under a task scope with a TTL
in seconds. MCP runs through the existing app transport authentication. MCP
agent spawn and HTTP POST /sessions/agent select the same scope and inject
only child environment variables. Deadlines revoke future injection; per-session
zeroizing masks remain until teardown. The PTY ingestion boundary sanitizes
output before every publication path, including tcap and diagnostic rings.
Bounded repository file pages
GET /fs/read supports optional byte offset/length. Either selects a
base64 JSON page with offset, bytesRead, totalSize, hasMore and
clamped. The default/maximum page is 1 MiB. The blocking pool performs a
seek and bounded read through the same canonical guard as full text reads.
No parameters keep the text reply and editor cap; the remote editor adapter
also keeps its text-only cap. See Bounded file reads
for defaults, UTF-8 handling, errors and concurrent-file limits.
Post-land proof service
The existing workflow run action accepts {"action":"proof","request":...}
and returns {"type":"proof","value":...} identically over IPC, HTTP and
MCP. ProofAction is included in the generated MCP schema. Status/tick,
explicit operator/gate configuration, cohort ownership/execute/finish/retry,
registry gate/backup/restore and read-only Test Janitor comparison share one
backend. See the backend workflow guide, Post-land proof cohorts, for payloads,
defaults, target requirements, receipt validation and restore limits.
Typed agent reports use the shared Rust mail owner: agent send accepts an optional report object, while inbox/wait/subscriptions preserve it. Shared HTTP/IPC session rows and MCP inventories expose derived stage, reason and report acceptance time. See the contract and ordered table.
The managed workflow tool accepts the full WorkflowAction under {action:"definition",input:{action:...}}, including draft lifecycle, publication, agent-policy preview/import and run-pin inspection. Its private validation schema is derived from the Rust service enum. Definition actions require a bound live managed session and resolve its project before calling the shared service; file actions keep the same envelope.
Managed PTY silence alarms share the existing idle-maintenance sweep. Inventory field stalled is independent of stage, and parent mail reports one state_change/stalled per silence episode. See silent workers.
Workflow run input supports read-only inspect and the WF15 release authorize request for attached ACP peers using their host-owned project root, without a terminal binding. PTY callers retain the existing run actions. The inspection supplies committed snapshots and bounded cursor deltas; chat content is never authoritative run state.
Attention projection
GET /agents/attention exposes the shared Rust snapshot of waiting items and agent health on desktop and headless routers. Native report publication, input submission and relevant story mutations dual-publish boss-attention-changed. Workflow changes use the existing workflow event. Remote session-state or attention events reseed authoritative session rows, then publish an origin-stamped attention invalidation; failed refreshes clear cached stages rather than retaining old stages as current.
Portfolio workflow actions
MCP workflow action=run validates the generated PortfolioAction schema under {"action":"portfolio","request":...}. It shares the IPC/HTTP project-scoped service, retained claim rules and bounded replay contract; see Portfolio delivery. No additional route or story-store SQL connector is introduced.
ACP story actions
The story tool accepts a live host-issued ACP MCP origin as well as a bound PTY. The connection generation must match; settled or unbound origins are refused. ACP actions derive their project from the live peer root and retain the peer ID as managed actor provenance through the story backend port and the native execution ledger. Native story revision, project and approval checks still apply. ACP implementers can check satisfied criteria and submit the candidate for independent review before reporting completion; a report itself does not advance story status. Manual claim remains PTY-only because it uses PTY claim lifecycle ownership.
Worktree creator provenance
repo worktree_create records its bound TUIC peer identity as creator_session
in Git administration metadata. ACP peers do not need a PTY. The create receipt
and repo worktree_list expose this identity after reload; legacy and unbound
allocations expose null. Creation and API inventory use the allocation lock
so inventory cannot pass the allocation before its creator write completes.
Recycling and archived-checkout restoration replace the previous allocation’s
creator. The worktree-created event keeps its separate live-PTY routing identity.
Automation definition create/update accepts optional boolean close_on_finish
(default false) on MCP and the shared /automations/action API. Confirmed
completion reuses explicit session close and its desktop/SSE notification; it
never requests worktree cleanup or closes sibling sessions.
AI Chat message actions use acp_message_actions behind matching IPC and HTTP adapters.
The shared module builds conversational prompts, submits them to the original ACP queue, then
saves accepted reaction marks through the existing config delta transaction. It does not call a
provider rating API or answer permissions. GET reactions and POST message-action are documented
in the HTTP API reference. The existing settings-changed bridge invalidates saved marks.
Story backend selection status
The existing story action route carries backend_status without first requiring a working content backend. IPC, HTTP, CLI and managed MCP reads use the same project ownership and selector. approve_connector {installation,expected_identity} is a human UI write; managed actors and unauthenticated HTTP callers cannot approve execution. No new transport route is required. See story-backend-protocol.md.
set_backend {backend:"native"|"automatic"|"wiz-stories"} is also an authenticated-human-only shared action. Native continuity precedes discovery; active run snapshot provenance prevents backend changes after restart. Approval compares the displayed generation (entry/version), not a full installation-tree digest.
Heap diagnostics share the HTTP control plane on both entry points: GET/POST /diagnostics/heap verifies status, toggles sampling and writes dumps on a blocking worker. /diagnostics/memory reports allocator provenance separately from native malloc zones and physical footprint. See Heap profiling.
Neutral workflow parity
workflow {action:"neutral",input:<NeutralAction>} uses the same backend action and {type,value} reply as IPC and /workflows/neutral/action. Project selection uses the live managed PTY/ACP binding; local/authenticated transport access does not replace native service admission. With a native catalog installed, bound projects discover the workflow tool even before creating a draft. See the neutral contract.
Scheduled neutral bindings
The existing neutral action accepts trigger source scheduled with kind: "schedule",
resource_prefix: "schedule:<binding id>", events: ["due"], and optional draft field
schedule: {"cron":"0 9 * * *","timezone":"UTC","text":"Review the summary"}.
Only scheduled bindings accept that field, and it is required for them.
The installed mapping fields are text (string) and occurrence_ms (integer).
Starts and exact local approval answers use the existing run/Answer envelopes.
See trigger admission.
ACP Client for ego
TUICommander speaks the Agent Client Protocol (v1) as a client, to
ego as the agent. Two repositories, no shared
crate: both pin agent-client-protocol and agree on the wire, not on types.
AI Chat uses this backend through acp_* Tauri commands and, identically,
through /acp HTTP routes.
Layout
| File | What lives there |
|---|---|
src-tauri/src/acp/mod.rs | The vocabulary: ids, snapshots, events, errors, notices, and the capability snapshot taken at initialize |
src-tauri/src/acp/manager.rs | AcpClientManager — one supervised child per connection, and every operation a caller can ask for |
src-tauri/src/acp/connection.rs | The per-connection actor: decides and writes serially, waits concurrently |
src-tauri/src/acp/events.rs | AcpEventJournal — the ordered, bounded record every subscriber reads from |
src-tauri/src/acp/ego_ext.rs | _ego/pause, _ego/resume, _ego/compact |
src-tauri/src/acp/mcp_host.rs | MCP-over-ACP: the host contract and the per-connection channel |
src-tauri/src/mcp_http/acp_mcp.rs | The host: tuicommander served through the /mcp handler |
src-tauri/src/acp_commands.rs | The Tauri surface: one command per manager method, nothing else |
src-tauri/src/mcp_http/acp_routes.rs | The HTTP surface, calling the same cores |
Conversational message actions
acp_message_actions is the shared IPC/HTTP service for AI Chat reactions and comments.
It sends the native source message ID, a quote capped at 4000 characters, and the action
through the original attachment’s prompt queue. The text states that the action is
conversational, not an evaluation or authorization. No provider-specific feedback path,
permission response, reconnect, or PTY fallback is used.
Accepted reactions are stored by session and native message ID in configuration deltas. The service serializes acceptance through persistence; failed queue acceptance does not change marks. A persistence error after acceptance explicitly tells the client not to resend. Marks mean queue acceptance, not model consumption. Removing a mark sends a new conversational turn and cannot retract earlier context. Clients reread marks after settings invalidation, reconnect, and action receipts.
MCP over ACP
Every attended session is given one MCP server,
{"type":"acp","name":"tuicommander","serverId":"tuicommander"} (schema 1.5.0,
unstable_mcp_over_acp). ego reaches it on this connection:
| ego sends | TUIC answers |
|---|---|
mcp/connect {serverId} | {connectionId}; any other serverId is -32602 |
mcp/message {connectionId, method, params} request | the inner MCP result, or the inner MCP error as the ACP error |
mcp/message notification | accepted, nothing sent back |
$/cancel_request {requestId} for a pending mcp/message | that request answers -32800 and its handler future is dropped |
mcp/disconnect {connectionId} | {} |
TUIC sends mcp/message notifications on the same connectionId for what the
HTTP SSE stream carries: notifications/tools/list_changed and channel
notifications. An unknown connectionId is -32602 and never reaches the host.
The connection layer only routes; McpOverAcpHost is injected with
set_mcp_host because the handler needs the application state the manager must
not hold. AcpMcpHost opens one MCP protocol session per mcp/connect, bound to
the peer id ego was launched under (its TUIC_SESSION), and sends every request
through mcp_post — the same handler, tool registry and collapsed surface as
HTTP /mcp. mcp/disconnect and the end of the ACP connection both run
end_mcp_session, the teardown DELETE /mcp uses. There is no tuic-bridge
process and no HTTP round trip for ego.
Two resources exist only on this channel (its initialize/server/discover
add "resources":{"subscribe":true}; HTTP /mcp does not):
| URI | Contents |
|---|---|
tuic://workspace | {repos:[{name,path,branch,liveAgents:[{sessionId,name,agentType}]}],viewedRepo} — repositories.json order, agents by PTY cwd, activeRepoPath |
tuic://inbox | {messages:[{id,from:{session,name},body,timestamp}],nextSince} — unread mail after the peer’s cursor; reading does not advance it, agent action=inbox does |
resources/subscribe {uri} opts in; a subscribed resource gets one
notifications/resources/updated {uri} per 250 ms burst, and the workspace only
when its content changed. Mail also wakes an idle ego: two seconds after the
first message of a burst, if any of it is still unread and no turn is running on
the connection, wake_idle_peer sends one session/prompt carrying
PEER_MAIL_WAKE. A busy ego hears about mail at its next tool boundary through
resources/updated instead.
The actor
One ConnectionActor per connection. Deciding and writing is serial — a single
task owns the decision of whether an operation is allowed and the write that
follows, so two callers cannot both pass a gate that only one of them should
have. Waiting is concurrent: replies are awaited in a FuturesUnordered, so a
turn that takes a minute does not hold up a cancel.
Agent→client requests (session/request_permission,
session/create_elicitation) arrive on the same channel as session/update.
That is deliberate: the question and the updates that explain what is being
asked about must stay in the order the agent sent them, and two channels would
reorder them.
The SDK hands a responder to a callback that holds the dispatch loop. Answering there would freeze the connection for as long as a person takes to decide — so the responder is carried out of the callback and parked. What the tests pin is that it is always answered exactly once: by the person, by the cancel that took the question away, or immediately when there was no seat to offer.
Capabilities are checked on the way in too. initialize advertises
elicitation.form and nothing else, so an elicitation/create in url mode —
or in one from a version this client has never seen — is declined on arrival
rather than seated. Seating is how rendering happens here: the request lands on
the attachment and a frontend draws the form it knows how to draw, which is
precisely what the protocol says a client must not do with a mode it does not
understand. A URL elicitation drawn as a form is worse than a refusal, because
the address it is actually asking about is what a form has nowhere to put.
A bad answer never costs the person their question. An answer is validated
before the seat is taken, so a permission option the agent never offered, or an
elicitation action outside the protocol’s three, is refused with invalid_input
and the question stays open for a real answer. Forwarding either would spend the
seat on something the agent cannot read, and nobody could then try again.
The journal
Every accepted callback and every local settlement is stamped with a sequence number, appended, and only then fanned out. That gives a host two things a snapshot cannot: the order the agent said things in, and the ability to join late.
It is bounded (1024 events). A subscriber asking for a cursor that has fallen
off the end is told stream_gap rather than being resumed past the hole: the
missing chunks exist nowhere in this client, and a stream that silently skipped
them would render as a turn where part of what the model said never happened.
Recovery is a fresh connection and session/load, which replays from ego — the
only place that still knows.
Nothing in append can block the SDK reader: an uncontended lock and a
broadcast send that drops the slowest subscriber’s view rather than waiting for
it.
Capabilities are decided before the wire
The initialize response becomes an immutable capability snapshot. Every
operation is checked against it, and an unadvertised one is refused with
capability_unavailable without sending a byte. The same holds for content
blocks a session never said it accepts, for extra roots, and for ego’s own
extensions — whose advertised version must match the one this client speaks.
This is why capability_unavailable is never retryable: the answer comes from a
snapshot taken once, so the identical request on this connection will refuse
identically. Reaching an agent that has it is a different action, not a retry.
There is no provider surface, and that is the same rule rather than a gap.
providers/list|set|disable are a draft the pinned schema keeps behind an
unstable feature, so ego does not serve them and never advertises them — and
providers/set would let whatever is connected rewrite the base URL that every
generation egresses to. Model, effort and mode arrive instead as
session/set_config_option options the session itself publishes, so a host
picks from what the agent offered rather than from a list this client made up.
A config_option_update may arrive after session/new, before any prompt.
It replaces the matching attachment’s complete option set and publishes the
connection snapshot before the update enters the journal. The frontend refreshes
that snapshot on the update, using the same path as an explicit set-config reply.
An empty offer clears the controls; other session attachments keep their options.
The snapshot is also what makes method_not_found fatal. Nothing reaches the
wire that the snapshot did not allow, so a method-not-found coming back is not
the agent declining — it is the agent disowning what it published, and the one
thing this client knows about it is no longer true. The caller is answered with
protocol_violation, and only then does the connection settle as failed: a host
that asked deserves to be told why, not just that the connection is gone.
When ego answers a prompt with its dedicated -32011 pause error, the client
settles that turn and records the attachment as paused. The AI Chat control
bar therefore keeps Resume available until _ego/resume reports running.
Other prompt errors settle the attachment to idle, even if their message
mentions a pause; the numeric error code is the state signal.
Each prompt error also emits turnFailed with the agent’s diagnostic and the
resulting attachment state. The event carries the turn ID in its envelope so
every subscribed view can show the failure in the conversation.
Two transports, one set of judgements
acp_commands.rs and acp_routes.rs are both thin. Neither decides what is
allowed, validates a permission option, or invents a fallback — those are the
client’s judgements, made once in crate::acp, so the desktop and a phone
cannot disagree.
The error body is the serialized AcpClientError on both. Over HTTP the status
is a translation of its code, never a second opinion: 400/404 for the caller,
501 when the agent never advertised the operation, 410 when the connection or
the cursor is genuinely gone, 502 when the agent answered with a refusal.
The one asymmetry is the stream, and it is a transport detail: a Tauri Channel on the desktop, a WebSocket in the browser, carrying byte-identical frames.
Lifecycle invariants
Written down because each of them is a variant the plan named and this client deliberately does not have:
-
One live process per peer. Concurrent connects for the same peer wait through launch and initialization, then reuse the registered connection. Connects for different peers remain independent.
-
A connection id is not public until initialization has succeeded. It is minted inside
connectand does not escape until v1 is negotiated, so there is nostartingorinitializingstate — nothing that is still coming up can be named, listed, subscribed to, or asked about. Launch and negotiation are phases of theconnectoperation, not states of a connection. -
A failed attempt is never registered and never settles. It is answered with
initialization_failedas an error code; there is no settlement reason by that name, because there is nothing there to settle. -
A settled connection stays readable, and then is forgotten. Ending is exactly when a host wants to read one — the reason, the attachments it had, the tail of its stream — so the last eight are kept. Kept forever they would be a leak: each holds a journal of up to a thousand events, and a
reconnectloop against an agent that keeps dying is an ordinary thing to happen. -
transport_errorcovers write failures too. A child that closes its pipes or exits produces a write failure, a stdout EOF and an SDK shutdown at once, and which one the supervisor sees first is a scheduling accident. A separatewrite_errorwould be an attribution no one here can make. -
A line that is not a frame does not end the connection. The SDK owns the framing: an unparseable line is answered with JSON-RPC’s
-32700and the reader carries on, and nothing about it reaches this client. So the mistake is reported to the only party that can do anything about it — the agent that made it — and the stream stays in sync, because a line is a frame boundary and the next one starts clean. The exception is a malformed line shaped like a response, which the SDK drops in silence: answering an answer is not a thing JSON-RPC can do, so a request it might have been for waits out the connection. -
A session is attached to a connection at most once. A
loadorresumenaming a session this connection already holds is refused withinvalid_input, not merged and not re-run. The attachment is where the running turn, the usage totals and the ids of the questions a person has open live, and attaching writes a fresh one — so a second attach would blank the turn, and the response that settles it would arrive for a turn nothing names any more and be dropped as stale, leaving a host watching a turn that never ends. The seats, meanwhile, outlive the overwrite, so the two views would then disagree about what is being asked. A host that wants the history replayed detaches first, which says what it means. A fork is not affected: it names the session it forks from and comes back with an id of its own. Aloadorresumestill waiting for its answer holds the session too, so a second one sent meanwhile is refused the same way: each load makes ego admit every MCP server again. Every attach is logged (ACP attach, with the wire method and session id) so a storm of them can be attributed. The AI Chat panel keeps one replay per tab in flight and does not replay a tab whose load failed until a person selects it or presses Retry. -
Configured conversation reopen preserves live output.
acp_chat_openreports whether history was loaded usingreplayed. The client keeps the existing transcript while the request is pending or refused. On a genuine replay, it clears the projection before subscribing to the returned journal; an already attached conversation keeps chunks received during the request. -
A replay starts before the load response. Ego may send
session/updatechunks whilesession/loadis pending. The requested session ID is already known, so those updates enter the ordered journal before the attachment is published. Updates for other unattached sessions are still discarded. Usage received during the replay is included in the resulting attachment snapshot.
Changing the first two means a different, asynchronous connect API — one that hands back an id before there is a connection behind it, with its own cancellation, retention and ownership rules. That is a decision to make when something asks for it, not a set of enum variants to leave lying around.
Process authority
Shared runtime decision (2026-11-06, #2859-fdff): AI Chat keeps separate processes for distinct peers. An isolated ego 0.4.3 raw ACP probe measured later same-process session/new calls at 37–41 ms, versus 109–255 ms for separate-process launch, initialization and first-session creation; these samples exclude MCP and model prompts and are not TUIC end-to-end measurements. Pooling is not implemented: src-tauri/src/acp/manager.rs sets the peer’s TUIC_SESSION on the process launch (near line 304), while ego’s crates/ego-tools/src/exec/backend.rs:152–170 takes inherited tool environments from that process. Separate listener connections can preserve MCP peer identity, but cannot give simultaneous tool subprocesses different host identities. A future ego per-session host-environment extension would need an explicit negotiated contract that binds the host-issued identity to each session’s execution and subprocess environment, keeps concurrent sessions isolated without process-global environment changes, and defines identity ownership across load, fork, compaction and reconnect. It would also need to preserve per-session MCP routing and cancellation. The coordinator rejected pooling without that capability; this is not a measured ego defect.
The ego binary is the ego_executable setting, read at each connect. It is
not held by the manager — a copy taken once would keep launching the previous
binary after somebody corrected the setting, without ever saying so — and it is
not an argument of any command or route, so no request body can name what this
machine runs. An empty setting refuses every connect, because “not configured”
and “configured wrongly” are different things to be told.
POST /acp/connections and .../reconnect are the only routes that launch a
process, and the only two that take the loopback-or-authenticated guard.
Notices
AcpEventJournal::append is the single place every event is stamped, so it is
where the wake signal is derived. Four kinds — ready, settled,
interaction_pending, interaction_settled — become an AppEvent::AcpNotice
that spawn_acp_notice_pump mirrors to the desktop window and to /events.
A turn’s chunks never ride that bus: one turn emits more of them per second than the 256-entry broadcast can carry without lagging every unrelated subscriber in the app. A notice says where to look; the payload stays on the stream, the snapshot, or the interactions list.
settled covers both a turn finishing and a connection ending. They are told
apart by whether the notice names a session, not by a fifth kind.
Tests
src-tauri/tests/story092_*.rs, against tuic-acp-fixture-agent — a
non-bundled binary that replays a tests/fixtures/acp/*.jsonl scenario through
the exact production launch path. tests/fixtures/acp/ego-initialize.json is a
recording of what real ego answers, copied from ego’s own committed golden;
editing it to make a test pass would turn the recording into a wish.
Mid-turn text steering
The shared Rust connection actor routes text-only acp_session_prompt submissions
through advertised agentCapabilities._meta.ego.steer v1 (_ego/steer, text
content). Only a running, prompting attachment with an empty FIFO qualifies. Accepted input returns
the existing turn ID, emits no PromptSent, and appears through ego’s
user_message_chunk. Steering reserves its submission position in the existing
FIFO until the response arrives; later submissions queue behind it and cannot drain
past it. Accepted or uncertain outcomes consume the reservation. not-busy and
rejected retain it for normal prompt serialization;
attachments and absent or mismatched capabilities retain the queue. An uncertain
transport outcome is reported without retry because acceptance may be durable.
Only the _ego/steer request has a 10-second deadline (EGO_STEER_TIMEOUT):
this is a durable append that ego normally acknowledges in milliseconds. A timeout
reports that delivery is uncertain, releases the FIFO reservation through the
existing error settlement, and never resends the text. Other ACP requests retain
their existing behavior.
Repository profile ceiling
Desktop acp_session_new, HTTP session creation and new conversation-specific
chat launches call the same
acp_commands::session_new core. The manager reads .tuic.json at the canonical
session cwd. If it contains ego_profile, the request includes
_meta.ego.profile and the machine Settings selection as ceilingProfile.
An empty machine selection refuses creation. TUIC does not calculate policy.
Ego resolves and restricts mode, sandbox, roots and executable paths.
TUIC requires ego to acknowledge both selected names, an effective policy object
and a string-array warnings result before attaching the session. This prevents
an older ego that ignores the extension from being exposed as a bounded session.
Attachment snapshots carry nonempty warnings as profileWarnings on both
transports. AI Chat shows them once per visible conversation through its existing
warning notice path. With no repo selection, requests and snapshots retain their
previous shape. Unattended sessions retain their existing launch behavior.
Load, resume, fork and compact rely on ego’s durable ceiling, rather than sending
a replacement authority from the current repository file.
When ego reports a failed session setup (config_option_update with
_meta.ego.configOptions.state = "failed"), the attachment snapshot keeps ego’s
reason as configFailure on both transports until a later config update
replaces it. The managed-launch readiness wait and the workflow model adapter
read it from the snapshot, so a failure sent before a wait subscribes ends that
wait at once with ego’s error instead of at the config deadline.
Ego settings (#1775-330c): model/provider defaults and perimeter reads/writes now
share one captured trusted executable, configured profile and AI Chat workspace
per operation. These owner CLI calls do not change any live ACP session. The
internal settings adapter preserves this distinction; launch defaults stay in the
app store and apply to later launches.
Session command offers
AcpAttachmentSnapshot.availableCommands holds the latest complete
available_commands_update offer, serialized identically over IPC and HTTP.
Every offer replaces the prior list, including an empty list. The ordered stream
continues to carry the original update; the frontend projects it into its owning
attachment, and a snapshot restores the list for a late subscriber.
Initial offers can reach the actor before a new/fork response settles, even when the agent wrote the response first. The actor retains command metadata for those pending attachments and for claimed load/resume ids, then adopts only the offer whose id matches the successful attachment. The holding map is bounded by pending attachments, never creates an attachment, and drops unclaimed entries when no unidentified attachment remains. Normal unknown-session transcript updates remain ignored. The composer sends advertised agent invocations as unchanged slash text; its host actions call existing chat handlers instead.
Workflow launch readiness
A workflow launch allows up to 30 seconds for its attached conversation to
advertise the requested effort and model values. Offers may arrive after
session/new through config_option_update. Effort is applied first because
it can change the model offer. Readiness waits release the global launch lock;
configuration reacquires it and reloads and validates the retained launch before
applying settings. Unrelated launches, receipt reads and prompt delivery remain
available during the wait. The absolute deadline is saved with the launch;
interrupted waits retain the same launch key, connection, generation and
conversation. Missing live inventory is uncertain and never starts a replacement.
The offer event wakes a fresh attachment check. Missing options or values still return the existing not-offered error when the deadline expires. Binding commits before prompt delivery. Once readiness succeeds, cancellation that won during the wait prevents binding and disconnects the unbound child.
MCP Proxy Hub
Module: src-tauri/src/mcp_proxy/
The MCP Proxy Hub turns TUICommander into a universal MCP aggregator. TUIC acts simultaneously as an MCP server (serving downstream clients such as Claude Code or Cursor) and as an MCP client (connecting to upstream MCP servers). Tools from all connected upstreams are merged into the single /mcp endpoint that TUIC already exposes, with each upstream’s tools namespaced as {upstream_name}__{tool_name}.
Architecture
Claude Code ──┐
Cursor ───────┼──▶ POST /mcp ──┬──▶ GitHub MCP (HTTP)
VS Code ──────┘ (TUIC server) ├──▶ Filesystem MCP (stdio)
├──▶ Database MCP (HTTP)
└──▶ Custom MCP (HTTP/stdio)
The entry point for all MCP traffic is POST /mcp (legacy Streamable HTTP
transport, revision 2025-11-25). When a tools/call request arrives with a name
containing __, the transport layer routes it to the upstream registry instead
of the native tool handler.
Module Layout
| File | Purpose |
|---|---|
mcp_proxy/mod.rs | Module declaration |
mcp_proxy/registry.rs | Central registry — connection lifecycle, tool aggregation, routing, circuit breaker |
mcp_proxy/http_client.rs | MCP client over Streamable HTTP |
mcp_proxy/stdio_client.rs | MCP client over stdio (spawned process) |
mcp_upstream_config.rs | Config schema, validation, persistence (mcp-upstreams.json) |
mcp_upstream_credentials.rs | OS keyring credential management |
mcp_http/mcp_transport.rs | Routing logic inside the /mcp handler |
Tool Namespace
All proxied tools are exposed with the prefix {upstream_name}__{tool_name}. The double underscore (__) is the routing discriminator — native TUIC tools never contain it. The separator splits only on the first occurrence, so tool names with internal underscores work correctly (e.g. upstream__tool__with__underscores routes to upstream upstream, tool tool__with__underscores). The namespace identifies the origin; the upstream description is preserved byte-for-byte so TUIC instructions are not duplicated across every discovered tool.
UpstreamRegistry
UpstreamRegistry (registry.rs) is the central hub stored in AppState as Arc<UpstreamRegistry>. It is thread-safe — all internal maps use DashMap (lock-free concurrent HashMap) and per-entry state is protected by parking_lot RwLocks and Mutexes.
Entry Lifecycle
connect_upstream(config)
│
├── Validate: no duplicate name, no circular URL
├── Build client (Http or Stdio)
├── Insert UpstreamEntry into DashMap
│
├── If disabled → status = Disabled (done)
│
└── Spawn async task:
initialize_entry()
├── Run MCP handshake
├── Fetch tools/list
├── On success → status = Ready, cache tools
└── On failure → circuit breaker records failure
→ status = CircuitOpen or Failed
Statuses
| Status | Meaning |
|---|---|
Connecting | Handshake in progress (initial state for enabled entries) |
Ready | Handshake complete, tools available |
CircuitOpen | Too many failures, backoff timer active |
Disabled | Disabled by user in config (enabled: false) |
Failed | Retry budget exhausted; health recovery resumes after the extended backoff |
NeedsAuth | Upstream returned 401/challenge (or its OAuth token was rejected and could not be refreshed) — awaiting the user to click “Authorize”. Tool calls are rejected with -32001 until a user-initiated OAuth flow succeeds |
Authenticating | OAuth flow in progress (user clicked “Authorize”) — tool calls rejected with -32001 |
Boot-Time Auto-Connect & tools/list Readiness
On startup, auto_connect_saved_upstreams() (mcp_upstream_config.rs) registers every saved upstream. It is spawned, not awaited, on both boot paths (desktop and run_remote, both in lib.rs): mcp_http::start_server parks on the shutdown signal and never returns, so any auto-connect placed after it would be dead code — leaving every upstream unconnected until the user touches the UI. Registration is fast (the per-upstream async initialize is itself spawned), so it never delays IPC socket binding.
To avoid serving a stale tool list, the registry exposes a one-shot settle gate:
mark_initial_connect_complete()— set byauto_connect_saved_upstreamsonce every upstream is registered (at both exits, including the empty-config early return). Asyncinitializemay still be in flight.await_initial_settle(timeout)— the firsttools/listcalls this beforemerged_tool_definitions(). It blocks (≤timeout, default 3s) until auto-connect is complete and no entry is stillConnecting, then serves. A globalinitial_settle_donelatch makes every later call a no-op, so steady-statetools/listnever blocks. On timeout it logs a warning and serves a possibly-partial list rather than hanging.
This also protects clients and older client versions that fetch tools/list during
their handshake but do not apply a later notifications/tools/list_changed.
Compatible current clients can refresh live; clients that ignore the notification
still receive the complete settled list at connection time.
Tool Aggregation
aggregated_tools() collects tools from all Ready upstreams, applies per-upstream tool filters, prefixes names, and annotates descriptions. Non-Ready upstreams are silently omitted. The merged list is returned as the tools array in tools/list responses alongside native TUIC tools.
Tool Routing
proxy_tool_call(prefixed_name, args) parses the __ separator, looks up the upstream by name, checks the circuit breaker, dispatches the call to the correct client, and records metrics and circuit breaker outcomes.
Circuit Breaker
Each upstream has an independent circuit breaker with the following thresholds:
| Parameter | Value |
|---|---|
| Failures before circuit opens | 3 |
| Initial backoff on open | 1 second |
| Maximum backoff cap | 60 seconds |
| Backoff growth | Exponential (1000ms × 2^excess) |
| Maximum retries before permanent failure | 10 |
State transitions:
- Closed → CircuitOpen: 3 consecutive failures trigger the circuit. Backoff starts at 1s and doubles with each additional failure, capped at 60s.
- CircuitOpen → Ready: A successful tool call or health check resets the failure count and closes the circuit.
- CircuitOpen → Failed: After the retry budget is exhausted, the entry is marked Failed with a 10-minute backoff. Health checks can recover it after that backoff; manual reconnect (
reconnect_mcp_upstream) is also available.
Health Checks
A background task (spawn_health_checker) runs every 60 seconds and probes all
Ready upstreams. HTTP probes use tools/list. Stdio probes check the child:
if alive, they refresh tools/list; if dead, they respawn it and repeat the full
initialize handshake and tool discovery. The existing client mutex serializes
calls and recovery, and the 5-second spawn rate limit still applies.
CircuitOpen and Failed upstreams are eligible after their backoff expires;
stuck Connecting entries repeat initialization. Successful recovery replaces
the cached tools, resets the circuit breaker, clears last_error, and publishes
the restored ready status/tool-list notification. Disabled and authentication
states are not probed.
Before this recovery path, a dead stdio process was only reported as not running: repeated health checks could not create a new process. Reply timeouts also tore down the child, so a slow action could cause a persistent upstream outage.
HTTP Client (http_client.rs)
Implements the legacy MCP Streamable HTTP transport (revision 2025-11-25):
initialize()— Reads Bearer token from OS keyring (if any), sendsinitializerequest, cachesmcp-session-idheader, sendsnotifications/initialized(fire-and-forget), fetchestools/list.call_tool(name, args)— Sendstools/callwith the cached session ID and auth token.call_tool_with_reconnect(name, args)— Callscall_tool, and on HTTP 400 (session expired) or connection error, re-initializes once and retries.health_check()— Pings viatools/list. Used by the background health checker.shutdown()— SendsDELETE /mcpwith the session ID to cleanly terminate the upstream session.
Custom HTTP headers are configured as headers: [{name, credential_ref}] on each server. The reference is a UUID; each value is stored through the existing upstream credential vault under an upstream-scoped key (<name>/header/<uuid>), separate from the Bearer/OAuth entry. No secret read API is exposed to the editor. POST requests and session DELETE resolve values in the backend at request time, so rotation takes effect without caching values in the client. Legacy configs omit headers and require no migration.
Header names use HTTP token syntax and are case-insensitively unique. Authorization cannot coexist with Bearer/OAuth; routing, framing and MCP transport headers are reserved. Values are validated without including them in errors and marked sensitive in reqwest. Same-origin redirects retain credentials, while the redirect policy stops cross-origin hops before a request reaches the new origin. Upstream response bodies and authentication challenge parameters are excluded from diagnostics because a server can echo credentials.
The User-Agent header is set to tuicommander-mcp-proxy/{version}. Every POST
also carries MCP-Protocol-Version: 2025-11-25; the stdio client offers the
same revision during initialization.
OAuth Refresh Failure → Re-Authorization
When a request needs a fresh token, refresh_token_if_needed() runs the refresh and routes any failure through classify_refresh_error():
- Fatal (
invalid_grant, no refresh token available, HTTP 400/401) →UpstreamError::AuthFailed. The refresh token is expired/revoked and cannot recover automatically. - Transient (network, 5xx) →
UpstreamError::Other(retryable) so the circuit breaker + health checks keep trying.
In initialize_entry_with_oauth, an AuthFailed on an OAuth2-configured upstream deletes the dead keyring token and re-enters NeedsAuth (UI shows “Authorize”) instead of parking the upstream in a silent red Failed/CircuitOpen the user can’t act on. Non-OAuth upstreams with a bad static token still go red (the arm is guarded by matches!(auth, Some(OAuth2 { .. }))). The health checker skips NeedsAuth entries, so there is no delete/init loop.
Stdio Client (stdio_client.rs)
Spawns a local process and communicates via newline-delimited JSON-RPC on stdin/stdout.
Process Lifecycle
spawn_and_initialize()— Rate-limited (minimum 5s between spawns), clears any existing process, spawns a new child with a sanitized environment, runs the MCP handshake.call_tool(name, args)— Sendstools/callJSON-RPC via stdin, reads response from stdout.is_alive()— Non-blockingtry_wait()check on the child process.health_check()respawns a dead child throughspawn_and_initialize(); a live child receivestools/list.shutdown()— Closes stdin (signals EOF), waits up to 2s for voluntary exit, then kills.
Reading stdout
A dedicated thread pumps the child’s stdout into a bounded queue so read_line
can wait with a deadline — a blocking read straight off the pipe is uninterruptible,
and the caller is a blocking-pool thread holding this client’s mutex. Nothing drains
that queue between calls, so the bound is what keeps an upstream that chatters while
idle from growing TUIC’s memory. Three limits, because a line count alone bounds
nothing: 256 lines, 8 MiB queued in total, and 16 MiB for any single line (a longer
one is discarded whole rather than published as a truncated line nobody sent).
The queue is lossy — it drops the oldest line, it never blocks the reader. Blocking the reader parks the child on its stdout write, and a child that is not reading its stdin can then park TUIC on the write side: neither side moves again. What gets dropped is what a call discards anyway — messages that arrived while nothing was waiting for them. A reply lost to a genuine flood surfaces as the timeout the call already has, and the timeout log carries the drop count.
Writing stdin
A second thread owns the child’s stdin, for the same reason the reader has one:
write_all on a pipe is uninterruptible. A request larger than the pipe buffer
parks there until the child reads it, and a child that stopped reading never
does — so the write parks a blocking-pool thread holding this client’s mutex,
and that upstream’s call and health-check paths are wedged for the life of the
process.
write_line hands the line to that thread and waits on the same deadline as
the reply, so an unresponsive child costs one timeout_secs, not forever.
A write that runs out of time tears the client down: the bytes may still be
half-inside the pipe, and a child holding a partial JSON-RPC frame cannot be
spoken to again.
One request waits on one deadline for the whole exchange (timeout_secs),
armed before the write rather than after it, and covering write and reads
alike. It is not a per-message count. Server notifications and log messages arriving in
between are skipped, however many there are: a chatty upstream must not lose a
reply it answered correctly. Being out of time outranks having a line ready to
parse, or an upstream that refills the queue faster than TUIC drains it would keep
a call alive forever.
Timeout rule: a reply timeout fails only that request and leaves the process
running. A long tool action is not evidence that its server has died. Request ids
increase across calls; a late reply to an abandoned request is skipped until the
current request’s matching reply arrives. No action is automatically retried or
cancelled: a timed-out action may still complete and its external outcome is
unknown. Set the upstream’s timeout_secs high enough to receive the result of a
known long action. A write timeout still tears down the client, because a partial
JSON-RPC frame cannot safely be reused and the blocked writer must be released.
Environment Sanitization
The parent environment is cleared before spawning to prevent credential leakage (ANTHROPIC_API_KEY, AWS_SECRET_ACCESS_KEY, etc.) to potentially untrusted MCP server processes. A safe allowlist is re-applied:
PATH, HOME, USER, LANG, LC_ALL, TMPDIR, TEMP, TMP, SHELL, TERM
User-configured env overrides from the upstream config are then applied on top of the safe set.
Respawn Rate Limit
To prevent tight loops when an MCP server crashes, the client enforces a minimum 5-second interval between spawn attempts. A premature respawn call returns an error immediately without spawning.
Config Schema
Configuration is persisted to mcp-upstreams.json in the platform config directory, separate from the main AppConfig.
UpstreamMcpConfig (top-level)
{
"servers": [ /* array of UpstreamMcpServer */ ]
}
UpstreamMcpServer
| Field | Type | Default | Description |
|---|---|---|---|
id | String | required | Unique UUID for config diff tracking |
name | String | required | Human-readable name, also the namespace prefix. Must match [a-z0-9_-]+ |
transport | UpstreamTransport | required | Connection type (http or stdio) |
enabled | bool | true | If false, the entry is registered but never connected |
timeout_secs | u32 | 30 | Per-request timeout (0 = no timeout, HTTP only) |
tool_filter | ToolFilter? | null | Optional allow/deny filter |
UpstreamTransport
HTTP variant:
{
"type": "http",
"url": "https://example.com/mcp"
}
Stdio variant:
{
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem"],
"env": { "ALLOWED_PATHS": "/home/user/projects" }
}
ToolFilter
| Field | Type | Description |
|---|---|---|
mode | "allow" or "deny" | Allow only matching tools, or deny matching tools |
patterns | Vec<String> | Exact names or glob patterns (trailing * = prefix match) |
Filter examples:
- Allow only read tools:
{ "mode": "allow", "patterns": ["read_*", "list_*"] } - Block dangerous tools:
{ "mode": "deny", "patterns": ["delete_*", "rm", "exec_*"] }
Validation
validate_upstream_config() runs before every save_mcp_upstreams call and collects all errors (not just the first):
| Error | Cause |
|---|---|
EmptyName | Server name field is empty |
InvalidName | Name contains characters outside [a-z0-9_-] |
DuplicateName | Two servers share the same name |
EmptyUrl | HTTP transport has an empty URL |
InvalidUrlScheme | HTTP URL does not start with http:// or https:// |
SelfReferentialUrl | HTTP URL points to TUIC’s own MCP port (circular proxy guard) |
EmptyCommand | Stdio transport has an empty command |
The self-referential check compares the URL’s host (localhost, 127.0.0.1, ::1, 0.0.0.0) and port against TUIC’s own running port.
Credential Management
Credentials (Bearer tokens for HTTP upstreams) are stored in the platform OS keyring, never in config files:
| Platform | Backend |
|---|---|
| macOS | Keychain |
| Windows | Credential Manager |
| Linux | keyutils / Secret Service |
The keyring service name is tuicommander-mcp. The account name is the upstream name. Credential names follow the same [a-z0-9_-]+ validation as upstream names.
read_upstream_credential(name) returns None (not an error) when no credential exists.
Adding a server submits its secrets with the config save. The backend validates the latest locked config before writing new vault entries and rolls those entries back if the save fails. Duplicate names cannot replace an existing Bearer or OAuth credential, including at the same origin. Standalone credential writes require replace: true to edit an existing entry.
Hot-Reload
apply_config_diff(old, new) compares two configs using server id as the stable identifier:
- Removed servers →
disconnect_upstream(name)(stdio: graceful shutdown, HTTP: no-op) - Added servers →
connect_upstream(config) - Changed servers (same
id, any field changed) → disconnect + reconnect - Unchanged servers → left running, no interruption
This is called automatically by save_mcp_upstreams after writing the config file, so adding or reconfiguring upstreams takes effect immediately without restarting TUIC.
SSE Events
Status changes emit UpstreamStatusChanged events via the app event bus, which surfaces as Server-Sent Events on GET /events. The event payload is:
{
"type": "upstream_status_changed",
"name": "github-mcp",
"status": "ready"
}
Valid status values: connecting, ready, circuit_open, disabled, failed, needs_auth, authenticating.
Metrics
Each upstream tracks lock-free atomic counters:
| Metric | Type | Description |
|---|---|---|
call_count | AtomicU32 | Total tool calls routed |
error_count | AtomicU32 | Total failed tool calls |
last_latency_ms | AtomicU32 | Last observed round-trip time |
Available via status_snapshot() which returns a JSON snapshot of all upstreams including status, transport info, tool count, and metrics.
Integration with /mcp Transport
In mcp_transport.rs, the tools/call handler checks the tool name for __:
#![allow(unused)]
fn main() {
if tool_name.contains("__") {
// Route to upstream registry (async)
state.mcp_upstream_registry.proxy_tool_call(&tool_name, args).await
} else {
// Handle natively (sync, via spawn_blocking)
handle_mcp_tool_call(&state, addr, &tool_name, &args)
}
}
The tools/list response merges native tools with upstream tools via merged_tool_definitions().
The build_mcp_instructions() function supplies TUIC protocol and orchestration context once in the initialize response. Proxied upstream descriptions remain upstream-owned and do not repeat that preamble.
Successful proxied tools/call responses that are valid MCP CallToolResult objects
(an object with a content array) pass through as the downstream JSON-RPC result.
TUIC does not re-wrap or mutate their content, isError, structuredContent, or
extension fields. The same passthrough is used when collapse_tools routes an upstream
call through the call_tool meta-tool. If an upstream returns a malformed result, TUIC
falls back to a compact JSON text content envelope; native TUIC tools always use that
compact envelope.
Voice Dictation
Domain crate: src-tauri/crates/tuic-dictation/
Application adapters: src-tauri/src/dictation/
Playback admission stays busy across every closed utterance in a capture batch, including an empty or rejected transcript followed by another utterance. After the batch, admission still waits for any remaining open phrase and pending submission. A disarm or new conversation invalidates the old batch.
The application enables native dictation with the non-default Cargo feature
dictation. Plain application Cargo dev/test builds omit Whisper and WebRTC;
use --features dictation to check or test the voice adapters. Tauri builds
(including make dev and releases) enable the feature in tauri.conf.json,
and desktop CI enables it explicitly. cuda and vulkan imply dictation.
Headless tuic-remote --no-default-features does not compile the audio stack.
Notification audio remains available in desktop builds without dictation. Both
notification and speech output share tuic-core::audio_output, behind its
optional audio-output feature. The output-device selection is unchanged.
The application, tuic-core and tuic-dictation use rodio 0.23 with CPAL
0.18.2. Capture explicitly starts its stream and retains F32/I16 input handling:
if CPAL prefers a higher-precision default, capture selects a supported F32/I16
configuration, retaining the default sample rate when that range supports it.
Captured audio still becomes 16 kHz mono PCM. Playback retains the selected-device
then system-default routing, notification volume/envelopes and rodio’s output
buffer policy. Edge speech retains the symphonia-mp3 decoder feature.
Local voice-to-text using Whisper with Metal acceleration on macOS. Push-to-talk workflow with streaming partial results: hold hotkey to record, see partial transcriptions in real-time, release to finalize.
Fn down/up listeners use the current WebviewWindow target, not global event listeners.
Global (Any) listeners also receive labeled events and would create competing recording owners.
Each window disposes its guarded subscriptions when its hook scope ends.
On macOS, Fn key-down is sent to the detached AI Chat WebView when it has focus,
or to the secondary terminal WebView when it has focus, otherwise to the main
WebView. Each owns its DOM target and dictation hooks.
Key-up reaches all three supported WebViews; only the handler that saw key-down can
stop a take. Losing a supported window’s focus does not release a physically held Fn key.
The local event monitor still handles ordinary key-up. After focus loss, a
temporary AppKit timer checks the current modifier flags every 50 ms, stops
capture and emits key-up once Fn is released, then invalidates itself. The timer
runs in common main-run-loop modes so menu tracking does not suspend it. It
requests no global keyboard-monitor permission and does not poll while idle.
The file log records Fn focus loss observed with the physical key state; a
release found by the timer records origin="fn-state-poll".
Long text delivery to Claude
Push-to-talk sends long Claude CLI text as a bracketed paste, with or without Auto-send. The frontend and backend frame Claude text above 500 UTF-8 bytes; short dialog answers remain key events. Codex keeps its existing character threshold. Recording limits and Whisper decode flags do not change.
Claude Code 2.1.311 accepted only the last 137 characters of an isolated
1159-character plain write. The same text inside bracketed paste markers reached
its native transcript in full. The recorded fixture is
src-tauri/src/fixtures/agent_prompts/claude-long-dictation-2502.json.
Dictation delivered records a completed target write, not proof that the
external CLI accepted every character. Compare the actual CLI transcript with
that log before attributing a missing beginning to audio capture or Whisper.
Diagnose speech that also appears in the mobile composer
Hands-free terminal targets use pty::write_voice_turn; AI Chat targets use the existing ACP prompt submission. The mobile
input_line feed observes that terminal prompt; it does not choose the voice
destination. Correlate Hands-free turn accepted and Hands-free turn typed now
with the session ID before treating a mobile draft as a delivery failure. The
typed log alone does not prove that the agent accepted the submission.
Check the mobile client build as well as /api/version. The mobile
Update available: <client> → <server> log identifies an older loaded bundle.
Before the #1662 fix, an empty composer accepted any nonempty PTY input as an
echo, so a voice paste could remain as a local draft after terminal delivery.
Current clients accept only explicitly requested completion/history responses.
Save any local draft, then use the mobile update action to load the current
bundle. A desktop rebuild does not replace JavaScript already loaded on a phone.
Module Structure
| File | Purpose |
|---|---|
root mod.rs | DictationState — shared application state for dictation |
audio.rs | Audio capture from microphone via CPAL (VecDeque ring buffer) |
root commands.rs | Tauri command handlers, AppState and event integration |
root browser.rs | Browser audio transport and Tokio broadcast |
root adapters.rs | PTY and ACP delivery and target checks for hands-free mode |
root model_download.rs | Tokio/HTTP Whisper model download |
root asset_download.rs | Tokio/HTTP staging of pinned speech assets |
model.rs | Whisper model catalogue and local file management |
transcribe.rs | Transcriber trait + WhisperTranscriber implementation via whisper-rs |
streaming.rs | Streaming transcription loop with adaptive windows and shared speech gates |
vad.rs | Tail-silence detector (energy-based, ported from whisper.cpp; not a whole-window speech gate) |
corrections.rs | Post-processing text corrections |
continuous.rs | Hands-free mode: utterance segmentation and session-bound delivery |
speaker.rs | The reply queue: Speaker (bounded, generation-stamped), the Output port and its rodio adapter |
speech.rs | The speech port: Speech, SpeechAudio, SpeechError, SpeechCancel, budget_seconds — no engine named |
speech/edge.rs | The default adapter: Microsoft Edge neural voices over a WebSocket (own minimal client), MP3 decoded through rodio, voice-list parsing, default voice per language |
speech/pocket/ | The Pocket TTS adapter: pocket.rs (the port impl), bundle.rs (manifest + streaming state), tokenizer.rs (SentencePiece Unigram), engine.rs (the four ONNX graphs) |
speech/external.rs | The bring-your-own-engine adapter: a configured command plus a RIFF/WAVE reader |
speech/assets.rs | The pinned, allowlisted catalogue and local install rules: Asset, Fetch, status, promote, remove |
speech/assets_voices.rs | Generated by scripts/speech-assets/gen_voice_catalogue.py. Do not edit. The 150 voices that download one by one |
loudness.rs | The loudness stage for spoken replies: levelling, gain, limiter, clamp. speaker.rs runs it on every reply and on a voice preview |
speech/library.rs | SpeechLibrary: one engine per language, loaded lazily, and the order that keeps installing from racing speaking |
echo.rs | Acoustic echo cancellation: the Canceller port, the FarEnd pacing buffer and EchoGuard |
echo/webrtc.rs | The WebRTC AEC3 adapter |
All unqualified files in this table are in tuic-dictation/src/. The domain crate has no Tauri or Tokio dependency. DictationConfig is defined in the root config.rs and re-exported at its previous command path. The root keeps the desktop feature gate, commands, downloads, PTY ports and event emission.
Screen wake lock while capturing
holdScreenAwake() (src/utils/screenWakeLock.ts) owns the one Screen Wake Lock of a browser client.
Browser hands-free (connectBrowserVoice, only when the microphone opens) and mobile push-to-talk
(useBrowserDictation) take it at capture start and release it at stop, failure or cancel. The page
releases it when hidden and requests it again on return while capture runs. The per-device setting
tuic-mobile-keep-awake (mobile Settings, default on) turns it off. A missing API or a refused request
is logged once and never blocks capture. Safari supports the API from 16.4, but home-screen web apps
only from iOS 18.4 (WebKit bug 254545).
Whisper build cache
src-tauri/.cargo/config.toml sets GGML_CCACHE=OFF for Cargo builds. The
whisper-rs-sys build script passes this value to whisper.cpp’s CMake build, so
ggml does not add its own sccache or ccache compiler wrapper. That wrapper can
fail when it invokes an mbx compiler shim. mbx still caches the Cargo build,
including the resulting whisper-rs-sys artifacts. Run
cargo check -p tuic-dictation from src-tauri/ to verify the native build.
On macOS, tuic-dictation/build.rs also links Xcode’s libclang_rt.osx.a for
ggml-metal’s availability checks. Keeping this directive in the domain crate
lets standalone release tests link without building the Tauri root package.
Tauri Commands
Recording
| Command | Description |
|---|---|
start_dictation() | Start recording + streaming transcription |
stop_dictation_and_transcribe() | Stop streaming, apply the hands-free sustained-speech gate to the full capture, then run the final transcription pass. Return TranscribeResponse { text, skip_reason, duration_s, truncated_s }. A gate skip keeps its specific reason; only an empty successful pass uses no speech detected. |
inject_text(text) | Apply corrections to text (called after transcription) |
Hands-free
AI Chat targets use opaque acp:<connectionId>:<sessionId> binding ids, not PTY ids. The shared voice sink submits through AcpClientManager::prompt_with_context, the same path as typed acp_session_prompt input. The existing ACP actor owns queuing and transcript events. The visible chat publishes its effective pinned-or-viewed repository through acp_session_set_viewed_repo / POST /acp/connections/{cid}/sessions/{sid}/viewed-repo. The voice sink forwards that live attachment-local hint through the existing prompt context parameter, including a cleared hint; it does not change the session cwd or add a prompt queue. Context is discarded on detach or connection replacement. Open permissions hold speech; a removed attachment or settled connection fails the target probe. MCP-over-ACP speech resolves the bound target only when its native channel owns the exact live connection and generation. Terminal voice routing is unchanged.
get_voice_targets / GET /dictation/hands-free/targets lists attached host-managed chats as { id, name, chatSessionId }. Both docked and detached panels use this host-owned list. Closing a chat tab, changing its selected session, stopping ego or closing its last view releases its voice binding. HTTP disarm runs on a blocking worker so an ACP exit notice cannot block the async executor.
| Command | HTTP | Description |
|---|---|---|
arm_hands_free_dictation(sessionId, owner) | POST /dictation/hands-free/arm | Bind the delivery target and the audio owner, open a generation, return HandsFreeStatus. Refused when the target cannot take hands-free input (neither an agent PTY session nor an attached AI Chat). Does not open a microphone. |
disarm_hands_free_dictation() | POST /dictation/hands-free/disarm | Disarm the whole mode, drop the transcript that never reached the model, return HandsFreeDisarmed. Idempotent. |
get_hands_free_status() | GET /dictation/hands-free | HandsFreeStatus. |
get_hands_free_default_notice() | GET /dictation/hands-free/default-notice | The built-in start notice (MODE_ENTRY_HINT) as a string, so a settings surface can show it and reset to it without a copy of the text. |
Both transports serialize the same structs, camelCase on the wire:
HandsFreeStatus { armed, phase, sessionId, owner, generation, pendingText, holdBackMs, error, deliveredTurns, droppedTurns } and
HandsFreeDisarmed { wasArmed, generation, discardedPending, discardedCapture, status }.
sessionId and owner are bounded at 256 bytes and may not be blank.
phase is one of disarmed, waiting, capturing, wake_confirmed, transcribing,
holding_back, delivered, error.
deliveredTurns (bumped in HandsFree::note_written) and droppedTurns
(bumped on TranscriptOutcome::Rejected) are monotonic for the process and
never reset on arm; the frontend plays its earcons when one moves between two
polls (turnEarcon in stores/dictation.ts), unless hands_free_earcons
(dictation config, default true, read by the frontend only) is false.
Tauri Events
| Event | Direction | Payload |
|---|---|---|
dictation-partial | Rust → Frontend | String — partial transcription text |
dictation-download-progress | Rust → Frontend | { downloaded, total, percent } |
Model Management
| Command | Description |
|---|---|
get_model_info() | List available Whisper models with download status |
download_whisper_model(model_name) | Download model (emits progress events) |
delete_whisper_model(model_name) | Delete a downloaded model |
Speech assets
The catalogue is an allowlist: asset is an id from it, and an id that is not
in it is refused before it can become a path or a URL. See “Where the bytes come
from” below.
| Command | Description |
|---|---|
get_speech_assets() | Every installable asset with its state: absent, downloading, incomplete (with the missing files named) or ready |
download_speech_asset(asset) | Download and install, verifying every sha256 (emits speech-download-progress) |
cancel_speech_download(asset) | Abandon a download in flight; succeeds with a note when there was none |
delete_speech_asset(asset) | Unload the engine, then remove the files |
A voice asset (id voice-<language>-<voice>, see “Every voice is an asset of
its own” below) is accepted by download_speech_asset, cancel_speech_download
and delete_speech_asset. get_speech_assets lists the runtime and the
languages first, then every catalogue voice (kind: "voice", with language as
the Whisper code and voice as the voice name). choose_voice accepts a voice
from installed_voices: the shipped voice, a catalogue voice that is fully
downloaded, or a voice file the user imported. A catalogue voice that is not
downloaded is refused with a message that says to download it. It does not
check that the language itself is downloaded; that is reported where the engine
opens. available_voices, which get_speech_voices returns, is the same list
but empty while the language is not fully downloaded: no voice speaks without
the language’s model.
Voices
language is always the Whisper code ("it"), as in the rest of this API.
| Command | HTTP | Description |
|---|---|---|
get_edge_voices(language) | GET /dictation/speech/edge-voices?language= | The Microsoft Edge voices that speak the language, from the service’s own list, as [{ id, locale, gender, label }]. Needs the network; the list is cached for six hours and a failed fetch is not cached. An unreachable service is an Err naming the network, never an empty list |
get_speech_voices(language) | GET /dictation/speech/voices?language= | The voices the language can speak with now, as [{ id, source }] with source "default", "downloaded" or "user", in that order |
import_speech_voice(language, name, dataBase64) | POST /dictation/speech/voices/import | Store a voice file the user chose (the whole file as base64). Checked before it is stored — see “Voice files the user adds” below. This route alone accepts a body of about 85 MiB (SPEECH_VOICE_IMPORT_BODY_BYTES); every other route keeps the 2 MB limit |
delete_speech_voice(language, name) | POST /dictation/speech/voices/delete | Remove a voice file the user imported. A file that is already absent is success |
preview_speech_voice(language, voice, text) | POST /dictation/speech/voices/preview | Speak text (at most 200 characters) in voice on this machine’s speaker, through the configured engine (Edge or Pocket; an external command names its own voices and is refused), the same loudness stage and echo tap as a reply. Needs no hands-free conversation and does not change speech_voice or speech_edge_voice. An Edge voice that does not speak language previews as the language default, the same resolution a reply makes and what the picker shows for it. Refused, not queued, while a hands-free reply is queued, rendering or playing |
The HTTP body of the import uses the same camelCase key as the IPC argument
(dataBase64).
Spoken replies
Hands-free listening and spoken replies are two independent settings (hands_free_listening, hands_free_spoken_replies, both default true). Listening on, replies off: speech is captured and the model is told to answer in text. Listening off, replies on (replies-only): arming binds the terminal, opens the reply queue and sends the entry hint, but never opens a microphone — the runtime runs against a MutedVoiceEndpoint that only reports whether the owner is still there, so a closed terminal or lost client still ends the conversation. Input stays push-to-talk, and the language Whisper detects for a push-to-talk take is recorded on the conversation (note_push_to_talk_language) so auto can voice a reply. Both off: arming is refused. Migration: a config without hands_free_listening reads as true, so every existing user keeps today’s behaviour (listening on, replies unchanged). hands_free_listening is read at arm time only; HandsFreeStatus.listening reports what the running conversation does.
Spoken replies is on by default. The persisted hands_free_spoken_replies preference applies to the backend device and its armed conversation, shared by mobile and Settings. Turning it off cancels queued speech, refuses new replies before engine access, and makes the arming notice request text replies. Dictation continues.
An Edge HTTP 401/403 rejection starts a five-minute backend speech-library cool-down measured with a monotonic clock. Queued and new replies skip the service during it; voice status reports the rejection and the five-minute policy. Voice or language changes do not reset it. Other network errors do not start this cool-down. An asynchronous queued rejection sends one outage notice through the hands-free notice sink, asking the model to tell the user in text. Barge-in cancels a reply but still delivers the outage notice to the active conversation. A composer hold defers that notice; it cannot cross into a newly armed conversation.
Available only while hands-free is armed and the conversation opened with a
working voice. Every one of them answers available: false with a reason rather
than failing, so a caller can always ask.
| Command | HTTP | Description |
|---|---|---|
speak_reply(text, turn?) | POST /dictation/speech/speak | Queue one reply, at most 2000 characters. Returns SpokenReply { utteranceId, state, error?, turn } with state: "queued" — never "finished". turn refuses a reply written for a turn the user has already talked over; omitting it means “now”. |
stop_speech() | POST /dictation/speech/stop | Stop now, drop the queue, open a new turn. Returns the SpeechStatus afterwards, so the caller learns the new turn. |
pause_speech() | POST /dictation/speech/pause | Hold the reply where it is (paused: true, speaking: false). No-op with nothing playing. Sticky: the capture loop’s own resume never lifts it; a stop still drops it. |
resume_speech() | POST /dictation/speech/resume | Continue a reply the user held. |
get_speech_status(utterance?) | GET /dictation/speech/status?utterance= | SpeechStatus. With utterance it also carries that one reply’s SpokenReply; an id this conversation no longer remembers comes back as state: "unknown" rather than as an absent field. |
A model does not call these. It calls the voice MCP tool, which supplies its
own identity so the binding can be checked — see “Who may speak” below.
Investigate gaps in spoken replies
The speech port returns a complete utterance before output starts. Pocket text
chunks and Edge response pieces are assembled inside their synthesis adapters;
they are not device playback chunks. The speaker worker can render the next
queued utterance while the preceding audio plays. Its 25 ms completion poll is
not an inter-buffer scheduling timer. Speaking means handed to the output,
not an acoustic start timestamp.
For isolated native timing, build the speech_gap_probe example in
tuic-dictation through the authorized native build slot and mbx. It opens no
microphone or app instance and sends silence to the output while preserving
synthesized rates and lengths. Default mode records synthesis, append, and
mixer source-consumption boundaries; --direct uses production DeviceOutput
and records append/drain state. Source-consumption times are not DAC or acoustic
measurements. --load adds bounded synthetic load and needs explicit authority
on a shared machine.
The 2605-53fc measurements and repeat instructions are in
src-tauri/crates/tuic-dictation/fixtures/playback-2605/README.md.
Pocket and Edge did not reproduce a native boundary gap under the measured
partial load. The report retains one Edge network failure and the limits of
that result. Historical capture-loop pause/resume entries are a separate
candidate mechanism, not proof of a synthesis or device-scheduling defect.
Do not increase buffers or remove the activation-verdict hold without a failing
capture that distinguishes those mechanisms.
Configuration
| Command | Description |
|---|---|
get_dictation_status() | Model status, recording/processing state, and normalized audio_level (0–1). The preview polls this shared IPC/HTTP response while recording. |
get_dictation_config() | Load dictation configuration (includes rms_threshold and no_speech_threshold — see “Speech gates”) |
set_dictation_config(base, config) | Save dictation configuration (includes hands_free_hold_back_ms, hands_free_activation_phrase, hands_free_notify_model, hands_free_start_notice, hands_free_earcons, speech_engine, speech_command, speech_edge_voice, speech_voice, speech_volume_db and speech_levelling). Applies the caller’s changes to the latest document — see “Configuration persistence” |
get_correction_map() | Load text correction dictionary |
set_correction_map(map) | Save text correction dictionary |
list_audio_devices() | List available audio input devices |
DictationState
#![allow(unused)]
fn main() {
pub struct DictationState {
pub audio: Mutex<Option<AudioCapture>>,
pub active_model: Mutex<Option<String>>,
pub corrections: Mutex<TextCorrector>,
pub recording: AtomicBool,
pub processing: AtomicBool,
pub streaming: Mutex<Option<StreamingSession>>,
pub transcriber_arc: Mutex<Option<Arc<dyn Transcriber>>>,
pub accumulated_partials: Arc<Mutex<String>>,
pub hands_free: Mutex<HandsFree>,
/// The armed conversation's reply queue and voice. `None` while nothing is
/// armed, and while a conversation is armed without a working voice.
pub speaker: Mutex<Option<speaker::Armed>>,
}
}
Managed as Tauri state alongside AppState.
speaker is emptied first on both shutdown and disarm_hands_free, before
the engine and the runtime go: dropping the queue cancels the reply in flight and
stops the device, which is what makes disarm revoke speech whether or not the
model ever acknowledged anything.
Transcriber Trait
#![allow(unused)]
fn main() {
pub trait Transcriber: Send + Sync {
fn transcribe(&self, audio: &[f32], language: Option<&str>) -> Result<TranscribeResult, String>;
}
}
WhisperTranscriber implements this trait using whisper-rs. The trait abstraction enables mock implementations for testing without requiring a Whisper model.
Recording Guard (TOCTOU)
start_dictation(source?) uses compare_exchange(false, true, AcqRel, Acquire) on the recording flag to prevent TOCTOU races from concurrent IPC calls. If two calls arrive simultaneously, only the first succeeds; the second returns "Already recording". A drop guard resets recording = false on any early error return. A native Fn start passes source: "fn"; if the key was released before the command arrived, recording is refused. Other callers use "hotkey" or "ui".
The macOS Fn monitor stops the CPAL capture directly on key-up, before the WebView processes the event. Losing window focus synthesizes the release in both Rust and the hotkey hook; other DOM hotkeys also release on blur. If key-up races microphone initialization, the native stop remains pending and closes the stream as soon as it opens. The later stop command joins streaming and transcribes the audio already captured. File logs record Fn edges, stop request and execution timestamps/latency, retained and lost audio seconds, and final/partial character counts without transcript text.
Streaming Architecture
User holds hotkey
│
▼
start_dictation()
├── Load/reuse WhisperTranscriber (Arc-wrapped)
├── Start CPAL AudioCapture → VecDeque<f32> buffer
├── Start StreamingSession (background thread)
│ │
│ ├── Poll audio buffer (50ms interval)
│ ├── Accumulate in step_buf
│ ├── When step_buf >= window size:
│ │ ├── Skip all-zero window; otherwise use shared speech gates
│ │ ├── Build window: [keep_tail | step_buf]
│ │ ├── whisper_full(window)
│ │ └── Send partial via mpsc::channel
│ └── Adaptive growth: 1.5s → 2.0s → 2.5s → 3.0s (max)
│
├── Spawn event forwarder thread
│ └── mpsc::Receiver → emit("dictation-partial")
│
└── Set recording = true
│
User releases hotkey
│
▼
Native Fn release stops CPAL immediately (macOS); window blur recovers a missed release
│
▼
stop_dictation_and_transcribe() [async]
├── Set recording=false, processing=true (synchronous, UI updates immediately)
├── Stop cpal stream (buffer preserved)
├── Signal StreamingSession stop → join thread
├── Collect ALL audio (processed + unprocessed + capture buffer remainder)
├── spawn_blocking: Final transcription on full captured audio (if >= 0.5s)
│ ├── ProcessingGuard (drop guard) clears processing=false on completion/panic
│ ├── Apply text corrections
│ └── Return TranscribeResponse
└── Return TranscribeResponse { text, skip_reason, duration_s, truncated_s }
│
▼
Frontend injects text into focus target
VAD (Voice Activity Detection)
The legacy vad_simple helper detects a quiet tail, not an entirely silent
window. Streaming must not use it to discard a complete window: a short phrase
followed by a pause still contains speech. Streaming skips only all-zero windows
and passes other audio to the transcriber’s shared RMS and speech-confidence
gates. The complete retained recording still goes through the final pass.
The tail detector is ported from whisper.cpp common.cpp vad_simple():
- Algorithm: Compare absolute energy of last
last_ms(1000ms) vs entire buffer - High-pass filter: First-order RC at 100Hz removes ambient noise (HVAC, fans)
- Threshold:
vad_thold = 0.6— ifenergy_last / energy_all < 0.6, silence detected - Relative: Microphone gain doesn’t affect detection (ratio-based)
Hands-free mode (continuous.rs)
Push-to-talk is unchanged by this module and does not use it. Hands-free is a
separate mode with two independent state machines, neither of which reads a
clock — the caller supplies frame durations and now_ms.
Segmenter cuts the capture stream into utterances over 20 ms frames:
| Setting | Default | Purpose |
|---|---|---|
pre_roll_ms | 300 | audio kept ahead of the first speech frame, so a soft first syllable survives |
trailing_silence_ms | 1 500 | quiet interval that ends an utterance |
min_speech_ms | 200 | below this the utterance is discarded, not sent |
max_utterance_ms | 30 000 | hard cap; a monologue is cut rather than buffered without limit |
activity_rms | 0.01 | frame RMS at or above which a frame counts as speech |
While nobody speaks the only retained audio is the bounded pre-roll ring, so an
armed microphone in a quiet room holds constant memory and runs no inference.
vad_simple is not used here: it answers “is the tail quiet”, which is a
different question from “where does this utterance end”.
HandsFree owns the mode. Arming binds a target session and an audio
owner and opens a generation. A focus change is not an input to this machine at
all, which is what makes a redirected delivery impossible rather than merely
unlikely. Every asynchronous result carries the generation it was captured
under; one that no longer matches is rejected as stale.
A transcript is held back for a visible interval before it is written, so an unintended turn can be stopped while nothing has been typed yet. A manual abort disarms the whole mode — pending capture, transcription and the held-back transcript are discarded, and nothing re-arms by itself. Target closure, audio owner disconnect and device failure disarm the same way.
Delivery is a direct write, not the Compose queue. VoiceSink is the only
exit, and its one production implementation is pty::write_voice_turn. It
types the turn into the bound agent’s composer at once, even while the agent
is busy — the same as a line the user types by hand into a working Claude
Code, which the agent queues or takes mid-turn itself. The Compose queue is for
something else (“one message, let the agent work, then the next”), so a voice
turn never enters it and never reorders it. Parking speech there until idle
measured a median delay of 103 s, max 594 s.
The write is the framed path every injection uses (run_claimed_injection:
Ctrl-U, the text, then a separate Enter), never raw text plus \r. An idle
agent is claimed IDLE→BUSY like any injection, without the confirmed-idle
requirement. A busy agent is claimed without touching its BUSY atom, and a
write that does not start never reports the agent idle.
Two holds remain, and they are the reason this is not a raw write:
Hold (pty::VoiceHold) | Why |
|---|---|
Question | a confident question or permission dialog owns the composer; speech must never answer it |
Draft | the user has text in the composer; the opening Ctrl-U would erase it |
InFlight | another write holds the composer, or an earlier one is uncertain |
WriteNotStarted | the PTY refused the first byte |
A held turn stays in the mode: pendingText still shows it, the phase is
holding_back, and deliver_due retries it on every tick. Speech that
arrives meanwhile joins it, so turns that were held reach the model as one
message, in spoken order, with a line break between phrases. The PTY sink wraps
the multiline turn in bracketed paste (ESC[200~, LF-separated text,
ESC[201~), then sends one separate CR to submit. The embedded LF is composer
content, not a submit key. Transcript trimming prevents a trailing newline from
adding a blank line between phrases. A disarm drops a held turn like one still inside its
hold-back (discardedPending). A target that cannot take hands-free input is
refused at arm and at the sink; it stays unavailable, with no fallback.
The shipping segmenter waits for 1.5 s of silence before closing speech, so a one-second breath stays in one transcription. With an activation phrase, the effective hold-back is at least 5 s even if the saved setting is shorter. Speech that starts before this deadline keeps the pending turn in the mode until its transcription can be appended. The 15 s activation window still decides whether a later, separate turn needs the phrase again.
Each attempt is logged at INFO with the session: Hands-free turn typed now,
or Hands-free turn held with the reason — a hold once, not once per tick.
The runtime that drives it
The state machines above are inert. spawn_runtime starts the thread that feeds
them: it wakes every POLL_INTERVAL_MS (50 ms) and calls tick, which is the
whole capture -> segment -> transcribe -> hold-back -> write path in one
clock-free function. tick takes now_ms from the driver, so every test drives
the real production path with a fake clock instead of sleeping.
One tick, in order:
- read the binding; if the mode is not armed, do nothing;
TargetProbe::accepts— a session that has gone away disarms withTargetClosed;VoiceEndpoint::connected— a released audio owner disarms withOwnerDisconnected;VoiceEndpoint::drain— an error disarms withDeviceFailedcarrying the device’s own message, and a stream that returns no samples at all forDEVICE_SILENCE_TIMEOUT_MS(5 s) disarms the same way. A silent room still delivers samples, so this catches a dead device rather than a quiet one;- push the samples through the
Segmenter; - for each closed utterance: mark transcribing, read the generation, release the mode lock, transcribe, re-acquire and offer the transcript. The lock is deliberately not held across inference, which is what lets a manual abort land mid-transcription and reject the result that arrives after it;
deliver_due— write a held start notice first, else whatever the hold-back has now cleared; a held write goes back into the mode.
Three details that are load-bearing rather than incidental:
- Never lock the mode in a
matchscrutinee.parking_lotis not reentrant and a temporary in the scrutinee lives for the wholematch, somatch deliver_due(&mut mode.lock(), ..)deadlocks the runtime — and every status poll behind it — the first time the sink refuses a delivery. Bind the result in its own statement. - A refused delivery is not a disarm:
note_send_failedrecords the message and returns the mode toWaiting, still armed. HandsFreeRuntimestops and joins its thread onDrop, so dropping it out ofDictationStateis the only shutdown handshake there is.
Two endpoints, and no fallback between them (832-e730)
VoiceEndpoint is the port: a microphone plus a recogniser. There are two
adapters, and which one open_endpoint builds is decided by the owner name
alone:
| Owner | Adapter | Microphone | Speaker |
|---|---|---|---|
DESKTOP_OWNER ("desktop") | DesktopVoiceEndpoint (commands.rs) | cpal on this machine | DeviceOutput on this machine |
| anything else | BrowserVoiceEndpoint (browser.rs) | the client’s socket | BrowserOutput on the same socket |
Neither direction falls back. An owner with no registered socket is refused
with No client is connected for audio owner '<owner>' rather than handed the
local microphone, and the desktop owner ignores a connected browser client even
when one exists. A silent fallback here is not a degraded experience, it is a
laptop user being listened to — or answered out loud — by the machine running
TUICommander, in another room or another building. Both directions have a test,
with the desktop case as the negative control
(a_desktop_conversation_ignores_a_connected_browser_client).
The desktop adapter shares push-to-talk’s transcriber Arc (loading a second
multi-gigabyte Whisper model would be absurd) and its permission and model
helpers, but not its capture. cpal::Stream is !Send, so the capture stays
in DictationState::hands_free_audio — a slot distinct from audio, which is
push-to-talk’s — and only the sample buffer handle crosses to the worker thread.
The two modes therefore cannot arm or stop each other. Because the runtime thread
cannot drop a !Send stream, a runtime that disarmed itself is reaped on the
next hands_free_status poll, which is where the device is actually released.
DictationState::shutdown clears the owner flag and disarms with
OwnerDisconnected itself before dropping the runtime, rather than relying on
the thread noticing — the thread may already be parked on its way out.
The browser endpoint (browser.rs, 832-e730)
A browser tab has a microphone and a speaker; what it does not have is a way to
be one. BrowserEndpoints is the registry that closes that gap: a DashMap of
owner id to Arc<BrowserLink>, where a link is one client’s audio socket seen
from the conversation’s side — a bounded capture queue, a broadcast channel for
playback, an alive flag, and the deadline of whatever is currently speaking.
GET /dictation/hands-free/audio?owner=<id> (mcp_http/dictation_routes.rs)
registers one and serves it; the frontend half is src/utils/browserVoice.ts.
iPhone Now Playing. The browser keeps navigator.audioSession.type at
play-and-record and resumes its capture context in the arming gesture, retaining
simultaneous microphone and reply playback. WebKit’s
AudioContext::isNowPlayingEligible
checks a connected destination and the explicit playback or play-and-record
category. This explains eligibility even before a reply; there is no HTML audio
element in this path. Boss observed music controls on iPhone; attribution to this
WebKit path is source-based inference until the device build is inspected.
Neither the Audio Session nor
Media Session web API exposes a switch to
hide Now Playing while keeping these audio semantics. Changing categories while
listening is not a proven safe fix for reply volume or background behavior.
Instead the dictation store uses Media Session metadata TUICommander hands-free
and the custom Now Playing actions documented by Apple.
Play/Pause use the pill’s reply resume/pause commands, leaving capture active;
Stop disarms the conversation, stopping capture and dropping replies. Backend
speech state updates the displayed playback state. Ending hands-free clears the
metadata, handlers and explicit playback state; iOS decides when its card disappears.
Real iPhone lock-screen rendering, action delivery and media volume still need
the device check in to-test.md.
A link outlives its socket, and that is the whole design. The socket handler
owns the Arc it registered and drops it on close, but the conversation holds
its own clone through BrowserVoiceEndpoint, so a tab that vanishes mid-turn
leaves a link that answers connected() == false instead of a dangling lookup.
tick then disarms with OwnerDisconnected on exactly the path a lost desktop
device takes — no second shutdown route, no special case
(a_browser_client_that_closed_its_socket_disarms_the_conversation_it_owned
drives the real tick to prove it).
Eviction is by identity, not by key. disconnect(owner, link) uses
remove_if(owner, |_, current| Arc::ptr_eq(current, link)), because a reconnect
under the same owner replaces the entry: without the pointer check, the old
socket’s late close would evict its successor and disarm a conversation that had
just been re-established. connect deliberately disconnects the link it
replaced, so the conversation armed against the old socket disarms rather than
silently migrating to whoever reconnected under that name.
Capture is bounded and drops the oldest. MAX_CAPTURE_SAMPLES is 60 s at
16 kHz. A client that ships audio nobody drains — armed, then the runtime dies —
must not grow without limit, and when the drain resumes the newest audio is what
matters: the user is still talking now.
is_speaking has no device to ask. A cpal stream knows whether it is still
playing; a browser cannot be interrogated, only told. BrowserOutput therefore
treats the rendered duration as the authority (speaking_until), takes the
client’s playback-ended ack as an early-out, and reports false outright for a
dead link. Without the last of those, a closed tab would strand a reply in
Speaking for ever and barge-in would never resolve.
The frontend decides nothing. browserVoice.ts captures 1024-sample frames
at 16 kHz and ships them, including silence — whether an utterance ended is the
Segmenter’s call in Rust, and a frontend that dropped quiet frames would be a
second segmenter that disagreed with the first one only on browsers. That is
asserted directly (sends silence too, rather than deciding the user stopped talking), because it is the property that is invisible once it breaks.
Since 832-e730 the Voice settings page (formerly the Dictation tab) renders in browser mode. Two groups stay behind
isTauri(): the global hotkey, which the browser cannot register, and the
microphone device list, which enumerates the server’s devices — offering a
browser user a device in another building is worse than offering nothing.
Early wake acknowledgement
waiting and VAD-only capturing both display Listening. With a configured
activation phrase, the shared continuous runtime recognizes prefixes of the open
utterance at one-second audio intervals, up to four seconds. A recognized
leading phrase changes the phase to wake_confirmed (Go ahead) while the
utterance is still open. Recognition uses the same endpoint, model, language,
speech gates and phrase matcher on desktop and browser capture. No extra model
or parallel inference worker is created.
There are at most four prefix passes per utterance, each borrowing at most 64,000 samples (256 KB at 16 kHz mono f32). Backlogged cadence points are skipped rather than queued. Idle capture, an unset phrase and an already confirmed wake run no prefix inference. A failed prefix is best effort; final transcription still owns error reporting. Slow inference can delay the next capture-loop tick; this is not a dedicated keyword spotter or a fixed-latency guarantee.
The acknowledgement does not open the activation window, schedule delivery or
change the spoken language. The final transcript still passes through
Activation::admit, including when it revises a matching partial. Closing the
utterance changes the phase to Transcribing. A disarm or generation change
invalidates an in-flight prefix, and an old capture cannot adopt a new arm.
Successful acknowledgement logs prefix_ms and inference_ms; these are probe
measurements, not a measured acoustic wake-to-display latency.
The activation phrase
hands_free_activation_phrase is optional. Empty, every recognised utterance is
a turn. Set, it must open each new turn, and three properties are the contract:
- It is local. Whisper runs on this machine on every utterance before the gate sees anything — the gate reads text, not audio. A phrase does not reduce what is recognised; it reduces what is submitted.
- It gates new model input, never the microphone. The match sits in
HandsFree::accept_transcript, after transcription and before the send slot. A rejected transcript never enters that slot, andpoll_sendis the only thingdeliver_duecan hand to the sink — which is the module’s only exit. “It never reaches PTY, ACP or MCP” is therefore structural, not a check repeated per call site. - It bounds a conversation, not a sentence. One accepted turn opens
ACTIVATION_WINDOW_MS(15s) in which follow-ups need no phrase. Every accepted turn restarts it; every disarm — manual, target closed, owner disconnected, capture failure — closes it, so a fresh arm is always gated.
Matching is on complete leading words, where a word is a maximal run of
alphanumeric characters. Both the setting and the transcript are lowercased and
accent-folded (fold_word: à á â … → a, ç → c, ñ → n), so case,
punctuation and accents never decide a match — "Attività, Tuic!" matches
attività tuic, and "Sentì, Mac." matches senti mac. Two spellings Whisper
invents are tolerated, and nothing else:
- Joined words. One heard word may be several phrase words run together, in
order —
Sentimacmatchessenti mac.Sentimentodoes not. - One extra trailing letter on a phrase word of three or more letters —
Mackmatchesmac. The tolerance is one-sided on purpose: a shorter word or a different last letter is how ordinary speech starts (Senti, ma…,Senti mai…,Senti Max…are a person being addressed), so none of those match. There is no general edit distance.
A longer word that merely starts with the phrase is otherwise a different word
rather than a prefix — Tuicommander does not match tuic. A
phrase heard mid-sentence does not activate: it must lead. The phrase is
stripped from what is submitted, including when it is repeated inside an open
window, so a model never reads it. Spoken alone, it opens the window and submits
nothing.
The window is anchored on acceptance, not on the model’s reply: this module writes and observes nothing coming back, which is what keeps the sink its only exit. A user who waits out a long answer will need the phrase again. Story 816-cbbf adds spoken playback and is the first caller that will know when an answer ended; the anchor is worth revisiting there. Interrupting playback is that story’s work and belongs upstream of this gate — stopping a speaker is not new model input — but whatever stops playback, the words that follow are new model input and stay gated whenever a phrase is configured.
Telling the model the mode changed (821-842a)
A model cannot see a microphone open. The voice tool is listed whether or not
anything is armed, and a model with no reason to speak writes text — so without
a notice the feature ships a voice nobody ever hears. Two constants in
continuous.rs carry it:
| Constant | Sent when | Says |
|---|---|---|
MODE_ENTRY_HINT | arm_hands_free_with, before the runtime starts | messages are spoken; acknowledge aloud at once, then give a short spoken answer when done |
MODE_EXIT_HINT | both disarm paths | the tool can no longer speak here; reply as text |
hands_free_notify_model (default true) controls both. Off sends neither
and changes nothing else — in particular, a disarm still revokes speech, because
that is a fact about this machine rather than a message to a model.
The default start notice is one line:
Hands-free voice is on: messages from now on are spoken. Answer aloud with the
voicetool (tuicommander MCP, action “speak”; if not loaded, search deferred tools for “voice”): one short sentence at once that you are on it, then a short answer when done.
This asks the model to acknowledge each spoken message before starting work, then speak a short answer when done. It is an instruction, not a guarantee of model compliance or playback timing.
hands_free_start_notice (default empty) replaces the start notice with the
user’s own text; empty or blank means MODE_ENTRY_HINT. It is read at arm time
and passed through entry_hint_text, which folds line breaks and whitespace
runs to single spaces — the settings field is multiline, and the sink submits
on a newline. The reply language is not part of the user’s text:
deliver_entry_hint appends Reply in <Name>. by code when the dictation
setting names a language, so a custom notice cannot drop it. Under auto the
notice names nothing and the first spoken turn carries the language instead —
see “The requirement travels in the spoken entry”. The exit notice is not
configurable.
Five rules, and each of them is a test:
- The sink, like every spoken turn.
deliver_entry_hintgoes throughVoiceSink::write, so the notice is typed at once — into a busy agent too — and lands in the session the mode bound to rather than in whatever tab the user has since focused. It is one line, for the reasoncompose_entrygives: the sink types an entry and submits it, and a newline submits half of it. - A held notice waits in the mode, first. A dialog or a draft holds it as
EntryHint::Pending;deliver_dueretries it on every tick before any spoken turn, so no turn reaches the model ahead of the notice it depends on. A disarm drops it with the mode. It does not move the phase: the phase describes what the user’s speech is doing, and nothing has been said. - The exit notice is owed only to a model that read the entry notice. The
evidence is
Disarmed::entry_hint_written: a notice still held at disarm was never typed, so the model never read it, and an exit notice after it would be the only thing it ever heard about a mode it never had. A typed notice cannot be retracted, so the model believes it can speak and has to be told otherwise. That isdeliver_exit_hint, and it is why a rapid arm/disarm leaves no contradictory pair. The exit notice gets one attempt: the mode is gone, so a dialog or a draft on screen at disarm drops it with a warning log. - Driven by what this arm sent, never by the setting as it now reads. A user
who turns the notices off mid-conversation has changed what the next arm
says; a model already holding “you can answer out loud” still gets its exit
notice.
disarm_hands_freetherefore never re-reads the config. - Both disarm paths, not just the user’s.
report_exit_hintis called fromdisarm_hands_freeand from the runtime thread’sTick::Disarmedarm, so a closed target, a lost owner and a dead microphone all end the model’s expectation too. A target that has gone away refuses the write; that is reported, not swallowed — there is nobody left to tell.
A refused entry notice does not fail the arm. The microphone works and ordinary
turns may still land; the reason lands in HandsFreeStatus::error via
note_send_failed, and the notice was never typed, so no exit notice follows
either.
Push-to-talk shares none of this. It never calls arm_hands_free, so it opens
no VAD runtime, reads no activation phrase, makes no speech available and sends
no notice — asserted at the surface in
push_to_talk_alone_arms_nothing_and_tells_the_model_nothing.
Configuration persistence
set_dictation_config accepts the loaded base and edited config, then
applies only their delta to the latest file under its lock. Every hands-free
field carries #[serde(default)] so a config written before the field existed
still loads. A caller must keep the loaded snapshot and override only the
fields it changed. A recovered malformed document is rewritten from its
salvaged values as before; ordinary saves refuse to overwrite a newly corrupt
file. dictationStore.saveConfig reads the stored config and overrides only the
field in the request, and
src/__tests__/stores/dictation.test.ts drives that field list off this crate’s
struct so a newly added field is covered by whoever adds it.
Speech gates
Whisper transcribes whatever it is given. On room noise it invents subtitle
boilerplate. Before the final push-to-talk pass, the captured audio goes through
the hands-free Segmenter with its 20 ms frame and min_speech_ms duration rule.
Push-to-talk takes the frame activity floor from the configured transcription
rms_threshold; hands-free retains its own activity_rms default. A short
burst or capture below that floor returns no sustained speech without invoking
Whisper; an utterance still open at key release counts. Three further gates in
transcribe() decide whether the admitted audio is speech at all. They run in
order and each returns a skip_reason the push-to-talk stop
response, store and status show verbatim.
| Gate | Rejects | Tunable |
|---|---|---|
| RMS floor | audio quieter than rms_threshold — never reaches Whisper | yes |
no_speech_probability | the segments Whisper itself scores above no_speech_threshold | yes |
is_hallucination | known subtitle boilerplate and bare thanks | no |
The two thresholds are settings, not constants (VoiceGates, read from
DictationConfig on every start). The right RMS floor depends on the room and
the microphone: a headset a metre away picks up enough noise to clear a fixed
floor, which is how an empty room ends up transcribed. Settings > Voice
exposes both against a live meter — see the user guide.
no_speech_probability() is read per segment and filters per segment
(filter_speech_segments): a segment above the threshold is dropped, the rest
are kept, and only a run where every segment was rejected skips the whole
transcript. It generalises where a phrase list cannot, because it rejects
whatever the model invented rather than only the wordings someone remembered to
add to a list. Note that whisper.cpp does not implement the no_speech_thold
parameter, so the value must be compared after the run, not set on
FullParams.
The gate used to take the worst score across the run and discard everything on it. That was harmless while a run was one segment, and wrong as soon as recordings longer than one window started decoding into many: an ordinary pause inside a long dictation scores as no-speech, so one silent segment threw away a transcript that was almost entirely speech.
is_hallucination matches per sentence, not on the whole trimmed string.
The short-phrase list (HALLUCINATION_EXACT) holds words a user genuinely
dictates, so it only fires when every sentence is boilerplate — "Grazie."
is filtered, "Grazie. Ora committa e pusha." is not. Matching the trimmed
string as one unit missed the repeated form: streaming windows are 1.5–3 s and
produce one bare "Grazie.", but the final pass runs on the whole buffer, where
Whisper loops into "Grazie. Grazie." — the form that actually reached the
terminal. A bare "Grazie a tutti." is also filtered, while an instruction
containing those words survives. HALLUCINATION_SUBSTRING holds channel
boilerplate nobody dictates, so one occurrence anywhere condemns the transcript.
Decode flags depend on audio length
decode_flags_for picks single_segment and no_timestamps from the sample
count, split at SINGLE_WINDOW_SAMPLES (30 s — one whisper encoder window).
Both flags are set at or under one window and cleared above it.
no_timestamps suppresses every timestamp token outright (whisper.cpp:6191),
so has_ts never becomes true. With either flag set, the end of a segment forces
the window shift to a whole chunk (whisper.cpp:7381, seek_delta = 100*WHISPER_CHUNK_SIZE) and seek += seek_delta (whisper.cpp:7734) advances a
full 30 s no matter how much the decoder actually reached. An early end-of-text
token or the 220-token decode limit (whisper.cpp:7184) then drops the rest of
that window permanently — with timestamps on, seek would instead advance only
to the last decoded timestamp and the remainder would be re-decoded.
A 127.7 s dictation came back with 1175 characters against 1442 from the
streaming partials before this split existed. At or under one window the loss
cannot happen, because the loop breaks once seek reaches the end of the audio
(whisper.cpp:7008) — which is why short dictation keeps both flags and the
hallucination suppression they were added for (whisper.cpp issue 1724).
Streaming windows are 1.5–3 s, so they keep the flags by the same rule; a
MAX_BUFFER_S forced flush is the one window that can cross the line, and
clearing the flags there is correct for the same reason.
Recording cap
Dictation is push-to-talk, so a real utterance lasts seconds. MAX_RECORDING_S
(300 s) bounds the audio kept for the final pass — without it a stuck key is both
an unbounded allocation and an unbounded whisper pass. The cap keeps the newest
audio and drops the oldest, TRIM_HYSTERESIS_S at a time.
The cap is applied twice, because the streaming thread only sees what it drained
itself: once per poll inside streaming_loop (past TRIM_HYSTERESIS_S, so the
memmove is rare), and once by cap_finished_recording in
stop_dictation_and_transcribe after the capture-buffer tail is appended to the
joined result. A slow final whisper window makes that tail long, so without the
second pass the buffer handed to the final transcription can exceed the cap.
The CPAL callback’s pending queue also keeps up to 300 s, instead of silently
discarding the first samples after 30 s while a streaming Whisper pass is busy.
Its cap and any real-time lock-contention losses are counted with the streaming
losses. The trim is reported, never silent: both passes count the dropped samples,
StreamingSession::stop() returns the loop’s count in StreamingAudio, and the
command converts the sum to truncated_s. useDictation turns a non-zero value
into a status message instead of “Ready”, so a transcription missing audio
cannot read as a complete one. Losses from lock contention may be gaps within
the recording rather than a prefix.
StreamingAudio.interrupted marks a panicked streaming thread. Its audio is
gone, so what remains in the capture buffer is a fragment; the command returns
skip_reason rather than transcribing that fragment and presenting it as the
recording.
Streaming Constants
| Constant | Value | Purpose |
|---|---|---|
INITIAL_STEP_MS | 1500 | First window size (fast first partial) |
MAX_STEP_MS | 3000 | Maximum window size |
STEP_GROWTH_MS | 500 | Growth per iteration |
KEEP_MS | 200 | Overlap from previous window |
POLL_INTERVAL_MS | 50 | Audio buffer polling interval |
MAX_BUFFER_S | 30 | Force flush on very long recordings |
MAX_RECORDING_S | 300 | Cap on the audio retained for the final pass |
TRIM_HYSTERESIS_S | 30 | Slack before the cap trims, to make trimming rare |
VAD_THRESHOLD | 0.6 | Energy ratio threshold |
VAD_FREQ_THRESHOLD | 100.0 | High-pass cutoff Hz |
Audio Pipeline
Microphone → CPAL callback → try_lock() → VecDeque<f32> ← drain_samples() ← StreamingSession
│
whisper_full()
│
mpsc::channel
│
event forwarder thread
│
"dictation-partial"
│
DictationToast (UI)
Key design: try_lock() in the CPAL callback ensures the real-time audio thread never blocks. On contention, samples are silently dropped — acceptable for dictation at 16kHz mono (~64KB/s).
Audio Resampling
process_audio_chunk() converts raw microphone input to the 16kHz mono f32 PCM format required by Whisper:
- I16 → F32 conversion — If the audio device provides
I16samples, they are normalized to[-1.0, 1.0]by dividing byi16::MAX. - Stereo → mono — Multi-channel frames are averaged (
frame.sum() / channels). - Nearest-neighbor resampling to 16kHz — For sample rates other than 16kHz (e.g., 48kHz), the output length is calculated as
input_len * (16000 / sample_rate)and samples are picked by index mapping (src_idx = i / ratio).
Pre-allocated scratch buffers (mono_buf, resample_buf) are captured in the CPAL closure to avoid per-callback heap allocations. The buffer is capped at 30 seconds (480k samples) to prevent unbounded growth.
Model Storage
Models stored in: <config_dir>/models/
Available models (GGML format):
| Model | Size | Quality |
|---|---|---|
small | ~488 MB | Good |
small.en | ~488 MB | Good (English-only) |
large-v2 | ~3.0 GB | Highest accuracy (slow) |
large-v3-turbo | ~1.6 GB | Best (recommended, default) |
Text Corrections
User-configurable dictionary for post-processing:
{
"new line": "\n",
"tab": "\t",
"period": ".",
"comma": ","
}
Stored in dictation config. Applied after transcription, before injecting into terminal.
Platform Notes
- macOS: Metal acceleration via whisper-rs (GPU-accelerated, always)
- Linux: releases build with
--features vulkan. With the Vulkan loader but no GPU device, whisper.cpp runs on the CPU. Without the loader the binary does not start, so the.debrequireslibvulkan1, the.rpmrequireslibvulkan.so.1()(64bit)and the AppImage carrieslibvulkan.so.1(scripts/check-appimage-vulkan-loader.shchecks it). Optionalcudabuild feature. - Windows: releases build with
--features vulkan. The binary hard-importsvulkan-1.dlland does not start on a machine that has none (exit0xC0000135, story 3055-95d9). The NSIS hooksrc-tauri/windows/installer-hooks.nshinstalls the pinned Khronos loader (scripts/fetch-vulkan-loader.py) next to the app only whenSystem32\vulkan-1.dllis missing, removes that copy once System32 has one, and deletes it on uninstall. Release builds setTUIC_REQUIRE_VULKAN_LOADER=1, so a missing download failsmakensis. transcribe::gpu_device()asks ggml’s device registry for the first GPU or integrated GPU, the device whisper.cpp takes withuse_gpu. Thedictation-backend-infoevent reportsgpuonly when that device exists, and whisper decodes on 1 thread with a GPU or 4 without.- Microphone permissions deferred until first use (avoids startup permission popup)
Microphone Permission Detection
Module: src-tauri/crates/tuic-dictation/src/permission.rs
On macOS, microphone access is gated by the TCC (Transparency, Consent, and Control) framework. The MicPermission enum tracks the current state:
| State | Meaning |
|---|---|
NotDetermined | User hasn’t been asked yet — system will prompt on first access |
Authorized | User granted access |
Denied | User denied access — must be changed in System Settings |
Restricted | System policy prevents access (e.g., MDM) |
API:
MicPermission::check()— queriesAVCaptureDeviceauthorization status via Objective-C bridge (objc2,objc2-av-foundation)MicPermission::open_settings()— opens macOS System Settings at the Privacy & Security > Microphone pane
Platform behavior:
- macOS: Full TCC integration via AVFoundation
- Linux/Windows: Always returns
Authorized(no TCC framework)
Speech engines
Three engines sit behind the Speech port; speech_engine picks one: edge
(the default), pocket or external. Echo cancellation, hush, loudness and
the stale-generation checks live in speaker.rs and echo.rs and see only
SpeechAudio, so they behave the same for all three.
Which engine a configuration means. get_dictation_config never returns
an empty speech_engine. While the file has none, the answer is derived
(legacy_speech_engine in dictation/commands.rs): a configured
speech_command is external; a chosen speech_voice or a Pocket runtime on
disk is pocket; everything else, including a fresh install, is edge. The
settings panel writes the key as soon as the user picks an engine in the Expert
section, after which the derivation is never consulted — so downloading Pocket
later does not move a fresh install off Edge.
Microsoft Edge voices (speech/edge.rs)
The service behind the browser’s “Read aloud”. No model, no download; it needs the internet, and the text of every reply is sent to Microsoft’s online speech service (the settings panel says so under Spoken replies).
- Client. Our own, not the
msedge-ttscrate (0.4.0, MIT OR Apache-2.0, maintained): its blocking client reads from a socket it keeps private, so aSpeechCancelraised mid-request cannot reach it, and it addsureqand a second certificate-verifier setup beside therustlsandtungstenite0.30 the application already ships. This one is a blockingtungstenitesocket with a 100 ms read timeout: cancel, the deadline and the budget are checked between reads, so a cancelled reply stops within about 100 ms. - Protocol (recorded, see
speech/fixtures/edge_stream.json): handshake atwss://api.msedgeservices.com/tts/cognitiveservices/websocket/v1, with the public token in theOcp-Apim-Subscription-Keyquery parameter.Sec-MS-GECretains ordinary SHA-256 over the five-minute Windows clock bucket and token, with version1-130.0.2849.68. A live Mac probe on 2026-10-16 returned HTTP 101 and 22,752 MP3 bytes with this v1 digest; omitting both GEC parameters returned HTTP 403 and no audio. The v2 control also returned HTTP 101 and 22,752 bytes, but is not needed. No LGPL digest implementation is included. The endpoint migration follows Readest PR 6722. The voice list stays on the original Bing URL (verified HTTP 200 on 2026-10-16). The handshake also sends the browser’sOrigin, desktop Edge user agent, language/encoding headers and a random MUID cookie.speech.configthenssml; text framesturn.start,response,turn.endaround binary frames made of a big-endianu16header length, the headers and the MP3 body. Output isaudio-24khz-48kbitrate-mono-mp3, which makes the budget a byte count (6000 bytes per second) and the audio rate a constant. - Whole utterance.
synthesizereturns onceturn.endhas arrived and the MP3 is decoded (rodio,symphonia-mp3) to mono PCM at 24 kHz. Streaming playback is a separate decision. Text whose escaped SSML ('is six bytes) exceeds 3000 bytes is sent as several requests on separate connections and the MP3 streams are joined; the service refuses about 4 KB. - Bounds. Name resolution and
connectcannot look at a flag, so the dial runs on a helper thread that the request polls: cancel and the deadline apply to the dial too, and an abandoned dial ends at its own connect timeout. Cancel →SpeechError::Cancelled. More audio thanbudget_secondsjustifies →Runaway. Noturn.endwithinmax(30 s, budget)→Failed("… did not finish in time"). A connection closed beforeturn.endisFailed, not truncated speech. - Errors say what is wrong. Offline or DNS failure:
Failed("cannot reach the Microsoft Edge speech service (…); it needs an internet connection"). HTTP 403 on the handshake mentions the system clock, becauseSec-MS-GECdepends on it. - Safety. The voice id reaches SSML as an attribute, so anything but
letters, digits and hyphens is
UnknownVoicebefore a connection is opened; the text is XML-escaped and control characters are dropped. - Voices.
get_edge_voicesfetches the service list (dictation/edge_voices.rs) andedge::voices_for_languagefilters it by the language subtag.speech_edge_voiceholds one voice; for a reply it is used only if it speaks the conversation language (or is multilingual), else the language default (DEFAULT_VOICES, every language the settings offer, verified against the live list and recorded infixtures/edge_voices.json). A language with no default and no chosen voice is an error that tells the user to choose one — never a voice of another language. - Proxy. The voice list goes through reqwest and honours the system proxy;
the synthesis socket does not (DEFERRED 2026-10-01,
dial_service). Behind a proxy the picker loads and speech fails with “cannot reach … needs an internet connection”. Pocket TTS or an external command work there. - Defaults.
get_config_defaultsand the settings catalogue shareDictationConfig::fresh_defaults(), which reportsspeech_engine: "edge". The schema reports the same effective default, so the settings panel hides the Expert engine selector while Edge is in use. Serde still keeps a missing engine empty for the legacy resolver described above. - Unofficial. The service is not a supported API. If it changes, the adapter fails with a typed error and Pocket TTS or the external command stay available in Expert.
Pocket TTS speech synthesis (speech/pocket/)
This engine is selected with speech_engine: "pocket" (Expert section of the
settings).
Spoken replies are rendered locally by Pocket TTS, run in-process over ONNX Runtime. There is no Python, no external service, and no fallback to either.
Kokoro was here first and was removed. Its Italian voices graded C, Boss
rejected all twelve evaluation samples, and it dragged GPL-3.0 espeak-ng into
an Apache-2.0 repository. That is the reason speech.rs is a port and names
no engine: the engine behind it has already changed once.
Nothing of the model is in this repository
A bundle is a directory downloaded at runtime under the dictation models directory, not a build artifact:
<config dir>/models/speech/
onnxruntime/libonnxruntime.dylib the runtime library, also downloaded
italian/
bundle.json tokenizer.model *.onnx
voices/giovanni.safetensors the voice the language ships with
voices/italian/jean.safetensors a voice downloaded on its own
The weights are Kyutai’s, CC-BY-4.0, attributed in THIRD_PARTY_NOTICES.md.
Every absence is a typed SpeechError::ModelUnavailable naming the missing
file, never a panic and never silence.
Where the bytes come from (speech/assets.rs)
The catalogue is Rust, not a JSON file beside the binary, and that is the whole security property: a manifest the installer could rewrite is not an allowlist. Every file is named by a URL pinned to an immutable revision and checked against a sha256 written in the source, so an upstream that is compromised — or merely re-tagged — produces a refused install rather than a different model.
| Part | Published by | Source | Pinned to |
|---|---|---|---|
ONNX graphs, tokenizer, bundle.json | KevinAHM/pocket-tts-onnx (exports of Kyutai’s weights) | Hugging Face | commit 58a6d00c |
| Speaker embeddings (voices) | Kyutai (kyutai/pocket-tts-without-voice-cloning) | Hugging Face | commit 8843db76; French (french_24l) commit 00eac05e |
| onnxruntime | Microsoft | GitHub release | v1.23.0 |
The voices do not come from kyutai/pocket-tts: that repository is gated,
because it ships the weights that clone a voice from a sample, so an application
cannot download from it on a user’s behalf. Kyutai’s
kyutai/pocket-tts-without-voice-cloning is public, leaves those weights out,
and carries the same speaker embeddings byte for byte (same sha256). Only the
preset voices are used, so nothing is re-hosted.
onnxruntime is pinned at 1.23.0 rather than the newest release. 1.24 dropped
the macOS Intel and universal2 builds and TUICommander still ships for Intel
Macs. ort 2.0.0-rc.13 needs API version 17 or later and 1.23 provides 23, so
nothing is given up.
Microsoft ships a whole SDK, of which one shared library is wanted. The member
is found by rule, not by a hardcoded path: a regular file under a lib/
component whose name starts with the platform stem and a dot. The trailing dot
is what excludes libonnxruntime_providers_shared.so; the lib/ component is
what excludes pkgconfig/libonnxruntime.pc; “regular file” is what excludes the
symlinks Linux uses for the unversioned name. macOS ships both
libonnxruntime.dylib and libonnxruntime.1.23.0.dylib as real files, so an
exact name is preferred rather than required — and two candidates with no exact
match are refused rather than guessed between.
Every voice is an asset of its own
Each of the six languages has 26 Kyutai voices. One voice ships in the language
payload: giovanni (Italian), alba (English), estelle (French), juergen
(German), rafael (Portuguese) and lola (Spanish). The other 25 per language are
separate downloads. The user downloads only the voices they want. That makes
150 voice assets, in VOICES (speech/assets_voices.rs). They are not in
CATALOGUE, because a voice is chosen within its language and is not a row of
its own. find looks in CATALOGUE first, then in VOICES.
Where a downloaded voice goes. Kind::Voice { language, voice } installs at
<speech>/voices/<language>/<voice>.safetensors. This directory is outside the
language directory on purpose. promote replaces a language directory whole,
so a voice kept inside it would be deleted when the user reinstalls or updates
the language. A voice stages into its own .staging/<id>/ and promote_voice
moves one file into place. It never renames a directory, because that would
replace the other downloaded voices of the language. remove of a voice deletes
its file only.
pocket::voice_path looks in three places, in this order:
<language>/voices/<voice>.safetensors(the shipped voice). A shipped voice wins over a download with the same name.<speech>/voices/<language>/<voice>.safetensors(a downloaded voice). A voice downloaded for another language is not found.<speech>/user-voices/<language>/<voice>.safetensors(a voice file the user imported).
Voice files the user adds. TUICommander does not make voices. A user who
wants another voice makes a .safetensors voice file with other tools and
imports it into one language. import_speech_voice stores it at
<speech>/user-voices/<language>/<name>.safetensors, outside the language
directory, so a reinstall of the language keeps it. Before it writes anything,
library::import_speech_voice checks, in this order:
- The name uses only letters, digits,
-and_, with at most 32 characters (MAX_USER_VOICE_NAME), the same rulevoice_pathapplies. - The name is not the name of a catalogue voice of that language.
- The file is at most 64 MB (
MAX_USER_VOICE_BYTES), more than the largest 24-layer voice. - The language is downloaded, and the file fits its model:
PocketSpeech::validate_voiceparses it withVoiceState::from_bytesandbundle::check_voicecompares every tensor with the language’s state manifest. A tensor the model has no place for, or a shape larger than its slot, is refused. This refuses a 24-layer voice in a 6-layer language, and afrench_24lvoice from8843db76(it carriesself_attn/pad), which would otherwise stop after one frame.
A file that fails a check is refused with the reason and is never stored. A file that passes is written beside its final name and renamed into place, so a failed write never leaves half a voice in the list.
Two revisions, and why French stays behind. The voices of five languages
are pinned at kyutai/pocket-tts-without-voice-cloning commit 8843db76.
French (french_24l) is pinned at commit 00eac05e. The French voices at
8843db76 have 72 tensor keys: they add a self_attn/pad key per layer and a
KV cache for a newer model than the ONNX export at 58a6d00c. With that export,
every one of them stops on the first frame and renders 0.72 s, in this engine
and in the reference runtime. The French voices at 00eac05e render normally.
The macro voice_revision! in assets.rs gives each language its revision.
The test every_voice_url_carries_its_languages_revision holds every voice URL,
default voices included, to that revision.
The catalogue is generated, never typed. scripts/speech-assets/gen_voice_catalogue.py
reads the sha256 and the size of each voice from Hugging Face (paths-info, the
LFS object id) at the pinned revision, and writes speech/assets_voices.rs with
a do-not-edit header. It also checks that the default voice of each language in
assets.rs has the same revision, sha256 and size that Hugging Face reports,
and fails if it does not. Run it with uv run scripts/speech-assets/gen_voice_catalogue.py.
The gate comes before the catalogue. Do not add a voice that
scripts/speech-assets/verify_voices.py has not rendered with the same
revisions. For each language and each of its 26 voices, the script renders one
sentence in that language with the reference runtime of the ONNX export at
58a6d00c (downloaded at run time, not copied into this repository). A voice
passes when its audio is not empty, contains no NaN and no infinity, and lasts
0.5x to 3x as long as the language’s default voice on the same sentence. The
sentence must be in the language of the model: a model that reads a foreign
sentence can continue for seconds, and then the probe measures the sentence,
not the voice. The script writes nothing into the repository; all downloads go
to --cache-dir. A failure exits non-zero. The result at the pinned revisions
is 156/156.
uv run scripts/speech-assets/verify_voices.py --cache-dir ~/Gits/.tmp/pocket-voices
Installing is two steps, and the split is the point
download and verify into .staging <- no lock held; the engine may be speaking
unload the engine for this language <- waits for the sentence in flight
rename .staging into place <- microseconds, nothing can speak
next synthesis loads the new files <- lazily, as it always did
The long part holds nothing; the part that excludes synthesis is a rename.
SpeechLibrary (speech/library.rs) owns that order — assets.rs deliberately
does not take the lock itself, so the two cannot be collapsed by accident.
The old directory is removed before the new one is renamed in, which leaves a window where neither exists. That is the right way round: a crash inside it leaves the language absent, which the status query reports honestly and the user can fix by downloading again. The other order can leave a directory half belonging to each version, which passes every existence check and then fails somewhere inside onnxruntime.
Readiness is checked by size, not by hash. The hash is verified once, while
the bytes are arriving; re-reading 125 MB to answer a status query would make
opening a settings panel cost a disk sweep. A file truncated after install still
shows the wrong size, which is the failure this has to catch. The three states
are distinct on purpose — absent offers a download, incomplete names what is
missing, and only ready lets a language be used.
bundle.json is the contract, not the code
The manifest publishes the streaming-state shape — 18 flow-LM and 56 Mimi
tensors, each with input name, output name, module, key, dtype, fill and shape
— plus sample rate, frame rate, chunk size and text-preparation flags.
bundle.rs carries that state between steps, so a bundle for a new language
loads unmodified. This is why English works with no language-specific branch.
A voice file is the flow-LM cache itself, keyed module/key. Voices disagree
about its size (Italian giovanni holds 94 frames in 12 tensors, English
cosette 126 frames in 18, with an extra pad key), so copy_overlap copies
the voice into the corner of the graph’s larger cache instead of assuming a
shape.
The runtime library is loaded explicitly
ort is built in load-dynamic mode: its default feature downloads
onnxruntime during the build and then has to be bundled on three platforms,
while here the library travels with the model it serves.
That mode panics if left to itself. ort resolves the library through the
system loader on first use and expects the result, so a half-finished
download would abort the process. load_runtime calls ort::init_from on an
explicit path before any session is built, turning it into
ModelUnavailable. It memoises only success, so a user who downloads the
runtime after a failed attempt gets speech on the next request rather than
after a restart. ORT_DYLIB_PATH still wins when it is set.
The tokenizer is not the sentencepiece crate
That crate statically links protobuf 3.14 while onnxruntime links 3.21, and
the two abort the process on first use. tokenizer.rs reads the model proto
with sentencepiece-model and runs the Unigram Viterbi through tokenizers,
both pure Rust. ids_match_the_reference_tokenizer holds it byte-identical to
Python sentencepiece on the real Italian bundle.
Cancellation and the budget
Unlike the Kokoro C ABI, this one can stop: generation is a loop this process
drives, so SpeechCancel is checked at the chunk, frame and decode loops and
an abandoned reply stops within a frame.
Generative TTS also runs away — one evaluation candidate produced 195 KB and
675 KB of audio for the same sentence across four runs. budget_seconds
states the ceiling once for every adapter, Bundle::frames_for converts it to
frames, and remaining_frames returns SpeechError::Runaway rather than
letting a chunk mint audio the input never warranted.
Threading
An ort::Session is driven by &mut while the port hands out &self, so the
engine sits behind a mutex and synthesis serialises. One spoken reply at a
time is the actual requirement, not a limitation.
Bring your own engine (speech/external.rs)
The bundled bundles cover English, French, German, Italian, Portuguese and
Spanish. Japanese, Chinese, Korean and Russian are not among them, and no
engine stays the best one for long. speech_command in the dictation config
makes the engine a setting: TUICommander hands a command the text and a path
to write, and reads the audio back through the same port the bundled adapter
implements. Neither adapter knows the other exists.
The template
The command is argv, not a shell line. Three markers say where the pieces
go, and each is replaced inside the argument that holds it — so
--output={out} works as well as -o {out}.
| Marker | Meaning |
|---|---|
{out} | the file the command must write. Required |
{text} | the text to speak. Omit it and the text goes to the command’s stdin instead |
{voice} | the voice identifier, as the engine spells it |
Japanese, with piper — a language the bundled engine does not reach:
"speech_command": [
"piper",
"--model", "/Users/me/voices/ja_JP-test-medium.onnx",
"--output_file", "{out}"
]
piper reads its text on stdin, so there is no {text}. macOS say takes it
as an argument and names its voices, so both markers appear:
"speech_command": [
"say", "-v", "{voice}", "-o", "{out}",
"--data-format=LEF32@22050", "{text}"
]
It runs as you
The configured command runs as the user who is running TUICommander, with that user’s environment, permissions and files — exactly like a shell alias they wrote. Nothing here sandboxes it, and nothing here should: the point of the setting is to run an engine the application does not know about.
What the application does guarantee is narrower and worth stating exactly:
no shell is involved. The command is spawned directly, so the transcribed
text is one argument (or stdin), never part of a line something parses. A
sentence containing ; or a backtick is a sentence. A {voice} that is not a
plain identifier is rejected as UnknownVoice before spawning, because that
one does become argv.
Failure is never silence
| What the command does | What the port returns |
|---|---|
| is not installed | ModelUnavailable naming the program |
has no {out}, or none is configured | ModelUnavailable naming what is missing, before anything is spawned |
| exits non-zero | Failed with the exit status and the tail of its stderr |
| exits 0 and writes nothing, or an empty file | Failed — the silent success this exists to prevent |
| writes something that is not 16-bit PCM or 32-bit float WAVE | Failed naming the encoding it did write |
| does not finish in time | Failed, after being killed. The budget is 30 s or four times the audio the text justifies, whichever is larger — a cold engine loads a model before it says the first word |
| is abandoned mid-run | Cancelled, after the next poll stops the command tree and reaps the direct child |
| returns more audio than the text can justify | Runaway, at the same ceiling the bundled adapter stops itself at |
Timeout and cancellation stop the owned Unix process group, or the Windows
process tree through taskkill /T /F, before reaping the direct child. This
also stops an engine started by a shell wrapper, rather than leaving it
running with the stderr pipe open. Commands that deliberately detach from
their process group are outside this cleanup contract.
Stereo is mixed down to mono rather than refused. WAVE_FORMAT_EXTENSIBLE
headers are read through to the encoding inside them.
Speaking the replies (speaker.rs)
Speaker is a bounded queue and one render thread between the model’s text and
the speaker. It carries the same generation counter the hands-free state
machine uses for turns, and it exists for one case: a reply can finish
rendering after the turn it answers is over.
say(generation, text)
│
▼
[queue] <= MAX_QUEUED (4); a reply whose generation is over never reaches an engine
│
▼
synthesis holds a SpeechCancel; both adapters check it as they go
│
▼
generation checked again <-- finished, correct audio is discarded here
│
▼
output.play()
Three checks, because a reply can go stale at three moments and only the last of them has audio to throw away. Cancellation covers the first two; nothing can cancel a request that already returned.
The loudness stage (loudness.rs)
The render thread runs loudness::process on every reply after synthesis and
before output.play(). The audio it gives to the output is therefore also the
echo canceller’s reference. Rendered voices differ in level by more than 10 dB,
and one reply also changes level within itself. The stage brings every reply to
one level.
Two DictationConfig fields control it: speech_volume_db (default -18 dBFS,
the “Voice volume” slider) and speech_levelling (default 0.67, the
“Levelling” slider). set_dictation_config gives the new values to the armed
speaker with set_loudness. The next reply uses them; the queue is not dropped
and the speaker is not rebuilt. A voice preview goes through the same stage
with the saved values.
It runs offline on the whole rendered buffer, in place, in four steps. It does not run as a streaming rodio source: the reply is fully rendered before playback, so a level measured over the whole reply costs nothing. A causal AGC increases the gain slowly during the first words and boosts the silence.
- Levelling. A 300 ms running RMS envelope drives a gain toward the reply’s
own speech level. The ratio comes from
levelling: 0 gives 1:1 (off), 1 gives 4:1 (1 + 3 × levelling). The boost is at most +12 dB. A sample whose envelope is below the -50 dBFS gate is silence and is not levelled. - Gain to
volume_db. The speech level is measured over a 20 ms envelope, on the samples above the gate only, so the silence next to a sentence does not pull the level down. A gated sample never gets more than unity gain, so the noise floor between sentences does not increase. - A look-ahead limiter at -1 dBFS, for the peaks that the gain moved near
full scale. It is not rodio’s
Limit, which is a streaming limiter. - A hard clamp at -1 dBFS, because a limiter with an attack time can let the first samples of a transient through.
Loudness { volume_db, levelling } takes volume_db in dBFS (-30 to -12; the
config clamps a stored value into that range) and
levelling from 0 to 1. The envelopes use a running sum, so the cost is O(n).
The test a_thirty_second_reply_is_processed_within_budget holds 30 s of audio
at 24 kHz to 5 ms in release (50 ms in debug). It is excluded from coverage
builds because instrumentation changes the work being timed; run the normal
release test to verify the 5 ms budget. Empty audio, a zero sample rate and
audio with no sample above the gate are not changed.
What hush guarantees
Speaker::hush() is what the user talking over the reply calls. It bumps the
generation, clears the queue, cancels the in-flight request and stops the
device, then returns the new generation. It does the device stop outside
the state lock and never waits on the render thread, so its cost is an atomic
store rather than the remainder of an utterance.
The render thread plays while holding the state lock, on purpose. Released
between the generation check and the play, an interruption landing in that
window would bump the generation, stop an idle device, and then have the stale
audio appended behind it. play only queues a buffer, so hush waits on the
order of a mixer append.
Two hush calls are two turns. That is not an accident of the counter: two
interruptions in a row are two turns, and a reply addressed to the first one
is no more current than a reply addressed to the turn before it.
Failures are reported, never retried in place
| What happens | What the queue does |
|---|---|
| the engine cannot render (missing bundle, bad voice) | records the message in SpeakerStatus.last_error, drops the reply, takes the next one |
| the device refuses the audio | same, and the render thread stays alive |
the engine returns Cancelled | nothing — somebody asked for that |
| a fifth reply is queued | refused as SpeakError::Full while the queue is still short enough to drain |
| a reply arrives for a turn that is over | refused as SpeakError::Stale, before any engine is called |
the Speaker is dropped | shutdown flag, queue cleared, in-flight request cancelled, device stopped, worker joined |
last_error is cleared by the next reply that plays, so the UI cannot show a
problem that is over.
Utterance identity: accepting a reply is not the user hearing it
say returns a UtteranceId, and the queue remembers the last 64 of them with
what became of each. A caller polls Speaker::utterance(id) — through
get_speech_status or the voice tool — to find out.
| State | Means |
|---|---|
queued | accepted, nothing has been rendered |
rendering | synthesis is running |
speaking | handed to the device |
finished | the device went quiet with this reply behind it — the only state that means somebody heard it |
interrupted | the turn ended first, or hush arrived mid-sentence |
failed: <reason> | never audible; the reason is the engine’s or the device’s |
The distinction is structural, not documentary. finished is written in exactly
one place — note_playback_drained, which runs only when Output::is_speaking()
is false. And hush reads the device before stopping it, so a reply already
heard to the end is not rewritten as interrupted just because an interruption
followed it.
The device reports one boolean for its whole queue, so replies handed to it resolve together when it goes quiet. That is correct rather than approximate: it drains in order.
Finding out costs a timed condvar wait of 25 ms — but only while something is actually playing. An idle speaker blocks on the condvar and never queries the device at all.
Who may speak
Speech belongs to a conversation, not to the application. Caller is the whole
rule:
| Caller | May drive |
|---|---|
Owner — the user’s own UI, on either transport | always |
Model(session) — an MCP connection, named by the TUIC session it is bound to | only the conversation armed for that same session |
An MCP connection with no TUIC session is refused outright rather than falling
back to Owner: that path exists for the user’s UI, and handing it to a model
would let any client speak into whichever conversation happened to be armed.
status checks the binding too — the fields alone say what somebody else’s
conversation is doing, and a model that can see a queue will try to speak into
it.
The same speech contract on every transport (817-f67c)
There is one implementation per operation and every transport reaches it. That is the parity, and it is structural rather than mirrored by hand:
| Transport | Entry point | Caller |
|---|---|---|
| Tauri IPC | #[tauri::command] speak_reply / stop_speech / get_speech_status | Owner |
| HTTP | dictation_routes.rs → the same dictation::commands functions | Owner |
MCP (HTTP and the collapsed call_tool path) | mcp_transport.rs::handle_voice | Model(session) |
The Owner surfaces are the user’s own UI on either transport; the MCP surface
is the model’s, and the split is the ownership rule in Who may speak above.
There is no WebSocket surface for speech and none is wanted: a WS lane is for
high-frequency streams, and a reply produces a handful of state changes.
Three tests hold it. command_table_paths_all_hit_a_registered_route proves
every COMMAND_TABLE speech path resolves to a registered route.
the_speech_status_wire_shape_names_every_field_a_client_reads and
a_reply_looks_the_same_whether_it_was_accepted_or_polled_for pin the two wire
shapes — the second compares the keys of an accepted reply against the keys of
the same reply polled for, because the render thread moves the state between the
two reads and a value comparison would be a race dressed as a contract.
voice_binds_to_the_calling_terminal_on_the_direct_and_collapsed_paths proves
the MCP identity survives both dispatch paths.
The push half, on both transports (833-6fd4)
Three pushes leave the backend, and each one is dual-emitted: a desktop
app.emit(name, payload) and state.event_bus.send(AppEvent::…{ payload })
for the /events SSE stream. There is no bus→window forwarder, so a producer
that emits only one of the two reaches only one kind of client.
| Event | Fires when | Payload |
|---|---|---|
dictation-download-progress | a Whisper model is downloading | { downloaded, total, percent } |
speech-download-progress | a speech asset is downloading, and once more when it ends | the same, plus asset; the last event is { asset, done: true } on success and failure alike |
speech-utterance | a reply changes state | the SpokenReply shape speak_reply returns |
One serializer feeds both. Each AppEvent variant carries an
already-built serde_json::Value; the desktop emit gets payload.clone() and
the SSE arm returns payload.clone(). The two cannot drift, because there is
only one place the body is built. every_dictation_push_names_and_shapes_itself_the_same_on_both_transports
pins the half that still can — the SSE event name, and its refusal to re-wrap a
body that is already the payload.
asset distinguishes the two downloads, and only the speech one carries it.
A client that renders both bars needs to know which one moved; a Whisper model
download has no asset id to give. only_a_speech_download_names_its_asset holds
that.
Utterance state is pushed by the speaker, not by speak_reply. The
transitions that matter happen on the render thread, seconds after the call that
queued the reply returned: Finished and Interrupted have no caller to return
to. So speaker.rs carries an UtteranceObserver port, commands.rs installs
the AppHandle-backed adapter at startup, and every track/set is announced.
Two details are load-bearing:
- Transitions are buffered and dispatched with the lock released.
State::setruns inside the render thread’s critical section — several times perhush— so calling an observer there would run arbitrary caller code under the speaker’s mutex. next_replydrains before it waits. The last reply of a conversation is markedFinishedand then the loop blocks on the condvar; without a drain at that point the final transition would wait for a next reply that never comes.
A speaker nobody watches is the ordinary case for a unit test and for the
headless build, so the observer slot is a OnceLock that stays empty and the
buffered transitions are dropped rather than accumulated.
The engine’s own sample rate reaches the device
DeviceOutput passes SpeechAudio::sample_rate straight through and lets
rodio resample to whatever the device wants. Pocket TTS renders at 24 kHz; a
user-supplied command renders at whatever its engine likes, and assuming a rate
here would pitch-shift every external engine. A zero rate or an empty buffer is
rejected before the buffer is built, because SamplesBuffer::new panics on
a zero rate and a panic on the render thread would take the queue down with no
message.
Echo cancellation is not in this file
Deciding when to interrupt means hearing the user over the speaker, which is
acoustic echo cancellation. Whoever detects near-end speech calls hush; this
module has no microphone and no opinion. The split is deliberate — the queue’s
correctness is provable without audio hardware, and an audio-hardware test
cannot prove the queue. It lives in echo.rs, below.
Barge-in: pause on voice, stop on the wake word (1376-f33e)
Voice activity alone does not stop a reply: a turn needs the activation phrase,
and so does interrupting one. The capture loop in continuous.rs drives the
Interruptible port it holds for the armed conversation:
- Voice pauses. When the open utterance first holds a voice,
pause()holds the reply where it is. Nothing queued is dropped and no turn changes. - The transcript decides. An accepted turn (
HeldBack, orActivatedfor the phrase alone) callshush(): the reply stops and the turn begins. Any other verdict (Rejected,Empty,Stale), an utterance dropped for too little speech, the end of the loop, orPAUSE_LIMIT_MS(8 s) callsresume(). Measured on the log of 2026-10-02, voice edge to accepted turn is 2.2 s for a short command, plus the length of longer speech. - A voice is a run, not a sum.
Segmenter::has_voiceneedsmin_speech_msof activity with dips of at mostVOICE_GAP_MS(60 ms).has_speechadds up every active frame of an utterance that stays open until 1.5 s of quiet, so scattered residual echo (a frame in every 200 ms) reached the bar within a second and hushed replies 600-900 ms in. Speech keeps thehas_speechrule for sending. - After the canceller, on the edge.
capture.echo.lock().clean(...)runs first; the trigger is the edge of the voice, not its level. - The echo reference follows the pause.
FarEndTapmarks the far end paused only when the output holds its audio (Output::can_pause), from the position the microphone had recorded when it paused and symmetrically on resume; capture recorded before the pause heard the reply. - The slot, not the queue, and never lost. The port is
commands::ArmedSpeaker, which holdsDictationState.speakerrather than theSpeakerthat was in it when the loop started. A command that meets a rebuild inspeakis recorded (latest wins) and applied by a thread once the slot frees; the capture loop never waits for it, and the verdict on a pause is never dropped. - Outputs.
DeviceOutputpauses the rodioPlayer;BrowserOutputsendspause/resumeframes and the client stops the audio node and continues from the same position, keeping a reply that arrives while held.
The queue is built in arm_hands_free_with before the runtime is spawned
whenever a language is already known, for this reason alone: a loop started
first would spend its first ticks unable to interrupt anything.
Correlated hold diagnostics (2605-53fc)
After a Rust rebuild/restart, each capture hold writes two structured INFO events
with source="dictation": barge-in hold opened and barge-in hold resolved.
Pair them by hold_id, owner and generation within the same process run.
The process-local hold ID starts again after a restart. No new transcript text
or PCM is retained. Existing admission logs are unchanged.
The opening event is sampled before requesting the output pause:
| Fields | Meaning and limits |
|---|---|
output_nonempty, can_pause | Best-effort output probe. Some(true) for nonempty means queued or paused audio, not acoustic activity. None means the slot is busy, absent, or has no probe. The probe does not wait for a voice rebuild. |
raw_rms, raw_peak | Mono 16 kHz energy of the drained batch before cancellation. This is not the normalized UI level. |
cleaned_rms_max, cleaned_active_frames | Maximum RMS and active count over complete 20 ms frames of this cleaned batch. Frames follow this batch’s start; they can differ from the segmenter’s carried-frame boundaries. |
longest_run_ms, activity_rms, min_speech_ms | Longest sustained run in the open/closed utterance and the actual segmenter thresholds that caused the edge. A long batch can open and close an utterance in one tick. |
drained_samples, backlog_samples, partial_samples | Batch size, best-effort endpoint backlog after drain, and echo cleaner’s carried partial 10 ms frame. None backlog means the capture buffer was busy or unavailable; it is not zero. |
capture_batches, dropped_samples | Cumulative capture counters: native CPAL callback batches/lost 16 kHz samples, or browser received WS batches/server overflow samples. Browser counters do not measure hardware callbacks or audio lost before receipt. An old drop count alone does not date the loss. |
far_end_samples, far_end_position, far_end_dropped | Reference queue length, capture-sample cursor and cumulative reference overflow, sampled under the echo lock just after cleaning this batch. Queue length can include alignment silence, not only reply PCM. |
last_render_age_ms | Time since reference registration, not time since DAC onset; None if no reply has registered for this capture. |
drain_to_clean_us, tick_interval_ms | Time from drain completion until the echo lock is acquired, and wall time between tick entries (None on the first tick). The latter includes inline recognition and scheduling, not just scheduler delay. |
The resolution event has the same identity plus reason, monotonic elapsed_ms
since opening, and cumulative inference_us spent in prefix/final recognition
while that hold was pending. inference_us=0 is valid when no recognition ran.
Resolution reasons are:
| Reason | Existing decision |
|---|---|
accepted | Final transcript was admitted with content; hush the old reply. |
activated | Final transcript was the activation phrase alone; hush the old reply. |
rejected | Final transcript did not pass activation; resume. |
empty | Final recognition returned no text, including downstream speech-gate skips; resume. |
stale | Final recognition belonged to a withdrawn/unarmed generation; resume. |
discard | Capture returned to no open utterance without a qualifying closed result; resume. |
limit | A tick observed elapsed capture time strictly greater than the 8000 ms hold limit; resume. |
release | Runtime cleanup released a still-pending hold, including a device/recognition failure, stop, or prefix-generation withdrawal. |
Only the first resolution of a pending hold is recorded. Runtime release after
an admitted/rejected/limited hold does not add another event. The existing
speech: resumed, nothing addressed to us message stays for compatibility;
use the new reason rather than inferring rejection from that old text.
The eight-second limit still runs on ticks and cannot preempt synchronous
recognition. Diagnostics do not change VAD, admission or output policy.
Read the existing instance-local daily logs/tuic.log.YYYY-MM-DD, or use the
existing log panel/API when enabled, and filter for barge-in hold . Compare
raw and cleaned energy, the reference queue and capture-drop counters at an
edge, then its actual verdict. A nonempty output plus high residual and a
capture discontinuity is useful evidence, not proof that the residual is echo.
Numeric aggregates cannot distinguish room speech from TTS echo or reconstruct
reference alignment. PCM replay requires a separate, explicitly authorized,
bounded opt-in capture; this diagnostic does not record or open a microphone.
What barge-in measures (816-cbbf)
The barge-in tests above this one all use Subtract, a perfect non-adaptive
canceller. It answers is the wiring right and cannot answer how long does it
take or how often does it fire when nobody spoke, because a perfect
subtraction leaves no residual to misjudge.
talking_over_the_reply_stops_it_without_losing_the_first_words in
continuous.rs drives the shipping AEC3 adapter through the same tick and
turns those into numbers. Measured 2026-09-22, macOS 27 arm64:
| Stop latency | 200 ms (re-measured 2026-09-23) — min_speech_ms of sustained speech, landing on a POLL_INTERVAL_MS tick. Was 50 ms while the hush fired on the first frame over the floor; that edge let residual echo stop every reply. |
| False triggers | 0 over 1200 ms of reply reaching the microphone with no user speech at all |
| Pre-roll preserved | 280 ms of audio ahead of the user’s first sample, out of the 300 ms ring |
| Utterance length | 1720 ms, against 280 ms of pre-roll plus 600 ms of speech — nothing was truncated |
The fixture is a room model, not a recording: the microphone hears the rendered reply 40 ms late and at 0.35 of its level, with the user’s voice added on top at a different pitch so the canceller cannot subtract the user by subtracting the echo and still look correct. That is the signal an echo canceller is specified against — a linear path with a delay — which is what makes the numbers comparable between runs. It deliberately does not model reverberation, the microphone’s noise floor, or a speaker driven into distortion.
without_the_canceller_the_same_room_interrupts_the_reply_on_its_own_echo is
the control, and the only reason the zero above means anything: the same room
with PassThrough installed must interrupt the reply before the user has said
a word. Without it, a false-trigger count of zero would be equally consistent
with a fixture too quiet to trip anything.
a_residual_echo_burst_does_not_stop_the_reply models what the linear room
cannot: a 100 ms burst the canceller cannot see, above the activity floor but
below min_speech_ms. It must not hush the reply.
Neither is a substitute for a real microphone and a real speaker in a room.
That probe is in to-test.md.
The eight states the conversation has to survive (820-21a5)
Story 820 names eight scenarios and asks for each one to be verified rather than
argued about. They are spread across continuous.rs and commands.rs because
they belong to two different layers — the mode’s own bookkeeping, and the
commands that arm and disarm it — so this table is the index. A row with no test
beside it is a gap, not an omission from the documentation.
| Scenario | Held by |
|---|---|
| Optional activation, on and off | an_empty_activation_phrase_lets_every_turn_through, speech_without_the_activation_phrase_never_reaches_the_queue, a_configured_activation_phrase_decides_which_speech_reaches_the_model, a_configured_phrase_gates_a_turn_and_is_stripped_from_what_is_sent |
| Phrase matching tolerates Whisper spellings, not look-alike speech | the_phrase_matches_the_spellings_whisper_invents_for_it, speech_that_only_resembles_the_phrase_does_not_activate, an_accented_or_capitalised_phrase_setting_matches_the_plain_transcript, the_rejection_excerpt_keeps_the_first_words_verbatim_and_nothing_more |
| Phrase-only timeout | the_phrase_alone_opens_the_window_without_sending_anything, follow_up_speech_inside_the_window_needs_no_phrase, speech_after_the_window_expires_needs_the_phrase_again |
| Hold-back cancellation | nothing_is_enqueued_before_the_hold_back_expires, an_abort_inside_the_hold_back_sends_nothing |
| Pause mid-sentence during the hold-back — the continuation is appended to the pending text and restarts the hold-back, never replaces it | a_one_second_breath_keeps_both_phrases_in_one_utterance, speech_that_arrives_during_the_hold_back_joins_the_pending_turn, keyword_turn_keeps_a_five_second_follow_up_in_the_same_terminal_message, speech_started_before_the_five_second_deadline_is_not_submitted_mid_phrase |
| Manual disarm | a_manual_abort_disarms_the_whole_mode_and_discards_the_pending_send, disarming_a_mode_that_was_never_armed_reports_no_work |
| Busy or dialog target | a_busy_target_takes_the_turn_a_dialog_holds_it_and_all_stay_targets, a_turn_the_composer_holds_stays_in_the_mode_and_is_retried, arming_types_speech_into_a_busy_session_and_leaves_its_compose_queue_alone, arming_against_a_target_that_cannot_take_a_compose_entry_is_refused |
| Target closure | a_closed_target_disarms_the_running_mode, a_closed_target_disarms_and_a_different_session_does_not, closing_the_bound_session_disarms_the_running_mode_and_releases_the_device |
| Owner disconnect | a_disconnected_owner_disarms_the_running_mode, a_disconnected_owner_disarms_and_a_different_owner_does_not |
| No stale submission | a_transcript_from_a_previous_generation_cannot_send, a_transcription_that_finishes_after_a_disarm_never_reaches_the_sink, an_abort_during_transcription_lands_and_its_result_is_refused |
| No stale playback | disarming_while_a_reply_is_playing_stops_the_device, a_reply_written_for_a_turn_the_user_talked_over_is_refused |
Two of those rows are worth reading before changing anything near them.
Busy is not closed, and not a hold. PtyTargetProbe::accepts asks whether
the target exists and can take voice at all — never what it is doing. A probe
that also answered “is it free right now” would end the conversation on the
first reply the user asked for. A busy agent takes the turn at once; only a
dialog or a draft holds it, and the hold lives in the mode, never in the
Compose queue. That is why the busy row asserts on VoiceWrite for three
sessions at once — idle, busy, and idle with a confident question — with the
idle one as the control, and checks that none of them gained a Compose entry.
Disarming silences by dropping, not by hushing. disarm_hands_free sets the
speaker slot to None; Drop for Speaker cancels the render in flight and calls
Output::stop. Asserting that the slot is empty is therefore not the same
assertion as asserting the room went quiet, and only the second one is what a
user experiences. The test uses an output that reports itself speaking until it
is stopped, because QuietOutput is never speaking and cannot tell a silenced
device from one nobody ever asked to stop.
The language of the conversation
Boss’s requirement is one sentence: the model and the voice use the language Whisper is transcribing, and nothing replies in English by accident. Four places enforce it, and they all read the same source.
| Where | What it does |
|---|---|
transcribe.rs | TranscribeResult.language — the two-letter code whisper used, read off full_lang_id_from_state() |
continuous.rs | HandsFree.turn_language, set by accept_transcript, cleared on arm and disarm |
continuous.rs | HandsFree.announced_language — the language the model was last told; compose_entry appends (reply in <Name>) only when a turn’s language differs from it |
commands.rs | speech_language picks the voice, and Armed.language records which one |
There is one language, not one per subsystem. The dictation setting is the
source when it names a language; under auto the source is what whisper
actually detected, carried out of the transcript by Transcript.language. There
is no separate TTS language setting, and the voice MCP tool takes no language
and no voice — a model that could pass either would be a second source, and the
two would disagree the first time the user switched languages.
auto before the first turn has no language, and that is a state.
speech_status reports available: false with a reason naming Auto, and
speak refuses. It is the one moment in a conversation where no reply can be
spoken, and inventing English to fill it is exactly the bug this exists to
prevent. The voice opens on the first speak after somebody has spoken.
Confidence is not available on this path. whisper_full_lang_id_from_state
returns the id and nothing else, so an ambiguous detection is indistinguishable
from a certain one. The probabilities live behind WhisperState::lang_detect,
which needs its own mel and encoder pass and would double the cost of every
utterance. What is handled is a missing answer: an id that maps to no code
leaves language: None, which reaches the model as the transcript alone — no
requirement rather than a guessed one.
A language with no bundle is named, never substituted. for_language_code
answers None for Korean, and the status says No speech bundle ships for language "ko". Picking the Italian voice because it is installed is how an
assistant answers a Korean conversation in Italian.
Which of the language’s voices speaks is a setting; which language speaks is
not. speech_voice names one of the voices the chosen language ships — the
Dictation panel offers them from voices on the asset, and the setting is empty
in an untouched configuration, which choose_voice reads as “whatever this
language ships first”. That is also what every configuration written before the
setting existed says, so no migration is needed. A user-supplied engine ignores
the setting: it names its own voices inside its command template.
A named voice the language does not ship is an error, not a fall back.
choose_voice answers with the offered names instead of speaking in the first
one. Two things get you here — a catalogue that dropped a voice, and a language
the user changed underneath the setting — and in both, speaking in a voice
nobody chose is worse than saying why nothing was spoken. The message reaches
the user through the hands-free status rather than a log.
The requirement travels in the spoken entry, once per conversation.
esegui i test is typed as esegui i test (reply in Italian); the next
Italian turn is typed as spoken, and a turn in English announces
(reply in English) again. The model is told once, not on every message:
HandsFree.announced_language records the language last stated, set only when
the sink typed the entry that stated it (a held or refused entry told the
model nothing) and cleared on arm and disarm. A turn with no nameable language
leaves it alone. With a fixed dictation language the start notice already
states it, so the first turn carries nothing either. In the entry rather than
only in a mode hint, because hints are optional and this is not; on one line, because the sink types
the entry into a terminal and submits it, and a newline in the middle submits
half a sentence. The English name comes from dictation/language.rs, whose
table is checked against WHISPER_LANGUAGES in src/stores/dictation.ts by a
test that reads the TypeScript.
Changing the language stops the replies written for the old one.
save_dictation_config drops DictationState.speaker when language,
speech_engine, speech_command, speech_edge_voice or speech_voice moves — and on nothing else, because cutting
a reply off mid-word because somebody moved a threshold slider would be the
worse bug. A voice belongs to a conversation as much as a language does: a
sentence half said in one voice does not finish in another. The
next speak opens a voice for the language now configured. The same rebuild
happens mid-conversation under Auto: speak compares Armed.language against
the turn language and, when they differ, hushes the old queue before building
the new one. That hush is what invalidates the replies in flight — it opens a
new turn, and say refuses anything addressed to the turn before it.
Lock order: the mode, then the speaker. Resolving a language takes
hands_free; rebuilding takes speaker. speak and speech_status both
resolve everything they need from the mode before taking the speaker lock, and
open_speaker_for is handed the language rather than looking it up, so the
rebuild under the speaker lock cannot invert the order.
Hearing the user over our own voice (echo.rs)
The microphone hears the speaker. Left alone, the energy VAD in continuous.rs
opens a turn on the reply the application is speaking, transcribes it, and
answers itself. Muting capture while speaking would stop that and would also
stop the user interrupting, which is the one thing hands-free has to get right,
so the capture stream stays open and the echo is subtracted from it instead.
speaker::render_loop ──note_rendered(SpeechAudio)──┐
v
┌─────────┐
│ FarEnd │ 16 kHz, ≤120 s
└────┬────┘
│ take(n), padded with silence
capture (mono 16 kHz) ──clean(&[f32])──> EchoGuard┴──> Canceller ──> cleaned capture
10 ms frames │ │
remainder carried │ v
│ segmenter.push
hush ──note_stopped───┘
The two streams must arrive in step
A canceller subtracts a delayed, filtered copy of the far end (what we played) from the near end (what the microphone heard). It can only do that if it is fed both at the same pace: one 10 ms frame of each, in turn.
Our two sources do not behave that way. Capture arrives in small chunks as the
device produces them, while speaker.rs hands over a whole rendered utterance
at once — seconds of audio in one call, before a single sample of it has left
the speaker. Pushing that straight into a canceller would put it seconds ahead
of the microphone, and it would subtract nothing.
FarEnd is the buffer that fixes the pace: the reply goes in whole and comes
out only as fast as capture is consumed, padded with silence whenever nothing is
playing. Alignment is therefore by sample count, not by wall clock, and the
residual offset — the device’s own output latency — is what the canceller’s
delay estimator is for. note_stopped (called on hush) clears the buffer,
because audio that will never be heard must never be subtracted.
The buffer must hold every reply the speaker has accepted, not a window of
recent audio. A reply is pushed whole before any of it plays, and the next
reply is pushed while the current one is still playing. So the head of the
buffer is always what the microphone hears next. The bound is 120 s (~7.7 MB,
only while that much is queued). It is reached only when capture stops
consuming, and then the newest samples are dropped, counted in
dropped_far_end() and logged at WARN (echo: far-end reference full).
Until 2026-09-23 the bound was two seconds and the oldest samples were
dropped. The oldest samples were the start of the reply, which had not played
yet. Every reply longer than 2 s was cut to its last two seconds: the start of
playback was matched against the end of the reply, then against silence.
Nothing was cancelled, and with laptop speakers hands-free heard itself, cut
its own replies off and sent them back as turns.
a_reply_longer_than_two_seconds_reaches_the_canceller_from_its_first_sample
holds that closed.
The start of a reply is aligned to the capture backlog. Sample counting
works only if the far end starts counting when the device starts playing. The
capture loop drains every POLL_INTERVAL_MS and runs Whisper inline, so when a
reply is handed over, up to several seconds of capture can still wait in the
endpoint’s buffer. That audio was recorded before the reply. So
note_rendered, when the far end is empty, first queues silence equal to that
backlog plus the carried partial frame, and then the reply. Otherwise the
reference runs ahead of its echo, which AEC3 cannot cancel. A reply queued
behind one still playing gets no padding, because the device plays it
back-to-back. The backlog is read through EchoGuard::attach_capture(Backlog),
a probe installed by open_endpoint for the desktop buffer and for
BrowserLink::pending_capture. Attaching a stream also clears what the
previous stream left behind.
Two log lines make a self-heard episode reconstructible from tuic.log:
speech: hushed, turn N begins (INFO, speaking, into_playback_ms since the
current run of replies was handed to the device, interrupted) and
Hands-free turn accepted (INFO, heard= the first four words), to compare
with the reply text.
Everything runs at 16 kHz
Not a preference. audio.rs already converts capture to mono 16 kHz for
Whisper, and 16 kHz is one of the rates the WebRTC APM accepts, so the near end
needs no conversion at all. The far end is whatever the speech engine rendered —
24 kHz for Pocket TTS, anything at all for a user-supplied command — and is
resampled on the way in. That resampling is linear, not the nearest-neighbour
audio.rs uses for Whisper: a canceller subtracts a waveform, and
nearest-neighbour’s step artefacts are error it would have to model.
The port exists so the pacing is provable without hardware
| Adapter | What it is for |
|---|---|
webrtc::WebRtc | The real one: WebRTC AEC3, one instance, 10 ms frames |
PassThrough | No cancellation. A build without a canceller, and the tests for everything in EchoGuard that is not the subtraction itself |
PassThrough is not a silent fallback — whoever installs it owns saying so. It
exists because a hands-free mode that refuses to arm is worse than one that
cannot be interrupted over the speaker: headphones still work.
AEC3 runs with stream_delay_ms: None, so it estimates the offset itself. We
could not supply an honest number anyway: the far end is handed over when the
reply is rendered, and how long the OS and the device then hold it before it
reaches the air is not something this process is told. One consequence worth
knowing — the estimator has to converge, so the first fraction of a second of a
reply is cancelled poorly or not at all.
The render frame is analyzed, never processed. The APM offers to filter the playback stream too; by the time we see it that audio is already on its way to the device, so any change to our copy would be a change nobody hears while the microphone still hears the original.
Noise suppression, gain control and high-pass filtering are all left off. The same capture stream feeds Whisper, which was trained on speech that has not been gated or gain-ridden.
The fork this needs (patches/webrtc-audio-processing-sys/)
webrtc-audio-processing 2.1.0 is used with the bundled feature — it
statically links the APM rather than looking for a system library, because there
is one on Linux, a brew-only one on macOS, and none at all on Windows. Upstream
CI runs ubuntu-latest and macos-latest only, and the bundled build does not
work on Windows at all; five of our six patches exist for that, and one
for a macOS link failure. They are listed, with the exact symptom each one fixes,
in the [patch.crates-io] comment in src-tauri/Cargo.toml.
Build prerequisites
Every platform needs meson, ninja, a C++20 compiler and libclang
(for bindgen) on PATH, plus network access: the meson wrap fetches
abseil-cpp 20240722.0 from github.com while the build runs. None of this
reaches tuic-remote — cargo tree --no-default-features -i webrtc-audio-processing matches no packages, so the headless binary needs
neither meson nor ninja.
Windows MSVC targets force Meson’s Visual Studio environment with --vsenv,
so MinGW on PATH cannot become the bundled library’s compiler. Compilation
and installation run through meson compile and meson install to reactivate
that environment in each subprocess.
MSVC setup uses --wipe so a restored Meson cache cannot retain a previously
selected MinGW compiler; other targets continue to use --reconfigure.
| Platform | Extra | Why |
|---|---|---|
| Windows | set CARGO_TARGET_DIR=C:\t | abseil’s hashtablez_sampler_force_weak_definition.cc resolves one character past MAX_PATH (260) from the meson build directory under a normal target path. cl reports it as C1083: Cannot open source file for a file that is plainly there. Not fixable by a patch — it is a path-length limit. |
| Linux | a libclang with its builtin headers (clang-devel, not the pip libclang wheel) | The wheel ships libclang.so and no resource directory, so bindgen fails on 'stddef.h' file not found. Recoverable with BINDGEN_EXTRA_CLANG_ARGS=-I/usr/lib/gcc/<triple>/<ver>/include. |
| macOS | — | Xcode’s clang and a brew meson are enough. |
Do not tar the fork on a Mac without COPYFILE_DISABLE=1. bsdtar writes
an AppleDouble ._abseil-cpp.wrap beside the real one, meson globs *.wrap,
and the build dies with UnicodeDecodeError: 'utf-8' codec can't decode byte 0xa3 — a message that points at the wrap file rather than at the sidecar.
Packaging evidence
A probe that builds the fork, links it, and asserts the canceller measurably changes a 440 Hz capture frame:
| Platform | Toolchain | Result |
|---|---|---|
| macOS 27 (arm64) | Xcode clang, meson 1.12.0 | PROBE OK |
| Windows 10.0.26200 (x86_64) | VS 2022 BuildTools 14.44.35207, meson 1.12.0 | PROBE OK |
| RHEL 9.4 (x86_64) | gcc 11, meson 1.11.2 | PROBE OK |
Linux is not a formality here: patch 3 replaced the pkg-config abseil lookup with an unconditional vendored subproject, and Linux is the one platform that has a system abseil for pkg-config to find. It is therefore the platform that patch most plausibly broke, and the only one upstream CI covered.
Voice settings choice owners (#1909-0d24)
The internal voice settings owner uses cache-only describe and explicit refresh for input devices, Whisper models, installed Pocket voices and Edge voices. Refresh reads the configured language through the strict voice file owner. Model options include installed/downloadable state; installed voice options retain their source. Input backend failure is unavailable, not a supported empty list. Edge refresh may fetch the service catalogue; describe never fetches or downloads.
VoiceAction provides typed assets, model download/delete, speech asset download/cancel/delete and voice import/delete. It delegates to the existing command owners and their allowlisted asset IDs, size validation and runtime locks. These are internal host methods for later transport publication, not an arbitrary command executor. Existing engine/language descriptors and runtime invalidation remain authoritative. Builds without dictation still describe unavailable voice fields.
Pocket voice recovery: a missing configured catalogue voice uses the ready bundle’s default voice in the same language. Each reply resolves the voice again before enqueueing, so a completed download takes effect on the next reply without rebuilding the language model. Unknown voice names remain errors. No voice or model from another language is substituted.
Settings correction owner (#1992-d4fa)
The machine-scoped corrections Settings store projects the existing
dictation-corrections.json map as /replacements records keyed by from.
Discover corrections.replacements.{from}.from and .to, then create/remove
records or set /replacements/<escaped heard text>/to with the current owner
revision. JSON Pointer escaping applies to heard text containing / or ~.
The file format remains a plain string-to-string map.
Both the Settings facade and the legacy IPC/HTTP map writer use TextCorrector’s
strict locked update and atomic persistence. Invalid maps and corrupt files do
not replace the live dictionary. Empty match keys are rejected because replacement scanning must advance.
Settings applies stable-key rules to requested paths and create/remove keys,
plus transaction size bounds. Existing legacy keys outside those rules remain
unchanged when ordinary sibling records are edited, created or removed;
legacy maps retain their existing string-to-string representation.
The live corrector is refreshed from the latest committed map, not an older
transaction result. Durable writes publish value-free corrections generations;
open Voice pages reload the saved map without replacing the new-entry draft.
Builds without dictation describe this family as unavailable. No microphone or
speech service is needed for correction configuration.
Isolated speech diagnostics
An authorized make agent-test AGENT_TEST_INSTANCE=agent-test-<name> AGENT_TEST_SPEECH_OUTPUT=1 can exercise spoken replies without microphone input. The runtime forces hands-free listening off and refuses microphone permission/capture. It does not claim global input ownership. Each actual reply synthesis logs its engine, resolved voice, language and completion, but not reply text or external command arguments. The default agent-test build still excludes dictation.
Voice saves normalize the latest locked engine selection before applying the caller’s field delta. An unchanged resolved Edge choice must not remain unset on disk and later migrate to an inactive external command or Pocket voice. A concurrent explicit engine choice is retained unless this caller changed that field.
ACP channel origins do not identify an individual session within a shared connection. If another session on that connection has an unsettled turn, voice calls are unavailable rather than attributed to the wrong chat. Settled turn history does not mute the target.
Browser reply scheduling (2605-53fc)
The browser appends complete downlink buffers on AudioContext.currentTime.
Each source starts at the preceding source’s end, without waiting for the
main-thread ended callback. Pause stops scheduled sources and retains their
positions; resume reschedules the active remainder before later replies. Stop
and teardown invalidate every scheduled source and its stale callbacks.
Each binary reply has a sample rate, a monotonically increasing 64-bit sequence,
and PCM samples. Per-reply playback-ended controls echo the sequence as a
string. The backend uses one locked playback state for appends, holds, stops and
ACKs, adds queued durations, and ignores ACKs that would retire newer audio.
Client and backend ship together; reload an old browser tab after updating.
With perfDebug on (window.__TUIC__.setPerfDebug(true)), each chunk logs an INFO dictation line at schedule time (seq, audio-clock at, dur, gapMs) and one when it ends (audioClock). gapMs is the silence between the previous scheduled end and this start on the audio clock; it is large after an idle period and 0 for chunks queued back to back. Output is off by default. A hidden browser tab delivers no ended callbacks, so keep it visible when measuring.
This fixes browser truncation present since f03ec66af5. It does not establish
that browser playback caused the reported native stutter. The retained native
probe and capture-hold evidence describe separate mechanisms and limitations.
Reply admission during near-end speech (#2683-5b0f)
Synthesis may complete while the user speaks. A new rendered reply stays in the reply queue until the segmenter has closed the utterance and its transcript has passed hold-back and completed submission. A draft or question that holds the submission also holds playback. A failed submission does not release playback; a later successful turn can release it. With no pending input, playback starts immediately.
Native and browser output share one backend gate. It reads the existing hands-free state under the same lock as capture edges and transcript submission. The final output append occurs under that lock. A blocked renderer releases its queue lock and retries at the existing 25 ms playback cadence, so cancellation and shutdown remain immediate. The gate precedes the far-end tap: unplayed audio is not added to the echo reference. A new phrase still open after a closed phrase in the same capture batch keeps the gate closed, even if the closed phrase was submitted.
The existing barge-in policy remains: accepted activation can cancel obsolete replies. This admission rule does not diagnose acoustic echo or replace the separate pause/resume verdict policy. State/queue regressions use the real segmenter and submit boundary; they do not claim a speaker/microphone reproduction.
Alacritty Terminal Integration
TUICommander uses alacritty_terminal 0.26.0 as its terminal emulation backend. We maintain a local patch at src-tauri/patches/alacritty_terminal/ referenced via [patch.crates-io] in Cargo.toml.
Why a local patch
alacritty_terminal is designed for the Alacritty GUI app. Several methods and fields needed by an embedded terminal backend are private. Rather than forking the entire repo, we patch the crate locally — minimal changes, easy to audit, easy to rebase on upstream updates.
Our patches
The patch includes semantic changes listed below as well as rustfmt-only
changes in other files. term/search.rs now has a semantic change: it searches
retained zero-width scalars in addition to the base scalar. Do not classify it
as formatting-only when rebasing. The crate is a workspace member with no
local rustfmt.toml, so workspace formatting also rewrites upstream style;
review semantic changes separately from that reflow.
| File | Change | Why |
|---|---|---|
src/term/mod.rs | Zero-width input damages the actual base cell | Separately received combining marks reach both parse-side changed rows and render frames, including marks attached to a wide base cell. |
src/term/search.rs | Feed base and zero-width scalars to the regex search automaton in both directions | Match exact stored Unicode sequences while returning cell coordinates; TUIC converts buffer-search ranges to UTF-16 for JavaScript consumers. |
src/term/mod.rs | pub fn resize_reflow(size, reflow: crate::grid::ReflowMode) | Choose the reflow policy on resize. Ink/Claude Code uses CUU cursor positioning that breaks when reflow merges/splits screen lines. |
src/term/mod.rs | pub fn mark_fully_damaged() (was fn) | Lets us force full-frame damage directly instead of maintaining a parallel flag. |
src/term/mod.rs | Parse-side damage: TermParseDamage enum, TermDamageState.parse_lines/parse_full, pub fn parse_damage()/reset_parse_damage(), damage recorded in write_at_cursor | A SECOND, independent damage view for TUIC’s PTY parse path (TerminalGrid::process → ChangedRow), read+reset separately from the render damage so the two consumers never steal each other’s damage. Lets process() diff only changed rows instead of rebuilding+diffing the whole screen per PTY chunk. write_at_cursor now damages the written cell (upstream reconstructs input damage lazily at damage() time from cursor deltas, which left the parse consumer blind to typed text); this is at worst a safe over-damage for the render consumer. Correctness pinned by the process_damage_matches_full_diff differential test. |
src/term/mod.rs | fn osc7770(&mut self, verb, payload) | OSC 7770 TUIC protocol handler. Fires Event::Tuic { verb, payload } for in-band state/suggest/intent signalling. |
src/term/color.rs | pub fn named_color_to_index(NamedColor) -> Option<u8> | Maps named colors to xterm-256 indices. Eliminates 30-line match duplication in our serializer. |
src/event.rs | Event::Osc133 { command, params, line }, Event::Osc7(String), Event::Tuic { verb, payload, line } variants | Carry parsed OSC 133 / OSC 7 / OSC 7770 events from VTE to the application layer. All three carry the grid line where the marker landed. |
src/term/mod.rs | Config.alt_scrolling_history + alt-grid history in Term::new/set_options, era reset in swap_alt | Optional alternate-screen scrollback, implemented with Alacritty’s separate grids rather than a shared persistent line buffer. Upstream gives the alternate grid capacity 0 (XTerm semantics), so an app printing more than a screenful (gh run watch, less, man) loses whatever scrolls off. The field defaults to 0, preserving upstream behavior for consumers that do not opt in; TUICommander uses the primary cap. Each enter/exit starts a fresh alternate era, so sessions never inherit one another and no alternate lines remain logically retained after exit. Oversized repeated redraws remain repeated because the emulator is byte-faithful, not a semantic snapshot deduplicator. |
src/term/mod.rs | pub fn primary_total_scrolled() | Returns the primary grid origin including evicted rows, selecting the inactive primary grid during alternate-screen use. Durable-log extraction and resize synchronization use this origin to keep capturing after the history cap. |
src/term/mod.rs | pub fn primary_history_size() | Returns primary-grid history even while the alternate grid is active. Durable-log resize synchronization must stay in this coordinate space; using active alternate history can suppress the first normal-shell lines after exit. |
src/grid/row.rs, src/grid/mod.rs, src/grid/resize.rs, src/term/mod.rs | Row::copy_origin_unknown | Per-row copy provenance: predecessor eviction/purge makes the oldest retained origin unknown; full row reset/erase restores it. Selection cleanup consults this flag without changing absolute row counters. |
src/grid/mod.rs | pub fn reset_history_era() | clear_history() keeps lines_scrolled monotonic because absolute row ids must be stable for the life of a physical line. The alternate screen is a separate content universe wiped on every enter/exit, so it gets a fresh era instead: history and counter reset. Frame-protocol keyboard_flags bit 5 marks the transition; the frontend then atomically invalidates row, scroll, selection, search, and link state. |
src/grid/mod.rs | lines_scrolled field + pub fn total_scrolled() | Monotonic count of lines ever scrolled into history (incremented in scroll_up). total_scrolled() - history_size() gives lines evicted from the top, the base for an eviction-stable absolute row coordinate. Excluded from PartialEq; serde(default) so old ref fixtures still load. |
src/grid/mod.rs | pub enum ScrollSource + pub fn scroll_up_with(region, positions, source) | Says why lines move up, because the region cannot: a linefeed past the bottom margin and a DL at the top row both present a region that starts at line 0. Overflow feeds history, advances lines_scrolled and shifts a scrolled-back viewport; Control swaps within the region and moves no counter. scroll_up still delegates as Overflow, so resize.rs and clear_viewport are untouched (#834-1878). |
src/grid/resize.rs | pub enum ReflowMode { None, All, HistoryOnly }; Grid::resize and grow_columns/shrink_columns take it instead of bool | HistoryOnly is the mode TUIC runs: scrollback stays readable across resize cycles while visible screen rows are truncated/padded, so a cursor-addressed TUI is not re-wrapped under itself. The screen/history boundary is derived from the post-rezero() storage layout (i < self.lines is screen). |
src/grid/mod.rs, src/term/cell.rs, src/grid/row.rs, src/grid/resize.rs | GridCell::is_blank() (a space with no visible attributes, any colour); Row::shrink trims trailing blanks; shrink_columns fills the last wrapped row with the edge cell when the background padding reached the old right edge | Programs pad coloured rows (diff lines) to the full width with background-coloured spaces or EL. Upstream is_empty requires the default background, so a narrower reflow wrapped that padding into partial coloured rows the program never drew. Padding is dropped at the cut, and the row it wraps into stays coloured to the new edge. Pinned by terminal_grid_diff_padding_2780_tests.rs with recorded Claude Code diff bytes (#2780-e44d). |
src/grid/row.rs | Row.reflow_wrap: bool (serde(default)) | Marks a wrap produced by this shrink. History rows only merge when it is set, so a stale natural wrap from an earlier width is never joined. Reset by Row::reset, propagated when a row is absorbed. |
src/grid/storage.rs | debug_assert_eq!(size_of::<Row<T>>(), size_of::<usize>() * 5) (was * 4) and the matching cache loop bound | Consequence of the extra Row field — the assertion is upstream’s guard against an accidentally fat Row. |
src/term/cell.rs | pub enum Osc133CellType { None, Prompt, Input, Output } + Cell.cell_type (serde(default)) | Semantic cell tagging from OSC 133 A/B/C/D, written by Term::osc133 and read by TerminalGrid to emit prompt/input/output zones. Replaces the regex pre-parser TUIC used to run over raw output. |
src/grid/tests.rs | Upstream resize tests migrated to ReflowMode; new shrink_reflow_history_only case | Keeps upstream’s reflow coverage green after the signature change and pins the new mode. |
src/term/cell.rs | CellExtra.zerowidth: ArrayVec<char, MAX_ZEROWIDTH_CHARS> (was Vec<char>), push_zerowidth uses try_push, clear_wide assigns ArrayVec::new(); direct arrayvec dep | Backport of upstream ede2ac14 (2026-08-26, master only — 0.26.0 predates it, so this is not yet available from crates.io). The unbounded Vec let a single cell absorb combining marks forever (echo -en a; while true; do echo -en '\xcc\x81'; done), a memory-exhaustion vector any PTY child can reach. Overflow now drops the character instead of allocating. Bound is 9, upstream’s value — no glyph cluster we render needs more, and zerowidth() still hands out a &[char] so no caller changed. This row exists to stop the next rebase silently reverting the fix: delete it only once the version we pin actually contains ede2ac14. arrayvec was already in the lock via vte, so the dep costs no new crate. |
src/grid/row.rs | Safe Row::new using iter::repeat_with(T::default).take(columns).collect() | Backport of upstream d692748d (2026-08-31, master only; 0.26.0 predates it). Removes the unsafe initializer and its hidden nonzero-column requirement. A zero-column row is now empty. Keep this backport until the pinned upstream release includes it. |
src/grid/row.rs | grow reserves exactly the requested additional columns; shrink returns allocation slack in both the retained row and its nonempty tail | Width changes no longer double row capacity or retain the previous wide allocation after shrinking. The cell values and reflow contract are unchanged. |
src/grid/storage.rs | MAX_CACHE_SIZE = 32 (upstream: 1,000) | Bounds spare allocated rows while retaining batched allocation during scrollback growth. At 220 columns and 24 bytes per cell, the spare-cell budget falls from 5,280,000 to 168,960 bytes per grid, before allocator rounding. See the scrollback memory measurement below. |
src/tty/unix.rs | ShellUser::from_env calls getpwuid_r only when USER/HOME/SHELL is missing | Upstream resolves the passwd entry unconditionally on every PTY spawn. TUIC spawns many PTYs; the lookup is skipped when the environment already answers. |
src/term/mod.rs | IL/DL reset the cursor column; ICH/DCH/ECH clear the pending wrap; ED0 spares the cell behind a pending wrap | Three inherited divergences from the DEC contract, found by the ANSI differential harness. They are described one row below; each is pinned by a term::tests case that names the operation. |
src/term/mod.rs | fn scroll_up_overflow(), separate from Handler::scroll_up; DL and SU scroll as ScrollSource::Control | DL and SU remove lines that never reached the bottom, so TUIC gained scrollback rows the agent never printed — an agent TUI that repaints with DL manufactured history. wrapline and advance_line called the same Handler::scroll_up the SU control dispatches to, so routing that one method would have stopped a linefeed feeding history as well; the overflow path gets its own entry point instead. Replaying the retained ANSI captures moves the row-count-grew residual bucket from 205 to 0 (#834-1878). |
The pending wrap and the edit operations
A character written into the last column leaves the cursor there and arms
input_needs_wrap instead of moving past the margin. Which operations resolve
that pending state is not a matter of taste — it decides where the next
character lands and whether the last visible cell survives. Upstream Alacritty
answers three of them differently from DEC and from xterm:
| Operation | Contract | What upstream did |
|---|---|---|
IL (CSI Ps L), DL (CSI Ps M) | return the cursor to the left margin, but only when the line is inside the scroll region; clear the pending wrap either way | left the column stranded mid-row, so the rest of the line painted at the wrong offset |
ICH (CSI Ps @), DCH (CSI Ps P), ECH (CSI Ps X) | edit the cell under the cursor, therefore resolve the pending wrap | carried the wrap past the edit, so the next character jumped to the following row |
ED0 (CSI 0 J) | the erase origin is past the right margin, so the current line keeps its last cell; lines below still clear | erased that cell, dropping a character the user had already seen |
ED1 pending-wrap behavior, EL0, EL1 and EL2 already agreed with the reference
and are deliberately unchanged — clear_line has carried the LineClearMode::Right guard all along.
Do not “fix” them alongside the three rows above; term::tests pins their
current behaviour for exactly that reason.
VTE patch (src-tauri/patches/vte/)
We also patch the vte crate (0.15.0) to extend the Handler trait:
| Method | Purpose |
|---|---|
fn osc133(&mut self, command: char, params: &str) | Shell integration markers (A/B/C/D). Routes OSC 133;X from osc_dispatch. |
fn osc7(&mut self, url: &str) | Current working directory. Routes OSC 7;url from osc_dispatch. |
fn osc7770(&mut self, verb: &str, payload: &str) | TUIC protocol. Routes OSC 7770;verb=payload from osc_dispatch. |
OSC 7770 — TUIC Protocol
In-band signalling via the PTY stream. Never written to the grid (consumed by VTE before rendering).
Format: ESC ] 7770 ; verb=payload BEL or ESC ] 7770 ; verb=payload ST
Verbs:
| Verb | Payload | Effect |
|---|---|---|
state | idle, busy, or awaiting | idle/busy: immediate shell state transition (bypasses silence timer). awaiting: emits a confident Question (sets awaiting_input); busy also clears a prior awaiting. Driven by native agent hooks (see AI Agents → Native Hook Instrumentation). Unknown payloads are ignored. |
suggest | A|B|C (pipe-separated) | Emits ParsedEvent::Suggest — never hits the grid, no conceal needed. |
intent | text or text (Title) | Emits ParsedEvent::Intent with optional tab title. |
Advantages over text-based detection:
- Zero cross-chunk issues (OSC has delimiter-based framing in VTE)
- Zero conceal (never written to grid cells)
- Zero regex (structured parse in VTE dispatcher)
- Zero stale rescan (not in visible buffer)
Upstream API we use directly (no patch needed)
| API | Usage |
|---|---|
Term::new(config, dimensions, event_proxy) | Create terminal grid |
Processor::advance(&mut term, data) | Feed PTY bytes |
term.grid() / term.grid_mut() | Read cell grid, cursor, history |
term.damage() / term.reset_damage() | Dirty-row tracking for incremental serialization |
term.scroll_display(Scroll::Delta) | Viewport scrolling |
term.mode() | Check TermMode flags (ALT_SCREEN, SHOW_CURSOR, kitty keyboard) |
term.cursor_style() | Cursor shape (block/beam/underline) |
term.colors() | Dynamic color palette (OSC 4/10/11/12 overrides) |
term.selection / term.selection_to_string() | Native selection API |
RegexSearch::new(query) + term.regex_search_right() | Native DFA regex search across grid + scrollback |
EventListener trait | Capture bell, title, clipboard, PTY write-back events |
Canonical HTTP text snapshots read a single absolute range from this grid. They must not rebuild a snapshot by appending a separately retained log to the screen: increasing terminal rows can move history back into the viewport and make the two representations overlap.
Clipboard selections use the same absolute grid coordinates. TUICommander joins
rows marked with WRAPLINE, preserves real spaces at wrapped margins, omits
synthetic WIDE_CHAR_SPACER and LEADING_WIDE_CHAR_SPACER cells from text and
text-length accounting, trims unwrapped terminal padding, and then removes only
coherent multi-line Claude space/NBSP ▎ visual gutters. Claude composer
selections remove one leading ❯ and two continuation-margin columns only
when the ordered selection starts at grid column zero with the marker in the
first two cells and the preceding row has no WRAPLINE. Partial body selections
and VT soft-wrap continuation origins remain literal. At every retained
row, cleanup requires known row provenance. A single copy_origin_unknown
flag prevents cleanup even when RI/IL moves the physical row. Eviction or purge
of nonblank predecessor content sets it on the surviving boundary row, including
a blank survivor; removing only blank rows does not set it. Cap trimming,
reprint-tail removal and reflow truncation use the same content-loss rule.
There is no separate latent flag, blank-history exemption or resize promotion.
Full row replacements (ECH, DCH, ICH, EL or ED covering every column from
column zero, and DECALN alignment-screen replacement) share Row::reset, which
clears the flag without changing absolute row counters. Partial edits preserve it.
A composer redrawn on a blank loss boundary can retain its ❯ in copied text
until the row is fully erased. This cosmetic limitation is intentional: literal
content takes priority over speculative cleanup of an ambiguous origin.
ED1 resets every row above the cursor, including row zero when the cursor is on
row one; upstream skips that row with its cursor.line > 1 guard. The cursor row
is erased only through its current column, and rows below remain unchanged.
ED2 resets all visible rows after scrolling occupied content into history. This
clears loss flags that overflow can attach to a fresh blank row with zero scrollback,
while retained history keeps its provenance. ED3 does not erase live content.
DECALN fills live rows with default-background E cells after resetting provenance;
it does not inherit the active erase background. Ordinary printing, including
insert-mode shifts and a sequence that overwrites every cell, preserves unknown
provenance because it has no explicit whole-row replacement boundary.
RI/IL retains the moved row’s flag and literal copy behavior at its new position.
Unknown content stays literal; the same width-evidence rule rejoins wraps
while preserving short typed lines and deeper content indentation. Pasted prompt
glyphs remain content. This normalization is
outside the Alacritty fork and is shared by desktop IPC and HTTP clients.
Atomic MCP agent-submission receipts require no Alacritty patch. The receipt boundary is the raw child-output ring offset captured before Enter; after that offset moves, the current agent screen adapter may classify the already-built grid as working, ready, or interrupted. Neither grid mutation nor local input bookkeeping is itself an acknowledgement.
Notable forks and patches (external)
Zed Editor (zed-industries/alacritty)
Zed maintains branches on their fork with patches not yet upstream:
| Branch | What | Relevance |
|---|---|---|
osc-133 | Semantic cell tagging — cells get Osc133CellType (Prompt/Input/Output) from OSC 133 sequences. Fires Event::Osc133. Requires Zed’s VTE fork (osc-133-2 branch). | None — already implemented in our own patch (term/cell.rs + Term::osc133 + our VTE osc133 hook). The regex pre-parser this was meant to replace no longer exists. |
v0.16-child-exit-patch | exit_status.into_raw() for ChildExit. | Story 1553 needs re-evaluation — implement independently if needed. |
use-zed-vte | Serialize/Deserialize on parser state. | Was prerequisite for OSC 133; check if osc-133 branch still depends on it. |
grid-mut | Makes grid_mut() public (removes #[cfg(test)]). | Low — we already expose grid access via our own patches. |
click-links | URL detection + click-to-open in grid. Ancient branch (pre-0.26 API). | None — we handle link detection in our Canvas renderer. |
cursor-blink | Cursor blink timer via mio::Timer. WIP with debug prints. | None — we handle blink in Canvas/JS. |
cursor-config | Restructures cursor config into cursor.style/hide_when_typing/custom_colors. | None — we don’t use alacritty’s config system. |
scrollback | Added scrollback buffer — already merged into upstream alacritty. | None (already upstream). |
scroll/fix-alt-grid-size | Alt screen gets zero scrollback — already merged upstream. | None (already upstream). |
Update procedure
Checking for upstream updates
# Check latest version on crates.io
cargo search alacritty_terminal
# Compare with our pinned version
grep "alacritty_terminal" src-tauri/Cargo.toml
Rebasing our patch on a new upstream version
-
Download the new version:
cargo download alacritty_terminal@<new_version> -o /tmp/alacritty_newOr copy from
~/.cargo/registry/src/after adding the new version to Cargo.toml. -
Diff our patches against the old upstream:
diff -ru ~/.cargo/registry/src/*/alacritty_terminal-0.26.0/src/term/mod.rs \ src-tauri/patches/alacritty_terminal/src/term/mod.rs -
Apply patches to the new version. Our changes are small and isolated:
resize_reflowinterm/mod.rs— add method, modifyresize()to call itmark_fully_damagedvisibility interm/mod.rs—fn→pub fnnamed_color_to_indexinterm/color.rs— new function, no existing code modified
-
Update
Cargo.tomlversion and thepatches/directory. -
Run tests:
cargo test terminal_grid && cargo test vt_log
Checking Zed’s fork for new patches
# List branches on Zed's fork
gh api repos/zed-industries/alacritty/branches --jq '.[].name'
# Compare a specific branch
# https://github.com/zed-industries/alacritty/compare/master...<branch>
Periodic review cadence
Driven by the alacritty-upstream entry in .claude/scheduled-checks.json (every 20 days). Each run:
- Check crates.io for new alacritty_terminal releases (
cargo search alacritty_terminal). - Review Zed fork branches for new patches relevant to our embedded backend.
- On major issues: If we hit terminal emulation bugs, check if upstream or Zed has a fix before writing our own.
Deliberately not ported (re-evaluate only if the reason changes):
| Upstream | What | Why we skipped it |
|---|---|---|
d692748d (2026-08-31) | Replaces the unsafe hand-rolled Vec fill in grid/row.rs Row::new with iter::repeat_with, dropping the undocumented columns >= 1 limit. | Pure cleanup with no user-visible defect, and it collides with our reflow_wrap patch: the hunk’s closing context is the Row { inner, occ: 0 } literal, which in our fork carries a third field. TUIC never builds a zero-column row, so the unsoundness it fixes is unreachable here. Take it for free at the next version bump instead of hand-merging it now. |
Planned patches (stories)
| Story | Priority | Description | Status |
|---|---|---|---|
| 1552-02ff | P2 | Port Zed OSC 133 semantic cell tagging (requires VTE fork) | Done — cell_type tagging + VTE osc133/osc7 handlers implemented |
| 1550-64b1 | P3 | Move OSC 133 extraction into VTE handler (blocked by 1552) | Done — VTE routes OSC 133 directly to Handler::osc133() |
| — | P2 | OSC 7770 TUIC protocol (state/suggest/intent) | Done — full pipeline from VTE→Event→PTY→ParsedEvent |
| — | P3 | Use cell_type for idle detection (OSC 133 shells) | Pending — next step after TUIC protocol |
| 1553-5e8c | P3 | Port Zed child-exit raw waitpid status | Pending |
Stored terminal marker coordinates
OSC 133 and OSC 7770 event rows use grid.total_scrolled() + cursor row. Capture this origin inside the OSC handler, before later bytes in the same chunk can evict history. Retained history size is not an absolute origin.
Scrollback memory and the single-grid contract
VtLogBuffer owns the session’s only TerminalGrid. That grid backs desktop
frames, HTTP scrollback, copy and search, as well as log extraction. Its
10,000-row history is user-visible history; it is not a duplicate scratch grid
that can be capped independently. The separate 10,000-line LogLine deque serves
mobile pagination. Reducing its grid history would delete terminal scrollback.
The 2026-10-07 six-session measurement uses 220 columns and full history,
including a resize cycle to expose retained row capacity. The workload and native
RSS, vmmap, footprint, heap, and diagnostics measurements are recorded in
story 1575-2c7b. Row cache sizing retains a 32-row allocation batch instead of
allocating one row at a time. This patch changes allocation retention, not the
history limit or transport behavior.
| Metric (six sessions after the width cycle) | Before | After |
|---|---|---|
| RSS (KiB) | 977,584 | 966,176 |
| Physical footprint (bytes, diagnostics) | 1,118,438,912 | 596,067,624 |
| Malloc bytes in use (diagnostics) | 822,958,480 | 454,159,264 |
Heap bytes (heap -s) | 822,623,440 | 453,913,968 |
LogLine bytes (diagnostics estimate) | 14,638,752 | 14,638,752 |
The requested 50% RSS reduction was not reached: RSS fell by 1.17%, while
malloc bytes in use fell by 44.81% and physical footprint by 46.71%. The after
footprint report also classified 355 MB of Malloc Small as reclaimable; RSS
alone does not show the live-allocation reduction. Heap row allocations changed
from approximately 60,294 12 KiB blocks to 60,295 6 KiB blocks. At that measured
6 KiB per 220-column row, the spare-row bound is 6,144,000 bytes per grid before
and 196,608 bytes after. This is a bound calculation, not a separate measurement
of the cache’s contribution to the total reduction.
The largest remaining payload is the retained terminal grid: (10,000 + 24) × 220 × 24 = 52,926,720 nominal cell bytes per session, before inactive-screen
rows, spare rows and allocator rounding. Compact cells or file-backed history
need a separate decision; neither is included in this patch.
Retained wrap edges without reflow
Non-reflow width growth preserves the original cells, including a WRAPLINE
flag at the old margin. Blank columns added to the right do not cancel that
edge. The styled-range and live-frame serializers inspect the full retained
row for the wire wrap bit, even when a dirty frame ships only a partial span
(#2560-b448). This keeps answer gutters on continuation rows without changing
the configured reflow policy, cell positions, or copy semantics. The fork’s
existing independent-row input, CR, and LF clearing paths remove wrap flags
across the retained row, not only at the current margin. Repainting a former
continuation therefore cannot join unrelated output to the preceding answer.
Resize repaint reconciliation
Every primary-screen resize records the source/target column widths, grid sequence, original viewport-top row index and the viewport’s own row snapshot (#1407-1ab2). Live VtLogBuffer width changes use full reflow so visible logical lines retain their complete content and soft-wrap continuity. History-only reflow truncates visible cells on shrink and leaves natural wrap flags at the old column on growth, breaking session-output redaction. The cursor-addressed Ink redraw remains a separate replacement domain for the reconciliation below.
The first explicit full viewport erase can replace an old displaced row only when that complete physical row occurs in the new replacement. A two-row viewport anchor does not license removing other old rows.
Full reflow can move the original viewport prefix into history even when the height is unchanged. A unique complete two-row source prefix locates that owned range in the reflowed coordinates; incomplete or ambiguous matches retain the rows. Each old row still needs complete replacement proof.
Blank screen-prefix rows created by proven suppression retain explicit provenance. A write, erase, scroll or alternate-screen switch touching them invalidates that provenance, even if the visible text remains blank. Before the next full reflow, only still-owned synthetic blanks are removed without adding history. Program-authored separators are never included.
A fresh redraw prefix is suppressed only when its entire text equals a contiguous suffix of an immutable history snapshot ending immediately above the owned viewport. The snapshot includes at most four original viewport heights, capped at 256 rows. Only its first row may start inside a source logical line, with a fragment of at least 16 visible characters; all following content must match exactly through the anchor. Short fragments, non-suffix matches, gaps or missing anchors preserve the entire prefix. Trailing historical blank separators remain in the comparison: a redraw omitting that gap provides no replay proof. Leading blank rows owned by the viewport remain in its replacement domain, so the prefix boundary excludes their replacement. This path never deletes old history. A genuinely new prefix identical to that complete retained suffix is indistinguishable from a replay: its older copy remains, but event multiplicity is lost. This bounded residual is explicit and regression-tested.
Height growth records the exact history coordinates pulled into the new viewport,
so their new redraw is retained. Matching preserves intra-line whitespace and
uses the shared greedy-width rule for Ink’s hard-line word wrapping. The bounded
snapshot retains recorded source widths for unchanged hard rows across subsequent
width changes; native VT soft wraps are joined before comparison, and blank
paragraph separators remain explicit. Fresh
visible duplicates are blanked without shifting child row coordinates.
Alternate screens and ordinary edits provide no replacement authority.
The recorded streaming and idle PTY captures and resize byte timelines live in
crates/tuic-terminal/src/fixtures/claude-resize-1407/.
Resize-owned physical fragments retain their complete logical-record identity from the post-resize WRAPLINE boundaries, before a redraw can erase a continuation still on screen. Replacement proof must match that complete record; a substring in a different replaced record never licenses deleting an omitted history record.
History-anchored viewport scrolling
History-anchored scrolling uses TerminalGrid::screen_origin() (total_scrolled) and scroll_to_anchor; it resolves the all-time row to a display offset under the VT lock. The existing fork origin and history cap provide the coordinate; no new fork patch is required.
Soft-wrap extraction contract
TerminalGrid uses the existing alacritty WRAPLINE flag for text and styled-log extraction. Wrapped rows retain their trailing cells, including a real space in the final column. Non-wrapped rows still trim unused terminal padding. No fork patch is needed: the grid already carries the required boundary. The log wire format exposes this flag as wrapped for mobile output.
VT100-to-PWA Protocol
How TUICommander transforms raw PTY output into structured, styled terminal content for the mobile Progressive Web App.
Architecture Overview
PTY (raw bytes)
│
▼
VtLogBuffer (TerminalGrid — the patched alacritty_terminal fork)
├── scrollback → LogLine[] (styled spans)
├── screen_rows → String[] (plain text)
└── prompt_input_text → String (user-typed, no ghost text)
│
▼
HTTP / WebSocket handlers
├── trim_screen_chrome() → remove agent UI footer
├── is_separator_line() → detect decorated separators
└── SessionState → accumulated parsed events
│
▼
Frontend (SolidJS)
├── OutputView → log + screen rendering, auto-scroll
├── CommandInput → bidirectional PTY ↔ textarea sync
└── SlashMenuOverlay → arrow navigation, prefill
1. VtLogBuffer — VT Parsing Engine
File: src-tauri/crates/tuic-terminal/src/vt_log.rs (buffer) · src-tauri/crates/tuic-terminal/src/terminal_grid.rs (grid)
There is no vt100 crate. VtLogBuffer wraps a TerminalGrid, TUIC’s patched
alacritty_terminal fork — see alacritty-integration.md.
Every parsing, changed-row and scrollback query below is delegated to that grid.
Configuration
| Parameter | Value | Notes |
|---|---|---|
| Scrollback | 10,000 lines (GRID_SCROLLBACK) | Grid history, sized so it cannot fill between two process() calls |
| Log capacity | 10,000 lines (VT_LOG_BUFFER_CAPACITY) | Ring buffer of finalized LogLines |
| Default size | 24 rows × 80 cols | Resizable via resize() |
#![allow(unused)]
fn main() {
VtLogBuffer::new(rows, cols, capacity)
// Grid created with: TerminalGrid::new(rows, cols, GRID_SCROLLBACK)
}
process(data: &[u8]) -> Vec<ChangedRow> — Core Pipeline
Called for every PTY read chunk. Steps:
- Detect a screen switch (primary ↔ alternate). On a switch,
grid.clear_prev_rows()forces the next diff to report every non-empty row. - Feed bytes to the grid —
grid.process(data)parses and returns the changed rows itself;VtLogBufferkeeps noprev_rowsof its own. - Extract the scrollback delta, primary screen only:
total_sb = self.grid.scrollback_count(); delta = total_sb.saturating_sub(self.scrollback_read); new_lines = self.grid.read_scrollback_log_lines(delta); - Mark agent chrome on the new lines (
mark_agent_chrome). - Stamp
colswith the current PTY width and push to the log ring buffer. - Return the changed rows (for the output parser).
Changed rows are reported for both screens, so parsers still see status lines and
intent tokens from alternate-screen agents (Claude Code / Ink). Log capture is skipped
on the alternate screen and for inline TUIs (mouse reporting on the primary screen, e.g.
grok --no-alt-screen) — but scrollback_read is still advanced so the cursor stays
in sync.
Scrollback Extraction
The grid accumulates history when lines scroll off the top of the primary screen (a real line feed at the bottom), but NOT when cursor-based TUI redraws repaint in place.
Key invariant: scrollback_read is monotonically increasing. Each process() call
reads only the delta since the last call. resize() re-syncs it to
grid.primary_screen_origin() — the primary coordinate space — so a resize taken
while an alt-screen app is active cannot strand the durable-log cursor. The re-sync
leaves the rows that the resize itself moved from the viewport into history
(last_resize_displaced_rows) unread, so the next process() logs them. Output
written while the terminal is narrow is logged like any other output (#2726-7833).
TerminalGrid::extract_log_line(&self, line: Line) -> LogLine — Styled Cell Extraction
Converts one grid line into a LogLine with colored spans:
#![allow(unused)]
fn main() {
struct LogLine {
spans: Vec<LogSpan>,
cols: u16, // PTY width at capture time — lets the frontend spot narrow-captured lines
chrome: bool, // Agent UI chrome; never serialized, readers skip it
}
struct LogSpan {
text: String,
fg: Option<LogColor>, // Idx(u8) or Rgb(r,g,b)
bg: Option<LogColor>,
bold: bool,
italic: bool,
underline: bool,
}
}
Algorithm:
- Iterate columns left-to-right
- Skip wide-char continuation cells
- Group consecutive cells with identical attributes into one span
- Flush span when attributes change
- Trim trailing empty/whitespace-only spans with default styling
mark_agent_chrome flags lines from find_scrollback_chrome_cutoff down as
chrome: true; it does not delete them. A misclassification therefore hides text
rather than destroying it.
screen_rows() — Current Screen Content
Returns the visible terminal content as plain text strings, from the grid’s cached
snapshot (grid.screen_text_rows()). screen_rows_ref() borrows the same snapshot so
a caller already holding the lock avoids the clone.
prompt_input_text() — User Input Extraction
Extracts what the user has typed at the prompt, excluding ghost/suggestion text.
Algorithm:
- Scan rows bottom-to-top for prompt character (
❯,>,>) - Walk cells left-to-right after the prompt char
- Collect cell contents while
!cell.dim() - Stop at first dim cell — that’s ghost/autocomplete text
- Return trimmed result
This is critical: Claude Code shows inline suggestions in dim text (e.g., ❯ /wiz:status where /wiz:status is grey). Without the dim check, the suggestion text would appear in the PWA textarea.
mark_agent_chrome() — Log Line Filtering
Flags agent UI chrome (prompt box, status bar, separator) on captured log lines.
- Uses
find_scrollback_chrome_cutoff()— anchors only on a bare prompt row (is_agent_prompt_row), never on a standalone separator - Extends cutoff upward past separator, empty and task-list lines
- Sets
LogLine::chrome; the line stays in the buffer andlines_since_owned()skips it. Nothing is deleted from history, so a misclassification hides text rather than destroying it — the failure mode that made the mobile log show paragraphs starting mid-sentence.
2. HTTP/WS Session Handlers
File: src-tauri/src/mcp_http/session.rs
GET /sessions/:id/output?format=log
Initial data fetch before WebSocket connects.
Response:
{
"lines": [LogLine, ...],
"total_lines": 1234,
"offset": 1134,
"screen": ["row1", "row2", ...],
"input_line": "user typed text"
}
total_linesserves as the offset cursor for WS catch-upoffsetis the absolute start of the returned window. Clients must use it instead oftotal_lines - lines.length: chrome lines occupy offset slots without being returned, so the subtraction lands inside the window already held and replays those lines on scroll-upscreenhas chrome trimmed viatrim_screen_chrome()input_linefromprompt_input_text()(dim text excluded). Only agent prompts (❯,›,>) are recognized — a plain shell prompt ($/#/%/➜) yieldsnull, so the textarea gets no PTY-driven reconciliation for shells.
WS /sessions/:id/stream?format=log&offset=N
Real-time bidirectional stream. Two concurrent tasks:
Server → Client (polling task)
Runs in a tokio::select! loop with two branches:
Branch 1: 200ms timer — polls VtLogBuffer for changes:
#![allow(unused)]
fn main() {
let (lines, new_offset) = buf.lines_since_owned(offset);
let trim = trim_screen_chrome(buf.screen_rows());
let input_line = buf.prompt_input_text();
}
Change detection via hash:
#![allow(unused)]
fn main() {
let mut hasher = DefaultHasher::new();
screen.hash(&mut hasher);
input_line.hash(&mut hasher);
let screen_hash = hasher.finish();
let screen_changed = screen_hash != prev_screen_hash;
}
Frame sent only when !lines.is_empty() || screen_changed:
{
"type": "log",
"offset": 100,
"total_lines": 142,
"lines": [...],
"screen": [...],
"input_line": "text"
}
offsetis the start position oflines(where the delta begins).total_linesis the post-read monotonic cursor (== offsetwhen no new lines). The client stores it and passes it back as?offset=on reconnect, so catch-up resumes from the last consumed line instead of replaying the whole scrollback from the mount offset. The catch-up frame on connect carriestotal_linestoo. (Without this, every WS reconnect — frequent on mobile: background/foreground, lock, network change — re-injected the entire session scrollback, duplicating it.)
Branch 2: event bus — forwards SessionState on parsed events:
{
"type": "state",
"state": { "awaiting_input": true, "agent_type": "claude-code", ... }
}
Client → Server (input passthrough)
WebSocket Text/Binary messages are written directly to the PTY.
trim_screen_chrome() — Screen Footer Removal
Removes Claude Code’s TUI footer (separator, status bar, permissions line, prompt).
Scan window: Last 15 rows from content end (handles Claude Code’s ~12-row footer).
Two anchor strategies:
-
Separator line —
is_separator_line():#![allow(unused)] fn main() { fn is_separator_line(s: &str) -> bool { // 4+ consecutive: ─ ━ ═ — ╌ ╍ // Tolerates decorated separators: // "──────── ■■■ Medium /model ─" } } -
Prompt line — starts with
❯,>,>
Takes the higher anchor (closer to content), extends upward past empty/separator lines, truncates.
write_to_session() — Slash Mode Tracking
When users type / from the mobile PWA, the backend tracks this to enable slash menu detection in the output parser:
#![allow(unused)]
fn main() {
if data == "/" || data.starts_with('/') {
slash_mode.store(true);
} else if data.contains('\r') || data.contains('\n') {
slash_mode.store(false);
}
}
The output parser checks slash_mode before scanning screen rows for slash command menus.
3. Frontend Transport
File: src/transport.ts
subscribePty(sessionId, onData, onExit, options)
Auto-detects Tauri (native) vs browser (HTTP/WS) mode.
Browser mode connects a WebSocket:
ws(s)://host/sessions/{sessionId}/stream?format=log&offset={logOffset}
Options:
interface SubscribePtyOptions {
format?: "log";
logOffset?: number;
onLogLines?: (lines: unknown[]) => void;
onScreenRows?: (rows: string[]) => void;
onInputLine?: (text: string | null) => void;
onStateChange?: (state: Record<string, unknown>) => void;
}
Frame dispatch:
| Frame type | Callback | Data |
|---|---|---|
"log" | onLogLines, onScreenRows, onInputLine | Styled lines, screen rows, prompt input. total_lines is tracked as the reconnect cursor. |
"state" | onStateChange | SessionState snapshot |
"exit" / "closed" | onExit | Session ended |
On reconnect the WebSocket reopens with ?offset=<last total_lines> (log mode) so the server’s catch-up only sends lines committed since the last one the client received. The raw (format omitted) path uses total_written byte offsets for the same purpose.
Returns a PtySubscription: callable to dispose, plus pause() / resume(). A backgrounded PWA renders nothing, so OutputView pauses on visibilitychange and the socket is dropped. The cursor above is what makes that safe — resume() reopens from it, so a hide/show cycle neither duplicates nor drops scrollback, and onExit is not raised for a close the client asked for.
rpc("write_pty", { sessionId, data })
Maps to POST /sessions/{sessionId}/write with body { data: "..." }.
Used for all PTY input: typed characters, escape sequences (arrow keys), control characters (Ctrl-U, Ctrl-C).
4. Mobile Components
OutputView
File: src/mobile/components/OutputView.tsx
Renders combined log history + current screen with auto-scroll management.
Text wrapping strategy: reflowDisplayLines() joins prose rows that the agent hard-wrapped before they reached the phone. It estimates the agent’s wrap width from the widest row in a contiguous prose run; LogLine.cols provides a lower-bound gate because Claude may wrap near 80 columns inside a much wider PTY. Short lines, paragraph breaks, lists, indented code, and box drawing stay separate. The browser then wraps the joined paragraph once at the phone width. Normal text uses pre-wrap; consecutive box-drawing lines stay in scrollable tableBlock containers with white-space: pre and overflow-x: auto. The rendering helpers live in src/mobile/utils/logLine.ts.
Initialization:
- HTTP fetch:
GET /sessions/{id}/output?format=log - WebSocket connect with
logOffsetfrom step 1 (avoids duplicate lines)
Data model:
displayedLines = [...logLines, ...screenRows] // combined
.filter(searchQuery) // optional filter
logLines: Accumulated scrollback (max 500, ring buffer)screenRows: Current terminal screen (replaced each update)
Auto-scroll suppression:
- Track
userScrolledUpvia scroll event listener - “At bottom” = within 80px of scroll end
scrollToBottom(force?): skips if user scrolled up, unlessforce=true- Initial load and session exit force-scroll
CommandInput — Delta Sync (textarea is source of truth)
File: src/mobile/components/CommandInput.tsx
Helpers: src/mobile/components/syncGuards.ts
The textarea is the source of truth; the PTY is a write-only sink fed character deltas as the user types. Echoes from the PTY are accepted back only under strict conditions, so a laggy link can’t clobber what the user sees.
Direction 2: Textarea → PTY (syncDelta)
On every input event, syncDelta(newText) streams a minimal end-anchored
delta computed by computeInputDelta(syncedText, newText):
// keep longest common prefix, backspace the divergent tail from the end,
// then type the new tail
function computeInputDelta(oldText, newText) {
let prefix = 0;
const max = Math.min(oldText.length, newText.length);
while (prefix < max && oldText[prefix] === newText[prefix]) prefix++;
return "\x7f".repeat(oldText.length - prefix) + newText.slice(prefix);
}
Append (no backspaces) and truncate (no retype) fall out as special cases. A mid-line edit backspaces only the divergent tail instead of nuking and retyping the whole line. This is correct as long as the remote cursor is at end-of-line (true while the user only appends/backspaces and hasn’t moved the readline cursor via arrow keys).
Why minimal, not full-nuke: the old “complex edit” branch sent
\x7f×oldLen + newText on any mid-line change. That keystroke storm flickered readline and corrupted the line when a write dropped/reordered over a laggy mobile link — the “typing fa casino” symptom. Minimal deltas send the fewest keystrokes and keep the textarea consistent with the screen.
Direction 1: PTY → Textarea (guarded echo)
Source: ptyInputLine prop (from WebSocket input_line). An echo is accepted
into the textarea only when both gates pass (syncGuards.ts):
- Post-send guard — within
POST_SEND_GUARD_MS(500ms) of Enter, every echo is ignored (suppresses the ghost flash of the just-sent command). - Strict-extension rule —
isSupersetEcho(echo, syncedText): accept only if the echo strictly extends what we’ve sent (tab completion / autocomplete). Prompt redraws, lagging echoes, and history-nav replacements are ignored so the textarea can’t be clobbered.
For a plain shell, ptyInputLine is null (see prompt_input_text — it
only recognizes agent prompts), so there is no PTY-driven reconciliation; the
authoritative display of the shell line is the screen rendered by OutputView.
Send (Enter)
The typed text is already in the PTY via live delta sync, so Enter just writes
\r (and clears the textarea + arms the post-send guard).
Mid-line editing
Moving the readline cursor is done with the ← / → keys in TerminalKeybar
(\x1b[D / \x1b[C), not by moving the textarea caret. When arrows move the
remote cursor, the textarea’s end-anchored model can diverge from the screen —
the screen stays authoritative.
SlashMenuOverlay
File: src/mobile/components/SlashMenuOverlay.tsx
Displays slash command menu items detected from the terminal.
Item source: sessionState.slash_menu_items — populated by the output parser when it detects a slash command menu on screen (gated by slash_mode).
Arrow navigation:
┌─────────────────────────┐
│ /help Get help... │
│ /compact Compact... │
│ /review Review code │
│ ⏫ ▲ ▼ ⏬ │ ← arrow bar
└─────────────────────────┘
- Single arrow (▲/▼): sends one
\x1b[Aor\x1b[B - Page arrow (⏫/⏬): sends
items.lengtharrows (scrolls one page) - Anti-zoom:
touch-action: manipulationon all buttons
Selection flow:
- User taps item →
onSelect(command)callback - CommandInput replaces the slash fragment, updates the textarea, and sends its text delta to the PTY
- User reviews, optionally edits, and submits; CommandInput waits for the last write and the agent’s Enter gap before sending Enter
SessionDetailScreen — Orchestration
File: src/mobile/screens/SessionDetailScreen.tsx
Wires everything together:
OutputView ──onStateChange──→ wsState signal
──onInputLine───→ ptyInputLine signal
│
▼
CommandInput ←── SlashMenuOverlay selection
State merging: WebSocket state is authoritative when present; 3s poll state fills gaps.
5. SessionState Accumulation
File: src-tauri/src/state.rs — apply_event_to_session_state()
The output parser emits PtyParsed events. These accumulate into SessionState:
| Event type | Fields updated |
|---|---|
question | awaiting_input = true, question_text |
user-input | awaiting_input = false, clear slash menu, capture last_prompt |
rate-limit | rate_limited = true, retry_after_ms |
usage-limit | usage_limit_pct |
api-error | last_error |
status-line | Clear rate-limit/error/suggest/slash, set current_task |
intent | agent_intent |
suggest | suggested_actions |
slash-menu | slash_menu_items |
progress | progress (0-100, None on state=0) |
tool-activity | current_tool (newest live native tool name, None when no call is live) |
Lifecycle:
- Created on
SessionCreated - Removed on
SessionClosed is_busycleared onPtyExit
6. Key Escape Sequences
| Sequence | Meaning | Usage |
|---|---|---|
\x15 | Ctrl-U | Clear input line (readline) |
\x7f | DEL/Backspace | Delete char before cursor |
\r | Carriage Return | Submit input |
\x1b[A | Arrow Up | Navigate menu / history |
\x1b[B | Arrow Down | Navigate menu / history |
\x1b[C | Arrow Right | Move readline cursor right (mid-line edit) |
\x1b[D | Arrow Left | Move readline cursor left (mid-line edit) |
\x1b[3~ | Delete | Delete char after cursor |
\x03 | Ctrl-C | Interrupt |
\x04 | Ctrl-D | EOF / exit |
7. Debugging
Check backend logs
GET /logs?source=terminal&limit=20
Inspect raw WS frames
In browser DevTools → Network → WS → filter by /stream:
"type":"log"frames show line count, screen rows, input_line"type":"state"frames show accumulated session state
Verify input_line extraction
GET /sessions/{id}/output?format=log
Response includes "input_line" — should show only user-typed text (no ghost/dim suggestions).
Verify separator detection
If agent chrome leaks through, check trim_screen_chrome() scan window (15 rows) and is_separator_line() threshold (4+ consecutive box-drawing chars).
Components
Catalog workflow authoring
WorkflowDesigner preserves the legacy editor and lazily mounts NeutralDesigner
through Catalog authoring. Both views retain unsaved state while switching.
neutralClient.ts owns the proposed workflow_neutral_action wire types;
useNeutralDraft reads project catalog/draft metadata on repository revisions,
without replacing unsaved definitions. CatalogInspector and SchemaFields
render configuration and ports from ActivityDescriptor, including custom scripts.
MappingFields edits the Rust data-source representation. NeutralGraphEditor
edits neutral control nodes and outcome links. Structured conditions, scopes and
subflows use the complete JSON editor, with backend validation before applying.
NeutralInspection requests pure preview or retained inspection independently
from publication. Preview distinguishes present, unknown and absent sample data and shows pure
effect preparation. Retained inspection groups path events, outputs, waits,
failures, effect uncertainty and subflow boundaries, with cursor paging. TriggerBindings selects exact publications, fetches installed source schemas and previews normalized payload mappings. Save stores a disabled binding; enable requires a fresh preview and explicit acknowledgement of returned overlapping binding revisions. Mutation errors re-read durable metadata. Authoring uses the shared desktop/HTTP action contract. Catalog errors remain visible while independent saved drafts load; a successful refresh clears them. Native activities require the installed backend catalog/provider.
The selected plan has an Edit plan control in the Plans column. It edits title and document/link with Save and Cancel. Save sends only changed fields using the revision captured when editing started. A conflict keeps the draft and requires Cancel and reopening Edit plan to load the latest version; an active-coordinator refusal keeps the source draft and displays the backend remedy. Successful saves refresh the plan list.
Repository Settings uses scoped cards and responsive labelled rows. The existing repository update callbacks and export command remain authoritative. Reset is presented with its repository scope and consequences rather than as an unscoped footer action.
Agents Settings uses page and section primitives while its machine context still owns agent configuration writes. Per-agent lists and nested run/environment editors use scoped responsive styles; drafts, validation, and save handlers are unchanged.
Workspace Settings pages use SettingPageHeader, SectionCard, and opt-in row fields. WorkspaceTabs.module.css scopes shortcut action-first layout without changing capture handlers or global Settings styles.
Application Settings tabs opt into SettingFields row presentation. The default stacked layout remains available to unchanged consumers. Row controls use SettingRow for label and hint association; slider input and commit events remain separate.
ui/Select, ui/Input and ui/Textarea forward native form attributes and events.
ui/SegmentedControl provides a keyboard-accessible single-choice view switch.
ui/Button provides primary, secondary, ghost and danger actions in default or compact size.
ui/Switch, ui/Slider and ui/ColorInput forward native checkbox, range and colour input attributes/events. Switch and ColorInput wrap decorative visuals but forward refs, IDs and labels to the native input; ColorInput also accepts selected and decorative children.
All shared form controls use ui/FormControls.module.css; screen CSS owns layout only. Settings field wrappers retain labels, hints and owner callbacks.
Compose the shared toolbar density on header, tab, filter and toolbar rows: 22px height and 6px horizontal padding. Form density stays 36px with 8px padding. Nested configuration menus compose form to reset inherited toolbar tokens. Both densities retain 44px touch targets. CSS module compositions can export multiple class names; DOM selectors must join them as a compound selector, not a descendant selector.
Native list-row/card buttons use the explicit data-control-layout marker described in the style guide.
The native-select guard in src/__tests__/nativeSelect.test.ts rejects new raw
selects outside ui/ and requires the explicit pending-migration list to shrink.
Tasks/detail/TasksDetail is the core work-item detail surface. Its props are
provider, reference, optional visible, onClose and onItemChange.
It renders schema-driven fields, sanitized Markdown, all declared comment
variants, cursor pagination, a comment composer and provider transition actions.
The shell must pass visibility to pause the default 60-second refresh timer.
Read-only enum fields resolve provider option IDs to their schema labels, falling back to the stored value when an option is unknown. Editing still sends the option ID.
useTasksDetail fences responses by item generation and serializes mutations.
Committed mutations remain accepted if reloading opened comment pages fails;
the view reports the history error and Retry reloads those pages.
TaskMarkdown preserves reader disclosure state across provider refreshes.
Shell mounting and provider registration are owned by the Tasks integration.
Tasks/create/TasksCreate is the core work-item create form. Its props are
provider, onCreated(detail) and optional onCancel. It renders the item-type
picker and per-type fields with SettingField and SettingMultiSelect.
useTasksCreate fences schema responses by generation and submits once;
createDraft converts control values to tagged field values.
TaskCreateUser renders static choices and optional provider user searches, with
request cancellation and stale-response fencing. Free labels keep raw text until
collection; required-field messages sit beside their inputs.
Slice F exposes start_graph {target:{type:story|plan,id},expected_revision?,definition_id,definition_revision,request_id,limits?} through the existing owning-daemon service. Story starts require the current native revision and pin the selected publication; the request ID is bound to its payload. Omitted limits use Rust defaults. Plan dispatch remains unavailable in this build and its start control says so. The workflow action=run MCP entry uses an inline schema generated from RunAction and the public RunCommand variants; it returns the same scoped snapshots and cursor-ordered events as IPC/HTTP. Run history shows pinned activations, decisions/evidence, repair counters, pause targets and complete event payloads across pages. Graph recovery uses resume_graph {execution_id,activation_id,resolution} after answering pending input; pause and cancel use the existing sequence-fenced commands. Legacy runs offer inspection and cancellation in the UI. No new persistence or client scheduler is added.
All components are SolidJS functional components in src/components/.
Tasks/roadmap/TasksRoadmap consumes a data-only WorkItemProvider, optional host
start/target date field IDs and an item-opening callback. It reuses createTasksQuery
and the list’s virtual rows for undated items; RoadmapTimeline virtualizes dated rows.
Month/quarter controls navigate local calendar geometry from calendar.ts. The default
field mapping uses the first two date descriptors in provider order. Missing, invalid
or reversed dates stay in the side list. Shell mounting is a separate integration step.
MobileViewBanner offers browser clients a link to /mobile. On tablets it remains visible, even if previously dismissed on a phone, so users who chose desktop in mobile Settings can return. Switching clears the device-local desktop preference; native Tauri never renders the banner.
Component Tree
App.tsx (central orchestrator)
├── Toolbar/ # Window drag region, repo/branch display
├── Sidebar/ # Repository tree with branches
│ ├── GroupSection # Collapsible repo group with color + drag-reorder
│ ├── RepoSection # Single repo entry with branches
│ ├── ParkedReposPopover # Popover to recall parked (hidden) repos
│ ├── CiRing # CI status ring per branch
│ ├── StatusBadge # Git status badge (clean/dirty/conflict)
│ └── PrDetailPopover/ # PR details popup (CI, reviews, labels)
├── main
│ ├── TabBar/ # Terminal tabs with drag-to-reorder
│ ├── Terminal/ # Native terminal renderer (never unmounted)
│ ├── TerminalArea/ # Terminal + split pane layout (up to 6 panes)
│ ├── SuggestOverlay/ # suggest: follow-up action chips
│ ├── GitPanel/ # Git panel (6 tabs)
│ │ ├── ChangesTab # Staged/unstaged file list with stage/unstage/discard
│ │ ├── LogTab # Commit log with expandable diffs
│ │ ├── StashesTab # Stash list with apply/pop/drop/show
│ │ ├── BranchesTab # Branch CRUD, prefix folding, search, checkout
│ │ ├── BlameTab # Line-by-line git blame viewer
│ │ ├── HistoryTab # Per-file commit history
│ │ ├── CommitGraph # Visual commit graph with lane assignments
│ │ └── SyncRow # Push/pull/fetch action bar
│ ├── DiffTab/ # Individual file diff tab (with Cmd+F search)
│ │ └── AllChangesView # All-files scroll view (scroll mode): Uncommitted, Branch vs base, Commit / range
│ ├── PrDiffTab/ # PR diff viewer tab
│ ├── CodeEditorPanel/ # CodeMirror 6 code editor tab
│ ├── MarkdownPanel/ # Markdown file browser
│ │ └── ContentRenderer # Markdown to HTML (DOMPurify), interactive checkboxes, tweak highlights
│ ├── HtmlPreviewTab/ # Multi-format preview tab (HTML, PDF, images, video, audio, text)
│ ├── MarkdownTab/ # Markdown tab and detached document window (checkboxes, tweak comments, search)
│ ├── IdeasPanel/ # Ideas panel with edit, send, delete
│ ├── FileBrowserPanel/ # File tree browser with content search
│ │ └── TreeNode # Recursive tree node (lazy-loaded)
│ ├── PluginPanel/ # Plugin HTML panel (sandboxed iframe)
│ ├── ClaudeUsageDashboard/ # Claude API usage dashboard (SolidJS)
│ ├── CodexUsageDashboard/ # Codex App Server usage dashboard
│ ├── GrokUsageDashboard/ # Grok ACP billing dashboard
│ ├── ErrorLogPanel/ # Application error log viewer
│ └── StatusBar/ # Status messages, agent badge, toggles
│ └── ZoomIndicator # Font size display
├── TabBar/ # Ordering, overflow, drag/drop, and menus
│ └── TabViews # Shared terminal, diff, Markdown, and editor tab views
├── SettingsPanel/ # Settings overlay; nav grouped by task (GLOBAL_TAB_GROUPS)
│ ├── ExpertSetting # ExpertSetting / ExpertSection / ExpertModeSwitch
│ ├── DictationSettings # Voice page
│ ├── tabs/GeneralTab # Language, context bar, confirmations, power management, updates, experimental, TUIC CLI, Code Intelligence, ego executable, IDE, custom launchers
│ ├── tabs/AppearanceTab # Tabs, repository groups, layout, UI legend
│ ├── tabs/NotificationsTab # Sound and notification prefs
│ ├── tabs/TerminalTab # Theme, shell, font, cursor, clipboard, blocks
│ ├── tabs/KeyboardShortcutsTab # Rebindable keyboard shortcuts, global hotkey
│ ├── tabs/GitHubTab # Git & GitHub: OAuth login, PR/issue display, repo + worktree defaults
│ ├── tabs/AgentsTab # Agent detection, run configs, Claude Usage toggle
│ ├── tabs/AiChatTab # default model, providers
│ ├── tabs/SmartPromptsTab # Smart Prompts library
│ ├── tabs/RemoteMachinesTab # Remote Machines page (wraps services/RemoteMachinesPanel)
│ ├── tabs/PluginsTab # Plugin management, logs
│ ├── tabs/services/ # LocalMcpPanel + UpstreamMcpPanel (MCP page), RemoteAccessPanel, RemoteMachinesPanel
│ ├── tabs/RepoScriptsTab # Per-repo scripts
│ └── tabs/RepoWorktreeTab # Per-repo worktree options
├── HelpPanel/ # Keyboard shortcuts documentation
├── TaskQueuePanel/ # Agent task queue
├── PromptOverlay/ # Agent prompt interception
├── PromptDrawer/ # Prompt library management
├── CommandPalette/ # Cmd+P / browser-toolbar palette with transport-safe actions
├── ActivityDashboard/ # Compact inline or detached terminal activity list
├── BranchSwitcher/ # Quick branch switcher (held-key overlay)
├── BranchPopover/ # Branch selection popover
├── TipOfTheDay/ # Startup tip notification
├── DictationToast/ # Dictation recording/transcribing indicator, hands-free meter, reply controls and the spoken-replies toggle
├── ConfirmDialog/ # Reusable in-app confirmation dialog
├── RenameBranchDialog/ # Branch rename dialog
├── CreateWorktreeDialog/ # Worktree creation dialog
├── PostMergeCleanupDialog/ # Post-merge cleanup (switch base, pull, delete)
├── PromptDialog/ # Text input prompt dialog
├── RunCommandDialog/ # Configure terminal commands
├── WorktreeManager/ # Overlay panel for worktree management
├── MergePostActionDialog/ # Dialog for post-merge actions (keep/delete branch)
├── ContextMenu/ # Shared right-click menu (all panels). `separator:true` on an item = trailing divider AFTER it; empty-label item = standalone divider; a trailing separator on the LAST item is suppressed
└── IdeLauncher/ # Open repository in an IDE or a TUICommander shell
The new-tab AgentLaunchMenu opts into the large ContextMenu variant (44 px rows, --font-lg labels), supplies AgentIcon/terminal glyphs and separates agent/config names. Other context menus keep their normal sizing.
Application Controllers
Application lifecycles live in focused hooks under src/hooks/; App.tsx
composes them and owns the top-level layout. Git operations retain the
useGitOperations facade for callers, with stateful domains implemented under
src/hooks/git/:
- repository refresh and stale-result suppression;
- serialized branch selection;
- terminal/worktree ownership and OSC 7 reassignment;
- worktree creation, setup, recovery, and removal;
- merge, autofix, and conflict-assistance workflows.
Each coordinator owns its timers, queues, generations, or locks. These are behavioral boundaries rather than generic service wrappers.
PanelOrchestrator loads the AI Chat panel after its first inline opening and
keeps it mounted when hidden. The detached AI Chat adapter loads the same panel
when its window opens. Neither path loads its markdown renderer before the
desktop terminal view.
The detached Markdown document adapter likewise loads MarkdownTab only when
its window renders, so its renderer stays outside the initial desktop graph.
SessionControls lists ego’s durable session/list results by updatedAt and
loads a picked session through ACP. useAcpChat restores the saved root-to-session
binding from app config after a fresh document opens.
The control bar summarizes the current model and mode, with pending values while
the selected attachment has not published options. Its session settings
button opens a shared-style modal with one labeled select and description per
ACP select config option. Choices and displayed values come from the selected
session’s latest attachment snapshot. Flat choices use ACP value fields;
grouped choices use group and nested options. Rejected changes show an error
in the modal.
The panel draws open chat tabs from aiChatTabs; each tab selects one ACP
session on the shared default connection or its saved custom-launch connection.
Selecting a restored tab connects and attaches or replays it without a prompt;
the panel shows connecting status, or the reason and Retry after a refusal.
Concurrent selections share a pending default connection and only the latest
selection changes focus. A detached window reads the saved tab list.
aiChatDraft keeps unsent text and
staged images per tab while the document is mounted.
ACP session title updates rename the panel header and picker entry. The usage
footer shows context-window occupancy and the reported cumulative cost.
Untitled sessions use their first prompt or latest activity time in tabs and the picker,
with the session ID in the tooltip. Small single-choice elicitation
forms use direct answer buttons and Cancel. Prompt failures and empty completed
turns appear in the transcript.
Transcript displays one provider-retry status line. useAcpChat supplies its
live countdown, clamped at “retrying now”, through a panel-owned timer. User-message
Copy buttons use a single unwrapped line, including in the full app shell.
Transcript interprets complete ACP answer text as it streams: it hides the
connection acknowledgement, shows a declared intent as status, and offers
bracketed suggest: items as prompt buttons. Markdown examples stay literal.
Messages, tool output and code blocks have copy actions. Chat preserves fenced-code padding inside highlighted answers and places Copy in a normal-flow row above the code, so the control neither clips nor covers wrapped text. The transcript has
text selection and find/select-all/clear shortcuts. Find selects phrases across
inline Markdown within each block, skips collapsed disclosure bodies, and closes
on Escape from the input or navigation buttons. Local file paths use the
terminal’s backend path resolver and file opener. Web links use the shared
external URL opener. A detached AI Chat window sends resolved file links to
the main window’s same file opener, where the editor and viewer tabs live.
Tool-call dots pulse only while a call is pending or in progress. The
transcript projection settles unfinished calls when their turn ends, so a
missing final tool update cannot leave an old dot animating.
AI Chat context-overflow recovery reuses the manual compact action, opens the continuation and resubmits the original prompt once. Progress uses existing informational notices; publication, load and repeated-overflow failures remain visible.
The status-bar AI Chat toggle uses the shared CountBadge to show pending ACP
questions while the panel is hidden.
The composer stages pasted images in its shared draft and sends ACP image
blocks through acpClient.prompt. It checks promptImage and the shared 10 MiB cap
before reading clipboard bytes; each preview can be removed before sending.
The mobile HTTP prompt route allows base64 expansion of that cap; images refused
by the draft show their size and the limit in the composer.
During a turn it offers Queue beside Stop, lists the host-owned queued
prompts, and can remove any queued ID. The list follows ACP snapshots and
events, so another window or a phone sees the same order and cancellations.
Mobile Screens (src/mobile/)
useSessionChatView offers the existing header CLI / Chat switch for Claude, Grok, Codex and ego through the same supported-adapter predicate as desktop. chat_view_snapshot owns transcript binding; a refusal returns to CLI with its reason. The shared transcript does not replace the mounted terminal, composer, keyboard bar or native question controls.
SessionDetailScreen replaces its state with each complete WebSocket or polled
session snapshot, except polls whose last_activity_ms is older than the applied
state. Equal timestamps remain replaceable; this field is not a protocol revision.
Omitted optional fields mean cleared state, not missing deltas.
A fresh poll can therefore retire a stale socket’s agent identity and question,
return Chat to CLI, and route the composer to the remaining shell after agent exit.
Mobile connection presentation follows useSessions, not the independent version poll. Recovery increments a root revision consumed by Files, Chat settings, Activity, Settings and Progress discovery. Failed Files reads retry without replacing unsaved edits. During an outage, tab views stay mounted but hidden so contradictory empty/setup errors do not replace the shared connection banner. Mobile Chat hydrates settings quietly and does not infer missing ego configuration from an unsuccessful read.
OpenMarkdownMenu adds a scrollable Markdown section to session overflow.
It reads repository-scoped desktop file metadata and refetches on tab changes,
repository changes and SSE resynchronization. Selecting an entry keeps the
session mounted and opens FilesScreen with the entry’s original checkout root.
OutputView keeps a 500-line live tail while following. While the reader is
scrolled up or touching the output, it retains the loaded rows instead of
evicting the content being read. Older-history pages extend that reading window.
The next log update after following resumes restores the 500-line tail.
The backend preserves the full Claude /resume modal in both the initial HTTP
screen and log-WebSocket frames, including session rows and no-match results;
the mobile view does not reconstruct the picker from transcript text.
Terminal ego selectors open the existing ChoicePromptOverlay when a new native question arrives or a waiting session is opened. The header question action can close and reopen it; equivalent polling snapshots and highlight changes preserve a manual close. Full titles and option labels, including descriptions, wrap within its scrollable overlay. A selection_required composer refusal reopens the current question without sending the refused draft. Free-text cards still open explicitly; the terminal keeps its full height. The composer uses the backend navigation selection mode and its existing in-flight guard to submit only once.
The session composer has a 44 px paperclip in its existing row. It uploads a
selected file and stages @path without Enter; the upload chip floats above
the row. Mobile AI Chat uses the shared composer to stage images as ACP image
blocks and other files as ACP resource links with a readable path in text.
The mobile PWA opens on Sessions. Its bottom tabs are Sessions, Chat (only with ego configured),
Files, Progress, and Activity; Settings opens from the app-bar overflow.
The session detail screen loads after a session is selected (or opened from a
deep link), keeping its terminal and attachment controls out of the Sessions
entry graph.
SessionsScreen shares one debounced status accessor per session between its card badge
and the Working, Idle and Awaiting header counts. Accessors are keyed by session id
so the Working hold survives replacement snapshots. Sub-tasks counts as Working.
Finished and other badge states
are excluded from these totals; exited sessions leave the live snapshot. The counts
cover the full snapshot even while search is open. Working and Idle are read-only.
SessionsScreen filters its existing session snapshot locally while search is open;
the backend list and card order remain unchanged. Closing search clears the query.
Waiting sessions sort above idle agents and shells without changing order within each
group. The new-session sheet chooses an agent and repository, then opens the new
session after spawn_agent succeeds. The question counter opens the first waiting
session from the AWAITING tile, without a duplicate app-bar count; each banner shows its session name and repository.
Each session card uses separate buttons to open or kill the session. Both have
accessible names, and the kill button has a 44 px hit area. The list reserves
space below its last card so the floating new-session button cannot cover it.
SessionDetailScreen uses one 56 px header row with the agent logo and state dot,
display name, repository/branch and elapsed state, tasks count, and overflow.
The name, tasks, and session-scoped Progress open temporary sheets over the
terminal; Commands, Files, output search, Ideas, usage, copy ID, and terminate
remain reachable in overflow. No fixed intent/task rows reduce terminal space.
MobileApp measures visualViewport.height and offsetTop into the fixed shell’s
CSS variables. Resize, viewport scroll, pageshow, foreground visibilitychange
and document resume share one animation-frame measurement. Lifecycle listeners
are removed on unmount. This prevents stale geometry after a restore without a
viewport event; it does not establish the cause of the reported iPhone grey screen.
MobileApp keeps SessionDetailScreen mounted while its overflow opens the shared
FilesScreen at the session’s worktree or containing registered repository.
The session’s output stream and command draft stay alive while Files is shown;
the regular Files bottom tab still starts at the repository picker.
Repository paths preserve their trailing segment and reveal the full path on
long press. The tree sorts hidden folders after normal entries and uses the
backend’s recursive search_files route for nested matches. File actions share
the title row; the editor fills the remaining height and wraps source lines.
Markdown references in output use the desktop path resolver and open the Files
viewer only within a registered repository. External paths show a toast with the
resolved path. HTTP(S) output links open outside the PWA.
Markdown images in the Files viewer resolve relative to their source file and
load through the authenticated /fs/markdown-image route.
Desktop Markdown list comment actions use a shared gutter outside the outermost list, independent of item depth. Paragraph and heading actions retain their block-relative position.
QueuedPrompts reads the host PTY FIFO and shows only in the mobile CLI view; the chat view shows each queued prompt inline with Send now and Cancel. A 404 read
without a pending count or accepted local enqueue leaves the optional queue view
hidden, so older hosts do not add an error to every empty session. Other read
failures, and 404 responses with known pending work, remain visible and retryable.
FilesScreen receives the existing mobile session list and the originating session ID from MobileApp. Its Markdown review controls prefer the document opener from published desktop metadata, resolve the stable TUIC identity to a live repository agent, and preserve an explicit user choice. Without an opener, the originating mobile session remains the default; an unavailable opener falls back to the first eligible repository agent. The controls call enqueue_agent_command over HTTP. Desktop and mobile use buildMarkdownReviewPrompt for the same path, checkbox, and tweak-comment contract. Both views retain the pre-save review baseline across local saves and invalidate it on external reload. Before sending, markdown_review_changed_lines checks the captured content against disk and computes current-file ranges in Rust; the shared one-sentence prompt requests those ranges with their enclosing sections. Missing, unchanged, or stale snapshots retain whole-file reading. Successful sends acknowledge only the captured review window; failed sends retain it and later edits remain sendable.
The embedded Progress list clamps long messages to four lines until More is
pressed. Activity presents local 24-hour times, minute durations, and singular
block counts. Mobile Settings shows app/server versions and a persistent Dark
or Light choice using the desktop theme tokens. Its server-side mobile_theme
preference is independent of the desktop terminal theme.
The detail keybar and composer each keep their previous total height while their
controls use 44 px touch targets. The keybar slash button inserts / at the
composer selection through the same input path as typing. It preserves the surrounding draft, syncs the same
PTY delta, and shows the agent parser menu with navigation. Picking a command
updates the input; closing the menu clears the input through the same sync path.
A vanished session keeps its output visible but disables both input controls.
The mobile composer owns its draft. PTY prompt snapshots do not create a draft or extend it on their own: a hands-free paste can be visible before Enter, and a queued agent message can look like prompt input. A Tab request from the composer or keybar accepts one strict extension of a nonempty local draft. Explicit keybar Up/Down accepts one history replacement after its PTY write is acknowledged, including an empty line, and updates the edit delta baseline. When a managed agent awaits an answer without parsed choices, keybar Tab and Up/Down still go to the PTY so an open picker can navigate. These keys do not import history into the local answer draft. Typing, sending, Escape, or a failed write cancels the request. A history response arriving before the HTTP acknowledgement is dropped, causing a missed recall. Because snapshots have no causal request ID, an unrelated delayed snapshot after the acknowledgement can still be mistaken for history.
Core Components
PluginPanel (PluginPanel/)
URL tabs and inline plugin panels mount their sandboxed iframe only while their tab is visible. Hiding a tab, switching repositories or pane tabs, or covering split panes with an orphan tab removes the iframe from the DOM. Showing it again loads the page anew, so iframe scroll, focus and JavaScript state do not persist. This prevents hidden page timers from blocking terminal input on the shared WebContent main thread. Native tuic://edit and tuic://open tabs use their own components and are unaffected.
Terminal (Terminal/)
Native terminal renderer with full PTY integration.
Responsibilities:
- Creates and manages CanvasTerminal instance backed by
alacritty_terminal - Renders grid frames to HTML canvas for GPU-accelerated display
- Subscribes to PTY output events
- Handles terminal resize (with debouncing)
- Applies font, theme, and zoom settings
- Link detection for clickable URLs
- Selection management for copy operations
- Terminal search retains match highlights across unchanged or colour-only grid frames; changed text invalidates affected rows before the backend refresh completes.
CanvasTerminal keeps frame decode, reconciliation, scheduling, and paint in
one imperative hot path. Sibling controllers own selection/search state, link
verification cancellation and caches, fractional scroll/cache handoff, and DOM
input-listener cleanup. These controllers do not use reactive state.
Key behavior: Terminals are never unmounted — they stay in the DOM when switching tabs. Only visibility is toggled. This preserves terminal state (scroll position, content, active processes).
Sidebar (Sidebar/)
Session rows use the shared ContextMenu and writeClipboard utility to copy their PTY session ID, child PID, or alias. PID and alias come from the owning row of an on-demand list_active_sessions snapshot, shared with GET /sessions; they are checked again before copying. Unknown PID and absent alias entries are hidden, including exited or suspended sessions. Both desktop and mobile copy confirmation uses the toast store.
Repository tree with branch management. Touch branch rows reveal their existing actions in a full-height tray after a horizontal left swipe. A Sidebar-owned row identity permits one open tray across repositories; vertical scrolling and mouse interactions keep their existing behavior.
Branch rows keep the status icon separate from the always-visible agents disclosure button. Clicking status selects the workspace; the chevron toggles its agents.
Features:
- Expandable/collapsible repository entries
- Icon-only collapsed mode
- Branch list with active branch highlight
- CI ring indicator per branch (from githubStore)
- PR status badge
- Nested sub-agent rows use a muted parent robot tag, while the actionable GitHub badge keeps the accent color
- Compact diff stats (additions/deletions) with exact tooltip counts
- Workspace lifecycle badge from the backend (
Dirty,Merged, orUnknown), plus a compact unmerged-commits mark, keyed by workspace id;DirtyandUnknownexpose their meaning and removal consequence in a WebView-compatible hover/focus tooltip. Branch-name tooltips include each diagnostic once and omit removal warnings for main checkouts - Context menu (right-click) for repo/branch operations
- Resizable width via drag handle (300-500px); branch hover/focus actions overlay the row end, and the list clips horizontal overflow without allowing focus to shift row starts
- Keyboard redirect to active terminal
Shared PR presentation (PrStateBadge) and merge eligibility are leaf modules
below the sidebar views. RepoSection, GitHubPanel, PrSection, and
RemoteOnlyPrPopover do not import back through one another.
TabBar (TabBar/)
Terminal tab management.
Features:
- Tabs filtered to active branch only
- Drag-to-reorder tabs
- Tab rename (double-click)
- Close button per tab
- Activity indicator (dot) for background terminals
- Awaiting input indicator (question/error icons)
- Context menu: Close, Close Others, Close to Right
- Context menu, debug builds only (
isPerfDebug()): Capture Session — arms the raw PTY capture tap on that session so a state-detection bug can be recorded as it happens. Seedocs/frontend/utilities.md→ptyCapture.ts.
PromptDrawer (PromptDrawer/)
Creates, edits, and executes custom and built-in Smart Prompts. A normal click or
keyboard Enter follows the prompt’s autoExecute value. Double-click and
Insert & Run explicitly submit once; Insert explicitly keeps the resolved
text editable. The drawer delays a single pointer click until the double-click
window closes so one gesture cannot trigger both delivery paths.
SettingsPanel (SettingsPanel/)
Settings overlay. The nav groups the global pages by task
(GLOBAL_TAB_GROUPS in SettingsPanel.tsx); each group renders as a static
label row above its pages, and the configured repositories follow under
Repositories.
Pages:
- Application
- General (
GeneralTab) — Language, agent context bar, confirmations, power management, updates, Experimental Features, TUIC CLI, Code Intelligence, ego executable (always shown), default IDE, custom launchers - Appearance (
AppearanceTab) — Tabs, repository groups, layout reset, UI legend - Notifications (
NotificationsTab) — Sound and notification preferences
- General (
- Workspace
- Terminal (
TerminalTab) — Theme, shell, font, font size and weight, cursor style, clipboard, command blocks, scrollback reflow - Keyboard Shortcuts (
KeyboardShortcutsTab) — Rebindable shortcuts (auto-populated fromactionRegistry.ts) and the global hotkey. The Help panel reuses the same editor - Git & GitHub (
GitHubTab) — GitHub OAuth login (Device Flow), token management, diagnostics, PR and issue display, repository and worktree defaults, additional accounts, repository bindings
- Terminal (
- AI
- Agents (
AgentsTab) — Agent detection, run configurations, Claude Usage toggle - AI Chat (
AiChatTab) — default model, provider list. Hidden whileisAiChatEnabled()is false. The ego executable is on General - Voice (
DictationSettings) — see below - Smart Prompts (
SmartPromptsTab)
- Agents (
- Integrations
- MCP (
LocalMcpPanel+UpstreamMcpPanel) — HTTP API server status, TUIC tools, upstream MCP servers - Remote Access (
RemoteAccessPanel) — Remote access, Tailscale HTTPS, QR/connect URL, cloud relay; local IP discovery failures stay inline with retry while the remaining controls stay available - Remote Machines (
RemoteMachinesTab) —tuic-remoteconnections - Plugins (
PluginsTab) — Plugin management, enable/disable, log viewer
- MCP (
- Repositories
- Repo Scripts — Setup and run scripts, plus the optional per-repository Dev Server URL for Design Mode
- Repo Worktree — Base branch, copy ignored/untracked files
Expert mode (ExpertSetting.tsx, stores/settingsExpert.ts). The header
carries ExpertModeSwitch, which flips the persisted UI pref
settings_expert_mode. <ExpertSetting configKey value> hides its children in
basic mode while value equals the default at configKey, as returned by
get_config_defaults. It shows them in expert mode, when the value is
modified, when a search result revealed that configKey during the current
Settings open, or while the defaults are unknown. All of this is one rule,
settingsExpertStore.isVisible.
The rule is sticky for an edited control: a native input or change event
from any child of an ExpertSetting calls settingsExpertStore.pin(configKey),
and a pinned control stays shown for the current open, so setting it back to
the default does not make it disappear under the cursor.
settingsExpertStore.open(), which SettingsPanel calls each time Settings
opens, clears the pins and the search reveals. Pinning happens on the edit, not
when isVisible sees a non-default value: a tab’s pre-load placeholder (a value
that differs from the default until its config loads) is not an edit and must
still hide. The listeners sit in the capture phase on the resolved top-level
child elements — no wrapper element, which would break the .group + .group
and :last-child rules — so the pin lands before the control’s own handler
changes the value. A control that changes its value without input/change
(a button) does not pin.
<ExpertSection> hides a section, heading included, when all of its
ExpertSettings are hidden. No page uses it today, because every section keeps
at least one basic control.
The search index marks labels inside an ExpertSetting with expert: true and
the configKey. SettingsSearch shows an Expert badge on such a result
(data-expert-badge). Selecting it calls settingsExpertStore.reveal(configKey)
before SettingsPanel scrolls to the label, because a hidden control has
nothing to scroll to.
One index entry carries one configKey, so one label must not cover two expert
controls. On Git & GitHub, Copy ignored files and Copy untracked files
are therefore two SettingToggle rows, each in its own ExpertSetting, and not
one group under a shared label.
DictationSettings (SettingsPanel/DictationSettings.tsx)
Hands-free listening is a standard toggle beside it (also in mobile Settings); off arms a replies-only conversation. The DictationToast carries a speaker button (aria-pressed) that flips the same spoken-replies setting while recording or while a conversation is armed. Spoken replies is a standard toggle, also available in the mobile conversation
header and mobile Settings. It stays visible in browser mode and saves the
backend device preference; it does not stop microphone dictation.
The Voice page (nav key dictation). One <h3> per section. Speech-to-text and
text-to-speech are separate sections, and each keeps its own advanced controls
at its bottom — there is deliberately no shared “Advanced” section:
The Rust dictation crate split does not change these controls or their transport calls.
- Dictation — enable, hotkey, long-press threshold, auto-send
- Speech recognition (
SpeechRecognition) — input device (desktop only), Whisper model, language, then voice tuning: the test recording and both speech gates - Auto-Corrections
- Hands-free conversation (
HandsFreeControls) - Spoken replies (
SpeechSetup)
SpeechRecognition, HandsFreeControls and SpeechSetup each open with their
own heading: the settings search index reads source order, so a sub-component
without one would file its labels under the wrong section.
The two voice sections:
- Spoken replies (
SpeechSetup) — the runtime and language downloads fromget_speech_assets(voices excluded), each with Download / Repair / Cancel / delete. Then, while the language ships a voice:- a voice
<select>with the ids fromget_speech_voices(only voices that can speak now), and a Listen button that previews the selected voice throughpreviewSpeechVoiceand shows a refusal inline; VoiceLibrary, the Voices list of the language, in three groups: Installed (downloaded catalogue voices), Downloadable (the others, with Download and progress, collapsed by default in a<details>whose<summary>shows the count; both reuseSpeechAssetRow) and Yours (the user’s voice files, each with a delete button, and Add voice file…, a hidden.safetensorsfile input; a refused file shows its reason inline);- two
SettingSliders: Voice volume (-30 to -12 dB) and Levelling (Off to Strong, stored as 0–1). Each shows the value while it is dragged and saves only on release (onCommit). It offers no language control: the spoken language is the Whisper language, and a second control would be a second source that disagrees with it (seedocs/backend/dictation.md→ “The language of the conversation”). A voice row is Active when it is the selected voice; only a language row is active for the language.
- a voice
- Hands-free conversation (
HandsFreeControls) — a terminal-or-AI-Chat target picker, Start / Stop (accent Start, distinct Stop), a coloured Running/Stopped indicator, the polled phase, the activation phrase, the hold-back slider, the earcons toggle, the “notify model” toggle and, while that is on, the start notice textarea. Its placeholder isgetDefaultHandsFreeStartNotice()— Rust owns the built-in text, the frontend keeps no copy. The slider edits the saved delay; the polled status gives the effective delay, which is at least five seconds when an activation phrase is configured.
Nothing here arms on mount. Opening this panel must never open the
microphone, and neither must starting the app: onMount only starts a 500 ms
status poll, cleared in onCleanup. Push-to-talk (the hotkey) and continuous
mode (Start) are rendered as the two distinct mechanisms they are — there is no
“mode” config field behind them.
Since 832-e730 the tab renders in browser mode and HandsFreeControls still
has no browser branch — this time because none is needed. armHandsFree opens
the tab’s own audio socket and passes its own owner id, so the same control runs
a conversation on either transport. Two groups stay behind isTauri():
- the global hotkey and its long-press slider, which a browser cannot register; and
- the microphone device list, which enumerates the devices of the machine running TUICommander. A browser user picking from that list would be choosing hardware in another building — the browser’s own device picker is the platform’s, not ours.
SpeechSetup and HandsFreeControls are defined at the bottom of the file,
after VoiceTuning, because extractSettings builds the settings search index
from source order — their entries in settingsSearchIndex.ts follow in the same
order.
PrDetailPopover (PrDetailPopover/)
Rich PR detail popup shown on hover/click in sidebar.
Displays:
- PR title, number, author
- State (open, merged, closed, draft)
- Merge readiness (ready, conflicts, behind, blocked)
- Review decision (approved, changes requested, review required)
- CI check summary (passed/failed/pending ring)
- Individual CI check details
- Labels with computed colors
- Line change counts (+additions/-deletions)
- Timestamps (created, updated)
StatusBar (StatusBar/)
Status messages, agent badge, CWD display, ticker, and panel toggles.
Layout (left to right):
-
ZoomIndicator — font size display
-
Status info — notification text with pendulum ticker for overflow
-
CWD — current working directory (click to copy, shortened with
~/) The remaining items form one right-aligned group. Free space is before this group, not between the cwd and an absorbed usage widget. -
Agent badge — unified agent + plugin usage display (see below); provider recovery replaces it while active
-
Ticker — plugin messages in priority order, then creation order; side by side when they fit, with overflow rotating in the last slot. Absorbed usage is excluded before rotation.
-
Offline machines — disconnected machines with registered repositories
-
GitHub badges — PR badge + CI badge with popover
-
Toggle buttons — Notes (with badge count), File Browser, Markdown, Diff, Dictation mic
The right group uses at most 75% of the bar. The ticker uses its measured natural pool width, capped at 45% of the viewport. At narrow widths, status labels truncate and the ticker rotates before fixed controls can overlap.
Agent Badge — display priority:
The agent badge appears when the active terminal has a recognized agent type. It shows a single integrated element with the agent icon and the most relevant info, following this priority cascade:
| Priority | Condition | Display | Example |
|---|---|---|---|
| 1 (highest) | PTY rate limit detected | Icon + warning + countdown | ⚠ 3m 20s |
| 2 | Usage API available (Claude only) | Icon + usage percentages | 5h: 6% · 7d: 69% |
| 3 | PTY usage limit parsed | Icon + percentage + limit type | 82% daily |
| 4 (lowest) | No usage data | Icon + agent name | claude |
Data sources:
- Rate limit (priority 1): Detected by Rust output parser via regex on PTY output (e.g. “429”, “rate limit”, “too many requests”). Stored in
rateLimitStore. Applies to all agents. - Usage API (priority 2): Polled every 5 min from Claude’s API by
claudeUsage.ts. Posted tostatusBarTickerwith pluginId"claude-usage". Claude Code only. When active, the separate ticker message is suppressed to avoid duplication. - PTY usage limit (priority 3): Parsed from terminal output by the output parser (e.g. Claude’s
[C1 S30 K26]status line). Stored on the terminal entry asusageLimit. Applies to all agents that emit usage info. - Agent name (priority 4): Fallback — just shows the agent type name.
Usage blink threshold: API ticker priorities and PTY percentages apply the critical animation only from 96% usage. Usage from 70% to below 96% stays warning-coloured. Dashboard critical colours remain at 90%.
Usage throttling: Claude usage HTTP 429 is displayed immediately as rate-limited, retry HH:MM (host local time) over IPC and HTTP. The backend records a bounded account-profile cooldown instead of sleeping inside the request.
Ticker integration: usagePlacement in features/agentUsage.ts is the one rule for the shared usage message. When its sessionId is the active agent session, the badge shows it (priority 2); otherwise it shows nowhere. TickerArea excludes every message that rule does not place in the ticker. formatAgentUsage is the one text formatter (weekly percent, monthly remaining, “ -4d“ reset suffix), and the writer skips the store when the text, label and priority are unchanged. The badge shows no tool name. Other ticker messages (from plugins, etc.) display normally.
Pendulum ticker: When the status info text overflows its container, a CSS pendulum animation scrolls the text back and forth at ~50px/s. Clicking the text dismisses the notification until the message changes.
Ideas badge: The Ideas toggle button shows a count badge (accent-colored) with the number of ideas visible for the current repo filter. Uses ideasStore.filteredCount().
PR lifecycle in StatusBar: CLOSED PRs are never shown. MERGED PRs are shown with a 5-minute activity-based grace period (accumulated user activity tracked by userActivityStore). OPEN PRs are shown as-is.
IdeasPanel (IdeasPanel/)
Ideas panel with per-repo filtering and terminal integration.
Features:
- Add, edit, delete notes
- Send note text to active terminal (marks note as “used”)
- Notes filtered by active repo (global notes always visible)
- Reassign notes to different projects via dropdown
- Count badge in panel header and in the StatusBar toggle button
- Used notes shown with a checkmark and dimmed styling
StoriesDialog (StoriesDialog/)
Choose All plans in the Plans column to show stories from every non-archived plan together in List or Kanban. Each story row and card shows its plan title. Status, type and archived-story filters apply to the combined view. Archived plans switches the combined view to archived plans only, as it does for a single-plan view. Select a specific plan to filter back and enable plan editing or story creation. Story detail, status actions, workflow starts and run history use the selected story’s own plan; dependency choices stay inside that plan.
Archive and restore controls send the selected record revision to the shared native service. Independent Archived plans and Archived stories toggles select archived records; Rust projects list ids and Kanban columns. Archived details stay readable, but work actions and new-story creation under archived plans are unavailable until restoration. Ownership refusals use the existing error banner.
QA stories have a separate status label, QA-only filter and Kanban column. Criteria remain editable in QA. QA passed sends approval; QA failed returns development work to In progress. These controls use the shared revision-checked story service.
Story details show the persisted origin, plan step, revision and claiming session. A live terminal name appears beside the stable session ID; closed or unavailable terminals retain the ID. Transition history shows committed commands, revisions and actors in backend order, with Refresh history and explicit loading, error and empty states. New story offers Native or Plan step origin; a plan-step story requires a step label.
The project-scoped plan and story dialog creates manual plans and stories, presents criteria and dependency status, and sends revision-checked actions through the shared IPC/HTTP transport. It uses wire status types generated from Rust with python3 scripts/generate-story-types.py (--check detects drift). The selected plan state stays visible beside cancellation counts while a story is selected. It renders the Rust plan_view projection, including transitive abandoned dependency labels and the WontFix count or all-cancelled label. Only a direct WontFix dependency on a Backlog story offers the human Remove action; the backend decides whether the dependent becomes Ready. Visible labels use t() and English catalog entries, the controls use style-guide tokens and button variants, and the close button takes focus when the dialog opens.
The Plans and Stories toolbar button (StoriesButton.tsx) widens into a pill while the project has an active plan: active plans, stories in progress and a done/total bar, with the breakdown in its tooltip and aria-label. Counts come from the Rust summary story action. Nothing signals story changes, so it re-reads on repo change, window focus or visibility, dialog close, and every 60 s while the window is visible; a failed call leaves the plain icon.
The dialog probes story_capabilities before loading. A missing capability receives the restart message; action failures retain their own error details.
ProgressDialog (ProgressDialog/)
Embedded mobile mode has a two-row project/Filters and List/Flow header, status-labelled cards and an entry detail action. Its default list excludes messages/delegations with backend progressOnly; desktop layout is unchanged.
The whole Progress UI: one newest-first list for the active PTY by default,
with a selector for other PTYs and the repository aggregate. It has a divider
marking where the last visit ended, and a blocked-only
checkbox. Blocked entries are red, host-written intent entries are muted, and
each row can be deleted. The list opens with at most 100 entries; Load older
appends another cursor page. The control is disabled while a read is pending.
The header uses its project selector as the project label when available.
Without a selector, including on desktop, it shows a project subtitle instead.
There is no export — Progress is a thing you glance at, so it is a dialog and not a
panel that competes with the terminal for width.
The toolbar bell always includes Terminal Progress, regardless of unread count.
The command palette and Cmd/Ctrl+Shift+P open the same dialog.
On macOS, clicking a native done or blocked notification opens this dialog
for the notification’s project and source terminal, even if another project is active.
Opening asks the shared journal once, for the selected PTY or project. The old panel fanned out across every registered repository and answered with one red unavailable block per repository that no longer existed; the dialog shows one project and one failure line.
Each PTY and the aggregate has a separate divider, frozen while that view is open. Switching views loads the new scope’s mark; closing records every visited scope without moving a line under the reader’s cursor.
A List | Flow toggle switches to ProgressFlow.tsx, a sequence diagram of
the same journal: one column per participant (terminal or Claude subagent), one
row per event, arrows for delegations, returns and messages, and intents as
muted notes. Every row is the same CSS grid, so lifelines, headers and arrow
ends line up without measurement. Journal text expands in place; a subagent
arrow fetches its full text through progressStore.fetchFlowDetail. The
component only renders what progress_flow returns.
embedded drops the overlay and the floating box so the mobile PWA’s Progress
tab can host the same component full-bleed; a whole bottom tab is already the
modal surface a dialog would create. On phone widths, its header wraps the
title, project and terminal selectors, view toggle, and blocked filter so each
control remains visible without horizontal scrolling.
ConfirmDialog (ConfirmDialog/)
Reusable in-app confirmation dialog that replaces native Tauri ask() dialogs (which render as light-mode macOS system sheets). Uses shared dialog.module.css for consistent dark-theme styling.
Props: visible, title, message, confirmLabel, cancelLabel, kind (warning/info/error), onClose, onConfirm.
Keyboard: Enter confirms, Escape cancels.
ClaudeUsageDashboard (ClaudeUsageDashboard/)
Native SolidJS component (not a plugin) showing Claude API usage data. Displayed as a tab in the markdown/editor area. Features rate bucket gauges, per-model token breakdown, daily usage chart, and project stats. Clicking the Claude Usage ticker opens it for that terminal session’s credential profile. The rate-limit API follows CLAUDE_CONFIG_DIR; transcript statistics still use the default Claude projects directory.
Quota presentation is fed by providerQuotaStore: the initial get_provider_quotas response includes each key’s session_ids. The store subscribes to quota and binding events before it applies that response. Session changes select cached entries; they do not start a provider read. A native agent badge accepts only its own registry owner and provider; an ego badge accepts only the ego owner. A previous agent’s binding on the same PTY cannot supply quota text or a dashboard action while reconciliation is pending. An explicit refresh cannot store a different subscription’s response under the requested key. Claude plan and extra-usage sections use the optional typed detail response, while quota bars use the registry windows. The local session statistics and timeline still refresh separately.
CodexUsageDashboard (CodexUsageDashboard/)
Native dashboard for the official Codex App Server account snapshot. Shows rate windows, reset times, daily token buckets, and the lifetime metrics that the documented surface actually supplies. Unsupported legacy metrics are omitted.
Codex quota bars and typed provider detail come from the same registry store. Badge clicks pass the opening session to all three native usage dashboards. A reused dashboard tab updates that session, and an absent or mismatched binding never falls back to another account. Codex quota bars and Grok billing detail select the same session binding as the badge. A Codex dashboard opened without a session selects an owner only when its bound subscription is unambiguous; a Grok dashboard opened without a session retains the host billing path. Local usage statistics keep their separate refresh path.
GrokUsageDashboard (GrokUsageDashboard/)
Native dashboard for Grok Build’s _x.ai/billing ACP extension. Shows the
current billing-period percentage, subscription tier, period end, on-demand
used/cap amounts, and prepaid balance. It shares the usage-dashboard visual
system and never turns an absent provider value into zero.
UI Primitives (components/ui/)
| Component | Description |
|---|---|
AgentIcon | Agent identity SVG with consistent sizing and inherited color; ego uses a rounded Greek small epsilon (ε, U+03B5) inside a ring, independent of provider and installed fonts |
CiRing | SVG circular CI status indicator with proportional segments |
DiffViewer | Syntax-highlighted unified diff renderer |
Dropdown | Reusable dropdown select component |
ContentRenderer | Safe markdown-to-HTML rendering with DOMPurify sanitization (including raw form and image-map removal), with escaped preformatted text on parser failure, interactive checkboxes, tweak highlights, and click interception for every rendered link; Mermaid 12 diagrams retain the dark theme and strict security setting while using upstream layout and appearance defaults; MarkdownTab sends local href resolution to Rust |
PanelResizeHandle | Draggable resize handle for panel boundaries |
PromptOption | Agent prompt multiple-choice option |
StatusBadge | Git status badges (clean/dirty/conflict) |
ZoomIndicator | Terminal font size indicator |
Shared Components (components/shared/)
| Component | Description |
|---|---|
ColorPickerDialog | Color selection dialog (used by repo groups) |
ColorSwatchPicker | Preset color swatch grid |
KeyComboCapture | Keyboard shortcut capture input (for keybinding editor) |
SearchBar | Reusable search bar with regex/case-sensitive toggles |
Panel Toggle States
| Panel | Toggle Shortcut | Store |
|---|---|---|
| Sidebar | Cmd+B | uiStore.toggleSidebar() |
| Git Panel | Cmd+Shift+D | uiStore.toggleGitPanel() |
| Markdown Panel | Cmd+Shift+M | uiStore.toggleMarkdownPanel() |
| Ideas Panel | Cmd+Alt+N | uiStore.toggleIdeasPanel() |
| File Browser | Cmd+E | uiStore.toggleFileBrowserPanel() |
| Settings | Cmd+, | Local state in App.tsx |
| Help | Cmd+? | Local state in App.tsx |
| Prompt Library | Cmd+Shift+K | promptLibraryStore.toggleDrawer() |
| Task Queue | — | Local state in App.tsx |
| Command Palette | Cmd+P; browser toolbar button | commandPaletteStore.toggle(); browser mode filters to explicitly supported web/HTTP actions |
| Activity Dashboard | — | activityDashboardStore.toggle() |
| Project Progress | Command palette / bell | progressStore.toggle() |
| Worktree Manager | Cmd+Shift+W | worktreeManagerStore.toggle() |
Dashboard row navigation uses the shared navigateToTerminal path. It opens the
manual Global Workspace for parked sessions before activating their content,
leaves that workspace for a repository session that is not a member, and focuses
its existing pane group when present. Undocked terminals use the full-page overlay
without changing the split layout being left. Existing tab/session bindings are
preserved. Notification and detached-dashboard navigation use the same path.
Activity Dashboard uses a 500px inline overlay and the same compact row layout
in its detached window. On startup and reopening, saved detached geometry cannot
make the Activity window larger than its 550×650 default; smaller saved sizes
remain in effect. SubAgentIcon supplies the shared 11px robot marker
for both the dashboard and sidebar; only its tooltip/accessible name contains
the parent name. The session list supplies each parent’s live tuic_session
when its PTY ID differs from that identity.
Private secret form
SecretForm is a standalone entry (secret-form.html, src/secretForm.tsx),
mounted in a separate backend-created WebView or a capability-gated browser.
It imports no App stores, debug globals or logging handlers. Sensitive input
values stay in input elements until submit, then are cleared and unmounted
before IPC/HTTP entry. Only requested fields render; approval instead shows
exact argv/names/directory and optional template consent. SSO and phone URLs share
selectable HTTP(S) links, copy actions and explicit system-browser opening;
non-web SSO display values remain selectable plain text.
SettingsPanel/tabs/TelegramTab renders the shared Telegram setup controls in desktop Settings and, when opened, in mobile SettingsScreen. All validation, pairing, private-file writes and polling ownership remain in Rust. The registered agent is read-only; agents opt in through MCP rather than a destination selector.
Pending agent commands in Terminal drain once when both the command and an idle shell session are available. Parsed events, shell-state synchronization and WebSocket snapshots feed this same readiness check, including late launch preparation.
Closed refusal turns show one plain-text card with the agent’s existing ACP refusal text. A refusal without text shows a generic refusal message.
Browser HTML and Markdown previews load local images only from open repositories and their linked worktrees, through the authenticated repository image route. Images outside those roots show “Image unavailable: outside open repositories.” Desktop asset loading is unchanged.
StoriesDialog run history embeds RunIncidents. It renders backend-owned cause and recovery suggestion text with run/attempt/story/session/task identities. It refreshes on run cursor changes and explicit operator refresh, ignores stale responses after selection changes, and discloses unavailable evidence. It does not execute recovery.
Rich RepoSection metadata shows PR and worktree count chips only for positive counts, with reactive store updates.
In rich mode, sessions idle for more than two hours fold into an expandable count. Backend activity timestamps determine age; busy sessions, awaiting input, unread output, selected rows and parents of visible children stay visible. Expanding preserves row order. Compact mode does not fold idle sessions.
Rich working agent rows reserve two clamped intent lines. Idle, awaiting-input and error rows stay on one line with status dots; their full intent, task or prompt remains in the tooltip. Compact rows keep their one-line layout.
Rich navigation keeps compact typography and padding. Branch identity and facts share one line, with names truncated and full PR/lifecycle facts in tooltips. Repository metadata disappears when PR and worktree counts are both zero. Header controls use compact sizing to protect repo names. Returned subagents fold into an expandable count independently of running work.
In rich mode, ungrouped repositories with open terminals appear first, followed by an Idle section. Manual order is preserved inside each section. Idle headers start on one line; disclosure reveals their branches without changing activity or saved order. Headers count agents in the backend working state, independently of open-terminal membership.
Rich active/idle sections also apply independently inside each existing repository group. Group membership and group ordering remain intact; active-only filtering hides idle-only groups and empty Idle headings.
Rich merged linked worktrees with no sessions and verified lifecycle facts use a one-line summary: Merged, N uncommitted, Clean up. Live, unmerged, or unknown worktrees retain full rows. Clean up enters the existing lifecycle preflight and confirmation workflow; cancellation preserves the worktree.
Rich parent terminal rows show N agents in each other repository containing live children. Clicking reveals the child group, repository and workspace, then selects a child through existing terminal navigation. Session placement and same-branch nesting stay intact; closed children disappear from summaries.
Browser repository picker
ApplicationOverlays uses RemoteRepoPicker for browser Add Repository as well as connected daemon folders. An omitted connectionId browses the serving TUIC with the existing get_home_directory and list_directory RPCs; an explicit ID browses that daemon. Selection and cancellation resolve the existing path prompt. Native desktop selection still uses the OS dialog.
AutomationsDialog
src/components/AutomationsDialog/ provides a machine-local scheduled-run dialog.
AutomationsHost loads it on demand from the command palette. The searchable
list shows the stored zone, next occurrence and last status, including overlap
skips. The editor supports literal prompts, run config, workspace, precheck,
limits, backend cadence presets and backend schedule previews. Once uses
once_local plus the stored zone, without browser timezone conversion. Pause, Run now,
save, confirmed deletion and recent history share one adapter. Deletion retains
saved history. Escape uses the modal stack; Tab stays in the dialog.
The Step 8 API is a separate integration dependency. transportAdapter.ts is the
only provisional command-envelope boundary; tests inject AutomationAdapter.
No schedules or launch decisions are calculated in TypeScript.
RunsView in the Automations dialog renders all-history pages and backend 24h/7d summaries. RunOutput renders saved stdout/stderr and immutable workspace details. View run only focuses a live terminal with matching daemon ownership; unavailable sessions never launch a replacement.
Reusable setting field controls
SettingsPanel/SettingFields.tsx exports SettingAccount, SettingList,
SettingMultiSelect, SettingStatus and SettingButton. The implementations in
SettingsPanel/fields/ share the existing label and hint layout. Editable rows use
stable IDs; multiselect uses checkboxes; status is read-only. The account picker
loads the core account list and delegates Add to a token-free native-flow callback.
These controlled components do not persist settings or define catalogue fields.
The dev-only fields/preview.html mounts the actual controls for visual checks.
The Precheck section includes a default-off stdout context checkbox. It edits
precheck.inject_output through the existing store and shared save API, without
changing prompt text. Disabling and re-enabling the precheck resets the flag.
The mobile session header uses a handset icon and Start/Stop voice call labels for the two-way voice control. The phone More menu uses the same Start/Stop voice call labels. The composer dictation button keeps its microphone icon.
Mobile composer browser dictation
Restored dictated drafts stay in the composer without writing to the terminal on mount. Send or the first edit reconciles the saved text with the current PTY input line through the existing delta path. Later edits use the local baseline so delayed terminal echoes do not replay text.
CommandInput mounts useBrowserDictation, a feature-detected browser interaction hook. Its mic is directly before Send in the existing row; interim hypotheses are replaced and final speech stays in the current draft without focus or automatic Enter. SessionDetailScreen excludes server hands-free while browser recognition is pending or active, and useMobileVoice.recording blocks browser starts during server arming/recording. Manual typing or keybar text insertion cancels recognition and preserves the edited draft. The mic stays claimed until the browser emits end, including after an error; queued results from that recording are ignored. Tap the mic to resume after end. Browser errors request cancellation through the same shutdown path as an edit or send. Browser failures are logged as well as toasted. The toast is the only failure surface; the composer has no retained failure label or failure colour. MobileToastContainer keeps a polite live region mounted before any toast appears, so failure text can be announced without moving focus from the composer. The hook also stops on send, session end, or unmount. No setting or backend route is added. Bounded lifecycle diagnostics use source dictation, level debug: start attempt, first result, first error with code, abort request, end and ownership release. Each record includes the captured session ID, a random take ID and a per-take sequence number, not transcript text. The sequence preserves event order even if uploads arrive out of order. Unbound AI Chat drafts use a null session ID. At most six records are emitted per take; they reach the owner through the existing log route.
IdeasOverlay reuses the same hook and MobileDictationButton. SessionDetailScreen passes its existing voice-call and terminal-dictation recording signals to block the Ideas hook and disable its mic while either owns the microphone. It supplies an optional getSelection accessor, so each take captures its insertion range and replaces only that range as hypotheses change. Empty hypotheses preserve the original selection. Typing and explicit idea submission cancel recognition before changing the draft. Speech updates only the unsaved idea input, never the terminal or idea store. The hook keeps tail insertion for consumers that omit getSelection.
Tasks board
Tasks/board/TasksBoard.tsx renders the provider/core board projection. Each lane
has a virtualized card list. Pointer capture supports drag and drop; the native
move menu provides keyboard and touch access. Moves dispatch the provider’s per-card
action, show pending feedback, and restore the origin on rejection. Cancellation
and scope changes clean up drag state. Consumers refresh the projection after a
successful move by merging page one into the loaded cards. Other loaded pages are
retained until reload. The move menu stays open when its own list scrolls; scrolling
outside it dismisses it. The view does not infer workflow transitions.
Terminal marker layout uses viewportProjection.ts: suggest anchors and hard-wrapped tails consume no display row; answer marker cells and their trailing space consume no display columns. Intent stays visible. Grid painting, cursor/IME, selection, search and link hit testing use the same reversible projection, including cache-driven smooth scrolling; PTY cells and absolute scrollback/copy coordinates remain unchanged.
Submitting a new prompt clears old choices and reopens follow-up delivery. A user-input event can arrive after shell-state: busy, so it must not dismiss the choices for the new turn.
Tasks useStartWork obtains the brief from build_start_work_prompt before the
provider action, with a pending state covering that read. The Rust builder reads
.tuic-start-work.md in the repository root; absent files use the legacy brief.
Read failures use the existing error/Retry state. Host delivery retains the
untrusted-content wrapper and 12,000-character cap.
Terminal Compose shortcuts
ComposePanel binds Enter to immediate send, Ctrl+Enter and Shift+Enter to a newline, and Shift+Ctrl+Enter to the existing agent-only idle queue. CodeMirror owns IME composition filtering, including Safari candidate-confirmation ordering. Desktop CLI and Chat use this editor; the mobile terminal retains its separate CommandInput and keybar.
Terminal Compose attachments
ComposePanel uses useComposeImages for paste, file drops and its image-only multi-file input. All three reuse saveImageFile in pastedImage.ts. Drop/picker insertion ranges track document edits during saving. Native file drops route to a registered mounted editor before the existing global terminal/tab dispatcher; closing or unmounting unregisters that target. Rejected files and save failures appear in an accessible alert.
The desktop macOS General page includes Hide Dock icon in background under
Confirmations. It uses the shared setting toggle and persists
background.hide_dock_icon; browser settings omit this native control.
The mobile AI Chat composer uses the same device-local keyboard correction preference as the terminal composer; toggling it updates autocorrect, spellcheck and sentence capitalization on the open textarea. Desktop Chat retains its existing input attributes.
Answer highlights in the terminal grid, AnswersPanel, AI Chat markdown and terminal Chat cards use a green left rule without an answer background layer. Paragraph spacing and each content block’s own background stay unchanged. User-question styling is separate. Terminal Chat keeps semantic answer scope on the blocks selected by answerBlockRanges and on marked list items. Only an outer data-tuic-answer-region container draws the rail, never a paragraph, list or list item. A list with any marked descendant stays intact inside the region as visual context; unmarked items do not acquire answer ownership. Adjacent Markdown streaming segments keep renderer-owned DOM and draw adjoining rail fragments with padding instead of margin gaps. Desktop and mobile use the same selection.
The shared --answer-rule token preserves the dark-theme rule and uses --success in Paper to keep the rule visible on the light page. Terminal Chat cards already use --success.
Answer overlay caching includes cell height and projected row positions as well as marker content, so font loading and theme remeasurement cannot retain old rule geometry.
Tasks list controls use provider-declared field sort, group and filter capabilities. A rejected selection restores the last successful query and shows the provider reason.
Tasks small-list mode (#1851-7ade): when the provider reports at most 1,000 matches, Tasks collects the complete search/preset scope and uses the Rust projection for all-field sort, group and filter. A changed total, missing rows or a nonterminal cursor cannot establish completeness. Unknown totals and larger lists keep provider-supported server controls. No extra cache or persisted state is added.
GitHub Tasks boards (#1846-55d7): the optional provider listBoards(signal) port discovers the current user Projects v2 when Board opens. The existing picker selects a project; paging preserves project identities. Missing read:project stays visible instead of claiming there are no boards. Providers without discovery retain their configured boards. Discovery does not persist selections or write to GitHub.
TasksDetail provides Follow task / Unfollow task in its toolbar. Settings → Notifications has a Tasks section with an independent default-off OS notice preference.
FileBrowserPanel subscribes to successful folder-drop completion and routes it through its existing mutation refresh. The subscription is scoped to the filesystem root and owning connection, and is removed when the panel unmounts.
External changes use nonrecursive directory watches for the current listing and each visible expanded tree node. The panel reconciles this set without restarting unchanged watches, invalidates the changed relative cache key, and reloads cached children when their watch resumes after a collapse or hidden panel. Watches stop when their directory leaves the visible tree, during search, or when the panel closes. This path does not depend on Git status or repository revisions. The backend shares one native watch per absolute path and counts successful acquisitions across IPC and HTTP consumers, so one panel releasing a path does not stop another panel’s watch.
Settings presentation vocabulary
SettingsPrimitives.tsx provides SettingPageHeader, SectionCard, SettingRow, StatusSummary, ListRow, EmptyState and DangerZone. These components render caller-owned content only. SettingRow reuses SettingField label and descriptive IDs, including field errors; controls remain the existing UI Input/Select/Textarea components. SectionCard and DangerZone titles are understood by the static Settings search extractor and render h3 anchors. Existing field consumers retain their stacked layout unless they opt into row presentation.
Settings integration keeps SettingsPanel as the page-selection owner. Search catalogue reads do not mount page consumers; plugin describe supplies navigation and search while scoped get starts only when the editor mounts. Search reveals expert keys before the next-frame scroll without persisting Expert Mode. Section links preserve retired-tab mappings, ignore missing anchors and cancel scheduled work on close. pluginSettingsTab.test.tsx, settingsPanelSearch.test.tsx, settingsPanelExpert.test.tsx and DeepLinkSection.test.tsx cover these shared boundaries, including local loading/errors and removal during pending plugin reads. No global save transaction or status inference belongs in the shell.
The Pocket Voice picker includes installed and downloadable catalogue voices for the active language. A missing configured voice stays selected with a Not Downloaded label and an adjacent Download row.
Terminal ego provider recovery: the tab replaces its busy animation with a recovering label. StatusBar mounts ProviderRecoveryStatus only while a complete backend recovery snapshot exists; its one-second display timer stops on unmount. The component displays phase, attempt, next-time and a zero-clamped countdown, with a single-flight Force retry button using the shared backend retry transaction. A non-empty composer refuses the retry; the status bar displays the error.
Voice correction controls carry corrections.replacements.{from}.from and
corrections.replacements.{from}.to catalogue identities. Import, add and remove
retain the existing TextCorrector workflow; export does not change settings.
Progress toast repository navigation uses navigateToTerminal for both a live origin and a surviving destination-workspace tab. With no destination tab, it clears terminal activation and the previous pane layout. Chat and Compose stay owned by their terminal; no second navigation listener retargets them.
Desktop TerminalChatView renders active native questions from the existing session lifecycle store below the shared transcript. ChoicePromptOverlay has an embedded layout; desktop and mobile share sendNativeChoice for agent-specific PTY keys. Compose drafts and ACP interaction state are not involved.
Mobile offers the Chat tab only when the host has a configured ego executable, using the same availability predicate as desktop. Host settings changes update the tab without reloading. Removing ego configuration returns an open Chat view to Sessions; unavailable saved Chat links also stay on Sessions.
Abandoned-shell markers in desktop sidebar session rows and mobile SessionCard render the same backend state.abandoned_since_ms timestamp. A missing field retracts the marker; the frontend does not infer abandonment from silence.
Context menu viewport bounds
Context menus use their unscaled layout size to stay within an 8px viewport margin. Oversized menus scroll; their minimum width also shrinks in narrow windows. Shell workspace rows do not offer branch workflow actions or Git smart prompts.
Shell-folder rows offer the same available-agent menu as Git workspace rows. Launching an agent uses the folder as its working directory, without creating a branch or worktree. The Add Terminal button also offers agents on a long press.
Detached worktree inventory is rendered by RepoSection as informational rows, outside the selectable branch-workspace list. The header retains a detached count while folded; no branch or terminal actions are attached to detached rows.
FileBrowserPanel and TreeNode render the backend link target and target kind with a link icon instead of a file-size badge. Delete refreshes the listing after success and shows a persistent error notification after failure. Navigation stays unchanged. The code editor shows the backend target-specific refusal when an outside-repository link is opened.
Mobile SessionUsageBlock
SessionUsageBlock is mounted inside the session overflow. It loads
get_session_usage on mount/session change, invalidates pending responses on
cleanup, and renders backend-owned token/cost lines without usage computation.
Quota fields use sessionUsageFormatting, also used by desktop Claude/Codex cards.
The shared presenter owns provider/plan/window words and client-local short times.
The block shows model metadata only when available and keeps explicit loading,
unavailable and stale presentation. The overflow height is bounded by its session
pane rather than the viewport, and its sections do not flex-shrink.
Sidebar worktree diagnostics render recorded paths and repair guidance without buttons, tab focus or branch-selection handlers. The repository header retains a diagnostic count while folded. These transient inventory rows are separate from branch workspaces and are not saved in repository configuration.
StoryNotes (native story detail)
StoryNotes renders the selected story’s append-only notes and workflow receipt references. Its local Suspense boundary keeps pending notes from removing the parent dialog through the inline or detached host’s lazy-loading boundary. Plan, story and filter selections update the visible dialog in place. StoriesDialog mounts it with a project/story key, so changing selection cannot carry a draft or a late append response into another story. It calls the shared story service for list_notes and add_note; the backend owns validation, author/time/revision provenance, receipt ownership and append order. A failed append keeps the exact draft. A confirmed append clears it and reloads persisted notes. Refresh notes loads additions from MCP or another window; there is no polling or alternate state store.
Stories dialog actions use the shared Button geometry. Plan, story and run list rows and Kanban cards retain native layout buttons with explicit row/card markers.
ui/ColorSwatch is the shared native button for immediate preset/clear color selection.
It keeps selection in the owner through selected/aria-pressed, defaults to
type="button", forwards native refs/events/disabled, and uses a 36px circular
target with a 44px touch minimum. Set swatchColor for a preset; omit it for
the dashed clear target. Give each target an accessible name. Feature CSS may
arrange the wrapping picker but must not resize its swatches.
Settings shell and shared Settings actions use ui/Button; native navigation
and search-result rows retain their layout marker and click semantics. Settings
search lays out the icon, shared Input and clear Button as siblings. Select
arrow clearance belongs to FormControls, not to Settings selectors.
SettingPageHeader, SectionCard, StatusSummary, ListRow, EmptyState
and DangerZone action slots arrange their children only. Pass shared UI
controls into these slots; the containers do not set descendant button sizes.
SettingButton, account add/retry actions and list add/remove actions also
use ui/Button; field CSS owns their width and row layout only.
Button geometry="stretch" fills a flex/grid cross-axis container with square
edges and at least 36px desktop or 44px touch targets. Use it for edge actions
such as swipe actions and tab scroll arrows; the container owns placement.
ButtonGroup joins direct Button children with connected edges and one
divider. Each action retains its native events, disabled state and size. Label
the group with aria-label or aria-labelledby. Keep dropdown content outside
the direct action children; the group does not clip focus rings or popovers.
Textarea autoGrow is a compact content-sized editor: it starts at the shared
36px desktop or 44px touch target and grows to three control heights before
scrolling. It recalculates after native input, controlled value updates and
width changes. Remove caller height caps and auto-resize handlers when adopting
it; the shared CSS is the single owner of the bounds. Default Textarea keeps
its existing three-control-height minimum and manual vertical resize.
Textarea embedded keeps the native ref and event handling without standalone
field styling, for a composer whose surrounding shell owns the focus frame.
Shared fields style native aria-invalid="true" with the error border token
without replacing the focus outline. Button variant="removalToggle" supports
installed/removal toggles via native aria-pressed; see the Style Guide for
state and hover semantics. Consumers retain validation messages and callbacks.
Agent settings use shared Button, Switch and Textarea controls, including launch module and launch-addition editors. Validation fields expose native invalid and error descriptions; the installed MCP action uses the shared removal toggle. Agent feature CSS retains only layout, width and text presentation.
GitHub settings actions use shared Button variants for secondary, primary and danger actions. Feature CSS owns only action-row layout, not button geometry.
Shared Button supports opt-in shape="icon", with required aria-label and
optional circular presentation. Its native square target stays 36/44px even
with compact size. Circular presentation does not remove the corner hit region.
Plugin settings actions use shared Button variants and a circular icon-only documentation target. Log visibility uses native aria-pressed; install suggestions use the same shared Button as their work-item setup consumer. Feature CSS owns action layout only.
Repository settings use shared Button for team export and shared Switch for worktree consolidation. The switch retains its native checkbox, accessible row label, and repository-owned update callback; feature CSS only aligns the control.
Smart Prompt editor variable triggers and reset actions use shared Button.
Variable choices remain native list-row buttons with name and description;
data-control-layout="row" makes their intentional list geometry explicit.
Telegram settings inherit target sizing and touch typography from shared Button, Input, and Switch controls. Feature styles only format the chat-list heading.
Keyboard Shortcuts uses shared Button for the built-in Rebind actions and the global-hotkey Clear action. Workspace styles retain binding-column layout only.
Ego terminal usage (#2386-6f7c)
Ego terminal usage uses the exact live pid lease and ego usage --json --session <id> reports v3–v5. The badge shows the short model name and observed context tokens/capacity. Its tooltip shows the full provider/model. Anthropic models use the existing Claude usage endpoint and ticker; openai-codex models use the existing Codex usage endpoint and ticker. Other providers show model/context only. Ego ledger costs and provider-limit observations do not supply badge quotas; session details still show ledger accounting. Unsupported report versions return an error and log one warning per process, rather than silently emptying the badge. The executable comes from the live terminal, not the AI Chat setting.
Chat working indicator
The shared Transcript renders WorkingIndicator from its existing busy and retry props on desktop and mobile. The indicator uses the theme accent for a dot and breathing ring, preserves the host working label through its status role, and hides the decorative orb from assistive technology. Reduced motion removes the ring animation and leaves the static dot. Provider retry status takes precedence; no effect selector or setting exists.
Terminal Chat sends use a session-scoped, presentation-only pending projection. Desktop Compose and mobile CommandInput show the submitted text immediately as muted Pending user bubbles, in send order. New matching native user messages replace that feedback atomically; activity and idle updates do not clear it. A failed send removes only its own bubble. The CLI owns delivery and cancellation: these bubbles are not the server-owned command queue or the ACP queue. Closing Chat or replacing its transcript clears this local feedback.
WorkflowDesigner uses ReviewPolicy for bounded review/repair controls and NodeFields for exact role, prompt, profile and tools plus typed contracts. RunDefinitionPins renders backend-derived counters and immutable live/replay definitions; it clears stale requests on run or sequence changes. Shared UI primitives own control geometry.
RunInspectionPanel / RunInspectionContent
The Stories dialog run history expands Inspect delivery and cost on demand. The panel refreshes on durable run wake hints and reconnect revisions, rejects old selection responses, pages cursor deltas and retains the last committed outcome during a disconnected refresh. Content renders backend projections for pinned nested delivery, reports, questions, integration/proof journals, evidence links, owned sessions and usage coverage. It performs no scheduling or cost arithmetic. Existing recovery controls remain in the run view.
Waiting items and AgentHealthView
waitingItemsStore (src/stores/waitingItems.ts) holds the Rust boss_attention projection while a holder retains it. It refreshes on attention, workflow, repository-set and remote-connection events, repository revisions and browser SSE resync. Session events refresh it only while a health view (retain({ health: true })) is open. Invalidations are debounced by 250 ms and serialized, so an overtaken response cannot restore a resolved item. Each reply is reconciled with reconcileById (src/utils/reconcileById.ts): unchanged rows keep their objects, and an unchanged reply keeps the previous snapshot, so no row is rebuilt. A failed read clears the cached snapshot.
useWaitingItems(App) syncs the projection into the activity bell sectionwaiting: one entry per item id, never re-added while present (dismissed included), removed when the item leaves a complete snapshot. A snapshot with warnings only adds. It starts afteractivityStore.whenHydrated(), so persisted dismissals stay.WaitingOnYou(Plans and Stories) lists the current project’s items. A selection calls the dialog’s reveal: select the story, or open Run history on the item’s run. A bell click on a workflow question opens the run in the Workflows space (workflowsUi.reveal); a manual check opens its planning item. A report item opens its typed report path instead: the inline dialog closes and opens the file; a detached dialog sendsopen-reportto the main window, which focuses and opens it. Bell entries usestoriesUi.reveal, consumed by the dialog throughstoriesUi.takeTarget; a report entry opens the report file.AgentHealthView(Activity Dashboard, including detached windows) renders health entries only: Failed, Stalled, Input stalled and Blocked. A missing live stage alone is not a health warning, even for a managed agent. Detached navigation is routed back to the main window.
The bounded correction-region section renders the backend-generated criteria, selected activity, correction limit and full input/output/control/loop/subflow contract. It opens the exact selected child publication read only and validates before adopting the generated definition. Retained inspection displays consumed corrections from the durable correction loop iteration, excluding the initial attempt; there is no independent UI budget counter.
Stores Reference
Slice F exposes start_graph {target:{type:story|plan,id},expected_revision?,definition_id,definition_revision,request_id,limits?} through the existing owning-daemon service. Story starts require the current native revision and pin the selected publication; the request ID is bound to its payload. Omitted limits use Rust defaults. Plan dispatch remains unavailable in this build and its start control says so. The workflow action=run MCP entry uses an inline schema generated from RunAction and the public RunCommand variants; it returns the same scoped snapshots and cursor-ordered events as IPC/HTTP. Run history shows pinned activations, decisions/evidence, repair counters, pause targets and complete event payloads across pages. Graph recovery uses resume_graph {execution_id,activation_id,resolution} after answering pending input; pause and cancel use the existing sequence-fenced commands. Legacy runs offer inspection and cancellation in the UI. No new persistence or client scheduler is added.
All stores use SolidJS createStore for reactive state. Each store exposes a state getter and action methods.
terminalsStore
File: src/stores/terminals.ts
Manages terminal instances, active tab selection, split pane layout, and closed tab history.
State Shape
| Field | Type | Description |
|---|---|---|
terminals | Record<string, TerminalData> | All terminals by ID |
activeId | string | null | Currently active terminal |
layout | TabLayout | Split pane layout state |
Key Types
interface TerminalData {
id: string;
sessionId: string | null;
name: string;
nameIsCustom: boolean; // When true, OSC/status-line title changes are ignored
fontSize: number;
cwd: string | null; // Current working directory (from OSC 7)
repoPath: string | null; // Owning repo — the record. null = parked guess (see terminalOwnership)
awaitingInput: AwaitingInputType; // "question" | "error" | null
awaitingInputConfident: boolean; // High-confidence detection — don't clear on idle→busy
shellState: ShellState; // "busy" | "idle" | null
activity: boolean;
unseen: boolean; // Terminal completed work while user wasn't viewing it
progress: number | "indeterminate" | null; // OSC 9;4 progress (0-100), "indeterminate" for state 3, null when inactive
agentType: AgentType | null; // Detected foreground agent process (e.g. "claude")
pendingResumeCommand: string | null; // Set at restore time, consumed on first shell idle
pendingInitCommand: string | null; // Setup/run script to auto-execute on first shell idle
usageLimit: { percentage: number; limitType: string } | null;
lastDataAt: number | null; // Timestamp of last PTY output
lastActivityAt: number | null; // Backend timestamp of last semantic session activity
lastPrompt: string | null; // Last relevant user prompt (>= 10 words), set by Rust
agentIntent: string | null; // LLM-declared intent via intent: token
currentTask: string | null; // Current agent task from status-line parsing
activeSubTasks: number; // Count of running sub-agents from ›› status line
isRemote: boolean; // Created via HTTP/MCP (not locally by the UI)
exactAgentSessionId?: string | null; // Live, validated Codex hook binding; never persisted
agentSessionId: string | null; // Agent session ID for session-specific resume
tuicSession: string | null; // Stable tab UUID — injected as TUIC_SESSION env var
suggestedActions: string[] | null; // Follow-up suggestions from suggest: token
suggestDismissed: boolean; // true after user dismissed — prevents re-show
}
interface TabLayout {
direction: SplitDirection; // "none" | "vertical" | "horizontal"
panes: string[]; // Terminal IDs (up to MAX_SPLIT_PANES = 6)
ratios: number[]; // N fractions summing to 1.0 (length === panes.length)
activePaneIndex: number; // 0..N-1
}
Actions
| Method | Description |
|---|---|
add(data) | Add a terminal |
remove(id) | Remove a terminal |
setActive(id) | Set active terminal (clears activity flag) |
update(id, data) | Partial update terminal data |
setSessionId(id, sessionId) | Update session ID |
setFontSize(id, fontSize) | Update font size |
setAwaitingInput(id, type) | Set awaiting input indicator |
clearAwaitingInput(id) | Clear awaiting input |
splitPane(direction) | Split into two panes |
closeSplitPane(index) | Collapse back to single pane |
setSplitRatio(ratio) | Adjust split ratio |
setActivePaneIndex(index) | Switch active pane |
Queries
| Method | Description |
|---|---|
get(id) | Get terminal by ID |
getActive() | Get active terminal |
getIds() | Get all terminal IDs |
getCount() | Get terminal count |
hasAwaitingInput() | Any terminal awaiting input? |
getAwaitingInputIds() | Get IDs of terminals awaiting input |
repositoriesStore
File: src/stores/repositories.ts
Manages saved repositories, branches, terminal associations, and PR status cache.
State Shape
| Field | Type | Description |
|---|---|---|
repos | Record<string, RepositoryState> | Repositories by path |
activePath | string | null | Active repository path |
Key Types
interface RepositoryState {
path: string;
displayName: string;
initials: string;
isGitRepo?: boolean; // false for plain directories
expanded: boolean; // Show branch list
collapsed: boolean; // Icon-only mode
parked: boolean; // Hidden from sidebar (recallable via popover)
workspaces: Record<WorkspaceId, WorkspaceState>;
activeBranch: string | null; // holds a WorkspaceId; renamed in a later pass
}
/**
* Opaque. Existing records were migrated with `workspaceId = branchName`, so the
* value looks parseable, but callers still read `WorkspaceState.branchName`
* instead of taking display data out of the key.
*/
type WorkspaceId = string;
// Load-time repair (`workspaceIdentity.ts` `repairIdentity`) TYPE-CHECKS the
// path and name fields rather than only replacing null/undefined. The document
// is untrusted input, and the realistic corruption is a shape skew, not a
// hostile write: `get_worktree_paths` became `{id: {branch, path}}` in one
// commit, and a WebView still holding the pre-change module wrote the whole
// record into `worktreePath`. That value round-trips through every later load
// and reaches `joinPath`, which calls `.replace` on it and takes the app down
// with an error naming neither the field nor the repo; a non-string
// `branchName` does the same via `compareBranches` -> `localeCompare` inside
// the sidebar's sort memo. A corrupt path degrades to `null` — "no separate
// checkout", which every reader already handles — and the next refresh writes
// the real value back. Salvaging `.path` out of the object is deliberately not
// done: it encodes one historical shape and would hide the next one.
interface WorkspaceState {
workspaceId: WorkspaceId; // equal to the key that holds this record
branchName: string; // display data, not a lookup key
kind: "main" | "worktree";
parentRepoPath: string | null;
isMain: boolean;
isShell?: boolean; // true for non-git directory shell entries
worktreePath: string | null;
terminals: string[]; // Terminal IDs
hadTerminals: boolean; // Suppresses auto-spawn after close-all
lastActiveTerminal: string | null;
additions: number;
deletions: number;
isMerged: boolean; // Fully merged into main branch
lifecycleStatus?: {
dirty: boolean | null;
commitStatus: "unmerged" | "merged" | "unknown";
removalSafety: "safe" | "requires_force" | "unknown";
error?: string;
}; // derived, workspace-id keyed, never deletion authority
lastCommitTs: number | null; // Unix timestamp of last commit
runCommand?: string;
savedTerminals?: SavedTerminal[];
ciAutoHeal?: { enabled: boolean; attempts: number; lastRunId?: number; healing?: boolean };
layout?: TabLayout; // Split layout persisted per-branch
}
lifecycleStatus is populated by progressive refresh from the backend’s
workspace_statuses map. It is preserved as live derived state when another
window writes the repository document and excluded from intent comparisons.
Removal never trusts the cached value: it requests a fresh backend preflight.
Actions
| Method | Description |
|---|---|
hydrate() | Load from Rust backend |
add(repo) | Add repository |
remove(path) | Remove repository |
setActive(path) | Set active repository |
toggleExpanded(path) | Toggle branch list visibility |
toggleCollapsed(path) | Toggle icon-only mode |
Every method below that takes a workspaceId takes the map key, never a branch | |
| to look up. The two are the same string for everything a linked worktree ever | |
created — the identity migration minted workspaceId = branchName so nothing | |
| persisted moved — which is exactly why the parameter is named for the key: a caller | |
| holding a branch off git output and a caller holding an id off a workspace record | |
| are indistinguishable at the call site otherwise. |
| Method | Description |
|---|---|
setWorkspace(repoPath, workspaceId, data) | Add/update one workspace. data.branchName defaults to the id |
setActiveWorkspace(repoPath, workspaceId) | Set the active workspace. Rejects an id that names no row and keeps the previous pointer — a dangling one fails later and elsewhere: the sidebar renders no tab row for it, and the next terminal added to that workspace spawns in $HOME. migrateActiveWorkspaceId drops the same dangling id at load time; this is the live half of that rule |
addTerminalToWorkspace(repoPath, workspaceId, terminalId) | Link terminal |
removeTerminalFromWorkspace(repoPath, workspaceId, terminalId) | Unlink terminal |
setRunCommand(repoPath, workspaceId, command) | Save run command |
updateWorkspaceStats(repoPath, workspaceId, additions, deletions) | Update diff stats |
removeWorkspace(repoPath, workspaceId) | Remove one workspace |
renameBranch(repoPath, oldName, newName) | A branch was renamed — moves the record AND its workspaceId, since a branch-derived id is the key |
mergeWorkspaceState(repoPath, sourceId, targetId) | Move terminals/saved tabs between workspaces |
reorderTerminals(repoPath, workspaceId, fromIndex, toIndex) | Reorder tabs |
Queries
| Method | Description |
|---|---|
get(path) | Get repository by path |
getWorkspace(repoPath, workspaceId) | One workspace record — the only supported way to reach one |
branchNameFor(repoPath, workspaceId) | The branch that workspace has checked out. id → branch is a lookup; branch → id is a guess, so there is no inverse |
findOwnerForTerminal(termId) | { repoPath, workspaceId } for a terminal |
getActive() | Get active repository |
getPaths() | Get all repository paths |
getActiveTerminals() | Get terminal IDs for the active workspace |
isEmpty() | Check if no repositories |
resolveRepoOwner(path) (same module) answers { repoPath, workspaceId | null }:
a path resolves to a workspace id because two workspaces may share a branch but
cannot share a directory. null means the match was at the repo root, whose
checkout changes under the user’s feet — resolve it late through
activeWorkspaceId, or via placementWorkspaceFor(owner).
settingsStore
File: src/stores/settings.ts
Application settings: font, shell, IDE, theme, confirmations.
Each hydrated window tracks its own normalized settings baseline. Debounced saves
apply only preferences changed since that window’s last successful save to a fresh
config load, then submit the existing base/config pair through updateAppConfig.
Unchanged preferences stay as loaded, including fields another settings window
edited. Failed saves retain pending edits; edits made during a save remain pending
for the next save. Hydration itself does not persist normalized defaults.
State Fields
| Field | Type | Default | Description |
|---|---|---|---|
ide | IdeType | "cursor" | IDE for “Open in…” |
font | FontType | "JetBrains Mono" | Terminal font |
agent | string | "claude" | Primary agent |
defaultFontSize | number | 12 | Default font size |
shell | string | "" | Shell override |
theme | string | "dark" | Terminal theme |
confirmBeforeQuit | boolean | true | Quit confirmation |
confirmBeforeClosingTab | boolean | true | Tab close confirmation |
maxTabNameLength | number | 20 | Max tab name length |
Constants
IDE_NAMES— Display names for IDEsIDE_ICONS— Emoji iconsIDE_ICON_PATHS— SVG icon pathsIDE_CATEGORIES— IDE grouping (editors, terminals, git, utilities)FONT_FAMILIES— CSS font-family strings
githubStore
File: src/stores/github.ts
GitHub PR and CI data with background polling.
Actions
| Method | Description |
|---|---|
updateRepoData(repoPath, prStatuses) | Update PR data for all branches (detects state transitions for notifications) |
startPolling() | Start background polling (30s base, 2m when hidden, 5m backoff on rate limit) |
stopPolling() | Stop polling |
pollRepo(path) | Immediately poll a single repo (debounced 2s to coalesce rapid git events) |
setRemoteStatus(repoPath, remote) | Set remote tracking status directly (used by simulator) |
Queries
| Method | Description |
|---|---|
getCheckSummary(repoPath, branch) | Get CI check summary |
getPrStatus(repoPath, branch) | Get PR status |
getCheckDetails(repoPath, branch) | Get CI check details |
getBranchPrData(repoPath, branch) | Get full BranchPrStatus |
getRemoteStatus(repoPath) | Get remote tracking status (ahead/behind) |
promptLibraryStore
File: src/stores/promptLibrary.ts
Prompt template management with variable substitution.
State Fields
| Field | Type | Description |
|---|---|---|
prompts | SavedPrompt[] | All prompts |
drawerOpen | boolean | Drawer visibility |
searchQuery | string | Search filter |
selectedCategory | PromptCategory | Category filter |
recentIds | string[] | Recently used prompt IDs |
Actions
| Method | Description |
|---|---|
hydrate() | Load from Rust |
openDrawer() / closeDrawer() / toggleDrawer() | Drawer visibility |
createPrompt(data) | Create new prompt |
updatePrompt(id, data) | Update prompt |
deletePrompt(id) | Delete prompt |
toggleFavorite(id) | Toggle pinned status |
markAsUsed(id) | Add to recent list |
processContent(prompt, variables) | Substitute variables (via Rust) |
extractVariables(content) | Parse {{variable}} placeholders (via Rust) |
statusBarTicker
File: src/stores/statusBarTicker.ts
Rotating message ticker for the status bar. Plugins and native features post messages; the highest-priority message is displayed, with rotation among equal-priority messages.
TickerMessage Type
interface TickerMessage {
id: string; // Unique message ID (scoped to plugin)
pluginId: string; // Plugin that posted the message
text: string; // Display text (~40 chars max)
icon?: string; // Optional inline SVG icon
priority: number; // Higher = more visible. >=80 gets warning styling
ttlMs: number; // Time-to-live in ms (0 = persistent until removed)
createdAt: number; // Timestamp when added
onClick?: () => void; // Optional click handler
}
Actions
| Method | Description |
|---|---|
addMessage(msg) | Add or replace a message (by id + pluginId). Resets TTL on replace. |
removeMessage(id, pluginId) | Remove a specific message |
removeAllForPlugin(pluginId) | Remove all messages from a plugin |
clear() | Clear all messages and stop timers |
Queries
| Method | Description |
|---|---|
getCurrentMessage() | Get the highest-priority non-expired message (rotates among equal-priority) |
getAll() | Get all active (non-expired) messages |
Internals
- Rotation: Messages at the same priority level rotate every 5 seconds.
- Scavenging: Expired messages (past TTL) are cleaned up every 1 second.
- StatusBar integration: The
claude-usageticker message (pluginId"claude-usage") is absorbed into the agent badge when the active terminal runs Claude, and suppressed from the separate ticker area.
ideasStore
File: src/stores/ideas.ts
Persistent ideas with per-repo tagging and usage tracking.
The store, the panel and this type say “idea”. The backend commands
(load_notes / save_notes / save_note_image / delete_note_assets), the
notes.json payload field and the note- id prefix still say “note”: they are
on-disk and on-wire identifiers, renamed by no migration. The translation
happens only at the IO boundary in hydrate() and saveIdeas().
Idea Type
interface Idea {
id: string;
text: string;
createdAt: number;
repoPath: string | null;
repoDisplayName: string | null;
usedAt: number | null; // Timestamp when sent to or queued for a terminal
images: string[];
}
Actions
| Method | Description |
|---|---|
hydrate() | Load ideas from Rust backend |
addIdea(text, repoPath?, repoDisplayName?, images?, ideaId?) | Add a new idea, optionally tagged with a repo |
removeIdea(id) | Remove an idea by ID |
updateIdea(id, text, images) | Update an idea in-place |
reassignIdea(id, repoPath, repoDisplayName) | Reassign an idea to a different project |
markUsed(id) | Mark an idea as used (sets usedAt timestamp) |
clearCompleted() | Remove every idea that has been used |
Queries
| Method | Description |
|---|---|
getFilteredIdeas(activeRepo) | Get ideas for repo (global + repo-specific). null = all ideas. |
filteredCount(activeRepo) | Count of ideas visible for the given repo filter |
pendingCount(activeRepo) | Count of ideas not yet used |
count() | Total idea count |
Other Stores
Config-backed stores retain the snapshot returned by their load command and
send { base, config } on save (paneLayoutStore uses layout, and
activityStore uses items for the edited value). Their shared
configDeltaWriter orders overlapping saves within one WebView and advances
the base after each successful write. The backend merges only changed keys
against the latest locked file; arrays such as keybindings and notes replace as
a unit. A failed load disables saving rather than treating defaults as the
user’s prior document.
repoSettingsStore (repoSettings.ts)
Per-repository settings (base branch, scripts, worktree options).
uiStore (ui.ts)
Panel visibility (sidebar, diff, markdown, notes, file browser), sidebar width, dropdown state, loading state. Editor wrap defaults for text and code live here too; they use localStorage, like recent command-palette actions, so toggling them needs no backend restart.
notificationsStore (notifications.ts)
Notification sound preferences and playback. Remote orchestration muting uses
the terminal’s backend-preserved isRemote origin; completion lifecycle code
sets a per-busy-cycle latch before playback so idle and exit cannot both chime.
The playback manager applies one 500 ms gate across every sound type, because
all types share the same audio output and separate per-type gates allowed tones
from a notification burst to overlap.
ACP interaction notifications are keyed by connection and request ID, so a
re-render cannot send a duplicate. Settlement closes the matching notification.
acpStore.turnOutcome retains the latest streamed completion per attached session, including the turn ID on ACP v1 failures after activeTurn clears. Older replayed completions cannot replace it, and removed attachments release it. AI Chat matches it to locally submitted prompts before using the shared compact action and a single replay; history or another client’s turn cannot start recovery.
acpTranscript also projects ACP session titles and usage by session ID. The
AI Chat header, conversation picker and usage footer read that projection.
Provider-retry patches retain the provider text and an arrival-based presentation
deadline. createRetryCountdown owns one timer for the selected conversation;
recovery, final failure, settlement or panel disposal stops it. Missing or invalid
delays keep the provider text without starting a timer.
aiChatTabs is the single per-root store for open chat session IDs and the
selected tab. It mirrors its state to localStorage so a detached WebView can
restore the same tabs; useAcpChat replays their ACP histories after connecting.
ai_chat_sessions is the backend authority for active selection per configured workspace. createAiChatSelectionSync subscribes before its first read, rereads after ai-chat-selection-changed or SSE reconnect, and applies snapshots without writing them back. Local tab IDs and pins remain visual state; a local selection invalidates older reads and writes in order. useAcpChat attaches the shared selection only while visible.
acpStore replaces only the matching attachment’s complete option set on
config_option_update, including an empty set. It applies the published options
directly, without a snapshot request that could arrive after a confirmed settings
change. Explicit requests still refresh the authoritative backend snapshot.
acpStore takes queuedPrompts from the connection snapshot and replaces it
on each promptQueueChanged event, so desktop and browser views share the
same FIFO. acpTranscript adds a user message on promptSent, when the host
has sent it to ego; a queued prompt cancelled before dispatch never enters
the transcript.
turnFailed carries an ACP error diagnostic into the transcript and restores
the attachment state. A completed turn with no agent message receives an
explicit no-reply entry.
dictationStore (dictation.ts)
Whisper dictation config, model management, recording state — plus the speech
assets, the hands-free conversation and the spoken-reply status the Dictation
settings panel renders.
The backend crate split leaves its IPC and HTTP response shapes unchanged.
startRecording(source) sends the same origin over IPC or HTTP. A native Fn
release stops capture before the frontend’s stopRecording() awaits the final
transcription. DOM hotkeys release on blur if key-up was lost. Native macOS Fn
keeps recording across focus loss while physically held; Rust detects its
release outside the main window and sends the same fn-key-up event.
stopRecording() stores the response’s skip_reason as lastSkipReason, and
useDictation shows that reason in the status. A final transcription gate’s
specific reason reaches both; an empty successful pass shows no speech detected.
handsFreeListening reads and saves hands_free_listening the same way (setHandsFreeListening); armHandsFree passes it to connectBrowserVoice so a replies-only browser tab opens no microphone. spokenReplies reads and saves hands_free_spoken_replies through the existing
load/base/delta configuration path. Browser clients refresh configuration when
voice controls load; mobile Settings and conversation controls use the same
store action. Rust owns enforcement and cool-down decisions.
speechAssets/speechDownloads— the installable languages and ONNX runtime, and a percent per asset keyed by asset id, because the runtime library and a language are separate downloads a user can start together.downloadSpeechAssetclears its key withsetState("speechDownloads", id, undefined): a store update at a path merges, so returning a smaller object leaves the key exactly where it was.speechVoices— the voices of one language asget_speech_voicesreturns them ({ id, source },source"default","downloaded"or"user").refreshSpeechVoices(language)reloads it; the voice picker offers only these ids, because Rust refuses a catalogue voice that is not downloaded.importSpeechVoice(language, file)sends the file as base64 (dataBase64) under its file name without the extension, anddeleteSpeechVoice(language, name)removes a user voice. Both re-read the catalogue. The import returns the reason Rust refused the file, or null, so the panel can show it.previewSpeechVoice(language, voice)callspreview_speech_voicewith a short sample. It does not save the voice. It returns the refusal (for example, a hands-free reply is being spoken), or null.speechVolumeDb/speechLevelling— the loudness settings, read byrefreshConfig(defaultsDEFAULT_SPEECH_VOLUME_DB-18 andDEFAULT_SPEECH_LEVELLING0.67 until then).setSpeechVolumeDbandsetSpeechLevellingeach save one field.handsFree/speech— polled status, never pushed.refreshHandsFreeis deliberately one command, because the dictation hotkey asks on every press. Starting arm or disarm invalidates older status reads, so their late responses cannot overwrite the new conversation state or close its browser audio.handsFree.pendingTextis the unsent hands-free turn; push-to-talk’spartialTextis a separate recording. With an activation phrase,handsFree.holdBackMsis at least 5000 even if the saved setting is shorter.turnEarcon(previous, next, owner)—applyHandsFreeplays an earcon (utils/earcon.ts, Web Audio, 80 ms) whendeliveredTurnsordroppedTurnsmoved since the last stored status. Only the client that owns the audio plays it, and the first status a client reads is only a baseline.armHandsFreeprimes the audio context inside the user’s gesture, and readshands_free_earconsintohandsFreeEarconsat each arm, including after another client saves.setHandsFreeEarcons(value)saves it; off, nothing plays.armHandsFree(sessionId)sendsDESKTOP_AUDIO_OWNERon the desktop andbrowserAudioOwner— a per-tab random id — in a browser. In browser mode it opens the audio socket (utils/browserVoice.ts) before arming, because Rust refuses an owner with no connected client rather than falling back to the server’s microphone. A refused arm closes that socket again in thecatch, so a failure never leaves the device light on;disarmHandsFreecloses it in afinally. The refusal is stored inhandsFreeErrorrather than thrown. Successful browser arming also owns the page’s Media Session throughbrowserVoiceMediaSession: title TUICommander hands-free, Play/Pause useresumeSpeech/pauseSpeech(capture remains active), and Stop usesdisarmHandsFree(capture and replies end). Speech responses and pushed reply state keepplaybackStatecurrent; listening is active, held replies are paused. Disarm, including a polled backend disarm, clears metadata, handlers and playback state and closes browser audio. Browsers without the API still support hands-free; unsupported actions are logged and omitted.handsFreeStartNotice— the saved start notice,""meaning the built-in text.setHandsFreeStartNotice(value)saves it trimmed,resetHandsFreeStartNotice()saves"", andgetDefaultHandsFreeStartNotice()asks Rust for the built-in text (get_hands_free_default_notice) — the frontend keeps no copy of it. Its save falls back to the stored value, like the other one-panel fields.saveConfigabandons the save whenget_dictation_configcannot be read or answers something that is not a config. It sends the loaded document asbaseand overrides only the requested fields inconfig, preserving one-panel settings that other surfaces do not model.
errorHandlingStore (errorHandling.ts)
Error retry configuration and active retry tracking.
rateLimitStore (ratelimit.ts)
Active rate limit tracking per session.
tasksStore (tasks.ts)
Agent task queue management.
promptStore (prompt.ts)
Active prompt overlay state and agent stats buffer.
diffTabsStore (diffTabs.ts) / mdTabsStore (mdTabs.ts)
Open diff and markdown tab management (identical API patterns).
MCP native Markdown file tabs survive document reloads through a per-window sessionStorage snapshot. initApp restores their MCP identity, file target, repository/branch scope and pin state after terminal adoption. The store then saves relevant changes synchronously, including closes, pinning and selection, so native recovery does not depend on beforeunload. The unload handler also saves a final snapshot. Both automatic and explicit saves wait until initial restoration finishes, preserving the unread snapshot if another reload interrupts startup. Restoration consumes the prior snapshot only once per document and still runs if restoring the active repository branch fails. The selected document is selected again; background tabs remain inactive. A new MCP event received during startup takes precedence over the snapshot, including one that moves the identity to an editor tab. Snapshots are consumed before parsing so corrupt JSON is not replayed on the next initialization. Restoration indexes existing Markdown/editor identities once, accepts the first valid entry per identity, and appends the new tabs and their display order in one batch; duplicate-heavy snapshots do not rescan the growing tab collection. User-opened files and generated or iframe panels are not included. This is reload recovery, not backend persistence across app restarts.
mdTabsStore.openUiTab treats URL and HTML content as alternatives. Updating an existing URL tab with HTML clears its URL; updating an HTML tab with a URL clears its HTML. Visibility is decided by the tab renderers, which unload hidden plugin and URL iframes.
updaterStore (updater.ts)
App update check, download, and install. Supports stable (Tauri built-in), beta, and nightly channels.
keybindingsStore (keybindings.ts)
Rebindable keyboard shortcuts (persisted, auto-populated from action registry).
commandPaletteStore (commandPalette.ts)
Command palette visibility and search state.
activityDashboardStore (activityDashboard.ts)
Activity center (bell dropdown) visibility.
prNotificationsStore (prNotifications.ts)
PR state transition notifications (merged, closed, blocked, CI failed, etc.).
userActivityStore (userActivity.ts)
Tracks last user activity timestamp. Used for merged PR grace period calculations.
worktreeManagerStore (worktreeManager.ts)
Worktree Manager overlay state and selection.
State Shape:
| Field | Type | Description |
|---|---|---|
isOpen | boolean | Overlay visibility |
selectedIds | Set<string> | Multi-select worktree IDs |
repoFilter | string | null | Filter by repo path |
textFilter | string | Free-text search filter |
Actions: open(), close() (resets all state), toggle(), toggleSelect(id), selectAll(ids), clearSelection(), setRepoFilter(path), setTextFilter(text).
agentConfigsStore (agentConfigs.ts)
Per-agent configuration (spawn args, environment overrides).
editorTabsStore (editorTabs.ts)
Open code editor tabs (CodeEditorTab).
activityStore (activityStore.ts)
Session activity history and timeline data. Mutations before the first successful activity load remain pending in memory. After hydration merges stored and live items, one save persists the latest merged list without a readiness error. A failed load keeps the pending save for a later successful hydration; ordinary post-load mutations retain the 300 ms debounce on desktop and browser clients.
branchSwitcher (branchSwitcher.ts)
Branch switch state and loading indicators.
terminalOwnership (terminalOwnership.ts)
Which repo owns a terminal. TerminalData.repoPath is the record; the branch
terminals[] arrays are a display index derived from it, so a wrong placement is
repairable instead of permanent. null means no registered repo claimed the cwd —
the tab is parked in whatever repo was active so it stays visible, and the null
marks the placement as a guess.
| Function | Use |
|---|---|
reconcileTerminalOwnership(terminalId?) | Ask “who owns this?” again. For answers that genuinely changed: repos loaded, one added or removed, a worktree appeared, a branch renamed. Omit the id to sweep every terminal. |
reclaimParkedTerminal(terminalId) | The only thing an OSC 7 cwd change may trigger. No-op unless repoPath === null. |
A cd does not re-home an owned tab. The tab belongs to the repo it was
opened in; the directory the shell sits in does not revoke that. Calling the full
reconcile from the cwd handler moved tabs out from under the user, because three
states answer “where am I” and only one moved: activeRepoPath stayed put, so the
sidebar and the tab bar (which filters on it) kept showing the old repo while the
tab left the strip — and TerminalArea renders on terminalsStore.activeId alone,
so the pane went on drawing a terminal belonging to a repo nobody had selected.
Agents cd across repos constantly, which is why it read as the app switching repo
on its own. Only a parked tab is settled by a cd, because for it the question was
still open.
Parking says which repo is missing. An MCP-spawned agent inherits its parent’s
cwd, so sessions land in worktrees of repos the user never registered; the tab was
then filed under whichever repo had focus, and the only trace was a warning naming
the cwd. unregisteredRepoRootFor(cwd) (utils/repoOwnership.ts) turns that cwd
into the directory to register — …/gate-os__wt/poc-0001 → …/gate-os via the
__wt convention, otherwise the path itself — and assignSessionToRepoBranch
puts it in the warning and in one deduped toast. It is a guess for the user to act
on, never a placement: resolveRepoOwnerIn remains the single answer to “who owns
this tab”, and registering the repo lets reconcileTerminalOwnership move the tab
home by itself. Auto-registering instead was rejected — addRepository calls
setActive(), which would yank the user’s focused repo from a background event,
the exact failure the paragraph above describes.
contextMenuActionsStore (contextMenuActionsStore.ts)
Dynamic context menu action registration.
progressStore (progress.ts)
progressOnly is an optional list scope used by embedded mobile Progress. Changing it clears list entries/cursor, invalidates older requests and refetches; Flow requests do not inherit this filter.
Transport-neutral presentation state for Progress. It selects the active PTY when available and retains a repository aggregate view. It holds the selected scope’s entry list and its divider timestamp frozen while that scope is shown. Switching scopes loads the new mark; closing records every visited scope.
It queries on open, for the one project the dialog shows — not once per
registered repository, which is what made the old panel fire a request per repo
and answer with a red block for each one that no longer existed. Boot reads
nothing at all. Each read requests at most 100 entries. nextCursor is an
exclusive entry ID returned by the backend, and loadOlder reads one page on
demand with the current filters. Refreshes replace the list with the newest
page. A request epoch discards stale reads after a refresh or selection change;
the loading state prevents concurrent older-page appends.
The unread count is the number of progress-recorded pushes that arrived while
the dialog was closed, reset on open. It is deliberately not a query: the
persistent record of where the reader stopped is the divider.
view selects List or Flow. The Flow view’s data lives in state.flows,
per project, and is read with progress_flow for the selected scope whenever
the Flow view is showing and something changes (open, PTY switch, live entry).
The list is read in both views because it carries the divider and deletion.
fetchFlowDetail fetches one subagent arrow’s full text on demand.
A Progress toast opts out of the generic MESSAGES mirror because the bell has its
own aggregate row, and it is silent — a blocked entry is not automatically a
demand for attention. Its source PTY id lets the repo action activate the
reporting terminal and its workspace; if that terminal has closed, the action
opens the repository and logs why it could not focus the terminal. intent,
delegated and message entries toast nothing: they are what an agent set out
to do or said to another agent, not a result. Failures stay on the affected
project as one line instead of being rendered as an empty feed.
errorLog (errorLog.ts)
Error ring buffer and error panel state.
pluginStore (pluginStore.ts)
Loaded plugin instances and lifecycle state.
registryStore (registryStore.ts)
Remote plugin registry cache and install state.
repoDefaults (repoDefaults.ts)
Default settings applied to newly added repositories.
tabManager (tabManager.ts)
Tab ordering, branch-key mapping, and tab persistence logic.
One ordering implementation. reorderIds (splice source before/after target) and
orderedThenRemainder (known order first, never-dragged ids appended) are the only
ordering code in the app. Both display orders call them: each store’s own _order
via reorderByIds / getVisibleIds, and tabOrderingStore — the single cross-kind
list that spans terminals, diffs, markdown and editor tabs, which the tab bar reads in
the terminals-first and free ordering modes. A per-store _order cannot express
that list, because a drag between two kinds moves an id across store boundaries.
tabOrderingStore is only correct while the stores keep it populated: _addTab,
_addTabBackground, remove, clearAll and _clearWhere mirror into it, and
terminals.ts (outside the factory) does the same from its add and remove. Skip
that wiring and the list stays empty, reorder finds neither id and returns, and every
drag across tab kinds silently does nothing. Pinned by
src/__tests__/stores/tabOrderWiring.test.ts.
Terminal order itself is NOT here: it lives in repositoriesStore, per repo and per
branch, and is persisted. tabOrderingStore holds terminal ids so a cross-kind drag
can place them, but the branch list stays the source of truth for terminals alone.
Exclusive pane activation. TerminalArea renders terminals, diffs, markdown and
editors as four independent For lists, each marking its pane active from its
OWN store’s activeId — so “only one pane shows” is a cross-store invariant.
createTabManager registers a deactivator per store (registerPaneDeactivator);
terminals.ts registers its own since it doesn’t use the factory. Activating a
tab — setActive(id) with a non-null id, or _addTab — calls
activatePaneExclusively(storeName), which clears every other store’s activeId.
setActive(null) and the _addTabBackground variants are local: a background
open must not yank the user out of the pane they’re in.
Call sites therefore must NOT hand-roll setActive(null) on the other stores.
This replaced the useTabActivationSync hook, which enforced the same rule from
deferred on(activeId) effects: an effect keyed on a change cannot enforce an
invariant that has to hold on every activation request, so re-activating an
already-active tab (Edit on a file whose editor tab was already the active one)
wrote the same value, fired nothing, and left the other pane rendered underneath.
Pinned by src/__tests__/stores/paneExclusivity.test.ts.
appLogger (appLogger.ts)
Centralized logging — replaces direct console.* calls. Writes all levels and their data to the local ring buffer and surfaces them in ErrorLogPanel. Info, warn, and error messages also reach the browser console without data objects. Debug messages reach the console only while window.__TUIC__.setPerfDebug(true) is active; they also omit data objects. Info, warn, and error entries continue to reach the Rust log ring and /logs, including serialized data, for diagnostics such as tuic-health.sh. The only mirrored debug records are source dictation messages starting with Browser dictation lifecycle:: at most six content-free records per take, in the diagnostic audience. Other debug entries remain local.
debugRegistry (debugRegistry.ts)
Dynamic snapshot registry for MCP invoke_js introspection. Stores self-register a snapshot function at init time, exposed on window.__TUIC__ as stores() (list names) and store(name) (get snapshot).
Registered stores: github, globalWorkspace, keybindings, notes, paneLayout, repositories, settings, tasks, ui.
Adding a new store — append 2 lines at the end of the store file:
import { registerDebugSnapshot } from "./debugRegistry";
registerDebugSnapshot("storeName", () => ({ /* fields to expose */ }));
Each store decides what to expose — no need to modify debugGlobals.ts.
remoteAcp (remoteAcp.ts)
Keeps pending ACP permissions and elicitations scoped to their owning daemon. Only interaction, ready, and settled notices advance snapshot revisions; unrelated card notices leave in-flight permission refreshes valid. Settlement and disconnect invalidate obsolete responses before removing their pending requests.
automations
src/stores/automations.ts exposes automationsUi for dialog visibility and
createAutomationsStore(adapter) for dialog-scoped state. It keeps failed-write
drafts, ignores obsolete previews and history replies, and reports Run now
receipts without claiming that a skipped run started. Pause and Resume send only the definition id through atomic backend actions;
they preserve both newer agent edits and an unsaved local prompt. Once stores
a local wall-clock string and uses backend preview_definition for UTC
occurrences and completion evidence. The backend owns validation, cron,
capacity, execution and durable history; the adapter owns transport.
Notice navigation reloads current definitions before exposing an editor; historical
run snapshots are never saved as replacement definitions. Deleted definitions
leave saved run details visible without an editable draft.
Automation all-run history uses 20-row pages plus one backend lookahead row. loadRuns reads both backend summaries with the page and rejects stale replies. Definition deletion does not remove the all-history view. The transport adapter accepts an explicit remote connection so global history and summaries do not fall back to the local ledger.
Automatic agent toast cards (#1760-bab7)
MCP toast notices show a transient card only while their origin terminal tab is active. Settings → Notifications → Show cards from the active terminal defaults on and is saved per client; turning it off restores urgent-only cards. Urgent notices always show a card, and notices without an origin session remain bell-only unless urgent. The listener reads terminalsStore.state.activeId at arrival; notificationsStore.state.autoToastCards is stored under tui-commander-auto-toast-cards in localStorage. Bell deduplication, sound and terminal navigation are preserved.
Transcript view preference
transcriptPreferences stores the shared terminal Chat and AI Chat new-text indicator toggle in client localStorage (tui-commander-new-text-indicator, default on). Desktop Appearance → Chat and mobile Settings edit the same client preference. It does not write backend configuration. The Transcript compares entry identities and text lengths to detect arrivals while detached, clears unread state when content is replaced, and follows in-place streamed text while attached.
Background entry uses repositoriesStore.snapshotTerminals() followed by
flushSave() to await both the in-flight save and the newest queued snapshot.
Only then does the main WebView acknowledge snapshot-now. A persistence error
is logged and leaves the acknowledgement pending for the backend timeout.
Tasks notice preferences use uiStore.tasksViewPreferences: a default-off policy and per-provider/account/item follow state with comment baselines. Existing detail refreshes send snapshots to Rust through compare_work_item_comments; native delivery reuses the PR notice service. No additional store or provider poller is created.
The settings Voice picker combines speechVoices (installed) with the language-scoped voice entries in speechAssets (downloads); a configured missing catalogue voice remains visible.
TerminalData.providerRecovery is an optional transient native-ego recovery
snapshot. useAgentPolling.applySessionState applies it from both lifecycle
catch-up and push snapshots; omission clears it. It never changes shell busy
semantics, awaiting state, or turn completion.
Settings reload coordination
services/settingsRefresh.ts owns one disposable settings-event subscription per window. Readers register a section and optional remote connection, plus separate read and non-saving apply functions. It coalesces same-turn hints, deduplicates each owner/section generation, invalidates older in-flight reads and refetches on SSE resync. Replacement reads wait for the invalidated operation to settle, crossing the IPC read-deduplication boundary. A remote-machine hint only reaches readers registered for that connection.
App settings, notifications, preferences, repository defaults and overrides, registration metadata, agent configurations, prompts, pane layout, tunnels, connection metadata and upstream lists adopt reads without bootstrap migration. Mounted owner pages also refresh GitHub, ego, Telegram and plugin settings. Dirty form fields remain local; same-field conflicts produce a content-free notice. createConfigDeltaWriter.adopt advances the backend baseline. The existing save tail rebases queued edits onto that baseline: unrelated local changes still persist, while conflicting remote leaves are not overwritten automatically. Component-local launch-instruction drafts also survive incoming saved values until blur or explicit reset.
Pane layout reads apply the Rust owner’s defaults for omitted root, groups and activeGroupId before baseline adoption and disk restoration. Direct restore calls use the same defaults. Restore batches tree, groups, focus and revision publication so reactive consumers see a complete layout, while reconciliation keeps unchanged group and tab identities.
Snapshot adoption merges object leaves. Arrays are atomic owner values: concurrent changes to the same list retain the local list and report a conflict instead of guessing an index-based merge. A remote disconnect cancels in-flight adoption; reconnect clears that owner’s generation cursor and fetches a fresh snapshot. Successful daemon mirror stream subscriptions and owner-scoped lag notifications also trigger this resync, even when the health status stayed connected.
Startup workflow state versus Settings state
Settings startup workflows separates device-login state, human confirmation, owner CAS revisions and process-local invalidation generations. A terminal command exiting is not authentication success. services/egoLogin.ts remains the UI login entry point. Schema-only consumers use the typed Ego owner begin_login/login_status workflow; status reads the configured credential owner after termination and provider refresh determines the displayed model state. The typed inspector blocks another write after partial/unknown persistence until authoritative readback, and retains a dirty draft’s original CAS revision across incoming refreshes.
The dictation store subscribes separately to voice configuration and
corrections dictionary generations. Correction refresh calls
get_correction_map without saving; the Voice page’s new-entry text remains
component-local and is not overwritten. Both subscriptions are disposed together.
Terminal ownership and creation provenance are independent: TerminalData.isRemote reflects a configured remote connection_id; isExternallyCreated preserves the backend is_remote HTTP/MCP creation flag for worker-tab cleanup, decoration and completion policy. Local session-created events set only creation provenance; startup reconciliation derives ownership from the connection, not the launch transport. Both live creation and reconnect retain the backend-issued tuic_session as tuicSession. Caller-bound worktree declarations use this stable identity to place a newly spawned tab without changing its actual cwd.
Native story controls retain the QA-only visibility filter through storiesUi, alongside All, Open and Closed. The backend derives filter membership and Kanban columns.
Ideas synchronization
ideasStore.hydrate() subscribes once to ideas-changed on desktop or SSE, with reconnect resynchronization. Reads wait for queued local persistence. A read raced by a newer mutation or read is discarded and retried when needed. Hydration never saves. The backend merges save_notes baselines by stable idea id and changed field, so an agent addition absent from a panel snapshot is not a deletion.
Terminal Chat pending receipt matching uses the Rust-cleaned pendingTexts returned by chat_view_snapshot. Candidates and results retain request order; the client binds them to the captured local send IDs, so an in-flight rollback cannot acknowledge a newer send. Original submitted text remains presentation-only.
AI Chat voice bindings
chatVoiceTargets() reads host-owned ACP attachments through get_voice_targets, so the Voice picker does not depend on the current window holding the chat stream. stopChatVoice(sessionId) releases only that chat binding; without a session id it releases the AI Chat binding when the last panel view closes. Terminal bindings are not affected. Spoken prompts enter the existing backend ACP prompt queue, not the terminal store or Compose.
Hooks Reference
Hooks contain business logic and side effects, bridging stores and Tauri commands.
useOpenMarkdownPublication
src/hooks/useOpenMarkdownPublication.ts observes main-window desktop file tabs and sends
metadata to sync_open_markdown_tabs. It serializes writes, coalesces rapid
changes and retries failures. Browser and mobile documents do not publish.
The Rust snapshot is temporary and contains no file contents.
useAppInit
File: src/hooks/useAppInit.ts
Initializes the application on startup.
export function initApp(deps: AppInitDeps): Promise<void>
What it does:
- Hydrates all stores from Rust backend (settings, repos, UI, prompts, etc.)
- Detects installed binaries (Claude, Codex)
- Applies platform CSS class (
platform-darwin,platform-win32,platform-linux) - Sets up close handler (quit confirmation dialog)
- Starts GitHub polling
- Loads custom fonts from settings
- Refreshes dictation config
usePty
File: src/hooks/usePty.ts
Low-level PTY session management. Wraps Tauri PTY commands.
Return API
| Method | Description |
|---|---|
canSpawn() | Check if under session limit (50) |
createSession(config) | Create PTY session, returns session ID |
createSessionWithWorktree(ptyConfig, wtConfig) | Create worktree + PTY |
write(sessionId, data) | Write to PTY |
sendCommand(sessionId, text, agentType, submit?) | Insert through the shared command path; optionally withhold Enter for review |
resize(sessionId, rows, cols) | Resize PTY |
pause(sessionId) | Pause reader thread |
resume(sessionId) | Resume reader thread |
close(sessionId, cleanupWorktree) | Close PTY session |
getStats() | Get orchestrator stats |
getMetrics() | Get session metrics |
listWorktrees() | List managed worktrees |
getWorktreesDir() | Get worktrees directory |
listActiveSessions() | List all active sessions |
useSmartPrompts
File: src/hooks/useSmartPrompts.ts
Resolves Smart Prompt variables and routes inject, shell and headless
execution. For inject mode, explicit Insert/Run choices take precedence over
autoExecute; prompts without that persisted field retain their legacy target
default. Only actions that will submit are idle-gated. PTY delivery always uses
usePty.sendCommand, including review-only fallback with submit=false.
api mode has no executor. canExecute refuses it with a reason naming
#787-ee50 rather than falling through to inject, and resolveHeadlessAgent
returns api as its own answer so a headless prompt pointing at the removed
External API slot is refused the same way. The mode stays a value a saved prompt
can hold, and stays an option the editor offers, because ego restores it — but
silently running the prompt as something the user did not choose is worse than
saying where it went.
useGitOperations
File: src/hooks/useGitOperations.ts
High-level git workflows: branch switching, worktree creation, repo management.
Worktree removal holds a per-repository/workspace lock through preflight, confirmation and cleanup, and releases it in finally. A failed initial confirmation propagates its error, preserves the workspace and terminals, and allows a later retry.
Dependencies
interface GitOperationsDeps {
createTerminal: (repoPath, branch, opts?) => Promise<void>;
closeTerminal: (id) => void;
// ... other callbacks from App.tsx
}
Return API
| Method | Description |
|---|---|
handleBranchSelect(repoPath, branch) | Switch to branch (creates worktree if needed) |
handleAddTerminalToBranch(repoPath, branch) | Add terminal to existing branch |
handleRemoveRepo(repoPath) | Remove repository from sidebar |
handleRemoveBranch(repoPath, branch) | Remove worktree and branch |
handleRenameBranch(oldName, newName) | Rename git branch |
handleAddRepo() | Open folder dialog, add repository |
handleAddWorktree(repoPath) | Create worktree with generated name |
handleNewTab() | Create new tab for active branch |
handleRunCommand(forceDialog, openDialog) | Execute or configure run command |
handleRepoSettings(repoPath, openPanel) | Open repo-specific settings |
refreshAllBranchStats() | Refresh diff stats for all branches |
activeWorktreePath() | Get active worktree path |
activeRunCommand() | Get active run command |
Signals
| Signal | Type | Description |
|---|---|---|
currentRepoPath() | string | null | Active repository path |
currentBranch() | string | null | Active branch name |
repoStatus() | string | Repository git status |
branchToRename() | {repoPath, branchName} | null | Branch rename state |
useTerminalLifecycle
File: src/hooks/useTerminalLifecycle.ts
Terminal tab management: create, close, zoom, copy/paste, reopen.
Return API
| Method | Description |
|---|---|
createNewTerminal() | Create terminal for active branch |
closeTerminal(id, skipConfirm?) | Close terminal (with confirmation) |
closeOtherTabs(keepId) | Close all except one |
closeTabsToRight(afterId) | Close tabs after given ID |
reopenClosedTab() | Reopen last closed tab |
navigateTab(direction) | Switch to prev/next tab |
clearTerminal() | Clear active terminal |
copyFromTerminal() | Copy selection from terminal |
pasteToTerminal() | Paste to active terminal |
zoomIn() / zoomOut() / zoomReset() | Font size controls |
activeFontSize() | Get active terminal’s font size |
handleTerminalFocus(id) | Handle terminal focus event |
handleTerminalSelect(id) | Handle tab click |
terminalIds() | Memo: terminal IDs for active branch |
useKeyboardShortcuts
File: src/hooks/useKeyboardShortcuts.ts
Registers global keyboard event listener with platform-aware modifiers.
interface ShortcutHandlers {
newTab: () => void;
closeTab: () => void;
toggleSidebar: () => void;
// ... 30+ handlers
}
Returns cleanup function to remove listener on unmount.
useNativeKeyCombo
File: src/hooks/useNativeKeyCombo.ts
Feeds natively-captured keys into a shortcut recorder. macOS never delivers F13–F20
to WKWebView, so a keydown listener sees nothing at all and those keys look unbindable
even though keyEventToCombo, validateGlobalHotkeyCombo and the global-hotkey crate
all accept them. src-tauri/src/native_keys.rs catches them with an NSEvent monitor and
re-emits native-key-down; this hook turns that back into the same combo string the DOM
path produces.
useNativeKeyCombo(active: () => boolean, onCombo: (combo: string) => void): void
export function nativeKeyToCombo(payload: NativeKeyDown): string
- The listener is attached only while
active()is true, so these keys keep their normal behaviour everywhere else in the app. nativeKeyToCombomirrorskeyEventToCombo’s modifier order (Cmd, Ctrl, Alt, Shift) — the two are compared against each other for conflicts and persisted to the same store, so a mismatch would make one physical chord compare as two different combos.- No-op outside Tauri (
isTauri()); the event does not exist in browser mode. - Consumers:
KeyComboCapture(Global Hotkey) andKeyboardShortcutsTab(per-action recording), both routing the result through the same conflict check as the DOM path.
useGitHub
File: src/hooks/useGitHub.ts
GitHub status for a single repository.
Return API
| Signal/Method | Description |
|---|---|
status() | Reactive GitHub status |
loading() | Loading state |
error() | Error message |
refresh() | Force refresh |
startPolling() / stopPolling() | Polling control |
useRepository
File: src/hooks/useRepository.ts
Git repository operations (lower level than useGitOperations).
Return API
| Method | Description |
|---|---|
getInfo(path) | Get RepoInfo (name, branch, status) |
getDiff(path) | Get full git diff |
getDiffStats(path) | Get additions/deletions counts |
getChangedFiles(path) | List changed files with stats |
getFileDiff(path, file) | Get single file diff |
openInApp(path, app) | Open in IDE |
renameBranch(repoPath, old, new) | Rename branch |
createWorktree(base, branch) | Create worktree |
removeWorktree(repo, branch) | Remove worktree |
getWorktreePaths(repo) | Get worktree paths |
listMarkdownFiles(path) | List .md files |
readFile(path, file) | Read file contents |
generateWorktreeName(existing) | Generate unique worktree name |
useQuickSwitcher
File: src/hooks/useQuickSwitcher.ts
Held-key branch quick-switcher (Cmd+Ctrl on macOS, Ctrl+Alt on Win/Linux). Number keys select branches before configurable actions. Configured letter actions, including Ctrl+Alt+V on Windows/Linux, still dispatch while the chord is held. The shortcut dispatcher captures handled quick-switcher chords before terminal input so the same key does not also write PTY bytes.
switchToBranchByIndex(index: number): void
useSplitPanes
File: src/hooks/useSplitPanes.ts
Split terminal pane management.
handleSplit(direction: "vertical" | "horizontal"): void
useConfirmDialog
File: src/hooks/useConfirmDialog.ts
Confirmation and info dialogs using Tauri dialog plugin.
| Method | Description |
|---|---|
confirm(options) | Show Yes/No confirmation |
info(title, message) | Show info dialog |
error(title, message) | Show error dialog |
confirmRemoveWorktree(branch) | Confirm worktree removal |
confirmCloseTerminal(name) | Confirm terminal close |
confirmRemoveRepo(name) | Confirm repo removal |
useDictation
File: src/hooks/useDictation.ts
Push-to-talk dictation integration. The destination and selection are captured before any asynchronous work. Explicit editors take priority; transcript or BODY focus in terminal Chat targets that terminal’s Compose editor. CodeMirror receives a transaction, preserving the surrounding draft. Terminal Chat Compose also honors auto-send through its editor-owned submit callback, sharing normal Send deduplication and successful-draft cleanup; ordinary editors remain review-only. CLI uses the captured PTY session and its existing auto-send semantics, even if the active tab changes.
Detached AI Chat mounts the same hook and hotkey lifecycle in its own WebView, hydrates the shared dictation configuration, and supplies its composer as the fallback when its transcript has focus. Main-window callers supply no fallback, so terminal and form targeting stay unchanged. Native Fn chooses the focused supported window at key-down; focus changes do not move the captured target.
A removed target, replaced session, changed draft, or failed insertion retains the transcript in a sticky error message and the Messages bell. It never falls through to another destination. Start and delivery logs contain the recording id, target kind, terminal/session identity, character count and outcome, without transcript text.
| Method | Description |
|---|---|
handleDictationStart() | Start recording |
handleDictationStop() | Stop and transcribe, inject text |
useAgentDetection
File: src/hooks/useAgentDetection.ts
Detect installed AI agents and IDEs.
| Method | Description |
|---|---|
detectAll() | Detect all known agents |
detectAgent(type, binary) | Detect specific agent |
isAvailable(type) | Check if agent is available |
getAvailable() | Get all available agents |
getDetection(type) | Get detection result (path, version) |
useFileDrop
File: src/hooks/useFileDrop.ts
Handles external file drag & drop using Tauri’s native onDragDropEvent API (not the HTML5 File API, which provides no paths in Tauri webviews).
Signals
| Signal | Type | Description |
|---|---|---|
isDragging() | boolean | true while files are being dragged over the window |
Behaviour
A folder target takes precedence. The File Browser panel supplies its connection id to descendant folder rows. Local drops call fs_transfer_paths; remote drops call the local Rust fs_transfer_remote_paths coordinator with that id, and always use copy semantics. Recursive-directory confirmation retains the connection id when retrying.
- Active PTY session — dropped file paths are written to the terminal as space-separated quoted strings (enables Claude Code image drops)
- No active PTY —
.md/.mdxfiles open in the Markdown viewer; all other files open in the Code Editor
A global dragover/drop preventDefault on document prevents the Tauri webview from treating drops as browser navigation (which would replace the UI with a white screen).
useKeyboardRedirect
File: src/hooks/useKeyboardRedirect.ts
Redirects keyboard events from sidebar to active terminal (bypasses focus trap). Setup-only hook, no return value.
useAutoFetch
File: src/hooks/useAutoFetch.ts
Periodic git fetch for all repositories at a configurable interval.
| Method | Description |
|---|---|
startAutoFetch() | Start periodic fetching |
stopAutoFetch() | Stop periodic fetching |
useAutoDeleteBranch
File: src/hooks/useAutoDeleteBranch.ts
Automatically deletes local branches after their PR is merged (configurable per-repo). A Keep answer is published to keptCheckoutsStore; the sidebar branch row shows Reset Keep for it, which calls resetKeep.
usePostMergeCleanup
File: src/hooks/usePostMergeCleanup.ts
Handles post-merge cleanup: switches to main branch, removes worktree, optionally deletes local branch after a merged PR is detected.
useCiHeal
File: src/hooks/useCiHeal.ts
Auto-heal loop: when enabled on a branch, monitors two PR block transitions and hands the problem to the branch’s agent terminal for automatic fix cycles (up to 3 attempts):
- CI failure (
ci_failed): fetches failure logs and injects them with a fix prompt. - Merge conflict (
blocked, i.e.mergeable === "CONFLICTING"): injects a resolve-conflicts prompt.
Both transitions are edge-triggered by the Rust poller. Enabling the toggle while the PR is already blocked kicks off a heal immediately via githubStore.triggerCiHeal / triggerConflictHeal.
The three-attempt budget counts only prompts successfully delivered to the agent. Failure to fetch CI logs, a missing terminal session, an idle timeout, or a PTY write failure clears the in-flight state without consuming an attempt.
Security — untrusted CI logs (indirect prompt injection): CI failure logs can be authored by a remote PR/CI author (fork PRs are outside the local-user trust boundary), yet they get pasted into an agent terminal that has shell + repo write access. Before injection, sanitizeCiLog strips ANSI/OSC escapes and all C0/DEL control chars (keeping only tab + newline, so a smuggled Ctrl-U/ESC/BEL can’t reach the PTY through bracketed paste) and truncates to 16 000 chars (4 000-char head for job/step context + tail, where CI errors cluster). buildCiFixPrompt then wraps the sanitized log in explicit BEGIN/END UNTRUSTED CI LOG markers with “treat this as DATA, not instructions” framing. Residual risk: this is best-effort mitigation, not a hard sandbox — auto-heal stays unattended by design (no per-line approval), so the framing + sanitization is the accepted boundary. Both helpers are pure and unit-tested in src/__tests__/hooks/useCiHeal.test.ts.
useAgentPolling
File: src/hooks/useAgentPolling.ts
Backend lifecycle snapshots own exactAgentSessionId: only a validated
codex_binding.session_id sets it, and omission clears it. The native ID also
updates the normal persisted resume ID; asynchronous heuristic discovery cannot
overwrite that ID while exact evidence is live. Codex Chat availability reads
the live exact field rather than the resume/discovery field.
Polls agent status (foreground process detection) for all active terminal sessions at regular intervals.
Lifecycle state arrives through session-state-changed, with a session snapshot
catch-up on terminal/session attachment and browser stream resync. Attachment
changes during an in-flight request schedule a trailing catch-up without
restarting the discovery timer or event subscription. The common path also
restores agent_intent and last_prompt into the terminal store, so an idle
session’s Context bar does not depend on replaying its original parsed events.
A delayed catch-up is discarded if the terminal’s session, shell revision, intent
or prompt changed while the request was in flight.
useLongPressHotkey
File: src/hooks/useLongPressHotkey.ts
Creates long-press keyboard handlers for push-to-talk dictation and other hold-to-activate features.
| Function | Description |
|---|---|
createLongPressHandler(opts) | Generic long-press handler with configurable thresholds |
createLongPressHandlerFromHotkey(hotkey, opts) | Long-press handler bound to a specific hotkey combo |
useWorktreeSwitchPrompt
File: src/hooks/useWorktreeSwitchPrompt.ts
Handles worktree lifecycle events. A newly created worktree can be opened or declined; when an agent is active, opening the worktree selects its own terminal without changing the agent terminal’s branch or working directory. Removed worktrees are pruned from the sidebar.
useFileBrowser
File: src/hooks/useFileBrowser.ts
File browser panel logic: directory listing, file operations (create, delete, rename, copy), content search, and gitignore management.
Automatic agent toast cards (#1760-bab7)
MCP toast notices show a transient card when their origin terminal is not active or the window is unfocused. Settings → Notifications → Show cards from other terminals defaults on and is saved per client; turning it off restores urgent-only cards. Urgent notices always show a card, and notices without an origin session remain bell-only unless urgent. The listener reads terminalsStore.state.activeId and document.hasFocus() at arrival; notificationsStore.state.autoToastCards is stored under tui-commander-auto-toast-cards in localStorage. Bell deduplication, sound and terminal navigation are preserved.
Desktop close decisions come from Rust through close-dialog; useAppInit forwards the request to the close dialog store. There is no JavaScript onCloseRequested interceptor or frontend PTY teardown on desktop Quit.
Utilities
Pure functions and helpers in src/utils/.
Branch Sorting (branchSort.ts)
compareBranches(a: SortableBranch, b: SortableBranch, aPr?: BranchPrState, bPr?: BranchPrState): number
Sort priority:
- Active branch first
- Main branches (main, master, develop, trunk)
- Branches with open PRs (alphabetical)
- Feature branches without PRs (alphabetical)
- Merged/closed PR branches (last, alphabetical)
Note: This is a frontend wrapper around Rust’s sort_branches(). The sorting rules are implemented in Rust; this utility provides the TypeScript interface.
CI Ring Segments (ciRingSegments.ts)
computeCiRingSegments(
failed: number,
pending: number,
passed: number,
circumference: number,
colors: { passed: string, failed: string, pending: string }
): CiRingSegment[]
Calculates SVG arc segments for the circular CI status indicator. Returns array of segments with offset, length, and color for each status category.
PR State Mapping (prStateMapping.ts)
classifyMergeState(mergeable?: string, mergeStateStatus?: string): StateLabel | null
classifyReviewState(reviewDecision?: string): StateLabel | null
Maps GitHub merge state and review decision to display labels with CSS classes. Frontend mirror of Rust’s classify_merge_state() / classify_review_state().
Terminal Utilities
sendCommand.ts
sendCommand(writeFn, text, agentType, shellFamily, submit?, sessionId?) is the single
frontend path for terminal command insertion and submission. It applies
platform-aware line clearing, bracketed paste for multi-line text, and the
agent-specific delay before Enter (200 ms for Codex to clear its 120 ms paste
suppression window; 50 ms for other known agents). With a session ID and no
detected type, it probes the foreground process: a non-shell process gets
separate Ctrl-U and text writes and the 200 ms gap. A failed probe keeps the
existing shell framing but delays Enter. Passing submit=false keeps the text
editable and does not write Enter.
terminalFilter.ts
filterValidTerminals(branchTerminals: string[], existingTerminalIds: string[]): string[]
Filters branch’s terminal list to only include IDs that exist in the terminals store. Handles cleanup of stale references.
terminalOrphans.ts
findOrphanTerminals(terminalIds: string[], branchTerminalMap: Record<string, string[]>): string[]
Finds terminals that exist in the store but aren’t associated with any branch. Used for cleanup.
ptyCapture.ts
ptyCaptureStore drives the raw PTY capture tap from the UI: isRecording(sessionId),
bytes(sessionId), refresh(), and toggle(sessionId). It backs the Capture Session
item in the tab context menu, which appears only while isPerfDebug() is on.
The tap has to be armed before a reproduction — the per-session output ring holds only the last 8 KB, so a state-detection bug reported after the fact has already lost its evidence. That is why the control sits one click from the misbehaving tab instead of in a curl the reporter has to look up.
The tap is one global switch that POST /diagnostics/capture and other windows can also
flip, so refresh() runs on every context-menu open rather than trusting the last value this
window wrote. Starting always opens a fresh file, so the byte count reported when stopping
belongs to that recording alone.
Path Utilities (pathUtils.ts)
Cross-platform path helpers that handle both / (Unix) and \ (Windows) separators. All path comparison and construction in the frontend MUST use these instead of raw string operations.
| Function | Description |
|---|---|
isAbsolutePath(p) | True for Unix /..., Windows C:\..., and UNC \\... paths |
normalizeSep(p) | Convert all backslashes to forward slashes |
pathStartsWith(path, prefix) | Directory-boundary-aware prefix check, separator-agnostic |
pathStripPrefix(path, prefix) | Strip prefix at directory boundary, returns relative portion |
joinPath(base, ...parts) | Join segments, stripping redundant separators |
pathParts(p) | Split by either separator |
pathBasename(p) | Last segment (filename or directory name) |
pathDirname(p) | Directory portion, preserving original separator |
replaceBasename(p, newName) | Replace last segment |
Forbidden patterns (use the helpers instead):
startsWith("/")→isAbsolutePath()path + "/"→joinPath().split("/").pop()→pathBasename()path.startsWith(prefix + "/")→pathStartsWith()
File Preview (filePreview.ts)
classifyFile(filePath: string): FileOpenTarget
Routes a file path to one of three open targets based on extension:
"markdown"—.md,.mdx"preview"— documents (PDF, HTML), images (PNG, JPG, GIF, WebP, SVG, AVIF, ICO, BMP), video (MP4, WebM, MOV, OGG), audio (MP3, WAV, FLAC, AAC, M4A), text/data (TXT, JSON, CSV, LOG, XML, YAML, TOML, INI, CFG, CONF)"editor"— everything else
Used by App.tsx (clickable paths, Command Palette), useFileDrop.ts (drag & drop), and HtmlPreviewTab (preview routing).
Shell Utilities (shell.ts)
| Function | Description |
|---|---|
escapeShellArg(arg) | Escape string for safe shell argument |
isValidBranchName(name) | Validate git branch name format |
isValidPath(path) | Validate file system path |
Hotkey Utilities (hotkey.ts)
| Function | Description |
|---|---|
hotkeyToTauriShortcut(hotkey) | Convert display format to Tauri format |
tauriShortcutToHotkey(shortcut) | Convert Tauri format to display format |
Time Utilities (time.ts)
relativeTime(isoString: string): string
Formats ISO timestamp as relative time (e.g., “5 minutes ago”, “2 hours ago”, “yesterday”).
Main Index (utils/index.ts)
General utilities including:
- Platform detection helpers
- Path manipulation
- Theme conversion utilities
- Hotkey conversion helpers (display ↔ Tauri format)
Type Definitions (types/index.ts)
All shared TypeScript types are centralized in a single file. Key type groups:
Terminal Types
TerminalPane, TerminalRef, PtyOutput, PtyExit, PtyConfig, IPty, SessionState, SavedTerminal
Repository Types
RepoInfo, Repository
GitHub Types
GitHubStatus, PrStatus, CiStatus, CheckSummary, CheckDetail, BranchPrStatus, PrLabel
PR State Types
MergeableState, MergeStateStatus, ReviewDecision
UI Types
SplitNode, SplitDirection, AgentStats, DetectedPrompt, OrchestratorStats
Callback Types
PtyDataHandler, PtyExitHandler
Clipboard (utils/clipboard.ts)
writeClipboard and readClipboard use the desktop-only write_clipboard_text
and read_clipboard_text Tauri commands. These arboard commands bypass WebView
focus and user-gesture restrictions and the macOS Paste confirmation pill.
Failures reject the promise. Browser mode uses the client’s navigator.clipboard;
there is no HTTP route to the host clipboard. copyPathToClipboard keeps absolute
paths and shortens the home directory to ~.
Default-application opens
handleOpenUrl accepts only HTTP, HTTPS and mailto URLs. Desktop calls use
open_default_app; browser clients use window.open on their own machine.
openConfirmedLink serves owner clicks on network (UNC) and custom-scheme links
(isHandlerLink): it shows the exact target in the app confirmation dialog
(registered by App.tsx through registerLinkConfirm; Cancel is the default)
and only then calls open_default_app with kind: "handler". Without a
registered dialog it opens nothing. Handler failures show an error toast.
Browser clients open custom schemes with window.open and cannot open UNC paths.
openLocalPath sends trusted local paths to the same desktop command and does
not launch a host application in browser mode. Settings plugin documentation
links and File Browser default-app actions use these helpers. Reveal in file
manager remains the opener plugin’s separate native reveal operation.
The backend uses open::commands for platform selection and option-safe
arguments, then tuic_core::child_reaping::spawn_reaped for each launch. It does
not use the dependency’s detached fork. It returns after spawning, preserves
the application, and waits off the caller thread to reap the launcher.
Mobile resume diagnostics
The mobile entry checks the document after one animation frame on pageshow and
on a change to visible. An empty root or a shell wholly outside the visible
viewport produces an app warning with the URL, root child count, shell bounds,
visual viewport height and top offset, visibility state, and the last window
error since hide. Normal resumes are silent. The diagnostic does not reload or
change the page. Read it promptly through MCP debug logs: frontend warnings reach
the backend memory ring, not the daily log file (#1900-5ff6).
Transport Layer
The transport layer provides a unified IPC abstraction so the same frontend code works in both Tauri (native desktop) and browser (HTTP) modes.
Repository-owned calls resolve their machine from path arguments, including
project on the Project Progress commands. The remote backend owns the
journal; the local transport routes reads and writes to it.
OS drops are a cross-machine operation: desktop-only fs_transfer_remote_paths runs through local Tauri IPC, reads Finder source paths and streams bounded archives to /fs/upload-copy on the connection id supplied by the drop target. It is INTENTIONALLY_UNMAPPED: HTTP token holders must not trigger exfiltration of sources that cannot be gated to registered roots. It uses remote_runtime for the live endpoint and existing token. It must not route local source paths to the receiving daemon.
Files
| File | Purpose |
|---|---|
src/invoke.ts | Smart invoke() wrapper — zero overhead in Tauri |
src/transport.ts | Public transport entry point (re-exports) |
src/transport/http.ts | RPC routing, coalescing, cached IPC invocation and HTTP requests |
src/transport/ipc.ts | Event and PTY subscriptions, including their browser WS/SSE branches |
src/transport/sse.ts | One reference-counted browser event stream per backend, shared by both event APIs |
src/transport/commandTable.ts | Command-to-endpoint mappings and native/WS exclusions |
src/transport/types.ts | Shared transport and upstream MCP types |
src/transport/environment.ts | Shared Tauri environment detection |
invoke.ts
export function invoke<T>(cmd: string, args?: Record<string, unknown>): Promise<T>
export function listen<T>(event: string, handler: (event: Event<T>) => void): Promise<Unsubscribe>
Resolution: At module import time, detects if running in Tauri webview:
- Tauri mode: Delegates directly to
@tauri-apps/api/core.invoke()(zero overhead) - Browser mode: Maps command to HTTP endpoint via
transport.ts
In development, an exact local IPC Command <requested command> not found
rejection becomes a backend/frontend version mismatch error with manual restart
guidance. Both deduplicated reads and writes use this diagnosis. Other failures,
release builds, browser HTTP calls and remote-owner calls keep their original errors.
In-flight dedup (Tauri mode)
Concurrent identical calls for read-only commands in DEDUP_COMMANDS share a single IPC round-trip — the second caller gets the same Promise as the first, cleared on settle. Prevents the repo-changed fan-out storm where ~20 mounted components each spawned parallel git processes for the same repo. Mutations (stage/commit/push) are never deduped. Browser mode has the equivalent via isIdempotentRpc in transport.ts.
export function isTauri(): boolean
// Checks window.__TAURI__ existence
transport.ts
Command Mapping
Maps every Tauri command name to an HTTP method + path via a declarative COMMAND_TABLE. Each entry is a CommandTableEntry — an object { map } whose map(args, p) returns { method, path, body?, transform? }.
// Table-driven: each command maps to an HTTP request
const COMMAND_TABLE: Record<string, CommandTableEntry> = {
create_pty: { map: (args) => ({ method: "POST", path: "/sessions", body: args.config }) },
get_repo_info: { map: (args) => ({ method: "GET", path: `/repo/info?path=${enc(args.path)}` }) },
write_pty: { map: (args) => ({ method: "POST", path: `/sessions/${args.sessionId}/write`, body: { data: args.data } }) },
// ... ~80 commands
};
This replaces the previous 370-line switch statement with a flat lookup table for easier maintenance and review.
HTTP Response Semantics
Successful JSON responses preserve the backend’s decoded value exactly. In
particular, a literal null body is a valid result for commands whose Tauri
contract returns Option<T>; browser and PWA callers receive the same null
that desktop IPC returns for None.
A successful non-JSON response to a JSON RPC is rejected with the request URL
and content type; connection tokens are excluded from that URL. This prevents an
HTML page from becoming a remote picker’s home path. JSON bodies without a
content type remain supported. read_plugin_data also accepts text/plain
(or an omitted content type) and preserves those bytes as a string. HTML is
rejected for that route too.
A zero-length text or JSON body is not the same value and is rejected with the
command name in the error. Responses declared as JSON are also rejected when
their non-empty body is malformed, while non-success HTTP statuses retain their
status and command context. Binary application/octet-stream routes are the
deliberate exception: an empty buffer can be a valid terminal chunk.
The void log commands push_log and clear_logs declare allowNoContent.
Their HTTP 204 responses acknowledge a successful write and resolve without
a value. Other JSON commands still reject an empty response, including 204.
This acknowledgement lets the mobile logger drain its startup queue instead
of sending the first warning again on each later log call.
PTY Subscription
export function subscribePty(
sessionId: string,
onData: (data: string) => void,
onExit: () => void,
onParsedOrOptions?: ((event: WsParsedEvent) => void) | SubscribePtyOptions
): PtySubscription
- Tauri mode: Uses
listen("pty-activity-{id}")andlisten("pty-exit-{id}")Tauri events - Browser mode: Opens WebSocket to
/sessions/{id}/stream
PtySubscription is still callable to dispose the subscription — every existing
caller works unchanged — and carries pause() / resume() for a client that is
not on screen (src/mobile/utils/pageVisibility.ts wires them to
visibilitychange).
pause() is deliberately NOT unsubscribe() followed by a fresh
subscribePty(). Two things would break:
- The close handler reads codes 1000/1001 as a real session exit, so the view would print “session exited” and clear the screen on every tab switch.
- The consumed-line cursor is closure-private, so a fresh subscription replays from the mount offset and duplicates the whole scrollback.
Instead the paused socket is closed with the cursor kept alive, onExit stays
silent, pending reconnect backoff is cancelled, and resume() reopens from that
cursor. A paused subscription delivers nothing, and because the cursor only
advances on delivery, nothing is skipped either. On desktop there is no socket
to drop, so pause() suppresses delivery instead — the same observable
contract.
onData receives PTY output in browser/PWA mode only. Desktop sends no output
over IPC: the canvas renders from grid frames and plugin watcher lines are
assembled in Rust, so no desktop consumer needs the bytes.
For “is this session producing output”, use options.onActivity — a payload-free
pulse the backend throttles to ~1/s and delivers on both transports from one
signal (pty-activity-{id} on desktop, the {"type":"activity"} WS frame in the
browser). It is the only activity signal that works for a background tab: the
canvas stops acking grid frames while a terminal is hidden, so frame traffic
cannot stand in for it.
Shared browser event subscriptions
Browser listen() and subscribeEvents() share one SSE connection per backend
URL in each page. Two mobile tabs therefore use two long-lived HTTP connections,
not one for each session, Chat, Markdown, dictation or speech consumer. This
leaves capacity for state reads and permission answers under the observed
six-connection HTTP/1.1 budget. Tabs do not share JavaScript state; this is not a
guarantee for an unlimited number of tabs.
Startup registrations are coalesced. The server filter is the union of consumer
event types, widened in place with serialized POST /events/types requests.
Each consumer receives only its registered types. A late consumer receives its
onResync("connect") after its filter is live; reconnect restores the widened
filter before resync. lagged also requests a snapshot. The server cannot replay
missed events, so snapshots remain authoritative. Local HTTP-response events use
the same registry and never reach another backend’s consumers.
Unsubscribe is idempotent and removes only that consumer. The final unsubscribe closes the stream; a mount disposed before the queued open creates no connection. Late filter replies cannot resurrect a stream after cleanup. Desktop Tauri listeners are unchanged and do not use this SSE registry.
URL Building
export function buildHttpUrl(path: string): string
// Reads MCP port from config, builds http://localhost:{port}{path}
Design
The transport abstraction enables:
- Development: Run frontend with
pnpm devagainst the Rust HTTP server - Browser mode: Access TUICommander from a browser on another device
- Testing: Frontend tests can mock at the invoke level
- MCP integration: External tools use the same HTTP API
The abstraction is resolved once at module load — no per-call overhead in production Tauri mode.
The enqueue_agent_command mapper forwards optional idempotencyKey unchanged
to POST /sessions/:id/queue. Both transports return { accepted, typed, queued }.
A recognized retry has accepted: true even after the queue drained; typed
reports no new typing on that retry.
Telegram setup maps telegram_settings/telegram_setup to authenticated GET/PUT /config/telegram, with identical action payloads across IPC and HTTP. Mobile Settings mounts the same Telegram component.
Automations command
automation_action({input}) maps to POST /automations/action with {input}.
The action and all snake_case model fields pass through unchanged. The backend
returns the raw action result, including persisted definitions on save and full
runs on Run Now. Explicitly address the desired backend; no execution fallback
exists. The route is shared by desktop and headless hosts.
Terminal Features & Keyboard Shortcuts
Returning to terminal tabs
When you return to a terminal tab, it repaints the last visible viewport while it requests a fresh backend frame. Hidden tabs still release their canvas backing stores. Retained rows cover the viewport, not the full scrollback history.
Pending Session Chat prompts
Busy Session Chat sends wait in TUIC’s existing idle-gate queue on desktop and mobile. Each host-owned Pending prompt has Cancel and, for Claude, Codex and ego, a compact return-key Send now action. Send now uses one forced-steer flow for all three harnesses: reserve the next ready composer, send Escape to a working turn, confirm idle, then submit the selected full text before ordinary queued inputs or mail wakes. The tooltip reads Send now: stop the current request. An idle recipient skips Escape. A prompt already taken by the idle gate is not sent again, and a refused Send now keeps the prompt queued. Native CLI receipts from earlier direct sends remain read-only.
Mobile keeps the visible draft when you switch between Chat and CLI. Chat holds the draft locally; CLI streams it to the native composer. A switch transfers this composer’s known native draft without submitting it. Tab and history temporarily use the native composer, then return the result to the local Chat draft before a queued send.
On desktop, returning from Chat to CLI focuses the terminal input. You can type immediately after using the switch, closing Chat Compose, answering in CLI, or falling back from unavailable Chat. Only the active terminal restores focus, and an automatic fallback does not take the caret from an editable field outside that terminal.
Session Chat shows a pulsing Working… row after Send and while the terminal reports busy. It disappears when the terminal reports idle or awaits a question or permission answer. Desktop and mobile use the existing session state; Chat does not infer activity from the conversation text.
Consolidated reference for all terminal behaviors, keyboard shortcuts, and configurable features.
The desktop CLI | Chat switch uses shared toolbar density. In both modes it is centred on the Context header and stays above its bottom divider, without adding a separate row. Without Context, both modes reserve one shared control row so content cannot run beneath the switch. Switching modes keeps the switch and content at the same height. At touch widths up to 600px, the Context header and collapsed bar reserve a 48px row for the shared 44px switch; expanded Context keeps the same header clearance.
Terminal Find overlays the grid below the Context and CLI/Chat switch row. Search controls wrap within narrow panes without covering the view switch.
Answer gutters after resize
When scrollback reflow is disabled, widening a terminal keeps existing text in its original physical rows. Green answer gutters still cover the retained soft-wrapped continuation rows. This does not enable reflow or join the text into wider rows. MCP session creation without dimensions starts at 80 columns and 24 rows; callers can supply dimensions before starting output.
Mobile composer focus
The composer border highlights only while its textarea has focus. Tapping the mic releases editor focus without changing the insertion range. Recording uses the red mic icon, not an extra accent border. Keyboard navigation retains the mic focus ring. The blue slash key marks an available action, not retained focus.
Keyboard Shortcuts
With terminal input focused, Ctrl+Enter sends ESC [ 13 ; 5 u when Kitty keyboard flag 1 is active. Identified ego sessions receive the same encoding without negotiation to preserve BusySteer; current ego does not enable its Reedline Kitty guard. Legacy shells and other nonnegotiating agents receive CR. In enhanced mode, Control plus Shift or Alt retains those modifiers in the CSI u parameter. Plain Enter remains CR, Shift+Enter remains ESC CR, legacy Alt+Enter remains CR, and Cmd+Enter stays available to app shortcuts. This applies to desktop and browser/remote grid terminals; Compose has its own editor shortcuts.
Terminal Management
| Shortcut | Action | Notes |
|---|---|---|
| Cmd+T | New terminal tab | |
| Cmd+W | Close tab/pane | Closes active split pane, or tab if no split |
| Cmd+Shift+T | Reopen closed tab | Restores last 10 closed tabs |
| Cmd+1–9 | Switch to tab N | First 9 tabs only |
| Ctrl+Tab | Next tab | NSEvent monitor on macOS |
| Ctrl+Shift+Tab | Previous tab | NSEvent monitor on macOS |
Terminal Content
| Shortcut | Action | Notes |
|---|---|---|
| Cmd+L | Clear terminal | Sends Ctrl+L to shell (clear screen) |
| Cmd+K | Clear scrollback | Clears entire scrollback buffer (common terminal convention) |
| Cmd+C | Copy selection | |
| Cmd+V | Paste | |
| Cmd+F | Find in terminal | Search overlay with match highlighting |
| Cmd+G | Find next match | |
| Shift+Cmd+G | Find previous match |
Scrolling
| Shortcut | Action |
|---|---|
| Cmd+Home | Scroll to top of scrollback |
| Cmd+End | Scroll to bottom |
| Shift+PageUp | Scroll one page up |
| Shift+PageDown | Scroll one page down |
| Wheel / two-finger | Scroll the scrollback (smooth) |
| Shift+Wheel | Force scrollback scroll, never sent to the app |
Wheel vs. mouse-reporting apps. When an app enables mouse tracking, the wheel
is forwarded to it as SGR mouse codes whenever mouse reporting is on, in either
buffer — the alternate screen (vim, lazygit, htop) and inline fullscreen TUIs in the
main buffer alike (e.g. grok --no-alt-screen, or Claude Code, which enables mouse
tracking without switching to the alt screen). Hold Shift to force scrollback
scrolling regardless of mouse mode (consistent with Shift bypassing mouse reporting
for clicks/selection). The scrollbar thumb always moves TUIC history.
Selection repaints use the displayed viewport, including while a local smooth scroll is ahead of the backend frame. Starting a selection does not restore the older backend viewport. Search highlights, the block-timestamp toggle and block folding repaint the same way: they never paint the backend frame over a local smooth scroll.
Quantization (forwarded to an app). A physical wheel notch or trackpad flick
delivers a burst of many small-delta DOM wheel events (macOS reports the whole
momentum decay, not just the initial motion). The forwarded path accumulates those
pixel deltas and emits one SGR notch per full line height crossed, capped at 3 notches
per event in pixel mode (to match native terminal behavior for a single discrete mouse
click); the residual resets on direction reversal and when the gesture goes idle
(200 ms). Line-mode devices (deltaMode 1) are rounded to whole lines and clamped to
the viewport row count; page-mode devices (deltaMode 2) emit viewportRows - 1
notches per event.
Scrollback scrolling. The scrollback path (no mouse reporting, or Shift held) is not quantized: pixel deltas, normalized from line/page mode, drive smooth fractional scrolling. Gesture acceleration ramps from 0.5x (first screenful of travel) to 1.0x (after 2 screens) and is capped at 2.0x (after 4 screens); it resets on direction reversal and when the gesture ends.
Split Panes
| Shortcut | Action | Notes |
|---|---|---|
| Cmd+\ | Split vertically | Side-by-side, max 4 panes |
| Cmd+Alt+\ | Split horizontally | Stacked |
| Cmd+Shift+Enter | Maximize/restore pane | Toggle zoom on active pane |
| Alt+Arrow Left/Right | Navigate vertical panes | |
| Alt+Arrow Up/Down | Navigate horizontal panes |
Panels
| Shortcut | Action |
|---|---|
| Cmd+[ | Toggle sidebar |
| Cmd+, | Settings |
| Cmd+E | File browser |
| Cmd+Shift+M | Markdown panel |
| Cmd+Alt+N | Notes/ideas panel |
| Cmd+O | Open file picker |
| Cmd+N | New file (picker for name + location) |
| Cmd+J | Task queue |
| Cmd+B | Quick branch switch |
| Cmd+G | Branches tab |
| Cmd+Shift+D | Git operations panel |
| Cmd+Shift+E | Error log |
| Cmd+Shift+A | Activity dashboard |
| Cmd+Shift+W | Worktree manager |
| Cmd+Shift+M | MCP servers popup |
| Cmd+Shift+G | Diff scroll view |
| Cmd+? | Help panel |
Navigation
| Shortcut | Action |
|---|---|
| Cmd+P | Command palette |
| Cmd+Shift+K | Prompt library |
| Cmd+Shift+R | Run saved command |
| Cmd+R | Reload active web/preview tab |
| Cmd+Shift+F | Search file contents |
| Cmd+Ctrl+1–9 | Quick branch switch (hold Cmd+Ctrl, press number); in the Global Workspace it switches to tab N |
Zoom
Desktop terminal Chat and AI Chat use the shared scale in styles/chat-tokens.css: 14px plus the terminal font-size delta from the configured default, bounded to 8–32px. Terminal Chat reads its own terminal; AI Chat reads the active terminal and uses zero delta when none is active. Reset restores the 14px reading size. Mobile retains its device-local reading preference.
| Shortcut | Action |
|---|---|
| Cmd+= / Cmd++ | Zoom in |
| Cmd+- | Zoom out |
| Cmd+0 | Reset zoom |
Terminal Behaviors
Copy on Select
Auto-copies selected text to clipboard when text is selected in terminal. Configurable in settings (copy_on_select, default: on).
URL Click
Cmd+Click on URLs in terminal output opens them in the system browser. URL detection handled by the native terminal link parser. Dotted link underlines and solid hover underlines, including soft-wrapped file URLs, follow the text during smooth scrolling. Verified underlines remain visible when unrelated cells or full grid frames redraw; changed link text removes the old underline before asynchronous verification completes.
File Path Click
Clickable file paths in terminal output resolve against the terminal working directory when relative. Sentence periods are excluded from heuristic path targets, including paths in soft-wrapped lines. Existing files open in their viewer or editor; directories open in the File Browser.
Tab Features
- Middle-click closes tab
- Right-click context menu: Close, Close Other, Close Right, Rename, Detach to Window, Move to Worktree, Pin/Unpin, Copy Path
- Drag-and-drop to reorder tabs
- Double-click tab title to rename
- Unseen activity badge when tab has new output
Split Panes
- Max 4 panes per branch
- Drag divider to resize
- Flexible ratios preserved across layout changes
- Modes: “separate” (independent tab bars) or “unified” (shared tab bar)
Configurable Settings
| Setting | Default | Description |
|---|---|---|
copy_on_select | true | Auto-copy terminal selection to clipboard |
confirm_before_quit | true | Show dialog when quitting with active terminals |
confirm_before_closing_tab | true | Show dialog when closing tab with running process |
split_tab_mode | "separate" | Tab bar mode for split panes |
tab_ordering_mode | "grouped-by-type" | Tab ordering: “grouped-by-type”, “terminals-first”, “free” |
intent_tab_title | true | Show agent intent as tab title |
suggest_followups | true | Show suggested follow-up actions from agents |
bell_style | "visual" | Terminal bell: “none”, “visual”, “sound”, “both” |
prevent_sleep_when_busy | false | Prevent system sleep while terminal is busy |
Mobile queued prompt disclosure
The mobile CLI/Chat queued panel shows only entries whose server origin is user_command; server notices and spawned initial prompts stay in the FIFO but do not appear or count here. Clear all removes only the listed user prompt IDs. Hide/Show folds the item list into one count control. It retains the existing server FIFO snapshot and count, with no second queue. Successful snapshots with no user prompts reset the local disclosure; newly queued work opens again. Cancel and Clear all remain available after reopening, and read/action errors remain visible while hidden.
Collapsed Compose queue count
The collapsed handle has transparent chrome and muted text at rest. Hover or keyboard focus reveals its background and border. The label and queue count stay fully opaque.
The CLI Compose button shows a muted count pill for all pending FIFO entries, including user commands and TUIC messages. It hides at zero and follows the backend session state without opening the editor. Hover or keyboard focus loads the command/message breakdown; the count remains available if details fail.
Compose editor size
Terminal Compose uses the shared auto-grow control bounds: one control line when empty (36px desktop, 44px touch), intrinsic CodeMirror growth for newlines and wrapping, and the existing 96px editor maximum. Longer drafts scroll inside the editor. Clearing or successfully submitting a draft restores the minimum. The queue list keeps its independent height cap. Desktop CLI Compose reserves only the shared minimum editor row plus its natural footer height. Additional editor, image, or queue content overlays upward without changing terminal geometry. Outside Compose focus, the desktop editor collapses to its shared minimum and scrolls the retained draft; refocusing restores intrinsic overlay growth. Neither focus transition changes the grid. Closing releases the reservation. Chat remains fully docked; mobile retains its existing overlay and pin behavior.
Compose editor shortcuts
The newline legend shows only Ctrl+Enter. A panel-relative CSS container query hides shortcut hints at widths up to 640px, including split terminals inside a wide window. The footer does not wrap its hints around the action controls.
In the terminal Compose panel, Enter sends the draft. Ctrl+Enter and Shift+Enter insert a new line. Shift+Ctrl+Enter queues for the next idle moment when an agent is detected. Enter used to confirm an IME candidate does not submit the draft. These shortcuts do not change native terminal keybar controls.
Mobile stream recovery
Mobile CLI output releases a terminal subscription when the transport reports exit, including retry exhaustion. Visibility resume starts a fresh subscription if none remains and the session poll has not confirmed the session ended. Retired stream callbacks cannot close a newer subscription or change its connection error state. Handshake retries retain their three-second initial delay and 30-second backoff cap; hidden pages do not start a scheduled retry.
Unsized pane diagnostics
Canvas sizing retries run only for a visible pane connected to the layout. A pane that stays unsized for 120 animation frames logs a warning. Hiding or closing the pane cancels the retry; showing it starts a new measurement.
Restored PTY sessions attach their event listeners before the first layout pass. The reconnect resize waits for that attachment and reuses successful listeners instead of adding another API-error consumer. If the initial handshake failed, reconnect retries the attachment once. Suspend detaches them; resume attaches the replacement PTY once.
Claude native question cards in desktop PTY Chat and mobile keep wrapped answer labels separate from the selected option’s monospace preview. They retain the question tabs and the native Chat about this action. Hidden options still use explicit previous/next/select controls rather than guessed labels.
Expanded Chat tool rows
Expanded tool rows use theme colours for Bash/execute commands, flags, strings and operators. Read, Edit and Write keep the tool name separate from the path; other tools retain readable text. The collapsed activity summary and row sizing are unchanged.
Pending Chat prompts
In an open terminal Chat view, a submitted composer prompt appears immediately as a muted Pending bubble. Several prompts stay in send order while the agent works. A matching new user message from the native transcript replaces its bubble and removes older unmatched bubbles, since the CLI handles sends in order. A local slash command or rewritten prompt therefore cannot block later receipts. Adapter-redacted or truncated text can remain pending until a later matching prompt arrives or Chat closes. Failed sends remove their own feedback; ordinary activity and idle signals do not. This applies to the shared Claude, Codex, Grok and ego transcript presentation, but does not add queueing support to a CLI that lacks it. TUIC cannot preview prompts typed in the hidden CLI or sent outside this client. The CLI owns its queue; pending bubbles have no Cancel action and are not persisted when Chat closes.
Recall a host-owned pending prompt
With an empty desktop Compose editor, press ArrowUp to withdraw the newest user command from TUIC’s idle-gate queue and edit it. Notices and initial prompts are not recalled. The command is restored only if queue removal succeeds before delivery. A normal Send’s muted Pending bubble belongs to the native CLI and cannot be withdrawn by this action. AI Chat’s shared ACP composer supports the same shortcut for text-only queued turns. Nonempty drafts and slash menus keep their normal arrow-key behavior.
Compose queue item actions
The Compose N queued list has a labelled Cancel action for each item and keeps Clear all. Supported items also show Steer, which uses the same backend delivery as Session Chat Send now. Claude Code, Codex and ego interrupt the running turn, confirm idle, then submit the selected full text. The tooltip states that the current request stops. Steer is hidden while a native question waits.
Custom Glyph Rendering
CanvasTerminal renders certain Unicode character ranges as geometric primitives instead of delegating to font glyphs. This is the approach Alacritty’s built-in font also takes — ensuring pixel-perfect alignment regardless of which font is installed.
Why Custom Rendering
Font-based rendering of structural terminal characters has three problems:
- Cell mismatch — glyph metrics from the fallback font may not match the primary font’s cell dimensions, causing gaps or overlap
- Height/width fill — powerline arrows and block elements must fill the entire cell edge-to-edge;
fillText()renders at the font’s natural metrics - Font dependency — users would need specific “Nerd Font” or “Powerline” font variants installed
Custom rendering eliminates all three: shapes are drawn to exact cell boundaries using Canvas 2D primitives.
Rendered Ranges
| Range | Count | Description | Drawing Method |
|---|---|---|---|
| U+2500–U+257F | 128 | Box drawing (lines, corners, T-junctions, crosses) | Line segments with light/heavy weights |
| U+2580–U+259F | 32 | Block elements (halves, shades, quadrants) | fillRect with opacity for shades |
| U+E0B0–U+E0BF | 16 | Powerline arrows (triangles, semicircles, diagonals) | beginPath/fill with fg/bg color handling |
| U+2800–U+28FF | 256 | Braille patterns (2×4 dot grid) | Circles via arc() |
| U+1FB00–U+1FB3B | 60 | Sextant blocks (2×3 grid) | fillRect per active cell |
| U+1FB3C–U+1FB6F | 52 | Smooth mosaic wedges/triangles | Filled polygons |
| U+1FB70–U+1FB8B | 28 | 1/8th block elements | fillRect at precise eighths |
Characters outside these ranges fall through to fillText() using the configured font.
Specifications
Box Drawing (U+2500–U+257F)
Line segments from cell center to edges. Two weights: light (cellWidth/8) and heavy (cellWidth/4). Includes:
- Single/double lines and corners
- T-junctions and crosses (all light/heavy combinations)
- Rounded corners (╭╮╰╯) — rendered as straight segments (same as light corners)
- Diagonals (╱╲╳)
- Dashed lines — see below
Dashed Lines
All dashes use 2:1 dash-to-gap ratio (standard dash spec):
| Codepoints | Type | Segments | Formula |
|---|---|---|---|
| U+2504/05, U+2506/07 | Triple dash (H/V) | 9 units: 3×(2+1) | dash=2/9, gap=1/9 |
| U+2508/09, U+250A/0B | Quadruple dash (H/V) | 12 units: 4×(2+1) | dash=2/12, gap=1/12 |
| U+254C/4D, U+254E/4F | Double dash (H/V) | 6 units: 2×(2+1) | dash=2/6, gap=1/6 |
Drawn as filled rectangles (not setLineDash) for pixel precision.
Block Elements (U+2580–U+259F)
- Half blocks:
fillRectcovering half the cell - Shades (░▒▓): full-cell
fillRectwithglobalAlphaat 0.25, 0.5, 0.75 - Quadrants (▖▗▘…▟):
fillRectfor each active quadrant (cell/2 × cell/2)
Powerline (U+E0B0–U+E0BF)
These handle their own background: first fill the cell with bg color, then draw the shape in fg color. This is necessary because powerline arrows create a visual transition between two differently-colored segments.
| Codepoint | Shape |
|---|---|
| U+E0B0 | Right-pointing filled triangle |
| U+E0B1 | Right-pointing line triangle |
| U+E0B2 | Left-pointing filled triangle |
| U+E0B3 | Left-pointing line triangle |
| U+E0B4/B5 | Right semicircle (filled/line) |
| U+E0B6/B7 | Left semicircle (filled/line) |
| U+E0B8–U+E0BF | Diagonal triangles (8 variants) |
Braille (U+2800–U+28FF)
2 columns × 4 rows = 8 dots. The low byte of the codepoint IS the dot bitmask (ISO 11548):
bit 0 → col 0, row 0 (dot 1) bit 3 → col 1, row 0 (dot 4)
bit 1 → col 0, row 1 (dot 2) bit 4 → col 1, row 1 (dot 5)
bit 2 → col 0, row 2 (dot 3) bit 5 → col 1, row 2 (dot 6)
bit 6 → col 0, row 3 (dot 7) bit 7 → col 1, row 3 (dot 8)
Each dot is a circle with radius cellWidth/8, centered within its (cellWidth/2 × cellHeight/4) sub-area.
Sextant Blocks (U+1FB00–U+1FB3B)
2 columns × 3 rows = 6 segments. Each segment is cellWidth/2 × cellHeight/3.
Bit-to-position mapping:
bit 0 = top-left bit 1 = top-right
bit 2 = middle-left bit 3 = middle-right
bit 4 = bottom-left bit 5 = bottom-right
The 60 codepoints cover all 6-bit combinations except: empty (0), left-half (0b010101 = U+258C), right-half (0b101010 = U+2590), and full (0b111111 = U+2588). A lookup table maps each codepoint offset to its bitmask.
Smooth Mosaic Wedges (U+1FB3C–U+1FB6F)
52 filled polygons using normalized coordinates (0–1) mapped to cell dimensions. Grid points: X ∈ {0, 1/2, 1}, Y ∈ {0, 1/3, 2/3, 1}. All shapes are straight-edged (no curves).
Includes:
- Lower-left/right diagonal families
- Upper-left/right diagonal families
- Three-quarter blocks (3 of 4 center-corner triangles filled)
- One-quarter blocks (single center-corner triangle)
1/8th Block Elements (U+1FB70–U+1FB8B)
| Range | Description |
|---|---|
| U+1FB70–U+1FB75 | Vertical 1/8 strips at column positions 2–7 |
| U+1FB76–U+1FB7B | Horizontal 1/8 strips at row positions 2–7 |
| U+1FB7C–U+1FB81 | Combined corner/edge 1/8 blocks + stripe patterns |
| U+1FB82–U+1FB86 | Upper fractional blocks: 2/8, 3/8, 5/8, 6/8, 7/8 |
| U+1FB87–U+1FB8B | Right fractional blocks: 2/8, 3/8, 5/8, 6/8, 7/8 |
Positions 1/8 and 8/8 are not included because they already exist as U+258F (left 1/8), U+2595 (right 1/8), U+2594 (upper 1/8), U+2581 (lower 1/8), U+258C (left half), U+2590 (right half), U+2580 (upper half).
Implementation
All custom rendering happens in CanvasTerminal.tsx’s paintRow() function (Pass 2: text). Before the generic fillText() fallback, codepoints are checked against each range in order:
- Box drawing →
drawBoxDrawingChar() - Block elements →
drawBlockChar() - Powerline →
drawPowerlineChar()(handles own fg/bg) - Braille →
drawBrailleChar() - Legacy computing →
drawLegacyComputingChar() - Everything else →
fillText()with configured font
References
Frontend Performance Instrumentation (perfDebug)
These rules moved here from AGENTS.md to keep that file inside the
32,768-byte project-instruction budget. They stay binding for every agent;
AGENTS.md keeps a summary and a link to this page.
Frontend performance instrumentation (perfDebug)
The frontend counterpart to backend Diagnostics. One master flag gates ALL frontend perf/debug instrumentation — isPerfDebug() from src/utils/perfDebug.ts.
- Default =
import.meta.env.DEV→ active in dev, dormant in release. We ship a quiet binary; we never distribute hyper-logging. - Runtime-toggleable, NOT tree-shaken — a release build can be woken up to diagnose a field issue:
(Run via the WebView devtools / MCPwindow.__TUIC__.setPerfDebug(true) // persists to localStorage; starts the freeze detector window.__TUIC__.perfDebug() // read current statedebug invoke_js. After toggling on in a build that started dormant, the freeze detector is (re)started automatically.) - Dormant cost: a single boolean read at each entry point — negligible even per-frame.
What it gates (all in src/utils/): markPerf, timeSync, timeBatch (perfTrace.ts), noteFrameRequest (frame-burst detector), and startFreezeDetector (freezeDetector.ts). frameTiming.ts is a heavy opt-in sub-harness subordinate to this master gate — it has its own local enable (__terminalFrameTiming.enable(true)), but cannot record unless perfDebug is also on.
RULE for all future perf/debug instrumentation: gate it on isPerfDebug() (or route it through a perfTrace helper, which already does). Never ship always-on perf logging or per-frame timing. Do not invent a second on/off flag — extend this one.
Reading the output (only present when active): appLogger.warn lines like SLOW <label>: <n>ms (and SLOW git.refreshBatch:<repo>: <n>ms (body Xms + flush Yms) — body = our setState loop, flush = dependent effects/memos waking), plus UI freeze: <n>ms main-thread block carrying a perfTrace breadcrumb that names the culprit. Read via GET http://localhost:9876/logs (or :9877 for a worktree build).
TUICommander — Visual Style Guide
Reference for all UI/CSS/layout work. Every visual change MUST follow this guide.
Design Philosophy
VS Code Dark theme adapted for a terminal-first, developer-focused interface. The UI is a frame for terminal content — chrome recedes, content dominates. No bright whites. Muted UI elements, vivid status colors. Everything monospace except UI labels.
Application Layout
┌─────────────────────────────────────────────────────────────────────┐
│ #toolbar (38px macOS / 32px Win+Linux, --bg-primary, drag region) │
│ ┌──────────────┬────────────────────────────────────┬────────────┐ │
│ │ toolbar-left │ toolbar-center (tab bar) │toolbar-right│ │
│ │ (sidebar w) │ [Tab1] [Tab2] [Tab3] [+] │ [IDE btns] │ │
│ └──────────────┴────────────────────────────────────┴────────────┘ │
├─────────────────────────────────────────────────────────────────────┤
│ #app-body (flex: 1, flex-direction: row) │
│ ┌──────────┬─────────────────────────────────┬───────────────────┐ │
│ │ #sidebar │ #main │ Side panels │ │
│ │ 300px │ (flex: 1) │ (400px, optional)│ │
│ │ --bg- │ │ │ │
│ │ secondary│ ┌──────────────────────────────┐ │ ┌──────────────┐ │ │
│ │ │ │ #terminal-container │ │ │ Diff or │ │ │
│ │ REPOS │ │ (flex: 1, --bg-primary) │ │ │ Markdown or │ │ │
│ │ section │ │ │ │ │ Notes/Ideas │ │ │
│ │ title │ │ terminal fills this │ │ │ panel │ │ │
│ │ repo │ │ entire area │ │ │ │ │ │
│ │ header │ │ │ │ │ panel-header │ │ │
│ │ branch │ │ │ │ │ panel-content│ │ │
│ │ branch │ │ │ │ │ │ │ │
│ │ │ │ │ │ └──────────────┘ │ │
│ │ FOOTER │ │ │ │ │ │
│ │ [+ Add] │ └──────────────────────────────┘ │ │ │
│ │ [icons] │ │ │ │
│ └──────────┴─────────────────────────────────┴───────────────────┘ │
├─────────────────────────────────────────────────────────────────────┤
│ #status-bar (28px, --bg-secondary, border-top) │
│ [zoom][sessions] [branch ↑2][PR #42][CI ✓] [toggles][💡][⚙][?] │
└─────────────────────────────────────────────────────────────────────┘
Key structural rules:
#appisflex-direction: column, fills 100vh × 100vw.#app-bodyisflex-direction: row,flex: 1,min-height: 0.- Sidebar is fixed-width (resizable 200–500px), main area fills remaining space.
- Side panels (Diff, Markdown, Notes) appear right of
#main, width 400px, max 50vw. - All sections have
overflow: hidden— scrolling is on inner content areas only. - Status bar is always at the bottom, never scrolls.
Color Palette
Values shown are the startup :root defaults: foregrounds from shared foreground-tokens.css and other colors from global.css, in effect until a theme loads. The app supports 13 bundled themes (Commander is the default and the fallback) — all core colors are CSS custom properties overridden at runtime by applyAppTheme() in themes.ts, which also sets html[data-theme="<key>"] so a theme can carry typography rules in global.css (only clean does: neutral gray --tab-*-rgb tints so typed tabs do not each bring their own hue). Font smoothing is global: html forces -webkit-font-smoothing: antialiased and 0.01em tracking, the rasterization every native-looking macOS app uses. Existing profile files keep their user edits. On load, Rust replaces only a recognized built-in’s exact legacy foreground triplet with the current bundled triplet; partial foreground customizations and renamed themes stay unchanged, and no file is rewritten. The native window and webview backing layers also use bgPrimary: Rust resolves the saved theme before window creation, and applyAppTheme() synchronizes both layers on theme changes and hot reload. When writing CSS, always use variables, never hardcode core palette values.
Theme gallery (dev only). With make dev running, open http://127.0.0.1:1421/theme-gallery.html (src/dev/themeGallery.tsx). It renders one row per bundled theme: the shipped theme on the left and, on the right, the edit proposed in src/dev/themeProposals.ts (a partial override merged over the JSON; empty when nothing is under review). Each card mounts the real Toolbar, Sidebar, TabBar, StatusBar and collapsed ComposeToggle components over stores seeded once in the page (a fake __TAURI_INTERNALS__ in theme-gallery.html answers every invoke), so a component or stylesheet edit repaints every theme through HMR and a theme JSON edit shows up within a second. Only the terminal body and the dialog are stand-ins; never hand-copy component markup into the gallery, a copy drifts within a session (the page polls /__tuic_themes, a serve-only Vite middleware in vite.config.ts). Use it to check a palette change against every theme at once before touching the live app. A static snapshot of the 2026-09-22 review, taken before its edits were applied, is in docs/design/theme-gallery-2026-09-22/. It is not a build input and never ships. To show it as a TUIC ui tab inside a dev build, use http://localhost:1421/...: the dev app is served from 127.0.0.1:1421, and PluginPanel blanks a same-origin iframe (guardSameOriginNav).
CSS Variables (startup :root tokens)
| Variable | Startup default | Usage |
|---|---|---|
--bg-primary | #1e1e1e | Main canvas — terminals, panel bodies |
--bg-secondary | #252526 | Sidebar, tab bar, status bar |
--bg-tertiary | #2d2d30 | Inputs, settings rows, button defaults |
--bg-highlight | #37373d | Hover states, active branch bg |
--fg-primary | #d4d4d4 | Primary text (Commander startup value) |
--fg-secondary | #b5b5b5 | Labels, secondary text |
--fg-muted | #a6a6a6 | Section titles, tertiary text |
--accent | #59a8dd | Primary actions, active indicators, links (theme-dependent) |
--accent-hover | #7abde5 | Hover on accent elements (theme-dependent) |
--activity | #59a8dd | Busy/activity pulse indicators (fixed in global.css, not overridden by themes) |
--success | #4ec9b0 | Positive states, open PRs (teal) |
--warning | #dcdcaa | Caution, pending, main branch icon (yellow) |
--attention | #e8984c | Actionable alerts, confirmation prompts (orange) |
--error | #f48771 | Errors, failures, closed PRs (coral) |
--merged | #ae83ff | PR merged marker and badge background (purple; Paper uses #7540b0) |
--text-on-merged | #000000 | Filled merged badge label (Paper uses #ffffff); independent of accent action foreground |
--unseen | #c084fc | Terminal completed while user wasn’t viewing (purple, clears on view) |
--diff-del | --error mixed 25% with white | Deleted-line counts in the sidebar stats badge. Lighter than --error so a negative diff does not read as an alarm; vscode-light resets it to --error |
--border | #3e3e42 | All borders and dividers |
--text-on-accent | #000000 | Black text on colored badge backgrounds |
--text-on-error | #000000 | Black text on error backgrounds |
--text-on-success | #000000 | Black text on success backgrounds |
Extended Palette (hardcoded, contextual only)
| Color | Context |
|---|---|
#d29922 | Changes requested / review required (orange) |
#e3b341 | CI pending (golden) |
#ffd700 | Rate limit, question icon (gold) |
rgba(122, 162, 247, *) | Branch ahead/behind tint, pulse glow |
rgba(158, 206, 106, *) | Diff additions bg, CI success tint |
rgba(247, 118, 142, *) | Diff deletions bg, CI failure tint |
Background Stacking Order (darkest → lightest)
#1e1e1e --bg-primary Terminal canvas, main area
#252526 --bg-secondary Sidebar, tab bar, status bar, modals
#2d2d30 --bg-tertiary Buttons, inputs, settings rows, panel headers
#37373d --bg-highlight Hover, active branch, selected items
Every surface uses exactly one of these four levels. Elevation = lighter.
Typography
| Variable | Stack | Usage |
|---|---|---|
--font-mono | JetBrains Mono, Fira Code, Hack, Cascadia Code, Source Code Pro, DejaVu Sans Mono, monospace | Terminals, branch names, stats badges, PR badges, code |
--font-ui | -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Noto Sans, Liberation Sans, sans-serif | UI labels, buttons, headings, descriptions, settings |
Size Scale
| Variable | Size | Where |
|---|---|---|
--font-3xs | 8px | Micro labels, pixel-level detail |
--font-2xs | 10px | Smallest visible labels |
--font-xs | 11px | Badge text, hotkey hints, metadata |
--font-sm | 12px | Section titles (REPOS), secondary labels |
--font-md | 13px | Branch names, tab names, settings labels — default for UI |
--font-base | 14px | Body text, document default |
--font-lg | 15px | Panel headings |
--font-xl | 17px | Dialog titles |
--font-2xl | 20px | Large headings |
--font-3xl | 24px | Hero text, splash screens |
Font weight: 400 normal, 500 medium (branch names), 600 semibold (repo names, badges), 700 bold (headings only).
Spacing
Fixed Dimensions
| Variable | Value |
|---|---|
--sidebar-width | 300px (resizable: min 200px, max 500px) |
--toolbar-height | 38px macOS / 32px Win+Linux |
--tab-bar-height | 32px |
--status-height | 28px |
Spacing Scale
| Size | Usage |
|---|---|
| 1–2px | Branch item vertical margin, micro separation |
| 4px | Sidebar content top padding, compact flex gaps, micro padding |
| 6px | Icon-to-text gaps, sidebar footer gaps, repo header padding |
| 8px | Button padding, form gaps, sidebar footer padding, standard gap |
| 12px | Branch item horizontal padding, panel header padding, medium padding |
| 16px | Sidebar section margin, branch list left indent, modal padding |
| 20px | Dialog content padding, sidebar empty state padding |
Use gap on flex containers, not margins between children.
Border Radius
| Variable | Value | Usage |
|---|---|---|
--radius-xs | 2px | Minimal — focus rings |
--radius-sm | 3px | Small interactive elements |
--radius-md | 4px | Standard — buttons, badges, inputs, branch items |
--radius-lg | 6px | Larger controls — dropdowns, add-repo button, form inputs |
--radius-xl | 8px | Modals, panels, dialogs |
--radius-pill | 12px | PR badges, status pills |
--radius-full | 9999px | Pills; square elements stay circular — toggle thumbs, repo initials avatar |
Shadows
| Variable | Value | Usage |
|---|---|---|
--shadow-popup | 0 8px 32px rgba(0,0,0,0.4) | Modals, dialogs |
--shadow-dropdown | 0 4px 16px rgba(0,0,0,0.3) | Menus, popovers, context menus |
--shadow-bottom-anchor | 0 -4px 20px rgba(0,0,0,0.4) | Bottom-anchored panels |
Three levels only. Never invent new shadow values.
Transitions & Animation
Durations
| Duration | Usage |
|---|---|
| 0.1s | Hover backgrounds, active states — instant feedback |
| 0.15s | Standard — opacity, color, transform, border changes |
| 0.2s | Layout — sidebar collapse, toggle switches, chevron rotation |
Keyframe Animations
pulse-opacity: Opacity 0.4 → 1.0 → 0.4, infinite. Duration 1.5s or 2s.
Defined in each CSS Module file that uses it (not in global.css — CSS Modules scope animation names).
Used for: active branch icon, CI pending badge, rate limit indicator.
pulse-question: Box-shadow 0 → 0 0 12px 4px rgba(122,162,247,0.4) → 0.
Variants exist with red (error) and orange (confirm) colors.
Used for: terminal tab glow when agent awaits input.
pendulum: Translates text from 0 to -overflow-px and back. Duration computed dynamically from overflow width (~50px/s, minimum 4s cycle). Uses CSS custom properties --overflow-px and --ticker-duration.
Used for: status bar notification text that overflows its container.
Tab status dot color scheme (single ● indicator left of tab name):
- Grey (opacity 0.3): idle — no session or command never ran
- Blue (
--activity, pulse infinite): busy — producing output now - Green (
--success): done — command completed - Purple (
--unseen, static): completed while user wasn’t viewing (clears on view) - Orange (
--attention, pulse infinite): agent needs user input (question) - Red (
--error, pulse infinite): API error or agent stuck
Tab type color scheme (gradient background + colored border-bottom):
- Red (
#ef4444): diff tabs - Blue (
--accent/#7aa2f7): editor tabs - Teal (
#2dd4bf): markdown tabs - Purple (
#a78bfa): panel tabs - Amber (
#fbbf24): remote PTY sessions (created via HTTP/MCP)
Always use ease timing. Respect prefers-reduced-motion. Never transition: all.
Component Reference
Sidebar
#sidebar {
width: var(--sidebar-width); /* 300px */
min-width: 200px;
max-width: 500px;
background: var(--bg-secondary);
border-right: 1px solid var(--border);
display: flex;
flex-direction: column;
}
Section title (e.g. “REPOS”):
font-size: --font-sm,text-transform: uppercase,color: --fg-mutedletter-spacing: 0.05em,padding: 4px 16px
Repo header:
- Flex row,
gap: 6px,padding: 6px 12px 3px - Repo initials: 28×28px circle,
--accentbg,--text-on-accenttext,--font-xs, semibold - Repo name:
--font-sm, semibold, uppercase,--fg-secondary, truncated with ellipsis - Chevron: the shared
ChevronIcon(src/components/ui/ChevronIcon.tsx, 12px SVG),--fg-secondary, rotates 0→90° on expand (150ms ease). Branch rows use a separate, always-visible disclosure button beside the status icon. The collapsed count stays beside the chevron; the status icon and row only select the branch. - Actions (⋯, +): hidden by default (
opacity: 0), shown on repo-header hover
Branch item (the most complex sidebar element):
.branch-item {
display: flex;
align-items: center;
gap: 8px;
padding: 4px 12px;
border-radius: var(--radius-md);
margin: 1px 0;
transition: background 0.1s;
}
.branch-item:hover { background: var(--bg-highlight); }
.branch-item.active {
background: var(--bg-highlight);
border-left: 2px solid var(--accent);
padding-left: 10px; /* compensate for border */
}
Branch item anatomy (left to right):
[icon 14px + agent count?] [name flex:1] [unmerged mark?] [PR marker?] [diff numbers?] [actions on hover]
- Icon (18px wide, centered):
★yellow for main,Ymuted for feature,Yaccent+pulse when agent active,Ygreen when shell idle,?warning (orange)+pulse when awaiting input - Name:
--font-md, weight 500,--fg-primary, ellipsis on overflow - Agent count (when the tab tree is on): a bare
--font-3xsdigit at the icon’s bottom-right corner with a--bg-secondaryhalo. Never a pill: a pill covers the glyph that tells main, branch and worktree apart - PR marker (optional): a 7px square plus
#N, both in the state color, no fill or border. A conflict rotates the square into a diamond so it does not rely on color. Draft and Review outline the square instead of filling it, as their pills did (Review vs Changes requested differ only by fill). Motion matches the pill form: the conflict marker pulses at 1.5s, Checking and CI Running at 2s; the number never moves. The UI Legend renders this same component The state word (Review, Conflicts, …) and any uncommitted-file count live in thedata-tooltip - Unmerged mark (optional): a 7px outlined square in
--fg-secondary, centered in a 14px target with no pill background. It marks a worktree with commits outside the default branch even when its working tree is clean; hover or focus explains why branch deletion is blocked. - Diff numbers (optional): plain
+N -Nin--font-2xs,--success/--diff-del, no chip. Always shown beside the PR marker, never alternating with it - Actions (on hover only): reveal the natural width of shared compact
Buttoncontrols (+, ×) over the row’s inline end on hover or keyboard focus, without reserving space or pushing facts outside the row. Compact actions are 22px high on desktop and at least 44px high at touch widths. Swipe-tray actions use shared stretch geometry; the open tray grows with its controls.
Tab Bar
Located inside #toolbar, center section. Background matches toolbar (--bg-primary).
.tab {
height: var(--tab-bar-height); /* 32px */
padding: 0 12px;
font-size: var(--font-md);
font-family: var(--font-mono);
color: var(--fg-secondary);
background: transparent;
border: none;
border-top: 2px solid transparent;
cursor: pointer;
display: flex;
align-items: center;
gap: 6px;
min-width: 80px;
max-width: 200px;
}
.tab.active {
color: var(--fg-primary);
border-top-color: var(--accent);
background: var(--bg-secondary);
}
.tab:hover:not(.active) {
color: var(--fg-primary);
background: var(--bg-tertiary);
}
Tab anatomy: [agent badge?] [name, truncated] [close × on hover]
- Agent badge: small colored prefix (e.g.
C claude,G gemini) - Close button: invisible by default,
opacity: 1on tab hover - New-tab and scroll actions use shared stretch
Buttongeometry with square edges (22px toolbar density, 44px at touch widths). The tab-bar container grows with these controls. Close and global-workspace actions use shared compact Buttons; inline rename uses a shared compact Input.
Status Bar
.bar {
height: var(--status-height); /* 28px */
min-height: var(--status-height);
background: var(--bg-secondary);
border-top: 1px solid var(--border);
display: flex;
align-items: center;
padding: 0 12px;
font-size: var(--font-sm);
gap: 8px;
overflow: hidden;
}
Three sections: left (zoom, status info, CWD, agent badge, ticker), center (PR + CI badges), right (toggle buttons).
Agent badge (.agentBadge): --font-mono, --font-sm, weight 500, 1px 6px padding, --radius-sm, --bg-tertiary bg. Usage-dependent color classes:
.agentUsage—--fg-secondarytext (normal usage).agentUsageWarning—#dcdcaatext (usage >=70%).agentUsageCritical—#f48771text +pulse-opacityanimation (usage >=96%).agentRateLimited—#f44747text +pulse-opacityanimation
Ticker message (.tickerMessage): --font-mono, --font-sm, --fg-muted, max-width 300px, --radius-sm. Warning priority (>=80): #ffd700 text, gold bg at 0.1 alpha. .tickerClickable adds cursor pointer and hover effect.
Pendulum overflow (.infoTickerActive): When the status info text is wider than its container, a CSS pendulum keyframe animation scrolls the text left then back. Duration is computed dynamically from overflow width (~50px/s). Click dismisses.
Count badges (CountBadge in components/ui): the one counter for every icon button: status bar toggles (errors, ideas, git changes) and the sidebar footer (parked, stale, tunnels). 12px high, --radius-sm, 9px bold tabular digits, top-right corner at -3px of a position: relative button. Color is a tone (accent, error, success), never an inline style. It renders nothing for a zero count.
PR badges (center section): PrBadge + CiBadge components in .githubStatus, separated by a left border. CLOSED PRs are hidden; MERGED PRs have a 5-minute activity-based grace period.
Toggle buttons (right section): --bg-tertiary bg, --border border, --font-xs, 2px 8px padding.
Active: --accent bg, white text. Each has a hotkey hint overlay positioned below.
Side Panels (Diff, Markdown, Notes/Ideas)
All follow the same structure:
.panel {
width: 400px;
min-width: 300px;
max-width: 50vw;
border-left: 1px solid var(--border);
display: flex;
flex-direction: column;
background: var(--bg-primary);
}
.panel-header {
display: flex;
justify-content: space-between;
align-items: center;
padding: 8px 12px;
background: var(--bg-tertiary);
border-bottom: 1px solid var(--border);
}
.panel-title { font-size: var(--font-lg); font-weight: bold; }
.file-count-badge {
background: var(--accent);
color: var(--text-on-accent);
border-radius: var(--radius-pill);
padding: 1px 6px;
font-size: var(--font-xs);
}
.panel-content { flex: 1; overflow-y: auto; }
Dialog / Modal
.overlay {
position: fixed;
inset: 0;
background: rgba(0, 0, 0, 0.65);
display: flex;
align-items: center;
justify-content: center;
z-index: 1000;
}
.dialog {
width: 480px;
max-width: 90vw;
max-height: 80vh;
background: var(--bg-secondary);
border: 1px solid var(--border);
border-radius: var(--radius-xl);
box-shadow: var(--shadow-popup);
display: flex;
flex-direction: column;
overflow: hidden;
}
.dialog-header {
padding: 16px;
border-bottom: 1px solid var(--border);
display: flex;
justify-content: space-between;
align-items: center;
}
.dialog-header h2 { font-size: var(--font-xl); }
.dialog-content { padding: 16px; overflow-y: auto; flex: 1; }
.dialog-actions {
padding: 12px 16px;
display: flex;
justify-content: flex-end;
gap: 8px;
border-top: 1px solid var(--border);
}
Primary button: background: var(--accent); color: var(--text-on-accent); padding: 8px 16px; border-radius: var(--radius-lg);
Secondary button: background: var(--bg-tertiary); color: var(--fg-secondary); same padding/radius.
Danger button: background: var(--error); color: var(--text-on-error);
Ready action (Send, Save): set data-ready="true" on the button while it can act (unsaved changes, agent selected). styles/ready-actions.css, imported by desktop global.css and PWA mobile.css, gives button[data-ready]:not(:disabled) the accent border, text and a faint accent tint; clean or disabled stays neutral. Never hand-roll a per-component “dirty” colour.
Form Controls
There are two shared densities: form (36px, 8px horizontal padding) and
toolbar (22px, 6px horizontal padding). The toolbar size matches the measured
22px panel close/detach controls and fits inside the 32px app toolbar. Compose
toolbar from ui/FormControls.module.css on header, filter, tab and toolbar
rows. Do not apply it to a whole panel with configuration forms. Compose form
on a nested form to reset inherited toolbar tokens. Shared dialog popovers, native
dialogs, [role="dialog"] and native [popover] roots reset to form density, including when
mounted inside a toolbar. Mark custom modal roots with their dialog role and
accessible name; do not add a per-dialog density override.
Shared icon actions and segmented switches follow the row density. Settings and
configuration forms keep form density. Both densities retain the 44px touch
minimum at viewport widths up to 600px. Mobile segmented controls draw their
border inside the surface, so the segments keep the full 44px hit region.
Use Button, Select, Input and Textarea from src/components/ui for form fields.
They forward native attributes, refs, options and events. Input is for text,
numeric and date fields. Use Switch, Slider and ColorInput for native
checkbox switches, ranges and colour pickers; file pickers keep their specialised controls. FormControls.module.css owns their presentation:
--control-height (36px), --control-padding-x (8px), theme colours,
--radius-lg and --font-md. Containers own width and alignment, never
control height, padding, borders or colours. Textareas resize vertically;
multiple selects keep native listbox behavior. Shared Select reserves 32px at the inline end for its native arrow; consumers must not add feature padding for this. At widths up to 600px,
controls have a 44px minimum height and 16px text to prevent iOS zoom.
Button forwards native button attributes and defaults to type="button" (set
type="submit" for form submission). Variants are primary, secondary (default),
ghost, hint and danger; sizes are default (36px) and compact (22px), both with a
44px touch minimum. It shares FormControls height and padding tokens with fields.
Use variant="hint" for discreet actions such as the collapsed Compose handle:
transparent chrome and muted text at rest, then a highlighted surface, border and
primary text on enabled hover or keyboard focus. The primitive owns these styles;
feature CSS owns placement only.
For status-only toggles whose icon already indicates the active state, use
pressedIndicator="none" to omit the pressed border. The default remains
"border"; keyboard :focus-visible styling stays intact.
Clickable list rows/cards retain native buttons with data-control-layout="row"
or data-control-layout="card". Their geometry selectors must include both the
button tag and the exact marker. This exception is for content layout, never
form, toolbar or dialog actions.
AI Chat retains native full-frame conversation pickers and native session
details/summary disclosures. Mark these controls with
data-control-layout="overlay-picker" or "disclosure" and retain only their
exact, reasoned geometry exceptions. The visible picker frame and disclosures
use the shared 36px/44px control tokens. Its shared Textarea retains the tested
panel-relative editor cap and one-line reset with a narrow composer-editor
exception; this does not exempt other actions or fields. Keep desktop editor
resize and overflow rules scoped to the non-mobile composer. The phone editor
keeps its native scrollable surface for drafts beyond its height cap. Use
Textarea embedded inside the mobile composer: the surrounding shell owns the
border and focus frame, so the editor does not add standalone form-field chrome.
SegmentedControl is the shared view switch. It uses a named tablist, one
keyboard tab stop, and Arrow Left/Right, Home and End to select and focus an
enabled choice. Tasks uses it for List, Board and Roadmap.
Toggle switch: use ui/Switch, with a 36px row-height target (44px on touch),
a 36×20px track, --radius-full (10px), off=--bg-tertiary, on=--accent. White thumb slides with 0.2s transition.
Range slider: use ui/Slider, with the shared row-height target, a 4px track
and the existing 14px circular thumb in --accent. Native input/change events
remain separate. ui/ColorInput keeps the native colour picker over a shared
swatch target; its selected prop marks a custom selection. The controls guard
also rejects feature-owned checkbox/range/colour widths and shared primitive sizing.
Settings Panel
Full-screen overlay. All pages share width: min(1136px, calc(100vw - 48px)), height: 80vh, independently scrolling navigation and content, and existing theme tokens. This width replaces the previous 700px guide after the 2026-10-16 mock approval. Never resize on tab selection or eagerly mount pages to avoid flashes.
- Navigation: 232px default; retain saved user width and resize behavior. Content padding: 24px 32px.
SettingPageHeader: 20px title, optional subtitle, scope badge and optional source. Omit subtitles that only repeat card headings. A header without a subtitle or source reserves no subtitle space.SectionCard: semantic<h3>, 15px heading, 16px padding/gap, 8px radius,--bg-primary.SettingRow: persistent label/hint left, existing shared control right (up to 260px, 36px high), 12px vertical padding. ReuseSettingFieldIDs; errors go below the field and joinaria-describedby.SectionCard layout="aligned": approved dense structured editor layout. Use a 120px label column and one shared control column. It sets shared form tokens to 28px; controls keep the 44px mobile minimum. Named child grids retain their own layout. The Smart Prompt editor uses this layout with two placement columns and one row per conditional setting.StatusSummary: visible status words and existingStatusBadgesemantic tone, source and freshness. Unknown is neutral; saved sign-in is not a live connection.ListRow: wrapping name/subtitle, source/version/access badges and named actions.EmptyStateexplains absence and offers one valid action; do not conflate loading, failed or unsupported state.DangerZone: explicit scope and consequence for destructive/disconnecting actions only; caller retains confirmation. Ordinary reset is not automatically destructive.- Label/help pairs use the shared
.helpLabellayout so stacked and grid fields reserve one cell for the pair; the badge remains beside wrapped label text. - Paper shades the shared success, attention, changes/review and merged tokens for readable marker text; the legend and sidebar keep the same components and shapes.
- Agent color tiles use metadata-selected
--identity-on-lightor--identity-on-dark; identity fills do not change with the app theme. - Settings maps secondary and muted copy to the shared
--settings-foregroundtoken, mixed from the theme foregrounds for elevated/highlighted surfaces. Links and link buttons use--link-foregroundwithout changing action fills. Settings accent actions retain the theme’s--text-on-accentforeground. - Help is 12px
--fg-secondary, never essential--fg-muted. Contextual help is selective and adds information beyond the subtitle; do not add a question mark to every row. - Card heading actions stay in the shared heading flex layout so descriptions cannot flow beneath an absolute action. Color targets do not shrink; compact color targets are 44px circles and wrap within the full-width control column.
- Below 800px rows stack; below 600px navigation is compact and controls/actions have 44px targets. Preserve keyboard labels and long translations.
- Keep existing autosave/explicit-save boundaries and lazy mounting. Shared primitives never probe, save or infer service state.
Status Badges Reference
PR State (sidebar .branch-pr-badge)
| State | Background | Border | Text Color | Extra |
|---|---|---|---|---|
| Open | --success | none | --text-on-success | — |
| Draft | transparent | 1px dashed --fg-muted | --fg-muted | — |
| Merged | --merged | none | --text-on-merged | — |
| Closed | --error | none | --text-on-error | — |
| Conflict | --error | none | --text-on-error | pulse-opacity 1.5s |
| CI Failed | --error | none | --text-on-error | bold |
| CI Pending | transparent | 1px solid #e3b341 | #e3b341 | pulse-opacity 2s |
| Changes Req. | #d29922 | none | --text-on-accent | — |
| Review Req. | transparent | 1px solid #d29922 | #d29922 | — |
All badges: font-size: --font-xs, font-family: --font-mono, font-weight: 600, border-radius: --radius-pill, padding: 1px 6px.
CI State (status bar)
| State | Background | Text |
|---|---|---|
| Success | rgba(158,206,106,0.2) | #9ece6a |
| Failure | rgba(247,118,142,0.2) | #f7768e |
| Pending | rgba(224,175,104,0.2) | #e0af68 |
Agent/Usage (tab + status bar)
| State | CSS Class | Style |
|---|---|---|
| Agent running | Tab colored agent prefix | Tab has colored agent prefix badge |
| Usage normal | .agentUsage | --fg-secondary text |
| Usage ≥70% | .agentUsageWarning | #dcdcaa text (warning yellow) |
| Usage ≥96% | .agentUsageCritical | #f48771 text + pulse-opacity 2s |
| Rate limited | .agentRateLimited | #f44747 text + pulse-opacity 2s |
| Ticker warning (≥80 priority) | .tickerWarning | #ffd700 text, gold bg at 0.1 alpha |
| Update available | .updateBadge | #4ec9b0 text, teal bg at 0.15 alpha |
Icons
No icon library dependency. Icons are monochrome inline SVGs with fill="currentColor", so they inherit the surrounding text colour and recolour with the theme for free. Never emoji — AGENTS.md → “Visual”.
Text symbols and Unicode are still correct where the glyph is the content rather than an icon: the branch and state markers in the table below, and single characters inside a dense row. Reach for an inline SVG for anything that reads as an icon.
| Symbol | Meaning | Where |
|---|---|---|
★ | Main/primary branch | Sidebar branch icon |
Y | Feature branch | Sidebar branch icon |
? | Awaiting input | Branch icon (warning/orange, pulsing) |
+ | Add/create | Buttons |
× | Close/remove | Tab close, panel close, dialog close |
⋯ | Context menu | Repo header |
✎ | Edit/rename | Branch double-click |
▶ | Send/execute | Notes panel send button |
ChevronIcon | Chevron (expand/collapse), SVG not text | Sidebar groups, repos, GitHub sections, search bar |
● | Tab status dot | Tab bar (grey=running, green=idle, purple=unseen, blue-pulse=activity, orange-pulse=awaiting, red-pulse=error) |
⎇ | Git branch symbol | Status bar |
💡 | Ideas panel | Status bar, panel header |
Brand SVG viewports crop blank favicon artboard margins. Preserve each mark’s aspect ratio and use the shared AgentIcon artwork for desktop and mobile identities.
Icon dimensions: 18px wide container for branch icons. --font-md or --font-lg size. Always left of text with gap: 6–8px.
Scrollbars
::-webkit-scrollbar { width: 8px; height: 8px; }
::-webkit-scrollbar-track { background: transparent; }
::-webkit-scrollbar-thumb {
background: var(--bg-highlight);
border-radius: var(--radius-md);
}
::-webkit-scrollbar-thumb:hover { background: var(--fg-muted); }
Terminal scrollbar overridden to 8px with !important.
Interactive States
Hover
- Background: one level up (
--bg-secondary→--bg-tertiary, or--bg-tertiary→--bg-highlight) - Text:
--fg-secondary→--fg-primary - Border: transparent →
--accent(for add-repo button) - Duration: 0.1s
Active / Selected
- Active branch:
--bg-highlightbg +2px solid var(--accent)left border - Active tab:
--bg-secondarybg +2px solid var(--accent)top border +--fg-primarytext - Active toggle:
--accentbg + white text - No hover animation on already-active items
Focus
:focus-visible {
outline: 2px solid var(--accent);
outline-offset: 2px;
}
Shared Input, Textarea, Select and bordered Button variants use an accent border plus a 1px inset accent
shadow instead of an offset outline. This forms one continuous border-hugging
focus band. Invalid text fields retain their error border and inset accent focus
indicator. In forced-colour mode, a system-colour outline with no gap replaces
the shadow. Ghost, hint and circular buttons, switches, sliders and swatches retain their
offset keyboard focus rings.
Excluded on toggle buttons and mic button.
Disabled
opacity: 0.3(strong) or0.5(mild)cursor: not-allowed- No hover, no transitions
Hidden-until-hover
Pattern used for actions that clutter the UI when always visible:
- Repo actions:
opacity: 0; pointer-events: none;→opacity: 1; pointer-events: auto;on.repo-header:hover - Branch actions:
max-width: 0; overflow: hidden;→max-width: 44px;on.branch-item:hover - Tab close button:
opacity: 0→opacity: 1on.tab:hover
Platform Differences
| Property | macOS | Windows/Linux |
|---|---|---|
| Toolbar height | 38px | 32px |
| Traffic light offset | .platform-macos .toolbar-left { padding-left: 78px; } | None |
| System font | -apple-system first | Segoe UI (Win) / Roboto (Linux) first |
| Quit menu | App menu | File menu |
| Check for Updates | App menu | Help menu |
CSS classes on <html>: .platform-macos, .platform-windows, .platform-linux.
Accessibility
- Commander primary text (#d4d4d4 on #1e1e1e) exceeds WCAG AAA.
- Secondary and muted informational text must meet WCAG AA (4.5:1) on all four neutral chrome surfaces, including highlighted rows and pills. Built-in themes retain primary > secondary > muted contrast. Do not reduce informational text with whole-control opacity.
- Desktop and mobile startup foregrounds come from
src/styles/foreground-tokens.css; the runtime fallback reads Commander foregrounds from its bundled theme JSON.themeContrast.test.tsprotects the contrast and startup palette contract. - Status communicated by color + shape + icon — never color alone.
:focus-visibleoutlines for keyboard navigation.prefers-reduced-motionquery disables all animations.- Custom scrollbars maintain 8px touch target.
PWA / Mobile (src/mobile/mobile.css)
The mobile PWA has its own standalone stylesheet at src/mobile/mobile.css, completely independent from the desktop global.css. This allows the mobile UI to evolve separately while sharing the same design language.
What’s shared
- Core color palette (same
--bg-*,--fg-*,--accent,--success,--warning,--attention,--errorvariables with identical default values) - Border radius scale (
--radius-smthrough--radius-full, excluding--radius-xs) - Shadow tokens (
--shadow-popup,--shadow-dropdown) - ANSI terminal palette
- Session Chat semantic prompt/answer colors and the font size scale, imported from
src/styles/chat-tokens.cssby both stylesheet entrypoints
What differs
| Property | Desktop (global.css) | Mobile (mobile.css) |
|---|---|---|
| Font mono stack | JetBrains Mono, Fira Code, Hack, Cascadia, … | SF Mono, Menlo, Consolas, DejaVu, … |
| Font size scale | --font-3xs through --font-3xl (8–24px) | Same shared scale; native inputs retain 16px text |
| Layout variables | --sidebar-width, --toolbar-height, --tab-bar-height, --status-height | Not used — mobile uses flex-based layout |
| User select | Disabled (none) | Enabled (text) |
| Theme variables | --activity, --merged, --unseen | Not present (mobile has no terminal activity tracking yet) |
| Safe areas | Not used | env(safe-area-inset-top/bottom) on #mobile-app |
| Input font-size | From scale | Fixed 16px minimum to prevent iOS auto-zoom |
The idle terminal command editor and special-key rows intentionally use 15px text at the owner’s request. Their shared mobileCommand density owns button text and horizontal padding; action hit regions retain the 44px minimum. This is a narrow exception to the usual 16px mobile input typography, not a new density for other forms. The focused command editor retains 16px text at the iOS zoom threshold.
Keeping in sync
The foreground startup palette is defined once in src/styles/foreground-tokens.css, imported by both entrypoints. When updating other core palette colors in global.css, also update mobile.css — the :root blocks must stay aligned for the shared variables. Theme-specific variables (--activity, --merged, --unseen) are desktop-only and do not need mobile equivalents until that functionality ships in PWA.
Anti-Patterns (DO NOT)
- No bright whites — max text brightness is the selected theme’s
--fg-primary. - No new shadows — only the three defined levels exist.
- No
transition: all— always list specific properties. - No hardcoded core colors — use CSS variables for the four bg levels, three fg levels, and status colors.
- No icon libraries, no emoji — monochrome inline SVG with
fill="currentColor". - No off-scale radius — only
--radius-xsthrough--radius-full. - No
!important— except terminal scrollbar overrides. - No pixel values outside the spacing scale unless component-specific dimension (like 28px repo initials).
- No inline styles for theming — all colors and spacing via CSS variables (desktop:
global.css, mobile:mobile.css).
Touch Sidebar Action Trays
Keep branch actions hidden at rest on touch devices. A left swipe reveals a
full-height tray with neutral More, accent Add, and error-coloured Remove
buttons, with at least 44px width per action. Only removable linked worktrees
show Remove. Keep native vertical scrolling with touch-action: pan-y.
Use the existing palette and radius tokens, and disable slide transitions when
reduced motion is requested. Mouse hover controls retain their existing layout.
Rich working agent rows reserve two clamped intent lines. Idle, awaiting-input and error rows stay on one line with status dots; their full intent, task or prompt remains in the tooltip. Compact rows keep their one-line layout.
Rich navigation keeps compact typography and padding. Branch identity and facts share one line, with names truncated and full PR/lifecycle facts in tooltips. Repository metadata disappears when PR and worktree counts are both zero. Header controls use compact sizing to protect repo names. Returned subagents fold into an expandable count independently of running work.
The mobile update banner sits below the app header to keep its small text away
from the translucent iOS status edge. It uses --mobile-update-foreground:
black on Commander’s blue accent and white on Paper’s darker blue. The pressed
state changes the background to --accent-hover instead of fading the whole
strip. Do not reuse Commander’s shared white accent foreground here: at 13px,
its 3.36:1 contrast does not meet WCAG AA.
Paper mobile question-banner names use --warning; Input badge labels use
--fg-primary over the existing attention tint. The Paper Input badge does not
fade: whole-badge opacity would reduce small-text contrast below WCAG AA.
Commander retains its urgent/attention foregrounds and pulse.
Constrained layouts and theme surfaces
- Detached Files and Markdown panels fill their window; inline panels retain their docked width limits.
- Dialog footer hints wrap as complete groups, with gaps between groups and actions. Action labels do not wrap letter by letter.
- Task field labels align at the top when neighboring controls have different heights. Roadmap state labels use ellipsis inside short bars.
- Native controls use the light color scheme on the Paper theme. Mobile bottom tabs and diff gutters use the existing application surface tokens.
ui/ColorSwatch is the shared native button for immediate preset/clear color selection.
It keeps selection in the owner through selected/aria-pressed, defaults to
type="button", forwards native refs/events/disabled, and uses a 36px circular
target with a 44px touch minimum. Set swatchColor for a preset; omit it for
the dashed clear target. Give each target an accessible name. Feature CSS may
arrange the wrapping picker but must not resize its swatches.
Shared edge actions and content-sized editors
- Use
Button geometry="stretch"for square-edged container-height actions. Keep placement in the consumer; do not restore feature-owned control sizes. - Use
ButtonGroupwith direct sharedButtonchildren for connected split actions. Buttons retain their own size and behavior; the shared group owns corners and the single divider. Do not clip focus rings or dropdown content. - Use
Textarea compactwhen an owner already manages editor expansion and needs a one-control-height minimum. Keep its padding in the shared primitive. - Use
Textarea autoGrowfor compact content-sized editors. The shared minimum is 36px desktop or 44px touch, and the maximum is three control heights. Remove consumer auto-resize callbacks and height caps when adopting it. - Rich editors use the same
FormControls.autoGrowintrinsic bounds. A rich editor can retain its established maximum through--auto-grow-max-height; CodeMirror owns content measurement, with no textarea sizing loop.FormControls.autoGrowMinimumreserves the same minimum without a maximum or scroll container, for layouts whose extra editor content overlays upward.
Shared validation and removable toggles
- Use native
aria-invalid="true"onInput,SelectandTextareafor an error-token border. Link existing validation text witharia-describedby. The shared keyboard focus indicator remains visible; text fields keep their inset accent band beside the error border. - Use
Button variant="removalToggle"only for an on/off action where clicking the pressed state removes or uninstalls the active integration. Set nativearia-pressedfrom owner state. Pressed uses the success border; enabled pressed hover uses the danger tone. Disabled actions keep their state tone. Ordinary selection buttons retain their existing accent styling.
Icon-only actions
Use Button shape="icon" aria-label="Describe the action" for an icon-only action.
Use circular when the action needs a circular visual. The native hit region stays
square at 36 × 36px in forms, 22 × 22px in toolbar rows, and 44 × 44px at touch widths; only the inner
surface is circular. size="compact" alone does not shrink a standalone icon target; a toolbar row selects toolbar density for all its controls. Icon mode
cannot combine with stretch geometry. Supply one icon or glyph and a nonempty,
descriptive aria-label (required by the TypeScript API); a tooltip alone is not
an accessible name. Do not add feature-level sizing or rounding rules.
Plugin Dashboard Style Guide
This document is the source of truth for plugin dashboard visuals. Every plugin that renders a dashboard (analytics, status, reports) MUST follow it so dashboards feel like a coherent part of TUICommander rather than a patchwork of third-party panels.
The reference implementation is the built-in Claude Usage dashboard (src/components/ClaudeUsageDashboard/). New plugin dashboards should visually match it at a glance.
Rules
- Use the shared classes. Do not hand-roll CSS for layout, cards, tables, stats, or typography. The classes below are injected into every plugin panel iframe via
PLUGIN_BASE_CSS(src/components/PluginPanel/pluginBaseStyles.ts). - Never hardcode colors. Use CSS variables (
var(--accent),var(--fg-primary),var(--bg-secondary), …). These follow the active theme. - Never hardcode pixel fonts for common text. Headings/body are sized by the base stylesheet.
- Register via
host.registerDashboard(...)so the Settings → Plugins row shows a one-click Dashboard button. Do not rely on context menus as the only entry point.
Layout skeleton
<div class="dashboard">
<div class="dash-header">
<h1 class="dash-title">My Plugin</h1>
<button class="primary" id="refresh">Refresh</button>
</div>
<div class="dash-section">
<h2 class="dash-section-title">
Overview
<span class="dash-section-hint">last 7 days</span>
</h2>
<div class="dash-stat-grid">
<div class="dash-stat">
<div class="dash-stat-label">Commands</div>
<div class="dash-stat-value">1.2k</div>
<div class="dash-stat-sub">+8% vs prev</div>
</div>
<!-- more .dash-stat cards … -->
</div>
</div>
<div class="dash-section">
<h2 class="dash-section-title">Details</h2>
<table>
<thead><tr><th>Name</th><th class="num">Count</th></tr></thead>
<tbody>…</tbody>
</table>
</div>
</div>
Class reference
| Class | Purpose |
|---|---|
.dashboard | Outer flex container. Provides padding, gap, vertical stacking. |
.dash-header | Top row with title + optional controls (refresh, selectors). |
.dash-title | 18px / 600 title. |
.dash-subtitle | Small muted subtitle (breadcrumb, repo name). |
.dash-section | Logical group. Inside .dashboard they auto-space via gap: 16px. |
.dash-section-title | Uppercase muted section label (12px / 600). |
.dash-section-hint | Inline secondary hint next to a section title. |
.dash-stat-grid | Auto-fill grid for headline numbers (minmax(160px, 1fr)). |
.dash-stat | Single stat card. |
.dash-stat-label | Uppercase 10px label. |
.dash-stat-value | 22px tabular value. |
.dash-stat-sub | Secondary caption under a value. |
.dash-meter / .dash-meter-fill | Horizontal progress bar. Add .ok, .warn, or .critical for color. |
.num | Right-aligned tabular cell (use inside table <th>/<td>). |
Generic classes from PLUGIN_BASE_CSS also apply inside dashboards: .card, .badge, .empty-state, button.primary, .hint, etc. See pluginBaseStyles.ts.
Do
- Keep the
<style>block inbuildPanelHtml()empty unless you need plugin-specific visual tweaks that cannot be expressed via the standard classes. - Place the refresh button inside
.dash-header, right-aligned viajustify-content: space-between. - Use
<table>+.numfor tabular data. The base stylesheet already themes it correctly. - Use
.dash-statcards for headline numbers, not custom grids. - Use
.empty-statefor “no data yet” screens.
Don’t
- Don’t redefine
.card,.stat-card,.stat-grid,h1/h2/h3sizes. These are global. - Don’t introduce custom color tokens — pick one of:
--accent,--success,--warning,--error,--fg-primary,--fg-secondary,--fg-muted,--bg-primary,--bg-secondary,--bg-tertiary,--border. - Don’t set explicit
background: #...anywhere. - Don’t wrap the dashboard in max-width containers narrower than the panel — let it fill the iframe.
- Don’t use emoji icons. Use monochrome inline SVGs with
fill="currentColor"(TUICommander convention).
Registering the dashboard
export default {
id: "my-plugin",
async onload(host) {
// ... existing capability setup ...
host.registerDashboard({
label: "My Plugin", // optional — defaults to "Dashboard"
icon: MY_PLUGIN_ICON, // optional inline SVG
open: () => openDashboard(host),
});
},
};
The registered entry powers the Dashboard button in Settings → Plugins next to the plugin’s enable toggle. The host also closes the Settings panel automatically on click so the dashboard becomes visible.
Checklist before shipping
- Dashboard uses
.dashboard+.dash-*classes — no duplicated layout CSS - No hardcoded colors or font sizes for common elements
- Registered via
host.registerDashboard(...) - Empty/error states use
.empty-state+ generic.card.error-cardif applicable - Verified visually against
ClaudeUsageDashboardside-by-side
HTTP API Reference
App config reads (GET /config and load_config) can include the transient config_recovery: { fields: string[], backup_path: string } diagnostic after startup recovery. It names reset fields and the preserved original; it is never persisted.
Build identity
GET /api/version returns version and git_hash in all builds. The desktop
debug WebView also receives window.__TUIC_DEV_BACKEND__ before frontend scripts:
exe (current executable), build_exe (original Cargo artifact when the copy
runner is used), bridge_exe (the used bridge build artifact, when present),
started_at_ms (application-entry Unix milliseconds), and git_hash.
Vite alone serves GET /__tuic_backend_identity?backend=<URL-encoded launch JSON>,
uncached. It returns status (current, stale, or unavailable), a dismissal
key, and, when available, backend_id, tree_id, and the checked input count.
It reads Cargo’s final binary dep-info and compares mtimes. This development
endpoint is not part of the packaged HTTP server; release builds expose neither
the launch global nor the warning module.
Planner Ideas use the same StoryAction envelope as plans and stories: add_idea {text,source?}, list_ideas, and update_idea {idea_id,text}. IPC story_action_command, HTTP POST /stories/action?path=<project> ({action:<StoryAction>,sessionId?:string}), CLI tuic story, and MCP workflow action=story input=<StoryAction> share the Rust owner. Add/update return {type:"idea",value:<camelCase Idea>}; list returns {type:"ideas",value:[...]}. The project sets repoPath; list also includes global Ideas, while update requires project ownership. Source defaults to the bound session id or local-api. Text is trimmed to a nonblank maximum of 16000 characters; source is nonblank with a maximum of 256. Writes use the strict locked notes.json owner and publish payload-free ideas-changed on desktop and /events SSE. UI save_notes(base,config) / PUT /config/notes applies per-id and per-field intent instead of replacing stale arrays. See Ideas through the planner.
Native plans have a stored revision. update_plan takes plan_id, expected_revision, and patch with optional title and source. At least one field is required. The shared service validates both fields and commits them with one revision increment in one transaction; stale revisions leave the plan unchanged. Existing records start at revision 1. A metadata change changes the workflow planning and verification fingerprints, including plans with no stories. Source prose stays in the external document; the update does not move or rewrite that file. Source-changing edits are refused with a user error while a plan coordinator/planner attempt is running, including an unbound attempt or a paused run. Finish the coordinator or cancel its run first. Title-only and unchanged-source edits remain allowed. The same action is available through MCP, HTTP, desktop IPC, and tuic story.
Scoped plugin settings
POST /api/plugins/{id}/settings accepts the same tagged PluginAction body as IPC: describe, get, set, reset, patch. Get takes paths; writes take expectedRevision. It returns descriptors, a redacted snapshot or a commit reply. Errors are structured settings failures: 400 invalid path/value, 404 unloaded owner, 409 stale revision. Existing API authentication applies. No caller-selected target, store or file is accepted.
POST /sessions/:id/queue optionally accepts expectedDraft. It must match the tracked live composer and trim to text; the server clears that draft before using the existing ready-window queue. Preflight rejection writes nothing. A later error may have cleared the composer, so clients must report uncertainty and must not automatically retry this transfer.
Request authentication and browser boundary
Every TCP request validates its Host and Origin before reaching a handler, including login, health and preflight requests. Unknown/missing/duplicate Host or foreign/opaque Origin returns 403. Allowed hosts are localhost, loopback/private IP literals, local interface IPs and the detected Tailscale FQDN. Allowed origins are the exact bundled WebView origins, Vite http://127.0.0.1:1421/http://localhost:1421, and the HTTP/HTTPS origin of the validated Host. Cross-site requests are rejected except for the explicit WebView/development origins.
Protected routes require the existing ?token=..., tui-session cookie or Basic Auth even from loopback/LAN. Native HTTP clients may omit Origin, but must send Host and credentials. Login assets and valid preflight remain public; the headless /health probe remains public. Local Unix socket and Windows named-pipe clients keep their existing IPC access.
HTML GET navigation to / and /mobile uses /mobile/login when credentials are missing and a password is configured. After login, next may return to / (including its query) or a mobile path. API calls and non-HTML requests keep the existing 401 Basic challenge.
Native stories
POST /stories/action?path=<project> also accepts {action:{action:"backend_status"}}. It returns {type:"backend_status",value:{backend,label,provenance,reason,availability,installation,version,error,generation}}, including unavailable configuration. {action:{action:"approve_connector",installation:"/resolved/install",expected_identity:"displayed-version:entry-sha256"}} saves global installed-Wiz approval only for an authenticated human caller, not a managed session. It uses the same action service as IPC. See the story backend protocol for approval drift and detection rules.
set_backend {backend:"native"|"automatic"|"wiz-stories"} is also an authenticated-human-only shared action. Native continuity precedes discovery; active run snapshot provenance prevents backend changes after restart. Approval compares the displayed generation (entry/version), not a full installation-tree digest.
Native stories expose qa for work that waits on manual checks. A criterion starts with [MANUAL], or is marked through set_criterion_manual {index,manual}. Active work automatically enters QA when all unchecked criteria are manual; submit_qa explicitly requests that state. reject_qa returns QA to In progress; approve requires every criterion checked. QA keeps plans Active and dependencies blocked. All transitions retain expected-revision checks. See the native stories guide.
Reversible native record archival
All native story transports share archive_story, unarchive_story, archive_plan, and unarchive_plan. Story actions take story_id; plan actions take plan_id. Each requires expected_revision and returns the updated record with its incremented revision and archived flag. Stale revisions fail without a write. Archival preserves status, criteria, dependencies, and child archive flags; it never deletes records or cascades to children.
list_plans and list_stories default to archived: false. Set archived: true to select archived records. The story filter combines with the other filters and is bound into pagination cursors. filtered_plan_view also accepts camel-case filter.archived (default false), which selects archived list ids and board columns without changing the active-plan state calculation. Direct reads remain available. Default plan views and workflow dispatch omit archived stories; archived plans and stories cannot start manual or workflow work. Restore the parent plan before starting its stories.
Both archive and restore refuse claimed stories and plans that contain a claimed story. Story archival also refuses any prerequisite that is not Done while an open dependent references it, including inside an archived plan. The refusal lists the dependent IDs and leaves the record and history unchanged. WontFix does not satisfy dependencies. Done prerequisites and unresolved stories with only closed dependents remain archivable. Adding a dependency to an archived unresolved story requires restoring it first; both dependency editors enforce this rule. Whole-plan archival does not change dependency readiness. An active or paused plan-root workflow owns the plan’s story set. A story-root workflow owns its target and execution stories, not unrelated siblings. Cleanup of an owned story or its parent plan is refused until the run ends. The workflow writer lock remains held through the archive transaction, so a concurrent run cannot start between the ownership check and the write.
story_archive_history (story_id) and plan_archive_history (plan_id) return {type:"archive_history",value:[{revision,archived,actor}]} in revision order. Events commit atomically with the record and retain caller provenance. Existing status transition history remains separate. Consecutive archive-only revisions preserve accepted-work integration receipts; a work change or a moved canonical Git ref still invalidates them. Example: tuic story '{"action":"archive_story","story_id":"<id>","expected_revision":1}' --project /absolute/project.
GET /stories/capabilities?path=<project> returns the story capability descriptor of the project’s backend, { "backend": "native" | "external:<adapter id>", "operations": { ... } }, with one boolean per operation (without path: the native descriptor; an external adapter that cannot start answers 503, never the native descriptor); a plain true comes from a backend older than the story backend port and is treated as outdated. The frontend refreshes capabilities on dialog opening, project/backend refresh and repository revisions, recognizes a missing route by HTTP 404, and preserves other HTTP failures as errors.
POST /stories/action?path=<absolute-project> accepts { "action": StoryAction, "sessionId"?: string } and returns a tagged StoryReply ({type, value}). StoryAction uses a snake-case action discriminator: create_plan, list_plans, list_plan_sources, add_plan_source, get_plan, plan_state, plan_view, filtered_plan_view, create_story, update_story, list_stories, get_story, transition_history, add_dependency, remove_dependency, claim, or transition. Create-story input uses the shared camel-case NewStory fields. create_plan takes title and source; add_plan_source takes a local document source and derives its title from front matter or the first heading. list_plan_sources reads top-level Markdown files in plans/ and .claude/plans/, so a new file appears on the next call. It returns {type:"plan_sources",value:[{title,source}]}. get_plan, plan_state, plan_view, and list_stories take plan_id; get_story and transition_history take story_id; claim takes story_id and expected_revision; transition also takes a command; both dependency actions take story_id, dependency_id, and expected_revision. transition_history returns committed transitions with their resulting revisions, commands, and actor provenance.
add_plan_source reuses an active plan with the same source. If only an archived plan matches, it returns an error that identifies the plan and gives explicit restore instructions; it does not create another record or change archive state.
Story transition provenance comes from host-validated credentials: desktop IPC and credential-authenticated HTTP record human; sessionless local HTTP records local_api. Managed calls record their session identity, including when the claiming session approves its own story. Actor identity never restricts actions; state, revision, project and claim-conflict rules remain enforced.
plan_view returns {type:"plan_view",value:{stories,state,wontFixCount,allCancelled,visibleStoryIds,columns}}. Each story in stories includes a read-only abandoned boolean, derived from whether that story or any dependency reachable from it is WontFix. The summary and state are derived from the same read; no abandonment flag is persisted.
list_stories accepts optional snake-case state (a native story status), priority (1–3), and story_type (feature, fix, refactor, chore, task). Filters combine with AND; omitted filters match all values, including untyped records. The type filter reads persisted storyType, not origin. With no limit, the reply remains the complete filtered {type:"stories",value:Story[]} in ascending id order. A limit of 1–100 opts into keyset pagination; next_cursor is an optional sibling of value and is absent on the final page. Send it as cursor with a limit and the same plan and filters. Cursors are versioned, limited to 1024 bytes, and rejected for another plan/query; invalid priority, limit, or cursor values return HTTP 422 user errors. Page size may change between requests. These are live reads, not retained snapshots: changes at or before an already consumed id require starting again without a cursor. Internal workflow dispatch still reads the full plan and retains priority/id ordering. Archive filtering uses the archived flag described below.
project_story_view takes archived_plans (default false) and a camel-case filter with the same fields and defaults as filtered_plan_view. It returns {type:"project_story_view",value:{stories,visibleStoryIds,columns}} across every plan in the envelope project and selected plan archive scope. archived_plans:true selects archived plans only; filter.archived:true independently selects archived stories. Full records remain available for detail and dependency reads; only display ids and columns are filtered. The reply has no combined plan state. The shared StoryAction service exposes this action through IPC, HTTP, MCP and CLI.
filtered_plan_view takes plan_id and a camel-case filter: {visibility:"all"|"open"|"closed",storyType?:"feature"|"fix"|"refactor"|"chore"|"task"|null,untypedOnly?:boolean}. Defaults are all statuses and all types. Open excludes only done and wont_fix; closed includes those two states. untypedOnly:true cannot be combined with a non-null storyType. The reply is the same plan_view shape. Full stories and plan summary remain unfiltered for detail and dependency reads; visibleStoryIds and columns:[{status,storyIds}] are the Rust-owned display projection. The unfiltered action supplies the all-stories projection. Creation input and stored story JSON accept optional storyType; omitted historical values stay absent and untyped. No database migration assigns a type.
GET /stories/capabilities also exposes additive operations.story_edits:
{title,priority,problem,criteria_add,single_change}. update_story remains the
legacy aggregate flag (native true; external apply && set_fields). For a
restricted external adapter, the shared update action accepts one supported
metadata field or one appended criterion only, never a split multi-op save;
unsupported patches refuse with zero applies. Dedicated dependency actions are
separate. Native and aggregate legacy behavior is unchanged; the latter’s
existing multi-op sequence is not atomic. See the protocol mapping.
Native update_story takes story_id, expected_revision, and a camel-case patch. Omitted fields stay unchanged. The patch accepts title, priority (1–3), fileScope, origin (including a plan step), nullable storyType (feature, fix, refactor, chore, task), optional problem and risk (low, medium, high), ordered criteria, and the final dependencies set. Null clears storyType, problem or risk; old story records default both to absent. Unknown fields, invalid values, cross-plan dependencies, duplicates, cycles and stale revisions are rejected without partial story writes. Only unclaimed Backlog/Ready stories without active or paused workflow ownership can be amended. Unique byte-identical criteria retain their checks after reorder; changed, new or ambiguous duplicate criteria become unchecked. A priority-only patch preserves all checks. Dependency changes recompute readiness. Planning and execution fingerprints include the amended requirements/revision, so existing evidence cannot certify changed work.
summary returns {type:"summary",value:{activePlans,ready,inProgress,qa,done,total}} for the project: plans whose derived state is active, and over their stories those in_progress, those waiting in qa, those done, and all except wont_fix and abandoned ones. The Plans and Stories toolbar button reads it; it is also available over IPC through story_action_command.
The project path is resolved to its canonical owner, so a managed worktree shares its parent project’s plans. Unknown action and create-story fields are rejected. Claim requires a live PTY session in that project. transition accepts the start_manual command to begin a Ready story without a terminal. Actor identity is tracking only; managed, local API and human callers use the same transition rules. remove_dependency accepts only a Backlog dependent with a direct WontFix prerequisite; it returns the revised story, Ready only when all remaining prerequisites are Done. WontFix never satisfies dependencies. A nonempty plan with only Done/WontFix stories has plan_state: done, while an empty plan is draft. Reads and writes verify the stored plan’s project; a story ID alone grants no cross-project access. Revisions are required for mutations to detect stale clients. The same service backs desktop IPC and MCP. There is no import or export endpoint.
Project Progress
Six POST routes and one GET route, all with normal route authentication.
The mobile PWA uses GET /progress/projects to discover journal projects,
newest activity first. The POST routes other than /progress/flow/detail
require an explicit path query naming a registered project.
| Route | Body | Response |
|---|---|---|
/progress/report | { type, text, step? }, type is done or blocked | { id } |
/progress/list | { progressOnly?, blockedOnly?, ptyId?, limit?, cursor? } | { project, entries, total, nextCursor, ptyIds, lastViewedMs? } |
GET /progress/projects | none | Array of project paths with journal entries, newest first |
/progress/delete | { ids } | { deleted } |
/progress/viewed?ptyId=<id> | none | { lastViewedMs } |
/progress/flow | { ptyId? } | ProgressFlow |
/progress/flow/detail | { ptyId, agentId, part }, part is prompt or report | { text } |
Unknown fields are rejected. text is capped at 500 characters and step at 80.
All Progress entry kinds redact secret-shaped text and step fields before
storage; agent and target names are redacted and capped at 80 characters.
Omit ptyId on /progress/viewed to mark the repository aggregate; supply it
to mark one PTY. Each scope keeps a separate last-visit timestamp.
intent is a valid entry kind but not a reportable one — TUIC writes those
itself from the agent’s intent: marker, and /progress/report refuses one.
ptyId selects one PTY; omitting it returns the repository aggregate. Each
entry includes ptyId when TUIC knows its source. Older entries and direct
IPC/HTTP reports have no PTY ID and remain visible in the aggregate. ptyIds
lists the 32 most recently active PTYs with stored history, including closed PTYs;
older PTYs’ entries stay in the aggregate. The list is
newest-first in pages of 8 entries by default. limit is clamped to 1–100;
total counts entries matching the filters before the cursor, and nextCursor
is null after the last page. Pass it back as cursor to read older entries.
There is no revision: the journal is append-only, so an entry is written once
and either kept or deleted. The one exception is a host-written intent that
repeats that PTY’s newest intent (same text, same agent): it returns the
existing entry, because a screen repaint is not a new intent. delete is scoped
to the project in the query, so one project cannot delete another project’s row
by id.
Recorded entries are published as progress-recorded on /events with
{ entry } as the payload.
delegated and message are host-written like intent. TUIC writes a
delegated entry when a terminal runs agent action=spawn and a message
entry when it runs agent action=send to a peer that has a terminal. The entry
is attributed to the sender’s PTY and adds targetPtyId and targetName. Its
text is the prompt or message, redacted first and then cut to 500 characters;
the full text is not stored. /progress/report refuses both kinds.
/progress/flow draws the journal as a delegation sequence. All ordering,
joining and redaction happen in Rust:
ProgressFlow = {
project, truncated, // truncated: journal > 500 entries
participants: [{ id, kind: "terminal"|"subagent", title, agentType?,
state: "busy"|"idle"|"awaiting"|"closed"|"running"|"done",
parent?, intent?, toolCalls, ptyId, agentId? }],
events: [{ id, kind: "intent"|"done"|"blocked"|"delegated"|"message"
|"subagent_spawn"|"subagent_return",
from, to?, summary, text?, detail?: { ptyId, agentId, part },
step?, atMs }] // oldest first
}
A terminal is a participant when it wrote an entry or was the target of one. A
subagent id is <ptyId>/<agentId>. Participants come parents first. A child’s
done/blocked has to set to the terminal that delegated to it; without a
parent, to is absent and the event is a note on its own column. Subagent
spawns and returns are read from the Claude transcripts of open terminals only.
summary is redacted and at most 200 characters. text is the whole redacted
journal text, present only when the summary is shorter. detail marks a
subagent arrow whose full prompt or report must be fetched from
/progress/flow/detail; that route looks ptyId up in AppState and compares
agentId with the subagents listed on disk, so neither value can reach a path.
An event id is stable across reads (entry:<journal id>, or
<ptyId>/<agentId>:spawn / :return); key client state by it, never by
position. Past 64 subagents per terminal, the newest are kept plus every one
still running. Both routes run on the blocking pool.
With ptyId, the flow keeps that terminal, its direct parent and its direct
children.
REST API served by the Axum HTTP server when MCP server is enabled. All Tauri commands are accessible as HTTP endpoints.
progressOnly: true selects only intent, done, and blocked before counting and pagination. It intersects with blockedOnly and ptyId; omitted or false keeps all five kinds. The mobile list enables it by default. Flow is not filtered.
Base URL
- Local (Unix socket):
<config_dir>/mcp.sock— always started on macOS/Linux. No auth, MCP always enabled. Used by the local MCP bridge binary. - Remote (TCP):
http://<host>:{remote_access_port}— only started when remote access is enabled in settings. HTTP Basic Auth required.
Authentication
- MCP mode (localhost): No authentication
- Remote access mode: HTTP Basic Auth with configured username/password, or
the
?token=session token the QR code embeds.
Both halves of the credential pair are required: validate_basic_auth
(mcp_http/auth.rs) reports NotConfigured when either the username or the
password hash is empty, and the server then answers every Basic Auth attempt
with 401 and the body Scan the QR code or authenticate with Basic Auth — the
same response a request with no Authorization header gets. A 401 carrying that
body while credentials were sent means the pair is incomplete, not wrong.
GET /api/auth/session-token
Trades an authenticated Basic Auth call for the running session token:
{ "token": "b0b9…" }
It is in shared_routes(), not the desktop router, on purpose — the daemon
run_remote starts builds build_remote_router, so a route registered only in
build_router would 404 on the one server that needs it.
This is how a client escapes header-only Basic Auth. A WebSocket upgrade cannot
carry an Authorization header, and with remote_auth on the server answers
Access-Control-Allow-Origin: *, which forbids credentialed cookies; ?token=
is the only credential HTTP, WS and SSE can all carry. 503 means the server
has no session token configured.
tuic-remote generates its token on the first start and stores it in the
credential vault like the desktop does, so a restart keeps the token and every
paired phone stays logged in. A host with no usable vault falls back to a token
that lives for one run (logged as a warning); a client re-fetches the token on
every connect either way.
Session cookie
A successful login (QR token, Basic Auth or the form below) sets the
tui-session cookie. It is sliding: every authenticated request re-issues
it with a fresh Max-Age, so a device in use never expires. The lifetime is
services.auth.session_token_duration_secs, 30 days (2592000) by default —
the longest a device may sit unused before it must log in again. Rotating the
session token logs every device out.
Mobile login form: /mobile/login and POST /auth/login
A page navigation of the mobile app (GET /mobile, /mobile/*, Accept: text/html) without a valid session is redirected (302) to
/mobile/login?next=<path> when a username and password are configured. An iOS
home-screen app never shows the native Basic dialog, so the in-app form is the
only way back in. Every other unauthenticated request keeps the 401 +
WWW-Authenticate: Basic contract, and so does a navigation when no password is
configured.
Public without a session: GET /mobile/login, GET /mobile-login.js and
POST /auth/login (nothing else).
POST /auth/login
Content-Type: application/json
{ "username": "…", "password": "…", "next": "/mobile/session/a" }
200 {"ok":true,"next":"/mobile/session/a"}+Set-Cookie: tui-session=….nextis returned only if it is inside/mobile, otherwise/mobile.401wrong credentials or no password configured; noWWW-Authenticate.403cross-origin:Sec-Fetch-Sitemust besame-origin, or, when the browser sends none (plain HTTP on a LAN address),Originmust matchHost.415notapplication/json;400malformed body;413body over 4 KiB.429+Retry-After: the per-IP failure budget is spent. The body is{"error":"…"};errornames the wait and the QR recovery, and the login page shows it. The Basic fallback answers the same text as a plain body.
Lockout and recovery. At most services.auth.auth_rate_limit_max (default
5) new credentials per IP reach bcrypt in each
services.auth.auth_rate_limit_window_secs window (default 300 s; 0 max turns
the limit off). A repeat of a cached wrong credential answers 401 and spends
nothing. Once the budget is spent, every new credential gets 429, the correct
password included, until the window ends. The QR ?token= and the session
cookie are checked before admission, so they still sign in, and a QR sign-in
clears the IP’s budget. A wrong token is a plain 401 and opens no extra
budget.
Credentials are checked by the same code as the Basic fallback (per-IP rate
limit, failed-credential cache, bcrypt on a blocking thread), so form and Basic
failures spend one shared budget. The service worker never caches
/mobile/login or a non-200 response as the offline shell.
Server Limits
Both the desktop and remote routers apply request bounds
(with_server_limits in mcp_http/mod.rs):
408 Request Timeout— a handler that has not produced a response within 301 s is cut off. This includes slow worktree creation with warm build artifacts while still bounding a wedged handler. 301 s is a deliberate 1 s margin aboveui action=confirm’s own 300 s answer window, so that handler’s own timeout body always wins the race instead of a bare 408 (docs/backend/mcp-http.md→ “Server Limits”). SSE (/events) and WebSocket endpoints return their headers immediately and then stream for as long as they like, unaffected. Streamed/fs/upload-copyuses a 30 s idle deadline per body chunk instead of this total response deadline. A separate 17-minute total receive budget also prevents trickling clients from retaining an upload slot.413 Payload Too Large— a request body over 2 MB is refused rather than buffered. Exceptions:/fs/writeand/fs/write-externalaccept up to the twice the editor large-file cap plus 64 KiB (500 MiB + 64 KiB; JSON escaping can double the text) so the remote editor can save any file it opens;/fs/write-if-unchangedkeeps 2 MB.
See docs/backend/mcp-http.md → “Server Limits” for
the rationale and the tests that pin both.
Unknown Paths
The desktop server also serves the frontend, so any path that matches no route falls through to a catch-all. That catch-all splits on the first path segment:
- API path — the first segment is one of
agent,agents,ai,api,attachments,audio,claude,codex,config,debug,diagnostics,dictation,events,exec,fs,generators,github,health,logs,mcp,metrics,plugins,process,prompt,registry,repo,sessions,stats,system,tasks,terminal,tunnels,watchers,worktrees. The response is404with{ "error": "no such endpoint: /<path>" }. - Anything else — a deep link such as
/settingsor/mobile/session/<id>. The response is200with the SPA shell (index.html, ormobile.htmlunder/mobile), so client-side routing takes over.
A registered path called with the wrong method still returns 405, not 404.
The catch-all is the router’s fallback, so it answers on every method: an
unregistered path returns 404 whether it was reached with GET, POST or
anything else. It used to be a GET-only route, which made any non-GET call
to a path that does not exist answer 405 — a reply that claims the path is
real. The parity gate below depends on telling those two apart.
Without this split an unregistered API path answered 200 with HTML, which the
client read as success and then failed to parse as a command result — every
missing route looked like a malformed response. The prefix list is checked
against the registered routes by a test, so a new route family cannot silently
drop back to the HTML answer.
The tuic-remote daemon embeds no frontend and has no catch-all: unknown paths
there return a bare 404.
Route Parity Gate
Every COMMAND_TABLE entry in src/transport.ts must resolve to a registered
route. Two tests enforce it, one per language:
src/__tests__/transport.test.tsexecutes every mapper and snapshots the resulting paths tosrc-tauri/src/mcp_http/command_table_paths.txt.mcp_http::tests::command_table_paths_all_hit_a_registered_routereads that file andPATCH-probes each path againstbuild_router.PATCHis used because no route accepts it, so a registered path answers405without running its handler, while an unregistered one falls through to the catch-all. A404or an HTML body fails the test.
Adding a command therefore fails the Vitest half first (stale snapshot). Regenerate with:
pnpm vitest run src/__tests__/transport.test.ts -u
If the route was never registered, the Rust half then fails. Both run in
make check. The gate proves the path exists, not that it accepts the
method the table declares — probing the declared method would execute the
handler, which is what the technique avoids.
INTENTIONALLY_UNMAPPED commands never enter the snapshot: they are not
COMMAND_TABLE entries, and the Vitest half asserts the two sets stay disjoint.
Session Endpoints
List Sessions
GET /sessions
Session rows include optional child_pid: the live PTY child PID, not the foreground agent leaf. It is omitted when unavailable or exited. list_active_sessions returns the same field over desktop IPC; mirrored rows retain their owning connection_id.
Returns array of active session info (ID, cwd, worktree path, branch,
display_name, display_name_is_custom, display_name_from_spawn,
is_remote, optional pty_description, optional terminal alias, optional
parent_session, optional tuic_session, and nested state). The
alias field is the only record of a tab’s alias after a WebView reload, because
term-alias-assigned fires once, at spawn; parent_session is the same for the
sub-agent tag, which session-created publishes once. It holds only a resolved
parent, never a pending-mcp: placeholder.
tuic_session identifies the live agent bound to this PTY, which may differ from
session_id; clients use it to name a spawned child’s parent. It is omitted
when no live identity is bound. display_name_from_spawn is true when
agent action=spawn named the session and no user rename has replaced it; a
non-custom name synced back from an OSC or intent title does not set it. The
origin fields let browser and desktop clients preserve manual-title protection
and remote-completion muting across reconnects. For detected agents,
state.agent_state distinguishes PTY
silence (idle) from explicit protocol completion (completed); the latter
requires a parsed suggest: [ ... ] marker. Other values are starting,
working, and awaiting_input. state.background_work is true when meaningful
non-helper descendants keep autonomous work alive despite an input-ready
terminal (state.shell_state == "idle").
Sessions running on a connected remote machine are in this list too, each
with connection_id naming the connection that owns it; a local row has no such
field (#791-055e). The rows come from remote_mirror.rs, which reads the remote
daemon’s own GET /sessions and then follows its /events. The Tauri command
list_active_sessions answers with the same rows, from the same builder.
Create Session
POST /sessions
Content-Type: application/json
{
"rows": 24,
"cols": 80,
"shell": "/bin/zsh", // optional
"cwd": "/path/to/dir", // optional
"alias": "tu-1" // optional — reclaim a persisted alias
}
Returns { "session_id": "..." }.
When cwd is missing or names a file, the server returns 400 with { "error": "Working directory ..." } before registering a PTY session.
alias lets a client restore the short address a tab had before a restart. The server
honours it only when it still has the <prefix>-<number> shape and no live session
holds it, and then raises the per-prefix counter past that number so the next
auto-assigned alias cannot collide. Anything else is ignored and the session receives a
freshly minted alias.
Create Session with Worktree
POST /sessions/worktree
Content-Type: application/json
{ "pty_config": { ... }, "worktree_config": { ... } }
Creates a git worktree and a PTY session in one call.
Spawn Agent Session
POST /sessions/agent
Content-Type: application/json
{ "agent_type": "codex", "prompt": "Fix the bug", "args": ["resume"] }
Spawns an AI agent in a PTY session. The request is flat; browser transport sends
only the HTTP spawn fields from the desktop pty_config and agent_config objects.
It uses agent_config.cwd when present, otherwise pty_config.cwd. Desktop-only
PTY fields such as shell, tuic_session, and alias are omitted. The optional
env map and model string use the same field names as desktop IPC spawn. By default,
supported interactive CLIs use native scrollback according to the agent’s
prevent_alt_screen setting.
The child receives its own TUIC_SESSION, equal to the returned session_id,
and GET /sessions exposes that identity as tuic_session immediately.
Write to Session
POST /sessions/:id/write
Content-Type: application/json
{ "data": "ls -la\n" }
Raw /write and /write-parts calls leave the runtime thread free and return
an error after two seconds if PTY input has not finished. Delivery is uncertain:
a started kernel write may still complete, so clients must not automatically
resend the data. WebSocket input uses the same bound and closes the connection
on a write error. Session close bypasses the writer and can terminate a blocked
session.
Submit One Managed-Agent Reply
POST /sessions/:id/submit
Content-Type: application/json
{ "input": "Please wait for my approval" }
Authenticated browser/PWA counterpart of session action=submit. It checks the
managed agent and empty composer, writes the whole reply and Enter atomically,
and returns the same submission receipt. An explicit human reply can answer an
awaiting_input session even while its shell is busy and no question text was
recognized. Otherwise confirmed idle is required. A recognized picker returns
selection_required: use its answer controls instead of submitting prose. A closed session returns
HTTP 404 with submitted: false and reason: "session_not_found"; another
rejection returns HTTP 409 and its precise reason. A successful write can
still have acknowledged: false: the client must not retry blindly. While a
question is awaiting human input, a human reply can pass queued automated messages;
those messages remain parked until the question clears. The mobile client shows
the returned detail on refusal and keeps the draft. Foreground ownership,
unfinished drafts and uncertain prior writes still block submission. Automated
session action=submit may answer confirmed-idle conversational questions,
including progress blocked reports, but cannot answer native dialogs. Native
refusals include prompt_kind: choice, approval, free_text, or question.
The human HTTP reply path retains its busy-question behavior.
Write Several Inputs at Once
POST /sessions/:id/write-parts
Content-Type: application/json
{ "parts": ["/", "help", "\r"] }
One round trip and one PTY writer lock for the whole batch, but the parts stay
separate: the backend applies its post-write bookkeeping once per part. This is
not the same as joining them into /write — that bookkeeping reads each part
as one keystroke, so a lone / opens slash mode and an exact option key answers
a choice prompt, and a joined payload matches neither. The transport uses this
route when keystrokes arrive while an earlier write is still in flight; a
solitary keystroke keeps the plain /write route.
Queue a Command for the Next Idle Window
POST /sessions/:id/queue
Content-Type: application/json
{ "text": "run the tests", "idempotencyKey": "bg-job-1" }
-> { "accepted": true, "typed": false, "queued": 2 }
GET /sessions/:id/queue -> [ { "id": 7, "text": "run the tests", "kind": "user_command", "send_now": "interrupt" } ]
DELETE /sessions/:id/queue -> 2 (commands dropped)
DELETE /sessions/:id/queue/:cmdId -> true (false when it already drained)
POST /sessions/:id/queue/:cmdId/send-now -> true (false when already claimed)
The explicit send-now action instead forces the selected item through the shared Claude Code, Codex and ego steer flow: Escape, confirmed idle (up to ten seconds), then full-text submission ahead of ordinary queued mail. It never uses busy Enter or backgrounds a running tool. A refusal restores an unwritten queued item; an uncertain write is not retried.
Hands the text to the same idle gate peer messages use instead of typing it now:
submitted immediately when the agent is idle (typed: true, queued: 0),
otherwise parked until the agent’s next busy→idle transition, so a running turn
is never steered. User commands and peer messages share one typed FIFO and are
submitted one per idle window in backend acceptance order (a run of hands-free
voice entries at the head is joined into one submission). queued,
state.queued_commands, and DELETE count or remove only user commands;
clearing Compose commands never deletes pending peer/orchestrator delivery.
Automatic background completions additionally send automaticCompletionOrigin,
using state.background_wake_origin from the originating session’s launch-time
GET /sessions row. A native user stop revokes that origin permanently, including
across later explicit turns. The queue checks origin at arrival, flush and the
serialized PTY write. A stale origin returns accepted: true, typed: false,
retained: true: keep the log and receipt; do not retry through mail or restore a
suspended session. Ordinary explicit commands omit this field and stay valid.
idempotencyKey is optional. Use the same key for retries of one logical
command; distinct commands need distinct keys even when their text is identical.
Keys contain 1–128 UTF-8 bytes. The backend
remembers the last 128 accepted keys per live PTY, including drained or cancelled
entries. A recognized retry returns accepted: true, typed: false and the
current queue depth without appending or flushing again. accepted confirms
queue acceptance, not a model turn. Keys expire on eviction, PTY teardown or
backend restart; this is an in-memory retry window. Omitted keys preserve the
usual append behavior. HTTP and Tauri use the same request and response fields.
Agent sessions only — 400 for a plain shell ("Session is not running an agent") or empty text, 404 when the PTY is gone. The current depth is also on
every session snapshot as state.queued_commands (omitted when zero).
Resize Session
POST /sessions/:id/resize
Content-Type: application/json
{ "rows": 30, "cols": 120 }
Read Output
GET /sessions/:id/output?limit=4096&format=text
Returns recent output. Format controls what is returned:
format | Response shape | Description |
|---|---|---|
| (omit) | { "data": "<string>", "data_length": N, "total_written": N } | Raw PTY output as a lossy-UTF-8 string (not base64), read from the ring buffer |
text | { "data": "<string>", "data_length": N, "total_written": N } | One canonical terminal-grid snapshot, joined by \n (not from the ring buffer) |
log | { "lines": [...], "total_lines": N, "screen": [...], "input_line"? } | VT100-extracted clean lines (no ANSI, no TUI garbage) plus current screen rows and optional input line |
| Param | Default | Description |
|---|---|---|
limit | raw: 8192 bytes; text/log: all | raw: max bytes; text/log: max lines to return |
offset | (tail) | text/log: absolute start row/line offset. When omitted, returns the newest limit rows/lines. When provided, returns data starting from that offset |
format | (raw) | See table above |
format=log reads from VtLogBuffer — a VT100-aware buffer that extracts only scrolled-off lines, suppressing alternate-screen TUI apps (vim, htop, claude). Ideal for mobile clients.
The HTTP log response and log-WebSocket screen use the shared active agent identity.
After agent exit, they keep the shell prompt and subsequent output even if old
agent chrome remains on screen, and omit the historical agent input_line.
format=text is a point-in-time canonical grid view. It does not concatenate
the finalized log cursor with the visible screen, because growing a viewport can
move history rows back onto the screen and make that concatenation overlap.
total_written is the snapshot’s total grid-row count for this format.
total_lines in the response is a monotonically increasing counter — it never decreases when old lines are evicted from the buffer. Use it as a stable cursor for paginated reads. The offset parameter operates in the same coordinate space.
Kitty Protocol Flags
GET /sessions/:id/kitty-flags
Returns the current Kitty keyboard protocol flags (integer) for a session.
Foreground Process
GET /sessions/:id/foreground
Returns the foreground process info for a session. Detection uses the spawn-recorded root role and foreground process group. Returning to a shell root revokes an observed agent; a child of a direct agent holds unattended input without revoking its identity. Unknown root ownership refuses unattended input. Concurrent observations apply in generation order.
PTY / Terminal Read State
GET /sessions/:id/shell-state -> { "state": "busy"|"idle"|null }
GET /sessions/:id/shell-family -> "posix"|"windows-native"|"unknown"|null
GET /sessions/:id/last-prompt -> { "prompt": string|null }
GET /sessions/:id/input-buffer -> { "content": string }
GET /sessions/:id/leaf-pid -> { "pid": number|null }
GET /sessions/:id/chat-view?from_seq=N&epoch=E -> { epoch, nextSeq, reset, updates[], unknownRows, malformedRows, pendingTexts: [] }
POST /sessions/:id/chat-view { epoch?, fromSeq?, pendingTexts?: string[] } -> same snapshot with cleaned pendingTexts[]
GET /sessions/:id/chat-view/messages/:message_id/full-text -> { text } (the whole message the stream capped; Claude only)
GET /sessions/:id/has-foreground -> { "process": string|null }
POST /sessions/:id/visible { "visible": bool } -> { "ok": true }
GET /sessions/:id/terminal/selection-text?startRow=&startCol=&endRow=&endCol=&historyBase= -> { "text": string }
GET /sessions/:id/terminal/logical-line?row=N -> [logicalStartRow, text]
GET /sessions/:id/terminal/hyperlink-span?row=R&col=C -> [startCol, endCol, url] | null
GET /sessions/:id/terminal/styled-rows?start=N&count=N -> application/octet-stream (packed rows)
GET /process/stats -> ProcessStats[]
POST chat-view accepts optional pending prompt candidates in its JSON body, not the URL. pendingTexts in the response preserves request order and uses the same Rust redaction-then-character-cap contract as native user messages. Desktop IPC accepts the same camelCase fields. Terminal Chat compares these forms while keeping original pending text for display; normalization adds no extra polling. The GET form remains available for readers without candidates.
chat-view is the transcript of a Claude or Grok terminal as ACP SessionUpdates, tailed from the agent’s own session file (never the grid). updates are the entries from from_seq in the epoch the client last saw; reset: true means the client holds a different conversation (/clear, new session, file truncated) or fell behind the bounded log, and must drop what it has and apply updates from scratch. A Grok terminal is bound only through its pid’s ~/.grok/active_sessions.json entry (never the newest session). A terminal with no bound Claude or Grok agent answers 500 {"error":"not_bound: <reason>"}. A read keeps the tail alive for 20 s; the server wakes clients with the chat-view-changed event while one reads.
The /agents/map, /agents/map/data and /agents/map/prompt routes were
removed on 2026-09-23. The Progress Flow view (/progress/flow, see Project
Progress above) replaced them.
terminal/styled-rows fills the CanvasTerminal client-side row cache and answers
binary, not JSON: a 64-row chunk is ~141 KB of packed cells, which as a JSON
number array becomes ~350 KB of decimal text for the client to parse back into the
bytes it started as. The desktop terminal_styled_rows command returns the same
payload raw (tauri::ipc::Response), and rpcImpl decides between
arrayBuffer() and json() on the content-type alone. An empty body means “no
such session or range” — a valid empty chunk, not an error.
shell-family classifies the session’s shell so the client picks the right control
sequences (Ctrl-U is line-kill under POSIX readline, a literal character on
cmd.exe/PowerShell). It answers the bare value, not a {field} wrapper,
because get_session_shell_family returns Option<ShellFamily> bare over IPC and
src/utils/sendCommand.ts reads both transports with the same code. An unknown
session is null, which is the same “fall back to the host default” answer.
Read-only PTY/terminal state mirroring the desktop Tauri commands (story 062). The
{field}-wrapped responses are unwrapped by the frontend transport to match the
command’s bare return (e.g. Option<String> → null). The desktop-only commands
themselves are absent from the remote binary, so these handlers read AppState
directly.
terminal/selection-text reads grid-relative scrollback coordinates (row zero
is the oldest retained row), rejoins
soft-wrapped rows, trims terminal padding, and removes only coherent multi-line
Claude NBSP NBSP ▎ visual gutter runs. Desktop IPC returns the same string.
The optional historyBase is the evicted-row count from the frame used to
select the text. When supplied, the backend rebases both row coordinates against
the current history while holding the grid lock; an evicted selection is
rejected with HTTP 409 and {"error":"selection rows are no longer retained"}
instead of reading replacement rows. Omitting it retains the original
current-grid coordinate semantics.
Pause/Resume
POST /sessions/:id/pause
POST /sessions/:id/resume
Agent Hook Frames
POST /sessions/:tuic_session/hook
<OSC 7770 frames>
The side channel of the generated agent hooks (#2749-bee7). Served only on
the local IPC endpoint (the $TUIC_SOCKET Unix socket, or the
\\.\pipe\tuicommander-mcp named pipe on Windows), never on a TCP listener.
:tuic_session is the hook’s $TUIC_SESSION. The body must be only complete
ESC ] 7770 ; <verb>=<printable ASCII> ST|BEL frames with the verbs state,
claude-hook, grok-hook, codex-session or codex-tool. TUIC feeds them to
the session’s PTY reader as if it had read them from the tty, but they never
reach the output ring, the WebSocket stream or the terminal grid. The answer
comes after the frames are processed.
| Status | Meaning |
|---|---|
| 204 | Processed |
| 400 | The body is not only hook frames, or only one ordering header is present or it does not parse |
| 404 | No live PTY reader for that TUIC_SESSION |
| 409 | Stale or repeated stamped post; nothing was processed |
tuic agent-state (the native Windows hooks, #2632-97ef) adds two ordering
headers: x-tuic-hook-stamp, the system-wide monotonic clock
(CLOCK_MONOTONIC, or QueryPerformanceCounter on Windows) read when the hook
process started, and x-tuic-hook-pid. TUIC refuses a stamped post with 409
when it started before the current PTY generation of that TUIC_SESSION, at or
before the last applied stamped state=idle, or when the same (pid, stamp)
was already applied. A late hook therefore cannot revive a settled turn or
reach a respawned agent. The wall clock and arrival order are never used.
Unstamped posts keep arrival order.
Claude Status Line Relay
POST /sessions/:tuic_session/claude-status-line
x-claude-config-dir: <CLAUDE_CONFIG_DIR of the agent, may be empty>
x-home: <HOME of the agent, may be empty>
<Claude Code status line stdin JSON>
The relay script that TUIC’s Claude launch settings put in place of the user’s
statusLine posts here (story 2992-0150). Like the hook frames route, it is
served only on the local IPC endpoint, never on a TCP listener. The script
sends its $TUIC_SESSION as :tuic_session, but the handler does not read the
path parameter: it updates no session. It updates the provider quota entry of
the Claude credential instead.
The handler resolves the credential as the claude-code subscription key from
the two headers: x-claude-config-dir when it is an absolute path, otherwise
<x-home>/.claude when x-home is absolute. When neither resolves, it stores
nothing and answers with an empty body.
The body is the stdin JSON that Claude Code gives to a status line command. The
handler reads rate_limits.five_hour and rate_limits.seven_day
(used_percentage, and resets_at in Unix seconds) as passive quota windows,
timestamped on arrival. It stores them only when they differ from the last
relayed windows for that key and do not show a lower usage for the same window
and reset time. When it stores them, it brings that key up to date in the
provider quota registry. A body that is not JSON
or has no rate_limits stores nothing.
For any UTF-8 body the response is 200 with a plain-text body (axum’s
String extractor refuses a body that is not UTF-8 with 400): the user’s own status
line command, or an empty body when no source defines one. The handler takes
statusLine.command from the first non-empty source in this order:
<project>/.claude/settings.local.json, <project>/.claude/settings.json,
<config dir>/settings.json. <project> is the first absolute path among
workspace.project_dir, workspace.current_dir and cwd in the stdin JSON.
The relay script runs the returned command under /bin/sh with the same stdin,
so the user’s status line does not change.
Rename Session
PUT /sessions/:id/name
Content-Type: application/json
{ "name": "my-session", "isCustom": true }
Sets a display name and its origin. isCustom: true protects an explicit user
rename from subsequent OSC/intent titles; spawn-assigned and dynamic titles use
false. Omitting the field preserves the legacy custom-rename behavior.
Close Session
DELETE /sessions/:id?cleanup_worktree=false
Design Mode Endpoints
The inspector opens a dedicated Chrome window on the machine running
TUICommander. It binds to an agent terminal, even when the request comes from
a browser/PWA client. Optional url opens an absolute HTTP(S) address directly,
including localhost. Without it, start uses dev-server discovery and profile onboarding.
Optional browser selects chrome or edge. Invalid URLs fail before browser side effects.
Start or rebind inspection
POST /design-mode/start
Content-Type: application/json
{ "sessionId": "<agent session ID>", "url": "http://localhost:5173/page", "browser": "chrome" }
Starting another terminal in the same repository reuses its Chrome window and changes the bound session. A plain shell or unknown session is refused, and so is a second start while the repository’s Chrome window is still launching.
Stop inspection
POST /design-mode/stop
Content-Type: application/json
{ "repoPath": "/path/to/repository" }
Reload or navigate the reviewed tab
POST /design-mode/reload
{ "repoPath": "/path/to/repository" }
POST /design-mode/navigate
{ "repoPath": "/path/to/repository", "url": "http://localhost:5173/page" }
Both need an armed Design Mode and answer 400 {"error": ...} otherwise. url must be
HTTP(S) on localhost, 127.0.0.1 or [::1] without credentials. The extension applies
each request once on its next heartbeat (about 5 s).
Read status
GET /design-mode
The status endpoint returns an array of { "repoPath": string, "sessionId": string, "status": "armed" | "stopped" } objects. Start, stop and status use the same backend state as
their Tauri command counterparts. Status changes also arrive as the
design-mode-changed event on GET /events with the snake_case payload
{ "repo_path": string, "session_id": string, "status": "armed" | "stopped" }.
A grab is
prefilled into the bound agent draft, never submitted by these endpoints.
Streaming Endpoints
WebSocket PTY Stream
WS /sessions/:id/stream
Receives real-time PTY output as text frames. One WebSocket per session.
WebSocket JSON Framing (Mobile/Browser)
WebSocket connections to /sessions/:id/stream receive JSON-framed messages:
{"type": "output", "data": "raw terminal output text"}
{"type": "parsed", "event": {"type": "question", "text": "Allow?"}}
{"type": "watcher-lines", "session_id": "abc", "lines": [{"text": "clean line", "matched_ids": ["<client_id>/w0"]}]}
{"type": "exit"}
{"type": "closed"}
Frame types:
output— Raw PTY output (ANSI-stripped when?format=text)log— VT100-extracted clean lines batch (when?format=log):{"type":"log","lines":[...],"offset":N}parsed— Structured events (questions, rate limits, errors) from the output parserwatcher-lines— A batch of assembled PTY lines for the plugin OutputWatchers registered throughPOST /api/plugins/output-watchers. Sent on the raw stream and on?format=grid;?format=log|textdoes not carry it. Each entry is{text, matched_ids}:textis the cleaned line Rust matched on, so the client can run its ownRegExpon it and obtain the capture groups;matched_idsare the qualified ids (<client_id>/<watcher_id>) of the watchers Rust matched. A client ignores the ids of other clients. While every registered pattern compiles, only the matched lines are sent; while one does not, every line is sentexit— Session process exitedclosed— Session was closed
WebSocket format=log
WS /sessions/:id/stream?format=log
When ?format=log is specified, the connection streams VT100-extracted log lines instead of raw PTY chunks:
- On connect: sends all accumulated lines as a single catch-up frame
- While running: polls every 200ms and sends new lines batched by offset
- PTY input passthrough is still available (write text/binary frames to send to PTY)
Grid cell text and search offsets
Packed styled rows and grid frames may end in a sparse
TCX1 cell-text trailer.
It carries retained zero-width scalars without changing the 11-byte cell core.
Absent trailers remain valid. Binary consumers must retain these extensions to
reconstruct complete cell text, and clear previous extensions in replaced spans.
Text row and selection endpoints return the same stored codepoint sequence.
Buffer-search string ranges use UTF-16 offsets for JavaScript slicing; terminal
search highlight coordinates remain grid-cell based. Matching is exact, without
NFC normalization. Ranges cover whole
matching cells: a regex matching only a combining mark still reports its base
cell’s full text span, since native search points have no subcell index.
WebSocket format=grid
WS /sessions/:id/stream?format=grid
The transport behind CanvasTerminal in browser/PWA mode. Binary frames carry the
serialised terminal grid; JSON text frames carry the side-channel events the canvas
needs, each one the desktop Tauri payload plus a type key:
{"type": "osc133", "marker": "D", "line": 42, "exit_code": 0}
{"type": "cwd", "cwd": "/Users/me/project"}
{"type": "watcher-lines", "session_id": "abc", "lines": [{"text": "clean line", "matched_ids": ["<client_id>/w0"]}]}
osc133— Shell-integration marker (Aprompt,Bcommand start,Coutput start,Dcommand end). Drives command blocks, gutter marks and Cmd+Up/Down navigation.exit_codeisnullfor every marker exceptD, andnullon aDwithout one. The field isexit_code, notexitCode— it is serialised from the same Rust struct as the desktoppty-osc133-{id}event, and the two must not driftcwd— OSC 7 working-directory change. Same{ cwd }object as the desktop eventwatcher-lines— See the frame list above; carried here as well as on the raw stream
Frames the server has no grid consumer for are dropped rather than forwarded, so this
socket does not carry output, parsed or the activity pulse.
Initial replay. Attachment sends a full binary viewport immediately. When a live grid watch has no available frame, the server sends {"type":"grid-replay-empty"} instead. This transport control message confirms a healthy empty replay; it is not a PTY event and has no Tauri listener. It uses the same negotiated text framing as the side-channel events. Clients can finish their initial replay deadline on a binary viewport or this marker, while unrelated text events do not establish grid health.
Dropped-frame recovery. Binary frames are deltas, and the watch channel behind
this socket keeps only the newest value — a client that cannot keep up skips frames
and would apply a delta onto a row map missing rows. Each published frame therefore
carries a Rust-internal sequence number; when the reader sees a gap it re-serialises
the full grid and sends that instead. The sequence never reaches the wire, so the
binary frame format is unchanged.
WebSocket compress=deflate
WS /sessions/:id/stream?format=grid&compress=deflate
What is compressed on a remote connection, and by what:
| Traffic | Compressed by | Where |
|---|---|---|
| HTTP request and response bodies over 860 bytes | CompressionLayer (gzip/br/deflate, from Accept-Encoding) | mcp_http::build_router |
| Stream WebSocket frames, direct remote peer | raw deflate per frame, level 6, this option | mcp_http::ws_compression |
| Stream WebSocket frames, SSH-tunnelled peer | ssh -C on the tunnel channel | tunnels::command, ProfileOptions::compression |
| Stream WebSocket frames, local peer | nothing — there is no link to save | — |
The WebSocket half needs its own mechanism because CompressionLayer is an HTTP
layer and never sees a WebSocket frame, and tungstenite 0.30 — behind both
axum::extract::ws and the tunnel’s client — has no permessage-deflate.
Negotiation. ?compress=deflate on the upgrade, plus tuic.deflate in
Sec-WebSocket-Protocol. It is the only value offered; anything else, including
absent, leaves the socket in the framing described above, byte for byte, so a
client that does not know about this option is unaffected. The server refuses to
deflate for a loopback peer even when it asks — a browser on this machine has
no link, and an SSH-tunnelled client arrives through the local ssh process, whose
channel Compression=yes already deflated. A loopback peer is decided on the
canonical address, so the ::ffff:127.0.0.1 an IPv4 client wears on the
dual-stack [::] listener counts as local. Such a socket still gets the tagged
framing it asked for, with every tag saying identity.
The acceptance is on the handshake, not inferred. A server that is going to
tag its frames selects the tuic.deflate subprotocol, which RFC 6455 lets it do
only for a subprotocol the client offered. A client reads ws.protocol in
onopen — before any frame can arrive — and uses the tagged framing only when it
reads that value back. Against a server that predates the option, the parameter
and the offer are both ignored, no subprotocol comes back, and the client reads
the original framing. Inferring acceptance from the request alone is what this
replaces: an untagged grid frame beginning 0x01 fails to inflate, one beginning
0x00 reaches the renderer a byte short, and a JSON frame arrives as a string
the tag decoder throws on.
Framing. On a negotiated socket every frame is a binary WebSocket message whose first byte names the rest. Text travels as binary because deflate output is not UTF-8, and a frame whose WebSocket type changed with its size would leave the reader guessing:
| Tag | Payload |
|---|---|
0x00 | binary (a grid frame), as it is |
0x01 | binary, raw deflate |
0x02 | UTF-8 (one of the JSON frames above), as it is |
0x03 | UTF-8, raw deflate |
Raw deflate, no zlib wrapper — DecompressionStream("deflate-raw") in a browser.
A frame under 860 bytes, or one deflate does not shrink, is sent as it is with an
identity tag, so compression can never make a frame larger than the one byte that
describes it. An unrecognised tag must close the socket rather than be rendered.
Measured, on 957 grid frames replayed from a committed capture of a real Codex
session (mcp_http::ws_compression::measurement): 2,199,978 raw bytes become
127,243 — 5.8%. One full-screen repaint is 111,158 bytes raw and 3,004 compressed,
for 0.234 ms of added latency, against a 16 ms grid tick. Permessage-deflate with
context takeover (what adopting yawc would buy) reaches 53,540 bytes, a further
3.3% of the raw stream; that was judged not to pay for replacing the WebSocket
implementation on both the server and the tunnel client, nor for a stream in which
one dropped frame corrupts every frame after it.
Server-Sent Events (SSE)
GET /events?types=repo-changed,pty-parsed&stream_id=<uuid>
Browser clients share one reference-counted stream per backend URL per page across listen() and subscribeEvents(). Consumer-specific filtering and cleanup do not create extra connections. Reconnect and late filter installation finish before consumer snapshot resync. Two mobile tabs use two SSE connections, leaving ordinary HTTP/1.1 capacity; an unlimited number of tabs is not guaranteed.
Broadcasts server-side events to all browser/mobile clients. Supports optional ?types= query parameter for comma-separated event name filtering. Omitting types asks for every event; sending it empty is an empty allowlist and delivers none. Uses monotonic event IDs and 15-second keep-alive pings.
stream_id is a client-chosen id for the connection. With one, types is only the
initial filter and the client can widen it later on the same connection:
POST /events/types
Content-Type: application/json
{ "stream_id": "<uuid>", "types": ["repo-changed", "dir-changed"] }
types is the full set the client wants from now on, not a delta. 204 applies it to
the live stream; 404 means the server is not tracking that stream (it ended, or more
than 64 streams are already tracked), and the client must fall back to reconnecting with
a wider ?types=.
A panel that mounts late needs an event type the stream was not opened with, and
reconnecting to get it loses every event published between the close and the new
subscription — the server subscribes to the event bus at connect time and replays
nothing. That is what this route exists to avoid. A client that lets EventSource
auto-reconnect must re-post its set on every onopen: the reconnect replays the URL, so
the server is back to the filter the connection was opened with.
| Event | Payload | Description |
|---|---|---|
session-created | {session_id, cwd, agent_type, display_name, parent_session} | New session started; display_name is the optional stable assigned name; parent_session is the $TUIC_SESSION of the agent that spawned it (null otherwise) |
pty-description-changed | {session_id, description} | Orchestrator updates the short task description shown above a PTY |
chat-view-changed | {session_id, seq} | The chat view of a Claude, Grok, exactly bound Codex or exact PID-bound ego terminal has entries past seq; read them with GET /sessions/:id/chat-view |
session-renamed | {session_id, name, is_custom} | An MCP session action=rename changed a tab’s display name |
session-suspended | {record} | Rust persisted a suspended tab before ending its PTY; record fields use snake_case |
term-alias-assigned | {session_id, alias} | A session received its terminal alias (e.g. tu-3); published once, after session-created |
session-closed | {session_id} | Session ended |
design-mode-changed | {repo_path, session_id, status} | Design Mode for the repository changed to armed or stopped; the bound agent tab follows this status |
repo-changed | {repo_path, kind} | Repository changed. kind is "git-state" (.git/ was written — a commit, ref or index change) or "working-tree" (files changed and .git did not). A git-state emit cancels the pending working-tree one, so "git-state" does not mean “only .git changed” — a client that needs working-tree news must react to both kinds. |
head-changed | {repo_path, branch} | Git HEAD changed (branch switch) |
pty-parsed | {session_id, parsed} | Structured output event from PTY parser |
pty-exit | {session_id} | PTY process exited |
pty-activity | {session_id} | Bytes are flowing from the PTY. Payload-free pulse, at most one per second — a dropped pulse loses nothing |
pty-osc133 | {session_id, marker, line, exit_code} | Shell-integration marker (OSC 133). exit_code is null except on a D marker that reported one |
pty-cwd | {session_id, cwd} | Working directory changed (OSC 7) |
plugin-watcher-lines | {session_id, lines} | A batch of assembled PTY lines for the plugin OutputWatchers; each line is {text, matched_ids}, where text is the cleaned text the match was made on |
plugin-changed | {plugin_ids} | Plugin(s) installed/removed/updated |
upstream-status-changed | {name, status} | MCP upstream server status change |
mcp-toast | {title, message, level, sound, urgency, origin_repo_path?, origin_session_id?} | Toast notification from MCP layer, including the caller repository/cwd and the caller’s TUIC session when known. Clients use the session id to focus the terminal that raised the toast. urgency is normal (bell only) or urgent (bell plus a transient card); clients treat an absent field as normal |
session-state-changed | {session_id, state} — state is the same object GET /sessions returns per session (shell_state, agent_state, awaiting_input, question_confident, background_work, queued_commands, …), snake_case, with the fields serde skips at their zero value omitted | A session’s derived lifecycle state moved. Published by the session-state accumulator (state.rs publish_session_state_change) once per real transition, deduped by SessionState’s PartialEq — a repaint that changes only last_activity_ms publishes nothing. Dual-emitted on the Tauri window under the same name and with the same payload, so useAgentPolling.ts consumes both transports with one handler instead of polling list_active_sessions. Absence of a field means its zero value, not “unknown” |
dictation-download-progress | {downloaded, total, percent} | A Whisper model is downloading. Dual-emitted on the Tauri window with the identical body |
speech-download-progress | {asset, downloaded, total, percent}, then {asset, done: true} | A speech asset is downloading; the done event ends it, success or failure. asset is the only difference from the line above, and it is what a client joins the bar against |
speech-utterance | {utteranceId, state, error?, turn} — the SpokenReply shape POST /dictation/speech/speak returns | A reply moved between queued, rendering, speaking and one of finished / interrupted / failed. Pushed by the render thread that performed the transition, so a client no longer polls speech/status |
| (any of the above, mirrored) | the daemon’s own payload plus __tuic_origin: {connection} | An event this machine repeated from a connected remote daemon (remote_mirror.rs). It arrives under the daemon’s own event name, so a client needs no new subscription; __tuic_origin says which connection it came from. A frame that already carries the key is dropped rather than repeated, so a mirrored event never crosses a second hop |
lagged | {missed} | Client fell behind; N events were dropped. Dropped events are never resent, so a client that derives state from the stream must re-read it — subscribeEvents’ onResync("lagged") callback exists for that. It fires with "connect" once the initial subscription is live, closing any gap after the initial snapshot read, and with "reconnect" on any EventSource re-open after the first, because a drop loses the same way silently. Both are SSE-only: Tauri listen() is in-process and cannot drop |
MCP Streamable HTTP
POST /mcp
Content-Type: application/json
{ JSON-RPC message }
Single endpoint for all MCP JSON-RPC requests (legacy initialize, current
server/discover, tools/list, tools/call). Returns JSON-RPC responses
directly in the HTTP response body. Session ID returned via Mcp-Session-Id
header on legacy initialize. For 2026-07-28 requests, server/discover and
tools/list return resultType: "complete", ttlMs: 0, and
cacheScope: "private"; completed tools/call results, including tool-level
errors, return resultType: "complete" without cache fields. Legacy result
shapes are unchanged.
The native session tool includes action=submit for a managed-agent command
and bounded terminal-movement receipt in that same JSON-RPC response. It is
limited to a loopback or credential-verified caller, never queues, and rejects a busy/dialog/partial composer before
writing. action=input and POST /sessions/:id/write remain raw write-only
surfaces; neither returns submission acknowledgement. See
MCP & HTTP Server.
GET /mcp → 405 Method Not Allowed
DELETE /mcp → Ends MCP session (pass Mcp-Session-Id header)
Git Endpoints
Repository Info
GET /repo/info?path=/path/to/repo
Returns RepoInfo (name, branch, status, initials).
Git Diff
GET /repo/diff?path=/path/to/repo[&scope=staged|head|<commit>|base:<ref>|base-uncommitted:<ref>|range:<from>..<to>]
Returns { "diff": "..." } with the unified diff. Optional scope: absent = unstaged changes, staged = index, head = index plus working tree against HEAD, a commit hash = that commit against its first parent, base:<ref> = <ref>...HEAD (the committed work of the branch), base-uncommitted:<ref> = the working tree against the merge base of <ref> and HEAD, range:<from>..<to> = the first parent of commit from against commit to. A base ref that starts with - or does not resolve to a commit is rejected. Same scope as the get_git_diff IPC command. The diff stats and changed files routes take the same scope.
Diff Stats
GET /repo/diff-stats?path=/path/to/repo[&scope=...]
Returns { "additions": N, "deletions": N }.
Changed Files
GET /repo/files?path=/path/to/repo[&scope=...]
Returns array of ChangedFile (path, status, additions, deletions).
Single File Diff
GET /repo/file-diff?path=/path/to/repo&file=src/main.rs
Returns diff for a single file.
Read File
GET /repo/file?path=/path/to/repo&file=src/main.rs
Returns file contents as text.
Branches
GET /repo/branches?path=/path/to/repo
Returns sorted branch list.
Remotes
GET /repo/remotes?path=/path/to/repo
Returns [{ "name": "origin", "url": "https://github.com/acme/app.git" }]. Userinfo (an embedded token) is removed from every URL. IPC twin: get_git_remotes.
Work-item links
GET /workitem-links
PUT /workitem-links {"repoPath": "/repo", "branch": "feat/x", "link": WorkItemLink}
DELETE /workitem-links {"repoPath": "/repo", "branch": "feat/x"}
GET returns { repoPath: { branch: WorkItemLink } }. WorkItemLink is { reference: { providerId, accountId, id }, key, title, url, state: { id, name, tone } | null }. PUT answers 400 for a relative repoPath, an empty key or a non-http(s) url. DELETE returns true when a link existed. Stored in workitem_links.json in the config dir; TUIC drops the link when it removes the worktree. IPC twins: list_workitem_links, link_workitem, unlink_workitem.
Repo Summary
GET /repo/summary?path=/path/to/repo
Aggregate snapshot: worktree paths, merged branches, and per-path diff stats in one round-trip. Replaces 3+ separate IPC calls.
Repo Structure (Progressive Phase 1)
GET /repo/structure?path=/path/to/repo
Returns { "worktree_paths": { "branch": "/path", ... }, "merged_branches": ["branch", ...] }. Fast path — no diff stats computation. merged_branches lists the merged state of the checked-out workspace branches only; GET /repo/branches/merged classifies every local branch.
Repo Diff Stats (Progressive Phase 2)
GET /repo/diff-stats/batch?path=/path/to/repo
Returns { "diff_stats": { "/path": { "additions": N, "deletions": N }, ... }, "last_commit_ts": { "branch": N, ... }, "workspace_statuses": { "workspace-id": { "dirty_files": 24, "commit_status": "unmerged", "removal_safety": "requires_force" } } }. Slow path — computes per-worktree diff stats, timestamps, and lifecycle verdicts. Lifecycle entries are keyed by workspace id, never branch name.
Background Git Actions
POST /repo/run-git accepts {path, args} from authenticated callers. args[0] must be an allowlisted subcommand; normal Git options after it are accepted (for example log --oneline or push --force-with-lease). An unsupported subcommand, a global option before the subcommand, or a generic branch deletion returns HTTP 400 before execution; use the dedicated branch deletion routes instead. The policy is shared with IPC; see Git backend.
Local Branches
GET /repo/local-branches?path=/path/to/repo
Returns local branch list.
Checkout Remote Branch
POST /repo/checkout-remote
Content-Type: application/json
{ "repoPath": "/path/to/repo", "branchName": "feat-remote" }
Creates a local tracking branch from origin/<branchName>.
Rename Branch
POST /repo/branch/rename
Content-Type: application/json
{ "path": "/path/to/repo", "old_name": "old", "new_name": "new" }
Check Main Branch
GET /repo/is-main-branch?branch=main
Returns true if the branch is main/master/develop.
Initials
GET /repo/initials?name=my-repo
Returns 2-char repo initials.
Markdown Files
GET /repo/markdown-files?path=/path/to/repo
Returns list of .md files in a directory.
Recent Commits
GET /repo/recent-commits?path=/path/to/repo
Returns recent git commits.
GitHub Status
GET /repo/github?path=/path/to/repo
Returns has_remote, current_branch, ahead and behind. This route and
/repo/prs, /repo/prs/batch and /repo/issues are shared by desktop and
headless servers. PR and CI snapshots are not part of this status object.
PR Statuses (Batch)
GET /repo/prs?path=/path/to/repo
Returns BranchPrStatus[] for all branches with open PRs.
PR Statuses (Multi-Repo Batch)
POST /repo/prs/batch
Content-Type: application/json
{ "paths": ["/repo1", "/repo2"], "include_merged": false }
Returns aggregated PR statuses across multiple repositories.
Issues
GET /repo/issues?path=/path/to/repo
Returns GitHubIssue[] for the repo, filtered by the user’s configured issue filter.
Close Issue
POST /repo/issues/close
Content-Type: application/json
{ "repo_path": "/path/to/repo", "issue_number": 42 }
Closes the specified issue via GitHub GraphQL API.
Reopen Issue
POST /repo/issues/reopen
Content-Type: application/json
{ "repo_path": "/path/to/repo", "issue_number": 42 }
Reopens a closed issue via GitHub GraphQL API.
GitHub Poller Controls (Desktop and Headless)
These existing handlers share one route registration on both servers. TCP uses normal server authentication; the local Unix socket remains trusted local IPC.
| Method | Path | JSON body |
|---|---|---|
| POST | /repo/github-poller/start | { "paths": ["/repo"], "issueFilter": "all", "prHideDrafts": false } |
| POST | /repo/github-poller/stop | none |
| POST | /repo/github-poller/visibility | { "visible": true } |
| POST | /repo/github-poller/poll-repo | { "path": "/repo" } |
| POST | /repo/github-poller/update-paths | { "paths": ["/repo"] } |
| POST | /repo/github-poller/set-issue-filter | { "filter": "all" } |
| GET / POST | /repo/github-poller/api-debug | POST: { "enabled": false } |
Start cold-starts the poller without a WebView. An automation executor also starts polling its registered issue-intake allowlist without a client. Client path/filter changes do not replace this subscription; stop releases only client paths while intake is enabled. Intake paths use issue filter all, while other paths retain the client filter. Control delivery returns
{"ok":true} or an error when no poller accepts the command. API-debug reads
return {"enabled":false} (or true); writes also return ok. Repository status
is read through /repo/github?path=...; there is no separate poller-status route.
PR/issue updates also reach /events SSE. Empty paths or a repository with no
GitHub remote permit a credential-free lifecycle smoke; that does not verify
GitHub authentication, network calls or populated snapshots.
GitHub Auth & Diagnostics
Browser/PWA parity for the GitHub settings panel. Registered on the loopback
router only (the headless tuic-remote daemon exposes monitoring, not account/auth routes).
GET /github/viewer-login -> string (login)
GET /repo/ci-failure-logs?repoPath=&branch=&checkUrl=&headSha= -> string (logs; checkUrl and headSha optional)
GET /circleci/token -> CircleCiTokenStatus (no token value)
POST /circleci/token { token } -> null (store read-only token)
DELETE /circleci/token -> null
POST /github/pr-hide-drafts { hide } -> null
POST /github/auth/start -> DeviceCodeResponse
POST /github/auth/poll { deviceCode } -> PollResult (default login)
GET /github/accounts -> GitHubAccount[]
POST /github/accounts/poll { deviceCode } -> PollResult (named account; preserves default login)
POST /github/auth/logout -> null
POST /github/auth/disconnect -> null
GET /github/auth/status -> AuthStatus
GET /github/diagnostics -> GitHubDiagnostics
Enterprise account creation uses the core account manager and account_secret_form. The legacy POST /github/accounts PAT endpoint is removed.
Auth commands share the desktop *_impl (device-code flow + OS-keyring token via
crate::credentials). get_all_issues is intentionally unmapped — it has no frontend
invoke() caller (the /repo/issues route already serves browser issue lists).
Merged Branches
GET /repo/branches/merged?path=/path/to/repo
Returns list of branch names merged into the default branch.
Orphan Worktrees
GET /repo/orphan-worktrees?repoPath=/path/to/repo
Returns list of worktree directory paths that are in detached HEAD state (their branch was deleted).
GET /repo/orphan-cleanup-assessment?repoPath=/path/to/repo returns each orphan’s
{ path, safe, reason?, live_sessions? }. A checkout is safe for automatic removal only when it
has no tracked or untracked changes, its HEAD is reachable from a local or
remote branch, and no live session has its cwd inside it. live_sessions
([{ session_id, name }], omitted when empty) names those sessions and reason
repeats them. Ignored files do not make it dirty. Assessment failures are
unsafe.
While the Ask dialog is open, POST /repo/orphan-cleanup/begin with
{ "repoPath": "...", "paths": ["..."] } registers the pending request.
GET /repo/orphan-cleanup/pending?repoPath=... returns its answer (true for
remove, false for keep, or null while unanswered).
POST /repo/orphan-cleanup/answer with { "repoPath": "...", "decision": "remove" }
answers it; remove rechecks every path server-side and refuses unsafe (including live-session) or stale
worktrees. POST /repo/orphan-cleanup/clear with { "repoPath": "..." } clears
the request when the dialog closes. MCP repo action=orphan_cleanup_answer
uses the same answer operation with path and decision=remove|keep.
Remove Orphan Worktree
POST /repo/remove-orphan
Content-Type: application/json
{ "repoPath": "/path/to/repo", "worktreePath": "/path/to/worktree", "safeOnly": true }
Removes an orphan worktree by filesystem path. The worktree path is validated against the repo’s actual worktree list. safeOnly is optional; when true, the server rechecks clean status, branch reachability and live sessions immediately before removal and refuses a checkout a session still works in. With safeOnly false the caller has confirmed the removal from the assessment: confirmedSessions (default []) lists the live_sessions ids it showed, and the server refuses when a live session outside that list works in the checkout. HTTP cannot force removal of a dirty checkout. The desktop confirmation path compares the reviewed fingerprint before removal; it is not atomic with Git removal. The fingerprint includes collapsed ignored path names, but not file content or new entries inside an already-ignored directory.
Resolve Worktree Diagnostic
POST /repo/worktree-diagnostic/resolve
Content-Type: application/json
{ "repoPath": "/path/to/repo", "worktreePath": "/path/to/worktree", "action": "repair" }
action is repair (run git worktree repair <path> from the main checkout; the checkout folder must exist) or prune (drop the registration of a deleted folder; no files are deleted). The path must be a current missing worktree diagnostic of the repo, otherwise 400. Same operation as the resolve_worktree_diagnostic_cmd command.
Merge PR via GitHub
POST /repo/merge-pr
Content-Type: application/json
{ "repoPath": "/path/to/repo", "prNumber": 42, "mergeMethod": "squash", "expectedHeadSha": "<head sha the caller reviewed>" }
Merges a PR via the GitHub API. mergeMethod must be "merge", "squash", or "rebase". expectedHeadSha is required and is sent to GitHub as sha: if the PR head moved since the caller saw it, GitHub answers 409 and the route returns an error starting with PR head changed; the caller must refresh and review, never retry with the new head. Returns {"sha": "..."} on success.
Approve PR
POST /repo/approve-pr
Content-Type: application/json
{ "repoPath": "/path/to/repo", "prNumber": 42 }
Submits an approving review on a PR via the GitHub API.
Update PR Branch
POST /repo/update-pr-branch
Content-Type: application/json
{ "repoPath": "/path/to/repo", "prNumber": 42, "expectedHeadSha": "<head sha the caller saw>" }
Merges the base branch into the PR branch (GitHub update-branch, 202 accepted; the merge commit lands asynchronously). expectedHeadSha is required: if the PR head moved, the route returns an error starting with PR head changed. Returns {"ok": true}.
Close PR
POST /repo/close-pr
Content-Type: application/json
{ "repoPath": "/path/to/repo", "prNumber": 42 }
Closes the PR without merging. Returns {"ok": true}.
CI Checks
GET /repo/ci?path=/path/to/repo
Returns detailed CI check list.
Unresolved Review Threads
GET /repo/pr-review-threads?path=/path/to/repo&pr_number=42
Returns {"bot": N, "human": M, "ego": E}: unresolved review threads of one PR, split by the first comment. A first comment that holds <!-- tuic:ego-review --> (appended to every finding posted from the PR review) counts as ego, not human. One GraphQL point per page of 100 threads.
PR Diff
GET /repo/pr-diff?path=/path/to/repo&pr=42
Returns {"diff": "...", "headSha": "..."}. headSha is the commit the diff was read at; the call fails with 502 if the PR head moves while the diff loads.
Conflict Assist
GET /repo/merged-prs?path=&sinceTag= -> MergedPr[]
POST /repo/conflict-assist { repoPath, prNumber } -> ConflictAssistResult
/repo/conflict-assist creates a worktree on the PR head and rebases it onto
the base. status is clean only when the base was refreshed from origin,
clean_unverified when a conflict-free result used an existing tracking ref or
local fallback, and conflicts when manual resolution is needed. The response
includes base_source, an optional base_warning, the conflicted-file list,
and an agent prompt; it never pushes or merges. None of it calls a model.
Review, changelog and improvement scan (ego)
POST /repo/pr-review { repoPath, prNumber } -> PrReviewResult
GET /repo/changelog?path=&sinceTag= -> ChangelogResult
POST /repo/improvement-scan { repoPath, focus } -> ImprovementScanResult
POST /repo/create-issue-from-proposal { repoPath, proposal } -> CreatedIssue
Each of the first three is one unattended ego turn (#795-320b) over the
acp::oneshot seam: the whole input goes inline, ego is offered no host tools,
and every permission request is refused. TUICommander stores no API key and makes
no provider HTTP call for any of them; which model runs is ego’s configuration.
They are not desktop-gated — ego is reached over ACP, so tuic-remote serves
them too. /repo/merged-prs is unchanged and still a plain GraphQL query.
PrReviewResult carries { repo_path, pr_number, head_sha, summary, files[] },
each file { path, summary, findings[] } and each finding
{ path, line, hunk, severity, confidence, message }. The confidence gate runs in
Rust before the response is built (default 0.7, overridable with
TUIC_REVIEW_CONFIDENCE_THRESHOLD), so a finding that arrives has already passed
it. head_sha hashes the reviewed diff — it is not a git sha.
ChangelogResult is { markdown, json }; json is null when ego answered in
prose only, which is a valid answer rather than an error.
An ego that cannot be reached is a 4xx/5xx with ego’s own sentence in the
error body — never a 200 with an empty result. POST /repo/pr-review,
POST /repo/improvement-scan and POST /repo/conflict-assist also emit
review-progress, proposals-ready and conflict-assist-status on /events
while they run — on every build. The routes are mounted in build_router,
which the desktop app serves, and a browser reading
/events is the only client a non-desktop build has: the desktop window emit is
gated on feature = "desktop", the event_bus send never is (#808-84e1). They
are not in shared_routes, so the tuic-remote daemon does not serve them
at all (#810-4986).
POST /ai/review/pr and POST /ai/improvements/scan are gone with the engine
#784-0aec deleted; the /ai/ prefix belonged to it, so the replacements sit
under /repo/.
install_agent_mcp/remove_agent_mcp (config-file writes, also no caller).
GET/PUT /config/agents read and write agents.json, including each agent’s optional prevent_alt_screen override (false disables TUIC’s screen control; absent means enabled). The route is in shared_routes(), so the tuic-remote daemon serves it too: a remote repository’s agents run with that machine’s agents.json, and the frontend loads it per connection. The /config/agents/{agent}/… sub-routes below stay desktop-only.
GET /config/agents/{agent}/native-status-signals returns { "enabled": boolean }. PUT accepts the same boolean field for Claude or Codex and changes launch behavior for new sessions only. The existing /hook-instrumentation route remains the explicit global installer. Codex installation attempts exact native trust and preserves successful file installation if normal review remains necessary. Hook-state GET returns { "state": "reviewRequired" } when canonical Codex files lack verified current native trust; installed requires CLI readback. Status reads never grant trust.
No provider keyring routes
/config/provider-key*, /config/slot-test and /config/ollama-models were
removed with the provider registry (#784-0aec). TUICommander stores no model API
key and makes no provider HTTP call, so there is nothing for a browser or remote
client to proxy. Story 786-4a6d brings a provider list back (now on the Settings → AI Chat
page), configured against ego rather than against a registry of TUICommander’s own.
The OAuth upstream flow (start_mcp_upstream_oauth / cancel_mcp_upstream_oauth) is
not mapped: start binds a loopback callback server and opens the OS browser, so
the redirect can’t return to a remote/PWA client. Desktop drives it over IPC; browser
clients get a clean host-only error until the redirect UX is redesigned.
Hash Password
POST /config/hash-password
Content-Type: application/json
{ "password": "..." }
Returns bcrypt hash string.
Notification Config
Interactive config PUT routes below (except /config/repositories, which has
its own keyed mutation protocol) accept { "base": <last GET response>, "config": <edited document> }. The server computes the changes from base to
config and applies them to the latest file under its lock. Objects merge by
key, arrays replace whole, and JSON null deletes a key. A field unchanged by
this caller is never written. Clients should serialize their own overlapping
saves so each later request has the preceding desired document as its base.
PUT /config uses this same envelope. Its GET response omits secret values;
unchanged omitted secrets remain on disk. PUT /config refuses with 403 {"error":"confirmation_required"} and writes nothing when the change adds authority that the Settings facade gates on owner confirmation (a new ego_executable, a widened services.server|auth|tls|relay setting, a new AI chat launcher executable, an added plugin HTTP destination, a new or changed custom launcher executable/args or a launcher turned on); make those edits through POST /settings/action. Clearing or narrowing such a setting stays writable. POST /tunnels/profiles refuses the same way when it changes a profile’s port, turns auto_connect on or adds a forward (a new profile compares against an empty default one), and PUT /mcp/upstreams refuses an added, enabled or changed stdio upstream; HTTP upstreams, removals and ordinary tunnel fields stay writable.
GET /config/notifications
PUT /config/notifications
Load/save NotificationConfig.
UI Preferences
GET /config/ui-prefs
PUT /config/ui-prefs
Load/save UIPrefsConfig.
Config Defaults
GET /config/defaults
Both methods are available on the desktop server and the authenticated remote daemon.
POST /config/defaults returns the same shape with launch instruction previews
for a draft, including module switches and append-only additions in agents. The body is { "agents": <AgentsConfig>, "intent_tab_title": true, "suggest_followups": true }. Both marker flags are optional; omitted flags use
the server’s current app config. No values are saved. The launch_instructions
section contains a resolved default_text, required_markers, and an
effective_text map for supported agents. Agent previews follow the same
override priority, marker flags, and {VER} replacement as launches.
Read-only. Returns ConfigDefaults — see docs/backend/config.md → “Config
Defaults” — for Settings “expert mode”: { app, notifications, agent_settings, repo_defaults, agents, github_accounts, dictation?, launch_instructions }. dictation is present only on desktop
builds. None fields are omitted (skip_serializing_if); a missing key inside
a present object means null.
Repository Settings
GET /config/repo-settings
PUT /config/repo-settings
Load/save per-repository settings.
Repository Defaults
GET /config/repo-defaults
PUT /config/repo-defaults
Load/save default settings applied to new repositories.
Check Custom Settings
GET /config/repo-settings/has-custom?path=/path/to/repo
Returns true if the repo has non-default settings.
Repositories
GET /config/repositories
PUT /config/repositories
GET loads the repositories document. Every PUT must send the same versioned
mutationVersion: 1 delta as desktop save_repositories: keyed
repos/groups entries carry {id,before,after}, while repoOrder,
activeRepoPath, and groupOrder optionally carry {before,after}. The
backend applies the delta to the latest document under the cross-process lock.
Different repository/group IDs and independent order membership changes
compose; incompatible changes to the same record return 409 Conflict and a
malformed or unversioned delta returns 400 Bad Request.
A PUT that actually moves the document broadcasts a payload-free
repositories-changed SSE event (subscribe with GET /events?types=repositories-changed)
so the other clients re-read the document instead of saving over it from a stale
baseline. A delta that was already applied changes nothing on disk and is not
announced. See docs/backend/config.md for what a receiving client is allowed to
adopt.
Stale-temp Repository Repair (#763-d219)
GET /config/repositories/stale-temp
POST /config/repositories/stale-temp
GET returns StaleTempCandidate[] ({path, displayName}) — a read-only
preview, re-classified against the live document on every call, of rows that
match ALL of: local path absent, path under a recognized OS/project temp root,
isGitRepo: false, exactly one shell-only workspace with no terminals/saved
terminals/parent/commit state, and no user metadata (see docs/backend/config.md
for the exact classifier). Never mutates.
POST body {"paths": ["/tmp/…", …]} — the user-explicit repair. Re-validates
every named path against the classifier on the document as it stands on disk
right now; if even one no longer matches, the whole request is rejected with
400 Bad Request and nothing is written (no implicit or partial deletion). On
success it writes an exact pre-repair backup (repositories.repair-backup-<UTC timestamp>.json) in the config directory, removes the validated rows from
repos/repoOrder/every group’s repoOrder (and clears activeRepoPath if it
pointed at a removed row) in one write, returns StaleTempRepairSummary
({removed, backupPath}), and broadcasts repositories-changed like PUT /config/repositories. Requires local-or-authenticated like every other
mutating config route.
Prompt Library
GET /config/prompt-library
PUT /config/prompt-library
Load/save prompt entries.
Notes
GET /config/notes
PUT /config/notes
Load/save notes (opaque JSON, shape defined by frontend).
Remote Connections
GET /config/remote-connections
PUT /config/remote-connections
DELETE /config/remote-connections/{id}
PUT /config/remote-connections/{id}/password
PUT /config/remote-connections/{id}/relay-pairing
GET /config/remote-connections/{id}/password
POST /config/remote-connections/{id}/token
POST /config/remote-connections/{id}/install
DELETE /config/remote-connections/{id}/install
GET /config/remote-connections/{id}/update
POST /config/remote-connections/{id}/update
The configured remote machines and their vault password. The password is write
only: it goes to the OS credential vault keyed by the connection’s UUID and is
never returned, never written to connections.json — GET .../password answers
whether one is stored, not what it is. POST .../token trades it for the remote
daemon’s in-memory session token. Successful password set/clear requests publish
a value-free settings-changed event for connections after vault persistence;
a failed vault write publishes nothing. Deployment pairing-token creation and
persisted deployment-mode changes invalidate the same Settings section.
PUT .../relay-pairing takes { "bundle": "tuic-pair-v1:..." }, the text printed
by tuic-remote --relay-pair. The bundle is parsed first; an unparsable one is
rejected, nothing is stored and nothing is published. It is kept in the vault
only (it holds the end-to-end secret) and an empty string forgets it. A
successful change publishes the same value-free connections event. The
connection status of a relay connection carries relay_failure
(relay_unreachable, daemon_offline, pairing_rejected, link_lost).
PUT /config/remote-connections takes { "base": null, "connection": {...} }
for a new machine, or the loaded connection as base when editing. The server
merges only changed fields into that connection’s latest locked record.
The install pair is SSH-only. POST .../install stages the matching release
binary, installs and starts a systemd user unit or launchd agent, and persists
deploy = "installed". DELETE .../install stops and removes the service
files and persists deploy = "on_connect". Pairing tokens stay in the credential
vault; neither response nor the connection document contains them.
GET .../update previews the selected daemon binary: remote_build,
desktop_build (version, target triple, SHA-256), source (release or
local), session_count, and out_of_date. The release asset is preferred;
when it is absent, a locally built sibling tuic-remote is accepted only for
the same target triple. POST .../update takes
{ "confirmedSessions": N, "expectedSha256": "..." }. A changed count or
binary after confirmation is rejected. Direct connections upload over the
authenticated daemon route; SSH connections use the existing SCP deployment.
The call returns after /health reports the new SHA-256, or an error if the
restart cannot be verified. Live remote PTY sessions are lost.
DELETE /config/remote-connections/{id} tears the live connection down before it
rewrites the store: status poll, mirror task, mirrored session rows, SSH tunnel
and session token all go, through the same remote_runtime::teardown the
disconnect route uses. Deleting a connected machine therefore needs no
disconnect first — and must not be given one, because the tunnel is keyed by the
profile the delete is about to remove.
Remote Connection Runtime
GET /config/remote-connections/status
POST /config/remote-connections/{id}/connect
DELETE /config/remote-connections/{id}/connect
Live state, not configuration: GET .../status answers with one object per
connection — { id, status, base_url?, token?, protocol_version?, build?, out_of_date?, live_sessions?, update_notice?, update_in_progress?, error?, retry_after_secs?, step? },
where status is disconnected | connecting | deploying | connected | unauthenticated | error. error is shown only for settled failures.
retry_after_secs is the rounded-up delay of a scheduled retry, present only
while waiting after a failure; it is omitted when a new attempt starts. step is present while deploying. base_url, token
and protocol_version are present only while
connected; update_in_progress is present as true while a manual or unattended update
owns the connection. The route and token fields answer “where do I send a call”, and a
connection that is not connected has no such answer.
POST .../connect brings a connection up and DELETE .../connect takes it
down. Neither returns the new status: every transition is pushed as a
remote-connection-status event on /events SSE (and to the desktop window),
so one client connecting is visible to all of them.
Both directions are idempotent. A second POST .../connect while one is already
in flight is a no-op rather than a second handshake, and DELETE .../connect on
an unknown id creates nothing. A connect that fails stops the SSH tunnel it
started, so a bad password leaves no ssh process behind. A connection in
error keeps its poll: the daemon coming back is a connected push, not a
reconnect the user has to ask for.
These three routes are desktop-only — they are registered on build_router, not
in shared_routes(). A tuic-remote daemon is the far end of a remote
connection; it does not hold connections of its own.
SSH Discovered Hosts
GET /tunnels/ssh-hosts/discovered
Returns { "hosts": [{ "host", "target", "user", "port", "source": "config | known_hosts" }], "hashed_count": n }:
non-wildcard ~/.ssh/config aliases plus plain ~/.ssh/known_hosts names,
deduplicated by resolved target and port (target is the alias’s HostName,
else the name itself). Names that start with -, contain control characters or
have a port outside 1-65535 are dropped; known_hosts is read up to 4 MiB and at
most 2000 of its names are listed. Hashed known_hosts entries cannot be
listed and are only counted. No host is contacted.
SSH Host Status
GET /tunnels/ssh-hosts/status
Probes the ~/.ssh/config aliases (at most 64) and returns
[{ "host": "name", "target": "resolved", "port": 22, "auth": "shell | no_shell | auth_failed | unreachable" }].
known_hosts names are never probed in bulk.
POST /tunnels/ssh-hosts/probe {"target": "10.0.0.5", "port": 2222}
Probes one entry of the discovered list, identified by target and port
(404 when it is not in the list). A known_hosts entry is probed with
StrictHostKeyChecking=yes.
The probe runs only on request, checks at most four hosts concurrently, uses
batch authentication with a five-second connect timeout, and caches results for
60 seconds.
MCP Status
GET /mcp/status
Returns MCP server status (enabled, running, active sessions, connected MCP clients, maximum sessions). tls_active is true only while the current TCP listener serves with a loaded TLS configuration; Tailscale certificate capability does not set it. It becomes false when that serving task stops or is replaced. native_tools contains the unfiltered native MCP registry as {name, summary, description} entries, including disabled tools. summary is the first line of the full registry description. This Settings inventory is independent of upstream tools, collapse mode and progress tracking; MCP client discovery still applies all configured filters.
Suspended Sessions
POST /sessions/suspended accepts the same request as IPC suspended_session_action, from loopback or an authenticated client.
{"action":"list"}returns an object keyed by stabletuic_session. Each record containssession_id,agent_type,cwd,worktree,agent_session_id,launch_command,alias,pane_slot,reason,nameandshell.{"action":"suspend","sessionId":"...","metadata":{...}}persists before ending an idle PTY and returns{ok:true}. Optional camelCase metadata containsname,agentSessionId,agentLaunchCommandandpaneSlot; live backend state controls refusal and identity.{"action":"resume","tuicSession":"..."}verifies and spawns the replacement PTY, removes its durable record after successful creation and returns{ok:true,session_id:"..."}.{"action":"forget","tuicSession":"..."}removes a closed suspended tab.{"action":"sync","sessionId":"...","metadata":{...}}retains live frontend metadata for later headless suspension.{"action":"resolve_resume","agentType":"...","cwd":"...","tuicSession":"...","agentSessionId":"...","launchCommand":"..."}returns{cmd,verified}for existing restart restoration consumers. Verification checks the saved launch profile’s store; an unavailable session returnscmd:null.
Errors return HTTP 400 with {error}. MCP session action=suspend uses the same Rust operation without requiring a WebView or a frontend verdict. session-suspended precedes the close event so connected clients retain the tab.
MCP Upstream Credentials
PUT /mcp/upstreams accepts optional write-only credentials: [{server_id, token, header?}] alongside base and config. Each credential must target a newly added HTTP server, with matching header metadata or Bearer auth. The backend validates the merged configuration under its cross-process lock before creating vault entries. Duplicate names and existing vault entries are rejected without replacement. Partial vault writes and config-save failures roll back new entries; a successful save then hot-reloads the upstream. Secrets never enter the config file.
POST /mcp/upstreams/credential accepts {name, token, url, header?, replace?}. It refuses to overwrite an existing vault entry by default. Use replace: true only for an explicit credential edit. Without header, it saves a Bearer credential. With header: {name, credential_ref}, it saves a secret header value in the upstream-scoped OS credential vault. credential_ref must be a UUID. url is required and must be HTTP or HTTPS. The vault entry binds the secret to that URL origin; requests to a different origin fail before sending. Old unbound credentials require re-saving or authorization. Names and values are validated without echoing values in errors.
DELETE /mcp/upstreams/credential accepts {name, header?} and removes that credential. Both return JSON null on success, matching IPC unit results. POST /mcp/upstreams/reconnect also returns JSON null on success. Config entries carry only headers: [{name, credential_ref}]; the API never returns header values.
MCP Upstream Status
PUT /mcp/upstreams
Content-Type: application/json
{
"base": { "servers": [...] },
"config": { "servers": [...] }
}
base is the configuration previously loaded by the caller and config is its
desired result. The backend derives an ID-keyed three-way delta, then applies it
to the latest mcp-upstreams.json under the cross-process file lock. Removing a
server from config explicitly deletes that ID; removing an optional auth
field explicitly clears it. Fields and servers unchanged from base preserve
concurrent updates, including OAuth/DCR auth written by another process. After
the atomic write, the live registry hot-reloads the exact locked pre/post
configurations. Returns 200 with JSON null, 400 for invalid config or
duplicate IDs, and 500 for persistence or conflicting-add failures.
GET /mcp/upstream-status
Returns status and metrics for all upstream MCP servers (connecting, ready, circuit_open, disabled, failed).
MCP Instructions
GET /mcp/instructions
Returns server guidance for the MCP bridge binary as {"instructions": "..."}. It uses the same producer as MCP initialize, without live terminal or peer inventory. Configuration and capability changes can change the guidance; use session action=list and agent action=list_peers for current inventory.
Filesystem Endpoints
The sender-side fs_transfer_remote_paths coordinator is desktop IPC only (INTENTIONALLY_UNMAPPED), with no /fs/transfer-remote HTTP route. Data leaves the machine; Finder source paths cannot be gated to registered repository roots, so HTTP token holders must not trigger exfiltration. The desktop coordinator uses the existing authenticated daemon connection; only the receiving upload endpoint is exposed over HTTP.
POST /fs/upload-copy?destDir=<absolute-directory>&name=<leaf-name>&directory=true|false accepts a streamed, uncompressed tar body under the existing daemon authentication. All archive paths must start with name; only files and directories are accepted. Limits: 256 MiB of archive and extracted file data, 10,000 entries, two concurrent uploads. Destination resolution uses registered repository directory capabilities, rejects traversal and escapes through symlinks, and never follows a target symlink. Staging is removed on failure/disconnect; the completed top-level file or directory is published with a no-replace atomic rename. A concurrently created target is skipped; existing targets drain the bounded body before returning skipped. The upload is exempt from the global response timeout and aborts after 30 s without a body chunk. Its total receive budget is 17 minutes. A connection below roughly 2 Mbit/s cannot finish a 256 MiB drop within that budget. The concurrency permit lasts through extraction even if the handler is cancelled. Filenames use the receiver platform rules (POSIX permits colon and backslash); Windows rejects colon and backslash. Unix tar permissions are masked to 0755 for executable files/directories and 0644 for ordinary files, with the receiving umask applied and no privilege bits. Normal request-drop cleanup consumes the staging directory handle before removing its tree, including on Windows. Abrupt process termination (for example, kill -9) can leave a .tuic-upload-<uuid> directory in the destination; there is no startup sweep, and the leftover can be removed manually once no upload is running. Final directory permissions are applied after publication; a permission failure is logged and the already published copy remains successful. The sender uses the existing tui-session cookie header; tokens are absent from upload URLs and reqwest error text. No new listener or credential is created.
POST /attachments/upload?kind=pty|acp&id=<pty-or-connection-id>&session=<acp-session-id>&name=<filename>
streams a binary request body into attachments/<session>/<timestamp>-<safe-name>
under TUIC’s data directory. session is required for ACP and omitted for PTY.
It returns { "path": "/absolute/path", "size": N, "notice"?: "..." }.
The default per-file cap is 25 MiB (attachment_max_bytes), including uploads
without Content-Length; partial and empty files are removed on failure.
Uploads never touch the cwd or Git excludes. PTY close, kill and exit, ACP
conversation detach and connection settlement remove their uploads; startup
removes only directories whose recorded owner process is provably dead. Live or
unknown ownership is preserved, including concurrent instances sharing the data
directory. Symlinked attachment roots/sessions are rejected.
Legacy agents without a launch grant receive HTTP 409 with a new-session notice.
Ego PTY and ACP receipts carry a notice because ego currently cannot accept extra
read roots through invocation flags or ACP. Authentication matches the other shared HTTP routes.
GET /fs/list?repoPath=/path/to/repo&subdir=src
GET /fs/search?repoPath=/path/to/repo&query=main&limit=50
GET /fs/search-content?repoPath=/path/to/repo&query=foo&caseSensitive=false&useRegex=false&wholeWord=false&limit=200
GET /fs/search-content-all?query=foo&caseSensitive=false&limit=200 -> cross-repo BM25 over every ready index
GET /fs/read?repoPath=/path/to/repo&file=src/main.rs
GET /fs/markdown-image?repoPath=/path/to/repo&file=docs/images/chart.png -> image bytes
GET /fs/read-external?path=/absolute/path/to/file
POST /fs/write { "repoPath": "...", "file": "...", "content": "..." }
POST /fs/markdown-review-lines { "path": "/abs/review.md", "baseline": "...", "expected": "..." } -> "3, 7-9" | null
POST /fs/write-if-unchanged { "repoPath": "...", "file": "...", "expected": "...", "content": "..." } -> true | false (false: disk text differs from `expected`, nothing written)
POST /fs/mkdir { "repoPath": "...", "dir": "..." }
POST /fs/delete { "repoPath": "...", "path": "..." } # removes final symlink itself, even when dangling
POST /fs/rename { "repoPath": "...", "from": "...", "to": "..." }
POST /fs/copy { "repoPath": "...", "from": "...", "to": "..." }
POST /fs/gitignore { "repoPath": "...", "pattern": "..." }
GET /fs/resolve-terminal-path?cwd=/repo&candidate=src/x.ts -> ResolvedFilePath | null
POST /fs/resolve-terminal-paths { "cwd": "/repo", "candidates": [...] } -> (ResolvedFilePath | null)[]
POST /fs/resolve-markdown-link { "root": "/repo", "currentFile": "docs/readme.md", "href": "../guide.md#intro" } -> MarkdownLinkTarget
GET /fs/stat?path=/absolute/path -> PathStat (exists/is_dir/size/modified_at)
POST /fs/warm-index { "repoPath": "..." } -> { "ok": true } (fire-and-forget BM25 build; strategy-gated, see below)
POST /fs/write-external { "path": "/abs", "content": "..." } -> { "ok": true }
POST /fs/copy-abs { "from": "/abs", "to": "/abs" } -> { "ok": true }
POST /fs/move-abs { "from": "/abs", "to": "/abs" } -> { "ok": true }
POST /fs/transfer { "destDir": "/abs", "paths": [...], "mode": "move"|"copy", "allowRecursive": bool } -> TransferResult
Bounded file reads
GET /fs/read accepts optional offset and length query parameters, both
unsigned 64-bit byte counts. Either parameter selects range mode. The default
offset is 0. The default and maximum length is 1,048,576 bytes (1 MiB).
Larger lengths are clamped; clamped is true only when the requested length
exceeds that limit. This endpoint uses query parameters, not the HTTP Range header.
Example: /fs/read?repoPath=/repo&file=notes.txt&offset=1&length=2, for a file
containing inside, returns HTTP 200:
{"data":"bnM=","offset":1,"bytesRead":2,"totalSize":6,"hasMore":true,"clamped":false}
| Field | Meaning |
|---|---|
data | Exact slice bytes as standard padded base64; no text conversion |
offset | Requested byte offset, including offsets beyond EOF |
bytesRead | Decoded byte count returned in this page |
totalSize | File size in bytes from metadata on the opened file |
hasMore | The end of this page is before totalSize |
clamped | Requested length exceeded 1 MiB |
Next offset is offset + bytesRead. Zero length returns an empty page;
hasMore can still be true, so clients must request a positive length to advance.
At or beyond EOF the page is empty with hasMore=false. Split UTF-8 sequences
and binary bytes are preserved exactly. Reassemble bytes before text decoding,
or use a streaming decoder. A page reads at most its bounded length, even for
files above the editor size cap. Pages are independent reads, not a file snapshot;
concurrent changes can alter size or contents between pages.
Without either parameter the existing JSON text string and 10 MiB editor cap
remain unchanged. IPC text reads retain their existing contracts. Range mode uses the same repository path check as full reads: the
requested path must be relative, and absolute, drive, network and above-root
.. paths are refused; owner symlinks are followed wherever they point. Existing authentication applies. Malformed, negative or overflowing
numbers return 400. Read/containment errors retain the existing 500 JSON error
shape; range mode also refuses non-regular files.
Editor pages. GET /fs/read-editor?repoPath&file and
GET /fs/read-editor-external?path accept the same optional offset and
length parameters and then return the same page object. IPC equivalents:
read_editor_file_page { repoPath, file, offset, length? } and
read_editor_file_external_page { path, offset, length? }. Without the
parameters, the whole-file text reply is unchanged: 250 MiB on the desktop
router, 10 MiB on the tuic-remote router. A page request refuses a file larger
than the 250 MiB editor limit with the same “too large” error, on both routers.
The external page route checks path syntax like the whole external read: a
relative or traversal path is refused with 400. The browser editor offers Load in
pages when the whole read is refused; it decodes pages with a streaming UTF-8
decoder and rejects the load when totalSize or the file’s stat changes.
/fs/warm-index returns { "ok": true } whether or not it scheduled anything.
/fs/markdown-image serves image MIME types up to 10 MiB for mobile Markdown previews. The requested file must be relative to the repository: absolute, drive, network and above-root .. paths return 403. Symlinks are followed wherever they point, like other repository reads; image type, the 10 MiB size limit and authentication still apply. It uses the same HTTP authentication as the other filesystem routes.
Under the disabled or active_only index strategies it deliberately builds
nothing, so a repo switch cannot index behind a setting that asked it not to.
The warm_content_index IPC command applies the identical gate — the two
transports share one implementation so they cannot drift.
/fs/search-content-all reports why a repo produced nothing, so the UI can tell
“no match” apart from “not searched yet”. Its result and every
content-search-batch carry repos_searched, repos_pending, and
repos_indexing — the last being the subset of repos_pending with a build
actually in flight. Only that subset justifies telling the user to retry; the
rest are waiting on a scheduling event that may never come.
Content-search results expose match_start and match_end as zero-based,
end-exclusive UTF-16 code-unit offsets within line_text. They can be passed
directly to JavaScript String.slice, including when text before the match
contains multibyte characters or non-BMP emoji.
Sandboxed filesystem operations for the file manager panel. /fs/read-external reads an arbitrary absolute path (not sandboxed to a repo).
Markdown review coordinates use the text before the first unsent local save, not Git history. baseline may be null; the range response is null when it is absent, no lines differ, or disk no longer equals expected. Deletion-only hunks name a surviving adjacent line (line 1 for an empty file). IPC and HTTP share the blocking-pool implementation; read/diff errors let the UI retain the whole-file prompt. Coordinates describe the captured saved document at send time; subsequent edits can move them while an agent request waits in the idle queue.
Agent Usage Endpoints
GET /claude/usage?sessionId=<id> -> UsageApiResponse (session profile rate limits, 5-min cache per profile; omitted id selects default; API-key sessions return the same `Claude API-key authentication` error as IPC without credential lookup or usage requests)
GET /claude/projects -> ProjectEntry[]
GET /claude/timeline?scope=all&days=7 -> TimelinePoint[] (hourly token aggregation)
GET /claude/session-stats?scope=current -> SessionStats
GET /codex/usage -> CodexUsageApiResponse (rate-limit usage, 5-min cached)
GET /codex/stats -> CodexStatsResponse (token history + lifetime stats)
GET /grok/usage -> GrokUsageApiResponse (billing usage, 5-min cached)
Terminal theme
POST /terminal/theme-colors {foreground:[r,g,b], background:[r,g,b], cursor:[r,g,b]}
Publishes the resolved terminal theme so the emulator can answer OSC 10 / 11 / 12 colour queries. Not session-scoped: one window, one palette.
This is not cosmetic. An app asks for the background with OSC 11 ; ? ST
followed by ESC[c as a fence — DA is universally supported, so a DA reply
arriving with no colour reply before it is meant to mean “this terminal cannot
answer”. A terminal that stays silent therefore never reads as “no”, and the
probe simply retries: Claude Code re-sent the pair every ~1.2 s for the whole
life of a session, and every DA reply it triggered was written into the PTY as
if typed. Until the frontend posts here, the emulator answers from a dark
default — a plausible wrong colour ends the probe, silence does not.
Powers the Claude Usage dashboard in browser/PWA/remote. scope is "all",
"current", or a project slug. timeline/session-stats are desktop-only Tauri
commands; the handlers call non-gated *_impl siblings so they also serve the
remote daemon.
Both Codex routes launch the documented Codex App Server over JSONL and request
account/rateLimits/read plus account/usage/read in one cached snapshot. The
Codex CLI owns OAuth, refresh, and its upstream protocol; TUIC never reads
~/.codex/auth.json or calls private ChatGPT backend routes. The response keeps
the existing snake-case TUIC transport shape, but fields that the official
surface does not expose remain null rather than being inferred.
/grok/usage launches grok agent stdio briefly and calls Grok Build’s
_x.ai/billing ACP extension. It returns billing-period utilization,
subscription tier, on-demand amounts, and prepaid balance. This process is
telemetry-only and does not change the PTY routing of interactive Grok tabs.
Gemini has no corresponding endpoint: its /stats and /usage commands are
session-local UI data, not a stable account quota contract. TUIC therefore does
not expose a Gemini account-usage route.
/fs/read-external and /fs/read-editor-external read any absolute local text file the owner can read, for every authenticated caller (loopback and network), matching the desktop IPC reads. HTTP authentication and the Host/Origin boundary still apply. A traversal (..), NUL or relative path gets a 400 before any read. Markdown link clicks use /fs/resolve-markdown-link to decode tuic://open/ before the normal local filesystem checks. Image previews use the existing authenticated, directory-scoped /fs/markdown-image route.
Absolute-path write boundary. /fs/write-external, /fs/copy-abs, and /fs/move-abs are gated to registered repository roots for the HTTP boundary (a 403 otherwise), although the absolute-path reads are not confined. The gate rejects traversal syntax (..), NUL bytes, and relative paths before the containment check: containment is Path::starts_with, which is purely lexical, so /repo/../../etc/passwd is “inside” /repo by components while the OS resolves it far outside. Paths are deliberately not canonicalized — a symlink inside a registered repo that points outside it is an accepted design decision in this project. /fs/transfer gates only its destDir — sources are commonly external (a file dragged in from the desktop). /fs/stat and /fs/resolve-terminal-path return only metadata (no content) so they are not repo-gated; both also refuse macOS TCC-protected directories. /fs/resolve-terminal-path returns JSON null on a miss (Option<ResolvedFilePath>). /fs/resolve-terminal-paths is its batched sibling and is a POST for one reason: a whole terminal screen’s candidates do not fit a query string, and being able to send many of them is the point. It answers positionally — the array it returns has one entry per input candidate, in order, null where that candidate resolved to nothing — so a caller may index the response by the index of the request.
/fs/resolve-markdown-link returns a tagged kind (heading, file, missing, external, or blocked). It decodes path and fragment separately, resolves relative to the source file, permits local symlinks outside the root, and returns UNC/network paths as { kind: "external", target } before filesystem access; the client opens them only after owner confirmation. Device and verbatim namespaces (\\.\, \\?\) stay blocked.
Monitoring Endpoints
Health Check
GET /health
Returns { "ok": true, "uptime_secs": N, "session_count": N, "protocol_version": 1, "build": { "version": "...", "target": "...", "sha256": "..." }, "socket_path"?: "...", "instance_id": "<uuid>", "survive_secs"?: N }.
The one route served without a credential. instance_id identifies the running
process (minted at startup, not derived from the instance id or the config
directory): a remote connection compares it against its own before mirroring and
refuses a base URL that resolves back to itself. A daemon that omits the field is
older than the check and still connects.
The daemon hashes its running executable once at startup, so build.sha256
identifies the process that answered even after an update stages a new file.
POST /remote/update exists only on the daemon router. It needs the same
session token as PTY access, supplied only as a tui-session cookie (a
?token= query is rejected with 401 on this route and on /fs/upload-copy), and the x-tuic-target, x-tuic-sha256, and
x-tuic-confirmed-sessions headers. It streams at most 512 MiB into the
daemon executable’s own directory, verifies the hash and current session
count, and atomically promotes the file before restarting. Windows currently
returns 501 because a running executable cannot be replaced there.
survive_secs is present when tuic-remote was launched with an idle lifetime.
Desktop-managed SSH deployment sets the vault pairing token as this daemon’s
session token, so the same ?token= contract protects every authenticated HTTP,
SSE and WebSocket route without a separate pairing bypass.
Orchestrator Stats
GET /stats
Returns { "active_sessions": N, "max_sessions": 50, "available_slots": N }.
Session Metrics
GET /metrics
Returns { "total_spawned": N, "failed_spawns": N, "bytes_emitted": N, "pauses_triggered": N }.
Raw PTY Capture
POST /diagnostics/capture accepts { "enabled": true, "session_id"?: "<id>" }
to start recording one or all sessions; { "enabled": false } stops it.
GET /diagnostics/capture reports the active directory, session filter and
bytes recorded. Captures default to <config dir>/captures/<id>.tcap.
Set the process environment variable TUIC_CAPTURE_DIR to an absolute path
before launch to select another directory. A relative value returns
{ "enabled": false, "error": "TUIC_CAPTURE_DIR must be absolute" } on enable.
Local IPs
GET /system/local-ips
Returns local network interfaces and addresses, ranked for pairing and phone secret entry: active Tailscale HTTPS, Wi-Fi/LAN, HTTP-only Tailscale, then other networks. Equal-ranked entries retain interface order. All candidates remain available for manual selection; an empty list means no detected address.
Local IP (Primary)
GET /system/local-ip
Returns the preferred local IP address (single value).
Home Directory
GET /system/home-directory
Returns the serving machine’s home directory as a JSON string. The remote repository picker uses this route through the selected connection.
Watcher Endpoints
Head Watcher
POST /watchers/head?path=/path/to/repo
DELETE /watchers/head?path=/path/to/repo
Start/stop watching .git/HEAD for branch changes. Browser-only mode.
Repo Watcher
POST /watchers/repo?path=/path/to/repo
DELETE /watchers/repo?path=/path/to/repo
Start/stop watching .git/ for repository state changes. Browser-only mode.
Directory Watcher
POST /watchers/dir?path=/path/to/directory
DELETE /watchers/dir?path=/path/to/directory
Acquire/release a shared nonrecursive directory watch for file changes (create/delete/rename). Pair each successful POST with one DELETE. A path shares one native watcher across IPC and HTTP consumers; only the last release stops it. Emits dir-changed SSE events. Used by the File Browser panel for auto-refresh.
Hot Repos
PUT /watchers/hot-repos
Body: {"paths": ["/path/to/repo", ...]}
Updates the set of “hot” repository paths (repos with active terminals). Cold repos (not in this set) get throttled watcher debounce (15s vs 1.5s) and reduced GitHub polling frequency (~10min vs ~1min). HTTP equivalent of the set_hot_repos Tauri command, served by both the desktop server and tuic-remote — a browser client of the desktop app needs it just as much as a remote one.
Every /ai/* route is unmounted (#784-0aec)
GET/PUT /ai/chat/config, the /ai/chat/conversation* CRUD, the per-chat and
per-session token WebSockets, /ai/watchers*, /ai/conversation/*,
/ai/session-knowledge, /ai/knowledge/*, /ai/scheduler/config,
/ai/suggestions/toggle, /ai/triage/run, /ai/improvements/scan and
/repo/create-issue-from-proposal are all gone, together with the Rust modules
behind them. Nothing under /ai/ is served.
build_router is the authority, and the route parity gate holds the two halves
together: command_table_paths_all_hit_a_registered_route PATCH-probes every
path src/transport.ts can produce, so a COMMAND_TABLE entry pointing at a
removed route fails the Rust suite rather than 404-ing at runtime.
The ACP routes are the replacement surface — see ACP endpoints — and they
carry no provider configuration: TUICommander launches one ego executable named
by ego_executable in app_config.json and holds no API key.
Agent Endpoints
Verify Agent Session
POST /agents/verify-session
Content-Type: application/json
{ "agentType": "claude", "sessionId": "af467730-5e79-49d9-8a17-ebd94c99f262", "cwd": "/work/project", "agentPid": null, "envOverrides": { "CLAUDE_CONFIG_DIR": "/profiles/work" } }
Returns a JSON boolean. agentPid is a live process ID when available and null after restart; envOverrides carries the saved launch profile so verification reads the same session store the agent used. The same fields apply to Codex (CODEX_HOME) and Gemini (GEMINI_CLI_HOME).
Detect All Agents
GET /agents
Returns detected agent binaries and installed IDEs.
Detect Specific Agent
GET /agents/detect?binary=claude
Returns { "path": string|null, "version": string|null, "supports_no_alt_screen": boolean } for a specific agent binary name or absolute executable path. Codex and Grok probe --no-alt-screen; OpenCode probes --mini. Successful help results are cached per executable version. A failed probe warns once and is retried after a short cooldown; each attempt has a two-second deadline. An absolute path checks that exact installed version.
Prepare Agent Launch Arguments
POST /agents/launch-args
Content-Type: application/json
{ "agentType": "codex", "binaryPath": "codex", "args": ["resume"] }
Returns the argument array with the agent’s supported native-scrollback option inserted before an interactive subcommand. An explicit option, a disabled per-agent prevent_alt_screen setting, or a non-interactive subcommand leaves the array unchanged. The removed allowAltScreen request field is rejected, as is allow_alt_screen on HTTP agent spawn. The desktop prepare_agent_launch_args command uses the same Rust builder. Remote HTTP callers must authenticate.
Detect Installed IDEs
GET /agents/ides
Returns list of installed IDEs.
Batch Detect Agent Binaries
POST /agents/detect-all
Content-Type: application/json
{ "binaries": ["claude", "codex"] }
Returns { "<binary>": { "path": string|null, "version": string|null, "supports_no_alt_screen": false }, ... }.
Detection runs in parallel and skips version lookup for speed; use
GET /agents/detect when the version matters. Blank names are dropped, so a name
that was sent may be absent from the map.
Open Path in Application
POST /agents/open-in-app
Content-Type: application/json
{ "path": "/repo/src/main.rs", "app": "vscode", "line": 42, "col": 7 }
Opens the path in an IDE, terminal or file manager. line and col are optional
and only used by editors that support them. An unknown app is rejected before
anything is spawned. Returns null on success, matching the open_in_app command.
Dictation Endpoints
The HTTP routes and Tauri commands share the root dictation adapter. The tuic-dictation crate supplies the audio and speech domain without changing these route shapes.
Desktop-only: audio capture and the whisper model live behind the desktop
feature, so the remote daemon serves none of these. Every response is exactly what
the matching dictation::commands Tauri command resolves to — a bare string for
inject, null for the commands that return nothing — because
src/stores/dictation.ts reads both transports with the same code. Before the app
handle is up, every state-touching route answers 503.
The dictation config field hands_free_listening (default true) selects hands-free capture versus a replies-only conversation, and hands_free_spoken_replies (default true) is shared by IPC and HTTP. Off cancels speech and refuses new replies without disarming capture. Speech status reports available=false and unavailableReason. The MCP voice tool includes these fields on refused speak requests. Edge HTTP 401/403 starts a five-minute cool-down across queue rebuilds; status names the rejection and the five-minute policy.
GET /dictation/status -> DictationStatus
GET /dictation/models -> ModelInfo[]
POST /dictation/models/download { "model": "..." } -> "Downloaded to <path>"
POST /dictation/models/delete { "model": "..." } -> "<deletion message>"
GET /dictation/speech/assets -> SpeechAssetInfo[]
POST /dictation/speech/assets/download { "asset": "..." }
-> "Installed to <path>"
POST /dictation/speech/assets/cancel { "asset": "..." }
-> "<cancellation message>"
POST /dictation/speech/assets/delete { "asset": "..." }
-> "<deletion message>"
GET /dictation/speech/voices?language=it -> VoiceChoice[]
POST /dictation/speech/voices/import { "language": "it", "name": "...", "dataBase64": "..." }
-> "<import message>"
POST /dictation/speech/voices/delete { "language": "it", "name": "..." }
-> "<deletion message>"
POST /dictation/speech/voices/preview { "language": "it", "voice": "...", "text": "..." }
-> null
POST /dictation/speech/speak { "text": "...", "turn": 3 }
-> SpokenReply
POST /dictation/speech/stop -> SpeechStatus
POST /dictation/speech/pause -> SpeechStatus
POST /dictation/speech/resume -> SpeechStatus
GET /dictation/speech/status?utterance=7 -> SpeechStatus
POST /dictation/start { "source": "fn" | "hotkey" | "ui" } -> null
POST /dictation/stop -> TranscribeResponse
GET /dictation/corrections -> { "<from>": "<to>", ... }
PUT /dictation/corrections { "map": { ... } } -> null
GET /dictation/devices -> AudioDevice[]
POST /dictation/inject { "text": "..." } -> "<corrected text>"
GET /dictation/config -> DictationConfig
PUT /dictation/config {base, config} -> null
GET /dictation/hands-free -> HandsFreeStatus
GET /dictation/hands-free/default-notice -> string
POST /dictation/hands-free/arm { "sessionId": "...", "owner": "..." }
-> HandsFreeStatus
POST /dictation/hands-free/disarm -> HandsFreeDisarmed
GET /dictation/hands-free/audio?owner=<id> -> WebSocket upgrade
POST /dictation/stop stops the recording and transcribes it, returning
{ text, skip_reason, duration_s, truncated_s }. A final transcription gate’s
skip_reason is returned unchanged. A capture without 200 ms of activity at
the configured transcription RMS floor returns no sustained speech before
Whisper; an empty successful transcription uses
no speech detected. PUT /dictation/config takes the loaded base and
edited config; unchanged keys survive a concurrent save.
The speech-asset routes take asset, an id from the catalogue in
dictation::speech::assets. That is an allowlist, not a hint: an unknown id is
a 400-shaped error string rather than a path or a URL built from what the
caller sent. download is minutes long and streams nothing back — progress
arrives as speech-download-progress, on the desktop window and on
/events, carrying { asset, downloaded, total, percent }, then one final { asset, done: true }
whether the download succeeded or failed. That last event is how a client that
did not start the download ends its bar; it carries no outcome, so re-read
GET /dictation/speech/assets for the new state. The Whisper-model
download beside it pushes dictation-download-progress with the same body minus
asset.
SpeechAssetInfo is snake_case on the wire — it carries no serde rename,
unlike SpeechStatus and HandsFreeStatus beside it. Its language is the
Whisper language code ("it"), null for the runtime library: the same
alphabet as DictationConfig.language and SpeechStatus.language, so a client
can join an asset to the configured language directly. For a language, voices
lists the voice it ships. get_speech_assets also lists every catalogue voice
(kind: "voice", language = its language’s code, voice = the voice name),
which the download routes above accept like any other asset.
Voices
language is the Whisper code on all four routes.
GET /dictation/speech/voices?language=answers the voices the language can speak with now — the valuesspeech_voicemay be set to — as[{ id, source }],sourcebeing"default","downloaded"or"user". It is[]while the language itself is not fully downloaded.POST /dictation/speech/voices/importstores a voice file the user chose. The body carries the whole file as base64 underdataBase64, the same camelCase key as the IPC argument. This route alone accepts a body of about 85 MiB (SPEECH_VOICE_IMPORT_BODY_BYTES: a 64 MB file in base64 plus 64 KiB); every other route keeps the 2 MB limit. The server checks the name, the size and whether the file fits the language’s model before it stores anything, and refuses with the reason otherwise.POST /dictation/speech/voices/deleteremoves a user voice file. Absent is success.POST /dictation/speech/voices/previewspeakstext(at most 200 characters) invoiceon the speaker of the machine that runs TUICommander, with the saved loudness settings. It needs no hands-free conversation and does not change the saved voice. It is refused, not queued, while a hands-free reply is queued, rendering or playing.
Spoken replies
The three speech routes are the browser/remote half of speak_reply,
stop_speech and get_speech_status, and carry the identical payloads — the
same store code reads both transports.
POST /dictation/speech/speak takes { text, turn? } and answers
SpokenReply { utteranceId, state, error?, turn }. state is what the queue
knows at that instant, which is "queued" and never "finished": accepting a
reply is not the user hearing it. Poll GET /dictation/speech/status?utterance=
with the id to learn the outcome — finished, interrupted (normal, the user
talked over it) or failed. An id the conversation no longer remembers comes
back as "unknown", which is a different answer from “you asked about nothing”.
turn is optional and refuses a reply written for a turn the user has already
talked over; omitting it means “now”. POST /dictation/speech/stop stops
immediately, drops the queue and opens a new turn, returning the SpeechStatus
so the caller learns that turn.
All three are answerable at any time: with nothing armed, or with no working
voice, status reports available: false and names the reason rather than
failing.
Polling is no longer the only way to learn the outcome: every transition is
pushed as speech-utterance, carrying the same SpokenReply body this route
returns, on the desktop window and on /events. It is emitted by the render
thread that performs the transition rather than by speak — finished and
interrupted happen long after speak returned — so a client that subscribes
sees queued → rendering → speaking → finished without asking.
SpeechStatus.language is the two-letter code this conversation is being held
in: the dictation setting when it names one, and what Whisper detected when the
setting is auto. Empty means nobody has spoken yet under auto — the one
state in which no reply can be spoken, reported as available: false with a
reason naming Auto rather than filled in with a default. Neither the speak
payload nor the voice MCP tool takes a language or a voice: the language comes
from this field and the voice from the speech_voice setting, and a second
source would disagree with them the first time the user switched languages.
speech_voice names one of the voices the configured language ships, reported
in voices by GET /dictation/speech-assets. Empty — what every configuration
written before the setting existed says — means the first voice that language
ships. A name the language does not ship is refused with a message that lists
what it does ship, rather than being replaced by a voice nobody chose.
PUT /dictation/config with a different language, speechCommand or
speech_voice drops the voice built for the previous one, cancelling whatever
it was speaking. Every other field leaves it alone.
Hands-free
POST /dictation/hands-free/arm binds the delivery target and the audio owner,
and opens a generation. It does not open a microphone. A target that cannot
take a Compose entry — an unknown session, or a session that is not running an
agent — is refused with the error the Tauri command returns, so the two
transports reject the same cases.
owner is the caller’s own endpoint identity: a remote client that arms here
binds itself, so a later disconnect can disarm the mode it owns. Both fields
are bounded at 256 bytes and may not be blank. Open the audio socket below
first — arming an owner with no socket is refused with No client is connected for audio owner '<owner>', because the backend will not substitute the server’s
own microphone for a client’s (see docs/backend/dictation.md).
POST /dictation/hands-free/disarm disarms the whole mode and drops the
transcript that never reached the model (discardedPending). It is idempotent:
the second call reports wasArmed: false. Spoken turns are typed straight into
the bound agent’s composer — busy or not — and never parked in the Compose
queue, so there is nothing to cancel and nothing typed can be taken back.
Both bodies are the structs dictation::commands serializes, camelCase on the
wire and identical on both transports:
HandsFreeStatus { armed, listening, phase, sessionId, owner, generation, pendingText, holdBackMs, error, deliveredTurns, droppedTurns }HandsFreeDisarmed { wasArmed, generation, discardedPending, discardedCapture, status }
pendingText is the turn waiting out its hold-back, or held by a permission
dialog or a draft in the composer (phase holding_back) until it can be typed.
With an activation phrase, holdBackMs reports the effective minimum of 5000
ms, even when the saved hold-back setting is shorter. A continuation that
starts before that deadline joins the same pending turn.
wake_confirmed acknowledges a recognized leading activation phrase during open
capture; it does not admit or submit the final transcript. VAD alone remains
capturing. Both capture sources use the same bounded prefix recognition.
phase is one of disarmed, waiting, capturing, wake_confirmed, transcribing,
holding_back, delivered, error.
deliveredTurns counts spoken turns typed into the composer and
droppedTurns counts turns the activation phrase dropped. Both are monotonic
for the life of the backend process and are never reset on arm, so a client
detects a turn by comparing two polls — the earcons key on them, because a
delivered phase can be overwritten before the next poll and a drop has no
phase at all. hands_free_earcons in the dictation config (default true)
turns them off; only the frontend reads it.
Arming and disarming also tell the bound model so, unless
hands_free_notify_model is false in the dictation config (it defaults to
true; DictationConfig is snake_case on the wire, unlike the two structs
above). The start notice is typed like a spoken turn; a dialog or a draft holds
it in the mode, ahead of any turn, and a disarm that arrives first drops it — in
which case no end notice is sent, because the model never read the start one.
hands_free_start_notice replaces the start notice’s text (empty means the
built-in one, which GET /dictation/hands-free/default-notice returns as a JSON
string); Rust folds it to one line before it is typed.
error carries the reason when the queue refuses a notice; arming still
succeeds. Turning the setting off never leaves speech running: a disarm revokes
it either way.
The client’s microphone and speaker (832-e730)
GET /dictation/hands-free/audio?owner=<id> upgrades to the WebSocket that
is a browser client’s audio hardware, seen from the conversation’s side. It
carries capture up and replies down on one socket, in both directions at once.
| Direction | Frame | Meaning |
|---|---|---|
| up | binary | f32 little-endian samples, mono, 16 kHz |
| up | {"type":"playback-ended","sequence":"1"} | the reply finished playing |
| down | binary | u32 little-endian sample rate, u64 little-endian reply sequence, then f32 little-endian samples |
| down | {"type":"stop"} | stop playing and drop anything queued |
| down | {"type":"pause"} | hold the reply where it is, and any that arrives |
| down | {"type":"resume"} | continue from where it was held |
Replies append on the browser audio clock; they do not replace active audio or
wait for a JavaScript ended callback to start the next buffer. Each completed
reply acknowledges its sequence as a decimal string (preserving all 64 bits).
Sequences increase for the socket lifetime, including across stop controls. Old,
duplicate and unknown acknowledgements cannot finish newer queued audio. The
server fallback deadline adds queued durations and preserves the remainder
across pause/resume. Reload browser clients when updating the backend: the
sequence-bearing binary format replaces the previous four-byte-only header.
The downlink carries its own rate because it is not the uplink’s: the engine renders at 24 kHz and the client resamples. A reply decoded at the capture rate plays 50% slow — audible to a person, invisible to an assertion about lengths. A trailing partial sample on the uplink is ignored rather than rejected.
owner must be present, non-empty and not the literal desktop; both
violations are a 400. Registering as desktop would let a remote client
impersonate the machine’s own endpoint, which is the one owner that means local
hardware.
Opening a second socket under an owner that already has one replaces it and
disconnects the first, so the conversation the first socket held disarms with
OwnerDisconnected rather than silently following the new client. Closing the
socket does the same. There is no reconnect window: a conversation belongs to a
socket, not to a name.
Playback here is best-effort by construction — the server can stop sending,
but only the client can stop playing. The playback-ended ack is what lets
the backend see the end of a reply; without it the utterance stays speaking
until its rendered duration elapses.
Desktop Integration Endpoints
Desktop-only, like the three commands they mirror: the relay client, the audio
output and the updater are all gated on the desktop feature.
Relay Status
GET /system/relay-status
Returns { "enabled": bool, "connected": bool, "url": string, "session_id": string }.
Shares one body with the get_relay_status command, so the two transports cannot
drift.
Play Notification Sound
POST /system/notification-sound
Content-Type: application/json
{ "sound": "question", "volume": 0.5, "device": "Studio Display Speakers" }
sound is one of question, completion, error, warning, info,
attention. device is the chosen audio output; null or omitted uses the
system default. Returns null, matching the command.
Check Update Channel
GET /system/check-update?channel=nightly
Returns { "available": bool, "version": string|null, "notes": string|null, "release_page": string|null, "not_found": bool }.
Channels are beta and nightly. Beta returns the immutable versioned release page for downloads. Channel URLs are hardcoded — no user-supplied URL is accepted. An unpublished
channel is not_found: true, not an error; an unknown channel name is a 500.
Prompt Endpoints
Process Prompt
POST /prompt/process
Content-Type: application/json
{ "content": "...", "variables": { ... } }
Substitutes {{var}} placeholders in prompt text.
Extract Variables
POST /prompt/extract-variables
Content-Type: application/json
{ "content": "..." }
Returns list of {{var}} placeholder names found in content.
Plugin Endpoints
List Plugins
GET /plugins/list[?plugin_ids=<URL-encoded JSON string array>]
Returns an array of valid plugin manifests. Omit plugin_ids for full discovery;
pass a JSON string array to read only those plugin IDs. An empty array returns no
plugins. Invalid JSON returns 400. IPC uses the same optional pluginIds array.
Payload digests reuse unchanged file hashes by modification time and size.
Plugin Development Guide
GET /plugins/docs
Returns the complete plugin development reference as {"content": "..."}. AI-optimized documentation covering manifest format, PluginHost API, structured event types, and example plugins.
Plugin Data
GET /api/plugins/:plugin_id/data/*path
Reads a plugin’s stored data file. Returns application/json if content starts with { or [, otherwise text/plain. Returns 404 if the file doesn’t exist. Goes through the same auth middleware as all other routes.
Note: write_plugin_data maps to POST /api/plugins/:plugin_id/data/*path; delete_plugin_data has no HTTP route (no frontend caller). Data is sandboxed to ~/.config/tuicommander/plugins/{plugin_id}/data/.
Plugin RPC (host capabilities, story 071)
Browser/PWA parity for the plugin host RPC surface. Every route is :plugin_id-scoped
and reuses the same per-plugin sandboxing as the Tauri commands (plugin_fs.rs absolute-path
resolution with a $HOME jail for writes and renames, plugin_http.rs allowed-URL check, plugin_exec.rs binary whitelist).
GET /api/plugins/:plugin_id/fs/read?path=<p> -> string (plugin_read_file)
GET /api/plugins/:plugin_id/fs/read-base64?path=<p>&maxBytes=<n> -> string (plugin_read_file_base64; maxBytes optional, 10 MiB default, 512 MiB host ceiling)
GET /api/plugins/:plugin_id/fs/tail?path=<p>&maxBytes=<n> -> string (plugin_read_file_tail)
GET /api/plugins/:plugin_id/fs/list?path=<p>&pattern=&sortBy= -> string[] (plugin_list_directory)
POST /api/plugins/:plugin_id/fs/write { path, content } -> { ok } (plugin_write_file)
POST /api/plugins/:plugin_id/fs/write-base64 { path, content, maxBytes? } -> { ok } (plugin_write_file_base64; 10 MiB default, 512 MiB host ceiling, atomic replace)
POST /api/plugins/:plugin_id/fs/rename { from, to } -> { ok } (plugin_rename_path)
POST /api/plugins/:plugin_id/build-artifacts/scan { repoPaths, forceRefresh? } -> BuildArtifact[]
POST /api/plugins/:plugin_id/build-artifacts/delete { path, repoPaths } -> { ok }
POST /api/plugins/:plugin_id/build-artifacts/trim { path, repoPaths } -> { ok } (intermediates only; keeps executables)
POST /api/plugins/:plugin_id/exec { binary, args, cwd?, timeoutMs? } -> string (plugin_exec_cli; timeoutMs 1..3600000, default 30000; 4 concurrent per plugin)
POST /api/plugins/:plugin_id/http { url, method?, headers?, body?, account? } -> HttpResponse
GET /api/plugins/:plugin_id/pty/output?sessionId=<id>&maxLines= -> string (plugin_read_session_output)
POST /api/plugins/:plugin_id/register { capabilities } -> { ok }
POST /api/plugins/:plugin_id/unregister -> { ok }
GET /api/plugins/:plugin_id/readme -> string | null
Build-artifact scans normalize the root set, share an in-flight scan across callers,
and reuse completed results for 30 seconds. Set forceRefresh: true to bypass a
completed cached result; a scan already running for the same roots remains shared.
Intentionally not mapped (native/host-only, stay Tauri-only): plugin_watch_path /
plugin_unwatch (change events need AppHandle/WS delivery), plugin_read_credential
(OS keychain), and user-plugin install/uninstall (install_plugin_from_*,
uninstall_plugin — local-FS install + AppHandle emit). delete_plugin_data is unmapped
for lack of a frontend caller (YAGNI).
Plugin Output Watchers
POST /api/plugins/output-watchers
Content-Type: application/json
{
"client_id": "b7d1…",
"seq": 3,
"watchers": [{ "id": "w0", "pattern": "model is at capacity", "flags": "i" }]
}
Replaces the compiled OutputWatcher set the PTY reader thread matches lines against
(set_plugin_output_watchers). pattern and flags are the source and flags of a JS
RegExp; i, m and s are applied. The route is not :plugin_id-scoped: one
frontend owns one set, holding the watchers of all its plugins, and pushes all of it on
every add or remove.
client_id identifies the frontend. Sets are per client (at most 8; the least recently
synced is evicted, and an empty watchers array leaves a parked record so a delayed
older sync cannot resurrect the disposed set), so a desktop window and a browser tab
cannot overwrite each other. A client is expected to re-post its set every 30 s while it
holds any watcher: nothing signals a disconnect, so that heartbeat is both what keeps it
from being evicted as dead and how it recovers if it was. It must not contain /, which qualifies the
watcher ids reported back. seq is a monotonic per-client counter that orders the
mutations: a sync whose seq is not above the stored one is stale and changes nothing.
Returns { "applied": bool, "rejected": [id] }. rejected lists the ids the Rust
regex crate cannot compile (lookaround, backreferences, a negated class escape inside
a character class). A rejected id is not an error — the frontend keeps matching that
watcher itself, and Rust ships every assembled line for as long as one is registered.
When applied is false the sync was stale: the client must ignore rejected, because
it describes a set the backend does not hold.
Assembled lines are pushed back as the watcher-lines WebSocket frame (on
/sessions/:id/stream in both ?format=grid and raw mode; ?format=log|text does not
carry it) and the plugin-watcher-lines SSE event.
Worktree Endpoints
List Worktrees
GET /worktrees
Returns list of managed worktrees.
Create Worktree
POST /worktrees
Content-Type: application/json
{ "base_repo": "/path", "branch_name": "feature-x", "base_ref": "main" }
base_repo must be an absolute, normalized path. The route rejects invalid paths
before invoking git, matching MCP repo action=worktree_create validation.
Creation always produces a linked worktree and refuses a branch that already has a checkout. Parent tracked and untracked changes are not carried over.
An explicit base_ref is resolved to a commit before creation. A missing or
non-commit ref fails without creating a checkout or branch. If the requested
branch already exists at a different commit, creation fails instead of ignoring
the base or resetting the branch. A matching existing branch remains reusable.
Without base_ref, the existing branch or repository HEAD remains the default.
Both HTTP and MCP return base_commit: the full checkout commit captured before
the setup script runs. This also applies to recycled checkouts.
Creation receipts and GET /worktrees/paths include creator_session: the
stable TUIC peer identity of the bound MCP caller, not its PTY ID. HTTP and
IPC creation without a peer binding, legacy checkouts and external checkouts
report explicit null. The identity is stored in the checkout’s Git
administration directory before creation events or API inventory publication.
It survives daemon reloads and is replaced when a checkout is recycled or
restored for a new allocation. MCP repo worktree_create and worktree_list
return the same field. Existing-branch allocation records the same identity.
The creation event’s creator_session remains a live PTY routing field; it is
not the durable provenance field on receipts and inventory.
201 returns:
{
"name": "feature-x",
"path": "/path__wt/feature-x",
"workspace_id": "feature-x",
"branch": "feature-x",
"base_repo": "/path",
"base_commit": "<full resolved commit ID>"
}
instructions is the model-facing payload: it states that tracked changes were
not carried over, lists warm artifact directories with their sizes and
warmed_directories, and explains that refs and objects are shared with the
parent. It is byte-identical to
what MCP repo action=worktree_create returns — one value, two carriers — and
it is the ONLY instruction channel: there is no enforcement layer behind it.
Its warm_artifacts.status starts as pending; wait for done or failed
in GET /worktrees/paths?path=<base_repo> before installing or building.
The setup script completes before warming begins. Desktop IPC creation also
returns pending and warms in the background.
workspace_id is how every later call addresses this workspace — DELETE /worktrees/:workspaceId, POST /worktrees/finalize,
GET /repo/worktree-dirty, MCP action=worktree_remove. Read it from the
response rather than deriving it from display data. MCP
repo action=worktree_create returns the same two fields.
GET /worktrees/lifecycle provides the removal preview: branch history, dirty and untracked counts, live session names, and warnings. DELETE /worktrees/:workspaceId includes the same warnings on success.
Creation announces itself on both transports as worktree-created
({ repo_path, workspace_id, branch, worktree_path, kind, creator_session, spawn_session }, with kind equal
to "worktree") and removal as
worktree-removed ({ repo_path, workspace_id, branch }) — the desktop Tauri
event and the /events SSE frame serialize the same struct, so the field names
are identical by construction. Payload table: docs/sync-matrix.md.
creator_session is the live PTY id resolved from the MCP connection, or null
for creation without a bound caller. When spawn_session is false, the UI moves
only that session within its existing repository. Explicit session creation
leaves the caller in place. Placement does not change the shell cwd or send
input to an agent. The existing per-workspace terminal snapshots preserve the
placement on restart; an inactive caller does not change the current selection.
Worktrees Base Directory
GET /worktrees/dir
Returns the base directory where worktrees are created.
Get Worktree Paths
GET /worktrees/paths?path=/path/to/repo
Returns { "<workspace-id>": { "branch": "feature-x", "path": "/worktree/path", "kind": "worktree", "warm_artifacts": { "status": "pending" } }, ... }.
The map is keyed by workspace id and carries the branch explicitly as display data. Linked-worktree ids currently equal their branches, but clients should use the returned id for later calls.
Workspace Lifecycle Preflight
GET /worktrees/lifecycle?repoPath=/path&workspaceId=feature-x~a1b2c3d4
Returns a fresh { dirty_files, missing_checkout, dirty_fingerprint?, submodule_unpushed_commits, commit_status, removal_safety, error? } verdict
for one exact workspace. dirty_files counts the staged, unstaged and untracked
files a removal would discard; null means the inspection failed and is not the
same answer as 0. dirty_fingerprint identifies checkout status, HEAD, and submodule refs for
revalidation. submodule_unpushed_commits lists counts per initialized module
for commits absent from its remote-tracking branches. commit_status is
unmerged, in_sync, merged, or unknown — in_sync is HEAD sitting on the default branch’s tip, which
satisfies the same ancestry check as merged while having merged nothing.
removal_safety is safe, requires_force, or unknown. An inspection
failure is returned as an unknown verdict and must never be treated as zero or
safe. A missing registered checkout returns missing_checkout: true, dirty_files: null, no fingerprint, and requires_force; unknown ids remain unknown. The response also includes archive_checklist (checks: [{ passed, label }], can_delete, archive_explanation, delete_explanation), untracked_files, copied_files (path and classification; legacy untracked paths use uncertain-no-copy-proof), live_sessions with names, and warnings for removal review. This is the HTTP twin of get_workspace_lifecycle.
Generate Worktree Name
POST /worktrees/generate-name
Content-Type: application/json
{ "existing_names": ["name1", "name2"] }
Returns a unique worktree name.
Finalize Merged Worktree
POST /worktrees/finalize
Content-Type: application/json
{ "repoPath": "/path/to/repo", "workspaceId": "feature-x", "action": "archive", "force": false }
Finalizes a merged worktree, addressed by workspace id. The merge already
happened, so no branch is needed here — only which checkout to dispose of. action must be "archive" (moves to archive directory) or "delete" (removes worktree and branch).
For action: "delete", the response includes branch_delete_warning when the worktree was removed but safe branch deletion failed, for example because the branch has unmerged commits.
force (optional, default false) records explicit confirmation. A dirty, unverified, or live worktree returns { "action": "needs_confirmation", "merged": true } without cleanup; an archive also waits if commit integration is unverified. Ask the user, then re-send with "force": true and "expectedFingerprint" from the confirmed lifecycle verdict. A changed fingerprint aborts cleanup. This route shares finalize_merged_worktree_impl_with_confirmation with the Tauri command, so both transports pass the identical gate.
Run Setup Script
POST /worktrees/run-script
Content-Type: application/json
{ "script": "pnpm install", "cwd": "/path/to/worktree" }
Runs the script through sh -c (Unix) or cmd /C (Windows) in cwd and returns
exit code plus captured output. cwd accepts ~. A cwd that does not exist is a
500 with { "error": ... }. Same body as the run_setup_script command.
Remove Worktree
DELETE /worktrees/:workspaceId?repoPath=/path&deleteBranch=true
Query parameters:
repoPath(required) – base repository pathdeleteBranch(optional, defaulttrue, orfalsewhenforce=true) – whentrue, also requests deletion of the local git branchforce(optional, defaultfalse) – whentrue, permits discarding dirty linked-worktree files but does not bypass branch proof or a lockoverrideLock(optional, defaultfalse) – explicit authorization to override a locked worktree during removalexpectedFingerprint(required withforce=truefor an existing checkout) – lifecycle fingerprint shown at force confirmation; removal refuses if checkout status, HEAD, or submodule refs changedpermanentDelete(optional, defaultfalse) – explicitly deletes rather than recycling a clean finished checkout; requiresdeleteBranch=true, clean and integrated state and no live sessions, and rejects force or lock overrides. Safety is checked again at removal.confirmMissingCheckout(required withforce=truefor a missing registered checkout) – confirms the lifecycle result without inventing a fingerprint; removal refuses if the checkout reappears
The path segment is the opaque workspace id from GET /worktrees/paths, not a branch name.
Returns { "ok": true, "branch_delete_warning": null, "removal_rule": "ancestry" }
on full success. removal_rule names the rule that allowed removal:
in_sync, ancestry, patch_equivalence, kept_branch, or force.
A non-force request requires a clean worktree and submodules with no Git
operation in progress, even when deleteBranch=false. A populated submodule
requires one git worktree remove --force after a fresh clean-state check.
Initialized submodule refs are preserved in the main module repository; an
uninitialized submodule without Git state does not block removal. A clean
branch whose commits were squash- or rebase-merged can use
patch_equivalence when git cherry finds no unique patches. Merge commits
are refused because git cherry does not compare their resolution changes. When
deleteBranch=true and the branch fails proof or moves after the preflight,
the compare-and-delete operation keeps the branch and the request
still succeeds with branch_delete_warning set so clients can report the
partial outcome.
Push Notification Endpoints
Get VAPID Public Key
GET /api/push/vapid-key
Returns the VAPID public key for PushManager.subscribe(). No authentication required.
Response: { "publicKey": "<base64url>" }
Returns 404 if push is not enabled.
Subscribe
POST /api/push/subscribe
Content-Type: application/json
{ "endpoint": "https://...", "keys": { "p256dh": "...", "auth": "..." } }
Register a push subscription. Idempotent (same endpoint updates keys).
The endpoint must use HTTPS, and its host must match a built-in push service
or an owner-added provider in services.push.added_providers, exactly or as a
subdomain. Otherwise the route returns 400 and stores nothing. The request body
cannot add a provider: unknown fields are ignored. The browser’s
PushManager.subscribe() chooses the endpoint, but the backend receives only
JSON from a local or authenticated caller and cannot prove that a browser made
it. The provider list, not the request, decides the outbound destination.
Question and completion pushes are sent when the desktop window is unfocused or,
on macOS, HID input has been idle for at least 120 seconds. The idle threshold
also covers a focused window left in front when Boss walks away. Other platforms
use focus when HID idle time is unavailable. A committed progress type=blocked
report supplies the question text to the same session event and 30-second push
limit as a parsed question. Empty blocked text is rejected by Progress validation.
Unsubscribe
DELETE /api/push/subscribe
Content-Type: application/json
{ "endpoint": "https://..." }
Remove a push subscription by endpoint.
Test Push Delivery
POST /api/push/test
Content-Type: application/json
{}
Returns { "sent": 1, "failed": 0, "stale_removed": 0 }, where sent counts
push-service acceptance, not display on the phone. HTTP 404 means no saved
subscription. HTTP 503 with sent: 0 means push is disabled or the private
VAPID key is unavailable. A 410 Gone response removes the stale subscription
and increments stale_removed; Boss must re-subscribe from the phone PWA.
ACP (ego)
Every acp_* Tauri command has a route here, with the same request field
names, the same response body, and the same error body — an AcpClientError
serialized whole (code, message, connectionId, sessionId, operation,
retryable). The HTTP status is a translation of code, never a second
opinion about it:
code | Status |
|---|---|
invalid_input | 400 |
not_found | 404 |
capability_unavailable | 501 — the agent never advertised it; the caller did nothing wrong |
transport_closed, stream_gap | 410 — what the URL names is genuinely gone |
unsupported_protocol, initialization_failed, agent_error | 502 |
protocol_violation | 502 — the agent denied a method it advertised; the connection is now failed |
POST /acp/connections {root, env?} -> AcpConnectionSnapshot
GET /acp/connections/{connection_id} -> AcpConnectionSnapshot
DELETE /acp/connections/{connection_id} -> AcpConnectionSettlement
POST /acp/connections/{connection_id}/kill -> AcpConnectionSettlement
POST /acp/connections/{connection_id}/reconnect {root} -> AcpConnectionSnapshot
GET /acp/connections/{connection_id}/sessions?cwd=&cursor= -> ListSessionsResponse
POST /acp/connections/{connection_id}/sessions {authority} -> AcpAttachmentSnapshot
POST /acp/connections/{cid}/sessions/{session_id}/load {authority} -> AcpAttachmentSnapshot
POST /acp/connections/{cid}/sessions/{session_id}/resume {authority} -> AcpAttachmentSnapshot
POST /acp/connections/{cid}/sessions/{session_id}/fork {authority} -> AcpAttachmentSnapshot
DELETE /acp/connections/{cid}/sessions/{session_id} -> null
POST /acp/connections/{cid}/sessions/{session_id}/close -> null
POST /acp/connections/{cid}/sessions/{session_id}/viewed-repo {viewedRepo: string|null} -> null (live speech context; no prompt)
POST /acp/connections/{cid}/sessions/{session_id}/prompt {prompt:[ContentBlock], viewedRepo?} -> AcpTurnId
POST /acp/connections/{cid}/sessions/{session_id}/cancel -> null
DELETE /acp/connections/{cid}/sessions/{session_id}/queue/{turn_id} -> null
POST /acp/connections/{cid}/sessions/{session_id}/queue/{turn_id}/recall -> string (full text, text-only prompts; refusal leaves queue unchanged)
POST /acp/connections/{cid}/sessions/{session_id}/config {configId, value} -> [SessionConfigOption]
POST /acp/connections/{cid}/sessions/{session_id}/pause {requestId} -> EgoHoldResponse
POST /acp/connections/{cid}/sessions/{session_id}/resume-turn {requestId} -> EgoHoldResponse
POST /acp/connections/{cid}/sessions/{session_id}/compact {requestId} -> EgoCompactResponse
GET /acp/connections/{connection_id}/interactions -> [AcpPendingInteraction]
GET /acp/connections/{connection_id}/events?after=&limit=&maxBytes= -> AcpEventPage
POST /acp/connections/{cid}/permissions/{request_id}/response {outcome} -> AcpInteractionSettlement
POST /acp/connections/{cid}/elicitations/{request_id}/response {action} -> AcpInteractionSettlement
POST /acp/one-shot {root, prompt} -> EgoTurn
POST /acp/one-shot/prepare -> String
POST /acp/one-shot/{request_id}/cancel -> bool
POST /acp/story-draft {project, request, requestId} -> StoryDraft
The ACP session prompt route accepts a buffered JSON body large enough for the shared 10 MiB image draft cap after base64 encoding, plus 64 KiB for JSON and text. Other JSON routes retain the 2 MiB default body limit.
POST /acp/connections, .../reconnect and POST /acp/one-shot are the three
that launch a process, and they are the three that take the
loopback-or-authenticated guard. The executable is never in the body: it comes
from the ego_executable setting.
Connect accepts an optional env object of string names and values. Overrides
apply only to the new child, never the host or another launch. Host-issued
TUIC_SESSION takes precedence. A supplied map, including an empty map, is
rejected with disconnect-first guidance if the root already has a live peer;
omitting env adopts that peer as before. Reconnect starts without the previous
overrides. Values are not stored in connection state, returned by read endpoints,
or included in request diagnostics. The host does not censor agent-generated
content if an agent itself prints a value.
prompt returns an ID immediately. When the session already has a turn, the
host queues the prompt and sends it only after the current ACP response leaves
the session idle; a paused session keeps its queue until resume succeeds. It
never puts two prompts in flight on that session. Each attachment snapshot has
queuedPrompts: [{turnId, summary}], and promptQueueChanged replaces that
list on both streams. A promptSent event records the user-visible text when
ego actually receives the prompt. Image data stays in the actor until dispatch,
not in queue snapshots or journal events. An accepted prompt that later fails
publishes turnFailed {message, state} on the ACP stream with its session and
turn in the frame. Either transport can remove a queued
ID with the DELETE route; cancel stops the active turn for every view.
One-shot (POST /acp/one-shot)
One unattended ego turn for a Smart Prompt in api mode. It takes no connection
id because it owns the whole lifetime — launch, one turn, shutdown — so it can
neither be handed a connection the AI Chat panel is using nor leave one behind.
The session is opened with no MCP server, so ego cannot reach TUICommander’s terminals or repositories from it, and every permission request and elicitation is refused the moment it arrives: there is no seat for anyone to answer from, and a question nobody answers is a turn that never ends.
{ "text": "the answer, trimmed", "stopReason": "end_turn", "declined": 0 }
declined counts the questions refused. It is the only way to tell “ego had
nothing to say” from “ego wanted a tool this mode cannot grant”.
Two budgets, both server-side and neither a parameter — a timeout a request body
could choose is a way to pin an ego process for as long as the sender likes. The
launch (initialize) gets 60s and the turn itself gets 240s, so the whole call
is bounded by 300s and fits inside the router’s 301s REQUEST_TIMEOUT with the
same one-second margin the confirm handler keeps. It has to: the outer layer
answers a bare 408, while these two answer a sentence naming what ran out.
The work is not the caller’s to cancel. The handler runs the turn on its own task and awaits the result, so a request that is dropped — by that outer timeout, or by a browser that navigates away — abandons the answer and not the turn: ego is still shut down and the connection still unregistered. Before #804-2ec8 the drop skipped the shutdown, and nothing else would ever have done it.
Stream (WebSocket)
GET /acp/connections/{connection_id}/stream?after={sequence} (WebSocket)
The browser half of acp_subscribe. Frames are {"kind":"event",...},
{"kind":"gap",...} or {"kind":"end"} — byte-identical to what the desktop
Channel carries. after is the first sequence wanted; 0 means everything the
journal still holds. A cursor the journal has dropped is refused before the
upgrade, with a 410 stream_gap error body, rather than by opening a socket
and closing it.
A gap is terminal: the missing frames exist nowhere in this client, and a
stream that silently resumed past them would render a turn with a hole in it.
Recovery is a fresh connection and session/load.
The server reads the next frame only after the socket accepted the previous
one. A client that stops reading costs TUIC no more than the connection’s
1024-event journal: a reader that falls behind the 256-event live buffer but
stays inside the journal resumes from it, in order and without a gap. Only a
reader that falls behind the journal gets the terminal gap (stream_gap),
never an unbounded queue.
Event page (bounded read)
GET /acp/connections/{connection_id}/events?after={sequence}&limit={n}&maxBytes={n}
-> {events: [AcpEventEnvelope], next, latest}
The same journal as the stream, for a reader that does not want a socket.
after has the stream’s meaning (first sequence wanted, 0 for everything
held), and a dropped cursor is the same 410 stream_gap. limit defaults to
256 and is capped at 1024 events; maxBytes (serialized event JSON) defaults to
1 MiB and is capped at 4 MiB. The first event is always returned, however large,
so the cursor always moves. Pass next back as after to read on; next > latest means the page reached the newest event held when it was taken.
This is deliberately not on /events: one turn emits more frames per second
than the 256-entry SSE broadcast can carry without lagging every other
subscriber. /events carries only the low-frequency acp-notice wake signal
(ready, settled, interaction_pending, interaction_settled, card), whose
payload names the connection, generation, sequence and — when it has one — the
session and request it is about.
ego Command Line (mcp_http/ego_routes.rs)
EgoProviders from /ego/providers and /ego/providers/model can include an optional diagnostic string. Health failures do not turn successful config/model reads into HTTP errors; valid doctor exit-1 JSON is still consumed. Without usable credential evidence, provider credentials are unknown.
The browser half of the dedicated ego configuration commands — what the Settings →
AI Chat page reads and writes. Same field names, same response body, same error
body: an EgoCliError serialized whole (code, message, command, stdout,
stderr, exitCode).
GET /ego/providers[?refresh=true] -> EgoProviders
POST /ego/providers/model {model} -> EgoProviders
GET /ego/perimeter -> PerimeterView
POST /ego/perimeter/roots {roots:{rootDir,rootAccess,readAllowlist,writableDirs}} -> PerimeterView
POST /ego/perimeter/network {enabled} -> PerimeterView
All routes take the loopback-or-authenticated guard, which is stricter than
/acp/*, where only connect and reconnect do. The difference is deliberate:
every route here runs a process, and the write one changes a configuration file
that decides which model a later run uses. Neither is a read of state TUIC
already holds.
The executable is never in the request. It comes from the ego_executable
setting, captured with the configured ego_profile and ai_chat_workspace per operation. Model and perimeter config commands select that profile explicitly, run in that workspace, and clear ambient EGO_PROFILE. The profile flag is omitted for user-base edits. Existing ACP sessions are not modified. Only model, roots and network are writable keys, each through its own
route rather than a key/value pair, so no body can reach sandbox or
permissions.judge.
The status is a translation of code, never a second opinion about it:
code | Status |
|---|---|
notConfigured | 409 — no ego executable is set; nothing was run |
invalidInput | 400 — the model id, root paths or workspace were refused before ego was started |
launchFailed | 424 — a binary is named and could not be started |
commandFailed, unreadableOutput | 502 — ego ran and failed, or printed something unreadable |
Tauri-Only Commands (No HTTP Route)
The following commands are accessible only via the Tauri invoke() bridge in the desktop app. They have no HTTP endpoint.
| Command | Module | Description |
|---|---|---|
get_claude_usage_api | claude_usage.rs | Fetch rate-limit usage from Anthropic OAuth API |
get_claude_usage_timeline | claude_usage.rs | Get hourly token usage timeline from session transcripts |
get_claude_session_stats | claude_usage.rs | Scan session transcripts for aggregated token/session stats |
get_claude_project_list | claude_usage.rs | List Claude project slugs with session counts |
plugin_watch_path | plugin_fs.rs | Start watching path for changes (change events need AppHandle/WS) |
plugin_unwatch | plugin_fs.rs | Stop watching a path |
plugin_read_credential | plugin_credentials.rs | Read credential from system store |
fetch_plugin_registry | registry.rs | Fetch remote plugin registry index |
install_plugin_from_zip | plugins.rs | Install plugin from local ZIP file |
install_plugin_from_url | plugins.rs | Install plugin from HTTPS URL |
uninstall_plugin | plugins.rs | Remove a plugin and all its files |
get_agent_mcp_status | agent_mcp.rs | Check MCP config status for an agent |
install_agent_mcp | agent_mcp.rs | Install TUICommander MCP entry in agent config |
remove_agent_mcp | agent_mcp.rs | Remove TUICommander MCP entry from agent config |
Private secret entry
Generic form metadata includes an absolute mobile_url when Remote Access has
an address. Otherwise mobile_url is null and optional mobile_unavailable
explains disabled remote access or missing address discovery. Native-only
account forms expose neither a phone URL nor phone setup guidance. The URL
contains the existing one-use nonce, never a pairing session token.
GET /secrets/forms/{nonce}returns only the pending schema, argv and entry capability; no stored values. A guessed or expired nonce returns 404.POST /secrets/forms/submitaccepts{nonce,status,values,template}. Status isstored,approvedordeclined; values must exactly match requested non-SSO fields. Approval accepts no values; decline accepts neither values nor a template. A valid submit consumes the nonce and returns names/status. Invalid or replayed submissions return 400 without echoing values.
Authenticated HTTP call with secret action=run
run takes names, argv, cwd and an optional reason; any other field is
refused with Invalid secret command (field ...). The value reaches the child
only through its environment, so the program must read it from there. curl 8.3+
does this with --variable %NAME and --expand-header:
{"action":"run","names":["GITEA_TOKEN"],"cwd":"/path/to/repo","reason":"Read the Gitea account",
"argv":["curl","--silent","--show-error","--fail","--max-time","20",
"--variable","%GITEA_TOKEN","--expand-header","Authorization: token {{GITEA_TOKEN}}",
"http://gitea.straus.local/api/v1/user"]}
Output masking is unchanged. A shell, env, or an interpreter evaluation flag
is still refused.
The native private-window identity is the only bootstrap authority. There is no
public endpoint listing forms or issuing their nonces. Open the entry path
shown in that window on your trusted server address; it uses the existing
application origin, authentication and transport. This feature does not enforce
TLS or origin isolation. Responses carry
Cache-Control: no-store, Referrer-Policy: no-referrer and frame denial.
Remote peer mail
GET /mcp/peer?connection_id=<configured-id>&token=<daemon-token> upgrades to
the desktop-initiated duplex peer-mail WebSocket. A real daemon token is required even
on loopback. One hub is admitted per daemon. JSON frames use kind:call with
id, sender, arguments and optional message_id, or kind:reply with
id and result. Calls allow register/list_peers/send/inbox/wait; daemon-to-hub
calls allow send/list_peers. Sender host is bound to the authenticated connection.
Frames and outstanding requests are bounded; heartbeat loss closes the link.
GET /sessions/{id}/output?format=mcp|mcp_raw returns the native MCP output object,
including exited, cursor and truncation fields. It accepts limit, from_line
and since_cursor, plus from_byte for raw source-byte pages. Follow
next_cursor while has_more is true; continuation names the next native
request. Tail reads name how to fetch older output. oldest_offset and
missed_count identify eviction gaps; evicted data cannot be recovered. Explicit
raw pages mask secrets before slicing and keep original-byte cursor positions.
POST /sessions/{id}/submit also accepts timeout_ms.
These are the configured remote desktop MCP adapters, sharing native backend behavior.
Peer handshakes serialize per configured connection, so a mute daemon cannot hold mail calls to another host behind its network deadline. Session targets reject empty ids/prefixes before owner selection. Forwarded notice deduplication survives inbox reads: it retains fingerprints of the last 100 forwarded ids per sender and registered recipient, without retaining message bodies. The cache holds at most 65,536 ids globally and 1,024 per remote host. A host quota rejection names the host; one host cannot consume every other host’s replay budget. Full 100-id windows can still rotate in place, and retained replays still deduplicate at either cap.
There is no time expiry: the sender’s outbox lives until acknowledgement. Only under global or host quota pressure, the cache reclaims all windows of the least-recently-active sender with no live peer shadow (within the pressured host when its quota is full). Live sender windows are never reclaimed. Sender retirement alone preserves dedupe; recipient unregister frees only that recipient’s records and quota. Accepted risk: a departed sender that reconnects after pressure evicted its history can deliver one duplicate. Disconnect retires that host’s existing shadows synchronously, independently of a pending handshake or a later reconnect generation. This is a bounded replay horizon, not unbounded or restart-persistent exactly-once delivery.
POST /stories/action answers a mistake the user can fix with HTTP 422 and { "error": "..." }: add_plan_source for a missing plan file (plan document not found: <path>) and submit_review with unchecked criteria (criteria are incomplete: unchecked indexes N). Other failures stay HTTP 500.
Workflow definition and run APIs are actorless and share the same services across transports. Story transition actors track provenance and never restrict actions. Desktop IPC and valid HTTP credentials record Human; sessionless local requests record LocalApi; managed story requests record their session. Missing ConnectInfo on Unix sockets and in-process services means local/unknown caller metadata, not HTTP 500. Local token exchange is accepted; state, revision, project and integration checks remain enforced.
Stored terminal marker coordinates
OSC 133 event line and hook-generated UserInput.line are eviction-stable all-time rows, identical to IPC. Scroll-to, line reads and search results keep retained-grid coordinates. Convert stored marker rows using the current grid frame historyBase.
Telegram Settings
GET /config/telegram mirrors telegram_settings. Its pairing_pending flag indicates whether the one-use pairing file still exists; the frontend clears its local pairing hint when this is false. recent_events is a memory-only newest-first list of at most 20 events in this process: {id,time,direction,kind,outcome,preview}. Time is epoch milliseconds; previews are redacted before truncation to 60 Unicode characters. This list is not persisted or shared with another process. PUT /config/telegram accepts { "change": { "action": "..." } } and mirrors telegram_setup, including token replacement/check, one-use pairing, typed chat IDs and enable/target updates. Both routes require local access or the existing authenticated remote session. The read response contains only token_set, never the token. Chat IDs are decimal strings. polling_owner is this_app, tuic_remote, desktop, another_process (an older owner), or null when disconnected; the name is relative to the process serving the snapshot.
The ACP session fork route accepts optional atMessageId beside authority. It is forwarded as _meta.ego.atMessageId only when ego advertises sessionCapabilities.fork._meta.ego.atMessage; unsupported agents are refused. For a busy source without an explicit cutoff, the actor selects the last successful completed turn observed on that connection. No verified cutoff returns an error without sending a tip fork. Failed and cancelled turns do not replace the saved boundary. Ego validates every explicit cutoff against durable successful-turn history.
The host ACP session list gathers all ego pages before ordering ancestry. Each row retains _meta.ego.lineage and adds _meta.tuicommander.lineageDepth; placeholder rows for deleted parents add _meta.tuicommander.deleted=true. The response has no continuation cursor after collecting the pages.
Memory diagnostics
GET /diagnostics/memory performs payload accounting and the native large-malloc-block census on demand. The watchdog logs only cheap allocator counters and structure counts at footprint thresholds; it does not walk payloads or malloc zones.
accounted_bytes sums the measured maps rows. malloc_large_blocks counts all large allocator blocks, including map-owned blocks. Its may_overlap_accounted_bytes: true field warns that its bytes must never be added to accounted_bytes as attributed memory. Model holders remain separate from heap accounting.
Launch instruction receipts
GET /sessions/{id}/prompt-receipt mirrors get_prompt_receipt. Missing sessions return 404. The response is {sections, captureLimited}. Each section has label, source, bytes (original UTF-8 payload size, or null when unknown), text (redacted bounded preview), status (sent, queued, served, file_snapshot, or not_observable), truncated, count (observations folded into the row; one served row per label keeps the newest body), firstSeenMs and lastSeenMs (unix milliseconds). The endpoint reads live PTY/MCP metadata and never rebuilds text from settings. Capture/retention limits and unobservable cases are documented in AI Agents.
Conversation-specific AI Chat launch
POST /acp/chat/open accepts { "profile": "coordinator", "workspace": "/absolute/workspace", "executable": "/absolute/ego" }. All fields are optional for a new conversation; omitted values use global defaults. It returns { connection, sessionId, launch, replayed }, where launch contains the resolved executable, profile, workspace and durable peerId. Use the existing ACP session prompt and stream routes with the returned ids.
Reopen with { "sessionId": "<returned-session-id>" }; saved launch options cannot be replaced on reopen. This route requires localhost or authenticated access, like ACP connect. Each custom conversation owns a dedicated peer/process. Its options are persisted under ai_chat_launches without modifying the global settings.
Caller-bound worktree declaration
An agent that uses git -C or tools without changing shell cwd can declare an
existing linked worktree with:
session action=declare_worktree worktree_path=/absolute/path/to/worktree
The authenticated MCP binding identifies the caller’s live PTY. Omit
session_id; a foreign session target is rejected. The backend resolves the
repository from the immutable launch directory and discovers current worktrees
from Git. The main checkout, unknown paths and worktrees owned by another
repository are rejected before any configuration or placement changes. External
worktrees are discovered without recreating or deleting them.
The response and session-worktree-declared event use the worktree lifecycle
payload, with creator_session naming the caller and spawn_session=false.
Only that tab moves. Its real cwd, sibling tabs and an inactive selection stay
unchanged; an active caller’s selected workspace follows the same tab. Retrying
the same declaration is idempotent.
The stable TUIC_SESSION association is stored in the owning repository’s
declaredWorktrees map using the existing locked repository delta. Any saved
caller snapshot moves to the target workspace; sibling snapshots are preserved.
After a restart or WebView reconnect, HTTP GET /sessions and IPC
list_active_sessions return the declared worktree_path and worktree_branch
while cwd remains the actual shell directory. The frontend restores placement
from the persisted stable caller declaration across registered repositories,
independent of a changed cwd-derived repository, when the workspace id and checkout
path still match. Declaration does not acquire worktree cleanup ownership.
A concurrent repository edit can return a configuration conflict; retry the
declaration after refreshing rather than overwriting that edit.
The explicit placement remains authoritative over later shell cwd notifications
until another declaration changes it. The frontend retains the backend placement
in declaredWorktrees separately from the observed cwd during reconciliation.
Removing or replacing the matching checkout invalidates that placement.
Intentional request transport exception: declare_worktree is an MCP-only
action, callable over the existing HTTP POST /mcp route with a bound caller.
There is no Tauri command or COMMAND_TABLE entry: window IPC has no managed
agent caller binding. Its push event is dual-emitted over Tauri and /events SSE,
and session-list response fields are identical over IPC and HTTP. Schema and
serialization regressions cover these shared contracts.
Terminal title notifications
Raw, text and log /sessions/{id}/stream WebSockets carry OSC titles as
{"type":"title","title":"Claude Code"} and title resets with "title":"".
GET /events also carries event: pty-title with {session_id,title}. These are
presentation events, independent of activity pulses and semantic lifecycle.
Grid clients continue to receive binary rendering frames; terminal metadata
consumers use the separate session event subscription.
Automations
POST /automations/action accepts { "input": { "action": "list" } }.
Saved run configurations are validated against the same named-profile lookup used
by the runner. Names are case-insensitive; a bare agent type such as claude
is not a saved profile unless a profile has that name. Create, definition
updates and re-enabling reject an unresolved name with a repair hint listing
valid saved profiles. Existing list rows retain invalid definitions, but expose
run_config_error and return next_run_ms: null until repaired. A profile can
be removed after saving; launch checks it again and records a failed run.
Unknown agent-created runs offer an automation_run_unknown creator message
with run_id, session_id and last_error through the same owner channel.
Failed agent-created runs also offer an automation_run_failed creator inbox
message with run_id, definition_id, name and reason, even before spawn.
The durable owner notification channel deduplicates publication; acceptance
means inbox queued, not read. No creator means the existing bell/alert path.
Unknown /automations/* endpoints return HTTP 404 with a JSON error, rather
than the SPA frontend shell.
It is available on desktop, browser/PWA and headless hosts. The addressed backend
owns the definitions, history and execution; this route never forwards Run Now
to a different machine. It shares its input parser and Rust implementation with
automation_action IPC. Success is the JSON value below (no reply wrapper).
Static action-schema violations use HTTP 400 with the same invalid_arguments
repair payload as MCP, including bounded, value-masked violations and
effect=not_started. Both entry points use the advertised MCP input contract
before dispatch. Semantic application errors use HTTP 500 with
{ "error": "message" }; IPC rejects with the identical semantic message and
retains its string-error signature. Malformed HTTP JSON/envelopes use Axum
extraction errors.
| Action | Input fields besides action | Success |
|---|---|---|
| templates | None | Built-in recipe array with id, name, cron and prompt |
| template | template_id, repository, run_config, optional/null timezone | Fresh unsaved AutomationDefinition with enabled:false; omitted zone uses host local IANA zone |
list | None | Array of {definition,next_run_ms,last_status} |
get | id | Stored definition |
create | definition, optionally with in_secs instead of an absolute schedule | Stored definition, resolved timezone/local fire time and computed next_run_ms |
update | definition, optional id; or id,enabled | Stored definition |
pause, resume | id | {ok:true}; atomic enabled-only edit |
delete | id | {ok:true}; history retained |
run_now | id | Full persisted run, including status and reason |
profiles | None | Saved run profile names for the addressed backend, sorted by name |
list_runs | Optional id, limit (default 50, 1–100), offset (default 0), group_failures (default false) | Newest-first run snapshots, including deleted definitions. Grouping collapses failures with the same definition, repository, profile and reason before pagination; returns the newest representative plus failure_count. Other states remain separate. Individual ledger records and summaries do not change. stdout/stderr text is cut to its last 2048 bytes (truncated: true); run returns it whole. |
worktree_preview | Saved run id | {automation_id,run_id,repository,workspace,workspace_id,can_remove,reason,safety} |
cleanup_worktree | Saved run id | {removed:true,run_id,branch_delete_warning}; unsafe workspaces return an error |
summary | window: 24h or 7d | {total,by_status} over elapsed UTC windows |
preview | cron, optional/null timezone, count (default 4, 1–20) | {cron,timezone,occurrences} with UTC ISO timestamps |
preview_definition | definition, count (default 4, 1–20) | Preview plus once_local,completed; respects the durable cursor |
preset | preset: hourly/daily/weekdays/weekly cadence | {cron} |
Definitions use the snake_case storage model, including optional once_local.
Create accepts in_secs (positive integer elapsed seconds from the host UTC clock)
as an alternative to cron and once_local; combinations are rejected. Relative
creation stores the local time in the selected IANA zone and an exact UTC once_at
so a DST fold cannot move the occurrence. Preserve once_at for unchanged schedule
edits; clear it when changing the schedule. next_run_ms in create replies is
computed, not stored; update/preview ignore this read-only field.
HTTP/IPC callers without bound agent identity supply all normal definition fields.
Bound MCP callers can omit id, repository, workspace, enabled, grace_secs,
overlap and max_duration_secs. They must supply the actual saved run_config:
agent-type defaults are not proof of the caller’s account/model profile.
Generated bound creates are idempotent by caller plus original request; identical
retries return the first saved occurrence without resetting its delay. Supply a
new explicit id for a separate identical reminder. See the MCP guide for defaults.
Update replaces only the named definition and rejects a changed id; enabled-only
update preserves concurrent edits. Supplying both definition and enabled is
an error. Create ignores client creator provenance; update preserves it.
Presets use {kind,minute}, adding hour for daily/weekdays and hour,weekday
for weekly (Sunday 0 or 7). Blank create/definition-preview zones and omitted
cron-preview zones resolve to the backend’s local IANA zone.
Paused or consumed Once definitions have a null next_run_ms. List computes
future cron occurrences and the scheduler dispatches each due one. Run Now requires
the runtime owner, allows paused Once and cron definitions, bypasses prechecks and records
overlap/capacity refusals without queueing. No execution retry is introduced.
Automation runtime transitions are streamed on /events as
automation-run-changed, with payload { "run": <AutomationRun> }, identical
to the desktop event. This includes failure and needs-you changes. Final runs
retain bounded output; missed live events are reconciled from host state rather
than replaying or restarting execution.
Event run replies add nullable outcome: {decision, pr_url, comment_url, failure_reason, publication_intent}. The intent has {repository, head, base, issue_number}. This is identical through IPC and HTTP, including run,
list_runs and automation-run-changed (notice: false on publication updates).
Execution completed is distinct from outcome published,
publication_pending, publication_unknown, publication_failed or
publication_refused. skipped_filtered and skipped_duplicate history rows
retain refusal reasons; repeated event/reason observations coalesce in one row.
The empty default intake evaluates nothing. No comment publication is added.
Automation action run accepts {id: "<run id>"} and returns the canonical saved AutomationRun independent of definition lifetime. The live automation-run-changed payload adds notice: boolean; only true invites a bell item. False and history reads never notify.
Design Mode extension pilot
POST /design-mode/extension is available on the existing local IPC HTTP server
(and the existing authenticated remote transport). The native host uses this
route; it introduces no TCP listener. Requests carry id, action, version
(2.x) and repoPath. Replies are {id, ok, result} or {id, ok:false, error}.
heartbeat records extension liveness and returns {armed, reloadSeq, navigate: {seq, url?}, backendId?}. The navigation sequence is included without a pending URL. backendId identifies the manager lifetime so the extension resets its navigation acknowledgement after a backend restart, even when a command arrives before an idle beat. It runs every five seconds; armed modes expire after 60 seconds without a beat, or 600 seconds from Start when no beat arrived. MCP ui action=design_reload repo_path=<repoPath> increments the sequence; unchanged replies do not repeat a successful reload.
hello checks the major version. pick accepts raw DOM extraction and returns
bounded, redacted, fenced evidence. Non-HTTP(S) page URLs are rejected. Page data
cannot invoke privileged operations: the worker accepts those only from its panel.
The framed native host maps list_agents to the existing GET /sessions route,
then applies the shared Rust repository recipient rule. hello checks /health
against the process identity recorded at install. Other v2 operations use the
extension route. An older running backend returns a visible HTTP 404 plus the
exact endpoint and a restart instruction; the host does not guess another socket.
Automation precheck context (#1631-45bf): definitions can opt in with
precheck.inject_output: true (default false). Proceeding checks prefix the
literal prompt with delimited, escaped untrusted stdout capped at 16 KiB;
truncation is marked and stderr is excluded. Empty output and manual bypasses
inject nothing. The run ledger records precheck_context: {injected, bytes} for
the prepared launch prompt, counting escaped stdout bytes before framing/marker.
The MCP automations tool and tuic automations '<action JSON>' use the same
action table, parser and result values as this endpoint. MCP receives the action
object directly; HTTP wraps it in input. MCP creation additionally requires a
bound caller identity and records it in created_by_session. CLI sends the
unchanged action through HTTP-over-IPC MCP, prints JSON on success and reports
the same backend error text on stderr with exit 1.
PR line reviews
Desktop command arguments and HTTP bodies use the same camelCase fields.
| Method | Route | Arguments |
|---|---|---|
| GET | /repo/pr-line-threads | repoPath, prNumber, optional after |
| GET | /repo/pr-open-threads | repoPath, prNumber — returns the get_pr_open_threads string |
| GET | /repo/pr-thread-comments | repoPath, threadId, optional after |
| POST | /repo/pr-thread-resolved | {repoPath, threadId, resolved} |
| POST | /repo/pr-thread-reply | {repoPath, threadId, body} |
| POST | /repo/pr-draft-review | {repoPath, prNumber, draft:{headSha, body, event, comments}} |
Draft submission rejects a moved reviewed head and pins REST commit_id. Thread and comment connections expose pagination; outdated threads retain null current lines. Thread shapes match get_pr_line_threads: comment authors carry bot, and each thread carries a nullable parsed finding (untrusted bot text).
PR actions
| Method | Route | Arguments |
|---|---|---|
| GET | /repo/pr-action-state | repoPath, prNumber |
| POST | /repo/pr-auto-merge | {repoPath, prNumber, enabled, mergeMethod?, expectedHeadSha?} |
| POST | /repo/pr-merge-queue | {repoPath, prNumber, enqueued, expectedHeadSha?} |
| POST | /repo/pr-merge-or-enqueue | {repoPath, prNumber, mergeMethod, expectedHeadSha} |
| POST | /repo/pr-rerun-failed | {repoPath, runId} |
The routes share desktop command results. Enabling auto-merge and queue entry require the reviewed head. Merge policy read failures stop writes. The legacy /repo/post-pr-review and pinned /repo/pr-draft-review reject empty REQUEST_CHANGES bodies.
Account actions
POST /accounts/action accepts the tagged core account action directly, without an IPC request envelope. It is registered identically on desktop and headless routers with the loopback-or-authenticated route guard. TCP listeners additionally require transport authentication, including loopback requests. Reads return metadata and credential presence only; no action returns a token. List/add/test/remove, site operations and write-only token replacement/clear share the Rust account owner service. See the account action table. Frontend mapping lives in src/transport/commandTable.ts.
Account credential entry
POST /accounts/secret-form accepts the same metadata-only request as
account_secret_form (see the Tauri command reference). It requires local or
authenticated access and a desktop host; a headless host returns an error. The
request waits for native entry and returns status only, with Cache-Control: no-store. It never returns a nonce or credential. Account forms cannot be read
through GET /secrets/forms/{nonce} or submitted through
POST /secrets/forms/submit, even with the correct nonce. Ordinary secret forms
retain their existing mobile capability support.
History-anchored viewport scrolling
POST /sessions/:id/terminal/scroll-to-anchor accepts { "anchor": number | null } and returns { "ok": true }. The anchor is an all-time row index including evicted rows, matching grid-frame historyBase + historySize - displayOffset. Null follows the tail; a trimmed anchor clamps to the oldest retained row. The request is coalesced with offset requests and applied under the ticker VT lock, so intervening output cannot move the target.
Codex session lifecycle snapshots (GET /sessions, session-state-changed SSE,
and the equivalent desktop IPC) include optional
codex_binding: { "session_id": "<native thread UUID>" } only while the native
hook evidence passes live PID, rollout id and cwd validation. Omission retracts
exactness; clients must not substitute a heuristic discovery ID. The existing
GET /sessions/:id/chat-view route repeats validation on every Codex read and
returns not_bound when evidence is missing or stale. Native hook binding also
applies to PTYs created through the HTTP agent route, MCP agent spawn and generic
POST /sessions: their readers use the live identity inherited by the child, not
an absent transport caller identity.
Desktop close notification
close-dialog SSE carries {kind: "ask" | "confirm_quit", sessions: number, background_available: boolean}, identical to the desktop event. Browser clients do not render host close prompts. Native lifecycle commands request_quit and resolve_close are deliberately desktop-only and have no HTTP route.
Tasks start-work brief
POST /tasks/start-work-prompt accepts { "repoPath": "/repo", "input": { "key": "TASK-1", "url": null, "title": "Title", "body": "Description" } }
and returns a JSON string. It reads .tuic-start-work.md with repository
containment and UTF-8/size guards, substitutes sanitized item fields once, or
uses key/title/body when absent. Template read failures return an error. Its IPC
twin is build_start_work_prompt; the host wraps and caps the returned brief
at delivery.
Tasks provider bridge
POST /work-items/provider-bridge is the HTTP twin of work_item_provider_bridge({input}). Body: {action:"claim", requestId} returns the typed provider request or null when already claimed/expired; {action:"complete", requestId, value} completes a claimed request and returns null. The route requires local or authenticated access. Clients subscribe to work-item-provider-request on /events, whose payload contains request_id and request; only a client with the target provider loaded should claim it. Rust alone creates pending requests after MCP validation and write opt-in. Replies are validated as Tasks DTOs before entering model output.
project_work_items / POST /tasks/project: accepts {items, fields, query} using the work-item DTOs. Returns WorkItemGroupedPage with the filtered unique count, no cursor and one unnamed group when no grouping is selected. Pure Rust projection, maximum 1,000 collected items, no provider access or persisted state.
Settings policy foundation (#1786-9cbd): the existing
POST /mcp/confirm-response also answers backend-built settings proposals shown
by mcp-confirm. Only the first answer settles a question. A settings grant is
bound to its origin connection and original target/revision/content, lasts at
most 300 seconds from proposal creation, and cannot be replayed. There is no new
settings HTTP endpoint in this step; replacement settings transport publication
remains separate.
Open desktop Markdown files
| Method | Path | Request | Response |
|---|---|---|---|
| GET | /repo/open-markdown-tabs | cwd query: session directory | Array of {id,title,relative_path,absolute_path,fs_root,opener_tuic_session?} |
| PUT | /config/open-markdown-tabs | {tabs:[{id,repoPath,filePath,fsRoot?,openerTuicSession?}]} | null |
GET uses the existing remote authentication and returns 403 for unregistered
directories. Repository/workspace ownership is computed by Rust. Only file tabs
inside registered roots with a .md suffix are listed; no contents are included.
PUT is the desktop publication twin and refuses non-loopback clients, including
authenticated remote clients. The in-memory list resets with the backend.
open-markdown-tabs-changed has an empty payload and is emitted on IPC and SSE;
consumers reread after this event or SSE resynchronization.
Immediate Design Mode browser commands
Design Mode captures accept per-call format (webp by default or png),
quality (WebP 1–100, default 25) and optional max_long_edge (positive pixels,
downsize only). Use WebP for text/layout, quality 50+ for small glyphs/icons, or
PNG for pixel-exact detail. Responses report path, format, quality (null for PNG),
bytes and media type; MCP sends a correctly typed image block. Token cost follows
pixel dimensions, not file format or bytes (Claude: about 1,296 tokens per
megapixel, capped at 1,568 standard / 4,784 high-res). HTTP/IPC use the same
screenshot fields in args; no user setting is added.
POST /design-mode/start returns armed only after the extension acknowledges the requested page through a correlated internal ready command. Failed acknowledgment returns browser_not_ready and closes the owned launch. Stop closes and reaps that dedicated launch. The extension starts receiving at worker boot; a sidebar gesture is not required to choose the initial reviewed tab. Native disconnect closes the command queue, so later requests return browser_disconnected immediately instead of timing out. Eval needs the owner’s sidebar consent for the armed session and the page host; without it, eval returns eval_not_granted: grant needed: click Allow agents on this host. Every command on a remote host needs the same consent and otherwise returns host_denied. Local reload, errors, navigation and screenshots need no consent. Chrome’s capture permission remains a Chrome prerequisite.
POST /design-mode/command accepts {repoPath, action, args}. Actions are
navigate (args.url), reload, screenshot, errors, and eval (args.script,
optional args.result_offset). Command arguments are bounded at 256 KiB. Eval returns
{evidence, total_bytes, next_offset}: the redacted JSON value is paged in 16 KiB
UTF-8 pages, and next_offset is null on the last page. Pass next_offset as
result_offset to read the next page; each page evaluates the script again, so page
only deterministic expressions. Screenshots that exceed 512 KiB are downscaled in the
browser until they fit, and the response reports downscaled.
It shares the design_mode_browser_command IPC implementation. The extension’s
existing native port receives commands over a pending native-host IPC receive;
replies match UUIDs and expire after ten seconds. Errors include not_armed,
command_timeout, host_denied, eval_not_granted and tab_not_visible.
Legacy /design-mode/navigate and /design-mode/reload keep the restart-safe
heartbeat sequence contract. Immediate commands do not change those sequences.
Tasks comment comparison
compare_work_item_comments / POST /tasks/compare-comments accepts {detail, previous, enabled, followed} and returns {snapshot, notify}. detail is the unchanged WorkItemDetail; previous is null or {latest, ids, count} (latest is a UTC timestamp in milliseconds). The pure Rust comparison has no provider IO or persistence. First observations, disabled/unfollowed inputs, older comments and edits are silent. GitHub full comment counts cover normal comments outside the first page. Desktop and HTTP use the same implementation.
Shared session wake
POST /sessions/wake accepts {tuicSession} and returns {ok:true,session_id}. It has the same local-or-authenticated guard as suspended-session actions and maps to IPC resume_session. An already-live target returns its current PTY. A failure returns HTTP 400 with {error} and retains the record. MCP session list/status expose retained sessions with state:"hibernated"; submit resumes and returns status:"resuming" after accepting input into the existing ready-window queue. Mail wake failure reports resume_error without deleting inbox mail.
session-created carries optional tuic_session on IPC and SSE so a backend wake reattaches the existing suspended tab. Hibernated terminal aliases remain valid peer-mail addresses.
Account-scoped GitHub review and action ports
host.githubReviewThreads(account, reference, after) returns the core B6 review
thread page, including head SHA, bot authors and parsed findings.
host.githubPrAction(account, reference, request) calls core B7 policy.
Both require net:http and an on-disk manifest declaring providers: ["github"].
The reference must identify a GitHub pull request in the selected account. Core
loads that exact account credential, never a local repository default. Cross-account
references fail before credential lookup. No token is returned to the plugin.
Requests use action: state, auto_merge (enabled, optional mergeMethod,
expectedHeadSha), queue (enqueued, optional expectedHeadSha), merge
(mergeMethod, expectedHeadSha), rerun (runId), or review (draft with
headSha, body, event, comments). Existing core reviewed-head validation,
merge queue policy and shared request budgets apply unchanged. The desktop command
plugin_github_action and POST /api/plugins/{plugin_id}/github accept identical
{account, reference, request} payloads (IPC also supplies pluginId).
The GitHub Work runtime binds both ports when it registers each configured account.
No live write or desktop-load verification is implied by recorded-fixture tests.
Guarded automated agent input
POST /sessions/{id}/input-if-empty accepts { "text": "[noop]" } and returns a boolean. false means no input was sent because the agent is not ready, awaits input, has a tracked draft, or has queued commands. The backend serializes checks, split writes, and bookkeeping against raw user input. IPC equivalent: send_agent_input_if_empty.
Shared settings action (#1787-4778)
Both the desktop HTTP server and headless tuic-remote register this route through the same shared router. They also share GET /config and PUT /config, used by browser Settings hydration and refresh; reads retain the existing credential redaction. Headless upstream begin_login returns unavailable before resolving or contacting an upstream; bridge installation and opening agent config files remain desktop-only.
POST /settings/action accepts the Rust-generated settings envelope directly, identical to IPC settings_action request and MCP settings arguments. It requires local or authenticated access. Describe is bounded to 128 fields per page. Owner edits require explicit target and expectedRevision; structured errors contain no input values. The owner inventory is complete; the same gate rejects future unresolved gaps. Typed workflows use {action:"perform",target:{kind:"machine"},store,operation}. The store selects the Rust operation DTO: github_accounts, ego (also expectedRevision), upstreams, connections, circleci, telegram, and voice in dictation builds. Dynamic-choice describe/refresh uses target, store and paths; catalogue describe uses bounded filters instead.
Gated HTTP and IPC edits return confirmation_required with proposalId and do not write.
Confirmation applies only when a change adds authority: enabling or widening a listener, loosening authentication, replacing TLS material or weakening TLS, enabling the relay or changing its destination, adding or replacing an executable, launcher argument or stdio upstream command, and adding a tunnel forward or auto-connect. Narrowing, disabling, lowering a timeout and no-op edits apply directly. The owner’s own Settings window (the native settings_action command) applies every edit directly; HTTP, MCP and other native callers get the proposal flow. No request field can claim owner-window intent.
Replay the exact original edit with approval: "<proposalId>" and confirm: true.
The same request opens the existing all-client human confirmation dialog, waits for the
answer, and, only after approval, commits the exact edit under its original caller.
A decline, expiry, changed edit, caller mismatch or reused approval cannot commit.
HTTP proposal identity uses the source IP, not the ephemeral TCP port; every request
still requires local or authenticated access. MCP callers can continue to use
ui action=confirm proposalId=... followed by an exact replay with approval.
Tunnel forward lists, including empty replacements, require confirmation like tunnel ports.
POST /api/plugins/{plugin_id}/http accepts optional requestId (UUID). POST /api/plugins/{plugin_id}/http/cancel accepts { "requestId": "<UUID>" }; both use the shared IPC backend. Cancellation covers headers and body. Early cancellation markers expire after 60 seconds and the shared registry is capped at 4096 entries.
Audio choice availability (#1908-c327, #1909-0d24)
Existing input/output device enumeration returns the same device objects on success, including a successful empty array. Backend enumeration failure now returns an error rather than an empty array. Internal settings choice refresh reuses those owners; cache-only describe and typed voice asset actions are not new public routes in this change. The settings transport cutover remains separate.
GET /events carries pty-bell with {session_id}. Both session WebSocket formats carry {type:"bell"}. Bells originate in the PTY reader, independently of grid frame serialization or desktop visibility.
Terminal ego recovery snapshots appear as state.provider_recovery in session
snapshots and session-state-changed events: {phase, next_attempt_ms, attempt}.
POST /sessions/{id}/force-retry (IPC force_retry_provider_recovery_command)
returns null on success or HTTP 409 {error} on refusal. It shares MCP
force-retry validation and the input lock: non-empty composers are never overwritten.
The field is omitted when no recovery is active. MCP session action=force_retry
submits /retry once to a recovering ego PTY and returns {submitted:true, session_id} or an error; it requires a loopback or credential-verified caller.
Application log acknowledgements
POST /logs accepts { level, source, message, data_json?, audience? } and
returns HTTP 204 No Content after adding the entry to the backend log ring.
DELETE /logs also returns 204 after clearing the ring. The matching browser
RPCs (push_log, clear_logs) resolve without a JSON value. Data-returning RPCs
still reject empty bodies. GET /logs returns the log entries as JSON.
Mobile lifecycle diagnostics use the existing POST /logs route. A prior
abnormal document’s bounded trail uses source app, level warn, audience
diagnostic, and message Mobile previous document lifecycle trail. The client
keeps that report in per-tab session storage until an acknowledged upload. A
lost acknowledgement can cause a retry; this route does not provide durable
exactly-once delivery or persist the backend ring across an app restart.
Browser dictation also mirrors at most six content-free lifecycle debug records per take through POST /logs. Read them with GET /logs?source=dictation&level=debug&audience=diagnostic. Messages start with Browser dictation lifecycle:; data_json contains event, a per-take sequence, sessionId, takeId, recording/discarding flags and the first error code when applicable. Session ID is null for an unbound AI Chat draft. This uses the same bounded, best-effort backend ring, not a persistent event journal.
Telegram request streaming (1959-162a)
Telegram replies now use TUIC-driven receipt (👀), working (👨💻), waiting (🤔), answered (👍) and failed (👎) reactions. An ephemeral native draft shows Italian status lines or unapproved agent previews; it refreshes while work continues and the final reply replaces it. Acknowledgement of work requires inbox Read and a new recipient turn. PTY intent/activity and AI Chat assistant chunks share request correlation; finish remains authoritative after draft retirement. Telegram-mail-woken AI Chat turns automatically send their settled assistant text if finish has not answered. Queue and no-reply notices occur at ten minutes and sixty seconds after Read respectively. Restart keeps no request history. Phone rendering requires a live check after the backend restart.
Styled terminal log wrap boundaries
Rows returned by session format=log output and the format=log|text WebSocket include wrapped: boolean alongside spans and cols. True means the next row continues this logical line: concatenate span text verbatim, with no added space or newline. False means a hard line boundary. A finalized log row can wrap into the first current-screen row. Wrapped rows preserve real trailing spaces. MCP session text output applies these boundaries before redaction.
Settings change stream
GET /events publishes settings-changed with {section: string, generation: number, persisted: boolean, applied: boolean} after a durable settings-facade write. A persisted apply failure also emits a hint, with applied: false; its structured error carries the same generation. A refusal or failed persistence emits no hint. Successful reads expose the current generation, while owner revision remains the compare-and-swap token. The counter is process-local and resets after restart: clients must refetch their active settings snapshots after SSE connect, reconnect or lagged, not compare generations across process lifetimes. Values and credentials are never included in the event.
Frontend shortcut metadata publication
POST /settings/action and IPC settings_action accept {action:"publish_plugin_keybinding_actions",actions:["plugin:pluginId:commandId"]}. IDs are validated and bounded; the newest frontend publication replaces the process-local set. This is runtime metadata, not configuration persistence. It returns persisted=false/applied=true and does not emit settings-changed. Existing host-issued caller guards apply. Explicit keybinding choice refresh reads this set with built-in actions.
Settings startup and recovery
The published Settings startup sequence and GitHub/Ego owner contracts are documented in Settings startup workflows. Device-login status is not authentication success; owner revisions, confirmation proposals and persisted-but-unapplied outcomes require their distinct recovery paths. Do not substitute a legacy HTTP command for an action absent from the Settings schema.
CircleCI credential settings (#1991-bd88)
The machine-scoped circleci.token descriptor is write-only. Read
{action:"get",target:{kind:"machine"},store:"circleci",paths:["/token"]}
through MCP settings, IPC settings_action, or HTTP POST /settings/action.
Readback returns only stored.status and effective.status: set, unset, or
unavailable. It describes the stored TUIC token, not environment or CLI fallbacks.
Use {action:"perform",target:{kind:"machine"},store:"circleci",operation:{action:"set_token",token:"..."}}
or operation:{action:"clear_token"}. Both actions use the existing CircleCI
owner; replies contain only token presence. Clearing the stored token does not
remove CIRCLE_TOKEN or the CircleCI CLI configuration. The Git & GitHub page
continues to show the effective token source. No transport returns the token.
Durable managed-agent launch
POST /agents/launch (loopback or credential-verified caller) and IPC managed_agent_launch { request } use the same Rust transaction as MCP agent action=launch. Send:
{
"idempotency_key": "story-worker-1",
"parent_session_id": "<registered-peer-uuid>",
"name": "worker-1",
"keep_open": true,
"workspace": {"existing_path": "/absolute/checkout"},
"spawn": {"agent_type": "claude", "prompt": "Perform the task"}
}
For a new workspace use workspace: {repo_path, branch, base_ref?}. No fallback checkout is used after a refusal. spawn accepts the existing MCP spawn options; do not put cwd, name, keep_open, action, parent_session_id or idempotency_key inside it. These values belong to the transaction. Model, account and local brief policy remain caller-owned.
The receipt includes launch_id, reserved session_id, stage, status, live, prompt_delivery, ready, reason, workspace_path, warm_artifacts, and the original child spawn response when available. Read it with {launch_id} on the same endpoint, or repeat the identical creation request. Keys are scoped to the explicit parent identity. A changed request under the same key returns idempotency_conflict. Retain the key across connection loss; do not generate a new key to retry.
status is created, prompt_delivered, ready or blocked. prompt_delivery=delivered proves argv handoff or successful queued PTY submission, not model acceptance. ready additionally requires the native Ready-screen adapter and the shared idle/completed session projection. Terminal movement or silence alone is insufficient. Deferred prompt timeouts (including parentless automation/workflow children after the 30-second budget), questions and a refused turn (agent_state=error, with its message in last_error and reason) report blocked; the initial prompt stays queued and a retry never re-enqueues it. Warm-artifact readiness is a separate observation, not a promise that copying or setup has finished before the child starts.
The journal in the app data directory, managed-launches.sqlite, persists request digests and resource identities, not prompt/environment bodies. Its checkpoints precede workspace and PTY creation. A crash in an uncertain creation window returns blocked rather than attempting that side effect again. A retained live child is recovered by its reserved identity; missing delivery metadata stays unknown. An exited child or server restart never causes the same key to create a replacement. Journal records are not expired: they are retry tombstones, unlike the process-lifetime task_id in a child response. On uncertain workspace creation inspect the requested repository/branch before a separate, explicitly chosen launch.
Native automation and workflow run bindings also use this transaction through managed_launch: automation run IDs and workflow attempt IDs provide stable keys, with an in-process run-owner scope when no peer parent exists. No synthetic peer is registered. Run-owned children use the same pinned-name and explicit keep-open path as MCP children; the existing run controller still owns cancellation and completion. The unkeyed public spawn compatibility action continues to use the same low-level PTY spawn implementation.
Byte-bounded MCP-compatible terminal output
GET /sessions/{id}/output?format=mcp&byte_budget=4096 (or format=mcp_raw)
uses the same validator and immutable snapshot pager as MCP session output.
byte_budget must be an integer from 1024 to 65536. The compact JSON response,
including the page envelope, fits that UTF-8 byte budget; HTTP/MCP framing does
not count. It returns encoding:"json-text", chunk, offset, total_bytes,
continuation, omitted_fields, and expires_after_seconds. Concatenate chunk
values, then parse JSON. Continue on the same session and format with the opaque
continuation query parameter until it is null. A token defaults to 4096 bytes
when the budget is omitted. Snapshots expire after 300 seconds, restart or cache
eviction; invalid or expired tokens fail explicitly. Concurrent output cannot
change a captured snapshot. Other output formats keep their existing contract.
See the full paging and inventory contract.
HTTP MCP-compatible output tokens share the local ipc continuation scope with
IPC MCP passthrough for the same target. A local caller holding a token may
resume it through either transport. This is not a new authentication boundary;
normal endpoint admission still applies. Remote byte-budget requests reject
legacy daemons that do not return the bounded envelope.
Frame workload evidence
POST /debug/frame-workload accepts { "recording": "<schema v1 JSON>" } and returns the saved path as a JSON string. Same writer and payload as save_frame_workload IPC; 8 MiB request cap, 6 MiB recording cap, existing authentication. Writes rotate two instance-local content files and run on the blocking pool. See stall evidence.
Startup owner discovery and interactive login
POST /settings/action shares these typed perform requests with IPC/MCP:
- Machine
github_accounts,operation:{action:"list_accounts"}returns owner metadata, credential presence and revision; no secret values or auth document. - Machine
ego,expectedRevisionfrom its machine read andoperation:{action:"begin_login",provider:"openai-codex"}returns a boundedflowIdandsessionIdfor human authentication. Terminal output/input use the existing session HTTP/WS APIs; Settings does not transport codes or tokens. - The same Ego envelope with
operation:{action:"login_status",flow_id:FLOW}returnsinteractive,closedwith owner credential presence, orexpired. Status does not compareexpectedRevision; begin does. Closed is not success. Refresh providers explicitly after the person completes login. Configured executable/workspace changes invalidate status withconflict.
See startup workflows for expiry, retained-terminal cleanup, readback and error semantics.
Dictation correction Settings records
POST /settings/action describes the machine-owned corrections store. Get
/replacements, create/remove records keyed by from, and set
/replacements/<JSON-Pointer-escaped heard text>/to with expectedRevision.
The same owner backs PUT /dictation/corrections and its existing {map} body.
Persistence precedes runtime adoption and value-free corrections change hints.
No microphone is opened. Non-dictation builds describe unavailable fields.
Legacy upstream credential POST/DELETE now shares the IPC state-bearing owner
adapter and emits value-free upstreams Settings generations after persistence.
Failed validation or vault writes emit no hint; compound durable-vault failures
emit an unapplied hint so readers reload instead of assuming nothing changed.
MCP static repair errors (#2007-59f6)
POST /mcp rejects native static input-schema violations before effects with
invalid_arguments, bounded value-masked violations, effect=not_started, and
retryable=false. Correct the identified JSON-pointer fields before retrying.
See the native argument repair contract in the MCP backend guide. Progress HTTP
and IPC use the same raw 500-Unicode-scalar text limit as MCP.
GET /mcp/usage
Last 7 days of MCP usage per role, from the persistent daily rollup (#2808-5998). Gated by mcp_usage_rollup_enabled (default on): when off the body is {"enabled":false,"days":7,"roles":[]}. Body-free; shape and limits in the MCP backend guide, “Persistent usage rollup”. IPC: get_mcp_usage.
GET /mcp/audit
Gated by mcp_call_audit_enabled (default off in release, on in debug): when off the body is {"enabled":false,"records":[]}. Rows add outcome: replied, error or cancelled. IPC: get_mcp_audit.
Returns a bounded, body-free runtime MCP call outcome projection (100 newest rows, 1024 retained per instance). Includes call/parent correlation UUIDs, recognized operation, target digest, UTF-8 response text bytes, application error and separate transport/effect uncertainty. HTTP and ACP tools/call share the instrumentation. See MCP runtime audit for measurement, retention, privacy and retry-grouping limits. Reply construction does not prove delivery; cancelled/lost replies must not imply no effect.
Modern /mcp managed calls may omit mcp-session-id while carrying the exact
host-issued x-tuic-session for a live PTY/ACP peer. Internal identity recovery
adds no legacy response session header. Missing identity returns structured
identity_context_required with effect=not_started, retryable=false and one
context-change repair attempt; a request repeated unchanged cannot repair it.
Durable peer-mail subscriptions
These endpoints accept a loopback or credential-verified caller, use the existing MCP peer identity from Mcp-Session-Id and
respect the agent tool enable switch. They do not accept a recipient identity.
| Method | Path | Contract |
|---|---|---|
| POST | /agent/subscriptions/action | Same subscribe, inbox, ack, unsubscribe request and validation as the MCP agent tool |
| GET | /agent/subscriptions/{id}/events | Continuous SSE; one mail event per pending batch cursor, with messages, cursor, acknowledged_cursor, missed_count and has_more |
Create with {"action":"subscribe","subscription_id":"pump","filter":"actionable"}.
Process each batch and post {"action":"ack","subscription_id":"pump","cursor":N}.
The filter defaults to actionable; alternatives are all, exit, failure and report (TUIC child_report mail only).
Reconnect replays retained unacknowledged batches. Last-Event-ID is not an
acknowledgement. The journal retains 1000 messages per peer across restart;
matching unacknowledged evictions are explicit in missed_count. Legacy inbox
reads do not consume this reader. Subscription ACK observes exact live delivery
IDs without advancing the legacy cursor or acknowledging its loss watermark.
byte_budget and continuation are unsupported for subscriptions; acknowledge
each bounded batch, then read again when has_more is true. These endpoints
require the bound Mcp-Session-Id; a stateless x-tuic-session alone is not an
HTTP subscription binding. See retention and notification semantics.
Inbound agent webhook
POST /agent/webhook/{to} delivers an external event, or the result of a script, to
an agent as mail. {to} is the recipient: its tuic_session, registered peer name,
PTY id or terminal alias (for example tu-3). The raw request body is the payload,
as UTF-8 text; any content type is accepted, so a service can post its own JSON.
curl -sS --fail-with-body --unix-socket "$TUIC_SOCKET" --data-binary @result.json \
"http://localhost/agent/webhook/$TUIC_SESSION"
--fail-with-body makes a refused request exit non-zero. Windows has no $TUIC_SOCKET,
and the TCP port listens only while remote access is on, so Windows launch instructions
use tuic agent send <recipient> "<result text>" over the named pipe instead (same send
path; the sender is then the calling session, not webhook). With remote access on, any
device can post to the TCP port. The caller must be on loopback or authenticated; the
agent tool enable switch applies.
The payload uses the same send path as agent action=send with normal urgency. The
sender is always webhook, which is not a peer, so a reply to it is refused. A managed
recipient receives only the payload-free inbox notice in its terminal; the payload is
never typed into the terminal. The response is the send result (message_id,
delivered, delivery_path).
| Status | Cause |
|---|---|
| 200 | Mail filed; read delivered and delivery_path for the wake route |
| 400 | Unknown recipient, the orchestrator role address (the webhook has no caller to resolve it from), empty body, non-UTF-8 body, or agent tool disabled; nothing is filed |
| 403 | Remote caller without authentication |
| 413 | Body larger than 64 KB (the mail size limit); nothing is filed |
Plugin catalogue entries returned by fetch_plugin_registry can include optional
contentSha256. Installed plugin discovery returns the same field computed from
the installed payload, not from manifest input. Both transports use the same Rust
manifest serialization and payload identity algorithm. See Plugin Registry.
Session state can carry question_card ({request_id, kind: "questions" | "plan_approval", questions: [{header?, question, options: [{label, description?}], multi_select, free_text}]}) while awaiting_input belongs to the same native request. choice_prompt can then carry header, question_index and question_count (1-based) from that card. Both are absent otherwise and never change the option keys. Desktop IPC state uses the same Rust snapshot.
Session state can carry current_tool (string, at most 64 characters): the newest live native tool name of an agent session, from verified hook or protocol metadata (#2636-5551). It is absent when no tool call is live and while the shell is idle. It never carries tool arguments and never changes shell_state, agent_state or awaiting_input.
An ego session can also carry native_children (array of child labels in flight, omitted when empty) and native_turn_outcome (outcome of the last settled native turn, such as completed, interrupted or failed) (#2674-1be8). Both come from ego agent-event frames, are cleared on process exit and never change shell_state, agent_state or awaiting_input.
Native question choice_prompt.selection_mode can be navigate-only for a
clipped Claude form. Its ↑, ↓, and ↵ option keys denote previous, next,
and select-highlighted controls, not native answer labels. Send one Up, Down, or
Enter respectively; never append Enter to a navigation key. The same payload
and semantics apply to desktop IPC state.
Remote session closure
MCP session action=close accepts a remote connection_id or connection-qualified session reference. The host resolves aliases on the owning daemon and sends authenticated DELETE /sessions/{id}. The caller’s own PTY remains protected from self-close, and non-loopback MCP callers cannot invoke destructive close actions. A disconnected connection reports an error; it never falls back to a local session. HTTP DELETE and local MCP close use the same teardown, session-closed events and retained output tombstone. Repeating a close of a retained tombstone succeeds. Explicit close remains user-directed and is not limited to abandoned shells.
GitHub diagnostics (GET /github/diagnostics) also returns repo_access_errors:
owner/account/host groups with repos: [{repo, reason, message}] and an
optional oauth_app_url for every github.com OAuth group, regardless of reason.
reason is not_found, forbidden or unknown. Messages are the exact per-alias GraphQL errors.
Only confirmed root NOT_FOUND responses enter repos_not_found and its 24-hour
exclusion. Other denials are eligible for the next monitoring poll.
Manual GitHub diagnostics refresh uses POST /github/diagnostics (no body). It
clears the NOT_FOUND cooldown for all accounts and returns the same diagnostics
DTO. GET /github/diagnostics remains read-only. This maps to
github_diagnostics with refresh: true over IPC; omitted or false is read-only.
Detached checkout inventory
GET /repo/structure and GET /repo/summary add detached_worktrees beside worktree_paths. Each record is {path, head, short_head, directory_name, state: "detached"}. The branch map and its workspace IDs do not change. GET /worktrees/paths remains a branch-only map for lifecycle and terminal placement. Both discovery backends retain detached checkouts in the additive inventory and exclude only the configured TUIC archive pool. Detached records are read-only sidebar information, not selectable workspaces.
Directory listing link metadata
GET /fs/list?repoPath=…&subdir=… returns the same DirEntry shape as list_directory IPC. Symbolic links include optional symlink_target (link text) and symlink_target_kind (directory, file, or unavailable) fields and size 0. These fields are metadata only. Repository reads follow links wherever they point; the requested path itself must stay repository-relative.
Session usage
GET /sessions/{id}/usage mirrors get_session_usage(session_id). It returns
{agent, model, scope, source, availability, reason, observed_at_ms, stale, lines, quota_windows}.
Each non-quota line has label and value; Rust owns token and cost semantics.
Each quota window has provider, nullable plan, nullable window_seconds,
window_name, used_percent, and nullable resets_at (an ISO instant).
The shared desktop/mobile presenter owns quota wording and converts reset and
report instants to the viewing client’s local short date and time.
Availability is available or unavailable; unknown identity/timestamp fields
are null, not inferred from defaults. Scope is account_quota or session_usage.
Claude/Codex quota windows describe shared account windows, not session spend.
Claude mobile refreshes retain the local credential plan in the profile-scoped cache
shared with desktop. A missing credential plan stays absent; stale fallback data
keeps its original plan and is marked stale. A mobile primary GET that returns HTTP 429 sets the
same profile backoff used by desktop reads. The delay is at least 120 seconds;
a numeric Retry-After can extend it up to 300 seconds. During backoff, reads
return stale cache or unavailable without another request. Mobile quota reads
never use the generating messages fallback. Timeouts and other errors do not
activate rate-limit backoff.
ego v3
lines retain token categories, currencies, unknown costs and separate subscription
API-equivalent estimates. observed_at_ms for ego is report creation, not latest
settlement. Remote sessions are forwarded to their owning daemon or are unavailable.
The request is bounded to 30 seconds locally; ego stdout is capped at 4 MiB.
Worktree discovery diagnostics (#2157): /repo/structure and /repo/summary also return worktree_diagnostics: Array<{path: string, branch: string | null, state: "missing" | "duplicate_branch", guidance: string}>. These records have no workspace ID and cannot select a branch workspace. /worktrees/paths remains a branch map with the same deterministic primary path used by lifecycle resolution. Discovery failures return errors and are not cached as empty inventories. MCP repository list entries expose discovery failures as worktree_error; ACP workspace resource entries use worktreeError.
Unavailable detached registrations are excluded from automatic orphan cleanup in both Ask and On modes, including the Ask countdown. They remain repair diagnostics until restored or explicitly removed. Safe-only removal rechecks availability, so a directory moved after assessment cannot be pruned automatically. Explicit user-confirmed removal remains available.
Append-only story notes
The shared story service accepts add_note with story_id, expected_revision, text, and optional receipts (an array of {runId, commandId}). list_notes takes story_id and returns {type:"notes",value:StoryNote[]} in append order; add_note returns {type:"note",value:StoryNote}. Each note includes id, storyId, storyRevision, text, actor, createdAt (Unix milliseconds), and receipts.
The backend derives actor provenance and time. It checks the current story revision atomically with the append. A note does not advance the story revision or change its status, claim, criteria, or integration proof. Notes have no edit or delete action. Text must be nonblank and at most 16,000 characters; a note can reference at most 16 distinct receipts. Invalid note input is a user error (HTTP 422).
Receipt references identify persisted workflow event receipts by run ID and command ID, not a policy check name. Each receipt must exist in the same project and plan as the story. The note stores only these identifiers, not a copy of the receipt. A reference is historical evidence, not an assertion that the story is approved or its integration checks are current. All actions use the existing project-scoped IPC, HTTP, MCP, and CLI boundary.
ACP attachment snapshots include availableCommands, the latest complete session
command offer: each entry has name, description, and optional input.hint.
An empty list revokes earlier commands. IPC and HTTP snapshots use the same shape;
the existing ACP stream carries the original available_commands_update update.
Shared AI Chat selection
GET /acp/chat/selection returns { workspace, sessionId, replacing } for the host-configured canonical AI Chat workspace (sessionId is nullable). replacing names the conversation that sessionId continues while the selection is a compaction successor, else null; a follower replaces that tab in place. The link is held in memory and is not persisted. PUT /acp/chat/selection accepts { sessionId: string | null, replacing?: string | null } and requires local or authenticated access. It persists through the shared config delta writer. Last committed selection wins. Changes, including config deletion cleanup, dual-emit payload-free ai-chat-selection-changed on desktop IPC and /events SSE. Clients reread on this event and on reconnect; adopting a snapshot does not write it back. Repository focus and session CLI | Chat remain per device.
Ego terminal usage
GET /ego/usage?sessionId=<terminal UUID> returns the same { text, tooltip?, usage_agent } as get_ego_usage. Ego terminal usage uses the exact live pid lease and ego usage --json --session <id> reports v3–v6. The badge shows the short model name and observed context tokens/capacity. Its tooltip shows the full provider/model. Anthropic models use the existing Claude usage endpoint and ticker; openai-codex models use the existing Codex usage endpoint and ticker. Other providers show model/context only. Ego ledger costs and provider-limit observations do not supply badge quotas; session details still show ledger accounting. Unsupported report versions return an error and log one warning per process, rather than silently emptying the badge. The executable comes from the live terminal, not the AI Chat setting. Local or authenticated access is required. The shared reader caps stdout at 4 MiB and has a twenty-five-second child deadline; the ticker polls every five minutes.
Headless TLS transport
With services.tls.mode: "manual", daemon TCP routes support HTTPS, SSE over
HTTPS, and WSS on the same port. Like desktop remote access, plain HTTP/WS stays
available on that port for local relay and SSH clients. TLS off retains HTTP/WS. Invalid PEM stops startup before bind;
tls_active reports the live TLS listener, not configured certificate paths.
Cancellable story drafts
The prepare, cancel and story-draft routes require loopback or authentication.
Prepare returns a single-use cancellation handle. Pass it as requestId to
story-draft; this invokes the same isolated ego one-shot driver and returns
{title, storyType, priority, problem, criteria} only after Rust validation.
The request is nonblank and at most 20000 characters. Cancel signals the owned
turn, including before it starts, and removes the handle. A running draft request
settles after connection shutdown. Dropping an HTTP caller does not skip cleanup.
Unused handles expire after 301 seconds. These calls never save a story.
create_story accepts optional problem beside input and saves both atomically.
Task-scoped secret injection
The MCP secret tool accepts action: "put", names: string[],
values: string[] (same order), scope: string (task ID), and a positive integer
ttl in seconds. It returns {names,status:"stored"} without values. Use the
existing authenticated /mcp transport; there is no public value-read endpoint.
POST /sessions/agent accepts optional scope, with the same meaning as MCP
agent action=spawn scope=.... Values are injected only into the child env.
Expiry stops new injection; already-bound session masks survive until teardown.
Output is sanitized before raw/text/log HTTP, raw/log/grid WS, terminal history
and tcap output captures. Potential split-secret prefixes are withheld until
resolved, and incomplete trailing prefixes are discarded at teardown. See
Private secret forms.
Archive retention cleanup
POST /worktrees/archive-retention accepts { "repoPath": "/absolute/repository" } and returns { "deleted": ["archive-name"], "kept": ["archive-name: reason"] }. The host resolves retention from its repository settings; no threshold is accepted from the caller. Desktop IPC uses the identical result via sweep_archive_retention. It deletes only recorded eligible completed archives under __archived/, with live-session checks and non-force Git removal; commit archive refs remain.
AI Chat voice targets
GET /dictation/hands-free/targets returns [{ id, name, chatSessionId }] for attached host-managed AI Chat sessions. Pass the opaque id unchanged as sessionId to the existing hands-free arm endpoint. The arm, status, disarm and speech payloads remain unchanged. Terminal session ids continue to work.
Native Windows agent hook state returns unsupported. Both hook instrumentation and native status setters reject changes without writing preferences or hook files. These routes share the desktop command cores; availability belongs to the backend machine, not the browser OS.
Agent reports: POST /mcp tool agent action send accepts structured report metadata alongside required message. GET /sessions exposes report, report_at (host Unix ms), report_message_id, stage and stage_reason; stage is null when unknown or not live. Contract.
GET /sessions and MCP peer/session inventories also include boolean stalled, evaluated for local managed PTYs from report, input and output activity. A stall sends one state_change parent notice with state: "stalled", recovery (nudged_worker, or parent_decides when the worker already sent a RESULT and gets no nudge), background_work and stop (the explicit session action=kill command), and one stall_nudge notice to the worker; actionable and failure subscriptions include the parent notice. Recovery never stops the PTY. See silent workers.
Waiting items and agent health
GET /agents/attention mirrors IPC boss_attention() and returns { items, health, warnings }. Items are stories waiting for manual checks, unanswered workflow questions and unread reports of registered local projects. They contain id, kind (manual_check, question, help, approval, outside_request or report), title, detail, options: [{ id, label }], project, nullable planId, nullable runId nullable story: { id, title, status } and nullable report: { id, kind, title, path, revision } (the typed report reference; path is relative to the project). Health entries contain sessionId, nullable connectionId, name, kind and reason. This is a fresh read-only projection, not a report or answer store. Partial story/workflow read failures appear in warnings. Remote session stages are mirrored from their owning host and feed health only. boss-attention-changed is a payload-free invalidation on /events; clients reread after reconnect.
POST /agents/attention/outside-request mirrors IPC answer_outside_request({ requestId, decision }). The body is { "requestId": string, "decision": "accept" | "decline" }; the reply is { "ok": true }, or 502 { "error" } when the Fabbrica control MCP refuses (for example a second answer). Items of kind outside_request (id fabbrica:outside:<requestId>) are Fabbrica outside requests in the ask state.
Close completed run tabs
Set close_on_finish: true on an automation definition, or select Close the run
tab after confirmed completion in the Automations editor. The optional boolean
defaults to false. Create and update accept the same field over MCP, HTTP and
desktop IPC, and store it in automations.json and the immutable run snapshot.
Only a positively confirmed completed run closes its recorded session through
the existing session-close path and tab countdown. Failed, unknown, timed-out,
interrupted and needs_you runs do not trigger this option. Idle is not completion.
The option never removes a worktree or branch and never closes sibling sessions
in an existing checkout. Worktree removal remains a separate explicit
cleanup_worktree action with its existing safety checks.
AI Chat message actions
GET /acp/chat/{session_id}/reactions(acp_message_reactions) returns{ [nativeMessageId]: ["thumbs_up" | "thumbs_down" | "heart" | "celebrate"] }.POST /acp/connections/{connection_id}/sessions/{session_id}/message-action(acp_message_action) accepts{ messageId, text, action }.textis the source snapshot;actionis{ kind: "reaction", reaction, remove: boolean }or{ kind: "comment", comment }. It returns{ turnId, reactions }after the original conversation queue accepts the prompt and the reaction mark is saved. It does not acknowledge model consumption. The prompt contains the exact native ID, a source excerpt capped at 4000 characters, the action, and an explicit statement that the action is conversational, not evaluation or authorization. Empty IDs/source text/comments are refused. A disconnected or missing attachment fails without a replacement conversation. If persistence fails after acceptance, the error states that acceptance occurred and warns against resending. Accepted marks are invalidated through the existing dual-transportsettings-changedevent; clients reread on reconnect.
Plugin binary ranges
GET /api/plugins/:plugin_id/fs/size?path=<absolute> returns the byte count.
GET /api/plugins/:plugin_id/fs/range?path=<absolute>&offset=<n>&length=<n> returns exact Base64 bytes. Both require fs:read; length is capped at 8 MiB and past-EOF reads fail.
Heap profiling diagnostics
GET /diagnostics/heap verifies profiler availability, process-start configuration and active sampling. POST /diagnostics/heap accepts {"action":"activate"}, {"action":"deactivate"} or {"action":"dump","path":"/absolute/file.heap"}. Dump responses contain path, bytes, duration_ms; unavailable profiling or dump errors return HTTP 400 with error. Shared by desktop and headless, using existing diagnostics authentication. See the heap runbook. /diagnostics/memory now qualifies malloc_scope and reports separate allocator allocated/active/resident/retained bytes when available.
Neutral workflow actions
Native start captures backend Owner provenance only for loopback/verified user
credentials, before waking execution; transport admission alone cannot bind it.
Native answer requires authenticated Owner or the bound Agent with captured
and current Operator. Exact retries preserve the original binding. Published
constant verification requests select installed check names; start JSON does not.
POST /workflows/neutral/action?path=<project> accepts the same NeutralAction as desktop IPC; the JSON body is the action itself. Local/authenticated guard, closed request fields, snake_case {type,value} replies, cursor-based inspection and lifecycle SSE are shared. See neutral transport.
Scheduled neutral bindings
The existing neutral action accepts trigger source scheduled with kind: "schedule",
resource_prefix: "schedule:<binding id>", events: ["due"], and optional draft field
schedule: {"cron":"0 9 * * *","timezone":"UTC","text":"Review the summary"}.
Only scheduled bindings accept that field, and it is required for them.
The installed mapping fields are text (string) and occurrence_ms (integer).
Starts and exact local approval answers use the existing run/Answer envelopes.
See trigger admission.
Provider quota registry
GET /provider-quotasreturns the current registry views without a network read.GET /sessions/{session_id}/quota-bindingreturns the subscription key for the session, ornull.POST /provider-quotas/refreshaccepts{ "key": { "owner": "…", "provider": "…", "credential": "…" } }and returns the updated view. The registry limits forced refresh to once per minute per key; an early request returns an error with the retry time.- Each quota view includes
session_ids, the initial client binding inventory for its key. /eventspublishesprovider-quota-changedwith the changed view as its payload. Desktop clients receive the same payload through the Tauri event./eventsalso publishesprovider-quota-binding-changedwith{session_id, key}when a binding changes. A null key retracts the binding. Desktop clients receive the same event. Clients subscribe before reading initial session bindings so a late read cannot overwrite a newer event.- A subscription key can include an optional
profile. A named profile remains separate from the credential path. Owners that do not support it returnunavailablewith reasonprofile not supported; they do not use the default profile.
Tauri Commands Reference
App config reads (GET /config and load_config) can include the transient config_recovery: { fields: string[], backup_path: string } diagnostic after startup recovery. It names reset fields and the preserved original; it is never persisted.
Planner Ideas use the same StoryAction envelope as plans and stories: add_idea {text,source?}, list_ideas, and update_idea {idea_id,text}. IPC story_action_command, HTTP POST /stories/action?path=<project> ({action:<StoryAction>,sessionId?:string}), CLI tuic story, and MCP workflow action=story input=<StoryAction> share the Rust owner. Add/update return {type:"idea",value:<camelCase Idea>}; list returns {type:"ideas",value:[...]}. The project sets repoPath; list also includes global Ideas, while update requires project ownership. Source defaults to the bound session id or local-api. Text is trimmed to a nonblank maximum of 16000 characters; source is nonblank with a maximum of 256. Writes use the strict locked notes.json owner and publish payload-free ideas-changed on desktop and /events SSE. UI save_notes(base,config) / PUT /config/notes applies per-id and per-field intent instead of replacing stale arrays. See Ideas through the planner.
Native plans have a stored revision. update_plan takes plan_id, expected_revision, and patch with optional title and source. At least one field is required. The shared service validates both fields and commits them with one revision increment in one transaction; stale revisions leave the plan unchanged. Existing records start at revision 1. A metadata change changes the workflow planning and verification fingerprints, including plans with no stories. Source prose stays in the external document; the update does not move or rewrite that file. Source-changing edits are refused with a user error while a plan coordinator/planner attempt is running, including an unbound attempt or a paused run. Finish the coordinator or cancel its run first. Title-only and unchanged-source edits remain allowed. The same action is available through MCP, HTTP, desktop IPC, and tuic story.
Scoped plugin settings
plugin_settings_action(plugin_id: String, action: PluginAction) returns catalogue descriptors, a redacted snapshot, or a commit reply. Actions: describe, get with paths, set/reset with path and expectedRevision, patch with operations and expectedRevision. The backend binds the plugin owner and config file; unloaded or schema-less plugins are unavailable. HTTP twin: POST /api/plugins/{id}/settings.
Native stories
story_action_command accepts backend_status and the explicit human approve_connector {installation,expected_identity} action. The status descriptor includes backend identity, automatic/explicit provenance, reason, availability, installation, version and error even if initialization fails. HTTP and headless use the same service; see the story backend protocol.
set_backend {backend:"native"|"automatic"|"wiz-stories"} is also an authenticated-human-only shared action. Native continuity precedes discovery; active run snapshot provenance prevents backend changes after restart. Approval compares the displayed generation (entry/version), not a full installation-tree digest.
Native stories expose qa for work that waits on manual checks. A criterion starts with [MANUAL], or is marked through set_criterion_manual {index,manual}. Active work automatically enters QA when all unchecked criteria are manual; submit_qa explicitly requests that state. reject_qa returns QA to In progress; approve requires every criterion checked. QA keeps plans Active and dependencies blocked. All transitions retain expected-revision checks. See the native stories guide.
Reversible native record archival
All native story transports share archive_story, unarchive_story, archive_plan, and unarchive_plan. Story actions take story_id; plan actions take plan_id. Each requires expected_revision and returns the updated record with its incremented revision and archived flag. Stale revisions fail without a write. Archival preserves status, criteria, dependencies, and child archive flags; it never deletes records or cascades to children.
list_plans and list_stories default to archived: false. Set archived: true to select archived records. The story filter combines with the other filters and is bound into pagination cursors. filtered_plan_view also accepts camel-case filter.archived (default false), which selects archived list ids and board columns without changing the active-plan state calculation. Direct reads remain available. Default plan views and workflow dispatch omit archived stories; archived plans and stories cannot start manual or workflow work. Restore the parent plan before starting its stories.
Both archive and restore refuse claimed stories and plans that contain a claimed story. Story archival also refuses any prerequisite that is not Done while an open dependent references it, including inside an archived plan. The refusal lists the dependent IDs and leaves the record and history unchanged. WontFix does not satisfy dependencies. Done prerequisites and unresolved stories with only closed dependents remain archivable. Adding a dependency to an archived unresolved story requires restoring it first; both dependency editors enforce this rule. Whole-plan archival does not change dependency readiness. An active or paused plan-root workflow owns the plan’s story set. A story-root workflow owns its target and execution stories, not unrelated siblings. Cleanup of an owned story or its parent plan is refused until the run ends. The workflow writer lock remains held through the archive transaction, so a concurrent run cannot start between the ownership check and the write.
story_archive_history (story_id) and plan_archive_history (plan_id) return {type:"archive_history",value:[{revision,archived,actor}]} in revision order. Events commit atomically with the record and retain caller provenance. Existing status transition history remains separate. Consecutive archive-only revisions preserve accepted-work integration receipts; a work change or a moved canonical Git ref still invalidates them. Example: tuic story '{"action":"archive_story","story_id":"<id>","expected_revision":1}' --project /absolute/project.
| Command | Parameters | Result | Description |
|---|---|---|---|
story_action_command | project, action, sessionId? | tagged StoryReply | Creates, reads, amends, claims, transitions, or removes a cancelled dependency from native stories. update_story takes a revision-checked typed patch for unclaimed Backlog/Ready stories without run ownership; metadata, criteria and dependencies commit atomically. list_plan_sources discovers project Markdown plans and add_plan_source records one with its document title; both are also available through HTTP and MCP. plan_view returns a Rust-derived plan summary and transitive abandoned indicators; transition_history returns actor provenance. Removal requires a Backlog dependent, a direct WontFix prerequisite, and the current revision. The backend checks project ownership and claim session identity. See HTTP API. |
story_capabilities | project? | Result<StoryCapabilities> | Capability probe used before loading the dialog: { backend, operations }, booleans per operation plus additive operations.story_edits {title,priority,problem,criteria_add,single_change} of the project’s story backend (native, or external:<adapter id> from story-backends.json; see docs/backend/story-backend-protocol.md). Without project it answers native; an external adapter that cannot start is an error. Its absence, or a plain true from an older build, means the running backend needs a restart. |
add_plan_source reuses an active plan with the same source. If only an archived plan matches, it returns an error that identifies the plan and gives explicit restore instructions; it does not create another record or change archive state.
list_stories shares optional top-level state, priority, story_type, limit (1–100), and cursor across all transports. Without a limit it returns every matching story; limited responses retain the value array and add next_cursor only when more matches remain. Cursors require a limit and the same plan/filters. See the HTTP API for bounds and live-read semantics.
project_story_view takes archived_plans (default false) and a camel-case filter with the same fields and defaults as filtered_plan_view. It returns {type:"project_story_view",value:{stories,visibleStoryIds,columns}} across every plan in the envelope project and selected plan archive scope. archived_plans:true selects archived plans only; filter.archived:true independently selects archived stories. Full records remain available for detail and dependency reads; only display ids and columns are filtered. The reply has no combined plan state. The shared StoryAction service exposes this action through IPC, HTTP, MCP and CLI.
filtered_plan_view uses the same service on IPC, HTTP, MCP, and CLI. It takes plan_id and filter (camel-case visibility, storyType, untypedOnly), and returns the full plan with filtered list ids and per-status board ids. Optional storyType on create input and persisted stories is feature, fix, refactor, chore, or task; omitted types stay untyped. See the HTTP API for defaults and combined-filter rules.
Project Progress
| Command | Parameters | Result | Description |
|---|---|---|---|
report_progress_event | project, report | {id} | Appends one done or blocked entry through the same core as MCP and HTTP. |
progress_list | project, input.progressOnly?, input.blockedOnly?, input.ptyId?, input.limit?, input.cursor? | ProgressList | A newest-first page (default 8, maximum 100), matching total, next cursor, available PTY IDs, and stored last-visit mark. |
progress_projects | none | string[] | Journal projects ordered by their most recent entry, for clients without an active desktop repository. |
progress_delete | project, input.ids | {deleted} | Deletes entries by id, scoped to the project — one project cannot delete another’s. |
progress_flow | project, input.ptyId? | ProgressFlow | The journal as a delegation sequence: participants and ordered hand-off events (see docs/api/http-api.md → Project Progress). |
progress_flow_detail | input.ptyId, input.agentId, input.part | {text} | Full redacted prompt or report of one subagent arrow, fetched on demand. |
progress_mark_viewed | project, ptyId? | {lastViewedMs} | Moves the selected PTY’s or repository aggregate’s last-visit mark to now. Deliberately not an MCP action: it is the reader’s, not the agent’s. |
The journal is append-only. There is no pause, clear, correction or export
command: an entry is written once and either kept or deleted. intent entries
are written by TUIC from the agent’s intent: marker and cannot be reported.
Every stored entry has secret-shaped text and step values redacted; agent and
target names are redacted and capped at 80 characters.
All commands are invoked from the frontend via invoke(command, args). In browser mode, these map to HTTP endpoints (see HTTP API).
Grid-frame channels and terminal_styled_rows share the optional
TCX1 cell-text trailer
with HTTP/WS. Complete cell text includes retained zero-width characters.
terminal_search_buffer returns UTF-16 string ranges; terminal_search retains
grid-cell coordinates. Both match the stored sequence without normalization.
PTY Session Management (pty.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
create_pty | config: PtyConfig | String (session ID) | Create PTY session |
create_pty_with_worktree | pty_config, worktree_config | WorktreeResult | Create worktree + PTY |
write_pty | session_id, data | () | Write to PTY |
write_pty_parts | session_id, parts: Vec<String> | () | Write several inputs under one writer lock. The parts stay separate on purpose: post-write bookkeeping runs once per part, and it is not a function of the joined bytes (a lone / opens slash mode, an exact option key answers a choice prompt) |
enqueue_agent_command | session_id, text, idempotency_key?, expected_draft? | { accepted, typed, queued } | Queue for the next idle window; optional expectedDraft validates and clears the live composer first (errors after clearing are uncertain; do not retry automatically); optional key (1–128 UTF-8 bytes, wire name idempotencyKey) recognizes the last 128 accepted keys per live PTY without resubmitting; acceptance is not a model-turn receipt |
clear_queued_agent_commands | session_id | usize | Drop every queued command; returns how many |
list_queued_agent_commands | session_id | [{ id, text, kind, send_now? }] | Every parked entry in delivery order, including notices and initial prompts. send_now is interrupt, or absent when the harness has no Send now |
send_queued_agent_command_now | session_id, command_id | bool | Force one pending item: Claude, Codex and ego share Escape, confirmed idle (up to 10 s), then full-text submission before queued mail; false when already claimed; a refusal keeps an unwritten item queued; ambiguous writes never retry |
remove_queued_agent_command | session_id, command_id | bool | Drop one queued command by id; false when it already drained |
resize_pty | session_id, rows, cols | () | Resize PTY; alternate-screen resizes preserve primary-log continuity |
pause_pty | session_id | () | Pause reader thread |
resume_pty | session_id | () | Resume reader thread |
close_pty | session_id, cleanup_worktree | () | Close PTY session |
can_spawn_session | – | bool | Check session limit |
get_orchestrator_stats | – | OrchestratorStats | Active/max/available |
get_session_metrics | – | JSON | Spawn/fail/byte counts |
list_active_sessions | – | Vec<SessionInfo> | List all sessions with display_name_is_custom, display_name_from_spawn, is_remote, optional live tuic_session, the optional resolved parent_session, and the same optional lifecycle state (shell_state, agent_state, background_work, queued_commands) returned by GET /sessions — one builder serves both. Sessions running on a connected remote machine are in the list too, each carrying connection_id; a local row has none (#791-055e) |
list_worktrees | – | Vec<JSON> | List managed worktrees |
get_session_foreground_process | session_id | JSON | Get foreground process info |
get_kitty_flags | session_id | u32 | Get Kitty keyboard protocol flags for session |
get_prompt_receipt | session_id | PromptReceipt | Read captured launch sections and observation gaps; async/blocking worker |
get_last_prompt | session_id | Option<String> | Get last user-typed prompt from input line buffer |
get_shell_state | session_id | Option<String> | Get current shell state (“busy”, “idle”, or null); agent-specific semantic Working markers can repair a transient false-idle state |
has_foreground_process | session_id: String | bool | Checks if a non-shell foreground process is running |
get_pty_capture | – | JSON | Raw PTY capture tap state: enabled, session filter, directory, bytes per session. Browser parity: GET /diagnostics/capture. |
set_terminal_literal_reads | session_id: String, enabled: bool | {session_id, enabled} | Owner grant for literal terminal reads of one PTY session; memory only, cleared on session close and restart. session action=output literal=true then skips secret-shaped pattern masking for that session on screen, delta, absolute and raw reads; registered and scoped secrets stay masked. Surfaced as Allow Literal Terminal Reads in the tab context menu. Desktop-only (INTENTIONALLY_UNMAPPED): models reach loopback HTTP and MCP, so no HTTP route can grant it. |
set_pty_capture | enabled: bool, session_id: Option<String> | JSON | Start/stop recording raw PTY bytes to <config dir>/captures/<id>.tcap or the absolute TUIC_CAPTURE_DIR override; a relative override returns an error and leaves recording disabled. Starting begins a fresh file. Surfaced as Capture Session in the tab context menu under isPerfDebug(). Browser parity: POST /diagnostics/capture. |
set_session_name | session_id, name, is_custom? | () | Set a session display name and whether it represents an explicit user rename |
get_input_buffer_content | session_id | String | Get the current content of the input line buffer (what the user is typing). Used by plugins with pty:read capability. |
terminal_get_selection_text | session_id, start_row, start_col, end_row, end_col, history_base? | Result<String, String> | Read a scrollback-aware selection, join soft-wrapped rows, and remove coherent Claude visual gutter runs. Optional frame history_base rebases grid-relative rows atomically against history eviction; evicted endpoints are rejected. Browser parity: GET /sessions/:id/terminal/selection-text (historyBase query parameter). |
get_process_stats | – | Vec<ProcessStat> | CPU% and RSS memory for TUIC and all child process trees |
subscribe_terminal_grid | session_id, channel: Channel<Response>, visible: bool | u64 (epoch) | Register the grid-frame channel and initial visibility for the calling WebView and install a fresh delivery gate (counting from zero). Navigation or destruction releases only that WebView’s subscriptions. Returns the subscription epoch the client must carry on ack_terminal_frame and unsubscribe_terminal_grid. Frames are raw bytes, not JSON. Browser parity: WS /sessions/:id/stream?format=grid |
ack_terminal_frame | session_id, epoch: u64, received: u64, visible?: bool | () | Report the total number of frames this client has received and optionally update epoch-scoped desktop visibility. Hidden subscriptions receive no frames. The gate opens when the echo catches up with what was sent, which is what tells a fresh ack from a late one for an abandoned frame. An ack whose epoch is not the live subscription’s is dropped. A receipt never marks the grid dirty or generates a frame; actual pending damage and recovery debt are retained by the ticker. Browser parity: none — the WS path uses sequence numbers instead |
unsubscribe_terminal_grid | session_id, epoch: u64 | () | Tear down the grid channel and its gate. The pending scroll target is NOT torn down — it belongs to the session, so an attached browser keeps scrolling after the desktop terminal closes. A non-matching epoch is ignored: a remount subscribes before the outgoing instance unsubscribes, and honouring the stale call would blank a mounted terminal. Browser parity: closing the WS |
chat_view_snapshot | session_id, epoch: Option<u64>, from_seq: Option<u64>, pending_texts: Option<Vec<String>> | ChatViewSnapshot | Chat view of a Claude or Grok terminal: transcript entries from the bound session file as ACP updates, with a bounded log, epoch and reset flag. Errors not_bound: <reason> for a terminal with no bound Claude or Grok agent. Browser parity: POST /sessions/:id/chat-view. Optional pending texts return in request order after the same Rust redaction and character cap used for user receipts |
chat_view_full_text | session_id, message_id | { text } | Whole prompt or reply of one message the Chat stream capped at 20 000 characters, read back from the bound Claude transcript through the same adapter (redaction kept, no cut). Errors not_bound: …, not_supported (other agents), message not found in the transcript. Browser parity: GET /sessions/:id/chat-view/messages/:message_id/full-text |
terminal_styled_rows | session_id, start, count | Result<Response, String> (packed bytes) | A range of styled rows by absolute index, filling the client-side scroll cache. Raw bytes for the same reason as grid frames. Browser parity: GET /sessions/:id/terminal/styled-rows (application/octet-stream) |
terminal_scroll_info, terminal_search, terminal_search_buffer,
terminal_get_row_text, terminal_get_logical_line, and terminal_get_lines
use pty::vt_try_read, so each returns Result<T, String> rather than a bare T.
The Err arm means the pool task itself failed; a session that is gone is still
the old default (or a 404 over HTTP). See
docs/backend/command-threading.md.
MCP session action=submit deliberately has no new Tauri command. It is a
request-scoped orchestration contract in mcp_transport.rs: it reuses the PTY
injection claim, writer, input FSM, and output ring, then keeps the MCP response
open for a bounded terminal-movement receipt. Desktop write_pty and
write_pty_parts remain raw input primitives and make no acknowledgement claim.
Raw input returns an uncertain-delivery error after two seconds rather than
waiting indefinitely on a blocked writer. The write can still complete; do not
retry automatically. Session close does not wait on the input writer.
Design Mode (design_mode/tauri_commands.rs)
The desktop commands and their HTTP equivalents control the same per-repository Chrome inspector. A start is bound to the named agent session; a second start for the repository rebinds its existing Chrome window. A grab is inserted into that session’s input draft without submitting it.
| Command | Args | Returns | Description |
|---|---|---|---|
start_design_mode | sessionId: String, browser?: String, url?: String | DesignModeStatus | Start or rebind an agent terminal; optional HTTP(S) url opens directly, otherwise uses discovery/onboarding |
stop_design_mode | repoPath: String | DesignModeStatus | Stop inspection for a repository |
get_design_mode_status | – | Vec<DesignModeStatus> | Read the active per-repository modes |
Command responses use { repoPath, sessionId, status }, with status equal
to armed or stopped. The backend also emits design-mode-changed with a
snake_case event payload { repo_path, session_id, status }; browser clients
receive it on /events.
Generators (generators.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
generate_value | generator_id, options | GeneratedValue | Generate a secure random value (password, uuid_v4, uuid_v7, ulid, cuid2, jwt_secret, totp_secret, nano_id, slug, ed25519_keypair) |
Git Operations (git.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
get_repo_info | path | RepoInfo | Repo name, branch, status |
get_git_diff | path | String | Full git diff |
get_diff_stats | path | DiffStats | Addition/deletion counts |
get_changed_files | path | Vec<ChangedFile> | Changed files with stats |
get_file_diff | path, file | String | Single file diff |
get_gutter_changes | path, file, scope? | Vec<GutterChange> | Per-line editor gutter/scrollbar change markers (diff parsed in Rust); empty for an untracked file |
get_git_branches | path | Vec<JSON> | All branches (sorted) |
get_recent_commits | path | Vec<JSON> | Recent git commits |
get_git_remotes | path | Vec<{name,url}> | Every remote; credentials in URLs removed (workitem_links.rs) |
list_workitem_links | — | {repoPath: {branch: WorkItemLink}} | Work-item links of worktree branches (workitem_links.rs) |
link_workitem | repoPath, branch, link | () | Link a worktree branch to a work item; url must be http(s) |
unlink_workitem | repoPath, branch | bool | Remove a link; true when one existed |
rename_branch | path, old_name, new_name | () | Rename branch |
check_is_main_branch | branch | bool | Is main/master/develop |
get_initials | name | String | 2-char repo initials |
get_merged_branches | repo_path | Vec<String> | Branches merged into default branch |
get_repo_summary | repo_path | RepoSummary | Aggregate snapshot: worktree paths + merged branches + per-path diff stats in one IPC |
get_repo_structure | repo_path | RepoStructure | Fast phase: worktree paths + merged branches only (Phase 1 of progressive loading) |
get_repo_diff_stats | repo_path | RepoDiffStats | Slow phase: per-worktree diff stats, last commit timestamps, and workspace_statuses keyed by opaque workspace id (Phase 2 of progressive loading) |
run_git_command | path, args | GitCommandResult | Run an allowlisted git subcommand with normal options; generic branch deletion is refused (success, stdout, stderr, exit_code) |
get_working_tree_status | path | WorkingTreeStatus | Full porcelain v2 status: branch, upstream, ahead/behind, stash count, staged/unstaged entries, untracked files |
update_from_base | path, branch_name, strategy? | String | Fetch configured base ref and rebase or merge the branch onto it. Conflict cleanup reports (aborted) only after abort succeeds; abort failure includes manual recovery guidance. |
git_stage_files | path, files | () | Stage files (git add). Path-traversal validated |
git_unstage_files | path, files | () | Unstage files (git restore --staged). Path-traversal validated |
git_discard_files | path, files | () | Discard working tree changes (git restore). Destructive. Path-traversal validated |
git_commit | path, message, amend? | String (commit hash) | Commit staged changes; optional --amend. Returns new HEAD hash |
get_commit_log | path, count?, after? | Vec<CommitLogEntry> | Paginated commit log (default 50, max 500). after is a commit hash for cursor-based pagination |
get_stash_list | path | Vec<StashEntry> | List stash entries (index, ref_name, message, hash) |
git_stash_apply | path, index | () | Apply stash entry by index |
git_stash_pop | path, index | () | Pop stash entry by index |
git_stash_drop | path, index | () | Drop stash entry by index |
git_stash_facts | path, stash_ref | StashFacts | Deterministic facts for the stash Check prompt (files already in HEAD, branch state, diff) |
git_stash_check_drop | path, stash_ref, hash, verdict | StashCheckOutcome | Drop a stash only when the verdict is redundant/obsolete AND git proves every file is in HEAD; archives the commit under refs/archive/stash/<hash> first |
git_stash_show | path, index | String | Show diff of stash entry |
git_apply_reverse_patch | path, patch, scope? | () | Apply a unified diff patch in reverse (git apply --reverse). Used for hunk/line restore. scope="staged" adds --cached. Patch passed via stdin (no temp files). Path-traversal validated |
get_file_history | path, file, count?, after? | Vec<CommitLogEntry> | Per-file commit log following renames (default 50, max 500) |
get_file_blame | path, file | Vec<BlameLine> | Per-line blame: hash, author, author_time (unix), line_number, content |
get_branches_detail | path | Vec<BranchDetail> | Rich branch listing: name, ahead/behind, last commit date, tracking upstream. No merged status: the Branches tab loads that separately through get_merged_branches, so the per-branch classifier never delays the list |
delete_branch | path, name, force | () | Delete a local branch. force=false uses the shared integration proof and compares the ref with its proved tip; content-based proof requires an exact-tip archive. force=true preserves the exact tip at refs/archive/<branch> before deleting, archives at refs/archive/<branch>-<sha7> when that name holds a different tip, and cannot delete a checked-out branch. Refuses to delete the current branch or default branch |
create_branch | path, name, start_point, checkout | () | Create a new branch from start_point (defaults to HEAD). checkout=true switches to it immediately |
get_recent_branches | path, limit | Vec<String> | Recently checked-out branches from reflog, ordered by recency |
Commit Graph (git_graph.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
get_commit_graph | path, count? | Vec<GraphNode> | Lane-assigned commit graph for visual rendering. Default 200, max 1000. Returns hash, column, row, color_index (0–7), parents, refs, and connection metadata (from/to col/row) for Bezier curve drawing |
GitHub Authentication (github_auth.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
github_start_login | — | DeviceCodeResponse | Start OAuth Device Flow, returns user/device code |
github_poll_login | device_code | PollResult | Poll for token; saves to keyring on success |
github_logout | — | () | Delete OAuth token from keyring, fall back to env/CLI |
github_auth_status | — | AuthStatus | Current auth: login, avatar, source, scopes |
github_disconnect | — | () | Disconnect GitHub (clear all tokens from keyring and env cache) |
github_diagnostics | — | JSON | Diagnostics: token sources, scopes, API connectivity |
GitHub Integration (github.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
get_github_status | path | GitHubStatus | PR + CI for current branch |
get_ci_checks | path | Vec<JSON> | CI check details |
get_pr_review_threads | path, pr_number | {bot, human, ego} | Unresolved review threads of one PR, split bot vs human vs ego (first comment carries <!-- tuic:ego-review -->) |
get_repo_pr_statuses | path, include_merged | Vec<BranchPrStatus> | Batch PR status (all branches) |
approve_pr | repo_path, pr_number | String | Submit approving review via GitHub API |
update_pr_branch | repo_path, pr_number, expected_head_sha | () | Update a BEHIND PR branch from its base, pinned to the shown head |
close_pr | repo_path, pr_number | () | Close a PR without merging |
merge_pr_via_github | repo_path, pr_number, merge_method, expected_head_sha | String | Merge PR via GitHub API, pinned to the reviewed head |
get_all_pr_statuses | path | Vec<BranchPrStatus> | Batch PR status for all branches (includes merged) |
get_pr_diff | repo_path, pr_number | {diff, headSha} | Get PR diff content and the head it was read at |
get_merged_prs | repo_path, since_tag? | Vec<MergedPr> | Merged PRs via GraphQL, optionally since a tag’s date |
start_conflict_assist | repo_path, pr_number | ConflictAssistResult | Worktree on PR head + rebase onto base; reports verified/unverified clean or conflicts, base provenance/warning, and agent prompt (push gated, never auto-merge) |
fetch_ci_failure_logs | repo_path, branch, check_url?, head_sha? | String | Fetch failed-job logs for the local branch head, or select a check at the supplied PR head SHA; failing checks come from the paginated commit rollup and Actions logs from REST using the repository account on github.com or GHE; one 60-second sweep deadline |
circleci_token_status | — | CircleCiTokenStatus | Report token presence and source without returning the token |
circleci_set_token | token | () | Store a read-only CircleCI token |
circleci_delete_token | — | () | Remove the stored CircleCI token |
check_github_circuit | path | CircuitState | Check GitHub API circuit breaker state |
Review, Changelog and Improvement Scan (pr_review.rs, changelog.rs, improvement_scan.rs)
Each of the first three is one unattended acp::oneshot turn (#795-320b): the
whole input goes inline, ego is offered no host tools, and every permission
request is refused. No API key is stored and no provider HTTP call is made from
TUICommander; which model runs is ego’s own configuration. An ego that cannot be
reached is an error carrying ego’s own sentence, never an empty result.
| Command | Args | Returns | Description |
|---|---|---|---|
run_pr_review | repo_path, pr_number | PrReviewResult | Review a PR’s diff. Findings under the confidence threshold (default 0.7, TUIC_REVIEW_CONFIDENCE_THRESHOLD overrides) are dropped before the result is built. Emits review-progress |
generate_changelog | repo_path, since_tag? | ChangelogResult | Changelog over the merged PRs since a tag. { markdown, json }; json is null when ego answered in prose only |
run_improvement_scan | repo_path, focus | ImprovementScanResult | Up to five proposals for refactor, testing or perf. Emits proposals-ready |
create_issue_from_proposal | repo_path, proposal | CreatedIssue | File one proposal as a GitHub issue through account-aware REST. No model call |
Worktree Management (worktree.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
create_worktree | base_repo, branch_name, create_branch?, base_ref? | { status: "ok", name, path, workspace_id, branch, base_repo, base_commit, instructions } | Create a linked worktree and start warming in the background. instructions.warm_artifacts.status is pending, matching HTTP/MCP. Parent tracked changes are not carried over. |
remove_worktree | repo_path, workspace_id, delete_branch?, force?, override_lock?, expected_fingerprint?, confirm_missing_checkout?, permanent_delete? | { branch_delete_warning?: string, branch: string, removal_rule: string } | Remove a linked worktree by workspace_id. Branch deletion defaults to true, or false when force is true. permanent_delete=true explicitly opts out of recycling, requires branch deletion, a fresh clean and integrated lifecycle and no live sessions, and rejects force or lock overrides. Without force, a clean checkout and submodules with no Git operation in progress are required even when the branch is kept. force permits discarding dirty files but does not skip branch proof or override a lock; override_lock is separate. A live checkout requires expected_fingerprint for force removal. A missing registered checkout instead requires force and explicit confirm_missing_checkout; its absence is rechecked before cleanup and module refs are preserved before pruning. Branch deletion uses the same integration proof as MCP, including no-op merges, corroborated squash messages and archived content heuristics, alongside ancestry, patch equivalence and verified merged GitHub PRs fetched over account-aware, fully paginated HTTP GraphQL; it uses the captured OID and warns if the proof fails or the ref moves. Keeping the branch skips only branch proof. Before Git removes a live checkout, owner write permission is restored inside it so read-only ignored artifacts cannot block deletion. A leftover unregistered directory is reported with its path. removal_rule names the matching rule. |
delete_local_branch | repo_path, branch_name, workspace_id, keep_worktree? | () | Delete a local branch and dispose of the workspace workspace_id names. Two identifiers because there are two objects: branch_name is the ref to delete, workspace_id the checkout holding it. Refuses to delete the default branch, and refuses when the resolved workspace is on a different branch than the one asked for. Uses safe git branch -d |
check_worktree_dirty | repo_path, workspace_id | bool | Check if the workspace workspace_id names has uncommitted changes. Addressed by id because the answer gates an irreversible cleanup — a sibling on the same branch being clean must never authorise destroying this one. Returns false if the id resolves to no checkout. When git cannot answer (the worktree list or status call fails) it returns an error, never false — callers that gate a destructive action must see the failure |
get_worktree_paths | repo_path | HashMap<String, { branch, path, kind: "worktree", warm_artifacts }> | Every linked worktree of a repo, keyed by workspace id. warm_artifacts.status is pending, done, or failed. |
get_worktrees_dir | – | String | Worktrees base directory |
generate_worktree_name_cmd | existing_names | String | Generate unique name |
list_local_branches | path | Vec<String> | List local branches |
checkout_remote_branch | repo_path, branch_name | () | Check out a remote-only branch as a new local tracking branch |
detect_orphan_worktrees | repo_path | Vec<String> | Detect worktrees in detached HEAD state (branch deleted) |
assess_orphan_cleanup | repo_path | Vec<{ path, safe, reason?, live_sessions? }> | Classify every orphan for automatic removal using tracked/untracked status, branch reachability and live sessions in the checkout. |
begin_orphan_cleanup | repo_path, paths | () | Register the open Ask dialog for an agent answer. |
pending_orphan_cleanup_answer | repo_path | bool? | Read the pending answer, or null while unanswered. |
clear_orphan_cleanup | repo_path | () | Clear the pending answer when the dialog closes. |
resolve_worktree_diagnostic_cmd | repo_path, worktree_path, action | () | Fix one unavailable-registration sidebar diagnostic. action=repair runs git worktree repair <path> from the main checkout for a present checkout whose .git pointer is dead; action=prune drops the registration of a deleted folder (never deletes files). The path must be a current missing diagnostic. |
remove_orphan_worktree | repo_path, worktree_path, safe_only?, confirmed_sessions?, expected_fingerprint? | () | Remove a registered detached orphan by filesystem path. A dirty checkout requires the fingerprint from the confirmed assessment. With safe_only, recheck clean status, branch reachability and live sessions immediately before removal. Without it, refuse when a live session in the checkout is not in confirmed_sessions (the session ids the user saw). |
switch_branch | repo_path, branch_name | () | Switch main worktree to a different branch (with dirty-state and process checks) |
merge_and_archive_worktree | repo_path, branch_name, workspace_id, target_branch, after_merge, force?, expected_fingerprint? | MergeArchiveResult | Merge worktree branch into base and archive or delete. A pre-flight counts commits and checks the exact checkout. For archive or delete, an unverified or dirty checkout or one with a live session returns action: "needs_confirmation" before merging. Re-call with force: true and the confirmed lifecycle expected_fingerprint to proceed; a changed fingerprint aborts. A locked checkout is not archived. If conflict cleanup abort fails, the error includes the manual abort command. |
finalize_merged_worktree | repo_path, workspace_id, action, force?, expected_fingerprint? | MergeArchiveResult | Clean up after a completed merge, or explicitly archive a reviewed workspace without merging (action: "archive", force: true, confirmed fingerprint). Uses the same lifecycle review as one-click cleanup and also requires merged commit status before automatic cleanup. Without force, a dirty, unverified, or live checkout returns action: "needs_confirmation" (merged: true — only cleanup stopped). Force requires the confirmed lifecycle expected_fingerprint and rejects changed state. A lock stops archiving. Delete may include branch_delete_warning if safe branch deletion kept the branch. |
get_workspace_lifecycle | repo_path, workspace_id | { archive_checklist, dirty_files, untracked_files, copied_files, live_sessions, warnings, missing_checkout, dirty_fingerprint?, submodule_unpushed_commits, commit_status, removal_safety, error? } | Fresh workspace-id-addressed removal preflight. copied_files lists paths and copy classifications; legacy untracked files are explicitly uncertain. archive_checklist supplies checks: [{ passed, label }], can_delete, archive_explanation, and delete_explanation; Delete recomputes this verdict before mutation. missing_checkout: true identifies a registered checkout whose directory is gone; it has no dirty fingerprint and requires force confirmation. dirty_files counts files a removal discards (null when unavailable — not 0); commit_status is unmerged, in_sync, merged, or unknown; removal_safety is safe, requires_force, or unknown. Unknown never authorizes removal. HTTP twin: GET /worktrees/lifecycle. |
list_base_ref_options | repo_path | Vec<String> | List valid base refs for worktree creation |
run_setup_script | script, cwd | JSON | Run a setup script through sh -c / cmd /C in cwd; returns exit code and captured output |
generate_clone_branch_name_cmd | base_name, existing_names | String | Generate hybrid branch name for clone worktree |
Configuration (config.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
load_app_config | – | AppConfig | Load app settings |
save_app_config | base, config | () | Save app settings |
load_notification_config | – | NotificationConfig | Load notifications |
save_notification_config | base, config | () | Save notifications |
show_native_notification | title, body, target | () | macOS desktop-only alert that retains the Notification Center click and emits native-notification-click for a terminal or Progress target; browser/remote clients cannot call it |
load_ui_prefs | – | UIPrefsConfig | Load UI preferences |
save_ui_prefs | base, config | () | Save UI preferences |
get_config_defaults | preview?: LaunchPreview | ConfigDefaults | Read-only defaults and resolved launch instruction previews; optional draft agent config and global marker flags |
load_repo_settings | – | RepoSettingsMap | Load per-repo settings |
save_repo_settings | base, config | () | Save per-repo settings |
check_has_custom_settings | path | bool | Has non-default settings |
load_repo_defaults | – | RepoDefaultsConfig | Load repo defaults |
save_repo_defaults | base, config | () | Save repo defaults |
load_repositories | – | JSON | Load saved repositories |
save_repositories | config (mutationVersion: 1 keyed delta) | () | Apply repository/group/order/active-selection changes to the latest locked document; same-record conflicts are returned to the caller |
list_stale_temp_repository_candidates | – | StaleTempCandidate[] ({path, displayName}) | Read-only preview of rows classified as stale-temp ghosts (#763-d219); never mutates |
repair_stale_temp_repositories | paths (string[]) | StaleTempRepairSummary ({removed, backupPath}) | Re-validates every path against the classifier on the current on-disk document, refusing the whole request if any no longer matches, then removes the validated rows in one transactional write after backing up the pre-repair document |
load_prompt_library | – | PromptLibraryConfig | Load prompts |
save_prompt_library | base, config | () | Save prompts |
load_notes | – | JSON | Load notes |
save_notes | base, config | () | Save notes |
save_note_image | note_id, data_base64, extension | String (absolute path) | Decode base64 image, validate ≤10 MB, write to config_dir()/note-images/<note_id>/<timestamp>.<ext> |
delete_note_assets | note_id | () | Remove note-images/<note_id>/ directory recursively (no-op if missing) |
get_note_images_dir | – | String | Return config_dir()/note-images/ absolute path |
load_keybindings | – | JSON | Load keybinding overrides |
save_keybindings | base, config | () | Save typed action/key overrides; reject invalid records before persistence |
load_agents_config | – | AgentsConfig | Load per-agent run configs, including optional model defaults, and prevent_alt_screen overrides |
save_agents_config | base, config | () | Save per-agent run configs, including optional model defaults, and prevent_alt_screen overrides |
get_agent_native_status_signals | agent_type | bool | Read effective Claude/Codex launch-scoped status setting; false on native Windows without the bundled tuic.exe |
set_agent_native_status_signals | agent_type, enabled | () | Change launch-scoped status injection for future sessions; native Windows without the bundled tuic.exe rejects without writes |
load_activity | – | ActivityConfig | Load activity dashboard state |
save_activity | base, items | () | Save activity dashboard state |
load_repo_local_config | repo_path | RepoLocalConfig? | Read .tuic.json from repo root; returns null if absent or malformed |
save_repo_local_config | repo_path | () | Write the repo’s effective resolved worktree/branch settings (global defaults + per-repo overrides) to .tuic.json at its root (committable, team-shareable). Preserves fields already in the file (e.g. mcp_upstreams); never writes script fields |
SSH Tunnels (tunnels/tauri_commands.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
list_tunnel_profiles | – | Vec<TunnelProfile> | Load all tunnel profiles (global + per-repo merged) |
save_tunnel_profile | profile: JSON | String (profile ID) | Create or update a tunnel profile. Auto-generates UUID if id is empty. Validates before saving |
delete_tunnel_profile | id | bool | Delete a tunnel profile by ID. Stops the tunnel if running |
start_tunnel | id | String | Start a tunnel by profile ID. Loads the profile, validates, and spawns the SSH process |
stop_tunnel | id | () | Stop a running tunnel by profile ID |
list_active_tunnels | – | Vec<JSON> | List all active tunnels with ID, status, and started_at |
get_tunnel_status | id | JSON | Get the current status of a specific tunnel (starting, connected, reconnecting, stopped, error) |
list_ssh_config_hosts | – | Vec<String> | Parse ~/.ssh/config and return all non-negated, non-wildcard Host entries |
list_discovered_ssh_hosts | – | DiscoveredSshHosts | List non-wildcard ~/.ssh/config aliases and plain ~/.ssh/known_hosts names deduplicated by resolved host and port; hashed known_hosts entries are counted in hashed_count |
probe_discovered_ssh_host | target, port? | SshHostStatus | Probe one discovered entry (known_hosts entries use StrictHostKeyChecking=yes); refuses a host not in the discovered list |
probe_ssh_config_hosts | – | Vec<SshHostStatus> | Probe the ~/.ssh/config aliases (known_hosts names excluded) with bounded concurrency and classify shell, no-shell, authentication-failed and unreachable results |
get_tunnel_audit | id, limit? | Vec<JSON> | Query audit log events for a tunnel (default limit 20). Returns timestamp, kind, and extracted message |
list_ssh_agent_keys | – | SshAgentInfo | Detect SSH agent type (1Password, Secretive, GPG, generic) and list loaded keys via ssh-add -l |
Remote Connections (remote_connection.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
list_remote_connections | – | Vec<RemoteConnection> | Load every configured remote machine from connections.json |
save_remote_connection | base, connection | () | Create with null base or update a remote machine from its loaded snapshot; merges changed fields into the latest record under the config file lock |
delete_remote_connection | id | () | Tear down and delete a remote machine, both vault credentials, and its ephemeral daemon best-effort; an installed service is left for explicit uninstall |
set_remote_connection_relay_pairing | id, bundle | () | Parse and store the relay pairing bundle from tuic-remote --relay-pair in the OS credential vault, or forget it when bundle is empty. Same owner and value-free connections Settings change as the HTTP route |
set_remote_connection_password | id, password | () | Store the Basic Auth password in the OS credential vault, or forget it when password is empty. Never written to connections.json. Publishes a value-free connections Settings change only after vault persistence, through the same owner as HTTP |
remote_connection_password_exists | id | bool | Whether a password is stored. The password itself is never readable — this and the token exchange are the only answers given about it |
fetch_remote_connection_token | id, baseUrl, username | String | Trade the stored password for the daemon’s in-memory session token over GET /api/auth/session-token. Runs in the backend so the password never reaches the WebView. Re-run on every connect: the daemon mints a new token on restart |
install_remote_daemon | id | () | Stage the matching daemon and install/start a systemd user unit or launchd agent, then persist deploy = installed |
uninstall_remote_daemon | id | () | Stop and remove the systemd/launchd service files and persist deploy = on_connect |
Remote Connection Runtime (remote_runtime.rs)
remote_connection.rs above says what a connection is; these say whether it is
up. The state machine — health probe, token exchange, status poll, SSH tunnel and
base URL — runs in Rust so that backend tasks, not only the WebView, can reach a
remote daemon.
| Command | Args | Returns | Description |
|---|---|---|---|
connect_remote_connection | id | () | Bring a connection up. SSH connections may deploy a matching loopback-only daemon first, then authenticate with the vault pairing token; direct and unmanaged connections use the stored password exchange. Idempotent while connecting or connected, so a double click opens one tunnel. Every transition is announced as a remote-connection-status event |
disconnect_remote_connection | id | () | Stop the status poll, forget the token, stop the tunnel |
remote_connection_statuses | – | Vec<RemoteConnectionStatus> | Live status of every connection. base_url, token and protocol_version are present only while connected; update_in_progress is true during a manual or unattended update. A disconnected machine has no route to hand out |
prepare_remote_update | id | UpdatePreview | Select the release or matching local daemon binary and report both build identities and the live session count |
update_and_restart_remote | id, confirmedSessions, expectedSha256 | UpdatePreview | Check the confirmation, update by Direct upload or SSH deployment, and verify the new build after reconnect |
Agent Detection (agent.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
detect_agent_binary | binary | AgentBinaryDetection | Check binary name in PATH or an exact absolute path, version, and cached supports_no_alt_screen help probe |
prepare_agent_launch_args | agent_type, binary_path, args | Vec<String> | Add a supported native-scrollback flag according to the agent setting; probes in a blocking worker with a deadline. HTTP parity: POST /agents/launch-args |
detect_all_agent_binaries | binaries | HashMap<String, AgentBinaryDetection> | Detect the named binaries in parallel, path only (no version or screen-capability lookup) |
detect_claude_binary | – | String | Detect Claude binary |
detect_installed_ides | – | Vec<String> | Detect installed IDEs |
open_default_app | target: String, kind: "url" | "path" | "handler" | () | Host-only default application open; url allows http/https/mailto/tel URLs, handler (owner-confirmed links only) allows a UNC path or a custom-scheme URL and refuses javascript/vbscript/data/blob/about/file and one-letter schemes (UNC becomes smb:// outside Windows), checks path metadata, returns after spawn and reaps the launcher through tuic_core::child_reaping |
open_in_app | path, app, line?, col? | () | Open path in application; line/col are used only by editors that support them |
spawn_agent | pty_config, agent_config | String (session ID) | Spawn agent in PTY |
Agent Session Discovery (agent_session.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
discover_agent_session | agent_type, cwd, claimed_ids, agent_pid, env_overrides | Option<{ sessionId, launchCommand, provider }> | Discover the agent’s session UUID for session-aware resume. IPC and HTTP run filesystem and process reads on the blocking pool. Ego bindings are cached by sessions root and pid, with one-lease pid and writer-lock validation; a miss scans for the latest matching heartbeat. Claude and grok resolve it exactly from their pid→session registry when agent_pid is known; every other agent (and any Claude/grok too old to publish one) falls back to the newest unclaimed session file, which cannot tell two tabs in one folder apart. launchCommand is the command the live process really runs, rebuilt from its argv and env (CLAUDE_CONFIG_DIR=… claude --dangerously-skip-permissions) — a shell alias is expanded before exec, so it is the only record of which config dir holds the session. null for agents with no verified session-flag list, and on Windows, where argv is unreadable. provider is the model provider the session runs on, for ego only: the first segment of model in the pid-leased <EGO_HOME>/sessions/<id>/manifest.json; the sidebar shows it as tooltip text (null when unreadable). The session always uses the ego icon, regardless of provider |
verify_agent_session | agent_type, session_id, cwd, agent_pid, env_overrides | bool | Verify that the session file exists in the agent’s selected profile. A live PID can supply process environment; saved launch environment selects the profile after restart. HTTP parity: POST /agents/verify-session |
Panel Windows (panel_window.rs)
Detaching a panel into its own OS window. Used by the AI Chat panel, the Activity Dashboard and the Git panel.
| Command | Args | Returns | Description |
|---|---|---|---|
open_panel_window | panel_id, title?, params?, width?, height? | () | Open (or focus) a detached panel window. panel_id becomes the window label prefix (panel-{id}). URL: /?mode=panel&panel={id}&{params}. Emits panel-window-closed { panelId } on destroy |
close_panel_window | panel_id | () | Close a detached panel window by ID |
focus_main_window | — | () | Bring the main window to foreground (used by detached panels after cross-window actions) |
The embedded AI engine is gone (#784-0aec)
The embedded ReAct loop, provider registry and model-key storage were removed. ego supplies intelligence over ACP — see ACP client for ego below. PR review, changelog generation and improvement scanning use unattended ego turns.
ai_agent/ retains only tui_detect.rs, which classifies terminal activity. The write-only command knowledge store and its persistence task were removed in #2115-1333. No knowledge accessor command remains.
MCP OAuth 2.1 (mcp_oauth/commands.rs)
OAuth 2.1 authorization for upstream MCP servers. Full RFC 9728 (Protected Resource Metadata) + RFC 8414 (Authorization Server Discovery) flow with PKCE S256. Completion via the tuic://oauth-callback deep link.
| Command | Args | Returns | Description |
|---|---|---|---|
start_mcp_upstream_oauth | name: String | StartOAuthResponse | Begin an OAuth flow for the named upstream. Transitions status to authenticating, returns the authorization URL + AS origin for the consent dialog. PKCE challenge is generated and stored per pending flow |
mcp_oauth_callback | code: String, oauth_state: String | () | Consume the tuic://oauth-callback?code=…&state=… deep link. Exchanges the code for tokens, persists OAuthTokenSet to the OS keyring, transitions upstream to connecting |
cancel_mcp_upstream_oauth | name: String | () | Abort an in-flight OAuth flow. Drops the pending entry and resets upstream status |
MCP Upstream Proxy (mcp_upstream_config.rs, mcp_upstream_credentials.rs)
Commands for managing upstream MCP servers proxied through TUICommander’s /mcp endpoint.
| Command | Args | Returns | Description |
|---|---|---|---|
load_mcp_upstreams | – | UpstreamMcpConfig | Load upstream config from mcp-upstreams.json |
save_mcp_upstreams | base: UpstreamMcpConfig, config: UpstreamMcpConfig, credentials?: {server_id, token, header?}[] | () | Add-time credentials are validated and created under the config lock; failures roll back new vault entries. Apply the caller’s ID-keyed base-to-config delta to the latest locked mcp-upstreams.json, validate it, and hot-reload the exact persisted change. Removing a server or its optional auth field is an explicit deletion; unrelated concurrent changes are preserved |
reconnect_mcp_upstream | name: String | () | Disconnect and reconnect a single upstream by name. Useful after credential changes or transient failures |
get_mcp_upstream_status | – | Vec<UpstreamStatus> | Get live status of all upstream MCP servers. Status values: connecting, ready, circuit_open, disabled, failed, authenticating, needs_auth |
save_mcp_upstream_credential | name: String, token: String, url: String, header?: {name, credential_ref}, replace?: boolean | () | Refuse to overwrite an existing entry unless replace: true explicitly requests an edit. Store a Bearer token or scoped header secret with its intended HTTP origin in the OS credential vault |
delete_mcp_upstream_credential | name: String, header?: {name, credential_ref} | () | Remove a Bearer/OAuth token or a scoped custom header secret (idempotent) |
UpstreamMcpConfig schema
interface UpstreamMcpConfig {
servers: UpstreamMcpServer[];
}
interface UpstreamMcpServer {
id: string; // Unique UUID, used for config diff tracking
name: string; // Namespace prefix — must match [a-z0-9_-]+
transport: UpstreamTransport;
enabled: boolean; // Default: true
timeout_secs: number; // Default: 30 (0 = no timeout, HTTP only)
tool_filter?: ToolFilter; // Optional allow/deny filter
}
type UpstreamTransport =
| { type: "http"; url: string }
| { type: "stdio"; command: string; args: string[]; env: Record<string, string> };
interface ToolFilter {
mode: "allow" | "deny";
patterns: string[]; // Exact names or trailing-* glob prefix patterns
}
Upstream status values
The live registry exposes status via SSE events (upstream_status_changed). Valid status strings:
| Value | Meaning |
|---|---|
connecting | Handshake in progress |
ready | Tools available |
circuit_open | Circuit breaker open, backoff active |
disabled | Disabled in config |
failed | Permanently failed, manual reconnect required |
Agent MCP Configuration (agent_mcp.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
get_agent_mcp_status | agent | AgentMcpStatus | Check MCP config for an agent |
install_agent_mcp | agent | String | Install TUICommander MCP entry |
remove_agent_mcp | agent | String | Remove TUICommander MCP entry |
get_agent_config_path | agent | String | Get agent’s MCP config file path |
get_mcp_bridge_info | — | McpBridgeInfo | Bridge path + ready-to-paste JSON config snippet |
Prompt Processing (prompt.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
extract_prompt_variables | content | Vec<String> | Parse {var} placeholders |
process_prompt_content | content, variables | String | Substitute variables |
resolve_context_variables | repo_path: String | HashMap<String, String> | Resolve git context variables (branch, diff, changed_files, commit_log, etc.) for smart prompt substitution. Best-effort: variables that fail are omitted |
Smart Prompt Execution (smart_prompt.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
execute_headless_prompt | command: String, args: Vec<String>, stdin_content: Option<String>, timeout_ms: u64, repo_path: String, env: Option<HashMap<String,String>> | Result<String, String> | Spawn a one-shot agent process in argv form (no shell — metacharacters in args are literal). Prompt content piped via stdin. Timeout capped at 5 minutes |
execute_shell_script | script_content: String, timeout_ms: u64, repo_path: String | Result<String, String> | Execute shell script content directly via platform shell (sh/cmd). No agent involved — runs the content as-is. Captures stdout. Timeout capped at 60 seconds |
Claude Usage (claude_usage.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
get_claude_usage_api | sessionId? | UsageApiResponse | Fetch rate-limit usage for the Claude session’s credential profile; omitted session selects the default profile. API-key sessions return Claude API-key authentication without credential lookup or HTTP requests |
get_claude_usage_timeline | scope, days? | Vec<TimelinePoint> | Hourly token usage from session transcripts |
get_claude_session_stats | scope | SessionStats | Aggregated token/session stats from JSONL transcripts |
get_claude_project_list | – | Vec<ProjectEntry> | List project slugs with session counts |
get_codex_usage_api | – | CodexUsageApiResponse | Read quota through the shared Codex credential owner |
get_codex_usage_stats | – | CodexStatsResponse | Fetch daily token history and supported lifetime stats through the Codex App Server |
get_grok_usage_api | – | GrokUsageApiResponse | Fetch billing-period usage through Grok Build’s _x.ai/billing ACP extension |
set_terminal_theme_colors | foreground: [u8;3], background: [u8;3], cursor: [u8;3] | () | Publish the resolved terminal theme so the emulator can answer OSC 10/11/12 colour queries |
scope values: "all" (all projects) or a specific project slug. days defaults to 7.
Uses incremental parsing with a file-size-based cache (claude-usage-cache.json) so only newly appended JSONL data is processed on each call. The cache is persisted across app restarts.
Voice Dictation (dictation/)
These commands stay in the root dictation/commands.rs adapter; their audio and speech operations use tuic-dictation. The command names and payloads are unchanged by the crate split.
| Command | Args | Returns | Description |
|---|---|---|---|
start_dictation | source? ("fn", "hotkey", "ui") | () | Start recording; Fn starts are refused after native key release |
stop_dictation_and_transcribe | – | TranscribeResponse | Stop + transcribe. Returns {text, skip_reason?, duration_s, truncated_s}; a capture without sustained speech returns no sustained speech before Whisper, a final transcription skip keeps its specific reason, an empty successful result says no speech detected, and truncated_s counts captured audio lost before transcription |
inject_text | text | String | Apply corrections |
get_dictation_status | – | DictationStatus | Model/recording status plus normalized audio_level (0–1) |
get_model_info | – | Vec<ModelInfo> | Available models |
download_whisper_model | model_name | String | Download model |
delete_whisper_model | model_name | String | Delete model |
get_speech_assets | – | Vec<SpeechAssetInfo> | The ONNX runtime, the speech languages, then every catalogue voice (kind: "voice", with language and voice), each absent/downloading/incomplete/ready |
download_speech_asset | asset | String | Download and install, verifying every pinned sha256. asset is an id from the catalogue allowlist |
cancel_speech_download | asset | String | Abandon a download in flight |
delete_speech_asset | asset | String | Unload the engine, then remove the files |
get_speech_voices | language | Vec<VoiceChoice> | The voices a language (Whisper code) can speak with now: { id, source } with source "default", "downloaded" or "user"; empty while the language is not fully downloaded |
import_speech_voice | language, name, dataBase64 | String | Store a user voice file (base64) at <speech>/user-voices/<language>/<name>.safetensors. Refused with the reason for a bad name, a catalogue voice name, more than 64 MB, a file that is not safetensors, or a voice that does not fit the language’s model |
delete_speech_voice | language, name | String | Remove a user voice file. Absent is success |
preview_speech_voice | language, voice, text | () | Speak text (max 200 characters) in voice on this machine’s speaker with the saved loudness. Needs no hands-free conversation and does not change speech_voice. Refused while a hands-free reply is queued, rendering or playing |
speak_reply | text, turn? | SpokenReply | Queue one spoken reply, max 2000 characters. Returns state: "queued" — never "finished"; poll get_speech_status with the id. turn refuses a reply written for a turn the user talked over |
stop_speech | – | SpeechStatus | Stop now, drop the queue, open a new turn. Returns the status so the caller learns that turn |
pause_speech | – | SpeechStatus | Hold the reply where it is; paused true, speaking false. No-op with nothing playing |
resume_speech | – | SpeechStatus | Continue a reply the user held |
get_speech_status | utterance? | SpeechStatus | Whether anything can be spoken, and optionally what became of one reply. An id no longer remembered reports state: "unknown". language is the conversation’s language — empty under auto before the first turn, which is the one state in which nothing can be spoken |
get_correction_map | – | HashMap<String,String> | Load corrections |
set_correction_map | map | () | Save corrections |
list_audio_devices | – | Vec<AudioDevice> | List input devices |
get_dictation_config | – | DictationConfig | Load saved config. With an activation phrase, the hands-free runtime applies at least 5000 ms of hold-back even when the saved hands_free_hold_back_ms is shorter; hands-free status reports the effective value |
get_voice_targets | – | ChatVoiceTarget[] | List live host-managed AI Chat attachments as { id, name, chatSessionId }; ids are opaque voice targets, not PTY ids |
get_hands_free_default_notice | – | string | The built-in hands-free start notice, sent while hands_free_start_notice is empty |
set_dictation_config | base, config | () | Save only the changes between the loaded base and edited config. A changed language, speechCommand or speech_voice also drops the voice built for the previous one, cancelling what it was speaking; hands_free_spoken_replies=false also cancels it and refuses new speech while dictation stays armed. Edge 401/403 rejection makes speech unavailable for five minutes. Other fields leave the voice alone. hands_free_listening (default true, read at arm time only; false arms a replies-only conversation with no microphone, and arming with it and hands_free_spoken_replies both false is refused). hands_free_earcons (default true) turns the hands-free earcons off; only the frontend reads it. hands_free_notify_model (default true) is read at arm time only — turning it off mid-conversation does not cancel the end notice the model is already owed. hands_free_start_notice (default empty = built-in text) replaces the start notice, also at arm time only, folded to one line |
check_microphone_permission | – | String | Check macOS microphone TCC permission status |
open_microphone_settings | – | () | Open macOS System Settings > Privacy > Microphone |
Native file dialogs (native_dialog.rs)
Desktop-only, therefore INTENTIONALLY_UNMAPPED in transport.ts: the panel
browses the host’s filesystem, and a remote client uses the in-app file
browser instead.
| Command | Args | Returns | Description |
|---|---|---|---|
pick_path | kind ("file"|"files"|"folder"|"save"), title?, defaultPath?, fileName?, filters? | Option<Vec<String>> | Open a native file/folder/save panel. null when the user cancels; always an array otherwise, even for a single pick. Err — never a crash — when the panel cannot be built |
Call it through src/utils/nativeDialog.ts (openDialog/saveDialog), not
directly, and do not import open/save from @tauri-apps/plugin-dialog.
The plugin builds NSOpenPanel/NSSavePanel inside its own main-thread closure,
so when AppKit’s window-server link is interrupted — the state the Mac wakes into
after standby — the binding’s NULL check panics on the main thread and the
process dies with every live PTY session. native_dialog.rs owns that closure so
the unwind is caught and returned as an error. The plugin’s confirm/message
are unaffected (they build NSAlert) and stay as they are.
Filesystem (fs.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
resolve_terminal_path | cwd, candidate | Option<ResolvedFilePath> | Resolve one terminal path candidate against cwd; null on a miss |
resolve_terminal_paths | cwd, candidates | Vec<Option<ResolvedFilePath>> | Batched form, answered positionally: entry i is the result for candidates[i]. One IPC round-trip per terminal screen instead of one per candidate |
resolve_markdown_link | root, currentFile, href | MarkdownLinkTarget | Decode and resolve a rendered Markdown link relative to its file; return a heading, file, missing path, external network target (UNC, never probed; the frontend opens it after owner confirmation), or blocked target. Runs filesystem work on the blocking pool |
list_directory | repoPath, subdir | Vec<DirEntry> | List directory contents; links add symlink_target (link text) and symlink_target_kind (directory, file, unavailable), with size 0 |
get_home_directory | — | String | Return this machine’s home directory for local or remote browsing |
fs_read_file | path | String | Read file contents |
write_file | path, content | () | Write file |
markdown_review_changed_lines | path, baseline?, expected | String? | Current-file changed line ranges from a saved editor baseline; null for missing, unchanged or stale snapshots |
write_file_if_unchanged | repo_path, file, expected, content | bool | Write only when the file still equals expected; false = changed on disk, nothing written (mobile Markdown review) |
create_directory | path | () | Create directory |
delete_path | path | () | Delete file, directory, or symbolic link; links are removed without following their targets |
rename_path | src, dest | () | Rename/move path |
copy_path | src, dest | () | Copy file or directory |
copy_path_abs | from, to | () | Copy a file by absolute paths (cross-repo paste). Rejects directories. |
move_path_abs | from, to | () | Move a file by absolute paths (cross-repo cut+paste); copy+remove fallback across filesystems. |
fs_transfer_remote_paths | connectionId, destDir, paths, allowRecursive | TransferResult | Sender-side coordinator for copying local OS paths onto a connected remote repository using its existing endpoint/token. Streams bounded archives; preserves recursion confirmation and skips existing names. Desktop IPC only (INTENTIONALLY_UNMAPPED): data leaves the machine; Finder source paths cannot be gated to registered roots; HTTP token holders must not trigger exfiltration. |
fs_transfer_paths | destDir, paths, mode ("move"|"copy"), allowRecursive | TransferResult { moved, skipped, errors, needs_confirm } | Move/copy OS paths into a destination directory. Skips silently on name conflicts; returns needs_confirm=true (no-op) when a source is a directory and allowRecursive=false. Used by the drag-drop handler when dropping files onto a folder in the file browser. |
add_to_gitignore | path, pattern | () | Add pattern to .gitignore |
search_files | path, query | Vec<SearchResult> | Search files by name in directory |
search_content | repoPath, query, searchId, caseSensitive?, useRegex?, wholeWord?, limit? | () | Full-text content search; streams results progressively via content-search-batch events, each echoing searchId. Binary files and files >1 MB are skipped. Supports cancellation. |
search_content_all | query, searchId, caseSensitive?, limit? | () | Cross-repo BM25 content search over every ready index; streams via the same content-search-batch events with each match tagged repo_path and every batch echoing searchId. Only repos whose index is built participate (depends on Content Indexing strategy). Shares the cancellation slot with search_content. |
warm_content_index | repoPath | () | Build a repo’s content index in the background, invoked on repo switch. Strategy-gated: under disabled or active_only it returns without scheduling anything, so a repo switch cannot index behind a setting that asked it not to. The POST /fs/warm-index route applies the same gate. |
search_content_all reports why a repo produced nothing, so the UI can tell
“no match” apart from “not searched yet”. Every ContentSearchResult and every
content-search-batch carries repos_searched, repos_pending, and
repos_indexing — the last being the subset of repos_pending with a build
actually in flight. Only that subset justifies telling the user to retry; the
rest are waiting on a scheduling event that may never come.
For both commands, every ContentMatch.match_start/match_end pair is a
zero-based, end-exclusive UTF-16 code-unit range within line_text, matching
JavaScript String.slice semantics for ASCII, accented text, and non-BMP emoji.
Plugin Management (plugins.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
list_user_plugins | pluginIds?: string[] | Vec<PluginManifest> | List valid plugin manifests with backend-derived optional contentSha256; async blocking-pool scan; invalid manifests are logged and skipped |
get_plugin_readme_path | id | Option<String> | Get plugin README.md path |
read_plugin_data | plugin_id, path | Option<String> | Read plugin data file |
write_plugin_data | plugin_id, path, content | () | Write plugin data file |
delete_plugin_data | plugin_id, path | () | Delete plugin data file |
install_plugin_from_zip | path | PluginManifest | Install from local ZIP |
install_plugin_from_url | url | PluginManifest | Install from HTTPS URL |
uninstall_plugin | id | () | Remove plugin and all files |
install_plugin_from_folder | path | PluginManifest | Install from local folder |
register_loaded_plugin | plugin_id | () | Register a plugin as loaded (for lifecycle tracking) |
unregister_loaded_plugin | plugin_id | () | Unregister a plugin (on unload/disable) |
set_plugin_output_watchers | client_id, seq, watchers: [{ id, pattern, flags }] | { applied, rejected } | Replace the OutputWatcher set of one frontend — the patterns the PTY reader thread matches lines against. The frontend pushes its whole set on every add or remove; sets are per client_id, and seq orders the mutations so a stale sync answers applied: false and changes nothing. Tauri IPC sets are released when their WebView navigates or closes. Browser clients have no reliable disconnect signal, so they re-send every 30 s to recover from bounded eviction and keep live sets recent. rejected lists the ids the Rust regex crate cannot compile (lookaround, backreferences, a negated class escape inside a character class); those watchers keep matching in the WebView, which then receives every line. |
Plugin Filesystem (plugin_fs.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
plugin_read_file | path, plugin_id | String | Read file as UTF-8 (absolute path the user can access, 10 MB limit) |
plugin_read_file_base64 | path, max_bytes?, plugin_id | String | Read file bytes as base64 from an absolute path the user can access; default 10 MiB, positive custom budgets clamped to 512 MiB |
plugin_write_file_base64 | path, content, max_bytes?, plugin_id | () | Atomically replace a file from base64 bytes within $HOME; default 10 MiB, positive custom budgets clamped to 512 MiB |
plugin_read_file_tail | path, max_bytes, plugin_id | String | Read last N bytes of file, skip partial first line |
plugin_list_directory | path, pattern?, plugin_id | Vec<String> | List filenames in directory (optional glob filter) |
plugin_watch_path | path, plugin_id, recursive?, debounce_ms? | String (watch ID) | Start watching path for changes |
plugin_unwatch | watch_id, plugin_id | () | Stop watching a path |
plugin_write_file | path, content, plugin_id | () | Write file within $HOME (path-traversal validated) |
plugin_rename_path | src, dest, plugin_id | () | Rename/move path within $HOME (path-traversal validated) |
Plugin HTTP (plugin_http.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
plugin_github_action | plugin_id, account, reference, request | Value | Account-scoped B6/B7 bridge; requires net:http, manifest github provider consent and matching PR reference |
plugin_http_fetch | url, method?, headers?, body?, account?, plugin_id, request_id? | HttpResponse | Make HTTP request (validated against the on-disk manifest allowedUrls; with account, Rust injects that account’s credential under the account host rule) |
plugin_http_cancel | plugin_id, request_id | () | Cancel a plugin-scoped HTTP request, including its response body. |
Code Intelligence / MDKB (mdkb_commands.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
mdkb_status | — | MdkbStatus | Check if mdkb binary is available and daemon connected |
mdkb_outline | repo_path, file_path | Vec<OutlineSymbol> | Get symbol outline (functions, types) for a file |
mdkb_goto_definition | repo_path, file_path, line, col? | DefinitionLocation? | Find definition of symbol at position |
mdkb_references | repo_path, symbol_name | Vec<ReferenceLocation> | Find all callers of a symbol via code_graph |
mdkb_code_find | repo_path, name, kind? | CodeFindResult | Exact symbol lookup by name, optionally filtered by kind. symbols is capped by mdkb; total is the unclamped match count and capped says whether rows were held back (both null when mdkb sent no count) |
install_mdkb | — | String | Download and install mdkb binary |
uninstall_mdkb | — | () | Remove mdkb binary (errors for homebrew/cargo installs) |
install_ego | — | String | Download the latest ego release binary (ego-<os>-<arch>, ego_install.rs), install it through the same routine as install_mdkb (release_install.rs), and save its path as ego_executable. Host-only, like install_mdkb |
Line numbers are 1-based on this boundary. mdkb stores symbol ranges 0-based
but takes a 1-based line as input to symbol_at_position. mdkb_commands::editor_line
shifts every response so line/line_start/line_end reaching the frontend
match CodeMirror’s doc.line(n). Request args (mdkb_goto_definition’s line)
are already 1-based and pass through unchanged.
Each mdkb method has a different response shape — do not assume “a JSON array of symbols”:
| mdkb hook method | result shape |
|---|---|
symbols_in_file | text = stringified bare array |
symbol_at_position | text = stringified object, or the literal "null" |
code_find | text = stringified envelope {total, showing, symbols} |
code_graph | text = prose for agents; the symbols are a separate symbols array on result |
code_graph’s symbols field was added after mdkb 3.7.17. Against an older
daemon the field is absent and the call fails loudly — “no callers” is symbols: [],
so an absent field can only mean a stale daemon and must never be reported as an
empty result.
Plugin CLI Execution (plugin_exec.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
plugin_exec_cli | binary, args, cwd?, plugin_id | String | Execute whitelisted CLI binary, return stdout. Allowed: mdkb. 30s timeout, 5 MB limit. |
Plugin Credentials (plugin_credentials.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
plugin_read_credential | service_name, plugin_id | String? | Read credential from system store (Keychain/file) |
Plugin Registry (registry.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
fetch_plugin_registry | – | Vec<RegistryEntry> | Fetch remote plugin registry index |
Watchers
| Command | Args | Returns | Description |
|---|---|---|---|
start_head_watcher | path | () | Watch .git/HEAD for branch changes |
stop_head_watcher | path | () | Stop watching .git/HEAD |
start_repo_watcher | path | () | Watch .git/ for repo changes |
stop_repo_watcher | path | () | Stop watching .git/ |
start_dir_watcher | path | () | Acquire a shared nonrecursive directory watch; pair each successful start with one stop |
stop_dir_watcher | path | () | Release a directory watch; the last release stops the native watcher |
set_hot_repos | paths: Vec<String> | () | Set repos with active terminals (cold repos get throttled watchers/polling) |
System (lib.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
load_config | – | AppConfig | Alias for load_app_config |
save_config | base, config | () | Alias for save_app_config |
hash_password | password | String | Bcrypt hash |
list_markdown_files | path | Vec<MarkdownFileEntry> | List .md files in dir |
read_file | path, file | String | Read file contents |
get_mcp_status | – | JSON | MCP server status including live tls_active (not Tailscale capability), plus unfiltered native_tools: [{name, summary, description}] Settings inventory (no token — use get_connect_url for QR) |
get_mcp_audit | – | JSON | Body-free MCP tools/call outcome audit (same body as GET /mcp/audit); {enabled:false,records:[]} while mcp_call_audit_enabled is off |
get_mcp_usage | – | JSON | Last 7 days of MCP usage per role (same body as GET /mcp/usage); {enabled:false,roles:[]} while mcp_usage_rollup_enabled is off |
suspended_session_action | request | JSON | Rust-owned durable suspend/resume, metadata sync, list, forget and verified resume resolution. HTTP: POST /sessions/suspended; actions and shapes documented in HTTP API |
mcp_confirm_response | request_id, confirmed | () | Answer a pending ui(action=confirm). HTTP: POST /mcp/confirm-response. Every client is shown the same request and the first answer wins, so an unknown or already-answered id is a no-op, not an error |
get_connect_url | ip | String | Build QR connect URL server-side (token stays in backend) |
check_update_channel | channel | UpdateCheckResult | Check beta/nightly channel for updates (hardcoded URLs, SSRF-safe) |
clear_caches | – | () | Clear in-memory caches |
get_local_ip | – | Option<String> | Get primary local IP |
get_local_ips | – | Vec<LocalIpEntry> | List local addresses in shared pairing/phone-entry preference order: active Tailscale HTTPS, LAN, HTTP-only Tailscale, then other networks |
regenerate_session_token | – | () | Regenerate MCP session token (invalidates all remote sessions) |
fetch_update_manifest | url | JSON | Fetch update manifest via Rust HTTP (bypasses WebView CSP) |
read_external_file | path | String | Read file outside repo (standalone file open) |
get_relay_status | – | JSON | Cloud relay connection status |
get_tailscale_status | – | TailscaleState | Tailscale daemon status (NotInstalled/NotRunning/Running with fqdn, https_enabled) |
Global Hotkey
| Command | Args | Returns | Description |
|---|---|---|---|
set_global_hotkey | combo: Option<String> | () | Set or clear the OS-level global hotkey. There is no getter: the current combo is the global_hotkey field of AppConfig, read through load_config. |
App Logger (app_logger.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
push_log | level, source, message | () | Push entry to ring buffer (survives webview reloads) |
get_logs | level?, source?, limit? | Vec<LogEntry> | Query ring buffer with optional filters |
clear_logs | – | () | Flush all log entries |
Notification Sound (notification_sound.rs)
| Command | Args | Returns | Description |
|---|---|---|---|
play_notification_sound | sound, volume, device? | () | Play a Rust rodio notification sound (question, completion, error, warning, info, or attention) on device, or the system default; every tone releases to zero and drains a short silent tail before the output stream closes |
block_sleep | – | () | Refresh backend-owned sleep prevention; cannot override the user setting |
unblock_sleep | – | () | Refresh backend-owned sleep prevention; cannot release live-work protection |
ACP client for ego (acp_commands.rs)
Drives an ego agent over the Agent Client
Protocol. Every command is a one-line pass-through to AcpClientManager; each
has an identical HTTP route (see docs/api/http-api.md) so a browser or the
PWA gets the same answers, including the same error bodies.
The shared event stream sends turnFailed {message, state} when an accepted
prompt later fails; the event envelope identifies its session and turn.
The binary this launches is not an argument. It comes from the
ego_executable setting, read at each connect, so no caller over IPC or HTTP
can choose what the host runs.
| Command | Args | Returns | Description |
|---|---|---|---|
ai_chat_selection | — | { workspace, sessionId: string | null, replacing: string | null } | Read the backend-owned active conversation for the configured workspace; HTTP GET /acp/chat/selection |
select_ai_chat_conversation | session_id: Option<String>, replacing: Option<String> | () | Persist last-writer-wins selection (null clears); replacing names the tab a compaction successor continues. HTTP PUT /acp/chat/selection with { sessionId, replacing }. Changed snapshots invalidate desktop and SSE clients |
acp_workspace_root | — | String | The directory AI Chat runs in, from ai_chat_workspace (empty = home directory of this host). A missing folder is created; an unusable one is refused with a message naming the setting |
acp_connect | root, optional env: Record<string, string> | AcpConnectionSnapshot | Launch ego with process-local env overrides; supplied env requires a fresh connection (disconnect first when already live). Omitted env adopts the live peer |
acp_reconnect | connectionId, root | AcpConnectionSnapshot | Settle the old connection and start a new generation |
acp_disconnect | connectionId | AcpConnectionSettlement | Ask the child to exit; the snapshot is retained |
acp_kill | connectionId | AcpConnectionSettlement | Kill the child without asking |
acp_connection_snapshot | connectionId | AcpConnectionSnapshot | State, capabilities, attachments, and the journal’s readable range |
acp_subscribe | connectionId, afterSequence, channel | () | Stream AcpStreamFrames over a dedicated Channel. The browser equivalent is a WebSocket, not an HTTP route |
acp_session_new | connectionId, authority | AcpAttachmentSnapshot | session/new |
acp_session_list | connectionId, cwd?, cursor? | ListSessionsResponse | session/list |
acp_session_load | connectionId, sessionId, authority | AcpAttachmentSnapshot | session/load |
acp_session_resume | connectionId, sessionId, authority | AcpAttachmentSnapshot | session/resume |
acp_session_fork | connectionId, sessionId, authority | AcpAttachmentSnapshot | session/fork |
acp_session_delete | connectionId, sessionId | () | session/delete — the session is gone for good |
acp_session_close | connectionId, sessionId | () | Detach without deleting |
acp_session_set_viewed_repo | connectionId, sessionId, viewedRepo? | () | Update or clear the attached chat’s effective repository hint for spoken prompts; no prompt is submitted and cwd is unchanged |
acp_session_prompt | connectionId, sessionId, prompt, viewedRepo? | AcpTurnId | Start a turn or accept it into the server-owned FIFO when one is running. viewedRepo is sent as _meta.tuicommander/viewedRepo, a hint for that turn only |
acp_message_action | connectionId, sessionId, request: { messageId, text, action } | { turnId, reactions } | Send a conversational reaction addition/removal or comment about an exact native message through the original prompt queue. Not evaluation or authorization; offline refusal leaves marks unchanged |
acp_message_reactions | sessionId | Record<string, string[]> | Read backend-persisted accepted marks keyed by native message ID; browser parity: GET /acp/chat/:sessionId/reactions |
acp_session_cancel | connectionId, sessionId | () | Cancel the running turn |
acp_queued_prompt_cancel | connectionId, sessionId, turnId | () | Remove one queued prompt before it reaches ego |
acp_queued_prompt_recall | connectionId, sessionId, turnId | string | Atomically withdraw a queued text-only prompt and return its full text; refuse missing, dispatched, steering-in-flight, or attachment-bearing prompts without removing them |
acp_session_set_config_option | connectionId, sessionId, configId, value | Vec<SessionConfigOption> | Set one option; the agent returns the whole resulting set |
acp_turn_pause | connectionId, sessionId, requestId | EgoHoldResponse | _ego/pause. state may be pending — the hold has not landed yet |
acp_turn_resume | connectionId, sessionId, requestId | EgoHoldResponse | _ego/resume |
acp_session_compact | connectionId, sessionId, requestId | EgoCompactResponse | _ego/compact. A durability_uncertain publication is never retry-safe |
acp_pending_interactions | connectionId | Vec<AcpPendingInteraction> | Questions the agent is waiting on, for a client that was not listening when they were asked |
acp_respond_permission | connectionId, requestId, outcome | AcpInteractionSettlement | Answer a session/request_permission |
acp_respond_elicitation | connectionId, requestId, action | AcpInteractionSettlement | Answer a session/create_elicitation |
acp_one_shot_prepare | — | String | Reserve a single-use owned cancellation handle; unused handles expire after 301s |
acp_one_shot_cancel | requestId | bool | Cancel only the reserved/active one-shot handle; false means it already settled, expired or was cancelled |
story_generate_draft | project, request, requestId | StoryDraft | Consume a prepared handle, run the existing isolated one-shot and validate an unsaved draft; never persists |
acp_one_shot_prompt | root, prompt | EgoTurn | One unattended turn: launch, prompt, shut down. No connection id — it owns the whole lifetime |
Errors are an AcpClientError — code, message, connectionId,
sessionId, operation, retryable — identical on both transports.
acp_one_shot_prompt is the odd one out and deliberately so. It is what a Smart
Prompt in api mode runs on, with no panel open and nobody watching, so its
session is opened with no MCP server and every permission request and
elicitation is refused the instant it arrives. EgoTurn is
{ text, stopReason, declined }; declined separates “ego had nothing to say”
from “ego wanted a tool this mode cannot grant”. The turn is abandoned after
300s, a server-side constant rather than an argument.
ego command line (ego_cli.rs)
Reads and writes ego’s configuration by running ego, for the Settings → AI
Chat page. TUIC stores no API key and makes no provider HTTP call; the one
network call is ego models --refresh, which ego makes, and only when asked.
Four rules hold this surface down:
- The binary is the configured
ego_executable, read per call. No argument names a program. - There is no key parameter. Dedicated operations write only
model,rootsandnetwork, so a caller cannot reachsandboxorpermissions.judgeat all. - A model value may not look like a flag, carry whitespace or a control character, or
contain
"or\— the last two would break out of ego’s TOML string. - A failure carries what ego printed.
ego_providers and ego_set_default_model return an optional EgoProviders.diagnostic alongside usable model data when the health check fails. Doctor exit 1 does not reject the whole response; IPC and HTTP use the same projection.
| Command | Args | Returns | Description |
|---|---|---|---|
ego_providers | refresh? | EgoProviders | config ls --profile=<configured> --json + models --json + doctor --json, joined in the configured AI Chat workspace. The profile flag is omitted for the base. refresh: true adds --refresh, the only call that reaches a provider |
ego_set_default_model | model | EgoProviders | config set --profile=<configured> -- model="<slug>" in the configured AI Chat workspace (profile omitted for the base), then a fresh read — the answer is what ego persisted, not what was sent |
ego_perimeter | – | PerimeterView | Stored config ls --json plus config ls --effective --json in the AI Chat workspace/profile |
ego_set_perimeter_roots | roots: {rootDir, rootAccess, readAllowlist, writableDirs} | PerimeterView | Encode a typed roots=[...] assignment, run config set --, then read back |
ego_set_perimeter_network | enabled: bool | PerimeterView | config set -- network="on" or network="off", then read back |
Perimeter operations select --profile from ego_profile and cwd from
ai_chat_workspace (empty means host HOME); that directory must exist. They
remove ambient EGO_PROFILE so the preview matches the configured ACP profile.
Path strings are TOML-encoded in Rust, never written to the TOML file by TUIC.
Each allowlist is newline-delimited; the primary root is one path. rootAccess
is read or read-write. Paths must be absolute or start with ~/; limits are
128 entries and 64 KiB of path input. Empty fields encode explicit roots=[].
The response contains the edit fields, networkEnabled, selected profile,
effective (ego’s original snake_case JSON schema), execEnforcement
(enforcedByOs, promptOnly, notChecked), and a display-ready preview.
Capability evidence remains exactly what ego reports: a measured string array
or not_checked, with optional capabilities_reason and probe_evidence.
Rust classifies the exec badge: ro needs read_scoped + write_denied,
workspace needs read_scoped + write_scoped, and offline adds no_ip_network.
An empty/partial measured set is Prompt only; unknown evidence is unverified.
The measured form needs its probe reference. off + online is Prompt only,
never a vacuous OS-enforcement success. Headless inspection currently has no
measurement, so it reports not checked and its reason.
All three reads must succeed. A partial answer would render as a tab silently missing one of the three things it exists to show.
Errors are an EgoCliError — code (notConfigured, invalidInput,
launchFailed, commandFailed, unreadableOutput), message, command,
stdout, stderr, exitCode — identical on both transports. command is
spelled by file name only, and the captured output is clipped to 4000
characters on a character boundary.
Private secret form commands
secret_form_bootstrap takes no arguments and checks the native caller window
against the backend-created private window. It is intentionally unmapped: an
HTTP client must already possess the privately delivered capability.
secret_form_submit {submission} checks the same native identity and uses the
same schema and consumption logic as POST /secrets/forms/submit.
Workflow definition and human-decision IPC commands use host Human authority. HTTP equivalents require verified credentials for that authority; local address admission grants LocalApi only. Native story plan_state and plan_view use current integration receipts for workflow-owned plans.
Stored terminal marker coordinates
OSC 133 event line and hook-generated UserInput.line use all-time rows. terminal_scroll_to, terminal_get_lines and search results keep their retained-grid coordinates; callers subtract the current frame historyBase when using stored markers.
Telegram Settings
telegram_settings: safe settings snapshot (enabled,token_set,bot_alias,registered_agent_name(nullable), decimal-stringchats,connected,last_error,last_message_time). Never returns a token or message text.telegram_setup { change }:change.actionistoken(passwordtoken, checksgetMe),pair(returnscode,expires_in_seconds),add_chat/remove_chat(chat_id), orconfigure(enabled). Errors are typed safe Telegram categories.
acp_session_fork accepts optional atMessageId, with the same behavior as the ACP HTTP fork route. Capability snapshots expose forkAtMessage separately from tip fork support.
acp_session_list uses the same complete ancestry projection as HTTP: original ego lineage plus _meta.tuicommander.lineageDepth and disabled deleted-parent placeholders.
acp_chat_open
Arguments: { request: { sessionId?, profile?, workspace?, executable? } }. Returns { connection, sessionId, launch, replayed }. Creates a conversation with its own durable launch options, or reopens the saved sessionId. HTTP equivalent: POST /acp/chat/open with the request object as the body. Global ACP connect defaults remain unchanged.
MCP session action=declare_worktree is intentionally not a Tauri command. It
requires a bound managed caller, which window IPC does not supply. Call it via
HTTP POST /mcp. Its session-worktree-declared push is also emitted to Tauri;
list_active_sessions and HTTP GET /sessions report the persisted declaration
in their existing worktree fields. See MCP backend.
Desktop text clipboard
| Command | Parameters | Returns | Description |
|---|---|---|---|
write_clipboard_text | text: String | () | Write UTF-8 text to the local OS clipboard through arboard. Errors reject the call so copy actions show failure. |
read_clipboard_text | — | String | Read UTF-8 text directly from the local OS clipboard without the macOS Web Clipboard Paste pill. |
Both commands require the desktop feature and run blocking clipboard operations
on worker threads. They have no focus or user-gesture requirement. The clipboard
owner stays alive between calls and is released on application exit. They are
INTENTIONALLY_UNMAPPED: browser clients use navigator.clipboard on their own
machine; HTTP clients cannot read or write the host pasteboard.
Automations
The profiles action lists saved profile names on the addressed machine. The
list_runs action accepts group_failures: true to page grouped identical
failures, with failure_count on the newest representative snapshot. Without
that flag, individual history remains unchanged.
automation_action(input: serde_json::Value) -> Result<serde_json::Value, String>
is an async command that shares parsing, definition edits, history, schedule
previews/presets, UTC run summaries and owner-guarded Run Now with
POST /automations/action. Invoke with {input:{action:"list"}}; response values
and application error messages match HTTP. See the HTTP Automations action table
for every field and reply. Blocking storage/schedule work runs off the main
thread. Run Now executes only on the addressed backend; Once and cron definitions both run.
automation_action also accepts {input:{action:"run",id:"<run id>"}} to fetch a canonical saved run for notification navigation. Native automation click targets are {kind:"automation",id:"<run id>"} on macOS.
Design Mode v2: start_design_mode(sessionId, browser?: "edge" | "chrome", url?: string) opens the dedicated browser profile and installs its native host. HTTP POST /design-mode/start accepts the identical camelCase body. Stop/status and the terminal badge retain their existing shapes. The browser opens on the backend host.
Automation precheck context (#1631-45bf): definitions can opt in with
precheck.inject_output: true (default false). Proceeding checks prefix the
literal prompt with delimited, escaped untrusted stdout capped at 16 KiB;
truncation is marked and stderr is excluded. Empty output and manual bypasses
inject nothing. The run ledger records precheck_context: {injected, bytes} for
the prepared launch prompt, counting escaped stdout bytes before framing/marker.
PR line review commands
get_pr_line_threads(repoPath, prNumber, after?):{headSha, threads, hasNextPage, endCursor}. Threads retain GitHubline,originalLine,diffSide,isOutdated,isResolved, andcommentsconnection; every comment author carriesbot(from the GraphQL actor type), and each thread carries a nullablefindingparsed from its first comment bytuic_git::review_bots(tool,title,severity,severityLabel,category,suggestion,agentPrompt,addressedIn,externalId; untrusted text).get_pr_open_threads(repoPath, prNumber): the{pr_open_threads}smart-prompt variable. A string: a preface, then a fenced untrusted block with one line per unresolved, non-outdated thread (- path:line · tool · severity · title · url, most severe first, at most 30 plus+N more open threads not listed). Each value is flattened to one line without control characters, and the fence is longer than any backtick run in the data.get_pr_thread_comments(repoPath, threadId, after?): GitHub comments connection.set_pr_thread_resolved(repoPath, threadId, resolved): confirmed thread.reply_pr_thread(repoPath, threadId, body): posted comment.submit_pr_draft_review(repoPath, prNumber, draft): posted review. Draft{headSha, body, event, comments}accepts COMMENT, APPROVE, REQUEST_CHANGES; request changes needs a body. Inline comments retain path/line/side/body.
PR action commands
get_pr_action_state(repoPath, prNumber):{id, headSha, baseRefName, state, isDraft, autoMergeRequest, mergeQueueEntry, queueRequired}. Queue entries retain id/position/state; auto-merge requests retain enabledAt/mergeMethod.set_pr_auto_merge(repoPath, prNumber, enabled, mergeMethod?, expectedHeadSha?): confirmed GraphQL payload. Enabling needs a valid merge/squash/rebase method and reviewed head.set_pr_merge_queue(repoPath, prNumber, enqueued, expectedHeadSha?): confirmed GraphQL payload with mergeQueueEntry. Enqueue needs reviewed head; dequeue does not.merge_or_enqueue_pr(repoPath, prNumber, mergeMethod, expectedHeadSha):{action:"enqueued", mergeQueueEntry}or{action:"merged", sha}. Queue-required branches enqueue.rerun_failed_pr_jobs(repoPath, runId):{accepted:true, runId}after GitHub accepts the failed-job rerun, not a claim the new run finished.
post_pr_review and submit_pr_draft_review require a nonempty body for REQUEST_CHANGES and reject unsupported event values.
Core account command
| Command | Arguments | Result | HTTP equivalent |
|---|---|---|---|
account_action | request: AccountAction | Metadata/presence-only action reply | POST /accounts/action, body = request |
The async command delegates to the same owner service as HTTP; disk/vault work runs on the blocking pool. See the account action table.
Private account credential entry
account_secret_form {request} opens the existing isolated native secret window.
The request is {action:"add",account:{provider,host,kind,label,username?}} or
{action:"rotate",id}; it accepts no credential. The reply contains only
{names:[],status:"stored"|"declined"|"failed"}. secret_form_bootstrap and
secret_form_submit require the active native window identity. Account forms
do not expose a mobile capability or accept HTTP bootstrap/submission.
Automation worktree cleanup (#1623-8b2a): Automation runs retain automation/run IDs and the exact created workspace path and ID in their saved snapshot, including after definition deletion. Worktree cleanup is explicit and limited to final runs. The backend resolves the saved identity and rechecks shared Git integration/archive proof, dirt, submodule commits and live sessions; it never forces removal or closes sessions. Shared automation_action actions worktree_preview and cleanup_worktree accept a saved run id on IPC, HTTP, MCP and CLI.
Automation templates (#1622-be11): the shared automation action accepts
templates (catalogue) and template (draft). Draft inputs are template_id,
repository, run_config and optional timezone (host local by default).
Drafts have fresh ids and start disabled; no definition or run is created until
an explicit create action. These actions match across HTTP, IPC, MCP and CLI.
History-anchored viewport scrolling
terminal_scroll_to_anchor accepts { sessionId: string, anchor: number | null } and returns (). The all-time row includes evicted rows, matching historyBase + historySize - displayOffset. Null follows output; a trimmed anchor clamps to the oldest retained row. HTTP uses POST /sessions/:id/terminal/scroll-to-anchor with the same anchor value.
Desktop close policy
request_quit()requests real quit regardless ofapp.close_behavior, with confirmation if enabled and terminal sessions exist.ack_background_snapshot(request_id: string)acknowledges a completed persisted terminal snapshot requested bysnapshot-now { request_id }. Native lifecycle only; intentionally unmapped over HTTP. The desktop waits at most two seconds before hiding.resolve_close(choice: "background" | "quit" | "cancel", remember: bool)answers the pending Rust-owned close dialog. Background and Remember apply only to Ask. A failed save leaves the dialog pending.- These native lifecycle commands are deliberately in
INTENTIONALLY_UNMAPPED; remote clients cannot hide or quit the host.close-dialogcarries{kind: "ask" | "confirm_quit", sessions: number, background_available: boolean}on desktop events and/eventsSSE.
Tasks start-work brief
| Command | Arguments | Returns | Description |
|---|---|---|---|
build_start_work_prompt | repoPath, input: {key, url: string or null, title, body} | String | Read .tuic-start-work.md, substitute sanitized fields once, or preserve the default brief when absent. HTTP: POST /tasks/start-work-prompt. Delivery applies the existing untrusted wrapper and 12,000-character cap. |
Tasks provider bridge
work_item_provider_bridge(input) claims or completes one Rust-issued Tasks provider request. It uses the same input and reply as POST /work-items/provider-bridge; see the HTTP API reference. The command only moves requests and replies; the existing provider port owns tracker calls.
project_work_items / POST /tasks/project: accepts {items, fields, query} using the work-item DTOs. Returns WorkItemGroupedPage with the filtered unique count, no cursor and one unnamed group when no grouping is selected. Pure Rust projection, maximum 1,000 collected items, no provider access or persisted state.
Settings policy foundation (#1786-9cbd): mcp_confirm_response also settles the
existing desktop/mobile dialog for a backend-built settings proposal. It grants
only that connection/target/revision/content-bound proposal once, within its
absolute five-minute lifetime. No new settings IPC command is registered by this
step; the replacement settings transport is a separate cutover.
Open desktop Markdown metadata
| Command | Arguments | Result | HTTP twin |
|---|---|---|---|
sync_open_markdown_tabs | tabs: {id,repoPath,filePath,fsRoot?}[] | void | PUT /config/open-markdown-tabs (loopback only) |
list_open_markdown_tabs | cwd: string | {id,title,relative_path,absolute_path,fs_root}[] | GET /repo/open-markdown-tabs?cwd=... |
The read command runs configuration I/O on the blocking pool. Publication stores
only metadata in memory and invalidates consumers with open-markdown-tabs-changed.
The list is scoped to registered repository/workspace ownership.
design_mode_browser_command(repo_path, action, args) executes an immediate
Design Mode native-port browser command. HTTP parity: POST /design-mode/command.
See the HTTP reference for action arguments and typed error prefixes.
Tasks comment comparison
compare_work_item_comments / POST /tasks/compare-comments accepts {detail, previous, enabled, followed} and returns {snapshot, notify}. detail is the unchanged WorkItemDetail; previous is null or {latest, ids, count} (latest is a UTC timestamp in milliseconds). The pure Rust comparison has no provider IO or persistence. First observations, disabled/unfollowed inputs, older comments and edits are silent. GitHub full comment counts cover normal comments outside the first page. Desktop and HTTP use the same implementation.
resume_session(tuic_session) returns {ok:true,session_id} through the shared Rust wake path. HTTP parity: POST /sessions/wake with {tuicSession}. Live targets are idempotent; failed resume retains the suspended record.
Guarded automated agent input
send_agent_input_if_empty { sessionId, text } -> boolean submits only to a confirmed-idle agent with no awaiting question, tracked draft, or queued command. Checks, split writes, and input bookkeeping share the per-session input transaction with raw UI and HTTP input. HTTP: POST /sessions/{id}/input-if-empty { text }.
Shared settings action (#1787-4778)
settings_action(request: JSON) -> JSON uses the same Rust-generated envelope as POST /settings/action and MCP settings. Native caller authority is host-issued, never deserialized from the request. Typed owner workflows use the same envelope and explicit machine target. Owner transactions remain inventory-gated.
Gated HTTP and IPC edits return confirmation_required with proposalId and do not write.
Confirmation applies only when a change adds authority: enabling or widening a listener, loosening authentication, replacing TLS material or weakening TLS, enabling the relay or changing its destination, adding or replacing an executable, launcher argument or stdio upstream command, and adding a tunnel forward or auto-connect. Narrowing, disabling, lowering a timeout and no-op edits apply directly. The owner’s own Settings window (the native settings_action command) applies every edit directly; HTTP, MCP and other native callers get the proposal flow. No request field can claim owner-window intent.
Replay the exact original edit with approval: "<proposalId>" and confirm: true.
The same request opens the existing all-client human confirmation dialog, waits for the
answer, and, only after approval, commits the exact edit under its original caller.
A decline, expiry, changed edit, caller mismatch or reused approval cannot commit.
HTTP proposal identity uses the source IP, not the ephemeral TCP port; every request
still requires local or authenticated access. MCP callers can continue to use
ui action=confirm proposalId=... followed by an exact replay with approval.
Tunnel forward lists, including empty replacements, require confirmation like tunnel ports.
Audio choice availability (#1908-c327, #1909-0d24)
Existing input/output device enumeration returns the same device objects on success, including a successful empty array. Backend enumeration failure now returns an error rather than an empty array. Internal settings choice refresh reuses those owners; cache-only describe and typed voice asset actions are not new public routes in this change. The settings transport cutover remains separate.
force_retry_provider_recovery_command(sessionId) submits /retry once through the
shared ego recovery transaction. It refuses a non-empty tracked composer and returns
the error to the caller. HTTP equivalent: POST /sessions/{id}/force-retry.
Settings startup ownership
settings_action shares its envelope and recovery behavior with HTTP and MCP; the owner’s Settings window skips human confirmation, but no caller skips owner CAS. Settings startup workflows describes GitHub list_accounts and configured Ego begin_login/login_status, including owner revision checks, a human-operated terminal and credential readback distinct from process completion.
CircleCI credential settings (#1991-bd88)
The machine-scoped circleci.token descriptor is write-only. Read
{action:"get",target:{kind:"machine"},store:"circleci",paths:["/token"]}
through MCP settings, IPC settings_action, or HTTP POST /settings/action.
Readback returns only stored.status and effective.status: set, unset, or
unavailable. It describes the stored TUIC token, not environment or CLI fallbacks.
Use {action:"perform",target:{kind:"machine"},store:"circleci",operation:{action:"set_token",token:"..."}}
or operation:{action:"clear_token"}. Both actions use the existing CircleCI
owner; replies contain only token presence. Clearing the stored token does not
remove CIRCLE_TOKEN or the CircleCI CLI configuration. The Git & GitHub page
continues to show the effective token source. No transport returns the token.
Managed launch transaction
managed_agent_launch(request: object) -> object creates or reads a durable managed-child launch. It shares validation, journal and execution with POST /agents/launch and MCP agent action=launch. See HTTP API for the request, receipt and retry contract. The explicit registered parent, stable name and keep-open policy are set before the prompt can run.
MCP passthrough calls use the same native inbox/output byte-budget validator and
snapshot pager as POST /mcp and HTTP MCP-compatible output; no separate IPC
paging implementation is added. See the paging contract.
Output snapshot references issued through IPC MCP passthrough and HTTP
MCP-compatible output intentionally share local ipc scope for the same
target. They are not authorization tokens; endpoint admission is unchanged.
Frame workload evidence
save_frame_workload(recording: String) -> Result<String, String> writes bounded schema-v1 live grid workload JSON through the same serialized blocking-pool writer as POST /debug/frame-workload. Returns the instance-local capture path. It does not enable capture.
Dictation corrections are also available through settings_action with machine
target and store corrections: discover /replacements records keyed by from,
create/remove records and edit replacement to values with an owner revision.
set_correction_map(map) retains its public arguments and shared TextCorrector
persistence; its host-injected state publishes a value-free change after saving.
The upstream credential save/delete commands retain their public arguments; host-injected state routes both through the shared value-free Settings publisher only after owner persistence. Their HTTP equivalents use the same adapters.
Progress reporting rejects text longer than 500 raw Unicode scalar values before trimming, consistently with HTTP and the native MCP schema (#2007-59f6).
github_diagnostics includes repo_access_errors grouped by account, host and
owner, with per-repository reason (not_found, forbidden or unknown) and
exact message, plus an OAuth app authorization URL for every github.com OAuth group. IPC and HTTP share this DTO.
github_diagnostics accepts optional refresh: boolean (default false). True
clears all accounts’ NOT_FOUND cooldowns before returning diagnostics; HTTP uses
POST /github/diagnostics for this explicit mutation and GET for ordinary reads.
Detached checkout inventory
get_repo_structure and get_repo_summary include detached_worktrees: Array<{path, head, short_head, directory_name, state: "detached"}>, matching HTTP. get_worktree_paths retains its branch-workspace map response. Detached records have no workspace ID and cannot be used in branch actions.
Session usage
| Command | Arguments | Result |
|---|---|---|
get_session_usage | sessionId: string | Session-owned usage snapshot; same shape as GET /sessions/{id}/usage |
This async command runs outside the macOS main thread. Rust selects the owner, profile and exact ego ledger row. Missing usage is an explicit unavailable snapshot, not a zero quota or cost. No messages-generation fallback is used. Quota windows are structured fields (provider, plan, duration, percentage and reset instant), formatted by the same client presenter on desktop and mobile.
get_repo_structure and get_repo_summary also return worktree_diagnostics: Array<{path, branch: string | null, state: "missing" | "duplicate_branch", guidance}>, identical to HTTP. Diagnostics are read-only and have no workspace ID. Discovery does not prune unavailable registrations.
Unavailable detached registrations are excluded from automatic orphan cleanup in both Ask and On modes, including the Ask countdown. They remain repair diagnostics until restored or explicitly removed. Safe-only removal rechecks availability, so a directory moved after assessment cannot be pruned automatically. Explicit user-confirmed removal remains available.
Append-only story notes
add_note and list_notes use the same shared story service on all transports. Notes retain backend actor/time and the subject revision without advancing it. Optional {runId, commandId} receipt references are validated against the same project and plan. See Native stories in the HTTP API for fields, replies, bounds, and append-only semantics.
Ego terminal usage
get_ego_usage({ sessionId }) returns { text: string | null, tooltip?: string, usage_agent: "claude" | "codex" | null }. Ego terminal usage uses the exact live pid lease and ego usage --json --session <id> reports v3–v6. The badge shows the short model name and observed context tokens/capacity. Its tooltip shows the full provider/model. Anthropic models use the existing Claude usage endpoint and ticker; openai-codex models use the existing Codex usage endpoint and ticker. Other providers show model/context only. Ego ledger costs and provider-limit observations do not supply badge quotas; session details still show ledger accounting. Unsupported report versions return an error and log one warning per process, rather than silently emptying the badge. The executable comes from the live terminal, not the AI Chat setting. HTTP parity: GET /ego/usage?sessionId=<id>. Async: child work stays off the macOS main thread.
Archive retention cleanup
sweep_archive_retention(repo_path) returns { deleted: string[], kept: string[] }. The host resolves the configured days; callers cannot supply a deletion threshold. Used by repository refresh. Named kept entries include their reason. It preserves archive refs and uses non-force Git removal. HTTP twin: POST /worktrees/archive-retention.
Unrelated branch integration status
Branch integration queries and workspace lifecycle/monitoring payloads serialize commit_status: "unrelated_history" when no default-branch candidate shares a common ancestor. The response remains successful with no inspection error and integrated: false in branch integration queries. IPC and HTTP use the same backend classifier. Missing refs and other Git errors remain errors; an absent common ancestor is not one.
Codex global hook setup
set_agent_hook_instrumentation(agentType, enabled) and get_agent_hook_state(agentType)
run asynchronously. Codex installation attempts exact native trust; canonical
files without verified current trust return reviewRequired from the state
command. installed requires native readback. The HTTP hook-instrumentation and
hook-state routes use the same owner. Status reads never grant trust. Normal
/hooks review remains available when the installed CLI cannot verify setup.
On native Windows without a usable bundled tuic.exe, hook instrumentation setters return an unsupported error before persistence or hook-file access. The matching HTTP routes use the same command cores. Saved hook preferences remain unchanged.
list_active_sessions returns the same typed agent report/stage projection as HTTP GET /sessions, including host report_at and null stage for unknown/non-live sessions. Contract.
Managed agent inventories expose the same stalled flag across transports. Silence policy.
Waiting items and agent health
boss_attention() -> { items, health, warnings } reads the items that wait on the user (manual checks, unanswered workflow questions and unread reports with their typed report reference) and agent health. The HTTP twin is GET /agents/attention; both offload the shared read-only Rust projection to spawn_blocking. boss-attention-changed carries {} and invalidates the projection on desktop and SSE. No answer, report acknowledgement or digest-link parsing is performed.
Native update installation
install_app_update(rid, onEvent) is desktop-only. rid is the Update resource
returned by the updater plugin to the same WebView; onEvent receives the plugin
compatible Started, Progress, and Finished download events. The command
returns the complete installation error chain, checks macOS extraction space,
and leaves relaunch policy to the existing frontend. It has no HTTP mapping:
remote clients do not own native updater resources or permission to replace the host.
Scheduled neutral bindings
The existing neutral action accepts trigger source scheduled with kind: "schedule",
resource_prefix: "schedule:<binding id>", events: ["due"], and optional draft field
schedule: {"cron":"0 9 * * *","timezone":"UTC","text":"Review the summary"}.
Only scheduled bindings accept that field, and it is required for them.
The installed mapping fields are text (string) and occurrence_ms (integer).
Starts and exact local approval answers use the existing run/Answer envelopes.
See trigger admission.
Plugin random-access reads
plugin_file_size(path, plugin_id) -> u64 and plugin_read_file_range(path, offset, length, plugin_id) -> String require fs:read. Absolute paths follow the existing binary read policy. Range results are exact Base64 bytes, capped at 8 MiB; past EOF and short reads fail. Both commands run filesystem work in the blocking pool.
Provider quota registry
| Command | Parameters | Result | Description |
|---|---|---|---|
get_provider_quotas | none | QuotaView[] | Return current views without a network read. |
get_session_quota_binding | sessionId | SubscriptionKey | null | Return the key bound to the session. |
refresh_provider_quota | key | Result<QuotaView, string> | Request a refresh, limited to once per minute per key and subject to registry backoff and authentication policy. |
provider-quota-changed delivers the changed QuotaView on both Tauri and /events. A SubscriptionKey can include an optional profile. An unsupported named profile is unavailable; it does not use the default profile.
Claude and Codex usage endpoints read the same registry owner as session quota
consumers. The existing response fields stay unchanged. Active provider detail
has a separate timestamp, so passive Codex window updates retain credits,
allowed/reached flags and model availability from the last active read. Claude
retains extra usage and local plan metadata. Codex statistics use only the
separate App Server account/usage/read method, not another quota request.
TUIC SDK
The TUIC SDK provides window.tuic inside iframes hosted by TUICommander, enabling plugins and external pages to interact with the host app: open files, read content, launch terminals, copy to clipboard, receive theme updates, and more.
Two Injection Modes
1. Inline HTML Tabs (Plugins)
Plugins use html tabs — TUIC injects the SDK <script> directly into the iframe content. window.tuic is available immediately on load.
// Plugin panel — window.tuic is injected automatically
tuic.open("README.md"); // relative to active repo
tuic.open("/absolute/path/file.txt", { pinned: true });
tuic.edit("src/App.tsx", { line: 42 });
tuic.terminal(tuic.activeRepo());
See Plugin Authoring Guide for full plugin details.
2. URL Tabs (External Pages)
Tabs created with url load content from a remote server in an iframe. The parent cannot inject scripts into cross-origin iframes, so the page must opt in to the SDK via a postMessage handshake.
Handshake Protocol
┌─────────────┐ ┌─────────────┐
│ TUIC Host │ │ iframe URL │
│ (parent) │ │ (child) │
└──────┬──────┘ └──────┬──────┘
│ iframe onload │
│── tuic:sdk-init ────────────────────────>│
│── tuic:repo-changed ────────────────────>│
│── tuic:theme-changed ───────────────────>│
│ │ creates window.tuic
│ │ dispatches "tuic:ready"
│ │
│ (fallback path — async listeners) │
│<── tuic:sdk-request ──────────────────────│
│── tuic:sdk-init + repo + theme ─────────>│
│ │
│<── tuic:open, tuic:edit, ... ─────────────│ (on user action)
│── tuic:get-file-result ─────────────────>│ (async response)
│── tuic:host-message ────────────────────>│ (push from host)
Both paths are implemented in src/components/PluginPanel/PluginPanel.tsx. The version field carries TUIC_SDK_VERSION so the child can feature-detect.
Step 1: Child Page — Bootstrap Listener
Add this <script> in the <head> of your page, before any framework initialization. It must be synchronous so the listener is registered before the parent’s onload fires.
<script>
(function () {
window.addEventListener("message", function (e) {
if (!e.data || e.data.type !== "tuic:sdk-init") return;
window.tuic = {
version: "1.0",
open: function (path, opts) {
parent.postMessage({ type: "tuic:open", path: path, pinned: !!(opts && opts.pinned) }, "*");
},
edit: function (path, opts) {
parent.postMessage({ type: "tuic:edit", path: path, line: (opts && opts.line) || 0 }, "*");
},
terminal: function (repoPath) {
parent.postMessage({ type: "tuic:terminal", repoPath: repoPath }, "*");
}
};
window.dispatchEvent(new Event("tuic:ready"));
});
})();
</script>
Note: For URL-mode pages, only the basic methods (open, edit, terminal) are shown above. To use the full SDK (activeRepo, getFile, theme, etc.), copy the complete SDK from
src/components/PluginPanel/tuicSdk.tsor use the inline HTML mode.
Step 2: Child Page — React to SDK Availability
Use the tuic:ready event to update your UI (e.g., show an “Open in TUIC” button):
// Alpine.js example
Alpine.data("myApp", () => ({
_tuicReady: false,
get hasTuic() { return this._tuicReady; },
init() {
window.addEventListener("tuic:ready", () => { this._tuicReady = true; });
// If SDK was already initialized before Alpine mounted
if (window.tuic) this._tuicReady = true;
},
tuicOpen(filePath) {
if (window.tuic) window.tuic.open(filePath, { pinned: true });
}
}));
API Reference
Files
tuic.open(path, opts?)
Open a file in a TUIC tab. Images, PDF, HTML, video and audio files open in the preview tab; other files open in the Markdown reader.
| Param | Type | Description |
|---|---|---|
path | string | File path — relative (resolved against active repo) or absolute |
opts.pinned | boolean | Pin the tab (default: false) |
tuic.edit(path, opts?)
Open a file in the external editor.
| Param | Type | Description |
|---|---|---|
path | string | File path — relative or absolute |
opts.line | number | Line number to jump to (default: 0) |
tuic.openUrl(url)
Open an http, https, or mailto URL outside TUICommander from an inline HTML panel. Clicked absolute links with these schemes use the same path automatically. Other schemes are rejected. Cross-origin URL tabs cannot prove a user click to the host, so this method is unavailable there; use the tab menu’s Open in Browser action instead.
tuic.getFile(path): Promise<string>
Read a file’s text content from the active repo.
| Param | Type | Description |
|---|---|---|
path | string | File path — relative or absolute |
Returns a Promise that resolves with the file content string, or rejects with an Error if the file is not found, the path escapes the repo root, or no active repo is set.
tuic.getFile("package.json")
.then(content => JSON.parse(content))
.catch(err => console.error("Cannot read:", err.message));
Host messaging
tuic.send(data) sends plugin data to the host’s openPanel({ onMessage }) callback.
tuic.onMessage(callback) receives the original data passed to PanelHandle.send(data, transfer?).
The host wraps it as { type: "tuic:host-message", payload: data }; transfer lists preserve buffer ownership semantics.
tuic.offMessage(callback) removes the listener. Closing or unloading the panel removes its host bridges.
Path Resolution
All file methods (open, edit, getFile) accept both relative and absolute paths:
- Relative paths (e.g.,
"README.md","src/App.tsx") resolve against the asking panel’s repository, not the focused one. - Absolute paths (e.g.,
"/Users/me/code/repo/file.ts") are matched against known repositories (longest prefix wins).openandeditalso open an absolute path outside every registered repository as an external file, owned by the asking panel’s repository; external files edit unlocked.getFilestill reads only inside a registered repository. - Path traversal (
../) in a relative path that escapes the repo root is blocked and returns an error...segments in an absolute path are resolved before it is classified. ./prefixes are supported and normalized.
tuic.open("README.md"); // → <panel repo>/README.md
tuic.open("src/../README.md"); // → <panel repo>/README.md
tuic.open("/Users/me/repo/file.ts"); // → absolute, matched to repo
tuic.open("/Users/me/Reference/a.md"); // → absolute, outside every repo: external file
tuic.getFile("../../../etc/passwd"); // → rejected (traversal)
tuic:// Links
HTML <a> tags with tuic:// href are automatically intercepted:
<a href="tuic://open/README.md">View README</a>
<a href="tuic://edit/src/main.rs?line=42">Edit main.rs:42</a>
<a href="tuic://terminal?repo=/path/to/repo">Open terminal</a>
Absolute link targets use an extra slash, for example tuic://open//Users/me/repo/file.md. The URL parser collapses redundant leading slashes to one POSIX root before resolving the file. A single leading slash is the URL delimiter for a relative path; Windows drive paths keep their existing meaning.
Repository
tuic.activeRepo(): string | null
Returns the path of the currently active repository, or null if none is active.
var repo = tuic.activeRepo();
// "/Users/me/code/myproject" or null
tuic.onRepoChange(callback)
Register a listener that fires when the active repo changes.
| Param | Type | Description |
|---|---|---|
callback | (repoPath: string | null) => void | Called with the new active repo path |
tuic.offRepoChange(callback)
Unregister a previously registered repo-change listener.
tuic.terminal(repoPath)
Open a terminal in the given repository.
| Param | Type | Description |
|---|---|---|
repoPath | string | Repository root path (absolute) |
UI Feedback
tuic.toast(title, opts?)
Show a native toast notification in the host app.
| Param | Type | Description |
|---|---|---|
title | string | Toast title (required) |
opts.message | string | Optional body text |
opts.level | "info" | "warn" | "error" | Severity (default: "info") |
opts.sound | boolean | Play a notification sound (default: false). Each level has a distinct tone: info = soft blip, warn = double beep, error = descending sweep. |
tuic.toast("Import complete", { message: "42 items imported" });
tuic.toast("Rate limited", { message: "Try again in 30s", level: "warn", sound: true });
tuic.clipboard(text)
Copy text to the system clipboard. Works from sandboxed iframes (which cannot access navigator.clipboard directly).
| Param | Type | Description |
|---|---|---|
text | string | Text to copy |
Messaging
tuic.send(data)
Send structured data to the host. The host receives it via pluginRegistry.handlePanelMessage().
| Param | Type | Description |
|---|---|---|
data | any | JSON-serializable payload |
tuic.onMessage(callback)
Register a listener for messages pushed from the host.
| Param | Type | Description |
|---|---|---|
callback | (data: any) => void | Called with the message payload |
tuic.offMessage(callback)
Unregister a previously registered message listener.
Theme
tuic.theme: object | null
Read-only property containing the current theme as a key-value object. Keys are camelCase versions of CSS custom properties (e.g., --bg-primary → bgPrimary).
var theme = tuic.theme;
// { bgPrimary: "#1e1e2e", fgPrimary: "#cdd6f4", accent: "#89b4fa", ... }
tuic.onThemeChange(callback)
Register a listener that fires when the host theme changes.
| Param | Type | Description |
|---|---|---|
callback | (theme: object) => void | Called with the new theme object |
tuic.offThemeChange(callback)
Unregister a previously registered theme-change listener.
Version
tuic.version: string
The SDK version string (currently "1.0").
Testing the SDK
An interactive test page is included at docs/examples/sdk-test.html. It runs automatic verification of all SDK methods and provides buttons for interactive testing.
How to launch it
From an AI agent (Claude Code, etc.):
Use the TUIC MCP ui tool to open it as an inline HTML tab:
mcp__tuicommander__ui action=tab id="sdk-test" title="SDK Test Suite" html="<contents of docs/examples/sdk-test.html>" pinned=false focus=true
From a plugin:
Register a plugin that serves the HTML content as a panel tab. The SDK is injected automatically into inline HTML tabs.
From JavaScript (dev console or app code):
// Read the file and open as a tab
const html = await invoke("fs_read_file", { repoPath: "/path/to/tuicommander", file: "docs/examples/sdk-test.html" });
mdTabsStore.addHtml("sdk-test", "SDK Test Suite", html);
The test page verifies:
- SDK presence and version
activeRepo()return valueonRepoChangelistener registration- Theme delivery and
onThemeChange onMessagelistener registrationgetFile("README.md")reads file contentgetFile("../../../etc/passwd")is blocked by traversal guard
Interactive buttons test: open, edit, terminal, toast (all levels), clipboard, getFile, and send.
Timing Notes
The <script> bootstrap in the child page must be synchronous and in <head> to guarantee the message listener is registered before the parent’s iframe.onload fires tuic:sdk-init. If your page loads the bootstrap asynchronously (e.g., as an ES module), there is a race condition — the init message may arrive before the listener exists.
If you cannot guarantee synchronous loading, implement a retry: have the child send { type: "tuic:sdk-request" } to the parent on DOMContentLoaded (or whenever the listener is registered), and the parent will respond with tuic:sdk-init. This fallback is fully supported by the host.
Source Files
| File | Description |
|---|---|
src/components/PluginPanel/tuicSdk.ts | SDK script injected into iframes |
src/components/PluginPanel/PluginPanel.tsx | Host-side message handlers |
src/components/PluginPanel/resolveTuicPath.ts | Path resolution (relative + traversal guard) |
docs/examples/sdk-test.html | Interactive test/example page |
Plugin Authoring Guide
Scoped plugin settings (#1785-c7a1)
Loaded plugins expose plugins.<id> descriptors through the Rust settings owner.
plugin_settings_action(pluginId, action) and POST /api/plugins/{id}/settings
share describe/get/set/reset/patch semantics. The backend fixes both the owner and
plugins/<id>/data/config.json; requests cannot choose a store, target or file.
Get requires explicit paths; writes require the last expectedRevision.
A configurable manifest declares settings: { schema, defaults }. The schema is
closed (additionalProperties: false), bounded to 128 annotated leaves, and uses
only the supported object, scalar and scalar-array constraints. Every leaf needs
x-setting sensitivity, apply mode, effect, operations and confirmationClass.
Opaque objects, unsupported constraints, missing metadata and secret defaults are
rejected. A plugin with an existing config file and no schema cannot load or write
that config. Other plugin data, including statistics, remains separate.
Tasks setup stores GitHub Work, Jira and GitLab provider account selections in
data/work-items.json through the plugin data API, not the Settings catalogue.
Configure these providers in Tasks setup; credential accounts stay in Settings > Accounts.
Core supplies typed migrations for build-cleaner, at-capacity-retry,
cache-keepalive, claude-wakeup and the Telegram notifier example. Registration
fills missing defaults without discarding saved values, validates the result and
atomically writes an owner-only config file (0600 on Unix). Numeric settings retain
their typed domains without adding new policy limits to legacy values. Data, config
and lock paths must stay inside the canonical plugin root and cannot be symlinks;
links of the whole plugin directory remain supported. Existing bot tokens
remain available to the notifier’s private config reader; the settings service
returns only set/unset. Catalogue definitions, errors and reload events contain no
stored credentials. Plugin enablement stays in app.disabled_plugin_ids; native
agent usage has no private plugin store.
Patches validate the entire batch against current state under the shared config
and cross-process file locks. Stale revisions conflict, failed writes emit no
reload event, and unload removes descriptors and revokes retained owner handles.
After persistence, plugin-changed is dual-emitted to desktop and SSE so existing
unload/load callbacks reread config. applied: false reports scheduled reload,
not completed callback acknowledgement. Backend unregistration is awaited before
reload registration. General MCP settings publication remains a separate cutover.
Plugins can call host.settings({ action: "get", paths: ["/enabled"] }) and pass
the resulting revision to set/reset/patch. The host supplies its plugin ID.
TUICommander uses an Obsidian-style plugin system. Plugins extend the Activity Center (bell dropdown), watch terminal output, and interact with app state. Plugins are external ES modules loaded at runtime from the user’s plugins directory in the desktop app. The native agent usage feature is initialized separately; there is no built-in plugin registration list.
Quick Start: External Plugin
- Create a directory:
~/.config/com.tuic.commander/plugins/my-plugin/ - Create
manifest.json:
{
"id": "my-plugin",
"name": "My Plugin",
"version": "1.0.0",
"minAppVersion": "0.3.0",
"main": "main.js"
}
Note: All manifest fields use camelCase (
minAppVersion,agentTypes,contentUri) — this matches the Rust serde serialization format. Do not use snake_case.
// ✅ Correct
{ "minAppVersion": "0.5.0", "agentTypes": ["claude"] }
// ❌ Wrong
{ "min_app_version": "0.5.0", "agent_types": ["claude"] }
- Create
main.js(ES module with default export):
const PLUGIN_ID = "my-plugin";
export default {
id: PLUGIN_ID,
onload(host) {
host.registerSection({
id: "my-section",
label: "MY SECTION",
priority: 30,
canDismissAll: false,
});
host.registerOutputWatcher({
pattern: /hello (\w+)/,
onMatch(match, sessionId) {
host.addItem({
id: `hello:${match[1]}`,
pluginId: PLUGIN_ID,
sectionId: "my-section",
title: `Hello ${match[1]}`,
icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor"><circle cx="8" cy="8" r="6"/></svg>',
dismissible: true,
});
},
});
},
onunload() {},
};
- In the desktop app, save a
.js,.mjs, or.jsoncode file outsidedata/to trigger hot reload. New top-level plugin directories and symlinks are discovered live. The watcher does not follow symlink targets, so edits within a linked target may need an explicit reload or restart. Browser/PWA clients do not load these external packages or run this watcher.
Architecture
PTY reader thread (Rust) ──> output_watchers.rs
|
+-- StreamLines (assemble lines — the only assembler)
+-- clean_line (strip ANSI codes + backticks)
+-- OutputWatcherRegistry (compiled patterns, per client)
+-- WatcherLineBatcher (one event per 100ms, lossless)
|
v
pty-watcher-lines event [{text, matched_ids}]
(matched lines only, or every line while a
pattern stays in the WebView)
|
v
pluginRegistry.handleWatcherLines()
|
+-- fire the ids Rust matched
+-- dispatchLine() — the watchers Rust
could not compile, skipping the
ids already fired
|
v
OutputWatcher.onMatch()
|
+-- host.addItem() --> Activity Center bell
|
user clicks item
|
markdownProviderRegistry.resolve(contentUri)
|
MarkdownTab renders content
Tauri OutputParser --> pluginRegistry.dispatchStructuredEvent(type, payload, sessionId)
|
+-- structuredEventHandler(payload, sessionId)
Plugin Lifecycle
- Discovery — Rust
list_user_pluginsscans~/.config/com.tuic.commander/plugins/formanifest.jsonfiles - Validation — Frontend validates manifest fields and
minAppVersion - Import —
import("plugin://my-plugin/main.js")loads the module via the custom URI protocol (on Windows the loader rewrites this tohttp://plugin.localhost/my-plugin/main.js, since WebView2 only serves custom schemes underhttp://{scheme}.localhost/...) - Module check — Default export must have
id,onload,onunload - Register —
pluginRegistry.register(plugin, capabilities)awaitsplugin.onload(host, signal) - Active — Plugin receives PTY lines, structured events, and can use the PluginHost API
- Hot reload — File changes emit
plugin-changedevents; the plugin is unregistered and re-imported. Creating a new top-level plugin directory or symlink after startup also emits the event (the watcher does not descend into symlink targets, so the create of the link itself is the trigger), and the new plugin is discovered and loaded without a restart - Unload —
plugin.onunload()is called only if itsonloadstarted, then tracked registrations are disposed andopenPaneltabs close. Timers, DOM listeners and other resources created directly by the plugin remain its responsibility.
Async startup receives an AbortSignal. Unload or reload aborts it and stops waiting for obsolete startup work. Pass the signal to cancellable operations. After unload, calls through the old host throw an abort error before they can register providers or change host state. The host cannot stop arbitrary plugin code or cancel requests that ignore the signal. A replacement waits for backend teardown, not for obsolete startup to finish. Startup must settle (resolve or reject); the host sets no startup or backend teardown timeout. An active startup that never settles remains loading, and a pending backend teardown blocks replacements for that plugin ID. A replacement removed before its startup begins receives neither onload nor onunload.
Crash Safety
Every boundary is wrapped in try/catch:
import()— syntax errors or missing exports are caught- Module validation — missing
id,onload, oronunloadlogs an error and skips the plugin plugin.onload()— synchronous throws and rejected promises are logged and partial registrations are cleaned up automatically- Watcher/handler dispatch — exceptions are caught and logged, other plugins continue
- UI callbacks registered through
PluginHost(file icons/previews, activity items, context menu actions, ticker messages, dashboards, commands) are isolated the same way; failures are written both to the app log and the plugin’s dedicated log buffer
A broken plugin produces a console error and is skipped. The app always continues.
Manifest Reference
File: ~/.config/com.tuic.commander/plugins/{id}/manifest.json
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Must match the directory name |
name | string | yes | Human-readable display name |
version | string | yes | Plugin semver (e.g. "1.0.0") |
minAppVersion | string | yes | Minimum TUICommander version required |
main | string | yes | Entry point filename (e.g. "main.js") |
description | string | no | Short description |
author | string | no | Author name |
capabilities | string[] | no | Tier 3/4 capabilities needed (defaults to []) |
allowedUrls | string[] | for net:http | Non-empty URL patterns required for HTTP access (e.g. ["https://api.example.com/*"]) |
agentTypes | string[] | no | Agent types this plugin targets (e.g. ["claude"]). Omit or [] for universal plugins. |
binaries | string[] | no | CLI binaries this plugin may execute via exec:cli (e.g. ["rtk", "mdkb"]) |
providers | (string | object)[] | no | Account providers for httpFetch({account}); requires net:http. A core id ("github") or a token-only descriptor registered on load (see Core account registry integration) |
Validation Rules
idmust match the directory name exactlyidmust not be emptymainmust not contain path separators or..- All
capabilitiesmust be known strings (see Capabilities section) minAppVersionmust be <= the current app version (semver comparison)
Plugin Interface
interface TuiPlugin {
id: string;
onload(host: PluginHost, signal?: AbortSignal): void | Promise<void>;
onunload(): void;
}
The onload function receives a PluginHost object — this is your entire API surface. External plugins cannot import app internals; everything goes through host.
PluginHost API Reference
Tier 0: Logging (always available)
host.log(level, message, data?) -> void
Write to the plugin’s dedicated log ring buffer (max 500 entries). Viewable in Settings > Plugins > click “Logs” on any plugin row.
host.log("info", "Plugin initialized");
host.log("error", "Failed to process", { code: 404 });
Levels: "debug", "info", "warn", "error". The optional data parameter accepts any JSON-serializable value and is displayed alongside the message.
Errors thrown inside onload, onunload, output watchers, and structured event handlers are automatically captured to the plugin’s log. Use host.log() for additional diagnostic output. Error count badges appear on plugins with recent errors in the Settings panel.
Tier 1: Activity Center + Watchers + Providers (always available)
All register*() methods return a Disposable with a dispose() method. You do not need to call dispose() manually — all registrations are automatically disposed when onunload() is called (including during hot reload). Panels opened through openPanel also close on unload, and their message, visibility and close bridges are removed. Resources created directly by plugin code, such as timers or DOM listeners, must be released by onunload(). Only call dispose() if you need to dynamically remove a registration while the plugin is still running.
host.registerSection(section) -> Disposable
Adds a section heading to the Activity Center dropdown.
host.registerSection({
id: "my-section", // Must match sectionId in addItem()
label: "MY SECTION", // Displayed as section header
priority: 30, // Lower number = higher position
canDismissAll: false, // Show "Dismiss All" button?
});
host.registerOutputWatcher(watcher) -> Disposable
Watches every PTY output line (after ANSI stripping, backtick removal, and line reassembly).
host.registerOutputWatcher({
pattern: /Deployed: (\S+) to (\S+)/,
onMatch(match, sessionId) {
// match[0] = full match, match[1] = first capture group, etc.
// sessionId = the PTY session that produced the line
host.addItem({ ... });
},
});
Rules:
onMatchmust be synchronous and fast (< 1ms) — it runs on the interface main thread (deferred to a microtask, but a slow handler still blocks painting)pattern.lastIndexis reset before each test (safe to use global flag, but unnecessary)- Input is ANSI-stripped but may contain Unicode (checkmarks, arrows, emoji)
- Arguments are positional:
onMatch(match, sessionId)— NOT destructured
Where the matching runs. The registry sends the pattern source and flags of every
watcher to Rust (set_plugin_output_watchers). The PTY reader thread assembles the
lines, cleans them (tuic-terminal/src/output_watchers.rs, a port of stripAnsi plus the backtick strip),
and tests them against the compiled patterns. Rust is the only line assembler: the
WebView reassembles nothing, so a watcher that registers halfway through a line still
sees that line whole. The WebView is only woken for a line that matched: it receives that
cleaned line, runs your RegExp on it again, and gives onMatch a genuine
RegExpExecArray. The i, m and s flags apply on both sides.
Rust may match a little more than your RegExp does, never less — the re-run in the
WebView filters the difference. One accepted divergence: a pattern that counts UTF-16
code units of astral characters (/^.{2}$/ against an emoji) matches in JavaScript only.
Patterns that stay in the WebView. The Rust regex crate is not a superset of JS
RegExp — it has no lookaround, no backreferences, and no negated class escape inside a
character class ([\D.]). Rust reports such a pattern as rejected instead of compiling
it to something different, and the registry keeps matching that watcher itself, on the
same assembled lines. The behavior of the watcher does not change; only the thread that
tests the line does. One rejected pattern makes Rust ship every line instead of the
matched ones alone, so prefer a portable pattern when you have the choice.
Every line is tested. The events are rate-limited to one per 100 ms, but the lines inside a window are concatenated in order, never dropped, so no line is lost and no line is fabricated from two spliced chunks.
host.registerStructuredEventHandler(type, handler) -> Disposable
Handles typed events from the Rust OutputParser.
host.registerStructuredEventHandler("plan-file", (payload, sessionId) => {
const { path } = payload as { path: string };
host.addItem({ ... });
});
See Structured Event Types for all types and payload shapes.
host.registerMarkdownProvider(scheme, provider) -> Disposable
Provides content for a URI scheme when the user clicks an ActivityItem.
host.registerMarkdownProvider("my-scheme", {
async provideContent(uri) {
const id = uri.searchParams.get("id");
if (!id) return null;
try {
return await host.invoke("read_file", { path: dir, file: name });
} catch {
return null;
}
},
});
host.addItem(item) / host.removeItem(id) / host.updateItem(id, updates)
Manage activity items:
host.addItem({
id: "deploy:api:prod", // Unique identifier
pluginId: "my-plugin", // Must match your plugin id
sectionId: "my-section", // Must match your registered section
title: "api-server", // Primary text
subtitle: "Deployed to prod", // Secondary text (optional)
icon: '<svg .../>', // Inline SVG with fill="currentColor"
iconColor: "#3fb950", // Optional CSS color for the icon
dismissible: true,
contentUri: "my-scheme:detail?id=api", // Opens in MarkdownTab on click
// OR: onClick: () => { ... }, // Mutually exclusive with contentUri
});
host.updateItem("deploy:api:prod", { subtitle: "Rolled back" });
host.removeItem("deploy:api:prod");
Tier 2: Read-Only App State (always available)
host.getActiveRepo() -> RepoSnapshot | null
const repo = host.getActiveRepo();
// { path: "/Users/me/project", displayName: "project", activeBranch: "main", worktreePath: null }
host.getRepos() -> RepoListEntry[]
const repos = host.getRepos();
// [{ path: "/Users/me/project", displayName: "project" }, ...]
host.getActiveTerminalSessionId() -> string | null
const sessionId = host.getActiveTerminalSessionId();
host.getRepoPathForSession(sessionId) -> string | null
Resolves which repository owns a given terminal session by searching all repos and branches for a terminal matching the session ID. Returns null if the session is not associated with any repository (e.g. a standalone terminal or an unknown session ID). Useful in output watcher callbacks where sessionId is provided but you need the repo context.
host.registerOutputWatcher({
pattern: /Deployed: (\S+)/,
onMatch(match, sessionId) {
const repoPath = host.getRepoPathForSession(sessionId);
if (!repoPath) return; // session not tied to a repo
// repoPath = "/Users/me/project"
},
});
host.getSessionCwd(sessionId) -> string | null
Returns the current working directory of the given terminal session, or null if the session is unknown or has no recorded CWD. No capability required.
const cwd = host.getSessionCwd(sessionId);
// → "/Users/me/project" (or null)
host.getActiveRepoPath() -> string | null
Shortcut for the active repository’s path (equivalent to host.getActiveRepo()?.path). Returns null when no repository is active. No capability required.
const repoPath = host.getActiveRepoPath();
host.getClaudeProjectDir(repoPath) -> Promise<string | null>
Resolves a repository path to the absolute path of its Claude Code project directory (~/.claude/projects/<slug>). The slug encoding is handled by the Rust side — plugins should use this instead of constructing paths manually. Requires "fs:read" capability.
const projectDir = await host.getClaudeProjectDir("/Users/me/my-project");
// → "/Users/me/.claude/projects/-Users-me-my-project"
const files = await host.listDirectory(projectDir, "*.jsonl", { sortBy: "mtime" });
host.getPrNotifications() -> PrNotificationSnapshot[]
const prs = host.getPrNotifications();
// [{ id, repoPath, branch, prNumber, title, type }, ...]
host.getSettings(repoPath) -> RepoSettingsSnapshot | null
const settings = host.getSettings("/Users/me/project");
// { path, displayName, baseBranch: "main", color: "#3fb950" }
host.getTerminalState() -> TerminalStateSnapshot | null
Returns the active terminal’s state snapshot.
const state = host.getTerminalState();
// { sessionId, shellState: "busy"|"idle"|null, agentType: "claude"|null,
// agentActive: boolean, awaitingInput: "question"|null, repoPath }
host.onStateChange(callback) -> Disposable
Register a callback for terminal/branch state changes. Fires on agent start/stop, branch change, shell state change, and awaiting-input change.
const sub = host.onStateChange((event) => {
// event.type: "agent-started" | "agent-stopped" | "branch-changed"
// | "repo-changed" | "shell-state-changed" | "awaiting-input-changed"
// event.detail: new branch, repo path, shell state or awaiting-input kind; undefined when cleared
// Branch/repo events describe active navigation (sessionId: null, terminalId: "").
// Shell/awaiting events identify the changed terminal and its session.
});
// sub.dispose() to unsubscribe
State events report changes after the runtime starts; use snapshot getters for initial values. Terminal events observe existing terminal sessions, including remote updates. Branch events describe the active workspace’s branch, not every repository HEAD in the background.
When teardown clears a session and changes its final shell or awaiting-input state together, those events retain the old session ID. A replacement session establishes a new baseline without replaying its initial state.
Tier 2b: Git Read (capability-gated)
These methods require declaring "git:read" in manifest.json. They provide read-only access to git repository state.
host.getGitBranches(repoPath) -> Promise<Array<{ name, isCurrent }>>
const branches = await host.getGitBranches("/Users/me/project");
// [{ name: "main", isCurrent: true }, { name: "feature/x", isCurrent: false }]
host.getRecentCommits(repoPath, count?) -> Promise<Array<{ hash, message, author, date }>>
const commits = await host.getRecentCommits("/Users/me/project", 5);
// [{ hash: "abc1234", message: "fix: bug", author: "name", date: "2026-02-25" }]
host.getGitDiff(repoPath, scope?) -> Promise<string>
const diff = await host.getGitDiff("/Users/me/project", "staged");
// Returns unified diff string
host.getRemotes(repoPath) -> Promise<Array<{ name, url }>>
const remotes = await host.getRemotes("/Users/me/project");
// [{ name: "origin", url: "https://github.com/acme/app.git" }] — credentials in URLs are removed
Tier 3: Write Actions (capability-gated)
These methods require declaring capabilities in manifest.json. Calling without the required capability throws PluginCapabilityError.
host.writePty(sessionId, data) -> Promise<void>
Sends raw bytes to a terminal session. Requires "pty:write" capability.
Prefer
sendAgentInput()for user input.writePtysends raw data — it does not handle Enter key semantics for Ink-based agents. Use it only when you need exact byte control.
await host.writePty(sessionId, "\x03"); // Send Ctrl-C
host.sendAgentInput(sessionId, text) -> Promise<void>
Sends user input to an agent session with correct Enter handling. Requires "pty:write" capability.
Ink-based agents (Claude Code, Codex, etc.) run in raw mode and need Ctrl-U, the text, and \r as three writes with a real time gap between them, so each arrives in its own read (Claude Code strips a Ctrl-U that arrives inside a long text and then refuses the Enter). Shell sessions receive Ctrl-U + text in one write, then \r. This method handles both cases automatically based on the detected agent type.
await host.sendAgentInput(sessionId, "y"); // confirm a prompt
await host.sendAgentInput(sessionId, "explain this code"); // send a message
host.sendAgentInputIfEmpty(sessionId, text) -> Promise<boolean>
Requires "pty:write". For automated idle messages, use host.sendAgentInputIfEmpty(sessionId, text). The backend checks the current idle, awaiting, and tracked composer state and serializes the complete submission with raw user input and its bookkeeping. It returns false without writing when blocked; it returns true after submission. This mode never answers a dialog or drains queued commands. Do not use a separate composer read to authorize a later send. Plugin load and reload replay the current awaiting state and shell state with agent_type. Older hosts do not expose this method, so plugins fail closed instead of falling back to destructive input.
host.openMarkdownPanel(title, contentUri) -> void
Opens a virtual markdown tab and shows the panel. Requires "ui:markdown" capability.
host.openMarkdownPanel("CI Report", "my-scheme:report?id=123");
host.openMarkdownFile(absolutePath) -> void
Opens a local markdown file in the markdown panel. Requires "ui:markdown" capability. The path must be absolute. This is useful for plugins that ship a README.md or other documentation files.
// Open the plugin's own README
host.openMarkdownFile("/Users/me/.config/com.tuic.commander/plugins/my-plugin/README.md");
host.openMarkdownFileBackground(absolutePath) -> boolean
Opens a local Markdown file as a pinned background tab without changing the active pane. Requires "ui:markdown" capability. Returns false when no registered repository owns the absolute path; otherwise returns true, including when the existing tab was reused.
const owned = host.openMarkdownFileBackground("/Users/me/project/plans/feature.md");
host.playNotificationSound(sound?) -> Promise<void>
Plays a notification sound. Requires "ui:sound" capability.
| Parameter | Type | Default | Description |
|---|---|---|---|
sound | string | "info" | One of: "question", "error", "completion", "warning", "info" |
await host.playNotificationSound("error"); // CI failure, build error
await host.playNotificationSound("question"); // input prompt, awaiting user
await host.playNotificationSound("completion"); // task finished
await host.playNotificationSound(); // defaults to "info"
Tier 3b: Filesystem Operations (capability-gated)
These methods provide capability-gated filesystem access. All paths must be absolute. Reads, listings and watches reach any path the user can access, including external volumes and symlink targets outside $HOME; the OS reports access errors and the size limits below still apply. Writes and renames stay within the user’s home directory ($HOME).
host.readFile(absolutePath) -> Promise<string>
Read a file’s content as UTF-8 text. Maximum file size: 10 MB. Requires "fs:read" capability.
const content = await host.readFile("/Users/me/.claude/projects/foo/conversation.jsonl");
host.readFiles(absolutePaths) -> Promise<(string | null)[]>
Read up to 1000 files in one round trip, in request order. An entry is null when that path could not be read — a file that vanished between the listing and the read does not lose the batch. Requires "fs:read" capability.
Use this instead of looping over readFile whenever the paths are known up front: listing a directory and reading every entry costs two calls instead of one per file.
const names = await host.listDirectory(dir, "*.md");
const contents = await host.readFiles(names.map((name) => `${dir}/${name}`));
const found = names
.map((filename, i) => ({ filename, content: contents[i] }))
.filter((entry) => entry.content != null);
host.readFileBase64(absolutePath, options?) -> Promise<string>
Read a file’s raw bytes and return them as a base64 string. The default maximum is 10 MiB. A plugin may request a positive per-call options.maxBytes; the host clamps it to 512 MiB to bound the Base64 and decoded-buffer memory peak. Use this for binary previews such as .docx, images, archives, or bounded in-memory database snapshots. Requires "fs:read" capability.
const encoded = await host.readFileBase64("/Users/me/Documents/spec.docx");
const bytes = Uint8Array.from(atob(encoded), (ch) => ch.charCodeAt(0));
const database = await host.readFileBase64("/Users/me/data.sqlite", {
maxBytes: 256 * 1024 * 1024,
});
host.writeFileBase64(absolutePath, content, options?) -> Promise<void>
Atomically replace a file with bytes supplied as Base64. The default maximum is 10 MiB; a positive options.maxBytes is clamped to the 512 MiB host ceiling. The complete decoded payload is validated before the temporary file is atomically renamed over the destination. Requires "fs:write" capability.
await host.writeFileBase64("/Users/me/data.sqlite", encodedDatabase, {
maxBytes: 256 * 1024 * 1024,
});
host.listDirectory(path, pattern?, options?) -> Promise<string[]>
List filenames in a directory, optionally filtered by a glob pattern. Returns filenames only (not full paths). Requires "fs:list" capability.
Options:
sortBy:"name"(default, alphabetical) or"mtime"(newest first). Use"mtime"to efficiently find the most recently modified file when the directory contains many historical entries.
const files = await host.listDirectory("/Users/me/.claude/projects/foo", "*.jsonl");
// ["conversation-1.jsonl", "conversation-2.jsonl"]
// Find the currently active session JSONL among 100+ historical ones:
const recent = await host.listDirectory(dir, "*.jsonl", { sortBy: "mtime" });
const activeFile = recent[0]; // most recently written
host.watchPath(path, callback, options?) -> Promise<Disposable>
Watch a path for filesystem changes. Emits batched events after a debounce period. Requires "fs:watch" capability.
Each watch delivers only its own events — a plugin with several watches gets one callback per change, not one per watch.
const watcher = await host.watchPath(
"/Users/me/.claude/projects/foo",
(events) => {
for (const event of events) {
console.log(event.type, event.path); // "create" | "modify" | "delete"
}
},
{ recursive: true, debounceMs: 500 },
);
// Later: stop watching
watcher.dispose();
Options:
recursive— Watch subdirectories (default:false)debounceMs— Debounce window in milliseconds (default:300)
FsChangeEvent:
interface FsChangeEvent {
type: "create" | "modify" | "delete";
path: string;
}
host.writeFile(absolutePath, content) -> Promise<void>
Write content to a file within $HOME. Creates parent directories if needed. Refuses to overwrite directories. Max 10 MB. Requires "fs:write" capability.
await host.writeFile("/Users/me/project/stories/new-story.md", "---\nstatus: pending\n---\n# New Story");
host.renamePath(from, to) -> Promise<void>
Rename or move a file within $HOME. Both paths must be absolute. Source must exist. Creates parent directories for destination if needed. Requires "fs:rename" capability.
await host.renamePath(
"/Users/me/project/stories/old-name.md",
"/Users/me/project/stories/new-name.md",
);
host.scanBuildArtifacts(repoPaths, options?) -> Promise<ArtifactEntry[]>
Recursively scan the given repo roots for build-artifact directories (Rust/Maven target/, node_modules/, JS framework caches like .next/.turbo, Python .venv/__pycache__/tool caches, .NET obj/bin, Gradle/CMake/Flutter build/, SwiftPM .build/Pods, .terraform, Elixir _build, Zig, Haskell, Composer vendor/). Read-only. Unlike listDirectory, this ignores .gitignore (artifact dirs are gitignored by design) and stops descending on a match, so a nested node_modules is folded into the outer entry — never double counted. Ambiguously-named dirs (target, bin/obj, build, vendor, …) only count when a toolchain marker sits beside them (e.g. Cargo.toml or pom.xml for target; a .csproj/.fsproj/.vbproj/.sln/.slnx for bin/obj; build.gradle/CMakeLists.txt/pubspec.yaml for build; composer.json for vendor) — a Go sysroot bin or an Xcode PIFCache/target is walked like any other dir, not claimed. The full rule table is ARTIFACT_RULES in src-tauri/src/plugin_fs.rs. Each repoPaths entry is $HOME-scoped and intersected server-side with the app’s actual registered-repository list — a path that isn’t equal to or nested under a genuinely registered repo root is silently dropped, so a plugin cannot widen its scan surface by passing arbitrary $HOME paths. Results for the same normalized set of roots are shared across concurrent callers and reused for 30 seconds. Pass { forceRefresh: true } to bypass a completed cached result; an already-running scan for the same roots is still shared. Requires "fs:scan" capability.
Each ArtifactEntry is { path, kind, size_bytes, trimmable_bytes, last_modified_secs, repo } — kind is one of rust | maven | node | jscache | python | dotnet | gradle | cmake | swift | flutter | terraform | elixir | zig | haskell | php, last_modified_secs is the max mtime of the dir’s direct children (a “last build” signal), and trimmable_bytes is the share of size_bytes that trimBuildArtifact would reclaim (0 for kinds with no separable intermediates). Both sizes come from one filesystem walk.
const entries = await host.scanBuildArtifacts(host.getRepos().map((r) => r.path));
const refreshed = await host.scanBuildArtifacts(host.getRepos().map((r) => r.path), {
forceRefresh: true,
});
host.deleteBuildArtifact(path, repoPaths) -> Promise<void>
Delete a build-artifact directory. Destructive. The backend guard requires (all must hold): the path canonicalizes to a basename that is a known artifact dir, it is strictly inside one of repoPaths (never a repo root itself), that containing root is itself a server-verified registered repository (caller-supplied roots not backed by a real registered repo are dropped — the plugin cannot claim an arbitrary $HOME directory as a “repo”), it is $HOME-scoped, and — for ambiguously-named dirs — the same toolchain marker required by the scanner sits beside it (so Rust src/bin sources are refused). Only then is remove_dir_all run. Requires "fs:delete" capability.
await host.deleteBuildArtifact("/Users/me/project/target", ["/Users/me/project"]);
host.trimBuildArtifact(path, repoPaths) -> Promise<number>
Remove only a build-artifact directory’s regenerable intermediates, leaving the built executables in place. Prefer this over deleteBuildArtifact: a full clean of a Rust target/ also deletes the binary the user may be running, while reclaiming (measured across 5 real repos) only ~1% more disk.
Authorization is deleteBuildArtifact’s, unchanged. On top of it, only paths produced by expanding the matched toolchain rule’s own trim patterns are removed, and each is re-verified to sit strictly inside the artifact dir; symlinked directories are never followed or expanded into.
Which sub-paths count as intermediates is a per-rule table (ARTIFACT_RULES[].trim in src-tauri/src/plugin_fs.rs):
| Kind | Trimmed | Kept |
|---|---|---|
rust (target/) | <profile>/{deps,build,incremental,.fingerprint}, plus the same under a target triple | the linked executables at each profile root |
swift (.build/) | index-build/, <triple>/<profile>/{ModuleCache,index,<Module>.build} | the product binary, Modules/, checkouts/, repositories/ |
maven (target/) | classes, test-classes, generated-*, maven-status, maven-archiver, *-reports | the packaged *.jar/*.war |
gradle (build/) | classes, tmp, kotlin, intermediates, generated, reports, test-results, jacoco | libs/, outputs/, distributions/, install/ |
The bar for inclusion is that rebuilding costs only local CPU — anything needing the network to restore (cargo registry, SwiftPM checkouts/repositories) is deliberately kept. Every other kind has an empty trim list: it reports trimmable_bytes: 0 and rejects a trim, because there is no subset that spares an output (node_modules, .venv, vendor) or because the whole dir is already the intermediate half of a pair (.NET obj vs bin, which the scanner reports as two separate entries).
Check trimmable_bytes > 0 before offering it. It resolves with the bytes it actually reclaimed, measured as it deleted; 0 means there was nothing left to trim. Patch cached totals with that number and never with the trimmable_bytes of the last scan — a build between the scan and the trim moves the estimate, and subtracting it publishes a total no measurement supports. Requires "fs:delete" capability — same blast-radius class, on a subset.
const reclaimed = await host.trimBuildArtifact("/Users/me/project/target", ["/Users/me/project"]);
Tier 3c: Status Bar Ticker (capability-gated)
The status bar has a shared ticker area that rotates messages from multiple plugins. Messages are grouped by priority tier:
| Tier | Priority | Behavior |
|---|---|---|
| Low | < 10 | Shown only in the popover, not in rotation |
| Normal | 10–99 | Auto-rotates every 5s in the ticker area |
| Urgent | >= 100 | Pinned — pauses rotation until cleared |
Plugin tickers and the active agent usage badge share one right-aligned status group, before Offline, PR/CI and panel controls. Matching usage is absorbed into the agent badge, not left beside the cwd. Tickers use priority order, then creation order; they appear side by side when space permits and rotate overflow in the last slot. Narrow layouts truncate labels without overlapping controls.
Users can click the counter badge (e.g. 1/3 ▸) to cycle manually, or right-click the ticker to see all active messages in a popover.
host.setTicker(options) -> void
Set a ticker message in the shared status bar ticker. Preferred API — supports source labels. If a message with the same id from this plugin already exists, it is replaced. Requires "ui:ticker" capability.
host.setTicker({
id: "my-status",
text: "Processing: 42%",
label: "MyPlugin", // Shown as "MyPlugin · Processing: 42%"
icon: '<svg viewBox="0 0 16 16" fill="currentColor">...</svg>',
priority: 10,
ttlMs: 60000,
onClick: () => { /* optional click handler */ },
});
Options:
id— Unique message identifier (scoped to your plugin). Reusing an id replaces the previous message.text— Message text displayed in the ticker rotation.label— Optional human-readable source label shown before the text (e.g."Usage").icon— Optional inline SVG icon.priority— Priority tier (see table above). Default:0.ttlMs— Auto-expire after N milliseconds.0= persistent (must be removed manually). Default:60000.onClick— Optional callback invoked when the user clicks the message text.
host.clearTicker(id) -> void
Remove a ticker message by id. Requires "ui:ticker" capability.
host.clearTicker("my-status");
The removed postTickerMessage and removeTickerMessage aliases are not supported. Use setTicker and clearTicker.
Tier 3d: Panel UI (capability-gated)
host.openPanel(options) -> PanelHandle
Open an HTML panel in a sandboxed iframe tab. Returns a handle for updating content or closing the panel. If a panel with the same id is already open, it will be activated and updated. Requires "ui:panel" capability.
When the panel is hidden, its iframe is unloaded; showing it loads the page again. Keep state that must survive tab switches outside the iframe. This also applies to URL tabs.
const panel = host.openPanel({
id: "my-dashboard",
title: "Dashboard",
html: "<html><body><h1>Hello</h1></body></html>",
onMessage(data) {
// Receive structured messages from the iframe
console.log("Got message from iframe:", data);
// Send response back
panel.send({ type: "response", ok: true });
},
onVisibilityChange(visible) {
// A panel stays mounted behind display:none when another tab is selected.
// Skip work while hidden and catch up here.
if (visible && stale) rebuild();
},
onClose() {
// The tab is gone for good, whoever closed it — the ×, a middle-click, the
// context menu, or your own close(). A hidden panel comes back; a closed one
// does not, and isVisible() reports false for both. Release what the panel
// owned here or it outlives the tab.
watch.dispose();
panel = null;
},
});
// …and query it at any time, e.g. before an expensive re-render
if (!panel.isVisible()) { stale = true; return; }
// Update content later. Returns false once the user has closed the tab — a
// plugin that renders on a timer or a file event should stop, or re-open with
// openPanel() if the render was user-requested.
if (!panel.update("<html><body><h1>Updated</h1></body></html>")) panel = null;
// Send a message to the iframe at any time
panel.send({ type: "refresh", items: [...] });
// Transfer ownership of large buffers instead of copying them. The sender's
// buffer is detached after postMessage succeeds.
panel.send({ type: "database", buffer }, [buffer]);
// Close the panel
panel.close();
Inside the iframe:
<script>
// Send message to host
window.parent.postMessage({ type: "save", config: { ... } }, "*");
// Receive messages from host
// The SDK unwraps the tuic:host-message envelope from panel.send().
window.tuic.onMessage((data) => {
if (data?.type === "response") {
// Use data.ok to update the panel.
}
});
</script>
CSS Base Stylesheet + Theme Injection: Every plugin panel iframe receives two automatic CSS injections:
-
Base stylesheet (
pluginBaseStyles.ts) — a complete design foundation with reset, typography, buttons, inputs, cards, tables, badges, toasts, scrollbars, and empty states. All values use CSS custom properties from the app theme. Plugins get a polished, consistent look without writing any CSS. -
Theme variables — all CSS custom properties from the app’s
:rootare injected (e.g.--bg-primary,--fg-primary,--border,--accent,--error,--warning,--success,--text-on-accent). These match the user’s active theme.
Design strategy: Write minimal plugin-specific CSS that overrides the base. The base provides:
| Base class | Description |
|---|---|
body | Themed background, font, color |
button, .btn | Default button with hover/active states |
button.primary, .btn-primary | Accent-colored button |
button.danger, .btn-danger | Error-colored button |
input, textarea, select | Themed form controls with focus ring |
.card | Bordered container with hover elevation |
table, th, td | Styled table with hover rows |
.badge | Inline label (combine with .badge-p1, .badge-error, .badge-success, .badge-accent, .badge-warning, .badge-muted) |
label, .hint | Form labels and help text |
.filter-bar | Flex row for search/filter UI |
.empty-state | Centered placeholder with .hint |
.toast, .toast.error, .toast.success | Fixed-position notification (add .show to display) |
h1–h4 | Themed headings |
code, a, hr, small | Themed inline elements |
::-webkit-scrollbar | Styled scrollbar matching the app |
Example — minimal plugin CSS:
<style>
/* Only what's specific to this plugin */
body { padding: 16px; }
.my-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px; }
</style>
Dashboard layout classes. For analytics/status dashboards, the base stylesheet also ships a .dashboard/.dash-* class family that mirrors the native Claude Usage dashboard. Use them instead of inventing layout CSS — see docs/plugins-style.md for the full guide, checklist, and class reference.
host.openEditorTab(filePath, repoPath, opts?)
Open a file in the CodeMirror editor tab. Requires "ui:panel" capability.
host.openEditorTab("src/main.ts", "/Users/me/project", { line: 42 });
| Param | Type | Description |
|---|---|---|
filePath | string | Relative or absolute file path |
repoPath | string | Repository root path |
opts.fsRoot | string? | Filesystem root (defaults to repoPath) |
opts.line | number? | Line number to scroll to |
host.registerFilePreview(options) -> Disposable
Register a custom file preview handler for specific extensions. When the user opens a file matching one of the claimed extensions, the onOpen callback is invoked instead of the default editor. Requires "ui:file-preview" capability.
host.registerFilePreview({
extensions: ["csv", "tsv"],
async onOpen(ctx) {
const raw = await host.readFile(`${ctx.fsRoot}/${ctx.filePath}`);
host.openPanel({ id: `csv-${ctx.filePath}`, title: "CSV", html: buildTable(raw) });
},
});
| Param | Type | Description |
|---|---|---|
options.extensions | string[] | File extensions to claim (without dot, case-insensitive) |
options.onOpen | (ctx: FilePreviewContext) => void | Handler called when the user opens a matching file |
FilePreviewContext:
| Field | Type | Description |
|---|---|---|
filePath | string | Relative path within the repo |
repoPath | string | Repository root path |
fsRoot | string | Filesystem root for resolving absolute paths |
On plugin unload, claimed extensions are released and files revert to the default open behavior.
host.registerDashboard(options) -> Disposable
Register a one-click entry point for the plugin’s dashboard. When registered, Settings → Plugins shows a Dashboard button in the plugin row that calls options.open() and automatically closes the Settings panel so the dashboard becomes visible.
host.registerDashboard({
label: "My Plugin", // optional, defaults to "Dashboard"
icon: MY_PLUGIN_ICON, // optional inline SVG string
open: () => openDashboard(host),
});
A plugin may only register one dashboard — calling registerDashboard a second time replaces the previous entry. Dispose the returned handle in onunload (or rely on automatic cleanup via the plugin’s disposable tracker).
host.registerCommand(options) -> Disposable
Register a plugin command that users can bind to a keyboard shortcut. The command appears in Settings → Keyboard Shortcuts under a dedicated “Plugin Commands” section and can be rebound by the user. The action name is auto-namespaced as plugin:<pluginId>:<id>. The active frontend publishes these IDs to the Rust keybinding choices owner; unload removes them from later refreshes. This runtime publication never saves shortcut overrides.
host.registerCommand({
id: "open-dashboard", // unique per plugin
title: "Open My Dashboard", // label in the Shortcuts UI
defaultShortcut: "Cmd+Shift+M",// optional — leave unbound by default
run: () => openDashboard(host),
});
If defaultShortcut conflicts with an existing binding (built-in or another plugin), the command is registered but left unbound; a warning is logged and the user can pick a free combo via Settings. The handle returned is automatically tracked and released on plugin unload.
All standard elements (buttons, inputs, tables) will look correct automatically.
Available CSS variables (from the app’s active theme):
| Variable | Usage |
|---|---|
--bg-primary | Main canvas |
--bg-secondary | Sidebar-level surfaces |
--bg-tertiary | Inputs, elevated surfaces |
--bg-highlight | Hover states |
--fg-primary | Primary text |
--fg-secondary | Labels, secondary text |
--fg-muted | Tertiary text |
--accent | Links, primary actions |
--accent-hover | Hover on accent |
--success | Positive states |
--warning | Caution states |
--error | Error states |
--border | All borders |
--text-on-accent | Text on colored backgrounds |
--text-on-error | Text on error backgrounds |
--text-on-success | Text on success backgrounds |
Security: The iframe uses sandbox="allow-scripts allow-same-origin". This permits scripts and same-origin access; it is not an isolation boundary from the host DOM. Plugin modules also execute in the host JavaScript realm. The close-panel message type is handled as a system message; all other messages are routed to the onMessage callback.
TUIC SDK (window.tuic)
Every plugin iframe automatically receives the TUIC SDK — a lightweight JavaScript API for host integration. The SDK is injected alongside the base CSS and theme variables.
Feature detection:
if (window.tuic) {
// Running inside TUICommander — SDK is available
console.log("TUIC SDK version:", window.tuic.version);
}
Programmatic API:
| Method | Description |
|---|---|
tuic.version | SDK version string (e.g. "1.0") |
tuic.open(path, opts?) | Open a markdown file in a new tab. path is absolute. opts.pinned pins the tab. |
tuic.openUrl(url) | Open an http, https, or mailto URL outside TUICommander. Other schemes are rejected by the host. |
tuic.edit(path, opts?) | Open a file in the code editor. opts.line (1-based) jumps to a line; omit for the top. |
tuic.terminal(repoPath) | Open a new terminal in the given repository. |
// Open a file
tuic.open("/Users/me/myrepo/README.md");
// Open a pinned file
tuic.open("/Users/me/myrepo/docs/guide.md", { pinned: true });
// Open a terminal in a repo
tuic.terminal("/Users/me/myrepo");
// Open a website in the system browser
tuic.openUrl("https://example.com/docs");
Link interception: Standard HTML links with tuic:// scheme are intercepted automatically — no JavaScript required:
Absolute http, https, and mailto links in inline plugin HTML also open through the host when clicked. Relative links remain blocked so an inline panel cannot navigate into the TUICommander app. A panel loading a cross-origin URL cannot have its clicks inspected by the host; use the tab menu’s Open in Browser action if that page needs external links.
<!-- Opens a markdown file -->
<a href="tuic://open/Users/me/myrepo/README.md">View README</a>
<!-- Opens a pinned markdown file -->
<a href="tuic://open/Users/me/myrepo/docs/guide.md" data-pinned>Pinned Guide</a>
<!-- Opens a terminal -->
<a href="tuic://terminal?repo=/Users/me/myrepo">Open Terminal</a>
URL format:
| URL | Action |
|---|---|
tuic://open/<absolute-path> | Open file in markdown tab |
tuic://edit/<absolute-path>?line=N | Open file in the code editor (optional line) |
tuic://terminal?repo=<repo-path> | Open terminal in repository |
Security: Paths are validated against the list of known repositories. Paths outside any registered repo are rejected with a warning. The SDK runs inside the sandbox and communicates with the host exclusively via postMessage.
Tier 3e: Sidebar Plugin Panels (capability-gated)
host.registerSidebarPanel(options) -> SidebarPanelHandle
Register a collapsible panel section in the sidebar, displayed below the branch list for each repo. Requires "ui:sidebar" capability.
Panels display structured data (not HTML) — the app renders items natively for visual consistency with the rest of the sidebar.
interface SidebarPanelOptions {
id: string; // Unique panel ID (scoped to plugin)
label: string; // Section header text
icon?: string; // Inline SVG for header
priority?: number; // Lower = higher in sidebar (default 100)
collapsed?: boolean; // Initial collapsed state (default true)
}
interface SidebarPanelHandle {
setItems(items: SidebarItem[]): void; // Replace all items
setBadge(text: string | null): void; // Header badge (e.g. "3")
dispose(): void; // Remove panel
}
interface SidebarItem {
id: string; // Unique item ID (scoped to panel)
label: string; // Primary text
subtitle?: string; // Secondary text (smaller, muted)
icon?: string; // Inline SVG (fill="currentColor")
iconColor?: string; // CSS color
onClick?: () => void; // Click handler
contextMenu?: SidebarItemAction[]; // Right-click actions
}
interface SidebarItemAction {
label: string;
action: () => void;
disabled?: boolean;
}
Example:
const panel = host.registerSidebarPanel({
id: "active-plans",
label: "ACTIVE PLANS",
icon: '<svg ...>...</svg>',
priority: 10,
collapsed: false,
});
panel.setItems([
{ id: "plan-1", label: "Feature Plan", subtitle: "In Progress · M", onClick: () => openPlan() },
]);
panel.setBadge("1");
Behavior:
- Panels appear inside
RepoSection, below branches, only when the repo is expanded - Items are rendered as native sidebar list items (same style as branches)
- Right-click on items shows a context menu with plugin-defined actions
- Badge appears as a small counter pill on the section header
- On plugin unload, panels are automatically removed
Tier 3f: Context Menu Actions (capability-gated)
host.registerTerminalAction(action) -> Disposable
Register an action in the terminal right-click “Actions” submenu. Requires "ui:context-menu" capability.
The action handler receives a TerminalActionContext snapshot captured at right-click time (not at click time), avoiding race conditions if the user switches terminals between opening the menu and clicking.
interface TerminalActionContext {
sessionId: string | null; // PTY session ID of the right-clicked terminal
repoPath: string | null; // Repository path that owns the terminal
}
interface TerminalAction {
id: string; // Unique action ID (scoped to plugin)
label: string; // Display label in the menu
action: (ctx: TerminalActionContext) => void; // Handler
disabled?: (ctx: TerminalActionContext) => boolean; // Evaluated at menu-open time
}
Example:
const d = host.registerTerminalAction({
id: "restart-agent",
label: "Restart Agent",
action: (ctx) => {
if (ctx.sessionId) host.sendAgentInput(ctx.sessionId, "exit");
},
disabled: (ctx) => !ctx.sessionId,
});
Behavior:
- Actions from all plugins are shown in a flat list under the “Actions” submenu
- The submenu is hidden when no actions are registered
disabledcallback is re-evaluated each time the context menu opens- On plugin unload, actions are automatically removed; stale handler references are no-ops
host.registerContextMenuAction(action) -> Disposable
Register an action in context menus for a specific target type. Requires "ui:context-menu" capability.
type ContextMenuTarget = "terminal" | "branch" | "repo" | "tab";
interface ContextMenuAction {
id: string;
label: string;
icon?: string; // Inline SVG
target: ContextMenuTarget;
action: (ctx: ContextMenuContext) => void;
disabled?: (ctx: ContextMenuContext) => boolean;
}
interface ContextMenuContext {
target: ContextMenuTarget;
sessionId?: string; // terminal, tab
repoPath?: string; // branch, repo, terminal
branchName?: string; // branch only
tabId?: string; // tab only
}
Example:
host.registerContextMenuAction({
id: "deploy",
label: "Deploy Branch",
target: "branch",
action: (ctx) => {
if (ctx.branchName) deploy(ctx.repoPath, ctx.branchName);
},
});
Behavior:
- Actions appear after built-in items, separated by a divider
disabledcallback is re-evaluated each time the context menu opens- On plugin unload, actions are automatically removed
Tier 3g: Credential Access (capability-gated)
host.readCredential(serviceName) -> Promise<string | null>
Read credentials from the system credential store by service name. Returns the raw credential JSON string, or null if not found. Requires "credentials:read" capability.
No consent dialog is shown: the installed manifest declares the credentials:read capability, and that declaration is the disclosure.
const credJson = await host.readCredential("Claude Code-credentials");
if (credJson) {
const creds = JSON.parse(credJson);
const token = creds.claudeAiOauth.accessToken;
}
Platforms:
- macOS: Reads from Keychain (
security find-generic-password -s <service> -w) - Linux/Windows: Reads from
~/.claude/.credentials.json
Tier 3h: HTTP Requests (capability-gated)
host.httpFetch(url, options?) -> Promise<HttpResponse>
httpFetch(url, { signal }) accepts a host-local AbortSignal. A pre-aborted signal starts no request; abort cancels the Rust request while waiting for headers or collecting the body and rejects with AbortError. Unloading the plugin also cancels its active HTTP requests. Signals never cross IPC/HTTP: the host sends a generated UUID and a plugin-scoped cancel command. Requests without a signal keep the same response contract.
Make an HTTP request. Non-2xx status codes are returned normally (not thrown as errors). Requires "net:http" capability. Each request sends the User-Agent tuicommander-plugin/<version> unless you set your own User-Agent header (GitHub REST refuses requests without one).
Plugins can only fetch URLs matching their manifest’s allowedUrls patterns. A manifest declaring net:http with empty or omitted allowedUrls is rejected. An empty list never grants unrestricted access, including localhost or private destinations.
Owner destinations: the owner can list URL patterns in plugin_http_destinations in config.json (same syntax as allowedUrls). Every net:http plugin can then reach them without an account and without a manifest change, localhost and LAN addresses included. The manifest still needs its non-empty allowedUrls list. Only http and https pass. The first URL and each redirect hop are checked. An agent write through the settings API that adds a pattern needs the owner’s confirmation; removing a pattern applies directly. Owner destinations never widen where an account request can start; a redirect hop to another scheme, host or port still loses Authorization.
const resp = await host.httpFetch("https://api.example.com/data", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ key: "value" }),
});
if (resp.status === 200) {
const data = JSON.parse(resp.body);
}
HttpResponse:
interface HttpResponse {
status: number;
headers: Record<string, string>;
body: string;
}
Account requests: httpFetch(url, { account: "<account id>" }) makes Rust inject that account’s credential (Authorization: Bearer <token>, or Basic for Basic accounts). The plugin never sees the token. Rules: the manifest providers list must contain the account’s provider; the URL must be under the account host (same scheme, host and port, path prefix of the site URL; GitHub accounts use their API base, https://api.github.com/ or https://<ghe>/api/); the account host rule replaces the allowedUrls check for the first URL; you must not set Authorization yourself. Each redirect hop must be under the account host, match allowedUrls or match an owner destination, and a hop to another scheme, host or port loses the Authorization header. The token is read again for each request, so a re-entered credential applies at once; a 401 comes back to you as a normal response. Token values in the response body and headers are replaced with [redacted].
const me = await host.httpFetch(`${site}/rest/api/3/myself`, { account: accountId });
Security and limits:
file://,data://,ftp://schemes are blocked- 30-second timeout, 10 MB response limit, max 5 redirects
- Localhost (
localhost,127.0.0.1,::1,[::1],0.0.0.0) is blocked unless explicitly declared inallowedUrlsor in an owner destination - Every HTTP request must match a declared pattern or an owner destination; otherwise an empty list permits no requests
allowedUrls pattern matching:
- Patterns use prefix matching with an optional trailing
*wildcard "https://api.example.com/*"— matches any path under that origin"https://api.example.com/v2/data"— matches that exact URL only"http://localhost:8080/*"— allows localhost on that port (required to unblock localhost)- The URL must start with the pattern prefix (before
*) to match
Tier 3i: File Tail (capability-gated)
host.readFileTail(absolutePath, maxBytes) -> Promise<string>
Read the last N bytes of a file, skipping any partial first line. Useful for reading recent entries from large JSONL files. Requires "fs:read" capability.
const tail = await host.readFileTail("/Users/me/.claude/hud-tracking.jsonl", 512 * 1024);
const lines = tail.split("\n").filter(Boolean);
Tier 3j: CLI Execution (capability-gated)
host.execCli(binary, args, cwd?, options?) -> Promise<string>
Execute a CLI binary declared in the plugin’s manifest and return its stdout. Requires "exec:cli" capability.
Only binaries listed in the manifest’s binaries field can be executed. The on-disk manifest is the source of truth — the frontend cannot grant access to undeclared binaries.
// manifest.json
{ "capabilities": ["exec:cli"], "binaries": ["mdkb"] }
const raw = await host.execCli("mdkb", ["--format", "json", "status"], "/Users/me/project");
const status = JSON.parse(raw);
console.log(status.index.documents); // 1486
// A long indexing or build command raises its own deadline (whole milliseconds).
await host.execCli("mdkb", ["index"], "/Users/me/project", { timeoutMs: 10 * 60 * 1000 });
Security and limits:
- Only binaries declared in the plugin’s
binariesmanifest field can be executed - Working directory must be an absolute path to an existing directory
- Timeout: 30 seconds by default;
options.timeoutMsraises or lowers it, from 1 ms to 3 600 000 ms (1 hour). A zero, fractional, non-finite or larger value is refused, not clamped. The deadline starts when the command starts. - Concurrency: at most 4 commands per plugin run at the same time. A further call waits for a free slot instead of failing; there is no calls-per-minute quota. A slot is released when its command ends, fails, times out or is cancelled.
- Cancellation: a timeout, an output overflow or a dropped request (for example a closed HTTP connection) stops the process and its subprocesses.
- 5 MiB limit per stdout/stderr stream; both streams drain concurrently. Stdout overflow or a read failure stops the process with an error. Stderr beyond 5 MiB is dropped (the child keeps running) and the failure message ends with
[stderr truncated at 5 MiB]. - A non-zero exit returns the captured stderr in the error, with registered secret values masked.
- The declared name resolves to the first executable in the backend PATH (the install folders that desktop-launched apps miss, such as
/opt/homebrew/binand~/.cargo/bin, then the inherited PATH), then~/.local/bin,~/.npm-global/binand~/go/bin. Homebrew comes before the inherited PATH, so the result can differ from your shell. System folders such as/usr/binand version-manager shims on PATH resolve. The program runs with this folder list as its PATH, so a#!/usr/bin/env nodescript finds its interpreter. A symlink runs as found, not as its target. On Windows the name resolves to<name>.exeor<name>.cmd. A declared name is never a path.
Tier 4: Scoped Tauri Invoke (whitelisted commands only)
host.invoke<T>(cmd, args?) -> Promise<T>
Invokes a whitelisted Tauri command. Non-whitelisted commands throw immediately.
Whitelisted commands:
| Command | Args | Returns | Capability |
|---|---|---|---|
read_file | { path: string, file: string } | string | invoke:read_file |
list_markdown_files | { path: string } | Array<{ path, git_status }> | invoke:list_markdown_files |
read_plugin_data | { plugin_id: string, path: string } | string | none (always allowed) |
write_plugin_data | { plugin_id: string, path: string, content: string } | void | none (always allowed) |
delete_plugin_data | { plugin_id: string, path: string } | void | none (always allowed) |
get_input_buffer_content | { sessionId: string } | string | pty:read |
Plugin data storage is sandboxed to ~/.config/com.tuic.commander/plugins/{id}/data/. No capability required — every plugin can store its own data.
// Store cache data
await host.invoke("write_plugin_data", {
plugin_id: "my-plugin",
path: "cache.json",
content: JSON.stringify({ lastCheck: Date.now() }),
});
// Read it back
const raw = await host.invoke("read_plugin_data", {
plugin_id: "my-plugin",
path: "cache.json",
});
const cache = JSON.parse(raw);
Capabilities
What capabilities are, and what they are not. Capabilities gate what a plugin declares — a plugin that never asked for
exec:clicannot reach the exec commands under its own id. They do not gate what a plugin can impersonate. Plugins load with a bare dynamicimport()into the same JavaScript realm as the host, andplugin_idis caller-supplied — it is the only key the Rust capability checks consult. Any plugin can therefore importinvokeitself and pass another plugin’s id to inherit that plugin’s exec, credential and allowed-URL grants.Plugins are isolated from the host’s declared surface, not from each other. Treat every installed plugin as trusted with the union of all installed capabilities, and vet what you install. This matches TUICommander’s threat model — a local tool where the human user is the trust boundary.
A per-plugin token was considered and deliberately rejected: same-realm JavaScript can read it out of the module that holds it, proxy the function that uses it, or monkey-patch the transport, so it would be a boundary in name only. Real isolation requires running each plugin off-realm (a Worker or sandboxed iframe) with a host-created
MessagePortas its only channel to the backend, so a plugin’s identity is the port it was handed rather than a string it supplies. That is tracked as future work, not a gap being quietly ignored.
Capabilities gate access to Tier 3 and Tier 4 methods. Declare them in manifest.json:
{
"capabilities": ["pty:write", "ui:sound"]
}
| Capability | Unlocks | Risk |
|---|---|---|
pty:write | host.writePty(), host.sendAgentInput(), host.sendAgentInputIfEmpty() | Can send input to terminals |
pty:read | host.invoke("get_input_buffer_content", …) | Can read the terminal input line buffer |
ui:markdown | host.openMarkdownPanel(), host.openMarkdownFile(), host.openMarkdownFileBackground() | Can open panels and files in the UI |
ui:sound | host.playNotificationSound(sound?) | Can play sounds (question, error, completion, warning, info) |
ui:panel | host.openPanel() | Can render arbitrary HTML in sandboxed iframe |
ui:ticker | host.setTicker(), host.clearTicker() | Can post messages to the shared status bar ticker |
credentials:read | host.readCredential() | Can read system credentials |
net:http | host.httpFetch() | Requires a non-empty allowedUrls list; requests must match a declared pattern or an owner destination (plugin_http_destinations) |
invoke:read_file | host.invoke("read_file", ...) | Can read files on disk |
invoke:list_markdown_files | host.invoke("list_markdown_files", ...) | Can list directory contents |
fs:read | host.readFile(), host.readFiles(), host.readFileBase64(), host.readFileTail() | Can read any file the user can access (10 MiB default; binary reads may request up to the 512 MiB host ceiling) |
fs:list | host.listDirectory() | Can list any directory the user can access |
fs:watch | host.watchPath() | Can watch any path the user can access for changes |
fs:write | host.writeFile(), host.writeFileBase64() | Can atomically write files within $HOME (10 MiB default; binary writes may request up to the 512 MiB host ceiling) |
fs:rename | host.renamePath() | Can rename/move files within $HOME |
fs:scan | host.scanBuildArtifacts() | Can recursively scan registered repos for build-artifact directories (read-only; ignores .gitignore) |
fs:delete | host.deleteBuildArtifact(), host.trimBuildArtifact() | Can delete a build-artifact directory inside a registered repo (guarded remove_dir_all), or remove just its intermediates |
exec:cli | host.execCli() | Can execute CLI binaries declared in manifest binaries field |
git:read | host.getGitBranches(), host.getRecentCommits(), host.getGitDiff(), host.getRemotes() | Read-only access to git repository state |
ui:context-menu | host.registerTerminalAction() | Can add actions to the terminal right-click “Actions” submenu |
ui:sidebar | host.registerSidebarPanel() | Can register collapsible panel sections in the sidebar |
ui:file-icons | host.registerFileIconProvider() | Can provide file/folder icons for the file browser (e.g. VS Code icon themes) |
ui:file-preview | host.registerFilePreview() | Can claim file extensions and provide custom preview UIs |
Tier 1, Tier 2, and plugin data commands are always available without capabilities.
Agent-Scoped Plugins
Plugins can declare which AI agents they target via the agentTypes manifest field:
{
"id": "claude-usage",
"agentTypes": ["claude"],
...
}
Behavior
- Universal plugins (
agentTypesomitted or[]): receive events from all terminals. This is the default. - Agent-scoped plugins (
agentTypes: ["claude"]): output watchers and structured event handlers only fire for terminals where the detected foreground process matches one of the listed agent types.
What gets filtered
| Dispatch method | Filtered by agentTypes |
|---|---|
registerOutputWatcher callbacks | Yes |
registerStructuredEventHandler callbacks | Yes |
| All other PluginHost methods (Tier 1-4) | No — always available |
How agent detection works
TUICommander polls the foreground process of each terminal’s PTY every 3 seconds (via get_session_foreground_process). The process name is classified into an agent type:
| Process name | Agent type |
|---|---|
claude | "claude" |
gemini | "gemini" |
opencode | "opencode" |
codex | "codex" |
amp | "amp" |
cursor-agent | "cursor" |
goose | "goose" |
droid | "droid" |
git | "git" |
| (anything else) | null (plain shell) |
Timing considerations
Agent detection is polled, not instant. When a user launches claude in a terminal, there is a brief window (up to 3 seconds) before the first poll detects it. During this window, agent-scoped plugins will not receive events from that terminal. This is by design — it avoids false matches during shell startup.
Example: Claude-only plugin
{
"id": "claude-usage",
"name": "Claude Usage Dashboard",
"version": "1.0.0",
"minAppVersion": "0.3.0",
"main": "main.js",
"agentTypes": ["claude"],
"capabilities": ["fs:read", "ui:panel", "ui:ticker"]
}
This plugin’s output watchers will only fire when the terminal is running Claude Code. If the user switches to a plain shell or runs Gemini, the watchers are silently skipped.
Example: Multi-agent plugin
{
"agentTypes": ["claude", "gemini", "codex"]
}
Targets Claude, Gemini, and Codex terminals. All other terminals are ignored.
Content URI Format
scheme:path?key=value&key2=value2
Examples:
plan:file?path=%2Frepo%2Fplans%2Ffoo.mdstories:detail?id=324-9b46&dir=%2Frepo%2Fstories
Icons
All icons must be monochrome inline SVGs with fill="currentColor" and viewBox 0 0 16 16:
const ICON = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor"><path d="..."/></svg>';
Never use emoji — they render inconsistently across platforms.
Hot Reload
Reload batches deduplicate changed enabled IDs and run one discovery request for that batch. Concurrent notifications share a serialized reload queue. Only the selected plugin roots are read; payload hashing reuses unchanged file hashes by modification time and size. Same-version source edits still change the computed payload digest. Full discovery remains available at startup.
When any file in a plugin directory changes, the app:
- Emits a
plugin-changedevent with the plugin ID - Calls
pluginRegistry.unregister(id)(runsonunload, disposes all registrations) - Re-imports the module under a fresh path version (
plugin://<id>/~v<timestamp>/main.js). Relative imports inherit the version, so every file the entry imports is re-read too - Validates and re-registers the plugin
This means you can edit main.js or any file it imports and see changes without restarting the app. The ~v<digits> segment exists only in the URL; do not name a plugin directory that way.
Build & Install
External plugins must be pre-compiled ES modules. Use esbuild:
esbuild src/main.ts --bundle --format=esm --outfile=main.js --external:nothing
Install by copying the directory to:
- macOS:
~/Library/Application Support/com.tuic.commander/plugins/my-plugin/ - Linux:
~/.config/com.tuic.commander/plugins/my-plugin/ - Windows:
%APPDATA%/com.tuic.commander/plugins/my-plugin/
Directory structure:
my-plugin/
manifest.json
main.js
Core-rendered plugin UX
Core renders the following Solid components. Plugins supply manifest metadata and host registrations; they do not import or mount these components.
Manifest UX field inventory
agentTypes, allowedUrls, author, binaries, capabilities, description, id, main, minAppVersion, name, providers, version.
Core UX component inventory
BrowseRow, PluginLogViewer, PluginRow, PluginsTab.
PluginsTab
Settings > Plugins has Installed and Browse views. Installed lists loaded/discovered plugin state. Browse reads community registry entries and offers install, update and refresh actions. Installation accepts ZIP archives. The manifest id identifies the package, main selects its module, and minAppVersion controls compatibility. author is optional metadata. allowedUrls, agentTypes, binaries and providers drive host access/event routing, not editable settings controls.
PluginRow
The Installed row shows manifest name (falls back to id), version, description and capabilities. It shows load errors, error counts and available updates. Its toggle persists enabled state; Logs expands PluginLogViewer; external packages can be uninstalled. A README.md adds a documentation button. host.registerDashboard({ label?, icon?, open }) adds a dashboard button: core closes Settings before calling open. Register only one dashboard per plugin. host.registerCommand({ id, title, defaultShortcut?, run }) adds a rebindable entry under Settings > Keyboard Shortcuts > Plugin Commands.
PluginLogViewer
The expanded Logs view shows the plugin ring buffer’s timestamp, level and message, or an empty state. Use host.log(level, message, data?); host boundary errors are captured automatically.
BrowseRow
The Browse row shows registry name, version, description, author, tags and minimum app version. It offers Install for an absent package, Update when a newer version is available, or Installed for the current version. Registry metadata is separate from the installed manifest.
Settings schema and Tasks views
Tasks list
Core TasksList consumes the async WorkItemProvider port. Providers supply
account and provider IDs, a display name, field descriptors, saved filters and
list(query, signal). Core renders Solid controls and virtual rows; providers
return data only. Source selection partitions cached pages by provider and
account. Queries include filters, saved-filter ID, search, sort and cursor.
Search waits 250 ms after input; sorting and filters run in the provider.
Grouping calls grouped(query, signal) with groupBy; core renders the returned
group names and members without inferring membership.
nextCursor enables Load more; repeated cursors stop pagination, and repeated
item references update the existing row. The cache holds at most 32 pages.
An obsolete request cannot replace current rows. A failed refresh retains
available rows and marks them stale. Detail data is requested by the detail
view after the host receives onOpen(reference). Shell mounting is separate.
The optional manifest settings: { schema, defaults } registers a scoped settings owner. Core renders one searchable Integrations page per live plugin catalogue and removes it on unload. All reads, edits and resets use the existing revision-checked plugin settings service. Titles and descriptions label controls; secrets show only set/unset. Objects group leaves; string enums render selects, booleans toggles, integers and numbers numeric inputs. Bounded arrays use multi-selects for string enums, lists for strings, and JSON inputs for other item types. Read-only fields render status controls. Plugins do not import core Settings components or save a second configuration file.
GitHub Work adapter status
plugins/github-work/provider.js exports createGitHubProvider against the A4
contract and an injected account-scoped fetch port. It returns data only; core owns
rendering and start-work execution. Recorded GitHub fixtures cover REST read shapes.
The adapter does not receive tokens or maintain a separate rate limiter.
The plugin lifecycle and manifest use host.httpFetch(url, {account}) from
story 1697-4cdc; the catalog lists GitHub Work. Configure data/config.json with
account IDs and repositories as described in the module README. B6/B7 core ports and the duplicate-picker consumer also need integration.
The current host.invoke whitelist must not be bypassed to reach core PR commands.
Projects v2 success paths remain unverified because the recording credential lacks
project for writes (read:project alone permits only reads). See the module README for the open integration tasks.
Plugin Management (Settings > Plugins)
The Settings panel has a Plugins tab with two sub-tabs:
Installed
- Lists external plugins with toggle, logs, and uninstall buttons; native agent usage is managed in Settings > Agents
- The UI retains a legacy “Built-in” badge path, but no built-in plugin packages are registered by the current startup code
- Error count badges appear on plugins with recent errors
- “Logs” button opens an expandable log viewer showing the plugin’s ring buffer
- “Install from file…” button opens a file dialog accepting
.ziparchives
Browse
- Shows plugins from the community registry (fetched from GitHub)
- “Install” button downloads and installs directly
- “Update available” badge when a newer version exists or equal-version payloads differ
- “Refresh” button forces a new registry fetch (normally cached for 1 hour)
Enable/Disable
Plugin enabled state is persisted in AppConfig.disabled_plugin_ids. Disabled plugins appear in the Installed list but are not loaded.
ZIP Plugin Installation
Plugins can be distributed as ZIP archives:
- From Settings: Click “Install from file…” in the Plugins tab
- From URL: Use
tuic://install-plugin?url=https://example.com/plugin.zip - From Rust:
invoke("install_plugin_from_zip", { path })orinvoke("install_plugin_from_url", { url })
ZIP requirements:
- Must contain a valid
manifest.json(at root or in a single top-level directory) - All paths are validated for zip-slip attacks (no
..traversal) - If updating an existing plugin, the
data/directory is preserved
Deep Link Scheme (tuic://)
TUICommander registers the tuic:// URL scheme for external integration:
| URL | Action |
|---|---|
tuic://install-plugin?url=https://... | Download ZIP, show confirmation, install |
tuic://open-repo?path=/path/to/repo | Switch to repo (must already be in sidebar) |
tuic://settings?tab=plugins | Open Settings to a specific tab |
tuic://open/<path> | Open markdown file in tab (iframe SDK only) |
tuic://terminal?repo=<path> | Open terminal in repo (iframe SDK only) |
Security: install-plugin requires HTTPS URLs (plain http:// only for localhost and loopback addresses, and redirects are checked the same way) and shows a confirmation dialog. open-repo only accepts paths already in the repository list. open and terminal validate paths against known repos (available only inside plugin iframes via the TUIC SDK, not as OS-level deep links).
Plugin Registry
The registry is a JSON file hosted on GitHub (sstraus/tuicommander-plugins repo). The app fetches it on demand (Browse tab) with a 1-hour TTL cache.
Registry entries include: id, name, description, author, latestVersion, minAppVersion, capabilities, downloadUrl, and optional contentSha256.
The Browse and Installed tabs compare versions and, at the same version, payload identities. Rust recomputes installed contentSha256 during discovery; a manifest cannot supply it. A missing identity keeps version-only behavior, and a newer installed version is never downgraded.
The community packager generates contentSha256 from sorted UTF-8 relative paths (using /), NUL, each file’s lowercase hexadecimal SHA-256, and LF. It hashes that complete sequence again with SHA-256. Directories named data, node_modules, scripts, .claude, .git, and files matching package*.json are excluded. Thus user settings and ZIP timestamps do not cause updates. Internal symlinks or unreadable files leave the installed identity unknown; the plugin can still load. This is content identity, not publisher authentication. The raw source catalogue can precede release completion; wait for the plugin release workflow before installing.
Per-Plugin Error Logging
Each plugin has a dedicated ring buffer logger (500 entries max). Errors from onload, onunload, output watchers, structured event handlers, and PluginHost-registered UI callbacks are automatically captured.
Plugins can also write to their log via host.log(level, message, data).
View logs in Settings > Plugins > click “Logs” on any plugin row.
Module import failures also produce an error-level application log with source
plugin. Its data includes the exact url, errorName, errorMessage,
httpStatus (null when the loader does not expose it), attempt (1 through 3),
documentId (the document’s performance time origin), and a unique loadCycleId.
The message includes the load ID so consecutive failures retain separate data.
These fields help distinguish repeated loads from document reloads; they do not
prove why an import failed.
An import rejection gets at most two retries, after 1 second and then 3 seconds. Each attempt uses a fresh numeric path version for the entire module graph; all attempts in one load share a load ID. A successful import is validated and activated once. Disabling the plugin or starting a replacement load retires pending import recovery. Module validation and activation failures are not retried. After the third import rejection, the plugin stays enabled but unloaded with its last error visible. The waits add at most 4 seconds, excluding time spent inside imports; a pending native import is not timed out. Avoid top-level side effects: a rejected graph can have evaluated some modules before the retry.
The original all-plugin boot incident remains unattributed. No retained file-log entry establishes its URL, status or native cause. The protocol handler reads plugin files directly, not through the HTTP server. See the investigation for evidence and limits.
Preinstalled External Plugins
Plan Tracker (plan) and Stories Ticker (stories-ticker) are external packages installed into the normal plugin directory by a one-time migration. They use only PluginHost, declare capabilities in their manifests, and can be disabled, uninstalled, or updated like any other external plugin. The migration marker prevents an explicitly uninstalled package from being recreated on later launches.
External packages are desktop-only. Browser/PWA mode does not import plugin code from the desktop configuration directory.
Note: Session prompt tracking is now a native Rust feature (via
input_line_buffer.rsand the Activity Dashboard). The formersessionPromptPluginbuilt-in has been removed.
See examples/plugins/report-watcher/ for a template showing how to extract terminal output into Activity Center items with a markdown viewer.
Create new plugins as external packages with a manifest and ES module entry point. src/plugins/index.ts initializes native agent usage and loads external packages; it has no BUILTIN_PLUGINS list.
Testing
Mock setup for plugin tests
import { describe, it, expect, beforeEach, vi } from "vitest";
vi.mock("../../invoke", () => ({
invoke: vi.fn(),
listen: vi.fn().mockResolvedValue(() => {}),
}));
import { invoke } from "../../invoke";
import { pluginRegistry } from "../../plugins/pluginRegistry";
import { activityStore } from "../../stores/activityStore";
import { markdownProviderRegistry } from "../../plugins/markdownProviderRegistry";
beforeEach(() => {
pluginRegistry.clear();
activityStore.clearAll();
markdownProviderRegistry.clear();
vi.mocked(invoke).mockReset();
});
Testing output watchers
Rust assembles the lines, so a test pushes an assembled line rather than raw PTY text:
it("detects deployment from PTY output", async () => {
pluginRegistry.register(myPlugin);
pluginRegistry.handleWatcherLines("session-1", [
{ text: "Deployed: api-server to prod", matched_ids: [] },
]);
// onMatch is deferred with queueMicrotask
await new Promise<void>((resolve) => queueMicrotask(resolve));
const items = activityStore.getForSection("my-section");
expect(items).toHaveLength(1);
expect(items[0].title).toBe("api-server");
});
registerOutputWatcher also calls set_plugin_output_watchers, so the invoke mock must
return a promise. Until it resolves to { applied: true, rejected: [] }, the registry
treats every watcher as its own and scans the line itself — which is what the example
above exercises with an empty matched_ids.
To test the Rust path instead, resolve the sync with { applied: true, rejected: [] } and
put the qualified id (<clientId>/<watcherId>, both read from the invoke payload) in
matched_ids. A watcher fires once per line either way: an id Rust flagged is skipped
by the frontend scan that follows. A reply with applied: false is ignored, because the
set it describes is not the set the backend holds.
Testing capability gating
it("external plugin without pty:write throws on sendAgentInput", async () => {
let host;
pluginRegistry.register(
{ id: "ext", onload: (h) => { host = h; }, onunload: () => {} },
[], // no capabilities
);
await expect(host.sendAgentInput("s1", "hello")).rejects.toThrow(PluginCapabilityError);
});
CSS Classes
Activity items use these CSS classes (defined in src/styles.css):
| Class | Element |
|---|---|
activity-section-header | Section heading row |
activity-section-label | Section label text |
activity-dismiss-all | “Dismiss All” button |
activity-item | Individual item row |
activity-item-icon | Item icon container |
activity-item-body | Title + subtitle wrapper |
activity-item-title | Primary text |
activity-item-subtitle | Secondary text |
activity-item-dismiss | Dismiss button |
activity-last-item-btn | Shortcut button in toolbar |
activity-last-item-icon | Shortcut button icon |
activity-last-item-title | Shortcut button text |
Structured Event Types
The Rust OutputParser detects patterns in terminal output and emits typed events. Handle them with host.registerStructuredEventHandler(type, handler).
plan-file
Detected when a plan file path appears in terminal output. The emitted path is relative or absolute, as it appeared in the output — the parser does NOT resolve relative paths to absolute:
- Relative paths (e.g.
plans/foo.md,.claude/plans/bar.md) are emitted unchanged - Tilde paths (
~/.claude/plans/bar.md) are the only ones rewritten —~is expanded to the user’s home directory - Already-absolute paths are passed through unchanged
Relative-to-absolute resolution (against the terminal session’s CWD via host.getSessionCwd) happens later, in the external Plan Tracker plugin; plans whose CWD cannot be determined are skipped.
{ type: "plan-file", path: string }
// path: relative or absolute, e.g. "plans/foo.md", ".claude/plans/bar.md",
// "/Users/me/.claude/plans/graceful-rolling-quasar.md"
Repo scoping: Plan Tracker asks host.openMarkdownFileBackground() to resolve the repository that owns each absolute plan path. Unowned paths are tracked but not opened, preventing cross-repository tab leakage.
rate-limit
Detected when AI API rate limits are hit.
{
type: "rate-limit",
pattern_name: string, // e.g. "claude-http-429", "openai-http-429"
matched_text: string, // the matched substring
retry_after_ms: number | null, // ms to wait (default 60000)
}
Pattern names: claude-http-429, claude-overloaded, openai-http-429, cursor-rate-limit, gemini-resource-exhausted, http-429, retry-after-header, openai-retry-after, openai-tpm-limit, openai-rpm-limit.
status-line
Detected when an AI agent emits a status/progress line.
{
type: "status-line",
task_name: string, // e.g. "Reading files"
full_line: string, // complete line trimmed
time_info: string | null, // e.g. "12s"
token_info: string | null, // e.g. "2.4k tokens"
}
pr-url
Detected when a GitHub/GitLab PR/MR URL appears in output.
{
type: "pr-url",
number: number, // PR/MR number
url: string, // full URL
platform: string, // "github" or "gitlab"
}
progress
Detected from OSC 9;4 terminal progress sequences.
{
type: "progress",
state: number, // 0=remove, 1=normal, 2=error, 3=indeterminate
value: number, // 0-100
}
question
Detected when an interactive prompt appears (Y/N prompts, numbered menus, inquirer-style).
{
type: "question",
prompt_text: string, // the question line (ANSI-stripped)
}
usage-limit
Detected when Claude Code reports usage limits.
{
type: "usage-limit",
percentage: number, // 0-100
limit_type: string, // "weekly" or "session"
}
Example Plugins
See examples/plugins/ for complete working examples:
| Example | Tier | Capabilities | Demonstrates |
|---|---|---|---|
hello-world | 1 | none | Output watcher, addItem |
auto-confirm | 1+3 | pty:write | Auto-responding to Y/N prompts |
ci-notifier | 1+3 | ui:sound, ui:markdown | Sound notifications, markdown panels |
repo-dashboard | 1+2 | none | Read-only state, dynamic markdown |
claude-status | 1 | none | Agent-scoped (agentTypes: ["claude"]), structured events |
telegram-notifier | 1+3 | net:http, ui:panel, ui:ticker | Telegram push notifications, per-event toggles, settings panel |
Distributable Plugins
Available from the plugin registry (submodule at plugins/). Installable via Settings > Plugins > Browse.
| Plugin | Tier | Capabilities | Description |
|---|---|---|---|
mdkb-dashboard | 2+3 | exec:cli, fs:read, ui:panel, ui:ticker | mdkb knowledge base dashboard |
rtk-dashboard | 3 | exec:cli, ui:panel, ui:context-menu | RTK token savings dashboard (binaries: ["rtk"]) |
csv-preview | 3 | ui:file-preview, ui:panel, fs:read | Preview CSV/TSV files as sortable HTML tables |
docx-preview | 3 | ui:file-preview, ui:panel, fs:read | Preview Word .docx/.dotx files as HTML with Mammoth.js |
xlsx-preview | 3 | ui:file-preview, ui:panel, fs:read | Preview Excel .xlsx/.xlsm/.xlsb/.xls and .ods spreadsheets as sortable tables with SheetJS |
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
| Plugin not loading | manifest.json missing or malformed | Check console for validation errors |
requires app version X.Y.Z | minAppVersion too high | Lower minAppVersion or update app |
not in the invoke whitelist | Calling non-whitelisted Tauri command | Only use commands listed in the whitelist table |
not declared in plugin ... manifest binaries | Binary not in manifest binaries field | Add the binary name to the binaries array in manifest.json |
requires capability "X" | Missing capability in manifest | Add the capability to manifest.json capabilities array |
| Module not found | main field doesn’t match filename | Ensure "main": "main.js" matches your actual file |
| Changes not reflecting | Hot reload cache | Save the file again, or restart the app |
default export error | Module doesn’t export default { ... } | Ensure your module has a default export with id, onload, onunload |
Core account registry integration
Provider accounts and sites are core-owned. Metadata reads expose credential presence only. Manifest providers descriptors ({id,label,kinds,verify:{path,loginPointer}}) register with accounts::register_provider(<plugin id>, descriptor) when the plugin loads; non-core providers use bearer/basic tokens only. Unload unregisters descriptors but keeps accounts and credentials.
providers: optional account providers this plugin may use with httpFetch({account}); requires net:http. An entry is either a core provider id (only "github") or a token-only descriptor that core registers when the plugin loads and removes when it unloads (accounts and credentials stay): { "id": "jira", "label": "Jira", "kinds": ["basic", "bearer"], "verify": { "path": "/rest/api/3/myself", "loginPointer": "/displayName" } }. kinds accepts bearer and basic; verify.path is a path under the site URL that the account Test calls, and loginPointer is the JSON Pointer of the viewer name in its response. An id may appear once; a declared descriptor must not use a core id.
Authenticated HTTP goes through host.httpFetch(url, { account }) (see Tier 3h). Account actions are not currently a grant in host.invoke. Secret entry belongs in the core private native sink, which calls the write-only account service; plugins must never receive token values. See Shared account registry.
Core setting controls
The core provides account, editable-list, multiselect, read-only status and action
button controls for catalogue-backed settings and work-item forms. Plugins do not
import these Solid components or gain new manifest fields from them. The host
owns account selection and native secret entry; no token enters a plugin prop.
See plugin_dev_guide → Settings field kinds for the core-rendered contracts.
Tasks roadmap
Core TasksRoadmap renders WorkItemProvider.list pages and the provider’s date
descriptors. The host passes provider, onOpen(reference), optional query,
visible, initialDate, startFieldId and targetFieldId. Absent field IDs use
the first and second kind: "date" descriptors in provider order. Field names are
never guessed. Provider-declared start/target roles need a later contract extension.
Month/quarter zoom and Previous, Next and Today navigate the local calendar. ISO date-only values retain their calendar day. Timestamps must carry an explicit offset and display in the viewer’s local time zone. Bars include the target day and clip to the visible period. A single endpoint gives a one-day milestone. Missing, invalid or reversed dates stay clickable in the Without usable dates side list; out-of-period tasks stay listed in the timeline.
The shell hides the Roadmap view while the selected provider declares no
kind: "date" field.
Both lists use virtual rows. Load more follows provider cursors. Failed refreshes retain stale results; obsolete provider responses cannot replace the active view. This component adds no manifest, IPC or HTTP API. Tasks shell mounting is a separate integration step.
Tasks data contract (Phase A4)
Register via host.registerWorkItemProvider(provider), returning an auto-cleaned
Disposable. Provider/account pairs must be unique; core consumers use
workItemProviderRegistry.get(providerId, accountId) or .list(providerId?).
The async WorkItemProvider port includes list/detail/comments/act, dynamic
createFields(itemType?), grouped(query) and board(id, query). Grouping uses query.groupBy;
board lanes include per-card moves (columnId and action) so UI never guesses legal moves.
The test/development fake is createInMemoryWorkItemProvider() in
src/plugins/testing/inMemoryWorkItemProvider.ts, seeded from the same synthetic
JSON as the Rust fake. No fake routes or IPC commands are installed.
Core owns the Solid Tasks views; provider plugins supply data, schemas and actions, never view HTML. A4 defines DTOs only: registration, transport and visible views are delivered by the following integration steps.
Work-item links (Phase A3b)
host.linkItem(repoPath, branch, link) persists a link from a worktree branch to a
work item; host.unlinkItem(repoPath, branch) removes it and resolves true when a
link existed. No capability is required. link is
{ reference: { providerId, accountId, id }, key, title, url, state: { id, name, tone } | null };
url must be http(s). The sidebar branch row shows key coloured by state.tone;
hovering refreshes the state through the provider’s detail(reference), and a click
opens url without selecting the branch. TUIC drops the link when it removes the
worktree. repoPath is the main repository path, branch the worktree branch name.
Work-item field kind inventory
text, markdown, enum, user, labels, date, number, link
text: a plain text input;markdown: the shared markdown renderer/editor.enum: a select using provider option IDs;user: a user picker, multiple users.labels: multiple labels with stable IDs;date: ISO-8601 date input.number: finite numeric input;link: URL/link control.
Display-only fields set sortable, filterable and groupable to false. The roadmap still reads date fields.
The canonical DTOs are work_items::model and work_items::protocol in Rust.
Generate their TypeScript declarations with
python3 scripts/generate-work-item-types.py; import from
src/types/work-items.gen.ts. Fields use camelCase; discriminated unions use
{kind, value} with snake_case kinds. WorkItemRef scopes opaque item IDs by
providerId and accountId. Missing field keys mean not loaded; null means unset.
Each field schema declares sortable, groupable and filterable booleans for
the provider list endpoint. Tasks offers only those declared query controls.
Create and detail schemas set these to false when they are not list fields.
A rejected query restores the last successful controls and shows the reason.
WorkItemQuery carries ANDed filters (values are ORed), saved filter ID, native
search, sort, bounded page size and opaque cursor. Providers must bind cursors to
the account/query; selecting a preset starts with no cursor. WorkItemPage
contains items, nextCursor and an optional total (all matches, when the provider knows it). Details load body, field schemas, allowed action
descriptors and a separately paginated comment page on open. Comment entries are
normal, review_thread (resolved, outdated, path, line, originalLine, reviewed
commitId and a nullable parsed finding), or review_summary (state and reviewed
commitId). Comment authors carry bot. Bodies are markdown, not trusted HTML; finding
text is untrusted bot data, shown as plain text and never applied or executed.
Actions are create, edit_field, transition, comment, and start_work.
Transitions use provider action IDs, not state display names. Board columns may carry a default edit/transition action or null; per-card moves
carry the actual legal action to dispatch on drop (workflow IDs can vary by item). Start-work carries repoPath,
branch, optional baseRef, prompt, agentType and explicit draft/submit delivery;
core executes the existing worktree/agent workflow and owns errors/rollback.
WorkItemBoard.writeDisabledReason is an optional nullable message for a read-only
board. Core keeps readable cards, shows the reason, and removes legal moves from
all loaded pages while the reason is set. Providers must reject direct writes too
and mark affected field schemas non-editable. Unrelated item actions remain available.
Core CardMoveMenu provides a portalled, keyboard-accessible menu of other columns and enables only destinations allowed by the card’s moves.
work_items::demo::demo_provider() supplies deterministic local-only data with
list, detail, comments, schemas, saved filters, board columns and mutations.
It touches no network, credentials, filesystem or subprocesses. It is a development
provider, not a fixture proving GitHub/Jira/GitLab API compatibility. Its search is
literal text; sort supports key/title/updatedAt. Its cursor expires on mutation.
Tasks detail
Core’s TasksDetail consumes the async WorkItemProvider port and a WorkItemRef.
The Tasks shell supplies the selected provider/reference and visible state.
Providers supply data and declared actions; they do not render this view.
The header shows key, title, type, state and updated time. Detail field schemas
select text, Markdown, enum, user, labels, date, number and link controls. Saving
requires an editable field and an enabled edit_field action. Required fields
cannot be cleared. Values retain their tagged field-value shape. The detail shows
Description first, then the fields, then Comments. A schema of more than eight
fields folds behind a “Fields (N)” summary so a wide Jira project does not push
Description and Comments out of view; no field is dropped.
Descriptions and normal comments, review threads and review summaries render
through ContentRenderer with untrustedContent. Markdown, tables, images and
<details> survive; scripts, event handlers and provider CSS do not. Review
threads show file/line and resolved state. The provider’s comment cursor drives
Load more. Add comment retains its draft on rejection.
An accepted comment clears its draft even if reloading opened comment pages
fails. Core keeps the returned item, reports the history error and lets Retry
reload those pages.
Transition buttons use declared IDs and disabled reasons. The pending action label appears immediately while the authoritative state ID stays intact. Success adopts the returned detail; rejection restores the state label and shows the error. Core does not infer a target state from a transition name.
A start_work descriptor in actions shows a Start work button in the detail and
in the board card’s actions menu (the menu reads the item’s detail when opened).
Core sends the provider a start_work action (active repository, branch, item
brief, draft delivery); the provider returns the intent and core runs the host
start-work workflow with the item link. The button shows a pending state, then
the started branch, or the error with Retry. The branch is the item field
branch (text) when the provider fills it, else a slug of key and title. This
field is a hint and needs no schema entry. “Copy branch name” copies that branch.
Refresh is manual and periodic (60 seconds by default) while the detail, Tasks view and document are visible. Refresh preserves disclosure state and reloads comment pages already opened. Switching items rejects stale responses.
Start work and URL paste
host.startWork({ repoPath, branch, baseRef?, prompt, agentType?, delivery?, link? })
(capability pty:write) creates a worktree on a new branch (from baseRef, default
the repo’s default branch) and opens an agent in it. The agent is agentType or, when
omitted, the first enabled agent with a run config on the repo’s machine; that run
config supplies the command and env. The prompt sits inside an <untrusted-content>
block, control bytes removed, capped at 12000 characters. delivery: "draft"
(default) waits for the agent’s composer and types the prompt there, leaving Enter to
the user. "submit" starts the agent with the prompt as its first message, quoted as
one POSIX shell argument after a -- option terminator, for claude, codex, gemini and grok
(their --help lists a positional prompt for an interactive session and they honour --); other agents (pi has no --
handling), prompts over 16384
characters and cmd/PowerShell shells get the prompt typed and submitted instead. link links the item to the
new worktree. It resolves to { repoPath, workspaceId, branch, worktreePath }.
The GitHub Auto-fix action uses the same path with delivery: "submit".
host.registerUrlResolver((url, signal) => ...) claims URLs pasted in the command
palette. Return null for a URL that is not yours, or { link, startWork? }.
Resolvers run in registration order; the first non-null result wins and a resolver
that throws is skipped. When a worktree is already linked to link.reference, the
palette offers Open worktree; otherwise it offers Start work with your
request (repoPath defaults to the active repository).
Tasks create
Core’s TasksCreate consumes createFields and act of the WorkItemProvider port.
The host supplies provider, onCreated(detail) to open the created item, and
optional onCancel. Providers supply types and schemas; they do not render the form.
createFields() without a type must return an enum field with id itemType that
lists the creatable types; a single type is preselected. createFields(type)
returns the fields of that type (an unknown type is an error, and create
rejects an undeclared itemType). Title and Description are fixed inputs, so a
schema does not repeat them. Only editable fields render.
Create lists Type, Title, Description and the required fields first. Optional fields sit in a folded “Optional fields (N)” group with a name filter; the filter only hides a field and never hides one that blocks Create.
A type change reloads the schema; values survive only for the same field id and
kind, and a late schema of an earlier type is dropped. Create stays disabled until
Title, Type and every required field of the current type are set. Submit sends one
create action with every current field (unset is null). A rejection keeps the draft.
Create user controls use optional lookupUsers(fieldId, query, signal?), which
returns {id, name} choices for that provider/account. Search text is never a
selected user; rejected searches stay visible and late responses are discarded.
Static user options remain selectable. Labels without static options accept
comma-separated free text. Required-field errors are linked to their controls.
The Jira provider omits configured Project and selected Issue Type from its
create schema, searches project-assignable users for Assignee, and searches users
for Reporter. Cloud choices use account IDs; Data Center choices use usernames.
A provider may declare optional singleUser(fieldId); Jira does, so a second pick in
a user field replaces the first. The control shows and announces the chosen user.
Jira create metadata that carries hasDefaultValue (Reporter) is not required in
the form, and empty optional fields are left out of the create payload so Jira
applies its own defaults.
Tasks setup
With no work-item provider registered, the Tasks tab shows install prompts for
github-work, gitlab and jira. Once a plugin is installed, a form edits its
account (id, repository, host, project/projectId, boards) and merges it
into the plugin’s data/config.json, then reloads the plugin. Other accounts and keys
stay; a file that is not valid JSON is never overwritten. Provider settings in the
Tasks header opens the same form. The Plugins settings tab lists install hints for
the work-item plugins that are missing. Open Tasks is always offered.
A provider page with total <= 1000 can enable complete local Tasks queries after every page is collected and its unique item count matches the stable total. Omit total when unknown; never infer a count from a cursor or loaded rows. Local query projection is the host Rust command project_work_items, shared with /tasks/project. Collection preserves GitLab type, state and preset scope. GitLab username filters remain server-side because list rows hold numeric user identities, not usernames. Roadmap keeps provider paging and does not collect complete scopes automatically.
GitHub Tasks boards (#1846-55d7): the optional provider listBoards(signal) port discovers the current user Projects v2 when Board opens. The existing picker selects a project; paging preserves project identities. Missing read:project stays visible instead of claiming there are no boards. Providers without discovery retain their configured boards. Discovery does not persist selections or write to GitHub.
Account-scoped GitHub review and action ports
host.githubReviewThreads(account, reference, after) returns the core B6 review
thread page, including head SHA, bot authors and parsed findings.
host.githubPrAction(account, reference, request) calls core B7 policy.
Both require net:http and an on-disk manifest declaring providers: ["github"].
The reference must identify a GitHub pull request in the selected account. Core
loads that exact account credential, never a local repository default. Cross-account
references fail before credential lookup. No token is returned to the plugin.
Requests use action: state, auto_merge (enabled, optional mergeMethod,
expectedHeadSha), queue (enqueued, optional expectedHeadSha), merge
(mergeMethod, expectedHeadSha), rerun (runId), or review (draft with
headSha, body, event, comments). Existing core reviewed-head validation,
merge queue policy and shared request budgets apply unchanged. The desktop command
plugin_github_action and POST /api/plugins/{plugin_id}/github accept identical
{account, reference, request} payloads (IPC also supplies pluginId).
The GitHub Work runtime binds both ports when it registers each configured account.
No live write or desktop-load verification is implied by recorded-fixture tests.
Settings startup is not a plugin capability
Plugin-scoped settings do not confer host account, executable or provider-login authority. Runtime shortcut-ID publication is metadata, not permission to invoke authentication or arbitrary commands. The host startup contract documents typed GitHub enumeration and Ego human-login owner workflows; these do not grant plugins host authentication authority.
Jira and GitLab expose a default project in their schema-driven plugin settings page. Jira uses a project ID; GitLab accepts a project path or ID. A project saved for an account in Tasks setup takes precedence. The default applies after the plugin reloads; empty means no fallback project. Account bindings remain in data/work-items.json, while these defaults use the settings service in data/config.json.
Jira Tasks setup uses the registered core account’s Basic or Bearer kind rather than a Cloud default. Jira detail editors retain current typed description and custom values; unsupported structured values do not get an empty editor. Jira create metadata retains Description requiredness for the fixed body input, not a second schema control. Empty or whitespace-only required descriptions block creation in both the host form and provider action.
Random-access binary previews
host.fileSize(absolutePath) returns the file size in bytes.
host.readFileRange(absolutePath, offset, length) returns exactly that binary range as Base64. Both require fs:read and reuse the existing absolute-path read policy (including external volumes). Offset and length must be non-negative safe integers; length is capped at 8 MiB. Ranges past EOF and short reads fail. Split larger requests into bounded calls. File changes between calls may cause a read to fail; reopen the preview to refresh metadata.
Development Setup
Prerequisites
The macOS desktop app supports macOS 12 Monterey or later and requires system WebKit updated to Safari 17.4 or later for Mermaid diagrams. The bundle declares macOS 12.0 as its minimum; this does not guarantee that Safari updates are installed. src-tauri/.cargo/config.toml forces MACOSX_DEPLOYMENT_TARGET=12.0 for Rust and native dependencies, including WebRTC and whisper.cpp, overriding inherited shell defaults. The Cargo config also forces CMAKE_OSX_DEPLOYMENT_TARGET=12.0 so whisper.cpp updates existing CMake caches instead of retaining an older target. Make does not set a separate default. scripts/test-macos-deployment-target.sh checks both values against the bundle minimum and runs with system Python without extra dependencies. The installed Xcode SDK’s libc++ __configuration/availability.h warns for macOS deployment targets below 11.0, so 12.0 needs no increase. Windows uses the Evergreen WebView2 runtime; Linux builds use WebKitGTK 4.1 API packages.
- Node.js 24+ (the repository version is pinned in
.nvmrc) - Rust (stable toolchain via rustup)
- Tauri CLI (
cargo install tauri-cli) - git for git features.
gh(GitHub CLI) is only a release tool; the app does not run it.
Windows users: See the Windows-specific prerequisites section below before proceeding.
Install Dependencies
pnpm install
Dependency release policy
The application and the standalone website/ project pin pnpm 12.15.0 in
packageManager. CI uses that pin through pnpm/action-setup.
Each project’s pnpm-workspace.yaml sets minimumReleaseAge: 10080:
new direct and transitive package releases must be at least seven days old.
There are no release-age exclusions. Use pnpm install --frozen-lockfile
for reproducible installs. pnpm 12 also verifies locked releases against this
policy, so an existing lockfile is not an exception.
Do not approve a young release interactively or add an exclusion to make an
install pass. Wait for the release to mature, or ask for an explicit policy
decision. minimumReleaseAgeExclude exists, but this project does not use it.
See the pnpm release-age settings.
Package popularity is a separate review. npm reports downloads, not users. Use last-week downloads as the agreed proxy and review every package below 10,000 downloads per week, including transitive and development packages. A low count is not permission to remove or replace a dependency.
TypeScript target
The app uses ES2024 for the TypeScript target and standard library, with
DOM and DOM.Iterable types. Vite keeps its existing esnext build target;
it does not lower ES2024 syntax to ES2021. This configuration does not add
runtime polyfills.
Paired Tauri dependencies
Update each Tauri Rust plugin and its npm counterpart together. Notification stays
on ~2.4.0 and updater on ~2.11.0 in both manifests until their next minor
versions are validated together. The direct rfd dependency must match the
version and features used by tauri-plugin-dialog; dialog 2.8.1 uses rfd 0.16.
Dependency audit exceptions
pnpm-workspace.yaml ignores no advisory. The former exception for
GHSA-vfj7-8cjw-p6xm (build-only braces 3.0.3, approved 2026-10-04, expired
2026-11-04) was removed on 2026-11-14: GitHub withdrew that advisory, and
pnpm audit --audit-level=high passes without it. Transitive security pins
live in the overrides block of pnpm-workspace.yaml, each with its reason:
DOMPurify for the application and Mermaid, the development-only qs, Seroval
=1.6.3, source-map-js >=1.2.2, and the test-only zod ^4.6.6 and undici ^8.12.2. KaTeX 0.16.47 remains under Mermaid 11; its patched >=0.18.2 line requires the separate Mermaid upgrade and browser compatibility review. Rust exceptions live in
src-tauri/.cargo/audit.toml, each with a reason and a review date.
pnpm 11 ignores the legacy pnpm.auditConfig field in package.json.
Development
Native Tauri App
make dev
Starts the Vite dev server and Tauri app. Frontend files use Vite HMR; Rust changes require restarting the development process.
On macOS, make dev requires Python 3 and passes a Cargo target runner to Tauri’s cargo run. The runner copies the desktop executable and its tuic-remote, tuic-bridge, and tuic siblings into ~/Library/Application Support/com.tuic.commander/dev-bin/ before launch. These are real copies, not links into Cargo or mbx targets. Target cleanup can no longer remove the running desktop executable. The path stays the same across runs; files are replaced, not accumulated, and remain after exit. A second launch at that path is rejected while the runner holds its process lock. TUIC_DEV_BIN_DIR overrides the directory for isolated script checks. Direct pnpm tauri dev does not use this protection. Linux and Windows keep the normal Cargo launch.
The existing MCP bridge installation still verifies and preserves its own revisions; the dev runner keeps its adjacent source available. The bridge installer runs inside the application, so it cannot protect the desktop executable before launch.
The macOS application firewall uses code signing for initial and tracking decisions (Apple TN2206). Its UI also selects applications by filesystem path (Apple firewall settings). Both the executable path and signing identity matter: a stable existing path contains the missing-executable failure, but does not promise unchanged firewall permission after a rebuild changes the signature. Confirm LAN and tailnet access after the next launch; no firewall setting is changed by the runner.
Vite excludes backend files and repository tooling output such as .tmp/, target/, dist/, coverage, reports, plans, stories, and docs from its watcher. Mutation testing keeps its disposable checkout under .tmp/; its HTML files must not reload the live WebView. Changes to this watch configuration require restarting the Vite dev server.
The watch allowlist and Tauri version are resolved from the directory containing vite.config.ts, so starting Vite from another working directory still uses this checkout’s inputs.
macOS application icon
src-tauri/tauri.macos.conf.json selects the macOS-only PNG for window icons
and icons/icon.icns for the application bundle. Tauri also embeds the ICNS
for the Dock when running pnpm tauri dev (it uses a PNG only if the ICNS
is missing). Restart the development process after changing these assets.
The shared PNGs and ICO remain unchanged for Linux and Windows.
Run bash scripts/generate-macos-icon.sh on macOS with ImageMagick to rebuild
these assets from the shared src-tauri/icons/icon.png art. The macOS canvas
is 1024 pixels with a centered 824-pixel rounded body and transparent margins.
Run bash scripts/test-macos-icon.sh to check transparent margins and an opaque
body in the PNG and every ICNS representation. The check needs ImageMagick and
the system iconutil command.
Isolated agent desktop checks (macOS)
Use a linked worktree, not the daily checkout. Inspect the complete plan first:
make agent-test AGENT_TEST_DRY_RUN=1
make agent-test
# In another shell, stop only this supervised instance:
make agent-test-stop
The dry run does not build, create runtime files, read application configuration,
or start a desktop process. The launch runs in the foreground. It builds the
frontend, then uses one Cargo build through the mbx shim for
tuicommander-agent-test, tuic-bridge and tuic. The existing orchestrator
build-slot wrapper serializes these builds when installed. mbx doctor must
succeed. Do not set CARGO_TARGET_DIR. No Vite server, Tauri watcher, release
bundle, signing operation or installed executable is involved. Embedded frontend
assets use tauri/custom-protocol even though this is a debug build.
Defaults are AGENT_TEST_INSTANCE=agent-test and AGENT_TEST_PORT=19876.
The isolated window starts at 1400 × 900 logical pixels so Tasks and other
virtualized panels have a usable viewport. Its minimum size is 390 × 420, so
native checks can use a phone-width viewport.
Override with, for example, make agent-test AGENT_TEST_INSTANCE=agent-check AGENT_TEST_PORT=19877 (on one line). Use the same instance on the stop target.
Agents must connect through the instance’s Unix socket, printed as socket and
as a ready-to-run connect command in the launch JSON:
curl --unix-socket '<socket from launch JSON>' http://localhost/health
tuic --instance <instance> <command> reaches the same socket from any shell:
the app publishes the path in its instance config directory.
Replace /health with the endpoint needed for the check. The socket does not
require HTTP authentication. TCP requests to 127.0.0.1:<port> require Basic
auth (or another configured authenticated session); an unauthenticated request
can return 401. A ready TCP listener does not mean an agent can use its API
without credentials. Do not read or copy the daily instance’s credentials.
These dedicated variables ignore inherited TUIC_APP_INSTANCE, TUIC_PORT,
TUIC_SOCKET and TUIC_DEV_BIN_DIR. Empty/default instance IDs and port 9876
are rejected, not interpreted as production defaults. The dedicated Rust entry
point also validates instance and port before any config read, and refuses
release, non-macOS or dictation-enabled builds.
The compiled executable has a distinct Cargo target name and is copied to
<worktree>/.tmp/agent-test/<instance>/tuicommander-agent-test. The running copy
is not a symlink into mbx’s target cache. The default instance stores app state
in ~/Library/Application Support/com.tuic.commander/instances/agent-test/.
It never seeds from the daily config. Never copy daily tokens or config there.
The test window starts at 1400×900 logical pixels, with a 390×420 minimum,
at the bottom-right of the primary screen work area (16 logical pixels inset).
It is always on top so ordinary application windows do not cover it. A higher
or another floating window (a second agent-test instance in the same corner, a
system authentication prompt) can still cover it fully; WebKit would then mark
the page hidden and stop requestAnimationFrame. The agent-test WebView
therefore disables WebKit window-occlusion detection, so the document stays
visible while the window is ordered in. It cannot become key or take keyboard
focus. Background throttling is disabled (supported on macOS 14+). The
agent-test application uses the Prohibited activation policy, set between
Tauri build and run: Tao 0.37.1 still calls activateIgnoringOtherApps(false)
at launch, and macOS grants it when the launching application (usually the
daily TUIC) is frontmost. As a result the test instance has no Dock icon or
menu bar and never becomes the active application. A process-lifetime activity
prevents App Nap during live latency checks but still permits idle system sleep.
These changes apply only to the dedicated agent-test runtime; the daily app keeps
its existing activation, occlusion and power-management behavior.
It starts hidden: Tao 0.37.1 app_state.rs::window_activation_hack otherwise
orders every visible window key even when focus=false. At Tauri Ready, after
that sweep, the agent-test path calls native NSWindow.orderFront without
becoming key. Saved-window restoration is disabled for this profile because
the window-state plugin calls show and set_focus during restoration.
Do not call window.show() or setFocus() to present it: the pinned Tao backend
uses makeKeyAndOrderFront for those APIs. The agent-test capability override
denies show and set-focus and grants core:window:allow-set-size only
to its main window. The grant is inline in the agent-test build overlay, not
in an auto-loaded capability file. The daily capability files are unchanged.
Stop the instance when the check ends to remove the floating window. The daily window configuration remains unchanged.
Resize the native test window
Use the socket from make agent-test AGENT_TEST_DRY_RUN=1 with the same
AGENT_TEST_INSTANCE=agent-test-<story> and AGENT_TEST_PORT=<port> values
as the running authorized instance. Do not use the orchestrator MCP debug tool:
it targets the daily app, not your worktree. Set SOCKET to that dry run’s
socket value, then send a native Tauri resize through the instance API:
curl --fail --unix-socket "$SOCKET" http://localhost/debug/invoke_js \
-H 'Content-Type: application/json' --data-binary @- <<'EOF'
{"script":"const api = window.__TAURI__.window; const w = api.getCurrentWindow(); await w.setSize(new api.LogicalSize(390, 844)); return {check: 'agent-test-resize', size: (await w.innerSize()).toLogical(await w.scaleFactor())};"}
EOF
curl --fail --unix-socket "$SOCKET" \
'http://localhost/logs?source=eval_js&limit=5'
invoke_js acknowledges dispatch, not completion. Read the matching
agent-test-resize log result and check its logical width and height before
capturing evidence; a permission error is not a successful resize. This changes
the native WebView viewport, not a browser-mode Vite page. Do not call show()
or setFocus(). To restore the initial viewport, use the same script with
new api.LogicalSize(1400, 900). Rebuild and restart only your named agent-test
instance to load a changed capability overlay; an existing binary keeps its
compiled permissions.
Persistent GitHub live-check login
Use one named instance for all authorized GitHub live checks, across stories and worktrees. Do not select a new instance name for each agent:
make agent-test-github AGENT_TEST_DRY_RUN=1
make agent-test-github
# Stop only after the current owner finishes:
make agent-test-github-stop
These targets always select agent-test-ghlive on port 19887, including when
AGENT_TEST_INSTANCE, AGENT_TEST_PORT or TUIC_* values are inherited or supplied
for another story. They reuse the instance used for the authenticated Tasks
checks. The generic agent-test defaults and all isolation guards are unchanged.
Coordinate ownership before starting or stopping this shared verification
instance. Its existing supervisor lock rejects a second owner; do not stop
another agent’s run. Stop preserves persistent state.
The agent-test executable is a debug build. Its credential adapter uses
~/.tuicommander-dev/instances/agent-test-ghlive/credentials.json, not macOS
Keychain. App configuration and account metadata remain under
~/Library/Application Support/com.tuic.commander/instances/agent-test-ghlive/.
The vault service is tuicommander-instance-agent-test-ghlive, user vault,
with the GitHub OAuth token in the account/github.com slot. A different instance
selects a different file and vault namespace; it does not reuse this login.
Rebuilding or changing the worktree does not change either persistent path.
agent-test-stop removes the PID and FIFO only, not credentials or configuration.
Do not read, copy, reset or delete credential files to move a login between
instances. Never copy the daily instance’s credentials.
Before requesting another Device Flow login, use the instance’s normal GitHub
status UI/API to check its existing account, not its token store. The 2026-10-23
Tasks worklog records a successful login and restart retention in
agent-test-ghlive. File existence alone does not prove that token is still valid.
An expired/revoked token or a newly required OAuth scope can still require consent;
for example, adding Projects write access requires project, not the older
read:project scope. Reusing a namespace does not add permissions to an old token.
Native visibility regression (authorized macOS runs only)
The unattended scripts/agent-test-tests.py checks launcher/configuration and
source-wiring contracts. It does not observe a rendered window. The separate
native regression launches this worktree’s make agent-test, observes the real
WebView through its Unix socket, and stops the supervised instance in cleanup:
python3 -B scripts/agent-test-visible.py --instance at-2090 --port 19883 \
--evidence-dir "$HOME/Gits/.tmp/results/agent-test-visible-$(date +%s)"
Add --duration 300 to observe presentation for five minutes. Add --cover as
well to put an opaque, non-activating panel from another process (accessory
policy; it absorbs clicks without activating anything) over the window for the whole observation; this is the
story 2095 regression for a covered test window. The observer records
visibility changes, animation-frame progress and gaps, native window-server layers,
application-hidden state, foreground identity, and compact-window geometry in
presentation.json. It fails if presentation or animation frames stop, the test instance becomes
frontmost or takes focus, or window geometry changes. Foreground changes between
other applications are recorded, not failures: the check must pass while Boss works.
The window-server query is read-only and does not activate or move other windows.
These observations do not read NSWindow.occlusionState directly or prove App Nap activity.
This needs explicit desktop-execution authorization, macOS, a linked worktree
with build inputs, an unused named instance/port, and an unrelated foreground
application at launch. Do not use an existing instance with sessions. The evidence directory
must be new and under ~/Gits.
agent_test_window_renders_visible_without_focus checks document/native
visibility, positive terminal canvas area, actual fillText paint, no native or
document focus, and that the test instance is not frontmost at readiness or
after painting. It also verifies the compact viewport and corner geometry.
It retains JSON receipts, the native build log and canvas-only PNGs, deletes
only sessions created by the check, calls make agent-test-stop, and checks
ps for this worktree’s executable. It never captures the desktop or drives
the daily instance. A failure exits nonzero after cleanup. Commenting out the
native orderFront presentation must make this observer fail; source contracts
alone are not behavioral RED evidence. This native check is intentionally not
part of the unattended shell/Rust/JS suites.
Shared-resource audit
| Resource | Agent-test policy |
|---|---|
| Daily binary, dev-bin and installed app bundle | No writes. Only the worktree’s distinctly named binary and adjacent sidecars are copied. A held supervisor lock prevents replacing the running test executable. |
| Config, credential vault, databases and file locks | Existing named-instance namespace; debug credentials remain file-backed. The test never claims the global-input lock, even in its own namespace. |
| HTTP and MCP | Explicit loopback-only 127.0.0.1:19876; never port 9876 or automatic next-port fallback. Unix MCP socket uses the selected instance hash and the launch’s short TMPDIR under ~/Gits/.tuic/tuic-at/. Child CLI/bridge processes inherit the same namespace. Runtime temp stays outside the intentional ego scratch grant ~/Gits/.tmp, so its negative filesystem probe remains meaningful. Do not grant the runtime temp parent to ego or disable confinement to admit a conversation. Stop older instances with their original launcher before updating: their FIFO/socket remains at the old path. |
| Global window shortcut and Fn/Globe monitor | Input ownership refused and shortcut registration rejected at runtime, including later Settings changes. The verification window is non-focusable; drive its own HTTP/socket API. |
| Microphone and dictation | Not compiled by default. With explicit authorization, AGENT_TEST_SPEECH_OUTPUT=1 and an agent-test-<name> instance enable runtime speech output only: effective listening is forced off, microphone permission/capture is refused, and global input ownership stays disabled. Speech output is audible; do not use this option without authorization. |
| Telegram bot | Supervisor never starts, tool availability is false, and setup changes are rejected. A copied or previously saved bot configuration cannot start polling. |
| Global CLI | Startup auto-update is skipped. Explicit installation, update and removal are rejected before sidecar resolution or filesystem changes, including elevated helper paths. |
| Global agent hooks | Hook enable and disable requests are rejected over IPC and HTTP before saving the instance flag or changing shared Claude, Gemini, Grok, Codex or OpenCode files. Read-only hook status remains available. |
| Global agent MCP configuration | Startup installation cannot claim ownership, even with an inherited owner override; explicit install/remove writes are rejected. |
| Updater | No native updater plugin, no channel checks and automatic updates default off. The test cannot replace the daily bundle. |
| Deep links, release single-instance lock and login items | Deep-link plugin is not installed. This debug-only binary never takes the release single-instance lock. Desktop startup has no login-item registration; remote service installation is an explicit operation, not part of this target. |
| Relay, Tailscale and sleep inhibition | Relay supervisor and startup TLS provisioning are skipped; sleep inhibition is a no-op. No remote configuration is copied. |
| Daily window-state repair | Skipped: the legacy repair scans daily config paths, not the test namespace. |
| WebView identity | com.tuic.commander.agent-test, titled TUICommander Agent Test, separate from the daily Tauri identity. |
| Stop ownership | PID is informational. The stop target writes to the instance’s FIFO; only the live supervisor signals its own Popen child. It never kills a PID read from disk. |
The launch plan prints the exact binary, config directory, environment, socket,
PID file and stop FIFO. A crash releases the advisory supervisor lock; the next
start replaces stale runtime markers. Do not use pkill, killall, or the daily
app’s Quit/Restart action to stop a test.
Desktop live proof is separate from a dry run or unit test. An authorized operator must checksum the running daily binary and app bundle before and after, start agent-test alongside it, verify both listeners without mutating the daily API, and stop only agent-test. Until that proof is recorded, do not claim macOS TCC, simultaneous listeners or global-input isolation have been verified live.
Development backend restart warning
tauri dev --no-watch keeps the Rust process running while Vite reloads the UI.
A short, dismissible warning appears when a Cargo-recorded input is newer than
its executable, or the backend executable was rebuilt after application entry.
It shows compact backend/tree identifiers (source SHA plus timestamp token) and
Restart tauri dev. Restart only when you are ready to end the backend session.
Missing executable or dep-info files, or an older backend without launch identity,
show Backend identity unavailable instead of a silent match.
Vite reads Cargo’s final <binary>.d, which covers local path crates and embedded
assets even outside src-tauri/. It also checks local package manifests found
through dependency ancestors and the workspace Cargo.lock. There are no source
extension allowlists or fixture-directory exclusions. The debug bridge built and
used by make dev has its own executable/dep-info check, against its own build
time. Unrelated frontend, test-only module and documentation edits stay quiet;
frontend assets embedded by Rust are backend inputs and do warn.
This uses Cargo-style mtimes, not content fingerprints: an edit followed by a
revert still asks for a restart. Vite checks on load and after HMR, without polling,
compiling or restarting the backend. The macOS copy runner passes
TUIC_DEV_BUILD_EXE so checks follow the original Cargo artifact rather than its
protected launch copy. A rebuilt original bridge also requires restart when the
runner still holds its older protected sibling copy. Without that binding, the running executable needs its
own sibling .d. Vite does not guess an mbx target directory. Source archives
with build artifacts can work without Git (the SHA is diagnostic only). Release
builds do not expose launch identity or include the warning module.
A local IPC failure such as Command select_ai_chat_conversation not found also
reports a Backend/frontend version mismatch in development. Restart make dev
(or pnpm tauri dev) when you are ready to end the backend session. A frontend
reload or Retry cannot add a missing command to the running binary. AI Chat hides
Retry for this failure. This does not change release or remote-owner errors.
Browser Mode
When the MCP server is enabled in settings, the frontend can run standalone:
pnpm dev
Connects to the Rust HTTP server via WebSocket/REST.
Note:
pnpm devrunsscripts/dev-server.mjs, notvitedirectly. The dev server is pinned to port 1421 (Tauri’sdevUrl), so the launcher checks the port first: if this checkout is already serving there it printsreusing itand exits 0 — the second Tauri app attaches to the running server. Starting a second Vite would wipe the sharednode_modules/.vite/depscache and kill hot reload for the session already running. If the port is held by another checkout or a stray process, the launcher fails with an explicit message instead of serving the wrong sources.
Build
When using mbx, src-tauri/build.rs emits MBX_SHARE_OUT_DIR=0 for the
tuicommander crate only, because Tauri’s generate_context! writes assets into
OUT_DIR during macro expansion and the shared OUT_DIR of mbx is read-only.
Do not move this setting to a workspace .mbx.toml: there it also gives every
dependency with a build script a checkout-specific OUT_DIR, and each worktree
then misses the cache for those crates and all crates that depend on them.
pnpm tauri build
Produces platform-specific installers:
- macOS:
.dmgand.app - Windows:
.nsis(.exesetup installer) - Linux:
.deband.AppImage
Note: The
.msibundle may fail on Windows due to WiX tooling issues. Use--bundles nsisto produce a working.exeinstaller:cargo tauri build --bundles nsis
Testing
Rust socket tests use tuic-test-support::short_socket_test_temp_root(). If the
checkout’s test path exceeds the Unix socket limit, the helper uses a short
checkout-specific directory under the nearest short Gits/.tmp/s<checkout-hash>.
Outside Gits, or when all such ancestors are too long, it uses
/tmp/tuic-s<checkout-hash>. It measures every candidate against the socket
budget, including the full mdkb staging filename and eight bytes of margin. The
scripts/with-test-tmp.sh wrapper removes abandoned Gits socket directories and
test-run directories under ~/Gits/.tmp/tuic-tests and the checkout’s
.tmp/tuic-tests after they have been unused for more than seven days. Run
standalone Rust tests through that wrapper.
Rust coverage uses make cov (cargo llvm-cov nextest). Nextest builds the ACP
and MCP fixture executables once for the library tests that launch them. Under
llvm-cov, setup uses the parent of LLVM_PROFILE_FILE as Cargo’s explicit
--target-dir, so those executables stay beside the instrumented tests rather
than in the ordinary build tree. This also supports custom coverage directories.
The fixture feature selection and test profile are unchanged.
Every Rust test binary that links tuic-test-support runs its git processes against a fixed hermetic gitconfig: GIT_CONFIG_GLOBAL points at it, GIT_CONFIG_NOSYSTEM=1 is set and inherited GIT_CONFIG_* variables are dropped. Your own merge.ff, url.*.insteadOf, rerere, signing or hooks-path settings therefore do not change test results.
When a named instance’s Unix socket path does not fit sun_path, the error names the path length, the 103-byte limit, the longest TMPDIR that would fit and TUIC_SOCKET; the bind is not retried.
Live peer-mail wake canary
After a Rust rebuild, run this against the isolated test instance, not the
orchestrator instance. The script starts a disposable managed peer through MCP
agent action=spawn, waits for its idle composer, sends mail from a separate
MCP identity, checks that PEER_MAIL_WAKE appears in the PTY within 20 seconds,
then closes the PTY and its MCP connections. It exits with an error if readiness,
delivery, or cleanup fails.
TUIC_APP_INSTANCE=peer-mail-canary make dev # in a separate terminal; use its reported HTTP port
TUIC_CANARY_URL=http://127.0.0.1:9877 python3 scripts/canary-peer-mail-wake.py claude
TUIC_CANARY_URL=http://127.0.0.1:9877 python3 scripts/canary-peer-mail-wake.py claude --capacity
--capacity sends 100 messages to the disposable agent, reads them through a
second MCP connection bound to that agent, then checks that the next send and
read succeed. Use codex instead of claude for the optional Codex check. The
agent CLI must already be installed and authenticated. Run the script only
after the test instance is listening on the URL you supply.
pnpm test # Run all tests
pnpm test:coverage # Coverage report
Test tiers:
- Tier 1: Pure functions (utils, type transformations)
- Tier 2: Store logic (state management)
- Tier 3: Component rendering
- Tier 4: Integration (hooks + stores)
Framework: Vitest + SolidJS Testing Library + happy-dom
Coverage: ~80%+
Chat browser landing gate (macOS)
Run make check-chat-readability at landing when Chat prose or answer-list CSS
changes. This local gate starts an isolated fixture Vite on an OS-assigned port,
runs the computed-colour, border and list-geometry regressions, then closes Vite
in a cleanup trap. It does not start Tauri or use a running app. The browser
harness closes its own named tab and does not close shared Chrome.
Prerequisites: installed frontend dependencies, agent-browser, matching Chrome
for Testing, and the approved ab-stealth.sh wrapper under
~/Gits/personal/brainstorming/tools/browser-stealth/. Set
TUIC_CHAT_BROWSER_WRAPPER to override the wrapper path. Evidence defaults to a
new .tmp/chat-readability-* directory in the checkout; set
TUIC_CHAT_EVIDENCE_DIR to retain it elsewhere. Managed agents run this target
through the shared build slot.
The frontend CI job runs on Ubuntu and cannot use this macOS .app/open wrapper.
This is a separate required local landing gate, not part of make check or the
ordinary Vitest run. The direct test retains its explicit opt-in skip when
TUIC_CHAT_BROWSER_URL is absent; the make target always supplies the URL and
evidence directory, so it runs both regressions without skips.
Rust build features
Plain application Cargo builds enable desktop but omit native speech. Add
--features dictation for Whisper/WebRTC and the voice adapters. Tauri dev and
release builds read build.features = ["dictation"] from tauri.conf.json, so
make dev and make build retain voice support. Desktop CI tests that feature;
headless daemon checks use --no-default-features. Workspace tests also select
the tuic-dictation crate explicitly, and therefore compile its native stack.
TLS uses the existing ring provider. Provider-free reqwest/axum-server features avoid compiling AWS-LC while retaining HTTPS and WSS.
Desktop frontend embedding gate
The desktop binary constructs the Tauri context and passes it to the library.
Library unit tests do not expand generate_context! or embed the ignored Vite
bundle. HTTP static-file tests use checked-in transport fixtures, including the
desktop and mobile HTML shells, instead of a worktree-specific dist/.
Run make check-desktop-embedding after pnpm build to compile the real desktop
entry point with tauri/custom-protocol. This gate fails if the frontend bundle
is missing. It does not launch or restart the application. make check and
desktop CI run this separate gate, so unit-test isolation does not hide desktop
startup or embedding errors. CI uses minimal HTML stubs; the release build still
embeds the real frontend bundle.
Rust tests in linked worktrees
Run standalone Rust tests through scripts/with-test-tmp.sh. In a linked
worktree, the wrapper clears an inherited CARGO_TARGET_DIR, so Cargo selects
that checkout’s artifacts instead of a target supplied by the parent
TUICommander process. The worktrees’ tuic-terminal builds have the same Cargo
fingerprint key, while Cargo checks path sources by file mtime;
sharing one target can therefore make an older checkout look fresh against an
artifact from another checkout. The wrapper also keeps test scratch files under
~/Gits. mbx binds its cache socket inside TMPDIR, and a Unix socket path
holds at most 103 bytes on macOS, so a scratch root longer than 51 bytes (a
deep worktree’s .tmp/tuic-tests) moves to ~/Gits/.tmp/tuic-tests; when no
short root exists, the wrapper stops with an error that names the limit.
TypeScript mutation testing
Run Stryker on the changed source files and their relevant Vitest files. Keep both lists narrow; a mutation run executes the selected tests for each mutant.
node scripts/ts-mutants.mjs \
'src/utils/pathUtils.ts:65-65' -- \
'src/__tests__/utils/pathUtils.test.ts'
List the changed source files or line ranges before --, and the tests that
exercise them after it. Read
reports/mutation/mutation.json and the console verdicts. A known behavior
change, such as inverting the pathBasename condition above, must be reported
Killed before treating the other verdicts as evidence. Install this checkout’s
dependencies with pnpm install --offline --frozen-lockfile when its local
node_modules/.bin/stryker is missing; linked worktrees do not share the main
checkout’s executables. The checked-in Stryker config copies frontend inputs,
Rust .rs files under src-tauri/src/, the terminal-grid source, and the generated
command_table_paths.txt into its sandbox. It also copies JSON assets under
src-tauri/{src,crates,fixtures,tests}/ by extension, including shared settings,
intent markers, themes, and test fixtures imported by frontend modules. Recorded
ACP JSONL fixtures under src-tauri/tests/fixtures/acp/ are also included for
frontend consumers. These rules exclude unrelated generated files and vendored
terminal reference grids. Add any
new asset types or files read directly by a Vitest test to that copy policy. It leaves the worktree source untouched and runs
Vitest as a separate command for each mutant. Stryker 10’s
Vitest runner reports false survivors with this repo’s Vitest 5, so it is not
used. Stryker’s TypeScript preprocessor is pointed at an absent file because
this repo’s TypeScript 7 does not expose the compiler API it calls; Vitest still
transforms and runs the TypeScript tests.
Project Structure
See Architecture Overview for full directory structure.
Key Files
| File | Purpose |
|---|---|
src/App.tsx | Central orchestrator |
src-tauri/src/lib.rs | Rust app setup, command registration |
src-tauri/src/pty.rs | PTY session management |
src/hooks/useAppInit.ts | App initialization |
src/stores/terminals.ts | Terminal state |
src/stores/repositories.ts | Repository state |
SPEC.md | Feature specification |
ideas/index.md | Feature concepts under evaluation |
Configuration
App config stored in platform config directory:
- macOS:
~/Library/Application Support/tuicommander/ - Linux:
~/.config/tuicommander/ - Windows:
%APPDATA%/tuicommander/
See Configuration docs for all config files.
Makefile Targets
make dev # Tauri dev mode
make build # Production build (skips updater artifact signing when TAURI_SIGNING_PRIVATE_KEY is unset)
make test # Run tests
make lint # Run linter
make docs # Build this documentation + search index into docs/book
make docs-serve # …and serve it at http://127.0.0.1:8123
make clean # Clean build artifacts
Documentation Site
The book you are reading is mdBook, built
by scripts/build-docs.sh and deployed to GitHub Pages by
.github/workflows/website.yml. The script is the single source of truth — CI
runs the same one, so a local build matches the deployed site.
make docs-serve # build + serve; open http://127.0.0.1:8123
Requires mdbook (brew install mdbook or cargo install mdbook) and npx.
Search is Pagefind, generated after the mdBook build,
which is why file:// previews have no search — the index is fetched over HTTP.
mdBook’s own elasticlunr search is disabled in book.toml.
Adding a page means adding it to SUMMARY.md: mdBook only renders — and
Pagefind only indexes — chapters listed there.
Windows Prerequisites
Building on Windows requires a few extra tools beyond the standard prerequisites. Install them in this order.
1. Visual Studio Build Tools (C++ compiler)
Download and install Visual Studio Build Tools and select the “Desktop development with C++” workload. VS Build Tools 2019 or later is fine.
Or via winget:
winget install Microsoft.VisualStudio.2022.BuildTools
2. Rust
winget install Rustlang.Rustup
Restart your terminal after installation, then verify:
rustc --version
cargo --version
3. Node.js
winget install OpenJS.NodeJS.LTS
4. CMake
Required to compile whisper-rs (the on-device dictation library).
winget install Kitware.CMake
5. LLVM 18 (libclang — required for whisper-rs bindings)
whisper-rs uses bindgen to generate Rust bindings for whisper.cpp, which requires libclang. Use LLVM 18 — LLVM 19+ produces broken bindings for this crate on Windows.
Download the LLVM 18 installer from GitHub releases (LLVM-18.1.8-win64.exe) and install it. Then set the environment variable so bindgen can find it:
# Add to your PowerShell profile or set permanently in System Environment Variables
$env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin"
If you have LLVM 22+ installed (e.g. from winget), install LLVM 18 to a separate directory and point
LIBCLANG_PATHthere instead.
6. Tauri CLI
cargo install tauri-cli --version "^2"
Full Windows Build Command
Always set LIBCLANG_PATH before building:
$env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin" # adjust path if LLVM 18 is elsewhere
cargo tauri build --bundles nsis
The installer will be at:
src-tauri\target\release\bundle\nsis\TUICommander_0.x.x_x64-setup.exe
Windows Known Issues
| Symptom | Cause | Fix |
|---|---|---|
whisper-rs-sys build fails with “couldn’t find libclang” | LLVM not installed or LIBCLANG_PATH not set | Install LLVM 18 and set LIBCLANG_PATH |
whisper-rs-sys compile error: attempt to compute 1_usize - 296_usize | LLVM 19+ generates broken bindings for this crate | Use LLVM 18 specifically |
WiX .msi bundle fails | WiX light.exe tooling issue | Use --bundles nsis instead |
| App window opens but shows a black screen | Navigation guard in lib.rs blocked http://tauri.localhost/ (Windows’ internal Tauri URL) | Fixed in current code — tauri.localhost is explicitly allowed |
Update check failed: windows-x86_64-nsis not found | Custom local build isn’t listed in official release manifest | Harmless — auto-update simply won’t trigger |
Updater diagnostics and fixture binaries
Product builds leave Cargo’s test-fixtures feature disabled. The ACP and MCP
fixture executables are never product sidecars. Nextest’s fixture setup enables
this feature for the library consumers and the main integration-test binary;
plain Cargo integration runs must use --features test-fixtures.
On macOS, verify release binary selection without compiling the app:
PYTHON=python3 scripts/with-test-tmp.sh node --test scripts/test-release-fixture-binaries.mjs
(Python 3.11+ and the installed Tauri CLI are required). This probes the real
bundler against the manifest declarations, with stale fixture executables present.
The checked updater resource is installed by TUIC’s host-only install_app_update
command. It downloads and verifies through the plugin, checks the macOS extraction
volume, and uses the plugin’s native installer. It preserves nested IO causes in
the returned error. A resource id and progress Channel belong to the calling
WebView, so HTTP clients cannot use this command to replace the host application.
The macOS preflight sums archive entries rounded to the volume’s allocation unit and adds 1 MiB of metadata headroom. Download bytes stay in memory; extraction and backup use the same volume and renames. The check reports required and available bytes; concurrent disk use can still cause a later install failure, whose cause is retained. Relaunch deferral remains owned by the existing updater store.
Reusing a pinned agent-test build
For workflow restart evidence, pass AGENT_TEST_REUSE_BUILD_SHA256=<full-sha256>
to make agent-test with the same named instance and port. It verifies the exact
existing binary and all three regular executable artifacts before launch; no
rebuild or copy occurs. Capture the digest from the original build and health
response. Worktree and process isolation still apply. Use the normal build path
after application-source changes.
Heap diagnostic preset
Set AGENT_TEST_HEAP_PROFILE=1 with a named isolated make agent-test instance to compile the opt-in whole-backend allocator profiler. Set _RJEM_MALLOC_CONF before launch; use the shared diagnostic HTTP endpoints to verify activation. Preserve the exact executable and symbols before rebuilding. See Heap profiling.
Continuous Integration
Five GitHub Actions workflows compile Rust:
| Workflow | Trigger | What it compiles |
|---|---|---|
ci.yml | pull request, push to main | clippy + cargo nextest + doctests on Linux, tuic-remote without the desktop feature, macOS and Windows builds on push |
release.yml | version tag | the signed artifacts users install |
remote-daemon.yml | called by release.yml and nightly.yml | tuic-remote and tuic-bridge for Linux x64/ARM64, Windows x64 and macOS ARM64, uploaded to the v* release or to the rolling nightly release |
nightly.yml | push to nightly, manual dispatch | the rolling nightly release |
audit.yml | Monday 09:00 UTC | nothing — a prebuilt cargo-audit runs the advisory scan; accepted advisories live in src-tauri/.cargo/audit.toml |
Frontend test shards
CI runs frontend checks once and Vitest on four independent ubuntu-22.04
runners with --shard=1/4 through --shard=4/4. Vitest discovers the full
configured file set and partitions it. No test-name filter or exclusion is added.
Each shard retains the four-worker cap, default fork pool, per-file isolation,
happy-dom (except explicit per-file environments), setup files and async-leak
detection from vitest.config.ts. Coverage is not enabled in CI.
The required check keeps its name, Frontend (typecheck + tests). It always
runs after frontend-checks and the complete frontend-tests matrix, and accepts
only success from both. Failure, cancellation or a skipped dependency fails
the gate. Matrix fail-fast is disabled so other shards can finish and report
failures. Typecheck, shell tests, workflow contracts, tracked-script checks and
third-party notices remain required. Each shard keeps the old 20-minute budget;
the aggregate check has a five-minute budget and runs no tests.
Duration evidence (story 2347-f621)
Run 40252619205 on b96b2b0fec exceeded the old 20-minute frontend job budget
while test output still advanced. Setup and checks used about 33 seconds;
tests ran from 01:07:45 to cancellation at 01:27:26 UTC. This was not an idle
worker hang. The coordinator’s local run on the same commit completed in
326.91 seconds (917 files passed, two files skipped; 10910 tests passed, three
skipped). The local machine reports 14 logical CPUs. This public repository’s
hosted Linux runner has four vCPUs and 16 GB RAM according to the
GitHub runner specification.
The new resource step records actual Node, CPU, parallelism and memory values.
Two earlier frontend jobs did not hit the job timeout:
| Commit / run | Vitest duration | Result |
|---|---|---|
d3404c764 / 40193236753 | 1133.59 s | One failed test: MobileFontSize, 5000 ms test timeout |
72c7c6823 / 40189776374 | 1140.79 s | The same failed test and timeout |
Both completed 912 passing files and 10871 passing tests. The subsequent font
fixture fix ad834cb712 moves reset module graphs out of the timed assertion.
Sharding does not replace that fix or increase test deadlines.
The 72c7 run attributes tracked time to imports (39%), tests (30%), setup (14%), environment (11%), transforms (5%) and workers (1%). It evaluated 2739 modules 50769 times, spending 1706.49 aggregate seconds importing. The local b96 run shows a similar profile: imports 36%, tests 33%, environment 14%, setup 13%, transforms 5%; 2749 modules evaluated 51144 times, with 422.31 aggregate import seconds. These are aggregate worker timings, not wall time. Expensive repeated isolated evaluation and DOM/setup work are present on both machines; the config has no CI-only pool, worker or coverage branch. The evidence supports distributing the work, not disabling isolation or raising worker counts. It does not isolate CPU speed, contention and verbose reporter I/O as separate causes of the hardware-dependent slowdown.
The cancelled b96 verbose log has these largest sums of reported individual test timings per file (not complete file durations, which include imports and setup):
File under src/__tests__/ | Timed test sum |
|---|---|
hooks/useAgentPolling.test.ts | 112.924 s |
stores/repositories.test.ts | 44.681 s |
stores/mdTabs.test.ts | 44.656 s |
stores/terminals.test.ts | 31.227 s |
components/FileBrowserPanel/FileBrowserPanel.test.tsx | 26.863 s |
The default reporter now emits file-level timings rather than a line for every passing test. This makes future slow-file analysis direct; no measured speedup is attributed to the reporter change. Four parallel shards target roughly 5-8 minutes each based on the old 19-minute run, with allowance for imbalance and cold transforms. This is an estimate, not a CI result. Two consecutive green runs on main remain the acceptance gate after the coordinator pushes.
Local verification used CI=true, the same config and shard arguments, and
an additional JSON reporter to compare executed file sets:
| Shard | Discovered/reported files | Passed tests | Existing skipped tests | Vitest duration |
|---|---|---|---|---|
| 1/4 | 230 | 2525 | 2 | 75.97 s |
| 2/4 | 230 | 2589 | 0 | 95.78 s |
| 3/4 | 230 | 2687 | 1 | 75.89 s |
| 4/4 | 229 | 3109 | 0 | 86.51 s |
The actual shard file sets are disjoint and their union equals all 919 files
from unfiltered Vitest discovery. Totals match the coordinator’s unsharded run:
10910 passed tests and three existing skips. No test was skipped by this change.
The font fixture passes too. Runs were sequential to bound local resource use;
these numbers do not claim a Linux CI pass. Vitest 5 list --filesOnly ignores
--shard, so do not use it as a shard manifest: compare the JSON reports from
actual runs instead. The workflow contract test also exercises the aggregate
shell command against all 16 pairs of success, failure, cancellation and skip.
Nightly release ordering
The nightly workflow checks out the public nightly snapshot, pins every build
and notes job to that commit, and passes it to the reusable daemon workflow.
make nightly publishes that snapshot through the shared squash tool; development
main stays private. The cleanup job moves the nightly tag, deletes the old release and recreates an
empty prerelease before the desktop and daemon matrices start. Successful daemon
builds can publish even if every desktop build fails. tauri-action reuses the
release with that tag and alone writes latest.json; daemon uploads contain only
tuic-remote and tuic-bridge binaries.
Nightly macOS build budget
The nightly macOS Tauri step has a 90-minute limit inside a 105-minute job. Linux and Windows retain their 60-minute step and 90-minute job limits. The version-tag release workflow is unchanged.
Duration evidence (story 2449-758d)
| Nightly run / macOS job | Cargo target cache | Tauri step | Main Cargo build |
|---|---|---|---|
40293763128 / 121474831042 (last green) | Restored about 986 MB | 32m28s | 30m04s |
40267929758 / 121394367658 (earlier cold green) | Not found | 50m34s | 47m14s |
40706484667 / 122880064054 (failed) | Not found | Cancelled at 60m01s | Did not finish |
All three used Rust 1.99.1 and runner image 20261013.0424.1
(macos-26-arm64). The failed run spent 45 seconds on job setup. Within the
Tauri step, the frontend finished at 14:31:32 UTC and both sidecars finished
by 14:32:26. The main Cargo build then ran until cancellation at 15:30:53,
without reaching application bundling, signing or notarization. Its last
compiler log line was at 14:44:17. sccache reported zero Rust hits and 863 Rust
misses, compared with 14 Rust misses in the last green run. The earlier cold
green also had 863 Rust misses. The last green needed about 96 seconds after
Cargo completed for packaging, notarization and upload.
This proves a cold build exceeded the old step limit; it does not prove whether the final quiet period was slow optimization/linking or a compiler hang. The 90-minute step gives 50% more time than the exhausted 60-minute budget. The 105-minute job reserves another 15 minutes for setup and post actions. These are bounded allowances, not a measured completion time for the failed commit. The next nightly must confirm completion and asset publication; a local build cannot prove the hosted runner’s elapsed time.
The retry-failed job did not run a second build: its log says
run 40706484667 cannot be rerun; This workflow is already running.
That separate retry limitation is not evidence of a second build timeout.
The Rust toolchain is pinned
Every dtolnay/rust-toolchain step takes its version from a workflow-level
RUST_VERSION variable:
env:
RUST_VERSION: "1.99.1"
# ...
- name: Install Rust ${{ env.RUST_VERSION }}
uses: dtolnay/rust-toolchain@stable
with:
toolchain: ${{ env.RUST_VERSION }}
The action’s toolchain input overrides the @stable branch default, so the
branch name in uses: no longer decides the compiler.
Why
@stable on its own floats. The day rustup publishes a new stable, the compiler
changes under the repository with no commit to point at: fresh clippy lints and
rustfmt reflows become a red main for whoever pushes next, not for whoever
wrote the code. That has happened three times — 7db734f9, 20e58629, and the
1.98 lints cleared on 2026-08-31 while CI was still green on an older stable, so
the tree failed locally and passed in CI at the same commit.
Pinning also makes the release reproducible: a tag built today and rebuilt in six months uses the same compiler.
How to bump the pin
-
Install the target toolchain locally (
rustup toolchain install <version>) and make it the default for this checkout. -
From
src-tauri/, confirm both gates are clean:cargo clippy --all-targets -- -D warnings cargo fmt --checkFix whatever the new compiler flags. This is the work the pin defers to a deliberate moment instead of ambushing the next push.
-
Raise
RUST_VERSIONin all five workflows —ci.yml,release.yml,remote-daemon.yml,nightly.yml,audit.yml— in a single commit. -
Push. CI runs on the new toolchain as part of that commit, so any breakage lands on its author and is bisectable.
Never raise the pin in one workflow only: ci.yml would then vouch for a
compiler that release.yml does not use.
The local
rustcis not pinned by arust-toolchain.toml, on purpose — contributors keep their own rustup default.cargo fmt --checkand clippy are the contract; the CI pin is what makes that contract stable over time.
Note on clippy scope
CI runs cargo clippy --workspace --exclude bm25 --all-targets -- -D warnings.
It includes test and bench code. The vendored bm25 patch is excluded from
Clippy, but remains in workspace tests.
Windows library compile check
The Windows CI leg runs cargo check --locked --manifest-path src-tauri/Cargo.toml --lib --target x86_64-pc-windows-msvc before Clippy and tests. This check rejects Windows-only source errors, such as unguarded Unix signal constants, without linking a desktop application or test binary.
Windows CMake debug flags
CI, release and nightly set CMAKE_C_FLAGS and CMAKE_CXX_FLAGS to -Z7
on Windows for sccache-compatible MSVC debug information. MSVC accepts both
slash and dash prefixes. Use the dash form because Git Bash converts /Z7
in environment variables into a Windows path before launching native Cargo.
That path reaches the CMake compiler probe as a source filename and fails the
whisper-rs-sys build. The Tests step uses Git Bash through
scripts/with-test-tmp.sh, so these flags must be safe in both shell paths.
Windows rustc command length
Release and nightly set CMAKE_CONFIGURATION_TYPES=Release on Windows.
whisper-rs-sys adds every directory below its CMake build tree as a rustc
-L path, and every crate that depends on it gets these paths. The Visual
Studio generator of CMake 4.5 makes Debug, MinSizeRel, RelWithDebInfo
and Release folders for each target, also in the vulkan-shaders-gen
sub-build (CMake 3.29 does not). With --features vulkan, the rustc command
for tuicommander_lib in release run 43660914077 was 35,835 characters.
Cargo passes a command that is too long through a response file, but sccache
0.19 expands that file and starts rustc with the full command. Windows accepts
at most 32,767 characters, so the build failed with os error 206 (sccache 0.16
passed the response file through without caching). With only the Release
configuration, CMake makes 60 fewer folders and the same command is 28,772
characters. CMake also reads the variable from the environment, so the
vulkan-shaders-gen sub-build gets it. A local build without sccache does not
need it.
Portable whisper.cpp CPU baseline
Release and nightly set GGML_NATIVE=OFF on every desktop leg.
whisper-rs-sys passes every GGML_* environment variable to CMake. With
the ggml default (native on), the x64 builds used the CPU of the GitHub runner
and emitted AVX-512, and dictation crashed on AVX2-only CPUs (issue #151).
With native off, x64 gets SSE4.2, AVX, AVX2, FMA, F16C and BMI2, and no AVX-512.
On macOS only -march=armv8.4-a from CMAKE_C_FLAGS applies, and every M1
supports it. A native build there takes the features of the runner chip.
whisper-rs-sys does not declare GGML_* with rerun-if-env-changed, so
cargo reuses a restored ggml build that was configured with other flags. The
“Drop cached whisper-rs-sys build” step removes its build-script output and
fingerprints before each build. After the build, the x64 legs run
scripts/check-ggml-x86-baseline.sh, which fails when a ggml static library
contains zmm registers or when ggml-cpu has no ymm code (an empty
disassembly).
Headless workspace scope
The remote job checks tuic-remote with --no-default-features. Dictation is
already an optional dependency behind desktop; the headless daemon does not
use WebRTC. Its workspace test command also excludes tuic-dictation, because
--workspace selects that desktop-only member independently of feature flags.
The desktop workspace jobs still compile and test dictation with Meson and Ninja.
Nextest setup scope check
make test-shell runs the frontend job’s tool-independent shell tests. The
Nextest fixture setup scope check is named scripts/check-nextest-fixture-scope.sh
and runs explicitly in the Linux Rust job after workspace tests. That job
installs Nextest and already has the compiled test binaries. The check retains
its positive fixture-consumer and negative non-consumer assertions.
macOS CI test compilation
The macOS cross-platform job has a 90-minute timeout. On 9a49ff1cb, Clippy
finished in 9m27s and the test build took 67m17s. Nextest fixture setup then
spent 532.140s building the headless fixture binaries. Actual test execution
had only about 4m18s before cancellation, with 6483 of 7391 tests passing.
The longest completed test took 41.268s. This log does not separate compiler
optimization from linking, and does not measure a complete suite duration.
The macOS and Windows Tests steps set CARGO_PROFILE_TEST_OPT_LEVEL=0 to avoid
optimizing workspace test harnesses. Non-workspace dependencies retain the
inherited [profile.dev.package."*"] optimization level of 1. The explicit
tuic-terminal test override also stays at 1 for corpus replays. Test selection,
retries, hang detection and the job budget stay the same. This does not change
release builds. The next CI run must measure the compile-time benefit and check
for runtime regressions.
Fixture build profile and Windows cache
On Windows run 40150611058, the test build took 45m36s. Nextest setup then
built the fixtures with the dev profile and no default features for 18m15s.
Dev includes debug information that the test profile disables. This second
profile and feature graph prevent reuse of many artifacts from the test build.
Local lib-only fixture setup uses cargo build --profile test --no-default-features --features test-fixtures. Desktop CI runs nextest with
--features dictation,test-fixtures and sets
TUIC_FIXTURE_FEATURES=dictation,test-fixtures, which selects
cargo test --workspace --no-run --features dictation,test-fixtures instead.
The setup script passes that value unchanged. This
matches nextest’s workspace test selection, including dev-dependency feature
unification. A binary-only build with --profile test does not activate dev
dependencies: under resolver 2 it omits features such as tokio/test-util and
tuic-core/test-support, so profile and top-level feature alignment alone do
not establish graph reuse.
The CI setup command runs no tests. Integration targets make Cargo build the
normal fixture executables; setup can reuse the workspace artifacts nextest
already built. Both paths put the executables beside the test binary’s deps
directory under debug, so consumer path resolution does not change. Setup
scoping remains unchanged: unrelated lib tests do not build fixtures.
scripts/check-fixture-build-graph.py captures each builder’s actual command
and compares its resolved package-feature graph with CI’s workspace test graph.
It does not replace a full-workspace warm-build measurement on Windows.
That Windows run restored no Cargo target cache. Rust sccache reported 131 hits
and 1291 misses (9.21% hit rate); linked binaries and proc macros were among its
non-cacheable calls. sccache does not replace the Cargo target cache. The Windows
Rust cache now saves after a failed or cancelled job too, so later runs can
restore the existing C:/t artifacts instead of depending only on sccache.
These changes do not prove that Windows fits its 90-minute bound: a complete
Windows CI run remains the required runtime evidence.
Release notes size
The nightly update-notes job groups commits since the latest stable tag.
Before publication, scripts/cap-release-notes.py limits the notes to 120000
UTF-8 bytes, below GitHub’s 125000-character body limit. Oversized notes end at
a complete line and include a link to the full comparison against main.
Short notes keep their original contents.
The version-tag workflow uses the matching CHANGELOG.md section and a download
legend. It does not use the nightly commit-history notes step.
Performance Profiling
Repeatable profiling infrastructure for identifying bottlenecks across the full stack: Rust backend, SolidJS frontend, Tauri IPC, and terminal I/O.
Quick Start
# Install profiling tools (one-time)
scripts/perf/setup.sh
# Run all automated benchmarks (app must be running)
scripts/perf/run-all.sh
# Or run individual benchmarks
scripts/perf/bench-ipc.sh # IPC latency
scripts/perf/bench-pty.sh # PTY throughput
scripts/perf/record-cpu.sh # CPU flamegraph
scripts/perf/record-tokio.sh # Tokio runtime inspector
scripts/perf/snapshot-memory.sh # Memory profiling guide
Results are saved in scripts/perf/results/ (gitignored).
Tools
| Tool | What it profiles | Install |
|---|---|---|
| samply | Rust CPU time (flamegraphs) | cargo install samply |
| tokio-console | Async task scheduling, lock contention | cargo install tokio-console |
| hyperfine | Command-line benchmarking | brew install hyperfine |
| Chrome DevTools | JS rendering, memory, layout | Built into Tauri webview |
| Solid DevTools | SolidJS signal/memo reactivity graph | Browser extension |
All tools are installed by scripts/perf/setup.sh.
Rust Backend
CPU Flamegraph
scripts/perf/record-cpu.sh --duration 60
Builds a release binary with debug symbols, records under samply for 60 seconds, saves a JSON profile. Open the result with:
samply load scripts/perf/results/cpu-YYYYMMDD-HHMMSS.json
What to look for:
- Functions with wide bars = high cumulative CPU time
std::process::Commandin hot paths = subprocess forksserde_json::to_value/serde_json::to_string= serialization overheadparking_lot::Mutex::lock= contention
Tokio Runtime Inspector
scripts/perf/record-tokio.sh
Builds with the tokio-console Cargo feature and launches both the app and the console UI. The console shows live stats for every Tokio task.
What to look for:
- Tasks with high “busy” time = CPU-bound work on the async executor
- Tasks with high “idle” time = blocked on I/O or lock contention
- Tasks stuck in “waiting” = possible deadlock
- Many short-lived spawn_blocking tasks = check if batching would help
Note: This uses a debug build. Timing numbers are not representative of production performance, but relative proportions and task scheduling patterns are valid.
Building with tokio-console manually
cd src-tauri
RUSTFLAGS="--cfg tokio_unstable" cargo build --features tokio-console
Then run the binary and connect tokio-console separately:
tokio-console
The console subscriber listens on 127.0.0.1:6669 by default.
IPC Latency
scripts/perf/bench-ipc.sh # auto-detect repo
scripts/perf/bench-ipc.sh /path/to/repo 50 # 50 iterations
Measures round-trip latency for key git commands via the HTTP API on port 9877. Reports p50, p95, and mean for each endpoint.
Endpoints measured:
repo_info(cached after first call, 5s TTL)diff_stats,changed_files,branchesrecent_commits,stash_list,remote_url
Interpreting results:
- p50 < 5ms for cached endpoints = healthy
- p50 < 50ms for uncached git commands = healthy
- p95 > 200ms = investigate (large repo? slow disk? lock contention?)
To measure cold vs warm cache, run bench-ipc.sh twice in quick succession: the first run hits cache misses, the second should show cache hits.
PTY Throughput
scripts/perf/bench-pty.sh # 10MB default
scripts/perf/bench-pty.sh 50 # 50MB stress test
Creates a PTY session, blasts data through it, and measures throughput in MB/s. Tests the full pipeline: PTY read -> UTF-8 decode -> escape processing -> VT100 parse -> Tauri event emit.
If the API doesn’t support session creation, the script prints manual commands to run in an existing terminal tab for the same measurement.
Frontend
Performance Recording
- Open DevTools in TUICommander:
Cmd+Shift+I - Go to Performance tab
- Click Record
- Exercise the scenario for 10-30 seconds
- Stop recording
What to look for:
- Long Tasks (>50ms red bars) = jank
- Layout/Recalculate Style = CSS forcing reflow
requestAnimationFramegaps = dropped frames- Frequent minor GC = allocation pressure
Memory Profiling
Run scripts/perf/snapshot-memory.sh for detailed scenario instructions. Key scenarios:
- Terminal memory — open/close 5 terminals, compare heap snapshots
- Panel leak check — open/close Settings/Activity/Git panels 10x
- Long-running session — compare snapshots at 0/10/20 minutes
Expected baselines:
- Each terminal: ~1.6MB heap (10k scrollback lines at 80 cols)
- Panel open/close cycle: <500KB retained after GC
- 20-minute session: sub-linear growth (not linear)
SolidJS Reactivity
Install Solid DevTools browser extension. In the devtools panel:
- Check how many times each
createMemore-evaluates - Find effects with unexpectedly high execution counts
- Trace which signal changes trigger cascading updates
Key areas to watch:
terminalsStoreupdates propagating to StatusBar/TabBar/SmartButtonStripdebouncedBusysignal reactivity scopegithubStorepolling triggering re-renders in unrelated components
Profiling Scenarios
Scenario 1: Startup Performance
scripts/perf/record-cpu.sh --duration 30
Open the app, wait for it to fully load, open DevTools Performance tab. Measure time-to-interactive.
Target: < 2s from launch to first terminal ready.
Scenario 2: Multi-Terminal Steady State
- Open 5 terminal tabs
- Run an AI agent in 2 of them
- Record CPU + memory for 2 minutes
- Check: is CPU usage stable? Is memory growing?
Scenario 3: Git-Heavy Workflow
- Open a large repo (>1000 commits, >50 branches)
- Open the Git panel
- Switch branches
- Run
bench-ipc.shagainst this repo
Scenario 4: High-Throughput Output
In a terminal tab:
dd if=/dev/urandom bs=1024 count=10240 | base64 # ~14MB of random base64
yes | head -n 500000 # ~2MB of repetitive data
find / -type f 2>/dev/null # realistic filesystem output
Monitor CPU usage and app responsiveness during output.
Comparing Results Across Sessions
Results accumulate in scripts/perf/results/:
results/
ipc-20260328-143000.txt # IPC latency run
ipc-20260330-091500.txt # After optimization
cpu-20260328-150000.json # CPU flamegraph
pty-throughput.log # PTY throughput history (appended)
Compare IPC results:
diff scripts/perf/results/ipc-{before,after}.txt
The PTY throughput log is append-only — each run adds a line for trend tracking.
Architecture Reference
The profiling targets map to these code areas:
| Layer | Key files | What to measure |
|---|---|---|
| Tauri commands | src-tauri/src/git.rs | spawn_blocking overhead, subprocess latency |
| PTY pipeline | src-tauri/src/pty.rs | Read buffer throughput, event emission rate |
| IPC serialization | src-tauri/src/pty.rs, git.rs | JSON payload sizes, serde time |
| State management | src/stores/terminals.ts | Signal propagation scope, batch effectiveness |
| Rendering | src/components/Terminal/CanvasTerminal.tsx | Grid frame batching, canvas atlas rebuilds |
| Polling | src/hooks/useAgentPolling.ts, src/stores/github.ts | Interval frequency, IPC calls per tick |
| Bundle | vite.config.ts | Chunk sizes, initial parse/eval time |
Agent Testing Rules
These rules moved here from AGENTS.md to keep that file inside the
32,768-byte project-instruction budget. They stay binding for every agent;
AGENTS.md keeps a summary and a link to this page.
The suite skips every test it cannot run on purpose — classify them, never pin the count
cargo nextest run --lib reports a handful of skips. Every one is #[ignore]
with a reason string. None is a cfg exclusion and none is a filter artifact,
so the skips are not missing coverage and not a harness defect: N run, M skipped is a complete result for what an unattended run can execute.
| Category | Precondition an unattended run cannot meet |
|---|---|
| Environment | interactive Keychain (×4), network + GitHub token (×2), authenticated gh CLI, a downloaded whisper model, a downloaded Pocket TTS bundle (×3, TUIC_POCKET_BUNDLE_DIR), real openpty |
| Corpus-driven | TUIC_CAPTURE_CORPUS, TUIC_DAMAGE_CORPUS, TUIC_REPLAY_FILE, plus 744-138c’s evidence capture |
| Benchmark | bench_chunk_path_replay, tunnels::audit::tests::bulk_insert_performance, mcp_http::ws_compression::measurement::level_six_is_the_knee_of_the_curve |
The per-category counts are deliberately not written down — see “Never assert the skip count” below. On 2026-09-21 the three categories held 12, 4 and 3.
dump_committed_tcap_fixture_event_sequences_744 is not a pass/fail test. It
is an evidence-capture harness for story 744-138c and the comment above it says
so. Un-ignoring it during a tidy-up of ignored tests is the failure to avoid.
Re-derive the classification; do not trust a count. Counting #[ignore]
attributes in the source happens to give the right answer for the wrong reason —
it counts one mechanism and cannot see the other two. This does discriminate:
cargo nextest list --lib --run-ignored all -> 4851
cargo nextest list --lib -> 4832
The delta is the skip count and the set difference is those names (19 on
2026-09-21). A cfg-excluded test
is absent from both lists, so the delta would not close if any were excluded
that way; a filtered skip would move the second number alone.
--run-ignored ignored-only is stronger still: it lists the set instead of
implying it by subtraction, and run against both configurations it names the one
test in the difference rather than leaving a count to interpret.
Parse that output carefully, because a wrong pattern returns zero and so does
an empty set. nextest list prints tuicommander <path> with no leading
whitespace; a grep -E '^\s+\S+::' written on the assumption that it indents
returns 0 lines for every configuration, exits 0, and answers a different
question. That is the same failure as a vacuous -E filter and as counting
#[ignore] attributes — a command that ran and told you nothing, in a shape
indistinguishable from a real result.
Never assert the skip count. It breaks the first time someone adds a legitimately ignore-worthy test, and it asserts nothing about whether the right tests run — green-by-absence one level up. The mechanism is the durable fact; the number is not. Note also that the raw totals above drift within a single afternoon as agents land tests in a shared tree (5170 → 5171 → 5172 → 5173 on 2026-09-13, all benign), which is exactly why the re-derivation method belongs here and the numbers do not.
--no-default-features reports four fewer, because mod dictation is
#[cfg(feature = "desktop")] (lib.rs) and its four ignored tests — one
whisper, three Pocket TTS — do not exist in that build: absent rather than
skipped. No #[ignore] anywhere is cfg-conditional, so nothing else moves
between the two configurations.
Which timing assertions are load-bearing
A test that waits on wall-clock time asserts one of three things, and they are not
interchangeable. Before adding an Instant deadline, decide which row you are writing.
| Bound | Belongs to | Rule |
|---|---|---|
| the behaviour under test | “a mute upstream gives up” | keep it — and arm it after setup succeeds |
| setup reaching a state | handshake, fetch, process start | it must not be able to fail: size it so it cannot, or delete it |
| “did this hang forever” | the outer harness bound | strictly larger than every bound inside it, or its message lies |
Never let one deadline serve two rows. call_tool_gives_up_on_a_mute_upstream
handed its 300ms give-up deadline to the handshake as well; a loaded machine pushed
the handshake past it and the test failed as call_tool never returned — accusing the
exact mechanism it exists to prove works. Two named budgets is the fix.
A freshly written executable is not a cheap thing to run. With exec-time code
scanning (macOS syspolicyd plus an endpoint-security agent) the first exec of a new
file blocks while it is scanned, while re-exec’ing the same file costs ~6ms. The
scan cost is episodic, not a constant: a quiet scanner charges ~0.25s for a fresh
inode and a backlog charges tens of seconds — 6s to 102s was measured here, 393s at
the worst. There is also a smaller persistent penalty (~1.5-2.7x) on /var/folders/…/T,
which is where tempfile::TempDir lands. How the two compound is unresolved on
purpose: a multiplicative model predicts ~9s where 393s was measured. None of that
changes the remedy, and chasing either variable is wasted time. A
per-run temp script pays that scan inside the test’s own timing window on every run,
which is why four tunnels::supervisor tests failed with the suite idle and passed
under a full parallel run. fake_ssh_script now keys the script by test name under
target/fake-ssh/, compares content, and execs it once with TUIC_FAKE_SSH_WARMUP set
before any supervisor starts: ~44s cold, once per machine, then ~1s a run. Do not
simplify it back to a NamedTempFile. The same reasoning applies to any test that
writes and runs a script — sh <script> is free, ./script is not.
A fetch that ran out of time looks exactly like a fetch that failed. Both fall
through to the remote-tracking ref, so FETCH_TIMEOUT’s 5s cfg(test) value turned a
conflict_assist test about which base ref wins into a test of how fast git had
been. Where the deadline is not the subject, pass an explicit bound instead
(resolve_rebase_target takes one) and let nextest’s slow-timeout catch a real hang.
The failure mode to fear is a bound you cannot tell apart from a bug. #[ignore],
#[serial] and --test-threads=1 all hide it rather than fix it, and cost coverage to
do so. When a timing assertion does fire, its message must name what actually broke —
otherwise the next reader spends a day re-diagnosing the wrong subsystem.
Test instance vs orchestrator instance — READ BEFORE TESTING
There are TWO running TUICommander instances; do not confuse them:
- Orchestrator instance — the one this agent is embedded in. The
tuicommanderMCP tools anddebug invoke_jstarget THIS instance (Mission Control on:14319, app logs on:9876). It does NOT run your worktree build, so testing it proves nothing about your changes. - Test instance — the isolated worktree build started with
make agent-testwhen desktop execution is authorized. Test it only via its own HTTP API, defaulthttp://127.0.0.1:19876. MCP/invoke_jscannot reach it. Implementation-only assignments must not launch it.
Test-instance endpoints (see src-tauri/src/mcp_http/mod.rs): GET/POST /sessions, DELETE /sessions/{id}, POST /sessions/{id}/write, GET /sessions/{id}/output, and terminal grid ops (all session-scoped) POST /sessions/{id}/terminal/scroll {delta}, POST /sessions/{id}/terminal/scroll-to {line} (absolute; line=top row, 0=oldest), POST /sessions/{id}/terminal/scroll-to-offset {offset} (coalesced display-offset jump; powers wheel + scrollbar-drag in browser mode), GET /sessions/{id}/terminal/scroll-info, GET /sessions/{id}/terminal/lines?start&end, GET /sessions/{id}/terminal/row-text?row, POST /sessions/{id}/terminal/search-buffer {query}. Create a throwaway session, exercise it, then DELETE it — never test against Boss’s live sessions.
Canvas rendering (selection highlight, smooth-scroll visuals, cursor) is not observable over HTTP — those still need a visual check with Boss.
Web-UI testing with agent-browser (browser mode, not Tauri)
You can exercise features through the web UI instead of the Tauri desktop app — every instance serves the full frontend at http://localhost:<port>/ (static_files.rs FRONTEND_DIST). Loading it in a real browser is browser mode (isTauri() === false), the exact web/PWA path a remote client sees.
- Port: authorized agent desktop checks use
make agent-test, preset tohttp://127.0.0.1:19876/. Do not launch another desktop throughmake devor use the orchestrator’s :9876 for change verification. The agent-test port is explicit and has no next-port fallback; see the development guide for overrides. - Drive it with
agent-browser, always via the stealth wrapper (see global rules).@refCDP clicks are trusted and work (open modals/panels/tabs); JS-dispatched keydown isisTrusted:falseso app keyboard shortcuts (Cmd+P, etc.) are ignored — click UI, never synthesize keys. Use a persistent--session <name>, restart the browser periodically (snapshots/clicks degrade after many calls), and wrap each call in aperl alarmtimeout (macOS has notimeout/gtimeout). - Isolation:
make agent-testselectsTUIC_APP_INSTANCE=agent-testwith a distinct binary, app identity and socket. It does not copy the daily config and disables global input, microphone, Telegram and updater. Ordinary default-instance debug/release launches still share config, so do not use them as substitutes. Filesystem access remains shared: use throwaway repositories, never Boss’s repositories, for repo-mutating checks. - The Command Palette DOES render in web mode.
App.tsx:984mounts it unconditionally as<CommandPalette actions={actionEntries()} browserMode={!isTauri()} />;browserModefilters the action list down to the HTTP-safe subset inBROWSER_ACTION_IDS/BROWSER_ACTION_PREFIXES(CommandPalette.tsx:27-103), which includessearch-filesandsearch-file-contents. Only the opening shortcut is unavailable toagent-browser: a JS-dispatched Cmd+P isisTrusted:false, so click the UI instead — that is a test-harness limit, not a missing feature. - Desktop-only features do NOT render in web mode — IdeLauncher, Dictation, Global Hotkey, detach-panel windows, updater, native file drop, user-plugin install, MCP/hooks config. Built-in plugins DO load. See mdkb
web-mode-verification-2026-07-02for the verified inventory before reporting a feature “missing”.
Documentation Sync Matrix
Every code change that affects user-visible behavior, APIs, or configuration MUST update the corresponding documentation files. This matrix maps codebase areas to their docs.
New Feature Checklist
- Feature works correctly
- Keyboard shortcut added (if applicable) —
keybindingDefaults.ts+actionRegistry.tsACTION_META -
docs/FEATURES.mdupdated with new feature entry -
CHANGELOG.md— entry in Unreleased section -
SPEC.md— feature status updated - Domain-specific docs updated (see matrix below)
- Screenshot taken (if visual/CSS/layout change)
-
src/data/tips.ts— add a Tip of the Day entry for discoverable features
Sync Matrix by Area
Plugin System
When modifying PluginHost API, capabilities, manifest schema, Tauri commands used by plugins, plugin panel rendering (base CSS, theme injection, iframe behavior), or plugin infrastructure (loader, registry, discovery):
| File | What to update |
|---|---|
src/plugins/types.ts | PluginHost interface, PluginCapability union, snapshot types |
src/plugins/pluginRegistry.ts | Implementation in buildHost() |
src/components/PluginPanel/pluginBaseStyles.ts | Base CSS classes available to all plugin panels |
src-tauri/src/plugins.rs | KNOWN_CAPABILITIES list (new capabilities); set_plugin_output_watchers sync |
src-tauri/crates/tuic-terminal/src/output_watchers.rs | Rust-side OutputWatcher matching: WatcherSpec, OutputWatcherRegistry::sync (per-client sets; which patterns are rejected back to the frontend), to_portable_pattern (ECMAScript class escapes — Rust may over-match, never under-match), clean_line — a port of src/utils/stripAnsi.ts + the backtick strip — and StreamLines, the only line assembler. Changing stripAnsi.ts requires changing clean_line, or the two sides match on different text |
src-tauri/src/lib.rs | Register new Tauri commands in invoke_handler |
docs/backend/command-threading.md | Where a new command runs (fn = macOS main thread). Update the audit when a command changes placement |
docs/plugins.md | Plugin developer guide (API reference, capabilities table, Panel CSS Design Strategy section, examples) |
src-tauri/src/mcp_http/plugin_docs.rs | AI-optimized plugin reference (PLUGIN_DOCS const — must stay in sync with docs/plugins.md); cargo nextest run -E 'test(plugin_docs)' checks source-derived capability, host method, base CSS and manifest/core UX inventories. Extend the UX check when adding settings schema field kinds or Tasks views. |
docs/api/tauri-commands.md | Tauri commands reference table |
docs/api/http-api.md | HTTP API reference (if new HTTP endpoints) |
docs/backend/mcp-http.md | MCP/HTTP server docs (if new routes) |
docs/FEATURES.md | Section 17.1 capabilities list |
docs/user-guide/plugins.md | User installation/management guide |
Terminal & PTY
When modifying PTY behavior, output parsing, shell state, or terminal UI:
| File | What to update |
|---|---|
docs/backend/pty.md | PTY session lifecycle, reader threads, output handling |
docs/backend/output-parser.md | Rate limits, structured events, parsing rules |
docs/frontend/canvas-terminal-audit.md | CanvasTerminal feature completeness audit |
docs/frontend/terminal-features.md | Consolidated terminal behaviors, shortcuts, configurable features |
docs/FEATURES.md | Section 1 (Terminal Management) |
docs/user-guide/terminals.md | User-facing terminal features |
docs/api/tauri-commands.md | PTY commands (create_pty, write_pty, resize_pty, etc.) |
docs/backend/alacritty-integration.md | Alacritty patch inventory, upstream API usage, update procedure |
Keyboard Shortcuts & Actions
When adding or changing shortcuts:
| File | What to update |
|---|---|
src/keybindingDefaults.ts | ACTION_NAMES + default key combo |
src/actions/actionRegistry.ts | ACTION_META (label, category) — auto-populates Settings and Command Palette |
src-tauri/src/native_keys.rs | macOS NSEvent monitor for keys WKWebView never forwards (Ctrl+Tab, F13–F20). Keep it as ONE KeyDown monitor — a second one doubles per-keystroke work on every key typed |
src/hooks/useNativeKeyCombo.ts | Turns native-key-down back into a combo string identical to keyEventToCombo’s; used by every recorder |
docs/FEATURES.md | Section 15 (Keyboard Shortcut Reference) |
docs/user-guide/keyboard-shortcuts.md | User-facing shortcut table |
docs/frontend/hooks.md | useNativeKeyCombo entry |
Tauri Commands & IPC
When adding or changing Tauri commands:
| File | What to update |
|---|---|
src-tauri/src/lib.rs | invoke_handler! macro registration |
src/transport.ts | COMMAND_TABLE entry, or INTENTIONALLY_UNMAPPED if host-only |
src-tauri/src/mcp_http/command_table_paths.txt | Generated — regenerate with pnpm vitest run src/__tests__/transport.test.ts -u. The Rust route probe reads it; never hand-edit |
docs/api/tauri-commands.md | Command signature + description |
docs/api/http-api.md | HTTP endpoint mapping (if browser/remote mode) |
| Domain backend doc | e.g. docs/backend/pty.md, docs/backend/git.md |
Tauri events emitted by backend
When adding a new app.emit(event_name, payload) call, document it here and listen in useAppInit.ts:
| Event | Payload | Emitted from | Frontend listener |
| provider-quota-changed | QuotaView | provider_quota_transport.rs, desktop emit and /events | providerQuotaStore |
provider-quota-binding-changed | {session_id, key}; null key retracts the binding | provider_quota_transport.rs, desktop emit and /events | providerQuotaStore |
|---|---|---|---|
boss-attention-changed | {} | Typed report, input and story mutations, and a changed Fabbrica read (fabbrica_attention.rs poller); desktop plus SSE. Remote authoritative reseeds retain origin ownership. | waitingItemsStore rereads while retained (App bell sync, Plans and Stories, Activity Dashboard health); reconnect and repository revisions also refresh |
ideas-changed | {} | Planner and UI notes mutations after persistence; desktop plus /events SSE | ideasStore.hydrate() reloads after local writes; reconnect also reloads |
ai-chat-selection-changed | {} | Config transaction after shared AI Chat selection changes; desktop plus /events SSE | createAiChatSelectionSync rereads the host selection on invalidation and reconnect; useAcpChat adopts without echo writes |
open-markdown-tabs-changed | {} | open_markdown_tabs::publish: desktop IPC and /events SSE after a changed metadata snapshot | createOpenMarkdownTabs refetches one session-owned list shared by the mobile menu and wide-screen dropdown |
background-mode-changed | { state: "hidden" | "unloaded" | "visible" } | Rust background lifecycle, desktop + /events SSE | useAppInit.ts logs desktop state; remote clients may display it |
close-dialog | { kind: "ask" | "confirm_quit", sessions: number, background_available: boolean } | Rust background close policy; dual-emit to desktop and /events SSE | useAppInit.ts presents it on desktop only |
native-notification-click | { kind: "terminal", id }, { kind: "progress", project, ptyId? }, { kind: "aichat", id }, { kind: "automation", id } or { kind: "pr", url } | native_notification.rs when a macOS Notification Center alert is clicked; desktop window only | useAppInit.ts → navigateFromNativeNotice → terminal, Progress dialog, AI Chat, saved automation run or the PR conversation in Tasks (GitHub fallback without a loaded provider) |
session-created | { session_id, tuic_session: string | null, cwd, agent_type, display_name, parent_session } | Generic HTTP sessions and MCP/HTTP agent spawns use session.rs emit_native_agent_session_created for desktop; register_pty_session publishes SSE with the same live identity binding | useAppInit.ts retains tuic_session for live caller-bound worktree placement |
session-standby | { session_id: string, standby: bool } | pty.rs emit_standby_event() | useAppInit.ts → terminalsStore.update(termId, { standby }) |
design-mode-changed | { repo_path: string, session_id: string, status: "armed" | "stopped" } | design_mode lifecycle, dual-emitted to the desktop window and event_bus → /events SSE when inspection starts, rebinds or stops | Design Mode status listener → bound agent tab indicator; reads the repository and session from the event, not the currently focused tab |
worktree-created | state.rs WorktreeCreatedPayload — `{ repo_path: string, workspace_id: string, branch: string, worktree_path: string, kind: “worktree”, creator_session: string | null, spawn_session: boolean }. workspace_ididentifies the linked-worktree row;branch` remains display and Git-ref data. | state.rs notify_worktree_created() — the only producer; called by session.rs (/sessions/worktree) and worktree_routes.rs create_worktree_shared (HTTP route + MCP repo worktree_create). Dual-emits: desktop emit plus event_bus → /events SSE, both serializing the same struct. |
session-worktree-declared | Same WorktreeCreatedPayload shape; creator_session is the declaring live PTY and spawn_session=false. | state.rs notify_session_worktree_declared() after caller validation and the locked repository delta; desktop emit plus SSE bus. | useWorktreeSwitchPrompt.ts registers/discovers the existing row and adopts the caller-bound declaration for display placement without changing cwd; no creation bell item. |
worktree-removed | state.rs WorktreeRemovedPayload — { repo_path: string, workspace_id: string, branch: string }. Addressed by the stable workspace id; branch is display data captured before the checkout goes away. | state.rs notify_worktree_removed() — called by every removal path: worktree.rs (remove_worktree, finalize_merged_worktree, merge_and_archive_worktree, delete_local_branch — all addressed by workspace_id), worktree_routes.rs (remove_worktree_http, finalize_merged_worktree_http), mcp_transport.rs (repo worktree_remove). Also drops the branch’s work-item link (workitem_links::drop_link_of_removed_worktree) | useWorktreeSwitchPrompt.ts → pruneRemovedWorktree() closes only terminals whose current cwd is inside the removed checkout, re-homes surviving tabs and drops the sidebar row |
settings-changed | { section, generation, persisted, applied } — no values or credential-derived hashes; process-local generation | settings/api.rs after durable facade outcomes (including partial persistence), plus state-bearing legacy save adapters; dual-emitted by AppState::publish_settings_changed to desktop and /events SSE | services/settingsRefresh.ts, activated by useAppInit.ts and mounted Settings pages; non-saving owner read/apply, dirty-edit preservation, per-owner/section deduplication and reconnect resync |
repositories-changed | {} — payload-free on purpose. One backend serves the desktop WebView, the browser and the PWA, and each keeps its own compare-and-swap baseline; the receiver only needs “disk moved, re-read it”. Shipping the document would copy the whole repository set to every client on every save, including the one that just wrote it. | state.rs notify_repositories_changed() — called by both save paths, config.rs save_repositories (IPC) and config_routes.rs put_repositories (HTTP), and only when save_repositories_request returns Ok(true), i.e. the delta actually moved the document. Also on event_bus for /events SSE | repositories.ts startRemoteSync() (registered by hydrate) → re-reads load_repositories → adoptRemoteRepositories(), which moves the store and the persisted baseline together for every key this client has no unsaved intent for. activeRepoPath is never adopted — focus is per-window |
repo-changed (git-state) | { repo_path: string, kind: "git-state" } | repo_watcher.rs — when the git-state fingerprint changed, or a shared ref/configuration or linked-HEAD event is pending (the fingerprint covers index size + resolved HEAD + porcelain status + the sorted .git/worktrees/* set; the path-driven exception observes sibling commits without scanning sibling HEADs). The worktree set is an input because add/remove touches nothing else, so worktree-only changes used to be swallowed and left ghost sidebar rows. Last fingerprint in AppState.repo_git_fingerprints. | useAppInit.ts → coalesced one bump/repo/frame via revisionCoalescer → repositoriesStore.bumpGitRevision, which bumps both the general and the git revision |
repo-changed (working-tree) | { repo_path: string, kind: "working-tree" } | repo_watcher.rs — non-.git, non-ignored file changes, debounced 1.5s when the repo is hot (has ≥1 open terminal, set_hot_repos) and 15s when cold. Ignore coverage is the full git set: the global core.excludesFile, the root .gitignore plus .git/info/exclude, and nested .gitignore files. ALWAYS_EXCLUDED_DIRS matches on any path component, so a nested git repo’s .git/ is treated as noise rather than a working-tree change. No fingerprint guard, but a firing git-state emit cancels the pending working-tree emit as a duplicate. Covers the main checkout and every linked worktree (sync_worktree_watches), which is what keeps a branch’s sidebar diff badge live while an agent works in its worktree; the payload always names the parent repo. | useAppInit.ts → revisionCoalescer → bumpRevision (general revision only) + debounced refreshAllBranchStats |
head-changed | { repo_path: string, branch: string } | repo_watcher.rs — only when the resolved HEAD target changed (resolve_head_target); skips the Linux inotify storm where .git/HEAD events recur without HEAD moving (issue #82). Last target in AppState.repo_head_targets; suppressed-emit count in AppState.repo_head_emits_suppressed. | useAppInit.ts → branch rename/activate (also dedupes on activeBranch === branch) |
conflict-assist-status | { repo_path: string, payload: { pr_number, status, conflicted_files } } | conflict_assist.rs emit_conflict_assist_status() lifecycle; also sent on event_bus for /events SSE. Only the window emit is gated on feature = "desktop" — the bus send runs on every build, because POST /repo/conflict-assist is mounted unconditionally (#808-84e1) | githubOpsStore listener updates conflict-assist state; remote window forwarding accepts only the registered repository owner (#1443-e2fd) |
review-progress | { repo_path: string, payload: { pr_number, done, findings_count?, error? } } | pr_review.rs emit_review_progress() — once with done: false when the turn starts, once with done: true carrying either findings_count or ego’s error; also sent on event_bus for /events SSE, on every build — only the window emit is desktop-gated (#808-84e1) | githubOpsStore listener → Review findings column; remote notices are gated by repository owner. pr_number must be a JSON number: Number(null) is 0, so a missing one would file as PR #0 |
proposals-ready | { repo_path: string, payload: { focus, proposals[] } } | improvement_scan.rs emit_proposals_ready() just before the command returns; also sent on event_bus for /events SSE, on every build — only the window emit is desktop-gated (#808-84e1). It, not the return value, is the path that reaches every window and every transport | githubOpsStore listener accepts the repository owner and replaces the repo’s proposals and clears the running flag |
ctrl-tab | "next" | "prev" | native_keys.rs — macOS only; the NSEvent is swallowed so AppKit cannot also cycle tabs | useNativeMenuBridge.ts → tab switch |
native-key-down | { key: "F13".."F20", cmd, ctrl, alt, shift } | native_keys.rs — macOS only, scoped to the main window; the event is passed through (nothing native to suppress) | useNativeKeyCombo.ts, attached only while a shortcut recorder is open |
mcp-toast | { title, message, level, sound, urgency, origin_repo_path?, origin_session_id?, __tuic_origin?: { connection, name } } | mcp_transport.rs — ui action=toast; derives origin from the calling MCP session rather than accepting caller-supplied scope. origin_session_id is the caller’s TUIC session, absent for an unbound caller | useAppInit.ts → repository-scoped Messages bell item, even when transient mirroring is disabled; urgency=urgent additionally shows a transient card (upper-right container, never over the composer), normal or an absent urgency also shows a card when an origin session is present and not being viewed (inactive terminal or unfocused document), controlled by the default-on per-client Show cards from other terminals setting; no origin stays bell only, and a mirrored urgent notice keeps its [connection] label on the card; consecutive identical notices from the same origin and connection id within five seconds deduplicate both the item and requested sound; mirrored titles/messages must be string/string-or-null or the notice is discarded with a content-free debug log. The explicit Open terminal action resolves origin_session_id at click time. remote_mirror.rs forwards connected remote toasts on both transports, adds the locally saved connection name to the origin marker, and resolves the remote peer to its PTY UUID. Mirrored notices are labelled with that name and navigate only within the owning connection; disconnected frames are dropped |
progress-recorded | { repo_path, payload: { entry: { id, project, ptyId?, type, text, ... } } } | mcp_transport.rs emit_progress_entry() after the SQLite transaction commits; dual-emitted to the desktop window and event_bus → /events SSE | progressStore refreshes the selected PTY or aggregate and routes the toast to that source |
workflow-run-changed | { repo_path, payload: { runId, sequence } } | workflows/run/api.rs emit_run_cursor() after neutral run progress; dual-emitted to the desktop window and event_bus → /events SSE. It is a cursor wake hint, not a replacement for event replay | NeutralInspection.tsx rereads the inspected neutral run |
stories-changed | { repo_path, payload: { rescan, ids, error? } } | story_adapter/binding.rs paths_changed() when the repo watcher sees a change under a running external story adapter’s watch_paths and changes answers; event_bus → /events SSE only (no desktop emit, no frontend consumer yet) | none yet |
ui-tab | {id,title,html,url?,pinned,focus,origin_repo_path?,opener_tuic_session?} | MCP UI tab handler; desktop emit plus SSE with the same optional stable caller identity | useAppInit.ts stores the opener on native Markdown tabs; desktop publication carries it to mobile Markdown menu metadata |
mcp-confirm | { request_id, title, message, origin_repo_path?, origin_session_id? } | mcp_transport.rs — ui action=confirm, dual-emitted, plus a mobile push. It used to be a native OS dialog, which no remote human could answer; every client now gets the request and the first answer wins | McpConfirmHost.tsx (mounted by BOTH ApplicationOverlays.tsx and MobileApp.tsx) → stores/mcpConfirm.ts queue → ConfirmDialog; remote confirmations retain the origin connection, show its locally saved host name, route answers to that daemon, and clear on disconnect. Resolution is scoped by connection and request id |
mcp-confirm-resolved | { request_id, confirmed } | mcp_http/mod.rs resolve_mcp_confirm() on an answer, and mcp_transport.rs when the 300 s wait expires | McpConfirmHost.tsx → drops that request from the queue, so the clients that lost the race take the dialog down |
pty-description-changed | `{ session_id: string, description: string | null }` | state.rs — MCP agent spawn / session submit / session input updates the orchestrator-owned PTY description |
chat-view-changed | { session_id: string, seq: number } | state.rs notify_chat_view_changed() — called by the chat view ticker (chat_view/mod.rs) when the tailed transcript produced new entries; dual-emitted to the desktop window and event_bus → /events SSE. Wake only: entries come from chat_view_snapshot | stores/chatView.ts watch() → refresh() for the terminal named by session_id |
session-renamed | { session_id: string, name: string, is_custom: boolean } | state.rs rename_session_from_backend — MCP session rename only (IPC/HTTP renames start in the frontend and do not emit) | useAppInit.ts → terminalsStore.update(name, nameIsCustom) → tab bar and sidebar |
session-suspend-requested | { session_id: string, request_id: string } | state.rs request_session_suspend — MCP session action=suspend after the busy check | useAppInit.ts → suspendTerminal → closes the PTY, tab stays with suspended; answers via session_suspend_response |
term-alias-assigned | { session_id: string, alias: string } | state.rs record_term_alias — every alias assignment; dual-emitted (window + /events bus, after session-created) | useAppInit.ts → terminalsStore.applyAlias → tab tooltip / context menu |
pty-title-{session_id} | Title string; empty string resets the title. HTTP/WS: pty-title SSE {session_id,title}, raw/text/log WS {type:"title",title} | pty.rs OSC 0/2 handler dual-emits; presentation only, bypasses the lossless state queue | Terminal.tsx → subscribePty onTitle applies existing custom/spawn-name protection on local IPC and the owner daemon WS |
pty-activity-{session_id} | { session_id: string } | pty.rs emit_pty_activity() via ActivityPulse, throttled to one pulse per ACTIVITY_PULSE_WINDOW (1 s). Payload-free and idempotent, so dropping pulses inside the window loses nothing — do NOT convert this throttle into a coalescer. Dual-emitted on event_bus as PtyActivity (activity WS frame on /sessions/:id/stream, plus pty-activity SSE); deliberately NOT forwarded on the ?format=grid WS, which has no activity consumer. Ignored by apply_event_to_session_state — it must not restamp SessionState.last_activity_ms, which answers a different question | Terminal.tsx → subscribePty(…, { onActivity }) → terminalsStore.touchLastDataAt + background-tab activity flag. Not in useAppInit.ts — per-session |
pty-osc133-{session_id} | { marker: string, line: number, exit_code: number | null } | pty.rs OSC 133 handler — serialised from terminal_grid.rs Osc133Event, so the field name is exit_code, NOT exitCode. Dual-emitted on event_bus as PtyOsc133 (osc133 frame on the ?format=grid WS via grid_ws_frame(), plus pty-osc133 SSE); the grid WS is the right lane because CanvasTerminal is the only consumer and it already holds that socket. Ignored by apply_event_to_session_state | CanvasTerminal.tsx → transport.onEvent("osc133", …) → terminalsStore.handleOsc133() → command blocks, gutter marks, Cmd+Up/Down. Not in useAppInit.ts — per-session |
pty-cwd-{session_id} | { cwd: string } | pty.rs OSC 7 handler. The desktop payload is the { cwd } object, not a bare string — both transports carry the same shape so the handler needs no branch. Dual-emitted on event_bus as PtyCwd (cwd frame on the ?format=grid WS, plus pty-cwd SSE). Ignored by apply_event_to_session_state | CanvasTerminal.tsx → transport.onEvent("cwd", …) → terminalsStore.update({ cwd }) + onCwdChange. Not in useAppInit.ts — per-session |
pty-watcher-lines-{session_id} | { session_id: string, lines: [{ text: string, matched_ids: string[] }] } | pty.rs emit_watcher_lines() — one emit per 100 ms batch of assembled lines; text is the CLEANED text Rust matched on, matched_ids are qualified client_id/watcher_id. Rust ships every line only while a registered pattern could not be compiled, otherwise the matched ones alone. Dual-emitted on event_bus as PluginWatcherLines (watcher-lines WS frame on /sessions/:id/stream in both ?format=grid and raw mode — not `?format=log | text, which returns before the event loop — plus plugin-watcher-lines` SSE) |
shell-abandoned | { session_id, since_ms: number | null } | idle_close.rs fresh OS sweep → lossless session-state accumulator | Internal state input; clients render the resulting session-state-changed.state.abandoned_since_ms through useAgentPolling and mobile /sessions, not a second raw-event listener |
session-state-changed | { session_id: string, state: SessionState } — state is exactly the object list_active_sessions returns per session, snake_case, with serde skipping the zero-valued fields. Both transports build it from state.rs session_state_payload(), one function on purpose | state.rs publish_session_state_change(), called only from the session-state accumulator — the sole writer of session_states and therefore the only place that can see a transition. Deduped by SessionState’s PartialEq (which excludes last_activity_ms), so a repaint that changes nothing a client renders emits nothing. Dual-emitted on event_bus as SessionStateChanged (session-state-changed SSE on /events). Ignored by apply_event_to_session_state — it is the accumulator’s output, never its input | useAgentPolling.ts → subscribeEvents({"session-state-changed"}) → applySessionState() → tab awaiting/busy badges + Activity Dashboard. Replaced a 1 Hz list_active_sessions poll; the only remaining reads are a single mount-time catch-up, for sessions already idle and silent, and the same catch-up re-run from subscribeEvents’ onResync when the SSE stream reconnects or reports lagged (browser only — Tauri listen() cannot drop) |
acp-notice | { connectionId, generation, sessionId?, requestId?, sequence, kind } — kind is ready | settled | interaction_pending | interaction_settled | card. camelCase, unlike the PTY rows above: it is the same object the /acp routes and the acp_* commands return, and a second spelling would be a second thing to keep in sync | state.rs spawn_acp_notice_pump(), fed by acp/events.rs AcpEventJournal::append — the one place every ACP event is stamped, so a notice cannot be forgotten by a new producer. Dual-emitted on event_bus as AcpNotice (acp-notice SSE on /events) |
remote-connection-status | { id, status, base_url?, token?, protocol_version?, build?, out_of_date?, live_sessions?, update_notice?, update_in_progress?, error? } — status is disconnected | connecting | connected | unauthenticated | error. snake_case: it is the RemoteConnectionStatus struct as /config/remote-connections/status returns it, and the push is the whole client view rather than a delta, so a missed event cannot leave a client holding a route the backend has retracted. base_url, token, live_sessions, and update_notice are present only while connected; diagnostic build and out_of_date remain visible in retained failed/reconnecting states | remote_runtime.rs publish() — dual-emitted on every real change (dedup is on the snapshot, so a poll that keeps answering 200 emits nothing) | stores/remoteConnections.ts applyStatus() → store state + the SSE bridge, which exists exactly while the connection is connected |
remote-repo-changed | { repo_path: string, kind: "git-state" | "working-tree", __tuic_origin: { connection } } | remote_mirror.rs apply_frame() — derived from a connected daemon’s mirrored repo-changed, worktree-created or worktree-removed frame (other repo-changed kinds are dropped). The raw frames still reach the bus and /events; only this owner-stamped hint is in WINDOW_MIRRORABLE_EVENTS | services/remoteRepositorySync.ts → subscribeEvents({"remote-repo-changed"}) → debounced refresh through the owning connection only (a git-state hint skips the coordinator’s 5 s automatic spacing; working-tree keeps it), plus start_repo_watcher re-registration on remote-connection-status connected and on resync. Local repo-changed/worktree-*/session-worktree-declared listeners ignore payloads with __tuic_origin |
HTTP & MCP Server
When adding routes or changing server behavior:
| File | What to update |
|---|---|
docs/api/http-api.md | REST endpoint reference |
docs/backend/mcp-http.md | Server architecture, routing, lazy tool discovery (collapse_tools / meta-tools) |
docs/user-guide/remote-access.md | User setup guide |
src-tauri/src/mcp_http/plugin_docs.rs | PLUGIN_DOCS (if plugin-facing) |
src-tauri/src/mcp_http/fixtures/ | A client’s exact captured handshake, when the change touches a lifecycle. /mcp serves two — legacy initialize (2025-11-25) and stateless server/discover (2026-07-28) — and a client that speaks only one is proven by its own request, not by a hand-written approximation |
Diagnostics
When modifying cpu_watchdog.rs or the /diagnostics HTTP endpoint:
| File | What to update |
|---|---|
src-tauri/src/cpu_watchdog.rs | Watchdog logic, thresholds, snapshot fields |
src-tauri/src/mcp_http/log_routes.rs | /diagnostics GET/POST handlers |
docs/backend/diagnostics.md | Usage, snapshot fields, known failure patterns (AGENTS.md keeps the summary) |
docs/FEATURES.md | Section 20.11 (Runtime Diagnostics) |
Agent state detection (working / idle / awaiting)
When changing an awaiting/idle/busy signal — a parser, the hook suppression, or the raw-stream composition:
| File | What to update |
|---|---|
src-tauri/crates/tuic-terminal/src/output_parser.rs | The parser itself (parse_question, parse_osc777_notify, …) |
src-tauri/crates/tuic-terminal/src/chrome.rs | Bottom-zone cutoff — anything at or below the input box must stay unparsed |
src-tauri/src/pty.rs | raw_stream_events composition + suppress_heuristic_question gating |
src-tauri/src/state.rs | apply_event_to_session_state — the arms that SET and CLEAR awaiting_input. A signal nothing retracts latches the badge |
src/components/Terminal/Terminal.tsx | The frontend twin of those arms (terminalsStore awaiting flags) |
src-tauri/src/fixtures/agent_prompts/ | A framed .tcap capture of the failure, recorded via /diagnostics/capture (.raw remains legacy-readable) |
src-tauri/src/pty/tests.rs | A case in the Awaiting-signal fixtures block replaying that capture |
src-tauri/src/pty.rs tests | A case in the Awaiting RETRACTION block when the failure is a state that never clears — fixtures assert emitted events and cannot express a MISSING one |
scripts/hooks/pre-commit | The fixture gate’s symbol/file lists — a new detection symbol or a new detection-carrying file must be added, or the gate silently stops covering it |
| docs/backend/agent-state-detection.md | Signal table, capture workflow, retraction (AGENTS.md “Agent state detection” keeps the core rules) |
The fixture gate compares the indexed and committed production scopes, excluding
#[cfg(test)] modules and #[test]/#[tokio::test] functions. Test-only
changes may reuse existing captures. Production detection changes require a staged,
framed TCAP v2 capture with nonzero geometry, complete records and a matching
provenance Markdown file (capture source and SHA-256). New raw/text external
fixtures are rejected; legacy captures remain readable. Framing and provenance
checks do not authenticate where bytes came from: the author must record them
from the real system.
MCP Tool Surface (native tools, upstream proxy, meta-tools)
When changing the tool list, tool handlers, disabled_native_tools, upstream allow/deny filters, or the Speakeasy meta-tools:
| File | What to update |
|---|---|
src-tauri/src/mcp_http/mcp_transport.rs | Tool definitions, merged_tool_definitions, searchable_tool_definitions, meta-tool handlers (search_tools, get_tool_schema, call_tool), build_mcp_instructions |
src-tauri/src/mcp_proxy/registry.rs | aggregated_tools, proxy_tool_call (filter is enforced on BOTH — discovery no longer gates dispatch under collapse_tools) |
src-tauri/src/tool_search.rs | BM25 ToolSearchIndex backing search_tools / get_tool_schema |
docs/backend/mcp-http.md | Lazy Tool Discovery section, meta-tool table, filter-enforcement note |
src-tauri/src/mcp_http/plugin_docs.rs | AI plugin guide references to MCP worktree inputs |
src-tauri/crates/tuic-cli/ | CLI callers of renamed or removed native actions |
docs/user-guide/cli.md, CHANGELOG.md | Public CLI examples and BREAKING migration instructions |
docs/backend/config.md | collapse_tools field in AppConfig table |
docs/user-guide/settings.md | MCP page → TUIC Tools — “Collapse tools” checkbox description |
Session tool actions added (swarm Layer 3–4)
session action=submit— submits one command to a confirmed-idle managed agent and returns a bounded terminal-movement receipt in the same response. It never queues or overwrites a partial composer;session action=inputremains raw and write-only.session action=status— returns{shell_state, idle_since_ms, busy_duration_ms, exit_code, agent_type}. Useful for polling agent progress without streaming output.session action=listresponse now includesshell_stateper entry, plustuic_session(the identity the tab persists) andalias. It no longer includeschild_pidorforeground_pgid— no action accepts a raw pid.session_idon every action accepts the PTY id,tuic_session, alias, unique short PTY-id prefix, or unique display name;toonagent action=senduses the same resolver and also accepts a peer’s registeredname(the onelist_peersprints); two peers sharing a name are refused with the candidates. Ambiguous prefixes or names return an error. Resolution lives inAppState::resolve_session_ref_checked/resolve_peer_ref_checked; an unresolvable reference falls through unchanged so a tombstoned session can still be read.session action=create(andPOST /sessions) accept an optionalalias, which the frontend replays from persisted tab state so an alias survives a restart.
Agent tool actions added (swarm inbox)
agent action=inboxresponse now includesmissed_count— number of unread messages evicted at capacity since last read. Same-child, same-kind lifecycle notice replacement does not increase it. Non-zero means the orchestrator missed messages and should increase polling frequency.- Reading
agent action=inboxsettles delivery for the returned messages, including queued terminal wakes. A queued generic wake is removed once no pending terminal-owned mail remains, so read mail can be reclaimed at the 100-message inbox limit. Delayed terminal handoffs and queue retries check the same pending-mail ownership before injecting a generic notice, so an inbox read cannot be followed by a recreated stale wake. Older unread terminal-owned mail still keeps its wake when an explicit read cursor skips it. agent action=sendresponse includesdelivered(bool) plus, when false,warningandrecipient_has_terminal.deliveredis false exactly whendelivery_path == "inbox_only": no waiter, channel, direct terminal delivery, or already-pending coalesced orchestrator wake will surface it, so it stays unread until the recipient polls. Registered orchestrators addwake_notification_and_inbox,coalesced_wake_and_inboxandlifecycle_summary_and_inbox; none of them exposes a peer payload — the last one is reachable only for a window made entirely of server-authoredtuic-auto-*lifecycle notifications, which it prints inline and acknowledges itself. Canonical idle/completed state may claim the wake; derivedworkingmay also claim it only through the stricter composer gate (idle shell, confirmed readiness, no question, no partial input), so background work cannot strand a result while active work remains protected. Ordinary Claude recipients use that same gate before selecting their SSE channel: a ready composer heldworkingby background work receives a PTY wake instead. A payload-free wake gets at most one retry after an uncertain PTY write per unread-mail group; coalesced mail does not reset that budget, and inbox/wait observation does.deliveredplusdelivery_pathare the whole verdict:ok,accepted,buffered_in_inboxandrecipient_has_terminalwere removed because they answered “buffered” to a question about delivery. Keep these distinct in every client and in the tool descriptions — reportinginbox_onlyas success is how a reply to an agent with no PTY silently vanished.agent action=registerresponse includesterminal(bool): false means the identity resolves to no live PTY (live_pty_for_peer→None), so it can never be typed into or woken, and the peer must consume its own inbox viawait/inbox. Identities without a PTY arise from a bridge that sent nox-tuic-sessionheader (agent launched outside a TUIC PTY) — the server then mints an MCP-scoped UUID.agent action=registeracceptsorchestrator(bool) as the only role declaration seam; omission preserves the current role and child spawn never infers it. Theregisterresponse surfacesorchestratorplusmail_wake(managed_pty_lifecycleornone);list_peersreportsorchestratorbut notmail_wake, which is a property of the caller’s own identity rather than of every peer in a listing. External/headerless orchestrators are inbox/wait-only because MCP/SSE activity is not an authoritative idle or wake surface.
Smart Prompts api mode (one unattended ego turn)
The same ego, a different shape of use (#787-ee50): no panel, no stream, no
second turn, and no MCP server in the session — a turn nobody watches cannot
be handed the tools that drive terminals and repositories. Changing any of the
three rules in acp/oneshot.rs changes what the mode is allowed to do.
| File | What to update |
|---|---|
src-tauri/src/acp/oneshot.rs | The turn: what counts as the answer, which questions are refused, how long the turn may take. detached is why a dropped caller cannot skip the shutdown, and TURN_TIMEOUT must leave room for INITIALIZE_TIMEOUT inside REQUEST_TIMEOUT |
src-tauri/src/acp/manager.rs | new_unattended_session / unattended — the emptied authority. granted is its attended counterpart. INITIALIZE_TIMEOUT bounds the launch, enforced inside the supervisor because only there can expiry stop the child |
src-tauri/src/acp_commands.rs, src-tauri/src/mcp_http/acp_routes.rs | acp_one_shot_prompt and POST /acp/one-shot. The route takes the spawn guard: it launches a process |
src/transport.ts, src-tauri/src/mcp_http/command_table_paths.txt | The parity entry and its regenerated snapshot |
src/hooks/useSmartPrompts.ts | canExecuteApi, apiRoot, executeApi — and the api branch of executeHeadless, which is the same one path |
src/types/acp.ts | EgoTurn, the mirror of the Rust type |
docs/api/tauri-commands.md, docs/api/http-api.md, docs/FEATURES.md, docs/user-guide/settings.md | The command, the route, the feature and what a user is told when ego is not configured |
PR review, changelog and improvement scan (one unattended ego turn each)
The three GitHub features #784-0aec deleted, back on ego (#795-320b). Each is
one acp::oneshot turn with the whole input inline — there is no multi-turn
engine, no read_file tool use and no per-file phase, because an unattended turn
is refused every tool it asks for. TUIC stores no API key and makes no provider
HTTP call for any of the three; which model runs is ego’s configuration and this
side is never told it. When ego is not reachable each one fails with ego’s own
sentence, never with an empty result.
| File | What to update |
|---|---|
src-tauri/src/acp/oneshot.rs | ask, answer_text, extract_json, unparseable — the seam all three share. A change here changes all three |
src-tauri/src/pr_review.rs | The review: diff split, prompt, envelope, and filter_findings_by_confidence — the gate runs before anything leaves the module. TUIC_REVIEW_CONFIDENCE_THRESHOLD overrides it |
src-tauri/src/changelog.rs | The changelog: prompt over merged PRs, plus split_changelog_output — lenient about format (markdown with a null json half is a valid answer), strict about reachability |
src-tauri/src/improvement_scan.rs | The scan: focus, prompt, parse_improvement_output, the five-proposal cap, and create_issue_from_proposal |
src-tauri/src/state.rs, src-tauri/src/mcp_http/sse_routes.rs | AppEvent::ReviewProgress / ProposalsReady and their /events SSE arms. Producers dual-emit |
src-tauri/src/mcp_http/{mod,github_routes,types}.rs | GET /repo/changelog, POST /repo/pr-review, POST /repo/improvement-scan, POST /repo/create-issue-from-proposal. Not desktop-gated: ego is reached over ACP, so tuic-remote serves them too |
src/transport.ts, src-tauri/src/mcp_http/command_table_paths.txt | The four parity entries and the regenerated snapshot |
src/types/index.ts | PrReviewResult, ReviewedFile, ReviewFinding, FindingSeverity, ChangelogResult, ImprovementProposal, ImprovementScanResult, ImprovementFocus, CreatedIssue |
src/stores/prReview.ts | Per-PR review state, the flatten/id scheme and GitHub’s needs-a-line posting rule |
src/stores/githubOps.ts | The ops event accumulator: review-progress and proposals-ready |
src/components/PrDetailPopover/PrDetailContent.tsx, src/components/shared/SeverityIcon.tsx | Where findings are shown, selected and posted |
src/components/ChangelogModal/, src/components/Sidebar/GitHubPanel.tsx | The modal and the button that opens it |
src/components/GithubOpsDashboard/GithubOpsDashboard.tsx | The Review findings and Proposals columns, the focus buttons and create-issue |
docs/api/tauri-commands.md, docs/api/http-api.md, docs/FEATURES.md, docs/backend/github.md | The four commands, the four routes and the three features |
AI Chat panel (ego over ACP)
The panel is a control plane over an agent that lives outside it (#785-58ca). It
is one chat for the app (#1157-1e54), never bound to a terminal or a
repository: sessions run in ~/Gits, and the repository on screen is a hint sent
with each prompt. Nothing here holds a
provider, an API key or a tool loop.
The session’s one MCP server is tuicommander on the ACP transport
(#1156-1b61): {"type":"acp","name":"tuicommander","serverId":"tuicommander"},
served on the ACP connection itself through mcp/connect, mcp/message and
mcp/disconnect. It replaced the stdio tuic-bridge entry (#796-7fa3), which
opened a fresh HTTP MCP session for every ego tool operation. Every request goes
through the same mcp_post handler as HTTP /mcp, bound to the connection’s
peer identity; the server-side synthesis in granted still keeps a caller from
naming a server — see plan §4.5.
| File | What to update |
|---|---|
src-tauri/src/acp/mod.rs | tuicommander_acp_mcp_server — the entry’s name and serverId, and mcp_acp/mcp_stdio in capability_snapshot |
src-tauri/src/acp/mcp_host.rs | The McpOverAcpHost contract and McpChannel: which serverId is served, unknown connection ids refused, every connection released when the ACP connection ends |
src-tauri/src/acp/manager.rs | granted replaces the caller’s list; the connection’s peer ID reaches ego’s environment and every MCP connection; set_mcp_host; mcp/message runs under $/cancel_request |
src-tauri/src/mcp_http/acp_mcp.rs | AcpMcpHost — one protocol session per MCP connection, the GET /mcp stream forwarded as notifications, end_mcp_session on disconnect; install at both startup sites |
src-tauri/src/acp_commands.rs, src-tauri/src/config.rs | Persist a root’s ACP peer UUID beside its selected conversation and reuse it after reconnect or restart |
src-tauri/src/mcp_http/mcp_transport.rs | Bind bridge mail, child parentage and blocked progress to the ACP peer without a PTY |
src-tauri/src/acp/activity.rs, connection.rs (publish, flush_activity), manager.rs (settle_connection) | Derived chat activity: busy/awaiting/idle, tools, ego children, interrupted, revision. Wire shape pinned in story785_event_wire_shapes.rs; the store keeps the higher revision and never re-admits a settled request id (src/stores/acp.ts) |
src/components/AIChatPanel/AIChatPanel.tsx | The panel frame plus the banners: gap, refusal, “not receiving updates” |
src/components/AIChatPanel/useAcpChat.ts | One connection for the app, rooted at ~/Gits and started by the first message or “+”; global tabs; the viewed repo sent per prompt; every action it offers |
src-tauri/src/acp/manager.rs (prompt_with_context, shutdown_all, peer adoption) | _meta.tuicommander/viewedRepo on session/prompt; one live connection per peer id; every ego ended on app exit |
src/components/AIChatPanel/Transcript.tsx | How each transcript entry is drawn — message, thought, tool call, plan, a turn that ended without answering, the provider-retry status line |
src/components/AIChatPanel/Interactions.tsx | Permission options and elicitation forms; a single choice field with up to three values has direct buttons. form is the only mode drawn |
src/components/AIChatPanel/SessionControls.tsx | The options the session publishes, pause/resume/compact, and readable labels for untitled conversations |
src/components/AIChatPanel/Composer.tsx, draft.ts | Where a turn is written; the draft is module-scoped so the context menu can seed it |
src/components/AIChatPanel/contextMenuActions.ts | “Explain with AI” / “Fix this error” on terminal right-click, registered through contextMenuActionsStore |
src/services/acpClient.ts, src/services/acpStream.ts | Every command the panel sends and the frame stream behind it. adopt commits to the store only after the pending fetch and the open succeed, and reconnect lets go of the id the backend replaced — the new one is a different connection |
src/stores/acp.ts | Protocol state per connection: snapshot, journal cursor, pending questions, gap. applyFrame takes the reading stream’s id because end names nobody on the wire |
src/stores/acpTranscript.ts | The render projection, keyed by session. Everything shown before the backend answered must be reversible: noteUserMessage/dropEntry, clear/restore |
src/panelAdapters/aiChat.tsx | Registry entry: what makes Cmd+Alt+A, the status-bar button, the palette entry and detach work |
src/components/PanelOrchestrator.tsx | Switches between AIChatPanel and DetachedPlaceholder |
src/components/DetachedPlaceholder.tsx | Placeholder shown in the main window when the panel is detached |
src/panelRouter.tsx | Panel adapter registry + routing for detached panel windows |
src/utils/panelSync.ts | PanelSyncProvider + PanelSyncReceiver for main<->detached communication |
src/hooks/initPanelWindow.ts | Bootstrap for detached panel windows (theme, font, settings) |
src/stores/ui.ts | aiChatPanelVisible + detachedPanels map |
src/stores/settings.ts | isAiChatEnabled() — whether the panel is offered at all (reads experimental_features_enabled) — and isAcpConfigured()/egoExecutable, the one binary the host may launch |
src/keybindingDefaults.ts | toggle-ai-chat + detach-activity-dashboard hotkeys |
docs/user-guide/ai-chat.md | User-facing AI Chat guide |
docs/FEATURES.md | AI Chat feature section |
AI Chat settings page (ego’s own configuration)
Settings → AI Chat reads and writes ego’s configuration through ego’s
command line (#786-4a6d). It replaces the provider registry #784-0aec deleted,
and the replacement is not a registry: TUIC stores no API key, keeps nothing in
its keyring, and makes no provider HTTP call. The one network call anywhere in
this area is ego models --refresh, which ego makes, when a person presses
Refresh.
| File | What to update |
|---|---|
src-tauri/src/ego_cli.rs | Which ego commands are run, how their three answers are joined, and what an ego failure carries. model, roots and network are dedicated write operations so no caller can reach sandbox or permissions.judge |
src-tauri/src/mcp_http/ego_routes.rs | GET /ego/providers, POST /ego/providers/model, GET /ego/perimeter, POST /ego/perimeter/roots, POST /ego/perimeter/network. All are behind require_local_or_auth — spawning a process is not a read |
src/transport.ts, src/__tests__/transport.test.ts | The ego_providers / ego_set_default_model / ego_perimeter / ego_set_perimeter_roots / ego_set_perimeter_network mappings and the generated path snapshot |
src/types/ego.ts | The TS mirror of the Rust projection. A mirror, not a second opinion — nothing reshapes it |
src/services/egoCli.ts | The provider and perimeter calls the tab makes |
src/components/SettingsPanel/tabs/AiChatTab.tsx | What the page draws: the default-model picker, the per-provider credential badge, and each of the four failure states |
src/components/SettingsPanel/tabs/EgoPerimeterSection.tsx | Root/access/allowlist editors, separate network write, backend-derived exec badge and effective preview |
src/components/SettingsPanel/tabs/GeneralTab.tsx | The ego section: the ego executable field and its Install latest button (install_ego, shared release_install.rs with install_mdkb), shown also while Experimental Features is off |
src/components/SettingsPanel/SettingsPanel.tsx | The nav entry (hidden while isAiChatEnabled() is false) and the tab body |
src/components/SettingsPanel/settingsSearchIndex.ts | Its rows in the settings search index — the drift test re-derives them from the JSX |
docs/user-guide/settings.md | The AI Chat page section |
docs/api/tauri-commands.md, docs/api/http-api.md | Both transports for the provider and perimeter commands |
docs/FEATURES.md | The AI Chat page entry under Settings |
TUI detection
The embedded agent’s write-only command knowledge store was removed in #2115-1333. Terminal-mode classification remains live.
| File | What to update |
|---|---|
src-tauri/src/ai_agent/tui_detect.rs | TerminalMode heuristics (Shell vs FullscreenTui) |
src-tauri/src/pty.rs | Alternate-screen and inline-TUI mode tracking; OSC 133 activity transitions |
src-tauri/src/state.rs | SessionState terminal_mode and has_osc133_integration |
src-tauri/crates/tuic-core/src/redaction.rs | redact_secrets, applied by session output |
src-tauri/crates/tuic-terminal/src/terminal_grid.rs | Grid search, hyperlinks and semantic zones; VtLogBuffer delegates |
What #784-0aec removed, and where it comes back
These areas had sections here and no longer have any code to sync. They are listed so a search for the feature lands on the reason rather than on nothing. Do not re-add a section for one of them until the story that restores it lands — the replacement lives in ego and will have a different file list.
| Removed area | Went with it | Comes back as |
|---|---|---|
| AI Prompts (diff-triage prompt) | AiPromptsConfig, diff_triage.rs, aiPrompts.ts, the list/load/save_ai_prompt MCP config actions | nothing. #795-320b restored the review itself but not the editable prompt: an unattended turn sends one prompt this side owns, so there is nothing for a user to tune |
| AI Agent ReAct loop | ai_agent/{engine,tools,safety,sandbox,context,commands,triggers,scheduler}.rs, SessionKnowledgeBar.tsx | nothing. ego runs its own tool loop; TUIC is the environment it drives, per plans/ego-integration/archive/plan.md §1 |
| Terminal Watcher | ai_agent/watcher.rs, the WatcherEngine spawn, the watcher_* commands, WatcherManager/, ai-watchers.json | not scheduled |
| PR review, changelog, improvement scan | diff_triage.rs, improvement_scan.rs, changelog.rs, aiTriageStore.ts, prReview.ts, AiTriagePanel/, ChangelogModal/ | landed as 795-320b — see “PR review, changelog and improvement scan” above. diff_triage.rs came back as pr_review.rs, because it no longer triages a diff; aiTriageStore.ts and AiTriagePanel/ did not come back at all |
Smart Prompts api execution mode | llm_api.rs, execute_api_prompt | landed as 787-ee50 — see “Smart Prompts api mode” above. The provider registry did not come back; the mode is one unattended ego turn |
Remote Daemon (tuic-remote)
When modifying the remote daemon binary or standalone server behavior:
| File | What to update |
|---|---|
src-tauri/src/bin/tuic_remote.rs | Binary entry point |
src-tauri/src/lib.rs | run_remote() — the daemon |
src-tauri/src/lib.rs | spawn_daemon_background_tasks() — every task is started or refused with a reason; the guard test is the_daemon_decides_on_every_desktop_background_task |
src-tauri/src/mcp_http/mod.rs | spawn_ipc_listener() / spawn_maintenance_sweep() — shared by the desktop and the daemon |
src-tauri/src/remote_lifetime.rs | Optional idle lifetime driven by SSE and WebSocket client counts; /health.survive_secs must stay in sync |
src-tauri/src/remote_deploy/{mod,assets,service}.rs | SSH asset resolution/cache, ephemeral launch, and systemd/launchd install lifecycle; keep Sections 22/24 and the remote-access guide aligned |
docs/user-guide/remote-access.md | tuic-remote (Beta) section, incl. “What the daemon runs” |
docs/FEATURES.md | Section 22 (Remote Daemon) |
.github/workflows/remote-daemon.yml | Daemon build job shared by release.yml and nightly.yml — publishes both tuic-remote and tuic-bridge per target |
SSH Tunnel Management
When modifying tunnel profiles, supervisor, audit logging, backoff, or tunnel UI:
| File | What to update |
|---|---|
src-tauri/src/tunnels/profile.rs | TunnelProfile, ForwardSpec, ProfileOptions structs |
src-tauri/src/tunnels/command.rs | SSH command-line argument building |
src-tauri/src/tunnels/classifier.rs | ExitReason enum and stderr classification |
src-tauri/src/tunnels/agent.rs | SSH agent socket discovery |
src-tauri/src/tunnels/port.rs | Local port availability check |
src-tauri/src/tunnels/backoff.rs | BackoffCalculator (delays, jitter, max retries) |
src-tauri/src/tunnels/audit.rs | AuditLog SQLite schema, insert/query/rotate |
src-tauri/src/tunnels/supervisor.rs | TunnelSupervisor lifecycle and reconnect loop |
src-tauri/src/tunnels/storage.rs | ProfileStore: TOML load/save (global + per-repo) |
src-tauri/src/tunnels/manager.rs | TunnelManager: orchestrates supervisors |
src-tauri/src/tunnels/commands.rs | Tauri commands for tunnel CRUD and control |
src/stores/tunnels.ts | Frontend tunnel state (profiles, statuses) |
src/stores/tunnelPanel.ts | Tunnel panel UI state |
src/components/TunnelsPanel/TunnelsPanel.tsx | Tunnel list with start/stop controls |
src/components/TunnelsPanel/TunnelEditorModal.tsx | Profile create/edit form |
src/components/TunnelsPanel/TunnelStatusBadge.tsx | Color-coded status indicator |
docs/features/ssh-tunnels.md | Feature architecture doc |
docs/FEATURES.md | Section 23 (SSH Tunnel Manager) |
docs/user-guide/remote-access.md | SSH Tunnel Management section |
Remote Connection Manager
When modifying remote connection config, storage, or transport routing:
| File | What to update |
|---|---|
src-tauri/src/remote_connection.rs | RemoteConnection, RemoteTransport, RemoteConnectionStore, the password/token commands |
src-tauri/src/remote_runtime.rs | The live half: status, base URL, session token, the status poll and the SSH tunnel. Every status change is dual-emitted as remote-connection-status. teardown() is the one way a connection goes down — poll, mirror task, mirrored rows, tunnel and token, in that order, idempotent and safe on an id nothing knows. Disconnect and delete both call it, over IPC and over HTTP alike; a second stop path is how the tunnel came to outlive the delete that removed its profile |
src-tauri/src/remote_deploy/{mod,assets,service}.rs | On-connect deployment, cached release assets, and systemd/launchd install/uninstall |
src-tauri/src/remote_lifetime.rs | Ephemeral daemon idle expiry and /health.survive_secs |
src-tauri/crates/tuic-core/src/credentials.rs | Credential::RemoteConnection — the password, keyed by the connection’s UUID |
src/stores/remoteConnections.ts | Frontend remote connections store — a renderer of the backend status, plus the token it holds in memory for the transport |
src/transportRuntime.ts | withRemoteToken — the one place a credential is put on a URL; resolveOwningConnection — the one place a call’s machine is decided |
src/stores/repositories.ts / src/stores/terminals.ts | the registered path→connection and session→connection lookups |
src-tauri/src/remote_mirror.rs | Mirrors a connected daemon’s sessions and events onto the local bus. The /events read carries an idle deadline (3× the daemon’s 15 s keep-alive): a silent stream is a dead stream, and it re-seeds rather than waiting forever |
src/transport.ts | owningConnectionFor + connectionId-based routing in COMMAND_TABLE |
src/invoke.ts | the desktop IPC path’s diversion to rpc() for a remotely-owned call |
src/components/Terminal/canvasTerminalTransport.ts | connectionId support for the remote WebSocket |
docs/FEATURES.md | Section 24 (Remote Connection Manager) |
docs/user-guide/remote-access.md | Remote Connection Manager section |
Terminal stream compression
When changing what a remote WebSocket puts on the wire, or which peers pay for it:
| File | What to update |
|---|---|
src-tauri/src/mcp_http/ws_compression.rs | The negotiation, DEFLATE_SUBPROTOCOL, the frame tags, the level, and the measurement the level and the stateless choice were made on |
src-tauri/src/mcp_http/session.rs | ws_stream reads ?compress= and the peer address, and selects the subprotocol when the mode is tagged; all three handlers send through WsFrameSender |
src-tauri/src/mcp_http/types.rs | OutputQuery::compress |
src/components/Terminal/wsFrameCodec.ts | The client half — the tag values must match FrameTag literal for literal, and DEFLATE_SUBPROTOCOL must match its Rust twin |
src/components/Terminal/canvasTerminalTransport.ts | Who asks for the encoding, who reads the acceptance off ws.protocol in onopen, and the chain keeping inflated deltas in order |
src-tauri/src/tunnels/profile.rs / command.rs | ProfileOptions::compression → ssh -C; the WebSocket’s loopback refusal assumes this is on |
docs/api/http-api.md | “WebSocket compress=deflate” — the table of what is compressed by what |
docs/user-guide/remote-access.md | What a user is told about it |
Machine-owned configuration
When changing which machine a config family belongs to, or adding a config file that describes a machine rather than this app:
| File | What to update |
|---|---|
src/stores/agentConfigs.ts | The per-machine registry: agentConfigsFor, ensureAgentConfigs, invalidateAgentConfigs, and the remote IO that names the connection |
src/stores/remoteConnections.ts | applyStatus — the connection edge that drops and refills a machine’s cached config |
src/components/SettingsPanel/MachineSelector.tsx | The selector every tab in the machine family carries |
src/components/SettingsPanel/tabs/AgentsTab.tsx | Run configs, the hook toggles, and which controls stay local because they have no remote route |
src/components/SettingsPanel/tabs/services/UpstreamMcpPanel.tsx | Upstream MCP servers, and the OAuth flow that cannot follow a machine |
src/__tests__/remoteRepoRouting.test.ts | Both halves: what follows the repo, and what must never leave this machine |
docs/backend/config.md | Agents Config section — the ownership rule and the local families |
docs/user-guide/remote-access.md | “Which config follows the repo, and which stays here” |
Project Progress (storage)
When modifying the project-owned Progress store, its ownership resolution, or its Git-exclude/watcher interaction:
| File | What to update |
|---|---|
src-tauri/src/progress/store.rs | Schema, migrations, recovery, and SQLite locking behavior |
src-tauri/src/progress/ownership.rs | Registered and nested workspace ownership resolution |
src-tauri/src/progress/model.rs | Entry kinds, which of them are reportable, and validation limits |
src-tauri/src/progress/service.rs | The progress_tracking gate and the shared record/list/delete core |
src-tauri/src/progress/flow.rs | The Flow sequence: participants, arrow joining, scope, redaction |
src-tauri/src/pty.rs | intent: capture — the host’s half of the journal |
src-tauri/src/mcp_http/mcp_transport.rs | journal_hand_off at agent action=spawn / send — the delegated and message entries |
src-tauri/src/repo_watcher.rs | The journal must stay outside every repository; the test asserts the tree is byte-identical after a write |
docs/backend/config.md | Progress Storage section |
docs/api/http-api.md | Project Progress section |
docs/api/tauri-commands.md | Progress command table rows |
docs/user-guide/project-progress.md | The whole document |
Project Progress (dialog)
When modifying the Progress dialog, its store, or the surfaces that open it:
| File | What to update |
|---|---|
src/components/ProgressDialog/ | The list, the frozen divider, the blocked filter, embedded mobile mode, the Flow view (ProgressFlow.tsx) |
src/stores/progress.ts | The one-project query, the frozen divider, live presentation |
src/actions/actionRegistry.ts | The progress action, and the browser allowlist in CommandPalette.tsx |
src/components/Toolbar/Toolbar.tsx | The aggregate unread bell row |
src/mobile/MobileApp.tsx | The lazy Progress tab |
docs/frontend/components.md | ProgressDialog entry |
docs/frontend/stores.md | progressStore entry |
docs/user-guide/command-palette.md | Project Progress action |
docs/user-guide/project-progress.md | The whole guide — it describes the dialog |
docs/user-guide/settings.md | The two progress_tracking toggles in the Agents table |
docs/FEATURES.md | Project history row |
Native Stories (manual plans and stories)
When modifying the native story store, its actions, or any of the four surfaces that reach them:
| File | What to update |
|---|---|
src-tauri/src/stories/store.rs, store/records.rs, store/transitions.rs | Schema version, claims, revisions, transitions, and the read-only claim probe on session close |
src-tauri/src/stories/model.rs, api.rs | The StoryAction / StoryReply wire shapes and project scoping — one shape for every transport |
src-tauri/src/pty.rs | Claim release on session teardown (remove_live_session_state) |
src-tauri/src/lib.rs | story_action_command (IPC) |
src-tauri/src/mcp_http/mod.rs | POST /stories/action and its auth guard |
src-tauri/src/mcp_http/mcp_transport.rs | The native story MCP tool (handle_story, bound caller only) |
src-tauri/crates/tuic-cli/src/main.rs | tuic story |
src/transport.ts + src-tauri/src/mcp_http/command_table_paths.txt | The story_action_command mapping; regenerate the paths file with pnpm vitest run src/__tests__/transport.test.ts -u |
src/components/StoriesDialog/, src/stores/storiesUi.ts, src/components/Toolbar/Toolbar.tsx | The dialog, its visibility store, and the toolbar entry point |
docs/api/tauri-commands.md, docs/api/http-api.md, docs/backend/mcp-http.md | The command, the route, and the MCP tool |
docs/user-guide/native-stories.md, docs/FEATURES.md, SPEC.md | The guide, the feature row, and the specification |
src-tauri/src/story_adapter/, scripts/story-adapter-reference/adapter.mjs | docs/backend/story-backend-protocol.md (methods, error codes, supervision); the reference adapter and the conformance tests change with the protocol version |
Git & Worktree Integration
When modifying git operations, worktree logic, or GitHub API:
| File | What to update |
|---|---|
docs/backend/git.md | Git command lifecycle, diff parsing, GitReads port (gix vs CLI op split), moka cache |
src-tauri/crates/tuic-git/src/git_reads.rs | GitReads port: flipping an op to gix requires a green byte-parity shootout test first |
src-tauri/crates/tuic-git/src/{github,github_account,github_auth,github_poller,circleci,pr_review,changelog,github_debug}.rs | Pure GitHub models, parsing, and decisions; keep network, credentials, scheduling, events, and commands in the root adapters |
docs/backend/github.md | PR fetching, CI checks, GraphQL |
docs/user-guide/worktrees.md | Worktree workflow, configuration |
docs/user-guide/github-integration.md | PR monitoring, CI rings |
docs/FEATURES.md | Sections 7 (Git) and 8 (GitHub) |
docs/api/tauri-commands.md | Git/worktree commands |
Voice dictation, spoken replies and hands-free
When modifying src-tauri/src/dictation/**, src-tauri/crates/tuic-dictation/**, or the Voice settings page (DictationSettings.tsx):
| File | What to update |
|---|---|
docs/backend/dictation.md | Commands, hands-free runtime, the speech port and its adapters, the speech-asset catalogue, and the one-language rule |
docs/api/tauri-commands.md | The Voice Dictation command table — including which config fields drop the voice built for the previous one |
docs/api/http-api.md | The /dictation/** routes and the wire shapes. SpeechAssetInfo is snake_case; SpeechStatus, HandsFreeStatus, SpokenReply and HandsFreeDisarmed are camelCase |
docs/frontend/stores.md | dictationStore — the speech assets, the polled hands-free/speech status, and the fields saveConfig reads off the stored config rather than store state |
docs/frontend/components.md | DictationSettings — including which groups stay behind isTauri() now that the tab itself renders in browser mode |
src/utils/browserVoice.ts | The browser half of the hands-free audio socket. Transport only: any decision added here becomes a second segmenter that exists only in browsers |
src/components/SettingsPanel/settingsSearchIndex.ts | One row per new label, in source order: extractSettings reads the file, not the render tree |
src/i18n/en.json | Every t("key", "double-quoted fallback"), verbatim — i18nKeyCollisions.test.ts is the gate |
docs/FEATURES.md | Section 9 (Voice Dictation) |
to-test/<area>*.md (index to-test.md) | Anything needing real audio, a real download or Boss’s eye — a Rust change here never reaches his live make dev session |
Settings & Configuration
When adding config fields or settings UI:
| File | What to update |
|---|---|
docs/backend/config.md | Config files, schema, platform directories |
docs/user-guide/settings.md | Settings page breakdown, by navigation group |
docs/FEATURES.md | Section 11 (Settings) |
src/components/SettingsPanel/SettingsPanel.tsx | GLOBAL_TAB_GROUPS — which group and page a new page belongs to |
src/components/SettingsPanel/settingsSearchIndex.ts | Search index rows for every new label; the drift test re-derives them from the JSX |
src/components/SettingsPanel/ExpertSetting.tsx, src/stores/settingsExpert.ts | Wrap a control in ExpertSetting only with a configKey that get_config_defaults can resolve; update the Expert Mode section of docs/user-guide/settings.md if the visibility rule changes |
Agent Detection
Launch-scoped Claude/Codex status changes must keep agent_hook_launch.rs, shell_integration.rs, direct/MCP spawn assembly, agent config types, Settings, HTTP/Tauri transport parity, the route snapshot, AI-agent/config/settings docs, FEATURES and CHANGELOG synchronized.
When adding agents or changing detection logic:
| File | What to update |
|---|---|
docs/user-guide/ai-agents.md | Agent support, detection method |
docs/backend/output-parser.md | Agent-specific parsing rules |
docs/FEATURES.md | Section 6 (AI Agent Support) |
src-tauri/src/mcp_http/plugin_docs.rs | agentTypes valid values in PLUGIN_DOCS |
UI Components & Panels
When adding or modifying panels, status bar, toolbar, sidebar:
| File | What to update |
|---|---|
docs/FEATURES.md | Relevant section (2-5: Sidebar, Panels, Toolbar, Status Bar) |
docs/frontend/STYLE_GUIDE.md | If changing visual patterns |
docs/frontend/components.md | Component tree, panel descriptions |
| Domain user guide | e.g. docs/user-guide/sidebar.md, docs/user-guide/file-browser.md |
Markdown Inline Review Comments (tweaks) & Highlight Rendering
When modifying the tweak-comment format, the selection/popover UI, or the DOM highlight wrapping:
| File | What to update |
|---|---|
src/utils/tweakComments.ts | Marker format, parse/insert/remove/update, sentinels, convention header |
src/utils/tweakDomHighlight.ts | DOM-side sentinel→.tweak-highlight span wrapping |
src/components/MarkdownTab/CommentOverlay.tsx | Floating Comment button + inline popover + hover tooltip |
src/components/MarkdownTab/MarkdownTab.tsx | Save/delete wiring, write-back to disk |
src/components/ui/ContentRenderer.tsx | Sentinel injection + applyTweakDomHighlights on render (shared with the AI Chat panel) |
docs/FEATURES.md | Section 3.3 (Markdown Panel) — Inline review comments |
TUIC SDK & iframe Integration
When modifying the TUIC SDK, iframe postMessage protocol, path resolution, or tab injection:
| File | What to update |
|---|---|
src/components/PluginPanel/tuicSdk.ts | Inline SDK script for plugin iframes |
src/components/PluginPanel/resolveTuicPath.ts | Path resolution (relative/absolute, traversal guard) |
src/components/PluginPanel/PluginPanel.tsx | Host-side message handlers, SDK injection |
docs/tuic-sdk.md | SDK reference — API methods, path resolution, testing |
docs/examples/sdk-test.html | Interactive test page (update when adding SDK methods) |
docs/plugins.md | Plugin developer guide (if plugin-facing API changes) |
Deep Links
When adding or changing tuic:// schemes:
| File | What to update |
|---|---|
docs/FEATURES.md | Section 17.4 (Deep Links) |
docs/plugins.md | If affecting plugin contentUri format |
Documentation Site (mdBook + Pagefind)
Mutation testing
When changing how make mutants selects, builds or runs mutants:
| File | What to update |
|---|---|
src-tauri/.cargo/mutants.toml | Test tool, cargo test args, excluded globs |
scripts/mutants.sh | git archive export + --in-place + --in-diff mechanics, the dist copy generate_context! needs |
Makefile | The mutants target and its RANGE default |
AGENTS.md | “Tests” section bullet (per-change rule, who runs it, surviving-mutant policy) |
CONTRIBUTING.md | The install line and the one-paragraph mention |
Config-instance scoping (TUIC_APP_INSTANCE)
When changing which make target launches against which configuration directory:
| File | What to update |
|---|---|
Makefile | The dev and test recipes. A TUIC_APP_INSTANCE default MUST be target-specific (test: TUIC_APP_INSTANCE?=…) — a line-start assignment is global whatever target follows it, and sends make dev to an empty instance |
scripts/check-make-instance-scope.sh | The expected value per target, and the structural check. It asks make -n what it expands rather than reading the line |
scripts/hooks/pre-commit | Gate 1 runs that script when Makefile is staged. Gate F runs landing’s cargo fmt --check (src-tauri) and biome check (staged src/ TS) on the working tree, refuses the staged paths they report and prints the fix command; TUIC_SKIP_FORMAT_GATE=1 skips only gate F. Gate 2 is the agent-state fixture gate; TUIC_SKIP_FIXTURE_GATE=1 deliberately skips only gate 2; a skip is declared by a Fixture-Gate-Skip: commit trailer that scripts/hooks/report-fixture-gate-skips.sh lists |
docs/backend/config.md | The override forms and what each target defaults to |
CHANGELOG.md | Only when the behaviour a user sees changes |
When adding, renaming or moving a docs page:
| File | What to update |
|---|---|
docs/SUMMARY.md | Required — mdBook only renders, and Pagefind only indexes, chapters listed here. A file that is not in SUMMARY.md is invisible to readers and to search |
docs/index.md | “Popular articles” cards and “Browse by section” list, if the page belongs there |
scripts/build-docs.sh | Only when the pipeline changes (excluded pages, Pagefind flags, HTML rewrites) — CI and make docs both run this one script |
docs/guides/development-setup.md | “Documentation Site” section, if the build steps change |
Documentation File Index
| Path | Purpose |
|---|---|
| Root | |
SPEC.md | Feature specification, architecture, version |
CHANGELOG.md | Release history (Keep a Changelog format) |
AGENTS.md | Project rules, compact reference; must stay under 32,768 bytes (~/Gits/.agent-tools/check-instruction-links.py) — move detail to the pages below |
CONTRIBUTING.md | Contributor guide (test requirements, PR quality gates) |
to-test.md, to-test/*.md | Manual testing tracker (index plus area files) |
| docs/ | |
docs/FEATURES.md | Canonical feature inventory (single source of truth) |
docs/plugins.md | Plugin developer authoring guide |
docs/tuic-sdk.md | TUIC SDK reference (inline + URL tab postMessage protocol) |
docs/api/tauri-commands.md | All Tauri IPC commands |
docs/api/http-api.md | REST/HTTP endpoint reference |
docs/architecture/overview.md | High-level architecture |
docs/architecture/data-flow.md | IPC and data flow |
docs/architecture/state-management.md | Store patterns |
docs/backend/pty.md | PTY session lifecycle |
docs/backend/output-parser.md | Output parsing and structured events |
docs/backend/git.md | Git operations |
docs/backend/github.md | GitHub API integration |
docs/backend/config.md | Configuration file management |
docs/backend/mcp-http.md | MCP/HTTP server, lazy tool discovery, meta-tools |
docs/backend/dictation.md | Whisper voice dictation |
docs/backend/error-classification.md | Error types and backoff |
docs/backend/agent-state-detection.md | Agent working/idle/awaiting detection rules (moved from AGENTS.md) |
docs/backend/agent-session-management.md | Agent session discovery and resume rules (moved from AGENTS.md) |
docs/backend/diagnostics.md | Runtime diagnostics reference (moved from AGENTS.md) |
docs/guides/agent-testing-rules.md | Test skips, timing assertions, test instance, web-UI testing (moved from AGENTS.md) |
docs/frontend/perf-debug.md | perfDebug master flag (moved from AGENTS.md) |
docs/frontend/STYLE_GUIDE.md | Visual design rules |
docs/frontend/components.md | Component tree reference |
docs/frontend/hooks.md | Custom hooks |
docs/frontend/stores.md | SolidJS stores |
docs/frontend/transport.md | Tauri/HTTP dual-mode transport |
docs/frontend/utilities.md | Utility function reference |
docs/frontend/terminal-features.md | Consolidated terminal behaviors, shortcuts, configurable features |
docs/features/ssh-tunnels.md | SSH tunnel architecture and module map |
docs/user-guide/*.md | User-facing guides (20 files) |
| Code-embedded docs | |
src-tauri/src/mcp_http/plugin_docs.rs | AI-optimized plugin reference (PLUGIN_DOCS const) |
src/actions/actionRegistry.ts | ACTION_META → auto-populates HelpPanel + Command Palette |
examples/plugins/ | Reference plugin implementations (7 examples) |
Remote upstream health (#1444-95a4): remote_mirror forwards upstream-status-changed with the locally saved host label; mcpPopupStore refreshes the originating daemon through explicit RPC into remoteStatus. Remote events never refresh or save local server configuration. App-lifetime notices remain visible while the popup is closed; disconnect invalidates in-flight snapshots.
Remote ACP notices wake a separate daemon-scoped interaction queue in AI Chat. Pending questions and responses use the existing ACP HTTP routes with an explicit remote owner; settlement/disconnection remove only that daemon’s questions. Local ACP connections are not attached or changed.
GitHub pollers now cold-start without a desktop AppHandle. Remote PR/issue snapshots and transitions share the notice forwarding path; repository ownership gates desktop consumers, daemon-owned URLs are fetched explicitly, and remote transitions never invoke local automation. Bell identity includes daemon ownership.
Terminal Chat view (desktop and mobile)
Update desktop TerminalChatView.tsx and mobile useSessionChatView.tsx through
TerminalChatTranscript.tsx. Keep their shared contract suite aligned. Mobile
wakes must use the existing useSessions SSE subscription, not another stream.
Host hints, file navigation and desktop search may differ; binding, cursor resets,
visibility lifecycle and transcript scrolling must remain shared.
A capped message (… [truncated, N chars total]) offers Show full text through
TruncatedTextAction and chat_view_full_text; the backend re-reads that one message from the
transcript, so the stream cap stays.
Settings startup workflows
When changing published Settings startup discovery, authentication workflows or recovery, keep docs/backend/settings-startup.md synchronized with the action schema/owner services. Update the API/Tauri references, backend config/GitHub/MCP docs, frontend store state semantics, user Settings/GitHub/AI Chat/remote guides, plugin authority boundaries, FEATURES and SPEC. Catalogue inventory completeness must not be presented as proof of live onboarding or UI parity.
Release & Tag Checklist
When Boss asks to tag a release:
- Update version: run
make bump V=x.y.z(updates all manifests, CHANGELOG, SPEC.md, and generates AI release notes with contributor extraction viascripts/generate-release-notes.sh) - Review release notes — the script shows AI-generated notes for approval (Y/edit/regenerate/quit). Ensure
### Communitysection in CHANGELOG lists all external contributors with PR links - Commit with message
chore: bump version to vX.Y.Z - Prepare the public snapshot — keep development
mainprivate. Create a reviewed JSON file with the groupsBreaking changes,New features, andFixes(arrays of public-facing sentences). Runmake github-release RELEASE_NOTES=/absolute/path/to/groups.json. The target uses the shared orchestratortools/release/snapshot.pytool, removes its configured private paths, refreshes public refs, and pushes onlyrelease/<version>. It prints the snapshot SHA. The existing generatedrelease-notes.jsonis a different format; do not pass it as grouped notes. - Integrate and tag — open a PR from
release/<version>to publicmain, wait for CI, then fast-forward publicmainto the reviewed snapshot. Runmake github-release RELEASE_COMMIT=<snapshot-sha>. It refuses tagging until publicmainequals that commit and its release version matches. The shared guard checks the public tag target before the push. TheReleaseworkflow builds the signed installers, remote daemon, andlatest.json, then publishes the release. Verify its assets; do not create a second release. - Milestone — close the matching milestone if one exists, create the next one
Prereleases (betas)
After publication, release.yml calls notify-tap.yml directly with the published
tag and prerelease flag. It uses the existing HOMEBREW_TAP_TOKEN to dispatch
release-published to sstraus/homebrew-tap with repo and version. The notifier
accepts stable v* releases only; beta and nightly releases do not update the tap.
It also listens for releases published outside the release workflow.
The direct call is required because GitHub suppresses workflow runs for release
events created with GITHUB_TOKEN.
Use make bump V=2.0.0-beta.1 and the same snapshot, PR, and post-integration tagging steps for v2.0.0-beta.1. scripts/release-flags.sh makes release.yml publish any version with a - suffix as a prerelease that is never “latest”, and notify-tap.yml skips prereleases. The stable updater endpoint (releases/latest/download/latest.json) and the install scripts read “latest”, so stable users stay on stable. After every completed versioned beta release, the finalization job copies its signed latest.json to the rolling beta prerelease (never latest). Installers remain on the immutable versioned release. Settings → General → Expert Mode → Update Channel → Beta checks this feed automatically and also checks stable, so testers receive the next beta and the final release. New beta installations default to Beta; an existing saved channel is preserved, so existing users who install a beta must choose Beta once. Beta updates open the versioned download page; final stable updates install in-app. Nightly behavior is unchanged. An older beta finishing later cannot replace a newer feed. No beta is published if the versioned release or its manifest is incomplete.
The macOS terminal installer preserves an installed Beta or Nightly channel when no version is given. Use install.sh beta or install.sh nightly to select one explicitly, or pass a version with or without a single v prefix to pin it. A default stable install resolves GitHub’s latest stable tag. Beta downloads use the immutable tag named by the rolling manifest.
GitHub Issue Management
- Labels: Use
type:,P0-P3:,area:,effort:prefixes. Applyneeds triageto new issues. - Milestones: Assign issues to version milestones (v0.4.0, v1.0.0, etc.)
- Issue templates: Bug reports and feature requests use
.github/ISSUE_TEMPLATE/*.ymlforms - Token for project ops: Use
GH_TOKEN=$GH_STRAUS gh ...when commands need theprojectscope (the defaultgh authtoken only hasrepo+workflow)
Daily public nightlies
Run make nightly only for an approved private main commit. It snapshots
refs/heads/main even when invoked from another clean branch, creating one snapshot per
local calendar day, parented to public origin/nightly (public origin/main for
the first nightly), removes private paths through the shared policy, and pushes
only the nightly branch and its moving nightly tag. tip is no longer used.
A repeated or earlier date is refused. NIGHTLY_DATE=YYYY-MM-DD selects an
explicit date. The workflow builds the exact public snapshot across desktop,
daemon, and release-note jobs, including manual dispatches.
Both targets require Python 3 and the orchestrator snapshot tool at
~/Gits/personal/orchestrator/tools/release/snapshot.py; SNAPSHOT_TOOL can select
another installed copy. The tool owns exclusion policy, ancestry validation,
secret scanning, and public push checks. Neither target pushes development main.
Use scripts/with-test-tmp.sh python3 scripts/test_release_targets.py to exercise
these targets against disposable local bare remotes with the shared tool installed.
Project History
Timeline
Started: February 5, 2026 Total commits: 475+ Contributor: Stefano Straus (solo developer) Convention: Conventional commits with story references
Milestones
| Date | Milestone | Key Changes |
|---|---|---|
| Feb 5 | Project inception | First commit, worktree terminal support |
| Feb 6-7 | Core infrastructure | Sidebar, toolbar, tab system, terminal persistence |
| Feb 8 | Stability & testing | PTY stability overhaul, 830 tests at 80% coverage |
| Feb 8 | GitHub integration | PR monitoring, CI rings, batch status checks |
| Feb 15 | Voice dictation | Whisper.rs integration, push-to-talk, model management |
| Feb 15 | Remote access | HTTP server, WebSocket streaming, MCP bridge |
| Feb 15 | Settings unification | Consolidated settings, Rust config infrastructure |
| Feb 16 | Architecture refactor | App.tsx split into hooks, lib.rs split into modules |
| Feb 16 | Rust migration | 14 business logic functions moved from TS to Rust |
| Feb 16 | Cross-platform | Windows/Linux support, platform detection |
| Feb 16 | Native menu | System menu with keyboard shortcuts |
Architecture Evolution
Phase 1: Rapid Prototyping (Feb 5-7)
- Monolithic
App.tsx(~2000+ lines) - localStorage for persistence
- Frontend-heavy business logic
- Working but unmaintainable
Phase 2: Stabilization (Feb 8)
- PTY reliability hardened (UTF-8 boundaries, ANSI escape handling, DashMap concurrency)
- Vitest test infrastructure added (830 tests across 4 tiers)
- Performance tuning (WebGL renderer, flow control with watermark backpressure)
Phase 3: Feature Expansion (Feb 8-15)
- GitHub integration (batch PR queries, CI ring visualization)
- Voice dictation (Whisper with Metal acceleration)
- Remote access (HTTP/WebSocket, MCP SSE transport)
- Split panes, prompt library, settings consolidation
Phase 4: Architectural Maturity (Feb 16)
- Hook extraction: App.tsx split into 8 focused hooks (useTerminalLifecycle, useGitOperations, useAppInit, etc.)
- Rust module extraction: lib.rs monolith split into state.rs, pty.rs, git.rs, github.rs, agent.rs, worktree.rs, etc.
- Business logic migration: 14 functions moved from TypeScript to Rust, following the “Logic in Rust” architecture mandate
- Cross-platform support: Shell detection, platform config directories, conditional compilation
Feature Commit Distribution
| Area | Commits | Percentage |
|---|---|---|
| Git/Worktree Operations | ~272 | ~57% |
| GitHub Integration | ~52 | ~11% |
| UI & Styling | ~36 | ~8% |
| Terminal & PTY | ~29 | ~6% |
| Architecture Refactors | ~23 | ~5% |
| Settings & Config | ~15 | ~3% |
| Testing | ~14 | ~3% |
| Voice Dictation | ~14 | ~3% |
| Remote Access & MCP | ~12 | ~3% |
| Cross-Platform | ~6 | ~1% |
Commit Conventions
- Conventional commits:
feat:,fix:,refactor:,chore:,perf:,test:,style:,docs: - Story references:
(Story 093)suffix when linked to a story - Git notes: Every commit has a git note for additional context
- Story tracking: 214+ stories in
stories/directory with YAML frontmatter
Story System
Stories are tracked as markdown files in stories/:
stories/
200-18c5-complete-P2-move-error-classification-logic-from-ts-to-rust.md
┃ ┃ ┃ ┗━ Slug from title
┃ ┃ ┗━ Priority (P1/P2/P3)
┃ ┗━ Status (complete/pending/blocked/wontfix)
┗━ Sequence number + 4-char hex suffix
Format: YAML frontmatter (id, title, status, priority, dates) + markdown body with work log.
External story adapter spike (2727-ae2c)
This is a disposable JSON-RPC stdio adapter, not a TUIC integration. It imports the
parser from the installed root returned by wiz-run --root; it does not copy Wiz
source or change the WORK repository. Writes call that root’s stories-cli.js.
The measurement uses a fresh Git repository below ~/Gits/.tmp/2727-spike/.
It copies 385 real story files: the current top-level files followed by enough
archived files to reach 385. Archive samples are flattened only in the copy.
The original design’s count was a snapshot; the active folder changes during work.
No adapter write targets the real store. Story tracking commands target the main
checkout separately.
Reproduce from the spike worktree:
node scripts/spikes/2727-story-adapter/measure.cjs \
/Users/stefano.straus/Gits/personal/tuicommander \
> "$HOME/Gits/.tmp/2727-spike/output.json"
The driver starts one Node adapter and closes it through shutdown. It exercises
initialize, list_stories, get_story, apply and changes over newline-delimited
JSON-RPC 2.0. initialize returns the copied folder as watch_paths.
changes reads and hashes every file on each call; a mismatched cursor requests a
rescan. It keeps one baseline, sufficient for this single-consumer spike only.
Read records include Wiz frontmatter and the SHA-256 version of the original bytes.
Latency is wall-clock time at the driver, including pipe transport, parsing and
serialization. Each warm measurement contains 50 sequential requests. Cold
initialize includes adapter startup. No jobs run in parallel except the explicit
competing writer. Watch latency contains 10 appends: arm a listener, append to a
copy, receive the fs.watch hint over stdout. This measures the hint, with no
debounce, not freshness of a rendered view. Events can coalesce; required cursor
scanning remains the correctness path.
The race probe first verifies a stale hash is refused with unchanged bytes. Then,
five times, it pauses the adapter immediately after a successful hash comparison,
runs the real Wiz CLI in a second process to change the same title, confirms that
write through get_story, releases the adapter, and reads the result. This is a
controlled interleaving, not an estimate of production race frequency. The pause
changes only scheduling; both competing mutations still use unmodified Wiz CLI.
The adapter re-reads after mutation, as proposed. A post-read cannot distinguish
its own legitimate write from a write that replaced another writer’s field.
The completion probe attempts set_status: complete on the selected pending/ready
story without satisfying its criteria. It records the actual Wiz refusal and final
status. Configuration in this scratch Git repository is default; it does not prove
all project-specific proof/review gates or exercise the native TUIC command path.
Results (2026-11-02)
Native Mac, darwin/arm64, Node v26.13.0, Wiz 6.0.0-beta.3. Source tree: dbefa5be83e5a5d791c6d6ac7a1fafed3be6acc5. Scratch evidence: /Users/stefano.straus/Gits/.tmp/2727-spike/run-1793639665721. Raw results preserve the samples summary, gate error and race outcomes. The committed scripts are the measured implementation; no Rust build or TUIC runtime integration was needed.
| Operation | Samples | Median ms | p95 ms | Maximum ms |
|---|---|---|---|---|
| initialize | 50 | 0.047 | 0.123 | 0.172 |
| get_story | 50 | 186.455 | 815.561 | 1513.866 |
| list_stories | 50 | 204.790 | 932.340 | 1010.835 |
| changes | 50 | 184.937 | 901.196 | 2890.126 |
| watch_hint | 10 | 50.904 | 61.693 | 61.693 |
Cold initialize: 72.096 ms (one sample). Complete refusal: 147.547 ms (one sample); CLI exit 1, RPC refused, two unmet criteria, status stayed pending. Stale expected-version: one conflict, byte version unchanged. Controlled check/write races: 5/5 external titles overwritten, 0/5 conflicts reported. Race elapsed times: 403.940, 1056.903, 382.014, 468.494, 337.332 ms.
The first setup attempt refused to run because only 381 active files existed, rather than silently reporting a 385-file measurement. The completed run used four real archive files to reach the requested size. The measurement assertions all passed; the unsafe race is the expected experimental finding, not a passing safety guarantee.
Decision: NO-GO for writable deployment
The process protocol works, but a hash check followed by an independent CLI mutation does not meet “detected, never overwritten”. Re-reading after the write does not repair that guarantee. This acceptance criterion remains unmet; it must not be checked off as safe. A lock used only by the adapter would also leave external CLI writers outside the transaction. The writer must compare the expected version under the same lock as its mutation, with all writers honoring that lock, before TUIC can offer this guarantee. That requires ownership and work in Wiz, outside this spike.
The stdio transport itself is viable for continued protocol and port work. Full-folder scans here cost about 185 ms median and 901 ms p95 under shared-machine load. These are implementation-specific costs, not pipe overhead: get_story intentionally scans all 385 files as well. Indexing/caching was outside the bounded experiment. A later adapter must budget scan frequency; watcher hints cannot replace cursor scans. No performance acceptance threshold was supplied.
Limits: one platform, one loaded-machine run, default scratch configuration, one operation class raced (same-field title update), and no production supervisor, crash recovery, malformed-file handling or multi-client cursor history. No claims are made for these unmeasured behaviors. The completion call came from the throwaway protocol driver, not the native TUIC UI. No production frontend/backend behavior changed, so no manual restart or visual check is required.
Desktop access to a remote daemon through the relay
- Date: 2026-10-20.
- Status: Proposal.
- Scope: one native desktop client and one already-installed headless daemon per relay room. No code changes, deployment, mobile onboarding, or hosted-service claim.
1. Result and roles
The desktop must connect to a daemon that has no inbound route from the desktop. Both endpoints make outbound WSS connections to a relay. After endpoint authentication, the desktop uses the same remote connection, HTTP handlers, events, and terminal protocols as a direct connection.
Desktop app Relay Remote host
remote_runtime tools/relay tuic-remote
| outbound WSS | outbound WSS <---------------- |
+-------------------------->| |
|<====== authenticated, encrypted endpoint channel =========>|
| |
local loopback listener opaque forwarding fixed daemon listener
|<------ multiplexed HTTP / SSE / WS byte streams ----------->|
| Role | Owns | Must not own |
|---|---|---|
| Desktop client | Saved connection ID/name, endpoint pairing secret, daemon credential, local tunnel listener, remote UI projection | Remote PTYs, remote filesystem state, a second implementation of daemon commands |
| Remote daemon | Repositories, sessions, PTYs, existing request handlers/auth, outbound relay agent, fixed local upstream target | Desktop window state, arbitrary relay-requested TCP destinations |
| Relay | Bearer admission, room occupancy, bounded forwarding, peer-loss hints | Pairing secret, daemon credential, application plaintext, command execution |
The daemon must already be running and configured through host access or a trusted administrator. A relay is not a way to install a daemon on an inaccessible host. Start with an installed daemon; do not add relay-driven SSH deployment or automatic daemon upgrades in this design.
2. Observed baseline, not product acceptance
This proposal does not establish that a hosted service is deployed. The baseline prototype does not provide endpoint encryption independent of relay admission.
Source integration seams:
| Source | Observation |
|---|---|
tools/relay/src/routes.rs, build_router, register | The relay has /register and /ws/{session_id}. Registration issues a relay bearer, not an endpoint identity or pairing secret. |
tools/relay/src/relay.rs, handle_ws | The current source requires the first Bearer frame and atomically checks room ownership, capacity, and token limits. Rooms still allow only two peers. |
Same file, forward_to_others | try_send still silently drops a full peer queue. This cannot carry a reliable tunnel without a defined close/backpressure policy. |
src-tauri/src/relay_client.rs, derive_key, connect_and_run | Encryption still derives from the relay bearer. The decrypted command branch still logs that dispatch is not implemented. Its mobile event bridge is not a remote-daemon transport. |
src-tauri/src/remote_connection.rs, RemoteTransport | Saved transports are SSH and Direct. The store and existing connect/disconnect commands are the connection-management seam. |
src-tauri/src/remote_runtime.rs, resolve_base_url, authenticate, teardown | SSH already resolves to a loopback HTTP URL. Runtime owns status, auth, version/health probes, supervision, and generation-safe teardown. |
src/transport/http.ts, owningConnectionFor, rpc; src/transportRuntime.ts | Repository/session ownership selects the connection; HTTP mappings and remote base URL/token select the daemon. |
src-tauri/src/remote_mirror.rs, seed, consume_stream, store_seed | Existing mirroring seeds GET /sessions, consumes /events, replaces owner-scoped rows, and re-seeds on reconnect. |
src/components/Terminal/canvasTerminalTransport.ts, WsTransport | Remote terminals use the connection’s URL/token and the existing grid WebSocket, including compression negotiation and stale-socket guards. |
src-tauri/src/lib.rs, spawn_daemon_background_tasks, run_remote | Headless startup has its own task list. A daemon-side outbound tunnel supervisor must be added explicitly; the desktop relay supervisor is not evidence that it runs there. |
Source inspection is not a fresh build, test run, or end-to-end demonstration.
3. Pairing and trust boundary
Separate three credentials
- R: relay admission bearer. The relay issues it and receives it in the first WSS text frame. Initially the two peers share the same R because current room ownership requires the same token. R grants relay capacity only.
- P: endpoint pairing secret. The daemon generates 32 random bytes with the OS CSPRNG, independently of R, room ID, passwords, and daemon tokens. P authenticates the encrypted desktop-to-daemon channel. The relay must never receive P or a key derived from P that permits decryption.
- D: existing daemon API credential. Keep the daemon’s existing authenticated HTTP boundary. P is not a replacement for the HTTP auth middleware, and R must never authenticate daemon requests.
P and D are separate values with separate storage. Existing RemotePairingToken is a daemon API credential used by remote_runtime::authenticate; despite its name, it must not silently become P. run_remote can set the daemon session token from its pairing-token option. It does not provide per-client API revocation today.
Proposed first pairing sequence
- On the remote host, the operator enables a new relay pairing through a host-local setup operation. It obtains R through the existing relay registration contract (or accepts an operator-provisioned R), chooses a random room ID, and generates P. This is an explicit setup action, not a registration on every reconnect.
- Store R, room, relay origin, P, pairing version/ID and daemon credential association in instance-scoped backend storage. Secrets use the existing credential-storage abstraction, not plaintext
connections.jsonor ordinary settings exports. A host without a usable credential backend needs an explicit protected-file or ephemeral setup choice; never silently write plaintext secrets. - The operator transfers a versioned pairing bundle to the desktop by a trusted channel independent of the relay: a file copied through authenticated SSH, a local QR, or a deliberate copy/paste from the host console. It contains the relay WSS origin, room, R, pairing ID and P. Neither registration nor the relay WebSocket URL contains P.
- The native desktop imports the bundle into an ordinary saved connection with proposed
Relaytransport metadata. Store P separately from public connection data. Do not upload the bundle, put it in process arguments, or log it. Do not load pairing code from a relay-served page. - Both peers connect outbound to
/ws/{room}, authenticate to the relay with R, then perform mutual endpoint authentication using P. The desktop is the initiator; the daemon is the responder regardless of arrival order. A plaintextrelay:status connectedis only a hint to start that handshake, never proof of daemon identity. - Only after endpoint authentication, the daemon supplies D inside the encrypted control channel to the paired desktop backend. The desktop stores D through the existing remote credential mechanism and runs the ordinary health/version/auth probes through the tunnel. On reconnect, refresh D over that authenticated channel if the daemon has changed it. Do not expose D in outer relay frames. Giving D to a holder of P deliberately grants the same full API authority as a direct paired client.
- Advertise
connectedonly after those probes succeed. Start the existing mirror and allow frontend routing at that point, not at WSS open.
A copied bundle is a capability: anyone holding it can impersonate either endpoint for that pairing. Initial scope is one desktop/daemon pair, not multi-user authorization. Delete pairing means remove P on the daemon, terminate its channel, and delete the desktop’s stored association. Rotate P and use a fresh room/R after bundle exposure. Revoking P alone does not revoke an already disclosed D; rotate the daemon credential too, with an explicit warning that other direct clients using it must re-pair. Do not claim per-client revocation until the daemon supports it.
Live pairing changes (2700-c56d). The headless daemon re-reads its stored pairing every 2 seconds. A pairing stored while it runs starts the agent; a replaced pairing restarts it on the new room and secret; a deleted pairing stops it, which closes the relay connection and any attached desktop session. The read bypasses the daemon’s in-process cache, because tuic-remote --relay-pair runs as a separate process. An unreadable vault keeps the running agent: a read error is not a deletion. A daemon started with a credential file (select_credential_file) has no other writer to follow, so it keeps the pairing until restart.
Relay registration stays anonymous, with these bounds (decision, 2700-c56d). POST /register issues a relay bearer R, and R is admission only. This matches the threat model of one developer with his own machines. The bounds are: R alone opens no upstream socket on the daemon, because the Noise handshake with P comes first; the relay rate-limits registration per IP (RELAY_RATE_LIMIT_PER_HOUR, default 10); a room holds two peers and a token holds a limited number of sessions (RELAY_MAX_SESSIONS_PER_TOKEN, default 5). An operator who wants no anonymous registration pre-provisions R and sets TUIC_RELAY_TOKEN instead of --relay-register, and sets the registration rate limit on the relay low (0 means unlimited). A relay-side authenticated owner is not built: it would add an identity system that no named threat in this model needs.
Encrypted channel requirements
Use a versioned, reviewed PSK-authenticated handshake with fresh session keys and mutual key confirmation. Recommendation: evaluate a maintained Noise PSK implementation (for example the NNpsk0 pattern) rather than inventing a handshake around the prototype’s encrypt function. The exact suite/library, dependency/license impact, record limits and handshake transcript must be reviewed and fixed before the crypto implementation step. This note is not an assertion that such a library is installed or verified.
Bind protocol version, pairing ID, room and expected roles into the authenticated handshake context. Use separate directional keys and ordered authenticated records. Each new attachment uses a fresh handshake/epoch; reject reflected frames, duplicate/out-of-order records, unknown versions, and old-epoch data before opening upstream sockets. Bound handshake time and record length. Never fall back to bearer-derived v1 encryption after a handshake failure. Do not claim forward secrecy without checking the selected handshake’s properties.
The relay sees R, room, IPs, timing, sizes, and attachment metadata. It can deny service, substitute peers, reorder/drop data, or lie about presence. It must not be able to authenticate an endpoint, derive P, decrypt payloads, or replay commands into a new epoch. Endpoint compromise or theft of the bundle is outside that guarantee. WSS protects each hop; endpoint authentication protects against an active relay. Native client distribution and the host setup channel are trusted. A future web client needs a separately trusted origin: relay-served JavaScript could steal P even if it arrives in a URL fragment.
No push hints with session names or command data are needed for this desktop tunnel. Keep push/mobile work separate.
4. Reuse the direct-remote contracts
Recommended adapter: a multiplexed byte tunnel
Add a backend-owned local loopback listener per active relay connection. It returns an ordinary http://127.0.0.1:<port> base URL, just as the SSH path does. Each accepted TCP socket becomes one logical stream inside the authenticated relay channel. On the daemon side, Open(stream_id) connects only to the daemon’s own configured loopback HTTP listener. The peer cannot supply a hostname, port, Unix socket, executable, or Tauri command name.
The new wire vocabulary is transport control only: Open, Opened/OpenFailed, Data, WindowUpdate, Fin, Reset, and authenticated liveness/control messages. Stream IDs are unique within an epoch. Data preserves byte order; half-close and cancellation are explicit. Tunnel frames are encrypted before the relay sees them. TCP socket lifetime provides HTTP response correlation; existing HTTP and WebSocket protocols retain their own request/frame semantics. There is no new application command/reply envelope or relay-specific handler dispatcher.
Keep daemon authentication enabled. The listener is not a trusted-local IPC bypass: the bytes terminate on the existing authenticated headless TCP server. The frontend and backend keep using D through current query/cookie/header handling. P and R never reach frontend URL builders. HTTP requests, status codes, error bodies, SSE framing, WebSocket upgrade/subprotocol headers and binary frames pass through unchanged. The desktop listener binds loopback only and lives only as long as that connection generation; it is not a relay-side HTTP gateway.
| Desktop operation | Existing contract to carry unchanged |
|---|---|
| List remote repositories | load_repositories mapping → GET /config/repositories |
| List sessions and seed badges | list_active_sessions / mirror → GET /sessions |
| Open a terminal | create_pty mapping → POST /sessions, same request and { session_id } reply; existing mapper extracts the ID |
| Input and resize | Existing /sessions/{id}/write, /resize contracts; keep current write ordering/coalescing |
| Terminal output | Existing /sessions/{id}/stream?format=grid WS, full initial frame, deltas, ACKs, compression subprotocol |
| State and lifecycle | Existing /events SSE, mirror owner tagging, reconnect seed and registered frontend consumers |
| Errors and compatibility | Existing auth, health/version probes, route errors and HttpRpcError; no application-level translation |
Reuse the same connection_id for repository/session ownership. Existing IPC calls for remote-owned work must continue through owningConnectionFor and the HTTP table, not accidentally invoke local Tauri handlers. Keep desktop-only commands intentionally unmapped. The tunnel exposes only what the headless daemon already exposes; it does not add desktop routes to it.
Backend consumers such as remote_mirror, version probes and remote file operations also use the loopback route. This is why a frontend-only relay rpc() branch is insufficient. Preserve the existing IPC/HTTP connection-management parity when extending the saved transport union and status metadata; no new command surface is needed for relay business operations.
Keep this pairing and its room separate from services.relay and the existing mobile event bridge. Do not repurpose that global desktop configuration as a saved remote connection or silently upgrade its bearer-derived protocol. The new version must fail closed with old peers; direct/SSH connections and the existing bridge retain their current explicit behavior until separately migrated.
Boundedness and congestion
The relay’s current 32-entry queues must not silently discard tunnel records. Initially close the affected room/attachment on queue overflow and notify both peers; closing only one forwarding direction can leave the other endpoint falsely connected. Never continue a byte stream after loss. Endpoint detection of missing ordered records and authenticated heartbeat deadlines is a second protection, including against a malicious relay.
Proposed initial limits, not measured performance claims: 32 logical streams, 16 KiB data chunks, and 64 KiB receive credit per stream. That is at most 2 MiB of credited data per receiving endpoint, plus separately bounded control, cipher and socket buffers. Charge queued bytes globally as well as per stream; queue counts alone do not bound memory. Bound outer WS message size before allocation. Reserve control capacity and schedule data fairly so one busy PTY cannot indefinitely block health replies or input. On credit exhaustion stop reading that socket; on a stalled peer close after a bounded deadline. These limits require integration tests before being treated as supported capacity.
Relay policy as implemented
- A full peer queue waits up to 5 s (
peer_send_timeout), then the relay closes the room with code 4004. No frame is dropped silently. - The relay pings every peer every 20 s and reaps a peer after 60 s of silence. A Pong counts as activity, so an idle but live peer is never reaped.
- The queue-overflow close and the reaper apply to every room, including the phone rooms of the existing event bridge, not only tunnel rooms.
- Outer WebSocket messages are capped at 1 MiB before allocation.
- The Noise prologue binds protocol version, pairing ID and room, not the relay hostname, because the two ends may reach one relay under different names.
5. Failure, reconnect and session identity
Use RemoteStatus for the public connection state and typed relay phase/reason metadata for detail. Proposed phases are dialing, waiting_peer, authenticating, probing, ready, and retry_wait; reasons include relay_unreachable, peer_absent, admission_rejected, pairing_rejected, congested, daemon_unreachable, and protocol_mismatch. Carry any new status fields on the same dual-emitted IPC/SSE remote-connection-status payload, with no secrets.
| Situation | Public state and behavior |
|---|---|
| Dialing, alone in room, handshake, probes | connecting, with a typed phase. No routable base URL/token until ready. |
| Mutual authentication and daemon probes pass | connected; publish the route, start one mirror and normal terminal sockets. |
| Relay loss, peer loss, authenticated heartbeat timeout or overflow | Immediately leave connected; disconnected with typed reason, then connecting/retry_wait while automatic retry is enabled. Close all old logical streams and fail pending I/O. |
| Wrong P, revoked P, invalid D or rejected R | unauthenticated, with a reason that distinguishes admission, pairing and daemon auth. No endless retries with the same rejected credential. |
| Incompatible protocol or invalid framing | error, typed reason, no legacy downgrade. |
| User disconnect/delete/disable | disconnected; existing teardown() retires the generation, closes listener, tasks, streams, mirror and credentials-in-memory. No retry may resurrect it. |
| Daemon restarts | Old streams fail. New handshake and probes, refresh D if needed, then re-list repositories/sessions and reopen subscriptions. Never infer that a prior PTY survived. |
Reuse the runtime’s single claimed supervisor and retirement generations. The relay adapter must report loss promptly into that owner, not create a competing reconnect loop that bypasses explicit disconnect. Reuse bounded exponential backoff with jitter; distinguish successful WSS admission from successful endpoint/daemon readiness before resetting it. Proposed endpoint liveness: authenticated ping every 15 seconds, consider the channel dead after 45 seconds without an authenticated response. Relay-generated status alone cannot refresh that deadline. Setup budgets are separate from liveness budgets.
Reconnect means reattach, not recreate. Keep daemon-issued session UUIDs and owner-scoped UI identities. Reuse the mirror’s replace-on-seed behavior and terminal initial-frame recovery. Do not replay old grid deltas, HTTP requests, terminal input, or POST /sessions after tunnel loss. If the daemon executed a mutation but its reply was lost, report an uncertain outcome and reconcile with current daemon state; do not automatically retry it. Existing handlers do not establish exactly-once creation across a broken connection. An operator can inspect the re-listed sessions before deliberately creating another one.
“No duplicate sessions on reconnect” therefore means the reconnect path performs no create request. It does not promise exactly-once retry of an interrupted user action. If transparent mutation retries become a requirement, an idempotency contract is a separate design decision, not a hidden relay feature.
Relay room attachment does not itself count as a live user for idle lifetime. Existing HTTP SSE/PTY subscriptions reach the daemon and use its existing client counters. Loss must close those upstream sockets. Recommend installed-daemon operation for this scope; if the operator chooses a finite survive time, warn that it may expire while only waiting in a relay room and desktop reconnect cannot restart that host process.
6. Design choices
The following options remain proposals.
- Transport adapter: use the backend loopback byte tunnel (recommended). It preserves HTTP, SSE, WS and backend consumers with one adapter. Cost: logical stream framing, flow control and a loopback listener. Alternative: relay-native RPC plus explicit event/PTY streams; it avoids the listener but adds adapters to every frontend/backend consumer and risks a parallel command surface. Do not choose a new command dispatcher.
- Pairing: host-generated, high-entropy bundle through a trusted independent channel (recommended). It requires one host-side setup action but works without inbound access. Alternative: manually provision the same random secret on both endpoints. A short relay-issued code alone is not an independent secret; a short-code PAKE flow would need a separate reviewed design.
- Crypto: select a maintained PSK protocol implementation before coding (recommended). It adds a dependency/review decision but avoids a custom cryptographic handshake. Alternative: design a protocol with existing ring primitives; this needs a precise transcript, nonce/replay/key-confirmation specification and independent crypto review. Never retain bearer-derived encryption as fallback.
- Initial topology: dedicated two-peer room, one installed daemon and one desktop (recommended). It matches current capacity and limits lifecycle ambiguity. Multiple desktops require separate pairings/rooms and a separate review of daemon-credential revocation; increasing room capacity alone is not sufficient.
- Recovery: fail in-flight mutations and reattach without replay (recommended). This preserves current handler contracts and prevents reconnect-created duplicates. Transparent retry would require backend idempotency and receipt semantics, beyond this note’s scope.
Select the transport, pairing protocol and topology before implementation.
7. Implementation sequence
Each step must preserve a runnable direct/SSH path; no deployment is required to validate the tunnel.
- Freeze the wire/pairing contract and repair reliable forwarding. Select/review the PSK library and fixed protocol version, encode bounds/roles/epoch rules, and specify admission versus endpoint errors. Change relay overflow handling from silent drop to attachment failure. Keep the already-repaired admission transaction. Tests: full queue disconnects both sides rather than corrupting a stream; a third peer cannot displace a valid pair; same-token second peer is permitted at the room cap; foreign token rejected. These protect named loss/admission regressions, not new application behavior.
- Add daemon pairing and outbound lifecycle. Add host-local setup/import, credential persistence, explicit daemon task startup and shutdown, and a connection to the existing relay endpoint. No inbound firewall change. Tests: R is independent of P; setup/reconnect never transmits P; wrong P never opens an upstream socket; missing/failed credential storage does not silently persist plaintext. Use isolated instance storage and injected credential stores, not the operator’s keychain.
- Add the encrypted stream adapter and desktop transport variant. Implement bounded multiplexing, fixed upstream target, loopback listener and runtime-owned teardown. Wire it through existing connection save/connect/disconnect HTTP and IPC handlers. Tests: HTTP reply correlation on concurrent sockets, WS upgrade plus binary data, incremental SSE delivery, half-close/reset, oversized frame rejection, ordered/replay/epoch rejection, flow-control isolation, delete-during-handshake cannot resurrect a route. Compare direct and relayed status codes/bodies at the existing router boundary.
- Attach existing consumers and UI state. Feed the listener URL/D through normal health/version/auth and ownership routing; extend typed status projection only. Keep current mirror and terminal consumer code unless a failing boundary test proves an adapter change is needed. Tests: repository/session routing stays on the remote owner, local commands remain local, stale-epoch frames do not repaint a replacement terminal, re-seed removes vanished sessions and preserves surviving UUIDs. Update the Remote Connection Manager, daemon and API/config docs identified by the sync matrix; do not advertise the feature as shipped before acceptance.
- One local end-to-end harness, then failure cases. Run a standalone local relay, isolated headless daemon and a desktop transport client using the production runtime adapter, not the daemon’s API directly. Make the daemon address unavailable to that client except through the adapter. Register/attach outbound, list a fixture repository and sessions, create one PTY, send a deterministic command through the existing submit/input contract, and assert output through the existing terminal stream. Wrong P must fail before any command executes. Drop/restart the relay and restart the daemon, reconnect, and prove no extra create request, no duplicate session row, clean initial terminal state, typed disconnect and successful recovery. Count daemon-side creations to catch invisible duplicates, not only visible rows. Drop the reply after a create to prove uncertain mutations are not retried. Use setup budgets separate from asserted disconnect deadlines; retain harness logs with secrets redacted.
Existing source tests to retain include remote_mirror::tests::every_stream_reconnect_re_reads_the_session_list, a_stream_that_stops_speaking_is_retired_rather_than_awaited_forever, and the remote-lifetime counter tests. They protect unchanged consumers; they do not prove a relay implementation exists.
CanvasTerminal Feature Audit
Last updated: 2026-09-21 Branch: refactor/solid-architecture
CanvasTerminal renders desktop and full-terminal browser sessions. The dedicated phone session screen instead uses SessionDetailScreen → OutputView: HTTP/WS log lines append to DOM history while screen frames replace its live region. Its durable log must continue advancing after the grid history cap. xterm.js has been fully removed. The renderer is powered by alacritty_terminal (Rust) sending binary grid frames over a Tauri Channel (desktop) or WebSocket (browser/PWA).
Remote grid streams report handshake, initial-replay timeout (15 seconds), decode and unexpected-close failures through the WS-only onStreamError callback (never a Tauri PTY listener). CanvasTerminal displays a persistent error toast. Reconnect health resets only after the renderer receives a frame or the server explicitly finishes an empty replay, not at socket open; intentional teardown cancels replay and reconnect timers. No silence deadline applies after initial replay. Replay timeouts detach the socket and schedule recovery directly, even when its close handshake never completes. The recorded idle remote replay regression asserts visible viewport text after reconnect without new PTY output. The backend WS attach regression separately verifies existing scrollback text at both the live viewport and a history offset without publishing a new frame (story 1421-733e); these prove recovery and replay, not attribution of the historical blank pane.
Answers-only history includes a retained prompt-less prefix before the first tracked prompt. Finished prefix and prompt turns share the history-base cache, with prompt association included in its validity check. The panel shows a status notice when no turn has a marked answer.
Submitted prompts are not tinted in the terminal grid. Recorded userPromptLines still drive scrollbar ticks and answers-only turn grouping; Chat user messages retain the theme prompt tint and gutter.
Adjacent 💬 answer paragraphs share one continuous tint and left bar, including blank rows between them. An unmarked prose paragraph after a blank row ends the answer; an uninterrupted indented continuation stays inside. The CLI gutter joins separate marked answer sections across internal blank rows and indented section headings when a later marked answer closes the gap. Trailing unmarked prose, unmarked list siblings, tools, prompts and status rows stay outside that gutter; extracted Answers and Chat keep their semantic paragraph boundaries. Lists, tables, quotations and fenced code remain attached to the answer. A non-answer output row or prompt ends the region. The CLI blanks only the marker glyph cells; selection and search retain their grid coordinates. Clipboard copy removes answer-prefix markers through the same helper used by AI Chat answer buttons (including mobile) and selectable Answers text. Inline emoji and fenced examples stay literal. Chat uses the same answer extent and strips every paragraph marker. User prompt echoes do not open answer regions: indented quoted markers stay in the prompt until an agent output bullet or an unindented answer marker begins output.
Link underlines use the same active viewport offset as selection and search before marker-row and marker-column projection. Backend-frame link rows (including each wrapped hover span) move with cached smooth-scroll text and are clipped when their text leaves the viewport. No additional scroll listener owns link decoration movement. Full-frame damage retains verified wrapped-link identities; installed row text and link boundaries invalidate changed identities synchronously. Asynchronous verification publishes its replacement atomically, and single-row file caches use candidate identities rather than unrelated row text.
Ctrl+Enter uses CSI u when Kitty flag 1 is active, or only for identified ego sessions that accept BusySteer without negotiation. Legacy input remains CR, avoiding shell command corruption. The mounted Enter-delivery regression asserts actual write_pty payloads, negotiated frame push/pop, current ego identity and shell-return behavior, and sibling Enter chords.
Incremental base-grid painting
Whole-row viewport movement in either direction can copy retained base-canvas pixels once. The smooth wheel gesture uses the same path: each frame paints from the row cache with the absolute viewport origin, so it repaints only the rows it exposes. The renderer compares all retained cells before reusing them and repaints changed or newly exposed rows. Geometry, font, theme, explicit invalidation and hidden marker layouts disable the copy. Full wire frames replace decoded state without forcing a full canvas clear. Overlay painting remains independent. Workload recordings include the optional absolute viewport origin for the same replay path; older recordings remain readable without scroll reuse.
Dirty rows are compared as cells, including colors, attributes and combining content. Unchanged rows do not paint. In-place changes repaint a clipped column span with neighboring glyphs for wide-cell and italic overlap. Changed row widths, marker ownership and combining sequences keep the whole-row fallback. Adjacent cells with the same resolved explicit background share one fill operation; default background gaps and resolved color changes split the runs.
Architecture
Terminal.tsx (outer shell)
+-- Session lifecycle (create/resume/reconnect PTY)
+-- Parsed event handling (status-line, question, progress, etc.)
+-- Activity tracking, notifications, auto-retry
+-- OSC 0/2 title change handling
+-- Resume/reconnect banners (JSX)
+-- ComposePanel
+-- TerminalSearch
+-- TerminalRef registration with terminalsStore
|
+-- CanvasTerminal (sole renderer)
+-- subscribe_terminal_grid (binary frame push from Rust via Channel/WS)
+-- Base canvas: text cells, backgrounds, block/box-drawing chars
+-- Overlay canvas (pointer-events:none): cursor, selection, search highlights, gutter markers
+-- Custom scrollbar (drag + track click)
+-- Suggest/intent overlay (DOM divs over canvas)
+-- Link detection (hover: file paths, web URLs, OSC 8)
+-- Keyboard input (VT100 + Kitty protocol)
+-- Touch input (tap/swipe/pinch for mobile/tablet via shared input)
+-- IntersectionObserver flow control (skip paint when hidden)
+-- Plugin watcher lines from Rust (pluginRegistry.handleWatcherLines)
+-- OSC 7 CWD + OSC 133 shell integration
+-- Imperative controllers (no reactive frame-path state)
+-- selection + search
+-- cancellable link verification + caches
+-- smooth-scroll position + styled-row cache
+-- keyboard/IME/mouse listener lifecycle
Frame decode, row reconciliation, scheduling, and paint remain colocated in
CanvasTerminal. The extracted controllers own independent state and cleanup;
they do not add Solid signals, effects, or store writes to the render hot path.
Key insight: Terminal.tsx handles parsed events, session lifecycle, banners, and compose panel. CanvasTerminal is purely a renderer + input handler with no session logic.
Binary Frame Format
Each frame: 26-byte header + variable row data. The header ends with a historyBase: u32 (lines evicted from the history top so far); historyBase + (historySize - displayOffset + screenRow) is the eviction-stable absolute index the smooth-scroll row cache keys by, so a cached row never aliases onto a different line after the scrollback cap rotates. keyboard_flags bits 0–4 remain the public keyboard-mode mask; bit 5 carries the active primary/alternate-screen identity and is removed before exposing keyboardFlags to input code. Per cell: 4 bytes codepoint + 3 bytes fg RGB + 3 bytes bg RGB + 1 byte attrs bitmask = 11 bytes. Decoded in decodeBinaryFrame using struct-of-arrays (SoA) typed arrays — zero per-cell object allocation.
Primary and alternate grids can reuse identical numeric row coordinates while representing unrelated content. A bit-5 transition therefore starts a new renderer generation: smooth-scroll animation, delayed row fetches, selection, search, link verification, reconciliation, and absolute-row caches are invalidated as one transaction. Partial transition frames wait for a full replacement instead of merging into the previous grid.
Cell text extension (TCX1)
Live frames (including full resynchronization) and styled-row payloads retain their existing headers, row records and 11-byte cell core. When at least one transmitted cell has zero-width scalars, an optional trailer follows all row records. Every integer is little-endian:
| Field | Type | Meaning |
|---|---|---|
| Magic | 4 bytes | ASCII TCX1 |
| Entry count | u32 | Number of sparse cell extensions |
| Row ordinal | u16 | Zero-based ordinal in this payload’s row records |
| Column | u16 | Absolute grid column, including for a partial row |
| Scalar count | u8 | 1–9 retained zero-width scalars |
| Scalars | u32[count] | Unicode scalar values in stored order |
The last four fields repeat per entry. No trailer means no extensions. New clients accept legacy payloads; legacy clients stop after the declared rows and ignore the trailer. The same serializer serves IPC and WebSocket delivery. Entries must name distinct cells inside their transmitted row spans and contain valid Unicode scalars (no surrogates or values above U+10FFFF). Truncated records, empty trailers, invalid bounds/counts, duplicate entries and trailing bytes are rejected and trigger full-frame recovery.
Decoded rows retain sparse cell strings and cached UTF-16 cell boundaries. Partial updates clear prior extensions inside the transmitted span before installing new ones, so overwriting an accented cell cannot leave a stale mark. Complete cell strings feed painting, block-cursor repaint, selection/copy and link offsets. For offsets returned with backend row/logical text, the renderer omits wire-zero wide spacers, validates the reconstructed text against the backend string and declines a mapping on mismatch. Native blank cells contain a space; PTY NUL controls do not become printed cells. Marked box/block glyphs use font shaping rather than geometric painting, preserving their marks and variation selectors. Terminal search geometry remains in grid cells; buffer-search string ranges use UTF-16 offsets. Ranges cover whole matching cells: a regex matching only a combining mark still reports its base cell’s full text span, since native search points have no subcell index.
Performance Notes
-
Selection row identity: Endpoints use
historyBase + historySize - displayOffset + viewportRow, the same eviction-stable identity as the styled row cache. Search and command-block coordinates keep their separate grid-relative contract. Copy converts endpoints back to grid-relative rows and includes the displayedhistoryBase; Rust rebases them under the grid lock, rejecting evicted endpoints. Reflow and primary/alternate transitions invalidate selection. -
Selection revalidation: Every new gesture discards the previous copied text snapshot. Full-frame content comparison applies only to released, fully visible selections; a range still being dragged is expected to change.
-
Coherent frame replacement: A changed viewport origin cannot borrow untouched columns from the previous viewport. A screenful of partial spans is still a delta, not an authoritative replacement. While requesting a full replacement, text and selection painting retain the same accepted viewport instead of clearing the row map and exposing missing rows to mouse-driven repaints. History growth that leaves the stable viewport origin unchanged does not itself invalidate that row map.
-
RAF coalescing: All paint triggers (frame arrival, keydown selection clear, mousedown) go through
scheduleRepaint()which schedules a singlerequestAnimationFrame. No synchronous paint calls — prevents double-paint in a single event loop turn. -
send_grid_frameclone guard: Frame is only cloned for thegrid_watchchannel whenreceiver_count() > 0(i.e. WS clients connected). Desktop-only path (Tauri Channel) is zero-copy. -
Raw bytes over the IPC: the channel carries
tauri::ipc::Response, notVec<u8>. A bareVec<u8>matches Tauri’s blanketIpcResponseimpl and is serialised as a JSON array of decimal numbers — a 110 KB frame becomes a ~250 KB string plus an extra IPC round trip, and JS receives anumber[]to walk instead of anArrayBuffer. Same forterminal_styled_rows.toBinaryPayloadstill acceptsnumber[], because Tauri’s postMessage fallback (custom-protocol IPC blocked) delivers that shape. -
Frame acks are counters, not a flag: the frontend echoes its total receipt count, so an ack for a frame the ticker already abandoned is a number in the past and cannot release a burst. See
tuic-terminal/src/grid_gate.rsfor pure ordering andsrc-tauri/src/grid_watch.rsfor the Tokio adapter. -
Receipts are not damage: desktop ACKs only release the gate. Paused ticks retain actual damage, and a missed-frame recovery sends its private full frame only to desktop and its delta only to browsers, without offering the same snapshot to desktop twice; normal output batching and input quotas are unchanged.
-
Retained input retry: newer reader damage that arrives during a send keeps its retry on the existing ticker. This does not add input credits, relax the 8 ms spacing or expiry, bypass desktop receipts, or change synchronized output.
-
Visibility batches:
IntersectionObservercan deliver multiple states for a terminal in one callback after resize/layout changes.latestIntersectionVisibilityselects the greatestentry.time(last entry wins ties), so a transient hidden sample cannot suppress later frames while the canvas is visible. Existing hidden-tab ACK throttling and the full-frame request on show remain unchanged. -
Hidden terminals: a background tab is
display:noneand never unmounted, so its producer keeps running. It decodes each frame (the bell rides in the header) and skips paint, links and cache fill, then acks on a 400 ms trailing timer — enough to keep the gate moving at ~2 frames/s without making the backend log a stuck frontend. Reconciliation (shouldFireReconcile) is off for it entirely: each fire would build and drop a full frame. -
Row cache bounds:
cacheRows()evicts FIFO atROW_CACHE_MAX, so the fill path is bounded too — trimming on scroll alone left an unbounded map for a session that only ever fetched forward. -
screen_text_rows_ref():TerminalGridexposes a borrowed&[String]view of cached screen rows. Used inprocess_chunkfor chrome cutoff detection to avoid cloning 50 Strings per PTY chunk. Downstream parsers (slash-menu, choice-prompt) share a single owned snapshot computed once per chunk. -
Plugin OutputWatcher matching moved to Rust: the reader thread assembles the lines, cleans them, and tests the compiled patterns (
tuic-terminal/src/output_watchers.rs). Rust is now the only line assembler — the per-sessionLineBuffers and the raw-output listener are gone, so the thread that paints the terminal no longer ANSI-strips and regex-tests every line. It is woken once per 100 ms window with the lines that matched. A pattern theregexcrate cannot express (lookaround, backreferences) is reported back as rejected and keeps matching in the WebView, which then receives every assembled line. -
No per-chunk parser logs: Slash-menu detection can remain active during a large output burst, so its hot path emits events only when a menu is found and never writes a debug record for every parse.
-
Trim in-place:
read_screen_text()androw_to_text()useString::truncate()instead of.trim_end().to_string(), eliminating one allocation per row.
Feature Table
Rendering
| Feature | Status | Notes |
|---|---|---|
| Cell rendering (text + colors) | OK | fillText per cell, SoA typed arrays |
| Bold / italic / dim / underline / strikeout | OK | |
| Inverse video | OK | resolveFg/resolveBg swap |
| Block elements (U+2580-259F) | OK | drawBlockChar() draws as geometry |
| Box-drawing (U+2500-257F) | OK | drawBoxDrawingChar() draws as geometry |
| Ligatures | OK | Adjacent cells with matching attrs grouped into text runs |
| Cursor shapes (block/beam/underline) | OK | computeCursorRect() |
| Cursor blink | OK | 700ms interval, reset on keypress |
| Unfocused cursor (outline) | OK | strokeRect |
| Overlay canvas (cursor+selection+search) | OK | Separate canvas cleared+redrawn every frame; base canvas only repaints dirty rows |
| DPI/Retina scaling | OK | dpr * logical sizing + ctx.scale() |
| DPR change listener | OK | matchMedia(resolution) re-register on change |
| Theme colors (ANSI 16) | OK | Colors come from Rust/Alacritty in frame data. In light themes, an explicit neutral SGR background with default foreground and contrast below 4.5:1 maps to --bg-tertiary. Explicit foreground pairs, colored backgrounds, inverse cells, and dark themes keep their wire colors. |
| Default fg/bg from terminal theme | OK | getTerminalTheme(settingsStore.state.theme) |
| Scrollbar themed | OK | Uses var(--fg-primary) CSS custom property with configurable opacity |
Zoom / Font
| Feature | Status | Notes |
|---|---|---|
| Per-terminal fontSize | OK | Reads terminalsStore[terminalId].fontSize |
| Global defaultFontSize | OK | Fallback when per-terminal not set |
| Font family reactive | OK | createEffect watches settingsStore.state.font |
| Font weight reactive | OK | |
| Line height (snapped) | OK | snapLineHeight() |
| Zoom Cmd+/- | OK | Via terminalsStore.setFontSize |
| Font preload | OK | document.fonts.load() targeting configured terminal font |
Scroll
| Feature | Status | Notes |
|---|---|---|
| Mouse wheel scroll | OK | Scrollback: fractional smooth scroll (wheelDeltaToPixels → handleScrollDelta → applySmoothScroll, acceleration capped at 2x via gestureAccelFactor), flushed through coalesced terminal_scroll_to_anchor. App-forwarded: whole-notch quantization (quantizeWheelNotches in canvasTerminalWheel.ts) written via write_pty as SGR notches |
| Scrollbar visibility | OK | Shows when historySize > 0 |
| Scrollbar thumb drag | OK | Custom implementation |
| Scrollbar track click-to-position | OK | |
| Arrow Down snap-to-bottom | OK | When displayOffset > 0 |
| Page Up/Down | OK | Via Terminal.tsx refMethods using terminal_scroll_info IPC |
| scrollToTop | OK | Via Terminal.tsx refMethods |
| scrollToBottom | OK | Via Terminal.tsx refMethods |
| scrollToLine (absolute) | OK | terminal_scroll_to IPC |
| Viewport lock (ESC[3J suppression) | N/A | Wontfix — no equivalent needed in canvas path |
Resize
| Feature | Status | Notes |
|---|---|---|
| ResizeObserver | OK | Installed only after onMount awaits the session subscriptions and the font load, so it cannot be the sole re-measure path |
| Debounce (100ms) | OK | clearTimeout + setTimeout(remeasure, 100) |
| Minimum size guard | OK | Guards both resize_pty IPC and measureNow() |
| Unsized pane | OK | measureNow() reports it measured nothing; remeasure() then waits for the first real box (retryUntilMeasured, bounded at SIZE_RETRY_MAX_FRAMES). A page reload mounts every terminal before layout, and dropping that measurement left the canvas in a corner of the pane |
| resize_pty IPC | OK |
Input / Keyboard
| Feature | Status | Notes |
|---|---|---|
| VT100 escape sequences | OK | keyToSequence() in terminalInput.ts |
| Kitty keyboard protocol (flag 1) | OK | kittySequenceForKey() |
| Shift+Enter (ESC CR) | OK | |
| Shift+Tab (CSI Z) | OK | |
| macOS Ctrl+letter (emacs) | OK | Uses e.code for reliability |
| macOS Left Option as Meta | OK | altSequenceFromCode() |
| Windows Ctrl+V paste | OK | |
| Cmd+Enter passthrough | OK | |
| IME composition | OK | compositionstart/compositionend; hidden input positioned at cursor coords via syncImePosition() for East Asian IME candidate windows |
| Bracketed paste | OK | \x1b[200~...\x1b[201~ |
| MCP atomic agent submission | OK | Backend-only session action=submit; the shared PTY writer lock spans payload, raw-mode gap, and Enter, so CanvasTerminal input cannot splice the submitted command. No renderer state or new frontend transport exists. |
| Image paste detection | OK | Shared isImagePaste() precedence: substantive text/plain wins over incidental images; screenshot-only and Finder image filename pastes send Ctrl+V |
| Resume banner keyboard | OK | Space/Enter/Escape/printable |
| Touch tap/swipe/pinch (mobile) | OK | installTouchHandlers focuses the shared keyboard input; primary compatibility mouse presses cancel the browser default canvas focus action; native keyboard animation still needs iPad verification |
Selection & Clipboard
| Feature | Status | Notes |
|---|---|---|
| Mouse drag selection | OK | |
| Double-click word select | OK | terminal_select_start with word:true |
| Triple-click line select | OK | |
| Cmd+C copy with selection | OK | terminal_get_selection_text IPC/HTTP parity path |
| Selection normalization | OK | Rust unwraps soft-wrapped rows, trims row padding, removes coherent Claude space/NBSP ▎ gutters, and strips one composer ❯ plus its continuation margin with conservative width reflow only when selected from grid column zero outside a VT soft-wrap continuation |
| Copy-on-select | OK | copySelection() called from onMouseUp |
| getSelection() ref method | OK | Returns the cached backend selection; getLocalSelectionText() is the transient fallback |
Focus
| Feature | Status | Notes |
|---|---|---|
| focus() ref method | OK | canvasTerminalRef?.focus() |
| Auto-focus on tab activation | OK | Visibility effect in Terminal.tsx |
| onFocus callback prop | OK | Wired in CanvasTerminalProps |
| Focus/blur cursor visual | OK | |
| focus() ref race | OK | Resolved via deferred ref registration |
Links
| Feature | Status | Notes |
|---|---|---|
| File path detection (hover) | OK | Async row text fetch + regex |
| File path Cmd+click open | OK | |
| Pointer cursor on link | OK | |
| Web URL links (http/https) | OK | webUrlRe regex in checkLinksAtRow |
| OSC 8 hyperlinks | OK | terminal_hyperlink_span IPC, priority over other link types |
Search
| Feature | Status | Notes |
|---|---|---|
| Cmd+F opens search bar | OK | |
| Escape closes search | OK | |
| Search results highlighting | OK | paintSearchHighlights on overlay canvas |
| Next/prev match navigation | OK | searchNext/searchPrev with wrap-around |
| searchBuffer() ref method | OK | terminal_search_buffer IPC |
| openSearch/closeSearch ref | OK |
Terminal Bell
| Feature | Status | Notes |
|---|---|---|
| Visual flash | OK | frame.bell → bell-flash CSS class (150ms) |
| Audio bell | OK | notificationsStore.play("info") via Terminal.tsx |
OSC Handlers
| Feature | Status | Notes |
|---|---|---|
| OSC 0/2 and structured intent title change | OK | Handled in Terminal.tsx wrapper; spawn labels remain replaceable, explicit user renames are protected |
| OSC 7 cwd tracking | OK | pty-cwd-{sessionId} on desktop, {"type":"cwd","cwd":…} on the grid WS. Both carry the same { cwd } object, so the handler needs no per-transport branch. |
| OSC 133 command blocks | OK | pty-osc133-{sessionId} on desktop, {"type":"osc133",…} on the grid WS — both serialised from Osc133Event, so the payload is { marker, line, exit_code } on either transport. Subscribed only here, and subscribed before the canvas waits for its fonts — that await used to sit between mount and subscription, which is the window the first prompt marker of a session falls in. Nothing replays either event, so a marker emitted before the terminal mounts at all is still lost; the fix closes the font window, not the whole race. handleOsc133 is not idempotent for the A marker, so a second listener invents one empty command block per prompt. |
| OSC 133 gutter decoration | OK | paintGutterMarkers on overlay canvas |
| User-prompt scrollbar markers | OK | Green ticks at userPromptLines — distinct from command-block marks, drawn in paintGutterMarkers |
| Cmd+Up/Down block navigation | OK | Reads commandBlocks + activeBlock |
| OSC 9 progress bar | OK | terminal()?.progress → 2px green bottom-edge fill on tab |
TerminalRef Methods
| Method | Status | Notes |
|---|---|---|
fit() | OK | Delegates to refresh() (full redraw via ResizeObserver) |
write(data) | OK | pty.write(sessionId, data) |
writeln(data) | OK | pty.write(sessionId, data + "\n") |
input(data) | OK | pty.write(sessionId, data) |
clear() | OK | Sends \x1b[2J\x1b[H\x1b[3J via pty.write |
refresh() | OK | Clears buffer + requests fresh frame |
focus() | OK | |
getSessionId() | OK | |
openSearch() | OK | |
closeSearch() | OK | |
toggleCompose() | OK | extractCurrentInput reads canvas row text |
openComposeWithText(text) | OK | |
searchBuffer(query) | OK | terminal_search_buffer IPC |
scrollToLine(lineIndex) | OK | terminal_scroll_to IPC |
getSelection() | OK | getLocalSelectionText() |
scrollToTop() | OK | |
scrollToBottom() | OK | |
scrollPages(pages) | OK | |
getBufferLines(start, end) | OK | terminal_get_lines IPC |
Other
| Feature | Status | Notes |
|---|---|---|
| File drag-and-drop (internal) | OK | application/x-tuic-path MIME from file tree |
| OS file drag-and-drop | OK | Finder/Explorer drag via tauri://drag event |
| Parsed events | OK | Handled by Terminal.tsx wrapper |
| Suggest overlay | OK | DOM divs over canvas |
| Intent row highlight | OK | |
| Notifications (sounds) | OK | Handled by Terminal.tsx wrapper |
| Flow control / backpressure | OK | IntersectionObserver: skip paint+ack when hidden |
| Plugin watcher lines | OK | pty-watcher-lines-{sessionId} (browser: watcher-lines WS frame) → pluginRegistry.handleWatcherLines. Rust assembled, cleaned and matched the lines on the reader thread; no raw stream is reassembled or scanned here. The listener is installed BEFORE the grid subscription — an event that lands while it is still being attached is gone, and nothing replays a watcher line |
Remaining Gaps
None. All tracked gaps have been resolved or marked wontfix.
Stored terminal marker coordinates
Stored command blocks and user prompt markers use all-time rows. Answers history consumes them directly. Gutter, scrollbar, search scope, navigation and buffer reads subtract the current frame history base at grid-relative boundaries. Evicted markers are omitted.
Terminal stream reconnect notices use the current terminal name when available and show the transport’s current attempt (up to 10). A received grid frame or confirmed empty replay removes only that stream notice; socket opening alone does not. Exhausted retries leave a persistent failure notice. Closing the terminal removes its notice, and late subscription failures cannot publish a notice after closure.
HTTP(S) link context menus include Start in Design Mode, passing the resolved URL and owning terminal session to the shared start command. File and other schemes retain Open and Copy link only.
History-anchored viewport scrolling
Wheel, touch and scrollbar gestures send terminal_scroll_to_anchor with historyBase + historySize - offset. Null resumes following output. The cache keeps rendering until the backend frame reaches the target; there is no timed settle handoff that can skip rows during sustained output.
Hidden agent marker rows
Mobile CLI uses the log transport rather than the canvas. Its serializer preserves intent spans in both history and screen snapshots. OutputView rejoins soft wraps before classification and applies the shared intent anchor and 12% warning tint to the whole paragraph.
The marker plan keeps intent text visible with a theme-aware warning tint, including column-zero ego rows and bullet-prefixed Claude/Codex rows. Intent continuation includes soft wraps and adjacent rows with at least two leading spaces (Codex/Ink cursor-move hard wraps). A blank row ends the walk. Complete suggest blocks are projected out of the displayed grid without changing stored backend coordinates. Paint and hit testing share the viewport projection. Copy classifies the same recorded rows and asks the backend for retained runs only, so omitted marker rows cannot leak through a selection spanning them. Backend selection reads still unwrap soft wraps and reject evicted rows. Off-screen selection classification reads styled rows with marker lookback. A blank row ends an indented marker tail. Unwrapped output, answer and prompt rows start separate blocks.
Answer-rule overlay geometry is invalidated on cell-height and projected-row changes, even when the answer markers are unchanged. This keeps font-load and theme remeasurements aligned with the grid.
Hidden desktop canvases retain their session event listeners but receive no grid frames. The intersection observer publishes epoch-scoped visibility in order; the desktop transport owns the show-frame request after publication, while the canvas owns it for WebSocket transports. Showing requests a full authoritative grid, including its display offset and history base. Bell callbacks use the backend session bell event rather than frame decoding. Browser grid sockets keep their independent stream.
Native terminal ego provider recovery is carried in the backend session snapshot, not inferred from canvas rows. Tab/status-bar presentation uses that snapshot; canvas rendering and input routing remain unchanged. Force retry uses the normal agent-aware command submission helper.
Soft-wrap text fidelity
Backend selection and logical-row extraction retain real spaces at soft-wrap margins. Mobile CLI log rendering uses serialized wrapped boundaries rather than word-length guesses when metadata is present. Older daemon rows without this field retain the existing prose reflow fallback. This changes extracted text, not canvas layout or styling.
Opt-in workload evidence
CanvasTerminal records raw arrivals before decode and immutable merged grid snapshots immediately before the base paint, plus visibility transitions. Capture requires both the explicit recorder flag and perfDebug. No render behavior changes. See stall evidence for caps, timing replay and limitations.
Prompt ownership after reflow (#1389-3a47)
Accepting changed frame geometry invalidates cached prompt boundaries and rejects ownership reads started with old coordinates, even if an interim old-frame paint refilled the cache after the resize request. Prefix reads classify each 256-row chunk once and retain one preceding row for blank separation and wrap semantics; they do not rescan the accumulated prefix.
Incremental projected painting (#2003-f218)
Hidden marker rows do not force a full canvas clear. Stable projections clear and paint only dirty display rows, using projected coordinates. A dirty hidden row does not clear the visible content that occupies its old backend coordinate. The renderer retains the backend owner and marker-span layout of each display slot. Projection changes invalidate only slots whose owner or marker span changed, including old bottom slots that must be cleared after rows move upward. Geometry, theme and other explicit full repaint requests still clear the canvas.
Viewport-bounded marker work (#2002-2239)
CLI painting classifies the visible rows, one bottom overscan row and at most
128 rows above the viewport. Unchanged row generations reuse the existing rowTextLayout text cache,
marker snapshots and the marker plan. Replaced rows invalidate their own text and the dependent plan;
a change to the preceding wrap flag invalidates the dependent snapshot too.
History outside this window is classified when scrolling reaches it. An answer
whose anchor is more than 128 rows above the viewport is not inferred from prose.
A tracked prompt can start much earlier. Its ownership prefix is limited to 128 rows synchronously and 128 rows per background read. Unresolved ownership stays fail-closed and resumes from the prior read boundary, including the preceding row to preserve blank separation. No background completion scans the accumulated prefix again, and intermediate chunks do not repaint the canvas. This bounds individual paint/read tasks, not the total work needed to resolve an arbitrarily long pasted prompt.
| Consumer | Trigger | Text work before this fix | Text work after this fix |
|---|---|---|---|
planViewportMarkers / planMarkers | Output frame, forced repaint | Viewport + 32 rows, but cold tracked prompt could synchronously walk retained history | Viewport + 128 rows; cold prefix at most 128; unchanged generations reuse text and plan |
renderCachedBase / planMarkers | Integer smooth-scroll paint | Same cold prompt exception | Same bounded planner; uncached history classified lazily |
readMarkerPromptBoundary / readTurnRows | Cold tracked prompt | One async operation fetched every prefix chunk | One operation reads at most 128 rows and retains its continuation position |
planSuggestOverlay, answerExtent, prompt echo and gutter gap walks | Called by marker plan | Caller range, except prompt prefix supplied by planner | Caller range is viewport + lookback; row dependencies cached |
gridRenderer / ViewportProjection | Paint and marker projection | Visible cells and marker sets, not history text classification | Unchanged; consumes bounded marker sets |
readAnswersHistory / buildAnswersTurn | Explicit Answers-only view; output refresh every 400 ms while open | Finished turns cached; running turn scanned in full, or last 5000 rows with no known prompts | Unchanged semantic full-history reader; not a canvas frame/scroll consumer |
The explicit Answers-only view still reads full retained turns to preserve its copy/selectable history contract. Its running-turn refresh is not viewport-bound; this change does not claim to fix that separate full-history consumer.
Font Size Audit
Date: 2026-05-11 Purpose: Harmonize font sizes across all panels, modals, and overlays.
Scale
| Variable | Size |
|---|---|
--font-2xs | 10px |
--font-xs | 11px |
--font-sm | 12px |
--font-md | 13px |
--font-base | 14px |
--font-lg | 15px |
--font-xl | 16px |
--font-2xl | 18px |
--font-3xl | 24px |
Current State
Panels
| Component | Title | Label | Content | Hint/Detail | Button |
|---|---|---|---|---|---|
| FileBrowser | — | sm | md | xs | — |
| References | — | — | sm | xs | — |
| Outline | — | — | sm | xs | — |
| TaskQueue | lg | sm | base | sm | sm |
| Sidebar | — | sm | md | xs | sm |
| AIChatPanel | — | sm | base | xs | sm |
Settings Panel
| Component | Title | Label | Content | Hint/Detail | Button |
|---|---|---|---|---|---|
| Settings shell | xl | base | base | sm | md |
| Settings nav | xs | lg | — | — | — |
| AgentsTab | — | base | sm | 2xs | sm |
| GitHubTab | lg | sm | sm | xs | sm |
| PluginsTab | — | base | sm | xs | sm |
| SmartPromptsTab | — | base | sm | 2xs | sm |
| DictationSettings | — | — | base | sm | md |
Overlays / Dialogs
| Component | Title | Label | Content | Hint/Detail | Button |
|---|---|---|---|---|---|
| CommandPalette | — | base | sm | xs | — |
| BranchSwitcher | — | base | base | sm | — |
| PromptOverlay | — | — | base | sm | — |
| ContextMenu | — | — | base | sm | — |
| ConfirmDialog | lg | — | — | — | md |
| CreateWorktree | — | sm | md | xs | sm |
Dominant Pattern
| Role | Panels | Settings (current) | Overlays/Dialogs |
|---|---|---|---|
| Title/heading | lg | xl (shell h2), lg (section h3) | lg |
| Label | sm | base (+2px) | base / sm |
| Content/input | sm–md | base (+1-2px) | base |
| Hint/detail | xs | sm (+1px) | sm / xs |
| Nav item | sm | lg (+3px) | — |
| Button (in-panel) | sm | md (+1px) | md (footer) |
| Toggle label | sm | base (+2px) | — |
Target (harmonized)
Settings should match the panel/overlay scale. Proposed target:
| Role | Target | CSS Variable |
|---|---|---|
| Modal title (h2) | lg | --font-lg |
| Section heading (h3) | md | --font-md |
| Nav item | md | --font-md |
| Form label / toggle label | sm | --font-sm |
| Content / input / select | sm | --font-sm |
| Hint / secondary text | xs | --font-xs |
| In-panel button | sm | --font-sm |
| Footer / dialog button | sm | --font-sm |
| Slider value | sm | --font-sm |
Hardcoded px values (off-scale)
| File | Value | Should be |
|---|---|---|
| McpPopup.module.css | 10px, 11px, 12px, 13px | 2xs, xs, sm, md |
| shared/dialog.module.css | 11px | xs |
| Sidebar.module.css (remoteBadge) | 9px | below scale — keep or raise to 2xs |
| OutlinePanel.module.css (kindBadge) | 10px | 2xs |
| AIChatPanel.module.css | 13px, 10px | md, 2xs |
Changes Required
Settings.module.css
| Selector | Current | Target |
|---|---|---|
.header h2 | xl | lg |
.navItem | lg | md |
.section h3 | lg | md |
.group label | base | sm |
.group select/input | base | sm |
.hint | sm | xs |
.hintInline | sm | xs |
.info | base | sm |
.warning | base | sm |
.toggle span | base | sm |
.slider span | base | sm |
.footerReset | md | sm |
.footerDone | md | sm |
.actions button | md | sm |
.saveBtn | md | sm |
.groupName | base | sm |
.groupNameInput | base | sm |
.input | base | sm |
.urlRow label | base | sm |
.urlFull | base | sm |
.mcpStatusText | base | sm |
.downloadBtn | base | sm |
.schedulerUnitSelect | base | sm |
.schedulerCronInput | base | sm |
.schedulerGoalInput | base | sm |
Tab-specific CSS
| File | Selector | Current | Target |
|---|---|---|---|
| PluginsTab.module.css | .pluginName | base | sm |
| AgentsTab.module.css | .agentName, .configName | base | sm |
| SmartPromptsTab.module.css | .promptName | base | sm |
| DictationSettings.module.css | various | base/md | sm |
Whole-backend heap profiling
heap-profile is an opt-in diagnostic Cargo feature. It selects the prefixed
tikv-jemallocator global Rust allocator in the shared backend library, so the
desktop, tuicommander-agent-test, and tuic-remote entry points use it. It does
not interpose C/Objective-C malloc. Default builds and Windows (including MSVC)
keep the system allocator. Do not adopt it for memory savings based on profiles.
Build and start
Use a linked worktree. Never replace or restart the daily application for a capture. On macOS run this isolated preset (choose an unused port and instance):
make agent-test AGENT_TEST_DRY_RUN=1 AGENT_TEST_INSTANCE=agent-test-heap AGENT_TEST_PORT=19879 AGENT_TEST_HEAP_PROFILE=1
_RJEM_MALLOC_CONF='abort_conf:true,prof:true,prof_active:false,lg_prof_sample:19' \
make agent-test AGENT_TEST_INSTANCE=agent-test-heap AGENT_TEST_PORT=19879 AGENT_TEST_HEAP_PROFILE=1
Run the long-lived launcher in the background. Stop that instance with
make agent-test-stop AGENT_TEST_INSTANCE=agent-test-heap. The launcher uses mbx
and the build slot. Ordinary diagnostic desktop builds add --features heap-profile
to pnpm tauri build; use the normal frontend embedding flow. For headless Linux,
install the platform’s libunwind development package, then use the build slot
with cargo build --manifest-path src-tauri/Cargo.toml --bin tuic-remote --no-default-features --features heap-profile.
The Cargo feature is also valid with desktop builds on Linux. It is unavailable
on other targets; the diagnostic endpoint reports an error there.
Profiling must be enabled at process start. With the prefixed allocator the
variable is _RJEM_MALLOC_CONF, not the system allocator’s configuration.
prof:true,prof_active:false initializes the profiler without sampling until
explicit activation. Existing allocations made while inactive cannot be recovered
later. For a complete startup baseline use prof_active:true in the isolated run.
lg_prof_sample:19 samples about every 512 KiB; profiles estimate live bytes,
not a census. Smaller intervals cost more CPU and memory. Leave
prof_thread_active_init:true (the default), so newly created threads participate.
Do not enable prof_gdump, prof_final, automatic intervals, debug, or validation.
The build forces upstream’s profiling_libunwind method, rather than the GCC
unwinder with its known multithreaded livelock. macOS provides unwind symbols in
libSystem; Linux requires libunwind. See the
upstream feature rationale.
No frame-pointer or global compiler overrides are needed. Verify actual stacks
on the platform before trusting a capture: unwinding support alone is not proof
that every Rust, native, or JIT frame resolves.
Control and capture
Use the isolated Unix socket from the dry run, or authenticated TCP on its port. The existing HTTP diagnostics control plane is shared by desktop and headless; there is no additional Tauri IPC command to drift from it.
curl --unix-socket "$socket" http://localhost/diagnostics/heap
curl --unix-socket "$socket" -H 'Content-Type: application/json' \
-d '{"action":"activate"}' http://localhost/diagnostics/heap
curl --unix-socket "$socket" -H 'Content-Type: application/json' \
-d '{"action":"dump","path":"/absolute/path/before.heap"}' http://localhost/diagnostics/heap
# Exercise throwaway repositories, searches, PTYs, logs and application state.
# Capture after.heap using the same endpoint, then deactivate.
curl --unix-socket "$socket" -H 'Content-Type: application/json' \
-d '{"action":"deactivate"}' http://localhost/diagnostics/heap
curl --unix-socket "$socket" http://localhost/diagnostics/memory
GET confirms compiled, enabled, active, new/current-thread sampling flags,
allocator debug assertions, sample interval, PID, executable,
and the process-start configuration. Unsupported builds, missing prof:true,
invalid filenames and failed writes produce HTTP 400 with an explicit error.
A dump is synchronous on a blocking worker; its response includes path, file size
and elapsed milliseconds. It does not stop sampling. Deactivation stops future
sampling, not retention of already sampled live allocations. Choose unique paths:
jemalloc may overwrite an existing dump. The server writes paths on its host.
Preserve symbols before rebuilding
Save the exact executable returned by GET, its SHA-256, source commit and
working-tree diff, Cargo.lock, toolchain versions, configuration and the raw
captures together in a private directory under ~/Gits/.tmp/heap-<date>/.
On macOS copy the executable, then run before any build or cache eviction:
(cd "$(realpath src-tauri/target)" && dsymutil /absolute/saved-executable -o /absolute/saved-executable.dSYM)
The development build’s unpacked DWARF refers to both relative and absolute mbx
object paths. Running from the repository root can produce a matching UUID yet
omit most symbols; --oso-prepend-path can break absolute paths. Require no missing
object warnings, verify matching UUIDs with dwarfdump --uuid, and resolve a real
allocation frame before trusting the dSYM. Keep it next to the saved executable.
On Linux preserve the unstripped ELF (or its exact separate debug file and build
ID). Release builds strip debug info by default: explicitly produce/preserve
symbols before stripping; an unrelated rebuild cannot symbolize an old capture.
jeprof --show_bytes --text saved-executable after.heap
jeprof --show_bytes --text --base=before.heap saved-executable after.heap
jeprof --show_bytes --lines --text saved-executable after.heap
Keep complete stack paths: inclusive rows overlap and must not be added together.
The sampled t* records in a heap_v2 dump are per-stack live object/byte counts;
jeprof corrects sampling bias using the interval in the header. On macOS verify
ASLR mappings and image load addresses; use atos -o saved-executable.dSYM/Contents/Resources/DWARF/<name> -l <load-address> <runtime-address>
for a raw frame. In the measured macOS run, automatic jeprof symbol labels
were missing or incorrect despite correct numeric totals. Relocate raw PCs using
the dump’s MAPPED_LIBRARIES load address; LLDB image lookup -v -a on the saved
binary plus complete dSYM resolves static PCs (runtime - load + Mach-O vmaddr).
Check addresses against the image range before resolving. A resolved Rust function and file:line is the minimum symbol
check. Keep unsymbolized frames visible as unknowns.
Interpret memory and overhead
GET /diagnostics/memory adds allocator to the existing report:
| Field | Meaning |
|---|---|
allocated_bytes | jemalloc’s current allocated bytes, including Rust allocations outside AppState |
active_bytes | pages backing those allocations; includes size-class/page slack |
resident_bytes | allocator metadata plus active/dirty pages; an allocator estimate, not OS footprint |
retained_bytes | unused virtual mappings retained for reuse; not live object bytes or physical footprint |
phys_footprint_bytes | macOS backend physical footprint including compressed memory; null elsewhere |
malloc_*, malloc_scope | native system malloc zone counters; default zone only for malloc_bytes_in_use, all enumerable zones for malloc_large_blocks |
These are overlapping views, not quantities to add. accounted_bytes describes
selected AppState holders and can overlap the Rust profile. Native system malloc
statistics cannot explain the prefixed Rust heap. Conversely jemalloc excludes
native malloc, mapped model files, stacks, executable pages, GPU allocations and
WebContent processes. Linux currently has no physical-footprint equivalent in
this endpoint: record /proc/<pid>/smaps_rollup separately and label RSS/PSS as such.
For a representative run, record backend footprint, associated WebContent PIDs and their separate footprint, native counters and allocator metrics before, during and after sampling. Record PIDs before launch and creation times, then verify associated processes disappear when your isolated instance stops. Shared resource coalitions and responsible PIDs can be inherited from the orchestrator: they are not sufficient ownership evidence. Keep ambiguous processes separate; a process-name match alone is insufficient. Do not sum RSS with footprint or add allocator counters to OS process totals. Never assign the user’s reported total to Rust without a matching capture.
Repeat the same throwaway workload with sampling off/on/off. Record elapsed work, dump latency/file size, metric changes, cleanup, and retained memory after cleanup. Keep the allocator and workload fixed; this measures profiler cost, not the system-versus-jemalloc adoption question. Asynchronous indexing and WebKit caches can survive the workload, so report run order and these limits. A separate matched whole-backend experiment is required before claiming reduced memory.
Profiles contain code addresses, binary/source paths and allocation/thread metadata; application logs and throwaway data can still contain sensitive information. Keep raw captures, executable, symbols and process snapshots local; share a redacted numeric/stack summary. Do not capture the daily instance or read its credentials.
Recorded application experiment
See the measured isolated run for source/symbol identity, retained allocation stacks, process split, overhead and unresolved attribution.