AI Code Trace Agent

Local CLI tool to scan, parse, and trace TypeScript/React/Next.js codebases.

Stack

• TypeScript + Bun
• Bun workspaces (no Turborepo)
• ts-morph (AST parser)
• bun:sqlite (local cache)
• commander (CLI)

Quick start

# Install dependencies
bun install

# Build all packages (optional — dev can run TS directly)
bun run build

# Go to a project to trace (demo app included)
cd examples/demo-app

# Init config
bun ../../apps/cli/src/index.ts init

# Index codebase
bun ../../apps/cli/src/index.ts index

# Export context for AI/Cursor
bun ../../apps/cli/src/index.ts export

# Trace a component
bun ../../apps/cli/src/index.ts trace component BlogDetail

# Trace a route
bun ../../apps/cli/src/index.ts trace route "/[locale]/blogs/[slug]"

# Generate Cursor rules
bun ../../apps/cli/src/index.ts cursor init

From repo root:

bun run ai-trace init
bun run ai-trace index
bun run ai-trace export

Project structure

apps/cli/              CLI entry point
packages/
  trace-types/         Shared types
  trace-config/        Config load/validate
  trace-scanner/       File scanner (fast-glob)
  trace-parser/        AST parser (ts-morph)
  trace-graph/         Graph builder + route detection
  trace-cache/         SQLite storage (bun:sqlite)
  trace-exporter/      Markdown/JSON export
  trace-agent/         Trace query engine
examples/demo-app/     Sample app for testing

Output

After index + export:

.ai-trace/
  config.json
  cache/index.sqlite
  exports/
    ai-context.md
    component-map.md
    hook-map.md
    route-map.md
    graph.json
    symbols.json
    routes.json

MVP commands

| Command | Description | |---------|-------------| | ai-trace init | Create .ai-trace/config.json | | ai-trace index | Scan → parse → graph → SQLite | | ai-trace export | Export markdown/json for AI | | ai-trace trace component <name> | Trace component flow | | ai-trace trace route <path> | Trace route flow | | ai-trace trace hook <name> | Trace hook usage | | ai-trace cursor init | Generate .cursor/rules |

Use as Git Submodule (another project)

Add the tool to your Next.js/React repo:

git submodule add [email protected]:your-org/ai-code-base.git tools/ai-code-trace-agent

One-time setup (per machine / after clone)

# From parent project root (e.g. web-chat-smith)
bash tools/ai-code-trace-agent/scripts/setup-submodule.sh

This runs bun install + bun run build inside the submodule (not your app).

Run trace on your project

# Still from parent project root
bash tools/ai-code-trace-agent/scripts/run-cli.sh init
bash tools/ai-code-trace-agent/scripts/run-cli.sh index
bash tools/ai-code-trace-agent/scripts/run-cli.sh export
bash tools/ai-code-trace-agent/scripts/run-cli.sh trace component BlogDetail
bash tools/ai-code-trace-agent/scripts/run-cli.sh cursor init

Output is created in your project, not inside the submodule:

your-project/.ai-trace/
your-project/.cursor/rules/   # after cursor init

Recommended package.json scripts (parent project)

{
  "scripts": {
    "trace:setup": "bash tools/ai-code-trace-agent/scripts/setup-submodule.sh",
    "trace:init": "bash tools/ai-code-trace-agent/scripts/run-cli.sh init",
    "trace:index": "bash tools/ai-code-trace-agent/scripts/run-cli.sh index",
    "trace:export": "bash tools/ai-code-trace-agent/scripts/run-cli.sh export"
  }
}

Parent .gitignore

.ai-trace/cache/
.ai-trace/snapshots/
.ai-trace/trace-results/

Clone parent repo with submodule

git clone --recurse-submodules [email protected]:you/your-app.git
cd your-app
bun run trace:setup

Or after a normal clone:

git submodule update --init --recursive
bun run trace:setup

Update tool version

# 1) Pull latest tool inside submodule
cd tools/ai-code-trace-agent
git pull origin main
bun install && bun run build

# 2) Pin new version in parent repo
cd ../..
git add tools/ai-code-trace-agent
git commit -m "chore: bump ai-code-trace-agent submodule"

Troubleshooting

| Error | Fix | |-------|-----| | Cannot find package 'commander' | Run trace:setup — submodule needs its own node_modules | | Indexes wrong folder | Run CLI from parent root via run-cli.sh (sets AI_TRACE_ROOT) | | Submodule empty after clone | git submodule update --init --recursive |