Skip to content

INSTALLATION.md

Latest commit

 

History

History
828 lines (566 loc) · 21 KB

INSTALLATION.md

File metadata and controls

828 lines (566 loc) · 21 KB

Loki Mode Installation Guide

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

Version: v6.75.3

What's New in v6.7.0

Dual-Mode Architecture (v6.0.0)

  • loki run command for direct autonomous execution
  • Dual-mode: skill mode (inside Claude Code) and standalone mode
  • Dynamic model resolution across all providers
  • Multi-provider issue fixes and stability improvements

ChromaDB Semantic Code Search (v6.1.0)

  • Semantic code search via ChromaDB vector database
  • MCP integration with loki_code_search and loki_code_search_stats tools
  • Automatic codebase indexing with tools/index-codebase.py

Memory System (v5.15.0+)

  • Episodic, semantic, and procedural memory layers
  • Progressive disclosure with 3-layer loading
  • Token economics tracking for discovery vs read tokens
  • Optional vector search with sentence-transformers

Table of Contents

npm (Recommended)

npm install -g loki-mode

Installs the loki CLI and automatically sets up the skill for Claude Code, Codex CLI, and Gemini CLI via the postinstall script.

Prerequisites: Node.js 18+

What it does:

  • Installs the loki CLI binary to your PATH
  • Creates skill symlinks at ~/.claude/skills/loki-mode, ~/.codex/skills/loki-mode, and ~/.gemini/skills/loki-mode
  • Each provider auto-discovers skills in its respective directory

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

Quick Start

# CLI mode (works with any provider)
loki start ./prd.md
loki start ./prd.md --provider codex
loki start ./prd.md --provider gemini

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

Verify Installation

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

Other Methods

Git clone, Docker, GitHub Action, and VS Code Extension are also available. See alternative-installations.md for details and trade-offs.

VS Code Extension

The easiest way to use Loki Mode with a visual interface.

Installation

From VS Code:

  1. Open Extensions (Cmd+Shift+X / Ctrl+Shift+X)
  2. Search for "loki-mode"
  3. Click Install

From Command Line:

code --install-extension asklokesh.loki-mode

From Marketplace: Visit marketplace.visualstudio.com/items?itemName=asklokesh.loki-mode

Features

  • Activity Bar Icon: Dedicated Loki Mode panel in the sidebar
  • Session View: Real-time session status, provider, phase, and duration
  • Task View: Tasks grouped by status (In Progress, Pending, Completed)
  • Status Bar: Current state and progress at a glance
  • Quick Actions: Start/Stop/Pause/Resume from command palette
  • Keyboard Shortcut: Cmd+Shift+L (Mac) / Ctrl+Shift+L (Windows/Linux)

Usage

  1. Open a project folder in VS Code
  2. Click the Loki Mode icon in the activity bar (or press Cmd+Shift+L)
  3. Click "Start Session" and select your PRD file
  4. Choose your AI provider (Claude, Codex, or Gemini)
  5. Watch progress in the sidebar and status bar

Configuration

Open VS Code Settings and search for "loki":

Setting Default Description
loki.provider claude Default AI provider
loki.apiPort 57374 API server port
loki.apiHost localhost API server host
loki.autoConnect true Auto-connect on activation
loki.showStatusBar true Show status bar item
loki.pollingInterval 2000 Status polling interval (ms)

Requirements

The VS Code extension requires the Loki Mode API server to be running.

Before using the extension, start the server:

# Option A: Using Loki CLI (if installed via npm or Homebrew)
loki start

# Option B: Using the autonomous runner (from source)
./autonomy/run.sh

# Option C: Direct API server start
loki serve

The extension will automatically connect when it detects the server is running at localhost:57374.

Troubleshooting: If you see "API server is not running" errors, make sure you started the server first using one of the commands above.

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
./autonomy/sandbox.sh ./my-prd.md

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

Security Controls

Prompt Injection Protection

By default, prompt injection is disabled for enterprise safety:

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

# Opt-in to enable prompt injection
LOKI_PROMPT_INJECTION_ENABLED=true ./autonomy/run.sh ./my-prd.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 PRD files
  • Enterprise environments with strict security requirements
  • Automated CI/CD pipelines
  • Multi-tenant deployments

Multi-Provider Support

Loki Mode v5.0.0 introduces support for multiple AI providers beyond Claude.

Supported Providers

Provider Status Notes
claude Full Support Default provider, all features available
codex Degraded Mode Core functionality only, some features unavailable
gemini Degraded Mode Core functionality only, some features unavailable

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-prd.md --provider claude

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

# Use Google Gemini
loki start ./my-prd.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-prd.md

# Use Gemini with Docker
docker run -e LOKI_PROVIDER=gemini \
  -v $(pwd):/workspace -w /workspace \
  asklokesh/loki-mode:latest start ./my-prd.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 PRD

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 PRD templates 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 VS Code extension, CLI tools, programmatic access). 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: Connects to API on port 57374 automatically (configurable via loki.apiPort setting)
  • 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 PRD templates.

  • 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

    loki start prd.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!