CodeStory
A local code map that gives coding agents cited context about files, symbols, call paths, and likely change impact
- Status
- v0.17.7 released
- Works with
- Codex, Cursor, Claude Code, and Copilot
- Runs on
- macOS 15+ Apple Silicon with Metal; Windows and Linux x64 with Vulkan
- 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.17.7 release includes the model and accelerator engine in the executable. Packages support macOS 15+ on Apple Silicon with Metal, and Windows and Linux x64 with Vulkan. CPU-only Windows and Linux, Intel Macs, and Windows ARM are unsupported.
Graph navigation covers application code across 15 languages. HTML, CSS, SQL, and supported configuration formats provide structural source anchors, with less depth than application-code graphs. Large or unusual repositories may have partial coverage.
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 cited search results. Answer packets expose gaps that may need further source inspection.
- 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.17.7 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 compact symbol and relationship records for semantic search over the structure of the program. The released executable includes CodeRankEmbed Q8 and its accelerator engine, so there is no separate model download or service to configure.
- Evidence limits
Keep a useful lead separate from a verified answer
A returned search result is a starting point for source inspection. Broad answer packets can report that a claim needs another lookup or has not been established. The published evaluation is a development comparison, so it does not establish a general accuracy or speed improvement.
Project links