Quick Start Guide

Installation

Install into the current project for your AI coding agent:

npx @lavralabs/lavra@latest --claude      # Claude Code
npx @lavralabs/lavra@latest --opencode    # OpenCode
npx @lavralabs/lavra@latest --gemini      # Gemini CLI
npx @lavralabs/lavra@latest --cortex      # Cortex Code

Or install globally so Lavra is available in every project:

npx @lavralabs/lavra@latest --global

Or with Bun:

bunx @lavralabs/lavra@latest --claude

Restart your agent after installing to pick up the new commands and hooks.

Verify Installation

cd /path/to/your-project

# Check that files were created
ls -la .claude/hooks/        # Should see auto-recall.sh, memory-capture.sh
ls -la .claude/commands/     # Should see lavra-*.md files
ls -la .lavra/memory/        # Should see knowledge.jsonl, recall.sh

Configuration

Workflow config (automatic)

The installer creates .lavra/config/Lavra.json automatically. Edit to tune the workflow:

{
  "workflow": {
    "research": true,        // run research agents in /lavra-design
    "plan_review": true,     // run plan review phase in /lavra-design
    "goal_verification": true // verify completion criteria in /lavra-work and /lavra-ship
  },
  "execution": {
    "max_parallel_agents": 3, // max subagents running at once
    "commit_granularity": "task" // "task" (atomic, default) or "wave" (legacy)
  },
  "model_profile": "balanced" // "balanced" (default) or "quality" (routes security-sentinel, architecture-strategist, goal-verifier, performance-oracle to opus)
}

Existing projects get this file automatically on next session start.

Codebase analysis (optional, for brownfield projects)

If you’re installing Lavra into an existing project, run /project-setup to generate a codebase profile:

/project-setup

When prompted “Run codebase analysis?”, choose Y. This dispatches 3 parallel agents to analyze your stack, architecture, and conventions, saving the results to .lavra/config/codebase-profile.md. This file is used by /lavra-design and /lavra-work as planning context.

Your First Workflow

1. Design

Describe the feature — Lavra runs the full six-phase design pipeline:

/lavra-design "add two-factor authentication with TOTP and QR codes"

1. Brainstorm — interactive interview to clarify scope, constraints, and success criteria
2. Plan — generates a structured multi-phase implementation plan
3. Research — dispatches domain-matched agents in parallel (security practices, framework docs, existing codebase patterns)
4. Revise — integrates research findings back into the plan
5. Review — four adversarial agents (CEO, engineering, security, simplicity) challenge the plan
6. Lock — final plan becomes an epic bead with child tasks ready for /lavra-work

The output is detailed enough that implementation is mechanical — subagents don’t need to ask questions.

2. Work

Pick up the epic and Lavra works through the child beads automatically:

/lavra-work BD-001

For each bead it:

• Recalls relevant knowledge from past sessions automatically
• Implements with parallel subagents where possible
• Runs multi-agent code review and fixes issues
• Commits atomically and closes the bead

3. QA (optional)

Verify the feature from a user’s perspective in a real browser:

/lavra-qa BD-001

4. Ship

Automated end-to-end: close remaining beads, run security scan, open PR:

/lavra-ship BD-001

Next Session

When you start a new session:

1. The auto-recall hook runs automatically
2. It sees you have open beads
3. It searches knowledge for relevant entries
4. Injects them as context

You get relevant learnings without manually searching!

Main Commands

See the full Command Reference or the Command Map for a visual overview of all commands and how they connect.

Manual Knowledge Search

See the Knowledge System docs for how capture, storage, and auto-recall work.

Mid-session, use the slash command in your agent to inject learnings into the agent’s context:

/lavra-recall oauth redirect
/lavra-recall rls postgres

Or search directly from the shell:

# Search by keyword
.lavra/memory/recall.sh "authentication"

# Filter by type
.lavra/memory/recall.sh "jwt" --type learned

# Show recent entries
.lavra/memory/recall.sh --recent 10

# Show stats
.lavra/memory/recall.sh --stats

Example: Full Feature Flow

# Design the feature -- creates epic BD-050 with child beads
/lavra-design "add two-factor authentication with TOTP and QR codes"
# Runs security and framework research agents in parallel
# Creates:
#   BD-050:   [epic] Two-factor authentication
#   BD-050.1: Database schema for OTP secrets
#   BD-050.2: QR code generation endpoint
#   BD-050.3: Verification endpoint
#   BD-050.4: Settings UI

# Work through the epic
/lavra-work BD-050
# Recalls security knowledge automatically
# Implements each child bead with parallel subagents
# Commits atomically, runs review, closes each bead

# Verify in a real browser
/lavra-qa BD-050

# Ship it
/lavra-ship BD-050
# Closes remaining beads, runs security scan, opens PR

Tips

1. Log liberally: Every insight is valuable. Future you will thank you.

2. Use prefixes consistently:

   • LEARNED: - Technical insights, gotchas, discoveries
   • DECISION: - Choices made and why
   • FACT: - Constraints, requirements, environment details
   • PATTERN: - Coding patterns, conventions, idioms
   • INVESTIGATION: - Root cause analysis, how things work
   • DEVIATION: - Auto-fixes applied outside bead scope

3. Review before closing: /lavra-review catches issues early

4. Plan complex features: /lavra-plan prevents rework by researching upfront

5. Checkpoint long sessions: /lavra-checkpoint saves progress without losing context

6. Trust auto-recall: Knowledge will be injected when relevant, no need to search manually

Troubleshooting

Knowledge not appearing at session start

# Check if knowledge exists
.lavra/memory/recall.sh --stats

# Check if hook is installed
ls -la .claude/hooks/auto-recall.sh

# Check if hook is configured
cat .claude/settings.json | jq '.hooks.SessionStart'

Commands not showing up

# Check if commands are installed
ls -la .claude/commands/lavra-*.md

# Restart Claude Code (required after installation)

Agents not found

The plugin references compound-engineering agents but doesn’t install them. If you don’t have compound-engineering installed, the agent dispatches in commands will fail. You can either:

1. Install compound-engineering plugin
2. Or modify the commands to use different agent names
3. Or just use basic beads workflow without the agent commands

Uninstall

npx @lavralabs/lavra@latest --uninstall

This removes the plugin but preserves:

• .beads/ directory
• All your beads
• knowledge.jsonl with all accumulated knowledge

Next Steps

• Read the README for the full feature overview
• Browse the Command Reference for all available commands