graphify-kit

Drop-in setup for graphify knowledge graphs in any git repo. Self-contained — no dependency on a Teams repo, additionalDirectories, or symlinks.

What you get

1. Ignition — builds the graph once (graphify .) and installs graphify's native post-commit / post-checkout git hooks so it auto-updates on every commit/checkout. Pure AST — no LLM, no API key, no tokens.
2. Scoping — a .graphifyignore so vendored/minified bundles don't pollute the graph.
3. Nudge (Claude Code only) — a versioned PreToolUse hook reminding agents to graphify query before grepping raw source. Advisory, never blocks.

What's in the graph — scoped in / out by default

The kit builds a code-only graph. Three mechanisms decide what's in it:

Category	Examples	In / out	By what method
Your source code	*.py *.js *.ts *.go *.rs …	✅ in	AST extraction (graphify update .)
Dependency / build dirs	node_modules/ dist/ build/ venv/ site-packages/ .git/	❌ out	graphify's built-in _SKIP_DIRS
Minified / compiled bundles	*.min.js *.min.css *.map	❌ out	.graphifyignore (this kit)
Prose docs	*.md *.mdx *.qmd *.rst	❌ out	.graphifyignore (this kit) — headings otherwise leak in as low-signal nodes
Docs semantic content, images, papers	markdown prose, *.png, PDFs	❌ out	code-only build never calls the LLM extractor (needs an API key)
Vendored / generated asset dirs	nginx/static/assets/, public/build/ …	⚠️ repo-specific	commented templates in .graphifyignore — uncomment for your repo

The last row is the one you must tune: graphify can't know your repo's build-output paths, so hash- suffixed compiled bundles (e.g. index-a1b2c3.js, which aren't *.min.js) slip through until you add their directory. Symptom: a graph with tens of thousands of nodes dominated by unreadable minified symbols. Fix: add the dir to .graphifyignore and rebuild with GRAPHIFY_FORCE=1 graphify update ..

To include docs/images instead, see Docs & images.

---

1. Setup instructions

Step 1 — Install graphify (once per machine)

Ubuntu, recommended (isolated, on PATH via ~/.local/bin):

# uv (if you don't have it):
curl -LsSf https://astral.sh/uv/install.sh | sh
# graphify:
uv tool install graphifyy
graphify --version    # verify it's on PATH

(pipx install graphifyy or pip install --user graphifyy also work — anything that puts graphify on PATH.)

Step 2 — Get the kit (once per machine)

Clone the kit somewhere permanent — you do not copy it into each project, you point at it. Pick any location and remember the path; ~/projects/dev-tools/ is the convention here:

git clone https://github.com/ahelme/graphify-kit ~/projects/dev-tools/graphify-kit

Step 3 — Run the installer from inside your target repo

cd into the repo you want graphify in, then run the installer by its full path (the path from Step 2). The installer acts on your current directory, not on the kit:

cd /path/to/your/repo                          # the repo you want graphify in (must be a git repo)
~/projects/dev-tools/graphify-kit/install.sh   # ← full path to where you cloned the kit in Step 2

That's the whole setup. The installer does scoping, gitignore, the nudge hook, the initial build, and graphify hook install (ignition) for you. Order between the kit and graphify's own hook install doesn't matter — graphify's installer is marker-based and idempotent.

To update the kit later: cd ~/projects/dev-tools/graphify-kit && git pull, then re-run install.sh in any repo to pick up a newer nudge hook (it's version-checked — see the table below).

Our project (comfyume-v1 clones) — run order

A comfyume-v1 clone already ships .graphifyignore, the graphify-out/ gitignore line, and (via the Teams symlinks) the nudge hook. So here the kit's one real job is ignition — the auto-rebuild the Teams setup doesn't provide. Recommended order:

git clone …comfyume-v1 && cd comfyume-v1      # 1. clone, checkout your branch
#   … set up the Teams symlinks per CLAUDE.md  # 2. gives you settings + the nudge hook
~/projects/dev-tools/graphify-kit/install.sh   # 3. ignition; nudge step no-ops on the identical hook

Running it after the symlinks means the installer sees the identical Teams nudge hook and makes no change (rather than writing through the .claude/hooks symlink into the Teams repo). Because our tracked files already carry every ignore pattern, the installer makes zero edits to tracked files — so a later git checkout all-teams-testing is conflict-free, and its post-checkout hook rebuilds the graph for the new branch automatically.

Step 4 (Claude Code repos) — wire the nudge hook

The installer copies the script but never touches your settings file. Merge the hooks.PreToolUse block from settings.local.json into your repo's .claude/settings.local.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Read|Glob|Grep",
        "hooks": [
          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/graphify-nudge.sh" }
        ]
      }
    ]
  }
}

If you already have a settings.local.json, copy only the PreToolUse entry into your existing hooks object — don't overwrite the whole file.

The one catch: git hooks don't survive git clone

.git/hooks/ is local to each clone and is never copied by git clone. So every fresh clone of your target repo must run the installer (or at least graphify . && graphify hook install) once.

---

2. Files created / modified & behaviour

Target	Behaviour	Overwrite risk
.claude/settings*.json	Never touched — you merge the snippet manually	None
.graphifyignore	Appends only patterns you don't already have, inside a # >>> graphify-kit >>> block. Skips if the block is already present.	None — your existing rules are preserved
.gitignore	Appends graphify-out/ only if not already present	None
.claude/hooks/graphify-nudge.sh	Version-checked (graphify-kit-version: marker). Identical → skip. Older → upgrade + .bak. Same-but-edited / no-marker → .bak then replace. Newer → left untouched, prints force command.	Backed up before any replace
.git/hooks/post-commit, post-checkout	Written by graphify hook install — marker-based, appends between # graphify-hook-start/end, never clobbers. Re-runs are no-ops. Remove with graphify hook uninstall.	None (graphify-managed)

On the git hooks — why the kit does NOT ship its own

Graphify's hooks are ~200 lines of graphify-maintained, cross-platform machinery (interpreter pinning for uv/pipx/venv, Windows-vs-POSIX detached launch, flock, timeouts, reflection). Because graphify hook install appends between markers and is idempotent, there is nothing to clobber and nothing to "revert" — installing the kit and graphify's hooks in any order, any number of times, is safe. Shipping our own forked copies would only add drift risk with zero benefit, so we don't. To remove graphify's hooks cleanly: graphify hook uninstall.

---

Docs & images — code-only by default (no API key)

The installer builds with graphify update ., which extracts code only via AST — no LLM, no API key, no tokens. This is deliberate and matches the auto-rebuild hooks (which are also code-only), so the graph stays consistent and free to maintain.

Docs, markdown, and images are out of scope by default. Bare graphify . would try semantic extraction on them and fail with no LLM API key found — which is why the installer never calls it.

Want docs/images in the graph? That's a separate, key-requiring step you run manually:

export GEMINI_API_KEY=…   # or GOOGLE_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY / …
graphify .                # full semantic build (code + docs + images)

Note the git hooks will still only rebuild the code side on commit/checkout, so re-run the semantic build by hand when docs change.

Off-switches (the nudge is deliberate-bypass-able)

• GRAPHIFY_NUDGE_OFF=1 (env) — off for the whole session.
• touch graphify-out/.nudge_off — off for this repo until the file is removed.

The nudge also auto-carves-out: piped commands, out-of-repo paths, and non-code files never fire.

Non-Claude repos

Everything except the nudge still works — you get a full, auto-updating graph. The nudge just needs a Claude Code settings.local.json; skip Step 4 if the repo isn't used with Claude Code.

Agent prompting note (replaces our Teams skills wiring)

The nudge reminds agents in-session, but for best results also tell agents directly:

Orient with graphify first. If graphify-out/graph.json exists, run graphify query "<question>" (or explain / path) before grepping — it's more thorough than grep, which only finds the exact string and misses related functions and config. Rebuild stale with graphify update .. When you dispatch subagents to explore code, include this instruction in their prompt too.

License

MIT © 2026 Anna Helme — see LICENSE.

Files in this kit

graphify-kit/
├── install.sh                     # run this from your repo root
├── .graphifyignore                # scoping template (marker-blocked for safe append)
├── settings.local.json            # Claude Code hook snippet to merge
├── README.md
└── .claude/hooks/graphify-nudge.sh   # versioned nudge hook