Loki Mode

Loki Mode

Your agent says done. Loki proves it: an autonomous coding agent that turns a task or issue into a verified pull request with a signed receipt you can check yourself.

[npm version] [npm downloads] [Docker Pulls] [License]

Website | Quickstart | Install guide | User guide | CLI reference | Compare with opencode | Changelog

The npm badge above tracks the current release; see CHANGELOG.md for release notes.

CLI reference: docs/CLI-REFERENCE.md (generated from the command registry).

Install

npm install -g loki-mode

The npm package installs the Bun runtime the engine needs as an optional dependency. Other ways in: bun install -g loki-mode, brew tap asklokesh/tap && brew install loki-mode, or docker pull asklokesh/loki-mode:latest (Docker guide). Upgrade with loki self-update.

Want to see a result before you install or spend anything?

npx loki-mode start   # no git repo: a real receipt, no key, no spendnpx loki-mode tour    # the same receipt when you are already inside a repo

npx downloads the package the first time, so that step needs the network. The receipt itself replays offline and checks with no provider and no key.

npx loki-mode wow     # a provider is ready: one tiny real task in a temp repo, its own receipt

First run

Loki needs a model. Claude Code (claude) is the default provider: install it and log in. The bundled Agent SDK with an ANTHROPIC_API_KEY can stand in for the CLI on the main path. Other coding CLIs are optional. See Requirements.

cd your-repoloki setup                                   # first-run wizard (or: loki doctor --fix)loki start "add rate limiting to /api/login" # the primary path: build, verify, seal a receipt, open a PRloki start prd.md                            # same, from a PRD fileloki start owner/repo#123                    # same, from a GitHub, GitLab or Jira issueloki "fix #123"                              # an issue of this checkout; a copied issue or PR URL works as isloki edit "rename fooBar to foo_bar"         # one small change, no looploki chat                                    # interactive alternative: Plan and Build modes

loki start, loki "<task>", loki owner/repo#N and loki quick "<task>" all run on the Loki 10 engine by default, whatever the flag order or input form. Add --no-pr to build and verify without opening a pull request, --max-cost <usd> to cap spend, and --provider <name> to pick another coding CLI. The spend cap defaults to $100 when ANTHROPIC_API_KEY or OPENAI_API_KEY is set and to no dollar cap on a subscription login; budgets.per_run in loki.yaml also sets it. Inspect the route without running: loki route start prd.md or --explain-route. New here? The 5-minute quickstart walks through it.

What you get

Every run starts from a delivery contract derived from your task, writes checks from the task alone before touching code, implements, verifies, and ends in exactly one outcome: VERIFIED, ALREADY_SATISFIED, FAILED, BUDGET_STOP, BLOCKED or STALLED (exit codes). If the contract cannot be satisfied as written, the run stops and asks one question instead of guessing.

• A pull request written for a quick review: what the issue asked, what changed, how it was tested, and what was NOT PROVEN. A VERIFIED run opens a ready PR; a PARTIAL run opens a draft PR titled [PARTIAL] that leads with what is not proven; any other outcome keeps the branch local and prints where it is.
• A signed receipt at .loki/runs/<run-id>/receipt.json, signed with a local Ed25519 key created on first run.
• A specialist review when the review council runs: it selects reviewers from a specialist pool (agents/types.json, scored by run.sh:FOCUS_KEYWORDS) by matching the changed files and diff against each reviewer's keywords.

loki verify              # newest run; or: loki verify <run-id>

loki verify re-hashes the receipt, checks its signature and checks it against the run's event log. It prints a verdict and exits 0 (VERIFIED), 1 (TAMPERED), 2 (UNCHECKED), 3 (UNSIGNED, refused unless --allow-unsigned), 4 (run outcome not verified) or 66 (no runs); [ $rc -eq 0 ] is the only safe test for "verified". It also checks that your checkout still matches the sealed code: a run that opened a PR returns you to your starting branch, so verify it from the run's branch (git fetch origin loki/<run-id> && git checkout --detach FETCH_HEAD), or it reads UNCHECKED and says so. loki start also requires fail-to-pass for a declared behavior change: a Wall test must fail on the old code and pass after, or the verdict stays PARTIAL (LOKI_MUTATION_STRICT=0 opts out). Full table: docs/exit-codes.md. On another machine, export the public key with loki keys export and pass it with loki verify --pubkey <file>. A receipt claims only what its checks ran, and lists what they did not; signing proves who produced it, not that the code is bug-free. Details: docs/SIGNED-RECEIPTS.md.

For a multi-repo change set, loki start --workspace <name> "<brief>" seals one signed composite.json over every child receipt, and loki verify <run-dir>/composite.json re-checks it offline (docs/WORKSPACES.md). A composite never reads higher than its weakest child.

Two vocabularies, not one. Receipt verdicts (sealed, 5): VERIFIED, PARTIAL, ALREADY_SATISFIED, SPEC_CONFLICT, FAILED. Run outcomes (printed, 8): VERIFIED, ALREADY_SATISFIED, PARTIAL, FAILED, BUDGET_STOP, BLOCKED, STALLED, CANCELLED. BUDGET_STOP, BLOCKED, STALLED and CANCELLED are run outcomes, never receipt verdicts.

Composite: every child VERIFIED or ALREADY_SATISFIED gives VERIFIED (all ALREADY_SATISFIED stays ALREADY_SATISFIED, any SPEC_CONFLICT child keeps SPEC_CONFLICT); one PARTIAL child caps it at PARTIAL; a FAILED child fails it. loki verify on a composite exits 0 VERIFIED, 1 TAMPERED, 2 UNCHECKED, 3 UNSIGNED.

Autonomy and deploy: .loki/policies.json autonomy: propose|execute|operate governs what loki start may do (propose opens nothing, execute opens a PR, operate also allows deploy); no file keeps today's behavior. loki trust prints advisory graduation advice from your receipts and never writes the policy. Loki deploys only behind loki deploy --execute (or loki start --deploy) plus a VERIFIED, HEAD-anchored receipt and the policy permission; --health-url and --auto-rollback add a post-deploy probe and a documented provider rollback. A Sentry alert webhook can enqueue a receipt-gated fix PR (docs/sentry-intake.md).

A finished run prints a short summary (every run on both engines also ends with a unified Result, Files, Cost, Elapsed, Receipt and next: block; --quiet prints only that block, --json adds a summary object):

Outcome:    VERIFIEDPR:         https://github.com/owner/repo/pull/1Receipt:    sha256:2f9a41c7e0b3...NOT PROVEN: full suite, app boot, security scanCost:       $0.42 (claude, 212k tokens)Time:       4m12s (intake 11s, plan 20s, implement 3m10s, verify 31s)

Core commands

Core verbs: docs/CLI-CORE-VERBS.md. Every command (generated): docs/CLI-REFERENCE.md. Engine guide, provider table, model routes, custom agents and chat: docs/v10/GUIDE.md. Honest comparison with opencode: docs/COMPARE-OPENCODE.md.

Models, providers and local models

Two providers are supported. Claude Code is the default Tier-1 provider (the claude CLI, or, with only ANTHROPIC_API_KEY, the Anthropic Agent SDK). --provider opencode (or LOKI_PROVIDER=opencode) runs opencode, which reaches any model, including OpenRouter: export OPENROUTER_API_KEY and pass --model openrouter/<vendor>/<model>; the Loki 10 engine enforces the wall-clock limit and a post-iteration guard scan there. codex, cline, aider and gemini were removed and exit 2 with a one-line migration message. To keep the Claude harness on OpenRouter or a local model, set LOKI_MODEL_ROUTE=<kind>/<id> (kinds: openrouter, ollama, lmstudio, llamacpp, vllm, custom) before loki start; loki models --local finds local runtimes and prints ready-to-paste values.

LOKI_MODEL_ROUTE=ollama/qwen3-coder loki start prd.mdOPENROUTER_API_KEY=sk-or-... loki start --provider opencode --model openrouter/deepseek/deepseek-v3.2 prd.md

Control Plane

A local UI and API for all your runs: outcomes, receipts, costs, and an answer box for BLOCKED runs. It is on by default (LOKI_CONTROL=0 turns it off) and listens on 127.0.0.1 only.

loki control serve       # http://127.0.0.1:47821 (--port N, --db PATH)loki control backfill .  # load existing ./.loki/runsloki control status      # reachable? how many runs?

While it is running, runs on this machine ship to it automatically. Guides: container, Helm and ECS, migrating from the old dashboard.

Requirements

loki doctor enforces this list.

Required:

• Claude Code (claude), installed and logged in: the default provider and the only one with every feature. Or only ANTHROPIC_API_KEY: loki "<goal>" then runs on the bundled Agent SDK with no CLI and no extra setting, but loki edit and loki chat call the claude CLI.
• Node.js 20+ (node; 22 LTS is the CI target)
• Git 2.x (git)
• curl

Optional:

• Python 3.8+ (python3): deep scans, Python repos and group runs use it. loki "<goal>" runs without it.
• jq: loki status and the bash fallback CLI use it.
• opencode (--provider opencode) for any model, including OpenRouter. Ollama or an OpenRouter key for model routes.
• Bun 1.3+ (bun) on your PATH (the npm package also bundles it).
• Docker, to run Loki from the published image.

macOS and Linux are supported.

More

• Installation, environment variables, exit codes, known issues, privacy and telemetry
• Agent Change Receipt format: docs/AGENT-CHANGE-RECEIPT.md
• Issue to PR from GitHub Actions, no hosted service: docs/examples/loki-issue-to-pr.yml.example
• Jira and Linear intake: docs/trackers.md. Two-way Slack: docs/slack.md. Multi-repo runs and composite receipts: docs/WORKSPACES.md. Deploy: docs/DEPLOY-PLAN.md
• MCP: the bundled server exposes 48 tools over stdio (loki mcp), including starting a run, reading its status and verifying its receipt. One-click install: Cursor, VS Code. Or run loki mcp install --client claude|cursor|vscode|windsurf.
• Claude Code plugin: claude plugin marketplace add asklokesh/loki-mode, then claude plugin install loki-mode@loki-mode. The same marketplace ships loki-seal, a Stop hook that refuses "done" when tests newly fail or were weakened.
• Architecture: docs/ARCHITECTURE.md. Upgrading: UPGRADING.md

Contributing

git clone https://github.com/asklokesh/loki-mode.git && cd loki-modenpm install && npm test

See CONTRIBUTING.md, TESTING.md and the Code of Conduct.

License

Business Source License 1.1. Free for personal, internal, academic and non-commercial use; it converts to Apache 2.0 on March 19, 2030. Contact [email protected] for other arrangements.

Loki Mode is built by Autonomi.