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. Only a VERIFIED run pushes its branch and opens a PR; 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". 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> "" 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