# stevesolun/ctx: find the cheapest AI coding setup that passes your repo's own tests

> CTX Fit profiles a repository, evaluates candidate AI coding configurations against tasks derived from its history, and writes the cheapest configuration that clears a reliability floor. The catch is that a real evaluation needs more than the base install.

**stevesolun/ctx** — Repo-aware recommendations for skills, agents, MCP servers, and model harnesses. Use your own inventory or the shipped 79,958-node graph with 68,494 skills, 467 agents, 10,790 MCPs, and 207 harnesses.

- Repository: https://github.com/stevesolun/ctx
- Website: https://stevesolun.github.io/ctx/
- Stars: 587 · Forks: 69
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/stevesolun-ctx

## The problem CTX Fit addresses: configuration choice as a cost decision

A repository accumulates an AGENTS.md, a CLAUDE.md, a tool config, and a pile of installed skills. Nobody knows which of those files and skills actually change outcomes on this codebase, and nobody knows what the current arrangement costs per task. The README frames the goal as finding the cheapest AI coding setup that actually works on your repo, and the design treats reliability as a gate rather than a tie-break.

The audience is a team that already runs an agent harness against a real repository and wants a defensible answer to whether a cheaper configuration would still pass. That is a narrower audience than the project's topic list suggests. The topics mention knowledge graphs, Obsidian, and micro-skills, but the README's release scope is explicit that comparison happens within one harness, so an engineer shopping for a harness will not get that question answered here.

## How the selection rule works, and why the LLM does not get a vote

The winner is chosen by a fixed rule. Candidates below the reliability floor are discarded, the remainder are minimized on attributable cost, and ties break toward the simpler configuration. An LLM may explain a result; the README states it never decides one. That ordering matters: a configuration that is cheap but flaky is not a candidate at all, not a cheap candidate with a warning.

Verification is repository-native. CTX Fit recognizes verification commands for Python, JavaScript/TypeScript, Go, Rust, and Make, and treats the selected test command as the verification authority. The example output in the README shows how commands are attributed to their source, such as a test command read from pyproject.toml with high confidence and a build command with medium confidence. Confidence is part of the report, which is the honest way to present a command inferred from a config file rather than declared.

The free profile also produces an AI agent readiness score with named components: verification, instructions, environment, CI enforcement, tool safety, and context tractability. In the abridged example the repository scores 91/100, and the highest-impact improvement is committing a dependency lockfile for a stated gain of 9 points. Treat that score as a checklist against your own repository rather than a benchmark against other projects, since the README presents it as a single-repository profile.

## Installing claude-ctx and running the free repository profile

The package is published as claude-ctx and requires Python 3.11 or newer. The README gives the install and first run in three lines.

```bash
pip install --upgrade claude-ctx
cd /path/to/my-project
ctx fit
```

Bare ctx fit is free, local, and read-only. The README states it runs no model, spends nothing, and issues no git commands at all. You should see the detected languages, the current AI coding setup including instruction files and installed skills, the verification commands with their source and confidence, the readiness score broken into components, and a short list of improvements with point values.

For scripting, add --json for machine-readable output. To see the shape of a full evaluation without running one, use --dry-run, which plans the campaign. The README notes that --dry-run does read your history, running read-only git queries (log, show --name-only, ls-tree, rev-parse) to derive representative tasks, and writes nothing to the repository, the index, or any ref.

## What a real evaluation costs you in setup, not just money

Spending requires both flags: ctx fit --test --budget N. The README states that --test without --budget only plans. Before that, ctx doctor reports whether a real evaluation can run on the machine at all.

A real evaluation needs the extra install, Node.js with npx for the workspace-filesystem MCP, a matching provider credential, and Bubblewrap on Linux. The base install can profile, plan, and simulate. Without a matching provider credential, --test runs in simulation, which the README says proves the pipeline but not your repository. With a credential but a missing live prerequisite, CTX refuses the run before trial setup. A simulated result is refused as evidence for --apply and --pr.

Ubuntu 24.04 adds a specific hurdle. The distribution restricts unprivileged user namespaces, and installing bwrap does not prove it can start the network-disabled namespace CTX uses. The README's fix is Ubuntu's packaged, scoped AppArmor profile for /usr/bin/bwrap.

```bash
sudo apt update
sudo apt install bubblewrap apparmor-profiles apparmor-utils
if [ ! -e /etc/apparmor.d/bwrap-userns-restrict ]; then
  sudo install -m 0644 \
    /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \
    /etc/apparmor.d/bwrap-userns-restrict
fi
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict
ctx doctor
```

The README is explicit that this is administrator-visible host policy for every /usr/bin/bwrap caller, not a CTX-private setting, and that the commands preserve an existing local profile rather than overwriting it. ctx doctor proves the path with a bounded /bin/true probe in the same no-network namespace, executing no repository code and calling no model. That is a heavier ask than most developer tools make, and it is the part of adoption that will consume a change-approval conversation.

## Where CTX Fit is the wrong tool, and what it does not prove

The build constraint is the sharpest limitation. For an installable Python project, CTX Fit builds a campaign environment and installs it without network access, so the build backend and dependencies must already be available without downloading them. In the other ecosystems, verification is supported only when the runtime is usable from the host PATH under an isolated home and the verification dependencies are already available in the repository. Final verification runs without network access, so a user's package caches are not a supported dependency source. A repository that resolves dependencies at install time will not fit this model without preparation.

There is also a stated epistemic boundary. The README says the evidence is for normal development and does not prove that deliberately hostile code cannot deceive its own test runner. If your threat model includes adversarial code in the repository, a passing campaign is not a security result.

Finally, the release notes state that qualification did not include a paid live-provider trial, and they direct the reader to inspect ctx doctor and the dry run before authorizing spend. That is a candid disclosure, and it means the first paid run on your machine is also your first paid run on this tool.

## How --apply and --pr differ, and what they leave untouched

ctx fit --apply writes the winning configuration into your working tree, on whatever branch you are standing on. It prints every proposed change first and stops there unless you pass --yes. The README states that the write itself runs no git command: nothing is staged, committed, or pushed. Reaching that point does run git, because --apply is refused without evidence from ctx fit --test --budget N, and deriving the tasks for that evaluation uses the same read-only queries --dry-run uses.

Each proposed change names the file and whether CTX Fit is creating or modifying it. The README says that today every plan contains exactly one CTX-owned file, which sets a clear expectation: this is not a tool that rewrites your instruction files wholesale. For a review workflow, --pr produces the winner as a pull request instead of a working-tree change.

The refusal rule is the design decision worth noting. A simulated result is not accepted as evidence for either output path, so you cannot get a written configuration out of a run that never touched a provider.

## Alternatives and the difference in approach

The obvious alternative is to do this by hand: pick a model and a set of skills, run your test command a few times, and keep what seems fine. The difference is that manual comparison has no fixed decision rule and no reliability floor, so a cheap configuration that passes twice gets adopted on the strength of two runs. CTX Fit discards candidates below the floor before cost is considered, and it refuses to write anything without executed evidence.

A second alternative is the harness-level comparison an engineer might expect from a tool with these topics. The 1.0.21 release scope rules that out: CTX Fit compares capability configurations within one coding-agent harness and does not compare Codex, Claude Code, or other harnesses against one another. If your actual question is which harness to standardize on, this project does not answer it.

A third path is a general benchmark suite run against your repository. Benchmarks measure a fixed task set across many repositories; CTX Fit derives tasks from your own history and treats your selected test command as the verification authority, so the result is specific to your codebase and not comparable across projects.

## Maintenance, licence, and upgrade cost

The repository is not archived. The last push was on 2026-08-31, and the most recent release, v1.0.21, was published on 2026-08-15, with graph artifacts for the same version published on the same day. The previous release, v1.0.20, dates from 2026-06-29. That cadence is recent enough to read as ongoing work, and the README's release-scope note is versioned to 1.0.21, so behaviour described here should be checked against the changelog after an upgrade.

The licence is MIT, declared in pyproject.toml and present as a LICENSE file at the repository root. MIT is permissive, so the usual obligations are attribution and inclusion of the licence text in distributions; I am not giving legal advice, and the NOTICE file at the root is worth reading alongside LICENSE before you redistribute.

The upgrade cost is concentrated in the extras. The base install has five runtime dependencies (markdown, networkx, numpy, pymdown-extensions, pyyaml) and can profile, plan, and simulate. Moving to real evaluations means the harness extra, Node.js with npx, a provider credential, and Bubblewrap on Linux, and on Ubuntu 24.04 the AppArmor profile has to be installed and reloaded. That is host-level configuration, so an upgrade that changes the namespace requirements will land on whoever administers the machine, not on the developer running ctx fit.

## Conclusion

Adopt CTX Fit if you already have a repository with a deterministic test command and you want a cost decision about AI coding configuration that is backed by executions rather than opinion. Do not adopt it expecting a harness comparison: the 1.0.21 release notes state it compares capability configurations within one coding-agent harness, not Codex against Claude Code. Before authorizing any spend, run ctx doctor to confirm the live prerequisites, then ctx fit --test --budget N with a small budget and read the dry-run plan, because the release notes say qualification did not include a paid live-provider trial.

## FAQ

### Is ctx fit free to run?

Yes. The README states that bare ctx fit is free, local, and read-only: it runs no model, spends nothing, and issues no git commands at all. Spending starts only with ctx fit --test --budget N, which requires both flags.

### What does ctx doctor check before I spend money?

It reports whether a real evaluation can run on the machine, including the live prerequisites such as a matching provider credential and Bubblewrap on Linux. On Ubuntu 24.04 it proves the Bubblewrap path with a bounded /bin/true probe in the same no-network namespace, executing no repository code and calling no model.

### Does ctx fit --apply commit or push anything?

No. The README states the write itself runs no git command: nothing is staged, committed, or pushed. It writes the winning configuration into your working tree on whatever branch you are standing on, and prints every proposed change first unless you pass --yes.

### Can CTX Fit compare Claude Code against Codex?

No. The 1.0.21 release scope states that CTX Fit compares capability configurations within one coding-agent harness and does not compare Codex, Claude Code, or other harnesses against one another.

## Sources

- [License: MIT](https://github.com/stevesolun/ctx/blob/main/LICENSE)
- [Project website](https://stevesolun.github.io/ctx/)
- [README](https://github.com/stevesolun/ctx/blob/main/README.md)
- [Releases](https://github.com/stevesolun/ctx/releases)
- [stevesolun/ctx on GitHub](https://github.com/stevesolun/ctx)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/stevesolun-ctx