Loki Mode

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

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, and blocks completion when tests run red, so "complete" means proven, not promised.
• Production quality built in -- 11 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. 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 + Claude Fable tier -- switch the model a live run uses from the dashboard (applies at the next iteration, current run only), with Claude Fable available as a premium tier at its published $10/$50 per MTok (2x Opus). For every model lever (session pin to Fable, 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).
• 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).
• 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 -- 34 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 34, 33 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, Codex, Cline, or Aider with automatic failover (loki-ts/src/runner/providers.ts); no vendor lock-in. Gemini CLI deprecated v7.5.18; Antigravity CLI coming soon.
• Open source -- Free for personal, internal, and academic use.

Get Started in 30 Seconds

bun install -g loki-mode                       # install (npm/brew/Docker also work, see below)
loki init my-app --template simple-todo-app    # scaffold a starter PRD
cd my-app && loki start prd.md                 # autonomous build from the spec

That is the happy path. One thing to know first: Loki drives a separate coding-agent CLI (Claude Code is the recommended one) and needs it plus a couple of common tools on your PATH. 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.

loki doctor                                    # check your setup before the first build

Required:

• An agent provider CLI: Claude Code (claude, Tier 1, recommended and E2E-verified - the provider Loki Mode is built for). Codex, Cline, and Aider 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.
• Python 3.10+ (python3) for the dashboard, memory system, and orchestration helpers.
• Git 2.x (git) for checkpoints and worktrees.
• curl for installation and network calls.

Recommended:

• Bun 1.3.0+ (bun) for the fast runtime (the recommended install path above installs it).
• Node.js 18+ and npm if you install via npm instead of Bun.
• jq for nicer JSON handling in shell flows.
• Docker if you want Loki's App Runner to run containerized projects, or to run Loki itself from the published image.

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

If you do not have Bun yet:

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

Other spec sources work the same way:

loki start owner/repo#123                       # a GitHub issue
loki start ./openapi.yaml                        # an OpenAPI/YAML spec

Or skip scaffolding and go straight to a quick task:

loki quick "build a landing page with a signup form"

Other install methods (all work, all keep working):

Upgrading:

loki self-update                  # upgrade in place via current manager
loki self-update --to bun         # switch from npm/brew to Bun
loki self-update --check          # show current install path + manager

loki self-update auto-detects which package manager installed loki and runs the right upgrade. If you installed via npm and want to switch to Bun (recommended for v8.0.0 forward-compat), loki self-update --to bun does the migration in one command (installs via Bun first, then uninstalls the npm copy).

See the Installation Guide for the long form.

Runtime Architecture

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

What ships today:

• 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.
• 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).
• If bun is not on PATH, the shim falls through to Bash silently. Existing users without Bun installed see no behavior change.

Rollback flag:

Force every command to take the legacy Bash path:

LOKI_LEGACY_BASH=1 loki <cmd>

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

Phase 6 (planned, calendar TBD):

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

Cost:

• Adds a Bun runtime dependency (Bun 1.3.0 or newer recommended; the shim works as long as bun resolves).
• 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.
• Speedup on the ported commands is measured in .loki/metrics/migration_bench_soak.jsonl and analysed in ADR-001. 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.

More:

• UPGRADING.md -- per-version upgrade and rollback guidance.
• ADR-001: Runtime Migration -- design rationale and phase definitions.

See the full Installation Guide.

A "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.

All formats land in the same RARV pipeline and pass the same 11 quality gates (skills/quality-gates.md).

What You Can Build

What To Expect

Architecture

Purple Lab

The hosted development platform. A Replit-like web UI for visual PRD-to-code workflow, with the Loki agent for iterative development. The same software is free and source-available as the local Loki Mode dashboard; offered managed to teams and enterprises under the Autonomi brand (Autonomi Cloud).

loki web                           # launches at http://localhost:57375

Loki Mode vs. Alternatives

Loki Mode is the only platform that is fully self-hosted, open source, and includes automated quality verification. Your code, your keys, your infrastructure.

Provider-Agnostic Runtime

Loki'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.

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

CLI Reference

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

Loki Mode integrates with the BMAD Method, a structured AI-driven agile methodology. If your project uses BMAD for requirements elicitation, Loki Mode can consume those artifacts directly:

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

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

See BMAD Integration Validation.

Enterprise features are included but require env var activation. Self-audit: 35/45 capabilities working, 0 broken, 1,314 tests passing.

export LOKI_TLS_ENABLED=true
export LOKI_OIDC_PROVIDER=google
export LOKI_AUDIT_ENABLED=true
loki enterprise status

Enterprise Architecture | Security | Authentication | Authorization | Metrics | Audit Logging

Self-reported results from the included test harness. Verification scripts included for reproduction.

See benchmarks/ for methodology.

11 slides: Problem, Solution, 41 Agents, RARV Cycle, 9 Quality Gates (HumanEval 98.78%), Multi-Provider, Enterprise Hardening (Live App Preview), Full Lifecycle

Download PPTX

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

Practitioner insights: Boris Cherny, Simon Willison, HN Community

Full Acknowledgements -- 50+ papers and resources

Contributing

git clone https://github.com/asklokesh/loki-mode.git && cd loki-mode
npm install && npm test              # 683 tests
python3 -m pytest                    # 631 tests

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 [email protected] for commercial licensing.