vh
53c3e8000e
Every agent on nh3-dev — Claude, Codex, Grok, Aider — needs the same answers: what runs here, how do I call it, what will bite me. Until now that lived in ~/.claude/CLAUDE.md, which only Claude sessions load, and it was interleaved with operator preferences that other families have no use for. Two-tier by design, matching the persistent-memory split: FLEETTOOLS.md is a 135-line index an agent reads whole, and each entry links to a detail file it opens only when it actually needs that tool. Reading the index costs about a fifth of reading the tree. Detail paths are absolute so they resolve from any working directory, since a non-Claude agent will cat the path rather than follow a markdown link. ~/FLEETTOOLS.md symlinks to the index for discovery. Rule zero is that live inventories get queried, not transcribed: Homepage /api/services, asset-engine /api/v1/services, LiteLLM /v1/models, and every FastAPI seat's /openapi.json. A copied service table would be stale within a month and this repo already has a standing rule against second copies that drift. Contents verified against the running fleet rather than copied from existing docs: binaries resolved on PATH, seven endpoints probed live, the LiteLLM roster counted at 40 models where the old note said ~30. No credentials are included; the vault and its CLI are pointed at instead.
1.7 KiB
graphify — repo knowledge graph
CLI: graphify (on PATH; uv tool install graphifyy) · MCP: graphify-mcp
graphify update <path> # build/refresh: writes graphify-out/{graph.json,GRAPH_REPORT.md}
graphify explain <symbol> # callers + neighbours
graphify query <...> # traversal over EXTRACTED call edges
graphify affected <symbol> # blast radius
graphify path <a> <b> # reach between two symbols
graphify update is the free, deterministic path: tree-sitter AST extraction plus
Leiden clustering, zero LLM, zero tokens, roughly 25 s for ~900 files. Highest-value
free output is the God Nodes list (core-abstraction surfacing).
The LLM layer is optional and points at any backend via ~/.graphify/providers.json —
pair community labeling (low-caliber) with the free LiteLLM summarizer endpoint.
Leave deep semantic extraction off unless you need it: its INFERRED/AMBIGUOUS edges
fight the explicit-over-implicit floor.
⚠ Graphify alone under-counts a blast radius — always cross-check with grep
Graphify is blind to function-local and DI-injected imports (from .x import y
inside a function body, store objects passed through constructors) — exactly the
pattern that hides cross-module callers. Graphify confirms call structure; grep catches
what its AST extraction misses; neither alone is sufficient (graphify-only
under-counts, grep-only misses transitive reach).
Run both before writing any contract that touches existing code. A contract that names 3 files when the rip touches 6 is a scope miss the up-front pass would have caught.
Complements a hand-authored docs/CODEBASE.md (curated geography); does not replace it.