better-context, the btca skill, and searching library source instead of docs

The problem btca attacks is stale documentation in the agent's context

Coding agents answer questions about libraries from whatever those libraries' documentation said when the model was trained, or from a documentation page that has drifted since. Both failure modes look the same from the outside: confident, well-formatted code that calls a function which was renamed two majors ago.

The bet behind better-context is that the fix is not a better summary but better ground. The README's pitch is one line: ask your AI agent questions about libraries and frameworks by searching the actual source code, not outdated docs. The project is TypeScript, published as `btca` on npm, and documented at https://btca.dev. That is a narrow claim with a clear test: if the answer comes from the repository at the version in front of you, it cannot be quoting a removed API.

The delivery has changed shape several times, and the README is candid about it. The author lists what has already been tried: a custom pi agent, a new CLI, a pi extension, and a complex resource management CLI. The conclusion drawn in the README is that the local version of this probably should have been a skill from the start. That history matters for anyone evaluating it, because the artefacts of the earlier attempts are still visible in the repository while the supported path is now a single skill file.

The sandbox directory is where the searching actually happens

The mechanism is unglamorous and that is its strength. When you use btca, the agent clones or searches the relevant repositories inside `~/.btca/agent/sandbox`, and answers from what it finds there. Nothing is summarized into a model weight; the repository is on disk under your home directory and the agent reads it.

The monorepo reflects that. The root `package.json` declares workspaces of `apps/*` and `packages/*`, and the top-level entries include `apps/`, `packages/`, `skills/`, `scripts/`, and `turbo.json`. Two of the root scripts are dedicated to the sandbox itself: `sandbox`, which runs `apps/sandbox/src/index.ts`, and `sandbox:snapshot`, which runs `apps/sandbox/src/snapshot.ts`. There is also a `server` script pointing at `apps/server/src/index.ts`, which suggests the searching runs as a service the agent talks to rather than as a one-shot command.

Two consequences follow. First, disk and time are real costs: every library you ask about is a clone under your home directory, and the README gives no pruning or cache-invalidation command, so the directory grows until you remove it yourself. Second, correctness depends on which revision is cloned. The README does not say whether the skill pins a version, tracks your project's lockfile, or clones the default branch of whatever repository name the agent infers, and that question matters more than any other for a tool whose entire claim is version accuracy.

Installing the btca-local skill and the three ways to run it

The install is one command, and it installs a skill rather than a package you import:

npx skills add https://github.com/davis7dotsh/better-context --skill btca-local

After that the README describes three ways to use it, and the differences between them are worth noting because they are about context, not about features.

The first is the loosest. During any prompt you simply say "use btca", and your coding agent clones and searches the important repositories in `~/.btca/agent/sandbox`. The second invokes the skill explicitly from the agent with "/btc..." or "$btc...", depending on the agent, and the README says this feels like the old terminal interface. The third is the same invocation with a question attached, which the README describes as basically the same thing as the `btca ask` command.

What you should notice is the runtime requirement hiding in all three: your coding agent has to support skills, and the explicit form depends on which agent you use, since the prefix differs. The README names pi and codex as the agents it recommends. If your agent has no skill mechanism, none of these three paths work, and the npm package plus the `cli` script in the root `package.json`, which runs `apps/cli/src/index.ts`, are the only remaining door, with the README's warning about the rewrite applying to them too.

The rewrite warning, and what a skill-first design gives up

The first thing under the title is a warning, and it is the single most important line for an adopter. The README says btca is being rewritten right now, that the new version will overwrite the current one with full backwards compatibility, while fixing a large number of issues and improving performance, and that it is being rebuilt around pi agent and node to improve the Windows experience.

Two things follow. First, "full backwards compatibility" is a promise about the new release, not a description of the current one, so treat the current behaviour as a moving target. Second, the rewrite is being developed in a different repository, which the README links as `davis7dotsh/btca-3`. That splits the change history: work on the rewrite will not show up as commits in this repository.

The author also names the cost of the current architecture without hedging. The README says the local version being a subagent for search was actually quite nice, and that the main issue with the new system is that it clogs the main context window. That is a real trade-off stated plainly. A subagent runs its search in an isolated context, so fetched files and grep output never enter the conversation you are trying to keep small. A skill runs inline, so every repository it reads competes with your conversation for the same budget. For long research tasks that difference is the whole ballgame, and the README's closing note that the local version might get revisited later is an admission that the trade may be reversed.

Monorepo drift between package.json, the README, and the repository URL

The root `package.json` is worth reading as a document in its own right, because it does not fully agree with the README. It declares `name` as `@btca/repo`, `version` as 0.1.4, and a `description` of "CLI tool for asking questions about technologies using OpenCode". The README no longer recommends a CLI, recommends pi or codex instead, and describes the deliverable as a skill. The description is a leftover from the earlier architecture.

The repository field points at `https://github.com/bmdavis419/better-context`, while the repository you installed from is `davis7dotsh/better-context`. Two different account names for what the README treats as one project. For an end user this is harmless. For anyone vendoring, mirroring, or auditing the code it is a genuine question: which URL is authoritative, and does the one in the manifest correspond to the source you cloned?

The toolchain requirements are stated precisely, which is good. The manifest requires `bun` with `>=1.1.0` and pins `packageManager` as `[email protected]`:

"engines": {
  "bun": ">=1.1.0"
},
"packageManager": "[email protected]"

The only container in the scripts is an analytics proxy, built and run like this:

"analytics-proxy:build": "docker build -t btca-analytics-proxy apps/analytics-proxy",
"analytics-proxy:run": "docker run --rm -p 8080:8080 -e POSTHOG_CLOUD_REGION=us btca-analytics-proxy"

It publishes port 8080 and takes a `POSTHOG_CLOUD_REGION` variable set to `us`. Nothing in the README connects that proxy to any of the three ways of using the skill, so on the evidence available it belongs to the web app side of the project. If you are only installing the skill, you have no reason to run it.

A skill, a subagent, or the web app: three different approaches

The most useful comparison here is internal, because the author has already built all three and says which one he prefers.

The subagent approach, which the project had before the rewrite, isolated search in its own context. The README's own words are that it was quite nice, and the stated reason the current system is different is that the new one clogs the main context window. So the difference in approach is not capability but where the fetched source ends up: in a separate context that is discarded afterwards, or inline in the conversation that carries your task.

The web app at https://btca.dev is the third option. The README says the author can do things there that he cannot do locally and does not want to make that experience worse. That is an argument for a hosted service over a local clone when the question is heavy research rather than a quick lookup about one library, and it comes with the usual cost of a service you do not control and cannot point at a local checkout.

For comparison outside this project, the ordinary alternative is to have the agent read the library's own documentation and type definitions from the project's installed dependencies. That is free, needs no clone, and works with any agent. It fails in the specific case btca targets: when the version in your lockfile is newer than the documentation the agent remembers, or when the library has no usable docs for the part you need.

MIT licensing, no releases, and a quiet commit history

The licence is the MIT License, declared in the root `package.json` and with the text in a `LICENSE.md` file at the repository root. That permits use in commercial and closed-source work provided the notice travels with copies. This is a reading of the licence text rather than legal advice.

Maintenance information is thinner than the licence information. The repository has no GitHub releases, so there is no tag history to read and no changelog of behaviour changes; the only version marker available is the `0.1.4` in the manifest, which is a workspace version rather than a published tool version. The repository also has `SMOKE_TESTS.md` and an `AGENTS.md` at the top level, which suggests the author does write down checks, but neither is a user-facing change log.

The last push to this repository was on 2026-04-12, and the repository is not archived. Given that the README says the rewrite is under way in a separate repository, that gap is at least partly explained by where the work is happening, and the warning about the new version overwriting the current one is the part of the roadmap to plan around. A 0.1.x version number, no releases, and an in-flight rewrite is a young project with a real product behind it, and the honest reading is that adopting it means adopting a moving target on the author's promise of backwards compatibility.

Editorial conclusion

Adopt btca if your coding agent's answers about third-party libraries come from documentation that no longer matches the code, and you are willing to let a skill clone repositories into ~/.btca/agent/sandbox. Hold off if your agent runtime cannot load a skill, or if you need search results kept out of the main context window, since the README names that as the current design's main problem. Verify first by reading the rewrite warning at the top of the README, confirming whether your agent supports the /btc or $btc invocation, and checking that the repository your agent clones is the version your project actually depends on.

Frequently asked questions

Official sources

1. davis7dotsh/better-context on GitHub
2. Issues
3. License: MIT
4. Project website
5. README