livespec

Public beta (v0.30). Local-first code intelligence for AI agents. Call graph, impact analysis, and Spec ↔ code traceability. Search is FTS5-only (no embeddings). Dead/legacy findings are graph evidence, not production traffic — confirm with APM/logs before deleting. Spec and docs mutation tools are plugin-gated. Pin: uvx [email protected].

License: GNU AGPL v3 (AGPL-3.0-only). If you modify livespec and offer it over a network (MCP host, SaaS, internal API), you must provide the corresponding source under the same license. Corporate adoption notes and a first-contact compliance template: docs/AGPL_COMPLIANCE_CONTACT.md.

Code intelligence for AI agents — call graph, impact analysis, and bidirectional Spec ↔ code traceability (functional requirements, ADRs, NFRs, and other spec kinds). Local-first, zero external services.

<p align="center"> <img src="docs/assets/spec-explorer.png" alt="livespec Spec Explorer — Spec list, coverage, and linked symbols" width="920" /> </p> <p align="center"><em>Spec Explorer (docs plugin) on this repo — Specs, coverage, and linked symbols at a glance.</em></p>

Who this is for / not for

For	Not for
Agents cold-opening an unfamiliar repo	“Delete all unused code” without APM/logs
Impact analysis before a refactor or PR	Deep semantic search (vectors removed in 0.29)
Spec ↔ code / OpenSpec traceability	Indexing a parent folder of many unrelated repos
Polyrepo HTTP flows via group_db	Replacing tests, human review, or runtime debugging

Ships as a Claude Code plugin bundling three things: the MCP server (the tools), a specialized subagent, and a preloaded Skill (the operating manual). Everything an agent sees — the plugin, subagent, Skill, and MCP tool namespace — is livespec. The PyPI distribution and console command are also livespec (uvx [email protected] / pip install livespec). The legacy command alias livespec-mcp still works on the same entry point.

Battle-tested on real codebases. Four releases of compounding wins on the same Django 5.1.4 queries:

Tool on Django (40K symbols)	v0.8	v0.9	v0.10	v0.14
find_dead_code candidates	824	514	348	344 (−58% cumulative)
find_endpoints(framework='django')	20	162 (+8×)	162	162
quick_orient p95	~60 ms	~60 ms	~60 ms	~60 ms
Partial reindex (touch 1 file, Django)	—	~7 s	—	1.4 s

Validated across 5 distinct agent profiles (exploration, refactor, Spec flow, Django bugfix, TypeScript feature) — see docs/AGENT_USAGE_DATA.md.

Want the agentic flow without reading further?

• MCP prompt agent_playbook — how to use tools and annotate code (@spec:).
• docs/AGENT_QUICKSTART.md — 10-step cold-open flow.
• docs/AGENT_PLAYBOOK.md — same content as the prompt.

30-second tour

# Wire as an MCP server next to your editor (claude.ai/code, Cursor, ...).
# Every tool call carries workspace="/abs/path" — one server, N repos.
uvx [email protected]
# alias still works: livespec-mcp

// First call: cold-index the workspace once
> index_project()
{ "files_total": 2898, "symbols_total": 39789, "edges_total": 465179,
  "languages": {"python": 2786, "javascript": 112}, "watcher_started": false }

// Composite first-contact on an unfamiliar symbol
> quick_orient(qna