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 "<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 run that did not verify opens a draft.
• 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". 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.

| Run outcome | Receipt verdict | loki start exit | |---|---|---| | VERIFIED, ALREADY_SATISFIED | same | 0 | | FAILED, PARTIAL | same | 1 | | 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, council, 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 "<task>" | 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 opt the first implement onto haiku). loki "<task>" and loki owner/repo#N are shorthand. No task and no git repo shows a receipt and spends nothing | | loki edit "<change>" | One targeted change in one pass, no PR, plan or council (--verify, --receipt, --commit, --dry-run) | | loki quick "<task>" | 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 <args> | 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] | Start a follow-up run from a BLOCKED run with your answer (--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 "<task>" | Same as loki start. The policy line is printed by start | | loki --help | Everything else; loki help <command> 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

Claude Code is the default Tier-1 provider. --provider codex|cline|aider|opencode (or LOKI_PROVIDER) picks another; on all of them the Loki 10 engine enforces the wall-clock limit and a post-iteration guard scan, and measures cost for codex, cline and aider (parsed from CLI output or estimated, flagged estimated) so --max-cost applies. For 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.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: docs/v10/CONTROL-PLANE.md, 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. The bundled Agent SDK with ANTHROPIC_API_KEY can stand in on the main loki start path, but loki edit and loki chat call the claude CLI.
• Python 3.8+ (python3)
• Node.js 20+ (node; 22 LTS is the CI target)
• jq
• Git 2.x (git)
• curl

Optional:

• Other coding CLIs: Codex, Cline, Aider, opencode (--provider). 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 47 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.