lev CLI — Practical Reference

Four primitives: get (gather context), work (lifecycle), check (validate), go (execute/close).

get (context gathering)

Everything about finding information. Subsumes the old lev-find, lev-index, lev-find-qmd, and llm-tldr skills.

Local search

lev get "auth middleware"                         # auto-selects indexes
lev get "auth" --indexes codebase,documentation   # explicit indexes
lev get "auth" --depth=fs                         # filesystem only
lev get "auth" --depth=bd                         # include bd issues
lev get "auth" --depth=research                   # include external backends

Depth order: context -> filesystem -> bd -> research.

External research backends

When --depth=research or --scope=research:

| Backend | What it does | Command | |---------|-------------|---------| | exa | Neural web + GitHub search | lev get "query" --scope=web | | valyu | Recursive turn-based refinement | valyu research "query" --turns 5 | | deep-research | Tavily multi-query synthesis | deep-research "query" --deep | | brave-search | Quick web lookup | brave-search "query" |

Index management (LEANN)

Source: core/index/ (gRPC server on port 50052, LEANN vendor lib)

lev index build ~/path my-index    # create index from directory
lev index search "query" --index X # semantic search
lev index add file.md --index X    # add content incrementally
lev index status --all             # list all indexes

Index locations: ~/.config/lev/indexes/ (leann/.leann, ck/.index)

Env: LEV_INDEX_PATH overrides base directory.

Markdown/session search (qmd)

Binary: ~/.bun/bin/qmd — BM25 + vector + reranking for local text files.

qmd query "topic" -c claude-sessions --full -n 10
qmd query "topic" -c claudesp-sessions -c clawdbot-sessions
qmd update           # incremental re-index
qmd embed -f         # generate embeddings

Index: ~/.cache/qmd/index.sqlite. Keep sessions < 2 months in index.

Code analysis (llm-tldr)

pip install llm-tldr
tldr warm /path/to/project         # index once
tldr context func_name --project . # function summary (95% token savings)
tldr semantic "validate JWT" .     # natural language code search
tldr impact func_name .            # callers + affected tests
tldr slice file.py func 42        # minimal code affecting line 42

Search decision tree

Local code/docs    → lev get "query"
Session history    → qmd query "topic" -c <collection>
Code structure     → tldr context / tldr semantic
External web       → brave-search, exa, tavily-search
Deep research      → valyu research, deep-research
Social/real-time   → grok-research
Multi-perspective  → skill://lev-research

Domain expansion ladder (when stuck)

Start at your certainty level, climb UP when results are sparse:

File/Function — "find auth.ts" (exact)
Component — "authentication module" (sweet spot for codebase)
Topic — "auth patterns" (pattern match)
Similar — "how NextAuth does this" (prior art)
Goals — "secure user sessions" (problem space)
Ideas — "zero-trust principles" (concepts)

work (lifecycle routing)

Source: plugins/core-sdlc/src/commands/work.ts

The work command owns lifecycle detection, artifact generation, and stage transitions.

work                              # auto-detect stage from context
work --stage=crystallizing        # force stage
work "spec auth system"           # keyword routing

Related commands in plugins/core-sdlc/src/commands/:

review.ts — review queue
instruct.ts — instruction generation
loop.ts — autodev chore loop

Lifecycle stages

ephemeral → captured → classified → crystallizing → crystallized → manifesting → completed
  [inline]   [report]    [typed]     [proposal]      [spec]       [handoff]     [archive]

Keyword routing

| Keywords | Stage | Route | |----------|-------|-------| | research, analyze, prior art | captured | lev get --depth=research | | design, propose, architect | crystallizing | lev-cdo | | plan, spec, implement | crystallized | work | | execute, do it | manifesting | bd | | handoff, checkpoint, resume | manifesting | work |

Learn mode

For fuzzy/early-stage intent that needs structured intake before spec:

learn                    # guided question-by-question interview
learn "some context"     # with seed context

Produces a proposal in .lev/pm/proposals/, then hands off to work --stage=crystallized.

check (validation/ops)

Alignment, drift detection, and health checks. Runs inside work by default.

Alignment audit

work "check alignment"           # preferred: runs inside work

What it checks:

North star freshness (README.md vision, docs/, .lev/pm/)
Priority alignment (bd issues vs. stated roadmap)
Drift types: stale docs, product pivot, coverage gap, status drift, path drift

For deep standalone audit: scan git log, bd issues, ADRs, session handoffs, compare against north star docs.

Issue tracking (bd)

bd ready --json                  # unblocked work
bd create "title" -p 1 --json   # new issue
bd update <id> --claim --json   # claim task
bd close <id> --reason "Done"   # complete
bd list --limit 100 --json      # list issues

Doctor / status

lev index status --all           # index health
qmd status                       # qmd collection freshness

go (execute/close)

Ship work and hand off.

bd close <id> --reason "Completed"   # close issue
git add <files> && git commit        # commit work
git push                             # push (MANDATORY before session end)

Session handoff checklist

File bd issues for remaining work
Run quality gates (tests, lint, build) if code changed
Update bd status — close finished, update in-progress
git pull --rebase && git push — work is NOT done until push succeeds
Write handoff context for next session

Config

Source: core/config/src/ — resolver chain, schema validation, XDG paths.

Resolution chain (later overrides earlier)

System: ~/.config/lev/config.yaml
Project: <project>/.lev/config.yaml
Module: <module>/config.yaml
Environment: LEV_* variables

Key paths

~/.config/lev/              # user config (XDG_CONFIG_HOME/lev)
~/.local/share/lev/         # persistent data
~/.local/state/lev/         # runtime state
~/.cache/lev/               # disposable cache

Autodev surfaces

Plan files: .lev/pm/plans/plan-*.md
Proposals: .lev/pm/proposals/
Handoffs: .lev/pm/handoffs/
Specs: docs/specs/

Source map

| Domain | Path | What it does | |--------|------|-------------| | CLI dispatch | core/poly/src/surfaces/cli/ | Envelope, discovery, aliases | | CLI binary | core/poly/bin/lev | Entry point | | Work/review | plugins/core-sdlc/src/commands/ | Lifecycle routing, review queue | | Exec runtime | core/exec/src/ | Execution SDK | | Config | core/config/src/ | Resolver chain, XDG paths | | Index | core/index/ | LEANN vector search, gRPC service | | Domain types | core/domain/ | Shared contracts and interfaces | | Event bus | core/event-bus/ | Inter-module events (LevEvent) | | FlowMind | core/flowmind/ | Flow declaration/runtime | | Daemon | core/daemon/ | Process supervision, health |

Sub-skills (specialists)

These have real independent logic and remain as separate skills:

| Skill | What it does | |-------|-------------| | work | Lifecycle router — auto-detects stage, generates artifacts | | lev-cdo | CDO deliberation framework — multi-perspective design decisions | | lev-research | Deep research orchestration — multi-backend, cross-validation | | lev-workshop | Workshop lifecycle — intake, analysis, POC, poly pipeline | | lev-builder | Build/migrate workflows — POC to production placement | | lev-intake | Content intake system | | lev-design | UX pipeline | | lev-design-os | Product design | | lev-social | Social research | | lev-orch-sidequest | Autonomous SDLC router | | lev-orch-thinking-parliament | Multi-model deliberation | | skill-discovery | Find skills: ~/.agents/skills/ |

Load any sub-skill with s://<skill-name>.