treck

Your codebase, visualised.

Evergreen maps of every code flow. Always in sync.

From button click, to API call, to background task, to database update — trace the whole flow end-to-end.

Quick Start

npm install treck

Initialize treck in your project (interactive wizard), then open the viewer:

npx treck init
npx treck serve

Commands

| Command | Description | | --- | --- | | treck init | Initialize treck in your project | | treck info [target] | Show project graph info | | treck check | Check if graph is stale | | treck diff | Compare graph changes between branches | | treck jsdoc | Show JSDoc coverage or print an agent prompt | | treck serve | Start interactive documentation viewer | | treck show [targets] | Show graph data for symbols | | treck trace [target] | Trace execution path through the graph | | treck mcp | Start MCP server for AI agents | | treck test | Check, generate, or run e2e tests for changed flows |

treck init

Initialize treck in your project. Creates a treck.yaml config file with your file scope patterns.

treck info [target]

Show project graph info. Builds the dependency graph and displays statistics including node/edge counts, entry points, and JSDoc coverage.

treck info              # show info for all files in scope
treck info src/api/     # show info for files under src/api/

treck check

Check graph freshness. Compares current code hashes against the hashes stored in graph.json and reports any that are out of sync. Returns exit code 1 if stale nodes are found (CI-friendly).

treck check        # report stale nodes

treck diff [--base <ref>] [--format <f>] [--depth <n>] [--watch]

Compare graph changes between branches. Shows which symbols changed, were added, or removed, with call chain context.

treck diff                    # auto-detect base branch
treck diff --base main        # compare against main
treck diff --format json      # JSON output
treck diff --format ascii     # Unicode box-drawing art
treck diff --depth 2          # limit impact zone depth
treck diff --watch            # re-run diff when graph.json changes

treck jsdoc [--verbose] [--prompt] [--run <agent>]

Show JSDoc coverage and optionally hand off to a coding agent to auto-populate missing comments.

treck jsdoc                    # coverage summary
treck jsdoc --verbose          # include full list of symbols missing JSDoc
treck jsdoc --prompt           # print agent prompt to stdout (for piping)
treck jsdoc --run claude       # hand off to Claude Code
treck jsdoc --run codex        # hand off to Codex

treck serve [--port <number>] [--focus <targets>]

Start an interactive documentation viewer in your browser. Displays a flow graph of your codebase with clickable nodes that open symbol documentation in a side panel.

treck serve                                              # default port 3456
treck serve --port 8080
treck serve --focus src/api/route.ts:GET,src/lib/db.ts   # open with symbols pre-selected

treck show <targets> [--format <f>] [--depth <n>] [--theme <name>]

Show graph data for symbols in your codebase. Outputs a mermaid flowchart by default.

Targets can be file:symbol or a file path (comma-separated for multiple).

treck show src/api/route.ts:GET                # mermaid diagram for one symbol
treck show src/api/route.ts                    # all symbols in a file
treck show src/api/route.ts:GET --format markdown  # full markdown documentation
treck show src/api/route.ts:GET --format json  # JSON output
treck show src/api/route.ts:GET --format ascii # Unicode box-drawing art in terminal
treck show src/api/route.ts:GET --depth 1      # limit traversal depth

Tip: If your file paths contain parentheses or brackets (common in Next.js route groups), wrap the target in quotes:

treck show "src/app/(dashboard)/users/[id]/page.tsx:UserDetail"

treck trace [target] [--params <json>] [--format <f>] [--depth <n>]

Trace execution path through the graph. Evaluates conditions and propagates parameters to show which branches are taken.

treck trace src/app/api/upload/route.ts:POST
treck trace src/app/api/upload/route.ts:POST --params '{"type":"image"}'
treck trace src/app/api/upload/route.ts:POST --format json

treck mcp

Start an MCP server over stdio for AI agents (Claude Code, Cursor, Windsurf, etc.). Exposes graph queries as tools: search_nodes, show_symbol, list_entry_points, find_callers, find_callees, paths_between, get_graph_summary, diff_graph, and sync_graph.

treck mcp

treck test [--base <ref>] [--generate] [--force]

Check, generate, or run e2e tests for changed flows. Compares the current graph against a base ref to find changed flows, then checks for existing tests or generates new ones with AI.

treck test                    # report missing/stale tests
treck test --base main        # compare against main
treck test --generate         # generate tests using AI
treck test --generate --force # regenerate all tests

How it works

1. Map — Treck walks your source files and finds every symbol: functions, classes, handlers, tasks
2. Connect — It traces the calls between them, building a graph of how everything fits together
3. Detect — Each symbol is hashed, so when code changes, treck knows exactly what's gone stale
4. Explore — Browse the graph in an interactive viewer, or check freshness in CI

Currently supports TypeScript and JavaScript, with framework-aware entry points for Next.js, Inngest, and Trigger.dev.

Configuration

treck.yaml:

scope:
  include:
    - src/**/*.{ts,tsx,js,jsx}
  exclude:
    - **/*.test.ts
    - **/*.spec.ts
    - node_modules/**
    - dist/**
    - build/**

Known Limitations

• Dynamic dispatch — Static analysis can't resolve which function a variable points to at runtime. For example, const fn = cond ? adminHandler : userHandler; fn() will show fn() as an unconditional call without knowing which handler it refers to.
• Switch fall-through (non-empty cases) — Empty cases that fall through are grouped correctly (case 'a': case 'b': foo() → case 'a' | 'b'), but fall-through from cases that have statements without break/return is not detected. Those calls are attributed only to the case they appear in, not to preceding cases that fall through.

License

The treck CLI is MIT licensed — free to use, modify, and distribute.

The treck.dev website and hosted services (website/) are licensed under the Functional Source License (FSL) — source available, free to use, but may not be used to offer a competing hosted service. Converts to Apache 2.0 after two years.

Contributing

git clone https://github.com/fredrivett/treck
cd treck
pnpm install

pnpm run dev          # watch mode
pnpm run build        # build to dist/
pnpm test             # run tests
pnpm run format       # format with biome