Setup Workflows - CodeGraphContext

This document provides exact, step-by-step workflows for setting up and using CodeGraphContext, both for first-time setup and everyday use.

Prerequisites

Required

Python 3.8+ installed on your system
pip package manager
Git (for cloning repositories)

Optional (for advanced features)

Neo4j (for large-scale repositories > 100k LOC)
Docker (for containerized deployment)

Check Prerequisites

# Check Python version
python --version
# Expected: Python 3.8.0 or higher

# Check pip
pip --version
# Expected: pip 20.0.0 or higher

# Check git
git --version
# Expected: git version 2.0.0 or higher

First-Time Setup: CLI Users

Time Required: 5-10 minutes
Frequency: Once per machine

Step 1: Install CodeGraphContext

# Install via pip
pip install codegraphcontext

# Verify installation
cgc --version

# Expected output:
# CodeGraphContext version 1.0.0

Troubleshooting: If cgc command not found, add Python scripts to PATH:

# Linux/Mac
export PATH="$HOME/.local/bin:$PATH"

# Windows
# Add %APPDATA%\Python\Scripts to PATH

Step 2: Choose Database Backend (Optional)

CodeGraphContext automatically uses FalkorDB (embedded, no setup needed) for most use cases.

When to use Neo4j instead: - Repository > 100,000 lines of code - Need to share graph across team members - Want persistent storage across machines

# Option A: Use FalkorDB (default, recommended for most users)
# No action needed - works out of the box

# Option B: Setup Neo4j (for large repositories)
cgc neo4j setup

# This will:
# 1. Check if Neo4j is installed
# 2. If not, provide installation instructions
# 3. Configure connection settings
# 4. Test the connection

Neo4j Setup Output:

Checking for Neo4j installation...
✗ Neo4j not found

Would you like to install Neo4j? (y/n): y

Installing Neo4j...
✓ Neo4j 5.x installed
✓ Started Neo4j service
✓ Default credentials: neo4j/neo4j

Please change the default password:
New password: ********
Confirm password: ********

✓ Password updated
✓ Connection tested successfully

Configuration saved to: ~/.cgc/config.yml

Step 3: Index Your First Repository

# Navigate to your project
cd ~/projects/my-project

# Index the repository
cgc index .

# Expected output:
# Indexing repository: /home/user/projects/my-project
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Scanning files...        ✓ 1,247 files found
# Parsing Python files...  ✓ 892 files (71%)
# Parsing JavaScript...    ✓ 234 files (19%)
# Parsing TypeScript...    ✓ 121 files (10%)
# 
# Building graph...
# ✓ Created 3,421 function nodes
# ✓ Created 892 class nodes
# ✓ Created 234 module nodes
# ✓ Created 15,234 relationships
# 
# Database: FalkorDB (embedded)
# Indexing completed in 23.4 seconds

Step 4: Verify Setup

# Check repository statistics
cgc stats

# Expected output:
# Repository Statistics
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Repository: my-project
# Path: /home/user/projects/my-project
# 
# Code Elements:
#   Files:      1,247
#   Functions:  3,421
#   Classes:    892
#   Modules:    234
# 
# Relationships:
#   Function calls:    8,234
#   Imports:           2,456
#   Inheritance:       234
#   Total:             15,234
# 
# Database: FalkorDB
# Last indexed: 2026-01-30 01:15:23

# Try a simple query
cgc find "main" --type function

# Expected output:
# Found 5 functions matching 'main':
# 
# 1. main
#    File: src/app.py:123
#    
# 2. main_loop
#    File: src/core/event_loop.py:45
# 
# ... (3 more)

Step 5: Explore Available Commands

# See all available commands
cgc help

# Expected output:
# CodeGraphContext CLI
# 
# Usage: cgc [COMMAND] [OPTIONS]
# 
# Project Management:
#   index [PATH]              Index a repository
#   reindex                   Re-index current repository
#   stats                     Show repository statistics
#   clean                     Clear the database
# 
# Code Discovery:
#   find <query>              Search for code elements
#   visualize                 Generate architecture visualization
# 
# Code Analysis:
#   analyze callers <name>    Find who calls a function
#   analyze callees <name>    Find what a function calls
#   analyze chain <a> <b>     Show call chain between functions
#   analyze deps <module>     Show module dependencies
#   analyze dead-code         Find unused functions
#   analyze complexity        Find complex functions
# 
# ... (more commands)

✅ Setup Complete! You're ready to use CodeGraphContext.

First-Time Setup: MCP Users

Time Required: 10-15 minutes
Frequency: Once per machine

Step 1-3: Same as CLI Users

Follow Steps 1-3 from First-Time Setup: CLI Users

Step 4: Configure MCP Integration

# Setup MCP configuration
cgc mcp setup

# Interactive prompts:
# 
# Select your IDE/Editor:
# 1. Cursor
# 2. VS Code (with Continue.dev)
# 3. Claude Desktop
# 4. Custom (manual configuration)
# 
# Choice: 1

For Cursor:

Configuring MCP for Cursor...

✓ Found Cursor config at: ~/.config/cursor/mcp.json
✓ Added CodeGraphContext MCP server
✓ Server command: cgc mcp start

Configuration:
{
  "mcpServers": {
    "codegraphcontext": {
      "command": "cgc",
      "args": ["mcp", "start"],
      "env": {
        "CGC_DB": "falkordb"
      }
    }
  }
}

✓ Configuration saved

Next steps:
1. Restart Cursor
2. Open Command Palette (Cmd/Ctrl + Shift + P)
3. Run: "MCP: Reload Servers"
4. Verify CodeGraphContext appears in MCP server list

For VS Code (Continue.dev):

Configuring MCP for VS Code (Continue.dev)...

✓ Found Continue config at: ~/.continue/config.json
✓ Added CodeGraphContext MCP server

Next steps:
1. Restart VS Code
2. Open Continue sidebar
3. Verify CodeGraphContext tools are available

For Claude Desktop:

Configuring MCP for Claude Desktop...

✓ Created config at: ~/Library/Application Support/Claude/claude_desktop_config.json

Next steps:
1. Restart Claude Desktop
2. Start a new conversation
3. Ask: "What MCP tools do you have access to?"
4. Verify CodeGraphContext tools are listed

Step 5: Start MCP Server

# Start the MCP server
cgc mcp start

# Expected output:
# CodeGraphContext MCP Server
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# ✓ Server started
# ✓ Protocol: Model Context Protocol (MCP)
# ✓ Transport: stdio
# ✓ Database: FalkorDB connected
# ✓ Repository: /home/user/projects/my-project
# ✓ Watching for file changes: enabled
# 
# Available tools: 18
#   - find_code
#   - analyze_code_relationships
#   - find_dead_code
#   - execute_cypher_query
#   ... (14 more)
# 
# Server ready. Listening for requests...

Note: Keep this terminal open, or run in background:

# Run in background (Linux/Mac)
cgc mcp start &

# Or use tmux/screen for persistent session
tmux new -s cgc
cgc mcp start
# Press Ctrl+B, then D to detach

Step 6: Verify MCP Integration

In Cursor/VS Code:

Open your IDE
Start a new chat with AI assistant
Ask: "What CodeGraphContext tools do you have?"

Expected AI Response:

"I have access to 18 CodeGraphContext tools:

Code Discovery: - find_code - Search for functions, classes, files - list_indexed_repositories - Show indexed projects

Code Analysis: - analyze_code_relationships - Find callers, callees, call chains - find_dead_code - Find unused functions - find_most_complex_functions - Find complex code - calculate_cyclomatic_complexity - Measure function complexity

Graph Queries: - execute_cypher_query - Run custom graph queries - visualize_graph_query - Generate graph visualizations

... (10 more tools)

How can I help you explore your codebase?"

Test with a real query:

Ask AI: "Find all functions that call authenticate"

Expected AI Response:

"I found 12 functions that call authenticate:

Direct callers (3): 1. login in api/auth.py:45 2. verify_token in middleware/auth.py:89 3. refresh_session in api/session.py:123

Indirect callers (9 more): ... (AI lists them)

Would you like me to show the call chain for any of these?"

✅ MCP Setup Complete! Your AI assistant now has code intelligence.

Every-Time Workflow: CLI Users

Time Required: 2-5 minutes per session
Frequency: Daily/as needed

Typical Daily Workflow

Morning: Start of Day

# 1. Navigate to your project
cd ~/projects/my-project

# 2. Pull latest changes
git pull origin main

# 3. Update the code graph (if files changed)
cgc reindex

# Output:
# Detecting changes...
# ✓ 12 files modified
# ✓ 3 files added
# ✓ 1 file deleted
# 
# Updating graph...
# ✓ Updated 45 nodes
# ✓ Updated 123 relationships
# 
# Reindexing completed in 3.2 seconds

Alternative: Use auto-watch mode (set once, forget it)

# Enable auto-watch for this repository
cgc watch .

# Output:
# ✓ Watching: /home/user/projects/my-project
# ✓ Auto-reindex on file changes: enabled
# 
# The graph will automatically update when files change.
# Press Ctrl+C to stop watching.

During Development: Common Tasks

Task 1: Understanding a new feature

# Find the entry point
cgc find "handle_payment" --type function

# See what it calls
cgc analyze callees handle_payment

# See the full execution flow
cgc analyze chain handle_payment process_payment

Task 2: Before refactoring

# Find all usages of a function
cgc analyze callers calculate_total

# Check complexity
cgc analyze complexity calculate_total

# Find dead code to remove first
cgc analyze dead-code

Task 3: Code review

# Check what a PR changes
git diff main...feature-branch --name-only > changed_files.txt

# For each changed file, check impact
cgc analyze callers MyChangedClass

# Verify test coverage
cgc find "test_my_changed_class" --type function

Task 4: Debugging

# Find where a variable is modified
cgc analyze modifies user_session

# Trace execution path
cgc analyze chain api_endpoint database_query

# Find similar code patterns
cgc find "try.*except.*pass" --regex

End of Day: Cleanup

# Optional: Clear cache if needed
cgc clean --cache-only

# Optional: Export graph for documentation
cgc visualize --output daily_architecture.html

Quick Reference: Most Used Commands

# Search
cgc find <query>                    # Find code elements
cgc find <query> --type function    # Find only functions
cgc find <query> --type class       # Find only classes

# Analysis
cgc analyze callers <name>          # Who calls this?
cgc analyze callees <name>          # What does this call?
cgc analyze chain <a> <b>           # Call path from A to B
cgc analyze dead-code               # Find unused code
cgc analyze complexity              # Find complex functions

# Visualization
cgc visualize                       # Generate architecture diagram
cgc stats                           # Show repository statistics

# Maintenance
cgc reindex                         # Update after code changes
cgc watch .                         # Auto-update on file changes

Every-Time Workflow: MCP Users

Time Required: 1-2 minutes per session
Frequency: Daily/as needed

Typical Daily Workflow

Morning: Start of Day

# Option 1: Start MCP server manually
cgc mcp start

# Option 2: Auto-start with system (set once)
# Add to ~/.bashrc or ~/.zshrc:
# cgc mcp start &

# Option 3: Use tmux/screen for persistent session
tmux attach -t cgc || tmux new -s cgc "cgc mcp start"

Verify server is running:

# Check if MCP server is running
ps aux | grep "cgc mcp"

# Expected output:
# user  12345  0.1  0.5  cgc mcp start

During Development: Natural Language Queries

Open your IDE and ask your AI assistant:

Understanding Code: - "What does the process_payment function do?" - "Show me all functions that call authenticate" - "What's the call chain from the API endpoint to the database?"

Before Refactoring: - "What will break if I change calculate_total?" - "Find all dead code in the auth module" - "Show me the most complex functions"

Code Review: - "What's the impact of changing UserService?" - "Are there any circular dependencies?" - "Find all functions that access the database"

Debugging: - "Trace the execution from handle_request to send_email" - "Who modifies the session_state variable?" - "Find all error handling code"

End of Day: Cleanup

# Optional: Stop MCP server if running manually
# Press Ctrl+C in the terminal running cgc mcp start

# Or kill the process
pkill -f "cgc mcp start"

Integration with AI Workflows

Example 1: Feature Development

Ask AI: "I need to add a new payment method. Show me how existing payment methods are implemented."
AI uses CGC: Finds PaymentMethod class, shows all implementations
AI generates: Boilerplate code following existing patterns
You review: AI-generated code with full context

Example 2: Bug Investigation

Ask AI: "Users report checkout fails for international orders. Help me debug."
AI uses CGC: Traces call chain from checkout to payment processing
AI identifies: Missing email notification call (like in User Journey #2)
AI suggests: Exact fix with line numbers

Example 3: Refactoring

Ask AI: "I want to refactor OldAuthService to NewAuthService. Create a migration plan."
AI uses CGC: Finds all 47 usages, analyzes complexity
AI generates: Step-by-step migration plan with risk assessment
You execute: Safe, incremental migration

Troubleshooting

Common Issues

Issue 1: `cgc` command not found

Symptoms:

cgc --version
# bash: cgc: command not found

Solution:

# Find where pip installed cgc
pip show codegraphcontext | grep Location

# Add to PATH
export PATH="$HOME/.local/bin:$PATH"

# Make permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Issue 2: Indexing fails with "Permission denied"

Symptoms:

cgc index .
# Error: Permission denied: /some/file.py

Solution:

# Check file permissions
ls -la /some/file.py

# Option 1: Fix permissions
chmod +r /some/file.py

# Option 2: Skip problematic files
cgc index . --ignore-errors

Issue 3: MCP server not connecting

Symptoms: - AI assistant says "CodeGraphContext tools not available" - MCP server starts but IDE doesn't see it

Solution:

# 1. Verify server is running
cgc mcp start
# Should show "Server ready. Listening for requests..."

# 2. Check MCP configuration
cat ~/.config/cursor/mcp.json
# Should contain "codegraphcontext" entry

# 3. Restart IDE completely
# Not just reload - full quit and reopen

# 4. Check IDE logs
# Cursor: Help > Toggle Developer Tools > Console
# Look for MCP connection errors

# 5. Test with manual MCP call
echo '{"method":"tools/list"}' | cgc mcp start
# Should return list of 18 tools

Issue 4: Slow indexing on large repositories

Symptoms:

cgc index .
# Takes > 5 minutes on 100k+ LOC repository

Solution:

# Option 1: Use Neo4j instead of FalkorDB
cgc neo4j setup
cgc index . --db neo4j

# Option 2: Exclude test files and dependencies
cgc index . --exclude "tests/*" --exclude "node_modules/*"

# Option 3: Index in parallel
cgc index . --parallel 4

# Option 4: Use pre-built bundle if available
cgc load <package-name>

Issue 5: Graph out of sync with code

Symptoms: - CGC shows old function names - Missing new files

Solution:

# Full reindex
cgc reindex --force

# Or use watch mode to auto-sync
cgc watch .

Getting Help

# Built-in help
cgc help
cgc help <command>

# Check version
cgc --version

# Enable debug logging
cgc --debug index .

# Report issues
# GitHub: https://github.com/CodeGraphContext/CodeGraphContext/issues

Next Steps

Learn by example → USER_JOURNEYS.md
Detailed use cases → USE_CASES_DETAILED.md
Integration patterns → INTEGRATION_GUIDE.md
CLI reference → CLI Reference
MCP reference → MCP Reference

Summary: Quick Start Cheat Sheet

First Time (CLI)

pip install codegraphcontext
cd ~/my-project
cgc index .
cgc stats

First Time (MCP)

pip install codegraphcontext
cd ~/my-project
cgc index .
cgc mcp setup
cgc mcp start
# Restart IDE

Every Time (CLI)

cd ~/my-project
cgc reindex  # or cgc watch .
cgc analyze callers <function>

Every Time (MCP)

cgc mcp start  # or auto-start
# Ask AI questions in natural language

That's it! You're ready to use CodeGraphContext. 🚀

Setup Workflows - CodeGraphContext

Table of Contents

Prerequisites

Required

Optional (for advanced features)

Check Prerequisites

First-Time Setup: CLI Users

Step 1: Install CodeGraphContext

Step 2: Choose Database Backend (Optional)

Step 3: Index Your First Repository

Step 4: Verify Setup

Step 5: Explore Available Commands

First-Time Setup: MCP Users

Step 1-3: Same as CLI Users

Step 4: Configure MCP Integration

Step 5: Start MCP Server

Step 6: Verify MCP Integration

Every-Time Workflow: CLI Users

Typical Daily Workflow

Morning: Start of Day

During Development: Common Tasks

End of Day: Cleanup

Quick Reference: Most Used Commands

Every-Time Workflow: MCP Users

Typical Daily Workflow

Morning: Start of Day

During Development: Natural Language Queries

End of Day: Cleanup

Integration with AI Workflows

Troubleshooting

Common Issues

Issue 1: cgc command not found

Issue 2: Indexing fails with "Permission denied"

Issue 3: MCP server not connecting

Issue 4: Slow indexing on large repositories

Issue 5: Graph out of sync with code

Getting Help

Next Steps

Summary: Quick Start Cheat Sheet

First Time (CLI)

First Time (MCP)

Every Time (CLI)

Every Time (MCP)

Issue 1: `cgc` command not found