User Guide

1. What problem this solves

AI coding assistants normally answer structural questions by searching files: spawn agents, glob, grep, read, repeat. That burns tokens and misses the architecture. simple_graphify builds the map once — deterministically, with no LLM — and every later question reads from the map. On mixed corpora the upstream Graphify project reports per-query savings up to 70x; a graph query here returns a few KB of targeted markdown regardless of repository size.

Use it when you ask questions like:

• "How is X wired to Y?" / "What depends on Z?"
• "What are the integration hubs of this codebase?"
• "Which classes have no contracts yet?"
• "What does the design doc say connects to this class?"

2. Installation

Requires the Simple Eiffel ecosystem (SIMPLE_EIFFEL environment variable) and EiffelStudio 25.02.

cd $SIMPLE_EIFFEL/simple_graphify
ec.sh release -config simple_graphify.ecf -target simple_graphify_app
# binary: bin/simple_graphify.exe

As a library dependency in your ECF:

<library name="simple_graphify" location="$SIMPLE_EIFFEL/simple_graphify/simple_graphify.ecf"/>

3. Building your first graph

simple_graphify build D:/prod/simple_http

This writes four artifacts to D:/prod/simple_http/graphify-out/:

4. Querying

query — scoped subgraph

simple_graphify query "how does the response cache work" --hops 1 --limit 30

Tokenizes the question, scores nodes (label match > label word > description > file path; class nodes score double), expands the neighborhood by --hops, and emits matched nodes, their connections, and the communities involved. Unmatched queries return the closest labels instead of failing.

explain — one node in full

simple_graphify explain SIMPLE_HTTP

Resolves by exact id (class:SIMPLE_HTTP), exact label, then unique substring. Shows description, file:line, degree, community, god-node rank, metrics (features, contracts, LOC), and every incoming and outgoing edge.

path — how two things relate

simple_graphify path SIMPLE_HTTP HTTP_COOKIE_JAR

Undirected shortest path with the edge kind and confidence at every hop.

stats — the shape of the graph

simple_graphify stats

5. Claude Code integration

simple_graphify install --project D:/prod/my_lib

Writes .claude/skills/graphify-eiffel/SKILL.md into the project with the absolute path of your simple_graphify.exe wired in. From the next session, Claude Code prefers graph queries over grep for structural questions, knows the command syntax, and knows to rebuild after large refactors.

The assistant as the semantic pass

Upstream Graphify sends documents to an LLM backend for semantic extraction. Here the assistant itself is that pass: when Claude infers a non-obvious connection (a design doc explaining why two subsystems are linked), it records the edge:

{"edges": [
  {"from": "class:HTTP_RETRY_POLICY", "to": "doc:docs/resilience.md",
   "kind": "references", "why": "retry strategy rationale"}
]}

simple_graphify annotate edges.json

Merged edges are forced to confidence inferred; endpoints must be existing node ids (unknown endpoints are rejected and reported). The graph is re-analyzed and rewritten in place.

6. Deep mode

simple_graphify build . --mode deep

Adds one node per feature (feature:CLASS.name) with argument counts, contract presence flags, and uses edges derived from signature and local types. Graphs get several times larger; use it for focused single-library analysis rather than ecosystem-wide maps.

7. Team workflow

• Commit graphify-out/ — the graph is deterministic, so diffs are meaningful and merges rarely conflict.
• Rebuild after structural changes (new classes, moved clusters, changed inheritance). A rebuild is full but fast — tens of seconds for thousands of files.
• Keep annotate insights flowing: they survive rebuilds only if re-applied, so store your edges.json files in the repo.

8. Error handling and limits

• Unparseable .e files fall back to a lightweight structural parser; files that still fail are skipped with a warning in the report — a build never aborts on one bad file.
• Duplicate class names across libraries (every library's TEST_APP): first registration wins, later ones warn. Supplier references resolve to the first.
• Short keyword-like class names (a class named FOR) will match uppercase tokens in comments ecosystem-wide and inflate that node's degree.
• Exit codes: 0 success; 1 usage error; 2 graph/file not found; 3 no Eiffel content; 4 annotate rejected all edges.