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.

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 spend
npx 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-repo
loki 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 PR
loki start prd.md                            # same, from a PRD file
loki start owner/repo#123                    # same, from a GitHub, GitLab or Jira issue
loki edit "rename fooBar to foo_bar"         # one small change, no loop
loki chat                                    # interactive alternative: Plan and Build modes

loki start, loki "", loki owner/repo#N and loki quick "" 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 to cap spend, and --provider 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//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/ && 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 . 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 "" seals one signed composite.json over every child receipt, and loki verify /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.

| Run outcome | Receipt verdict | loki start exit | |---|---|---| | VERIFIED, ALREADY_SATISFIED | same | 0 | | FAILED | same | 1 | | PARTIAL | same | 6 | | BUDGET_STOP | none (stopped at a cap) | 3 | | BLOCKED | SPEC_CONFLICT | 4 | | STALLED | none | 5 | | CANCELLED | none | 130 |

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:    VERIFIED
PR:         https://github.com/owner/repo/pull/1
Receipt:    sha256:2f9a41c7e0b3...
NOT PROVEN: full suite, app boot, security scan
Cost:       $0.42 (claude, 212k tokens)
Time:       4m12s (intake 11s, plan 20s, implement 3m10s, verify 31s)

Core commands

| Command | What it does | |---------|--------------| | loki start "" | The command you run: same provider model as a raw session, then the harness re-runs the checks and seals a receipt (--no-pr, --provider, --max-cost, --haiku to run implement and fix on Haiku, climbing to Sonnet on a failed check). loki "" and loki owner/repo#N are shorthand. No task and no git repo shows a receipt and spends nothing | | loki edit "" | One targeted change in one pass, no PR, plan or council (--verify, --receipt, --commit, --dry-run) | | loki quick "" | One small task with a verify loop, no PR | | loki chat | Interactive alternative: Plan and Build modes, slash commands, /run starts a loki start run, --attach joins one | | loki route start | Show the engine, provider, model and reason without running (also --explain-route) | | loki setup | First-run wizard: tools, Claude login, provider, model route, spend cap | | loki config list\|get\|set\|path | Read and write settings | | loki models [--local] | List model routes (OpenRouter, Ollama, LM Studio, llama.cpp, vLLM, custom); discover local models | | loki agents list\|new\|show\|export --claude | Custom child agents in .loki/agents/*.md | | loki status [run-id] | Status of the latest run, or of a given run | | loki verify [run-id] | Check a receipt's hash, signature and event log | | loki answer [run-id] "" | Answer a BLOCKED run; it continues under the same run id (also --text "...") | | loki doctor [--fix] [--json] | Check prerequisites, providers and login; --fix applies safe fixes | | loki control serve | Start the Control Plane (see below) | | loki dashboard | Open the Control Plane UI, starting it if needed | | loki tour | Show a sample receipt offline. loki start does this when you are not in a git repo and did not pass a task | | loki wow | Same live mini-task as a normal start, in a temp repo. Offline sample when no provider is ready | | loki factory "" | Same as loki start. The policy line is printed by start | | loki --help | Everything else; loki help for one command |

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//; 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=/ (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.md
OPENROUTER_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/runs
loki 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 "" 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

• Python 3.8+ (python3): deep scans, Python repos and group runs use it. loki "" 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.

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-mode
npm 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.