The One Weird Git Trick That Makes Coding Agents More Effect-ive

May 11, 2026

One of the most common questions we get on the Effect team in the era of AI-assisted coding is how to get coding agents to write good, idiomatic Effect code.

Our answer is always the same: give your agent real library code to learn from. More specifically, give the agent access to the Effect source code.

Stop Making Agents Guess

If you follow us on social media, you’ve probably heard us recommend cloning the Effect repository directly into your project. The advice sounds strange until you remember what coding agents are actually good at: reading and exploring code (crazy, I know).

They’re substantially less effective when working from documentation written for humans. When source code is available, an agent can explore it the way it was designed to: by following usage patterns, tracing abstractions, and learning from existing patterns. More importantly, this approach isn’t specific to Effect - it works for any external software your application depends on.

The most practical method for making external software explorable by your coding agent is to simply vendor the project’s Git repository directly into your application’s codebase.

In this post we will explain why this works, why git subtrees are a good fit for it, and how to set it up without making your project harder to manage.

Why Having the Source Code Available Matters

A common approach when utilizing coding agents is to rely on web search / web fetch to allow the agent to retrieve information about external dependencies when required. In practice, however, the agent will only have access to isolated code snippets without the surrounding structure, often requiring it to repeatedly fetch code it has already seen or until it has enough information to proceed. This is token inefficient and leads to highly fragmented context.

Documentation has a different limitation - it usually explains what an API or library does but not how it is actually used across a codebase. Coding agents rely on patterns and examples, not descriptions.

Having source code available locally allows us to remedy both issues at once. When the agent is unsure about how to use a particular API or library, it can explore the actual implementation of that codebase just like any other part of your project.

This is also why relying on code in node_modules usually isn’t enough. The code is often compiled or flattened, which removes the structure that makes it useful to read. Even if a particular library does publish their uncompiled source, most coding agents are deoptimized from exploring node_modules or other gitignore directories in the first place.

Why Git Subtrees Instead of Git Submodules?

It might seem intuitive to simply use git submodule to vendor external software into a project. Submodules are (unfortunately) a familiar feature of git for most developers, keep the repositories cleanly separated, and allow pinning external codebases to a specific commit.

And to be honest, submodules are fine - they accomplish the end goal which is allowing the agent direct access to external source code. But in our opinion there are features of git submodule that make them quite annoying for this specific purpose.

They require explicit initialization when cloning a project, which (if you are like me) can be really easy to forget to do
They also introduce a layer of indirection (your repo now “points” to another repo instead of just containing the source code)
They require additional metadata to be tracked in git (i.e. the .gitmodules file)

Instead, git subtree allows you to directly nest one repository inside another as a subdirectory. Once a subtree is created, it behaves like any other directory in your project. That means both the engineers and coding agents working on a project can ignore the fact that a subtree is even in use.

Adding a Git Subtree

You can add an external dependency to your project under a dedicated directory (such as repos/effect) with a single command:

1
git subtree add \
2
  --prefix=repos/effect \
3
  https://github.com/Effect-TS/effect.git \
4
  main \
5
  --squash

The --prefix flag controls where the repository will live inside your project. We recommend keeping all vendored projects under a single directory (i.e. repos/). This makes it much easier to, for example, add a one-liner to your AGENTS.md to explore repos/effect when writing Effect code.

It’s also worth calling out the --squash flag - without it, you will clone the entire history of the external repository into your own project’s git history. For larger projects this can mean thousands of commits. Including --squash in the command ensures that everything is collapsed into a single commit.

Updating a Git Subtree

When you want to pull in changes from an external project, you can simply run:

1
git subtree pull \
2
  --prefix=repos/effect \
3
  https://github.com/Effect-TS/effect.git \
4
  main \
5
  --squash

Each update shows up as a single commit, which keeps things predictable and easy to review.

Configuring Your Editor

Ok, now you’ve got a few external repositories sitting in your repos/ directory and you’re ready to let your agents --dangerously-skip-permissions.

The problem is that you (the human-in-the-loop) probably still want to be able to use your code editor from time to time. On those rare occasions where you are hands-on in a code editor instead of a prompt box, you probably do not want your editor suggesting search results and/or auto-imports from these external repositories.

In VSCode, you can exclude your repos/ directory from search, file watching, and auto-import suggestions with a few small tweaks to your project’s .vscode/settings.json:

1
{
2
  "typescript.preferences.autoImportFileExcludePatterns": [
3
    "repos/**"
4
  ],
5
  "javascript.preferences.autoImportFileExcludePatterns": [
6
    "repos/**"
7
  ],
8

9
  "files.exclude": {
10
    "repos/**": true
11
  },
12

13
  "files.watcherExclude": {
14
    "repos/**": true
15
  },
16

17
  "search.exclude": {
18
    "repos/**": true
19
  }
20
}

Other editors can be configured similarly, but your mileage may vary.

Configuring the Agent

Now that you’ve got one or more subtrees vendored into your project, you will need to make the agent aware that they are there, and how to use them. This is usually done through the AGENTS.md file (or whichever file your coding agent uses).

The important thing is to be explicit about both the location and the intended usage. You do not want the agent treating vendored repositories as part of your application codebase. You want it to read them as reference material. For example:

1
## Vendored Repositories
2

3
This project vendors external repositories under @repos/
4

5
  - Use vendored repositories as read-only reference material when working with related libraries
6
  - Prefer examples and patterns from the vendored source code over generated guesses or web search results
7
  - Do not edit files under @repos/ unless explicitly asked
8
  - Do not import from @repos/ - application code should continue importing from normal package dependencies

You can also make this more specific for the libraries you vendor, for example:

1
When writing Effect code, inspect @repos/effect/ for examples of idiomatic usage, tests, module structure, and API design. Treat it as the source of truth for Effect patterns.

If you’ve created a subtree for Effect v4, you can also explicitly tell the agent to always read @repos/effect/LLMS.md before writing any Effect code.

Creating Pattern Files

Another useful pattern is to ask the agent to create a small reference file for a particular data type or module from the vendored codebase. This gives the agent a project-local artifact it can come back to later instead of rediscovering the same patterns repeatedly.

For example, you might ask:

1
Review the implementation, tests, and documentation for `Schema` in `@repos/effect`.
2

3
Create a file at `agent-patterns/effect-schema.md` that illustrates the most important patterns an agent should follow when writing Schema code in this project.
4

5
Include:
6
- Common constructors and combinators
7
- Encoding and decoding examples
8
- Transformation patterns
9
- Error handling patterns
10
- Examples copied or adapted from the Effect codebase
11
- Notes about what to avoid

The resulting file does not need to be exhaustive. It should be a practical reference that captures the idioms the agent is most likely to need when working in your application code.

The Trade-Off

Vendoring repositories does increase the size of your project, and you take on a bit of responsibility for keeping them up to date. It’s not free.

But the payoff in terms of improved output quality from your coding agents when using external dependencies is, in our opinion, well worth it. Especially in an era where humans are doing less and less of the actual hands-on coding ourselves.