# 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](backend/workflows.md). 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](backend/workflow-script-interface.md). - **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](backend/workflow-trigger-admission.md). - **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](backend/workflow-http-connectors.md). - 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](frontend/prompt-input-keyboard-inventory.md). 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](user-guide/agent-teams.md#typed-reports-and-agent-stages). 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](backend/workflows.md). - **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](backend/workflows.md#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](../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](../CHANGELOG.md). **Current version:** 2.0.0\ **Last verified:** 2026-09-16 **Recent feature delta:** See the [Unreleased](https://github.com/sstraus/tuicommander/blob/main/CHANGELOG.md#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_checked` and 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](user-guide/terminals.md) | | Sidebar, repositories, and branches | [Sidebar](user-guide/sidebar.md) · [Branch Management](user-guide/branches.md) | | Git worktrees | [Worktrees](user-guide/worktrees.md) | | AI agents and agent teams | [AI Agents](user-guide/ai-agents.md) · [Agent Teams](user-guide/agent-teams.md) | | Visual element inspection | [Design Mode](user-guide/design-mode.md) | | GitHub, PRs, and CI | [GitHub Integration](user-guide/github-integration.md) | | Smart Prompts and Prompt Library | [Smart Prompts](user-guide/smart-prompts.md) · [Prompt Library](user-guide/prompt-library.md) | | Settings and shortcuts | [Settings](user-guide/settings.md) · [Keyboard Shortcuts](user-guide/keyboard-shortcuts.md) | | Plugins and MCP | [Plugins](user-guide/plugins.md) · [MCP Proxy Hub](user-guide/mcp-proxy.md) | | Remote, mobile, and browser modes | [TUICommander Modes](user-guide/modes.md) · [Remote Access](user-guide/remote-access.md) | | Setup and recovery | [Getting Started](user-guide/getting-started.md) · [Troubleshooting](user-guide/troubleshooting.md) | | Project history, mobile outcome-first list and full hand-off Flow | [Project Progress](user-guide/project-progress.md) | | Native plans and stories | [Native plans and stories](user-guide/native-stories.md) | 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=`; 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= url=` 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](user-guide/design-mode.md) 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=submit` call: 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=input` remains 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 parent `NO_COLOR` is 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_pty` Tauri 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 exact `active_sessions.json` registry 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 documented `ego export --format transcript --after` contract, 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+T` for 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+1` through `Cmd+9`, `Ctrl+Tab` / `Ctrl+Shift+Tab` - Hold `Cmd` alone (`Ctrl` on 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 `$HOME` shortened to `~`. The tab stores keep `filePath` relative 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) - **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 use `Cmd/Ctrl+T` for 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 editor - `file://` 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 (via `terminal_hyperlink_span` backend API) - Supports `:line` and `:line:col` suffixes; 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+F` opens 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 - `Escape` closes 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](backend/mcp-http.md). - Right-click a terminal tab → "Move to Worktree" submenu lists available worktrees (excluding the current one) - Selecting a worktree sends `cd` to the PTY; OSC 7 auto-reassigns the terminal to the target branch - Also available via Command Palette: dynamic "Move to worktree: \" 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 `cd`s 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_flags` Tauri 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 `onDragDropEvent` API (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`/`.mdx` files 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`/`drop` `preventDefault` prevents the Tauri webview from treating drops as browser navigation (which would replace the UI with a white screen) - macOS file association: `.md`/`.mdx` files 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). Set `bell_style` in `config.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+wheel` or 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=prompt` the submit-prompt hook emits; tool-call `state=busy` carries no row via `userPromptLines`). These are separate from command-block boundary marks and help you quickly locate your own prompts in long sessions - **Timestamp overlay** — Hold `Ctrl+Cmd` to 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 via `set_block_fold` Tauri command - **Block-scoped search** — Toggle with `Cmd+Shift+B` to restrict terminal search to the current block only - **Block navigation** — `Cmd+Shift+Up/Down` jumps 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; `Esc` returns 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+Enter` or `Shift+Enter` inserts 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. `Esc` and `Cmd+I` move 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; `Esc` closes 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** — `SIGCONT` targets 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; `0` disables) - **Not Suspend** — standby only `SIGSTOP`s the process group and keeps its memory; [Suspend Tab](#121a-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 a `zz` badge 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.json` in the config directory before ending the PTY. Records keyed by `tuic_session` retain cwd, worktree, alias, agent type, agent session id, launch command, pane slot and reason (`user`, reserved `idle_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=suspend` returns `{ok:true}` after Rust persists and ends the PTY, including when no UI is attached. Refusals return `Cannot suspend: `. - **Event** — `session-suspended` carries `{record}` over desktop events and SSE before the PTY closes. The IPC/HTTP `suspended_session_action` endpoint 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 `#number` plus its highest-priority state when applicable (Draft, Conflicts, CI, review, merged/closed), with state color — click for detail popover - Diff stats: `+N / -N` additions/deletions. Clicking the stats chip or the `N dirty` chip 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+Ctrl` held - 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) or `Ctrl+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 / total` count, 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 / total` count 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 `.md` and `.mdx` files 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:line` or `file:line:column` targets 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 `.md` files 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+F` search: 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 `.md` file 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 ` ```mermaid ` are 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+Enter` to 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 `.md` source as HTML-comment markers. Inline comments wrap their source text with `tweak:begin` / `tweak:end`; block comments use a `tweak:block` marker immediately before the target block, while list-item comments use a `tweak:item` marker 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 in `ContentRenderer`, whose consumers are the Markdown panel and the AI Chat transcript ### 3.4 File Browser Panel (`Cmd+E`) - **Bounded remote file API**: `/fs/read` can 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 `C` button 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_content` Tauri command; results delivered via `content-search-batch` events, each carrying the `search_id` of 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) or `Ctrl` (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+0` resets 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+Z` with 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+drag` for 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 a `tuic-remote` host; 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 · summary` annotation at the end of the active line, following the cursor over already-loaded blame data (fetched on load/save/repo-revision via `get_file_blame`, never per keystroke). Lines with uncommitted edits show `You · Uncommitted changes`. On by default (`inline_blame_enabled` config 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`, and `update_idea` through the `story` MCP tool, `tuic story`, IPC, or HTTP. Ideas keep their agent/session source and project scope in `notes.json`. Backend changes reload open panels through `ideas-changed`; stale panel saves merge by idea id and changed field, so they do not erase agent additions. - `Enter` submits idea, `Shift+Enter` inserts 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+V` pastes clipboard images as thumbnails attached to the note - Images saved to `config_dir()/note-images//` 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 - Edit preserves note identity (in-place update, no ID change) - `Escape` cancels 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-virtual` for 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_integrations` and `repo branch_integration` report 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 from `get_branches_detail` first; merged badges arrive from `get_merged_branches` when the classification is done - Click on sidebar "GIT" vertical label also opens Git Panel on the Branches tab **Keyboard navigation:** - `Escape` to close the panel - `Ctrl/Cmd+1–4` to 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, `Enter` to execute, `Esc` to 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_META` map) ### 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 read `Spawned by `, resolved from either the parent's PTY ID or live TUIC identity; an absent parent tab reads `Spawned 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 via `intent:` token - `lastPrompt` (speech bubble icon) — last user prompt (>= 10 words). Shown only when no `agentIntent` is 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_logs` Tauri 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-file` events from the output parser and via a `plans/` directory watcher - Auto-open: restores the active plan from `.claude/active-plan.json` on 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()` in `src/utils/filePreview.ts` - Supported formats: - **HTML** — rendered in sandboxed iframe with "Open in browser" button; `Cmd/Ctrl+F` find-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 `` via asset protocol - **Video** — MP4, WebM, OGG, MOV — rendered as `