Give a coding agent the real library source next to your code, and it stops guessing from docs. It reads the patterns instead.
The Trick
The Effect team published a small idea with a big payoff in The One Weird Git Trick That Makes Coding Agents More Effect-ive: vendor the source of the libraries you depend on directly into your repo, under something like repos/, using git subtree. One command pulls in the whole library as readable files:
git subtree add --prefix=repos/effect \
https://github.com/Effect-TS/effect.git main --squash
The --squash flag collapses the library’s entire history into a single commit, so you import the code without dragging in ten thousand foreign commits. Updating is symmetric:
git subtree pull --prefix=repos/effect \
https://github.com/Effect-TS/effect.git main --squash
Now the agent can open repos/effect like any other directory. It greps, traces call sites, and reads actual implementations of the abstractions it is being asked to use. That is the entire move. It sounds almost too plain to matter. It matters a lot.
Why Docs and Web Search Lose
Documentation tells an agent what an API does. It rarely shows how the API is used in anger across a real codebase. A doc page for Effect.retry describes the signature and gives a toy example. It does not show you the fifteen places inside Effect itself where retry composes with Schedule, timeouts, and typed errors. The patterns live in the source, not the prose.
Web search is worse for a coding agent, even though it feels like the obvious tool. When an agent searches the web mid-task it pulls back fragmented context: a Stack Overflow answer from 2022, a blog post on an older major version, a GitHub issue with half the relevant code elided. Each fetch costs tokens, the results contradict each other, and the agent has to reconcile versions it cannot verify. You are paying premium tokens to assemble a blurry, possibly stale picture of something that already exists, fully correct and version-matched, inside node_modules.
Which raises the obvious question: why not just point the agent at node_modules? Because what lives there is usually compiled, bundled, and flattened. The .d.ts files give you types but not idioms. The .js is transpiled down and stripped of the structure a human or an agent would learn from. Vendored source is the original TypeScript, with comments, tests, and the directory layout the maintainers actually reason in. That is the difference between reading a decompiled binary and reading the codebase.
Pattern Density Is the Real Asset
I keep coming back to a framing from information theory for coding agents: context is only useful in proportion to its signal density. A library’s source is one of the densest, highest-signal artifacts you can hand an agent, because every file is a worked example written by people who understand the abstraction better than any blog author.
When I work in Effect, the hardest part is never the syntax. It is knowing the idiomatic composition: when to reach for a Layer, how errors should be modelled in the E channel, where Scope belongs. That knowledge is implicit. It is distributed across hundreds of real usages. An agent with the source in-repo can find those usages by grepping for the exact combinator and reading three real call sites in seconds. An agent without it produces code that typechecks and is still subtly un-idiomatic, the kind of thing that compiles and makes a maintainer wince. This is the same reason few-shot examples from your own codebase beat generic ones. Vendored source is few-shot prompting where the examples are the library authors’ own code.
The Read-Only Guardrail
The one failure mode is the agent treating vendored code as application code and “helpfully” editing it. Two cheap guardrails close that off.
First, exclude the directory from your editor and search tooling so it does not pollute results or get auto-formatted:
// .vscode/settings.json
{
"files.watcherExclude": { "**/repos/**": true },
"search.exclude": { "**/repos/**": true }
}
Second, and more important, tell the agent explicitly in AGENTS.md or your CLAUDE.md what the directory is for:
## repos/
Read-only vendored source of our dependencies. Use it to learn
idiomatic patterns and trace implementations. Never edit these
files. They are reference material, not application code.
This is a small instance of a principle I trust generally: agents behave when the boundary is stated, not assumed. A directory full of code with no declared intent invites the agent to start refactoring it. A single sentence reframes it as a library you read.
When Not To Do This
This is not free, so I do not reach for it on every dependency.
- Repo weight. A full library subtree can be large. I only vendor the few dependencies whose idioms are hard, not every package in the tree. For Effect, yes. For
lodash, no. - Pinning drift. The subtree tracks a branch, not your installed version. If you vendor
mainwhile you run a released version, the agent may learn patterns from unreleased APIs. Pull the matching tag, or accept that the source is directional rather than exact. - Shallow dependencies. If a library is small or you already know its idioms cold, the source adds tokens without adding signal. Vendor where the learning curve is real.
The decision rule is the same one I apply to abstraction generally: spend the cost where the entropy is high. Vendor the libraries whose correct usage is genuinely hard to infer from types alone.
Why This Compounds
The deeper point is that retrieval is the wrong default for a coding agent working in a typed ecosystem. The correct, version-matched, idiomatic answer almost always already exists on disk. Searching the web for it is choosing a noisy, lossy copy over the original. Vendoring flips the default: the agent learns from primary sources sitting next to the code it is writing, in the same language, at the same version, with the same conventions.
It is a one-line git subtree add and one paragraph in AGENTS.md. For the libraries that actually carry your architecture, it is one of the highest leverage context moves I know.
References
- The One Weird Git Trick That Makes Coding Agents More Effect-ive – The original Effect team post
- git-subtree documentation
