Ctxo: Instructions file for Claude Code

CLAUDE.md — Ctxo

Project Overview

Ctxo is a Model Context Protocol (MCP) server that gives AI coding assistants dependency-aware, history-enriched context for codebases. It delivers "Logic-Slices" — a symbol plus all transitive dependencies, git intent, anti-pattern warnings, and change health scores — in under 500ms.

• Type: npm package / CLI tool / MCP server (stdio transport)
• Author: Alper Hankendi
• Status: 14 core MCP tools (18 with @ctxo/domain: get_domain_context, get_rule, find_shadow_specs, get_context_map), pnpm monorepo with 10 packages, 987+ tests
• Language: TypeScript (ESM-first, "type": "module")
• Runtime: Node.js >= 20

Quick Reference

# Dev (pnpm workspace)
pnpm --filter @ctxo/cli dev       # zero-build dev run
pnpm -r build                     # build all packages
pnpm -r test                      # run tests across workspace (987+ tests)
pnpm -r typecheck                 # typecheck all packages
pnpm --filter @ctxo/cli test:unit # unit tests only
pnpm --filter @ctxo/cli test:e2e  # end-to-end tests
pnpm --filter @ctxo/cli build     # build CLI package to dist/

# Usage (consumer)
npm install -g @ctxo/cli            # one-time global install (gives you the `ctxo` command)
ctxo install                        # install language plugins (interactive)
ctxo install typescript go --yes    # non-interactive install of specific plugins
ctxo install java                   # syntax tier + full-tier analyzer when JRE 11+ detected
ctxo install java --full-tier       # force full-tier analyzer install
ctxo install java --syntax-only     # skip analyzer, syntax tier only
ctxo install sql                    # T-SQL plugin (alias tsql); also turns on SQL edges at known C#, TypeScript, Java and Go call sites
ctxo install --dry-run --pm pnpm    # preview install plan with chosen pm
ctxo update                         # check + apply updates for ctxo + plugins
ctxo update --check                 # check only, exit 0
ctxo update --print                 # print install command, never execute
ctxo update --global                # force a global install
ctxo update --json                  # machine-readable output
ctxo index                          # build codebase index
ctxo index --install-missing        # auto-install detected plugins, then index
ctxo index --check                  # CI gate: fail if index stale (writes nothing, records no snapshot)
ctxo index --skip-history           # fast re-index without git history (co-changes.json is left as it is)
ctxo index --max-history 5          # limit commit history per file (intent depth only, not the co-change window)
ctxo index --files a.ts b.ts        # re-index only these files (--file <path> is the older spelling)
ctxo index --commit HEAD            # re-index the files one commit changed (the v2 post-commit hook runs this)
ctxo index --cochange-commits 500   # co-change window in commits (default 2000, or "all")
ctxo index --cochange-since 12m     # co-change window by age from HEAD (d, w, m, y)
ctxo watch                          # file watcher for incremental re-index; with @ctxo/domain also refreshes the domain artifacts
ctxo sync                           # rebuild SQLite from committed JSON
ctxo init                           # rules (+ a "ctxo domain discover" line once the domain layer is set up), skills, guard, MCP config, git hooks (post-commit v2), config + plugin install prompt
ctxo init --only <parts>            # install only these parts: rules,skills,guard,mcp,git-hooks,config,domain
ctxo init --skip <parts>            # install every part except these
ctxo init --no-guard                # does not install the safe-edit guard (full rules block unless a guard is already registered)
ctxo init --dry-run                 # list every file init would create or change; writes nothing
ctxo init --no-install              # init without plugin install prompt
ctxo status                         # show index manifest
ctxo doctor                         # health check all subsystems (--json, --quiet)
ctxo doctor --fix                   # dependency-ordered remediation (--dry-run, --yes): hook blocks, skills, the guard, rules blocks, the domain agent setup
ctxo <command> --help               # print the help; the command is not run
ctxo version                        # verbose version report (default)
ctxo --version --verbose            # version + installed plugins list
ctxo --version --json               # machine-readable version report
ctxo visualize                      # generate interactive dependency graph HTML
ctxo visualize --max-nodes 200      # limit to top 200 symbols by PageRank
ctxo visualize --no-browser         # skip auto-opening browser
ctxo blast-radius <symbolId> --json # blast radius for one symbol, JSON to stdout
ctxo gate --preview                 # preview which symbols the guard would block
ctxo gate --preview --json          # same, machine-readable
ctxo contexts [--json]              # candidate contexts: table to stderr, full contexts-view.json to stdout with --json

# Domain knowledge layer (opt-in, needs @ctxo/domain; ADR-018)
ctxo install domain                 # install @ctxo/domain at this CLI's version (globally without package.json)
ctxo init --domain                  # also set up the domain part: config defaults, registry skeleton, fold guard hooks, Cursor fold reminder (.cursor/hooks.json), skill
ctxo init --domain --boundaries by-rung|new-only|report   # boundary mode without the prompt
ctxo contexts-touched --since origin/main [--committed | --staged] [--json] [--check]   # named contexts a change touched
ctxo verify-domain --since origin/main [--boundaries by-rung|new-only|report] [--json]   # CI gate, 12 checks, exit 0/1/2; new-only fails only on violations the base lacks
ctxo domain rules --write|--check   # generated path-scoped loader rules (.claude/rules, .cursor/rules)
ctxo domain discover [--json] [--write]   # run first when adopting: tracker prefixes, rule trait keys, test folders and test-kind markers (external IDs, GitHub #N, lowercase ids: evidence only)
ctxo domain map [--json]            # context map: metrics, rung, suggested rung and criteria per context
ctxo domain shadow-specs <context> [--kinds <k,...>] [--all] [--json]   # shadow-spec candidates with fingerprints and resolutions

# Environment
DEBUG=ctxo:*                  # enable all debug output
DEBUG=ctxo:git,ctxo:storage   # enable specific namespaces
CTXO_RESPONSE_LIMIT=16384     # response truncation threshold (default 8192)