asklokesh/loki-mode

Loki Mode – an autonomous, spec‑driven coding assistant

What it is – Loki Mode is a CLI/SDK tool that lets you give a product specification (a one‑line idea, a PRD file, an OpenAPI spec, etc.) and walks you through a fully automated build of the requested software. It is built around a verified‑completion workflow: the agent runs until it can prove, with deterministic checks, that the generated code meets the spec, passes tests, builds, and (optionally) runs health‑checks. The proof is stored as a signed “Evidence Receipt” that can be audited later.

How it works –

• You provide a spec; Loki classifies its complexity and selects a starter template.
• An orchestrator assembles a team of 41 specialized agent roles (across 8 domains) that execute RARV cycles – Reason → Act → Reflect → Verify – with eight built‑in quality‑gate checks (tests, build, static analysis, secret scan, runtime health, etc.).
• The agent runs on Anthropic’s Claude models (or any compatible LLM) and can switch models mid‑run.
• When all gates pass, Loki writes the generated repository and a machine‑checkable receipt (.loki/proofs/<run_id>/) containing the diff hash, test/build results, and a GPG‑signed attestation.

Key commands

Command	Purpose
loki quickstart "<idea>" --yes	One‑shot build from a short idea; selects a template, shows cost/time estimate, then builds without further prompts.
loki start <spec.md>	Build from a full spec file you wrote.
loki modernize heal <repo> --assess	Read‑only analysis of an existing codebase – maturity rating, debt signals, and a ranked list of low‑risk improvement targets.
loki proof verify <id>	Re‑hashes the receipt and confirms the diff matches; exits 0 on a clean verification.
loki doctor	Checks that required environment variables (e.g., ANTHROPIC_API_KEY) and dependencies are present.
loki quickstart --dry-run --json > preview.json	Produce a deterministic preview of the plan (template choice, cost estimate, spec hash) without writing files or invoking the model.
loki verify	Run Loki’s quality‑gate checks on any branch/PR diff; CI‑friendly exit codes (0 = verified, 1 = concerns, 2 = blocked).

Installation – The project distributes a Node‑based CLI via several channels. The recommended method is bun install -g loki-mode (fast startup). npm, Homebrew, and Docker images are also provided. A Claude Code plugin (/loki-grill, /loki-spec-status, /loki-verify) can be added to Claude’s IDE integration.

Why “verified completion” matters – Many local coding agents claim they are “done” while actually making no changes or leaving tests failing. Loki refuses to mark a run as finished unless:

1. The git diff is non‑empty.
2. All required tests pass (real N passed output).
3. Build succeeds.
4. Optional gates (runtime health, secret leak detection) pass. If any gate is inconclusive, the receipt records a gap (e.g., VERIFIED WITH GAPS). The receipt is a plain file bound to the exact diff hash, making it possible for anyone to re‑run the verification without trusting the agent’s self‑report.

Evidence receipts – Each run creates a directory under .loki/proofs/ containing:

• diff_sha256 of the generated change.
• Test, build, and gate outcomes.
• AI‑generated “council verdict” (marked as an assessment, not a proof).
• Optionally a detached GPG signature (LOKI_PROOF_GPG_KEY). The headline (VERIFIED, VERIFIED WITH GAPS, or NOT VERIFIED) is derived solely from the deterministic facts.

Use cases

• Rapid prototyping – Turn a brief idea into a runnable full‑stack app (including Docker‑compose) with a single command.
• Legacy modernization – Run a read‑only assessment on an existing repo, get a prioritized list of low‑risk changes, then let Loki apply them under strict verification.
• CI integration – Use loki verify in pipelines to enforce that any PR meets the same quality gates the autonomous agent uses.
• Auditable AI‑generated code – Attach the receipt to a pull request; reviewers can independently verify the diff and test results.

Limitations / caveats

• Requires an Anthropic API key (or another compatible LLM) to run; without a model the tool can only show previews.
• The “verified” claim is only as strong as the deterministic checks; a malicious actor could rewrite both the facts and the receipt to stay consistent, which is why signed receipts are recommended for high‑trust scenarios.
• Currently the CLI only supports Claude‑based providers out‑of‑the‑box; other models need custom integration.
• The tool is open‑source but commercial editions (Autonomi Cloud/Enterprise) add team‑level features; the free version may lack some enterprise‑grade orchestration or UI components.

Bottom line – Loki Mode is a genuine, open‑source autonomous coding agent that emphasizes trust through verification. It automates the whole spec‑to‑code pipeline, provides deterministic evidence of what it did, and offers a set of commands that can be safely used in scripts or CI environments.