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