Your agent says done. Loki proves it.

An autonomous software factory that knows what it is supposed to deliver, and proves it did.

Website | Documentation | Installation | 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).

Loki Mode is a free, source-available autonomous coding agent by Autonomi. Hand it a PRD, GitHub issue, OpenAPI doc or one-line brief. It derives a delivery contract (the acceptance criteria), builds against it, and ends with a signed Evidence Receipt that states what was proven and what was not. If the contract cannot be derived, it stops and asks one question instead of guessing.

Before a build counts as done, a review council selects reviewers from a specialist pool (agents/types.json, scored by run.sh:FOCUS_KEYWORDS). The bundled MCP server exposes 47 tools over stdio (mcp/server.py), including loki_v10_run, loki_v10_status and loki_v10_verify to start a Loki 10 run in the background, read its phase, verdict and cost, and verify its receipt (BLOCKED runs report their question). Add it with claude mcp add loki-mode -- python3 -m mcp.server from the install directory.

• Install
• Loki 10 engine
• Outcomes and exit codes
• Signed receipts and loki verify
• loki workspace
• Quiet output
• Release channels: next and latest
• loki doctor
• Modernization: status of loki modernize
• Providers

bun install -g loki-mode          # recommended (npm, Homebrew, Docker below)
loki doctor                       # checks your setup, names any blocker

Upgrade with loki self-update. Long form: Installation Guide. npm install -g loki-mode installs the latest dist-tag; see Release channels for next.

Loki needs a model to drive. An ANTHROPIC_API_KEY alone is enough (the Claude Agent SDK ships inside Loki; on the legacy engine this path needs Bun and LOKI_SDK_MODE=full, see Setup details below), or point it at Claude Code, Cline, Codex, Aider or opencode. loki doctor tells you exactly what is missing.

export ANTHROPIC_API_KEY=sk-...
loki doctor
loki quick "fix the login bug"   # one small task on the Loki 10 engine, no PR
loki "fix the login redirect loop" --no-pr   # any task, Loki 10 engine
loki owner/repo#123              # one GitHub, GitLab or Jira issue to a pull request, Loki 10 engine

claude plugin marketplace add asklokesh/loki-mode
claude plugin install loki-mode@loki-mode

loki-seal is a Claude Code Stop hook that runs your repo's real test suite when the agent tries to finish and refuses "done" if tests newly fail or tests or CI config were deleted, skipped or weakened (details: packages/loki-seal/README.md). Install it from the repository's plugin marketplace:

/plugin marketplace add asklokesh/loki-mode
/plugin install loki-seal@loki-mode

Loki 10 is the default engine for loki "<task>", loki owner/repo#N and loki quick "<task>".

Guide, provider table and summary format: docs/v10/GUIDE.md.

loki "fix the login redirect loop" --no-pr

loki owner/repo#123

The v10 engine accepts a quoted multi-word task, a GitHub, GitLab or Jira issue reference, status, verify, dashboard, and other subcommands. Flags (loki-ts/src/engine10/cli.ts USAGE): --no-pr builds and verifies without opening a pull request, --deep requests the deep verify pass and a longer implement budget, --provider <name> picks the coding provider, --max-cost <usd> sets the per-run cost cap (default $100.00 when an API key is set, no dollar cap on a subscription run where the start line adds subscription: no dollar cap; usage counts against your plan limits; or budgets.per_run in loki.yaml; the flag wins; the start line prints it as cap $100.00 (default); reaching it ends the run BUDGET_STOP, exit 3) (--json and --verbose are also parsed by the supervisor, see Quiet output). The engine needs Bun; without it the command exits 1 with a message and installation instructions.

Legacy engine (being removed). Migration note: the previous engine is being removed and has no engine switch; use loki "<task>" and loki owner/repo#N. loki start owner/repo#N, loki start <issue URL> and loki start "<multi-word task>" run on Loki 10, the same as loki owner/repo#N and loki "<task>"; loki start ./prd.md, a flag-first call and a one-word start stay on the legacy engine. For many issues use loki backlog owner/repo --all|--label X|--issues N,N (many issues, N in parallel, each on a loki/backlog-N worktree branch) instead. Legacy removal is planned and resumes on 2026-10-07; see docs/v10/LEGACY-REMOVAL.md. Sections below marked "legacy" describe features that run only on that engine.

Every run starts from an explicit delivery contract and is judged only against it. The stage table lives in loki-ts/src/engine10/machine.ts (FLOW), the stages in loki-ts/src/engine10/stages/.

flowchart TD
    A[Intake: task or issue, repo map, test map] --> P[Plan]
    A --> W[Wall: checks written from the task alone, sealed]
    P --> G{Wall already passes on the base tree?}
    W --> G
    G -- yes --> C[Commit]
    G -- no --> I[Implement]
    I --> V[Verify]
    V -- checks fail --> F[Fix, at most 2 rounds]
    F --> V
    V -- pass, stall, cap or spec conflict --> C
    C --> S[Seal: signed receipt]
    S --> R[PR: opened by the supervisor]
    R --> D[Deep verify, detached: full suite, app boot, council, secret scan]

Warm start (experimental, LOKI_SPEED=1, off by default): loki engine10 dashboard also serves a unix socket at ~/.loki/run/engine.sock (override with LOKI_WARM_SOCK) that keeps the repo map and test map in memory, keyed by the tree SHA plus a hash of dirty files, so an edit invalidates them. A run tries the socket for 50ms and prints warm in Xs when it answers; with no daemon it runs the cold path with identical events.

PR body sample (loki-ts/src/e10ext/reviewer_body.ts):

## What the issue asked
- handles empty input
- rejects bad tokens

## What changed and why
- Why: Fix the parser
- src/parser.ts
- tests/parser.test.ts

## How it was tested
- Verdict: VERIFIED
- Checks: 2 passed, 0 failed, 0 not run, 0 flaky (4 individual tests counted)
- Command: `bun test tests/parser.test.ts` -> pass
- Target tests (written before the fix): parser.test.ts
- Before the fix: 2 failing, 0 passing on base; after: pass

## NOT PROVEN
- none

## Receipt
- Digest: sha256:ab12... (signed)
- Verify: `loki verify run-1`

The run cap is 900s (2700s with --deep, DEFAULT_CAP_S and DEEP_CAP_S in types.ts); commit, seal and pr still run after the cap fires. A run whose cap fired and which did not verify exits BUDGET_STOP.

A finished run prints a short summary (see Quiet output, which also shows an example) whose NOT PROVEN line is never empty by omission: deep checks deferred to the deep-verify pass are always listed there.

loki status [run-id] and loki verify [run-id] are built on the v10 path (bare loki verify follows the newest run, v10 or legacy). Two-way Slack (loki slack serve) is on by default and documented in docs/slack.md; outbound notifications use LOKI_SLACK_WEBHOOK_URL.

Loki 10 can start from a Jira or Linear issue the same way it starts from a GitHub issue: same run, same receipt. The issue is fetched deterministically before any model runs and normalized into the same issue.json, with a source field of jira or linear.

loki jira:PROJ-123     # or https://<site>.atlassian.net/browse/PROJ-123
loki linear:ENG-42     # or a linear.app issue URL

• Jira needs JIRA_EMAIL and JIRA_API_TOKEN, plus JIRA_BASE_URL (for example https://acme.atlassian.net) unless you pass the full browse URL. The ADF description is converted to plain text.
• Linear needs LINEAR_API_KEY.
• A missing variable stops the run before any work with an error naming it (exit code 2, like other intake errors). GitHub refs are unchanged.
• Self-hosted Jira: <JIRA_BASE_URL>/browse/KEY is accepted when its origin matches JIRA_BASE_URL. LOKI_TRACKER_INTAKE=0 turns tracker intake off. Intake only, no sync. Details: docs/trackers.md.

Two-way Slack is on by default. With SLACK_BOT_TOKEN and SLACK_SIGNING_SECRET in the environment, loki slack serve --port N (127.0.0.1 by default) lets you mention @loki <issue ref or task> in a Slack thread to start a run, and a BLOCKED question is answered in the same thread. With either variable missing it prints one line naming both and exits 2 without binding a port. Set LOKI_SLACK_INBOUND=0 to disable it. See docs/slack.md for the scopes.

On by default; set LOKI_CONTRACT=0 to turn it off. It does nothing unless .loki/contract.json exists. loki contract <spec.md> parses a spec or PRD into numbered acceptance criteria (AC-1, AC-2, up to 50) from checklist items (- [ ]) and from bullets and numbered lists under headings such as "Acceptance criteria", "Requirements" or "Must", prints them, and writes .loki/contract.json at the repo root. When a run seals with a contract present, each criterion is matched to changed files and checks by keyword overlap and recorded in an optional contract field on the receipt (keyword_match or no_match). Unmatched criteria are listed under NOT PROVEN in the receipt and the PR body (advisory only, the verdict is unchanged). Keyword overlap is a heuristic: keyword_match means a changed file plausibly relates to the criterion, not that the criterion is proven. The legacy PRD path is unchanged.

Both run on your own GitHub Actions minutes; there is no hosted service.

• Issue to PR: copy docs/examples/loki-issue-to-pr.yml.example to .github/workflows/loki-issue-to-pr.yml in your repository. Label an issue loki, or comment /loki as an owner, member or collaborator, and it runs loki owner/repo#N (the Loki 10 engine) and opens a pull request with an evidence receipt. The agent job holds a read-only token; a separate publish job opens the PR. Set ANTHROPIC_API_KEY in repository secrets.
• Nightly backlog: copy examples/loki-nightly-backlog.yml into .github/workflows/. Its schedule: trigger runs loki backlog owner/repo --label loki, one Loki 10 run per labeled open issue:

on:
  schedule:
    - cron: '17 3 * * *'   # nightly, 03:17 UTC
# ...
      - run: loki backlog "${GITHUB_REPOSITORY}" --label loki --concurrency 2

loki backlog also takes --all, --issues 1,2,3 and --dry-run. The nightly job runs the agent and a write token together, so label only issues you trust.

A v10 run ends in exactly one outcome. The mapping is EXIT in loki-ts/src/engine10/output.ts.

Severity rises with the code, so [ $rc -ge 2 ] always means worse than FAILED. The full table for other commands (loki verify, loki proof verify, loki ci, loki doctor, loki start) is in docs/exit-codes.md; that page does not yet list the v10 run ladder above, which is read from the code.

Known gap: the legacy loki verify exit table in docs/exit-codes.md lists four inputs that do not yet return the documented target. They are tracked as pending moat cases.

Every sealed v10 run writes a receipt to .loki/runs/<run-id>/receipt.json. receipt_sha256 hashes the canonical JSON without the verification block, so verifying never trusts the receipt's own signature field to compute the hash it checks.

Receipts are signed by default. On the first run Loki generates an Ed25519 key at ~/.loki/keys/receipt-ed25519.pem (mode 0600, directory 0700), or you supply your own with LOKI_RECEIPT_SIGNING_KEY or LOKI_RECEIPT_SIGNING_KEY_FILE. See docs/SIGNED-RECEIPTS.md.

loki verify

loki verify [run-id] (latest run by default) re-hashes the receipt, checks the signature against your local key (and retired keys listed in LOKI_RECEIPT_RETIRED_PUBKEYS), and checks the receipt against the event log. Verdicts and exit codes (loki-ts/src/engine10/verify_cmd.ts):

A verified receipt is bound to the run's event log, so a receipt lifted out of its run, or a log edited after sealing, does not verify. Signing proves the receipt came from the key holder; it does not prove the generated code is bug-free. A receipt only claims what its checks ran, and states what they did not.

loki verify <run> --export-dsse > receipt.dsse.json wraps a verified v10 receipt as a DSSE envelope whose payload is an in-toto Statement v1, signed with the Ed25519 receipt key. The export refuses unless the receipt verifies (exit 1 if tampered, 2 if unsigned or unchecked, 66 if no signing key is found) and its run outcome is VERIFIED or ALREADY_SATISFIED (exit 4 otherwise, empty stdout). It takes a receipt, not an envelope (exit 1), and an envelope found under a run id must carry that run id (exit 1). Example: loki verify 20261003-abc --export-dsse > r.dsse.json; echo $? prints 4 for a failed run. loki verify receipt.dsse.json accepts the envelope too; add --pubkey FILE on another machine. Details: docs/SIGNED-RECEIPTS.md.

By default (set LOKI_VISUAL_EVIDENCE=0 to turn it off), a v10 run that changed web page files (html, jsx, tsx, vue, svelte under app/, pages/, src/ or public/) starts the repo's dev, preview or start script and screenshots each changed route with the repo's own Playwright (nothing is downloaded) into a fresh per-run directory .loki/runs/<run_id>/evidence/<random>/ (at most 5 routes, total capture budget 25s, aborted with the seal stage). With an explicit LOKI_VISUAL_EVIDENCE=1, API-only repos with an openapi file also get an HTTP transcript at .loki/runs/<run_id>/evidence/<random>/http.json (not hashed into the receipt). Each screenshot's sha256 is recorded in the receipt as evidence_screens, the PR body gets an Evidence section, and loki verify reports TAMPERED if a recorded screenshot is altered, missing or a symlink. Capture never fails the run; a skip is listed in NOT PROVEN. On by default; it needs Playwright in the repo and changed pages, otherwise it only adds one NOT PROVEN line.

loki workspace runs one issue across several repos. Define groups under the workspaces key in loki.yaml (each with repos, optional per-repo path, setup and after, and an optional integration command), then:

loki workspace list                        # configured workspaces
loki workspace show <name>                 # one workspace's repos and order
loki workspace run <name> owner/repo#N     # or a task text instead of an issue ref
loki workspace status [<run-id>]           # recorded runs, one row per repo

Each repo gets its own worktree and engine run. The command exits 0 only when every repo and the integration step succeed, 3 when the only failures are budget stops, and 1 otherwise. After the integration step, a PR comment is posted on each repo's PR (when one exists) showing the integration status and every head SHA; LOKI_WORKSPACE_COMMENT=0 turns it off. LOKI_WORKSPACES=0 disables the whole command. Full reference: docs/WORKSPACES.md.

The v10 run is quiet by default: no stage chatter, only the final summary. --verbose tails the event stream live (one line per finished stage and a heartbeat with elapsed time and the running diff size). --json prints one JSON object (ok, outcome, stop, run_id, receipt_sha256) instead of text.

The summary is one outcome line, an optional reason on a non-VERIFIED run, then the PR, the receipt, what was NOT PROVEN, the cost and the time (formatSummary in output.ts):

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)

Cost is the provider-reported figure. When a provider does not report cost the line reads not measured, never $0.00. The legacy loki quick is also quiet by default; --verbose or LOKI_VERBOSE=1 shows setup and progress.

Releases are built in slices and shipped in trains: green slices merge, one train is pushed, and the release workflow publishes the exact tested tree to the npm next dist-tag. latest moves only through the promote workflow (.github/workflows/promote.yml), which installs that exact version from npm, runs the first-run gate on it (scripts/first-run-gate.sh --installed), and only then moves latest, Docker :latest and the Homebrew formula. A version whose commit is not an ancestor of main can never become latest.

The first-run gate runs the README's default entry point for a new user on a throwaway repo with a throwaway HOME and a stub provider, and asserts the run is honest: the exit code matches the result, tests are green, only the fix file changed, the printed digest equals what loki verify checks, the receipt is signed, output stays short, and a run that skips the target test does not end VERIFIED.

Policy (D49): every green release is promoted to latest after the automated first-run gate. The promote workflow runs automatically after Post-Release Smoke succeeds; a failed smoke or gate leaves the version on next. workflow_dispatch remains for manual runs of an exact version.

loki doctor            # human-readable check of prerequisites and providers
loki doctor --json     # machine-readable; JSON is emitted in full even on failure
loki doctor --airgap   # audit network egress and how to disable each

Exit 0 when every required check passes; optional warnings (an absent provider CLI) do not fail it. It checks the required tools, the provider CLIs and your login, and says what to install for each gap. The same contract holds for --json, so it is usable as an init-container or CI preflight gate.

Migration: loki modernize heal <repo> --assess was a legacy command for read-only analysis. The v10 path loki modernize <repo> --to <target> is not yet finished: only --dry-run works (inventory, dependency graph, unit clustering, cost, time and risk estimate). A real run stops after the estimate and prints modernize: oracle capture and execution are not built yet; use --dry-run. Targets python3 and java21 exist; the Java dependency graph is not wired in yet. Design: docs/v10/MODERNIZE.md, user summary: docs/v10/GUIDE-MODERNIZE.md.

A local control plane and UI for many runs, on by default. Turn it off with LOKI_CONTROL=0:

loki control serve                       # 127.0.0.1, default port 47821 (--port N, --db PATH)
loki control backfill .                  # ship ./.loki/runs to the control plane
loki control status                      # reachable? how many runs held?
loki control prune --repo acme/widget    # remove those runs from the local control DB (--before DATE, --dry-run)

The URL comes from LOKI_CONTROL_URL, else http://127.0.0.1:${LOKI_CONTROL_PORT:-47821}. While loki control serve is running, runs on this machine ship to it automatically (it publishes ~/.loki/control/instance.json, mode 0600, removed on exit); a run never starts the server. Set LOKI_CONTROL_URL to ship elsewhere. See docs/v10/CONTROL-PLANE.md.

Answering a BLOCKED run: when a run stops on a spec conflict, its run page shows the question and an answer box. Submitting posts to POST /v1/runs/<source>/<run>/answer (JSON {"answer": "..."}, up to 4000 characters, loopback only) and writes ~/.loki/control/answers/<source>/<run>.answer.txt (override the directory with LOKI_CONTROL_ANSWER_DIR). The page prints the resume command, loki answer <run>, which starts a fresh run carrying the task, the question and that file's text (or pass --text "..." yourself; with no run id it picks the newest BLOCKED run). A run that is not BLOCKED exits 2.

The Control Plane is the only UI. loki dashboard, loki dashboard start and loki dashboard open open it (starting loki control serve if none is running). The classic dashboard UI and its port 57374 are removed in 10.8; see docs/control-plane-migration.md for the route mapping and what is not yet available.

Container, Helm and ECS deployment: docs/control-plane-container.md.

Loki's autonomy and quality loop are the product; the coding CLI is swappable. With LOKI_PROVIDER unset, Loki auto-detects the first installed provider in this order (providers/loader.sh): claude, cline, codex, aider, opencode. An explicit choice always wins and is never silently substituted. Gemini CLI is deprecated: LOKI_PROVIDER=gemini exits with a migration message.

Claude Code is the provider Loki is built for and the one that is run end to end by us. The others are wired in but are experimental. On a non-Claude provider the v10 summary says so: the Cost line reads not measured and NOT PROVEN adds kill blocking not enforced. See Provider Guide.

npx loki-mode tour                # no install, no API key, no spend, no network

Prints a real Evidence Receipt from a past build, headline and all:

Headline: VERIFIED WITH GAPS

| Fact          | Value                                    |
| Files changed | 8                                        |
| Diff sha256   | c2be6fff3e774c387f276277b25fc424f07b667… |
| Tests         | verified (node-test)                     |
| Build         | not_run                                  |
| Security      | findings                                 |
| Cost          | $10.3218                                 |

"WITH GAPS" is the point. Build was not run, security has findings, and the receipt says so on its own front page. Recompute the diff hash yourself and check it matches.

Most coding agents declare a task done by telling you so in a transcript. The transcript is the agent's own narration; there is nothing to check. Loki Mode takes a different stance: it does not call work done until the work is verified, and every build produces an Evidence Receipt you can re-verify yourself.

The receipt separates two things most tools blur together:

• Facts -- deterministic, non-LLM, and re-derivable by anyone: the git diff (base/head SHAs, file/insertion/deletion counts, a diff_sha256), the test command that ran with its exit code, the build command with its exit code, and each quality-gate verdict. A skeptic can recompute every one of these from the same repo state.
• Assessments -- AI judgments such as the review council's verdict. These are labeled explicitly as judgment, not proof, and never make the headline green on their own.

The receipt's headline is computed only from the facts:

• VERIFIED -- tests recorded a real command, ran, and exited 0; the diff is non-empty; nothing was skipped.
• VERIFIED WITH GAPS -- some facts checked out, but something was not run or was inconclusive. Every gap is listed by name, so silence never reads as a pass.
• NOT VERIFIED -- a test, build, or gate ran and failed (or there was nothing to verify).

This is honesty-of-done, not a claim of perfection. The receipt proves the completion claim is backed by deterministic evidence and is independently re-checkable; it does not claim the generated code is bug-free.

loki init my-app --template simple-todo-app    # scaffold a starter PRD
loki start owner/repo#123                      # a GitHub issue (Loki 10; same as: loki owner/repo#123)
loki start ./openapi.yaml                      # an OpenAPI/YAML spec
loki demo --offline                            # replay a sample receipt, no key, no spend

export ANTHROPIC_API_KEY=sk-...               # or ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL
LOKI_SDK_MODE=full loki start prd.md          # runs the loop and the judges through the bundled SDK

loki provider set aider
export OPENROUTER_API_KEY=sk-or-...
loki start prd.md                          # defaults to deepseek-v3.2

export LOKI_AIDER_MODEL=openrouter/z-ai/glm-4.6   # or pick your own

# Ollama, fully local (no API key, no per-token cost)
export ANTHROPIC_BASE_URL=http://localhost:11434/v1
export LOKI_MODEL_OVERRIDE=<model you have pulled, e.g. the output of `ollama list`>
loki start prd.md

# LiteLLM / vLLM / any self-hosted gateway
export ANTHROPIC_BASE_URL=https://your-gateway.internal/v1
export ANTHROPIC_API_KEY=...
export LOKI_MODEL_OVERRIDE=<whatever your gateway calls the model>
loki start prd.md

# OrcaRouter (one key for both routes; model ids are namespaced by provider).
# The bare host is deliberate here: the Anthropic SDK appends /v1/messages
# itself, so adding /v1 would double it.
export ANTHROPIC_BASE_URL=https://api.orcarouter.ai
export ANTHROPIC_API_KEY=sk-orca-...
export LOKI_MODEL_OVERRIDE=<namespaced id, e.g. anthropic/claude-sonnet-5>
loki start prd.md

curl -fsSL https://bun.sh/install | bash       # macOS / Linux (or: brew install oven-sh/bun/bun)

For how Loki compares with other tools, see docs/COMPARISON.md and docs/EVALUATING.md.

Run loki --help for all options. Full reference: CLI Reference | Config: config.example.yaml

Pass a config file to loki start with --config <path> (aliases --env-file, --vars), or set LOKI_CONFIG_FILE. The format is detected from the extension or content: .yaml/.yml, .json, or .env (flat LOKI_*=value lines). A CLI flag beats an ambient env var, which beats the --config file, which beats built-in defaults. Never inline a secret; reference an env var with ${VAR}. Manage settings with loki config show|init|edit|path|set|get; a sample is in autonomy/config.example.yaml.

loki start --bmad-project ./my-project

export LOKI_ENTERPRISE_AUTH=true                 # token auth (dashboard/auth.py)
export LOKI_OIDC_ISSUER=https://accounts.google.com
export LOKI_OIDC_CLIENT_ID=your-client-id        # OIDC needs issuer + client id
export LOKI_ENTERPRISE_AUDIT=true                # force audit logging on
export LOKI_TLS_CERT=/path/cert.pem              # HTTPS: set BOTH cert and key
export LOKI_TLS_KEY=/path/key.pem
loki enterprise status

What "autonomous" means: the system runs RARV cycles without prompting. It does NOT access your cloud accounts, payment systems or external services unless you provide credentials. Human oversight is expected for deployment, API keys and critical decisions.

git clone https://github.com/asklokesh/loki-mode.git && cd loki-mode
npm install && npm test              # CLI + Node test suites
python3 -m pytest                    # Python test suite

See CONTRIBUTING.md for guidelines.

Business Source License 1.1 -- Free for personal, internal, academic, and non-commercial use. Converts to Apache 2.0 on March 19, 2030. Contact founder@autonomi.dev for other licensing arrangements.