Graphify on Ghafoor's Personal Blog

Adding API Keys

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Adding API Keys

Configure LLM API keys to enable semantic extraction of markdown, documentation, PDFs, and images for the full graph.

🔑 Supported Providers

Provider	Environment Variable	Model (default)	Free Tier
Google Gemini	`GEMINI_API_KEY` or `GOOGLE_API_KEY`	`gemini-1.5-flash`	60 req/min, 1M tokens/day
OpenAI	`OPENAI_API_KEY`	`gpt-4o-mini`	$5 credit new accounts
Anthropic	`ANTHROPIC_API_KEY`	`claude-3.5-sonnet`	None
Moonshot (Kimi)	`MOONSHOT_API_KEY`	`kimi-k2`	Generous
DeepSeek	`DEEPSEEK_API_KEY`	`deepseek-chat`	Generous

⚙️ Configuration Methods

Method 1: Shell Profile (Recommended - Persistent)

1# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
2export GEMINI_API_KEY="your-api-key-here"
3
4# Reload
5source ~/.bashrc
6
7# Verify
8echo $GEMINI_API_KEY

Method 2: Project .env File (Per-Project)

1# In project root
2cat > .env << 'EOF'
3GEMINI_API_KEY=your-api-key-here
4EOF
5
6# Or use .env.local for secrets (gitignored)
7echo "GEMINI_API_KEY=your-api-key-here" > .env.local

Graphify auto-loads .env, .env.local, .env.*.local from project root.

Architecture Queries

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Architecture Queries

Deeper architecture questions for system understanding, design reviews, and technical decision-making.

🏗️ System-Level Questions

Overall Architecture

1graphify query "describe the overall architecture of this project"
2graphify query "what are the main architectural patterns used?"
3graphify query "how is the codebase organized at a high level?"

Data Flow

1graphify query "describe the data flow from YouTube URL to Hugo content page"
2graphify query "how does data flow through the dictionary extraction pipeline?"
3graphify query "what is the data flow for anki flashcard generation?"

Module Boundaries

1graphify query "what are the module boundaries in this project?"
2graphify query "which modules are tightly coupled?"
3graphify query "show the dependency graph between major subsystems"

🔧 Subsystem Deep-Dives

Pipeline Architecture

1graphify query "describe the youtube content pipeline architecture"
2graphify query "how does the vocabulary extraction pipeline handle errors?"
3graphify query "what are the stages in the anki generation pipeline?"

Configuration & Extensibility

1graphify query "how is configuration managed across the project?"
2graphify query "how do skills integrate with the main application?"
3graphify query "what extension points exist for adding new content types?"

Build & Deployment

1graphify query "describe the Hugo build process and customizations"
2graphify query "how does the task automation work?"
3graphify query "what are the deployment steps for this site?"

🎯 Design Review Questions

Before Adding Features

1graphify query "where would a new content type fit in the current architecture?"
2graphify query "what existing patterns should a new skill follow?"
3graphify query "which modules would a new pipeline stage touch?"

Refactoring Candidates

1graphify query "which modules have the most incoming dependencies?"
2graphify query "what are the most complex functions by cyclomatic complexity?"
3graphify query "which files are central hubs in the dependency graph?"

Technical Debt

1graphify query "where are the circular dependencies?"
2graphify query "which modules violate layering principles?"
3graphify query "what code is unused or unreachable?"

📊 Visualization Queries

Community Structure

1graphify query "what communities exist in the codebase?"
2graphify query "which files belong to the 'YouTube Pipeline' community?"
3graphify query "show the relationship between communities"

Centrality & Importance

1graphify query "which files are most central in the graph?"
2graphify query "what are the hub files that connect subsystems?"
3graphify query "which symbols are most referenced across the codebase?"

🧪 Example Session: Onboarding

 1# 1. Big picture
 2graphify query "project overview"
 3
 4# 2. Subsystems
 5graphify query "what are the main subsystems?"
 6# → Dictionary, YouTube, Anki, Lexicon, JupyterLite
 7
 8# 3. Pick one
 9graphify query "how does the Dictionary subsystem work?"
10
11# 4. Pipeline
12graphify query "describe the data flow in the Dictionary pipeline"
13
14# 5. Key files
15graphify explain scripts/dictionary/extract_vocab.py
16
17# 5. Config
18graphify query "how is the Dictionary pipeline configured?"
19
20# 6. Extension
21graphify query "how would I add a new vocabulary source?"

💡 Query Tips for Architecture

Tip	Example
Ask for “architecture” or “design”	`graphify query "architecture of the skill system"`
Use “data flow” for pipelines	`graphify query "data flow from transcript to Hugo page"`
Ask for “boundaries” for coupling	`graphify query "module boundaries in scripts/dictionary"`
Request “patterns” for conventions	`graphify query "patterns used for Hugo content generation"`

Next Steps

Dependency Tracing - Trace specific relationships
Impact Analysis - Assess change impact

Code-Only vs Full Graph

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Code-Only vs Full Graph

Understanding the two graph modes and when to use each.

📊 Comparison

Aspect	Code-Only (`--code-only`)	Full Graph (default)
API Key Required	❌ No	✅ Yes
Build Time	~30-60 seconds	~1-2 minutes
Graph Size	Smaller (~3-5 MB)	Larger (~10-50 MB)
Languages Indexed	20+ via tree-sitter	Same + semantic docs
File Types	Source code only	Code + markdown + docs + PDFs + images
Query Depth	Code structure, calls, imports	+ Semantic content, cross-references
Cost	Free (local only)	API credits per build

🔍 What Each Indexes

Code-Only Mode

1graphify . --code-only

Indexes:

Command Reference

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Command Reference

Complete CLI reference for all Graphify commands.

🔑 Golden Rule

Signal activity before EVERY command:

1mkdir -p graphify-out && touch graphify-out/.graphify-activity

📋 Commands

`graphify .` — Initial Build

Build the knowledge graph from scratch.

1graphify . [OPTIONS]

Option	Description
`--code-only`	Index code only (no API key needed)
`--no-gitignore`	Ignore .gitignore rules
`--exclude PATTERN`	Additional exclude patterns
`-v, --verbose`	Verbose output

Examples:

1graphify . --code-only # Code-only (fast, free)
2graphify . # Full (needs API key)
3graphify . --no-gitignore # Include gitignored files

`graphify update .` — Rebuild

Incremental rebuild of existing graph.

Configuration

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Configuration

Graphify configuration file options, environment variables, and runtime settings.

📁 Config File Locations

Location	Scope	Priority
`~/.config/graphify/config.yaml`	Global (all projects)	Low
`.graphify.yaml`	Project root	Medium
`--config PATH`	CLI argument	High

📝 Config File Format (YAML)

 1# ~/.config/graphify/config.yaml
 2
 3# Model settings
 4model:
 5 path: ~/.cache/graphify/model.gguf # Local LLM model path
 6 n_ctx: 8192 # Context window
 7 n_gpu_layers: -1 # -1 = all on GPU; 0 = CPU only
 8 n_threads: 8 # CPU threads for inference
 9 verbose: false # Model debug output
10
11# Extraction settings
12extraction:
13 max_file_size_mb: 10 # Skip files larger than this
14 skip_binary: true # Auto-skip binary files
15 include_patterns: [] # Additional include globs
16 exclude_patterns: [] # Additional exclude globs
17 parallel_workers: 16 # AST extraction workers
18
19# LLM settings (for full graph)
20llm:
21 provider: gemini # gemini, openai, anthropic, moonshot, deepseek
22 api_key_env: GEMINI_API_KEY # Env var name for API key
23 model: gemini-1.5-flash # Model name
24 temperature: 0.1 # Generation temperature
25 max_tokens: 4096 # Max output tokens
26 timeout: 60 # Request timeout (seconds)
27
28# Activity tracking
29activity:
30 enabled: true # Enable activity signaling
31 path: ~/.graphify-stats # Activity data directory
32 auto_signal: true # Auto-touch .graphify-activity
33
34# Output settings
35output:
36 graph_path: graphify-out/graph.json # Graph file location
37 report_path: graphify-out/GRAPH_REPORT.md
38 html_path: graphify-out/graph.html
39 cluster_resolution: 1.0 # Community detection resolution
40 min_community_size: 3 # Min nodes per community
41
42# Logging
43logging:
44 level: INFO # DEBUG, INFO, WARN, ERROR
45 file: '' # Empty = stderr only
46 format: text # text, json

🌍 Environment Variables

Variable	Description	Default
`GEMINI_API_KEY`	Google Gemini API key	—
`GOOGLE_API_KEY`	Alias for Gemini	—
`OPENAI_API_KEY`	OpenAI API key	—
`ANTHROPIC_API_KEY`	Anthropic API key	—
`MOONSHOT_API_KEY`	Moonshot/Kimi API key	—
`DEEPSEEK_API_KEY`	DeepSeek API key	—
`GRAPHIFY_CONFIG`	Custom config file path	`~/.config/graphify/config.yaml`
`GRAPHIFY_CACHE_DIR`	Model/cache directory	`~/.cache/graphify`
`GRAPHIFY_GRAPH_PATH`	Graph output path	`graphify-out/graph.json`
`GRAPHIFY_VERBOSE`	Enable verbose logging	`false`
`GRAPHIFY_CODE_ONLY`	Force code-only mode	`false`

⚙️ CLI Overrides

All config options can be overridden via CLI flags:

Daily Usage

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Daily Usage

The most common Graphify queries you’ll run during daily development. Keep this page bookmarked.

🔑 The Golden Rule

Signal activity before EVERY command:

1mkdir -p graphify-out && touch graphify-out/.graphify-activity

🏗️ Architecture Questions

Project Overview

1graphify query "project overview"

Use when: Starting work, onboarding, or need a refresher.

How a System Works

1graphify query "how does the youtube content pipeline work?"
2graphify query "how does the dictionary extraction work?"
3graphify query "how does the anki generation work?"

Use when: Need to understand a subsystem before modifying it.

Dependency Tracing

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Dependency Tracing

Trace relationships between any two components using graphify path — the most powerful command for understanding how code connects.

🔗 The `path` Command

1# Always signal activity first
2mkdir -p graphify-out && touch graphify-out/.graphify-activity
3
4# Trace from A to B
5graphify path <source> <target>

What It Shows

Node chain — Sequence of nodes connecting source to target
Edge types — imports_from, calls, contains, references
File locations — Exact paths and line numbers
Direction — Data/control flow direction

🎯 Common Use Cases

1. Script → Config (How does a script read config?)

1graphify path scripts/dictionary/yt-to-content-v2.py tasks/content.yaml

Typical output:

Edge Types

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Edge Types

Reference for all relationship types (edges) in the Graphify knowledge graph.

📊 Edge Type Summary

Edge Type	Direction	Description	Code Example
`imports_from`	A → B	Module A imports module B	`import yaml`
`calls`	A → B	Function A calls function B	`main() → parse_args()`
`contains`	A → B	File/module A contains symbol B	`file.py → mergeParams()`
`references`	A → B	Symbol A references symbol B	`mergeParams() → deepMerge()`
`reads`	A → B	Code A reads file B	`script → config.yaml`
`writes`	A → B	Code A writes file B	`script → output.yaml`

🔍 Detailed Edge Types

`imports_from`

Meaning: Module/file imports another module.

First Query

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

First Query

Your first Graphify architecture question — from signal to answer.

Prerequisites

Graphify installed (uv tool install graphifyy && graphify install)
Graph built (graphify . --code-only in your project root)
In your project directory

The Golden Rule: Signal Activity

Before EVERY Graphify command, you must signal activity:

1mkdir -p graphify-out && touch graphify-out/.graphify-activity

This is required by the GraphifyStats VS Code extension and prevents stale data warnings.

Your First Query

1# 1. Signal activity
2mkdir -p graphify-out && touch graphify-out/.graphify-activity
3
4# 2. Ask an architecture question
5graphify query "project overview"

Expected Output

This project is a Hugo + HBStack site for a personal blog with course content.
The codebase includes:

**Core Systems:**
- Dictionary/vocabulary extraction pipeline (scripts/dictionary/)
- YouTube content automation (scripts/dictionary/yt-to-content-v2.py)
- Anki flashcard generation (scripts/anki/)
- CBT lexicon extraction (scripts/extract-cbt-lexicon.mjs)

**Content Structure:**
- Courses under content/courses/ags/ (spirituality, storytelling)
- Docs under content/docs/ (dictionary, anki, tutorials, lexicon)
- JupyterLite integration for interactive notebooks

**Build Pipeline:**
- Hugo with HBStack theme
- Task-based automation (Taskfile.yaml)
- Custom shortcodes for accordions, vocabulary, diagrams

Understanding the Output

Element	Meaning
Natural language answer	Graphify synthesizes findings into readable text
File references	Specific paths cited (e.g., `scripts/dictionary/yt-to-content-v2.py`)
Architectural concepts	Components, pipelines, data flows identified

Next Queries to Try

 1# Always signal activity first!
 2mkdir -p graphify-out && touch graphify-out/.graphify-activity
 3
 4# How does a specific system work?
 5graphify query "how does the youtube content pipeline work?"
 6
 7# What depends on a file?
 8graphify query "what depends on tasks/content.yaml?"
 9
10# Trace a relationship
11graphify path scripts/dictionary/yt-to-content-v2.py data/course/ags/storytelling/j-wiebe/youtube-content/course-structure.yaml
12
13# Deep-dive on a component
14graphify explain scripts/dictionary/yt-to-content-v2.py

Common Patterns

Question Type	Query Template
Architecture overview	`graphify query "project overview"`
How X works	`graphify query "how does X work?"`
Dependencies of X	`graphify query "what depends on X?"`
Relationship A→B	`graphify path A B`
Deep-dive on file	`graphify explain <file-path>`

Tips for Better Queries

Use specific names from your codebase — “yt-to-content-v2.py” not “the script”
Ask about concepts, not syntax — “how does auth work?” not “show me the login function”
Iterate — Start broad, then drill down with explain and path
Rebuild if stale — graphify update . after significant changes

Next Steps

Daily Usage - Common query patterns for development
Verification - Confirm your setup is correct

Ignoring Files

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Ignoring Files

Configure .graphifyignore to exclude files and directories from the knowledge graph, reducing noise and build time.

📝 What is .graphifyignore?

A .graphifyignore file in your project root tells Graphify which files/directories to skip during extraction. Syntax matches .gitignore.

🎯 Why Ignore Files?

Reason	Example
Reduce noise	Exclude generated files, vendor code
Faster builds	Skip large directories (node_modules, dist)
Privacy	Exclude secrets, configs, local files
Relevance	Focus on your code, not dependencies

📝 Syntax

Same as .gitignore:

Impact Analysis

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Impact Analysis

Assess the impact of changes before you make them — find all dependents, trace ripple effects, and plan safe refactoring.

🎯 The Core Question

“If I change X, what breaks?”

Graphify answers this by finding all nodes that depend on X, directly or transitively.

🔍 Finding Direct Dependents

What Depends on This File?

1graphify query "what depends on scripts/dictionary/yt-to-content-v2.py?"
2graphify query "what depends on tasks/content.yaml?"
3graphify query "what depends on data/course/meta/providers-ags-storytelling.yaml?"

What Calls This Function?

1graphify query "what calls mergeParams?"
2graphify query "what calls the vocabulary extraction function?"

What Imports This Module?

1graphify query "what imports scripts/dictionary/extract_vocab.py?"

🌊 Tracing Transitive Dependents (Ripple Effects)

Full Dependency Chain

1# Find ALL transitive dependents (not just direct)
2graphify query "show the full dependency tree for scripts/dictionary/yt-to-content-v2.py"

Path to Each Dependent

1# For each dependent, trace the path
2graphify path scripts/dictionary/yt-to-content-v2.py tasks/content.yaml
3graphify path scripts/dictionary/yt-to-content-v2.py content/courses/ags/storytelling/j-wiebe/youtube-content/articulate-your-thoughts/index.md
4graphify path scripts/dictionary/yt-to-content-v2.py .github/skills/youtube-content/SKILL.md

📋 Pre-Refactoring Checklist

Before Changing a File

 1# 1. Signal activity
 2mkdir -p graphify-out && touch graphify-out/.graphify-activity
 3
 4# 2. Find direct dependents
 5graphify query "what depends on path/to/file.py?"
 6
 7# 3. Find function-level dependents
 8graphify query "what calls functionName in path/to/file.py?"
 9
10# 4. Trace to each dependent
11graphify path path/to/file.py dependent1
12graphify path path/to/file.py dependent2
13
14# 5. Assess risk
15# - How many dependents?
16# - How critical are they?
17# - Are tests covering them?

Before Changing a Function Signature

1# 1. Find all callers
2graphify query "what calls functionName?"
3
4# 2. For each caller, trace the call chain
5graphify path path/to/file.py caller1
6graphify path path/to/file.py caller2
7
8# 3. Check if callers are in tests
9graphify query "which callers of functionName are in test files?"

Before Deleting a File

1# 1. Comprehensive dependent check
2graphify query "what depends on path/to/file.py?"
3
4# 2. Check if it's an entry point
5graphify query "is path/to/file.py an entry point or imported by tasks?"
6
7# 3. Verify no dynamic imports
8grep -r "import.*path/to/file" . --include="*.py" --include="*.js" --include="*.ts"

🎯 Real-World Examples

Example 1: Changing the YouTube Content Script

Scenario: Modify scripts/dictionary/yt-to-content-v2.py to add a new CLI flag.

Node IDs Explained

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Node IDs Explained

Understanding Graphify node identifiers — the keys to querying, explaining, and tracing your codebase.

🔑 What is a Node ID?

A Node ID is a unique identifier for any node in the Graphify knowledge graph. Every file, function, class, variable, and symbol gets a Node ID.

📋 Node ID Formats

Format	Example	Resolves To
File path	`scripts/dictionary/yt-to-content-v2.py`	File node
File + line	`scripts/dictionary/yt-to-content-v2.py:L100`	Symbol at line 100
Symbol name	`mergeParams`	Function/class by name
Qualified symbol	`scripts/dictionary/yt-to-content-v2.py:mergeParams`	Specific symbol in file
Class.method	`Config.load`	Method on class

🎯 Usage in Commands

`graphify explain`

 1# File (shows all symbols, imports, structure)
 2graphify explain scripts/dictionary/yt-to-content-v2.py
 3
 4# Specific function
 5graphify explain mergeParams
 6
 7# Qualified (disambiguates same-name functions)
 8graphify explain scripts/dictionary/yt-to-content-v2.py:mergeParams
 9
10# Line-specific
11graphify explain scripts/dictionary/yt-to-content-v2.py:L100

`graphify path`

1# File to file
2graphify path tasks/content.yaml scripts/dictionary/yt-to-content-v2.py
3
4# Function to file
5graphify path mergeParams scripts/dictionary/yt-to-content-v2.py
6
7# Qualified to file
8graphify path scripts/dictionary/yt-to-content-v2.py:mergeParams tasks/content.yaml

`graphify query`

1# Natural language (Graphify resolves internally)
2graphify query "explain the mergeParams function"
3graphify query "what does scripts/dictionary/yt-to-content-v2.py do?"

🔍 Resolution Rules

1. Exact File Path

scripts/dictionary/yt-to-content-v2.py

→ Resolves to file node if exists in graph.

Graphify Overview

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Graphify Overview

What Graphify is, how it works, and why it’s useful for understanding codebases.

🎯 What is Graphify?

Graphify is a local knowledge graph builder for codebases. It analyzes your project (code, docs, markdown, configs) and builds a queryable graph of files, symbols, and relationships. You ask natural language questions and get architectural answers with file references.

┌─────────────────────────────────────────────────────────────┐
│ YOUR CODEBASE │
│ Python, JS/TS, Go, Rust, Java, Markdown, YAML, PDF, ... │
└─────────────────────┬───────────────────────────────────────┘
 │ AST + Semantic Extraction
 ▼
┌─────────────────────────────────────────────────────────────┐
│ KNOWLEDGE GRAPH │
│ Nodes: files, functions, classes, variables, docs │
│ Edges: imports, calls, contains, references, reads, writes │
│ Communities: auto-detected logical groups │
└─────────────────────┬───────────────────────────────────────┘
 │ Natural Language Queries
 ▼
┌─────────────────────────────────────────────────────────────┐
│ ANSWERS │
│ "How does X work?" → Architectural explanation + files │
│ "What depends on Y?" → Dependency list + paths │
│ "Trace A to B" → Call/import chain with line numbers │
└─────────────────────────────────────────────────────────────┘

🔑 Key Concepts

Knowledge Graph

A network of nodes (files, functions, classes, variables, docs) connected by edges (relationships like imports, calls, contains, reads, writes).

Rebuilding the Graph

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Rebuilding the Graph

When and how to refresh your Graphify knowledge graph to stay current with your codebase.

🔄 When to Rebuild

✅ Rebuild Triggers

Trigger	Reason	Command
5+ files changed	Significant code changes since last build	`graphify update . --code-only`
Branch merged / PR merged	New code from other branches	`graphify update . --code-only`
Switched branches	Different codebase state	`graphify update . --code-only`
Graph >4 hours old	Stale during active development	`graphify update . --code-only`
API key added/changed	Enable/disable full graph	`graphify update .`
Deleted file referenced	Graph has stale references	`graphify update . --code-only`
Major refactor	Structural changes	`graphify update . --code-only`

❌ Don’t Rebuild When

1-2 small edits (query existing graph)
Graph <1 hour old, no code changes
Only documentation typos fixed (code-only unaffected)
Just exploring — query current graph

🛠️ Rebuild Commands

Code-Only Rebuild (Fast, No API Key)

1# 1. Signal activity (REQUIRED)
2mkdir -p graphify-out && touch graphify-out/.graphify-activity
3
4# 2. Rebuild
5graphify update . --code-only
6
7# Typical time: 30-60 seconds
8# Output: Updated graphify-out/graph.json

Full Graph Rebuild (Needs API Key)

 1# 1. Ensure API key is set
 2export GEMINI_API_KEY="your-key"
 3
 4# 2. Signal activity
 5mkdir -p graphify-out && touch graphify-out/.graphify-activity
 6
 7# 3. Rebuild
 8graphify update .
 9
10# Typical time: 60-120 seconds
11# Output: Updated graphify-out/graph.json (larger, includes docs)

First Build (No graphify-out/)

1# Same as rebuild but initial
2mkdir -p graphify-out && touch graphify-out/.graphify-activity
3graphify . --code-only # or without flag for full

⚡ Quick Rebuild Alias

1# Add to ~/.bashrc
2alias graphify-rebuild='mkdir -p graphify-out && touch graphify-out/.graphify-activity && graphify update . --code-only'
3alias graphify-rebuild-full='mkdir -p graphify-out && touch graphify-out/.graphify-activity && graphify update .'
4
5# Usage
6graphify-rebuild
7graphify-rebuild-full

🔍 Verification After Rebuild

 1# 1. Check graph size
 2ls -lh graphify-out/graph.json
 3# Should be > 500 KB (3.3 MB in this project)
 4
 5# 2. Test query
 6mkdir -p graphify-out && touch graphify-out/.graphify-activity
 7graphify query "project overview"
 8# Should return fresh architectural summary
 9
10# 3. Check timestamp
11stat graphify-out/graph.json
12# Modified time should be recent

🤖 CI/CD Integration

GitHub Actions: Auto-Rebuild on Main

 1# .github/workflows/graphify-rebuild.yml
 2name: Rebuild Graphify Graph
 3on:
 4 push:
 5 branches: [main]
 6 paths:
 7 - 'scripts/**'
 8 - 'tasks/**'
 9 - '.github/skills/**'
10 - 'content/docs/**'
11
12jobs:
13 rebuild:
14 runs-on: ubuntu-latest
15 steps:
16 - uses: actions/checkout@v4
17 - name: Install Graphify
18 run: |
19 curl -LsSf https://astral.sh/uv/install.sh | sh
20 echo "$HOME/.local/bin" >> $GITHUB_PATH
21 uv tool install graphifyy
22 graphify install
23 - name: Build code-only graph
24 run: |
25 mkdir -p graphify-out
26 touch graphify-out/.graphify-activity
27 graphify update . --code-only
28 - name: Upload graph artifact
29 uses: actions/upload-artifact@v4
30 with:
31 name: graphify-graph
32 path: graphify-out/graph.json
33 retention-days: 7

Pre-Commit Hook (Optional)

1# .git/hooks/pre-commit
2#!/bin/bash
3# Rebuild if Python/JS files changed
4if git diff --cached --name-only | grep -E '\.(py|js|ts|go|rs)$' | head -5 | grep -q .; then
5 echo "Rebuilding Graphify graph..."
6 mkdir -p graphify-out && touch graphify-out/.graphify-activity
7 graphify update . --code-only
8fi

📊 Rebuild Performance

Mode	Files	Time	Graph Size
Code-only (incremental)	~100	~15s	3.3 MB
Code-only (full)	~944	~45s	3.3 MB
Full (incremental)	~100	~30s	~15 MB
Full (full)	~3,000	~90s	~15 MB

🚨 Common Rebuild Issues

Issue	Solution
`graph.json` not updated	Forgot to signal activity: `touch graphify-out/.graphify-activity`
Stale references persist	Full rebuild: `graphify . --code-only` (not `update`)
API key error on full rebuild	Check `GEMINI_API_KEY` env var; fallback to `--code-only`
Build hangs	Kill with Ctrl+C; check disk space; try `--code-only`
Graph still empty after rebuild	Run `graphify . --code-only` (initial build, not update)

📋 Rebuild Checklist

Signaled activity (mkdir -p graphify-out && touch graphify-out/.graphify-activity)
Chose correct mode (--code-only vs full)
API key set (if full graph)
Command completed without errors
Graph file updated (check stat graphify-out/graph.json)
Test query works (graphify query "project overview")
(Optional) Regenerate clusters: graphify cluster-only .

Next Steps

Daily Usage - Use the fresh graph
VS Code Integration - Auto-signal activity in editor

Setup Guide

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Setup Guide

Complete installation, configuration, and troubleshooting for Graphify.

🚀 Installation

Prerequisites Check

1# Check Python version (3.10+ required)
2python3 --version
3
4# Check uv availability
5which uv
6# If not installed: curl -LsSf https://astral.sh/uv/install.sh | sh

Install Graphify

 1# Install via uv (recommended - isolated, fast)
 2uv tool install graphifyy
 3
 4# Verify installation
 5graphify --version
 6# Output: graphify 0.1.x
 7
 8# Install local LLM model (~2 GB, one-time)
 9graphify install
10# Downloads model to ~/.cache/graphify/
11# Creates ~/.claude/CLAUDE.md with instructions

Alternative: pip install

1# If uv not available
2pip install graphifyy
3graphify install

⚙️ Configuration

Project-Level (recommended)

Create .graphifyignore in project root to exclude paths:

Troubleshooting

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Troubleshooting

Common Graphify issues and their solutions.

🚨 Quick Diagnosis

 1# 1. Check installation
 2graphify --version
 3
 4# 2. Check graph exists
 5ls -lh graphify-out/graph.json
 6
 7# 3. Check activity signaling
 8cat graphify-out/.graphify-activity.json
 9
10# 4. Test basic query
11mkdir -p graphify-out && touch graphify-out/.graphify-activity
12graphify query "test"

📋 Common Issues

1. `graphify: command not found`

Cause: graphify not in PATH after uv tool install.

Verification

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Verification

Confirm your Graphify setup is working correctly at every level.

✅ Level 1: Installation

1# Check binary
2graphify --version
3# Output: graphify 0.1.x
4
5# Check model
6ls -lh ~/.cache/graphify/model.gguf
7# Should exist (~1.5-2 GB)

✅ Level 2: Graph Building

 1cd your-project
 2
 3# Signal activity
 4mkdir -p graphify-out && touch graphify-out/.graphify-activity
 5
 6# Build code-only graph
 7graphify . --code-only
 8
 9# Verify graph file
10ls -lh graphify-out/graph.json
11# Should be > 500 KB (3.3 MB in this project)
12
13# Check node/edge counts
14graphify query "project overview" | head -5
15# Should return architectural summary

✅ Level 3: Query Functionality

 1# Signal activity
 2mkdir -p graphify-out && touch graphify-out/.graphify-activity
 3
 4# Test basic query
 5graphify query "project overview"
 6
 7# Test specific component
 8graphify query "how does the dictionary extraction work?"
 9
10# Test path tracing
11graphify path scripts/dictionary/yt-to-content-v2.py tasks/content.yaml
12
13# Test deep-dive
14graphify explain scripts/dictionary/yt-to-content-v2.py

Expected Results

Command	Success Indicator
`graphify query "project overview"`	Returns multi-paragraph architectural summary with file paths
`graphify path A B`	Shows chain of nodes/edges connecting A to B
`graphify explain <file>`	Shows functions, classes, imports, calls in that file

✅ Level 4: Visual Report

1# Generate named communities and HTML report
2graphify cluster-only .
3
4# Check outputs
5ls -lh graphify-out/GRAPH_REPORT.md
6ls -lh graphify-out/graph.html
7
8# Open in browser
9open graphify-out/graph.html

Graph.html Features

Search - Filter nodes by name
Communities - Color-coded groups (e.g., “YouTube Pipeline”, “Dictionary System”)
Node details - Click node to see file, symbols, edges
Zoom/pan - Navigate large graphs

✅ Level 5: Activity Tracking (GraphifyStats)

1# Check activity marker
2cat graphify-out/.graphify-activity.json
3# Should show recent command with timestamp
4
5# Check machine config
6ls -lh ~/.graphify-stats/configured
7# Should exist (created during setup)

VS Code Extension

If using GraphifyStats:

VS Code Integration

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

VS Code Integration

The GraphifyStats extension provides seamless VS Code integration for Graphify.

📦 Installation

From Marketplace

Open VS Code Extensions (Ctrl+Shift+X)
Search “GraphifyStats”
Click Install

From Command Line

1code --install-extension graphify.graphify-stats

Via Graphify CLI (Auto-generates config)

1# Run in project root
2graphify install
3# Creates/updates .vscode/settings.json with Graphify config
4# Adds agent instructions to AGENTS.md / CLAUDE.md

🎯 Features

Status Bar Monitoring

Live spinner during graphify update . and graphify .
Last command with timestamp and duration
Status: idle / running / success / error
Click to open graph.html in browser

Auto Activity Signaling

Automatically touches .graphify-activity before every command
No manual mkdir -p graphify-out && touch graphify-out/.graphify-activity needed
Works with terminal, tasks, and keybindings

Command Palette Integration

Command	Action
`GraphifyStats: Query`	Run `graphify query "..."` with input prompt
`GraphifyStats: Explain`	Run `graphify explain <file>` on active editor
`GraphifyStats: Path`	Run `graphify path <A> <B>` with two-file picker
`GraphifyStats: Update`	Run `graphify update . --code-only`
`GraphifyStats: Open Graph`	Open `graphify-out/graph.html` in browser
`GraphifyStats: Add Agent Instructions`	Prepend Graphify instructions to AGENTS.md

Keyboard Shortcuts (Customizable)

 1// keybindings.json
 2{
 3 "key": "ctrl+g q",
 4 "command": "graphify-stats.query",
 5 "when": "editorTextFocus"
 6},
 7{
 8 "key": "ctrl+g e",
 9 "command": "graphify-stats.explain",
10 "when": "editorTextFocus"
11},
12{
13 "key": "ctrl+g p",
14 "command": "graphify-stats.path",
15 "when": "editorTextFocus"
16},
17{
18 "key": "ctrl+g u",
19 "command": "graphify-stats.update",
20 "when": "editorTextFocus"
21}

⚙️ Configuration

Settings (`.vscode/settings.json`)

1{
2 "graphify-stats.autoSignalActivity": true,
3 "graphify-stats.showStatusBar": true,
4 "graphify-stats.defaultMode": "code-only",
5 "graphify-stats.graphPath": "graphify-out/graph.json",
6 "graphify-stats.openGraphOnBuild": false
7}

Setting	Default	Description
`autoSignalActivity`	`true`	Auto-touch `.graphify-activity` before commands
`showStatusBar`	`true`	Show Graphify status in status bar
`defaultMode`	`"code-only"`	Default rebuild mode
`graphPath`	`"graphify-out/graph.json"`	Path to graph file
`openGraphOnBuild`	`false`	Auto-open graph.html after build

🔧 Workflow Integration

Task Integration (`.vscode/tasks.json`)

 1{
 2 "version": "2.0.0",
 3 "tasks": [
 4 {
 5 "label": "Graphify: Rebuild (Code-Only)",
 6 "type": "shell",
 7 "command": "graphify update . --code-only",
 8 "group": "build",
 9 "presentation": {
10 "reveal": "silent",
11 "panel": "shared"
12 },
13 "problemMatcher": []
14 },
15 {
16 "label": "Graphify: Rebuild (Full)",
17 "type": "shell",
18 "command": "graphify update .",
19 "group": "build",
20 "presentation": {
21 "reveal": "silent",
22 "panel": "shared"
23 },
24 "problemMatcher": []
25 },
26 {
27 "label": "Graphify: Query",
28 "type": "shell",
29 "command": "graphify query \"${input:query}\"",
30 "group": "test",
31 "presentation": {
32 "reveal": "always",
33 "panel": "shared"
34 },
35 "problemMatcher": []
36 }
37 ],
38 "inputs": [
39 {
40 "id": "query",
41 "type": "promptString",
42 "description": "Graphify query",
43 "default": "project overview"
44 }
45 ]
46}

Launch Configuration (`.vscode/launch.json`)

 1{
 2 "version": "0.2.0",
 3 "configurations": [
 4 {
 5 "name": "Graphify Query",
 6 "type": "node",
 7 "request": "launch",
 8 "command": "graphify query \"${input:query}\"",
 9 "console": "integratedTerminal"
10 }
11 ],
12 "inputs": [
13 {
14 "id": "query",
15 "type": "promptString",
16 "description": "Architecture question",
17 "default": "how does the youtube content pipeline work?"
18 }
19 ]
20}

🎯 Daily Workflow with Extension

1. Open Project

Extension detects graphify-out/graph.json
Status bar shows “Graphify: Ready”

2. Run Query

Ctrl+Shift+P → GraphifyStats: Query
Type: “how does the vocabulary extraction work?”
Output opens in new editor tab

3. Explain Current File

Open scripts/dictionary/yt-to-content-v2.py
Ctrl+Shift+P → GraphifyStats: Explain
Shows functions, imports, calls in output panel

4. Trace Relationship

Open two files (e.g., task + script)
Ctrl+Shift+P → GraphifyStats: Path
Select both files → shows call chain

5. Rebuild After Changes

Ctrl+Shift+P → GraphifyStats: Update
Status bar shows spinner during rebuild
Click status bar when done → opens graph.html

🐛 Troubleshooting

Issue	Solution
Extension not activating	Open folder with `graphify-out/`; run `graphify . --code-only` first
Status bar not showing	Enable `graphify-stats.showStatusBar` in settings
Auto-signal not working	Check `graphify-stats.autoSignalActivity: true`
Commands fail	Ensure `graphify` in PATH; restart VS Code after install
Graph not found	Run `graphify . --code-only` to create initial graph

📋 Extension Commands Reference

Command ID	Description
`graphify-stats.query`	Run architecture query with prompt
`graphify-stats.explain`	Deep-dive on active file
`graphify-stats.path`	Trace relationship between two files
`graphify-stats.update`	Rebuild graph (code-only)
`graphify-stats.updateFull`	Rebuild full graph (needs API key)
`graphify-stats.openGraph`	Open graph.html in browser
`graphify-stats.addAgentInstructions`	Add Graphify instructions to AGENTS.md

Next Steps

Rebuilding - When and how to refresh
Ignoring Files - Configure .graphifyignore

Graphify on Ghafoor's Personal Blog

Adding API Keys

Adding API Keys

🔑 Supported Providers

⚙️ Configuration Methods

Method 1: Shell Profile (Recommended - Persistent)

Method 2: Project .env File (Per-Project)

Architecture Queries

Architecture Queries

🏗️ System-Level Questions

Overall Architecture

Data Flow

Module Boundaries

🔧 Subsystem Deep-Dives

Pipeline Architecture

Configuration & Extensibility

Build & Deployment

🎯 Design Review Questions

Before Adding Features

Refactoring Candidates

Technical Debt

📊 Visualization Queries

Community Structure

Centrality & Importance

🧪 Example Session: Onboarding

💡 Query Tips for Architecture

Next Steps

Code-Only vs Full Graph

Code-Only vs Full Graph

📊 Comparison

🔍 What Each Indexes

Code-Only Mode

Command Reference

Command Reference

🔑 Golden Rule

📋 Commands

graphify . — Initial Build

graphify update . — Rebuild

Configuration

Configuration

📁 Config File Locations

📝 Config File Format (YAML)

🌍 Environment Variables

⚙️ CLI Overrides

Daily Usage

Daily Usage

🔑 The Golden Rule

🏗️ Architecture Questions

Project Overview

How a System Works

Dependency Tracing

Dependency Tracing

🔗 The path Command

What It Shows

🎯 Common Use Cases

1. Script → Config (How does a script read config?)

Edge Types

Edge Types

📊 Edge Type Summary

🔍 Detailed Edge Types

imports_from

First Query

First Query

Prerequisites

The Golden Rule: Signal Activity

Your First Query

Expected Output

Understanding the Output

Next Queries to Try

Common Patterns

Tips for Better Queries

Next Steps

Ignoring Files

Ignoring Files

📝 What is .graphifyignore?

🎯 Why Ignore Files?

📝 Syntax

Impact Analysis

Impact Analysis

🎯 The Core Question

`graphify .` — Initial Build

`graphify update .` — Rebuild

🔗 The `path` Command

`imports_from`

`graphify explain`

`graphify path`

`graphify query`

1. `graphify: command not found`