Skaden

Skaden is a standalone, simulator-first design-partner build for quantum software. Install it, run skaden inside a project, and ask it to inspect code, edit files, run approved commands, diagnose environments, compile circuits, simulate, verify, and preserve evidence. Models reason and propose actions inside Skaden; typed local tools and permissions own repository changes, quantum execution, policy, digests, and evidence.

Skaden owns the complete terminal experience. Codex, Claude Code, and OpenCode are product references only; they are not hosts or dependencies. MCP is an inward-facing extension protocol: Skaden connects to external MCP servers and exposes their tools to its selected model only through the same deterministic permission, policy, timeout, and audit boundary as built-in tools.

The current build provides:

• a strict built-in model-callable tool catalog spanning repository work, sandboxing, adapter discovery, quantum execution and research, governance, and local learning, plus explicitly allowed namespaced MCP tools;
• a pinned Deep Agents/LangGraph conversation runtime with streaming events, bounded context management, persistent SQLite checkpoints, cancellation, and three explicit read-only specialists;
• a deterministic Tool Gateway with strict argument validation, actor/risk scopes, exact-call approval binding, hardware fail-closed policy, and content-digested decisions and results;
• a versioned Quantum Adapter SDK with explicit registration, opt-in plugins, health checks, deterministic project detection, normalized result envelopes, and reusable conformance tests;
• bounded repository listing, file reading, text search, Python symbol inspection, Git status, and Git diff;
• read-only notebook inspection plus permission-gated cell replacement, insertion, and deletion;
• permission-gated exact edits, atomic file writes, deletion, and argv-based command execution;
• a strict sk.sandbox/v1alpha1 execution boundary using macOS Seatbelt or Linux Bubblewrap, with project filesystem policy, deny-by-default networking, secret filtering, cancellation, process-tree termination, bounded output, timestamps, and digest-bound evidence;
• read-only, interactive ask, and explicitly dangerous auto repository modes;
• project AGENTS.md and QUANTUM.md instructions plus digest-chained local session audit records;
• private rotating operational logs with bounded redaction, crash correlation IDs, durable terminal failure/cancellation events, and an explicit digested support-report export;
• digest-bound advisory project memories, progressively disclosed procedural skills, verified local session search, hashed repeated-task recognition, and explicit stale/archive curation;
• read-only, content-hashed project inspection;
• bounded, seeded local Aer simulation of validated OpenQASM files;
• OpenQASM 2/3 circuit inspection, frozen-target compilation, and seeded execution reproducibility checks that explicitly do not evaluate algorithm correctness;
• deterministic circuit drawing, linting, structural diffing, bounded equivalence checking, QASM translation, structural resource estimates, statistical distribution assertions, and seeded synthetic-noise simulation;
• Qiskit QPY and OpenQASM circuit intake with isolated QPY decoding, validated OpenQASM 3 normalization, exact transformation-faithfulness evidence, and conservative independent-module factorization that never mislabels circuit cutting as a simple split;
• a CI-ready circuit regression gate with digest-validated baselines, resource-delta ceilings, bounded equivalence, sampled-distribution comparison, machine-readable verdicts, and HTML reports;
• deterministic diagnosis of high-signal stale Qiskit API patterns;
• content-hashed JSON, Markdown, and standalone HTML experiment reports;
• deterministic .qhbundle reproduction/evidence archives with offline structural, digest, and typed cross-link verification, plus installed-package CFF/BibTeX/JSON citation output;
• a strict sk.experiment/v1alpha1 runtime for manifests, stable experiment identity, archived artifacts, lifecycle evidence, approved runs, reproduction, compatible-run comparison, and reports;
• bounded experiment sweeps and declaration-driven paper reproductions with separate zero-write planning, exact plan-digest approval, immutable artifact snapshots, and relational evidence checks;
• bounded local VQE and MaxCut QAOA runs with SPSA/COBYLA/L-BFGS-B orchestration, checkpoints, convergence reports, and digest-approved grid, seeded-random, and Latin-hypercube sweeps over parameters, ansatz depth, and numeric optimizer settings;
• an isolated Stim/PyMatching QEC command group for validated memory-experiment plans, distance curves with Wilson intervals, resumable evidence, and deterministic JSON/Markdown reports;
• an offline calibration-snapshot workflow for freshness checks, hardware-aware qubit selection, initial layouts, device-derived Aer noise recipes, ideal/noisy comparison, and linked reports;
• a raw-versus-mitigated comparison workflow that locally acquires independent readout calibration and every planned ZNE scale point, then emits movement-only deltas, bootstrap intervals, and publication figures without claiming physical-device improvement;
• evidence-bound simulator routing with executable statevector, MPS, stabilizer, and extended-stabilizer selections, including an honest --backend auto decision;
• a simulator-only multi-candidate research workflow with strict manifests, zero-write preflight, exact plan-digest execution, accepted/rejected candidate records, scope-bound claims and evidence, digest-verified JSON/Markdown/HTML deliverables, and archive-based child reproduction;
• bounded optimization and repeated-seed benchmark planners, deterministic Pareto selection, frozen target compatibility checks, advisory-only research roles and memory references, and safe no-execution detection of OpenQASM, Qiskit, Cirq, PennyLane, and Q# artifacts;
• an optional guarded literature reader whose content is untrusted context, never proof;
• an opt-in IBM Qiskit Runtime broker with OS credential storage, live target snapshots, immutable compiled plans, explicit target allowlists, bounded shots/runtime, exact-plan human approval, interactive submission, ambiguity-safe reconciliation, normalized results, and a chained audit log;
• a dated, source-linked provider/target catalog that is explicitly not live execution metadata;
• a local guided/chat-style command router;
• arbitrary provider profiles with native Anthropic, Google GenAI, OpenAI Responses, or OpenAI-compatible Chat Completions protocols;
• guided provider connection, custom base URLs and environment-backed headers, live model discovery, and model selection;
• strict versioned records for run plans, checks, policy decisions, and approvals;
• hardware-disabled-by-default policy evaluation;
• approval verification bound to the exact run-plan digest and spend ceiling;
• an MCP client/host for remote Streamable HTTP servers, with local stdio discovery and execution disabled until a native isolation boundary exists;
• a Phase-0 competitor absorption benchmark and scoring engine.

The model-callable tools intentionally do not approve, submit, cancel, or handle QPU credentials. Those operations live behind the separate sk qpu broker command surface and require a human at a real terminal. Secret values are stored in the operating-system credential service, not project or Skaden configuration. An external MCP tool cannot mint approval, submit through this broker, or bypass the tool gateway. MCP is not a sandbox: only attach servers you trust, because a malicious server can misdescribe its behavior. The command sandbox is not a VM, container, kernel, multi-user, or hostile-code-grade boundary. If a native backend is missing or cannot enforce the request, the default fallback fails closed. Do not use --approval-mode auto on an untrusted repository.

MQT QCEC is installed by the verification and all extras. If it is absent, automatic circuit equivalence falls back to the bounded exact-operator engine; explicitly requesting QCEC fails closed.

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[all,dev]'
pytest
ruff check .
sk init .
sk demo
sk doctor .
sk logs --limit 100
sk support-bundle --path . --output skaden-support.json
sk inspect examples/bell
sk circuit inspect examples/bell/bell.qasm
sk circuit intake two-bells.qasm3 --path examples/circuit-intake \
  --output-dir intake-output --max-module-qubits 2
sk circuit draw examples/bell/bell.qasm
sk circuit lint examples/bell/bell.qasm
sk circuit diff examples/bell/bell.qasm examples/bell/bell.qasm
sk circuit equivalence examples/bell/bell.qasm examples/bell/bell.qasm --method operator
sk circuit estimate examples/bell/bell.qasm
sk circuit translate examples/bell/bell.qasm --target openqasm3
sk circuit noise bell.qasm --path examples/bell --errors noise-errors.json --shots 1024
sk circuit assert-distribution observed-counts.json expected-probabilities.json \
  --path examples/bell --tolerance 0.1
sk circuit compile examples/bell/bell.qasm --target-qubits 5
sk circuit verify examples/bell/bell.qasm --shots 1024 --seed 7
sk circuit report examples/bell/bell.qasm --output-dir .skaden/bell
sk baseline save bell.qasm --path examples/bell --shots 1024 --seed 7
sk check bell.qasm --path examples/bell \
  --baseline .skaden/baselines/bell.json \
  --equivalence-method operator --output-dir .skaden/regression
sk targets list --provider aws-braket
sk adapters list
sk adapters detect examples/bell
sk adapters check qiskit-local --project examples/bell --fixture examples/bell/bell.qasm
sk sandbox doctor --path .
sk sandbox explain -- pytest -q
sk sandbox run --allow-project-write -- pytest -q
sk experiment validate experiment.sk.yaml --path examples/bell
sk experiment run experiment.sk.yaml --path examples/bell
sk experiment history --path examples/bell
# First print a sweep plan, then pass its exact plan_digest to the run command:
sk experiment sweep-plan experiment.sk.yaml --path examples/bell --shots 256 --shots 1024
sk experiment sweep experiment.sk.yaml --path examples/bell --shots 256 --shots 1024 \
  --approved-plan-digest sha256:...
sk research plan research.sk.yaml --path examples/research-bell
# Copy the printed record_digest; execution replans and accepts only that exact digest:
sk research run research.sk.yaml --path examples/research-bell \
  --approved-plan-digest sha256:...
sk research status research_RUN_ID --path examples/research-bell
sk research report research_RUN_ID --path examples/research-bell
sk research reproduce research_RUN_ID --path examples/research-bell
sk publish bundle run_REPLACE_WITH_RUN_ID --path examples/bell --output bell.qhbundle
sk publish verify bell.qhbundle
sk cite --format bibtex
sk paper plan paper.sk.yaml --path examples/bell
sk vqe run examples/vqe-h2-toy/vqe.json --state-dir .example-state/vqe-h2
sk qaoa sweep examples/qaoa-maxcut-sweep/qaoa.json \
  --state-dir .example-state/qaoa-sweep --strategy grid \
  --axis gamma_0=0.2,0.6 --axis beta_0=0.2,0.6
sk qec plan examples/qec-distance-scaling/curve.sk.yaml
sk device import examples/device-mitigation/device-projection.json \
  --format ibm-projection --account-name example --adapter-version fixture-1 \
  --captured-at 2026-07-20T12:00:00Z --evaluated-at 2026-07-20T12:00:00Z
sk device report SNAPSHOT.json examples/device-mitigation/bell.qasm \
  --output device-report.json --store device-evidence.sqlite3
sk noise from-device SNAPSHOT_DIGEST examples/device-mitigation/bell.qasm \
  --store device-evidence.sqlite3
sk mitigate compare noise-recipe.json examples/device-mitigation/bell.qasm \
  --output mitigation-report.json --figure zne.pdf
sk simulate examples/bell/bell.qasm --backend auto --shots 1024 --seed 7
sk memory set project.framework "Use Qiskit for local simulation." --path examples/bell
sk skills set verify-bell --description "Verify Bell locally." \
  --instructions "Inspect, lint, simulate with a fixed seed, and report limitations." \
  --path examples/bell
sk learning search "Bell equivalence" --path examples/bell
sk chat "test this circuit" --path examples/bell
sk plan --manifest examples/bell/run-plan.simulator.json --policy skaden.yaml

Protected IBM QPU execution is an opt-in beta. Simulator behavior remains the default, and no model or MCP tool can cross the human approval/submission boundary:

python -m pip install -e '.[qpu]'
sk qpu login ibm --plan open
sk qpu targets ibm
sk qpu enable ibm --target ibm_brisbane --max-shots 4096 --max-execution-seconds 600
sk qpu plan bell.qasm --path examples/bell --target ibm_brisbane \
  --shots 100 --max-execution-seconds 60
sk qpu approve qplan_REPLACE_WITH_PLAN_ID
sk qpu submit qplan_REPLACE_WITH_PLAN_ID
sk qpu status qjob_REPLACE_WITH_JOB_ID
sk qpu result qjob_REPLACE_WITH_JOB_ID
sk qpu audit qjob_REPLACE_WITH_JOB_ID

login, enable, approve, submit, cancel, and logout prompt in the terminal. Do not put the IBM API key on the command line or in a prompt. IBM's maximum execution time is a provider-enforced runtime bound, not a dollar quote or guaranteed bill ceiling. See the protected QPU guide before enabling hardware.

The repository is currently private. Add the tester as a collaborator and install the current GitHub version over SSH in an isolated environment:

# macOS; pin the exact reviewed commit, even when review started from a release tag.
brew install uv git
ssh -T git@github.com
REVISION=REPLACE_WITH_REVIEWED_40_CHAR_COMMIT_SHA
uv tool install --python 3.12 \
  --from "skaden[qiskit] @ git+ssh://git@github.com/skadendev/skaden.git@${REVISION}" \
  skaden

Linux users can install uv, Git, and an OpenSSH client, then run the same SSH and uv tool install commands. GitHub may return status 1 after printing a successful SSH-authentication message because it does not provide shell access. See docs/install.md for Linux, Windows, pipx, release, and packaging status.

On Arch Linux, install the signed system prerequisites with pacman, then install the private design-partner beta through GitHub SSH:

sudo pacman -Syu --needed uv git openssh bubblewrap
REVISION=REPLACE_WITH_REVIEWED_40_CHAR_COMMIT_SHA
uv tool install --python 3.12 \
  --from "skaden[qiskit] @ git+ssh://git@github.com/skadendev/skaden.git@${REVISION}" \
  skaden
uv tool update-shell
export PATH="$HOME/.local/bin:$PATH"
sk demo

The GitHub account attached to the SSH key must be a repository collaborator. See packaging/arch/README.md for the complete preflight and smoke test.

Choose a model engine, then start Skaden directly:

export OPENAI_API_KEY="..."
skaden models add openai --provider openai --model gpt-5.4-mini --activate
skaden

Or use the provider-neutral guided flow:

skaden models connect
skaden models discover PROFILE
skaden models select PROFILE
skaden models check PROFILE

OpenRouter has a built-in preset; configuration is not called ready until a live strict tool-call probe succeeds:

export OPENROUTER_API_KEY="..."
skaden models connect openrouter --provider openrouter --model PROVIDER/MODEL --activate
skaden models check openrouter

Any provider label is accepted. A custom provider must expose native Anthropic Messages, Google GenAI, the OpenAI Responses API, or the OpenAI-compatible Chat Completions API. Skaden can query the provider's model catalog, accept an explicit model ID, point at a proxy or private base_url, and send custom headers whose values come from environment variables.

skaden models add team-gateway \
  --provider acme \
  --protocol openai-chat \
  --base-url https://models.acme.example/v1/ \
  --model organization/model-name \
  --api-key-env ACME_MODEL_KEY \
  --header-env X-Tenant=ACME_TENANT \
  --activate

Example session:

$ skaden
sk: inspect this repository and tell me what can run
sk: find the bug, make the smallest fix, and run the tests
sk: verify the Bell circuit with 4096 shots and explain the evidence
sk: build a reproducibility report for this experiment

With a checked model connection, /tools shows every model-callable capability. Without one, the banner, /help, and /tools expose only the deterministic workflows the offline router can actually invoke. /adapters shows quantum integrations, /experiments lists evidence, /sessions and /resume manage digest-verified conversations, /memory and /skills inspect approved advisory learning, /history QUERY searches verified prior sessions, /learn reviews repeat/lifecycle candidates, /models shows configured providers, /mcp shows external-server health, and /status makes runtime, permission, and hardware boundaries visible.

The terminal also provides guided, local-first navigation commands:

• /setup [model|notes|qpu] and /ready inspect setup without contacting a model, provider, or QPU.
• /model use PROFILE, /model check [PROFILE], and /model add guide primary-model setup.
• /model notes PROFILE|off selects an optional advisory notes model with no approval authority.
• /plan REQUEST and /review [TARGET] use an isolated read-only, no-MCP model session.
• /usage reports only locally metered requests and bytes; it never invents token or cost totals.
• /qpu [accounts|targets|jobs] reads bounded local broker metadata and cannot submit hardware jobs.
• /new starts a fresh conversation, exactly like /clear.

Deep Agents is the default orchestration runtime. During the compatibility period, skaden --runtime legacy starts the previous provider loop explicitly; Skaden never switches runtimes silently inside a session.

Operational diagnostics are local and separate from authoritative audit/evidence records. By default Skaden keeps the active JSONL log plus five rotating 5 MB backups under the platform state directory (~/.local/state/skaden/logs on Unix-like systems, or %LOCALAPPDATA%\\skaden\\logs on Windows). SKADEN_LOG_DIR selects another private directory. Records contain lifecycle metadata and correlation IDs, not source, prompts, model responses, or credential values. Run sk logs --path-only to locate them and review sk support-bundle output before sharing. Remote LangSmith tracing remains disabled unless SKADEN_LANGSMITH_TRACING is explicitly enabled. See docs/operations.md for recovery and retention guarantees.

Run skaden models list to inspect configured profiles. Skaden stores only environment-variable names—not secret values—and reports credentials as unvalidated until models check completes. Without the selected cloud credential, the same command opens a bounded offline shell. QPU accounts remain disabled until a human separately configures and enables the protected broker; changing the model, terminal approval mode, or MCP configuration cannot enable it.

Install the complete development environment with python -m pip install -e '.[all,dev]', then run sk simulate examples/bell/bell.qasm --shots 1024 --seed 7.

Skaden is the MCP host. Users attach external MCP servers to the standalone terminal; they do not run Skaden as a server inside another coding agent. Attached tools are discovered at runtime, namespaced by server, converted to strict model-callable schemas, and dispatched through Skaden's Tool Gateway. Remote Streamable HTTP connections have explicit lifecycle, timeout, output, and configuration boundaries. Stdio server definitions may be retained in configuration, but this release rejects discovery and execution before resolving their environment or starting a process because they are not isolated from protected QPU authority.

An MCP server is not automatically trusted. sk mcp tools SERVER is the explicit remote discovery action; normal agent startup connects only after at least one exact tool has been allowlisted. Credential and header mappings store environment-variable names rather than values; commands and arguments are stored verbatim and must not contain secrets. Tools are denied until their exact remote names are allowlisted, and every allowed tool is conservatively classified as external execution. Exact-call user approval, result acceptance limits, digest-backed audit events, and fail-closed disconnect behavior continue to apply. External tools cannot acquire built-in authority or mint an approval through the Tool Gateway. Skaden does not infer safety or hardware intent from server-provided names and descriptions: every imported invocation is external execution and requires exact-call human approval. Approval is not a remote sandbox; an approved server can still perform any side effect its operator programmed. Imported results remain untrusted context and cannot become deterministic evidence or authority for the protected QPU broker. The broker's keyring credentials are never exposed to MCP transports, and known quantum/cloud-provider credential environment references are rejected from MCP configuration.

Configure and inspect servers from the terminal:

# Remote Streamable HTTP server. The token value is not written to configuration.
skaden mcp add team-tools \
  --url https://tools.example.com/mcp \
  --header-env Authorization=TEAM_MCP_AUTH

skaden mcp list
skaden mcp inspect team-tools
skaden mcp tools team-tools
skaden mcp allow team-tools EXACT_TOOL_NAME_FROM_THE_DISCOVERY_OUTPUT
# Restart `skaden`, then inspect the namespaced tool under /tools and /mcp.
skaden mcp disable team-tools
skaden mcp remove team-tools --yes

Run skaden mcp --help for the complete client command surface.

See docs/sandbox.md for enforced controls and explicit non-claims, docs/adapter-sdk.md to implement and test an adapter, docs/experiment-runtime.md for portable manifests and reruns, docs/publish-and-cite.md for reproduction bundles, citation, Zenodo, and trusted releases, docs/research-vertical-slice.md for the research workflow contract, docs/qpu-execution.md for the protected IBM workflow and honest limits, docs/qpu-broker-threat-model.md for its security boundary and fault model, docs/deepagents-integration.md for the orchestration boundary, docs/learning.md for local memory, skills, history retrieval, and curation, docs/security-boundaries.md for the trust model, docs/technical_roadmap.md and docs/public_roadmap.md for planned work, and benchmarks/phase0/README.md for the validation protocol.