ctx

CTX Fit is a recommendation and loading layer for AI coding configurations, with the main goal of "finding the cheapest AI coding configuration that actually works on your repository," and applying the winning configuration as a reviewable change.

[Purpose] CTX Fit analyzes your code repository, tests promising AI coding configurations against real tasks in the repository, and then produces the winning configuration. It selects the "cheapest configuration that works reliably"—reliability is a hard requirement, not a tiebreaker; if no configuration beats what you already have, it will say so outright. The winner is chosen by fixed rules, not scoring: first discard all candidates below the reliability floor, then minimize attributable cost, and finally, in case of a tie, favor the simpler configuration. The LLM can explain the results, but never participates in deciding them.

[Main capabilities]

• Bare ctx fit: free, local, read-only, runs no models, costs nothing, and executes no git commands.
• --dry-run: reads repository history (read-only git queries such as log, show --name-only, ls-tree, rev-parse) to derive representative tasks; writes nothing (not to the repository, index, or any reference).
• --test --budget N: evaluates candidate configurations against the derived tasks. Spending requires both flags to be provided; with only --test and no --budget, it only plans.
• --apply: writes the winning configuration into the worktree of the current branch. The write itself runs no git commands (no staging, committing, or pushing), but before writing it requires evidence from ctx fit --test --budget N. Every change first prints all proposed modifications, unless --yes is passed to continue. Currently each plan contains only one CTX-owned artifact: .ctx/fit-configuration.json, which records the fixed model as well as the exact instructions and capability bytes that were evaluated, along with their hashes. CTX Fit does not rewrite user-authored instruction files such as AGENTS.md or CLAUDE.md; instead, it embeds their evaluated bytes into the sidecar.
• --pr: writes to the remote. It creates a branch, commits the winning configuration, pushes to origin, and opens a pull request via the GitHub CLI. Before running anything, it first prints the PR body, the files to be written, and the exact command sequence; without --yes it stops and makes no changes. Use --yes runs only these five commands in order. CTX Fit never merges.
• ctx doctor: checks prerequisites, does not contact models, does not cost money.
• The established agent-loop commands (ctx run, ctx resume, ctx sessions) are still supported and are now grouped under ctx advanced, but the original spellings remain valid.

[Usage] Install the runtime graph from the repository you want to analyze and request recommendations: ctx-init --graph uses local runtime artifacts when a cache already exists, otherwise it downloads content-addressed GitHub release assets. Each clean graph installation preloads nine project-owned, MIT-licensed, key-free fallbacks: ctx-python-testing, ctx-python-state-protocols, ctx-python-input-boundaries, ctx-python-api-compatibility, ctx-javascript-testing, ctx-rust-patterns, ctx-typescript, the ctx-python-reviewer agent, and the local ctx-core MCP server. Real evaluation requires pip install "claude-ctx[harness]", Node.js and npx (for the workspace-filesystem MCP), matching provider credentials, and Bubblewrap on Linux; a basic installation can analyze, plan, and simulate. Without matching provider credentials, --test runs in simulation mode.

[Applicable scenarios] Compare capability configurations within a single coding-agent harness (do not compare Codex, Claude Code, etc. across harnesses). Supports identifying and running repository-native verification commands for Python, JavaScript/TypeScript, Go, Rust, and Make, and uses the selected test command as the verification authority.

[Limitations] Requires CPython 3.11 or newer. The tested platforms are Linux and macOS; other POSIX systems are best-effort. Native Windows and PowerShell are not supported; on Windowsit must be run as a Linux installation in WSL2. For installable Python projects, CTX Fit builds and installs the campaign environment without network access, and its build backend and dependencies must already be available. In other ecosystems, verification is supported only when the runtime can be used from the host PATH under an isolated home and the verification dependencies are already available in the repository. Final verification uses an isolated home and no network access. Ubuntu 24.04 restricts unprivileged user namespaces, so the bwrap-userns-restrict profile for /usr/bin/bwrap must be installed and loaded; CTX uses a targeted Bubblewrap profile rather than weakening system-level security boundaries. Release qualification did not include paid live provider trials; check ctx doctor and dry run before authorizing spending.

[Privacy and telemetry] Telemetry is enabled by default in local_redacted mode, events are written to ~/.ctx/telemetry/events.jsonl, metrics are written to ~/.ctx/telemetry/metrics.jsonl, and raw prompts and queries are removed or hashed. Continuous log, trace, and metric exporters are disabled by default. Network export requires an explicit ctx-telemetry-export command or an operator-enabled exporter configuration. Local JSONL may retain raw session_id, so the spool should be treated as sensitive data.

The release version is v1.0.21, the distribution package is still claude-ctx, the installed command is ctx, and it is MIT-licensed.