Install

bun install -g loki-mode          # recommended (npm, Homebrew, Docker below)

Use it

loki quickstart                   # guided first build: asks a few questions, quotes cost, builds

That is the whole happy path. It asks for a one-line idea, picks a template, shows the real cost and time estimate before spending anything, then builds. Press Enter through every step and you get a sample Todo app.

Or go straight at it:

loki quick "build a landing page with a signup form"     # one-shot task
loki start prd.md                                        # build from a spec you wrote
loki modernize heal ./your-repo --assess                 # existing codebase, read-only

Loki needs a model to drive. An ANTHROPIC_API_KEY alone is enough (the Claude Agent SDK ships inside Loki); or point it at Claude Code, aider, cline, or an open model. Run loki doctor and it tells you exactly what is missing.

export ANTHROPIC_API_KEY=sk-...
loki doctor                       # checks your setup, names any blocker

Try it first, without installing

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 -- you are not asked to trust the agent's self-report.

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()), assembles an agent team from 41 specialized agent roles across 8 domains - prompt-defined specifications the orchestrator adopts per phase, 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.

Already have a codebase? Start read-only.

Most agents are built to create new apps. The harder, more valuable problem is the ten-year-old repo that pays the bills. Loki works on both, and on an existing codebase it starts by changing nothing:

loki modernize heal ./your-repo --assess          # read-only. no writes, no commits.
loki modernize heal ./your-repo --assess --json   # same, machine-readable

You get a modernization readiness report: language mix, a 4-level maturity rating, technical-debt signals (test coverage, TODO density, oversized files, dependency staleness), and a ranked list of where to start -- ordered by blast radius, so the first change is the one least likely to break something.

Then, if you want it to act:

loki modernize heal ./your-repo --strict          # block ALL behavioral change without approval
loki modernize heal ./your-repo --phase archaeology   # extract knowledge only
loki modernize heal ./your-repo --compliance healthcare   # or fintech | government

The healing pipeline runs in phases -- archaeology, stabilize, isolate, modernize, validate -- and the validate phase checks behavioral equivalence against the pre-change baseline, not just that the tests are green. Friction points (the weird code that exists for a reason nobody remembers) are cataloged before anything touches them, because in a legacy system the strange code is usually load-bearing.

The Evidence Receipt: don't trust the agent, check it

Every coding agent tells you it finished. Loki hands you something you can check yourself.

We are not the only tool that checks its own work, and you should be suspicious of anyone who claims to be. Lovable runs a security scan on every publish and can block the publish outright. Claude Code's review has a step that checks findings against actual code behavior. Replit says its agent tests its own work.

The difference is what you are left holding. Their output lives in their dashboard: a findings count in a dialog, a check run that by design never blocks a merge. Ours is a file. It is bound to a specific diff by diff_sha256, it records what was NOT proven as prominently as what was, and someone who has never installed Loki can re-verify it from the repository alone. Commit it, attach it to the PR, hand it to an auditor.

Portable, diff-bound, and honest about its gaps -- that is the claim, and it is the one worth checking.

Each run writes a receipt to .loki/proofs/<run_id>/ that separates deterministic FACTS (the git diff with base and head SHAs plus a diff_sha256, the test command and its exit code, the build command and its exit code, each gate verdict) from AI ASSESSMENTS (the council verdict, labeled as judgment, never as proof). The headline is computed from the facts alone:

loki proof list            # every receipt from this project
loki proof show <id>       # the facts, the assessments, and the headline
loki proof verify <id>     # re-hash the receipt and re-derive the diff

loki proof verify exits 0 clean, 1 on tamper or drift. Receipts are attached to pull requests automatically (LOKI_PROVEN_PR=0 to opt out), so a reviewer sees the evidence next to the code.

What the receipt does NOT claim. On the unsigned path the generator is trusted: someone who rewrites both the facts and the headline into a mutually consistent lie and recomputes the hash will still pass verification. That is defense-in-depth, not non-forgeability, and neutral non-forgeability needs the signed record. We tested for exactly this and locked the limitation into the suite (tests/test-proof-forgery-defense.sh), and in v7.111.0 we removed our own earlier "non-forgeable" claim once we found it was false on that path. An honest boundary you can verify beats a marketing claim you cannot.

To close that gap, sign your receipts: export LOKI_PROOF_GPG_KEY=<key-id> and every receipt carries a detached GPG signature that any third party with your public key can verify offline. See docs/SIGNED-RECEIPTS.md.

Why Loki Mode?

• 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.
• 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).
• Production quality built in -- 8 quality gates (skills/quality-gates.md), blind 3-reviewer code review (run.sh:run_code_review()), anti-sycophancy checks
• 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).
• 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).
• 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).
• 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).
• 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).
• 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).
• 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).
• 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 " 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).
• 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).
• 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).
• 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).
• 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)
• Self-hosted and private -- Your keys, your infrastructure, no data leaves your network
• Legacy system healing -- loki modernize heal archaeology/stabilize/isolate/modernize/validate phases (v6.67.0, see skills/healing.md)
• 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).
• Full-stack output -- Source code, tests, Docker Compose stacks (multi-service with healthchecks), CI/CD pipelines, audit logs
• 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.
• Source-available (BUSL-1.1) -- Free for personal, internal, and academic use.

Loki does not lie about "done"

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 proof list              # every receipt: run id, time, council verdict, cost, files
loki proof show <id>         # the full proof.json (facts, assessments, honesty)
loki proof verify <id>       # re-check the receipt against the repo (exit 0 clean, 1 tamper/drift)

{
  "hash_ok": true,
  "diff_drift": false,
  "gpg_ok": "n/a",
  "degraded": [],
  "reason": "",
  "ok": true
}

loki init my-app --template simple-todo-app    # scaffold a starter PRD
loki start owner/repo#123                      # a GitHub issue
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

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

LOKI_LEGACY_BASH=1 loki <cmd>

What You Can Build

What To Expect

Internal architecture -- RARV cycle, agent roles, quality gates, memory, dashboard, enterprise layer (advanced)

RARV Cycle Every iteration: Reason (read state) - Act (execute, commit) - Reflect (update context) - Verify (run tests, check spec). Failures trigger self-correction. Core Workflow	41 Agent Roles 8 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. Agent Types	8 Quality Gates Static 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. Quality Gates
Memory System 3-tier architecture: episodic (interaction traces), semantic (generalized patterns), procedural (learned skills). Vector search optional. Memory Architecture	Dashboard Real-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. Dashboard Guide	Enterprise Layer TLS, OIDC bearer-token validation (the foundation for SSO; browser SAML login is roadmap), scoped RBAC, OTEL tracing, policy engine, audit trails. Activated via env vars. See Enterprise Identity Roadmap. Enterprise Guide

Loki Mode vs. Alternatives

Among 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.

CLI Reference

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

Configuration file

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). 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.

# config.yaml
dashboard:
  port: 9000
github:
  token: ${GITHUB_TOKEN}   # expanded from the environment, never stored inline

loki start --config config.yaml ./prd.md

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

Limitations

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.

Research Foundation

Contributing

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.

License

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 commercial licensing.