Loki Mode, by Autonomi, turns a spec or an issue into a verified pull request with a receipt you can check. This page covers installing it, a first run, and the options around it.
Version: v11.17.58
Engine note: loki start is the primary command. loki start, loki "<task>", loki owner/repo#N and loki quick all run the Loki 10 engine, whatever the flag order or input form (PRD file, issue ref, task or one-word brief). The previous loop runs only on --engine legacy, LOKI_ENGINE=legacy, or for one call when a flag Loki 10 cannot honor is present. See the user guide and the 5-minute quickstart.
Pick one. All three install the same loki CLI.
npm install -g loki-mode # Node.js 20+ (Node 22 LTS is the CI target)
bun install -g loki-mode # Bun 1.3+
brew tap asklokesh/tap && brew install loki-mode # Homebrew
The Loki 10 engine runs on Bun. The npm package bundles a Bun binary for macOS and Linux (x64 and arm64) as an optional dependency, so a plain npm install needs nothing else. With Homebrew, install Bun too if you do not have it: brew install oven-sh/bun/bun.
The npm postinstall step repoints any stale skill links and installs shell completions (skipped in CI or with LOKI_NO_COMPLETIONS=1). It never fails the install. To install the Loki skill into each detected provider CLI (~/.claude/skills/, ~/.codex/skills/, …), run:
loki setup-skill
npm install -g loki-mode --omit=optional
Skips the bundled Bun binary (62 to 86 MB per platform), the Claude Agent SDK and the OpenTelemetry packages. You then need Bun on PATH (curl -fsSL https://bun.sh/install | bash); without it every command exits with an error that says how to fix it.
pip install loki-mode-sdk installs only the Python REST client. The loki CLI is not on PyPI.
See alternative-installations.md for Docker, the GitHub Action and a git clone install.
loki --version # prints the installed version
loki doctor # checks providers, Bun, skill links and prerequisites
Required (loki doctor fails without them):
| Tool | Minimum |
|---|---|
| Node.js | 20+ (22 LTS is the CI target) |
| Python 3 | 3.8 |
| git | any recent version |
| jq | any |
| curl | any |
Plus a way to reach a model. Claude Code (claude) is the default provider and the only one with every feature, so the default path needs it installed and logged in: npm install -g @anthropic-ai/claude-code, then claude auth login. The bundled Claude Agent SDK with ANTHROPIC_API_KEY can stand in for the CLI on the engine10 path. loki edit and loki chat call the claude CLI directly. Every other provider CLI (codex, cline, aider, opencode) is optional.
Optional: Bun 1.3+ (bundled by the npm package), bash 4+ (recommended), Ollama or an OpenRouter key for non-Claude model routes.
One command checks and configures all of this:
loki setup # wizard: tools, Claude login, provider, model route, spend cap
loki setup --yes # non-interactive, accept defaults
loki setup --check # report only
loki doctor --fix # apply safe fixes; prints exact commands for the rest
loki config list # show settings; also: loki config get|set|path
loki doctor --json # machine-readable
loki doctor --fix creates state directories and a default config. It never installs system packages or runs sudo; it prints those commands instead.
Loki Mode ships an MCP server (npx -y loki-mode mcp, stdio). Register it in your editor with one click or one command.
loki mcp install --client claude, --client cursor, --client vscode or --client windsurf. Add --project or --global to pick the config scope, or --print to show the config and write nothing.loki setup # first-run wizard
loki start "add a /health route" # the primary path: build, verify, seal a receipt
loki start prd.md # same, from a PRD file
loki start owner/repo#42 # same, from a GitHub, GitLab or Jira issue
loki edit "rename fooBar to foo_bar" # one small change, no loop
loki chat # interactive alternative (Plan/Build modes)
loki welcome # what Loki is and what to do next
loki quickstart # guided first build: setup check, idea, template, plan, go
The shorter forms loki "<task>" and loki owner/repo#42 run the same engine. 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; change it with --max-cost <usd>, budgets.per_run in loki.yaml, or loki setup --budget. A quick walkthrough is in QUICKSTART.md.
loki quickstart asks four questions and shows the plan before anything runs. Press Enter at every step to build the sample Todo app. Add --dry-run --json to preview the plan without writing files.
Every finished run leaves a receipt. Check a branch the same way CI does:
loki verify # deterministic verification of HEAD against the base branch
Exit codes are listed in exit-codes.md. Receipt signing and third-party checking are covered in SIGNED-RECEIPTS.md.
The Control Plane is the local UI for runs, work and cost. It needs Bun.
loki control serve # 127.0.0.1:47821 by default
loki dashboard # reuse a running Control Plane, or start one, and open it
See control-plane-migration.md and control-plane-container.md.
| Provider | Notes |
|---|---|
claude |
Default (Tier 1). Full feature set. |
cline |
Full feature set; small local models may fail tool use. Engine10 cost parsed or estimated, guardrail scan. |
codex |
Sequential only. Engine10 cost parsed or estimated, guardrail scan, --sandbox workspace-write. |
aider |
Sequential only; ollama_chat/<model> works for local models. Engine10 cost reported or estimated, guardrail scan, --no-auto-commits. |
opencode |
Sequential only. Supported in engine10 (--provider opencode); cost not measured. Install with npm install -g opencode-ai; model via LOKI_OPENCODE_MODEL=provider/model. |
When LOKI_PROVIDER is unset, Loki uses the first installed CLI in this order: claude, cline, codex, aider, opencode. An explicit LOKI_PROVIDER or --provider NAME always wins.
Run OpenRouter or a local model through the Claude harness with LOKI_MODEL_ROUTE=<kind>/<id>, where kind is openrouter, ollama, lmstudio, llamacpp, vllm or custom (custom needs LOKI_MODEL_BASE_URL):
loki models --local # discover local models, print ready-to-paste values
LOKI_MODEL_ROUTE=ollama/qwen3-coder loki start prd.md
OpenRouter reads OPENROUTER_API_KEY. The route applies to the Claude child process only and every Loki control (cost, kill blocking, receipts) still applies. Details: user guide.
Loki runs with zero configuration. To set options in one place, use a config file:
loki config example > loki.yaml # annotated starter
loki config validate loki.yaml # rejects raw secrets and bad keys
loki start --config loki.yaml ./prd.md
A CLI flag beats an environment variable, which beats the config file, which beats the defaults. Reference secrets as ${VAR}; never write them inline. Every variable is listed in environment-variables.md.
Anonymous diagnostics are on for an ordinary interactive install and off automatically in CI, non-interactive sessions, and when LOKI_ENTERPRISE=true or LOKI_AIRGAP=true is set. They never include code, prompts, file paths or keys. Turn them off with loki telemetry off or DO_NOT_TRACK=1. Details: PRIVACY.md.
The npm install sets them up for you. To install them by hand:
loki completions install # detects bash or zsh
loki completions bash > ~/.loki-completion.bash # or print the script
| Method | Update | Uninstall |
|---|---|---|
| npm | npm update -g loki-mode |
npm uninstall -g loki-mode |
| Bun | bun update -g loki-mode |
bun remove -g loki-mode |
| Homebrew | brew upgrade loki-mode |
brew uninstall loki-mode |
Run state lives in .loki/ inside each project and in ~/.loki/. Remove those directories to delete it.
loki: command not found: the global bin directory of your package manager is not on PATH (npm prefix -g shows where npm installs).the Loki 10 engine cannot run on this machine: no working bun: install Bun, or reinstall without --omit=optional.loki doctor names it and prints the install command.loki doctor --json, then KNOWN-ISSUES.md, then loki crash to file a report.