ctx Tool

ctx is an agent-first JavaScript and TypeScript code navigation CLI.

The tool builds a compact structural model of a codebase so an agent can work from indexed symbols, call graphs, data flow, and compact reports instead of repeatedly reading raw files into context.

Examples below use ctx as the installed command name. In this repo checkout, run node tools/ctx/ctx ... from the repo root. Use ctx --root /path/to/repo ... when you want to target a repo other than the current working directory.

Why Use It

• Find exported, private, and nested symbols without grepping files by hand.
• Follow call relationships and data flow from real AST-based analysis.
• See impact and blast radius from one CLI surface.
• Prefer compact outputs when they help an agent stay precise with fewer tokens.

Quick Start

Install globally:

npm install -g @plunderstruck/repo-ctx
ctx --help

Or use the repo-local checkout:

npm install
node tools/ctx/ctx --help

Initialize ctx for an existing repo:

ctx init

That writes both ctx/config.json and a starter ctx/arch.json when the repo does not already have an architecture config.

Preview the generated config first:

ctx init --dry-run

Build the index:

ctx index

Use the indexed surfaces:

ctx find runRegen
ctx about runRegen
ctx context buildIndexedFileEntry --callers
ctx file tools/ctx/lib/index/regen.js

When in doubt, start with live help:

ctx help
ctx help context

Core Workflow

1. Run ctx init once per repo.
2. Run ctx index after source changes.
3. Use find, file, about, context, code, dataflow, and slice to navigate the codebase.
4. Use affected, cycles, and similar for change and hygiene views.

Command Chooser

• find searches for symbols by name or keyword.
• file shows one file's indexed symbols.
• about is the symbol card: signature and direct callers/callees.
• context is the local call-graph view around one symbol.
• code returns a bounded source snippet for one symbol.

Output Defaults

ctx does not force one renderer for every command.

• find defaults to TOON because exact symbol identity matters more than prose when names collide.
• file, about, context, code, impact, complexity, dataflow, and slice stay human-first because their structured forms are materially larger on real code and often repeat identity context across distinct results.
• map tree stays markdown-first.
• map stats is best as a human summary, with TOON useful when another tool needs explicit fields.

Use --toon, --json, or --human when a command supports them. Use ctx help <command> for the live contract.

Symbol Coverage

A symbol in ctx is a named code unit the agent can identify and relate. The current JS/TS parser covers:

• function declarations
• function-valued const bindings
• property-assigned functions such as store.reset = () => {}
• class declarations and class expressions assigned to bindings
• object-literal methods and accessors under named bindings
• methods, accessors, class properties, constructors, and constructor parameter properties
• private class members
• nested local helpers
• destructured bindings
• default exports, CommonJS export assignments, and named/namespace re-exports

The parser intentionally excludes throwaway anonymous callbacks that do not help navigation.

Key Commands

Use ctx help <command> or append --help for live usage.

Indexing

• ctx init [--dry-run] [--force] [--json]
• ctx index [--force]

Discovery

• ctx find "<query>" [filters]
• ctx file <path>
• ctx about <symbol>
• ctx context <symbol> [--depth=N] [--callers] [--budget=N]
• ctx code <symbol> [--context=<n>]

Analysis

• ctx impact <symbol> [--depth=N]
• ctx complexity <symbol>
• ctx dataflow <symbol>
• ctx slice <symbol> <variable> [--forward|--backward] [--line=N]

Navigation

• ctx map tree [--human|--toon|--json]
• ctx map stats [--human|--json|--toon] [--files] [--full]
• ctx config <key> [value]

Change And Hygiene

• ctx affected [ref] [--tests-only] [--verbose|-v] [--since=REF]
• ctx cycles
• ctx similar [--to=<symbol>] [--group] [--path=<dir>] [--threshold=<0-1>] [--max=N]

Choosing The Right Symbol Command

• about is the symbol card. Use it for identity and direct callers/callees.
• context is the local call-graph view. Use it to walk outward through callees or inspect direct callers around one symbol.
• impact is the reverse blast-radius view. Use it to trace caller chains back to entry points.

Repo And Package Surface

The named CLI entrypoint is tools/ctx/cli.js. The extensionless tools/ctx/ctx file is now only a tiny shim so existing repo-local workflows keep working.

Useful package scripts:

npm test
npm run check:self-host
npm run self:index
npm run self:help

Generated Files

Do not edit these by hand:

• ctx/config.json
• ctx/manifest.json
• ctx/index.top.md
• ctx/files/**