Cortex indexes a repository into a local semantic graph so agents can resolve ownership, inspect callers, trace dependencies, and estimate blast radius before they edit code.
Resolve who owns a symbol, where it is used, what calls it, and what sits in its immediate dependency neighborhood without walking raw grep output.
Cortex builds and queries a persistent graph on your machine. No hosted indexing service, background sync, or remote vendor dependency is required.
Use the CLI for one-off orientation or keep the daemon warm for editors, automations, and coding agents that need repeated graph lookups.
The repository ships a reproducible benchmark harness and published artifacts comparing Cortex against a raw text-search baseline on real open-source repositories.
Use the one-line installer for a release binary, or build from source if you want to work on the monorepo.
curl -fsSL https://raw.githubusercontent.com/Blu3Ph4ntom/cortex/main/scripts/install.sh | shirm https://raw.githubusercontent.com/Blu3Ph4ntom/cortex/main/scripts/install.ps1 | iexgit clone https://github.com/Blu3Ph4ntom/cortex.git
cd cortex
cargo install --path crates/cortex-cli
cargo install --path crates/cortex-daemonThe release installers place binaries in a common local path: ~/.local/bin on Unix and $HOME\.cortex\bin on Windows.
The PowerShell installer adds the default install directory to the current session PATH immediately and persists it for new shells. If you set CORTEX_INSTALL_DIR, it uses that directory but leaves your user PATH unchanged.
Build from source with the MSVC Rust toolchain if your GNU installation does not include gcc.exe and dlltool.exe.
The practical loop is simple: build the graph, resolve the owner, inspect callers, then check likely blast radius.
cortex index --repo /path/to/repocortex query --repo /path/to/repo find-symbol --name RepositorySessioncortex query --repo /path/to/repo callers --target open_sessioncortex query --repo /path/to/repo dependencies --target RepositorySession --direction both --depth 1
cortex query --repo /path/to/repo impact --target open_session --depth 1Cortex is strongest before edits, during refactors, and when review context needs real structure instead of filename heuristics.
Resolve the canonical owner of a symbol before an agent starts patching an unfamiliar codebase.
Inspect callers and dependencies before changing a signature or behavior that might ripple across the repository.
Attach structural neighbors and likely blast radius to a patch review so the summary is grounded in code relationships.
Keep a daemon warm for repeated lookups from editor tooling, local automations, and agent loops.
Repository orientation, targeted edits, change review, bounded impact checks, and machine-readable architecture discovery.
Compiler-grade proof, runtime data-flow certainty, or heavy framework indirection that only resolves through execution.
Cortex keeps the query model narrow so agents can learn it quickly and reuse it across repositories.
find-symbolResolve the canonical owner candidate for a symbol and get back a file path plus span.
callers / calleesWalk the call chain before you change behavior or when you are tracing outward from a function.
dependenciesInspect the local inbound and outbound structural neighborhood around a symbol or file.
references / impact / explainGet conservative reference sets, likely blast radius, and a summary of why a symbol matters in the current graph.
cortex query --repo /path/to/repo find-symbol --name PaymentServicecortex query --repo /path/to/repo callers --target update_statuscortex query --repo /path/to/repo explain --target PaymentServiceThe website renders the human-facing guide here. The repository root keeps the agent-facing `SKILL.md` that coding agents can install and use directly.
npx skills add https://github.com/Blu3Ph4ntom/cortex --skill cortexhttps://raw.githubusercontent.com/Blu3Ph4ntom/cortex/main/SKILL.mdUse the Cortex skill before editing this repository. Index the repo, resolve the owner of the target symbol, inspect callers or dependencies, then run impact before you patch code.SKILL.md teachesWhen to use Cortex, which queries to sequence first, how to quote structural results, and how to report uncertainty honestly when runtime behavior exceeds syntax.
Humans can review the workflow here on the website, while coding agents can consume the real source file directly from the repository.
Use the local daemon when another process needs repeated structural access without shelling out for each query.
cortexd --repo /path/to/repo --bind 127.0.0.1:8787curl "http://127.0.0.1:8787/graph/find_symbol?name=RepositorySession"curl "http://127.0.0.1:8787/graph/callers?target=open_session"The codebase is split so the core graph engine stays reusable while the CLI and daemon stay thin.
cortex-coreGraph model, parser extractors, indexer, storage layer, and typed query engine.
cortex-cliIndex, doctor, export, watch, and query commands for local use and scripting.
cortex-daemonLocal HTTP surface for tools that want a long-lived process instead of spawning the CLI for each lookup.
Repositories, files, symbols, and edges such as defines, contains, imports, references, calls, depends_on, and owned_by.
Cortex is intentionally conservative and syntax-driven. That makes it useful for navigation and pre-edit context, but not compiler-grade proof.
Contributor ergonomics, repeatable tests, and benchmark artifacts matter because Cortex is meant to support real engineering workflows.
cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets
powershell -ExecutionPolicy Bypass -File .\scripts\self-test.ps1Repository-specific contributor instructions for working on Cortex itself.
Agent-facing instructions for using Cortex on arbitrary codebases.
Reproducible benchmark artifacts and the PowerShell harness that generated them.
Cortex is already useful for local structural awareness and agent workflows. It is still OSS beta software, not yet a compiler-accurate or fleet-scale autonomous editing platform.
The benchmark harness in this repository compares Cortex warm-query results against `git grep -n -w` on the same structural tasks.
Cold indexing on a fresh local store, warm structural queries on a prepared store, and a raw grep baseline over the same repositories and targets.
Grep is often faster to start, but Cortex wins by collapsing the search surface into a much smaller set of structural answers that an agent can actually use.
9087 files, 63161 symbols, and 727716 indexed edges across the benchmark set.
34456 grep hits across 4379 files dropped to 18 structural answers.
Cold index median: 178.84 ms
Cold index median: 143.18 ms
Cold index median: 263.83 ms
Cold index median: 282.34 ms
Cold index median: 1209.77 ms
Cold index median: 7155.1 ms
Cold index median: 4355.44 ms
Cold index median: 1043.47 ms
Cold index median: 6894.25 ms
Cold index median: 2126.93 ms
Cold index median: 1327.34 ms
Cold index median: 540 ms
Cold index median: 222.5 ms
Cold index median: 263.3 ms
Cold index median: 1164.51 ms
Cold index median: 4203.7 ms
Cold index median: 732.59 ms
Cold index median: 372.47 ms
Cold index median: 1988.99 ms
Cold index median: 563.94 ms
Cold index median: 555.2 ms
Cold index median: 1007.6 ms
Cold index median: 342.35 ms
Cold index median: 914.59 ms
Cold index median: 3307.14 ms
Cold index median: 118.37 ms
| Scenario | Cortex median | Baseline median | Cortex results | Grep hits | Grep files | Reduction |
|---|---|---|---|---|---|---|
| Resolve RepositorySession owner Cortex / Rust | 102.03 ms | 17.86 ms | 2 | 51 | 15 | 25.5x |
| Trace open_session callers Cortex / Rust | 90.12 ms | 23.81 ms | 4 | 28 | 11 | 7x |
| Trace read_frame callers mini-redis / Rust | 85.32 ms | 17.71 ms | 2 | 7 | 4 | 3.5x |
| Resolve requests.Session owner requests / Python | 148.44 ms | 55.95 ms | 1 | 140 | 10 | 140x |
| Resolve chi.NewRouter owner chi / Go | 162.04 ms | 30.27 ms | 1 | 120 | 37 | 120x |
| Resolve axios.dispatchRequest owner axios / JavaScript | 564.23 ms | 33.28 ms | 1 | 5 | 3 | 5x |
| Resolve redux.createStore owner redux / TypeScript | 2882.81 ms | 47.69 ms | 1 | 333 | 55 | 333x |
| Resolve Retrofit owner retrofit / Java | 1499.76 ms | 72.55 ms | 1 | 1691 | 498 | 1691x |
| Resolve CoroutineScope owner kotlinx.coroutines / Kotlin | 76.6 ms | 80.08 ms | 0 | 645 | 194 | 0x |
| Resolve JsonConvert owner Newtonsoft.Json / C# | 2114.09 ms | 66.65 ms | 1 | 2061 | 211 | 2061x |
| Resolve curl_easy_init owner curl / C | 353.41 ms | 192.7 ms | 0 | 926 | 767 | 0x |
| Resolve fmt::format owner fmt / C++ | 97.12 ms | 24.14 ms | 0 | 2581 | 92 | 0x |
| Resolve ArgumentParser owner swift-argument-parser / Swift | 216.7 ms | 27.01 ms | 0 | 204 | 116 | 0x |
| Resolve AFHTTPSessionManager owner AFNetworking / Objective-C | 57.05 ms | 24.28 ms | 0 | 88 | 16 | 0x |
| Resolve Jekyll owner jekyll / Ruby | 67.95 ms | 53.06 ms | 0 | 2279 | 428 | 0x |
| Resolve Composer owner composer / PHP | 242.21 ms | 85.15 ms | 1 | 6428 | 625 | 6428x |
| Resolve Future owner twitter-util / Scala | 1385.72 ms | 82.77 ms | 1 | 2745 | 172 | 2745x |
| Resolve Phoenix.Endpoint owner phoenix / Elixir | 213.85 ms | 36.75 ms | 0 | 501 | 71 | 0x |
| Resolve cowboy_req owner cowboy / Erlang | 54.01 ms | 37.61 ms | 0 | 1370 | 160 | 0x |
| Resolve Client owner http / Dart | 290.86 ms | 48.62 ms | 1 | 250 | 60 | 250x |
| Resolve Rockspec owner luarocks / Lua | 195.73 ms | 46.61 ms | 0 | 152 | 52 | 0x |
| Resolve filter owner dplyr / R | 159.58 ms | 33.28 ms | 0 | 874 | 91 | 0x |
| Resolve DataFrame owner DataFrames.jl / Julia | 53.44 ms | 23.92 ms | 0 | 6804 | 77 | 0x |
| Resolve ToJSON owner aeson / Haskell | 53.55 ms | 72.95 ms | 0 | 391 | 38 | 0x |
| Resolve Base owner base / OCaml | 62.62 ms | 37.87 ms | 0 | 411 | 175 | 0x |
| Resolve clojure.core owner clojure / Clojure | 715.67 ms | 28.06 ms | 0 | 1526 | 107 | 0x |
| Resolve nvm owner nvm / Bash | 55.24 ms | 31.91 ms | 1 | 1845 | 294 | 1845x |
RepositorySession resolves to crates/cortex-core/src/indexer.rs:40.
open_session resolves to main, run_index, run_query, run_watch.
read_frame resolves to next_message, read_response.
Session resolves to src/requests/sessions.py:357.
NewRouter resolves to chi.go:60.
dispatchRequest resolves to lib/core/dispatchRequest.js:34.
createStore resolves to src/createStore.ts:96.
Retrofit resolves to retrofit/src/main/java/retrofit2/Retrofit.java:65.
CoroutineScope resolves to .
JsonConvert resolves to Src/Newtonsoft.Json/JsonConvert.cs:53.
curl_easy_init resolves to .
format resolves to .
ArgumentParser resolves to .
AFHTTPSessionManager resolves to .
Jekyll resolves to .
Composer resolves to src/Composer/Composer.php:27.
Future resolves to util-core/src/main/scala/com/twitter/util/Future.scala:1503.
Endpoint resolves to .
cowboy_req resolves to .
Client resolves to pkgs/http/lib/src/client.dart:36.
Rockspec resolves to .
filter resolves to .
DataFrame resolves to .
ToJSON resolves to .
Base resolves to .
defn resolves to .
nvm resolves to nvm.sh:3123.