<div align="center">

ecp · EgentCodePlexus

The structural code graph built for AI agents, not humans.

22k files indexed in 2.6 s · any query answered in <175 ms · honest unknowns, never hallucinated edges.

English · 繁體中文 · 简体中文 · 日本語 · 한국어 · Español · Português · Русский · हिन्दी

# Linux / macOS
curl -sSfL https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.sh | sh

All install options · Uninstall

</div>

---

Autonomous coding agents fire 20–50 structural queries per task. Those queries all hit tools built for humans: IDE sidebars, daemons that need warming, output formatted for reading. The mismatch shows up in three concrete failure modes:

1. Token waste — a grep dump returns 400 lines where the agent needed 10 symbols
2. Broken refactors — a missed caller slips through because the resolver guessed and got it wrong
3. Hallucinated dependencies — when static analysis can't reach an edge, the tool invents one

ecp was built to eliminate all three.

| Failure mode | ecp's answer | |---|---| | Context window blown on raw search output | TOON / compact JSON — symbols, lines, and edges only; no padding | | Missed caller, silent downstream breakage | impact — exact blast radius over real call and extend edges | | Fabricated dependency in the agent's reasoning | BlindSpot records — typed honest unknowns the agent can route around | | Graph goes dark outside the primary language | 31 languages — service code, IaC, SQL, smart contracts in one traversal |

---

🎯 Design principles

Each design decision has one source: what does the receiving agent actually need?

Output is a data structure. TOON and compact JSON carry only what the agent needs for its next decision. No prose summaries. No visual chrome. No section headers consuming the context budget. The format defaults are already the right choice for most LLM prompts.

Stateless. Zero warm-up. Each invocation mmaps a zero-copy rkyv graph file and exits. ~140–170 ms per query, startup included. No daemon to keep alive. No warm-up phase. No "server crashed, please restart" recovery path. An agent can fire 50 queries per task without paying a process boot cost.

BlindSpot over hallucination. When ecp can't statically resolve a call site — dynamic dispatch, reflection, an unresolved import — it emits a BlindSpot record: a named, typed, explicit gap in the graph. Agents can navigate around a known unknown. They cannot recover from a confident fabrication.

Polyglot by default. 31 languages at structural depth. Service code, Dockerfiles, GitHub Actions, Terraform, SQL, Move, Solidity — one traversal covers all layers. No language switch means no graph blind spot.

🎙️ Agent Interviews — Gemini CLI and Codex describe how they use ecp in live autonomous task flows.

Inspired by GitNexus by Abhigyan Patwari — same structural-graph concept, independently reimplemented in Rust for a different audience. Licensed MIT; see NOTICES.md for third-party attributions.

---

⚡ Performance receipts

Head-to-head against two other code-graph tools — codegraph (Node + SQLite) and upstream gitnexus (Node) — on the same checkouts, same machine. ecp is a stateless one-shot CLI: every latency below includes full process startup, no daemon, no warm-up.

Versions: ecp 0.4.2 · codegraph 0.9.4 · gitnexus 1.6.5. All tools capped at a 1 MiB max-file-size threshold where configurable (gitnexus hard-codes 512 KB). ecp medians over 5–7 runs. Hardware: AMD Ryzen 9 9950X (16 logical), Linux.

microsoft/vscode — 14,874 files, dense single-language TypeScript

| Metric | ecp | codegraph | gitnexus | |---|---|---|---| | Cold index | 4.6 s | 166.9 s | DNF — killed at 27 min | | Peak RSS | ~1.0 GiB | 1.7 GiB | 4.6 GiB (still climbing) | | Symbol find / query | 34.6 ms | 169.5 ms | — | | Callers / impact | 27.2 ms | 172.4 ms | — | | Inspect / context | 35.0 ms | 415.9 ms | — | | Impact baseline (git-diff) | 725.9 ms | N/A — no such mode | — | | Graph nodes | 507,257 | 315,498 | — | | Graph edges | 916,380 | 986,709 | — | | Index size on disk | 87 MiB | 671 MiB | — | | Files indexed | 14,874 | 10,814 | — |

gitnexus did not finish — killed after 27 min stuck in its in-memory graph-resolution phase (RSS 4.6 GiB, no output written).

abhigyanpatwari/GitNexus — 3,232 files, polyglot (the corpus all three can finish)

| Metric | ecp | codegraph | gitnexus | |---|---|---|---| | Cold index | 0.74 s | 11.2 s | 77.6 s | | Peak RSS | 264 MiB | 501 MiB | 2.5 GiB | | Find / query | 9.4 ms | 103.5 ms | — | | Callers / impact | 9.2 ms | 104.2 ms | 297.6 ms | | Inspect / context | 9.4 ms | — | 295.5 ms | | Graph nodes | 49,122 | 19,604 | 30,223 | | Graph edges | 48,271 | 39,155 | 47,218 | | Index size on disk | 7.7 MiB | 37 MiB | 306 MiB | | Files indexed | 3,232 | 2,968 | 3,232 |

Cold index: 15–37× faster than codegraph; gitnexus doesn't finish on a real large repo. Lowest memory, smallest on-disk index, densest graph — at every scale.

Scale: .sample_repo — 22,645 files, 25 languages, 2.1 GB polyglot corpus

Ingest:

| Metric | Value | |---|---| | Files indexed | 22,645 across 25 detected languages | | Cold ingest | 2.60 s (parse + resolve + serialize) | | Incremental ingest | 4.9 ms (xxh3_64 hash walk, zero dirty files) | | Hardware | AMD Ryzen 9 9950X (16 logical), 39.2 GiB RAM, Linux 6.6.87 |

Per-query latency, process startup included:

| Query | Median | What it covers | |---|---|---| | summary | 1.4 ms | registry mmap — smallest read | | routes | 142.3 ms | declarative + imperative route enumeration | | summary --detailed | 143.4 ms | full registry + per-framework confidence scoring | | impact --direction down | 145.0 ms | BFS over Calls / Extends edges | | inspect | 145.6 ms | symbol resolution + 1-hop traversal | | find --mode bm25 | 154.5 ms | Tantivy query + 5-bucket partition | | cypher (narrow) | 161.5 ms | one pattern, one row | | cypher (broad) | 174.2 ms | wider pattern, more matches | | impact --baseline HEAD~1 | 359.0 ms | git diff + parallel per-file parse + BFS |

Reproduce everything: python scripts/benchmark/benchmark_ecp.py.

Rust-tier competitor comparison

scripts/benchmark/benchmark_vs_competitors.py benchmarks against codescope (SurrealDB-backed) and coraline (SQLite-backed) across 6 phases: cold-index, symbol-find, callers, file-context, route-map, cypher. Missing phases → N/A (absence is signal). Results regenerate docs/benchmark-vs-competitors.md.

python scripts/benchmark/benchmark_vs_competitors.py
python scripts/benchmark/benchmark_vs_competitors.py --corpus path/to/repo --iterations 5 --no-plot

---

🆚 vs. upstream GitNexus

Same structural-graph concept, different audience. Not a drop-in replacement — choose based on who reads the output and what they do with it.

| Dimension | EgentCodePlexus | GitNexus | |---|---|---| | Primary consumer | Autonomous AI code agents | Human devs + IDE integration | | Runtime | Stateless one-shot CLI (zero warm-up) | Long-running MCP server | | Performance | < 2.5s cold index / < 175ms query | ~60s cold index / ~400ms query | | Unresolved edge | BlindSpot record (honest unknown) | Heuristic guess | | Default output | TOON / compact JSON (token-cheap) | Wiki / UI rendering | | Languages | 31 (14 deep + 17 structural) | 14 (deep, 9-dimension) | | Storage | Rust + rkyv zero-copy mmap | Node.js + LadybugDB |

Full breakdown, philosophy, and decision matrix → docs/vs-gitnexus.md

---

📦 Install

Prebuilt binaries ship with each GitHub Release. Installer scripts fall back to a cargo source build only when a matching asset is unavailable.

# Linux / macOS
curl -sSfL https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.sh | sh

# Windows PowerShell
iwr https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.ps1 -UseBasicParsing | iex

# Direct cargo (no installer wrapper)
cargo install --git https://github.com/coseto6125/egent-code-plexus egent-code-plexus --bin ecp --locked

Prefer a package manager? The npm and PyPI packages ship the same prebuilt binary (no compile, no toolchain) and pick the right platform automatically:

# npm — run without installing, or install globally
npx egent-code-plexus --help
npm install -g egent-code-plexus

# PyPI — via uv or pipx
uvx egent-code-plexus --help
uv tool install egent-code-plexus     # or: pipx install egent-code-plexus

# cargo-binstall (prebuilt, no source build)
cargo binstall egent-code-plexus

Update

ecp update           # replace the installed binary with the latest release
ecp update --check   # only report whether a newer release exists

ecp update works for every install channel above. Upgrading through npm, uv, pip, brew or cargo still works until 0.15, when ecp update becomes the only upgrade path.

CPU-tuned source build:

repo=https://github.com/coseto6125/egent-code-plexus
RUSTFLAGS="-C target-cpu=native" cargo install --git "$repo" egent-code-plexus --bin ecp --locked --profile release-dist

Uninstall

ecp uninstall            # remove agent integrations + ~/.ecp cache + the binary
ecp uninstall --dry-run  # preview what would be removed, change nothing

One command reverses every setup side-effect: Claude Code / Codex / Gemini hooks, MCP servers, and skills; the per-repo git hook; the ~/.ecp index cache; and the ecp binary itself. On Windows the binary is deleted by a short delayed step after the process exits (a running .exe can't delete itself in place).

Scope it to one agent with --agent claude (leaves the binary and cache in place), or keep the index cache across a reinstall with --keep-cache. If you installed via a package manager, use its own remover instead:

npm uninstall -g egent-code-plexus
uv tool uninstall egent-code-plexus   # or: pipx uninstall egent-code-plexus
cargo uninstall egent-code-plexus

---

🚀 Quick start

No daemon to start. No config required. One command from zero to a queryable graph.

# Index (incremental; first query also auto-indexes if index is absent)
ecp admin index --repo .

# Find a symbol — exact by default
ecp find loginUser
ecp find login --mode bm25            # BM25 ranking, partitioned into 5 output buckets

# Blast radius — who breaks if I change this?
ecp impact valida