Repository navigation
Releases
Releases · X-AlphaCoder-X/sigil-code
Sigil Code 1.1.0
Added
- Prompt caching for every model call, on by default. Sigil picks the method from the base URL
and model:cache_controlbreakpoints (Anthropic, OpenRouter Claude and Gemini, DashScope,
NanoGPT Claude),prompt_cache_key(OpenAI, Mistral, Together, Cerebras, DeepInfra, Kimi, and
servers with no documented scheme), session headers (xAI, Fireworks, OpenRouter), or nothing
where the provider caches on its own.SIGIL_PROMPT_CACHE(auto,on,off),
SIGIL_PROMPT_CACHE_TTL(1hby default,5m,24h) and thepromptCachesetting choose the
mode and lifetime for the main agent and all subagents. OpenAI'sprompt_cache_retentionis sent
only to the models OpenAI lists for it. See "Prompt caching" in the README. SIGIL_PROMPT_CACHE_PROVIDERnames the provider whose cache rules and prices apply to a server
Sigil does not recognise by its host, such as a local server on another port, a proxy or a
custom domain. A known host keeps its own rules. An unknown name is reported once and ignored.- Explicit context caches on the Gemini API and Vertex AI. When the published prices say it saves
money over Google's implicit caching, measured from recent replies, Sigil puts the system prompt
and tool list in acachedContentsresource, renews it while it is in use, and deletes it at
exit and at the end of a session. Caches left by a crashed run are deleted in the background at
the next start-up and at the first use of an endpoint, and only caches named with this install's
id are touched. A failed create, or a request that names a dead cache, goes out without the
cache. Only an error about the cache itself (403, 404, or a 400 that names it) drops it.
SIGIL_EXPLICIT_CACHEandSIGIL_EXPLICIT_CACHE_MAXcontrol it, and/cache list,
/cache deleteand/cache explicitmanage it. Storage cost appears in/cost,/stats, the
status line and OpenTelemetry, counts toward--max-budget-usdand background agents' cost, and
is saved with the session. - Vertex AI access tokens from
SIGIL_GOOGLE_TOKEN_COMMAND(for example
gcloud auth print-access-token), fetched again before they expire. The token used to be read
once from the key setting and stopped working after an hour. - Amazon Bedrock prompt caching. Claude and Nova models on a bedrock-runtime base URL, FIPS
endpoints (bedrock-runtime-fips.<region>.amazonaws.com) included, use the Converse API with
cachePointblocks on tools, system and messages, with 1h for Claude when the TTL is 1h. Nova
caches at most 20,000 tokens, so no Nova cache point is placed past that. Replies stream over
Bedrock's event stream and thinking blocks are kept for tool loops. The effort level reaches
Nova 2 models asreasoningConfig, and a JSON schema goes asoutputConfigstructured output.
A model that answers 400 to it gets the schema as an instruction instead. Auth is a Bedrock API
key (AWS_BEARER_TOKEN_BEDROCK) or AWS Signature Version 4 from the standard AWS variables or
~/.aws/credentials, using only the standard library.SIGIL_BEDROCK_CONVERSE=0keeps the
OpenAI-compatible endpoint. - Cache usage is read from each provider's own fields, among them DeepSeek's
prompt_cache_hit_tokens, DashScope cache writes, Together's top-levelcached_tokens,
SambaNova'scache_creation_tokens, and Fireworks'fireworks-cached-prompt-tokensheader and
perf_metricsin streamed replies. /cacheshows the hit rate and cache tokens and sets the mode or TTL for the session.
/cost,/usage,/stats, the status line JSON and OpenTelemetry records include cache reads,
writes, 1-hour writes and the hit rate. Sessions store 1-hour writes, and older sessions still
load.- Cache reads and 5-minute and 1-hour writes are priced with each provider's published ratio to
the input price: for example reads at 10% on Gemini, Vertex AI and SambaNova and 25% on Bedrock
Nova, and Nova writes at no charge. DeepSeek and Z.ai reads use the cache-hit prices on their
price pages. Gemini 3.6 and 3.8 Flash use the price Google lists for the day of the request (it
doubles on 2027-01-01).--cache-read-cost-per-million,--cache-write-cost-per-millionand
--cache-write-1h-cost-per-millionoverride these prices and are passed to background agents. - Model prices without flags. Sigil reads them from the server's model list where the server
publishes one (OpenRouter, NanoGPT), or from your own table in themodelPricessetting or
SIGIL_MODEL_PRICES(USD per million tokens:input,output,cache_read,cache_write,
cache_write_1h). Prices are looked up again after/model,/profile, a fallback model, a
subagent or background model, andagent-resume --model/--base-url, so each model is priced
as itself. A price set with a flag is kept. /costand/statshave a "Side calls" line, and the status line JSON has
cost.side_cost_usd. Side calls are model calls made outside the main loop, and their cost is
already part of the totals.background_agent_statusshows a finished background agent's input and output tokens and its
cache reads and writes next to its cost.- Hooks in the settings files are re-read on the next hook call after an edit. If a settings file
can't be read, the last good hooks stay in use.SIGIL_HOOKS_RELOAD=0turns this off. - Background agents can run on a different OpenAI-compatible endpoint from the main session. Pass
model: "name@base_url"or a separatebase_url. The key comes fromSIGIL_API_KEY_<HOST>
(for exampleSIGIL_API_KEY_NANO_GPT_COM). The main API key is never sent to another host, and
background_agent_startprints the endpoint it used. Abase_urlmust start withhttp://or
https://, and a model id that contains@but no URL is passed on unchanged. /mcp disableand/mcp enabletake effect from the next message, with no restart. A large server
stops costing its whole tool list at once, and the prompt cache is written again once. A refresh
that changes nothing sends the same tools in the same order, so the cache stays on every provider.
A server name that isn't configured, or one already in that state, says so and changes nothing.
Each change is logged with the server name and tool count only./loop <prompt>with no interval runs the prompt now and lets the agent pick when each next run
happens, from 1 minute to 1 hour, with the reason shown. The agent ends the loop with
schedule_wakeupwhen the task is done. A run that picks nothing gets one fallback run 20 minutes
later, and the loop ends if that run picks nothing too./loop every 10 minutes <prompt>works as
well as/loop 10m <prompt>.- Scheduled prompts are saved with their session and come back when it is resumed. Recurring prompts
older than 7 days, one-time prompts whose time passed while Sigil was closed, and a self-paced loop
whose next run came due while it was closed are not brought back, and Sigil says which ones and
why.SIGIL_LOOP_RESTORE=0restores nothing, andSIGIL_DISABLE_CRON=1turns scheduling off. - Scheduled prompts work with the prompt cache. A run due just as the cache would expire, like a
/loop 5mon a 5-minute cache, starts 15 seconds early so it still reads the cache. The cache
lifetime is worked out for the model in use at each run, so/modeland/profileare followed.
The agent is told how long the cache lasts after it picks a time, and the tool list never changes
while a loop runs. - Recurring prompts and loops end after 7 days, with one final run. A run that came due several
times while the agent was busy runs once.
Changed
- With an anthropic.com base URL, Sigil now uses the native Messages API by default because the
OpenAI-compatible endpoint does not cache prompts.SIGIL_ANTHROPIC_NATIVE=0keeps the old
behaviour. The native client now streams over server-sent events, andSIGIL_ANTHROPIC_STREAM=0
waits for the whole reply. - When a request gets HTTP 400 or 422 and the error names a cache field it carried, or is an
unknown-field error that names no other field, Sigil sends it once more without the cache
fields and sends that endpoint no cache fields for the rest of the session. Any other 400 or 422
is shown at once and not resent. Both cases are logged. /btw, compaction and rewind summaries send the main loop's own tools, system prompt and
messages plus one request message, so they read the conversation's prompt cache and don't write
a new entry.tool_choicestays as it is, since changing it would invalidate the cached
messages on Anthropic. The model is told not to call tools, a tool call in the reply is never
run, and a reply without text is asked for once more before Sigil falls back to the plain-text
transcript.- On servers that take
cache_controlmarkers in the OpenAI format, user, tool and system text is
always sent as one text part, so a message keeps the same bytes after its breakpoint moves on. - Microcompaction moved one old tool result per turn, which rewrote the cached prompt every turn.
While the cache is warm it now moves them in groups ofSIGIL_MICROCOMPACT_BATCH(default 3). - MCP tools are listed in a fixed order (server, then name), so the tool list at the start of
every prompt stays the same whatever order the servers answer in. - Each model call is priced when it is made, at the prices of the endpoint that answered. The cost
used to be recomputed every turn from the session's total tokens at the current prices. read_filewithallow_largereturns at most 240,000 characters (about 60k tokens), down
from 500,000. One full read of a large file could fill most of the context window.- The output one bash command keeps is still 10 times the tool output limit, but now stops at
240,000 characters when that limit is raised.SIGIL_BASH_STREAM_MAX_CHARSstill overrides it. - Sessions now record ho...
Sigil Code 1.0.0
First public release.
Added
Models and providers
- Any OpenAI-compatible endpoint: OpenAI, OpenRouter, DeepSeek, Groq, Together, Anthropic's
compatible endpoint, and local servers (vLLM, Ollama, LM Studio, llama.cpp). - Effort levels (
/effort,/thinking, Alt+T,SIGIL_EFFORT_LEVEL), sent in the field each
provider reads (reasoning_effort,chat_template_kwargs.enable_thinking,thinking). - Optional native Anthropic Messages API (
SIGIL_ANTHROPIC_NATIVE=1) with prompt caching, image
blocks and thinking blocks kept across tool calls. - Context window and vision support read from the server;
<think>blocks removed; tool calls
written as text (Hermes, Qwen3-Coder, JSON) run as real calls. - Provider profiles (
--profile,/profile), fallback models (--fallback-model), an
architect/editor split (--architect,--editor-model), and image input.
Agent loop and context
- Tool loop with parallel tool calls and budgets for turns, tokens, cost and tool calls.
- Auto-compaction, microcompaction of bulky tool results, AST outlines of untouched files,
snipping, and/contextto see token use. - Auto-nudge for stalled turns from weak and local models, and a message sanitizer for strict
providers. - Structured output with
--response-schema-file.
Tools
- 77 built-in tools: files, shell (with background shells), web fetch and search, subagents,
background agents, plans, tasks and todos, teams, LSP code intelligence, MCP, skills, worktrees,
workflows, triggers, config, andcreate_new_tool. - Opt-in tools: scheduled prompts (
cron_*,/loop),memory_save,session_note, and
editor_editin architect mode.
Subagents and background work
- Subagent types (
general-purpose,Explore,Plan, and agents in.sigil/agents/and
~/.sigil/agents/), parallel subagents,isolation: worktree,--agentand--agents. - Background agents (
sigil agent-bg,agent-ps,agent-restart, the agent bar) whose approval
questions appear in the main chat, and background shells (run_in_background,/bashes).
Permissions and folders
- Start read-only;
--allow-write,--allow-shell,--unsafe; permission modes (default,
acceptEdits, plan, bypass, dontAsk) with Shift+Tab; permission rules (allow/ask/deny). - Folder access switches (
SIGIL_OTHER_DIRECTORIES,SIGIL_ALLOWED_DIRECTORIES,--add-dir) and
a write-protected list (SIGIL_PROTECTED_PATHS). - Folder trust for project items a cloned repository can carry (see README, Folder trust).
- An opt-in bash sandbox on Linux (bubblewrap) and macOS (sandbox-exec).
Hooks, MCP and extensions
- Hooks in
settings.json: command, http, prompt, agent and MCP-tool hooks for 31 events. - MCP over stdio, streamable HTTP and SSE: one process per server per session, tools as
mcp__server__tool, prompts as slash commands, elicitation, and OAuth login (/mcp login). - Custom slash commands and skills (
.sigil/commands/,.sigil/skills/), plugin folders
(--plugin-dir), plugin marketplaces with sha / sha256 pins, output styles, custom tools.
Sessions, memory and CLI
- Sessions saved per workspace: resume (
-c,-r,sessions), names, search, fork, export,
sigil purge, and/rewindfor the conversation, the files, or both. - Memory files (
SIGIL.md,SIGIL.local.md,AGENTS.md,.sigil/rules/), plus opt-in auto
memory, session memory and a repo map. - Print mode (
-p) with text, JSON or stream-JSON output;sigil doctor; shell completion;
91 slash commands; type-while-it-works input; Esc to stop; multiline input; prompt history. - Windows support without WSL: Git-Bash path translation,
msvcrtkeyboard input, and a
PowerShell tool. - An always-on error log (
~/.sigil/logs, kept 2 days),--debugrequest logging with secrets
redacted, and opt-in OpenTelemetry logs.
Security
- Folder trust: hooks, MCP servers,
env, a.env, settings that grant more, commands and skills
withallowed-tools, agent hooks, custom tools insrc/custom_tools/, plugin manifests,
pre-set answer files and@importsoutside the folder only apply after you trust the folder
once.denyandaskrules always apply, and a project file never starts bypass mode. - A pre-set answer from
.sigil-ask-user.jsonor.sigil/ask-user.jsonreaches the model
labelled as a pre-set answer from that file, never as something you typed. - Credentials are dropped when an HTTP request is redirected to another origin; OAuth endpoints
must use HTTPS (http only on localhost); the OAuth callback page is not cached and sends no
referrer. - The main API key is sent only to its own server; other hosts use
SIGIL_API_KEY_<HOST>. MCP
servers get neither Sigil's keys nor, by default, the SSH agent socket. - Plan mode checks every command on a shell line (and PowerShell commands) before treating it as
read-only. Permission rules match bash and PowerShell commands alike. - A plugin source listed by a remote marketplace must use HTTPS or SSH; git runs with protocol
limits. - Restarting a background agent rebuilds Sigil's own worker command; a resumed session takes its
folders and permissions from the command line. - Escape sequences in model and tool text are removed before they reach the terminal; tool-result
text is framed as data for the model. - Every security limit can be changed by you: see the security overrides in
.env.example.
Notes
- Requires Python 3.10 or later. Core dependencies:
prompt_toolkitandrich. Optional extras:
pdf,yaml,ast,tokenizers,dev,all.
Install: git clone https://github.com/X-AlphaCoder-X/sigil-code.git, then cd sigil-code and pip install -e .. See the README for the quick start.