{
  "markdown": "<div align=\"center\">\n\n# Loki Mode\n\n### The spec-driven autonomous builder with verified completion.\n\n_The free, source-available autonomous coding agent by [Autonomi](https://www.autonomi.dev/). Same Loki CLI, SDK, and MCP for everyone; the commercial editions for teams and enterprises are sold under the **Autonomi** brand (Autonomi Cloud, Autonomi Enterprise)._\n\n**Hand it a spec. It does not accept \"done\" on an empty diff or failing tests.**\n\n[![npm version](https://img.shields.io/npm/v/loki-mode?style=for-the-badge&logo=npm&logoColor=white&color=553DE9)](https://www.npmjs.com/package/loki-mode)\n[![npm downloads](https://img.shields.io/npm/dt/loki-mode?style=for-the-badge&logo=npm&logoColor=white&color=1FC5A8&label=downloads)](https://www.npmjs.com/package/loki-mode)\n[![Docker Pulls](https://img.shields.io/docker/pulls/asklokesh/loki-mode?style=for-the-badge&logo=docker&logoColor=white&color=2F71E3)](https://hub.docker.com/r/asklokesh/loki-mode)\n[![License](https://img.shields.io/badge/License-BUSL--1.1-36342E?style=for-the-badge)](LICENSE)\n\n[Website](https://www.autonomi.dev/) | [Documentation](wiki/Home.md) | [Installation](docs/INSTALLATION.md) | [Changelog](CHANGELOG.md)\n\n</div>\n\n---\n\n## Install\n\n```bash\nbun install -g loki-mode          # recommended (npm, Homebrew, Docker below)\n```\n\n<details>\n<summary>Other install methods</summary>\n\n| Method | Command | Notes |\n|--------|---------|-------|\n| **Bun (recommended)** | `bun install -g loki-mode` | Fastest startup for CLI commands. |\n| **npm** | `npm install -g loki-mode` | Works without Bun (bash fallback). Migrate any time with `loki self-update --to bun`. |\n| **Homebrew** | `brew tap asklokesh/tap && brew install loki-mode` | Auto-installs Bun as a dep. |\n| **Docker** | `docker pull asklokesh/loki-mode:latest` | Bun + Claude CLI pre-installed. See [DOCKER_README.md](DOCKER_README.md). |\n\nUpgrade with `loki self-update`. Long form: [Installation Guide](docs/INSTALLATION.md).\n\n</details>\n\n<details>\n<summary>Claude Code plugin (adds /loki-grill, /loki-spec-status, /loki-verify)</summary>\n\n```bash\nclaude plugin marketplace add asklokesh/loki-mode\nclaude plugin install loki-mode@loki-mode\n```\n\nAdds three slash commands and the Loki MCP server (memory, task queue, code\nsearch, build management) to Claude Code. It calls the CLI rather than bundling\nit, so install `loki-mode` above first. Verify with `claude plugin list`:\na healthy install reports `Status: enabled`.\n\n</details>\n\n## Use it\n\n```bash\nloki quickstart                   # guided first build: asks a few questions, quotes cost, builds\n```\n\nThat is the whole happy path. It asks for a one-line idea, picks a template,\nshows the real cost and time estimate before spending anything, then builds.\nPress Enter through every step and you get a sample Todo app.\n\nOne command, no prompts (CI, scripts, containers, any shell without a terminal):\n\n```bash\nloki quickstart \"a todo app with user accounts\" --yes\n```\n\nBoth halves are required with no terminal: an idea (or a path to a PRD file)\nand an explicit `--yes`. Given both, Loki picks the top-ranked template\nautomatically, prints the same honest cost and time estimate, and starts the\nbuild without asking anything. Missing either half exits 2 with the\nneeds-a-terminal message and writes nothing, so an ambient `LOKI_AUTO_CONFIRM`\nor a stray argument in CI can never start a paid build on its own. Existing\nfiles are never overwritten: if `prd.md` is present the PRD lands at\n`prd-quickstart.md`, then numbered suffixes as needed.\n\nChoose an exact shipped starter when the top-ranked match is not the one you\nwant:\n\n```bash\nloki quickstart --list-templates\nloki quickstart --list-templates --json       # schema-v1 automation output\nloki quickstart \"an internal reporting workspace\" --template dashboard --yes\n```\n\nTemplate discovery works without a terminal or provider and lists every shipped\nstarter's stable name and purpose in catalog order. It returns before estimation,\nconsent, PRD writes, or build execution. Positional input and execution/preview\nflags are intentionally incompatible; `--json` is the only optional modifier.\n\n`--template` accepts an exact template name for idea inputs and works the same\nway with interactive use or `--dry-run` (including JSON preview). Unknown\ntemplates, duplicate flags, and combinations with a PRD path refuse before\nprovider discovery, estimation, writes, or build execution.\n\nPreview the same deterministic template choice and estimator-backed plan with\nzero writes or execution:\n\n```bash\nloki quickstart \"a todo app with user accounts\" --dry-run\n```\n\nPreview requires an idea or readable PRD path, works without a terminal or AI\nprovider, and exits before creating a PRD or starting a build. `--dry-run` and\n`--yes` are mutually exclusive so execution intent is never ambiguous.\n\nFor scripts and local dashboards, add `--json` to receive one versioned JSON\nobject instead of terminal text:\n\n```bash\nloki quickstart \"a todo app with user accounts\" --dry-run --json > preview.json\nloki quickstart --verify-preview preview.json --json\nloki quickstart --from-preview preview.json --yes\n```\n\nThe object contains the input kind, deterministic selected template (or `null`\nfor an existing PRD), the exact estimator response under `plan`, and a bounded\ncontinuation containing the exact idea/template or the PRD path and SHA-256.\n`--verify-preview` validates the same bounded duplicate-key-rejecting schema and\nrequires either a currently shipped idea template or the unchanged digest-bound\nPRD, while emitting no idea or PRD path. It accepts a file or piped stdin and\nreturns before provider discovery, estimation, writes, or build execution.\n`--from-preview` requires explicit argv `--yes`, rejects malformed, conflicting,\nsymlinked, or changed inputs before provider and build boundaries, then uses the\nexisting no-clobber quickstart path. The saved plan is evidence rather than\nexecution authority: Loki recomputes and displays the current estimate before\nstarting. `--json` requires `--dry-run`; invalid input or estimator failure\nwrites no JSON, and preview still exits before provider discovery, file writes,\nor build execution.\n\nOr go straight at it:\n\n```bash\nloki quick \"build a landing page with a signup form\"     # one-shot task\nloki start prd.md                                        # build from a spec you wrote\nloki modernize heal ./your-repo --assess                 # existing codebase, read-only\n```\n\n**Loki needs a model to drive.** An `ANTHROPIC_API_KEY` alone is enough (the\nClaude Agent SDK ships inside Loki); or point it at Claude Code, aider, cline,\nor an open model. Run `loki doctor` and it tells you exactly what is missing.\n\n```bash\nexport ANTHROPIC_API_KEY=sk-...\nloki doctor                       # checks your setup, names any blocker\n```\n\n## Try it first, without installing\n\n```bash\nnpx loki-mode tour                # no install, no API key, no spend, no network\n```\n\nPrints a real Evidence Receipt from a past build, headline and all:\n\n```\nHeadline: VERIFIED WITH GAPS\n\n| Fact          | Value                                    |\n| Files changed | 8                                        |\n| Diff sha256   | c2be6fff3e774c387f276277b25fc424f07b667… |\n| Tests         | verified (node-test)                     |\n| Build         | not_run                                  |\n| Security      | findings                                 |\n| Cost          | $10.3218                                 |\n```\n\n**\"WITH GAPS\" is the point.** Build was not run, security has findings, and the\nreceipt says so on its own front page. Recompute the diff hash yourself and\ncheck it matches -- you are not asked to trust the agent's self-report.\n\n---\n\n> **How it works:** Drop a spec -- a PRD, GitHub issue, OpenAPI/JSON/YAML, or one-line brief. Loki Mode classifies complexity (`run.sh:detect_complexity()`), selects reviewers from a specialist pool (`agents/types.json` ships 41 role definitions; 10 are keyword-scored by the review selector at `run.sh:FOCUS_KEYWORDS`, alongside the mandatory reviewers, and the rest are role descriptions in `references/agents.md` that the orchestrator adopts per phase rather than separate processes), with parallel review (blind council) and optional worktree streams on Claude Code, sequential on other providers - and runs autonomous RARV cycles (Reason - Act - Reflect - Verify, see `run.sh:run_autonomous()`) with 8 quality gates (see `skills/quality-gates.md`). Code is not \"done\" until it passes automated verification. Output is a Git repo with source, tests, configs, and audit logs.\n\n---\n\n<details>\n<summary><b>Why verified completion matters</b> -- the failure this exists to fix</summary>\n\nSelf-reported completion is the failure users actually hit. A survey of the\nopen issue trackers of seven coding harnesses (OpenHands, Cline, Aider,\nSWE-agent, Roo-Code, OpenCode, Continue) found the recurring complaint is the\nagent silently not doing the work -- \"always stuck at Preparing write\"\n([opencode#11112](https://github.com/anomalyco/opencode/issues/11112), 76\ncomments), \"Continue not making changes to code\"\n([continue#7143](https://github.com/continuedev/continue/issues/7143)), \"Agent\ndoes not execute functions\"\n([continue#5696](https://github.com/continuedev/continue/issues/5696)). None of\nthose seven publishes a machine-checkable completion artifact.\n\nWe measured every named competitor that ships a local CLI -- opencode 1.18.9,\naider 0.86.2, codex-cli 0.146.0, Claude Code 2.1.220, cursor-agent -- and none\nexposes a command that verifies the agent's own output. Rerun it yourself with\n`bash tests/test-competitor-verify-surface.sh`.\n\nThat is a measurement of the CLI surface, not of whole products: a web UI or an\nAPI could expose something `--help` does not, and Devin and Replit Agent ship no\nlocal CLI so they are not covered.\n\n**Evaluating this against something else?** [docs/EVALUATING.md](docs/EVALUATING.md)\nputs a runnable command next to every claim we make, and states plainly what we\ndo not have (no enterprise case studies, no independent benchmark placement, and\ngeneration is not air-gapped). It ends with the one question worth asking any\nagent vendor, including us.\n\n</details>\n\n## Already have a codebase? Start read-only.\n\nMost agents are built to create new apps. The harder, more valuable problem is\nthe ten-year-old repo that pays the bills. Loki works on both, and on an\nexisting codebase it starts by **changing nothing**:\n\n```bash\nloki modernize heal ./your-repo --assess          # read-only. no writes, no commits.\nloki modernize heal ./your-repo --assess --json   # same, machine-readable\n```\n\nYou get a modernization readiness report: language mix, a 4-level maturity\nrating, technical-debt signals (test coverage, TODO density, oversized files,\ndependency staleness), and a **ranked list of where to start** -- ordered by\nblast radius, so the first change is the one least likely to break something.\n\nThen, if you want it to act:\n\n```bash\nloki modernize heal ./your-repo --strict          # block ALL behavioral change without approval\nloki modernize heal ./your-repo --phase archaeology   # extract knowledge only\nloki modernize heal ./your-repo --compliance healthcare   # or fintech | government\n```\n\nThe healing pipeline runs in phases -- archaeology, stabilize, isolate,\nmodernize, validate -- and the validate phase checks **behavioral equivalence\nagainst the pre-change baseline**, not just that the tests are green. Friction\npoints (the weird code that exists for a reason nobody remembers) are cataloged\nbefore anything touches them, because in a legacy system the strange code is\nusually load-bearing.\n\n## The Evidence Receipt: don't trust the agent, check it\n\nEvery coding agent tells you it finished. Loki hands you something you can\ncheck yourself.\n\n**We are not the only tool that checks its own work, and you should be\nsuspicious of anyone who claims to be.** Lovable runs a security scan on every\npublish and can block the publish outright. Claude Code's review has a step that\nchecks findings against actual code behavior. Replit says its agent tests its\nown work.\n\nThe difference is what you are left holding. Their output lives in their\ndashboard: a findings count in a dialog, a check run that by design never blocks\na merge. Ours is a **file**. It is bound to a specific diff by `diff_sha256`, it\nrecords what was NOT proven as prominently as what was, and someone who has\nnever installed Loki can re-verify it from the repository alone. Commit it,\nattach it to the PR, hand it to an auditor.\n\nPortable, diff-bound, and honest about its gaps -- that is the claim, and it is\nthe one worth checking.\n\nEach run writes a receipt to `.loki/proofs/<run_id>/` that separates\n**deterministic FACTS** (the git diff with base and head SHAs plus a\n`diff_sha256`, the test command and its exit code, the build command and its\nexit code, each gate verdict) from **AI ASSESSMENTS** (the council verdict,\nlabeled as judgment, never as proof). The headline is computed from the facts\nalone:\n\n| Headline | Means |\n|---|---|\n| VERIFIED | tests ran a real command and exited 0, diff non-empty, nothing skipped |\n| VERIFIED WITH GAPS | each gap listed by name |\n| NOT VERIFIED | a check ran and failed |\n\n```bash\nloki proof list            # every receipt from this project\nloki proof show <id>       # the facts, the assessments, and the headline\nloki proof verify <id>     # re-hash the receipt and re-derive the diff\n```\n\n`loki proof verify` exits 0 clean, 1 on tamper or drift. Receipts are attached\nto pull requests automatically (`LOKI_PROVEN_PR=0` to opt out), so a reviewer\nsees the evidence next to the code.\n\n**What the receipt does NOT claim.** On the unsigned path the generator is\ntrusted: someone who rewrites both the facts and the headline into a mutually\nconsistent lie and recomputes the hash will still pass verification. That is\ndefense-in-depth, not non-forgeability, and neutral non-forgeability needs the\nsigned record. We tested for exactly this and locked the limitation into the\nsuite (`tests/test-proof-forgery-defense.sh`), and in v7.111.0 we removed our\nown earlier \"non-forgeable\" claim once we found it was false on that path. An\nhonest boundary you can verify beats a marketing claim you cannot.\n\nTo close that gap, sign your receipts: `export LOKI_PROOF_GPG_KEY=<key-id>` and\nevery receipt carries a detached GPG signature that any third party with your\npublic key can verify offline. See [docs/SIGNED-RECEIPTS.md](docs/SIGNED-RECEIPTS.md).\n\n## Why Loki Mode?\n\n- **Spec-driven, autonomous, with a built-in trust layer** -- Hand Loki a spec, walk away, come back to working code with tests. The full RARV-C closure loop (Reason - Act - Reflect - Verify - Close) runs until the work is actually done, not just attempted. The verified-completion evidence gate (`skills/quality-gates.md`) refuses any \"done\" claim on an empty git diff against the run-start commit, blocks completion when tests run red, and (v8.0.0) also blocks when a serveable app is confirmed unhealthy (runtime-boot axis, opt out `LOKI_EVIDENCE_BOOT_GATE=0`) or a credential is detected in the changed files (secret-leak axis, opt out `LOKI_EVIDENCE_SECRET_GATE=0`), so \"complete\" means proven, not promised.\n- **A checklist verifier that is honest, not brittle** -- Each completion checklist item is checked deterministically before the completion council will accept \"done\". The verifier speaks extended regex (`grep -E`) so real LLM-emitted patterns match instead of erroring, and it is runner-agnostic: it runs the project's own declared test command rather than assuming a fixed runner. Crucially, a check that cannot be established is reported as inconclusive (pending), never as a false pass and never as a false failure. `rc == 0` alone is not a pass; a test check goes green only on a real \"N passed\" signal from the runner (v7.121.x).\n- **Production quality built in** -- 8 quality gates (`skills/quality-gates.md`), blind 3-reviewer code review (`run.sh:run_code_review()`), anti-sycophancy checks\n- **Standalone verification: `loki verify`** -- Run Loki's deterministic gates (build, tests, static analysis, secret scan, dependency audit) against any branch or PR diff, including code written by other agents or humans. CI-ready exit codes (0 VERIFIED, 1 CONCERNS, 2 BLOCKED), machine-readable evidence at `.loki/verify/evidence.json`. Inconclusive evidence is never reported as VERIFIED (v7.27.0).\n- **Living spec and pre-build interrogation** -- `loki spec` locks a spec and detects drift deterministically (`spec.lock`, `drift-report.json`, and a `SPEC_DRIFT` finding in `loki verify` with CI exit codes), so you can tell when the build diverges from what was agreed. For an OpenAPI/GraphQL/Postman contract it locks one requirement per operation with a per-operation hash, so a single changed response schema drifts exactly that operationId (v8.0.0). `loki grill` runs a Devil's-Advocate interrogation of the spec before you build, surfacing gaps and contradictions early (v7.28.0).\n- **Mid-flight model switching** -- switch the model a live run uses from the dashboard (applies at the next iteration, current run only). A Fable tier lever exists in the CLI, dashboard, and override paths, but Claude Fable 5 is not yet available at the API, so selecting Fable currently collapses to Opus at every dispatch chokepoint and the `loki plan` quote reflects Opus accordingly. For every model lever (session pin, mid-flight override, architect pass) and every `LOKI_MAX_TIER` path, the `loki plan` quote, the dashboard's reported model, and the actual dispatched model agree, with the ceiling enforced (v7.31.0; Fable-to-Opus collapse v7.39.1).\n- **A calmer CLI** -- the help surface is ~20 grouped workflow entries instead of a 70-command wall; merged commands live on as aliases that forward byte-identically with a one-line stderr pointer, so no script breaks (v7.31.0).\n- **Guided first build: `loki quickstart`** -- four quick questions (setup check, one-line idea, template pick, plan review) and your build starts; pressing Enter through every step builds the sample Todo app. The plan step quotes the real cost/time estimate before anything is spent, and `loki demo` now confirms its estimate the same way. If no AI provider CLI is installed, Loki offers to install Claude Code (consent-gated, interactive terminals only) (v7.29.0).\n- **Live App Preview** -- The dashboard embeds the locally-running app in an iframe so you can interact with it immediately during a build. Use `loki preview` (alias `loki open`) to print the URL and open it in your browser. Local-first: no hosted service, no vendor lock (v7.24.0).\n- **Compose-first fullstack** -- When a spec needs more than one service (web + database + cache) Loki generates a 12-factor `docker-compose.yml` with healthchecks, `depends_on` wiring, env-var config, and a `.env.example`. The Live App Preview surfaces the web service URL (not a database port), and health reflects the web service's Docker healthcheck so a crashed app shows as crashed even when the database stays up. Single-service apps stay on a plain run command. All local-first, no hosted service (v7.26.0).\n- **Intelligent `loki start`** -- For interactive foreground runs the dashboard auto-opens in the browser (cross-platform; skipped in CI, SSH-without-TTY, and piped runs; opt out with `LOKI_NO_AUTO_OPEN=1`). The completion summary shows \"Your app is live at <url>\" so you know exactly where to try what Loki just built. The autonomous loop passes Claude Code's `--effort`, `--max-budget-usd`, and `--fallback-model` on every iteration (each gated on CLI support and individual opt-out env vars) for better long-run unattended execution (v7.25.0).\n- **Confidence is not evidence** -- When the agent's self-reported confidence spikes to near-certainty, Loki forces an EXTRA verification pass before accepting a stop, rather than taking the claim at face value. Strictly additive: high confidence makes the engine look harder, never less hard, and it can never skip or satisfy a gate (v8.0.0, opt out `LOKI_CONFIDENCE_SPIKE=0`).\n- **Goals it can actually measure** -- A goal with no checkable success condition (\"make it fast\") gives the loop no gradient: every iteration can claim progress and none can be verified. Loki flags an un-measurable goal up front and asks for a threshold, a metric, or a concrete artifact. Advisory only, and never rewrites your goal (v8.0.0, opt out `LOKI_GOAL_SCORING=0`).\n- **Stops paying for failures that cannot succeed** -- A positively-identified permanent failure (bad credentials, unknown model, exhausted quota) exits immediately instead of burning the retry budget on guaranteed-identical failures. Fail-safe: an unrecognized error still retries exactly as before, and rate limits are never treated as permanent (v8.0.0, opt out `LOKI_SMART_RETRY=0`).\n- **Cross-project memory** -- Episodic/semantic/procedural memory with vector search; knowledge learned on one project surfaces on the next (v5.15.0+, see `memory/engine.py`)\n- **Self-hosted and private** -- Your keys, your infrastructure, no data leaves your network\n- **Legacy system healing** -- `loki modernize heal` archaeology/stabilize/isolate/modernize/validate phases (v6.67.0, see `skills/healing.md`)\n- **MCP server** -- 36 tools (including ChromaDB code search) plus 3 resources and 2 prompts (`mcp/server.py`, with magic tools registered from `mcp/magic_tools.py` and the managed-memory tool from `mcp/managed_tools.py`). Of the 36, 35 are always available; `loki_memory_redact` is registered but only succeeds when `LOKI_MANAGED_AGENTS=true` and `LOKI_MANAGED_MEMORY=true`. Launch with `loki mcp` (bootstraps the Python MCP SDK on first run).\n- **Full-stack output** -- Source code, tests, Docker Compose stacks (multi-service with healthchecks), CI/CD pipelines, audit logs\n- **Provider-agnostic** -- runs on Claude, Cline, Codex, Aider, or opencode with automatic failover (`loki-ts/src/runner/providers.ts`); no vendor lock-in. When `LOKI_PROVIDER` is unset, Loki auto-detects in that order; an explicit choice always wins and is never silently substituted. Gemini was removed as a provider in v7.5.18.\n- **Source-available (BUSL-1.1)** -- Free for personal, internal, and academic use.\n\n---\n\n## Loki does not lie about \"done\"\n\nMost coding agents declare a task done by telling you so in a transcript. The\ntranscript is the agent's own narration; there is nothing to check. Loki Mode\ntakes a different stance: it does not call work done until the work is verified,\nand every build produces an **Evidence Receipt** you can re-verify yourself.\n\nThe receipt separates two things most tools blur together:\n\n- **Facts** -- deterministic, non-LLM, and re-derivable by anyone: the git diff\n  (base/head SHAs, file/insertion/deletion counts, a `diff_sha256`), the test\n  command that ran with its exit code, the build command with its exit code, and\n  each quality-gate verdict. A skeptic can recompute every one of these from the\n  same repo state.\n- **Assessments** -- AI judgments such as the review council's verdict. These are\n  labeled explicitly as judgment, not proof, and never make the headline green on\n  their own.\n\nThe receipt's headline is computed only from the facts:\n\n- **VERIFIED** -- tests recorded a real command, ran, and exited 0; the diff is\n  non-empty; nothing was skipped.\n- **VERIFIED WITH GAPS** -- some facts checked out, but something was not run or\n  was inconclusive. Every gap is listed by name, so silence never reads as a pass.\n- **NOT VERIFIED** -- a test, build, or gate ran and failed (or there was nothing\n  to verify).\n\nThis is honesty-of-done, not a claim of perfection. The receipt proves the\ncompletion claim is backed by deterministic evidence and is independently\nre-checkable; it does not claim the generated code is bug-free.\n\n<details>\n<summary><strong>Verify a receipt yourself -- <code>loki proof</code> commands, tamper/drift checks, proven PRs (advanced)</strong></summary>\n\n### Verify it yourself\n\nReceipts are written to `.loki/proofs/<run_id>/` automatically at run completion\n(opt out with `LOKI_PROOF=0`). Inspect and re-check them with `loki proof`\n(aliased as `loki receipt`):\n\n```bash\nloki proof list              # every receipt: run id, time, council verdict, cost, files\nloki proof show <id>         # the full proof.json (facts, assessments, honesty)\nloki proof verify <id>       # re-check the receipt against the repo (exit 0 clean, 1 tamper/drift)\n```\n\n`loki proof verify` does two independent checks and prints the result as JSON:\n\n- **Tamper check** -- recomputes the receipt's integrity hash and compares it to\n  the recorded one. If anyone edited the receipt after it was written, `hash_ok`\n  is `false`.\n- **Drift check** -- re-runs the diff from the recorded base SHA against the\n  current repo and compares the file/insertion/deletion counts and `diff_sha256`\n  to what the receipt recorded. If the repo no longer matches, `diff_drift` is\n  `true`.\n\nA clean receipt prints `\"ok\": true` and exits 0. A tampered or drifted receipt\nexits 1. When a check cannot run (for example a receipt with no recorded base\nSHA), the verifier reports it as unverifiable rather than passing it silently.\n\n```json\n{\n  \"hash_ok\": true,\n  \"diff_drift\": false,\n  \"gpg_ok\": \"n/a\",\n  \"degraded\": [],\n  \"reason\": \"\",\n  \"ok\": true\n}\n```\n\nYou can share a receipt as a self-contained HTML page (`loki proof open <id>`),\nor publish it as a GitHub Gist with `loki proof share <id>` (opt-in; the page is\nredacted before it leaves your machine). An optional, off-by-default GPG detached\nsignature (`LOKI_PROOF_GPG_KEY`) lets a third party confirm the receipt came from\nyou.\n\n### Proven PR\n\nWhen Loki opens a pull request, the PR body includes the Evidence Receipt\nsummary, so a reviewer does not have to take the agent on faith. It shows the\nhonest verdict (VERIFIED / VERIFIED WITH GAPS / NOT VERIFIED), the key facts\n(diff hash, tests, secure-gate, cost), and a \"verify this yourself\" line:\n`loki proof verify <id>` against the recorded base SHA. A green claim appears\nonly when the receipt's own headline is VERIFIED. This is on by default whenever\nLoki opens or advises a PR; opt out with `LOKI_PROVEN_PR=0`.\n\nFor a review-before-publish workflow, preparation and GitHub mutation are two\nexplicit steps:\n\n```bash\nloki start owner/repo#42 --prepare-pr  # builds and writes exact title/body locally\nloki ship --publish                    # pushes that issue branch and opens the PR\n```\n\nThe second command consumes `.loki/state/pr-title.txt` and\n`.loki/state/pr-body.md` byte-for-byte. Plain `loki ship`, previews, and default\nstart paths remain non-publishing. A failed PR creation preserves both files and\nprints the exact remote-branch rollback command.\n\nAn optional advisory status check (`loki: verified-completion`) maps the verdict\nto a GitHub check-run. It is opt-in (`LOKI_PROVEN_PR_CHECK=1`) and can never block\na merge on its own. To make verified-completion blocking, add it as a required\nstatus check in your repository's branch-protection settings.\n\n</details>\n\n---\n\n<details>\n<summary><b>Setup details: providers, other models, what loki doctor checks</b></summary>\n\nOther spec sources work the same way:\n\n```bash\nloki init my-app --template simple-todo-app    # scaffold a starter PRD\nloki start owner/repo#123                      # a GitHub issue\nloki start ./openapi.yaml                      # an OpenAPI/YAML spec\nloki demo --offline                            # replay a sample receipt, no key, no spend\n```\n\nLoki needs a model to drive. There are two ways to give it one.\n\n**Without a separate CLI (v8).** The Claude Agent SDK ships inside Loki, so an API key alone is enough:\n\n```bash\nexport ANTHROPIC_API_KEY=sk-...               # or ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL\nLOKI_SDK_MODE=full loki start prd.md          # runs the loop and the judges through the bundled SDK\n```\n\nThis needs Bun on your PATH (the SDK loop runs on the Bun runtime). `loki doctor` reports `Bundled Claude Agent SDK is usable -- no separate CLI needed` when that path is genuinely ready, and stays on the normal blocker otherwise: it checks that the SDK's platform binary is actually extracted, that credentials are present, and that the SDK loop is really the route your next run will take. It will not tell you that you are ready and then fail the build.\n\n**With a coding-agent CLI.** The classic path, and still the default: Loki drives a separate CLI (Claude Code is the recommended one) plus a couple of common tools on your PATH.\n\n**With a different model or provider.** Loki is not tied to Anthropic, but\n*how* you reach another model depends on which API the endpoint speaks. There\nare two routes, and picking the wrong one fails confusingly.\n\n*Route 1 -- OpenAI-shaped endpoints (OpenRouter, and most hosted open models).*\nUse a provider that speaks that API natively. `aider` and `cline` both do, and\nLoki now defaults them to open-weight models rather than Claude:\n\n```bash\nloki provider set aider\nexport OPENROUTER_API_KEY=sk-or-...\nloki start prd.md                          # defaults to deepseek-v3.2\n\nexport LOKI_AIDER_MODEL=openrouter/z-ai/glm-4.6   # or pick your own\n```\n\nOpenRouter serves **only** the OpenAI-shaped `/v1/chat/completions`; it has no\nAnthropic `/v1/messages` endpoint. Pointing `ANTHROPIC_BASE_URL` at it does not\nwork, which earlier versions of this README incorrectly suggested.\n\n[OrcaRouter](https://www.orcarouter.ai) is an OpenAI-compatible gateway that\nalso serves the Anthropic Messages API, so unlike OpenRouter the same key works\nthrough Route 2 below as well as Route 1 here.\n\n*Route 2 -- Anthropic-protocol gateways.* `ANTHROPIC_BASE_URL` routes Claude\nCode itself, so the endpoint must speak the Anthropic Messages API. LiteLLM,\nBedrock proxies, and self-hosted gateways can:\n\n```bash\n# Ollama, fully local (no API key, no per-token cost)\nexport ANTHROPIC_BASE_URL=http://localhost:11434/v1\nexport LOKI_MODEL_OVERRIDE=<model you have pulled, e.g. the output of `ollama list`>\nloki start prd.md\n\n# LiteLLM / vLLM / any self-hosted gateway\nexport ANTHROPIC_BASE_URL=https://your-gateway.internal/v1\nexport ANTHROPIC_API_KEY=...\nexport LOKI_MODEL_OVERRIDE=<whatever your gateway calls the model>\nloki start prd.md\n\n# OrcaRouter (one key for both routes; model ids are namespaced by provider).\n# The bare host is deliberate here: the Anthropic SDK appends /v1/messages\n# itself, so adding /v1 would double it.\nexport ANTHROPIC_BASE_URL=https://api.orcarouter.ai\nexport ANTHROPIC_API_KEY=sk-orca-...\nexport LOKI_MODEL_OVERRIDE=<namespaced id, e.g. anthropic/claude-sonnet-5>\nloki start prd.md\n```\n\n**Set both variables.** `LOKI_MODEL_OVERRIDE` is what makes the alt-provider\npath work: without it Loki keeps asking for `opus` / `sonnet` / `haiku`, which\nonly Anthropic resolves, and most providers reject those names outright. A\nproxy that maps the aliases for you (LiteLLM can) is the one exception.\n\nModel IDs are not listed here on purpose -- OpenRouter's catalogue changes every\nweek, and a stale ID in a README is a failure you would hit at runtime. Take the\nexact string from your provider's own model list.\n\nBoth routes honor these variables identically -- the bundled-SDK path and the\nClaude Code CLI path -- and `loki doctor` reports the endpoint it detected plus a\nwarning if the model override is missing.\n\nThe quality gates, the completion council, and the Evidence Receipt do not care\nwhich model produced the code. They check what was actually built.\n\nEither way, run `loki doctor` any time and it tells you exactly what is present and what is missing, with a copy-pasteable install command for each gap.\n\n**What Loki needs (and what `loki doctor` checks)**\n\nRequired:\n\n- An agent provider CLI: [Claude Code](https://docs.claude.com/en/docs/claude-code) (`claude`, Tier 1, recommended and E2E-verified - the provider Loki Mode is built for). Cline, Codex, Aider, and opencode are supported as experimental providers (wiring in place; not yet E2E-verified by us). Loki cannot run a build without one of these installed and authenticated.\n- Python 3.10+ (`python3`) for the dashboard, memory system, and orchestration helpers.\n- Git 2.x (`git`) for checkpoints and worktrees.\n- `curl` for installation and network calls.\n\nRecommended:\n\n- Bun 1.3.0+ (`bun`) for the fast runtime (the recommended install path above installs it).\n- Node.js 18+ and npm if you install via npm instead of Bun.\n- `jq` for nicer JSON handling in shell flows.\n- Docker if you want Loki's App Runner to run containerized projects, or to run Loki itself from the published image.\n\nYou also need credentials for whichever provider you use (for Claude Code, an authenticated `claude` login or `ANTHROPIC_API_KEY`). `loki doctor` flags a missing or unauthenticated provider as the first thing to fix.\n\nIf you do not have Bun yet:\n\n```bash\ncurl -fsSL https://bun.sh/install | bash       # macOS / Linux (or: brew install oven-sh/bun/bun)\n```\n\nDocker without installing loki locally: `loki docker start prd.md` runs it in the\npublished image with zero config, bind-mounting the current folder so `.loki`\nstate and resume work exactly like local. See [DOCKER_README.md](DOCKER_README.md).\n\nUpgrading: `loki self-update` auto-detects which package manager installed loki\nand runs the right upgrade. `loki self-update --to bun` migrates an npm install\nto Bun in one command. `loki self-update --check` shows the install path.\n\nSee the [Installation Guide](docs/INSTALLATION.md) for the long form.\n\n</details>\n\n---\n\n<details>\n<summary><strong>Runtime architecture -- dual Bash/Bun runtime, rollback flag, migration cost (advanced)</strong></summary>\n\nLoki Mode runs a dual runtime by deliberate design: the battle-tested Bash engine is the stable core (the autonomous loop, quality gates, and completion council stay on it; it receives bug fixes and hardening), and new product surfaces are built TypeScript/Bun-first as modules that wrap the engine rather than reimplement it. An earlier plan to make v8 Bun-only has been superseded by this stable-engine approach: rewriting the verified trust layer would risk the exact guarantees this product exists to provide, for no capability gain. Bash support is not going away.\n\n**What ships today:**\n\n- Commands routed to the Bun runtime when `bun` is on `PATH` (the router lives in `bin/loki`): `version`, `--version`, `-v`, `status`, `stats`, `doctor`, `provider` (covers `provider show` and `provider list`), `memory` (covers `memory list` and `memory index`), `rollback`, `kpis`, and `internal`.\n- Every other command continues to execute on the existing Bash CLI (`autonomy/loki`), including the autonomous `loki start` / `loki run` loop which remains the Bash orchestrator (`autonomy/run.sh`).\n- If `bun` is not on `PATH`, the shim falls through to Bash silently. Existing users without Bun installed see no behavior change.\n\n**Rollback flag:**\n\nForce every command to take the legacy Bash path:\n\n```bash\nLOKI_LEGACY_BASH=1 loki <cmd>\n```\n\nThis is the documented escape hatch for any user who hits a regression on the Bun route. The Bash path remains the source of truth through Phase 5.\n\n**Phase 6 (planned, calendar TBD):**\n\nThe next major release sunsets the Bash runtime entirely. There is no firm calendar date. Users who need to stay on the Bash route should pin the last v7.x release.\n\n**Cost:**\n\n- Adds a Bun runtime dependency (Bun 1.3.0 or newer recommended; the shim works as long as `bun` resolves).\n- Adds a Bun toolchain to the system (Bun itself is roughly 50 MB installed via `brew install` or the official curl installer). The published `loki-ts/dist/loki.js` bundle inside the npm tarball is approximately 152 KB.\n- Speedup on the ported commands is measured in `.loki/metrics/migration_bench_soak.jsonl` and analysed in [ADR-001](docs/architecture/ADR-001-runtime-migration.md). Recorded soak results show roughly 3x to 5x faster execution on the ported commands (per-command range 2.9x to 5.0x); treat as indicative, not contractual.\n\n**More:**\n\n- [UPGRADING.md](UPGRADING.md) -- per-version upgrade and rollback guidance.\n- [ADR-001: Runtime Migration](docs/architecture/ADR-001-runtime-migration.md) -- design rationale and phase definitions.\n\n</details>\n\n---\n\n<details>\n<summary><strong>Other install methods</strong></summary>\n\n| Method | Command |\n|--------|---------|\n| **Homebrew** | `brew tap asklokesh/tap && brew install loki-mode` |\n| **Docker** | `docker pull asklokesh/loki-mode:latest` |\n| **Inside Claude Code** | `claude --dangerously-skip-permissions` then type \"Loki Mode\" |\n| **Git clone** | `git clone https://github.com/asklokesh/loki-mode.git` |\n\nSee the full [Installation Guide](docs/INSTALLATION.md).\n\n</details>\n\n<details>\n<summary><strong>Supported spec formats</strong></summary>\n\nA \"spec\" is whatever you hand `loki start`. Loki auto-detects the format and normalises it before the RARV loop. A Markdown PRD is one form of spec; the table below lists every input the CLI accepts.\n\n| Format | Example | Notes |\n|--------|---------|-------|\n| Markdown PRD | `loki start ./prd.md` | Canonical form. Headings become section anchors. |\n| JSON spec | `loki start ./spec.json` | Free-form JSON; keys surfaced to agents. |\n| YAML spec | `loki start ./openapi.yaml` | OpenAPI / AsyncAPI / plain YAML all accepted. An OpenAPI/GraphQL/Postman contract expands into a per-operation build checklist (one item per operationId/field/request) so no operation is lost to prompt truncation (v8.0.0). |\n| Plain text brief | `loki start ./brief.txt` | One-paragraph briefs work; complexity auto-detects to \"simple\". |\n| GitHub issue URL | `loki start https://github.com/owner/repo/issues/42` | Title + body + labels become the spec. |\n| GitHub shorthand | `loki start owner/repo#42` | Same as above, shorter. |\n| Jira ticket key | `loki start PROJ-456` | Requires `JIRA_BASE_URL` + `JIRA_TOKEN` env vars. |\n| GitLab / Azure DevOps URL | `loki start https://gitlab.com/group/proj/-/issues/7` | GitLab and Azure DevOps issue URLs both supported. |\n| Bare issue number | `loki start #123` or `loki start 123` | Resolved against the current repo's `origin` remote. |\n| OpenSpec change directory | `loki start --openspec ./openspec/change-001` | Reads OpenSpec change manifest + delta files. |\n| Auto-detect (no input) | `loki start` | Picks up `./prd.md`, `./spec.{json,yaml,yml}`, or `./SPEC.md` from cwd. |\n\nAll formats land in the same RARV pipeline and pass the same 8 quality gates (`skills/quality-gates.md`).\n\n</details>\n\n---\n\n## What You Can Build\n\n| Project | Build Time | Complexity |\n|---------|:----------:|:----------:|\n| Landing page with signup form | ~10 min | Simple |\n| REST API with JWT auth | ~20 min | Simple |\n| Portfolio with animations | ~15 min | Simple |\n| SaaS dashboard with analytics | ~25 min | Standard |\n| E-commerce store with Stripe | ~45 min | Standard |\n| Task manager with kanban board | ~25 min | Standard |\n| Chat app with WebSocket | ~30 min | Standard |\n| Blog platform with MDX | ~30 min | Standard |\n| Microservice architecture | ~2 hours | Complex |\n| ML pipeline with monitoring | ~3 hours | Complex |\n\n---\n\n## What To Expect\n\n| | Simple | Standard | Complex |\n|---|---|---|---|\n| **Examples** | Landing page, todo app, single API | CRUD + auth, REST API + React | Microservices, real-time, ML pipelines |\n| **Duration** | 5-30 min | 30-90 min | 2+ hours |\n| **Autonomy** | Completes independently | May need guidance on complex parts | Use as accelerator with human review |\n\n---\n\n<details>\n<summary><strong>Internal architecture -- RARV cycle, agent roles, quality gates, memory, dashboard, enterprise layer (advanced)</strong></summary>\n\n<div align=\"center\">\n<img width=\"100%\" alt=\"Loki Mode Architecture\" src=\"https://github.com/user-attachments/assets/c9798120-9587-4847-8e8d-8f421f984dfc\" />\n</div>\n\n<table>\n<tr>\n<td width=\"33%\" valign=\"top\">\n\n### RARV Cycle\nEvery iteration: **Reason** (read state) - **Act** (execute, commit) - **Reflect** (update context) - **Verify** (run tests, check spec). Failures trigger self-correction.\n\n[Core Workflow](references/core-workflow.md)\n\n</td>\n<td width=\"33%\" valign=\"top\">\n\n### 41 Agent Roles\n8 domains: engineering, operations, business, data, product, growth, review, orchestration. These are prompt-defined role specifications the orchestrator adopts per phase, auto-composed by PRD complexity; parallelism comes from the blind review council, the adversarial reviewer, and optional git-worktree streams on Claude Code, sequential on other providers.\n\n[Agent Types](references/agent-types.md)\n\n</td>\n<td width=\"33%\" valign=\"top\">\n\n### 8 Quality Gates\nStatic analysis, test suite (pass/fail), blind 3-reviewer code review with severity blocking, anti-sycophancy Devil's Advocate, mock-integrity detection, test-mutation detection, documentation coverage, and Magic Modules debate. Backward-compatibility is a conditional healing-mode auditor (not one of the 8). Code does not ship until all gates pass.\n\n[Quality Gates](skills/quality-gates.md)\n\n</td>\n</tr>\n<tr>\n<td width=\"33%\" valign=\"top\">\n\n### Memory System\n3-tier architecture: episodic (interaction traces), semantic (generalized patterns), procedural (learned skills). Vector search optional.\n\n[Memory Architecture](references/memory-system.md)\n\n</td>\n<td width=\"33%\" valign=\"top\">\n\n### Dashboard\nReal-time monitoring, agent status, task queue, WebSocket streaming, and Live App Preview (embedded iframe of the running app with Refresh/Open/Restart toolbar). Auto-starts at `localhost:57374`.\n\n[Dashboard Guide](docs/dashboard-guide.md)\n\n</td>\n<td width=\"33%\" valign=\"top\">\n\n### Enterprise Layer\nTLS, OIDC bearer-token validation (the foundation for SSO; browser SAML login is\nroadmap), scoped RBAC, OTEL tracing, policy engine, audit trails. Activated via\nenv vars. See [Enterprise Identity Roadmap](docs/ENTERPRISE-IDENTITY-ROADMAP.md).\n\n[Enterprise Guide](docs/enterprise/architecture.md)\n\n</td>\n</tr>\n</table>\n\n</details>\n\n---\n\n## Loki Mode vs. Alternatives\n\n| Feature | Loki Mode | bolt.new | Replit | Lovable |\n|---------|:---------:|:--------:|:------:|:-------:|\n| Self-hosted / your keys | Yes | No | No | No |\n| Multi-provider failover (5 providers) | Yes | No | No | No |\n| 8 quality gates | Yes | No | No | No |\n| Blind code review | Yes | No | No | No |\n| Enterprise auth (OIDC token + scoped RBAC) | Yes | No | Yes | No |\n| Air-gapped deployment | Yes | No | No | No |\n| Docker + CI/CD generation | Yes | No | Yes | No |\n| Source-available (BUSL-1.1) | Yes | No | No | No |\n| Free tier | Source-available | Yes | Yes | Yes |\n\nAmong the four tools in this table, Loki Mode is the one that is fully self-hosted, source-available (BUSL-1.1), and includes automated quality verification. Your code, your keys, your infrastructure. We have not surveyed every tool on the market, so read this as a comparison against the named three, not a claim about the whole category.\n\n---\n\n<details>\n<summary><strong>Provider matrix -- per-provider status, autonomous flags, parallelism, install (includes deprecated Gemini)</strong></summary>\n\nLoki's autonomy and quality loop are the product; the underlying coding CLI is swappable. Loki runs on any of the providers below so you are never locked to one vendor. With `LOKI_PROVIDER` unset, Loki auto-detects the first installed provider in the order the table lists (claude, cline, codex, aider, opencode); setting it explicitly always wins and is never silently substituted.\n\n| Provider | Status | Autonomous Flag | Parallel Agents | Install |\n|----------|--------|:-:|:-:|---------|\n| **Claude Code** | Active (Tier 1, E2E-verified) | `--dangerously-skip-permissions` | Yes (10+) | `npm i -g @anthropic-ai/claude-code` |\n| **Cline CLI** | Experimental (Tier 2) | `-y` | Sequential | `npm install -g cline` |\n| **Codex CLI** | Experimental (Tier 3) | `exec --sandbox workspace-write --skip-git-repo-check` | Sequential | `npm i -g @openai/codex` |\n| **Aider** | Experimental (Tier 3) | `--yes-always` | Sequential | `pip install aider-chat` |\n| **opencode** | Experimental | `--auto` | Sequential | `npm install -g opencode-ai` |\n| **Google Gemini CLI** | REMOVED v7.5.18 | -- | -- | Upstream deprecated; runtime removed. `LOKI_PROVIDER=gemini` exits with a migration message. |\n\nStatus legend: \"E2E-verified\" means we run real spec-to-code builds on it ourselves. Claude Code is the primary, fully supported provider and the one Loki Mode is built for; it gets full features (subagents, parallelization, MCP, Task tool). \"Experimental\" means the wiring is in place but we have not produced an end-to-end verified build ourselves; treat as community-tested. Experimental providers run sequentially. Auto-failover switches providers when rate-limited. See [Provider Guide](skills/providers.md).\n\n</details>\n\n---\n\n## CLI Reference\n\n<details>\n<summary><strong>All commands</strong></summary>\n\n| Command | Description |\n|---------|-------------|\n| `loki start [PRD]` | Start with optional PRD file (also accepts an issue ref; replaces deprecated `loki run`). Auto-opens the dashboard in the browser for interactive runs and passes native `--effort`/`--max-budget-usd`/`--fallback-model` for resilience (v7.25.0) |\n| `loki stop` | Stop execution |\n| `loki modernize heal <path>` | Legacy system healing (archaeology, stabilize, isolate, modernize, validate -- v6.67.0; was: `loki heal`) |\n| `loki pause` / `resume` | Pause/resume after current session |\n| `loki steer \"<note>\"` | Nudge a running build with a directive (writes `.loki/HUMAN_INPUT.md`; the loop reads it when `LOKI_PROMPT_INJECTION=1`) (v8.0.0) |\n| `loki status` | Show current status |\n| `loki why` | Explain the last outcome; on a stalled run names the real stall reason (proactive stuck-detector + convergence signal) and suggests `loki steer` (v8.0.0) |\n| `loki cockpit` | Live multi-repo status as an inline terminal image (Kitty/iTerm2/WezTerm/Ghostty); text + dashboard fallback elsewhere (v7.126.0) |\n| `loki dashboard` | Open web dashboard |\n| `loki preview` | Print running app URL and open in browser (Live App Preview, v7.24.0; was: `loki open`) |\n| `loki web` | Launch Purple Lab web UI [DEPRECATED in v7.44.0 -- use `loki start` which auto-opens the dashboard at http://localhost:57374; for the hosted platform see Autonomi Cloud] |\n| `loki doctor` | Check environment and dependencies |\n| `loki plan [PRD]` | Pre-execution analysis: complexity, cost, iterations |\n| `loki review [--staged\\|--diff]` | AI-powered code review with severity filtering |\n| `loki test [--file\\|--dir\\|--changed]` | AI test generation (8 languages, 9 frameworks) |\n| `loki analyze onboard [path]` | Project analysis and CLAUDE.md generation (was: `loki onboard`) |\n| `loki import` | Import GitHub issues as tasks |\n| `loki ci` | CI/CD quality gate integration |\n| `loki failover` | Cross-provider auto-failover management |\n| `loki memory <cmd>` | Memory system: index, timeline, search, consolidate |\n| `loki enterprise` | Enterprise feature management |\n| `loki version` | Show version |\n\n</details>\n\nRun `loki --help` for all options. Full reference: [CLI Reference](wiki/CLI-Reference.md) | Config: [config.example.yaml](autonomy/config.example.yaml)\n\n### Configuration file\n\nPass 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). Values resolve by precedence: 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}` and the loader expands it at load time (an unset reference is skipped with a warning, and a raw-looking secret literal is flagged). Generate a starter with `loki config example`.\n\n```bash\n# config.yaml\ndashboard:\n  port: 9000\ngithub:\n  token: ${GITHUB_TOKEN}   # expanded from the environment, never stored inline\n\nloki start --config config.yaml ./prd.md\n```\n\n---\n\n<details>\n<summary><strong>Configuration env vars (intelligent defaults, opt-out knobs)</strong></summary>\n\nLoki Mode's accuracy and autonomy behaviors are default-on. Each is an opt-out escape hatch, not a setting you have to discover. The most relevant knobs from the v7.41.x accuracy/autonomy hardening:\n\n| Env var | Default | Effect |\n|---------|---------|--------|\n| `LOKI_REVIEW_INCONCLUSIVE_BLOCK` | `1` | Blocks completion when a code-review round returns zero usable verdicts (an all-empty review proves nothing). Set `0` to record the inconclusive result without blocking. |\n| `LOKI_COMPLETION_TEST_CAPTURE` | `1` | Captures fresh test results before the verified-completion evidence gate evaluates. Set `0` to skip the pre-gate capture. |\n| `LOKI_AUTO_DOCS` | `true` | Generates the `.loki/docs/` suite before the documentation gate scores it (bounded: once per run when docs are missing, and again only when >10 commits stale). Set `false` to opt out. |\n| `LOKI_CAVEMAN` | `1` (on) | Output-token compressor for free-form generation only (never trust-gate subcalls). Set `0` to opt out. |\n| `LOKI_CAVEMAN_LEVEL` | inferred | Compression level for the compressor. Auto-inferred per invocation from the run's RARV tier; set explicitly (`lite` / `full` / `ultra`) to override the inference. |\n| `LOKI_CONFIDENCE_SPIKE` | `1` (on) | Forces one EXTRA verification pass when the agent's self-reported confidence spikes, instead of trusting the claim. Strictly additive -- it can never skip a gate. Set `0` to opt out; tune with `LOKI_CONFIDENCE_SPIKE_DELTA` (default `40`) and `LOKI_CONFIDENCE_SPIKE_MIN` (default `90`). |\n| `LOKI_GOAL_SCORING` | `1` (on) | Flags a goal with no measurable success condition and asks for a threshold, metric, or concrete artifact. Advisory only -- never blocks a build or rewrites the goal. Set `0` to opt out. |\n| `LOKI_SMART_RETRY` | `1` (on) | Stops early on a positively-identified permanent failure (bad credentials, unknown model, exhausted quota) rather than burning retries. Unrecognized errors and rate limits still retry as before. Set `0` to retry every failure. |\n| `LOKI_SIMPLE` | `0` (off) | EXPERIMENTAL. Strips the coaching half of the system prompt -- the RARV cycle, SDLC phases and memory habits that a frontier model already does natively. Per-iteration state (which gate failed, self-heal output, checklist status) is never touched, because that is information the model cannot derive. Measured at -78% prompt size, ~1562 tokens per iteration, on both the bash and Bun routes. INERT on degraded providers (Codex, Aider): those take an earlier return path whose prompt is already minimal by design, so the flag has nothing to strip there -- a measured zero, not an untested case. Whether it changes build speed or quality is NOT yet measured, so treat it as an experiment, not a tuning knob: run `benchmarks/run-prompt-ablation.sh` on your own workload before adopting it. |\n\nThis is a subset. See the [wiki](wiki/Home.md) for the full env-var reference and the RARV-C closure knobs (`LOKI_INJECT_FINDINGS`, `LOKI_OVERRIDE_COUNCIL`, `LOKI_AUTO_LEARNINGS`, `LOKI_HANDOFF_MD`).\n\n</details>\n\n<details>\n<summary><strong>BMAD Method Integration</strong></summary>\n\nLoki Mode integrates with the [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD), a structured AI-driven agile methodology. If your project uses BMAD for requirements elicitation, Loki Mode can consume those artifacts directly:\n\n```bash\nloki start --bmad-project ./my-project\n```\n\nThe adapter handles BMAD's frontmatter conventions, FR-format functional requirements, Given/When/Then acceptance criteria, and artifact chain validation. Non-BMAD projects are unaffected -- the integration is opt-in via `--bmad-project`.\n\nSee [BMAD Integration Validation](docs/architecture/bmad-integration-validation.md).\n\n</details>\n\n<details>\n<summary><strong>Enterprise Features</strong></summary>\n\nEnterprise features are included but require env var activation.\n\n```bash\nexport LOKI_ENTERPRISE_AUTH=true                 # token auth (dashboard/auth.py)\nexport LOKI_OIDC_ISSUER=https://accounts.google.com\nexport LOKI_OIDC_CLIENT_ID=your-client-id        # OIDC needs issuer + client id\nexport LOKI_ENTERPRISE_AUDIT=true                # force audit logging on\nexport LOKI_TLS_CERT=/path/cert.pem              # HTTPS: set BOTH cert and key\nexport LOKI_TLS_KEY=/path/key.pem\nloki enterprise status\n```\n\n[Enterprise Architecture](docs/enterprise/architecture.md) | [Security](docs/enterprise/security.md) | [Authentication](docs/authentication.md) | [Authorization](docs/authorization.md) | [Metrics](docs/metrics.md) | [Audit Logging](docs/audit-logging.md)\n\n</details>\n\n<details>\n<summary><strong>Benchmarks</strong></summary>\n\nSelf-reported results from the included test harness. Verification scripts included for reproduction.\n\n| Benchmark | Result | Notes |\n|-----------|--------|-------|\n| HumanEval | 162/164 (98.78%) | Self-reported; harness + results JSON in `benchmarks/results/humaneval-loki-results.json`. Max 3 retries, RARV self-verification. |\n| SWE-bench | Not yet measured | Harness exists and generates patches, but the official SWE-bench evaluator has not been run, so there is no pass-rate to report. Run it yourself: `./benchmarks/run-benchmarks.sh swebench --execute` |\n\nSee [benchmarks/](benchmarks/) for methodology.\n\n</details>\n\n<details>\n<summary><strong>Presentation</strong></summary>\n\n![Loki Mode Presentation](docs/loki-mode-presentation.gif)\n\n*11 slides: Problem, Solution, 41 Agents, RARV Cycle, 8 Quality Gates (HumanEval 98.78%), Multi-Provider, Enterprise Hardening (Live App Preview), Full Lifecycle*\n\n**[Download PPTX](docs/loki-mode-presentation.pptx)**\n\n</details>\n\n---\n\n## Limitations\n\n| Area | What Works | What Doesn't (Yet) |\n|------|-----------|---------------------|\n| **Code Gen** | Full-stack apps from PRDs | Complex domain logic may need human review |\n| **Deploy** | Generates configs, Dockerfiles, CI/CD; `loki deploy` prints the exact deploy command | Does not deploy -- human runs the printed deploy command (Loki never runs a cloud CLI or git push) |\n| **Testing** | 8 automated quality gates | Test quality depends on AI assertions |\n| **Providers** | 5 providers with auto-failover | Non-Claude providers lack parallel agents |\n| **Dashboard** | Real-time single-machine monitoring | No multi-node clustering |\n\n> **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.\n\n---\n\n## Research Foundation\n\n<details>\n<summary><strong>Papers and sources</strong></summary>\n\n| Source | What We Use |\n|--------|-------------|\n| [Anthropic: Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) | Evaluator-optimizer, parallelization |\n| [Anthropic: Constitutional AI](https://www.anthropic.com/research/constitutional-ai-harmlessness-from-ai-feedback) | Self-critique against quality principles |\n| [DeepMind: Scalable Oversight via Debate](https://deepmind.google/research/publications/34920/) | Debate-based verification in council review |\n| [DeepMind: SIMA 2](https://deepmind.google/blog/sima-2-an-agent-that-plays-reasons-and-learns-with-you-in-virtual-3d-worlds/) | Self-improvement loop design |\n| [OpenAI: Agents SDK](https://openai.github.io/openai-agents-python/) | Guardrails, tripwires, tracing |\n| [NVIDIA ToolOrchestra](https://github.com/NVlabs/ToolOrchestra) | Efficiency metrics, reward signals |\n| [CONSENSAGENT (ACL 2025)](https://aclanthology.org/2025.findings-acl.1141/) | Anti-sycophancy in blind review |\n| [GoalAct](https://arxiv.org/abs/2504.16563) | Hierarchical planning for complex PRDs |\n\n**Practitioner insights:** Boris Cherny, Simon Willison, [HN Community](https://news.ycombinator.com/item?id=44623207)\n\n**[Full Acknowledgements](docs/ACKNOWLEDGEMENTS.md)** -- 50+ papers and resources\n\n</details>\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/asklokesh/loki-mode.git && cd loki-mode\nnpm install && npm test              # CLI + Node test suites\npython3 -m pytest                    # Python test suite\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\n[Business Source License 1.1](LICENSE) -- Free for personal, internal, academic, and non-commercial use. Converts to Apache 2.0 on March 19, 2030. Contact founder@autonomi.dev for commercial licensing.\n\n---\n\n<div align=\"center\">\n\n**[Autonomi](https://www.autonomi.dev/)** | **[Documentation](wiki/Home.md)** | **[Changelog](CHANGELOG.md)** | **[Comparisons](references/competitive-analysis.md)**\n\n</div>\n",
  "bytes": 56813,
  "sha": "d8763a0119587e03641d627bb921e8d9aaf79fc1a45ed0239a60d555a4fb52ca",
  "repo_slug": "asklokesh/loki-mode",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_asklokesh_loki_mode_f5a162a1/readme"
}