Skip to content

AI

This section covers the AI tooling shared across the ITsynch Suite monorepo.

Codebase knowledge graph (Graphify)

Graphify turns the repository into a queryable knowledge graph — god nodes (architectural hubs), community structure, and cross-file relationships — so your AI coding assistant (and you) can ask "what connects X to Y?" instead of blindly grepping thousands of files.

The tooling is committed to the repo and shared company-wide: the Claude Code skill, the CLAUDE.md instructions, the git hooks recipe, and the .graphifyignore scope. The graph itself is built locally — it is not committed.

Important

A whole-suite graph is 200 MB+ and would be regenerated on every commit, so committing it would balloon the repository. Instead, each developer builds the graph locally once (fast, AST-only, free) and a git hook keeps it current. graphify-out/ is git-ignored on purpose.

What "shared" means here

Committed to the repo (shared) Built locally (per developer)
.claude/skills/graphify/ — the assistant skill graphify-out/graph.json — the graph
CLAUDE.md — assistant instructions to query the graph graphify-out/GRAPH_REPORT.md — architecture report
.claude/settings.json — pre-tool hooks graphify-out/manifest.json, cache
.graphifyignore — what the graph indexes

One-time setup

Pin the version

Everyone must stay on 0.9.22. Do not upgrade without team sign-off — a mismatched version can change graph output. Any bump needs a human decision.

  1. Install the pinned CLI once (isolated environment, not global pip):

    Bash
    1
2
    uv tool install "graphifyy==0.9.22"
graphify --version    # must print 0.9.22

    If graphify is not found afterwards, run uv tool update-shell (or pipx ensurepath) and reopen your shell.

  2. Build your local graph — code-only, fully local, no API key, nothing leaves your machine. Both commands are required: extract writes graph.json, cluster-only adds the community structure and generates GRAPH_REPORT.md. Running only extract leaves you with a graph that has no communities, which is easy to miss:

    Bash
    1
2
    graphify extract . --code-only              # local AST only, ~1-2 min
graphify cluster-only . --no-viz --no-label # GRAPH_REPORT.md + communities

  3. Verify the graph actually exists:

    Bash
    1
    ls graphify-out/graph.json                  # must exist and be non-trivial

    This setup fails silently

    If graphify-out/graph.json is missing, the PreToolUse guard never fires, the assistant quietly falls back to grep, and everything looks completely normal. Check the file, don't assume the SessionStart hook ran successfully.

  4. Git hooks (post-commit / post-checkout) auto-refresh the graph. On macOS and Linux the SessionStart hook installs them for you on your first Claude Code session — nothing to do. On Windows, leave them off (see Windows below). To install them by hand, or to re-install after a Graphify upgrade:

    Bash
    1
2
    graphify hook install
graphify hook status                        # check current state

Daily use

Your assistant reads graphify-out/graph.json automatically. From the CLI you can query it directly:

Bash
1
2
3
4
graphify query "what connects authentication to the database?"
graphify path "OrderService" "AuditTrail"     # shortest path between two nodes
graphify explain "RateLimiter"                # a node and its neighbors
graphify god-nodes                            # most connected architectural hubs

After changing code, refresh the graph (the commit hook does this for you where it is installed, but you can run it manually too — and on Windows you should):

Bash
1
graphify update .                             # re-extract changed files, AST-only

Windows: keep the git hooks off

graphify hook install adds post-commit / post-checkout hooks that rebuild the graph automatically. On Windows, don't.

Those hooks shell out to a console-subsystem python.exe, up to four times per run. When git is driven from a GUI client (VS Code, Visual Studio, Fork) there is no console to inherit, so Windows allocates a fresh one per spawn and Windows Terminal surfaces each as a blank popup window — every commit, every branch switch. post-checkout also does a full rebuild rather than an incremental one, so on a repo this size you burn a minute-plus of CPU per branch switch.

The SessionStart hook already defaults to not installing them on Windows. To make that explicit, or to clean up hooks a previous setup left behind:

Bash
1
2
3
git config graphify.autohooks false    # opt out; SessionStart won't reinstall
graphify hook uninstall                # remove hooks already installed
graphify hook status                   # check current state

Then refresh manually after a batch of changes: graphify update .

The graphify.autohooks gate matters beyond Windows: it is per-clone and sticky, so a deliberate graphify hook uninstall is not silently undone the next time you open Claude Code. If you would rather keep the hooks installed but temporarily quiet, set GRAPHIFY_SKIP_HOOK=1 in your environment — it short-circuits both hooks.

Troubleshooting

Symptom Cause Fix
Assistant keeps grepping, never mentions the graph graph.json missing, so the PreToolUse guard never fires Run both build commands from One-time setup step 2
graphify: command not found in the hook, but works in your shell Claude Code was started before the PATH change uv tool update-shell, then restart Claude Code — not just the terminal. Claude Code inherits PATH from the process that launched it
Blank console windows on commit / branch switch (Windows) Git hooks spawning console-subsystem python.exe git config graphify.autohooks false + graphify hook uninstall
Uninstalled the git hooks and they came back An older SessionStart hook reinstalled them Set graphify.autohooks false — the config gate is what makes it stick
Graph exists but queries feel shallow, no communities Only extract ran, cluster-only did not Re-run both commands
Graph answers are confidently wrong Stale graph graphify update .
Background index never finished The detached child did not outlive the session hook Check .git/graphify-index.log, then run the build manually. Delete the log to let the hook retry

Scope of the graph

The graph indexes hand-written source only. Tests, EF Core migrations, generated code, native mobile shells, and data files are excluded via .graphifyignore (and .gitignore is also honored). Edit .graphifyignore if you need to widen or narrow what gets indexed for your local graph.

Semantic (docs / PDFs / media) extraction

This rollout is code-only — no model backend is configured and no data leaves your machine. Enabling the optional semantic pass over docs and media (via ANTHROPIC_API_KEY, AWS Bedrock, or Azure OpenAI) has cost and data-egress implications and is a deliberate org decision, not a per-developer toggle. Do not enable it unilaterally.