Grepai Trace Graph

yoanbernabeu/grepai-skills/skills/trace/grepai-trace-graph

by yoanbernabeu382d40261c0d41109c6e11872574ba0be9b064d0No licenseListed Oct 9, 2026Updated Oct 9, 2026

Build complete call graphs with GrepAI trace. Use this skill for recursive dependency analysis.

Instructions onlySoftware Development
AI-generated overview

Guides use of the grepai trace graph command to build recursive call graphs for code dependency and impact analysis.

What it does
This skill documents how to run grepai trace graph to produce recursive call graphs of function dependencies. It covers depth control, extraction modes, JSON, compact JSON and TOON output, cycle marking, and post-processing into Graphviz DOT or Mermaid diagrams. It also gives guidance on large graphs, complexity tracking, and common errors.
When to use it
Use it when mapping function dependencies, understanding complex code flows, planning refactors, or assessing the impact of changes. It also fits code review and architecture documentation tasks that need call graph data.
Requirements
Requires the grepai CLI with the trace graph command and an indexed codebase. Optional post-processing uses python3, jq, and Graphviz dot; no scripts ship with the skill.

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

bash
grepai trace graph "FunctionName"

Example

bash
grepai trace graph "main"

Output:

🔍 Call Graph for "main"
main├── initialize│   ├── loadConfig│   └── connectDB├── startServer│   ├── registerRoutes│   └── listen└── gracefulShutdown    └── closeDB
Nodes: 9Max depth: 3

Depth Control

Limit recursion depth with --depth:

bash
# 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

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

Output:

json
{  "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

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

Output:

json
{  "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:

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

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

Extraction Modes

bash
# 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

bash
# Map entire application startupgrepai trace graph "main" --depth 4

Impact Analysis

bash
# What depends on this utility function?grepai trace graph "validateInput" --depth 3
# Full impact of changing database layergrepai trace graph "executeQuery" --depth 2

Code Review

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

Documentation

bash
# Generate architecture diagram datagrepai trace graph "main" --depth 3 --json > architecture.json

Refactoring Planning

bash
# 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:

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

Large Graphs

For very large codebases, graphs can be overwhelming:

Limit Depth

bash
# Start shallowgrepai trace graph "main" --depth 2

Focus on Specific Areas

bash
# Instead of main, trace specific subsystemgrepai trace graph "authMiddleware" --depth 3

Filter in Post-Processing

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

Visualizing Graphs

Export to DOT Format (Graphviz)

bash
# Convert JSON to DOTgrepai trace graph "main" --depth 3 --json | python3 << 'EOF'import jsonimport 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:

bash
dot -Tpng graph.dot -o graph.png

Mermaid Diagram

bash
grepai trace graph "main" --depth 2 --json | python3 << 'EOF'import jsonimport 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:

bash
# Get node countgrepai trace graph "main" --depth 3 --json | jq '.stats.nodes'
# Compare before/after refactoringecho "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: 3Mode: 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

Source and attribution

Source:yoanbernabeu/grepai-skillsinskills/trace/grepai-trace-graphat commit382d402

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from yoanbernabeu/grepai-skills

Grepai Trace Callers

yoanbernabeu

Guides use of the grepai trace callers command to find code locations that call a given function.

Software DevelopmentOct 9, 2026

Grepai Trace Callees

yoanbernabeu

Guides use of the grepai trace callees command to list functions called by a given function.

Software DevelopmentOct 9, 2026

Grepai Storage Postgres

yoanbernabeu

Configures PostgreSQL with pgvector as the storage backend for GrepAI code indexes, including setup, tuning and troubleshooting.

DevOps & CloudOct 9, 2026

Grepai Storage Gob

yoanbernabeu

Explains how to configure GrepAI's GOB local file storage backend, including setup, operations, limits and migration.

Software DevelopmentOct 9, 2026

Grepai Search Tips

yoanbernabeu

Guidance on writing effective GrepAI semantic search queries to find code by intent rather than exact names.

Software DevelopmentOct 9, 2026

Grepai Search Boosting

yoanbernabeu

Configures GrepAI search score boosting to prioritize source paths and penalize tests, docs and vendor code.

Software DevelopmentOct 9, 2026

More in Software Development

Playground

anthropics

Featured

Builds self-contained interactive HTML playgrounds with controls, live preview, and copyable prompt output.

Software Development37Kupdated today

M5 Onboard

anthropics

Featured

Provisions M5Stack ESP32 boards by detecting them on USB, flashing UIFlow 2.0 firmware, and installing a MicroPython app bundle.

Software Development37Kupdated today

Cardputer Buddy

anthropics

Featured

Guides iterating on a Cardputer-Adv MicroPython app bundle: adding apps, pushing files over USB-serial, tailing logs, and running REPL commands.

Software Development37Kupdated today

Web Design Guidelines

vercel-labs

Featured

Reviews UI code against Web Interface Guidelines fetched from a remote source and reports findings as file:line entries.

Software Development32Kupdated 5 weeks ago

Vercel React Native Skills

vercel-labs

Featured

React Native and Expo best-practice rules covering list performance, animation, navigation, UI patterns, state, and monorepo setup.

Software Development32Kupdated 5 weeks ago

Vercel React Best Practices

vercel-labs

Featured

Vercel's React and Next.js performance guidelines, organized as 70 rules for writing, reviewing, and refactoring code.

Software Development32Kupdated 5 weeks ago