GrepAI Trace Graph

This skill covers using grepai trace graph to build complete call graphs showing all dependencies recursively.

When to Use This Skill

• Mapping complete function dependencies
• Understanding complex code flows
• Impact analysis for major refactoring
• Visualizing application architecture

What is Trace Graph?

grepai trace graph builds a recursive dependency tree:

main
├── initialize
│   ├── loadConfig
│   │   └── parseYAML
│   └── connectDB
│       ├── createPool
│       └── ping
├── startServer
│   ├── registerRoutes
│   │   ├── authMiddleware
│   │   └── loggingMiddleware
│   └── listen
└── gracefulShutdown
    └── closeDB

Basic Usage

grepai trace graph "FunctionName"

Example

grepai trace graph "main"

Output:

🔍 Call Graph for "main"

main
├── initialize
│   ├── loadConfig
│   └── connectDB
├── startServer
│   ├── registerRoutes
│   └── listen
└── gracefulShutdown
    └── closeDB

Nodes: 9
Max depth: 3

Depth Control

Limit recursion depth with --depth:

# Default depth (2 levels)
grepai trace graph "main"

# Deeper analysis (3 levels)
grepai trace graph "main" --depth 3

# Shallow (1 level, same as callees)
grepai trace graph "main" --depth 1

# Very deep (5 levels)
grepai trace graph "main" --depth 5

Depth Examples

--depth 1 (same as callees):

main
├── initialize
├── startServer
└── gracefulShutdown

--depth 2 (default):

main
├── initialize
│   ├── loadConfig
│   └── connectDB
├── startServer
│   ├── registerRoutes
│   └── listen
└── gracefulShutdown
    └── closeDB

--depth 3:

main
├── initialize
│   ├── loadConfig
│   │   └── parseYAML
│   └── connectDB
│       ├── createPool
│       └── ping
├── startServer
│   ├── registerRoutes
│   │   ├── authMiddleware
│   │   └── loggingMiddleware
│   └── listen
└── gracefulShutdown
    └── closeDB

JSON Output

grepai trace graph "main" --depth 2 --json

Output:

{
  "query": "main",
  "mode": "graph",
  "depth": 2,
  "root": {
    "name": "main",
    "file": "cmd/main.go",
    "line": 10,
    "children": [
      {
        "name": "initialize",
        "file": "cmd/main.go",
        "line": 15,
        "children": [
          {
            "name": "loadConfig",
            "file": "config/config.go",
            "line": 20,
            "children": []
          },
          {
            "name": "connectDB",
            "file": "db/db.go",
            "line": 30,
            "children": []
          }
        ]
      },
      {
        "name": "startServer",
        "file": "server/server.go",
        "line": 25,
        "children": [
          {
            "name": "registerRoutes",
            "file": "server/routes.go",
            "line": 10,
            "children": []
          }
        ]
      }
    ]
  },
  "stats": {
    "nodes": 6,
    "max_depth": 2
  }
}

Compact JSON

grepai trace graph "main" --depth 2 --json --compact

Output:

{
  "q": "main",
  "d": 2,
  "r": {
    "n": "main",
    "c": [
      {"n": "initialize", "c": [{"n": "loadConfig"}, {"n": "connectDB"}]},
      {"n": "startServer", "c": [{"n": "registerRoutes"}]}
    ]
  },
  "s": {"nodes": 6, "depth": 2}
}

TOON Output (v0.26.0+)

TOON format offers ~50% fewer tokens than JSON:

grepai trace graph "main" --depth 2 --toon

Note: --json and --toon are mutually exclusive.

Extraction Modes

# Fast mode (regex-based)
grepai trace graph "main" --mode fast

# Precise mode (tree-sitter AST)
grepai trace graph "main" --mode precise

Use Cases

Understanding Application Flow

# Map entire application startup
grepai trace graph "main" --depth 4

Impact Analysis

# What depends on this utility function?
grepai trace graph "validateInput" --depth 3

# Full impact of changing database layer
grepai trace graph "executeQuery" --depth 2

Code Review

# Is this function too complex?
grepai trace graph "processOrder" --depth 5
# Many nodes = high complexity

Documentation

# Generate architecture diagram data
grepai trace graph "main" --depth 3 --json > architecture.json

Refactoring Planning

# What would break if we change this?
grepai trace graph "legacyAuth" --depth 3

Handling Cycles

GrepAI detects and marks circular dependencies:

main
├── processA
│   └── processB
│       └── processA [CYCLE]

In JSON:

{
  "name": "processA",
  "cycle": true
}

Large Graphs

For very large codebases, graphs can be overwhelming:

Limit Depth

# Start shallow
grepai trace graph "main" --depth 2

Focus on Specific Areas

# Instead of main, trace specific subsystem
grepai trace graph "authMiddleware" --depth 3

Filter in Post-Processing

# Get JSON and filter
grepai trace graph "main" --depth 3 --json | jq '...'

Visualizing Graphs

Export to DOT Format (Graphviz)

# Convert JSON to DOT
grepai trace graph "main" --depth 3 --json | python3 << 'EOF'
import json
import sys

data = json.load(sys.stdin)

print("digraph G {")
print("  rankdir=TB;")

def traverse(node, parent=None):
    name = node.get('name') or node.get('n')
    if parent:
        print(f'  "{parent}" -> "{name}";')
    children = node.get('children') or node.get('c') or []
    for child in children:
        traverse(child, name)

traverse(data.get('root') or data.get('r'))
print("}")
EOF

Then render:

dot -Tpng graph.dot -o graph.png

Mermaid Diagram

grepai trace graph "main" --depth 2 --json | python3 << 'EOF'
import json
import sys

data = json.load(sys.stdin)

print("```mermaid")
print("graph TD")

def traverse(node, parent=None):
    name = node.get('name') or node.get('n')
    if parent:
        print(f"  {parent} --> {name}")
    children = node.get('children') or node.get('c') or []
    for child in children:
        traverse(child, name)

traverse(data.get('root') or data.get('r'))
print("```")
EOF

Comparing Graph Sizes

Track complexity over time:

# Get node count
grepai trace graph "main" --depth 3 --json | jq '.stats.nodes'

# Compare before/after refactoring
echo "Before: $(grepai trace graph 'main' --depth 3 --json | jq '.stats.nodes') nodes"
# ... refactoring ...
echo "After: $(grepai trace graph 'main' --depth 3 --json | jq '.stats.nodes') nodes"

Common Issues

❌ Problem: Graph too large / timeout
✅ Solutions:

• Reduce depth: --depth 2
• Trace specific function instead of main
• Use --mode fast

❌ Problem: Many cycles detected
✅ Solution: This indicates circular dependencies in code. Consider refactoring.

❌ Problem: Missing branches
✅ Solutions:

• Try --mode precise
• Check if files are indexed
• Verify language is enabled

Best Practices

1. Start shallow: Begin with --depth 2, increase as needed
2. Focus analysis: Trace specific functions, not always main
3. Export for docs: Use JSON for generating diagrams
4. Track over time: Monitor node count as complexity metric
5. Investigate cycles: Circular dependencies are code smells

Output Format

Trace graph result:

🔍 Call Graph for "main"

Depth: 3
Mode: fast

main
├── initialize
│   ├── loadConfig
│   │   └── parseYAML
│   └── connectDB
│       ├── createPool
│       └── ping
├── startServer
│   ├── registerRoutes
│   │   ├── authMiddleware
│   │   └── loggingMiddleware
│   └── listen
└── gracefulShutdown
    └── closeDB

Statistics:
- Total nodes: 12
- Maximum depth reached: 3
- Cycles detected: 0

Tip: Use --json for machine-readable output
     Use --depth N to control recursion depth