FAQ: Getting started, common issues, and tips

[asklokesh]

Installation

npm install -g loki-mode
loki doctor

loki doctor checks your environment: Node version, provider CLIs (Claude, Codex, Gemini), git config, and dependencies.

Common Issues

"No provider found"
You need at least one AI CLI installed. Claude is Tier 1 (recommended):

npm install -g @anthropic-ai/claude-code

"PRD classified as simple but my project is complex"
The classifier uses section count and word count. Add more structure to your PRD (separate sections for each module/feature) or override with:

export LOKI_COMPLEXITY=complex

"Session spins and never completes"
Update to latest -- safety valves are built in:

npm install -g loki-mode@latest

If it persists, tune LOKI_COUNCIL_DONE_SIGNAL_LIMIT (default 10).

"Tests fail but code looks correct"
Hard quality gates run static analysis and test coverage enforcement. Check:

export LOKI_HARD_GATES=false  # disable temporarily to debug

"Running multiple sessions on the same project"
Use loki start --parallel 3 (default 4, max 10). There is no LOKI_MAX_PARALLEL_SESSIONS environment variable.

Tips

• Start small. A CLI tool or single API is a good first project.
• Use loki plan ./prd.md first -- it shows estimated cost, time, and quality gates before you spend a token.
• Use loki start --openspec PATH if you have structured specs (v6.11.0+).
• Use loki run ISSUE to work from GitHub/GitLab/Jira issues directly.
• The Purple Lab dashboard shows real-time progress and lets you interact with your project in a browser-based IDE.

Ask your question below and we will help.