coseto6125/egent-code-plexus

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 · Русский · हिन्दी
All install options · Uninstall
---
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 | — |