DEV Community: Maciej Ciemborowicz

Brunch Gem: Isolated Development Environments for Git Branches and Worktrees

Maciej Ciemborowicz — Wed, 07 Oct 2026 16:11:54 +0000

Switching Git branches changes your code instantly. You may switch from main to a feature branch with a different database schema, different seed data, or different services running in the background. Then you switch back — and the source code follows Git, while the rest of the environment is still whatever the previous branch left behind.

With worktrees, it gets even more interesting. You may have several branches checked out at the same time:

~/my-app
~/my-app-login
~/my-app-payments

Now each of them may need its own database, containers, persistent state, and a different host port. This becomes especially relevant when IDEs or coding agents use worktrees to work on several tasks in parallel.

I wanted the development environment to follow Git:

branch -> isolated environment

Switch the branch, switch the environment. Create another worktree, give it another port and let both environments run in parallel. Come back to a branch later, and get its previous state back.

That is what Brunch does.

And the idea behind it started in 2018.

The idea started in 2018

Back then, the idea was much smaller. I wanted every feature branch in a Rails application to have its own database. If I created:

feature/login

I wanted a development database belonging to feature/login. If I switched back to:

main

I wanted the database belonging to main again.

The difficult part turned out not to be creating databases. It was knowing when Git had created, deleted, or switched a branch. At the time, I couldn't find a reliable way to do that without wrapping Git commands. And a tool that only works when everyone remembers to use a custom Git wrapper wasn't the solution I wanted. So I reserved the brunch name on RubyGems and abandoned the idea. For eight years.

The missing piece

When I returned to the problem, Git had a lower-level hook called reference-transaction.

That eventually became another project of mine, git-hooks-ext.

It translates low-level Git changes into semantic lifecycle events that other tools can react to. I wrote about the implementation in a separate article:

Git Hooks Ext: The Missing Git Callbacks for Reference Transactions

That article covers the Git internals, edge cases, worktrees, and the limits of what Git currently exposes. For Brunch, the important part is simpler: Git repository changes can now become lifecycle events. Brunch attaches development environments to those events.

The project I had abandoned in 2018 finally became practical.

What Brunch does

Brunch runs isolated development environments for Git branches and worktrees. The simplest model is:

main -> environment A

feature/login -> environment B

feature/payments -> environment C

With Docker Compose, each branch gets its own Compose project, containers, network, and named volumes. Suppose I am on main. Its environment is running. Then I switch:

git switch feature/login

Brunch stops the environment belonging to main and starts the one belonging to feature/login. Later:

git switch main

and the previous environment comes back, including its persistent volumes. The source code follows Git. Now the development environment can follow it too.

Why branch isolation matters

Imagine a Rails application where a feature branch contains new migrations. You switch to it, run the migrations, change some data, and work on the feature.

Then you switch back to main.

Your source code is back on main.

Your database isn't.

Sometimes that is fine.

Sometimes the branch has destructive migrations, incompatible schema changes, different seed data, different service versions, or state in Redis, queues, search indexes, or other infrastructure.

Git isolates the files. It doesn't isolate the runtime state surrounding them. Brunch makes that state part of the branch environment.

One worktree is the easy case

With a single Git worktree, only one branch can be checked out there at a time. That means branches can reuse the same host port. For example:

worktree
│
│ localhost:3000
│
├── main               [running]
├── feature/login      [stopped]
└── feature/payments   [stopped]

Switch branches and the active environment changes. The port does not have to. For the problem I originally had in 2018, that would already have been enough. But worktrees make things more interesting.

Worktrees change the problem

Git worktrees let several branches be checked out simultaneously:

~/my-app
~/my-app-login
~/my-app-payments

Now all three applications may need to run at the same time. They cannot all bind to:

localhost:3000

So Brunch separates two concepts:

The environment belongs to the branch.

The host port belongs to the worktree.

For example:

worktree 1
localhost:3000
├── main
└── feature/search

worktree 2
localhost:3001
└── feature/login

worktree 3
localhost:3002
└── feature/payments

In the first worktree, I can switch between main and feature/search. Both can use port 3000, because only one can be active there at a time. Meanwhile, the other two worktrees can run simultaneously on ports 3001 and 3002.

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. Brunch takes care of making the worktrees reachable on different host ports.

This becomes useful with coding agents

Worktrees have been around for a long time, but they are becoming more interesting as IDEs and coding agents use them for parallel work.

Imagine:

agent A -> feature/auth
agent B -> feature/search
agent C -> fix/payments

Git already gives each task its own working tree. But if all three tasks share the same database, containers, volumes, Redis instance, or port, the isolation is incomplete. One agent can migrate a database while another is using it. One can restart a service needed by another. Two application servers can compete for the same port.

For parallel development, the useful unit of isolation becomes:

worktree + branch + environment + persistent state + host port

That is the model Brunch is built around.

Installing Brunch

Brunch relies on git-hooks-ext for Git lifecycle events, so install that first and make sure ghe is available on your PATH.

Then install Brunch:

gem install brunch

Brunch runs on the host, so it doesn't need to be added to your application's Gemfile. For a Rails project using Docker Compose, you typically add:

Dockerfile.dev
compose.yaml
brunch.yml

A minimal brunch.yml can be as small as:

compose_file: compose.yaml

A simple Compose configuration may look like this:

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.

If the application uses PostgreSQL instead of SQLite, the same principle applies: the database service and its volume live inside the branch-specific Compose project.

Once the configuration is committed, install the hooks, check that everything is configured correctly and then activate the environment for the branch you are currently on:

brunch install
brunch doctor
brunch activate

Activation is needed because installing the hooks does not itself cause a Git lifecycle event. After that, normal branch changes can drive the environment lifecycle.

You can inspect the current state with, list environments grouped by worktree or print the port assigned to the current worktree

brunch status
brunch list
brunch port

Docker is not the abstraction

Docker Compose is the default environment manager. Brunch also supports Podman Compose. But the core idea is not:

branch → Docker container

It is:

branch → development environment

For example, Brunch can manage a local process:

manager: local_process
command: bin/dev

or project-specific commands:

manager: command

commands:
  create: bin/environment create
  start: bin/environment start
  stop: bin/environment stop
  remove: bin/environment remove

Containers are convenient because they already provide strong isolation, but they are not required by the model.

Why not just use Docker Compose manually?

You can. Brunch does not make anything possible that Docker Compose fundamentally could not do before. You can manually create separate Compose projects, volumes, and ports. You can also manually stop one environment and start another every time you change branches:

git switch feature/login
docker compose -p feature-login up -d

The interesting part is making the lifecycle follow Git automatically.

I don't want changing context to mean:

switch Git branch
remember the previous environment
stop it
choose the next project
choose its port
start it

I want:

git switch feature/login

Git already knows that the context changed.

Brunch reacts to that change.

Worktrees have one important limitation

Branches can be observed through Git's reference machinery. Worktrees cannot. Git currently has no native lifecycle hooks for operations such as creating, removing, moving, locking, or unlocking a worktree.

For now, git-hooks-ext provides:

ghe worktree ...

as a frontend for:

git worktree ...

The details of how that works are covered in my git-hooks-ext article.

For Brunch, the practical consequence is the necessity of using a wrapper if you want automatic worktree lifecycle handling. Use:

ghe worktree add -b feature/login ../feature-login

instead of plain git worktree add.

If another tool creates the worktree directly, Brunch can still be activated manually inside it:

cd ../feature-login
brunch activate

The wrapper works, but I would rather not need 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 any other tool could use ordinary:

git worktree add ...

and Git could notify interested tools that the worktree was created. No wrapper would be necessary.

I have started an RFC discussion about adding worktree lifecycle hooks to Git. If this would be useful in your workflow, please consider joining the discussion:

Worktree hooks RFC discussion

If your workflow would benefit from native worktree lifecycle hooks, describe the use case. If you have thoughts about the proposed interface, edge cases, or how such hooks should behave, add that feedback as well.

For this kind of change, it is useful to show why the functionality belongs in Git itself instead of another wrapper around git worktree.

For Brunch, native hooks would mean that IDEs and coding agents would not have to know that Brunch exists. They could use Git normally. Git would report what happened. Brunch would react.

That is the main limitation I would like to remove from the current workflow.

Eight years later

I reserved the RubyGems name for Brunch in 2018 because I wanted separate development databases for feature branches. Eight years later, the idea became broader.

A branch may imply not only different source code, but also a different database schema, data, services, volumes, and runtime configuration.

And with worktrees and parallel coding agents, several of those environments may need to exist at the same time. The difficult part was never creating another container. It was connecting the lifecycle of the environment to the lifecycle of Git.

git-hooks-ext provided that missing event layer.

Brunch finally gives those events something useful to manage.

Eight years after reserving the name, I can switch a Git branch and have the development environment switch with it.

Git Hooks Ext: The Missing Git Callbacks for Reference Transactions

Maciej Ciemborowicz — Wed, 23 Sep 2026 17:09:29 +0000

Git has had hooks for practically forever. We can stop a commit before it is created, validate a commit message, react after checkout, before push, after receiving changes on a server, or after a rebase.

The problem starts when we want to react not to a specific command, but to a change in repository state.

We want to know that a branch was created, deleted, or renamed. That a tag, stash, or remote-tracking branch changed. That HEAD became detached. Or that a worktree was created, moved, or removed.

Git does not provide most of these callbacks.

What it does provide is a much lower-level hook called reference-transaction, which observes transactions performed on references. git-hooks-ext uses exactly that mechanism and translates streams of ref updates into events that have meaning for humans and applications:

branch-created
branch-deleted
branch-updated
branch-renamed

tag-created
tag-deleted
tag-updated

remote-branch-created
remote-branch-updated

head-attached
head-detached
head-switched

Where Git does not expose even a sufficiently useful low-level event, as with the worktree lifecycle, the project wraps git worktree and observes the repository state before and after the operation.

The result is a layer that Git itself is missing: semantic callbacks on top of reference operations.

What hooks Git provides, and which ones it does not

Classic Git hooks are mostly tied to a specific workflow or command: pre-commit, commit-msg, post-commit, pre-rebase, post-merge, pre-push, post-checkout, post-rewrite, and others.

That works well if the question is:

Is the user currently making a commit?

It works much less well if the question is:

Did this particular part of repository state just change?

Git has no native branch-created, branch-deleted, branch-updated, or branch-renamed. There are no equivalent callbacks for tags, stashes, notes, replace refs, remote-tracking branches, or most special refs/* namespaces.

post-checkout looks like a partial solution for HEAD, but it is tied to checkout and switch, not to arbitrary HEAD changes.

On the server side, pre-receive and post-receive receive:

<old-oid> <new-oid> <ref-name>

but they are tied to receive-pack, so they are not general callbacks for local reference changes.

reference-transaction changes the perspective. It does not answer:

Which command did the user just run?

It is much closer to:

Which references did Git just change?

What are reference transactions?

A ref in Git is a name pointing to an object or to another reference.

refs/heads/main points to a commit. refs/tags/v1.0 may point to a commit or to a tag object. refs/remotes/origin/main represents a remote-tracking branch. refs/stash stores the current tip of the stash stack.

A branch is therefore not a special object of type "branch". From the reference subsystem's point of view, it is a name in a particular namespace. The same is true for tags and remote-tracking branches.

HEAD is a special case. Most of the time it is a symbolic reference:

HEAD -> refs/heads/main

In detached HEAD state, it points directly to a commit.

When Git changes one or more references, those operations can be performed as a reference transaction. The model is easy to see through:

git update-ref --stdin

where multiple ref updates can be prepared and then committed as one transaction.

The reference-transaction hook observes that layer. It receives the transaction state, including prepared, committed, and aborted, and in newer Git versions also preparing.

Via stdin it receives records in the form:

<old-value> <new-value> <ref-name>

For example:

0000000000000000000000000000000000000000 4fdc... refs/heads/topic

may look like a creation, while:

4fdc... 0000000000000000000000000000000000000000 refs/heads/topic

looks like a deletion.

Two non-zero values represent an update.

For symbolic refs, Git can also pass values such as:

ref:refs/heads/main

reference-transaction still does not say:

branch-created

It only provides low-level information about the ref transaction. Someone still has to assign meaning to that change.

Turning reference transactions into semantic hooks

The first step is identifying the namespace:

refs/heads/*        -> branch
refs/remotes/*      -> remote branch / remote HEAD
refs/tags/*         -> tag
refs/stash          -> stash
refs/notes/*        -> note
refs/replace/*      -> replace
refs/prefetch/*     -> prefetch
refs/bisect/*       -> bisect
refs/rewritten/*    -> rewritten
refs/worktree/*     -> worktree-specific ref

Unknown names below refs/* can still produce generic ref-created, ref-updated, and ref-deleted events. Refs outside refs/*, if they pass through the ref backend, can be classified as root-ref-*.

The second step is classifying the update itself.

At first glance, the rules look simple:

old	new	semantics
zero	value	creation, or an update without a specific expected old value
value	zero	deletion
value A	value B	update

The important complication is that an all-zero old value does not necessarily mean that the ref did not exist before the transaction.

Git can also use zero when an update does not require a particular previous value. In other words:

zero -> OID

can represent both a newly created ref and a ref that already existed but was updated without an old-value constraint.

That means the payload received at committed is not always enough to reconstruct the actual previous repository state.

The useful detail is that the previous state may still be available earlier.

During prepared, the transaction has not yet been committed, so a ref whose old value arrived as zero can still be inspected.

git-hooks-ext uses that phase to recover the previous value before it disappears.

If a ref has an all-zero old value, the bridge asks Git for its current state and records whether it exists, whether it is symbolic, and what it points to. It uses Git's own commands rather than reading loose ref files directly, so it does not assume that the repository uses the files backend instead of reftable.

The temporary state is stored in a private git-hooks-ext-state directory inside the Git administrative directory, resolved through:

git rev-parse --git-path git-hooks-ext-state

At committed, the bridge matches the snapshot to the transaction and restores missing old values before classifying the changes.

At aborted, the snapshot is discarded.

That makes the semantic distinction much stronger.

For example:

zero -> OID
refs/heads/topic

can be classified as branch-created if refs/heads/topic really did not exist before the transaction.

If the ref did exist and pointed somewhere else, the same low-level shape can instead be classified as an update.

The difference matters in real workflows.

Consider:

git stash push

The first stash creates refs/stash.

A later:

git stash push

updates the existing ref.

If Git reports:

zero -> new-OID refs/stash

the committed payload alone cannot tell those cases apart. By preserving the previous state during prepared, the bridge can correctly emit:

stash-updated

for the second operation rather than treating it as another creation.

The same recovery helps with operations such as:

git notes append
git notes remove

Removing a note changes the notes ref; it does not necessarily delete that ref. With the real previous value available, the operation can be classified as note-updated instead of being mistaken for a creation or deletion.

The principle is simple:

Observe the facts while they still exist, but react only after the transaction commits.

Rename

Rename is more interesting because reference-transaction has no rename operation.

If we see:

OID A -> zero refs/heads/old
zero -> OID A refs/heads/new

then git-hooks-ext can interpret that as branch-renamed, but only when the match is unambiguous.

This matters because deleting one branch and creating another at the same commit may look exactly like renaming one branch to the other at the ref-transaction level.

For example:

OID A -> zero refs/heads/old
zero -> OID A refs/heads/new

could correspond to:

git branch -m old new

but it could also represent two logically independent operations:

delete old
create new at the same commit

reference-transaction describes state changes, not user intent.

There is no field saying:

operation=rename

That is why rename detection is deliberately best-effort.

There is another ambiguity as well. Suppose the transaction contains:

OID A -> zero refs/heads/foo
OID A -> zero refs/heads/bar

zero -> OID A refs/heads/baz
zero -> OID A refs/heads/qux

Which branch was renamed to which?

Was it:

foo -> baz
bar -> qux

or:

foo -> qux
bar -> baz

The ref transaction itself cannot tell us.

A semantic layer should not invent an answer when multiple interpretations fit the same facts.

HEAD

HEAD allows a few more semantic events.

A transition from a direct OID to:

ref:refs/heads/main

can be recognized as:

head-attached

The inverse can become:

head-detached

A symbolic transition such as:

ref:refs/heads/main
->
ref:refs/heads/topic

can become:

head-switched

Every observable value change of HEAD also emits:

head-updated

The prepared-phase snapshot is useful here as well.

If Git reports the old value as zero, the bridge can preserve whether the previous HEAD value was symbolic or direct before the transaction commits.

That makes ordinary detach operations such as:

git checkout --detach

observable even when the committed payload alone would not contain enough information to classify the transition.

Attachment and symbolic target changes still depend on Git actually exposing the corresponding transactions. The same recovery mechanism also helps classify symbolic remote HEAD updates and deletions where those transactions are available.

The same rule applies here as everywhere else:

Missing values can sometimes be recovered. Missing refs cannot.

If Git reports a ref but omits its old value, the earlier state may still be observable.

If Git never reports the ref at all, git-hooks-ext does not guess that it existed.

Why semantic hooks are still post-factum

Even though git-hooks-ext observes some state during prepared, the semantic events are emitted only after committed.

prepared is used to collect facts.

It does not emit:

branch-created

before Git has actually created the branch.

Only after the transaction commits are the collected facts combined with the final payload and classified.

So branch-created means:

The committed transaction was classified as a branch creation from the information Git made observable.

It does not mean:

Git is about to create a branch.

The events describe repository state.

They are not another layer for rejecting Git transactions.

Why the state after the transaction matters too

Recovering the previous value is not always sufficient.

Some internal ref maintenance operations can produce records that look like deletions even though the logical ref still exists.

Packed-ref maintenance is one example.

That means a potential deletion should sometimes be confirmed after the transaction commits.

If the ref existed before the transaction, the payload resembles a deletion, but the ref still exists afterward, the bridge must not emit a false:

branch-deleted

or:

tag-deleted

This second check separates actual logical state changes from backend maintenance.

The same mechanism makes it possible to recover real deletions from commands such as:

git branch -D
git tag -d
git remote prune

even when Git reports the equivalent of:

zero -> zero

The bridge knows what the ref pointed to before the transaction and confirms that it is absent afterward.

No command wrapper is required for branch, tag, stash, notes, or checkout operations.

Worktree: where reference transactions stop being enough

A worktree can have its own HEAD, index, and worktree-specific refs, but a worktree itself is not a ref.

Consider:

git worktree add -b feature ../feature

Git may create refs/heads/feature, which can produce branch-created.

But that does not imply worktree-created: the same branch could have been created with:

git branch feature

and a detached worktree can be created without creating any branch at all:

git worktree add --detach ../experiment

The distinction becomes clearer for other operations.

git worktree remove can delete a worktree while leaving its branch unchanged.

git worktree move can change only the worktree path and administrative metadata.

git worktree lock, unlock, prune, and repair also operate on metadata that is not itself a ref.

Some git worktree commands can trigger ref transactions, but those transactions describe reference changes, not the lifecycle of the worktree itself.

The same distinction applies to refs/worktree/*.

Events such as:

worktree-ref-created
worktree-ref-updated
worktree-ref-deleted

concern worktree-specific references.

They do not mean:

worktree-created
worktree-removed
worktree-moved

The wrapper

Since there is no hook covering the worktree lifecycle, git-hooks-ext provides another observation point:

ghe worktree <command> ...

Before a mutating operation it records:

git worktree list --porcelain -z

then forwards the arguments to the real git worktree.

If Git succeeds, it reads the state again and derives events from the difference:

worktree-created
worktree-removed
worktree-moved
worktree-locked
worktree-unlocked
worktree-pruned
worktree-repaired

The event is based on an observed state change, not merely on the command that was invoked.

The trade-off is that:

ghe worktree remove ../feature

can generate:

worktree-removed

while:

git worktree remove ../feature

bypasses the wrapper entirely.

Unlike branch, tag, stash, notes, and checkout operations, the wrapper is genuinely necessary here because the worktree lifecycle cannot be reconstructed from reference transactions alone.

Git: bugs, RFCs, and the limits of observability

Even when an operation is fundamentally a reference change, Git does not always report it through reference-transaction in a way that allows its semantics to be reconstructed.

That is why the project has a separate compatibility matrix.

Real Git versions are built and executed, real commands are run, and their raw reference-transaction payload is inspected.

The matrix covers Git 2.27 through 2.55, both the files and reftable backends, and commands such as branch, tag, fetch, remote, notes, and stash.

Tests also cover concurrent transactions, aborted operations, corrupt snapshots, and storage failures.

The coverage gate checks 100% line, function, and region coverage.

This makes it possible to distinguish bugs in git-hooks-ext from cases where Git itself never provided enough information.

`git branch -m`

To detect:

git branch -m old new

as:

branch-renamed

both sides are needed:

OID -> zero refs/heads/old
zero -> OID refs/heads/new

In some Git and ref-backend combinations, Git reports the deletion of the old branch but not the corresponding creation of the destination ref.

With only:

OID -> zero refs/heads/old

there is no way to determine the new name.

The prepared-phase snapshot does not solve this.

A snapshot can recover the previous value of a ref that appears in the transaction.

It cannot recover the name of a destination ref that Git never reports.

That distinction is fundamental.

A missing value for a known ref can often be recovered.

A missing ref cannot be reconstructed without guessing.

I reported the issue together with a proposed fix:

git branch -m omits the destination ref from the reference-transaction hook

`git branch -D` and `git tag -d`

Deletion has a different shape.

For commands such as:

git branch -D

and:

git tag -d

some Git versions may report the equivalent of:

zero -> zero

which does not reveal the previous OID in the transaction payload itself.

But unlike the missing destination of a rename, that information still exists earlier.

During prepared, the ref can be inspected before it disappears.

The bridge records the previous value and, after committed, confirms that the ref is actually gone.

That makes it possible to emit the correct:

branch-deleted

or:

tag-deleted

even when the final payload is insufficient on its own.

Interestingly:

git update-ref -d refs/heads/topic

can provide enough information directly.

That shows that the limitation belongs to particular Git code paths rather than to the reference-transaction model itself.

Similar differences appear with remote prune, stash, notes, and HEAD operations.

The guiding rule remains the same:

Recover observable facts, but do not manufacture missing history.

Config-based hooks

Git's hook subsystem itself has also started to change.

For years, a hook essentially meant an executable file such as:

.git/hooks/pre-commit
.git/hooks/reference-transaction

Git 2.54 introduced config-based hooks.

More importantly for git-hooks-ext, the system allows wrappers to invoke event names that Git itself does not know about:

git hook run --allow-unknown-hook-name branch-created -- ...

That fits the architecture well:

Git
↓
reference-transaction
↓
git-hooks-ext
↓
branch-created
↓
Git's standard hook infrastructure

On Git 2.54 and newer, the bridge can therefore run as a config-based hook.

On Git 2.53 and older, the project still installs the classic:

.git/hooks/reference-transaction

hook.

What comes next

The obvious solution would be to add dozens of hooks directly to Git core:

branch-created
branch-deleted
branch-renamed
tag-created
tag-deleted
stash-updated
...

I am not convinced that this is the best boundary.

What matters more is that the lower layer provides a complete, correct, and consistent description of ref changes.

If:

git branch -m

changes two refs, the hook should see both.

If:

git branch -D

deletes an existing ref, its previous state should be observable.

If symbolic HEAD changes target, observers should see both the previous and new state.

The semantics should also remain consistent across the files and reftable backends.

If that contract is strong enough, the semantic layer can stay outside Git core:

Git:           old, new, ref

git-hooks-ext: branch-created, tag-deleted, head-switched

The semantic layer can use both the transaction payload and state that is still observable during prepared, while still emitting its events only after the transaction commits.

Worktrees remain the exception because their lifecycle does not fit into the reference-transaction model.

There, either native lifecycle hooks will eventually be needed, or the wrapper will remain the correct observation point.

Conclusion

Long term, the project does not need Git to gain fifty new hooks.

It mostly needs one strong contract:

Every real reference change should be completely and correctly observable through reference-transaction.

That does not necessarily mean that every useful fact has to appear directly in the committed payload.

Some information can be observed earlier during prepared, preserved for the duration of the transaction, and then used after the transaction commits.

But the boundary should remain clear.

If Git exposes a fact, either directly or through repository state that is still observable during the transaction, git-hooks-ext can translate it.

If Git never exposes the changed ref at all, as in some rename cases, the semantic layer should not invent it.

Git reports the facts.

git-hooks-ext translates them.

The user decides what should happen next.

That is the callback layer I was missing in Git.

The jokes about vibe coding aged poorly

Maciej Ciemborowicz — Tue, 22 Sep 2026 19:03:56 +0000

Three years ago, I wrote a short article after I managed to build a terminal Spotify client using nothing but Ctrl+C and Ctrl+V. Back then, in What To Focus On When Programming With Gpt4?, I predicted what would happen in the near future, and so far those predictions have turned out to be fairly accurate. At the time, I often encountered skepticism and opinions that AI would never be able to program well because it would always make mistakes and hallucinate. Meanwhile, the way we build software has changed very quickly. Less and less code is written entirely by hand, while an increasing share of the work is being done by AI tools and agents. Knowing a specific programming language is also becoming less important. What matters much more is the ability to read and evaluate code, understand architecture, and clearly define what actually needs to be built. In that sense, AI has already taken over a large part of the work that programmers used to do manually. The role of the programmer itself is gradually shifting toward that of an architect, a product developer, and, put simply, someone who coordinates and supervises the work of AI agents.

Later came the jokes about vibe coding. And those jokes have aged very badly. I am using the term fairly loosely here. I do not mean blindly accepting whatever an agent produces without reading the code or understanding the project. I mean building software where most of the implementation is produced by AI and the programmer focuses mainly on requirements, architecture, constraints, review, and feedback.

Sure, you can create an application this way that scales terribly and is difficult to maintain. But this can be addressed to a large extent. Practices around using AGENTS.md appeared, followed later by SKILLS. In 13 Programming Books as AI Agents Rules, I described one way of turning software-engineering habits into rules for coding agents. These rules do not solve the problem by themselves, but they can prevent a large class of recurring problems. You can use them to instruct the agent how it should organize the code, which patterns it should use, what layers the project should have, and how much emphasis we want to put on bounded contexts, which, in my opinion, are currently crucial in larger software projects. By following these rules, I can create projects with much higher code quality than the ones I used to write manually, when I constantly had to balance implementation speed against code quality.

For a vibe-coded project to have high code quality, however, it is worth focusing on a few things that are rarely discussed. You can put very strong guardrails around an agent by imposing strict rules on how it works and forcing it into a certain engineering discipline. I do this through a demanding quality check, not only in CI, but already in a pre-commit hook.

The quality check consists of several steps. First, I run a linter. At this stage alone, you can get rid of not only ugly code, but also many unnecessarily long blocks and methods. This is very cheap in terms of CPU usage and execution time. I also run the linter with automatic fixes enabled, which takes some work away from the agent and makes the process deterministic.

The next step is checking for code smells. Not everything can be measured, and a code smell reported by a static analyzer does not automatically mean that the code is bad. But many suspicious patterns can be detected mechanically. If one appears, the agent has to at least reconsider the code and either refactor it or make a conscious decision that the warning is acceptable. This happens already at commit time, before these problems have a chance to accumulate.

Without this step, they can grow very quickly. I measured this while building a project from a backlog of 80 tasks without any structural feedback for the agent. The most common problem was DuplicateMethodCall. For example, AI can produce something like this:

def report_summary(report)
  "Average: #{report.calculate_statistics.average}, median: #{report.calculate_statistics.median}"
end

This performs the same potentially expensive operation twice. Depending on what the expression does, repeated calls like this can be merely unnecessary or actually expensive. It is often better to make the intermediate result explicit:

def report_summary(report)
  statistics = report.calculate_statistics

  "Average: #{statistics.average}, median: #{statistics.median}"
end

The point is not that every duplicate method call is a serious problem. The useful part is that the agent gets immediate feedback about something worth looking at instead of repeating the same pattern throughout the project.

The second most common problem is TooManyStatements. The model tends to keep adding more steps to an existing method instead of stopping for a moment and thinking about whether the responsibilities should be split. So it can produce something like this:

def process_order(order)
  validate(order)
  calculate_total(order)
  apply_discount(order)
  save_order(order)
  send_email(order)
  log_order(order)
  update_metrics(order)
end

Depending on the context, it may be clearer to separate these responsibilities:

def process_order(order)
  prepare_order(order)
  persist_order(order)
  finalize_order(order)
end

def prepare_order(order)
  validate(order)
  calculate_total(order)
  apply_discount(order)
end

def persist_order(order)
  save_order(order)
end

def finalize_order(order)
  send_email(order)
  log_order(order)
  update_metrics(order)
end

And in a larger application it may make sense to extract separate objects:

def process_order(order)
  OrderPreparer.new(order).call
  OrderRepository.new.save(order)
  OrderFinalizer.new(order).call
end

Of course, splitting a method only to satisfy a static analyzer does not automatically make the code better. It can just as easily create unnecessary indirection. The value of this check is that it forces the agent to stop and reconsider the structure instead of endlessly extending whatever method already happens to exist.

The list of problems it produces is much longer, though, and it is worth seeing what it looks like on a chart:

Enforcing these checks at commit time therefore does not guarantee good code, but it prevents many simple structural problems from silently accumulating.

The next stage is test coverage. A large number of tests obviously does not give us confidence that the tests themselves are correct. The same is true for 100% coverage. I do not treat it as a quality metric, because coverage only tells us that the code was executed, not that the right behavior was actually verified. I treat it as a mechanical constraint that prevents the agent from adding completely untested paths without noticing. It also forces the agent to look at the tests whenever a refactoring changes behavior or makes some branch unreachable. For that reason, requiring 100% coverage is still a useful safeguard, especially when agents are modifying the code repeatedly.

At the end of the pre-commit process, all tests are run. Later, the process is repeated in CI, which gives us confidence that the same checks also pass outside the local environment. Which, of course, is nothing new.

What is new is the economics of this feedback loop. A strict pre-commit hook can be annoying for a human developer, because every failure means stopping, going back to the code, fixing it, and trying again. An agent does not really care. It gets an error, changes the code, runs the check again, and repeats the process until it passes. This makes checks that used to feel overly strict much more practical.

Outside of the quality check, most of my supervision is necessary in the context of code organization at the application structure level: layers, directories, files, boundaries, and their organization. SKILLS are obviously very helpful here as well. This is especially important when starting a project and when we have some idea of how large it is going to become. Based on that, we choose an architecture appropriate for the project, and if the project grows more than we initially expected, we supervise the refactoring.

This is also where I think the programmer's role is changing the most. Writing the implementation is becoming the cheap part. The more important part is defining the constraints under which the implementation is created: the architecture, boundaries, tests, static analysis, conventions, and feedback loops. Instead of describing every line of code, we increasingly describe the environment in which the code is allowed to exist.

The jokes about vibe coding aged poorly. Not because blindly generated code suddenly became good, but because we learned how to put enough engineering around the agent that blindly trusting it is no longer necessary.

DEV Community: Maciej Ciemborowicz

Brunch Gem: Isolated Development Environments for Git Branches and Worktrees

The idea started in 2018

The missing piece

What Brunch does

Why branch isolation matters

One worktree is the easy case

Worktrees change the problem

This becomes useful with coding agents

Installing Brunch

Docker is not the abstraction

Why not just use Docker Compose manually?

Worktrees have one important limitation

The missing piece belongs in Git

Eight years later

Links

Git Hooks Ext: The Missing Git Callbacks for Reference Transactions

What hooks Git provides, and which ones it does not

What are reference transactions?

Turning reference transactions into semantic hooks

Rename

HEAD

Why semantic hooks are still post-factum

Why the state after the transaction matters too

Worktree: where reference transactions stop being enough

The wrapper

Git: bugs, RFCs, and the limits of observability

git branch -m

git branch -D and git tag -d

Config-based hooks

What comes next

Conclusion

The jokes about vibe coding aged poorly

`git branch -m`

`git branch -D` and `git tag -d`