CodeStory
A local code map that gives coding agents cited context about files, symbols, call paths, and likely change impact
- Status
- v0.16.1 released
- Works with
- Codex, Cursor, Claude Code, and Copilot
- Built with
- Rust, MCP, SCIP, and CodeRankEmbed
- License
- Apache 2.0
Overview
What it is
CodeStory is a local code map for coding agents. It gives an agent durable, cited context about files, symbols, routes, call paths, snippets, search evidence, and likely change impact before the agent starts changing things.
The v0.16.1 release includes the model and accelerator engine in the executable, so the graph, embeddings, and queries stay on the machine. Public packages support Apple Silicon Macs, Windows x64, and Linux x64.
Capabilities
What it does
- 01
Grounds the repository
Builds a compact repository map before an agent begins editing, including languages, components, routes, and important paths.
- 02
Navigates symbols and impact
Finds definitions, callers, references, trails, likely tests, and change impact without repeatedly rereading the whole tree.
- 03
Broadens retrieval
Combines lexical, semantic, graph, and SCIP evidence into source-cited search results and answer packets.
- 04
Fails closed
Reports stale, partial, or incoherent coverage as a gap instead of silently presenting an incomplete map as truth.
- 05
Handles several repositories
Keeps repository indexes isolated while sharing one warm embedded retrieval engine across several checkouts.
- 06
Keeps the work local
Keeps repository maps and queries on the machine. The v0.16.1 executable includes the model and accelerator engine.
Under the hood
Engineering decisions
- The map
Build the map before the agent asks
CodeStory turns the repository into a deterministic graph of files, symbols, routes, calls, and dependencies. The agent can navigate that graph directly instead of repeatedly searching the tree and burning context just to work out how the code fits together.
- Semantic search
Embed the graph, not the codebase
CodeStory embeds the graph’s compact symbol and relationship records, not every chunk of source. That gives the agent semantic search over the structure of the program while making indexing several orders of magnitude faster than full-codebase embedding.
- Measured result
Check whether the agent does less work
On a pinned 18-task public-repository holdout, CodeStory cut context tokens by 43%, repeat-task time by 45%, and tool calls by 87%. It also eliminated direct source reads in that suite. Those results belong to the holdout, not every repository.
Project links