fallow trace

CLI reference for fallow trace. Walk the callers and callees of one exported symbol through the module graph, bounded by depth. A standalone, best-effort symbol-level surface, separate from the ranked review brief.

Walk the symbol-level call chain for one exported symbol: callers up (modules that import the symbol) and callees down (import-symbol edges plus intra-module call sites), bounded by --depth. trace is its own surface for following how a symbol connects through the codebase before you change it.

fallow trace src/api.ts:fetchUser --format json --quiet
fallow trace src/api.ts:fetchUser --callers --depth 2

fallow trace is a standalone, best-effort symbol-level surface. It is not folded into the ranked review brief and is never an input to the focus map or its ranking. Use it when you want to see how a symbol connects, not when you want a prioritized review.

Target

fallow trace takes one positional argument in FILE:SYMBOL form:

fallow trace src/api.ts:fetchUser

FILE is a project-relative path and SYMBOL is the exported symbol name.

Options

Flag	Description
--callers	Walk only the callers direction (modules that import the symbol).
--callees	Walk only the callees direction (import-symbol edges plus intra-module call sites).
--depth <N>	Bound the walk depth in each requested direction.

When neither --callers nor --callees is set, both directions are walked.

Common Flags

trace accepts the global project and performance flags:

Flag	Description
-r, --root <PATH>	Project root directory.
-c, --config <PATH>	Path to a fallow config file.
-f, --format <FORMAT>	Output format: human (default) or json.
-q, --quiet	Suppress progress and status output on stderr.
--no-cache	Disable incremental parse cache.
--threads <N>	Parser thread count.
--changed-since <REF>	Scope file discovery to files changed since this git ref.

How it works

trace walks the module graph in two directions from the target symbol:

1. Callers (up): the modules that import the symbol, followed up to --depth levels.
2. Callees (down): the import-symbol edges out of the symbol’s module plus the intra-module call sites, followed down to --depth levels.

The walk is best-effort and syntactic. Resolved and unresolved callees are reported honestly: an unresolved callee (for example, a dynamic call fallow cannot statically resolve) is surfaced as unresolved rather than silently dropped, so the chain reflects what fallow could and could not follow.

When the same export is referenced in both type and value space, JSON output adds direct_references_by_namespace with separate evidence for each lane. namespace and direct_references keep their existing winning-lane meaning for compatibility. The grouped field is omitted when only one lane has references, so consumers should treat its absence as the common single-namespace case.

Ambiguous star exports

When two export * sources contribute the requested name, the barrel exports nothing under that name. JSON output reports symbol_found: false and adds a star_export_ambiguity object:

{
  "symbol_found": false,
  "star_export_ambiguity": {
    "sources": ["src/models/admin.ts", "src/models/customer.ts"],
    "namespaces": ["type"]
  }
}

sources contains the sorted project-relative declaration origins. namespaces identifies whether the collision is in type space, value space, or both, with type before value. This field distinguishes a barrel collision from an unknown or misspelled symbol. Keep one origin, rename the others, or replace the star exports with explicit re-exports.

Because it is a standalone surface, trace never feeds the review brief’s focus map or its ranking. The same best-effort call-chain data is available as opt-in evidence on fallow inspect --symbol-chain and the inspect_target MCP tool’s symbol_chain option.

See also

Inspect a target

Compose one evidence bundle for a file or exported symbol, with opt-in --symbol-chain.

Audit and review brief

Changed-file verdict plus the graph-derived review brief and decision surface.

MCP integration

Use fallow tools from AI coding agents.