Call Graph Analysis

Find who calls a function, what it calls, and where JS/TS properties are read or written, with grepai trace and grepai refs.

grepai trace answers two questions about a function or method: who calls it, and what does it call. It reads a local symbol index, so queries never call your embedding provider.

Quick Start

Build the index once (or keep grepai watch running), then query it:

# Build or update the symbol index
grepai index            # one-time run, or: grepai watch

# Who calls Login?
grepai trace callers "Login"

# What does HandleRequest call?
grepai trace callees "HandleRequest"

# Callers and callees around ProcessOrder, 3 levels deep
grepai trace graph "ProcessOrder" --depth 3

Example output of grepai trace callers "Login":

Symbol: Login (function)
File: auth/service.go:12

Callers (1):
------------------------------------------------------------

1. HandleAuth
   Defined: handlers/auth.go:30
   Calls at: handlers/auth.go:42
   Context: user.Login(ctx, credentials)

If the symbol index is empty, the command fails with symbol index is empty. Run 'grepai watch' first to build the index.

Features

• trace callers: functions that call a symbol.
• trace callees: functions a symbol calls.
• trace graph: a call graph around a symbol, with a configurable --depth (default 2).
• refs readers|writers|graph: where a JavaScript/TypeScript property is read or written (see Trace vs Refs).
• Output formats: text (default), --json, --toon, and --ui for an interactive view (trace only).
• Workspace support: query one project or every project of a workspace.
• RPG feature paths: when the Repository Planning Graph is enabled, each symbol also shows its feature path.

Trace vs Refs

Use trace for call relationships. Use refs for data access: places where a property is read or assigned without a function call (for example store.uid in Vue or Pinia code).

# Call graph (functions and methods)
grepai trace callers "isAdmin"

# Property usage (reads and writes)
grepai refs readers "uid"
grepai refs writers "uid"
grepai refs graph "uid"     # readers and writers together

Property References (refs)

grepai refs uses the same symbol index as trace. Read and write references are only extracted from JavaScript and TypeScript (.js, .jsx, .ts, .tsx) and from Vue single-file components (.vue), which are converted to TypeScript before extraction. Other languages produce call references only, so refs returns nothing for them.

What counts as an access:

Accesses on built-in roots (Math, JSON, console, window, document, and similar), names starting with _, and Vue internals such as $el or $refs are ignored. An access outside any function is attributed to <top-level>.

Example output of grepai refs readers "uid":

Symbol: uid (property)

Readers (1):
------------------------------------------------------------

1. useAuth
   Defined: src/composables/useAuth.ts:5
   Access: read at src/composables/useAuth.ts:9
   Context: return store.uid

refs supports --json, --toon, --compact, --workspace and --project. It has no --ui or --mode flag.

Workspace Mode

Both trace and refs can query the projects of a workspace:

# One project of the workspace
grepai trace callers "HandleRequest" --workspace my-fullstack --project backend

# All projects of the workspace
grepai trace callers "HandleRequest" --workspace my-fullstack

# Cross-project call graph
grepai trace graph "ProcessOrder" --workspace my-fullstack --depth 3

# Property usage across projects
grepai refs writers "uid" --workspace my-fullstack

Each project keeps its own symbol index in <project>/.grepai/symbols.gob, whatever vector store the workspace uses. grepai watch --workspace and grepai index --workspace build these indexes. In workspace mode, results are not enriched with RPG feature paths.

Supported Languages

Extracted symbol kinds are functions, methods, classes, interfaces and types.

Note: in Ruby, method calls (receiver.method) are found with or without parentheses, but a bare function call without parentheses (route 'GET', path) is not, because it cannot be told apart from a variable with regular expressions.

Note: .vue files go through the Vue framework processor (framework_processing.frameworks.vue.enabled, on by default). It converts the script and template to TypeScript, then extracts symbols and references with the TypeScript rules. Full compilation needs Node.js and @vue/compiler-sfc installed in the Vue project. Without them, grepai logs a warning and falls back to the <script> blocks. The compiler is loaded from the project’s own node_modules, so it runs code from the repository: disable the Vue processor before indexing a repository you do not trust.

Only extensions listed in trace.enabled_languages are indexed. A config created by an older version may lack newer entries such as .vue or the F# extensions: add them by hand if needed.

Extraction Modes

Fast Mode (default)

Symbols and references are extracted with regular expressions, one pattern set per language. This is the extractor that grepai watch and grepai index use, and it needs no extra dependency.

Precise Mode

Note: precise mode was never wired into indexing. grepai watch and grepai index always use the regex extractor. The --mode flag of trace callers|callees|graph is deprecated: it is still accepted so existing scripts keep working, prints a deprecation warning, and the output always reports "mode": "fast".

A tree-sitter extractor exists in the source tree behind the treesitter build tag (CGO required) for Go, JavaScript, TypeScript, Python, PHP, C# and F#. Release binaries are built without it.

JSON Output

Use --json or --toon (token-efficient) for scripts and AI agents. Add --compact to drop the context line of each call site (or access site for refs). --compact requires --json or --toon; --json, --toon and --ui are mutually exclusive.

grepai trace callers "Login" --json
grepai trace callers "Login" --json --compact
grepai refs readers "uid" --toon --compact

trace callers output (callees has the same shape with a callees array):

{
  "query": "Login",
  "mode": "fast",
  "symbol": {
    "name": "Login",
    "kind": "function",
    "file": "auth/service.go",
    "line": 12,
    "signature": "func Login(ctx context.Context, creds Credentials) (*User, error) {",
    "exported": true,
    "language": "go"
  },
  "callers": [
    {
      "symbol": {
        "name": "HandleAuth",
        "kind": "function",
        "file": "handlers/auth.go",
        "line": 30,
        "signature": "func HandleAuth(w http.ResponseWriter, r *http.Request) {",
        "exported": true,
        "language": "go"
      },
      "call_site": {
        "file": "handlers/auth.go",
        "line": 42,
        "context": "user.Login(ctx, credentials)"
      }
    }
  ]
}

Symbols can also carry receiver (methods) and feature_path (when RPG is enabled). trace graph returns a graph object instead, with root, nodes (symbols keyed by name), edges (caller, callee, file, line) and depth.

refs output:

{
  "query": "uid",
  "kind": "property",
  "mode": "fast",
  "readers": [
    {
      "symbol": { "name": "useAuth", "kind": "function", "file": "src/composables/useAuth.ts", "line": 5, "language": "typescript" },
      "access": "read",
      "access_at": { "file": "src/composables/useAuth.ts", "line": 9, "context": "return store.uid" }
    }
  ]
}

refs writers returns a writers array, and refs graph returns both arrays.

Configuration

The trace section of .grepai/config.yaml (defaults shown):

trace:
  enabled_languages:
    - .go
    - .js
    - .ts
    - .jsx
    - .tsx
    - .vue
    - .py
    - .php
    - .lua
    - .gd
    - .rb
    - .c
    - .h
    - .cpp
    - .hpp
    - .cc
    - .cxx
    - .hxx
    - .rs
    - .zig
    - .cs
    - .java
    - .fs
    - .fsx
    - .fsi
    - .pas
    - .dpr

To keep files out of every index, including the symbol index, use the top-level ignore list. Older configs may contain trace.mode or trace.exclude_patterns: these keys never had any effect and were removed, and grepai ignores them.

How It Works

1. Symbol indexing: grepai watch (initial scan plus file events) and grepai index extract symbol definitions from every file whose extension is in trace.enabled_languages.
2. Reference tracking: each call (and, for JS/TS, each property read or write) is recorded with the function that contains it.
3. Call graph: caller to callee edges are derived from those references.
4. Storage: everything is saved in .grepai/symbols.gob. Unchanged files are skipped on the next run.

Use Cases

Understanding Code Flow

# Where is this function used?
grepai trace callers "ValidateToken"

# What does this function depend on?
grepai trace callees "ProcessPayment"

Impact Analysis

# Dependency chain around a critical function
grepai trace graph "DatabaseConnect" --depth 4

# Every place that assigns a store field before you rename it
grepai refs writers "uid"

AI Agent Integration

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

The same features are exposed to MCP clients as grepai_trace_callers, grepai_trace_callees, grepai_trace_graph, grepai_refs_readers, grepai_refs_writers and grepai_refs_graph (see MCP Integration).

Commands Reference

• grepai trace callers: find functions that call a symbol
• grepai trace callees: find functions called by a symbol
• grepai trace graph: build a call graph
• grepai refs readers: find property readers
• grepai refs writers: find property writers
• grepai refs graph: readers and writers together