CodeSextant

AI coding agents can generate code faster than they can understand a repository. They search for names, reread files, miss call sites, and break B while fixing A. The bottleneck is not model intelligence alone. It is the missing index.

CodeSextant is a local, shared code index for coding agents. It builds an import-aware symbol graph and answers the questions an agent needs before editing: who calls this symbol, what depends on it, and which few files are actually worth reading?

Python and TypeScript/JavaScript get resolved references. Other supported languages are clearly labelled when results come from low-confidence name matching. Index once, then every agent on the machine reuses the same map. No cloud, no API keys, and no source code leaves your machine.

The name is from the sextant: an instrument for fixing your position when there is no landmark in sight.

Visual map prototype

This working prototype renders 598 real symbols from CodeSextant itself. Its shape is not decorative: reference edges determine structural communities, cohesive communities form tighter and more separated clusters, and tangled coupling produces overlap and visual noise. The interaction supports rotation, semantic zoom, and flying from an overview into a symbol.

The visual renderer is not wired into the published Python package yet. Layout normalization, cross-machine reproducibility, and module-level aggregation for very large repositories remain open work. The current map command returns a ranked text map, not this renderer.

The problem

The hidden cost of agentic coding is token budget. An agent that starts editing without a global picture rewrites things that already exist, misses call sites, and creates conflicts.

The usual fallback is grep. But name matching treats every identically-named symbol as the same thing, so in a codebase with common names like handle, run, or Config, the results are mostly noise. We have measured cases where every returned "reference" was wrong.

CodeSextant resolves imports instead of matching text, and it keeps the resulting graph in a single resident service that every agent on the machine queries.

What makes it different

Quick start

Requires Python 3.10 or newer.

pip install codesextant

watchdog is installed with CodeSextant. The first index scans the repository once. After that, the daemon listens for native OS file events and sends only created, edited, moved, or deleted paths to the indexer after a short debounce. A normal save does not walk the repository. A full reconciliation is reserved for initial indexing, daemon restart recovery, lost watcher state, or an explicit forced rebuild.

Give CodeSextant to your agent

Download the single CodeSextant SKILL.md after installation and place it in your agent's skill directory. For example:

.agents/skills/codesextant/SKILL.md    # Codex and compatible agents
.claude/skills/codesextant/SKILL.md   # Claude Code

Keep the entry filename as SKILL.md. The containing codesextant directory is the skill name under the Agent Skills specification.

If an agent does not support skill directories, attach that one Markdown file and ask the agent to follow it before editing. The skill starts the shared daemon, binds the current repository, uses the map to narrow what should be read, checks references and impact before changes, and preserves confidence labels instead of treating name matches as confirmed callers.

High-confidence TS/JS resolution needs two more things: Node on your PATH, and a one-time npm install inside ts_bridge/. That directory ships in the git repository, not in the pip package. So a pip install gives you resolved references for Python and name-matched ones for TS/JS; clone the repository instead if you need TS/JS resolved. Either way the result carries its confidence label, and a missing bridge degrades the answer rather than breaking the tool.

python -m codesextant index      <repo>                     # build or incrementally update the index
python -m codesextant map        <repo> [--budget N]        # most important symbols, within a token budget
python -m codesextant references <repo> <symbol> [--src-root R] [--def-path D]
python -m codesextant symbols    <repo> [--file F]
python -m codesextant status     <repo>
# any command takes --json for machine-readable output

Running it as a resident service:

python -m codesextant.daemon ensure   # idempotent: starts one only if none is running
python -m codesextant.daemon ping     # strict liveness check (verifies /health brand, not just the port)
python -m codesextant.daemon stop
# then open http://127.0.0.1:8790/ for a self-contained dashboard (inline CSS/JS, no CDN, works offline)

HTTP endpoints, all taking project=<absolute repo path>: GET /health /get_symbols /get_map /status (?fresh=1 to compare against git HEAD) /projects; POST /find_references /reindex.

On Windows, tools/register_windows_startup.ps1 registers the daemon to start on login (run it as administrator to get boot-time start as well). It is idempotent, so re-running it is safe. A supervisor task probes liveness every 5 seconds and restarts the daemon if it exits.

Architecture

┌── CodeSextant daemon (Python, port 8790, single instance, shared by all agents) ──┐
│   tree-sitter symbol extraction + jedi / ts-morph import resolution               │
│   incremental SQLite (content hash + git HEAD freshness) + weighted PageRank      │
│   per-project isolation: sha1(repo path) -> ~/.codesextant/<key>.db               │
│   HTTP API, plus a self-contained dashboard on GET /                              │
└───────────────────────────────────────────────────────────────────────────────────┘
        ▲ one daemon, many front-ends: standalone shell, IDE webview, agent HTTP clients

Single-instance startup is what makes "every agent shares one map" work at all. Without it, each agent would build and hold its own copy of the graph.

Large cold map queries are served from a SQLite covering index plus a revision-checked JSON snapshot, with a small in-process LRU on top. Every snapshot is a cache keyed on index revision and query parameters; SQLite remains the only source of truth, and any change invalidates them.

Configuration

All settings are environment variables. Boolean flags accept 1/true/yes/on case-insensitively.

A few lower-level language-inference knobs (CODESEXTANT_INFER_LANG_*) are documented in the source.

Testing

python -m pytest tests/ -q

443 tests, about a minute on a developer laptop. They cover the daemon lifecycle, incremental indexing, map scalability, snapshot invalidation, and reference resolution across the supported languages.

Known limitations

We would rather state these than have you discover them.

• Reference lookup needs the right --src-root when the import root lives in a subdirectory (.../src). Get it wrong and high-confidence references are silently missed.
• When several symbols share a name, omitting --def-path means the first candidate definition wins, and high-confidence results may legitimately come back as zero. All candidates are listed so you can disambiguate.
• PageRank quality depends on how dense the reference edges are, and those accumulate as find_references is called. A freshly indexed repo produces a rougher map than one that has been queried for a while.
• High-confidence TS/JS resolution requires npm install in ts_bridge/, which only the git repository carries. A pip install therefore gets name-matched TS/JS references, and the confidence label says so rather than hiding it.
• Go and Rust get tree-sitter symbols but name-matched references. This is a real accuracy ceiling, not a temporary gap.
• Index freshness is content-hash incremental plus a git HEAD comparison; status?fresh=1 tells you whether the index has fallen behind.

Repository layout

Licence

MIT. See LICENSE.

The core is free and open source. A commercial edition is planned around what open source deliberately does not cover: a shared central map for teams and multi-agent fleets, access control with audit logs, private deployment, and supported integrations.