Settings

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

Search

A search box sits at the top of the tab list. Typing filters every setting across every tab at once, so you do not have to know which tab owns the one you want. Each result shows the setting name and the Tab › Section trail it lives under; selecting one opens that tab and scrolls to the field.

Two limits are deliberate:

• Repository tabs are not searched. A repository tab belongs to one specific repository, and a global box has no way to know which one you mean.
• Settings the current build does not render are not listed. Dictation, for example, is desktop-only, so searching for it in a browser session reports no match rather than opening a tab with nothing in it.

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 & MCP 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 every supported agent that is installed on the machine — see MCP bridge auto-install)
• Shows server status (running/stopped) and active session count

TUIC Tools

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

Manual MCP configuration (expandable) — shows the tuic-bridge binary path and a ready-to-paste JSON snippet for manually configuring MCP clients that aren’t auto-installed. Click “Copy” to copy the snippet to clipboard.

Collapse tools (checkbox) — when enabled, replaces the full tool list sent to AI agents with 3 lazy-discovery meta-tools (search_tools, get_tool_schema, call_tool). Cuts the baseline MCP context cost the agent carries every turn. Measured 2026-09-13 against the running desktop instance with 190 tools connected: the full list is 154,117 bytes / 35,104 tokens, the collapsed list 2,810 bytes / 615 tokens — and the collapsed figure does not move with the number of upstream tools, because they are no longer in the list. The agent fetches schemas on demand via BM25-ranked search. (Tokenizer: tiktoken 0.14.0 o200k_base, a GPT tokenizer used as a proxy; Anthropic publishes no offline tokenizer. Method and full table: mcp-http.md.) Native semantics do not change: a managed command is still one call_tool request for session action=submit, and its bounded receipt comes back in that response. Default: off. Grok sessions receive this compact surface automatically for compatibility with Grok’s tool-name parser, without changing the checkbox or other clients. Toggling emits notifications/tools/list_changed; compatible clients refresh automatically, while clients that ignore the notification may require a reconnect.

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

Manage in Settings in the MCP popup (Cmd+Shift+I) opens this tab scrolled to this block — the block sits below the fold, so a plain tab switch would look like nothing happened.

OAuth upstreams show Authorize when consent is required. TUIC prepares the OAuth request, then displays a blocking in-app confirmation naming the authorization-server origin before opening the system browser. Cancelling that confirmation discards the pending request.

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

• Add upstream servers via HTTP (Streamable MCP) or stdio (process) transport
• 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+I 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 (Help panel)

The keybinding UI lives in the Help panel (Help > Keyboard Shortcuts), not the Settings panel. Browse and rebind all app actions there:

• 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
• The Help panel notes that most shortcuts are also listed in the native system menu bar (desktop app only — browser/PWA clients have no native menu)

See Keyboard Shortcuts for the full reference and customization guide.

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

Smart Prompts Tab

Manage the AI-powered actions surfaced in the toolbar, context menus, and command palette. Reachable from the nav or directly via “Manage Smart Prompts…” in the Smart Prompts drawer.

• Headless Agent — default agent for headless prompts; individual prompts can override it
• Prompt list — grouped by category, with enable/disable toggle and placement/mode badges
• Editor (click a row) — name, description, content with variable insertion, placement checkboxes, Execution Mode, inject target, Auto-execute, output target, system prompt, keyboard shortcut
• Built-in prompts show “Reset to Default” once overridden; custom prompts can be deleted

See Smart Prompts for the full guide.

Providers Tab

Declares the LLM endpoints TUICommander calls directly — the AI Chat panel, diff triage, and Smart Prompts in API mode. Agent CLIs (Claude Code, Codex, …) keep their own credentials and are configured in the Agents tab instead.

The registry lives in <config_dir>/providers.json. API keys are never written there — they go to the OS keyring under provider/<provider-id>.

Providers

+ Add opens the form:

Each saved provider is a card showing its type, its key state (✓ key, no key, or no key needed), and a list of its models. Controls per card:

• Add model — model name as the provider spells it (e.g. claude-sonnet-4-5-20241022) plus a tier (Economic / Standard / Premium). The tier is stored with the model and shown next to it.
• API key row — save a key, or replace / remove an existing one. The key never returns to the UI once saved.
• × — remove the model, or the whole provider.

Reachability (Ollama only). An Ollama card probes /api/tags when the tab opens and shows Reachable or Not detected. When it fails, the backend’s own wording is shown underneath — the endpoint answered an HTTP error, it did not answer within the timeout, or the connection was refused (“is Ollama running?”). A reachable Ollama also lists the models it actually holds, which is what you type into Add model. Other provider types have no probe; use Test on a slot instead.

Slot Assignments

A slot names which model a TUIC feature uses. Each is a dropdown of every model in the registry, plus Test — one real request with a 15 s timeout, answering either the model’s reply or the failure verbatim.

The headless slot picks an agent rather than a model: any detected agent that has a headless template, or one of its run configurations. Choosing External API reveals the model dropdown and routes those calls through the provider registry instead of a CLI.

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% (applied natively by the Rust playback path). Releasing the slider plays a short preview at the new level.
• Audio Output Device — defaults to the system output. Click Choose output device… to enumerate available outputs and pick a specific one. Enumeration is deferred until you click, because on macOS the audio device scan triggers the microphone-permission prompt — notifications never record audio.
• Per-event toggles:
  • Agent asks question
  • Error occurred
  • Task completed
  • Warning
  • Info
  • Attention (agent needs you)
• Test buttons — Test each sound individually. The Test button bypasses the anti-spam rate limit, so rapid A/B volume comparisons always play.
• Silence orchestration completions — Remote HTTP/MCP workers still appear in Activity and update their tab state, but do not play a completion chime. The remote classification survives frontend reloads, and each busy cycle can notify at most once even when idle and process exit arrive separately.
• Reset to Defaults — Restore default notification settings
• Keep toasts in the bell — Each toast is also written to a MESSAGES section in the toolbar bell, so a message that faded while you looked at another window stays readable afterwards. The bell entry keeps the toast level (info / warning / error) and its action, if it had one. Turn this off to leave toasts transient. This setting is outside the audio block: the bell is visual, so it stays reachable on a machine with no audio output.

Attention is the distinct call-back-to-keyboard sound available to agent toasts. Native playback and the browser fallback share a triangular G4→G4→E5 motif with two short knocks and a longer rise; each engine applies its own envelope. It remains subject to the master toggle, configured volume, and its own per-event toggle; native playback also uses the selected output device.