ctx init                      index the project
ctx doctor                    inspect the project + index health
ctx search "create_user"      find symbols
ctx deps src/app.py           what a file imports (and what imports it)
ctx impact create_user        who would break if I change this?
ctx context "add OAuth"       build a ranked context package for a task
ctx changed                   files & symbols changed since HEAD
ctx diff                      semantic diff of symbols between refs
ctx skeleton src/models.py    body-less structural skeleton
ctx watch                     keep the graph in sync while editing
ctx mcp                       run the MCP server over stdio

scoop install mingw
$env:PATH = "$env:USERPROFILE\scoop\apps\mingw\current\bin;" + $env:PATH

cargo build --release
cargo install --path .        # installs `ctx` to PATH

ctx --version   # ctx 0.1.2
ctx version     # same

cd your-project
ctx init                     # creates .ctx/config.toml + indexes the project
ctx doctor                   # verify the index is current
ctx search "migrate"         # find functions/methods matching
ctx deps src/lib.rs          # what this file imports / what imports it
ctx impact create_user       # change analysis for a symbol or path
ctx context "add pagination" # context package for a task (JSON with --json)

AI reads:
  12,000 lines of source
  ~100,000 tokens

With ctx:
  AI receives an architecture tree
  relevant symbols + signatures
  dependency / impact map
  skeletons of the files that matter
  target implementations only when relevant

Usage: ctx [OPTIONS] [COMMAND]

Commands:
  init        Create .ctx, write a default config and index the project
  doctor      Inspect the project and report the health of the ctx index
  skeleton    Show a body-less structural skeleton of a source file
  search      Search the graph for symbols or files
  symbol      Details about a symbol: definition, references, dependencies
  deps        Show what a file imports and what imports it
  impact      Analyze impact of changing a symbol or file
  context     Build a relevance-ranked context package for a task
  changed     Show symbols changed in the working tree or between refs
  diff        Semantic diff of symbols between two git refs
  schema      Print the SQLite graph schema
  benchmark   Re-run an index pass and print incremental timing
  watch       Watch the project and keep the graph in sync
  mcp         Run the Model Context Protocol server over stdio
  stats       Show index statistics (files, symbols, dependencies, db size)
  version     Print version information
  help        Print this message or the help of the given subcommand(s)

Options:
  -R, --root <DIR>  Project root (defaults to the nearest directory containing .ctx)
  -j, --json        Emit machine-readable JSON instead of human text
  -q, --quiet       Suppress non-essential output
  -v, --verbose     Enable verbose diagnostics on stderr
      --no-color    Disable ANSI colors
  -h, --help        Print help
  -V, --version     Print version

ctx context --help
ctx impact --help

ctx context "add Google OAuth authentication"

Suggested files:
  src/auth/providers.ts  (score 0.91, ~180 tokens)
      + exact symbol match `OAuthProvider`
      + path matches keyword `auth`
      + imported by 4 files (hub)
      + modified in working tree

ctx context "add OAuth" --max-tokens 12000

Context budget: 7,842 / 12,000 tokens (estimate)
Omitted: 13 lower-relevance files

ctx impact UserService.updateUser --depth 5 --json

Direct dependents
Indirect dependents
Tests
UNKNOWN (unresolvable imports in affected files)
Potentially affected: N files / M symbols

ctx doctor          # human-readable
ctx doctor --json   # machine-readable

ctx search "user"                    # case-insensitive name match
ctx search --kind struct "user"      # filter by symbol kind
ctx search --kind function User      # kind aliases: fn, const, alias
ctx search --files "src/auth"        # search file paths instead
ctx search "user" --limit 20         # default 50, clamped to 1–500

ctx stats            # files, symbols, dependency edges, index.db size
ctx stats --json
ctx version          # ctx 0.1.2
ctx version --json   # {"name":"ctx","version":"0.1.2"}

ctx search User --json
ctx symbol UserService --json
ctx deps src/user.ts --json
ctx impact UserService --json
ctx context "add OAuth" --json
ctx changed --json
ctx diff --json
ctx doctor --json
ctx init --json
ctx benchmark --json
ctx schema --json
ctx stats --json
ctx version --json

ctx mcp                      # speaks MCP over stdio
ctx -R /path/to/project mcp  # or target a project root explicitly
npx ctxai-cli mcp            # no install required

{
  "mcpServers": {
    "ctx": {
      "command": "npx",
      "args": ["-y", "ctxai-cli", "mcp", "-R", "/absolute/path/to/project"]
    }
  }
}

{
  "mcpServers": {
    "ctx": {
      "command": "npx",
      "args": ["-y", "ctxai-cli", "mcp", "-R", "/absolute/path/to/project"]
    }
  }
}

{
  "command": "npx",
  "args": ["-y", "ctxai-cli", "mcp", "-R", "/absolute/path/to/project"]
}

command: npx
args: -y ctxai-cli mcp -R /absolute/path/to/project

## Supported languages

| Language | Files | Symbols | Dependencies | Skeleton |
| --- | --- | --- | --- | --- |
| TypeScript | ts, tsx, mts, cts | functions, methods, classes, interfaces, enums, constants, fields, modules, type aliases | `import` / `require` / dynamic `import()` / re-exports; `./`, `../`, `@/` aliases, bare specifiers | bodies elided, docs kept |
| JavaScript | js, jsx, mjs, cjs | same as TS | same as TS | bodies elided |
| Python | py, pyi, pyw | functions, methods, classes, constants, module-level vars | `import x`, `from x import y`, relative imports | bodies elided |
| Rust | rs | functions, structs, enums, traits, impl blocks, methods, consts | `use` — `crate::`, `self::`, `super::` | impl/fn bodies elided, struct/enum kept |
| Go | go | functions, methods, types, interfaces, consts | package `import` paths | fn/method bodies elided, types kept |

Partially-broken files degrade gracefully: tree-sitter recovers, valid symbols
are still extracted, and the file is reported in `parse_errors` for the
`ctx init` summary instead of aborting the index.

## Security

- Indexing **never** executes project code or evaluates scripts.
- Paths are validated before use: any user-supplied path that lexically escapes
  the project root is rejected (`path is outside the project root`), including
  through MCP (e.g. `../../../../etc/passwd`).
- No telemetry, no network calls, no external AI APIs. The engine is fully
  local and offline.

## Privacy

`ctx` reads source files, writes a local SQLite index under `.ctx/`, and spawns
`git` for change queries. Nothing leaves the machine.

## Configuration

`.ctx/config.toml` is written on `ctx init`:

```toml
[index]
exclude = ["node_modules", "target", ".git", ".ctx", "dist", "build", "vendor"]

[context]
max_tokens = 12000
max_files = 25
include_bodies = false

[watch]
enabled = true
debounce_ms = 200

src/
  parser/     tree-sitter extractors (Rust, TypeScript/JS, Python, Go) + resolver
  graph/      SQLite code graph: database, symbols, dependencies, impact
  indexing/   scanning (gitignore-aware), hashing, incremental reindex
  context/    skeletons, ranking, context package builder
  git/        diff & changed tracking via the `git` binary
  mcp/        JSON-RPC server, tools, protocol types
  commands/   CLI + MCP command implementations

cargo build
cargo test --lib --test integration --test skeleton   # unit + integration + golden
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --check