A local code map your coding agent can trust.
CodeStory gives coding agents a durable understanding of the repository in front of them: files, symbols, call paths, routes, snippets, and search evidence. Answers stay tied to source locations, and incomplete coverage is reported as a gap instead of being filled with guesses.
flowchart LR
Repo["your repository"] --> Map["local code map"]
Question["your question"] --> Agent["coding agent"]
Map --> Agent
Agent --> Answer["cited answer, change plan, or review context"]
The released executable includes CodeRankEmbed Q8 and its accelerator engine. There is no service to start, model to fetch separately, port to manage, or retrieval setup to approve. The plugin downloads that executable once, the first time you use it, and reports progress while it does. Source, indexes, and queries stay local by default.
- Repository grounding: a compact map of the checkout, its languages, components, and important paths.
- Symbol and impact navigation: definitions, callers, references, trails, routes, and likely tests without repeated whole-tree scans.
- Broad retrieval: lexical, semantic, graph, and SCIP evidence combined into cited search results and answer packets.
- Visible limits: stale, partial, or incoherent evidence fails closed instead of looking complete.
| Host | Start here |
|---|---|
| Codex | Codex guide — the recommended first install |
| Cursor | Cursor guide — install from Customize |
| Claude Code | Claude Code guide |
| GitHub Copilot | Copilot guide |
Capability comparison, day-1 checklist, and shared prompts: User guides.
- Open the guide for your host and install CodeStory once.
- Start a fresh agent session in the repository you want to understand.
- Ask an ordinary code question.
That is the normal setup. The first relevant call builds the local map. The first broad question also initializes the embedded model and prepares semantic search. If it needs more than one foreground turn, the agent retries the same call; there is no separate setup or approval flow.
One host process can work across several repositories. Their indexes stay isolated while they share one warm embedding engine:
flowchart LR
Host["one agent host"] --> A["runtime: repository A"]
Host --> B["runtime: repository B"]
A --> CacheA["private index A"]
B --> CacheB["private index B"]
A --> Engine["one warm CodeRankEmbed engine"]
B --> Engine
Something blocked? Troubleshooting.
| Platform | Release support |
|---|---|
| macOS 15+ on Apple Silicon | Supported with Metal |
| Windows x64 | Supported with Vulkan |
| Linux x64 | Supported with Vulkan |
| CPU-only Windows and Linux | Unsupported |
| Intel Mac | Unsupported |
| Windows ARM | Unsupported |
"Supported with Metal" and "Supported with Vulkan" describe what the release line ships and intends to prove. Each individual release proves it on the protected hardware for that platform, and a release whose accelerator host was unreachable ships with that platform's accelerator claim withheld rather than assumed: the accelerator ran on that host in earlier releases, but this release did not observe it.
You do not have to take the table's word for any single release. Every release
ships release-closeout-summary.json as a release asset, and its platform
section in the GitHub release notes is rendered from that release's ledger, so
a platform whose accelerator was withheld says so in the notes instead of being
listed as supported. In the summary, withheld_cells names every cell that did
not run, withheld_claims names the claims nothing in that release proved, and
partially_withheld_claims names the ones another host still proved. At most
one platform's accelerator may be withheld
(non_claim_policy.withhold_policy.maximum_withheld_hosts); a release that
proved no accelerator anywhere is refused rather than published. See
the testing matrix for how a claim
becomes withheld.
Use your project's symbols and paths:
Find ownership
Where is [Feature] defined, who calls it, and which files should I read first?
Plan a change
I am changing [path/to/file]. What symbols are affected and what tests should I run first?
Understand a subsystem
How does [subsystem] work? Cite concrete files and flag gaps if coverage is incomplete.
More shapes and host-specific invocation: User guides.
Surfaces, host differences, and platform support: User guides.
| If you want to... | Read |
|---|---|
| Install and use CodeStory | User guides |
| Know when to trust agent output | Trust and readiness |
| Repair a blocked session | Troubleshooting |
| Run CLI repair or debug | CLI reference |
| Change CodeStory itself | Contributor setup |
| Verify a claim or PR | Testing matrix |
Full routing: docs/README.md.
Scope: The language-expansion holdout compares agents on 18 pinned public OSS tasks with and without CodeStory. A result is published only when both arms finish every repeat, pass the answer-quality checks, and stay within the declared source-read budget. For day-to-day limits, see What to expect.
Broader public-repo evidence uses the language-support-ab manifest across 18 pinned OSS packages. We reran both arms from scratch against 0.17 on 2026-08-10. All 108 agent runs completed, but the result did not meet the publication bar: only 34 of 54 answers in each arm passed the manifest quality checks, and the CodeStory arm still needed ordinary source reads after its packet. The old 0.15 totals are therefore no longer presented as a current performance claim. See the language-expansion holdout evidence record for the exact run and rejection details.
A scoped rerun of four holdout tasks against 0.17, one repeat each, gpt-5.6-sol driven by
codex, CLI 552245c6. The no-CodeStory arm is reused unchanged from the pinned 2026-08-16
baseline, so both arms answer the same prompts on the same pinned checkouts.
| Task | Answer quality | Tokens | Wall time | Tool calls |
|---|---|---|---|---|
| Monolog record flow | passes in both arms | 191,759 → 31,053 (−84%) | 75s → 35s | 18 → 1 |
| Jekyll site build | passes in both arms | 257,094 → 35,763 (−86%) | 88s → 26s | 35 → 1 |
| AutoMapper map flow | passes without, fails with | 333,210 → 285,182 (−14%) | 118s → 80s | 28 → 3 |
| animate.css keyframes | passes without, fails with | 154,735 → 393,818 (+155%) | 54s → 84s | 13 → 5 |
Two of the four CodeStory answers did not pass the manifest quality checks, so this run does not meet the publication bar above and is not an answer-quality or performance claim for the release.
What it does show is the shape of the trade. On the two tasks whose packet proved the flow the
question asked about — disposition supported — the agent reached the same verified answer with
about 85% fewer tokens and a single tool call instead of 18 or 35. On the other two the packet
returned drill_once rather than a confident answer it could not support, and an agent that still
has to read the repository itself is worse off than one that started reading immediately. The
limit is visible in the packet rather than hidden in the answer, which is the behaviour the
grounding contract is built for; closing those two flows is ongoing work.
Apache-2.0. See LICENSE.