CIRCUIT

English | 繁體中文

Compiler-grade code structure, wired to the history that explains it — so every step your agent reasons stands on this graph as evidence.

Most tools that read a codebase stop at the file tree — what the code is, roughly — or the git log — what changed, in isolation. CIRCUIT builds both as a graph of a Java repo and joins them.

The code layer is compiler-grade: built from a SCIP index where scip-java drives your real build, so a CALLS edge is a call the compiler resolved — through overloads, generics, inheritance — not a name-match guess. Over it sit framework semantics (Spring stereotypes + DI, JAX-RS / Spring REST endpoints) and embeddings, so you search by concept, not string.

The history layer — commits, PRs, issues — is wired to the code by bridge edges: a commit modifies a file, an issue is resolved by a commit. History attaches only to code files that still exist — anchored to the live graph, not a parallel timeline. That join is the payoff. "Which issues drove the loan-repayment endpoint, and what did the fix touch?" is one walk — locate → HANDLES → MODIFIES → RESOLVED_BY — that no file tree or git log can make alone. Your agent reaches it over MCP: CIRCUIT supplies the cross-source join it can't cheaply rebuild.

How it fits together

The orange MODIFIES edge is the bridge — the one edge that crosses between the two layers, the join a flat file-and-git view doesn't have. Walk it backwards from a class and you get its provenance: the commits that touched its file, the PRs that merged them, and — on through RESOLVED_BY — the issues that asked for them.

Quickstart

The hands-on demo runs on Spring PetClinic — small, public, no API key.

# 1. Install — pulls circuit.jar, the launcher, and the PetClinic demo dump
curl -fsSL https://raw.githubusercontent.com/RiceTooCold/circuit/main/install.sh | bash

# 2. Start Neo4j and load the demo graph (open a new shell first, so circuit is on PATH)
circuit doctor              # checks Docker + Java 25
circuit up                  # starts Neo4j
circuit restore petclinic   # loads the PetClinic graph — no key needed

Then wire it into Claude Code and ask:

/plugin marketplace add RiceTooCold/circuit
/plugin install circuit@circuit

Ask in plain language — no file or symbol names needed:

A while back there was a bug where editing an owner's info made their pets disappear from the page, and pet updates wouldn't save. What was actually causing that, and what should I know about that part of the code before I touch it?

CIRCUIT walks the code↔history seam — find_precedent to reach the issues from the symptom, then traverse and inspect to follow them to the fixing commits and the code — and answers with the two root causes, the commits that fixed them, and file:line cautions, grounded in the graph and the source. Full transcript →

Go bigger. Point CIRCUIT at any Java repository that builds:

circuit ingest <your-repo-url>

(The first ingest builds the target to index it — see Known Limitations.)

What the agent gets

Five read-only tools over the graph (the MCP surface of circuit serve):

Tool	What it does
locate	Find the class or function you mean by concept and meaning, not just literal text. Returns an opaque id, a readable name, the kind, and the exact file + line range.
inspect	Zoom into one node by id — a scoped context card: what it is, and its immediate, named neighbors.
traverse	Walk a node's relationships across multiple hops — callers, dependencies, the commits that touched it.
find_precedent	Find the code that past tracked work on a concept touched — its precedent footprint across history.
status	Which graph is loaded — corpus, repository, modules, ingest commit SHA.

Search scope. Semantic (vector) search covers code symbols — classes and functions. Commits, PRs, and issues are reached through the graph and full-text search, not vectors.

Raw read-only Cypher stays a human escape hatch (via cypher-shell), deliberately off the agent surface (ADR-0040).

Evidence — a small A/B

A small A/B on a slice of Apache Fineract: the same tasks, answered by an agent with and without CIRCUIT. The clearest win is cross-source comprehension — the questions that need code and history together:

Per run	Without graph	With CIRCUIT	Δ
Comprehension score	0.843	0.900	+0.057
Tool calls	44.6	24.8	~−40%
Cost (USD)	$1.02	$0.63	~−40%

The other two task types map the boundary, honestly: on change-impact the graph wins modestly but both arms are near-ceiling (entity-F1 0.975 with the graph vs 0.946 native) at higher cost; on flat file-localization, plain grep already wins (file-F1 0.789 vs 0.731) — the graph's edge shows only at entity granularity (entity-F1 0.405 → 0.473). Across all three, the accuracy gaps are small; the real difference is cost, stability, and entity-level structure. CIRCUIT helps where structure beats search, not where search already suffices.

5 / 7 / 47 fixtures, run-noise-dominated (≈±0.08 per fixture). A directional illustration, not a benchmark — the full three-bench table and per-fixture detail are in docs/experiments/.

CIRCUIT is a demonstration project — built to show the approach, not under active maintenance.

Where to read next

• Known Limitations — scope edges + data egress (the only network call is embedding, and only if you pick the cloud option).
• Contributors — CONTRIBUTING.md for setup; then, by topic:
  • graph schema → docs/design/graph-capability-inventory.md
  • ingest pipeline → docs/design/spring-boot-etl-architecture.md
  • agent tools → docs/design/tool-layer-design.md
  • CLI & distribution → docs/design/distribution-and-cli.md
  • decisions → docs/adr/

---

CIRCUIT — Code Intelligence for Repository Context, Understanding, Impact, and Traceability · Apache-2.0