graphify

/graphify

Turn any folder of files into a navigable knowledge graph with community detection, an honest audit trail, and three outputs: interactive HTML, GraphRAG-ready JSON, and a plain-language GRAPH_REPORT.md.

Usage

/graphify                                             # full pipeline on current directory
/graphify <path>                                      # full pipeline on specific path
/graphify <path> --mode deep                          # thorough extraction, richer INFERRED edges
/graphify <path> --update                             # incremental - re-extract only new/changed files
/graphify <path> --directed                           # build directed graph (preserves edge direction)
/graphify <path> --whisper-model medium               # use a larger Whisper model for transcription
/graphify <path> --cluster-only                       # rerun clustering on existing graph
/graphify <path> --no-viz                             # skip visualization, just report + JSON
/graphify <path> --html                               # (HTML is generated by default - no-op)
/graphify <path> --svg                                # also export graph.svg
/graphify <path> --graphml                            # export graph.graphml (Gephi, yEd)
/graphify <path> --neo4j                              # generate graphify-out/cypher.txt for Neo4j
/graphify <path> --neo4j-push bolt://localhost:7687   # push directly to Neo4j
/graphify <path> --mcp                                # start MCP stdio server for agent access
/graphify <path> --watch                              # watch folder, auto-rebuild on code changes
/graphify <path> --wiki                               # build agent-crawlable wiki
/graphify <path> --obsidian --obsidian-dir ~/vaults/my-project  # write Obsidian vault
/graphify add <url>                                   # fetch URL, save to ./raw, update graph
/graphify add <url> --author "Name"                   # tag who wrote it
/graphify add <url> --contributor "Name"              # tag who added it
/graphify query "<question>"                          # BFS traversal - broad context
/graphify query "<question>" --dfs                    # DFS - trace a specific path
/graphify query "<question>" --budget 1500            # cap answer at N tokens
/graphify path "AuthModule" "Database"                # shortest path between two concepts
/graphify explain "SwinTransformer"                   # plain-language explanation of a node

What graphify is for

graphify is built around Andrej Karpathy's /raw folder workflow: drop anything into a folder - papers, tweets, screenshots, code, notes - and get a structured knowledge graph that shows you what you didn't know was connected.

Three things it does that Claude alone cannot:

1. Persistent graph - relationships are stored in graphify-out/graph.json and survive across sessions. Ask questions weeks later without re-reading everything.
2. Honest audit trail - every edge is tagged EXTRACTED, INFERRED, or AMBIGUOUS. You know what was found vs invented.
3. Cross-document surprise - community detection finds connections between concepts in different files that you would never think to ask about directly.

Use it for:

• A codebase you're new to (understand architecture before touching anything)
• A reading list (papers + tweets + notes - one navigable graph)
• A research corpus (citation graph + concept graph in one)
• Your personal /raw folder (drop everything in, let it grow, query it)

What You Must Do When Invoked

If no path was given, use . (current directory). Do not ask the user for a path.

Follow these steps in order. Do not skip steps.

Step 1 - Ensure graphify is installed

# Detect the correct Python interpreter (handles uv tool, pipx, venv, system installs)
PYTHON=""
GRAPHIFY_BIN=$(which graphify 2>/dev/null)
# 1. uv tool installs
if [ -z "$PYTHON" ] && command -v uv >/dev/null 2>&1; then
    _UV_PY=$(uv tool run graphifyy python -c "import sys; print(sys.executable)" 2>/dev/null)
    if [ -n "$_UV_PY" ]; then PYTHON="$_UV_PY"; fi
fi
# 2. Read shebang from graphify binary (pipx and direct pip installs)
if [ -z "$PYTHON" ] && [ -n "$GRAPHIFY_BIN" ]; then
    _SHEBANG=$(head -1 "$GRAPHIFY_BIN" | tr -d '#!')
    case "$_SHEBANG" in
        *[!a-zA-Z0-9/_.-]*) ;;
        *) "$_SHEBANG" -c "import graphify" 2>/dev/null && PYTHON="$_SHEBANG" ;;
    esac
fi
# 3. Fall back to python3
if [ -z "$PYTHON" ]; then PYTHON="python3"; fi
"$PYTHON" -c "import graphify" 2>/dev/null || "$PYTHON" -m pip install graphifyy -q 2>/dev/null || "$PYTHON" -m pip install graphifyy -q --break-system-packages 2>&1 | tail -3
# Write interpreter path for all subsequent steps
mkdir -p graphify-out
"$PYTHON" -c "import sys; open('graphify-out/.graphify_python', 'w').write(sys.executable)"

If the import succeeds, print nothing and move straight to Step 2.

In every subsequent bash block, replace python3 with $(cat graphify-out/.graphify_python) to use the correct interpreter.

Steps 2-5 - Build pipeline

Read references/pipeline-steps.md for the full pipeline:

• Step 2 - Detect files (corpus scan, size warnings)
• Step 2.5 - Transcribe video/audio (Whisper, only if video detected)
• Step 3 - Extract entities and relationships (Part A: AST for code, Part B: parallel semantic subagents for docs/papers/images, Part C: merge)
• Step 4 - Build graph, cluster, analyze
• Step 5 - Label communities with plain-language names

Steps 6-9 and Subcommands

Read references/subcommands.md for:

• Step 6 - Generate HTML + Obsidian vault (opt-in)
• Step 6b - Wiki generation (--wiki flag)
• Step 7 - Neo4j, SVG, GraphML, MCP exports
• Step 8 - Token reduction benchmark
• Step 9 - Cleanup and final report
• Subcommands - --update, --cluster-only, query, path, explain, add, --watch, hook, claude install

Key Extraction Rules (always loaded)

These rules apply to every extraction regardless of which reference file you are reading:

Confidence tagging

• EXTRACTED: relationship explicit in source (import, call, citation)
• INFERRED: reasonable inference (shared data structure, implied dependency)
• AMBIGUOUS: uncertain - flag for review, do not omit

confidence_score (REQUIRED on every edge)

• EXTRACTED edges: always 1.0
• INFERRED edges: 0.8-0.9 (strong evidence), 0.6-0.7 (reasonable), 0.4-0.5 (weak)
• AMBIGUOUS edges: 0.1-0.3

Node ID format

Lowercase, only [a-z0-9_]. Format: {stem}_{entity} where stem is filename without extension, entity is symbol name. Example: src/auth/session.py + ValidateToken -> session_validatetoken.

Subagent rules

• MUST use Agent tool for semantic extraction - reading files one-by-one is forbidden
• Always use subagent_type="general-purpose" (NOT Explore - it cannot write to disk)
• Always use model: "sonnet" for extraction subagents

Honesty Rules

• Never invent an edge. If unsure, use AMBIGUOUS.
• Never skip the corpus check warning.
• Always show token cost in the report.
• Never hide cohesion scores behind symbols - show the raw number.
• Never run HTML viz on a graph with more than 5,000 nodes without warning the user.