TUICommander

Multi-agent terminal orchestrator

Run multiple AI coding agents in parallel across isolated Git worktrees. Observe, control, and merge AI development from a single terminal workspace.

Key Features

• Terminal Management — Tabbed terminals with split panes, drag-and-drop reordering, and per-branch isolation via Git worktrees
• AI Agent Support — Auto-detect Claude Code, Aider, Codex, Gemini CLI and more. Monitor progress, costs, and active subtasks in real time
• Git Worktrees — Each branch gets its own working directory. Create, merge, archive, and batch-manage worktrees from the UI
• GitHub Integration — PR badges, CI status rings, merge from the UI, post-merge cleanup, and notification bell for PR events
• Plugin System — Extend TUICommander with JavaScript plugins. Full API for terminals, git, notifications, and status bar widgets
• MCP Bridge — Expose app capabilities to AI agents via Model Context Protocol

Getting Started

Head to the Getting Started guide.

TUICommander — Complete Feature Reference

Canonical feature inventory. Update this file when adding, changing, or removing features. See AGENTS.md for the maintenance requirement.

Version: 1.0.5 | Last verified: 2026-04-15

1. Terminal Management

1.1 PTY Sessions

• 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)
• 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
• Pause/resume PTY output (pause_pty / resume_pty Tauri commands) — suspends reader thread without killing the session

1.2 Tab Bar

• Create: Cmd+T, + button (click = new tab, right-click = split options)
• 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
• Rename: double-click tab name (inline editing)
• Reorder: drag-and-drop with visual drop indicators
• 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 (on diff/editor/markdown file tabs)
• 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
• Tab pinning: pinned tabs are visible across all branches (not scoped to branch key)

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
• Up to 6 panes in same direction (N-way split)
• Split layout persists per branch

1.4 Zoom (Per-Terminal)

• 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
• Paste to terminal: Cmd+V
• Copy on Select — When enabled (Settings > Appearance), selecting text in the terminal automatically copies it to the clipboard. A brief ‘Copied to clipboard’ confirmation appears in the status bar.

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
• 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
• Supports :line and :line:col suffixes for precise navigation
• 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: incremental search via @xterm/addon-search with highlight decorations
• 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

• 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: <branch>” entries appear when the active terminal belongs to a repo with multiple worktrees
• Only shown when the repo has more than one worktree

1.11 OSC 7 CWD Tracking

• Terminals report their current working directory via OSC 7 escape sequences
• Parsed in the frontend via xterm.js registerOscHandler(7, ...), then sent to Rust via update_session_cwd IPC 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
• Enables accurate branch association even when the user cds into a different worktree from a single terminal

1.12 Kitty Keyboard Protocol

• Supports Kitty keyboard protocol flag 1 (disambiguate escape codes)
• Per-session flag tracking via get_kitty_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

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 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). Configure in Settings > Appearance.

2. Sidebar

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
• CI ring: proportional arc segments (green=passed, red=failed, yellow=pending)
• PR badge: colored by state (green=open, purple=merged, red=closed, gray=draft) — click for detail popover
• Diff stats: +N / -N additions/deletions
• Merged badge: branches merged into main show a “Merged” badge
• 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.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 (200-500px range)
• 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

2.7 Park Repos

• Right-click any repo in the sidebar to park or unpark it
• 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

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)

• Renders .md and .mdx files with syntax-highlighted code blocks
• 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
• Inline review comments (tweaks): select text in rendered markdown, add a comment — stored as HTML comment markers invisible to standard renderers but readable by humans and LLMs

3.4 File Browser Panel (Cmd+E)

• Directory tree of active repository
• Auto-refresh: directory watcher detects external file changes (create/delete/rename) and refreshes automatically within ~1s, preserving selection
• 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)
• View modes: flat list (default) and tree view — 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
• 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

3.5 Code Editor (CodeMirror 6)

• Opens in main tab area when clicking a file in file browser
• 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
• 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

3.6 Ideas Panel (Cmd+Alt+N)

• Quick notes / idea capture with send-to-terminal
• Enter submits idea, Shift+Enter inserts newline
• Per-idea actions: Edit (copies back to input), Send to Terminal (sends + return), Delete
• Mark as used: notes sent to terminal 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
• Image paste: Ctrl+V / Cmd+V pastes clipboard images as thumbnails attached to the note
  • Images saved to config_dir()/note-images/<note-id>/ on disk
  • Thumbnails displayed inline below note text and in the input area before submit
  • Image-only notes (no text) are supported
  • Images removed from disk when the note is deleted
  • Send to terminal appends absolute image paths so AI agents can read them
  • Max 10 MB per image; accepted formats: PNG, JPEG, WebP, GIF
• 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, docs)
• Keyboard shortcuts are now in Settings > Keyboard Shortcuts tab (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 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
• 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)
• Backend: get_branches_detail, delete_branch, create_branch, get_recent_branches
• 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
• 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
• Discoverable search commands: “Search Terminals”, “Search Files”, “Search in File Contents” appear as regular palette commands and pre-fill the corresponding prefix
• Powered by actionRegistry.ts (ACTION_META map)

3.12 Activity Dashboard (Cmd+Shift+A)

• Real-time view of all active terminal sessions in a compact list
• Each row shows: terminal name, project name badge (last segment of CWD), agent type, status, last activity time
• 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
• Rate limit indicators with countdown timers
• Click any row to switch to that terminal and close the dashboard
• 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
• 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 Panel (Cmd+Shift+P)

• Lists active plan files for the current repository from the activity store
• Plans are detected via structured plan-file events from the output parser and via plans/ directory watcher
• Click a plan to open it as a virtual markdown tab (frontmatter auto-stripped)
• Plan count badge in the header
• Repo-scoped: only shows plans belonging to the active repository
• Auto-open: restores the active plan from .claude/active-plan.json on startup; new plans opened as background tabs on first detection (no focus change)
• Directory watcher: monitors plans/ directory for new plan files created externally
• Mutually exclusive with Markdown, Diff, and File Browser panels
• Panel width and visibility persist across restarts via UIPrefsConfig

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
  • PDF — rendered via asset protocol in embedded iframe
  • Images — PNG, JPG/JPEG, GIF, WebP, SVG, AVIF, ICO, BMP — rendered as <img> via asset protocol
  • Video — MP4, WebM, OGG, MOV — rendered as <video> with native controls
  • Audio — MP3, WAV, FLAC, AAC, M4A — rendered as <audio> with native controls
  • Text / data — TXT, JSON, CSV, LOG, XML, YAML, TOML, INI, CFG, CONF — raw text in a <pre> block
• Header bar shows shortened file path with “Open in browser” / “Open externally” button
• File content auto-refreshes on repository revision bumps (git change detection)
• Uses Tauri’s convertFileSrc() asset protocol for binary files, read_external_file IPC for text content
• CSP allows asset: and http://asset.localhost in frame-src and media-src

3.16 Focus Mode (Cmd+Alt+Enter)

• Hides sidebar, tab bar, and all side panels to maximize the active tab’s content area
• Toolbar and status bar remain visible for repo/branch state and mode exit
• Session-only (not persisted across restarts)
• Toggle again to restore the previous layout

4. Toolbar

4.1 Sidebar Toggle

• ◧ button (left side) — same as Cmd+[
• Hotkey hint visible during quick switcher

4.2 Branch Display

• Center: shows repo / branch name
• Click to open branch rename dialog

4.3 Plan File Button

• Appears when an AI agent emits a plan file path (e.g., PLAN.md)
• Click: .md/.mdx files open in Markdown panel; others open in IDE
• Dismiss (×) button to hide without opening

4.4 Notification Bell

• Bell icon with count badge when notifications are available
• Click: opens popover listing all active notifications
• Empty state: shows “No notifications” when nothing is pending
• PR Updates section — types: Merged, Closed, Conflicts, CI Failed, CI Passed, Changes Requested, Ready
• Git section — background git operation results (push, pull, fetch) with success/failure status
• Worktrees section — worktree creation events (from MCP/agent)
• Plugin activity sections — registered by plugins via activityStore
• Click PR notification: opens full PR detail popover for that branch
• Individual dismiss (×) per notification, section “Dismiss All”, auto-dismiss after 5min focused time

4.5 IDE Launcher

• Button with current IDE icon — click to open repo/file in IDE
• Dropdown: shows all detected installed IDEs, grouped by category
• Categories: Code Editors, Terminals, Git Tools, System
• File-capable editors open the focused file (from editor or MD tab); others open the repo
• Run command button: Cmd+R (run), Cmd+Shift+R (edit & run)

5. Status Bar

5.1 Left Section

• Zoom indicator: current font size (shown when != default)
• Status info text (with pendulum ticker for overflow)
• CWD path: shortened with ~/, click to copy to clipboard (shows “Copied!” feedback)
• Unified agent badge with priority cascade:
  1. Rate limit warning (highest): count + countdown timer when sessions are rate-limited
  2. Claude Usage API ticker: live utilization from Anthropic API (click opens dashboard)
  3. PTY usage limit: weekly/session percentage from terminal output detection
  4. Agent name (lowest): icon + name of detected agent
  • Color coding: blue < 70%, yellow 70-89%, red pulsing >= 90%
  • Claude usage ticker absorbed into badge when active agent is Claude (avoids duplicate display)
• Shared ticker area: multi-source rotating messages from plugins with source labels, counter badge (1/3 ▸), click-to-cycle, right-click popover, and priority tiers (low/normal/urgent)
• Update badge: “Update vX.Y.Z” (click to download & install), progress percentage during download

5.2 GitHub Section (center)

• Branch badge: name + ahead/behind counts — click for branch popover
• PR badge: number + state color — click for PR detail popover
  • PR lifecycle filtering: CLOSED PRs hidden immediately; MERGED PRs hidden after 5 minutes of accumulated user activity
• CI badge: ring indicator — click for PR detail popover

5.3 Right Section — Panel Toggles

• Ideas (lightbulb icon) — Cmd+Alt+N
• File Browser (folder icon) — Cmd+E
• Markdown (MD icon) — Cmd+Shift+M
• Git (diff icon) — Cmd+Shift+D (opens Git Panel)
• Mic button (when dictation enabled): hold to record, release to transcribe

6. AI Agent Support

6.1 Supported Agents

6.1.1 Session-Aware Resume

When an agent is detected running in a terminal, TUICommander automatically discovers its session ID from the filesystem and stores it per-terminal (agentSessionId). On restore, this enables session-specific resume instead of generic fallback commands.

• Claude Code — Sessions stored as ~/.claude/projects/<slug>/<uuid>.jsonl; UUID from filename
• Gemini CLI — Sessions stored in ~/.gemini/tmp/<hash>/chats/session-*.json; sessionId field from JSON
• Codex CLI — Sessions stored in ~/.codex/sessions/YYYY/MM/DD/rollout-*-<UUID>.jsonl; UUID from filename

Discovery runs once per terminal on null→agent transition. Multiple concurrent agents are handled via a claimed_ids deduplication list. On agent exit, the stored session ID is cleared to allow re-discovery on next launch.

6.1.2 TUIC_SESSION Environment Variable

Every terminal tab has a stable UUID (tuicSession) injected as the TUIC_SESSION environment variable in the PTY shell. This UUID persists across app restarts and enables:

• Manual session binding: claude --session-id $TUIC_SESSION to start a session bound to this tab
• Automatic resume: On restore, TUICommander verifies if the session file exists on disk (verify_agent_session) before using --resume $TUIC_SESSION
• UI spawn coherence: When spawning agents via the context menu, TUIC_SESSION is used as --session-id automatically
• Custom scripts: $TUIC_SESSION is available as a stable key for any tab-specific state

6.2 Agent Detection

• Auto-detection from terminal output patterns
• Multi-agent status line detection via regex patterns anchored to line start: Claude Code (*/✢/· + task text + .../…), [Running] Task format, Aider (Knight Rider scanner ░█ + token reports), Codex CLI (•/◦ bullet spinner with time suffix), Copilot CLI (∴/●/○ indicators), Gemini CLI (braille dots ⠋⠙⠹...)
• Status lines rejected when they appear in diff output, code listings, or block comments
• Brand SVG logos for each agent (fallback to capital letter)
• Agent badge in status bar showing active agent
• Binary detection: Rust probes well-known directories via resolve_cli() for reliable PATH resolution in desktop-launched apps
• Foreground process detection: tcgetpgrp() on the PTY master fd, then proc_pidpath() to get the binary name. Handles versioned binary paths (e.g. Claude Code installs as ~/.local/share/claude/versions/2.1.87) by scanning parent directory names when the basename is not a known agent

6.3 Rate Limit Detection

• Provider-specific regex patterns detect rate limit messages
• Status bar warning with countdown timer
• Per-session tracking: rate-limit events are only accepted for sessions where agent activity has been detected (prevents false warnings in plain shell sessions)
• Auto-expire: rate limits are cleared automatically after retry_after_ms (or 120s default) without requiring agent output

6.4 Question Detection

• Recognizes interactive prompts (yes/no, multiple choice, numbered options)
• Tab dot turns orange (pulsing) when awaiting input; sidebar branch icon shows ? in orange
• Prompt overlay: keyboard navigation (↑/↓, Enter, number keys 1-9, Escape)
• Two detection strategies run in priority order:
  1. Screen-based (Strategy 1): reads the live terminal screen, finds the last chat line above the prompt box (delimited by separator lines), checks if it ends with ?. Works with Claude Code, Codex (› prompt), and Gemini (> prompt) layouts
  2. Silence-based (Strategy 2, fallback): if terminal output stops for 10s after a line ending with ?, the session is treated as awaiting input
• Stale candidate clearing: candidates that fail screen verification are purged so the same question can re-fire in a future agent cycle
• Echo suppression: user-typed input echoed by PTY is ignored for 500ms to prevent false question detection
• extract_question_line() scans all changed rows (not just the last) for question text, applied in both normal and headless reader threads
• Question state auto-clears when a status-line event fires (agent is actively working, so it’s no longer awaiting input)

6.5 Usage Limit Detection

• Claude Code weekly and session usage percentage (from PTY output patterns)
• Color-coded badge in status bar (blue < 70%, yellow 70-89%, red pulsing >= 90%)
• Integrated into unified agent badge (see section 5.1)

6.6 Claude Usage Dashboard

• Native SolidJS component (not a plugin panel — renders as a first-class tab)
• Opens via status bar agent badge click or Cmd+Shift+A action
• Rate Limits section: Live utilization bars from Anthropic OAuth usage API
  • 5-Hour, 7-Day, 7-Day Opus, 7-Day Sonnet, 7-Day Cowork buckets
  • Color-coded bars: green < 70%, yellow 70-89%, red >= 90%
  • Reset countdown per bucket
• Usage Over Time chart: SVG line chart of token usage over 7 days
  • Input tokens (blue) and output tokens (red) stacked area
  • Interactive hover crosshair with tooltip
• Insights: Session count, message totals, input/output tokens, cache stats, tokens-per-hour metric (based on real active hours from session timestamps)
• Activity heatmap: 52-week GitHub-style contribution grid
  • Tooltip shows date, message count, and top 3 projects
• Model Usage table: Per-model breakdown (messages, input, output, cache)
• Projects breakdown: Per-project token usage with click to filter
• Scope selector: Filter all analytics by project slug
• Auto-refresh: API data polled every 5 minutes
• Rust data layer: Incremental JSONL parsing of ~/.claude/projects/*/ transcripts
  • File-size-based cache (only new bytes parsed on each scan)
  • Cache persisted to disk as JSON for fast restarts

6.7 Intent Event Tracking

• Agents declare work phases via intent: text (Title) tokens at column 0, colorized dim yellow in terminal output
• Colorization is agent-gated (only applied in sessions with a detected agent) to prevent false positives
• Structural tokens stripped from log lines served to PWA/REST consumers via LogLine::strip_structural_tokens()
• Structured Intent events emitted for LLM-declared work phase tracking
• Centralized debounced busy signal with completion notifications for accurate idle/active status

6.8 API Error Detection

• Detects API errors (server errors, auth failures) from agent output and provider-level JSON error responses
• Covers Claude Code, Aider, Codex CLI, Gemini CLI, Copilot, and raw API error JSON from providers (OpenAI, Anthropic, Google, OpenRouter, MiniMax)
• Triggers error notification sound and logs to the Error Log Panel

6.9 Agent Configuration (Settings > Agents)

• Agent list: All supported agents with availability status and version detection
• Run configurations: Named command templates per agent (binary, args, env vars)
• Default config: One run config per agent marked as default for quick launching
• MCP bridge install: One-click install/remove of tui-mcp-bridge into agent’s native MCP config file
• Supported MCP agents: Claude, Cursor, Windsurf, VS Code, Zed, Amp, Gemini
• Edit agent config: Opens agent’s own configuration file in the user’s preferred IDE
• Context menu integration: Right-click terminal > Agents submenu with per-agent run configurations
• Busy detection: Agents submenu disabled when a process is already running in the active terminal
• Environment Flags — Per-agent environment variables injected into every new terminal session. Configure in Settings > Agents > expand an agent > Environment Flags. Useful for setting feature flags like CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 without manual export.

6.10 Agent Teams

• Purpose: Enables Claude Code’s Agent Teams feature to use TUIC tabs instead of tmux panes
• Approach: Environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 injected into PTY sessions, which unlocks Claude Code’s TeamCreate/TaskCreate/SendMessage tools. Agent spawning uses direct MCP tool calls (agent spawn) instead of the deprecated it2 shim
• Session lifecycle events: MCP-spawned sessions emit session-created and session-closed events so they automatically appear as tabs and clean up on exit
• Settings toggle: Settings > Agents > Agent Teams
• Suggest follow-ups: Agents can propose follow-up actions via suggest: A | B | C tokens, displayed as floating chip bar
• Deprecated: The it2 shim approach (iTerm2 CLI emulation) is commented out — superseded by direct MCP tool spawning

6.11 Suggest Follow-up Actions

• Protocol: Agents emit suggest: action1 | action2 | action3 at column 0 after completing a task
• Token concealment: Suggest tokens are concealed in terminal output via line erasure or space replacement — the raw token never appears on screen. Concealment is agent-gated
• Desktop: Floating chip bar (SuggestOverlay) above terminal with larger buttons and keyboard shortcut badges (1–9 to select, Esc to dismiss). Auto-dismiss after 30s, on typing, or on Esc
• Mobile: Horizontal scrollable pill buttons above CommandInput in SessionDetailScreen
• Action: Clicking a chip (or pressing its number key) sends the text to the PTY via write_pty
• Settings: Configurable via Settings > Agents > Show suggested follow-up actions

6.12 Slash Menu Detection

• When the user types / in a terminal, slash_mode activates and the output parser scans the bottom screen rows for slash command menus
• Detection: 2+ consecutive rows starting with /command patterns, with ❯ highlight for the selected item
• Produces ParsedEvent::SlashMenu { items } — used by mobile PWA to render a native bottom-sheet overlay
• slash_mode cleared on user-input events and status-line events

6.13 Inter-Agent Messaging

• New messaging MCP tool for agent-to-agent coordination when multiple agents are spawned in parallel
• Identity: Each agent uses its $TUIC_SESSION env var (stable tab UUID) as its messaging identity
• Actions: register (announce presence), list_peers (discover other agents), send (message a peer by tuic_session), inbox (poll for messages)
• Dual delivery: Real-time push via MCP notifications/claude/channel over SSE when the client supports channels; polling fallback via inbox always available
• Channel support: TUICommander declares experimental.claude/channel capability; spawned Claude Code agents automatically get --dangerously-load-development-channels server:tuicommander
• Lifecycle: Peer registrations cleaned up on MCP session delete and TTL reap; PeerRegistered/PeerUnregistered events broadcast via event bus for frontend visibility
• Limits: 64 KB max message size, 100 messages per inbox (FIFO eviction), optional project filtering for list_peers
• TUICommander acts as the messaging hub — no external daemon needed

6.14 AI Chat Panel (Cmd+Alt+A)

• Conversational AI companion docked on the right, streaming markdown with syntax-highlighted code blocks. Every code block has Run (sends to the attached terminal via sendCommand()), Copy, and Insert actions
• Multi-provider: Ollama (local, auto-detected on localhost:11434 with live model list), Anthropic, OpenAI, OpenRouter, custom OpenAI-compatible endpoint. Provider abstraction via genai crate
• Per-turn terminal context: last context_lines rows from VtLogBuffer (ANSI-stripped, alt-screen suppressed), SessionState, recent ParsedEvents, git branch/diff. Attach / detach / auto-attach terminal via header dropdown
• API keys stored in OS keyring (service tuicommander-ai-chat, user api-key) — masked with eye-toggle in Settings
• Streaming via Tauri Channel<ChatStreamEvent> (chunk/end/error); cancellable mid-stream
• Conversation persistence: save / load / delete with in-memory cap of 100 messages per conversation. Files at <config_dir>/ai-chat-conversations/<id>.json
• Terminal context menu: Send selection to AI Chat, Explain this error. Toolbar toggle + hotkey
• Full user guide: docs/user-guide/ai-chat.md

6.15 AI Agent Loop (ReAct)

• Autonomous loop that observes and acts in a terminal. Same panel as AI Chat, mode toggle in the header
• Six tools exposed to the model: read_screen, send_input, send_key, wait_for (regex or stability), get_state, get_context
• Safety gates via the SafetyChecker trait — three verdicts: Allow, NeedsApproval { reason }, Block { reason }. Destructive commands (rm -rf, git reset --hard, git push --force, DROP TABLE, dd of=, …) surface a pending-approval card; hard-coded blocks refuse patterns like rm -rf /
• Pause / resume / cancel between iterations with clean state transitions. Tool-call cards collapse/expand in the panel. Conversation schema v2 persists tool-call records alongside messages
• Session knowledge store (Level 3): command outcomes (exit code, duration, CWD, classification, output snippet), auto-correlated error→fix pairs, CWD history, tui_apps_seen, terminal mode. Injected into the agent system prompt as a compact markdown summary
• OSC 133 semantic prompts feed exact exit codes when the shell supports them; a silence-timer fallback records Inferred outcomes otherwise. Persisted to <config_dir>/ai-sessions/<session_id>.json with a 2 s debounced flush
• SessionKnowledgeBar — collapsible footer under the panel showing live command count, last 5 outcomes with kind badges, recent errors with inferred error_type, TUI mode indicator. A History button opens the knowledge history overlay (two-pane sessions/detail browser with full-text search, errors-only filter, and 24h/7d/30d date window)
• Experimental AI block enrichment (opt-in, Settings > AI Chat) — after each completed OSC 133 D block, a bounded mpsc worker asks the active AI provider for a one-line semantic_intent and stamps it onto the CommandOutcome (identified by stable id: u64). Rate-limited ~10/min, silent drop on full queue, never blocks the PTY path
• TUI app detection via alternate-screen tracking (ESC[?1049h/l). TerminalMode::FullscreenTui { app_hint, depth } is set when the terminal enters vim/htop/lazygit/less/tmux/…; the agent adapts (prefers send_key + wait_for over line-oriented send_input)
• External MCP surface — same six tools exposed as ai_terminal_read_screen, ai_terminal_send_input, ai_terminal_send_key, ai_terminal_wait_for, ai_terminal_get_state, ai_terminal_get_context. Input operations always require user confirmation and are rejected while the internal agent loop is active on the target session

6.16 ChoicePrompt Detection

• New ParsedEvent::ChoicePrompt { title, options, dismiss_key, amend_key } recognises Claude-Code-style numbered confirmation menus (footer matches Esc to cancel · Tab to amend)
• Options parsed by regex with optional cursor marker (❯, ›, >). Title heuristics require ? or a verb prefix (proceed, confirm, do you want, …) to avoid matching Markdown numbered lists. Minimum two options
• Destructive labels (no, cancel, reject, abort, deny, don't) flagged for styling
• Piped into SessionState.choice_prompt; dispatched to plugins via pluginRegistry.dispatchStructuredEvent("choice-prompt", …); rendered as PWA overlay
• Single-key replies routed through sendPtyKey() (src/utils/sendCommand.ts) — never text + \r. Desktop listener plays a warning sound when the prompt arrives on an inactive tab

7. Git Integration

7.1 Repository Info

• Branch name, remote URL, ahead/behind counts
• Read directly from .git/ files (no subprocess for basic info)
• Repo watcher: monitors .git/index, .git/refs/, .git/HEAD, .git/MERGE_HEAD for changes

7.2 Worktrees

• Auto-creation on branch select (non-main branches)
• Configurable storage strategies: sibling (__wt), app directory, inside-repo (.worktrees/), or Claude Code default (.claude/worktrees/)
• Sci-fi themed auto-generated names
• Three creation flows: dialog (with base ref dropdown), instant (auto-name), right-click branch (quick-clone with hybrid {branch}--{random} name)
• Base ref selection: choose which branch to start from when creating new worktrees
• Per-repo settings: storage strategy, prompt on create, delete branch on remove, auto-archive, orphan cleanup, PR merge strategy, after-merge behavior
• Setup script: runs once after creation (e.g., npm install)
• Archive script: runs before a worktree is archived or deleted; non-zero exit blocks the operation
• Merge & Archive: right-click → merge branch into main, then archive or delete based on setting
• External worktree detection: monitors .git/worktrees/ for changes from CLI or other tools
• Remove via sidebar × button or context menu (with confirmation)
• Worktree Manager panel (Cmd+Shift+W or Command Palette → “Worktree manager”):
  • Dedicated overlay listing all worktrees across all repos with metadata: branch name, repo badge, PR state (open/merged/closed), dirty stats, last commit timestamp
  • Orphan worktree detection with warning badge and Prune action
  • Repo filter pills and text search for branch names
  • Multi-select with checkboxes and select-all for batch operations
  • Batch delete and batch merge & archive
  • Single-row actions: Open Terminal, Merge & Archive, Delete (disabled on main worktrees)

7.3 Auto-Fetch

• Per-repo configurable interval (5/15/30/60 minutes, default: disabled)
• Background git fetch --all via non-interactive subprocess
• Bumps revision counter to refresh branch stats and ahead/behind counts
• Errors logged to appLogger, never blocking
• Master-tick architecture: single 1-minute timer checks all repos

7.4 Unified Repo Watcher

• Single watcher per repository monitoring the entire working tree recursively (replaces separate HEAD/index watchers)
• Uses raw notify::RecommendedWatcher with manual per-category trailing debounce
• Event categories: Git (HEAD, refs, index, MERGE_HEAD), WorkTree (source files), Config (app config changes)
• Each category has its own debounce window — git metadata changes propagate faster than file edits
• Respects .gitignore rules — ignored paths do not trigger refreshes
• Gitignore hot-reload: editing .gitignore rebuilds the ignore filter without restarting the watcher
• When a terminal runs git checkout -b new-branch in the main working directory (not a worktree), the sidebar renames the existing branch entry in-place (preserving all terminal state) instead of creating a duplicate

7.5 Diff

• Working tree diff and per-commit diff via Git Panel Changes tab
• Per-file diff counts (additions/deletions) shown inline in Changes tab
• Click a file row to view its diff
• Side-by-side (split), unified (inline), and scroll (all files) view modes — toggle in toolbar, preference persisted
• Scroll mode (all-files diff) — shows every changed file (staged + unstaged) in a continuous scrollable view with collapsible file sections, per-file addition/deletion stats, sticky header with totals, and clickable filenames that open in the editor. Reactively reloads on git operations via revision tracking
• Auto-unified for new/deleted files — split view is forced to unified when the diff is one-sided
• Word-level diff highlighting via @git-diff-view/solid with virtualized rendering
• Hunk-level restore — hover a hunk header to reveal a revert button (discard for working tree, unstage for staged)
• Line-level restore — click individual addition/deletion lines to select them (shift+click for ranges), then restore only the selected lines via partial patch
• Text selection and copy enabled in diff panels (user-select: text)
• Cmd+F search in diff tabs via SearchBar + DomSearchEngine
• Submodule entries are filtered from working tree status (not shown as regular files)
• Standalone DiffPanel removed in v0.9.0 (see section 3.2)

8. GitHub Integration

8.1 PR Monitoring

• GraphQL API (replaces gh CLI for data fetching)
• PR badge colors: green (open), purple (merged), red (closed), gray (draft)
• Merge state: Ready to merge, Checks failing, Has conflicts, Behind base, Blocked, Draft
• Review state: Approved, Changes requested, Review required
• PR lifecycle rules: CLOSED PRs hidden from sidebar and status bar; MERGED PRs shown for 5 minutes of accumulated user activity then hidden
• Auto-show PR popover filters out CLOSED and MERGED PRs (configurable in Settings > General)

8.2 CI Checks

• Ring indicator with proportional segments
• Individual check names and status in PR detail popover
• Labels with GitHub-matching colors

8.3 PR Detail Popover

• Title, number, link to GitHub
• Author, timestamps, state, merge readiness, review decision
• CI check details, labels, line changes, commit count
• View Diff button: opens PR diff as a dedicated panel tab with collapsible file sections, dual line numbers, and color-coded additions/deletions
• Merge button: visible when PR is open, approved, CI green — merges via GitHub API. Merge method auto-detected from repo-allowed methods; auto-fallback to squash on HTTP 405 rejection
• Approve button: submit an approving review via GitHub API (remote-only PRs)
• Post-merge cleanup dialog: after merge, offers checkable steps (switch to base, pull, delete local/remote branch)
• Review button: if the branch’s active agent has a run config named “review”, spawns a terminal running the interpolated command with {pr_number}, {branch}, {base_branch}, {repo}, {pr_url}. Hidden when no matching config exists
• Triggered from: sidebar PR badge, status bar PR badge, status bar CI badge, toolbar notification bell

8.4 CI Auto-Heal

• When CI checks fail on a branch with an active agent terminal, auto-heal can fetch failure logs and inject them into the agent
• Toggle per-branch via checkbox in PR detail popover (visible when CI checks are failing)
• Fetches logs via gh run view --log-failed, truncated to ~4000 chars
• Waits for agent to be idle/awaiting input before injecting
• Max 3 attempts per failure cycle, then stops and logs a warning
• Attempt counter visible in PR detail popover
• Status tracked per-branch in BranchState.ciAutoHeal

8.5 PR Notifications

• Types: Merged, Closed, Conflicts, CI Failed, Changes Requested, Ready
• Toolbar bell with count badge
• Individual dismiss or dismiss all
• Click to open PR detail popover

8.5 Merge PR via GitHub API

• Merge PRs directly from TUICommander without switching to GitHub web
• Configurable merge strategy per repo: merge commit, squash, or rebase (Settings > Repository > Worktree tab)
• Merge method auto-detected from repo’s allowed methods via GitHub API (get_repo_merge_methods); auto-fallback to squash on HTTP 405 rejection
• Triggered from: PR detail popover (local branches), remote-only PR popover, Merge & Archive workflow (sidebar context menu)
• Post-merge cleanup dialog: sequential steps executed via Rust backend (not PTY — terminal may be occupied by AI agent)
  • Switch to base branch (auto-stash if dirty — inline warning shown with “Unstash after switch” checkbox)
  • Pull base branch (ff-only)
  • Close terminals + delete local branch (safe delete, refuses default branch)
  • Delete remote branch (gracefully handles “already deleted”)
  • Steps are checkable — user can toggle which to execute
  • Per-step status reporting: pending → running → success/error
• After-merge behavior setting for worktrees: archive (auto-archive), delete (remove), ask (show dialog)
• When afterMerge=ask: unified cleanup dialog includes an archive/delete worktree step (with inline selector) alongside branch cleanup steps — replaces the old 3-button MergePostActionDialog

8.6 Auto-Delete Branch on PR Close

• Per-repo setting: Off (default) / Ask / Auto
• Triggered when GitHub polling detects PR merged or closed transition
• If branch has a linked worktree, removes worktree first then deletes branch
• Safety: never deletes default/main branch; dirty worktrees always escalate to ask mode
• Uses safe git branch -d (refuses unmerged branches)
• Deduplication prevents double-firing on the same PR

8.7 GitHub Issues Panel

• Issues displayed in a collapsible section within the GitHub panel alongside PRs
• Filter modes: Assigned (default), Created, Mentioned, All, Disabled
• Filter persisted in app config (issue_filter field) and configurable in Settings > GitHub
• Each issue shows: number, title, state (OPEN/CLOSED), author, labels, assignees, milestone, comment count, timestamps
• Labels rendered with GitHub-matching colors (background opacity 0.7, contrast-aware text color)
• Issue actions: Open in GitHub, Close/Reopen, Copy issue number
• Expand accordion to see full details (milestone, assignees, labels, timestamps)
• Skeleton loading rows shown during first fetch
• Empty state message when no issues match the filter
• MCP HTTP endpoint: GET /repo/issues?path=... returns issues JSON
• MCP HTTP endpoint: POST /repo/issues/close closes an issue

8.8 Polling

• Active window: every 30 seconds
• Hidden window: every 2 minutes
• API budget: ~2 calls/min/repo

8.9 Token Resolution

• Priority: GH_TOKEN env → GITHUB_TOKEN env → OAuth keyring token → gh_token crate → gh auth token CLI
• gh_token crate with empty-string bug workaround
• Fallback to gh auth token CLI

8.10 OAuth Device Flow Login

• One-click GitHub authentication from Settings > GitHub tab
• Uses GitHub OAuth App Device Flow (no client secret, works on desktop)
• Token stored in OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service)
• Requested scopes: repo, read:org
• Shows user avatar, login name, and token source after authentication
• Logout removes OAuth token, falls back to env/gh CLI
• On 401: auto-clears invalid OAuth token and prompts re-auth

9. Voice Dictation

9.1 Whisper Inference

• Local processing via whisper-rs (no cloud)
• macOS: GPU-accelerated via Metal
• Linux/Windows: CPU-only

9.2 Models

9.3 Push-to-Talk

• Default hotkey: F5 (configurable, registered globally)
• Mic button in status bar: hold to record, release to transcribe
• Transcribed text inserts into the focused input element (textarea, input, contenteditable); falls back to active terminal PTY when no text input has focus. Focus target captured at key-press time.

9.4 Streaming Transcription

• Real-time partial results during push-to-talk via adaptive sliding windows
• First partial within ~1.5s, subsequent windows grow to 3s for quality
• VAD energy gate skips silence windows (prevents hallucination)
• Floating toast shows partial text above status bar during recording
• 200ms audio window overlap (keep_ms) carries context across windows for continuity
• Final transcription pass on full captured audio at key release

9.5 Microphone Permission Detection (macOS)

• On first use, checks microphone permission via macOS TCC (Transparency, Consent, and Control) framework
• Permission states: NotDetermined (will prompt), Authorized, Denied, Restricted
• If denied, shows a dialog guiding the user to System Settings > Privacy & Security > Microphone with an “Open Settings” button
• Linux/Windows: always returns Authorized (no TCC framework)

9.6 Configuration

• Enable/disable, hotkey, language (auto-detect or explicit), model download
• Audio device selection
• Text correction dictionary (e.g., “new line” → \n)
• Auto-send — Enable in Settings > Services > Dictation to automatically submit (press Enter) after transcription completes.

10. Prompt Library

10.1 Access

• Cmd+K to open drawer
• Toolbar button

10.2 Prompts

• Create, edit, delete saved prompts
• Variable substitution: {{variable_name}}
• Built-in variables: {{diff}}, {{changed_files}}, {{repo_name}}, {{branch}}, {{cwd}}
• Custom variables prompt user for input
• Categories: Custom, Recent, Favorites
• Pin prompts to top
• Search by name or content

10.3 Keyboard Navigation

• ↑/↓: navigate, Enter: insert (restores terminal focus), Ctrl+N: new, Ctrl+E: edit, Ctrl+F: toggle favorite, Esc: close

10.4 Run Commands

• Cmd+R: run saved command for active branch
• Cmd+Shift+R: edit command before running
• Configure per-repo in Settings → Repository → Scripts

10.5 Smart Prompts

AI automation layer with 24 built-in context-aware prompts. Each prompt includes a description explaining what it does. Prompts auto-resolve git context variables and execute via inject (PTY write), shell script (direct run), headless (one-shot subprocess), or API (direct LLM call) mode.

• Open: Cmd+K or toolbar lightning bolt button
• Drawer with category filtering (All/Custom/Recent/Favorites), search by name/description, and enable/disable toggles
• Prompt rows show inline badges: execution mode (inject/shell/headless/api), built-in, placement tags
• Prompts are context-aware: 31 variables auto-resolved from git, GitHub, and terminal state
• Variable Input Dialog: unresolved variables show a compact form with variable name + description before execution
• Edit Prompt dialog: full editor with name, description, content textarea, variable insertion dropdown (grouped by Git/GitHub/Terminal with descriptions), placement checkboxes, execution mode + auto-execute side-by-side, keyboard shortcut capture
• Auto-execute: when enabled, inject-mode prompts send Enter immediately via agent-aware sendCommand; when disabled, text is pasted without Enter so the user can review before sending
• API execution mode: calls LLM providers directly via HTTP API (genai crate) without terminal or agent CLI. Per-prompt system prompt field. Output routed via the same outputTarget options (clipboard, commit-message, toast, panel). Tauri-only (PWA shows “requires desktop app”)
• LLM API config (Settings > Agents): global provider/model/API key for all API-mode prompts. Supports OpenAI, Anthropic, Gemini, OpenRouter, Ollama, and any OpenAI-compatible endpoint via custom base URL. API key stored in OS keyring. Test button validates connection

10.6 Built-in Prompts by Category

10.7 Context Variables

Variables are resolved from the Rust backend (resolve_context_variables) and frontend stores:

10.8 Execution Modes

• Inject (default): writes the resolved prompt text into the active terminal’s PTY. Checks agent idle state before sending (configurable via requiresIdle). Appends newline for auto-execution
• Shell script: executes the prompt content directly as a shell script via execute_shell_script Tauri command. No agent involved — runs content as-is via sh -c (macOS/Linux) or cmd /C (Windows) in the repo directory. Output routed via outputTarget. 60-second timeout cap. No prerequisites (no terminal, agent, or API config needed)
• Headless: runs a one-shot subprocess via execute_headless_prompt Tauri command. Requires a per-agent headless template configured in Settings → Agents (e.g. claude -p "{prompt}"). Output routed to clipboard or toast depending on outputTarget. Falls back to inject in PWA mode. 5-minute timeout cap

10.9 UI Integration Points

10.10 Smart Prompts Management (Cmd+Shift+K Drawer)

• All prompt management consolidated in the Cmd+Shift+K drawer (Settings tab removed)
• Enable/disable individual prompts via toggle button on each row
• Edit prompt: opens modal with name, description, content, variable dropdown, placement, execution mode, auto-execute, keyboard shortcut
• Variable insertion dropdown below content textarea: grouped by Git/GitHub/Terminal, click to insert {variable} at cursor
• Create custom smart prompts with + New Prompt button
• Built-in prompts show a “Reset to Default” button when content is overridden

10.11 Headless Template Configuration

• Settings → Agents → per-agent “Headless Command Template” field
• Template uses {prompt} placeholder for the resolved prompt text
• Example: claude -p "{prompt}", gemini -p "{prompt}"
• Required for headless execution mode; without it, headless prompts fall back to inject

11. Settings

11.1 General

• Language, Default IDE, Shell
• Confirmations: quit, close tab (only when a process is running — agents or busy shell; idle shells close immediately)
• Power management: prevent sleep when busy
• Updates: auto-check, check now
• Git integration: auto-show PR popover
• Experimental Features: master toggle + per-feature sub-flags (AI Chat)
• Repository defaults: base branch, file handling, setup/run scripts, worktree defaults (storage strategy, prompt on create, etc.)

11.2 Appearance

• Terminal theme: multiple themes, color swatches
• Terminal font: 11 bundled monospace fonts (JetBrains Mono default)
• Default font size: 8-32px slider
• Split tab mode: separate / unified
• Max tab name length: 10-60 slider
• Repository groups: create, rename, delete, color-coded
• Reset panel sizes: restore sidebar and panel widths to defaults

11.3 Services

• HTTP API server: always active on IPC listener (Unix domain socket on macOS/Linux, named pipe \\.\pipe\tuicommander-mcp on Windows). TCP port only for remote access
• MCP connection info: bridge sidecar auto-installs configs for supported agents (Claude Code, Cursor, etc.)
• TUIC native tool toggles: enable/disable individual MCP tools (session, agent, repo, ui, plugin_dev_guide, config, debug) to restrict what AI agents can access
• MCP Upstreams: add/edit/remove upstream MCP servers (HTTP or stdio with optional cwd), per-upstream enable/disable, reconnect, credential storage via OS keyring, live status dots, tool count and metrics. Saved upstreams auto-connect on boot
• MCP Per-Repo Scoping: each repo can define which upstream MCP servers are relevant via an allowlist in repo settings (3-layer: per-repo > .tuic.json > defaults). Null/empty allowlist = all servers. Quick toggle via Cmd+Shift+M popup
• Remote access: port, username, password (bcrypt hash), URL display, QR code, token duration, IPv6 dual-stack, LAN auth bypass
• Voice dictation: full setup (see section 9)

11.4 Repository Settings (per-repo)

• Display name
• Worktree tab: storage strategy, prompt on create, delete branch on remove, auto-archive, orphan cleanup, PR merge strategy, after-merge action (each overridable from global defaults)
• Scripts tab: setup script (post-worktree), run script (Cmd+R), archive script (pre-archive/delete hook)
• Repo-local config: .tuic.json in repo root provides team-shared settings. Three-tier precedence: .tuic.json > per-repo app settings > global defaults. Scripts (setup, run, archive) are intentionally excluded from .tuic.json merging — arbitrary script execution by a checked-in file poses a security risk; scripts are always sourced from the local per-repo app settings only

11.5 Notifications

• Master toggle, volume (0-100%)
• Per-event: question, error, completed, warning, info
• Test buttons per sound
• Reset to defaults

11.6 Keyboard Shortcuts

• Settings > Keyboard Shortcuts tab (Cmd+, to open Settings), also accessible from Help > Keyboard Shortcuts
• All app actions listed with their current keybinding
• Click the pencil icon to rebind — inline key recorder with pulsing accent border
• Conflict detection: warns when the new combo is already bound to another action, with option to replace
• Overridden shortcuts highlighted with accent color; per-shortcut reset icon to revert to default
• “Reset all to defaults” button at the bottom
• Custom bindings stored in keybindings.json in the platform config directory
• Auto-populated from actionRegistry.ts (ACTION_META map) — new actions appear automatically
• Global Hotkey: configurable OS-level shortcut to toggle window visibility from any application. Set in the “Global Hotkey” section at the top of the Keyboard Shortcuts tab. No default — user must configure. Toggle: hidden/minimized → show+focus, visible but unfocused → focus, focused → instant hide (no dock animation). Cmd and Ctrl are distinct modifiers. Uses tauri-plugin-global-shortcut (no Accessibility permission required on macOS). Hidden in browser/PWA mode.

11.7 Agents

• See 6.9 Agent Configuration for full details
• Claude Usage Dashboard enable/disable toggle (under Claude agent section)

12. Persistence

12.1 Rust Config Backend

All data persisted to platform config directory via Rust:

• app_config.json — general settings
• notification_config.json — sound settings
• ui_prefs.json — sidebar visibility/width
• repo_settings.json — per-repo worktree/script settings
• repositories.json — repository list, groups, branches
• agents.json — per-agent run configurations
• prompt_library.json — saved prompts
• notes.json — ideas panel data
• dictation_config.json — dictation settings
• .tuic.json — repo-root team config (read-only from app, highest precedence for overridable fields)
• claude-usage-cache.json — incremental session transcript parse cache

12.2 Hydration Safety

• save() blocks before hydrate() completes to prevent data loss

13. Cross-Platform

13.1 Supported Platforms

• macOS (primary), Windows, Linux

13.2 Platform Adaptations

• Cmd ↔ Ctrl key abstraction
• resolve_cli(): probes well-known directories when PATH unavailable (release builds)
• Windows: cmd.exe shell escaping, CreateToolhelp32Snapshot for process detection
• IDE detection: .app bundles (macOS), registry entries (Windows), PATH probing (Linux)

14. System Features

14.1 Auto-Update

• Check for updates on startup via tauri-plugin-updater
• Status bar badge with version
• Download progress percentage
• One-click install and relaunch
• Menu: Check for Updates (app menu and Help menu)

14.2 Sleep Prevention

• keepawake integration prevents system sleep while agents are working
• Configurable in Settings

14.3 Splash Screen

• Branded loading screen on app start

14.4 Confirmation Dialogs

• In-app ConfirmDialog component replaces native Tauri ask() dialogs
• Dark-themed to match the app (native macOS sheets render in light mode)
• useConfirmDialog hook provides a confirm() → Promise<boolean> API
• Pre-built helpers: confirmRemoveWorktree(), confirmCloseTerminal(), confirmRemoveRepo()
• Keyboard support: Enter to confirm, Escape to cancel

14.5 Error Handling

• ErrorBoundary crash screen with recovery UI
• WebGL canvas fallback (graceful degradation)
• Error classification with backoff calculation

14.6 MCP & HTTP Server

• REST API on localhost for external tool integration
• Exposes terminal sessions, git operations, agent spawning
• WebSocket streaming, Streamable HTTP transport
• Used by Claude Code, Cursor, and other tools via MCP protocol
• tuic-bridge ships as a Tauri sidecar; auto-installs MCP configs on first launch for Claude Code, Cursor, Windsurf, VS Code, Zed, Amp, Gemini
• Local connections use Unix domain socket (<config_dir>/mcp.sock) on macOS/Linux or named pipe (\\.\pipe\tuicommander-mcp) on Windows; TCP port reserved for remote access only
• Unix socket lifecycle is crash-safe: RAII guard removes the socket file on Drop; bind retries 3× (×100 ms) removing any stale file before each attempt; liveness check uses a real connect() probe so a dead socket from a crashed run never blocks MCP tool loading

14.7 Cross-Repo Knowledge Base

• Knowledge base functionality is available via the mdkb MCP upstream server (configure in MCP Upstreams settings)
• Provides hybrid BM25 + semantic search across docs, code, symbols, and memory
• Call graph queries (calls, callers, impact analysis) via code_graph tool
• Requires mdkb binary on PATH (installed separately)

14.8 macOS Dock Badge

• Badge count for attention-requiring notifications (questions, errors)

14.9 Tailscale HTTPS

• Auto-detects Tailscale daemon and FQDN via tailscale status --json (cross-platform)
• Provisions TLS certificates from Tailscale Local API (Unix socket on macOS/Linux, CLI on Windows)
• HTTP+HTTPS dual-protocol on same port via axum-server-dual-protocol
• Graceful fallback: HTTP-only when Tailscale unavailable or HTTPS not enabled
• QR code uses https:// scheme with Tailscale FQDN when TLS active
• Background cert renewal every 24h with hot-reload via RustlsConfig::reload_from_pem()
• Session cookie gets Secure flag on TLS connections
• Settings panel shows Tailscale status with actionable guidance

15. Keyboard Shortcut Reference

Terminal

Zoom

Split Panes

AI

Panels

Git

Branches Panel (when panel is focused)

File Browser (when focused)

Code Editor (when focused)

Ideas Panel (when textarea focused)

Quick Switcher

Voice Dictation

Mouse Actions

16. Build & Release

16.1 Makefile Targets

16.2 CI/CD

• GitHub Actions for cross-platform builds
• macOS code signing and notarization
• Linux: libasound2-dev dependency, -fPIC flags
• Updater signing with dedicated keys

17. Plugin System

17.1 Architecture

• Obsidian-style plugin API with 4 capability tiers
• Built-in plugins (TypeScript, compiled with app) and external plugins (JS, loaded at runtime)
• Hot-reload: file changes in plugin directories trigger automatic re-import
• Per-plugin error logging with ring buffer (500 entries)
• Capability-gated access: pty:write, ui:markdown, ui:sound, ui:panel, ui:ticker, ui:context-menu, ui:sidebar, ui:file-icons, net:http, credentials:read, invoke:read_file, invoke:list_markdown_files, fs:read, fs:list, fs:watch, fs:write, fs:rename, exec:cli, git:read
• CLI execution API: sandboxed execution of whitelisted CLI binaries (mdkb) with timeout and size limits
• Filesystem API: sandboxed read, write, rename, list, tail-read, and watch operations restricted to $HOME
• HTTP API: outbound requests scoped to manifest-declared URL patterns (SSRF prevention)
• Credential API: cross-platform credential reading (macOS Keychain, Linux/Windows JSON file) with user consent
• Panel API: rich HTML panels in sandboxed iframes (sandbox="allow-scripts") with structured message bridge (onMessage/send) and automatic CSS theme variable injection
• Shared ticker system: setTicker/clearTicker API with source labels, priority tiers (low <10, normal 10-99, urgent >=100), counter badge, click-to-cycle, right-click popover
• Agent-scoped plugins: agentTypes manifest field restricts output watchers and structured events to terminals running specific agents (e.g. ["claude"])
• Plugin manifest fields use camelCase (minAppVersion, agentTypes, contentUri) — matches Rust serde serialization

17.2 Plugin Management (Settings > Plugins)

• Installed tab: List all plugins with enable/disable toggle, logs viewer, uninstall button
• Browse tab: Discover plugins from the community registry with one-click install/update
• Enable/Disable: Persisted in AppConfig.disabled_plugin_ids
• ZIP Installation: Install from local .zip file or HTTPS URL
• Folder Installation: Install from a local folder (copies plugin directory into plugins dir)
• Uninstall: Removes plugin directory (confirmation required)

17.3 Plugin Registry

• Remote JSON registry hosted on GitHub (tuicommander-plugins repo)
• Fetched on demand with 1-hour TTL cache
• Version comparison for “Update available” detection
• Install/update via download URL

17.4 Deep Links (tuic://)

• tuic://install-plugin?url=https://... — Download and install plugin (HTTPS only, confirmation dialog)
• tuic://open-repo?path=/path — Switch to repo (must be in sidebar)
• tuic://settings?tab=plugins — Open Settings to specific tab
• tuic://open/<path> — Open markdown file in tab (iframe SDK only, path validated against repos)
• tuic://terminal?repo=<path> — Open terminal in repo (iframe SDK only)

17.4.1 TUIC SDK (window.tuic)

• Injected automatically into every plugin iframe (inline and same-origin URL mode)
• Feature detection: if (window.tuic) — tuic.version reports SDK version
• Files: tuic.open(path, {pinned?}), tuic.edit(path, {line?}), tuic.getFile(path): Promise<string>
• Path resolution: relative paths resolve against active repo; absolute paths match longest repo prefix; ../ traversal outside repo root is blocked
• Repository: tuic.activeRepo() returns active repo path; tuic.onRepoChange(cb) / tuic.offRepoChange(cb) for live updates
• Terminal: tuic.terminal(repoPath) — open terminal in repository
• UI feedback: tuic.toast(title, {message?, level?, sound?}) — native toast notifications with optional sound (info blip, warn double-beep, error descending sweep); tuic.clipboard(text) — copy to clipboard from sandboxed iframe
• Messaging: tuic.send(data) / tuic.onMessage(cb) — bidirectional host↔plugin communication
• Theme: tuic.theme — current theme as JS object (camelCase CSS vars); tuic.onThemeChange(cb) for live updates
• <a href="tuic://open/..."> and <a href="tuic://terminal?repo=..."> links intercepted automatically
• data-pinned attribute on links sets pinned flag
• Interactive test page: docs/examples/sdk-test.html (see docs/tuic-sdk.md for launch instructions)

17.5 Built-in Plugins

• Plan Tracker — Detects Claude Code plan files from structured events

Note: Claude Usage Dashboard was promoted from a plugin to a native SolidJS feature (see section 6.6). It is managed via Settings > Agents > Claude > Usage Dashboard toggle.

17.6 Example External Plugins

See examples/plugins/ for reference implementations:

• hello-world — Minimal output watcher example
• auto-confirm — Auto-respond to Y/N prompts
• ci-notifier — Sound notifications and markdown panels
• repo-dashboard — Read-only state and dynamic markdown
• report-watcher — Generic report file watcher with markdown viewer
• claude-status — Agent-scoped plugin (agentTypes: ["claude"]) tracking usage and rate limits
• wiz-stories-kanban — Kanban board panel for file-based stories with drag-and-drop, filters, and work log timeline

18. Mobile Companion UI

Phone-optimized progressive web app for monitoring AI agents remotely. Separate SolidJS entry point (src/mobile/) served by the existing HTTP server at /mobile.

18.1 Architecture

• Separate Vite entry point (mobile.html + src/mobile/index.tsx)
• Shares transport layer, stores, and notification manager with desktop
• Server-side routing: /mobile/* → mobile.html, everything else → index.html
• Session state accumulator enriches GET /sessions with question/rate-limit/busy state
• SSE endpoint (/events) and WebSocket JSON framing for real-time updates

18.2 Sessions Screen

• Hero metrics header: active session count + awaiting input count with large tabular-nums display
• Elevated session cards with agent icon, status badge, project/branch, relative time
• Rich sub-rows per card: agent intent (crosshair icon) or last prompt (speech bubble), current task (gear icon) with inline progress bar, usage limit percentage
• Question state highlighted via inset gold box-shadow
• Pull-to-refresh spinner via touch events
• Loading skeletons during initial data fetch
• Empty state with instructional hint
• Tap card to open session detail

18.3 Session Detail Screen

• Live output via WebSocket with format=log (VT100-extracted clean lines, auto-scrolling, 500-line buffer)
• Semantic colorization: log lines are color-coded by type (info, warning, error, diff +/-, file paths) via classifyLine() utility
• Search/filter in output: text search bar filters visible log lines in real time
• Rich header: agent intent line (italic), current task line, progress bar, usage percentage (red above 80%)
• Error bar (red tint) when last_error is set
• Rate-limit bar (orange tint) with live countdown timer (formatRetryCountdown)
• Suggest follow-up chips: horizontal scrollable pills from suggested_actions, tap to send
• Slash menu overlay: frosted glass bottom sheet showing detected /command entries; tap to send Ctrl-U + command + Enter
• Quick-action chips: Yes, No, y, n, Enter, Ctrl-C
• TerminalKeybar: context-aware row of special key buttons above the main input. Shows Ctrl+C, Ctrl+D, Tab, Esc, Enter, arrow keys for terminal operations. When the agent is awaiting input, adds Yes/No quick-reply buttons. Consolidated from the former separate QuickActions component
• CLI command widget: agent-specific quick commands (e.g., /compact, /status for Claude Code) accessible via expandable button
• Text command input with 16px font (prevents iOS auto-zoom), inputmode="text"
• Offline retry queue: write_pty calls that fail due to network disconnection are queued and retried when connectivity resumes
• Back navigation to session list

18.4 Question Banner

• Persistent overlay when any session has awaiting_input state
• Shows agent name, truncated question, Yes/No quick-reply buttons
• Visible on all screens, between top bar and content
• Stacks multiple questions

18.5 Activity Feed

• Chronological event feed grouped by time (NOW, EARLIER, TODAY, OLDER)
• Reads from shared activityStore
• Throttled grouping: items snapshot every 10s to prevent constant reordering with multiple active sessions; new items/removals trigger immediate refresh
• Sticky section headers, tap to navigate to session

18.6 Session Management

• Session kill: swipe or long-press a session card to kill/close the PTY session
• New session: create a new PTY session from the sessions screen (optional shell/cwd selection)

18.7 Settings

• Connection status: connectivity indicator with real-time Connected/Disconnected state
• Server URL display
• Notification sound toggle (localStorage-persisted)
• Open Desktop UI link

18.8 PWA Support

• Web app manifest (mobile-manifest.json) with standalone display mode
• iOS Safari and Android Chrome Add to Home Screen support
• apple-mobile-web-app-capable meta tags
• PNG icons (192x192, 512x512) for PWA installability

18.8.1 Push Notifications

• Web Push from TUICommander directly to mobile PWA clients (no relay dependency)
• VAPID ES256 key generation on first enable, persisted in config
• Service worker (sw.js) handles push events and notification clicks
• PushManager.subscribe() flow with user gesture (click handler) for iOS/Firefox
• Push subscriptions stored in push_subscriptions.json, survive restarts
• API endpoints: POST/DELETE /api/push/subscribe, GET /api/push/vapid-key, POST /api/push/test
• Triggers: agent awaiting_input (question, orange dot) and PtyExit (session completed, purple/unseen dot)
• Deep link: notification click navigates to /mobile/session/<id>, opening the specific session detail
• Delivery gate: push is sent whenever the desktop window is not focused (minimized, hidden, or on another workspace). This prevents duplicate alerts while the user is at the desktop and still wakes the PWA service worker when the phone is locked
• Rate limited: max 1 push per session per 30 seconds
• Stale subscriptions cleaned on HTTP 410 Gone
• iOS standalone detection: shows “Add to Home Screen” guidance when not installed
• HTTP detection: shows “Push requires HTTPS (enable Tailscale)” when not on HTTPS

18.9 Notification Sounds

• Audio playback via Rust rodio crate (Tauri command play_notification_sound), replacing the previous Web Audio API approach
• Eliminates AudioContext suspend issues on WebKit and works in headless/remote modes
• State transition detection: question, rate-limit, error, completion
• Completion notifications deferred 10s and suppressed when active sub-tasks are running (detected via ⏵⏵/›› mode-line prefix)

18.10 Visual Polish

• Frosted glass bottom tabs: backdrop-filter: blur(20px) saturate(1.8) with semi-transparent background
• Elevated card design: border-radius: var(--radius-xl), background: var(--bg-secondary), margin spacing
• Safe-area-inset padding for notched devices
• font-variant-emoji: text on output view — forces Unicode symbols (●, ○, ◉) to render as monochrome text glyphs instead of colorful emoji

18.11 Standalone CSS

• Mobile PWA uses its own standalone stylesheet (src/mobile/mobile.css), independent from the desktop global.css
• Shares core color palette and border radius tokens; differs in font stacks, layout approach, and iOS-specific rules
• WebSocket state deduplication: duplicate state pushes are filtered to reduce unnecessary re-renders

19. MCP Proxy Hub

TUICommander aggregates upstream MCP servers and exposes them through its own /mcp endpoint. Any MCP client (Claude Code, Cursor, VS Code) connecting to TUIC automatically gains access to all configured upstream tools.

19.1 Architecture

• TUIC acts as both an MCP server (to downstream clients) and an MCP client (to upstream servers)
• All upstream tools are exposed via the single POST /mcp Streamable HTTP endpoint
• Native TUIC tools (session, git, agent, config, workspace, notify, plugin_dev_guide) coexist with upstream tools
• Tool routing: names containing __ are routed to the upstream registry; all others handled natively

19.2 Tool Namespace

• Upstream tools are prefixed: {upstream_name}__{tool_name}
• Double underscore (__) is the routing discriminator — native tool names never contain it
• Tool descriptions are annotated with [via {upstream_name}] to identify origin
• Clients always see the merged tool list in a single tools/list response

19.3 Supported Transports

• HTTP (Streamable HTTP, spec 2025-03-26) — connects to any MCP server with an HTTP endpoint
• Stdio — spawns local processes (npm packages, Python scripts, etc.) communicating via newline-delimited JSON-RPC

19.4 Circuit Breaker (per upstream)

• 3 consecutive failures → circuit opens
• Backoff: 1s → exponential growth → 60s cap
• After 10 retry cycles without recovery → permanent Failed state
• Recovery: successful tool call or health check resets the circuit breaker

19.5 Health Checks

• Background task probes every Ready upstream every 60 seconds via tools/list (HTTP) or process liveness check (stdio)
• CircuitOpen upstreams with expired backoff are also probed for recovery

19.6 Tool Filtering (per upstream)

• Allow list: only matching tools are exposed
• Deny list: all tools except matching ones are exposed
• Pattern syntax: exact match or trailing-* prefix glob

19.6.1 Per-Repo Scoping

• Each repository can define an allowlist of upstream server names in RepoSettings.mcpUpstreams
• 3-layer merge: per-repo user settings > .tuic.json (team-shareable) > defaults (null = all servers)
• Quick toggle via Cmd+Shift+M popup: shows all upstream servers with status, transport, tool count, and per-repo checkboxes
• Toggling a checkbox immediately persists to repo settings (reactive, no refresh needed)

19.7 Hot-Reload

• Adding, removing, or changing upstreams takes effect on save without restarting TUIC or AI clients
• Config diff computed by stable id field; only changed entries are reconnected

19.8 Credential Management

• Bearer tokens stored in OS keyring (Keychain / Credential Manager / Secret Service)
• Config file (mcp-upstreams.json) never contains secrets
• Per-upstream credential lookup at call time
• OAuth 2.1 token sets persisted as structured JSON in the keyring ({"type": "oauth2", "access_token", "refresh_token", "expires_at"})

19.8.1 OAuth 2.1 Upstream Authentication

• Full RFC 9728 (Protected Resource Metadata) + RFC 8414 (Authorization Server Discovery) flow with PKCE S256
• UpstreamAuth::OAuth2 { client_id, scopes, authorization_endpoint?, token_endpoint? } joins Bearer as a credential type; endpoints auto-discovered from the resource server’s WWW-Authenticate challenge when omitted
• Completion via native deep link tuic://oauth-callback?code=…&state=… — callbacks never touch the WebView console
• TokenManager shared across every HttpMcpClient refresh path with a per-upstream semaphore that defeats thundering-herd refresh. 60 s expiry margin; None expires_at treated as valid
• UpstreamError::NeedsOAuth { www_authenticate } transitions the registry to needs_auth; Services tab shows an Authorize button
• Auto-triggered OAuth is gated behind explicit user consent; the confirm dialog surfaces the Authorization Server origin to defend against AS mix-up
• Status values extended: authenticating (“Awaiting authorization…”) + needs_auth
• Tauri commands: start_mcp_upstream_oauth, mcp_oauth_callback, cancel_mcp_upstream_oauth

19.9 Environment Sanitization (stdio)

• Parent environment is cleared before spawning to prevent credential leakage
• Safe allowlist re-applied: PATH, HOME, USER, LANG, LC_ALL, TMPDIR, TEMP, TMP, SHELL, TERM
• User-configured env overrides applied on top

19.10 SSE Events

• upstream_status_changed events emitted on status transitions (connecting, ready, circuit_open, disabled, failed)
• tools/list_changed notification emitted when upstream tool lists change, enabling live tool-list updates for connected MCP clients
• Delivered via GET /events SSE stream

19.11 Metrics (per upstream, lock-free)

• call_count — total tool calls routed
• error_count — total failed calls
• last_latency_ms — last observed round-trip time

19.12 Validation

• Names: must match [a-z0-9_-]+, must be unique
• HTTP URLs: must use http:// or https:// scheme only
• Self-referential URL detection: rejects URLs pointing to TUIC’s own MCP port
• Stdio: command must be non-empty
• All errors collected (not just first) and returned to caller
• Respects sound toggle from Settings screen

20. Performance

20.1 PTY Write Coalescing

• Terminal writes accumulated per animation frame via requestAnimationFrame (~60 flushes/sec)
• High-throughput agent output (hundreds of events/sec) batched into single terminal.write() calls
• Reduces xterm.js render passes and WebGL texture uploads during burst output
• Flow control (pause/resume at HIGH_WATERMARK) unchanged

20.2 Async Git Commands

• All ~25 Tauri git commands run inside tokio::task::spawn_blocking
• Prevents git subprocess calls from blocking Tokio worker threads
• get_changed_files merged from 2 sequential subprocesses to 1

20.3 Watcher-Driven Git Cache

• Unified repo_watcher (FSEvents/inotify) monitors entire working tree with per-category debounce
• CategoryEmitter routes events to Git, WorkTree, or Config handlers with trailing debounce
• .gitignore-aware filtering prevents unnecessary cache invalidations
• Cache hit ~0.2ms vs git subprocess ~20-30ms
• 60s TTL as safety net for missed watcher events

20.4 Process Name via Syscall

• proc_pidpath (macOS) / /proc/pid/comm (Linux) replaces ps fork
• Eliminates ~100 fork+exec/min with 5 terminals open

20.5 MCP Concurrent Tool Calls

• HttpMcpClient uses RwLock instead of Mutex
• Tool calls use read lock (concurrent); only reconnect takes write lock

20.6 Serialization

• PTY parsed events serialized once with serde_json::to_value
• Reused for both Tauri IPC emit and event bus broadcast (was serialized twice)

20.7 Frontend Bundle Splitting

• Vite manualChunks: xterm, codemirror, diff-view, markdown as separate chunks
• SettingsPanel, ActivityDashboard, HelpPanel lazy-loaded with lazy() + Suspense
• PTY read buffer increased from 4KB to 64KB for natural batching

20.8 Conditional Timers

• StatusBar 1s timer only active when merged PR countdown or rate limit is displayed
• ActivityDashboard snapshot signal uses default equality check (no forced re-render every 10s)

20.9 Profiling Infrastructure

• Scripts in scripts/perf/: IPC latency, PTY throughput, CPU recording, Tokio console, memory snapshots
• tokio-console feature flag for async task inspection
• See docs/guides/profiling.md

Getting Started

What is TUICommander?

TUICommander is a desktop terminal orchestrator for running multiple AI coding agents in parallel (Claude Code, Gemini CLI, Aider, OpenCode, Codex). Built with Tauri + SolidJS + xterm.js + Rust.

Key capabilities:

• Up to 50 concurrent terminal sessions with split panes and detachable tabs
• 10 AI agents supported (Claude Code, Codex, Aider, Gemini, Amp, and more)
• Git worktree isolation per branch
• GitHub PR monitoring with CI status and notifications
• Obsidian-style plugin system with community registry
• Voice dictation with local Whisper (no cloud)
• Command palette, configurable keybindings, prompt library
• Built-in file browser and code editor
• MCP HTTP server for external AI tool integration
• Remote access from a browser on another device
• Auto-update, 13 bundled fonts, cross-platform (macOS, Windows, Linux)

First Launch

1. Add a repository — Click the + button at the top of the sidebar, or use the “Add Repository” option. Select a git repository folder.

2. Select a branch — Click a branch name in the sidebar. If it’s not the main branch, TUICommander creates a git worktree so you work in an isolated copy.

3. Start typing — The terminal is ready. Your default shell is loaded. Type commands, run AI agents, or execute scripts.

4. Open more tabs — Press Cmd+T (macOS) or Ctrl+T (Windows/Linux) to add more terminal tabs for the same branch.

Workflow Overview

Add Repository → Select Branch → Worktree Created → Terminal Opens
                                                    ├── Run AI agent
                                                    ├── Open more tabs
                                                    ├── Split panes
                                                    └── View diffs/PRs

Each branch has its own set of terminals. When you switch branches, your previous terminals are preserved and hidden. Switch back and they reappear exactly as you left them.

Sidebar

The sidebar shows all your repositories and their branches.

Repository groups:

• Repositories can be organized into named, colored groups
• Drag a repo onto a group header to move it
• Right-click a group to rename, change color, or delete it
• Groups collapse/expand by clicking the group header

Repository entry:

• Click to expand/collapse branch list
• Click again to toggle icon-only mode (shows initials)
• + button: Create new worktree for a new branch
• ⋯ button: Repo settings, remove, move to group

Branch entry:

• Click: Switch to this branch (shows its terminals)
• Double-click the branch name: Rename branch
• CI ring: Shows CI check status (green/red/yellow segments)
• PR badge: Shows PR number with color-coded state — click for detail popover. CLOSED and MERGED PRs are automatically hidden (MERGED PRs fade after 5 minutes of user activity).
• Stats: Shows +additions/-deletions

Git quick actions (bottom of sidebar when a repo is active):

• Pull, Push, Fetch, Stash buttons — run the git command in the active terminal

Next Steps

• Terminal Features — Tabs, splits, zoom, detachable tabs, find-in-terminal
• Sidebar — Repos, branches, groups, park repos, quick branch switcher
• AI Agents — Agent detection, rate limits, question detection
• Keyboard Shortcuts — All shortcuts and how to customize them
• Command Palette & Activity Dashboard — Fuzzy-search actions and monitor sessions
• File Browser & Code Editor — Browse files, edit code, git status
• GitHub Integration — PR monitoring, CI rings, notifications
• Git Worktrees — Worktree workflow, configuration
• Branch Management — Checkout, create, delete, merge, rebase, push/pull
• Prompt Library — Template management, variables
• Plugins — Install, browse, and manage plugins
• Voice Dictation — Push-to-talk setup
• Remote Access — Access from a browser on another device
• Settings — All configuration options

Terminal Features

Terminal Sessions

Each terminal tab runs an independent PTY (pseudo-terminal) session with your shell. Up to 50 concurrent sessions.

Creating Terminals

• Cmd+T — New terminal for the active branch
• + button on sidebar branch — Add terminal to specific branch
• + button on tab bar — New terminal tab

New terminals inherit the working directory from the active branch’s worktree path.

CWD Tracking (OSC 7)

When your shell reports directory changes via OSC 7, TUICommander updates the terminal’s working directory in real time. If the new directory falls inside a different worktree, the terminal tab is automatically reassigned to the corresponding branch in the sidebar.

Terminal Lifecycle

Terminals are never unmounted from the DOM. When you switch branches or tabs, terminals are hidden but remain alive. Switch back and your process, scroll position, and output are exactly as you left them.

Closing Terminals

• Cmd+W — Close active tab (confirmation only when a user-launched process is running — e.g. Claude Code, htop, npm; idle shells and shells still loading .zshrc close immediately)
• Middle-click on tab — Close tab
• Right-click → Close Tab — Context menu
• Right-click → Close Other Tabs — Close all except this one
• Right-click → Close Tabs to the Right — Close tabs after this one

Reopening Closed Tabs

• Cmd+Shift+T — Reopen the last closed tab
• Last 10 closed tabs are remembered with their name, font size, and working directory
• Reopened tabs start a fresh shell session in the original directory

Tab Management

Tab Names

• Default naming: “Terminal 1”, “Terminal 2”, etc.
• Double-click a tab to rename it (inline editing)
• Press Enter to confirm, Escape to cancel
• Custom names persist through the session

Tab Reordering

Drag tabs to reorder them. Visual drop indicators show where the tab will land.

Tab Indicators

Sidebar branch icons also show purple when they contain unseen terminals.

Tab Shortcuts

Hover a tab to see its shortcut badge: “Terminal N (Cmd+N)”. Use Cmd+1 through Cmd+9 to jump directly. Ctrl+Tab / Ctrl+Shift+Tab — Next / previous tab.

Scroll Shortcuts

Zoom

Per-terminal font size control:

Range: 8px to 32px. Each terminal has its own zoom level. The current zoom is shown in the status bar.

Split Panes

Split the terminal area into two panes:

Creating Splits

• Cmd+\ — Split vertically (side by side)
• Cmd+Alt+\ — Split horizontally (stacked)

The new pane opens a fresh terminal in the same working directory. Maximum 2 panes at a time.

Navigating Split Panes

• Alt+←/→ — Switch between vertical panes
• Alt+↑/↓ — Switch between horizontal panes
• The active pane receives keyboard input

Resizing Split Panes

Drag the divider between the two panes to adjust the split ratio. Both terminals re-fit automatically when you release.

Maximizing a Split Pane

• Cmd+Shift+Enter — Maximize / restore active pane (zoom pane). Expands the focused pane to fill the full terminal area; press again to restore the split.

Closing Split Panes

• Cmd+W closes the active pane and collapses back to a single pane
• The surviving pane automatically receives focus

Split Layout Persistence

Split layouts are stored per branch. When you switch branches and come back, your split configuration is restored.

Detachable Tabs

Float any terminal into its own OS window:

1. Right-click a tab → Detach to Window
2. The terminal opens in an independent floating window
3. The PTY session stays alive — the floating window reconnects to the same session

When you close the floating window, the tab automatically returns to the main window.

Requirements: The tab must have an active PTY session. Tabs without a session (e.g., just created but not connected) cannot be detached.

Find in Terminal

Search within terminal output with Cmd+F:

1. Press Cmd+F — a search overlay appears at the top of the active terminal pane
2. Type your search query — matches highlight as you type (yellow for all matches, orange for active match)
3. Navigate matches:
   • Enter or Cmd+G — Next match
   • Shift+Enter or Cmd+Shift+G — Previous match
4. Toggle search options: Case sensitive, Whole word, Regex
5. Match counter shows “N of M” results
6. Press Escape to close the search and refocus the terminal

Uses @xterm/addon-search for native integration with the terminal buffer.

Cross-Terminal Search

Search text across all open terminal buffers from the command palette:

1. Press Cmd+P and type ~ followed by your search query (e.g. ~error)
2. Results show terminal name, line number, and highlighted match text
3. Press Enter or click a result to switch to that terminal and scroll to the matched line (centered in viewport)
4. Minimum 3 characters after the ~ prefix

Also accessible via the “Search Terminals” command in the palette.

Copy & Paste

• Copy: Select text in the terminal, then Cmd+C
• Paste: Cmd+V writes clipboard content to the active terminal

Copy on Select

When enabled (Settings > Appearance), selecting text in the terminal automatically copies it to the clipboard. A brief confirmation appears in the status bar. This is enabled by default.

Clear Terminal

Cmd+L clears the terminal display. Running processes are unaffected.

Terminal Bell

The bell behavior when receiving BEL character (\x07) is configurable in Settings > Appearance:

• none — silent
• visual — brief screen flash
• sound — plays notification sound
• both — flash and sound

Clickable File Paths

File paths appearing in terminal output are automatically detected and become clickable links. Hover over a path to see the link underline, then click to open it.

• .md / .mdx files open in the Markdown viewer panel
• All other code files open in your configured IDE, at the line number if a :line or :line:col suffix is present

Paths are validated against the filesystem before becoming clickable — only real files show as links.

Recognized extensions include: .rs, .ts, .tsx, .js, .jsx, .py, .go, .java, .css, .html, .json, .yaml, .toml, .sql, and many more.

Plan File Detection

When an AI agent emits a plan file path (e.g., PLAN.md), a button appears in the toolbar showing the file name. Click it to open the plan — Markdown files open in the viewer panel, others open in the IDE. Click the dismiss button (x) to hide it.

Working with AI Agents

TUICommander detects rate limits, prompts, and status messages from AI agents:

• Rate limit detection — Recognizes rate limit messages from Claude, Aider, Gemini, OpenCode, Codex
• Prompt interception — Detects when agents ask yes/no questions or multiple choice
• Status tracking — Parses token usage and timing from agent output
• Progress indicators — Shows progress bars for long-running operations

When an agent asks a question, the tab indicator changes and a notification sound plays (if enabled).

Session Restore

When you restart TUICommander and a terminal had an active agent session, a clickable banner appears: “Agent session was active — click to resume.” Clicking the banner sends the agent’s resume command. Press Escape or click the x button to dismiss the banner without resuming.

OSC 8 Hyperlinks

Terminal output that uses the OSC 8 standard for hyperlinks (e.g., URLs emitted by ls --hyperlink) is supported. Clicking an OSC 8 hyperlink opens the URL in your system browser.

Sidebar

The sidebar is your primary navigation for repositories, branches, and git operations.

Toggle & Resize

• Toggle visibility: Cmd+[
• Resize: Drag the right edge (200–500px range)
• Width persists across sessions

Repository Management

Adding Repositories

Click the + button at the top of the sidebar and select a git repository folder.

Repository Entry

Each repo shows a header with the repo name and action buttons:

• Click the header to expand/collapse the branch list
• Click again to toggle icon-only mode (shows repo initials — saves space)
• ⋯ button — Opens a menu with: Repo Settings, Create Worktree, Move to Group (with submenus for existing groups, Ungrouped, and New Group), Park Repository, Remove Repository
• Right-click main worktree row → Switch Branch submenu: shows all local branches with a checkmark on the current one. If the working tree is dirty, prompts to stash changes first. Blocks switching when a terminal has a running process.

Removing Repositories

Repo ⋯ → Remove. This only removes the repo from the sidebar — it does not delete any files.

Repository Groups

Organize repos into named, colored groups.

Creating a Group

• Repo ⋯ → Move to Group → New Group…
• Enter a name in the dialog

Moving Repos Between Groups

• Drag a repo onto a group header
• Or: Repo ⋯ → Move to Group → select a group
• To ungroup: Repo ⋯ → Move to Group → Ungrouped

Managing Groups

Right-click a group header for:

• Rename — Change the group name
• Change Color — Pick a new accent color
• Delete — Remove the group (repos become ungrouped)

Groups can be collapsed/expanded by clicking the header, and reordered by drag-and-drop.

Branches

Selecting a Branch

Click a branch name to switch to it. This:

1. Creates a git worktree (for non-main branches) if one doesn’t exist
2. Shows the branch’s terminals (or creates a new one)
3. Hides terminals from the previous branch

Branch Indicators

Each branch row can show:

Branch Actions

• Double-click the branch name to rename the branch
• Right-click for context menu: Copy Path, Add Terminal, Create Worktree (for branches without a worktree), Delete Worktree, Open in IDE, Rename Branch/Worktree, Merge & Archive

Remote-Only PRs

When a repository has open PRs on branches that only exist on the remote (not checked out locally), a badge appears in the branch section. Click it to open a popover listing these PRs. Each row shows the PR number, title, and state badge. Click a row to expand an inline accordion showing PR details, with action buttons:

• Checkout — Create a local tracking branch
• Create Worktree — Create a worktree for the branch
• Merge — Merge the PR via GitHub API (shown when PR is mergeable)
• View Diff — Open PR diff in a panel tab
• Approve — Submit an approving review

Dismiss & Show Dismissed

Remote-only PRs can be dismissed to reduce sidebar clutter. Right-click the remote PRs badge or use the “Dismiss” action in the accordion. A “Show Dismissed” toggle at the bottom reveals dismissed PRs again.

Park Repos

Temporarily hide repos you’re not actively using.

Parking

Right-click any repo in the sidebar → Park. The repo disappears from the main list.

Viewing Parked Repos

A button in the sidebar footer shows all parked repos with a count badge. Click it to open a popover listing them.

Unparking

Click Unpark on any repo in the parked repos popover. It returns to the main sidebar list.

Quick Branch Switcher

Switch branches by number without the mouse:

1. Hold Cmd+Ctrl (macOS) or Ctrl+Alt (Windows/Linux)
2. All branches show numbered badges (1, 2, 3…)
3. Press a number (1–9) to switch to that branch instantly
4. Release the modifier to dismiss the overlay

Git Quick Actions

When a repo is active, the bottom of the sidebar shows quick action buttons:

• Pull — git pull in the active terminal
• Push — git push
• Fetch — git fetch
• Stash — git stash

For more git operations (staging, commit, push, pull, stash, blame, history), use the Git Panel (Cmd+Shift+D).

File Browser & Code Editor

File Browser Panel

Toggle with Cmd+E or the folder icon in the status bar. The file browser shows the directory tree of the active repository (or linked worktree when on a worktree branch).

The file browser, Markdown viewer, and Diff panels are mutually exclusive — opening one closes any other that is open.

Navigation

• Arrow keys (Up / Down) — Move selection
• Enter — Open a file or enter a directory
• Backspace — Go up to the parent directory
• .. row — Click to go up one level (appears when inside a subdirectory)
• Breadcrumb bar — Click any path segment to jump directly to that directory; click the root / to return to the repo root

Directories are listed first, then files. The entry count is shown as a badge in the panel header.

Sorting

Click the funnel icon in the toolbar to switch sort order:

Live Refresh

The panel watches the current directory for filesystem changes. When a file is created, deleted, or renamed outside the app, the listing refreshes automatically without a visible loading spinner.

Git Status Indicators

The panel header shows a legend for git status colors:

File and directory names inherit these colors based on their git status. Gitignored entries are shown in a dimmed style.

View Modes

The file browser supports two view modes, toggled via toolbar buttons:

Switching to tree mode resets to the repository root regardless of the current flat-mode subdirectory. When a search query is active, the view always shows flat results.

Filename Search

Type in the search box to search recursively across the entire repository by filename. Supports * and ** glob wildcards (e.g., *.ts, src/**/*.test.ts). Results appear with their full path. Clear the query with the × button or by emptying the input.

The search icon button to the left of the input toggles between filename mode (file icon) and content mode (magnifier icon).

Content Search

Switch to content mode (magnifier icon) to search inside file contents across the repository. Results are grouped by file, showing the matching line number and a highlighted excerpt. Click any result to open the file in the editor, jumping to that line.

Content search options (shown when in content mode):

A status bar below the search box shows match counts, files searched, files skipped (binary/large), and a “results limited” notice when the result set is truncated. Search begins after a short debounce and requires at least 3 characters.

File Operations (Context Menu)

Right-click any entry to open the context menu:

The keyboard shortcuts (Cmd+C, Cmd+X, Cmd+V) also work when the file browser has focus, without opening the context menu.

Cut + Paste performs a move (rename). Copy + Paste duplicates the file into the current directory. Pasting into the same directory where the file already exists is a no-op.

Opening Files

• Click a file — Opens it in the code editor (see below), or in the Markdown viewer if the extension is .md or .mdx
• Click a content search result — Opens the file and jumps to the matching line number

Panel Resize

Drag the left edge of the panel to resize it. Range: 200–800 px.

Code Editor

Clicking a non-Markdown file opens it in an in-app code editor tab in the main tab area, alongside terminal tabs.

Features

• Syntax highlighting — Auto-detected from file extension; disabled for files larger than 500 KB
• Line numbers, bracket matching, active line highlight, indentation support
• Save — Cmd+S saves the file when the editor tab is focused

Read-Only Mode

Click the padlock icon in the editor tab header to toggle read-only mode. When locked, the file cannot be edited.

Unsaved Changes

An unsaved-changes dot appears in both the tab bar and the editor header when the file has been modified but not saved.

Disk Conflict Detection

If the file changes on disk while you have unsaved edits, a conflict banner appears with two options:

• Reload — Discard local edits and load the disk version
• Keep mine — Dismiss the banner; the next save overwrites the disk version

When the editor has no unsaved changes, files reload silently when they change on disk.

Markdown Viewer

.md and .mdx files open in the Markdown viewer panel instead of the code editor. The viewer renders Markdown with syntax-highlighted code blocks.

See ai-agents.md for how AI-generated plan files are detected and surfaced as a one-click shortcut to open in the viewer.

Command Palette & Activity Dashboard

Command Palette

Open with Cmd+P (macOS) / Ctrl+P (Windows/Linux). The command palette gives you fast keyboard access to every registered action in the app.

How It Works

1. Press Cmd+P — the palette opens with a search input focused
2. Type to filter actions by name or category (substring match, case-insensitive)
3. Navigate with ↑ / ↓ arrow keys
4. Press Enter to execute the selected action
5. Press Escape or click outside the palette to close

What You See

Each row shows:

• Action label — What the action does (e.g., “Git panel”, “New terminal tab”)
• Category badge — The action’s category (Terminal, Panels, Git, Navigation, Zoom, Split Panes, File Browser)
• Keybinding hint — The assigned keyboard shortcut, if any

Search Behavior

Filtering matches against the action label and its category simultaneously. Typing “git” surfaces all Git actions; typing “panel” surfaces all panel-toggle actions regardless of category. There is no minimum query length — results update on every keystroke.

Recency Ranking

When the search box is empty, recently used actions float to the top, ordered by most recent first. Remaining actions are sorted alphabetically. The ranking persists across palette opens so your most-used commands are always one keystroke away.

Mouse Support

Hovering over a row highlights it (same as keyboard selection). Clicking a row executes the action immediately.

Powered by the Action Registry

The palette is auto-populated from actionRegistry.ts. Every action registered there — with its label, category, and keybinding — appears in the palette automatically. No manual configuration is needed, and plugin-contributed actions appear alongside built-in ones.

Search Modes

The command palette supports three search prefixes:

• Leading spaces after the prefix are ignored (~ error = ~error)
• File results show as a flat list with file path
• Content matches include line number and highlighted match text
• Terminal matches include terminal name, line number, and highlighted match text
• Press Enter or click to open the file in an editor tab, or navigate to the terminal match
• Terminal match navigation switches to the correct tab/pane and scrolls to the matched line
• Delete the prefix to return to command mode
• Search runs with a 300ms debounce
• Footer shows !, ?, and ~ hints when in command mode

If no repository is selected, file/content modes show “No repository selected”. If no terminals are open, terminal mode shows “No terminals open”.

Discoverable Search Commands

You can also access search modes via explicit commands in the palette:

These appear as regular commands in the palette — type “Search” to find them.

Activity Dashboard

Open with Cmd+Shift+A. A real-time overview of all your terminal sessions.

What You See

A compact list where each row shows:

Status Colors

Interactions

• Click any row — Switches to that terminal and closes the dashboard
• Rate limit indicators — Show countdown timers for when the limit expires

The dashboard is useful when running many agents in parallel — you can spot at a glance which ones need attention, which are stalled, and which are making progress.

Keyboard Shortcuts

All shortcuts use Cmd on macOS and Ctrl on Windows/Linux unless noted.

Customizing Keybindings

From the UI

Open Help > Keyboard Shortcuts (or Cmd+? → Keyboard Shortcuts). Click the pencil icon next to any shortcut to enter recording mode, then press your new key combination. The app warns you if the combo is already used by another action. Overridden shortcuts are highlighted in accent color with a reset icon to revert individually. A “Reset all to defaults” button is at the bottom.

By editing the config file

You can also edit the keybindings.json file directly in your config directory:

• macOS: ~/Library/Application Support/tuicommander/keybindings.json
• Windows: %APPDATA%\tuicommander\keybindings.json
• Linux: ~/.config/tuicommander/keybindings.json

The file is a JSON array of override objects. Only include shortcuts you want to change — anything not listed uses the default:

[
  { "action": "toggle-git-ops", "key": "Cmd+Shift+Y" },
  { "action": "toggle-markdown", "key": "Cmd+Shift+M" }
]

• "key" uses Cmd as the platform-agnostic modifier (resolved to Meta on macOS, Ctrl on Win/Linux)
• Set "key": "" or "key": null to unbind an action
• Changes made via the UI are saved to this same file
• The file is loaded at startup — restart TUICommander to pick up manual edits

See the action table below for all available action names.

Global Hotkey

A configurable OS-level shortcut to toggle TUICommander’s visibility from any application.

• Configure: Settings > Keyboard Shortcuts > Global Hotkey (top of the tab)
• No default — you must set it yourself (e.g., Ctrl+Space, `Cmd+``)
• Toggle behavior: hidden/minimized → show+focus, visible but unfocused → focus, focused → instant hide
• Cmd and Ctrl are treated as distinct modifiers
• Uses tauri-plugin-global-shortcut (no Accessibility permission required on macOS)
• Not available in browser/PWA mode
• Persists across app restarts

Terminal Operations

Tab Navigation

Zoom

Font size range: 8px to 32px, step 2px per action.

Split Panes

Panels

Note: File browser and Markdown panels are mutually exclusive — opening one closes the other.

Navigation

Git

Branches Panel (when panel is focused)

Quick Branch Switcher

While holding the modifier, all branches show numbered badges. Press a number to switch instantly.

File Browser (when panel is focused)

Code Editor (when editor tab is focused)

Ideas Panel (when textarea is focused)

Voice Dictation

Hold to record, release to transcribe and inject text into active terminal.

Tab Context Menu (Right-click on tab)

Mouse Actions

Action Names Reference (for keybindings.json)

Settings

Open settings with Cmd+,. Settings are organized into tabs.

General Tab

Appearance Tab

Agents Tab

Each supported agent has an expandable row showing detection status, version, and MCP badge.

See AI Agents for details on agent detection, rate limits, and the usage dashboard.

GitHub Tab

GitHub authentication and token management:

Token priority: GH_TOKEN env → GITHUB_TOKEN env → OAuth keyring → gh CLI config → gh auth token subprocess.

Services Tab

HTTP API Server

Enable the HTTP API server for external tool integration:

• Serves the REST API and MCP protocol for AI agents and automation tools
• Local MCP connections use a Unix domain socket at <config_dir>/mcp.sock — no port configuration needed
• AI agents connect via the tuic-bridge sidecar (auto-installed on first launch for Claude Code, Cursor, Windsurf, VS Code, Zed, Amp, Gemini)
• Shows server status (running/stopped) and active session count

TUIC Tools

Native tools exposed to AI agents via MCP. Each tool can be individually enabled or disabled to restrict what agents can access.

Collapse tools (checkbox) — when enabled, replaces the full tool list sent to AI agents with 3 lazy-discovery meta-tools (search_tools, get_tool_schema, call_tool). Cuts the baseline MCP context cost from ~35k tokens to ~500 tokens per agent turn; the agent fetches schemas on demand via BM25-ranked search. Default: off. Toggling refreshes connected clients via notifications/tools/list_changed.

Tools:

• session — PTY terminal session management
• git — Repository state queries
• agent — AI agent detection and spawning
• config — App configuration read/write
• workspace — Repo and worktree queries
• notify — User notifications (toast, confirm)
• plugin_dev_guide — Plugin authoring reference

Upstream MCP Servers

Proxy external MCP servers through TUICommander. Their tools appear prefixed as {name}__{tool}:

• Add upstream servers via HTTP (Streamable MCP) or stdio (process) transport
• API keys for HTTP upstreams are stored in the OS keychain
• Live status (connecting, ready, circuit open, failed) with tool count and call metrics
• Reconnect and remove controls per upstream
• Per-repo scoping: each repo can define an allowlist of active upstream servers via Cmd+Shift+M popup (or repo settings). Empty/null allowlist = all servers active

Remote Access

Enable HTTP/WebSocket access from other devices on your network. See Remote Access for full setup guide.

Voice Dictation

See Voice Dictation for full details.

Keyboard Shortcuts Tab

Browse and rebind all app actions:

• Every registered action is listed with its current keybinding
• Click any action row and press a new key combination to rebind it
• Custom bindings are stored in keybindings.json in the platform config directory
• Auto-populated from the action registry — new actions appear automatically

See Keyboard Shortcuts for the full reference and customization guide.

Plugins Tab

Install, manage, and browse plugins. See Plugins for the full guide.

• Installed — List all plugins with enable/disable toggle, logs viewer, uninstall
• Browse — Discover and install from the community registry

Repository Settings

Per-repository settings accessed via sidebar ⋯ → “Repo Settings”.

Worktree Tab

• Display Name — Custom name shown in sidebar
• Base Branch — Branch to create worktrees from (auto-detect, main, master, develop)
• Copy ignored files — Copy .gitignored files to new worktrees
• Copy untracked files — Copy untracked files to new worktrees

Scripts Tab

• Setup Script — Runs once after worktree creation (e.g., npm install)
• Run Script — On-demand script launchable from toolbar with Cmd+R
• Archive Script — Runs before a worktree is archived or deleted; non-zero exit blocks the operation

Repo-Local Config (.tuic.json)

A .tuic.json file in the repository root provides team-shareable settings that override per-repo app settings and global defaults. The file is read-only from TUICommander (edit it in your repo directly).

Precedence: .tuic.json > per-repo app settings > global defaults

Supported fields: base_branch, copy_ignored_files, copy_untracked_files, setup_script, run_script, archive_script, worktree_storage, delete_branch_on_remove, auto_archive_merged, orphan_cleanup, pr_merge_strategy, after_merge, auto_delete_on_pr_close.

User-specific settings (promptOnCreate, autoFetchIntervalMinutes) are intentionally excluded from .tuic.json.

Notification Settings

• Enable Audio Notifications — Master toggle
• Volume — 0-100%
• Per-event toggles:
  • Agent asks question
  • Error occurred
  • Task completed
  • Warning
• Test buttons — Test each sound individually
• Reset to Defaults — Restore default notification settings

AI Agents

TUICommander detects, monitors, and manages AI coding agents running in your terminals.

Supported Agents

Agent Detection

TUICommander auto-detects which agent is running in each terminal by matching output patterns. Detection uses agent-specific status line markers:

• Claude Code: Middle dot · (U+00B7), dingbat asterisks ✢ ✳ ✶ ✻ ✽ (U+2720–273F), or ASCII *
• Copilot CLI: Therefore sign ∴ (U+2234), filled circle ● (U+25CF), empty circle ○ (U+25CB)
• Aider: Knight Rider scanner blocks ░█
• Gemini CLI / Amazon Q / Cline: Braille spinners ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏
• Codex CLI: Bullets • ◦

When detected:

• The status bar shows the agent’s brand logo and name
• The tab indicator updates to reflect agent state
• Rate limit and question detection activate for that provider’s patterns

Binary detection uses resolve_cli() — Rust probes well-known directories so agents are found even in release builds where the user’s shell PATH isn’t available.

Rate Limit Detection

When an agent hits a rate limit, TUICommander detects it from terminal output:

• Status bar warning — Shows a badge with the number of rate-limited sessions and a countdown timer
• Per-session tracking — Each session’s rate limit is tracked independently with automatic cleanup when expired
• Provider-specific patterns — Custom regex for Claude (“overloaded”, “rate limit”), Gemini (“429”, “quota exceeded”), OpenAI (“too many requests”), and generic patterns

Question Detection

When an agent asks an interactive question (Y/N, multiple choice, numbered options), TUICommander:

1. Changes the tab indicator to a ? icon
2. Shows a prompt overlay with keyboard navigation:
   • ↑/↓ to navigate options
   • Enter to select
   • Number keys 1-9 for numbered options
   • Escape to dismiss
3. Plays a notification sound (if enabled in Settings → Notifications)

For unrecognized agents, silence-based detection kicks in — if the terminal stops producing output for 10 seconds after a line ending with ?, it’s treated as a potential prompt. User-typed lines ending with ? are suppressed from question detection for 500ms (echo window) to avoid false positives from PTY echo.

Usage Limit Tracking

For Claude Code, TUICommander detects weekly and session usage limit messages from terminal output:

• Unified agent badge — When Claude is the active agent, the status bar shows a single badge combining the agent icon with usage data. The badge displays rate limit countdowns (when rate-limited), Claude Usage API data (5h/7d utilization percentages), or terminal-detected usage limits, in that priority order.
  • Blue: < 70% utilization
  • Yellow: 70–89%
  • Red (pulsing): >= 90%
• Clicking the badge opens the Claude Usage Dashboard.

This helps you pace your usage across the week.

Claude Usage Dashboard

A native feature (not a plugin) that provides detailed analytics for your Claude Code usage. Enable it in Settings > Agents > expand Claude Code > Features > Usage Dashboard.

When enabled, TUICommander polls the Claude API every 5 minutes and shows:

• Rate limits — 5-hour and 7-day utilization bars with reset countdowns. Color-coded: green (OK), yellow (70%+), red (90%+).
• Usage Over Time — 7-day token usage chart (input vs. output tokens) with hover tooltips.
• Insights — Session count, message counts, input/output/cache token totals.
• Activity heatmap — 52-week GitHub-style heatmap of daily message counts with per-project drill-down on hover.
• Model usage — Breakdown by model (messages, input, output, cache created, cache read).
• Per-project breakdown — All projects ranked by token usage. Click a project to filter the dashboard to that project.

The dashboard opens as a tab in the Activity Center. You can also reach it by clicking the Claude usage badge in the status bar.

Agent Teams

Agent Teams lets Claude Code spawn teammate agents as TUIC terminal tabs. Enable it in Settings > Agents > Agent Teams.

When enabled, PTY sessions receive the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 environment variable, which unlocks Claude Code’s TeamCreate, TaskCreate, and SendMessage tools. Agent spawning uses direct MCP tool calls (agent spawn) — the earlier it2 shim approach (iTerm2 CLI emulation) is deprecated.

Spawned sessions automatically emit lifecycle events (session-created, session-closed) so they appear as tabs and clean up on exit.

Session Binding (TUIC_SESSION)

Every terminal tab has a stable UUID that persists across app restarts. This UUID is injected into the PTY shell as the TUIC_SESSION environment variable.

How It Works

1. When a terminal tab is created, a UUID is generated via crypto.randomUUID()
2. The UUID is saved with the tab and restored when the app restarts
3. On PTY creation, the UUID is injected as TUIC_SESSION=<uuid> in the shell environment
4. Agents can use $TUIC_SESSION for session-specific operations

Use Cases

Start a Claude Code session bound to this tab:

claude --session-id $TUIC_SESSION

Claude Code stores the session locally. When you restart TUICommander and switch to this branch, the session resumes automatically via claude --resume <uuid>.

Resume a specific session (manual):

claude --resume $TUIC_SESSION

Gemini CLI session binding:

gemini --resume $TUIC_SESSION

Custom scripts that persist state per-tab:

# Use TUIC_SESSION as a stable key for any tab-specific state
echo "Last run: $(date)" > "/tmp/tuic-$TUIC_SESSION.log"

Automatic Resume

When TUICommander restores saved terminals after a restart, it checks whether the agent session file exists on disk before deciding the resume strategy:

1. Verified session — If $TUIC_SESSION maps to an existing session file (e.g. ~/.claude/projects/…/<uuid>.jsonl), the agent resumes with --resume <uuid>
2. No session file — Falls back to the agent’s default resume behavior (e.g. claude --continue for the last session)
3. No agent detected — Tab opens a plain shell; $TUIC_SESSION is still available for manual use

UI Agent Spawn

When you spawn an agent via the context menu or command palette, TUICommander automatically uses the tab’s TUIC_SESSION as the --session-id. This ensures the spawned session is bound to the tab and will resume correctly on restart.

Sleep Prevention

When agents are actively working, TUICommander can keep your machine awake:

• Enable in Settings → General → Prevent sleep when busy
• Uses the keepawake system integration
• Automatically releases when all agents are idle

Environment Flags

Per-agent environment variables can be injected into every new terminal session. Configure in Settings > Agents > expand an agent > Environment Flags.

This is useful for enabling feature flags (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) without manually running export commands. Flags are organized by category with toggle, enum, and number types.

Tips

• Multiple agents on the same repo — Use split panes (Cmd+\) to run two agents side by side on the same branch
• Different agents per branch — Each worktree is independent, so you can run Claude on one branch and Aider on another
• Monitor all at once — Use the Activity Dashboard (Cmd+Shift+A) to see every terminal’s agent status in one view

Agent Teams

Agent Teams let Claude Code spawn teammate agents that work in parallel, each in its own TUICommander terminal tab. Teammates share a task list, communicate directly with each other, and coordinate autonomously.

How It Works

TUICommander automatically injects CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 into every PTY session. This unlocks Claude Code’s TeamCreate, TaskCreate, and SendMessage tools. When Claude Code spawns a teammate, TUICommander creates a new terminal tab via its MCP agent spawn tool — no external dependencies required.

Setup

No configuration needed. Agent Teams is enabled by default for all Claude Code sessions launched from TUICommander.

To verify it’s active, check the environment inside any terminal:

echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
# Should print: 1

Usage

Tell Claude Code to create a team using natural language:

Create an agent team with 3 teammates to review this PR:
- One focused on security
- One on performance
- One on test coverage

Claude Code handles team creation, task assignment, and coordination. Each teammate appears as a separate tab in TUICommander’s sidebar.

Navigating Teammates

Claude Code supports two display modes for teammates:

TUICommander works with both modes. In-process mode is the default and requires no extra setup. With split panes, each teammate appears as a separate TUICommander tab.

Key Controls (In-process Mode)

What Teams Can Do

• Shared task list — All teammates see task status and self-claim available work
• Direct messaging — Teammates message each other without going through the lead
• Plan approval — Require teammates to plan before implementing; the lead reviews and approves
• Parallel work — Each teammate has its own context window and works independently

Good Use Cases

• Code review — Split review criteria across security, performance, and test coverage reviewers
• Research — Multiple teammates investigate different aspects of a problem simultaneously
• Competing hypotheses — Teammates test different debugging theories in parallel and challenge each other
• New features — Each teammate owns a separate module with no file conflicts

Limitations

Agent Teams is an experimental Claude Code feature. Current limitations:

• No session resumption — /resume does not restore in-process teammates
• One team per session — Clean up before starting a new team
• No nested teams — Teammates cannot spawn their own teams
• Token cost — Each teammate is a separate Claude instance; costs scale linearly with team size
• File conflicts — Two teammates editing the same file leads to overwrites; assign distinct files to each

Troubleshooting

Teammates not appearing as tabs:

• Verify the env var is set: echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS should print 1
• Check that TUICommander’s MCP server is running (status bar shows the MCP icon)

Teammates not spawning at all:

• Claude Code decides whether to create a team based on task complexity. Be explicit: “Create an agent team with N teammates”
• Check Claude Code version: Agent Teams requires a recent version

Too many permission prompts:

• Pre-approve common operations in Claude Code’s permission settings before spawning teammates

Inter-Agent Messaging

TUICommander includes a built-in messaging system that lets agents in different terminal tabs communicate directly. This works alongside (and independently from) Claude Code’s native Agent Teams messaging.

How It Works

Every PTY session gets a stable TUIC_SESSION UUID injected as an environment variable. Agents use this as their identity to register, discover peers, and exchange messages through TUICommander’s MCP messaging tool.

When both sender and recipient are connected via SSE (the default for Claude Code agents), messages are pushed in real-time as MCP channel notifications (notifications/claude/channel). They also land in a buffered inbox as a fallback.

What Gets Injected Automatically

TUICommander injects these into every Claude Code PTY session — no manual configuration needed:

Messaging Flow

1. Register — The agent reads its $TUIC_SESSION and registers as a peer:

   messaging action=register tuic_session="$TUIC_SESSION" name="worker-1" project="/path/to/repo"
   

2. Discover peers — Find other agents connected to TUICommander:

   messaging action=list_peers
   messaging action=list_peers project="/path/to/repo"   # filter by repo
   

3. Send a message — Address by the recipient’s tuic_session UUID:

   messaging action=send to="<recipient-tuic-session>" message="PR review done, 3 issues found"
   

4. Check inbox — Read buffered messages (useful if channel push was missed):

   messaging action=inbox
   messaging action=inbox limit=10 since=1712000000000
   

Channel Push vs Inbox

Messages are always buffered in the inbox regardless of whether channel push succeeds. The inbox holds up to 128 messages per agent (FIFO eviction). Individual messages are capped at 64 KB.

Using Messaging from a Standalone Claude Code Session

If you run Claude Code outside TUICommander but still want to use TUIC messaging, you need to:

1. Set TUIC_SESSION — export a stable UUID:

   export TUIC_SESSION=$(uuidgen)
   

2. Connect to TUIC’s MCP server — add to your .mcp.json:

   {
     "mcpServers": {
       "tuicommander": {
         "url": "http://localhost:17463/mcp"
       }
     }
   }
   

3. Enable channel push (optional, for real-time delivery):

   claude --dangerously-load-development-channels server:tuicommander
   

4. Register on first turn — the agent must call messaging action=register with its $TUIC_SESSION before sending or receiving.

Messaging vs Claude Code Native SendMessage

Both systems work simultaneously. Claude Code agents spawned by TUICommander can use either or both.

Deprecated: it2 Shim

Earlier versions of TUICommander used an it2 shell script shim that emulated iTerm2’s CLI to intercept teammate creation. This approach is deprecated — teammate spawning now uses direct MCP tool calls (agent spawn). The shim at ~/.tuicommander/bin/it2 is no longer needed.

Smart Prompts

One-click AI automation for common git and code tasks. Smart Prompts inject context-aware commands into your active agent terminal, run headless one-shot operations, execute shell scripts directly, or call LLM APIs.

What are Smart Prompts?

Smart Prompts are context-aware automation shortcuts that turn repetitive developer workflows into single-click actions. They automatically resolve git context (branch, diff, changed files, PR data) and deliver a well-crafted prompt to your AI agent — no manual typing, no copy-pasting, no context switching.

TUICommander ships with 24 built-in prompts covering commit workflows, code review, PR management, CI fixes, and code investigation. Each prompt includes a description explaining what it does, so you always know what will happen before clicking.

How to Use

Toolbar Dropdown

Press Cmd+Shift+K (Ctrl+Shift+K on Windows/Linux) or click the lightning bolt icon in the toolbar. The dropdown shows all enabled prompts grouped by category with a search bar at the top.

Git Panel — Changes Tab

The SmartButtonStrip appears above the changed files list. Quick access to prompts like Smart Commit, Review Changes, and Write Tests.

PR Detail Popover

Click a PR badge in the sidebar to open the popover. The SmartButtonStrip shows PR-specific prompts: Review PR, Address Review Comments, Fix CI Failures, Update PR Description.

Command Palette

Open with Cmd+P and type “Smart” to see all smart prompts prefixed with “Smart:”.

Branch Context Menu

Right-click a branch in the Branches tab (Cmd+G) for branch-specific prompts like Create PR, Merge Main Into Branch, and Summarize Branch.

Built-in Prompts

Customizing Smart Prompts

Open Settings > Smart Prompts to manage prompts:

• Enable/disable individual prompts (disabled prompts are hidden from all UI surfaces)
• Edit prompt content — built-in prompts show a “Reset to default” button to revert your changes
• Create your own smart prompts with the same placement options and variable system
• View each prompt’s placement (toolbar, git-changes, pr-popover, git-branches) and execution mode

Status Feedback

When prompts cannot execute, the dropdown shows a status banner at the top explaining why:

• “No active terminal” — open a terminal first
• “No AI agent detected” — the active terminal has no agent running
• “Agent is busy” — wait for the current operation to finish

Items are visually dimmed but visible, so you can still browse what’s available.

Context Variables

Prompts use {variable_name} syntax. Most variables are auto-resolved at execution time — no manual input needed.

Git Context (from Rust backend)

GitHub/PR Context (from frontend stores)

Agent/Terminal Context

Manual Input Variables

Variable Input Dialog

When a prompt contains variables that cannot be auto-resolved, a Variable Input Dialog appears before execution. Each field shows the variable name and a human-readable description, so you know exactly what to fill in. Pre-populated suggestions are shown where available.

Execution Modes

Inject Mode (Default)

The resolved prompt is written directly into the active terminal’s PTY — as if you typed it. The agent processes it like any other input. Before sending, TUICommander checks that the agent is idle (configurable per prompt).

Shell Script Mode

Executes the prompt content as a shell script directly — no AI agent involved. The content runs via the system shell (sh -c on macOS/Linux, cmd /C on Windows) in the active repository’s directory.

Useful for automating repetitive CLI tasks: pruning orphan branches, running linters, collecting metrics, or any command pipeline you’d otherwise type manually. Context variables like {branch} and {repo_path} are resolved before execution.

Output is routed based on the prompt’s output target (clipboard, toast, panel, or returned in result). Timeout: 60 seconds.

Headless Mode

Runs a one-shot subprocess without using the terminal. Useful for quick operations like generating a commit message. Output is routed to the clipboard or shown as a toast notification.

Setup: Go to Settings > Agents and configure the “Headless Command Template” for each agent type. The template uses {prompt} as a placeholder:

• Claude: claude -p "{prompt}"
• Gemini: gemini -p "{prompt}"

Without a template, headless prompts automatically fall back to inject mode.

Note: Headless mode is not available in the Mobile Companion (PWA) — prompts fall back to inject mode automatically.

API Mode

Calls LLM providers directly via HTTP API without terminal or agent CLI. Supports an optional system prompt per prompt. Output routed via the same output target options. Requires LLM API configuration in Settings > Agents.

Smart Prompts Library

The Smart Prompts Library stores and manages all your prompt templates — both the 24 built-in AI automation prompts and your custom templates. Prompts are injected directly into the active agent terminal or run headless for quick one-shot operations.

Looking for one-click AI automation? See Smart Prompts for the full guide on built-in automation prompts, context variables, and headless execution.

Opening the Drawer

• Cmd+Shift+K — Toggle the prompt library drawer
• Toolbar button — Prompt library icon in the main toolbar

Browsing and Searching

When the drawer opens, the search input is focused automatically. Type to filter prompts by name, description, or content. Matching is case-insensitive and searches all three fields simultaneously.

Use the category tabs to narrow the list:

Keyboard Navigation

Creating a Prompt

1. Open the drawer (Cmd+Shift+K) and click + New Prompt, or press Ctrl+N/Cmd+N
2. Fill in the fields:
   • Name (required) — shown in the list
   • Description — optional subtitle, also searchable
   • Content (required) — the text to insert; use {{variable}} for dynamic values
   • Keyboard Shortcut — optional global shortcut to trigger this prompt directly
3. Click Save

Editing and Deleting

• Click the pencil icon on any prompt row, or select it and press Ctrl+E/Cmd+E
• Click the trash icon to delete — a confirmation dialog appears before deletion

Variable Substitution

Use {{variable_name}} placeholders in prompt content. When you send a prompt that contains variables, a dialog appears asking you to fill in each value before injection.

cd {{project_dir}} && cargo test -- {{test_filter}}

Built-in Variables

These are resolved automatically by the backend when present:

Custom Variables

Any {{name}} not in the built-in list becomes a custom input field in the variable dialog. You can optionally add a description and default value per variable when editing the prompt — the description appears as placeholder text in the dialog.

Inserting with Variables

The variable dialog offers two actions:

• Insert — writes the resolved text to the terminal input line (you can review before pressing Enter)
• Insert & Run — appends a newline, sending the command immediately

Favorites and Pinning

Click the star icon on any prompt row to toggle its favorite status. Favorited prompts appear at the top of any list view with a ★ prefix and are accessible via the Favorites category tab.

Recently Used

The Recent tab shows the last 10 prompts you sent, in order of use. Recency is also used to sort the All view — most recently used prompts appear first.

Sending to Terminal

Selecting a prompt (click or Enter) writes its content to the currently active terminal. If the prompt has no variables, it is injected immediately. If it does, the variable dialog appears first.

The drawer closes automatically after a successful injection and focus returns to the terminal.

Run Commands

A lighter-weight alternative for per-branch one-off commands:

• Cmd+R — Run the saved command for the active branch
• Cmd+Shift+R — Edit the command before running

Configure run commands in Settings → Repository → Scripts tab.

Voice Dictation

TUICommander includes local voice-to-text using Whisper AI. All processing happens on your machine — no cloud services.

Setup

1. Open Settings → Services → Voice Dictation
2. Enable dictation
3. Download a Whisper model (recommended: large-v3-turbo, ~1.6 GB)
4. Wait for download to complete (progress shown in UI)
5. Optionally configure language and hotkey

Usage

Push-to-talk workflow:

1. Hold the dictation hotkey (default: F5) or the mic button in the status bar
2. Speak your text
3. Release the key/button
4. Transcribed text is inserted into the focused input element (textarea, input, or contenteditable). If no text input has focus, the text falls back to the active terminal PTY. The focus target is captured at key-press time.

The hotkey works globally — even when TUICommander is not focused.

Models

Models are downloaded to <config_dir>/models/ and cached between sessions.

Languages

Auto-detect (default), or set explicitly: English, Spanish, French, German, Italian, Portuguese, Dutch, Japanese, Chinese, Korean, Russian.

Text Corrections

Configure word replacements applied after transcription:

Add custom corrections in Settings → Services → Dictation → Corrections.

Audio Device

Select which microphone to use from the dropdown in dictation settings. Lists all available input devices.

Platform Notes

• macOS: GPU-accelerated transcription via Metal
• Linux/Windows: CPU-only transcription
• Microphone permission is requested on first use (not at app startup)

Status Indicators

Hotkey Configuration

Change the push-to-talk hotkey in Settings → Services → Dictation. The hotkey is registered globally via Tauri’s global-shortcut plugin.

Default: F5

Auto-Send

Enable ‘Auto-send’ in Settings > Services > Dictation to automatically press Enter after the transcribed text is inserted into the terminal. Useful when dictating commands.

Branch Management

TUICommander has a built-in Branches tab inside the Git Panel. It lets you view, create, delete, rename, merge, rebase, push, pull, and compare branches — all without leaving the app.

Opening the Branch Panel

Three ways to open it:

• Cmd+G — Opens the Git Panel directly on the Branches tab
• Click the “GIT” vertical label in the sidebar — Opens the Git Panel on the Branches tab
• Cmd+Shift+D, then click the “Branches” tab header — Opens the Git Panel on the last active tab; click Branches to switch

Branch List Overview

The panel shows two collapsible sections:

• Local — all branches in your local repo
• Remote — tracking branches from all remotes

Each branch row displays:

• Branch name
• Ahead/behind counts relative to its upstream (e.g. ↑2 ↓1)
• Relative date of the last commit (e.g. “3h ago”, “2d ago”)
• Merged badge — shown on branches already merged into the default branch
• Stale dimming — branches with no commit in the last 30 days appear dimmed

A Recent Branches section at the top shows recently checked-out branches from the git reflog, for quick re-access.

Prefix Folding

When you have many branches following a naming convention (feature/, bugfix/, chore/), prefix folding groups them automatically:

• Branches sharing a common /-delimited prefix collapse into a folder row (e.g. feature/ (5))
• Click the folder row (or press → / ←) to expand or collapse it
• The toggle button in the panel header enables or disables prefix folding globally

Search / Filter

Type in the search bar at the top of the panel to filter branches by name. The filter applies to all sections simultaneously. Press Escape to clear the search.

Keyboard Operations

With the Branches panel focused:

Switching between Git Panel tabs:

Checkout

Press Enter (or double-click) on any branch to check it out.

If your working tree has uncommitted changes, a dialog appears with three options:

• Stash — automatically stashes changes, then checks out
• Force — discards changes and checks out
• Cancel — aborts the checkout

Create Branch

Press n to open the inline branch creation form:

1. Type the new branch name
2. Optionally change the start point (defaults to HEAD)
3. Toggle “Checkout after create” (on by default)
4. Press Enter to confirm or Escape to cancel

Delete Branch

Press d to delete the selected branch.

• Uses safe delete (git branch -d) by default — refuses to delete unmerged branches
• A confirmation prompt lets you switch to force-delete (git branch -D) if needed
• Deleting the current branch or the default branch (main, master, develop) is blocked

Rename Branch

Press R to edit the branch name inline. The current name is pre-filled. Press Enter to confirm or Escape to cancel.

Merge

Press M to merge the selected branch into the current branch. The merge runs in the background. Conflicts are reported in the Git Panel header.

Rebase

Press r to rebase the current branch onto the selected branch. Runs in the background; conflicts are reported.

Push

Press P to push the current branch. If no upstream is set, TUICommander automatically configures the tracking relationship (--set-upstream origin <branch>).

Pull

Press p to pull the current branch from its upstream.

Fetch

Press f to fetch all remotes (git fetch --all).

Context Menu

Right-click any branch for the full context menu:

Stale and Merged Indicators

• Stale (dimmed): the branch has no commits in the last 30 days — a visual cue that it may be abandoned
• Merged badge: the branch has been merged into the default branch and is safe to delete

Git Worktrees

TUICommander uses git worktrees to give each branch an isolated working directory.

What Are Worktrees?

Git worktrees let you check out multiple branches simultaneously, each in its own directory. Instead of stashing or committing before switching branches, each branch has its own complete copy of the files.

How TUICommander Uses Them

When you click a non-main branch in the sidebar:

1. TUICommander creates a git worktree for that branch
2. A terminal opens in the worktree directory
3. You work independently without affecting other branches

Main branches (main, master, develop) use the original repository directory — no worktree is created.

Worktree Storage Strategies

Configure where worktrees are stored (Settings → General → Worktree Defaults → Storage):

Override per-repo in Settings → Repository → Worktree.

Creating Worktrees

From the + Button (with prompt)

Click + next to a repository name. A dialog opens where you can:

• Type a new branch name (creates branch + worktree)
• Select an existing branch from the list
• Choose a “Start from” base ref (default branch, or any local branch)
• Generate a random sci-fi name

From the + Button (instant mode)

When “Prompt on create” is off (Settings → Worktree Defaults), clicking + instantly creates a worktree with an auto-generated name based on the default branch.

From Branch Right-Click (quick-clone)

Right-click any non-main branch without a worktree → Create Worktree. This creates a new branch named {source}--{random-name} based on the selected branch, with a worktree directory.

Worktree Settings

Global defaults apply to all repos. Per-repo overrides take precedence when set.

Global Defaults (Settings → General → Worktree Defaults)

Per-Repository Overrides (Settings → Repository → Worktree)

Each setting can use the global default or be overridden for a specific repository.

Merge & Archive

Right-click a worktree branch → Merge & Archive to:

1. Merge the branch into the main branch
2. Handle the worktree based on the “After merge” setting:
   • Archive: Moves the worktree directory to __archived/ (accessible but removed from sidebar)
   • Delete: Removes the worktree and branch entirely
   • Ask: Merge succeeds, then you choose what to do

The merge uses --no-edit for a clean fast-forward or merge commit. If conflicts are detected, the merge is aborted and the worktree is left intact.

When using Ask mode, the cleanup dialog detects uncommitted changes and auto-stashes them during the branch switch. An “Unstash after switch” checkbox lets you restore changes on the target branch.

Archive Script

A per-repo lifecycle hook that runs before a worktree is archived or deleted. Configure it in Settings → Repository → Scripts tab, or via .tuic.json (archive_script field).

• The script runs in the worktree directory that is about to be removed
• If the script exits with a non-zero code, the archive/delete operation is blocked and an error is shown
• Use cases: backing up local data, cleaning up resources, notifying external systems
• The script is invoked via the platform shell (sh -c on macOS/Linux, cmd /C on Windows)

Moving Terminals Between Worktrees

Right-click a terminal tab → Move to Worktree to move it to a different worktree. The terminal will cd into the target worktree path, and the tab automatically reassigns to the new branch in the sidebar.

Also available via Command Palette — type “move to worktree” to see available targets for the active terminal.

Removing Worktrees

• Sidebar × button on a non-main branch — Removes worktree and branch entry
• Right-click → Delete Worktree — Context menu option
• Both prompt for confirmation

Removing a worktree:

1. Closes all terminals associated with that branch
2. Runs git worktree remove to clean up
3. Removes the branch entry from the sidebar

Worktree Manager Panel

Open the Worktree Manager with Cmd+Shift+W (or via the Command Palette → “Worktree Manager”). It shows a unified view of all worktrees across your repositories.

What It Shows

Each worktree row displays:

• Branch name and repository badge
• Dirty status — file additions/deletions, or “clean”
• PR state — open (with PR number), merged, or closed
• Last commit timestamp — relative time since last activity
• Main badge — marks the main branch (actions disabled)

Orphan worktrees (detached HEAD or deleted branch) appear at the bottom with a warning badge and a Prune button to clean them up.

Filtering

• Repo pills — Click a repository name to filter by repo (appears when you have multiple repos)
• Text search — Type in the search field to filter branches by name
• Filters compose: selecting a repo and typing text shows only matching branches in that repo

Single-Row Actions

Each worktree row has action buttons (visible on the right):

• >_ — Open a terminal in the worktree directory
• ✔ — Merge the branch into main and archive (disabled for main branches)
• ✕ — Delete the worktree and branch (disabled for main branches)

Batch Operations

Select multiple worktrees using the checkboxes (shown when more than one selectable worktree exists). A batch bar appears with:

• Merge & Archive (N) — Merges and archives all selected branches
• Delete (N) — Deletes all selected worktrees

Use the Select All checkbox in the toolbar to toggle all non-main worktrees.

MCP Worktree Creation (AI Agents)

AI agents connected via MCP can create worktrees using the worktree action=create tool.

Claude Code — Agent Bridge

Claude Code cannot change its working directory mid-session. When CC creates a worktree via MCP, the response includes a cc_agent_hint field with:

• worktree_path — Absolute path to the worktree directory
• suggested_prompt — Instructions for spawning a subagent that works in the worktree using absolute paths

CC should spawn a subagent (Agent tool) with the suggested prompt. The subagent uses Read, Edit, Glob, Grep with absolute file paths and cd <path> && ... for shell commands.

Other MCP Clients

Non-Claude Code MCP clients receive the standard {worktree_path, branch} response without the cc_agent_hint field. These clients can change into the worktree directory directly.

External Worktree Detection

TUICommander monitors .git/worktrees/ for changes. Worktrees created outside the app (via CLI or other tools) are detected and appear in the sidebar after the next refresh.

Branch Switching

Switching branches in TUICommander does not change the working directory of existing terminals. Each branch’s terminals stay in their worktree path.

When you switch branches:

• Previous branch’s terminals are hidden (but remain alive)
• New branch’s terminals are shown
• If the new branch has no terminals, a fresh one is created

GitHub Integration

TUICommander monitors your GitHub PRs and CI status automatically.

Authentication

TUICommander needs a GitHub token to access PRs and CI status. You have two options:

Option 1: OAuth Login (Recommended)

1. Open Settings > GitHub
2. Click “Login with GitHub”
3. A code appears — it’s auto-copied to your clipboard
4. Your browser opens GitHub’s authorization page
5. Paste the code and authorize
6. Done — the token is stored securely in your OS keyring

This method automatically requests the correct scopes (repo, read:org) and works with private repositories and organization repos.

Option 2: gh CLI

If you prefer, install the gh CLI and run gh auth login. TUICommander will use the gh token automatically.

Token Priority

When multiple sources are available, TUICommander uses this priority:

1. GH_TOKEN environment variable
2. GITHUB_TOKEN environment variable
3. OAuth token (from Settings login)
4. gh CLI token

Requirements

• GitHub authentication (see above)
• Repository with a GitHub remote

PR Monitoring

When you have a branch with an open pull request, the sidebar shows:

PR Badge

A colored badge next to the branch name showing the PR number:

Click the PR badge to open the PR detail popover.

CI Ring

A circular indicator showing CI check status:

The ring segments are proportional to the number of checks in each state. Click to see detailed CI check information.

Diff Stats

Per-branch addition/deletion counts shown as +N / -N next to the branch name.

PR Detail Popover

Click a PR badge or CI ring to open the detail popover. Shows:

• PR title and number with link to GitHub
• Author and timestamps (created, last updated)
• State indicators:
  • Draft/Open/Merged/Closed
  • Merge readiness (Ready to merge, Has conflicts, Behind base, Blocked)
  • Review decision (Approved, Changes requested, Review required)
• CI check details — Individual check names and status
• Labels — With GitHub-matching colors
• Line changes — Total additions and deletions
• Commit count

PR Notifications (Toolbar Bell)

When any branch has a PR event that needs attention, a bell icon with a count badge appears in the toolbar.

Click the bell to see all active notifications in a popover list. Each notification shows the repo, branch, and event type.

Notification Types

Interacting with Notifications

• Click a notification item — Opens the full PR detail popover for that branch
• Click the dismiss (x) button on an item — Dismiss that single notification
• Click “Dismiss All” — Clear all notifications at once

PR Badge on Sidebar Branches

Click the colored PR status badge on any branch in the sidebar to open the PR detail popover directly.

Polling

GitHub data is polled automatically:

• Active window: Every 30 seconds
• Hidden window: Every 2 minutes (reduced to save API budget)
• API budget: ~2 calls/min/repo = 1,200/hr for 10 repos (GitHub limit: 5,000/hr)

Polling starts automatically when a repository with a GitHub remote is active.

Merge State Classification

Review State Classification

Auto-Delete Branch on PR Close

When a PR is merged or closed on GitHub, TUICommander can automatically clean up the corresponding local branch. Configure per-repo in Settings > Repository Settings or set a global default in Settings > General > Repository Defaults.

Safety guarantees:

• The default/main branch is never deleted
• If a branch has a linked worktree, the worktree is removed first
• Uses safe git branch -d — refuses to delete branches with unmerged commits
• Dirty worktrees (uncommitted changes) always escalate to Ask mode, even when set to Auto

Remote-Only Pull Requests

When a branch exists only on the remote (not checked out locally) but has an open PR, it still appears in the sidebar with a PR badge. These “remote-only” PRs support inline accordion actions:

• Checkout — Creates a local tracking branch from the remote
• Create Worktree — Creates a worktree for the branch

PR Detail Popover Actions

Clicking the PR badge on any branch (local or remote-only) opens the detail popover. Available actions:

Post-Merge Cleanup

After merging a PR from the popover, a cleanup dialog appears with checkable steps:

1. Switch to base branch — if the working directory has uncommitted changes, they are automatically stashed. An inline warning shows with an optional “Unstash after switch” checkbox
2. Pull base branch — fast-forward only
3. Delete local branch — closes terminals first, refuses to delete default branch
4. Delete remote branch — gracefully handles “already deleted”

Steps execute sequentially via the Rust backend (not PTY — your terminal may be occupied by an AI agent). Each step shows live status: pending → running → success/error.

Dismiss & Show Dismissed

Remote-only PRs can be dismissed from the sidebar to reduce clutter. A “Show Dismissed” toggle in the sidebar reveals them again.

GitHub Issues

The GitHub panel shows issues alongside PRs in a unified view.

Issue Filter

Control which issues appear using the filter dropdown in Settings > GitHub or directly in the panel:

The filter setting persists across sessions.

Issue Details

Expand an issue to see:

• Labels with GitHub-matching colors
• Assignees and milestone
• Comment count and timestamps (created/updated)

Issue Actions

Troubleshooting

No PR data showing:

1. Check gh auth status — must be authenticated
2. Check repository has a GitHub remote (git remote -v)
3. Check that gh pr list works in the repo directory

Stale data:

• Click the refresh button or switch away and back to the branch
• Polling updates every 30 seconds automatically

Plugins

TUICommander has an Obsidian-style plugin system. Plugins can watch terminal output, push notifications to the Activity Center, render markdown panels, control PTY sessions, and more.

Installing Plugins

From the Community Registry

1. Open Settings (Cmd+,) → Plugins tab → Browse
2. Browse available plugins — each shows name, description, and author
3. Click Install on any plugin
4. The plugin is downloaded and activated immediately

An “Update available” badge appears when a newer version exists in the registry.

From a ZIP File

1. Open Settings → Plugins → Installed
2. Click Install from file…
3. Select a .zip archive containing the plugin

Via Deep Link

Click a link like tuic://install-plugin?url=https://example.com/plugin.zip — TUICommander shows a confirmation dialog, then downloads and installs the plugin. Only HTTPS URLs are accepted.

Manual Installation

Copy the plugin directory to:

• macOS: ~/Library/Application Support/com.tuic.commander/plugins/my-plugin/
• Linux: ~/.config/tuicommander/plugins/my-plugin/
• Windows: %APPDATA%/com.tuic.commander/plugins/my-plugin/

A plugin directory contains at minimum manifest.json and main.js.

Managing Plugins

Settings → Plugins → Installed

The Installed tab lists all plugins (built-in and external):

• Toggle switch — Enable or disable a plugin. Disabled plugins are not loaded but remain installed.
• Logs — Click to expand the plugin’s log viewer. Shows recent activity and errors (500-entry ring buffer).
• Uninstall — Remove the plugin directory (confirmation required). Built-in plugins cannot be uninstalled.

Error count badges appear on plugins that have logged errors.

Built-in Plugins

TUICommander ships with built-in plugins (e.g., Plan Tracker). These show a “Built-in” badge in the list. They can be disabled but not uninstalled.

How Plugins Work

Plugins interact with the app through a PluginHost API organized in 4 capability tiers:

Capabilities are declared in the plugin’s manifest.json. A plugin without pty:write cannot send input to your terminals.

Activity Center

The toolbar bell icon is the Activity Center. Plugins contribute sections and items here:

• Sections — Grouped headings (e.g., “ACTIVE PLAN”, “CI STATUS”)
• Items — Individual notifications with icon, title, subtitle
• Actions — Click an item to open its detail (usually a markdown panel), or dismiss it

The bell shows a count badge when there are active items.

Hot Reload

When you edit a plugin’s files, TUICommander detects the change and automatically reloads the plugin — no restart needed. Save main.js and see changes in seconds.

Example Plugins

TUICommander ships with example plugins in examples/plugins/:

Writing Your Own Plugin

See the Plugin Authoring Guide for the full API reference, manifest format, capability details, structured event types, and testing patterns.

Troubleshooting

MCP Proxy Hub

TUICommander can act as a universal MCP (Model Context Protocol) proxy. Instead of configuring the same MCP servers in Claude Code, Cursor, and VS Code separately, you configure them once in TUICommander. All your AI clients connect to TUICommander’s single /mcp endpoint and get access to every upstream tool automatically.

How It Works

Claude Code ──┐
Cursor ───────┼──▶  TUICommander /mcp  ──┬──▶ GitHub MCP
VS Code ──────┘                           ├──▶ Filesystem MCP
                                          └──▶ Any MCP server

When a tool call arrives at TUICommander’s MCP endpoint, it routes the request to the correct upstream server and returns the result. Upstream tools appear prefixed with the server name — for example, a tool called search_code from an upstream named github becomes github__search_code.

The MCP server must be enabled (Settings > Services > MCP Server).

Adding an Upstream Server

Open Settings > Services > MCP Upstreams. Click Add Server and fill in:

HTTP Server

Use this for MCP servers that expose a Streamable HTTP endpoint.

Stdio Server

Use this for locally installed MCP servers (npm packages, Python scripts, etc.) that communicate over stdin/stdout.

Click Save. TUICommander connects immediately — no restart required.

Server Names

The server name becomes the namespace prefix for all its tools. Choose names that are:

• Descriptive and short (github, filesystem, db)
• Lowercase only
• No spaces, dots, or capital letters — only [a-z0-9_-]
• Unique (no two servers can share a name)

Authentication

For HTTP upstream servers that require a Bearer token:

1. Go to Settings > Services > MCP Upstreams
2. Find your server in the list
3. Click the key icon next to it
4. Enter your token

The token is stored in the OS keyring (Keychain on macOS, Credential Manager on Windows) — never in the config file.

To remove a credential, click the key icon and leave the field empty, then save.

Tool Filtering

You can restrict which tools from an upstream are exposed to downstream clients. Edit a server and set the filter:

Allow list — only these tools are exposed:

Mode: allow
Patterns: read_*, list_*, get_*

Deny list — all tools except these are exposed:

Mode: deny
Patterns: delete_*, rm, drop_*, exec_*

Patterns support a trailing * for prefix matching. Exact names also work. There is no other wildcard syntax.

Upstream Status

Each upstream server has a status indicator:

Circuit breaker: If an upstream fails 3 times consecutively, TUICommander stops sending requests to it briefly. Retries use exponential backoff starting at 1 second, capping at 60 seconds. After 10 retry cycles without recovery, the server is marked Failed.

To reconnect a Failed server, click Reconnect next to its name in the settings panel.

Health Checks

TUICommander probes every Ready upstream every 60 seconds to verify it is still responding. If a probe fails, the circuit breaker activates. If a Circuit Open server’s backoff has expired, the health check also attempts recovery.

Hot-Reload

Adding, removing, or changing upstream servers takes effect immediately when you click Save. TUICommander computes a diff and only reconnects servers that actually changed — unchanged servers are never interrupted.

Troubleshooting

The upstream shows “Failed”

1. Check the server URL or command is correct.
2. Verify the server process is running (for stdio servers).
3. Check credentials are set if the server requires authentication.
4. Click Reconnect to retry.

Tools are not appearing

• The upstream must be in Ready status for its tools to be included.
• Check that a tool filter is not hiding the tools you expect.
• Reconnect and check the error log (Cmd+Shift+E) for initialization errors.

“Circular proxy” error

The HTTP URL you configured points to TUICommander’s own MCP port. This would create an infinite loop. Use a different URL or port.

“Invalid URL scheme” error

Only http:// and https:// URLs are accepted. Other schemes (ftp, file, javascript, etc.) are rejected for security.

Stdio server crashes immediately

• Confirm the command exists on PATH (or use the full absolute path).
• Check the Args field for typos.
• Use the error log (Cmd+Shift+E) to see the stderr output from the child process.
• Note: the server cannot be respawned more than once every 5 seconds (rate limit).

Credential not found

If the upstream returns 401 errors:

1. Go to Settings > Services > MCP Upstreams.
2. Click the key icon for the server.
3. Re-enter the Bearer token and save.

The credential lookup uses the server name as the keyring key. If you renamed the server, the old credential is no longer found — re-enter it under the new name.

Example: Connecting the MCP Filesystem Server

Install the server:

npm install -g @modelcontextprotocol/server-filesystem

Add it in Settings > Services > MCP Upstreams:

• Name: filesystem
• Type: Stdio
• Command: npx
• Args: -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir

After saving, the tool filesystem__read_file (and others) will appear in your AI client’s tool list.

Example: Connecting a Remote HTTP MCP Server

• Name: github
• Type: HTTP
• URL: https://api.example.com/mcp
• Timeout: 30

Set the Bearer token via the key icon in settings. Tools appear as github__search_code, github__create_issue, etc.

Security Notes

• Config files (mcp-upstreams.json) never contain credentials — only the upstream name is stored. Tokens live in the OS keyring only.
• Stdio servers run with a sanitized environment. Your shell secrets (ANTHROPIC_API_KEY, AWS_SECRET_ACCESS_KEY, etc.) are not inherited by spawned MCP processes. Only PATH, HOME, USER, LANG, LC_ALL, TMPDIR, TEMP, TMP, SHELL, and TERM are passed through. Add anything else explicitly in the Env field.
• Self-referential HTTP URLs (pointing to TUIC’s own MCP port) are rejected to prevent circular proxying.
• Only http:// and https:// URL schemes are accepted.

Remote Access

Access TUICommander from a browser on another device on your network.

Setup

1. Open Settings (Cmd+,) → Services → Remote Access
2. Configure:
   • Port — Default 9876 (range 1024–65535)
   • Username — Basic Auth username
   • Password — Basic Auth password (stored as a bcrypt hash, never in plaintext)
3. Enable remote access

Once enabled, the settings panel shows the access URL: http://<your-ip>:<port>

Connecting from Another Device

1. Open a browser on any device on the same network
2. Navigate to the URL shown in settings (e.g., http://192.168.1.42:9876)
3. Enter the username and password you configured
4. TUICommander loads in the browser with full terminal access

QR Code

The settings panel shows a QR code for the access URL — scan it from a phone or tablet to connect quickly. The QR code uses your actual local IP address.

What Works Remotely

The browser client provides the same UI as the desktop app:

• Terminal sessions (via WebSocket streaming)
• Sidebar with repositories and branches
• Diff, Markdown, and File Browser panels
• Keyboard shortcuts

Security

• Authentication — Basic Auth with bcrypt-hashed passwords
• Local network only — The server binds to your machine’s IP; it’s not exposed to the internet unless you configure port forwarding (don’t do this without a VPN)
• CORS — When remote access is enabled, any origin is allowed (necessary for browser access from different IPs)