Sigil TUI User Guide

Docs home · Quickstart · Workflows · Reference · 简体中文

This guide is for day-to-day Sigil users. It focuses on what you see and control in the TUI.

If you are using Sigil for the first time, read Quickstart first. If you already know the UI and want prompt patterns for real tasks, use Common Workflows.

Start

Start the TUI:

sigil

If no usable config exists, Sigil opens Quick Setup. You confirm the workspace, choose a model, and provide authentication. After setup, Sigil writes workspace.root = ".", so the directory where you started the TUI becomes the active workspace.

If you have not installed Sigil yet, see Installation. During development inside a checkout, cargo run -p sigil is equivalent.

For authentication options, including environment variables, see Sigil Configuration Guide.

Headless And Local API Workflows

The TUI remains the normal user surface. For scripts, sigil run "<task>" uses human text by default; choose --output json for one terminal record or --output jsonl for an ordered event stream plus one terminal record. Machine stdout contains no human progress lines, so a standard JSON parser can consume it directly. Headless runs cannot open an approval modal: an unresolved ask decision fails closed.

sigil serve is an advanced loopback-only HTTP/SSE interface for a trusted local client. It requires SIGIL_HTTP_TOKEN by default, prints its actual OS-selected address, and stops gracefully on Ctrl-C. Do not expose it through a public bind or treat it as a multi-user daemon. See Machine output and local server for startup, routes, authentication, replay, and exit-code details.

Main Screen

The TUI is organized around these areas:

• Chat / transcript: user messages, assistant responses, thinking summaries, and tool activities.
• Composer: the bottom input area. It remains visible and clears after submit.
• Info rail: the right-side status area for session, permissions, model, LSP, usage, and controls.
• Activity: tool results such as file reads, searches, shell commands, file edits, and code diagnostics.
• Approval modal: a review card for tool calls that need confirmation, including summary, files, diff, and actions.

Text streamed before a tool call is treated as a collapsible thinking/progress preamble, not as a completed assistant reply. The transcript therefore keeps one assistant reply for the final answer.

The main workflow is typing tasks directly in the composer. Slash commands are reserved for a small set of high-frequency control actions.

Common Controls

When the composer is focused, Up/Down first handles prompt history or cursor movement inside multiline input. Ctrl-J inserts a newline reliably; Shift-Enter and Alt-Enter also insert a newline when terminal keyboard enhancement is active and reports those modifiers. Ctrl-Z restores the last non-empty draft cleared with Esc; it is a single draft restore, not a general undo stack.

When [terminal].mouse_capture = true, mouse mode supports transcript scrolling, composer cursor placement, approval controls, slash candidates, setup/config rows, session selection, activity selection, and tool card header or hidden-preview expand/collapse. Drag across transcript text to select by displayed columns, then press Ctrl-C to copy the selection through OSC52 when clipboard integration is enabled.

Use the Terminal section in /config to enable attention notifications, choose auto / osc9 / osc777 / bell, and set the long-run threshold. The same section shows keyboard enhancement, mouse capture, OSC52 copy, and scroll sensitivity as compatibility facts; edit sigil.toml for those lower-frequency overrides. Notifications are off by default, use fixed privacy-safe text, and are suppressed when reliable terminal focus telemetry says Sigil is focused.

For terminal-specific smoke checks and tmux/SSH guidance, see Terminal Compatibility Checklist.

Image Attachments

From an idle Build composer, paste one local PNG, JPEG, or WebP path (including a file:// URL), or press Ctrl-V when the system clipboard contains an image. Sigil shows each admitted image as a metadata chip above the text input. It does not put the original path in the conversation.

Press Up from the first input row to select the last chip, use Left/Right to move between chips, Down or Esc to return to the text input, and Backspace/Delete to remove the selected image. Enter can send text plus images or an image-only turn.

Image input is deliberately limited in V1:

• At most 4 images per turn, 8 MiB per image, and 24 MiB total.
• At most 8192 pixels on either side and 16 million pixels per image; the combined visual-token estimate must also fit the local limit.
• Images can only be sent as a direct idle Build turn. They are not queued and cannot accompany Plan, slash-command, skill, task, or agent input. Sigil keeps the draft when it blocks one of those routes.
• Only explicitly recognized image-capable model IDs on OpenAI Responses, Anthropic, and Gemini are admitted. DeepSeek, OpenAI-compatible endpoints, unknown model IDs, and unrecognized aliases fail before provider transport.

Sessions retain bounded image metadata while encoded bytes remain in the workspace-local attachment cache. Resume rechecks the cached content before the next provider request. If a required cache entry is missing or damaged, Sigil does not silently send only the text placeholder: paste the exact original image again to restore the content-addressed entry, or start/fork from a conversation that does not include that image turn. Safe session exports include metadata, not image bytes.

Slash Commands

/model, /effort, /resume, /agent, and /queue show candidates. Use Up/Down to select, Tab to accept, and Enter to execute. /agent rename and /agent cancel also show child-agent candidates before the argument is completed.

When Sigil is already running, ordinary chat input becomes a visible Follow-ups item instead of being dropped or added immediately to the timeline or provider-visible history. Follow-up dispatch is FIFO after the active turn finishes; the normal user message is added when the item dispatches. Before it sends, Sigil freezes the exact queued request and checks it against the admitted local token profile. A request that exceeds the verified budget may first apply one portable compaction; compaction CAS, queue-revision CAS, promotion, and provider dispatch remain separate ordered barriers. If local proof is unavailable, Sigil reports that fact and dispatches only the unchanged frozen request. If a restart or transport failure leaves it unclear whether a follow-up reached the model, Sigil marks it stale and never resends it automatically. next moves an item to the front for the next turn; interrupt stops the current run before dispatching the selected item. Agent mentions are not silently converted into main-thread follow-ups while the session is busy; wait for the current turn or use the dedicated agent messaging surface.

/plan creates a Plan ready card only when the planner returns a structured plan with at least one executable step. Plain review text or unstructured summaries remain ordinary assistant output and do not create a task approval surface. Press Enter on Plan ready to create and run the durable task, or Esc to discard it.

Config Panel

The /config panel groups provider, permission, Web, memory, compaction, code intelligence, terminal, appearance, Agents, Skills, Plugins, and MCP settings. The Web section can enable/disable Web tools, cycle the independent network policy and search route, and disable the bundled Exa profile; advanced destination and budget limits remain in sigil.toml. In the Appearance section, Enter cycles built-in themes, syntax themes, and usage cost currency; theme drafts preview immediately, and Ctrl-S saves the selected preferences to sigil.toml. In the Plugins section, Sigil discovers workspace plugin manifests under .sigil/plugins/<id>/plugin.toml.

Use PgUp/PgDn to move between discovered plugins. The detail view shows the current trust state, manifest path, full manifest hash, skills, hook commands with args and approval mode, and MCP server commands with args, startup, and required status. Footer approve trusts the currently displayed manifest hash; footer deny disables that hash. Sigil refreshes the manifest before writing the review decision and appends the review to the session log.

Web Search And Fetch

When [web] is enabled, Sigil exposes stable search through provider-hosted search or the websearch client tool. Before client query or remote transport egress, the TUI reserves a disclosure strip at the top of the live panel without covering the transcript, status band, or composer. MCP handshake, query, and tool-call disclosures for the same destination are aggregated into one continuous operation card; every underlying message still receives its own successful-frame receipt, and the card is removed only when the corresponding tool/activation finishes or the run ends. CLI run writes and flushes the same safe disclosure to stderr. Search results are external/untrusted and source metadata is shown in activity/audit views when available. Configure routes, limits, and opt-out controls in Permissions and sandbox.

webfetch reads one exact HTTP(S) URL that Sigil already observed in the current session. The model passes a session-local source_id, not a newly invented raw URL. The model should use search snippets directly when they answer the task and call webfetch only when the user explicitly asks to read a page or one specific fact is missing; it must not fan out across search results by default. Read-only fetches do not ask per request when network_mode = "allow"; with network_mode = "ask", Allow session applies only to the same read-only Web tool in the current session. User-message URLs, structured search results, provider-hosted sources, prior fetches, and cross-origin redirect targets can produce these capabilities. Query-bearing or signed URLs remain process-local and become unavailable after restart; Sigil never reconstructs them from the redacted display URL. Every fetch re-applies disclosure, SSRF/DNS rules, redirect limits, byte budgets, bounded decoding, and external/untrusted provenance.

Planned Tasks

Normal composer input always stays chat-first and no longer auto-continues a durable task just because the current session has unfinished task state. Use /task continue or a task UI action when you want to continue a task. Use /plan or /plan <prompt> when you want a read-only planning answer before editing; press Enter on the plan-ready card only when you want Sigil to create and run a normal durable task from that plan. Use /task <task> when you want Sigil to break a larger request into durable steps before execution without a separate planning pass.

Planned tasks use role-specific agents:

• Planner: reads context and writes the task plan.
• Executor: performs normal workspace changes for executor steps.
• Subagent read/write: runs delegated steps in child sessions and links the child session back to the parent task.

Task runs, plans, step status, child-session links, and subagent approval route summaries are stored as append-only control entries. The info rail shows the latest task status, plan version, and current step from that durable state. When child agents exist, the composer shows a compact agent panel under the input with each agent's status. Press Down from the last composer input row to focus that panel, use Up/Down to choose an agent, and press Enter to switch the main chat area. Alt-A / Shift-Alt-A still cycle the visible transcript between main and concrete child agents, and /agent picks a specific target. Child agent display names come from explicit plan metadata, then persisted /agent rename overrides, and otherwise fall back to generic role labels such as read 1 or write 1.

When a planned task needs verification, the task status band shows a compact Verification card with one recommended check and a short reason. It only offers a trusted task check or an approval that must happen before a check can run; it never starts a check by itself. Click the card or press Alt-V to focus it, then press Enter to run the exact rendered action. Press I to inspect the terminal reason, receipt, workspace snapshot, and any proven changeset/command/artifact link. Missing evidence is shown as not linked, not inferred. A queued or running check is shown as in progress instead of being recommended again.

Session restore only rebuilds the visible task state. It does not automatically continue unfinished work. Type the next instruction in the composer to continue the latest task with guidance, or use /task continue to continue without extra guidance.

Approvals and File Changes

Read-only file and search tools usually run directly. File writes, edits, deletes, shell execution, and external MCP tools follow the permission policy and may require approval.

In an approval card, focus on:

• Summary: what the tool call is about to do.
• Files: which files may be affected.
• Diff: preview of file changes.
• Actions: allow or deny.

Use Left/Right to choose an action and Enter to confirm. Y/N shortcuts are also supported. If no decision is made for a long time, the request is denied automatically so the worker does not wait forever.

After a file-changing tool runs, the activity keeps a bounded diff. Large diffs are truncated and show how many lines were hidden.

Sessions and Recovery

By default, session logs are written under Sigil's per-user state directory:

<state-root>/workspaces/<workspace-id>/sessions/

Sigil stores session and control state as append-only JSONL. For users, this means:

• Restarting the TUI restores the latest session by default.
• Current builds restore V2 session JSONL only. If Sigil finds the older raw session format, it reports the file as unsupported and leaves it unchanged; archive that file and start a new session. Sigil does not migrate the older format.
• Exiting the TUI prints the current session id and sigil resume <session-id> for command-line restore.
• Cancelling a run first closes admission for new provider, tool, process, socket, retry, redirect, and child-work effects, then waits up to a bounded cleanup deadline. The UI shows Cancelling while active work is converging; Cancelled means cleanup was confirmed, while Interrupted means the deadline expired or cleanup could not be proven.
• Cancelling a run does not discard messages and tool results already written to the log. /queue interrupt dispatches its follow-up only after the prior run reaches a durable cancellation terminal state.
• Tool executions that started but did not finish are shown as interrupted after restore.
• File-change activities are restored with their captured diff summaries.
• Saving new provider/model defaults in /config does not rewrite the identity of the current session.
• Before prompts, queued follow-ups, tool arguments, task controls, or external URLs are kept in session records, Sigil stores a redacted, size-limited description. Sensitive exact values remain only for active use and are not reconstructed after restart; if exact information is required again, Sigil asks you to retry the action.
• External material remains explicitly untrusted through compaction and recovery. Source records and claim citations are stored separately, and citations bind only to the final safe assistant text they support.

Manage saved sessions

Open /resume to browse saved sessions. Up/Down changes the selected row and Enter resumes it. With a row selected, press Ctrl-O or right-click the row to open the exclusive Session Actions dialog. The dialog keeps the composer draft unchanged and owns keyboard focus until it closes.

• Enter resumes the selected session.
• F forks its latest finalized turn and switches to the new conversation. Files and other side effects remain shared.
• E exports a safe JSON transcript under the workspace state directory's session-exports/ folder. The export contains safe conversation messages, not internal control state, tool arguments, credentials, or private continuation data.
• P pins or unpins the session. A pinned session is excluded from explicit cleanup.
• D opens an exact delete preview. A second Enter deletes only the reviewed file if it is still unchanged and inactive. The current session cannot be deleted.

For batch cleanup, open /config, choose Storage, move to the footer action named sessions, and press Enter. Sigil shows the configured retention limits, protected counts, candidates, and estimated released bytes before a second explicit confirmation. Normal startup, runs, resume, and sigil serve never apply retention automatically. Configure the limits in [[session.retention]](configuration.md#storage-and-session-paths).

Controlled checkpoints and conversation forks

When the latest completed turn contains controlled ordinary-file edits, press Ctrl-R to open its restore dialog. Sigil immediately asks the worker to rebuild an exact preview from the durable log; there is no separate first Enter step. The modal owns keyboard focus and directly shows the reverse diff, file restore directions, conflicts, and excluded unknown side effects. If no durable line diff was recorded, it shows current and restore-target hash evidence instead. Use Up/Down or PageUp/PageDown (or the mouse wheel) to scroll, Ctrl-R to refresh, and Esc to close without changing files. The composer draft is preserved and action keys are not inserted into it while the dialog is open.

After the modal reaches READY, press Enter to restore the controlled files. While preview or restore is in flight, duplicate actions are ignored. A completed restore closes the dialog and adds a RESTORED result to the timeline; late responses from an older dialog request are ignored.

Restore checks the current file hashes and stored snapshots before its first write. A changed file, missing or sensitive snapshot, different workspace, or stale preview blocks the whole operation. After a successful restore, prior verification is stale and should be rerun. This operation restores only controlled ordinary-file mutations: it does not undo shell commands, MCP/plugin effects, network requests, databases, remote services, directories, renames, or symlinks.

Press F in a ready or blocked restore dialog to fork the conversation through that completed turn. The fork becomes the active session and keeps only safe user/assistant/tool history plus rebound source provenance; active approvals, tasks, queues, continuation handles, and mutation state are not copied. The parent session stays append-only. Conversation fork does not isolate or restore the workspace—both sessions still refer to the same files.

Long Context and Compaction

The info rail shows the latest provider-reported prompt usage against the model context window. The ctx line labels whether the window came from provider metadata or fallback_context_window_tokens, and Sigil calculates soft and hard thresholds from that same window:

• Soft threshold: context pressure is getting high.
• Hard threshold: context pressure is critical. After a successful chat turn becomes fully idle, Sigil may prepare and apply one locally verified portable compaction in the background.
• /compact: opens a V2 fold review with fold, keep, and protection details. When the selected profile has an installed checksum-pinned tokenizer and exact local target-fit proof, Enter confirms one manual apply.
• If the window is unknown, configure fallback_context_window_tokens so the TUI can show percentages and threshold hints.

Opening the review is read-only: it never rewrites history or appends a compaction record, and it does not download a tokenizer. Applying is available only when the review says the target is ready; the confirmed apply appends the V2 lifecycle and activates the verified boundary without rewriting raw history. An unavailable review cannot apply.

To prepare a verified local DeepSeek V4 Flash tokenizer without changing any session state, run sigil tokenizer install deepseek-v4-flash. The command discloses its public network download before it starts. Installation enables local admission but does not itself alter a session.

Idle automation never preempts streaming work, queued input, an agent continuation, a manual review, model switching, or overflow recovery. Preparation is request/session-owned and its result is discarded if that idle frontier changes. Only an exact local admission may append the lifecycle and activate the boundary; unavailable admission leaves the session unchanged and enters a short process-local cooldown. Queued pre-turn preparation uses the same owned background pipeline; queue changes cancel it, and stale source or queue revisions fail before provider dispatch.

For the official OpenAI Responses endpoint and exact supported snapshot, one provider-confirmed context-window rejection before output or side effects may start guarded overflow recovery. Sigil performs two audited, non-generating input-token measurements for the rejected request and compacted target, requires exact fit and minimum-savings evidence, rechecks the session/rejection frontier, and retries the retained request once. Count failures, stale state, aliases, compatible endpoints, restored sessions, and a second overflow fail closed without replay.

Code Intelligence

For new requests, Sigil can attach a small request-local set of relevant repository snippets. It uses an already-warm, query-relevant language-server snapshot when one is available; otherwise it falls back to bundled Tree-sitter adapters for Rust, Python, JavaScript/JSX, TypeScript/TSX, and Go. It does not start a language server just to assemble this context, build a persistent repository index, or download grammars at request time. Ignore rules, secret-like and generated paths, symlinks, file-size caps, and the final context budget still apply. The detailed info rail shows the latest included sources and exclusion reasons without exposing the raw prefix. Queued follow-ups and compaction preparation keep the context selected for their frozen request instead of silently selecting it again at dispatch time.

Code intelligence is disabled by default. When enabled, Sigil registers code-query tools:

• code_symbols
• code_workspace_symbols
• code_definition
• code_references
• code_diagnostics
• code_actions

It also registers LSP edit tools that require an approval diff before writing:

• code_action
• code_rename

Language servers with the default trust_required = true start only after this exact workspace has a durable Trusted decision in the current session. A missing, restricted, or denied decision blocks the LSP process, but does not block normal chat, file tools, or the Rust Tree-sitter fallback. Workspace trust does not approve code_action or code_rename; their diff approval remains separate.

In the TUI, Alt-D can run diagnostics over git changed source files. Results appear as a normal activity and the LSP section of the info rail keeps a summary.

The separate code_* tool fallback for outline and syntax diagnostics remains Rust-specific when no LSP server is available. This is narrower than the multilingual automatic request context above. Failure does not block normal chat or tool calls.

See Sigil Configuration Guide for configuration.

FAQ

The TUI opens Quick Setup immediately

No usable config was found, or the config failed to load. Complete Quick Setup to enter the main screen.

Should I write the API key into the config file?

For temporary use or CI, choose the provider first and use its variable from the provider authentication map. If you save the key through Quick Setup or /config, it is stored as plaintext in the local config file. doctor reports that state as a warning with a remediation hint. Do not commit a real sigil.toml.

What if my terminal has broken mouse or clipboard support?

Review the Terminal section in /config, or set [terminal].keyboard_enhancement = "off" / [terminal].mouse_capture = false / [terminal].osc52_clipboard = false / [terminal].scroll_sensitivity = 3 in sigil.toml. Keyboard enhancement is resolved on the next launch; mouse capture changes apply on the next launch; OSC52 clipboard changes apply to the next copy action; scroll sensitivity controls mouse wheel row steps in transcript and approval diff views.

Run /doctor to see the detected terminal profile, multiplexer or remote layers, and clipboard bridge warnings.

Why are subcommands limited?

Running sigil opens the TUI. Subcommands such as sigil run and sigil doctor are for automation, scripts, and debugging, not the full product surface.

Why do some tools need approval?

Sigil's permission layer decides allow / ask / deny. File writes, command execution, and external tools are conservative by default so users can review previews and risks before key changes.