Skip to content

INSTALLATION.md

Latest commit

 

History

History
829 lines (574 loc) · 22.1 KB

INSTALLATION.md

File metadata and controls

829 lines (574 loc) · 22.1 KB

Loki Mode Installation Guide

The flagship product of Autonomi. Complete installation instructions for all platforms and use cases.

Version: v7.5.17

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.

Earlier highlights still in scope

  • Bash-to-Bun runtime migration in progress (see UPGRADING.md)
  • 5-provider support: Claude (full), Codex, Gemini, Cline, Aider
  • Memory system (episodic / semantic / procedural)
  • ChromaDB semantic code search via MCP

Table of Contents

npm (Recommended)

npm install -g loki-mode

Installs the loki CLI. 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, Gemini 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.

Prerequisites: Node.js 18+. 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, ~/.gemini/skills/loki-mode

Opt out of anonymous install telemetry:

LOKI_TELEMETRY_DISABLED=true npm install -g loki-mode
# Or set DO_NOT_TRACK=1

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)
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

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 gemini

# Spec as a GitHub issue
loki start --github-issue https://github.com/owner/repo/issues/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

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_ENABLED=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 providers across three tiers. Pick by capability + cost.

Supported Providers

Provider Tier Notes
claude Tier 1 (full) Default. All features incl. Task subagents, MCP, council.
cline Tier 2 Full feature set; small models (<13B) may fail tool-use.
codex Tier 3 (degraded) Sequential only, no Task tool; aligned with @openai/codex v0.125+.
gemini Tier 3 (degraded) Sequential only, no Task tool; uses --approval-mode=yolo.
aider Tier 3 (degraded) Sequential only; ollama_chat/<model> works for local models.

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 Google Gemini
export LOKI_PROVIDER=gemini

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 Google Gemini
loki start ./my-spec.md --provider gemini

Docker

Pass the provider as an environment variable:

# Use Codex with Docker
docker run -e LOKI_PROVIDER=codex \
  -v $(pwd):/workspace -w /workspace \
  asklokesh/loki-mode:latest start ./my-spec.md

# Use Gemini with Docker
docker run -e LOKI_PROVIDER=gemini \
  -v $(pwd):/workspace -w /workspace \
  asklokesh/loki-mode:latest start ./my-spec.md

Degraded Mode

When using codex or gemini 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.

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: Multi-Agent Autonomous Startup System
...
---

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:

Port Service Description
57374 Dashboard + API (FastAPI) Unified server serving both the web dashboard UI (real-time monitoring, task board, Completion Council, memory browser, log streaming) and the REST API (used by CLI tools, programmatic access, and the deprecated VS Code extension). Served by dashboard/server.py.

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 serve --port 57374

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> shows only installed providers (claude, codex, gemini).
    • 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

Need Help?

Happy Building!
⚡