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 tour    # prints a real receipt from a past build: no key, no spend, no network

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.

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”. 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 primary path: build a task, PRD file or issue, verify it, seal a receipt, open a PR (--no-pr, --deep, --provider, --max-cost). loki "<task>" and loki owner/repo#N are shorthand
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 --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:

Optional:

macOS and Linux are supported.

More

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 founder@autonomi.dev for other arrangements.

Loki Mode is built by Autonomi.

This site is open source. Improve this page.