GitHub - savant0x/savant-code: Multi-agent orchestration — 9 specialized agents coordinate via ECHO Protocol: Detective finds issues, Forge implements, Verifier audits, Recorder manages FIDs, Thinker reasons, Scout explores, Researcher investigates, Scribe documents.

Savant-Code — Multi-Agent AI Coding Assistant

A terminal-native AI coding assistant that audits every change before it touches your repo.

Built with TypeScript/Bun, governed by the ECHO Protocol, and designed for local-first use with Ollama.

v0.0.36 — local development line, not yet published (npm latest is still v0.0.35). This bump opens the dated heading so post-release work accumulates in one place, per the no-unreleased-accumulators ruling: the researcher-acceptance and lesson-feature-pipeline closures, the managed scratchpad and provider-inventory passes, and everything else that lands before the v0.0.36 cut. Release notes are written here at cut time; nothing in this section ships until then.

Get Started in 30 Seconds

# Install the CLI (npm i savant-code -g is the short form)
npm install -g savant-code

# Run it. If Ollama is running, it will auto-detect and use it.
savant-code

Published as savant-code on npm.

A terminal demo video is not yet available; the landing page and CLI source links below describe the currently verified workflow.

No Ollama yet?

# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh
ollama serve

# Windows: https://ollama.com/download/windows

On Windows, see WINDOWS.md for the bash requirement (Git for Windows / SAVANT_CODE_GIT_BASH_PATH), proxy configuration, and the launcher's version messages.

Then run savant-code again, or type /health inside the chat to verify the connection.

If Ollama is not running, configure a hosted provider before sending a prompt. The CLI boots to OpenRouter by default (openrouter/free free tier) — set a key and you are ready:

/provider openrouter

You can also enter /provider to choose from the interactive picker. Paste the key into the masked prompt; it is stored globally and is never added to chat history. The supported hosted providers are:

Provider	Selection	Environment variable	Notes
OpenAI	`/provider openai` or `DIRECT_PROVIDER=openai`	`OPENAI_API_KEY`	Hosted gateway
OpenRouter	`/provider openrouter` or `DIRECT_PROVIDER=openrouter`	`OR_MASTER_KEY`, `OPENROUTER_API_KEY`, or `INFERENCE_API_KEY`	Default provider; free tier (`openrouter/free`) is the boot default; direct mode without the Savant backend
TokenRouter	`/provider tokenrouter` or `DIRECT_PROVIDER=tokenrouter`	`TOKENROUTER_API_KEY`	Multi-provider gateway
NVIDIA NIM	`/provider nvidia` or `DIRECT_PROVIDER=nvidia`	`NVIDIA_API_KEY`	NVIDIA-hosted inference
AIHubMix	`/provider aihubmix` or `DIRECT_PROVIDER=aihubmix`	`AIHUBMIX_API_KEY`	Hosted gateway
Alibaba Cloud	`/provider alibaba` or `DIRECT_PROVIDER=alibaba`	`DASHSCOPE_API_KEY`	Hosted gateway
Anthropic	`/provider anthropic` or `DIRECT_PROVIDER=anthropic`	`ANTHROPIC_API_KEY`	Hosted gateway
APInex	`/provider apinex` or `DIRECT_PROVIDER=apinex`	`APINEX_API_KEY`	Hosted gateway with an authenticated live model catalog
Apixo	`/provider apixo` or `DIRECT_PROVIDER=apixo`	`APIXOAI_API_KEY`	[OI]-compatible gateway with a keyless live model catalog
Ashna	`/provider ashna` or `DIRECT_PROVIDER=ashna`	`ASHNA_API_KEY`	Hosted gateway
Atria AI	`/provider atria` or `DIRECT_PROVIDER=atria`	`ATRIA_API_KEY`	Hosted gateway
B.AI	`/provider bai` or `DIRECT_PROVIDER=bai`	`BAI_API_KEY`	OpenAI-compatible gateway with an authenticated live model catalog
Baseten	`/provider baseten` or `DIRECT_PROVIDER=baseten`	`BASETEN_API_KEY`	Hosted gateway
BazaarLink	`/provider bazaarlink` or `DIRECT_PROVIDER=bazaarlink`	`BAZAARLINK_API_KEY`	Hosted gateway
Cerebras	`/provider cerebras` or `DIRECT_PROVIDER=cerebras`	`CEREBRAS_API_KEY`	Hosted gateway
ChatAnywhere	`/provider chatanywhere` or `DIRECT_PROVIDER=chatanywhere`	`CHATANYWHERE_API_KEY`	Hosted gateway
Clean APIs	`/provider cleanapis` or `DIRECT_PROVIDER=cleanapis`	`CLEANAPIS_API_KEY`	Hosted gateway
Cloudflare	`/provider cloudflare` or `DIRECT_PROVIDER=cloudflare`	`CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID`	Workers AI gateway; the `/provider` flow prompts for the token, then the account id (env vars take precedence)
CodeCraft API	`/provider codecraft` or `DIRECT_PROVIDER=codecraft`	`CODECRAFT_API_KEY`	Hosted gateway
Cohere	`/provider cohere` or `DIRECT_PROVIDER=cohere`	`COHERE_API_KEY`	Hosted gateway
CommandCode	`/provider commandcode` or `DIRECT_PROVIDER=commandcode`	`COMMAND_CODE_API_KEY`	OpenAI-compatible hosted inference (dual-protocol)
DeepInfra	`/provider deepinfra` or `DIRECT_PROVIDER=deepinfra`	`DEEPINFRA_API_KEY`	Hosted gateway
DeepSeek	`/provider deepseek` or `DIRECT_PROVIDER=deepseek`	`DEEPSEEK_API_KEY`	Hosted gateway
Fireworks AI	`/provider fireworks-ai` or `DIRECT_PROVIDER=fireworks-ai`	`FIREWORKS_API_KEY`	Hosted gateway
Google AI	`/provider google` or `DIRECT_PROVIDER=google`	`GEMINI_API_KEY`	Hosted gateway
Groq	`/provider groq` or `DIRECT_PROVIDER=groq`	`GROQ_API_KEY`	Hosted gateway
HCNSec	`/provider hcnsec` or `DIRECT_PROVIDER=hcnsec`	`HCNSEC_API_KEY`	OpenAI-compatible gateway on an audited static 7-model allowlist
Infron	`/provider infron` or `DIRECT_PROVIDER=infron`	`INFRON_API_KEY`	Hosted gateway
Intern InkStone	`/provider intern` or `DIRECT_PROVIDER=intern`	`INTERN_API_KEY`	Hosted gateway
KiosAPI	`/provider kiosapi` or `DIRECT_PROVIDER=kiosapi`	`KIOSAPI_API_KEY`	OpenAI-compatible gateway (live catalog)
Meta Llama API	`/provider meta` or `DIRECT_PROVIDER=meta`	`META_MODEL_API_KEY`	Hosted gateway
MiniMax	`/provider minimax` or `DIRECT_PROVIDER=minimax`	`MINIMAX_API_KEY`	Hosted gateway
Mistral AI	`/provider mistral` or `DIRECT_PROVIDER=mistral`	`MISTRAL_API_KEY`	Hosted gateway
Moonshot AI	`/provider moonshotai` or `DIRECT_PROVIDER=moonshotai`	`MOONSHOT_API_KEY`	Hosted gateway
Nous Research	`/provider nous` or `DIRECT_PROVIDER=nous`	`NOUS_API_KEY`	OpenAI-compatible direct inference; Portal OAuth is separate
Ollama	Automatic detection	`OLLAMA_HOST` (optional)	Local inference; no API key required
OrcaRouter	`/provider orcarouter` or `DIRECT_PROVIDER=orcarouter`	`ORCAROUTER_API_KEY`	Multi-provider gateway with a live model catalog (free tier currently gated vendor-side on GitHub account linkage)
Perplexity	`/provider perplexity` or `DIRECT_PROVIDER=perplexity`	`PERPLEXITY_API_KEY`	Hosted gateway
Tiarina Cloud	`/provider tiarina` or `DIRECT_PROVIDER=tiarina`	`TIARINA_API_KEY`	Hosted gateway
Together AI	`/provider togetherai` or `DIRECT_PROVIDER=togetherai`	`TOGETHER_API_KEY`	Hosted gateway
TokenBom	`/provider tokenbom` or `DIRECT_PROVIDER=tokenbom`	`TOKENBOM_API_KEY`	OpenAI-compatible gateway on an audited static 7-model allowlist
TokenHarbor	`/provider tokenharbor` or `DIRECT_PROVIDER=tokenharbor`	`TOKENHARBOR_API_KEY`	OpenAI-compatible hosted gateway
UnoRouter	`/provider unorouter` or `DIRECT_PROVIDER=unorouter`	`UNOROUTER_API_KEY`	Hosted gateway
Venice AI	`/provider venice` or `DIRECT_PROVIDER=venice`	`VENICE_API_KEY`	Hosted gateway
Vercel AI Gateway	`/provider vercel` or `DIRECT_PROVIDER=vercel`	`AI_GATEWAY_API_KEY`	Hosted gateway
xAI	`/provider xai` or `DIRECT_PROVIDER=xai`	`XAI_API_KEY`	Hosted gateway
xKiro	`/provider xkiro` or `DIRECT_PROVIDER=xkiro`	`XKIRO_API_KEY`	Hosted gateway
Z.AI	`/provider zai` or `DIRECT_PROVIDER=zai`	`ZHIPU_API_KEY`	Hosted gateway
Custom endpoint	Environment configuration	`INFERENCE_BASE_URL`, `INFERENCE_API_KEY`	Advanced OpenAI-compatible endpoint; authorized by `INFERENCE_API_KEY` alone

CodeCraft and CleanAPIs use authenticated live catalogs. xKiro publishes a live chat catalog; its Anthropic-prefixed IDs use Messages and other IDs use chat. Select the full prefixed ID from /model so vendor namespaces survive routing. The picker supports filtering, keyboard, wheel, and scrollbar navigation; clipped display text does not alter the selected ID.

Agent model information includes reported limits, USD prices, capabilities, catalog tiers, and reasoning efforts. Missing values stay unknown. Catalog membership and tiers do not establish access for your key; xKiro paid models can return an account-access error. See models and metadata for exact IDs, protocol rules, and SDK modelInfoText usage.

The key is persisted at C:\\Users\\<username>\\.savant-code\\credentials.json on Windows or ~/.savant-code/credentials.json on macOS/Linux. Environment variables take precedence over saved credentials. For automation, set one provider key before launching Savant-Code:

# PowerShell — set one provider key (OpenRouter is the boot default;
# any gateway key from the table above works the same way)
$env:OPENROUTER_API_KEY = "your-key"
savant-code

:: Command Prompt — set one provider key (OpenRouter is the boot default;
:: any gateway key from the table above works the same way)
set OPENROUTER_API_KEY=your-key
savant-code

# macOS/Linux — set one provider key (OpenRouter is the boot default;
# any gateway key from the table above works the same way)
export OPENROUTER_API_KEY="your-key"
savant-code

Bring your own provider (custom providers)

Any OpenAI-compatible endpoint can become a first-class provider — no code, no fork. Run /provider add and answer the prompts:

/provider add

The wizard asks for an id (lowercase, 2–32 chars — it becomes the routing prefix for the provider's models), a display label, the API base URL, an API key name, an optional model list, and finally the API key itself (masked; stored locally like any built-in key). Afterwards the provider appears in /provider and /provider list like a built-in, and its models are selectable with the id/model prefix.

Manage custom providers with:

Command	Effect
`/provider add`	Add a custom OpenAI-compatible provider (wizard)
`/provider edit <id>`	Edit a custom provider (id is fixed; Enter on the key prompt keeps the stored key)
`/provider list`	List built-in and custom providers with configured markers
`/provider remove <id>`	Remove a custom provider (built-ins cannot be removed)

Removing the active provider resets the selection to the default. Model selection always works through /model <exact-id> even without a catalog (e.g. /model my-gateway/model-a); the id/model form routes through your endpoint.

OpenRouter direct mode

OpenRouter is the default boot provider (free tier openrouter/free); any openrouter/ model slug routes to https://openrouter.ai/api/v1 with the resolved key. To bypass the Savant Code backend and route inference directly to OpenRouter, set:

export DIRECT_PROVIDER=openrouter
export INFERENCE_BASE_URL=https://openrouter.ai/api/v1

OpenRouter key resolution is ordered as follows:

OR_MASTER_KEY — exchanges for a regular key through OpenRouter /api/v1/keys.
OPENROUTER_API_KEY — uses an existing regular OpenRouter key directly.
INFERENCE_API_KEY — uses the SDK-specific inference key.

Cloudflare Workers AI integrations use CLOUDFLARE_API_TOKEN together with CLOUDFLARE_ACCOUNT_ID — /provider cloudflare prompts for both (or set the env vars directly). Nous Research uses /provider nous or NOUS_API_KEY for direct OpenAI-compatible inference; Nous Portal OAuth is a separate integration and is not part of this provider. Ordinary CLI users should use /provider or one of the provider-specific keys above. Do not create a project-local .env file or edit credentials.json manually.

Overview

Savant-Code is a TypeScript monorepo that builds and ships the terminal-native AI coding assistant Savant Code and the public @savant-code/sdk. The CLI provides multi-agent orchestration, custom skills, MCP tool discovery, mode switching (HYBRID / SCAFFOLD / STRICT / ANALYZE), and local-first Ollama support. The SDK, agent runtime, multi-agent orchestration engine, tool layer, and LLM provider shims are shared so both surfaces ship from one codebase.

The whole project ships under ECHO Protocol v0.2.0 — the same 15-law agent discipline that governs the Savant ecosystem. Every change goes through the RED → GREEN → AUDIT → ADVERSARIAL → SELF-CORRECT → COMPLETE Perfection Loop FSM, with a hard 10-iteration cap and a 10% Levenshtein change-cap per pass.

Key Technologies

Layer	Tech	Version
Runtime	Bun	1.3.14 (exact runtime and package-manager pin)
Language	TypeScript	5.5.4 (`strict: true`, `noImplicitReturns: true`)
TUI	OpenTUI + React 19	`@opentui/core` 0.5.3, `react` ^19.0.0
State	Zustand + Immer	zustand ^5.0.8, immer ^10.1.3
Validation	Zod	^4.2.1
LLM SDK	Vercel AI SDK	`ai` ^5.0.52 + `@ai-sdk/anthropic` 2.0.50
MCP	Model Context Protocol	`@modelcontextprotocol/sdk` ^1.18.2
Code parsing	tree-sitter (WASM)	`@vscode/tree-sitter-wasm` 0.1.4
HTTP / WS	ws, node-fetch, custom SDK client	ws ^8.18.0
Package manager	Bun workspaces (hoisted)	`bunfig.toml` `[install] linker = "hoisted"`

Features

CLI (`@savant-code/cli`)

Multi-agent orchestration — 10 specialized agents coordinate via ECHO Protocol: Detective finds issues, Forge implements, Verifier audits, Adversary refutes the audit, Recorder manages FIDs, Thinker reasons, Scout explores, Researcher investigates, Scribe documents.
Thinker with sequential thinking — the Thinker agent accumulates stacked reasoning steps via sequentialthinking, converges to a typed non-null FinalArtifact (status/synthesis/payload/metrics/thoughts), and never returns a null or empty result.
Native tool-call hardening — fail-closed streaming boundary for incomplete/malformed/truncated tool calls; stale-fragment replacement for placeholder arguments; permissive coercion of stringified numbers/booleans before strict Zod validation.
Tool permission boundary — strict allowlist-based tool provisioning via filterToolSet; restricted agents (Thinker, Scout) never receive parent-only tools; executor authorization unchanged.
/init command — scaffolds .agents/types/{agent-definition,tools,util-types}.ts and a starter knowledge.md.
Slash commands — /new, /history, /bash, /goal, /loop, /feedback, /rewind, /theme:toggle, /logout, /exit, plus agent-specific commands.
Provider setup — /provider opens an interactive dropdown picker showing all providers with ✓/✗ configuration status. Select a provider to enter its API key (masked input). Keys stored in local credentials.json.
Research (keyless by default) — web_search, read_docs, and deep_research work with zero keys: web search falls back to a keyless Qwant + DuckDuckGo port, and read_docs builds a self-populating local SQLite docset cache (~/.savant-code/docsets/) with 7-day TTL + keyless version-aware freshness. Optional Bring-Your-Own-Key sources (Serper, Context7, Parallel, Tavily, Exa, Firecrawl) via /research-keys <service> (masked, saved to credentials.json) or the matching *_API_KEY environment variables. See features.md.
Self-improving harness & agent-created skills — Savant captures its own tool failures mechanically (in-process hook, no prompt compliance), promotes recurring patterns into canonical rules and versioned skills, and lets the operator trust or reject everything it authors. skill_manage (Scribe + Orchestrator) authors skills into .quarantine/ with on-disk versioning (versions/ + VERSIONS.jsonl); /skills list|show|trust|untrust|rollback is the operator-only release boundary; immutable: true skills reject every mutation; SessionEnd review, lessons→skills drafts, LEARNINGS retirement, and the evolution ritual run as bun run session-end:review|lessons:to-skills|learnings:retire|skills:evolve. Full guide: docs/self-improving-harness.md.
Telemetry controls — /telemetry status|enable|disable toggles remote analytics and error reporting. Remote analytics is enabled by default in the main CLI but remains user-disableable; local logs remain available when it is disabled. Contextual ads are separate: ads are disabled by default in the main CLI and can be controlled independently where available.
Discord Rich Presence (/presence) — enabled by default; externalize the active agent, ECHO phase, project basename, and model to Discord with a mechanical privacy boundary (paths, arguments, FID titles, and search queries redacted; fail-closed Zod fallback). /presence status | enable | disable (the client id is hardcoded to the Savant Discord application).
@filename and @AgentName mentions — file and agent mentions with inline autocomplete.
Bash mode — !command or /bash to run shell commands inline (with confirmation).
Permission and sandbox controls — --permission-mode safe|prompt|unsafe sets the startup policy, while /permissions (aliases /sandbox and /safety) shows or changes it during a session. safe denies risky tools; prompt currently also denies risky tools because interactive confirmations are not yet implemented, and unsafe allows them explicitly. Use unsafe only when you understand the command risk.
Durable budgeted goal mode — /goal <objective> [--budget tokens=N turns=N time=MS] starts a durable, budgeted goal run: an event-sourced goal state machine (active | paused | blocked | complete) with token/turn/wall-clock budgets and a runtime continuation driver that runs goal turns until the model verifies completion (update-goal), blocks on a genuine impasse, or a budget is exhausted. Goal text is injected as <untrusted_objective> (data, never instructions); /goal status|pause|resume|cancel manage the record and the sidebar shows live goal + budget consumption.
Auto Drive (/auto-drive) — clarify → plan → approve → run-to-completion autonomous execution that decomposes the plan into a FID backlog, runs it in dependency order, and certifies completion. Aliases /auto, /drive, /autodrive; subcommands status | pause | resume | stop; headless via --auto "<goal>". See the [Auto Drive blueprint](docs/design/Auto Drive Architecture Blueprint.md) and the FAQ.
Goal loop — /loop <cadence> schedules recurring prompt execution (e.g., /loop 5m check build status). The loop scheduler manages cadence, run counts, and convergence detection.
Extensible hook system — a project-scoped hooks: block in protocol.config.yaml runs external commands (or internal callbacks) at the tool-executor lifecycle (PreToolUse/PostToolUse/PostToolUseFailure plus session/subagent events). Hooks compose with the EHEL gate (an additional gate, never a bypass) and fail open: only an explicit deny decision or exit code 2 blocks a tool.
Structured planning and review — /interview turns an underspecified request into a structured specification, /plan creates an implementation plan, and /review opens a focused code-review workflow.
In-chat verification — /verify runs the four supported core workspace typechecks, or target one with /verify sdk, /verify common, /verify agent-runtime, or /verify cli. /diagnostics reports local process/resource information.
Conversation utilities — /copy (alias /copy-chat) copies the full conversation to the clipboard, /export (alias /save) writes a fully self-contained branded HTML report of the conversation to disk, while /image (aliases /img and /attach) attaches an image when the selected provider supports multimodal input.
Agent publishing — /publish opens the agent publishing flow for templates with the required publisher metadata. It requires the Savant Code backend rather than direct-provider mode.
Mode switching — HYBRID / SCAFFOLD / STRICT / ANALYZE execution-scope modes with hover descriptions, togglable at runtime via UI. See Execution Modes for the STRICT-vs-HYBRID ceremony contract.
Streaming & cancellation — token-by-token SSE streaming with mid-stream cancellation, retry-with-backoff, and subagent streaming for parallel work.
Knowledge files — project-level knowledge.md plus per-user home-dir knowledge, auto-loaded into agent context.
Skills — OpenClaw-format SKILL.md files discovered at startup, schemas sent to the LLM, available as native tools.
Loadable design-system library — the offline savant-design-systems skill ships 74 approximately 2 MB presets with deterministic manifests and provenance. Use /design list, /design use <id>, /design current, /design create, /design edit, /design import, /design validate, /design drafts, /design resume, /design discard, and /design reset; only the active contract enters agent context. Custom systems are validated, versioned, reloadable, and scanned at the EHEL write boundary. Headless authoring accepts --design-input <path|->. See the design-system library guide for the architecture, authoring lifecycle, security model, persistence contract, enforcement behavior, and packaging evidence. For live usability, agent-feedback, and latency validation, run the design-system live test prompt. For a complete regression across the current feature domains, run the v0.0.25 harness A–Z live-test prompt, which writes an evidence report to dev/scratchpad/az-v0.0.25-harness-live-test-report.md.
MCP tools — Model Context Protocol servers discovered at startup, schemas published to the LLM API.
deep_research tool — the Researcher role's mechanical multi-query web research tool (question + model-supplied queries[], research_depth, max_sources): max-3 concurrency, ≥1s query stagger, URL dedup, domain scoring, citations + gaps + truncated/incomplete flags. Pure search facade over the harness web-search API — no second LLM (FID-2026-0804-002).
github infra helper — read-only GitHub integration (PR/issue/CI review, code search, secret scanning) via the official remote-HTTP MCP server, with Authorization: Bearer $SAVANT_CODE_GITHUB_TOKEN interpolation (FID-2026-0804-003).
database infra helper + 4 native tools — list_tables, describe_table, execute_query, analyze_query over bun:sqlite with an adapter-enforced safety contract: read-only default, LIMIT injection, SQL redaction, destructive-DDL block, JSON-safe BLOB/bigint coercion (FID-2026-0804-004).
Browser-use param upgrades — viewport (mobile/tablet/desktop), wcag (offline DOM-walk accessibility scan, no CDN), and persistSession (default OFF) on the browser automation helper (FID-2026-0804-005).
Self-contained /export — writes the whole conversation to a branded, offline HTML report (Savant logo + Neon Slate theme + Font Awesome inlined as base64; zero network requests) with collapsible tool/thinking rows and per-message / copy-all buttons (FID-2026-0804-007).
Codebase knowledge graph — deterministic, incremental, SQLite-backed graph built on packages/code-map (tree-sitter) with sha256 diffing, IMPORTS/CALLS/EXTENDS edges, and seeded Louvain domain clustering. /graph refresh re-indexes on demand; Detective/Scout query blast radius, node edges, and domain clusters via read-only native tools; the Verifier's Law 4 reachability check is harness-computed and injected into its message history (zero-tool contract unchanged); /graph-export writes a branded, fully-offline interactive HTML report reusing the /export design system (FID-2026-0806-002).
ECHO Harness Enforcement Layer (EHEL) — structural enforcement of all 15 ECHO laws at the tool-executor level. Pre-write gates block violations before they happen (Law 1: read-before-touch, Law 3: verify-before-proceed, Law 7: search-before-create, Law 8: log-intent, FID Recorder gate above 100 lines). Post-write scanners batched at turn end (Laws 5, 6, 9, 10, 12, 14, 15). Law 4 call-graph reachability at turn end. FID completeness validator with mandatory Unanswered Questions. Mode-driven: Hybrid = Laws 1-4 blocking + Laws 5-15 advisory; Strict = all 15 blocking. Only 2 agents have write tools (Orchestrator + Recorder). Emergency bypass: agent requests, user confirms (FID-2026-0805-007).
Harness ECHO compliance layer — deterministic Law 1 (read-before-write), Law 3 (verify-after-write), and mechanical Verifier-criteria enforcement (10+ lines / 2+ files / new API / security-sensitive / Forge) via a per-run runtime tracker: non-blocking compliance_warning receipts plus corrective steering so the running agent self-corrects, escalated to always-on when a write touches an active FID (FID-2026-0804-009).
Zero-Trust Agentic Provenance (ZTAP) — optional, hash-only, per-role Ed25519-signed write receipts at the native write boundary; append-only session ledgers; signed Verifier/Adversary verdict bindings; /attest offline JSON and HTML receipts; an independent clean-process validator; and a read-only live Trust Matrix. Configure provenance.mode as off, record (default), or enforce. ZTAP proves recorded mechanical process and its integrity, not LLM independence. See the ZTAP feature guide.
Agent-Steering Teacher (/learn) — a local-first way to practice directing and reviewing an AI coding agent. /learn start <steering> drives a live exercise: the steering constraint goes to a read-only teacher-forge agent, the produced solution runs in a capability-sandboxed subprocess, and behavior-first equivalence + deterministic mutation-detection graders review it before you submit a critique of a seeded defect. Versioned local progression is recorded with an honest ZTAP process-evidence receipt and surfaced via /learn progress and a live, read-only sidebar panel. See the teacher guide.
Readable edit diffs — edit blocks tint added lines 50% neon green and removed lines 50% neon red (blended against the theme background) and show a [-N/+M] add/remove counter beside the copy button (FID-2026-0804-010).
Context compaction — 4-layer progressive auto-compaction: L0 (summarize old turns), L1 (compress tool results), L2 (prune stale context), L3 (aggressive reduction). Preserves critical context while reducing token usage. A live in-stream signal (⚙ Compacting context… → ✓ Compaction complete (−N tokens)) and a window-consistent sidebar Compaction row give real-time visual feedback instead of silent compaction. A single trigger authority (same verdict that fires the warning) drives the pruner spawn, and /compact forces an on-demand compact-and-stop pass.
Context window resolution — gateway models (e.g. tokenharbor/mimo-v2.5) resolve their real context length from the OpenRouter catalog at runtime.
Universal copy buttons — hover-to-copy on code blocks, tool outputs, and file diffs throughout the TUI.
Gateway providers — OpenRouter, TokenRouter, TokenHarbor, NVIDIA NIM, CommandCode, Nous Research, KiosAPI, APInex, OrcaRouter, B.AI, HCNSec, TokenBom, Infron, Intern InkStone, ChatAnywhere, Tiarina Cloud, UnoRouter, BazaarLink, Atria AI, OpenAI, Vercel AI Gateway, Clean APIs, CodeCraft API, Mistral AI, Apixo, Ashna, AIHubMix, xKiro, and Cloudflare Workers AI via @savant-code/llm-providers. First-party routes include Alibaba Cloud, Anthropic, Baseten, Cerebras, Cohere, DeepInfra, DeepSeek, Fireworks AI, Google AI, Groq, Meta Llama API, MiniMax, Moonshot AI, Perplexity, Together AI, Venice AI, xAI, and Z.AI. Nous Research uses the direct OpenAI-compatible API; Portal OAuth is a separate integration.
Default model — openrouter/free via OpenRouter (configurable via /model). One model project-wide: the model selected in the UI panel is the only model used — main chat agent, teacher-forge, headless runs, and spawned subagents all resolve the operator's active model (never a hardcoded paid fallback).
Headless / non-interactive mode — savant-code --print "<prompt>" runs a single prompt without the TUI and prints the final answer to stdout. Exit codes: 0 success, 1 error or timeout, 2 usage error. When stdin is piped or the environment is CI, the CLI auto-enters headless mode and uses stdin as the prompt. SAVANT_CODE_RUN_TIMEOUT_MS (default 10 minutes) bounds hung runs (FID-2026-0806-011). With --print ... --json, stdout carries NDJSON delegation frames (progress, one artifact, errors) and parent control frames (cancel/steer) are read on stdin — the Savant parent→child delegation transport (FID-2026-0907-003..006).
Consent-gated auto-update — the launcher never stops a running session: a newer version is staged and applied on the next launch after a y/N prompt. SAVANT_CODE_NO_AUTO_UPDATE=1 opts out entirely (FID-2026-0806-014).
Theming — light/dark toggle (/theme:toggle), Neon Slate aesthetic.
Sidebar folding — right-sidebar sections and FID cards start collapsed for a compact first render; click to expand.
Full command surface — the primary slash-command families are documented in the reference below; advanced commands remain available through the registry and autocomplete.
Checkpoint & Rewind — one persistent checkpoint per user turn records the pre-edit content of every file first touched (including subagent writes) plus the conversation boundary; /rewind opens a picker to restore code only, conversation only, both, or fork a new session from an earlier turn — no git required. Retention is bounded to the most recent 20 turns, and terminal side effects are never rewound.

Export Workflows: Conversation Reports and Code Universe

Savant-Code has two separate export features. They create different HTML artifacts for different jobs:

Command	What it exports	Use it when
`/export` (alias `/save`)	The current chat transcript	You want to preserve or share the agent session, tool calls, edits, and final answer
`/graph-export` (aliases `/graph:export`, `/gexport`)	The indexed repository as an interactive Code Universe	You want to explore, present, or share a visual offline snapshot of the codebase

Both reports are self-contained branded HTML files. They can be opened directly from file:// without a hosted service, local web server, project checkout, or runtime API connection.

`/export`: save the conversation

/export is a session report, not a plain-text dump. It captures the current conversation with the character logo, Neon Slate styling, session metadata, user/Savant/error rows, rendered Markdown, tool inputs and outputs, nested subagent blocks, plans, thinking sections, ask-user answers, and attachment notes. Tool and reasoning details remain collapsible, while each message has a Copy action and the header provides Expand all, Collapse all, and Copy all controls.

/export
/save
/export reports/session-review.html

/save is an alias. Without a custom path, the CLI creates and reuses this single rotating file:

dev/exports/conversation/savant-export.html

Relative paths resolve from the current working directory; absolute paths are honored. The command reports the message count, resolved output path, and artifact size after a successful write. An empty conversation produces a system message and no file; filesystem errors are reported in the chat.

The report HTML is escaped and self-contained. Font Awesome CSS/webfonts are inlined, and clipboard actions use a secure Clipboard API when available with a file://-compatible fallback otherwise. The report does not re-run tools, reconnect to a provider, or update when the repository changes. It is a static record of the decision trail: what was asked, what the agent did, which files changed, and what the final answer was.

The screenshot shows the local report's branded header, session metadata, global expand/collapse/copy controls, transcript rows, collapsible execution blocks, and per-message copy affordances. The exact session ID, timestamp, message count, and content vary for each export. See the full conversation export guide for the detailed rendering, safety, and sharing notes.

The three visuals below are intentionally for /graph-export, not the conversation transcript report.

`/graph-export`: explore the offline Code Universe

/graph-export is a repository report, not a conversation transcript. It serializes the local knowledge graph into a spatial, interactive HTML browser called the Code Universe.

First build or refresh the structural index:

/graph refresh
/graph refresh --full

The first refresh builds .savant/graph.db; later refreshes hash-compare files and re-parse only changed files. The database is regenerable, Git-ignored, and not itself shipped in the report.

Then generate the report:

/graph-export
/graph:export
/gexport
/graph-export reports/code-universe.html

The default output is a single rotating file at dev/exports/graph/savant-graph.html. A custom relative or absolute path is honored. During a larger export, the CLI shows stages for index refresh, graph serialization, layout, document embedding, compression, HTML assembly, and file writing instead of appearing frozen.

What the Code Universe includes

Universe view: a Sigma.js/Graphology WebGL canvas for systems, files, corridors, clusters, ambient space effects, and the Savant character mark.
Ranked search: search paths, systems, folders, and files using an export-time index; results appear below the search field and support mouse and keyboard selection.
Drill-down navigation: expand the systems sidebar into nested folders and files, open a folder in the center browser, or select a file directly.
Document viewer: open embedded text documents, validated raster images, or a clear unavailable/binary fallback without reading from disk after export.
Details and connections: inspect paths, metadata, clusters, directions, edge types, related objects, and copyable full paths.
Window controls: drag panels, minimize them to a taskbar-style dock, maximize, restore, or close them independently.
Document controls: copy text, toggle line wrapping, inspect bracketed line/byte metadata, use breadcrumbs, and move through previous/next sibling files.
Offline behavior: Sigma.js, Graphology, fonts, icons, branding, graph data, and enabled document payloads are embedded; no CDN or runtime network request is required.

Code Universe visual tour

The universe overview turns systems and file relationships into a navigable map. Select a system to enter its orbit, use search to jump to a path, or expand the left navigation tree to drill down into folders.

Raster documents open inside the same branded viewer. Supported PNG, JPEG, GIF, and WebP files are validated before embedding; unsupported, malformed, or unsafe media receives an explicit fallback instead of being silently misrepresented.

Text documents open with readable source presentation, path breadcrumbs, line and byte metadata, copy support, wrapping controls, and sibling-file navigation. The source is embedded in the report, so the viewer remains useful offline.

Document and privacy model

The graph index stores structural metadata—paths, symbols, hashes, edge types, and clusters—not a live server or an external copy of the repository. The HTML report is a snapshot and should be regenerated after source changes.

Text documents are embedded by default for the graph report. Positive limits can be supplied for smaller artifacts; binary content and unsupported media remain protected by format, signature, containment, and media-size checks. Useful controls include:

SAVANT_GRAPH_EXPORT_DOCUMENTS=0
SAVANT_GRAPH_EXPORT_NO_PREVIEW=1
SAVANT_GRAPH_EXPORT_PREVIEWS=1
SAVANT_GRAPH_EXPORT_DOCUMENT_LINES=<positive integer>
SAVANT_GRAPH_EXPORT_DOCUMENT_BYTES=<positive integer>
SAVANT_GRAPH_EXPORT_DOCUMENT_IMAGE_BYTES=<positive integer>
SAVANT_GRAPH_EXPORT_TOTAL_TEXT_BYTES=<positive integer>
SAVANT_GRAPH_EXPORT_TOTAL_MEDIA_BYTES=<positive integer>

SAVANT_GRAPH_EXPORT_DOCUMENTS=0 disables document bodies. Previews are off by default; SAVANT_GRAPH_EXPORT_PREVIEWS=1 opts into small details-panel previews, while SAVANT_GRAPH_EXPORT_NO_PREVIEW=1 is the hard-off switch. The remaining variables apply positive per-file or aggregate caps. A document that cannot be read safely is represented as unavailable rather than replaced with misleading content.

Use /export for the conversation and /graph-export for the repository. They work well together: the first preserves the reasoning and implementation trail, while the second preserves the visual codebase artifact that the session examined. See the full Export Workflows guide for detailed usage, troubleshooting, and the offline architecture.

Desktop (`@savant-code/desktop`)

Native shell — Tauri v2 workspace with a Rust supervisor that owns the Bun-compiled agent-runtime sidecar lifecycle (spawn/backoff/shutdown/watchdog) and hosts the React 19 renderer. See desktop/README.md.
Structured chat surface — the same engine, no terminal: bounded transcript virtualization, markdown message blocks with per-message copy, traffic-light status panels, phase stepper, and the Auto Drive dashboard with Emergency Halt.
Command deck (3D) — a neon-noir agent office rendered with R3F where the 10-agent robot cast mirrors live chat activity in real time: agents walk to tool stations while calls run, speech bubbles track the conversation, and a mini-chat island lets the operator message the agent without leaving the deck.
Project FIDs rail — a live view of the repo's FID queue over the gateway (authoritative diff-baseline inventory + watcher updates).

SDK (`@savant-code/sdk`)

SavantCodeClient class — single entry point for running agents from any Node.js / Bun / browser app.
Streaming events — handleEvent callback receives RunState updates, tool calls, file diffs, and final output.
Custom agents — pass agentDefinitions: AgentDefinition[] to override defaults.
Custom tools — pass customToolDefinitions to extend the tool registry.
Cancellation — AbortSignal propagates through subagent streams.
Checkpoint API — the persistent checkpoint store (openTurn, captureSnapshot, closeTurn, listTurns, restoreTurn, forkFrom) is re-exported from the SDK, so hosts can checkpoint and rewind any run; checkpointDir/checkpointTurnId run options thread the turn boundary into subagent writes.

Agent Runtime (`@savant-code/agent-runtime`)

LLM-agnostic — calls any provider registered with @savant-code/llm-providers (OpenAI-compatible chat, Anthropic, etc.).
Multi-step loop — model decides tool → tool executes → result fed back → repeat until end_turn or budget exhausted.
Tool registry — built-in (read_files, write_file, run_terminal_command, code_search, web_search, spawn_agents_inline, …) + custom + MCP.
Cost aggregation — per-call token counts and USD cost estimates surfaced in RunState.
Turn checkpoints — the write-gate in executeToolCall captures pre-edit content before write_file/str_replace/apply_patch dispatch; subagent writes inherit the parent turn via spawn context.

ECHO Protocol Integration

10 specialized agents — Orchestrator, Detective, Forge, Verifier, Adversary, Recorder, Thinker, Scout, Researcher, Scribe
FID-Bound Execution — Code is never written until the FID converges
Perfection Loop FSM — RED → GREEN → AUDIT → ADVERSARIAL → SELF-CORRECT → COMPLETE
Separation of Duties — The agent that writes code cannot verify it
15 Laws — 4 immutable process + 11 extended code laws

Execution Modes

The mode toggle (bottom-left of the chat) sets the execution scope for the current session. Modes are switchable at runtime from the UI or with the /mode slash commands — the bare form lists every mode and its contract, while /mode <name> or /mode:<name> switches (e.g. /mode strict); hovering the toggle shows each mode's one-line contract.

Mode	Agent	Contract
`HYBRID` (default)	`savant`	Direct, low-friction writing bounded by the harness: deterministic Law 1/3 + Verifier-criteria receipts at `warn`, with the full Perfection Loop auto-escalating past the 100-line ceremony threshold; anything above that routes through the Recorder for the FID.
`SCAFFOLD`	`savant-scaffold`	Umbrella-FID project initialization; scaffolds once, then hands back to HYBRID.
`STRICT`	`savant-strict`	Full ECHO ceremony for every code change — FID per change, Forge writes, Verifier audits, Law-4 greps.
`ANALYZE`	`savant-analyze`	Read-only: search, inspect, and reason without writing files.

STRICT mode: the full ceremony, on every change

STRICT is the guaranteed-ceremony mode. Where HYBRID allows the agent to escalate to the full loop (and the harness warns when the criteria are met), STRICT requires it for every code change. Enforcement is the STRICT prompt contract itself — the harness compliance layer watches alongside it and emits warn-level receipts when a criterion is missed (hard blocking is deferred future work). In STRICT, the prompt contract mandates, for each change:

Recorder creates a FID for the change (dev/fids/FID-YYYY-MMDD-NNN-{title}.md), tracked automatically in the sidebar's Active FIDs panel.
RED (Detective) analyzes the codebase and converges the change plan.
GREEN (Forge) writes the code — the only agent allowed to write during a ceremony pass.
AUDIT (Verifier) double-audits the result: run the tests, check the call graph, and Law-4 reachability greps (grep the production entry points to prove the new wiring is actually called).
Recorder archives the FID and appends the CHANGELOG entry.

No self-verification and no phase-skipping: the agent that writes code cannot verify it. Pure read-only Q&A (questions, explanations, analysis with no file writes) stays ceremony-free even in STRICT.

STRICT vs HYBRID: which should I use?

Consideration	`HYBRID`	`STRICT`
Speed	Fastest — write freely; the full loop auto-engages past 100 lines	Slower — every change pays the full loop
Friction	Minimal — the harness warns + steers, never blocks	Maximal — ceremony is required, not optional
Audit trail	FIDs only for escalated changes	A FID per change, archived with a CHANGELOG entry
Verification	Harness receipts at `warn` + self-escalation past 100 lines	Verifier + Law-4 greps on every change
Best for	Day-to-day building, exploration, prototypes, quick iterations	Security-sensitive or long-lived code, paid-API surfaces, team review, anything needing a durable audit trail

Rule of thumb: if a change would hurt to get wrong — auth, payments, migrations, anything shipping to users — use STRICT. If you are exploring or iterating quickly, HYBRID is the right default: the harness still watches Law 1/3 and the Verifier criteria, and the full loop still engages past the 100-line threshold.

Repo Map

Workspace	Package	Purpose
`agents/`	`@savant-code/agents`	Public agent definitions shipped with the CLI
`cli/`	`@savant-code/cli`	CLI source — UI, commands, state, hooks, OpenTUI/React components
`common/`	`@savant-code/common`	Shared types, tool definitions, utilities
`evals/`	`@savant-code/evals`	ECHO-native benchmark v2 runner + legacy eval fixtures
`packages/agent-runtime/`	`@savant-code/agent-runtime`	Agent loop, tool executor, LLM API integration
`packages/design-systems/`	`@savant-code/design-systems`	Offline design-system presets and visual contracts
`packages/code-map/`	`@savant-code/code-map`	tree-sitter code indexing, language detection
`packages/database/`	`@savant-code/database`	Database abstraction layer
`packages/knowledge-graph/`	`@savant-code/knowledge-graph`	Deterministic codebase knowledge-graph engine (indexer, queries, clustering, export serializer)
`packages/llm-providers/`	`@savant-code/llm-providers`	Public LLM provider shims
`packages/connectors/`	`@savant-code/connectors`	Connector layer — catalog + connector tool meta-family
`sdk/`	`@savant-code/sdk`	Public SDK — `SavantCodeClient`, types, build + verify scripts
`desktop/`	`@savant-code/desktop`	Tauri v2 desktop shell — sidecar supervisor + React renderer
`scripts/tmux/`	`@savant-code/tmux-scripts`	tmux CLI helpers used in interactive test runs

Quick Start

1. Clone and Install

git clone https://github.com/savant0x/savant-code.git
cd savant-code
bun install --frozen-lockfile

2. Run the CLI (development)

# Run the CLI in dev mode
bun run dev

# Or run with a specific permission mode
bun run dev -- --permission-mode safe

3. Build for Release

# Build the SDK
bun run build:sdk

# Build the CLI binary from the CLI workspace
bun run --cwd=cli build:binary

Reproducible clean-Linux workflow

The repository pins Bun 1.3.14 in .bun-version, package.json, and the container image. For a native Debian 12+/Ubuntu 24.04+ setup, install the prerequisites and the pinned runtime first (other distributions need equivalent packages):

sudo apt-get update
sudo apt-get install -y build-essential ca-certificates curl git unzip python3 nodejs npm \
  pkg-config libfontconfig1-dev libgif-dev libjpeg-dev libpango1.0-dev \
  librsvg2-dev libsqlite3-dev
curl -fsSL https://bun.sh/install | bash -s "bun-v1.3.14"
export PATH="$HOME/.bun/bin:$PATH"

Then, from a clean Linux checkout, run:

git clone https://github.com/savant0x/savant-code.git
cd savant-code
test "$(bun --version)" = "1.3.14"
bun install --frozen-lockfile
bun run ci
bun run test
cp .env.example .env.local
bun run dev

Edit .env.local with a provider key when using a hosted provider, or configure the local Ollama endpoint instead. .env.local is ignored by Git; .env.example contains placeholders only.

The same build and runtime are available in Docker. The image installs the native Linux libraries required by the workspace dependencies, installs from the committed lockfile, and runs the development CLI:

docker build --tag savant-code:local .
docker run --rm savant-code:local bun run test
docker run --rm --interactive --tty savant-code:local

To pass local settings into the container, use the ignored file created above:

docker run --rm --interactive --tty --env-file .env.local savant-code:local

The container runs the terminal CLI as the unprivileged bun user. The image also includes digest-pinned Node 22.20.0 and npm for release-wrapper tests. does not build the optional Tauri desktop application. For Ollama running on the Linux host, add --network host and set OLLAMA_HOST in .env.local. Keep only the credentials for your chosen provider in that local file; remove unused dummy keys, especially OR_MASTER_KEY, which takes precedence over OPENROUTER_API_KEY. Environment files and local credential/backup state are excluded from the Docker context.

Normal fast-forward pushes to main happen automatically under the standing operator authority. Release actions—version cuts, tags, publishing, deployment, and release artifacts—still require explicit approval. The repository .githooks/pre-push hook remains active for every push, including its no-attribution scan and configured verification gates.

4. Use the SDK

import { SavantCodeClient } from '@savant-code/sdk'

const client = new SavantCodeClient({
  cwd: '/path/to/your/project',
  onError: (err) => console.error('Savant-Code error:', err.message),
})

const result = await client.run({
  agent: 'savant',
  prompt: 'Add error handling to all API endpoints',
  handleEvent: (event) => console.log('Progress', event),
})

5. End-User Install

# npm
npm install -g savant-code

6. Use with local Ollama (zero API key)

If you have Ollama installed and running, Savant Code auto-detects it on first launch and routes inference to your local daemon — no API key, no account, no prompts.

# Start Ollama in the background, then run the CLI
ollama serve
savant-code

Run /health inside the chat to verify the Ollama connection, available local models, and current permission mode.

Configure a hosted provider key

If Ollama is not running, Savant-Code needs a provider API key for the selected model. The boot default is OpenRouter's free tier (openrouter/free), so /provider openrouter is the fastest path. Use /provider for the interactive picker or choose one directly:

/provider openai
/provider openrouter
/provider tokenrouter
/provider tokenharbor
/provider nvidia
/provider commandcode
/provider nous
/provider kiosapi
/provider apinex
/provider orcarouter
/provider bai
/provider atria
/provider hcnsec
/provider tokenbom
/provider infron
/provider intern
/provider chatanywhere
/provider tiarina
/provider unorouter
/provider bazaarlink
/provider vercel
/provider cleanapis
/provider codecraft
/provider xkiro
/provider mistral
/provider apixo
/provider aihubmix
/provider ashna
/provider alibaba
/provider anthropic
/provider baseten
/provider cerebras
/provider cohere
/provider deepinfra
/provider deepseek
/provider fireworks-ai
/provider google
/provider groq
/provider meta
/provider minimax
/provider moonshotai
/provider perplexity
/provider togetherai
/provider venice
/provider xai
/provider zai
/provider cloudflare

The supported environment variables are OPENAI_API_KEY, OPENROUTER_API_KEY, TOKENROUTER_API_KEY, TOKENHARBOR_API_KEY, NVIDIA_API_KEY, COMMAND_CODE_API_KEY, NOUS_API_KEY, KIOSAPI_API_KEY, APINEX_API_KEY, ORCAROUTER_API_KEY, BAI_API_KEY, HCNSEC_API_KEY, TOKENBOM_API_KEY, ATRIA_API_KEY, INTERN_API_KEY, INFRON_API_KEY, UNOROUTER_API_KEY, BAZAARLINK_API_KEY, DASHSCOPE_API_KEY, ANTHROPIC_API_KEY, BASETEN_API_KEY, CEREBRAS_API_KEY, COHERE_API_KEY, DEEPINFRA_API_KEY, DEEPSEEK_API_KEY, FIREWORKS_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, META_MODEL_API_KEY, MINIMAX_API_KEY, MOONSHOT_API_KEY, PERPLEXITY_API_KEY, TOGETHER_API_KEY, VENICE_API_KEY, XAI_API_KEY, ZHIPU_API_KEY, AI_GATEWAY_API_KEY, CLEANAPIS_API_KEY, CODECRAFT_API_KEY, XKIRO_API_KEY, MISTRAL_API_KEY, APIXOAI_API_KEY, AIHUBMIX_API_KEY, CHATANYWHERE_API_KEY, TIARINA_API_KEY, ASHNA_API_KEY, CLOUDFLARE_API_TOKEN. The key prompt is masked and stores the key globally in the Savant-Code config credentials.json; it is not added to chat history. Shell environment variables take precedence over stored keys, so CI and managed environments can configure providers without using local persistence. Advanced direct-provider integrations may use INFERENCE_BASE_URL and INFERENCE_API_KEY; when INFERENCE_BASE_URL names a custom endpoint, INFERENCE_API_KEY is that endpoint's only credential — the active provider's key chain is never sent to it, and a missing key fails fast naming the variable. OpenRouter can use OPENROUTER_API_KEY or SAVANT_CODE_BYOK_OPENROUTER.

CLI Commands

Command	What it does
`bun run dev`	Launch CLI in dev mode
`bun run build:sdk`	Build the SDK for npm publish
`bun run --cwd=cli build:binary`	Build the CLI binary from `cli/`
`bun run ci`	Build the SDK declarations
`bun run test`	Run the test suite
`bun run typecheck`	Type check (all workspaces)
`bun x eslint . --max-warnings 0`	Lint

Slash Command Reference

Commands can be entered with /; aliases are shown in parentheses.

Command	Purpose
`/help` (`/h`, `/?`)	Show command help and tips
`/new` (`/clear`, `/reset`)	Start a fresh chat; optional text starts the first prompt
`/history` (`/chats`)	Browse and resume previous conversations
`/copy` (`/copy-chat`)	Copy the complete conversation to the clipboard
`/export` (`/save`)	Write a self-contained branded HTML report of the conversation
`/graph refresh` (`/graph`)	Re-index the code knowledge graph and show summary stats (`--full` rebuilds)
`/graph-export` (`/graph:export`)	Write a branded, interactive offline HTML report of the code knowledge graph
`/attest` (`/trust-receipt`)	Export and verify the current project's signed ZTAP trust receipt
`/learn` (`/teacher`)	Practice directing and reviewing an AI coding agent through guided exercises
`/interview`	Turn an idea into a structured specification
`/plan`	Create an implementation plan
`/review`	Review code changes
`/compact`	Force an immediate context compaction (compact-and-stop)
`/goal` (`/g`)	Start or manage a durable, budgeted goal run (`status`, `pause`, `resume`, `cancel`)
`/auto-drive` (`/auto`, `/drive`, `/autodrive`)	Start or manage an Auto Drive run — clarify, plan, approve, then run to completion
`/loop` (`/repeat`)	Run a prompt on a recurring cadence; use `stop` or `status`
`/verify` (`/typecheck`)	Run the four supported core workspace typechecks, all or one selected
`/permissions` (`/sandbox`, `/safety`)	View or set `safe`, `prompt`, or `unsafe` tool policy
`/presence` (`/discord`)	Show or change Discord Rich Presence: `status`, `enable`, `disable`
`/rewind` (`/undo`, `/checkpoint`)	Restore a previous turn’s files and/or conversation
`/health` (`/status`, `/check`)	Check Ollama, provider mode, model, and permission status
`/diagnostics` (`/diag`, `/processes`)	Show local process and resource diagnostics
`/provider`	Configure a hosted provider key with masked input
`/provider free`	List free-model lanes you have (and haven't) wired
`/notifications`	Open the provider notification inbox
`/research-keys` (`/research-key`)	Set a research API key (`serper`, `context7`, `parallel`, `tavily`, `exa`, `firecrawl`) with masked input
`/mode`	List the four modes and their contracts, or switch: `/mode <name>` or `/mode:<name>`
`/model`	Select or switch the active hosted model
`/publish`	Publish agent templates through the Savant backend
`/feedback` (`/bug`, `/report`)	Open the feedback flow
`/telemetry` (`/analytics`)	View or change remote analytics consent
`/theme:toggle`	Switch between light and dark themes
`/design` (`/ds`)	List, select, create, edit, import, validate, resume, discard, and reset design systems
`/skills`	List, show, trust, untrust, or roll back agent-authored skills (operator-only release boundary)
`/bash` (`!`)	Run a shell command or enter Bash mode
`/image` (`/img`, `/attach`)	Attach an image for supported multimodal models
`/init`	Create starter agent types and `knowledge.md`
`/logout` (`/signout`)	End the current session and sign out
`/connect`	Connect a ChatGPT account (OAuth)
`/exit` (`/quit`, `/q`)	Quit the CLI

ECHO Protocol

This project ships with ECHO Protocol v0.2.0 — the single bootstrap file for agent behavior.

Core Principles

FID-Bound Execution — Code is never written until the FID converges
Perfection Loop — RED → GREEN → AUDIT → ADVERSARIAL → SELF-CORRECT → COMPLETE
Separation of Duties — The agent that writes code cannot verify it
No Deferrals — Every approved work item must be completed

15 Laws

4 immutable process laws (Read 0-EOF, Present Before Act, Verify Before Proceed, Call-Graph Reachability) + 11 extended code laws. strict: true in TypeScript.

Key Files

File	Purpose
`ECHO.md`	The 15 Laws + Perfection Loop FSM + FID lifecycle
`ARCHITECTURE.md`	Agent roster and tool restrictions
`protocol.config.yaml`	Build commands, quality bar, paths
`dev/fids/`	Feature Implementation Documents
`dev/session-summaries/`	Session audit trail
`dev/LEARNINGS.md`	Cross-session lessons
`dev/agenda.md`	Session-end learning agenda (≤50 lines)
`dev/experiences/`	Raw experience traces (unloaded, deduped)
`.agents/skills/`	Skills + `versions/` + `VERSIONS.jsonl` + `.quarantine/`
`docs/self-improving-harness.md`	Self-improving harness + agent-created skills (full guide)

Configuration

What	Where	Format
ECHO Protocol runtime config	`protocol.config.yaml`	YAML — language, commands, quality limits
TypeScript base config	`tsconfig.json`	JSON — `strict: true`
ESLint config	`eslint.config.js`	Flat config
Bun config	`bunfig.toml`	TOML — `linker: "hoisted"`

Validation

# Build
bun run build:sdk && bun run ci

# Test
bun run test

# Type check
bun run typecheck

# Lint
bun x eslint . --max-warnings 0

# Format
bun x prettier --write .

Privacy & Telemetry

Remote analytics and error reporting are enabled by default in the CLI (FID-2026-0806-015). The CLI sends anonymous usage events and error reports to help improve the product; no prompt content is transmitted as part of these events.

Disable anytime with /telemetry disable (or re-enable with /telemetry enable). /telemetry status shows the current state.
Local logs remain available when remote analytics are disabled.
Contextual ads are separate — disabled by default in the main CLI and controlled independently where available.
First launch prints a one-line notice about this default; it is shown once and never again.

Documentation

ECHO.md — The 15 Laws + Perfection Loop FSM
ARCHITECTURE.md — Agent roster and tool restrictions
protocol.config.yaml — Build commands, quality bar
CHANGELOG.md — Release history
docs/code-universe-export.md — /export conversation reports and /graph-export Code Universe guide
docs/design/zero-trust-agentic-provenance.md — ZTAP architecture, trust model, /attest workflow, verification, and operational boundaries
docs/design/agent-steering-teacher-overview.md — the complete Agent-Steering Teacher overview: product, exercise loop, command reference, module map, trust model, progression + ZTAP
docs/design/agent-steering-teacher-guide.md — the Agent-Steering Teacher: exercise loop, modules, trust model, /learn usage, and challenge authoring
docs/design/design-system-library.md — loadable design-system architecture, workflows, security, enforcement, and packaging
docs/design/hook-system.md — the extensible lifecycle-hook system: hooks: config schema, events, and fail-open protocol
docs/design/goal-mode.md — the durable budgeted /goal workflow: command reference, state machine, and budgets
docs/features.md — full feature reference, including Research (web_search/read_docs/deep_research + BYOK keys), Auto Drive (/auto-drive) and Discord Rich Presence (/presence)
docs/faq.md — FAQ: research keys, /goal vs /auto-drive, /presence, and headless --auto
desktop/README.md — the Tauri v2 desktop shell: sidecar lifecycle, renderer, 3D command deck, build/run commands
[docs/design/Auto Drive Architecture Blueprint.md](docs/design/Auto Drive Architecture Blueprint.md) — the Auto Drive architecture
[docs/design/Discord Presence For Savant-Code.md](docs/design/Discord Presence For Savant-Code.md) — the Discord Rich Presence blueprint
dev/test-prompts/design-system-live-ux-performance.md — live CLI usability, agent-feedback, and performance test prompt
dev/nova/outbox/archive/2026-08-11-fid-2026-0811-030-design-system-live-test-signoff-request.md — independent review request for the live test design and captured result
docs/archive/launch/index.html — Public landing page (archived launch artifact)
dev/LEARNINGS.md — Cross-session lessons
dev/session-summaries/ — Session audit trail

License

Apache-2.0 — see LICENSE for full text.

Savant-Code is the public TypeScript monorepo for the Savant-Code agent framework.

Savant • 2026

Name		Name	Last commit message	Last commit date
.agents		.agents
.githooks		.githooks
.github/workflows		.github/workflows
.vscode		.vscode
agents		agents
art		art
assets		assets
cli		cli
coding-standards		coding-standards
common		common
desktop		desktop
docs		docs
evals		evals
packages		packages
scripts		scripts
sdk		sdk
templates		templates
website		website
.bun-version		.bun-version
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmessage		.gitmessage
.markdownlint.json		.markdownlint.json
.markdownlintignore		.markdownlintignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.savantignore		.savantignore
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTORS.md		CONTRIBUTORS.md
Dockerfile		Dockerfile
ECHO-single-agent.md		ECHO-single-agent.md
ECHO.md		ECHO.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
SCOPE.md		SCOPE.md
SECURITY.md		SECURITY.md
VERSION		VERSION
WINDOWS.md		WINDOWS.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
eslint.config.js		eslint.config.js
knowledge.md		knowledge.md
package.json		package.json
protocol.config.yaml		protocol.config.yaml
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation