ctx

Get back up to speed on any codebase in seconds.

ctx scans a git repository and produces a complete snapshot of where things stand: recent commits, uncommitted changes, scattered TODOs/FIXMEs, and an AI-powered analysis that flags risks, detects work-in-progress, and suggests what to do next.

Install

git clone <repo-url> && cd ctx-cli
npm install
npm run build
npm link   # makes `ctx` available globally

Requires Node.js 18+.

Usage

ctx                        # scan current directory
ctx ./some-project         # scan a specific repo
ctx --no-ai                # skip AI analysis (no API key needed)
ctx --diff                 # focused AI review of uncommitted changes only
ctx --oneline              # single-line summary (great for shell prompts)
ctx --commits 20           # show more commits (default: 10)
ctx --json                 # output raw JSON
ctx -i                     # interactive TUI mode

# subcommands
ctx recall                         # show your last snapshot
ctx recall --date "last tuesday"   # recall by date
ctx hook install                   # auto-show context on cd into repos
ctx hook uninstall                 # remove the shell hook

AI setup

Just set your Anthropic API key — no other setup needed:

export ANTHROPIC_API_KEY=sk-ant-...

Without the key, use --no-ai to skip analysis. Everything else works without an API key.

What it shows

• Branch & repo info -- current branch, repo root path
• Recent commits -- hash, author, date, message
• Uncommitted changes -- modified, added, deleted, renamed, and untracked files
• TODOs & FIXMEs -- scanned across 22 file types (TS, JS, Python, Go, Rust, Java, C/C++, Ruby, PHP, Swift, Kotlin, and more)
• AI analysis -- risk flags, WIP detection, suggested next actions, and changes since your last scan

Project memory

ctx saves a snapshot every time you run it (in .ctx/snapshots/ inside your repo). On subsequent runs, it compares against the previous snapshot and reports:

• New and resolved TODOs
• Stale uncommitted files (sitting unchanged across scans)
• Branch switches
• Time since last scan

The .ctx/ directory is automatically git-ignored. Snapshots are pruned to keep the most recent 30.

Diff review mode

ctx --diff skips the full scan and gives you a focused code review of just your uncommitted changes — useful before committing to catch console.logs, missing error handling, or half-finished work.

Recall

Query your project history using saved snapshots:

ctx recall                          # show most recent snapshot
ctx recall --date "yesterday"       # what was happening yesterday
ctx recall --date "last tuesday"    # recall last Tuesday
ctx recall --date "3 days ago"      # 3 days back
ctx recall --date "2026-04-20"      # specific date

Shell hook

Install a shell hook so ctx automatically shows a one-line summary every time you cd into a git repository:

ctx hook install     # adds hook to your .zshrc / .bashrc / config.fish
ctx hook uninstall   # removes it

After installation, you'll see something like this on every cd:

main | 3 uncommitted | 12 TODOs | 2h ago: "fix auth flow"

Supports bash, zsh, and fish.

Interactive TUI

Run ctx -i to launch a split-pane terminal UI:

 ctx   main   /path/to/repo
 ┌─────────────────────┬──────────────────────┐
 │  Commits            │  Summary             │
 │  a1b2c3d 2h ago     │  You were working on │
 │  Fix auth bug       │  the auth flow...    │
 │                     │                      │
 │  e4f5g6h 5h ago     │  Changes (3)         │
 │  Add user model     │  M  src/auth.ts      │
 │                     │  A  src/user.ts      │
 │                     │                      │
 │                     │  TODOs (2)           │
 │                     │  TODO src/auth.ts:42 │
 └─────────────────────┴──────────────────────┘
 j/k scroll  tab/h/l switch panel  q quit

Project structure

src/
  cli.ts                  Entry point, arg parsing, subcommand routing
  commands/
    recall.ts             ctx recall — query snapshot history by date
    hook.ts               ctx hook install/uninstall — shell cd hook
  core/
    scanner.ts            Orchestrator — runs scans in parallel
    git-scanner.ts        Git history, branches, file status
    todo-scanner.ts       Extracts TODO/FIXME/HACK/NOTE/XXX from source
    diff-analyzer.ts      Smart diff extraction with token budgeting
    summarizer.ts         AI analysis via Claude Messages API
    memory.ts             Snapshot saving, loading, and diffing
  types/
    domain.ts             Branded types, discriminated unions
  utils/
    result.ts             Result<T, E> for explicit error handling
  ui/
    plain-renderer.ts     Colored terminal output
    tui/
      app.tsx             Main TUI component (Ink/React)
      commits-panel.tsx   Left panel — commit history
      right-panel.tsx     Right panel — changes, todos, summary

Development

npm run dev          # watch mode (recompiles on change)
npm run build        # compile TypeScript
npm run lint         # type-check without emitting
npm run test         # run tests (vitest)
npm run clean        # remove dist/

License

MIT