Best Practices for Using Graphify: Local Knowledge Graph Optimization

The best practices for using Graphify involve installing the CLI via uv or pipx, registering the skill with graphify install, maintaining a .graphifyignore file to exclude generated artifacts, committing the graphify-out/ directory to version control, and enabling automatic rebuilds through Git hooks to ensure your AI assistant always queries the most current graph structure.

Graphify transforms entire codebases—including documentation, PDFs, images, and videos—into a local knowledge graph that supports intelligent querying without relying on grep. According to the Graphify-Labs/graphify source code, implementing these best practices ensures reproducible builds, prevents accidental indexing of secrets, and maintains consistent graph-first interactions with your IDE assistant. The tool parses code using Tree-Sitter AST extraction (requiring no LLM or network traffic for code analysis) while attaching semantic information for non-code assets.

Installation and Skill Registration

Start with isolated installation to avoid dependency conflicts. The PyPI package is named graphifyy while the CLI command is graphify.

uv tool install graphifyy

# Alternative: pipx install graphifyy

After installation, register the skill to enable AI assistant integration. This writes the skill file to .agents/skills/graphify/SKILL.md (global) or ./.claude/skills/graphify/SKILL.md (project-scoped).

# Global registration (recommended for personal machines)

graphify install

# Project-scoped registration (for repository-specific setups)

graphify install --project

The skill file instructs your assistant to run graphify query before reading source files, establishing a graph-first workflow.

Building and Committing the Graph

Generate the knowledge graph artifacts by running the build command in your repository root. The first execution may take several seconds; subsequent runs are incremental.

graphify .

This creates the graphify-out/ directory containing three critical artifacts:

• graph.json – The serialized knowledge graph with god-node rankings and community detection
• GRAPH_REPORT.md – Human-readable summary of connections and suggested questions
• graph.html – Interactive visualization with edge confidence tags (EXTRACTED, INFERRED)

Commit the graphify-out/ directory to version control to ensure team consistency. However, exclude transient files that vary by environment:

# .gitignore additions

graphify-out/cost.json        # Local cost tracking only

graphify-out/cache/           # Optional: exclude large cache files

Automating Updates with Git Hooks

Prevent graph staleness by installing automatic rebuild triggers. The graphify hook install command configures post-commit and post-checkout hooks that regenerate the graph after code changes.

graphify hook install

These hooks include a specialized git merge driver that union-merges graph.json without conflicts, enabling smooth collaborative workflows. After installation, every git commit automatically triggers a graph rebuild, ensuring the knowledge graph remains synchronized with the codebase.

Configuring the Ignore List with .graphifyignore

Control indexing scope by creating a .graphifyignore file at your repository root. This file follows .gitignore syntax but operates with an important constraint: patterns are evaluated after .gitignore, meaning they can only exclude additional files—never re-include files already excluded by git.

# .graphifyignore example

node_modules/
dist/
*.generated.py

# Only index src/, ignore everything else

*
!src/
!src/**

Use the ! prefix to re-include specific paths within excluded directories when necessary. This configuration prevents Graphify from processing build artifacts, dependencies, and generated files that bloat the graph without adding semantic value.

Strict Mode and Advanced Configuration

For environments requiring guaranteed graph-first behavior, enable strict mode by setting the GRAPHIFY_HOOK_STRICT environment variable. This forces the assistant to query the graph before reading any source file.

export GRAPHIFY_HOOK_STRICT=1
graphify install  # Re-install to apply the strict configuration

Configure headless CI environments using these additional variables:

Variable	Purpose	Example
ANTHROPIC_API_KEY	Claude backend authentication	export ANTHROPIC_API_KEY=sk-...
GRAPHIFY_MAX_WORKERS	Parallel AST extraction threads	export GRAPHIFY_MAX_WORKERS=12

Serving the Graph for Team Access

Large teams can centralize graph access by serving the JSON file through an MCP (Model Context Protocol) server. This eliminates the need for each developer to maintain local builds.

python -m graphify.serve graphify-out/graph.json \
  --transport http --host 0.0.0.0 --port 8080 \
  --api-key "$GRAPHIFY_API_KEY"

Clients connect to http://<host>:8080/mcp and issue query_graph calls against the shared endpoint. This approach leverages the graphify.serve module as implemented in the Graphify-Labs/graphify repository.

Summary

• Install via uv or pipx using the package name graphifyy to maintain isolated environments
• Register the skill with graphify install (global) or graphify install --project (repository-scoped) to enable AI assistant integration
• Maintain .graphifyignore to exclude node_modules/, build artifacts, and generated files from indexing
• Commit graphify-out/ to version control while excluding cost.json and cache directories
• Enable automatic rebuilds via graphify hook install to keep the graph synchronized with code changes
• Use strict mode (GRAPHIFY_HOOK_STRICT=1) when requiring guaranteed graph-first queries
• Serve via MCP for team-wide access using python -m graphify.serve

Frequently Asked Questions

How does Graphify handle sensitive files and secrets?

Graphify respects your existing .gitignore patterns and supports additional exclusions via .graphifyignore. Since code parsing uses local Tree-Sitter AST extraction without LLM involvement, sensitive code never leaves your machine. The SECURITY.md file in the Graphify-Labs/graphify repository details the security model ensuring secrets remain local.

What is the difference between graphify install and graphify install --project?

The standard graphify install command registers the skill globally, writing to .agents/skills/graphify/SKILL.md in your home directory. The --project flag scopes the skill to the current repository only, creating ./.claude/skills/graphify/SKILL.md. Use global registration for personal development machines and project-scoped registration for repository-specific CI/CD pipelines or shared environments.

Why should I commit the graphify-out/ directory?

Committing graphify-out/ ensures all team members start from the same graph structure, eliminating build inconsistencies and reducing onboarding time. The directory contains graph.json (the serialized graph), GRAPH_REPORT.md (human-readable analysis), and graph.html (interactive visualization). Exclude only transient files like cost.json and cache subdirectories via .gitignore.

How do I force a complete graph rebuild after major refactoring?

Use the --force flag with the extract command to rebuild the graph from scratch, bypassing incremental updates. This is useful after large-scale refactoring that changes import structures or file organization:

graphify extract . --force

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}