Loki Mode Installation Guide

The flagship product of Autonomi. Loki Mode is a spec-driven autonomous builder with a built-in trust layer that takes any spec to a deployed product and verifies completion with evidence (quality gates plus a completion council), not just a "done" claim. Complete installation instructions for all platforms and use cases.

Version: v9.22.13

What's New in v7.5.x

Phase 1 RARV-C closure (shipped v7.5.0, default-on as of v7.5.3)

Phase 1 closure features now activate automatically when you run loki start -- no env flags required. Power users can opt out by setting any flag to 0.

• findings_injector.ts -- structured per-finding records (severity, file, line, reviewer) injected into the next iteration's prompt instead of bare comma-separated tokens. Default: ON. Opt out with LOKI_INJECT_FINDINGS=0.
• counter_evidence.ts -- override council. Drop a .loki/state/counter-evidence-<iter>.json to dispute reviewer findings; approval lifts the BLOCK. Default: ON. Opt out with LOKI_OVERRIDE_COUNCIL=0.
• learnings_writer.ts -- automatic structured learnings to .loki/state/relevant-learnings.json on every code_review failure. Default: ON. Opt out with LOKI_AUTO_LEARNINGS=0.
• escalation_handoff.ts -- structured human-handoff doc to .loki/escalations/handoff-*.md before PAUSE. Default: ON. Opt out with LOKI_HANDOFF_MD=0.
• loki status shows a "Phase 1 artifacts" section when findings, learnings, or escalations exist (added v7.5.5; see the phase1 block in loki status --json).
• See skills/quality-gates.md for full schema and reachability notes.

Output-token compressor (caveman, default-on, Claude-only)

Loki integrates caveman, an optional Claude Code skill that compresses the model's OUTPUT tokens only (keeping all technical substance). It activates on free-form generation (the main RARV dev loop) and is HARD-SUPPRESSED on every trust-gate subcall (council votes, code review verdict, evidence-related parses) so determinism is never affected.

• Claude-provider-only; runs are byte-identical on Cline / Codex / Aider / opencode.
• Default on; opt out with LOKI_CAVEMAN=0.
• Level: LOKI_CAVEMAN_LEVEL (default full; also lite, ultra, wenyan*).
• Pinned + vendor-less: LOKI_CAVEMAN_VERSION (default 1.9.0); Loki bootstraps the pinned version on demand (opt out LOKI_CAVEMAN_AUTO_BOOTSTRAP=0).
• Savings are output-token-only and bounded; Loki never quotes a dollar figure.
• See skills/quality-gates.md (Output-token compressor) for details.

Earlier highlights still in scope

• Bash-to-Bun runtime migration in progress (see UPGRADING.md)
• Provider-agnostic runtime: Claude (full), Cline, Codex, Aider, opencode (no vendor lock-in)
• Memory system (episodic / semantic / procedural)
• ChromaDB semantic code search via MCP

Table of Contents

• Bun (Recommended)
• npm
• Homebrew
• Quick Start
• Verify Installation
• Other Methods
• VS Code Extension (Deprecated)
• Sandbox Mode
• Multi-Provider Support
• Environment Variables
• Claude Code (CLI)
• Claude.ai (Web)
• Anthropic API Console
• Ports
• Shell Completions
• Troubleshooting

Bun (Recommended)

bun install -g loki-mode

Installs the loki CLI. Bun is the recommended path: the loki shim runs the faster TypeScript runtime when bun is on PATH, and the stable bash engine (the autonomous loop, quality gates, and completion council) runs underneath on every route, so you lose nothing by choosing Bun. Run loki setup-skill once after install to create the per-provider skill symlinks (Claude Code, Codex CLI).

Prerequisites: Bun 1.3+ (curl -fsSL https://bun.sh/install | bash, or brew install oven-sh/bun/bun). No separate Node install is required.

Update: bun update -g loki-mode

Uninstall: bun remove -g loki-mode

npm

npm install -g loki-mode

A fully supported alternative when you prefer npm or do not have Bun. As of v7.4.12 there is no postinstall step; run loki setup-skill once after install to create the per-provider skill symlinks (Claude Code, Codex CLI). The loki shim auto-routes read-only commands to the Bun runtime when bun is on PATH and falls back to the bash CLI otherwise (the core autonomous engine is the same on both routes).

Prerequisites: Node.js 20+ (Node 22 LTS recommended; it is the primary tested/CI target). Bun 1.3+ optional but recommended for the faster routed commands and forward-compat with v8.0.0.

What it does:

• Installs the loki CLI binary to your PATH (bin/loki shim)
• Subsequent loki setup-skill creates symlinks at ~/.claude/skills/loki-mode, ~/.codex/skills/loki-mode

Anonymous telemetry is OPT-IN and OFF by default. A default npm install sends nothing, so air-gapped and enterprise installs are safe out of the box. To opt in to anonymous diagnostics, run loki telemetry on or set LOKI_TELEMETRY=on. To make opting in impossible across a fleet, bake an opt-out into your base image (opt-out always wins):

# Hard-disable everywhere (belt and suspenders; opt-out always wins):
LOKI_TELEMETRY_DISABLED=true npm install -g loki-mode
# Or set DO_NOT_TRACK=1

See PRIVACY.md for the exact data sent and the full opt-in / opt-out model.

Update: npm update -g loki-mode

Uninstall: npm uninstall -g loki-mode

Homebrew

brew tap asklokesh/tap && brew install loki-mode

Installs the loki CLI. To also install the skill for interactive use with all providers:

loki setup-skill

Update: brew upgrade loki-mode

Uninstall: brew uninstall loki-mode

PyPI / Python SDK

The loki CLI is NOT available via pip install loki-mode. PyPI hosts only the Python REST client SDK at loki-mode-sdk (v7.4.18+). The dashboard, MCP server, and orchestrator components ship via npm, Docker, and Homebrew only.

# Install the Python REST client only
pip install loki-mode-sdk

# Install the full CLI (recommended)
bun install -g loki-mode  # or: npm install -g loki-mode, or: brew tap asklokesh/tap && brew install loki-mode

The naming asymmetry (loki-mode on npm vs loki-mode-sdk on PyPI) is intentional: PyPI's loki-mode namespace is reserved for a future server package, while loki-mode-sdk is the thin client.

Quick Start

New here? loki quickstart (v7.29.0) walks you through your first build in four questions (setup check, one-line idea, template pick, plan review with a real cost estimate before anything is spent). Pressing Enter at every step builds the sample Todo app.

loki quickstart

For a fully specified first build, provide the idea, an optional exact shipped starter template, and explicit consent:

loki quickstart "an internal reporting workspace" --template dashboard --yes

Use --dry-run instead of --yes to preview the same template and plan without provider discovery, file writes, or execution; add --json for one versioned machine-readable object.

For a local pipeline, pass that object to --from-preview - --yes. Loki accepts at most 1 MiB from non-terminal stdin, revalidates the schema, and recomputes the current estimate before the explicitly consented build starts:

loki quickstart "an internal reporting workspace" --template dashboard --dry-run --json \
  | loki quickstart --from-preview - --yes

Omit --yes, pipe malformed or oversized JSON, or use - from a terminal and the continuation exits 2 before provider discovery, PRD writes, or execution.

Drop a spec -- any artifact that describes what you want built -- and Loki Mode takes it from spec to deployed app. Specs can be a markdown PRD, a GitHub issue URL, or a YAML feature description.

# CLI mode (works with any provider) -- spec as markdown PRD
loki start ./spec.md
loki start ./spec.md --provider codex
loki start ./spec.md --provider cline

# Spec as a GitHub issue -- pass it positionally, it is auto-detected
loki start https://github.com/owner/repo/issues/42
loki start owner/repo#42

# Spec as a YAML feature description
loki start ./feature.yaml

# Interactive mode (inside your coding agent)
claude --dangerously-skip-permissions
# Then say: "Loki Mode with spec at ./my-spec.md"

Verify Installation

loki --version    # Should print the current version
loki doctor       # Check skill symlinks, providers, and system prerequisites

Configuration file

Instead of exporting many LOKI_* env vars, point loki start at a config file with --config <path> (aliases: --env-file, --vars), or set LOKI_CONFIG_FILE. The format is detected from the extension or content: .yaml/.yml, .json, or .env (flat LOKI_*=value lines). Values resolve by precedence: a CLI flag beats an ambient env var, which beats the --config file, which beats built-in defaults. Never inline a secret; reference an env var with ${VAR} and the loader expands it at load time (an unset reference is skipped with a warning, and a raw-looking secret literal is flagged and rejected by loki config validate). Run loki config example to generate an annotated starter.

# config.yaml
dashboard:
  port: 9000
github:
  token: ${GITHUB_TOKEN}   # expanded from the environment, never stored inline

loki start --config config.yaml ./prd.md
loki config validate config.yaml    # check refs and reject raw secrets before a run

Other Methods

Git clone and Docker installation methods are also available. See alternative-installations.md for details and trade-offs.

VS Code Extension (Deprecated)

DEPRECATED as of v7.2.0. The Loki Mode VS Code extension is no longer maintained. Use the dashboard at loki dashboard start instead.

The marketplace listing remains for users on v7.2.0 and earlier but will not receive further updates. The vscode-extension/ source remains in the repository for contributors who want to build the extension locally; it is no longer published to the VS Code Marketplace and is not included in npm tarballs.

Recommended replacement: the dashboard

loki dashboard start
# Then open http://localhost:57374 in your browser.

The dashboard provides session monitoring, task views, the completion council, log streaming, and the managed-memory panel -- the same surface the extension exposed, plus everything added since v7.2.0.

Sandbox Mode

Run Loki Mode in an isolated Docker container for enhanced security.

Features

• Docker isolation: Complete process isolation from host system
• Seccomp profiles: Restricted system calls
• Resource limits: CPU, memory, and process limits enforced
• Dropped capabilities: Minimal Linux capabilities
• Read-only rootfs: Immutable container filesystem
• Git worktree fallback: Automatic fallback when Docker unavailable

Usage

# Run in sandbox mode (spec can be PRD, issue link, or YAML)
./autonomy/sandbox.sh ./my-spec.md

# With provider selection
./autonomy/sandbox.sh --provider codex ./my-spec.md

Security Controls

Prompt Injection Protection

By default, prompt injection is disabled for enterprise safety:

# Default: prompt injection disabled
./autonomy/run.sh ./my-spec.md

# Opt-in to enable prompt injection
LOKI_PROMPT_INJECTION=true ./autonomy/run.sh ./my-spec.md

Human Input Security

The HUMAN_INPUT.md file has security controls:

• Symlink protection: Symlinks are rejected
• Size limit: Maximum 1MB file size
• Path validation: Must be within .loki/ directory

When to Use Sandbox Mode

• Running untrusted spec files (PRD, issue export, YAML)
• Enterprise environments with strict security requirements
• Automated CI/CD pipelines
• Multi-tenant deployments

Multi-Provider Support

Loki Mode supports five active providers across three capability modes, plus historical/upcoming entries. Pick by capability + cost.

Supported Providers

When LOKI_PROVIDER is unset, Loki auto-detects the first installed provider in this order: claude, cline, codex, aider, opencode (providers/loader.sh:191). An explicit LOKI_PROVIDER always wins and is never silently substituted.

Configuration

Environment Variable

Set the LOKI_PROVIDER environment variable to select your provider:

# Use Claude (default)
export LOKI_PROVIDER=claude

# Use OpenAI Codex
export LOKI_PROVIDER=codex

# Use Cline
export LOKI_PROVIDER=cline

CLI Flag

Use the --provider flag when invoking Loki Mode:

# Use Claude (default)
loki start ./my-spec.md --provider claude

# Use OpenAI Codex
loki start ./my-spec.md --provider codex

# Use Cline
loki start ./my-spec.md --provider cline

Docker

Docker is where sandboxes and runs happen. The easiest way to run Loki in a container is the loki docker host wrapper, which gives you the full local experience (including .loki/ state, resume, and continuity) in one command. The raw docker run and docker compose methods below remain as alternatives.

loki docker (easiest)

If you have loki installed on the host (npm/brew/bun) plus Docker, loki docker runs any loki command inside the published asklokesh/loki-mode image with zero config:

loki docker start prd.md             # full local experience in Docker
loki docker status                   # any loki command works
loki docker --dry-run start prd.md   # print the docker command, do not run

It bind-mounts the current folder to /workspace, so .loki/ state (memory, session, queue, checkpoints) persists on the host and resume and continuity behave exactly like the local loki CLI. Auth is auto-detected: ANTHROPIC_API_KEY if set, else your host's existing Claude Code login (Max/Pro subscribers need no API key), else an honest error with guidance. It also forwards ~/.gitconfig and ~/.config/gh (read-only) plus GITHUB_TOKEN/GH_TOKEN if set, so commits and PRs work like local, and exposes the dashboard on port 57374. Use --image IMG to override the image.

loki docker is a thin host wrapper around the image; it requires loki and Docker installed on the host.

Multi-repo + unified dashboard: you can run loki docker start in several different repos at once, exactly like the host CLI. Each repo gets its own container (deterministic name loki-<hash-of-path>) and its own bind-mounted .loki/ state. Every loki docker project registers with the host dashboard, so running loki dashboard on the host shows ALL your projects in one unified view, whether they run via local loki start or via loki docker start. Builds run with the dashboard off by default (so concurrent runs do not collide on port 57374); use the host loki dashboard, or loki docker start --api for a single containerized run's UI.

docker run

As of v7.45.0 the image ships the Claude Code CLI, so the default claude provider works inside the container. Provide auth with your Anthropic API key:

# Run Loki Mode in Docker (Claude provider, API-key auth)
docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v $(pwd):/workspace -w /workspace \
  asklokesh/loki-mode:8.0.0 start ./my-spec.md

docker compose + .env (no host install)

If you prefer not to install loki on the host, the repo ships a docker-compose.yml with env_file: .env. Copy the example, set your key once, then run without retyping long -e flags:

cp .env.example .env          # then edit .env and set ANTHROPIC_API_KEY
docker compose run loki start prd.md

.env is gitignored. Edit it and re-run any time; compose reloads it automatically.

Host OAuth (Claude Code Max/Pro subscribers, no API key)

If you have a Claude Code subscription and no API key, you can reuse your host login by mounting your credentials file at /home/loki/.claude/.credentials.json instead of setting ANTHROPIC_API_KEY. See DOCKER_README.md "Option 2: host OAuth" for the one-line export command and the compose volume to uncomment.

Other providers in Docker

The image ships only the Claude Code CLI. Cline, Codex, Aider, and opencode are bring-your-own-CLI: install the provider CLI in a derived image (or mount it), then select it with -e LOKI_PROVIDER=<name>. See DOCKER_README.md for details.

Degraded Mode

When using codex, cline, or aider providers, Loki Mode operates in degraded mode:

• Core autonomous workflow functions normally
• Some advanced features may be unavailable or behave differently
• Model-specific optimizations (Opus/Sonnet/Haiku routing) are adapted for each provider
• Quality gates and RARV cycle remain fully functional

Recommendation: For the best experience and full feature support, use the default claude provider.

Environment Variables

Loki Mode is designed to run with zero configuration: the trust-layer and quality features below are default-on and decide intelligently by inspecting the work. The environment variables here are opt-out escape hatches for power users, not required setup. Set the documented value to disable a feature; leave the variable unset to keep the intelligent default.

Trust-gate and completion knobs (default-on)

These are read by the orchestrator (autonomy/run.sh) on every run.

• LOKI_REVIEW_INCONCLUSIVE_BLOCK (default 1) -- when a code-review cycle returns zero usable verdicts (every reviewer produced empty output), the review is treated as INCONCLUSIVE and the gate BLOCKS, because an all-empty review proves nothing. A bounded one-shot retry runs first (LOKI_REVIEW_RETRY, default 1). Set LOKI_REVIEW_INCONCLUSIVE_BLOCK=0 to record the inconclusive result without blocking.

• LOKI_COMPLETION_TEST_CAPTURE (default 1) -- before the verified-completion evidence gate runs, Loki captures a fresh test-results.json so the gate scores on real PASS/FAIL test results instead of a stale or missing file. It reuses this iteration's results if already fresh, and never crashes the completion path on red tests (the gate is the decider). Set LOKI_COMPLETION_TEST_CAPTURE=0 to opt out.

• LOKI_AUTO_DOCS (default true) -- auto-generates the .loki/docs/ suite before the documentation gate evaluates, so the gate scores on real generated docs instead of nagging you to run loki docs generate by hand. Bounded: runs at most once per run when docs are missing, and again only when existing docs are substantially stale; best-effort, never fails the iteration loop. Set LOKI_AUTO_DOCS=false to opt out.

Output-token compressor (caveman, Claude-only)

Loki integrates caveman, an optional Claude Code skill that compresses the model's OUTPUT tokens only (keeping all technical substance). It activates on free-form generation (the main RARV dev loop) and is HARD-SUPPRESSED on every trust-gate subcall (council votes, code review verdicts, evidence-related parses) so determinism is never affected. It is Claude-provider-only; runs are byte-identical on Cline / Codex / Aider / opencode. These variables are read in autonomy/lib/claude-flags.sh.

• LOKI_CAVEMAN (default on) -- set LOKI_CAVEMAN=0 to disable the compressor. Suppression on trust-gate subcalls is unconditional and applies even when caveman is globally installed but LOKI_CAVEMAN=0, so trust gates are never exposed to compression.

• LOKI_CAVEMAN_LEVEL (default full) -- the compression level for free-form activation. When you do NOT set this, the level is inferred per-invocation from the run's RARV tier (planning -> lite, development/fast -> full); the auto path never selects ultra. Setting LOKI_CAVEMAN_LEVEL explicitly overrides the inference entirely (the opt-out escape hatch).

• LOKI_CAVEMAN_VERSION (default 1.9.0) -- the pinned caveman version used by the one-time bootstrap. Bump only to upgrade the compressor.

RARV-C closure knobs (default-on)

The Phase 1 / RARV-C closure loop (findings injection, override council, learnings writer, handoff doc) is default-on and documented in detail at the top of this guide under Phase 1 RARV-C closure: LOKI_INJECT_FINDINGS, LOKI_OVERRIDE_COUNCIL, LOKI_AUTO_LEARNINGS, and LOKI_HANDOFF_MD (each opt out with =0). For the full schema and reachability notes, see skills/quality-gates.md.

Claude Code (CLI)

Loki Mode can be installed as a skill in three ways:

Option A: Git Clone (Recommended)

Personal installation (available in all projects):

git clone https://github.com/asklokesh/loki-mode.git ~/.claude/skills/loki-mode

Project-specific installation:

# Navigate to your project directory first
cd /path/to/your/project

# Clone to local skills directory
git clone https://github.com/asklokesh/loki-mode.git .claude/skills/loki-mode

Option B: Download from Releases

# Navigate to skills directory
cd ~/.claude/skills

# Get latest version number
VERSION=$(curl -s https://api.github.com/repos/asklokesh/loki-mode/releases/latest | grep tag_name | cut -d'"' -f4 | tr -d 'v')

# Download and extract
curl -L -o loki-mode.zip "https://github.com/asklokesh/loki-mode/releases/download/v${VERSION}/loki-mode-claude-code-${VERSION}.zip"
unzip loki-mode.zip && rm loki-mode.zip

Result: Creates ~/.claude/skills/loki-mode/SKILL.md

Option C: Minimal Install (curl)

If you only want the essential files without the full repository:

# Create directory structure
mkdir -p ~/.claude/skills/loki-mode/references

# Download core skill file
curl -o ~/.claude/skills/loki-mode/SKILL.md \
  https://raw.githubusercontent.com/asklokesh/loki-mode/main/SKILL.md

# Download agent definitions
curl -o ~/.claude/skills/loki-mode/references/agent-types.md \
  https://raw.githubusercontent.com/asklokesh/loki-mode/main/references/agent-types.md

# Download deployment guides
curl -o ~/.claude/skills/loki-mode/references/deployment.md \
  https://raw.githubusercontent.com/asklokesh/loki-mode/main/references/deployment.md

# Download business operations reference
curl -o ~/.claude/skills/loki-mode/references/business-ops.md \
  https://raw.githubusercontent.com/asklokesh/loki-mode/main/references/business-ops.md

Note: This minimal install won't include examples, tests, or the autonomous runner. Use Option A or B for full functionality.

Claude.ai (Web)

For using Loki Mode on the Claude.ai web interface:

Step 1: Download the Skill Package

1. Go to Releases

2. Download either:

   • loki-mode-X.X.X.zip (standard format)
   • loki-mode-X.X.X.skill (skill format)

   Both contain the same skill and will work.

Step 2: Upload to Claude.ai

1. Open Claude.ai
2. Go to Settings (gear icon)
3. Navigate to Features → Skills
4. Click Upload Skill
5. Select the downloaded .zip or .skill file

File Structure: The Claude.ai package has SKILL.md at the root level as required by the web interface.

Anthropic API Console

For using Loki Mode through the Anthropic API Console (console.anthropic.com):

Step 1: Download the API Package

1. Go to Releases

2. Download loki-mode-api-X.X.X.zip (note the -api- version)

   Important: The API version has a different file structure than the web version.

Step 2: Upload to API Console

1. Go to console.anthropic.com
2. Navigate to Skills section
3. Click Upload Skill
4. Select the downloaded loki-mode-api-X.X.X.zip file

File Structure: The API package has SKILL.md inside a loki-mode/ folder as required by the API.

Verify Installation

For Claude Code (CLI)

Check that the skill file is in place:

cat ~/.claude/skills/loki-mode/SKILL.md | head -10

Expected output: Should show YAML frontmatter starting with:

---
name: loki-mode
description: Autonomous Spec-to-Product System (RARV-C closure loop)
...
---

For Claude.ai (Web)

1. Start a new conversation
2. Type: Loki Mode
3. Claude should recognize the skill and ask for a spec (PRD, GitHub issue link, or YAML)

For API Console

1. Create a new API call with skills enabled
2. Include the skill in your request
3. The skill should be available for use

File Structure

After installation, you should have this structure:

loki-mode/
├── SKILL.md              # Main skill file (required)
├── README.md             # Documentation
├── docs/
│   └── INSTALLATION.md   # This file
├── CHANGELOG.md          # Version history
├── VERSION               # Current version number
├── LICENSE               # Business Source License 1.1
├── references/           # Agent and deployment references
│   ├── agents.md
│   ├── deployment.md
│   └── business-ops.md
├── autonomy/             # Autonomous runner (CLI only)
│   ├── run.sh
│   └── README.md
├── templates/            # 22 spec templates (PRD-style) for project scaffolding
│   ├── simple-todo-app.md
│   ├── api-only.md
│   ├── static-landing-page.md
│   └── ... (22 templates total)
├── tests/                # Test suite (CLI only)
│   ├── run-all-tests.sh
│   ├── test-bootstrap.sh
│   └── ...
└── integrations/         # Third-party integrations
    └── vibe-kanban.md

Note: Some files/directories (autonomy, tests, templates) are only available with full installation (Options A or B).

Ports

Loki Mode uses two network ports for different services:

When to Use Which Port

• Browser access (dashboard, monitoring): Use port 57374 -- http://localhost:57374
• API calls (REST, programmatic): Use port 57374 -- http://localhost:57374
• VS Code extension (deprecated as of v7.2.0): Connects to API on port 57374 automatically (configurable via loki.apiPort setting). No new releases will be published; see the deprecation notice above.
• The server is started automatically when you run loki start or ./autonomy/run.sh. No manual configuration is needed.

Port Configuration

# Dashboard port (default: 57374)
LOKI_DASHBOARD_PORT=57374 loki dashboard start

# API port (default: 57374)
loki api start --port 57374   # was: loki serve

CORS Configuration

For remote or cross-origin access to the dashboard, configure allowed origins via the LOKI_DASHBOARD_CORS environment variable:

# Allow specific origins
LOKI_DASHBOARD_CORS="http://localhost:3000,https://my-dashboard.example.com" loki dashboard start

# Default: http://localhost:57374,http://127.0.0.1:57374 (localhost-only, secure by default)

Shell Completions

Enable tab completion for the loki CLI to support subcommands, flags, and file arguments.

Bash Setup

Option 1: Permanent Setup (Recommended)

Add the source command to your startup file so completions load every time you open a terminal.

Add this line to your ~/.bashrc (Linux) or ~/.bash_profile (macOS):

# npm install: use the npm package path
source "$(npm root -g)/loki-mode/completions/loki.bash"

# git clone: use the skills directory
source ~/.claude/skills/loki-mode/completions/loki.bash

Option 2: Manual Sourcing (Temporary)

If you only want to enable completions for your current terminal session (for example, for testing), run:

source completions/loki.bash

Optional: Smoother Bash Experience

By default, Bash requires two TAB presses to show the completion menu. To make it instant (similar to Zsh) and cycle through options more easily, add the following lines to your ~/.inputrc file:

# Show menu immediately on first TAB
set show-all-if-ambiguous on

# Case-insensitive completion (optional)
set completion-ignore-case on

Note: You will need to restart your terminal for ~/.inputrc changes to take effect.

Zsh Setup

Zsh completions require the script to be located in a directory listed in your $fpath.

Permanent Setup

Add the loki completions directory to your $fpath in ~/.zshrc before initializing completions:

# 1. Add the completions directory to fpath
fpath=(/path/to/loki/completions $fpath)

# 2. Initialize completions
autoload -Uz compinit && compinit

Testing Completions

After installation, restart your shell or source your configuration file, then verify:

Bash

loki <TAB>            # Should immediately list subcommands
loki start -<TAB>     # Should list flags (--provider, --parallel, etc.)

Zsh

loki <TAB>                # Should show subcommands with descriptions
loki start --pro<TAB>     # Should autocomplete to --provider

Completion Features

The completion scripts support:

• Subcommands start, stop, pause, resume, status, dashboard, import, council, memory, provider, config, audit, metrics, watchdog, secrets, help, completions

• Smart Context

  • loki start --provider <TAB> completes the supported providers (claude, cline, codex, aider, opencode; see completions/loki.bash:24).
  • loki start <TAB> defaults to file completion for spec files (PRD templates, YAML).

• Nested Commands Handles specific subcommands for council, memory, config, audit, metrics, watchdog, and secrets.

Troubleshooting

Skill Not Found

Problem: Claude doesn't recognize "Loki Mode" command.

Solutions:

1. Check installation path:

   ls -la ~/.claude/skills/loki-mode/SKILL.md
   

2. Verify YAML frontmatter:

   cat ~/.claude/skills/loki-mode/SKILL.md | head -5
   

   Should show name: loki-mode

3. Restart Claude Code:

   # Exit and restart claude command
   

Permission Denied

Problem: Cannot create directories or download files.

Solution:

# Ensure skills directory exists
mkdir -p ~/.claude/skills

# Check permissions
ls -la ~/.claude/

Download Fails

Problem: curl or wget commands fail.

Solutions:

1. Check internet connection

2. Try alternate download method:

   # Use wget instead of curl
   wget -O ~/.claude/skills/loki-mode/SKILL.md \
     https://raw.githubusercontent.com/asklokesh/loki-mode/main/SKILL.md
   

3. Manual download:

   • Visit the URL in a browser
   • Save file manually to ~/.claude/skills/loki-mode/

Autonomous Runner Won't Start

Problem: ./autonomy/run.sh gives "command not found" or permission errors.

Solutions:

1. Make executable:

   chmod +x autonomy/run.sh
   

2. Run from repository root:

   # Make sure you're in the loki-mode directory
   cd ~/.claude/skills/loki-mode
   ./autonomy/run.sh
   

3. Check prerequisites:

   # Ensure Claude Code is installed
   claude --version
   
   # Ensure Python 3 is available
   python3 --version
   

References Not Loading

Problem: Skill loads but agent definitions or deployment guides are missing.

Solution:

# Ensure all reference files are present
ls -la ~/.claude/skills/loki-mode/references/

# Should show:
# agents.md
# deployment.md
# business-ops.md

# If missing, download them:
curl -o ~/.claude/skills/loki-mode/references/agent-types.md \
  https://raw.githubusercontent.com/asklokesh/loki-mode/main/references/agent-types.md

Updating Loki Mode

For Git Installations

cd ~/.claude/skills/loki-mode
git pull origin main

For Manual Installations

1. Download the latest release
2. Extract to the same directory (overwrite existing files)
3. Or delete old installation and reinstall

Check Current Version

cat ~/.claude/skills/loki-mode/VERSION

Uninstalling

Claude Code (CLI)

# Remove the skill directory
rm -rf ~/.claude/skills/loki-mode

Claude.ai (Web)

1. Go to Settings → Features → Skills
2. Find "loki-mode" in the list
3. Click Remove

API Console

1. Go to Skills section
2. Find "loki-mode"
3. Click Delete

Next Steps

After installation:

1. Verify Setup: Check your environment is ready

   loki doctor
   

2. Scaffold a Project: Create a project from a template

   loki init my-app --template simple-todo-app
   cd my-app
   

3. Start Building: Launch autonomous development from any spec (PRD, GitHub issue, or YAML)

   loki start spec.md
   

4. Read Documentation: Check out README.md for usage guides

5. Join the Community: Report issues or contribute at GitHub

Release Operations

npm error 404 Not Found - PUT https://registry.npmjs.org/loki-mode

Need Help?

• Issues/Bugs: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: README.md

Happy Building!