Guides 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.

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:

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:

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

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

Guides 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)

Code-Only vs Full Graph

Code-Only vs Full Graph

📊 Comparison

🔍 What Each Indexes

Code-Only Mode

Ignoring Files

Ignoring Files

📝 What is .graphifyignore?

🎯 Why Ignore Files?

📝 Syntax

Rebuilding the Graph

Rebuilding the Graph

🔄 When to Rebuild

✅ Rebuild Triggers

❌ Don’t Rebuild When

🛠️ Rebuild Commands

Code-Only Rebuild (Fast, No API Key)

Full Graph Rebuild (Needs API Key)

First Build (No graphify-out/)

⚡ Quick Rebuild Alias

🔍 Verification After Rebuild

🤖 CI/CD Integration

GitHub Actions: Auto-Rebuild on Main

Pre-Commit Hook (Optional)

📊 Rebuild Performance

🚨 Common Rebuild Issues

📋 Rebuild Checklist

Next Steps

VS Code Integration

VS Code Integration

📦 Installation

From Marketplace

From Command Line

Via Graphify CLI (Auto-generates config)

🎯 Features

Status Bar Monitoring

Auto Activity Signaling

Command Palette Integration

Keyboard Shortcuts (Customizable)

⚙️ Configuration

Settings (.vscode/settings.json)

🔧 Workflow Integration

Task Integration (.vscode/tasks.json)

Launch Configuration (.vscode/launch.json)

🎯 Daily Workflow with Extension

1. Open Project

2. Run Query

3. Explain Current File

4. Trace Relationship

5. Rebuild After Changes

🐛 Troubleshooting

📋 Extension Commands Reference

Next Steps

Settings (`.vscode/settings.json`)

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

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