kings graph queries a code dependency graph built by Graphify
(tree-sitter AST extraction — no API key, no network, zero LLM tokens). Mostly run by AI agents
instead of ad-hoc grep, so the output is compact and every query opens with a staleness banner.
| Tool | Install |
|---|---|
| Python 3 | System one — standard library only |
| Graphify | uv tool install graphifyy — the package has two y's, the binary is graphify |
# No uv yet
brew install uv
# Install, then put ~/.local/bin on the PATH (restart the shell after)
uv tool install graphifyy
uv tool update-shellDon't
pip installit on macOS — it breaks withModuleNotFoundError.graphfinds the binary on thePATH, then in~/.local/bin.
| Command | Answers |
|---|---|
kings graph info |
Graph state: which branch/commit it came from and how far behind the working tree it is |
kings graph find <pattern> |
Name → graph node(s), with id, flagging [protocol] |
kings graph deps <Type> |
Full dependency survey: stored and init-only dependencies, what the init builds, contract width, existing tests/mocks, methods, callers |
kings graph impact <Type> [depth] |
Blast radius of changing a type, grouped by module and depth (default 2) |
kings graph update [path] |
Regenerates the graph and stamps SOURCE.json with branch, commit and time |
Every command accepts --graph DIR. Exit codes: 0 success · 1 error.
| What | Resolved from |
|---|---|
| Graph folder | --graph DIR → $KINGS_GRAPH_DIR → <git root of the cwd>/graphify-out |
graph.json |
<graph folder>/graph.json, or <graph folder>/graphify-out/graph.json |
SOURCE.json |
Next to graph.json — read from one folder up when the graph is inside graphify-out/ and it's only there (older layout) |
Repo update reads |
[path], else the git root of the cwd — must be a git repo |
To keep the graph out of the repo, point KINGS_GRAPH_DIR (in config.env) at any other folder.
update runs graphify extract <repo> --code-only --no-cluster --out <folder> and moves the
graphify-out/cache/ that extract leaks into the repo next to the graph.
Note
A graphify without extract falls back to graphify update <repo>, which can only write to
<repo>/graphify-out — any other graph folder asks for uv tool upgrade graphifyy.
- Regenerating the graph is the user's call. A graph behind the working tree is the normal state, not a bug — every query prints the drift (commits ahead/behind, source files changed, uncommitted files) so nobody trusts a stale graph silently.
depsexists becausegraphify explain <Type>doesn't roll up method parameters — looking only at the type's node, a dependency injected through the init seems not to exist.depsis tuned for Swift (stored fields,implements→ protocol). On other languagesfind,impactandinfowork the same, butdepsmarks every init parameter as init-only.- The graph fails by silent omission and knows nothing about behavior — a starting point, never the
source of truth. Without
SOURCE.json, the banner uses graphify's ownbuilt_at_commit.
Snippet for a project's CLAUDE.md:
### Dependency graph — check before grepping
`kings graph deps | impact | find | info` queries a local dependency graph of this repo in ~1s,
at zero LLM cost. It names the function holding each reference and types the relationship
(`inherits` ≠ `calls` ≠ `references`). Starting point, never source of truth: read the staleness
banner and confirm behavior in the code. Never run `kings graph update` unless asked.