Loki Mode
Turns software specs into tested code with independently checkable completion evidence.
- Source repo
- asklokesh/loki-mode
- Stars
- ★ 1.1k
- Last updated
- today
- License
- NOASSERTION
- Primary language
- Shell
- FA score
- 57/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesClaude Code · Claude APICodex · OpenAI API (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A product team that wants to hand a PRD or one-line feature brief to a CLI and receive code, tests, and a reviewable evidence artifact.
- Not a fit if
- Teams standardizing on a non-Claude provider for production builds: only Claude Code is Tier 1 end-to-end verified; others are experimental.
- Commercial users needing a permissive open-source license: the code is BUSL-1.1, converting to Apache 2.0 only in 2030.
- Source review
- 57/100 · Major gaps
What does this agent do, and when should you use it?
Loki Mode is a spec-driven CLI for building and verifying software projects. It accepts PRDs, GitHub issues, OpenAPI/JSON/YAML files, and plain-language briefs, then runs a Bash-orchestrated RARV loop: Reason, Act, Reflect, and Verify. A run produces a Git repository with source, tests, configuration, Docker Compose assets, CI/CD configuration, audit logs, and an Evidence Receipt under .loki/proofs/<run_id>/. The repository also includes a Python dashboard, cross-project memory, and an MCP server started through loki mcp. It can generate deployment assets, but its documented loki deploy boundary is to print a deployment command rather than execute a cloud CLI or git push.
With loki start <spec>, Loki normalizes Markdown, JSON, YAML/OpenAPI, GitHub issues, Jira tickets, and GitLab or Azure DevOps issues, then invokes autonomy/run.sh through run_autonomous() for RARV cycles. It composes prompt-defined roles according to detected complexity and runs eight quality gates: static analysis, tests, blind review, anti-sycophancy checks, mock-integrity detection, test-mutation detection, documentation coverage, and Magic Modules debate. At completion it writes base/head SHAs, diff_sha256, test and build commands with exit codes, and gate verdicts into an Evidence Receipt, inspectable with loki proof list, loki proof show <id>, and loki proof verify <id>. loki verify can separately run build, test, static-analysis, secret-scan, and dependency-audit gates on a branch or PR diff and writes evidence to .loki/verify/evidence.json. For established repositories, loki modernize heal <path> --assess creates a read-only readiness report covering language mix, maturity, debt signals, and a blast-radius-ranked starting list.
- A product team that wants to hand a PRD or one-line feature brief to a CLI and receive code, tests, and a reviewable evidence artifact.
- An engineering team assessing a long-lived repository with
loki modernize heal ./repo --assessbefore permitting any writes. - An API team that needs an OpenAPI, GraphQL, or Postman contract expanded into per-operation build checklist items.
- A reviewer who wants a pull request accompanied by test results, diff hashes, and gate outcomes instead of an agent's completion narrative.
- A developer centered on Claude Code who still needs documented provider paths for Cline, Codex, Aider, or opencode.
How do you install or deploy this agent?
For an offline sample, run npx loki-mode tour. The recommended global installation is bun install -g loki-mode, followed by loki doctor. Normal builds require Python 3.10+, Git 2.x, curl, and an installed, authenticated provider CLI; the README designates Claude Code as Tier 1. Alternatively, use the bundled Claude Agent SDK by setting ANTHROPIC_API_KEY=sk-... and running LOKI_SDK_MODE=full loki start prd.md; that route requires Bun on PATH.
How do you use this agent?
For a guided first build, run loki quickstart and complete setup checking, idea entry, template selection, and plan review. For a scripted path, run loki init my-app --template simple-todo-app, then cd my-app && loki start prd.md. After a run, use loki proof list to find its receipt and loki proof verify <id> to recompute receipt and diff checks; use loki verify against an existing branch. Open local monitoring or the running app with loki dashboard or loki preview.
What are this agent's strengths and limitations?
- Evidence Receipts persist diff hashes, actual test commands and exit codes, build outcomes, and gate verdicts in a file that can be rechecked; deterministic facts are separated from AI assessments.
loki verifyindependently evaluates a branch or PR diff and supplies CI-oriented exit codes: 0 for VERIFIED, 1 for CONCERNS, and 2 for BLOCKED.- The CLI accepts a broad set of documented spec sources, including PRDs, OpenAPI/JSON/YAML, GitHub issues, Jira tickets, and GitLab/Azure DevOps issues.
- It covers both greenfield building and legacy work through a healing pipeline with archaeology, stabilize, isolate, modernize, and validate phases.
- The repository documents provider paths for Claude Code, Cline, Codex, Aider, and opencode, plus a local MCP server, Docker Compose output, and a local dashboard.
- Claude Code is the only Tier 1, end-to-end-verified provider; Cline, Codex, Aider, and opencode are documented as experimental and run sequentially.
- A real build requires an authenticated model provider CLI or Anthropic credentials; the tour and offline demo replay past receipts and do not evaluate your project.
- For unsigned receipts, the README acknowledges that an actor who rewrites both facts and headline and recomputes the hash can still pass verification; GPG signing must be configured separately.
- The product maintains both Bash and Bun runtimes, with some commands routed through Bun; its documentation also describes a future major-version Bash sunset, creating a migration consideration.
- License evidence conflicts: the supplied repository metadata is
NOASSERTION, while the README declares BUSL-1.1 and an Apache 2.0 conversion in 2030.
How does this agent compare with similar options?
The README compares Loki Mode with bolt.new, Replit, and Lovable, positioning it around self-hosting, user-managed keys, provider failover, eight quality gates, and blind review. The comparison is explicitly limited to those named products, not the broader market.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Loki Mode This agent | 57 · Major gaps | CLIFree + model costs | ★ 1.1k | today | Shell | Claude Code · Claude API |
| MoAI Development Harness | 66 · Some gaps | CLIFree + model costs | ★ 1.3k | 4d ago | Go | Claude Code |
| Flow-Next Engineering Pipeline | 62 · Some gaps | Agent plugin / skillFree + model costs | ★ 716 | 1d ago | Python | Codex · Claude Code |
| Pilot Shell | 53 · Major gaps | CLIPaid | ★ 2.1k | today | Shell | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README emphasizes read-only assessment mode (--assess), user confirmation (--strict blocks all behavioral change), evidence receipts separating facts from AI assessments, optional GPG signing, secret-leak gate. Deductions: no specific implementation details for least privilege (e.g., filesystem access scope), sensitive data handling (e.g., API key storage) not detailed, dependency security (e.g., vulnerability scanning) only mentioned, rollback mechanism not explicit, publisher identity unverified.
Evidence shows: README claims 8 quality gates, deterministic verification, explicit failure reporting (NOT VERIFIED), test files show self-checks for equivalence report and grader. Deductions: dependency availability (e.g., Bun, Python) not explicitly guaranteed in docs, failure message specifics not shown.
Evidence shows: README describes multiple use scenarios (new projects, legacy code, different spec types), capability boundaries (e.g., unsupported models), trigger conditions (e.g., --assess read-only), environment fit (cross-platform, Docker). Deductions: no detailed configuration options documentation, environment requirements (e.g., Bun version) not explicit.
Evidence shows: README has clear structure, includes installation, usage, documentation links, changelog, license (BUSL-1.1), version number (v9.16.0). Deductions: known limitations not listed separately, maintenance responsibility (e.g., contribution guide) not explicit, publisher identity unverified.
Evidence shows: README emphasizes output as verifiable Git repo, evidence receipts, cost estimation, marginal value (e.g., verified completion) and cost-benefit (e.g., free use) are described. Deductions: no real-world usage cases or performance data.
Evidence shows: README provides runnable verification commands (loki proof verify), test files show self-checks, and clearly separates facts from AI assessments. Deductions: cross-source corroboration insufficient (relies on own docs), some claims (e.g., '8 quality gates') not directly verified in code.
- Publisher identity unverified; treat source with caution.
- Dependency security only mentioned; no specific vulnerability scan results or dependency list provided.
- Sensitive data handling details insufficient, e.g., API key storage.
- Rollback mechanism not explicit; confirm recovery on failure.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v11.132.0 Loki Mode v11.132.0
Release notes excerpt
Haiku runs get more correct fixes and more honest proof: Loki reads the whole function before editing, counts Go, pytest and pnpm proof it used to drop, and settles open either/or choices from the maintainer. Changed - On Haiku, the implementer reads the whole function it edits and makes the changed branch match its sibling branches (in a 48-session test on a real issue this raised the correct fix from 2 of 8 to 7 of 8 Haiku sessions), implements the fix the issue prefers with any fallback only on top, and never runs workspace-wide test commands itself. …View on GitHub ↗ -
v11.131.1 Loki Mode v11.131.1
Release notes excerpt
loki outcomes works again. Fixed - loki outcomes (revert, survival and change-failure per receipt) and loki outcomes canary were removed by mistake in 11.130.0 and exited 2; they run again and stay out of the short help.View on GitHub ↗ -
v11.131.0 Loki Mode v11.131.0
Release notes excerpt
Loki proves honest fixes again by testing them against the original code, and spends fewer fix rounds on failures it did not cause. Fixed - The check that a new test fails on the original code and passes on the change now runs on a correctly installed copy of the original code (same interpreter, nearest package's own vitest config), so honest fixes can reach VERIFIED again; import, collection and missing-function errors still never count as proof. - No Wall snapshot is taken when the Wall is off, which removed a "Wall failed" result on large trees. Changed …View on GitHub ↗
FAQ
Can I try it without installation or an API key?
npx loki-mode tour and loki demo --offline replay a past Evidence Receipt with no key or spend, but they are samples rather than a verdict on your code.Will it deploy or push my code automatically?
loki deploy behavior is to print a command rather than run a cloud CLI or git push.