Sigma Code

A durable, evidence-driven coding agent with a unified Pi model gateway.
Plan, inspect, edit, execute, validate, review, and resume—all from the terminal.

English · 简体中文

Sigma Code turns a coding task into a durable stream of typed decisions and evidence. It can explore a repository, make scoped changes, run sandboxed commands, validate the result, ask an independent reviewer, and recover the same session after interruption. The product uses one event-sourced kernel, one session format, and one terminal UI instead of separate execution paths that drift apart.

0.1.0 is the first formal release and the only supported product baseline.
Linux x64 is the stable release target. Windows x64 remains an explicitly
unsigned preview until trusted Authenticode signing is available. See the security
policy and contribution guide before reporting
or proposing changes.

[!IMPORTANT]
Current product boundary

• Sigma Code 0.1.0 is stable on Linux x64; Windows x64 is an unsigned preview. Both candidates must pass native sandbox, packaged-product, checksum, SBOM, and signed-provenance gates. Windows executables do not yet have a trusted Authenticode signature and may trigger Windows security warnings.
• Formal evaluation is preregistered, not provider-coded. The SHA-bound run manifest freezes the provider, model, source, archive, task selection, network, timeouts, concurrency, attempts, and retries before execution.
• Provider comparisons are valid only when their SHA-bound run manifests freeze comparable controls; the harness does not infer comparability from a model name.

Why Sigma Code

Quick start on Linux

Obtain the 0.1.0 Linux x64 stable archive from a verified project release or
build it from source, verify its SHA-256 sidecar and signed provenance, and
extract it:

SIGMA="$HOME/.local/share/sigma-code"
WORKSPACE="/path/to/your/repository"

export DEEPSEEK_API_KEY="your-api-key"

"$SIGMA/bin/agent" init --workspace "$WORKSPACE" --provider deepseek
"$SIGMA/bin/agent" doctor --workspace "$WORKSPACE" --check-api
"$SIGMA/bin/agent" tui --workspace "$WORKSPACE"

Quick start on Windows (unsigned preview)

[!WARNING]
The Windows x64 archive is an unsigned preview, not an official trusted Windows
binary release. Verify its SHA-256 sidecar and signed provenance before extraction.
Its executables do not have a trusted Authenticode signature, so Windows SmartScreen
or Smart App Control may warn or block execution.

Download the Windows x64 preview archive from GitHub Releases and extract it only if you accept the unsigned-preview risk. The bundle includes its pinned Node.js runtime, the native sigma-exec broker, the TUI runtime, TypeScript/Python language-server assets, and tokenizer data; a separate Node.js installation is not required.

$Sigma = "C:\Tools\sigma-code"
$Workspace = "D:\path\to\your\repository"

$env:DEEPSEEK_API_KEY = "your-api-key"

# One-time setup for the current Windows user.
& "$Sigma\bin\agent.cmd" sandbox setup

# Create workspace configuration, verify the runtime and provider, then enter the TUI.
& "$Sigma\bin\agent.cmd" init --workspace $Workspace --provider deepseek
& "$Sigma\bin\agent.cmd" doctor --workspace $Workspace --check-api
& "$Sigma\bin\agent.cmd" tui --workspace $Workspace

The example sets the key only for the current PowerShell process. Keep secrets out of .agent/config.toml and source control.

Published archives include a SHA-256 checksum, CycloneDX SBOM, signed
provenance, and the public provenance verification key. Linux x64 is stable at
0.1.0; Windows x64 remains an unsigned preview. See
SECURITY.md for the trust boundary and
RELEASING.md for the maintainer process.

For a one-shot task:

& "$Sigma\bin\agent.cmd" run "Fix the failing tests and explain the change" `
  --workspace $Workspace `
  --permission-mode auto

For read-only analysis:

& "$Sigma\bin\agent.cmd" inspect "Map the request path and identify reliability risks" `
  --workspace $Workspace `
  --permission-mode auto

run uses change mode. inspect uses analyze mode and rejects tools whose declared effects include filesystem writes, unrestricted process spawning, or destructive work.

What Sigma can do

• Interactive coding: use a CJK/IME-aware terminal UI with Markdown responses, activity views, command completion, multiline input, steering, follow-ups, scrolling, and approval overlays.
• Repository intelligence: bounded file listing and grep, repository statistics, Git status/diff, stable hash-aware workspace and declared host-input reads, nested AGENTS.md discovery, and LSP-backed code intelligence when a supported server is available.
• Scoped changes: write and edit files, apply atomic multi-file patches, delete individual files, detect no-op writes, create mutation checkpoints, and restore the current run's latest sealed checkpoint.
• Sandboxed execution: run direct executables or platform shells, execute semantic validation, manage background/PTY processes through broker-scoped session handles, and explicitly hand off verified Linux deliverable services.
• Read-only Web research: use web_run (web.run in documentation) to search, open, find, and follow numbered static links. Results retain durable references and are always marked as untrusted external content.
• Evidence-based delivery: record workspace deltas, commands, validation, diagnostics, reviews, child outcomes, and checkpoints in one typed evidence ledger.
• Durable sessions: list, inspect, replay, resume, cancel, steer, approve, and continue sessions after a process interruption.
• Child agents: delegate plan nodes to bounded child sessions; isolate writers in Git worktrees or narrow single-writer scopes, then explicitly integrate retained changes.
• Extensibility: load skills, profiles, and hooks through frozen/trusted customization boundaries, and connect explicitly trusted read-only MCP stdio servers.

Architecture

agent-runtime.createConfiguredRuntime is the single production composition root. It wires the model routes, context provider, pure kernel, effect-aware tools, MCP clients, segmented event store, checkpoint manager, reviewer, supervisor, execution broker, and in-process RuntimeClient. The CLI creates that runtime; the TUI receives the client rather than rebuilding the agent loop.

flowchart TB
  USER["User task / TUI input"] --> CLI["agent-cli<br/>commands and configuration"]
  CLI --> ROOT["agent-runtime<br/>single composition root"]
  ROOT --> CLIENT["RuntimeClient<br/>session command bus"]
  CLIENT --> KERNEL["agent-kernel<br/>pure reducer + effect decisions"]

  KERNEL --> MODEL["agent-model<br/>routing, budgets, retry policy"]
  MODEL --> PI["agent-pi + pi-ai<br/>provider auth and model transport"]
  KERNEL --> CONTEXT["agent-context<br/>instructions, retrieval, token budget"]
  KERNEL --> TOOLS["agent-tools<br/>typed effect plans and receipts"]
  KERNEL --> STORE["agent-store<br/>events, snapshots, artifacts"]

  TOOLS --> MCP["agent-mcp<br/>trusted read-only stdio bridge"]
  TOOLS --> SUP["agent-supervisor<br/>children, mailboxes, writer isolation"]
  TOOLS --> EXEC["agent-execution<br/>only arbitrary-process boundary"]
  EXEC --> NATIVE["sigma-exec (Rust)<br/>Windows AppContainer / Linux namespace sandbox"]

  MODEL --> EVENTS["AgentEventEnvelope"]
  CONTEXT --> EVENTS
  TOOLS --> EVENTS
  SUP --> EVENTS
  EVENTS --> STORE
  EVENTS --> KERNEL
  EVENTS --> PRESENT["agent-presentation<br/>incremental projection"]
  PRESENT --> TUI["agent-tui<br/>OpenTUI renderer"]

  EVAL["External evaluation + benchmark harness"] -.->|"launch packaged subject; collect only after run"| CLI

The event loop

1. A CLI/TUI command becomes a typed session command and durable event.
2. agent-kernel reduces the event stream into state and decides the next effect; it does not perform I/O itself.
3. agent-runtime executes that decision through protocol ports for the model, context, tools, store, review, or supervision.
4. Before a tool runs, Sigma freezes its exact read/write roots, network mode, process mode, idempotence, and checkpoint scope. Mode policy, approval, locks, and trust checks are evaluated against that plan.
5. The resulting receipt and evidence are appended as new events. The kernel then decides the next step from durable state, while agent-presentation projects the same events into CLI/TUI output.
6. A run ends only with a typed outcome: Completed, NeedsInput, Cancelled, RecoverableFailure, or Fatal.

This separation makes replay and recovery part of the normal execution model instead of a special UI feature.

Package map

The production package dependency graph is checked for cycles and packages communicate through public exports.

Safety, permissions, and recovery

Execution boundary

agent-execution is the only production package allowed to start arbitrary processes. It talks to the bundled Rust sigma-exec broker over a framed protocol. On Windows, each sandboxed command uses an AppContainer identity with scoped filesystem ACLs, a kill-on-close Job Object, capability-gated networking, and ConPTY for interactive processes. Linux uses the native namespace sandbox and a watchdog for process-tree cleanup.

Configuration schema 1 defaults to permission_mode=workspace-auto,
sandbox=required, read_scope=workspace, network=full,
web.mode=auto, process_handoff=allow, and the native sandbox backend. Workspace-scoped reads
and declared writes run automatically; external reads, full-network calls, and
repository metadata writes remain separately authorized. An explicit
network=none or network=loopback setting narrows the capability. Required
isolation never falls back to host execution, and container mode fails with
container_unavailable until a real OCI backend is installed.

web_run is exposed only when full network access is enabled, Web mode is not
disabled, and the connected broker advertises the restricted Web protocol. Its
session grant is scoped to read-only Web access and cannot authorize shell,
process, or MCP networking. The broker permits public HTTP(S) ports 80/443,
binds every request to an approved origin and method, and rejects local,
private, reserved, credential-bearing, or active browser content.

Absolute external inputs are read through stable no-follow traversal and produce input_access evidence with path, digest, and size. Process calls mount only their declared stable read roots. A failed goal input remains an unresolved completion obligation until the same external path is read successfully; a run-created fixture cannot replace it.

Path containment and OS isolation are separate checks. Workspace tools reject lexical and symlink/junction ancestor escapes; creating a workspace symlink object such as a virtual-environment interpreter link is allowed without granting writes to its external target. .git and .agent remain protected from sandbox write grants.

Linux advertises processHandoff only when safe transfer is available. A deliverable process uses detached stdio, cannot use PTY/stdin, and must be independently health-checked before process_handoff. Handoff removes it from session cleanup; unhanded processes are still terminated on failure, cancellation, timeout, or broker loss. Windows currently advertises this capability as unavailable and fails closed.

Checkpoints and durable state

Runtime state is stored outside the agent-writable workspace under a workspace-derived user-state directory:

<user-state>/sigma/workspaces/<workspace-sha256>/stores/v1/sessions/<session-id>/
  meta.json
  events/000001.jsonl
  snapshots/000000000250.json
  artifacts/<sha256>

Event records have checksums and monotonic sequence numbers. Segments rotate at 8 MiB or 10,000 events, snapshots are written every 250 events and at rotation, and a torn final record can be repaired under the append lock. Resume restores pending approvals, follow-ups, discovered instructions, budgets, and safe idempotent work. Interrupted non-idempotent effects become NeedsInput instead of being silently replayed.

Completion is a protocol action

A provider stop is only model_stopped. The Completion Coordinator independently derives assurance and review requirements from the current mutation frontier and emits run.completed only when model_stopped, assurance_satisfied, and review_satisfied are all true. Failed, stale, weak, or incomplete semantic validation produces structured repair guidance or a typed blocker; the model has no completion tool that can bypass the gate.

All net changes require passed semantic validation on the current state. Sealed
no-op checkpoints do not advance that frontier; mutating validation is rebound
after its checkpoint seals. The standard profile requires current-frontier
review approval or an explicit one-time user waiver. The strict profile does
not accept a waiver and requires approval backed by a reviewer-executed check.
Active non-detached children are joined before completion, and an unintegrated
writer worktree keeps the parent open.

Current serialized and tool contracts

• Every Sigma-owned serialized boundary uses strict schemaVersion: 1 (or
  schema_version = 1 in TOML). Unknown schemas, another store layout, and old
  checkpoint journals fail with unsupported_schema_version or
  unsupported_store_layout; the rejected files are never rewritten,
  migrated, or deleted.
• Active review is read-only and runs checks in a disposable overlay. It can
  inspect the authenticated current frontier and durable process lifecycle
  evidence without writing the parent workspace.
• At an ordinary solver-budget boundary, already-started session processes are
  allowed to settle within the outer deadline. Deliverable processes remain
  session-owned until an independently health-checked process_handoff
  succeeds.
• write and edit report the resulting byte length and SHA-256;
  write_chunk uses an expected preimage length and digest. An omitted shell is
  resolved deterministically by the broker. Non-UTF-8 process output must be
  preserved as a byte-safe artifact; a decoding error without that artifact is
  rejected as a broker protocol violation.
• inspect_image and inspect_document are bounded, offline, read-only
  fallbacks for text-only providers. Their OCR or extraction metadata is
  inspection data, not completion evidence.

Commands

Stable process exit codes are 0 for Completed, 2 for NeedsInput, 130 for Cancelled, and 1 for recoverable or fatal failure.

TUI controls

• Enter: send while idle, or steer the active run
• Shift+Enter / Ctrl+J: insert a line
• Alt+Enter: queue a follow-up
• Ctrl+O: collapse or expand activity
• PgUp / PgDn, Ctrl+U / Ctrl+D, mouse wheel: scroll
• /new, /mode analyze|change, /followup, /activity, /help, /quit: session commands
• First Ctrl+C: cancel; second press within 1.5 seconds: exit

Configuration

Precedence is CLI flags → environment → workspace .agent/config.toml → home ~/.sigma/config.toml → defaults. Unknown flags and TOML keys fail immediately. Workspace-authored MCP servers and executable hooks require an explicit digest-bound trust grant.

schema_version = 1

[model]
provider = "deepseek"
name = "auto"

[permissions]
mode = "workspace-auto"

[security]
sandbox = "required"
read_scope = "workspace"
network = "full"
process_handoff = "allow"

[web]
mode = "auto"
search_provider = "exa"

[runtime]
run_deadline_sec = 900
model_deadline_sec = 120
stream_idle_sec = 45

[tools]
max_parallel = 4

[agents]
max_parallel = 4

[ui]
output_format = "text"

[tui]
fps = 30

To opt into broader per-call capabilities, use:

schema_version = 1

[security]
sandbox = "required"
read_scope = "host"
network = "full"
process_handoff = "deny"

agent init writes the current schema directly. Sigma does not expose a
configuration migration command and does not read another durable store layout.
Back up or move incompatible state yourself; rejection is deliberately
read-only.

ChatGPT/Codex subscription provider (experimental)

Sigma can keep its own runtime, tools, recovery, budgets, reviewer, strategist,
and durable state while sending model requests through a ChatGPT/Codex
subscription:

[model]
provider = "openai-codex"
name = "gpt-5.6-terra"

This route uses ChatGPT OAuth and
https://chatgpt.com/backend-api/codex/responses; it never reads
OPENAI_API_KEY and does not use API-key billing. Credentials are shared by
Sigma processes on the same host in ~/.sigma/auth.json. Subscription usage
keeps token accounting, but records billingMode = "subscription" and a null
API cost. Authentication, allowance, rate-limit, network, timeout, and server
failures are returned directly. The built-in subscription route has one
candidate and cannot silently fall back to DeepSeek, GLM, or
api.openai.com/v1.

The JSONL login interface is intended for trusted desktop clients:

sigma auth status openai-codex --json
sigma auth login openai-codex --method browser --json
sigma auth login openai-codex --method device-code --json
sigma auth logout openai-codex --json

Unified Pi provider gateway

All model I/O is owned by agent-pi, pinned to
@earendil-works/[email protected]. The pinned directory exposes Pi's 38 built-in
providers and 1,109 static models, plus Sigma's historical glm compatibility
provider and endpoint. agent-model is only the policy layer: it chooses
explicit routes, reserves budgets, classifies failures, applies retry/fallback
rules, and tracks provider health.

Provider credentials and the dynamic model cache are stored separately in
~/.sigma/auth.json and ~/.sigma/models.json. Both use atomic replacement,
cross-process locks, and current-user-only permissions. Directory/status reads
are offline; only an explicit model refresh, login completion, or a normal
model request may access the network.

Billing is reported as metered, subscription, or unpriced.
Subscription and unpriced calls retain token usage with a null monetary cost;
they are never presented as zero-dollar API calls. An unpriced model is
rejected by default and requires --allow-unpriced-costs (or
budget.allow_unpriced_costs = true) for that task. Known metered budget
limits and token/turn/tool limits remain active.

ChatGPT subscription authentication and API-key billing are separate; see
OpenAI's authentication and
pricing documentation. The backend
used here is integrated through the version-pinned Pi community adapter rather
than a public third-party API with a stability commitment, so upgrades require
an explicit dependency bump and contract-test run. See OpenAI's
Codex community projects.

DeepSeek uses DEEPSEEK_API_KEY. The runtime also recognizes GLM_API_KEY, ZAI_API_KEY, or BIGMODEL_API_KEY for the experimental GLM/Z.ai path. Web search uses the Exa hosted MCP service; EXA_API_KEY is optional, and a 429 response tells the operator to configure it without silently changing providers. A provider is part of a formal claim only when it is frozen in that run's preregistration.

Evaluation and benchmark boundary

Sigma's formal experience evaluator runs the packaged product in fresh, opaque
workspaces and reduces the durable event stream into separate correctness,
safety, experience, and reliability results. Terminal-Bench formal runs require
a SigmaFormalRunPreregistration; code supplies no formal dataset, model,
quota, retry, or score threshold default.

The evaluator may select a task, launch the packaged CLI, and collect artifacts after the run. It must not send scenario identity, verifier output, scores, rewards, hidden checks, or post-run failures into the solving session, and verifier feedback never triggers another solving attempt. This fairness boundary is enforced by protocol types and production-source scans.

Terminal-Bench 2.1: Sigma Code + DeepSeek vs OpenCode + DeepSeek

A staged diagnostic run on July 27–28, 2026 compared both agents with
DeepSeek deepseek-v4-pro on the same 89-task Terminal-Bench 2.1 population.
The Sigma lane used a maximum concurrency of 5, one attempt per task, zero
retries, and no verifier feedback.

The raw view keeps six externally caused Sigma infrastructure-invalid
observations as non-passes. The secondary view removes those same six task
identities from both agents. Sigma's immutable observation union is
49 + 4 + 1 + 9 + 26 = 89: each source revision ran only the then-unconsumed
suffix, so this is a mixed-source diagnostic result rather than a score for the
final PR head. No consumed task was rerun, and the generic lifecycle fix made
after the final observation is intentionally not included in the score. See
PR #73 for the source-boundary,
stop-loss, and validation record.

# Audit existing sessions without a model call.
pnpm eval:session -- --workspace . --latest 2

# Live evaluation uses explicitly supplied provider/model controls.
pnpm eval:agent -- --suite quick
pnpm eval:agent -- --suite experience --repeat 3

# Create and consume an immutable formal run manifest.
pnpm bench:tb:preregister -- --draft formal-draft.json --output formal-run.json
pnpm bench:tb:formal -- --preregistration-file formal-run.json --expected-preregistration-sha256 <sha256> --batch <batch-id>

No cross-provider benchmark conclusion should be inferred from these results.

Build and develop

The repository pins Node.js 26.4.0, pnpm 11.7.0, and Rust 1.96.0.

corepack enable
corepack prepare [email protected] --activate
pnpm install --frozen-lockfile
pnpm build
cargo build --release --locked --manifest-path native/sigma-exec/Cargo.toml

pnpm lint
pnpm test:coverage

# Requires a packaged CLI, a model-provider key, and live network access.
pnpm smoke:web:live

Build and verify the current Windows preview candidate:

pnpm package:agent-cli:windows
pnpm verify:release:windows

After packaging, put the development key in the repository-local, gitignored .env file:

DEEPSEEK_API_KEY=your-api-key
# Optional; the hosted Exa MCP endpoint can be used without it.
EXA_API_KEY=your-exa-key

Then launch the development TUI:

pnpm tui:deepseek

Fake-gateway tests do not require provider credentials. See VALIDATION.md for coverage thresholds, real-terminal boundaries, native sandbox checks, packaging proofs, and release gates.

License

Sigma Code is available under the MIT License.

Direction

Sigma's near-term focus is deliberately narrow: make the Windows product dependable, deepen long-session convergence, improve real task performance, and keep evaluation feedback outside the solving boundary. Broader formal platform/provider claims should follow reproducible preregistration and demonstrated product reliability rather than lead it.