> The full benchmark is hard in a way that matters to me: the agents get the main behavior right much more often than they keep all tested behavior working as requirements change
So, it's like... software development? 90% of bugs come from unintended consequences of changes after the fact. There's a couple decades of design lessons people had to learn to keep this number low. The agents don't follow those lessons.
Good programmers rely on structure and reinforcement to prevent themselves from introducing bugs. Today that structure is a combination of software frameworks, SDLC gates, and system design patterns. For example, most any Python programmer can reliably churn out a Django app as a Microservice and be fairly sure it won't be that hard to make, or result in tons of unexpected bugs. The reason isn't that it's some perfect software design. It's that prescribed methods in themselves are bumper lanes, keeping you on track. A few of you may remember what programming was like before popular open source frameworks, or maybe you've worked on proprietary big-iron mega-projects. Left entirely to one's own devices, programmers can make a mess of things. Give them a formal structure and suddenly there's less to go wrong.
I wouldn't sit around waiting for models to become uber-programmers. Instead I'd treat 'em like humans, and enforce the structures we know have better results. You can try to impose good design as skills (ciembor/agent-rules-books) but the model will still do things its own way. That's why coding harnesses need to intervene and explicitly enforce the structure/framework/bumper lanes. Basically we need 1,000 different Pi extensions that will intervene as the agent codes in order to enforce the correct design. Otherwise we will forever be chasing some "perfect coding rlhf", and still the model will blunder into corners.
Brunch Gem: Isolated Development Environments for Git Branches and Worktrees
Introduction
Switching branches and worktrees in Git changes the code we're working on. This allows us to work on multiple things at the same time. But what it doesn't switch is the environment.
Feature branches, bug-fix branches, and branches used for code review or refactoring often have different migrations. Different seeds. Different data that we create to test our solutions. They may also have different background jobs or different gems in their Gemfiles.
In general, branches and worktrees should have separate environments.
When working with Ruby on Rails, we already have three environments by default: development, test, and production. But what we really need is a separate environment for each branch.
That's exactly what the Brunch gem provides.
It not only lets us manage these environments, but also ties them to Git using hooks.
The idea dates back to 2018
Back then, the scope was much narrower. I wanted to create a gem that would isolate databases, creating a separate database for each branch, so I wouldn't have to keep dropping and recreating the database every time I switched branches.
I reserved the name Brunch on RubyGems.
The problem, however, was that Git lacked the necessary hooks. Of course, I could have built a wrapper around Git, but I decided that such a solution was unlikely to catch on.
So I abandoned the idea. For eight years.
This year, I discovered that Git has had a reference-transaction hook since 2020, and that it could be used for this purpose. To make it work, I also had to create git-hooks-ext, which I described in a separate article.
The idea was back.
What does Brunch do?
Brunch runs isolated environments for Git branches and worktrees. It connects them to Git hooks so that environment lifecycles can follow branch changes automatically.
Each worktree is assigned a port on which the application runs. Within a single worktree, that port is used by whichever branch is currently active.
Let's take a situation where we have just one worktree:
worktree
│
│ localhost:3000
│
├── main [running]
├── feature/login [stopped]
└── feature/payments [stopped]
Containers are automatically created and removed when branches are created and deleted. When switching branches, the container belonging to the previously active branch is stopped, and the container for the branch we're switching to is started.
With multiple worktrees, things get a little more complex because several branches can be active at the same time.
Among other things, this allows multiple AI coding agents to work on different branches in parallel.
That's why each worktree gets its own port:
worktree 1
localhost:3000
├── main
└── feature/search
worktree 2
localhost:3001
└── feature/login
worktree 3
localhost:3002
└── feature/payments
Brunch exposes the assigned port through BRUNCH_PORT, so Docker Compose can use it like this:
services:
web:
ports:
- "127.0.0.1:${BRUNCH_PORT}:3000"
Rails can keep listening on port 3000 inside the container, and Brunch takes care of making the worktrees reachable on different host ports.
Installing Brunch
Brunch relies on git-hooks-ext, so install that first and make sure ghe is available on your PATH.
Then install Brunch:
gem install brunch
Brunch doesn't need to be added to your application's Gemfile, although you can also add it to the development group.
For a Rails project using Docker Compose, you typically add:
- Dockerfile.dev
- compose.yaml
- brunch.yml
A minimal brunch.yml:
compose_file: compose.yaml
Here's an example configuration for Ruby on Rails:
services:
web:
build:
context: .
dockerfile: Dockerfile.dev
command: >
sh -c 'bin/rails db:prepare &&
exec bin/rails server -b 0.0.0.0 -p 3000'
volumes:
- .:/rails
- storage:/rails/storage
ports:
- "127.0.0.1:${BRUNCH_PORT}:3000"
volumes:
storage:
The bind mount exposes the current worktree to Rails. The named volume belongs to the branch-specific Compose project. And BRUNCH_PORT maps the application to the port assigned to the worktree.
Once you've committed the configuration, install the hooks, check that everything is configured correctly, and then activate the environment for the branch you're currently on:
brunch install
brunch doctor
brunch activate
Activation is needed because installing the hooks does not itself trigger a Git lifecycle event.
Now you can inspect the current state, list Brunch environments, or print the port assigned to the current worktree:
brunch status
brunch list
brunch port
Worktrees must use a wrapper
Branches can be observed through Git's reference machinery, but Git still has no native lifecycle hooks for worktree operations.
For now, git-hooks-ext provides a wrapper: ghe worktree ....
Instead of plain git worktree add, use:
ghe worktree add -b feature/login ../feature-login
If another tool creates the worktree directly, Brunch can still be activated manually:
cd ../feature-login
brunch activate
The wrapper works, but I'd rather rely entirely on Git hooks without having to use it.
The missing piece belongs in Git
The clean solution is for Git itself to expose worktree lifecycle hooks. Then IDEs, coding agents, Brunch, and other tools could simply use git worktree add. No wrapper would be necessary.
There is an ongoing RFC discussion about adding worktree lifecycle hooks to Git. If this would be useful in your workflow, please join the discussion:
Worktree hooks RFC discussion
Links
- Brunch on GitHub
- Brunch on RubyGems
- git-hooks-ext on GitHub
- Git Hooks Ext: The Missing Git Callbacks for Reference Transactions
- Worktree hooks RFC discussion
3 reactions · 3 comments
Mentions
spotify-cmd: command line + TUI for the Spotify Library
spotify-cmd: Command line + TUI for the Spotify Library
> The full benchmark is hard in a way that matters to me: the agents get the main behavior right much more often than they keep all tested behavior working as requirements change So, it's like... software development? 90% of bugs come from unintended consequences of changes after the fact. There's a couple decades of design lessons people had to learn to keep this number low. The agents don't follow those lessons. Good programmers rely on structure and reinforcement to prevent themselves from introducing bugs. Today that structure is a combination of software frameworks, SDLC gates, and system design patterns. For example, most any Python programmer can reliably churn out a Django app as a Microservice and be fairly sure it won't be that hard to make, or result in tons of unexpected bugs. The reason isn't that it's some perfect software design. It's that prescribed methods in themselves are bumper lanes, keeping you on track. A few of you may remember what programming was like before popular open source frameworks, or maybe you've worked on proprietary big-iron mega-projects. Left entirely to one's own devices, programmers can make a mess of things. Give them a formal structure and suddenly there's less to go wrong. I wouldn't sit around waiting for models to become uber-programmers. Instead I'd treat 'em like humans, and enforce the structures we know have better results. You can try to impose good design as skills (ciembor/agent-rules-books) but the model will still do things its own way. That's why coding harnesses need to intervene and explicitly enforce the structure/framework/bumper lanes. Basically we need 1,000 different Pi extensions that will intervene as the agent codes in order to enforce the correct design. Otherwise we will forever be chasing some "perfect coding rlhf", and still the model will blunder into corners.
手里的AI编码工具想直接升级成编程大师？有个叫AGENTS Book Rules的开源项目值得一看。🚨 13本经典编程书的核心原则，如今可以直接喂给AI了。 从《代码整洁之道》到《领域驱动设计》，再到《重构》——这些必读书的精髓，统统整理成了开箱即用的规则文件。 🔗 GitHub：ciembor/agent-rules-books 每本书都配了三个版本： 完整版：理论控首选，底层逻辑拉满 精简版：日常搬砖，拿来就用 极简版：上下文窗口紧张时救命用 按任务类型分得明明白白： 日常代码质量 → 稳 架构设计 → 有章法 遗留代码处理 → 拆解到位 Claude Code、Codex、Cursor都能直接用。规则文件复制进项目，AI秒变资深老鸟。 别等了，不然你的代码还活在石器时代。
Brunch Gem: Isolated Development Environments for Git Branches and Worktrees Introduction Switching branches and worktrees in Git changes the code we're working on. This allows us to work on multiple things at the same time. But what it doesn't switch is the environment. Feature branches, bug-fix branches, and branches used for code review or refactoring often have different migrations. Different seeds. Different data that we create to test our solutions. They may also have different background jobs or different gems in their Gemfiles. In general, branches and worktrees should have separate environments. When working with Ruby on Rails, we already have three environments by default: development, test, and production. But what we really need is a separate environment for each branch. That's exactly what the Brunch gem provides. It not only lets us manage these environments, but also ties them to Git using hooks. The idea dates back to 2018 Back then, the scope was much narrower. I wanted to create a gem that would isolate databases, creating a separate database for each branch, so I wouldn't have to keep dropping and recreating the database every time I switched branches. I reserved the name Brunch on RubyGems. The problem, however, was that Git lacked the necessary hooks. Of course, I could have built a wrapper around Git, but I decided that such a solution was unlikely to catch on. So I abandoned the idea. For eight years. This year, I discovered that Git has had a reference-transaction hook since 2020, and that it could be used for this purpose. To make it work, I also had to create git-hooks-ext, which I described in a separate article. The idea was back. What does Brunch do? Brunch runs isolated environments for Git branches and worktrees. It connects them to Git hooks so that environment lifecycles can follow branch changes automatically. Each worktree is assigned a port on which the application runs. Within a single worktree, that port is used by whichever branch is currently active. Let's take a situation where we have just one worktree: worktree │ │ localhost:3000 │ ├── main [running] ├── feature/login [stopped] └── feature/payments [stopped] Containers are automatically created and removed when branches are created and deleted. When switching branches, the container belonging to the previously active branch is stopped, and the container for the branch we're switching to is started. With multiple worktrees, things get a little more complex because several branches can be active at the same time. Among other things, this allows multiple AI coding agents to work on different branches in parallel. That's why each worktree gets its own port: worktree 1 localhost:3000 ├── main └── feature/search worktree 2 localhost:3001 └── feature/login worktree 3 localhost:3002 └── feature/payments Brunch exposes the assigned port through BRUNCH_PORT, so Docker Compose can use it like this: services: web: ports: - "127.0.0.1:${BRUNCH_PORT}:3000" Rails can keep listening on port 3000 inside the container, and Brunch takes care of making the worktrees reachable on different host ports. Installing Brunch Brunch relies on git-hooks-ext, so install that first and make sure ghe is available on your PATH. Then install Brunch: gem install brunch Brunch doesn't need to be added to your application's Gemfile, although you can also add it to the development group. For a Rails project using Docker Compose, you typically add: - Dockerfile.dev - compose.yaml - brunch.yml A minimal brunch.yml: compose_file: compose.yaml Here's an example configuration for Ruby on Rails: services: web: build: context: . dockerfile: Dockerfile.dev command: > sh -c 'bin/rails db:prepare && exec bin/rails server -b 0.0.0.0 -p 3000' volumes: - .:/rails - storage:/rails/storage ports: - "127.0.0.1:${BRUNCH_PORT}:3000" volumes: storage: The bind mount exposes the current worktree to Rails. The named volume belongs to the branch-specific Compose project. And BRUNCH_PORT maps the application to the port assigned to the worktree. Once you've committed the configuration, install the hooks, check that everything is configured correctly, and then activate the environment for the branch you're currently on: brunch install brunch doctor brunch activate Activation is needed because installing the hooks does not itself trigger a Git lifecycle event. Now you can inspect the current state, list Brunch environments, or print the port assigned to the current worktree: brunch status brunch list brunch port Worktrees must use a wrapper Branches can be observed through Git's reference machinery, but Git still has no native lifecycle hooks for worktree operations. For now, git-hooks-ext provides a wrapper: ghe worktree .... Instead of plain git worktree add, use: ghe worktree add -b feature/login ../feature-login If another tool creates the worktree directly, Brunch can still be activated manually: cd ../feature-login brunch activate The wrapper works, but I'd rather rely entirely on Git hooks without having to use it. The missing piece belongs in Git The clean solution is for Git itself to expose worktree lifecycle hooks. Then IDEs, coding agents, Brunch, and other tools could simply use git worktree add. No wrapper would be necessary. There is an ongoing RFC discussion about adding worktree lifecycle hooks to Git. If this would be useful in your workflow, please join the discussion: Worktree hooks RFC discussion Links - Brunch on GitHub - Brunch on RubyGems - git-hooks-ext on GitHub - Git Hooks Ext: The Missing Git Callbacks for Reference Transactions - Worktree hooks RFC discussion