Loki Mode
by asklokesh
README.md
# Loki Mode
Your agent says done. Loki proves it: an autonomous coding agent that turns a task or issue into a verified pull request with a signed receipt you can check yourself.
[](https://www.npmjs.com/package/loki-mode)
[](https://www.npmjs.com/package/loki-mode)
[](https://hub.docker.com/r/asklokesh/loki-mode)
[](LICENSE)
[Website](https://www.autonomi.dev/) | [Quickstart](docs/QUICKSTART.md) | [Install guide](docs/INSTALLATION.md) | [User guide](docs/v10/GUIDE.md) | [CLI reference](docs/CLI-CORE-VERBS.md) | [Compare with opencode](docs/COMPARE-OPENCODE.md) | [Changelog](CHANGELOG.md)
<!-- generated:facts -->
The npm badge above tracks the current release; see [CHANGELOG.md](CHANGELOG.md) for release notes.
CLI reference: [docs/CLI-REFERENCE.md](docs/CLI-REFERENCE.md) (generated from the command registry).
<!-- /generated -->
## Install
```bash
npm install -g loki-mode
```
The npm package installs the Bun runtime the engine needs as an optional dependency. Other ways in: `bun install -g loki-mode`, `brew tap asklokesh/tap && brew install loki-mode`, or `docker pull asklokesh/loki-mode:latest` ([Docker guide](docs/DOCKER.md)). Upgrade with `loki self-update`.
Want to see a result before you install or spend anything?
```bash
npx loki-mode start # no git repo: a real receipt, no key, no spend
npx loki-mode tour # the same receipt when you are already inside a repo
```
`npx` downloads the package the first time, so that step needs the network. The receipt itself replays offline and checks with no provider and no key.
```bash
npx loki-mode wow # a provider is ready: one tiny real task in a temp repo, its own receipt
```
## First run
Loki needs a model. [Claude Code](https://docs.claude.com/en/docs/claude-code) (`claude`) is the default provider: install it and log in. The bundled Agent SDK with an `ANTHROPIC_API_KEY` can stand in for the CLI on the main path. Other coding CLIs are optional. See [Requirements](#requirements).
```bash
cd your-repo
loki setup # first-run wizard (or: loki doctor --fix)
loki start "add rate limiting to /api/login" # the primary path: build, verify, seal a receipt, open a PR
loki start prd.md # same, from a PRD file
loki start owner/repo#123 # same, from a GitHub, GitLab or Jira issue
loki "fix #123" # an issue of this checkout; a copied issue or PR URL works as is
loki edit "rename fooBar to foo_bar" # one small change, no loop
loki chat # interactive alternative: Plan and Build modes
```
`loki start`, `loki "<task>"`, `loki owner/repo#N` and `loki quick "<task>"` all run on the Loki 10 engine by default, whatever the flag order or input form. <!-- loki10-default --> Add `--no-pr` to build and verify without opening a pull request, `--max-cost <usd>` to cap spend, and `--provider <name>` to pick another coding CLI. The spend cap defaults to $100 when `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` is set and to no dollar cap on a subscription login; `budgets.per_run` in `loki.yaml` also sets it. Inspect the route without running: `loki route start prd.md` or `--explain-route`. New here? The [5-minute quickstart](docs/QUICKSTART.md) walks through it.
## What you get
Every run starts from a delivery contract derived from your task, writes checks from the task alone before touching code, implements, verifies, and ends in exactly one outcome: VERIFIED, ALREADY_SATISFIED, FAILED, BUDGET_STOP, BLOCKED or STALLED ([exit codes](docs/exit-codes.md)). If the contract cannot be satisfied as written, the run stops and asks one question instead of guessing.
- **A pull request** written for a quick review: what the issue asked, what changed, how it was tested, and what was NOT PROVEN. A VERIFIED run opens a ready PR; a PARTIAL run opens a draft PR titled `[PARTIAL]` that leads with what is not proven; a FAILED run with committed work opens a draft PR titled `[FAILED: <check>]` that leads with the checks still failing. The exception is a security scan secret match: that branch is never pushed, and Loki prints the file and line it matched and the push command to run after review. Any other outcome keeps the branch local and prints where it is.
- **A signed receipt** at `.loki/runs/<run-id>/receipt.json`, signed with a local Ed25519 key created on first run.
- **A specialist review** when the review council runs: it selects reviewers from a specialist pool (`agents/types.json`, scored by `run.sh:FOCUS_KEYWORDS`) by matching the changed files and diff against each reviewer's keywords.
```bash
loki verify # newest run; or: loki verify <run-id>
```
`loki verify` re-hashes the receipt, checks its signature and checks it against the run's event log. It prints a verdict and exits 0 (VERIFIED), 1 (TAMPERED), 2 (UNCHECKED), 3 (UNSIGNED, refused unless `--allow-unsigned`), 4 (run outcome not verified) or 66 (no runs); `[ $rc -eq 0 ]` is the only safe test for "verified". It also checks that your checkout still matches the sealed code: a run that opened a PR returns you to your starting branch, so verify it from the run's branch (`git fetch origin loki/<run-id> && git checkout --detach FETCH_HEAD`), or it reads UNCHECKED and says so. `loki start` also requires fail-to-pass for a declared behavior change: a Wall test must fail on the old code and pass after, or the verdict stays PARTIAL (`LOKI_MUTATION_STRICT=0` opts out). Full table: [docs/exit-codes.md](docs/exit-codes.md). On another machine, export the public key with `loki keys export` and pass it with `loki verify --pubkey <file>`. A receipt claims only what its checks ran, and lists what they did not; signing proves who produced it, not that the code is bug-free. Details: [docs/SIGNED-RECEIPTS.md](docs/SIGNED-RECEIPTS.md).
For a multi-repo change set, `loki start --workspace <name> "<brief>"` seals one signed `composite.json` over every child receipt, and `loki verify <run-dir>/composite.json` re-checks it offline ([docs/WORKSPACES.md](docs/WORKSPACES.md)). A composite never reads higher than its weakest child.
Two vocabularies, not one. Receipt verdicts (sealed, 5): VERIFIED, PARTIAL, ALREADY_SATISFIED, SPEC_CONFLICT, FAILED. Run outcomes (printed, 8): VERIFIED, ALREADY_SATISFIED, PARTIAL, FAILED, BUDGET_STOP, BLOCKED, STALLED, CANCELLED. BUDGET_STOP, BLOCKED, STALLED and CANCELLED are run outcomes, never receipt verdicts.
| Run outcome | Receipt verdict | `loki start` exit |
|---|---|---|
| VERIFIED, ALREADY_SATISFIED | same | 0 |
| FAILED | same | 1 |
| PARTIAL | same | 6 |
| BUDGET_STOP | none (stopped at a cap) | 3 |
| BLOCKED | SPEC_CONFLICT | 4 |
| STALLED | none | 5 |
| CANCELLED | none | 130 |
Composite: every child VERIFIED or ALREADY_SATISFIED gives VERIFIED (all ALREADY_SATISFIED stays ALREADY_SATISFIED, any SPEC_CONFLICT child keeps SPEC_CONFLICT); one PARTIAL child caps it at PARTIAL; a FAILED child fails it. `loki verify` on a composite exits 0 VERIFIED, 1 TAMPERED, 2 UNCHECKED, 3 UNSIGNED.
Autonomy and deploy: `.loki/policies.json` `autonomy: propose|execute|operate` governs what `loki start` may do (propose opens nothing, execute opens a PR, operate also allows deploy); no file keeps today's behavior. `loki trust` prints advisory graduation advice from your receipts and never writes the policy. Loki deploys only behind `loki deploy --execute` (or `loki start --deploy`) plus a VERIFIED, HEAD-anchored receipt and the policy permission; `--health-url` and `--auto-rollback` add a post-deploy probe and a documented provider rollback. A Sentry alert webhook can enqueue a receipt-gated fix PR ([docs/sentry-intake.md](docs/sentry-intake.md)).
A finished run prints a short summary (every run on both engines also ends with a unified Result, Files, Cost, Elapsed, Receipt and `next:` block; `--quiet` prints only that block, `--json` adds a `summary` object):
```
Outcome: VERIFIED
PR: https://github.com/owner/repo/pull/1
Receipt: sha256:2f9a41c7e0b3...
NOT PROVEN: full suite, app boot, security scan
Cost: $0.42 (claude, 212k tokens)
Time: 4m12s (intake 11s, plan 20s, implement 3m10s, verify 31s)
```
## Core commands
| Command | What it does |
|---------|--------------|
| `loki start "<task>"` | The command you run: same provider model as a raw session, then the harness re-runs the checks and seals a receipt (`--no-pr`, `--provider`, `--max-cost`, `--haiku` to run implement and fix on Haiku, climbing to Sonnet on a failed check). `loki "<task>"` and `loki owner/repo#N` are shorthand. No task and no git repo shows a receipt and spends nothing |
| `loki edit "<change>"` | One targeted change in one pass, no PR, plan or council (`--verify`, `--receipt`, `--commit`, `--dry-run`) |
| `loki quick "<task>"` | One small task with a verify loop, no PR |
| `loki chat` | Interactive alternative: Plan and Build modes, slash commands, `/run` starts a `loki start` run, `--attach` joins one |
| `loki route start <args>` | Show the engine, provider, model and reason without running (also `--explain-route`) |
| `loki setup` | First-run wizard: tools, Claude login, provider, model route, spend cap |
| `loki config list\|get\|set\|path` | Read and write settings |
| `loki models [--local]` | List model routes (OpenRouter, Ollama, LM Studio, llama.cpp, vLLM, custom); discover local models |
| `loki agents list\|new\|show\|export --claude` | Custom child agents in `.loki/agents/*.md` |
| `loki status [run-id]` | Status of the latest run, or of a given run |
| `loki verify [run-id]` | Check a receipt's hash, signature and event log |
| `loki answer [run-id] "<text>"` | Answer a BLOCKED run; it continues under the same run id (also `--text "..."`) |
| `loki doctor [--fix] [--json]` | Check prerequisites, providers and login; `--fix` applies safe fixes |
| `loki control serve` | Start the Control Plane (see below) |
| `loki dashboard` | Open the Control Plane UI, starting it if needed |
| `loki tour` | Show a sample receipt offline. `loki start` does this when you are not in a git repo and did not pass a task |
| `loki wow` | Same live mini-task as a normal start, in a temp repo. It says it makes model calls and what it can cost, and asks y/N first (`--yes` skips; with no terminal it spends nothing). Offline sample when no provider is ready |
| `loki factory "<task>"` | Same as `loki start`. The policy line is printed by start |
| `loki --help` | Everything else; `loki help <command>` for one command |
Core verbs: [docs/CLI-CORE-VERBS.md](docs/CLI-CORE-VERBS.md). Every command (generated): [docs/CLI-REFERENCE.md](docs/CLI-REFERENCE.md). Engine guide, provider table, model routes, custom agents and chat: [docs/v10/GUIDE.md](docs/v10/GUIDE.md). Honest comparison with opencode: [docs/COMPARE-OPENCODE.md](docs/COMPARE-OPENCODE.md).
### Models, providers and local models
Two providers are supported. Claude Code is the default Tier-1 provider (the `claude` CLI, or, with only `ANTHROPIC_API_KEY`, the Anthropic Agent SDK). `--provider opencode` (or `LOKI_PROVIDER=opencode`) runs opencode, which reaches any model, including OpenRouter: export `OPENROUTER_API_KEY` and pass `--model openrouter/<vendor>/<model>`; the Loki 10 engine enforces the wall-clock limit and a post-iteration guard scan there. codex, cline, aider and gemini were removed and exit 2 with a one-line migration message. To keep the Claude harness on OpenRouter or a local model, set `LOKI_MODEL_ROUTE=<kind>/<id>` (kinds: `openrouter`, `ollama`, `lmstudio`, `llamacpp`, `vllm`, `custom`) before `loki start`; `loki models --local` finds local runtimes and prints ready-to-paste values.
```bash
LOKI_MODEL_ROUTE=ollama/qwen3-coder loki start prd.md
OPENROUTER_API_KEY=sk-or-... loki start --provider opencode --model openrouter/deepseek/deepseek-v3.2 prd.md
```
## Control Plane
A local UI and API for all your runs: outcomes, receipts, costs, and an answer box for BLOCKED runs. It is on by default (`LOKI_CONTROL=0` turns it off) and listens on 127.0.0.1 only.
```bash
loki control serve # http://127.0.0.1:47821 (--port N, --db PATH)
loki control backfill . # load existing ./.loki/runs
loki control status # reachable? how many runs?
```
While it is running, runs on this machine ship to it automatically. Guides: [container, Helm and ECS](docs/control-plane-container.md), [migrating from the old dashboard](docs/control-plane-migration.md).
## Requirements
`loki doctor` enforces this list.
Required:
- Claude Code (`claude`), installed and logged in: the default provider and the only one with every feature. Or only `ANTHROPIC_API_KEY`: `loki "<goal>"` then runs on the bundled Agent SDK with no CLI and no extra setting, but `loki edit` and `loki chat` call the `claude` CLI.
- Node.js 20+ (`node`; 22 LTS is the CI target)
- Git 2.x (`git`)
- `curl`
Optional:
- Python 3.8+ (`python3`): deep scans, Python repos and group runs use it. `loki "<goal>"` runs without it.
- `jq`: `loki status` and the bash fallback CLI use it.
- opencode (`--provider opencode`) for any model, including OpenRouter. Ollama or an OpenRouter key for model routes.
- Bun 1.3+ (`bun`) on your PATH (the npm package also bundles it).
- Docker, to run Loki from the published image.
macOS and Linux are supported.
## More
- [Installation](docs/INSTALLATION.md), [environment variables](docs/environment-variables.md), [exit codes](docs/exit-codes.md), [known issues](docs/KNOWN-ISSUES.md), [privacy and telemetry](docs/PRIVACY.md)
- Agent Change Receipt format: [docs/AGENT-CHANGE-RECEIPT.md](docs/AGENT-CHANGE-RECEIPT.md)
- Label an issue, get a pull request (GitHub Actions, no hosted service, about 15 lines of workflow): [setup](docs/v10/GUIDE.md#triggers-without-a-cloud), [full example](docs/examples/loki-issue-to-pr.yml.example)
- Jira and Linear intake: [docs/trackers.md](docs/trackers.md). Two-way Slack: [docs/slack.md](docs/slack.md). Multi-repo runs and composite receipts: [docs/WORKSPACES.md](docs/WORKSPACES.md). Deploy: [docs/DEPLOY-PLAN.md](docs/DEPLOY-PLAN.md)
- MCP: the bundled server exposes 48 tools over stdio (`loki mcp`), including starting a run, reading its status and verifying its receipt. One-click install: [Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=loki-mode&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImxva2ktbW9kZSIsIm1jcCJdfQ==), [VS Code](vscode:mcp/install?%7B%22name%22%3A%22loki-mode%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22loki-mode%22%2C%22mcp%22%5D%7D). Or run `loki mcp install --client claude|cursor|vscode|windsurf`.
- Claude Code plugin: `claude plugin marketplace add asklokesh/loki-mode`, then `claude plugin install loki-mode@loki-mode`. The same marketplace ships [loki-seal](packages/loki-seal/README.md), a Stop hook that refuses "done" when tests newly fail or were weakened.
- Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). Upgrading: [UPGRADING.md](UPGRADING.md)
## Contributing
```bash
git clone https://github.com/asklokesh/loki-mode.git && cd loki-mode
npm install && npm test
```
See [CONTRIBUTING.md](.github/CONTRIBUTING.md), [TESTING.md](docs/TESTING.md) and the [Code of Conduct](.github/CODE_OF_CONDUCT.md).
## License
[Business Source License 1.1](LICENSE). Free for personal, internal, academic and non-commercial use; it converts to Apache 2.0 on March 19, 2030. Contact founder@autonomi.dev for other arrangements.
Loki Mode is built by [Autonomi](https://www.autonomi.dev/).
This server cannot be deployed
Maintenance
ActivityNo data
ResponsivenessMixed handling