Stay updated — Join the build list for tutorials and AI insights. No spam.
Browse Docs

Setup Guide

A. Ghafoor Sayyed November 9, 2026 3 min read Graphify Graphify Setup Installation Configuration Api-Keys

Complete installation and configuration guide for Graphify.

On this page

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

Create .graphifyignore in project root to exclude paths:

 1# .graphifyignore
 2# Exclude patterns (same syntax as .gitignore)
 3node_modules/
 4dist/
 5build/
 6*.min.js
 7vendor/
 8.attic/
 9*.log
10.env
11.env.*

Global Configuration

Graphify uses ~/.config/graphify/config.yaml (auto-created):

 1# Example config
 2model:
 3  path: ~/.cache/graphify/model.gguf
 4  n_ctx: 8192
 5  n_gpu_layers: -1 # -1 = all layers on GPU (if available)
 6
 7extraction:
 8  max_file_size_mb: 10
 9  skip_binary: true
10
11activity:
12  enabled: true
13  path: ~/.graphify-stats

🔑 API Keys (Optional - for Full Graph)

For semantic extraction of markdown, docs, PDFs, and images, you need an LLM API key. Graphify supports multiple providers:

ProviderEnvironment VariableGet Key
Google GeminiGEMINI_API_KEY or GOOGLE_API_KEYaistudio.google.com
OpenAIOPENAI_API_KEYplatform.openai.com
AnthropicANTHROPIC_API_KEYconsole.anthropic.com
Moonshot (Kimi)MOONSHOT_API_KEYplatform.moonshot.cn
DeepSeekDEEPSEEK_API_KEYplatform.deepseek.com

Setting the Key

1# Option 1: Shell profile (persistent)
2echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.bashrc
3source ~/.bashrc
4
5# Option 2: Project .env file (committed to repo - use .env.local for secrets)
6echo 'GEMINI_API_KEY=your-key-here' > .env.local
7
8# Option 3: Per-command (temporary)
9GEMINI_API_KEY=your-key graphify .

Verification

1# Test API key works
2graphify query "test" --backend=gemini --model=gemini-1.5-flash
3# Should return a response (uses 1 query credit)

📦 Building the Graph

Code-Only (No API Key Needed)

1cd your-project
2mkdir -p graphify-out && touch graphify-out/.graphify-activity
3graphify . --code-only
4# Indexes: Python, JS/TS, Go, Rust, Java, and 15+ languages via tree-sitter
5# Output: graphify-out/graph.json (AST-based, no semantic doc extraction)

Full Graph (Requires API Key)

1cd your-project
2mkdir -p graphify-out && touch graphify-out/.graphify-activity
3graphify .  # Uses API key from env
4# Indexes: code + markdown + docs + PDFs + images (semantic extraction)

Rebuild After Changes

1# Signal activity (required!)
2mkdir -p graphify-out && touch graphify-out/.graphify-activity
3
4# Full rebuild
5graphify update . --code-only    # code only
6graphify update .                # full (with API key)

🔍 Verification

 1# Check graph file exists and has content
 2ls -lh graphify-out/graph.json
 3# Should be > 500 KB for non-empty repos
 4
 5# Test query
 6mkdir -p graphify-out && touch graphify-out/.graphify-activity
 7graphify query "project overview"
 8# Should return architectural summary
 9
10# Check activity tracking
11cat graphify-out/.graphify-activity.json
12# Should show recent command

🐛 Troubleshooting

IssueSolution
graphify: command not foundRestart shell after uv tool install; check ~/.local/bin in PATH
no LLM API key foundSet GEMINI_API_KEY or run with --code-only
graph.json < 500 bytesGraph built on empty repo; run graphify update . after adding files
Python 3.10+ requiredInstall Python 3.10+; uv python install 3.10
Out of memoryReduce n_ctx in config; close other apps; use --code-only
Model download failsCheck disk space (~2 GB); graphify install retries automatically

📋 Checklist

  • Python 3.10+ installed
  • uv tool install graphifyy succeeded
  • graphify install completed (model downloaded)
  • mkdir -p graphify-out && touch graphify-out/.graphify-activity
  • graphify . --code-only completed without errors
  • graphify query "project overview" returns results
  • (Optional) API key set for full graph
  • (Optional) graphify . (full) completed
  • ~/.graphify-stats/configured exists

Next Steps

First Query