On this page
Advanced Configuration
Docs home · Configuration · Permissions · Field reference · 简体中文
Use these settings only after the normal setup works. Change one area at a time and run sigil doctor when the result is unclear.
Task Planning
[task]
enabled = true
routing_policy = "auto"
max_plan_steps = 12
max_replans = 2
max_subagents = 8
max_parallel_read_steps = 4
max_parallel_changeset_steps = 2
max_planning_research_agents = 3
multi_agent_mode = "explicit_request_only"
allow_write_subagents = trueThe values above are the current schema defaults. auto is the release default, so a missing-config Quick Setup saves auto + explicit_request_only on the review-first baseline. Quick Setup saves auto + proactive only when the installed release carries a qualified sidecar whose exact provider, model, official endpoint family, task-config digest, and binary build all match. Incompatible configurations are rejected. Missing, invalid, stale, or non-matching sidecars stay on the review-first baseline. sigil doctor reports the rollout state and the direct-task tier.
For a coarse rollback, set routing_policy = "manual" and multi_agent_mode = "explicit_request_only". This disables automatic handoff and proactive spawn without deleting durable Task history. A route-local zero-tolerance invariant applies the same effective fallback to subsequent input for the affected session and build.
routing_policy is a three-way semantic admission policy. The current schema default is auto, so ordinary input first runs an independent routing-only decision turn; the model can type one decision between Chat, PlanReview, and Task (the exact decision set depends on the effective route capability). A PlanReview decision runs a read-only plan review and waits for your decision; only an accepted plan can create a durable Task. A Task decision enters the durable planner/executor flow directly; simple prompts still remain chat, and routing never bypasses write, shell, network, or merge approval. Setting routing_policy = "manual" disables automatic routing for ordinary input while /plan and /task remain available as explicit entries. Planner, executor, subagent, and final-synthesis transcripts stay in isolated child sessions, while the parent keeps bounded results and one host-committed final answer. Independent shared-read-only Task steps may execute concurrently; max_parallel_read_steps bounds that fan-out together with max_subagents, while the host commits their terminal results to the parent in stable plan order. Independent ChangesetOnly write-subagent steps may also run concurrently, bounded by max_parallel_changeset_steps and max_subagents. Every member uses the same immutable parent-workspace snapshot, produces a proposal without changing that workspace, and is accepted for review only after the parent revalidates the snapshot. Independent physical Worktree writers can also run as a bounded whole batch in supported Git repositories. Sigil freezes the exact clean or safe dirty/untracked baseline, rebinds each child to a separately owned checkout, extracts bounded proposals, and routes them through a deterministic conflict graph. Non-conflicting integration lanes may apply and verify concurrently, but final promotion still requires exact integration review and authoritative parent verification. Direct or effectful writes in the shared parent workspace remain sequential and exclusive. The TUI Task strip and info rail mark every active step, and cancelling the Task closes the whole active batch. Before accepting a plan, the isolated planner may request one host-owned batch of independent read-only Explore probes. max_planning_research_agents defaults to 3, is hard-capped at 4, and may be set to 0 to disable this planner-only fan-out. The host waits for terminal probe results and resumes the planner automatically; no model polling command is required. The production HTTP driver, including the Desktop-owned sigil serve child, shares the same typed Task pause/continue, guidance, integration-review, restart-control, and recovery contracts with the TUI. Use /plan for a read-only plan and /task for deterministic multi-step execution; a complete sigil-plan-v2 DAG is promoted directly without replanning. When the model identifies independently meaningful outcomes, the plan may also propose typed intent definitions and bind steps to provider-local aliases. These remain unaccepted suggestions until you accept the Plan card; the host then derives all runtime identities and atomically persists the accepted Intent plan with the bound Task plan. The conservative agent mode uses child agents only when you or workspace instructions request delegation. Role-specific model and tool restrictions are listed in Configuration Reference.
Verification
[[verification.checks]]
id = "cargo-test"
command = "cargo"
args = ["test"]
effect = "read_only"Add only checks you understand. Repository hints can be suggested but do not run merely because they exist. A check that changes relevant files must be followed by a non-writing check before the result is current.
Memory, Skills, And Agents
[memory]
enabled = true
writable = trueenabled lets Sigil load workspace instruction files such as SIGIL.md, AGENTS.md, and SIGIL.local.md. Keep them short, current, and suitable for every session in the repository.
writable is enabled by default and can be set to false to opt out. Sigil exposes approval-gated remember_user_preference and remember_project_fact tools, plus inspect_memory and forget_memory. The model decides from the user's meaning whether durable memory is intended; Sigil does not classify prompts by matching phrases. A successful write returns a durable receipt with scope, memory_id, and version. Until that receipt exists, Sigil must not claim the information was remembered beyond the current session. User preferences are shared across local workspaces; project facts are isolated to the canonical current workspace. Secret-like content is rejected.
Forgetting stops future retrieval and physically deletes the Sigil-controlled memory sidecar. It cannot retract context already sent to a provider or erase independent session and audit evidence.
Sigil-native reusable workspace skills, commands, agents, and plugins live under .sigil/skills, .sigil/commands, .sigil/agents, and .sigil/plugins. By default, Sigil also discovers standard .agents/skills, Codex .codex/agents, OpenCode .opencode/{skills,commands,agents}, and Claude Code .claude/{skills,commands,agents} resources. Native Sigil resources win name conflicts. Compatible resources inherit workspace trust instead of requiring per-item review or enablement; compatible commands use /name, while compatible agents use @name and remain manual-only and read-only. Set [skills].compatibility_auto_discover = false to disable the default set, or use compatibility_sources to add or precisely select sources.
Compaction And Code Intelligence
[compaction]
enabled = true
strategy = "cache_aware_v3"
native_carrier_enabled = falsecache_aware_v3 is the only strategy. It keeps reusable prior input stable where supported, preserves current intent and complete recent turns, and starts a new cache period only when the conversation must fit or trusted cost evidence shows a benefit. Running /compact is the explicit request to generate, validate, and atomically activate one recoverable semantic checkpoint; it does not open a confirmation modal. On an admitted route this makes one additional LLM request on the current provider/model route, keeping the previous request as the cacheable prefix and appending a strict JSON summary instruction. This is not a child agent and cannot execute tools. The model contributes only untrusted narrative; objectives, constraints, authorization, completion, and verification remain grounded in saved session history. Sigil shows progress followed by an applied receipt or an actionable refusal. If generation, exact token proof, economics admission, or a concurrent conversation change prevents safe activation, the active context remains unchanged. Unsupported routes remain unavailable rather than selecting an older algorithm. A failed manual summary is not silently downgraded; only fit-required or overflow emergency paths may use an explicitly audited deterministic fallback. Large tool-output aging remains a separate deterministic maintenance path instead of being hidden behind /compact. Context-window resolution uses the exact connection/model value first, then provider-owned metadata, then fallback_context_window_tokens. Normal TUI settings expose Automatic, 64K, 128K, 256K, and 1M presets; Automatic leaves the exact override unset. Existing custom values remain valid and can still be maintained in sigil.toml.
native_carrier_enabled is a default-off provider-native acceleration flag. Setting it to true currently has no effect because Sigil does not yet reuse provider-specific compacted state in the next request on the same route. Portable continuity remains the only active compaction path.
[code_intelligence]
enabled = false
server_startup = "lazy"
auto_discover = trueWhen enabled, Sigil can use installed language servers for navigation, diagnostics, and reviewed edits. Alt-D checks changed source files. Missing language-server support does not block ordinary chat or file tools.
Terminal And Model Request Overrides
[terminal]
keyboard_enhancement = "auto"
mouse_capture = true
osc52_clipboard = true
scroll_sensitivity = 3
[terminal.notifications]
enabled = false
method = "auto"
minimum_run_duration_ms = 10000Disable a feature when a terminal, remote layer, or multiplexer does not support it. Notifications are off by default and use fixed text without prompts, paths, tool details, provider, model, or session id. Use Terminal compatibility to test the result.
SIGIL_MODEL_REQUEST_TIMEOUT_SECS, SIGIL_MODEL_STREAM_IDLE_TIMEOUT_SECS, and SIGIL_MODEL_STREAM_TOTAL_TIMEOUT_SECS temporarily override shared model-request timeouts. Provider credentials and endpoint settings stay on provider pages.
Plugins And MCP
Plugins are discovered at .sigil/plugins/<id>/plugin.toml and reviewed in /config. Review a changed plugin again before allowing it to run. Plugin entries cannot request inherited credential variables.
Configure MCP servers with [[mcp_servers]]. Local servers start with a cleared environment; grant only required variable names through root-user inherit_env. Remote authentication, trust, and compatibility belong in the MCP guide. Exact fields are in Configuration Reference.