build.golfnext.com

Delete the setup guide

Johann Böhler — Thu, 27 Aug 2026 00:00:00 +0000

Think about the last time you cloned a repository you’d never worked in before.

You read the README. It told you to install a JDK, and you had the wrong one, so you went and found the right one. It told you to install Node, and the version file said 18 while the lockfile clearly wanted 20. Somewhere near the bottom there was a line saying cp .env.example .env and then, in a smaller font, fill in the values. Fill them in from where? From a colleague. So you asked in Slack, someone pasted you a block of KEY=value lines, and now a production-adjacent credential lives in a chat history forever: searchable, backed up, exported to whatever compliance tool the company bought last year.

Nobody set out to build that. It’s what happens when the instructions live in a document instead of in the repository.

I’m the tech lead at GolfNext, a Danish company that builds software for golf clubs, and my first post on this blog was an inventory of what I’d walked into. Sixty-eight repositories, four product lines, thirteen years of accumulated technology choices: Java and Maven and Spring, Kotlin and Gradle, Node, Python, PHP, JavaFX, React Native. Starting work in one of them cold took somewhere between two and six hours depending which one you picked, and I set myself a target of five minutes from clone to running code.

This is the first serious attempt at that. Two tools, both by the same person, jdx. mise puts the right tools on your PATH, fnox puts the right secrets in your environment, and those are the two halves of one problem. mise is boring and widely used. fnox is neither of those things yet, and I’ll come back to that. What’s interesting is what falls away once both are in place, and what it does to the coding agents I have running in these repositories all day.

It’s mise as in mise en place, the kitchen thing. Pronounced “meez”, /miːz/, one syllable, no -uh on the end. You want that settled before you say it out loud in a meeting. fnox is easier: Fort Knox with most of the letters knocked out, so “eff-nox”, and the name tells you what it’s for.

Half one: the tools

If you’ve used nvm or pyenv you know the shape: declare a version, cd in, get that version. The difference is that mise doesn’t care what the version is of.

# .mise.toml
[tools]
java = "21"
maven = "latest"
node = "lts"
python = "latest"
gitleaks = "latest"

That’s a JVM, a build tool, a JavaScript runtime, a Python and a secret scanner (gitleaks) in one file, installed by one command, on your PATH only inside this directory tree. Add mise activate to your shell profile and even the command goes away: cd into the repo and the tools are there, cd out and they aren’t. It also sets the environment variables that go with them, so JAVA_HOME points at the JDK this project pinned rather than whatever your operating system decided last.

“Version manager” undersells this, and I want to be specific about why. The expensive part of a polyglot estate is the switching, not any single stack. You spend a morning in a Spring service, then move to an Android repo, then a small Python tool, and each hop is a chance for your shell to be wrong in a way that produces a confusing error rather than an obvious one. In one of our repositories a newer system JDK doesn’t fail loudly. It breaks a mocking library during tests, several layers down, with a message that has nothing to do with Java versions. That’s an hour of somebody’s life, and you pay it again every time a new person joins or a laptop gets replaced.

A per-language tool can’t help, because the problem is between languages.

One nuance you may as well steal instead of discovering. We deliberately let some of those versions float: latest for the scanner, lts for Node. What a build is made of is pinned in the CI workflow, and that pin is the one dependency automation watches and raises pull requests against. If we pinned the same versions in .mise.toml as well, we’d have two places to keep in step, and one of them would quietly fall behind. We know this because it had already happened, a .mise.toml claiming Node 22 while all four workflows said 24. Only one file gets to be authoritative, and it’s the workflow.

The JDK is the exception, pinned hard in both places on purpose. A wrong major version there is exactly the mocking-library failure above, and I’d rather keep two files in step than rediscover that error at four in the afternoon. Everything else floats.

The part I didn’t expect to care about

Every repository has a handful of things you do to it: build it, test it, run it, format it. In a Maven project that’s mvn spring-boot:run -Dspring-boot.run.profiles=local. In a Gradle project it’s ./gradlew and a task name with four words glued together. In a Node project it’s whatever the scripts block says this week. None of it is hard. All of it is something you have to look up when you’re in an unfamiliar repo, which is exactly when you have the least patience for looking things up.

mise lets you put those verbs in the same file as the tools:

[tasks.build]
description = "Package the artifact"
run = "mvn clean package -B"

[tasks.test]
description = "Full test suite (integration tests need Docker)"
run = "mvn clean test -B"

[tasks.serve]
description = "Run the API on http://127.0.0.1:5001 (starts the stack first)"
depends = ["stack:up"]
run = "mvn spring-boot:run -Dspring-boot.run.profiles=local"

[tasks."stack:up"]
description = "Start the local database and the mocks. Idempotent"
run = "docker compose up -d --wait"

So the interface becomes mise run build, mise run test, mise run serve. In the Android repository next door the same verbs sit on top of Gradle instead, and one of them wraps a four-word task name I still can’t type from memory. Doesn’t matter. mise tasks lists what a repository can do, with descriptions, and the answer is in the repo rather than in a wiki page that stopped being true in 2023.

Two small conventions have earned their place. A bare verb is the common case and verb:qualifier narrows it: test and test:signer, stack:up and stack:down and stack:clean. There’s also always an escape hatch task that wraps the underlying build tool directly, so anything the curated list doesn’t cover is still one command away:

[tasks.mvn]
description = "Any Maven command, with this repo's JDK and environment"
run = "mvn"

That escape hatch matters for the second half of the story.

Half two: the secrets

This is the part I actually wanted to fix.

The .env.example pattern is so common that it reads as a best practice. It’s a convention that gave up. Look at what it asks of a team.

A new developer copies a file of empty keys and then has to source real values from somewhere the repository can’t tell them about. In practice that means a person, which means a chat message, and now a secret exists in a second system with different retention rules and different access control than the one you chose on purpose. When a value rotates, every laptop holding the old one is silently wrong until someone notices, and the failure usually shows up as a confusing 401 rather than a message saying “your credential is four months stale”. When a new secret is added, everyone else’s .env is incomplete and nobody is told. And the file itself sits in your working directory in plaintext, one bad git add -A away from being committed, which is why every repository that uses this pattern also has a .gitignore line that somebody could delete.

The alternative isn’t complicated. Put the values in a secret store you already trust, put references to them in the repository, and let each developer’s own identity decide whether they resolve.

That’s fnox. Here’s the stage config for a service, committed, with no values anywhere in it:

# fnox.stage.toml
env = "exec"

[providers]
store = { type = "…" }

[secrets]
DB_PASSWORD    = { provider = "store", value = "DB_PASSWORD",    if_missing = "error" }
PAYMENT_API_KEY = { provider = "store", value = "PAYMENT_API_KEY", if_missing = "error" }
SIGNING_KEY    = { provider = "store", value = "SIGNING_KEY",    if_missing = "error" }

The type is the only line that’s specific to you, and I’ve left it blank on purpose, because which store you use is the least interesting decision in the whole setup. fnox speaks to Vault, 1Password, SOPS, and the managed secret stores of the big clouds. We took the one our provider already gave us, for the boring reason that we were paying for it and it already had access control we trusted. Everything else in the file is the same whichever way you go.

What that file buys:

The repository documents its own secrets. Every name a service needs is listed in one place, in git, with review history. New secret? It’s in the file, it arrives with git pull, and the next run either finds it or fails loudly because of that if_missing = "error". Nobody has to be told anything.

Rotation stops being an event. Change the value in the store; every machine picks it up on its next run. There’s no fleet of stale copies.

Access goes back to being an authorization question. Whether you can run against a given environment is decided by your identity in the secret store, not by whether someone remembered to forward you a file. Revoking someone becomes a permissions change instead of a hope that they delete a file.

And there’s a dry run. fnox check tells you whether every declared secret resolves for you, without printing any of them. It’s the fastest possible answer to “is it me or is it broken”, which is the question that eats onboarding days.

Then one deliberate restraint. That env = "exec" line means secrets are never injected into an interactive shell, only into the environment of a child process fnox launches. fnox will happily do the other thing; there’s a mode that puts everything into your shell the moment you enter the directory. We don’t use it. I don’t want every process started from that directory to inherit production-adjacent credentials, and that includes editors, and it includes the coding agents I have running in there most of the day. Scoping secrets to fnox exec -- is the whole difference between “the build can see the signing key” and “everything on my machine can see the signing key”.

That last part is what I’d underestimated. With nothing on disk and nothing in the shell, a secret only exists inside a process that something deliberately started, which turns “what can the agent reach” into an ordinary permission decision. Deny it fnox and the handful of tasks that call it, allow it everything else, and it can read the repository, build, test and format without a credential ever entering its context.

Then the hole, which I’d rather name than have someone else name for me. fnox reads the store as me, using credentials that are sitting on my machine regardless. An agent with a shell doesn’t need fnox at all; it can query the store with the provider’s own CLI. Denying fnox on its own closes the front door of a building with no walls. What does the real work is that the same allowlist doesn’t include that CLI, and that what’s within reach from a dev machine is stage rather than production. An agent that can edit .mise.toml can also write itself a task that shells out to anything. The deny rule is a fence, not a proof.

But hold it against what it replaces: a .env file sitting in the working directory in plaintext, readable by anything that can call cat, which is every agent anyone has ever run. Runtime-only injection plus a deny rule is, as far as I can tell, about as good as this currently gets.

Where the two halves meet

Individually these are two decent tools. Together they remove a category of manual step.

Because mise tasks are just commands, a task can be fnox exec -- something:

[tasks.gradle]
description = "The escape hatch from earlier, now with the build secrets loaded"
run = "fnox exec -- ./gradlew"

[tasks.secrets]
description = "Check that every build secret resolves for you"
run = "fnox check"

[tasks."serve:stage"]
description = "Run locally against stage secrets (needs cloud access)"
depends = ["stack:up"]
run = "fnox -c fnox.stage.toml exec -- mvn spring-boot:run"

Now mise run gradle :app:assembleRelease is a signed release build, and the person running it never types the word fnox, never learns which of the build’s inputs are secret, and never holds a copy of any of them. Nobody has to remember which commands need secrets. The task knows.

There’s one in there for anyone who lives in an IDE:

[tasks.ide]
description = "Launch the IDE with the build secrets in its environment (macOS)"
run = 'fnox exec -- open -na "Android Studio" --args "$PWD"'

An IDE knows nothing about any of this, so a build started from inside it can’t sign. Launch the IDE through fnox and its Gradle inherits the environment. It’s one line, and it’s the difference between a working release build and a signing error nobody can explain, so it stays in the file. I don’t reach for it much myself: most of my day is a terminal, a prompt and an agent doing the typing. That’s a preference, not a recommendation, and the task is there for whoever wants the other thing.

Then there’s the split by environment. One file each, the same variable names in all of them, different values behind those names:

fnox.toml         # local
fnox.stage.toml   # stage
fnox.prod.toml    # production

A task points at the file it needs. Anything that belongs to an environment goes in that environment’s file, so nobody can pair stage credentials with local settings by accident.

The local one is the file I’d point at if you only read one. It declares almost no secrets, because everything a local run needs already has a harmless default committed in the repository: a local database, a mock in front of anything external, obviously fake keys for the paid services. A fresh clone boots and serves for someone with no access to the secret store at all, and anything that would reach a real provider fails authentication rather than doing something expensive. Access buys you stage. It isn’t the price of entry.

Committing references means scanning for values

Committing secret references only works if you’re sure nothing real ever slips in beside them. So the same setup carries a scanner, and mise installs it without anybody being asked to:

[tools]
gitleaks = "latest"

[hooks]
postinstall = "git config core.hooksPath .githooks"

mise trust is the first thing anyone runs, and the first mise run after it installs the toolchain, which is also what fires the postinstall hook and points git at a directory holding a pre-commit secret scan. It arrives as a side effect of the step they were taking anyway, rather than a separate instruction that people skip.

The hook scans staged content only, so it’s fast, and if mise isn’t on the PATH it skips with a loud warning instead of failing. A GUI git client’s environment is often minimal, and blocking someone’s commit over a PATH problem is a good way to teach them to pass --no-verify forever. CI scans the same commits again after the push.

And the deployments

People tend to assume this bit works differently than it does.

Our deployed environments don’t run fnox. The platform they run on reads the same values from the same store itself and hands them to the process as ordinary environment variables. No application code knows about any of this. Nothing in the runtime imports a library, and no build has to be told which environment it’s for.

That’s deliberate. The store is the source of truth. fnox is how a human reads that truth, with their own credentials, on their own machine, and the deployment reads the same truth with the machine’s identity. The two never diverge, and the application on both sides just sees environment variables like it always did.

What it doesn’t fix

The honest version, then.

You still have to install mise, and put mise activate in your shell profile. That’s a real setup step and I’m not going to pretend it away. It’s one step, it’s the same step in all sixty-eight repositories, and it never goes stale, which is three things the paragraph it replaced could not say.

Docker is still yours. mise installs tools, not daemons. Our local stacks need containers, and the first-run experience for anyone without Docker configured is still a manual step and a download measured in gigabytes. Same for Xcode, which remains its own weather system.

Getting the tooling right removes the stupid part of a cold start. It does nothing about the hard part, which is understanding what the service actually does. That’s still reading code, and it still takes days.

You’re adding two dependencies to every developer’s day. mise is mature and widely used. fnox is young. We’ve committed real workflows to it, and if it stalls we’d be doing a migration. I think that’s a reasonable bet: the file is declarative, the values live in a store we’d keep either way, and the fallback is a shell script that reads the same parameters. But it is a bet, and pretending otherwise would be dishonest.

One line in that config deserves a careful review. fnox can be told to run a command that logs you in to the store when your session has expired, which is genuinely convenient and also means a committed config file now specifies something that executes on every reviewer’s laptop. Review that line the way you’d review a CI workflow.

There’s also a failure mode with a misleading error. Point the provider at the wrong account and what comes back is “not found”, which reads like a missing secret rather than a wrong identity, and sends people looking in entirely the wrong place. Both of our files carry a comment naming exactly which account the credentials have to resolve to.

Where we actually are

Two repositories fully on fnox. A handful more on mise. Sixty-odd to go, most of which will never need the secrets half at all.

I haven’t put a stopwatch on it and I’m not going to invent a figure I didn’t measure. The shape of the answer is clear enough though. On a machine that’s been through this once already, with mise installed and the toolchain cached and Docker running, a clone to a serving API is under a minute. Comfortably. What’s left of the old two-to-six hours is all first-time-on-this-laptop cost: downloading a JDK, pulling images, installing mise itself. You pay that once, rather than once per repository, and that second part is the whole difference from where we started.

In the repositories where this landed, the setup section of the README went from a list of things to install and a paragraph about asking a colleague down to this:

mise trust          # once, to allow this repository's config
mise run serve

Two lines, and the second one is the one you wanted anyway. The first is mise asking whether you actually trust a config file that’s about to install software and set environment variables, which, given that this file can now run commands on your machine, is a prompt I’m glad exists.

The pattern generalises well past our particular stack, which is why I think it’s worth writing down rather than filing as an internal chore.

Then delete the setup guide, because it’s finally lying about how much work there is.

Four products, sixty-eight repositories

Johann Böhler — Wed, 12 Aug 2026 00:00:00 +0000

I started at GolfNext on Monday the 3rd of August, at 8:00. I’d pictured a quiet office and twenty minutes of standing around. Most of the team was already in and in a good mood about it. I’d brought a cheesecake, which we ate after lunch, because I’ve been in Denmark long enough to know that turning up with cake is not really optional here.

Peter, who started the company in 2012, had Claude open before I’d found my desk, working through the accounts and permissions I’d need. Small thing to notice on a first morning. It told me more than an onboarding deck would have.

The first post on this blog was a letter I wrote to myself before I’d signed anything, full of predictions about a company I’d visited once. This is where I hold it up against what’s actually here. Most of what follows isn’t really about me though. It’s the company I want to describe: what we build, what sits underneath it after thirteen years, and what we’re planning to do about that.

What GolfNext builds

If you’ve never thought about the software a golf club runs on, here’s the shape of it. A club is a small business wearing several hats at once. There’s a pro shop, a driving range, memberships, a booking system, and more and more often a simulator bay or two. The booking system handles tee times, which, since I had to learn this myself, have nothing to do with tea. A tee time is the slot a group is booked to start their round on the first hole, and the whole day at a club is arranged around that grid.

Historically each of those hats arrived as its own box, from its own vendor, with its own software attached. Buy the dispenser, get the dispenser company’s system, whether or not it suits how you run your club.

Our position is the opposite of that. Your hardware and your infrastructure stay yours, and you stay free to pick the software that fits. We want to be open to any integration, so whatever management system a club already uses to run its tee times, the aim is to work with it rather than ask them to throw it out. Freedom to choose, power to connect.

Self-service kiosks. A digital reception that runs around the clock. Green fees, rentals, pro shop purchases, all without someone standing behind a counter. As far as we know it’s the only one of its kind in golf. A club gets fewer staffed hours and keeps earning outside opening times. A player gets the same convenience they already have everywhere else in their life.

Driving range payments. Payments on the range that work with any ball dispenser brand. That compatibility is the product. The dispenser belongs to the club, or to whoever sold it to them, and being able to sit on top of all of them is the whole selling point. Cards, apps, wallets, PIN codes, with real-time analytics behind it. In a lot of places the range still runs on cash, and this is where demand is growing fastest right now. More than 500 million balls a year go through it. That’s a lot of slices.

Voucher management. Issuing, distribution and redemption, all digital, from a single ticket up to a full sponsor package.

Simulator management. Automated access control, so a simulator only runs during a paid session. No more time theft, better utilisation.

Where that adds up to today: 400+ venues, 18 countries, 350,000+ active users. Founded in Denmark in 2012 and still very Danish, which is also why I walked out of my first day having decided to get serious about my Danish.

The stack, without the polish

Sixty-eight repositories. JavaFX on the desktop side, PHP, Vue, React, React Native, Spring, Java, Kotlin. All of it on AWS.

Written out like that it looks like indecision, and it isn’t. Thirteen years, four product lines, hardware sitting in the field, and for most of that history the software was built by external partners who were good at their jobs. Every project picked what made sense on the day it started, and most of those calls were reasonable ones. What never happened is anybody going back afterwards to make the choices agree with each other.

So, the honest state, because I said in the letter I’d write these things down rather than smooth them over.

A good share of those sixty-eight repositories hadn’t been touched in years and were never archived. Forks, spikes, one-off tools that outlived their reason. I started archiving in the first week, slowly, because for most of them I didn’t yet know what I was looking at, and not knowing is a much better reason to leave something alone than to delete it.

In the code you can read the generations. Several package structures inside the same language, none of them wrong, all of them different. An AGENTS.md written for Codex and a CLAUDE.md written for Claude, sitting in the same repository, describing the same project, disagreeing about it. A README.md documenting a version of the system that doesn’t exist anymore. A runtime that went end of life a while back and is still running. And a release process that’s properly good for some of our tools and a snowflake for others, where part of it lives in a pipeline and part of it lives in somebody’s head.

Security sits at the top of the pile. Of the twenty-nine engineering practice items I’ve written down so far, five are marked high priority, and all five are security. That’s not a discovery about GolfNext in particular. It’s what thirteen years of shipping tends to look like anywhere nobody has recently been paid to go and look.

Since I made a prediction about all this from the outside, I owe you the result. It’s roughly where I expected it to be, and I mean that as a fair outcome rather than a complaint. This is thirteen years of continuous delivery by people shipping features that customers actually needed, on deadlines, with the priorities they were handed at the time. You’d find much the same picture at most companies this age, and I’d rather be the person who tidies it than the person who tuts at it. The one prediction that landed exactly was the dull one: I’d guessed from outside that the repos would be under-automated, and they are. That’s my opening.

The part I got wrong

I’d braced myself for the products to be the weak spot. Companies carrying a stack like ours often have shipped-anyway software on top, the kind where you can feel the deadline in the interface.

That’s not what’s here. The products are good. There’s room in all of them, obviously. But the thing I keep noticing in meetings is that everybody reasons from the customer’s side first, including people with no engineering background at all. What does the player standing at the kiosk at half five in the morning actually experience. What does a club manager have to explain to a member when something goes wrong.

That instinct is hard to retrofit into a team. Package structures can be refactored and READMEs can be rewritten, and both of those are just work. Teaching a group of people to care about the person at the other end is a different order of problem, and we don’t have it.

What we started in week two

Two integrations landed almost immediately, and they’re the same bet in different clothes. The platform is only open if it actually connects to the systems clubs already run.

teeControl is a management system a lot of clubs use, and we’re integrating it so it works through our kiosks. First impressions are good. First impressions are also cheap, and there’s a fair way to go from here. We need proper test systems. We’ll probably have to adjust some of our own flows to fit theirs. There are decisions still to settle on both sides. That’ll be a process rather than a sprint, and I’d rather say so now than write a triumphant post about it in week two.

Lightspeed is a player-facing app we want to support as a payment option. Peter had already built a first version before I arrived, and taking it over was my excuse to get my hands into real code here for the first time. Ten thousand lines, read end to end, then run and poked at until I understood what it was doing. That produced a list of bugs and a stack of follow-up stories, which is what reading anything carefully produces. The more useful outcome is that it’s in my head now as well as his.

And Verifone terminals on the desk, which is the regular reminder that a lot of our software ends in a physical object somebody has to touch.

The approach John and I settled on is to skip the big upfront specification. John is the other developer, though that undersells him, since he’s as much solution architect and project manager as engineer. Get a test instance, build against it, let reality write the documentation. Two weeks in I don’t know these systems well enough to write a good spec, and pretending otherwise would just produce a document we’d quietly stop reading by September.

One small thing worth passing on to anyone thinking about working somewhere like this. I spent my first few days being patient about access, on the assumption there was a process I was supposed to wait for. Then I said out loud that this was more or less what I’d been hired for, and could I please just have it. Half an hour later I had AWS. The waiting was entirely my own invention.

How we ship

The most interesting problem of the first two weeks wasn’t inside a repository. It was working out how changes get out to customers.

I spent a Friday on proper detective work. CloudWatch logs on one screen, a downloaded database snapshot on the other, lining transaction states up against what the code believes should have happened. Somewhere in there I found forty commits that had never been pushed anywhere. This is the unglamorous half of bringing knowledge in-house. Credentials are the easy part. Rebuilding an understanding of what the system actually does takes a lot longer.

We don’t have a gradual rollout mechanism today. What we do have is customers who are physical places, and a handful of them are a short drive from the office. So the first ring is geography. A few nearby clubs get the new version first, and if it goes wrong the recovery plan is twenty minutes in a car with a spare terminal in the boot. That took about five minutes of conversation to arrive at, because once you notice where the customers are it’s a fairly obvious move. It’s not what I’d draw on a whiteboard. It’s available this week, and it buys enough confidence to keep shipping while the proper thing gets built.

Learning the game and the words for it

On day three I played the first round of golf of my life, with colleagues. Seven or eight shots a hole. Never a ten. We didn’t lose a single ball all round, which I’m told is the more impressive statistic for a beginner. Nobody wrote down a score.

I’d recommend the general version of that to anyone joining a company whose domain they don’t know. Not golf specifically. Going and doing the thing the software is about.

The week after, John and I sat down for what turned into the most useful two hours of week two: agreeing what we call things, before three systems each invent their own word for the same concept. Nine holes is a loop. Stroke index ranks the holes by difficulty. There’s rating category. None of this is exotic if you play golf, and all of it is invisible to an engineer who has never stood on a tee box, which two weeks ago was me.

Getting the vocabulary right early costs almost nothing. Getting it wrong costs you three services, three names for one thing, and a translation layer nobody set out to build. I did run one check I’d suggest to anyone doing this: I had Claude verify “loop” on its own, because it smelled to me like a word engineers invent and then talk themselves into believing is domain language. It came back as real golf. Using the model to check our own vocabulary, rather than to write code, is one of the better uses I’ve found for it so far.

Twenty-nine items, and where this is going

The improvement list lives in ClickUp now, mostly so I can stop carrying it around in my head. Twenty-nine items, all still in the backlog, grouped roughly into repository standards and conventions, security and secrets, CI/CD and testing and dependencies, infrastructure and data, architecture direction, and AI and agents.

The first thing we’ve actually rolled out is the least exciting item on the whole list. mise, which pins and installs the right language versions per project, so you clone a repo and the correct Java turns up on its own. With that many technologies spread across that many repositories, the tax you pay all day long is switching between them, and that particular tax is avoidable.

The goal hasn’t changed since the letter. Build a landscape where context is cheap to pick up. If a new engineer, or a fresh AI session, can understand a service quickly, work can start immediately, by whoever picks it up. If they can’t, every task starts with archaeology. Everything on that list of twenty-nine sits downstream of that one sentence.

The scorecard

Which brings me back to the letter, and the promise to mark my own homework in public.

Stay on the keys. Held. Two terminal fixes shipped, pull requests reviewed, and I’ve taken ownership of one of the apps. I’m still building, which was the condition I set before I accepted the job.

Rebuild the understanding, not just the access. Mostly. The CloudWatch afternoon, the database snapshot, the Lightspeed handover: that’s the right shape of work. What I can’t claim yet is being able to release anything in the stack without asking somebody.

Candor in the open. Held, and easier than I expected, mostly because the room here makes it easy.

Now the other half.

Goal one slipped. “Make the work visible” was first on the list and this blog was supposed to be how. Every post before this one was written before I’d signed the contract, which turns out to be the easiest possible time to write about a company. Then I actually started, and for two weeks there were things in front of me that mattered more than a blog post. I’m not going to call that a crisis. I did write that if it went quiet I should treat it as a warning sign, so: noted.

The cold start is nowhere near five minutes. I set myself five minutes from clone to running code and told future me to go and time it. I haven’t timed it properly, which is its own small failure. I’ve cloned enough of these repositories by now to give a fair estimate though. Somewhere between two and six hours depending which one you pick, call it four on average. Getting the iOS build running took most of a day of Xcode, pods and emulators. mise is the first real step at closing that, and a step isn’t a number.

The shared AI kit is item twenty-nine of twenty-nine, and that part is on purpose. In the letter I called it the thing that turns “AI-first” from a slogan into shared tooling. Two weeks in I can see why it can’t come first. A shared kit built on top of sixty-eight inconsistent repositories would mostly just encode the inconsistency. Foundation first, kit second, and I’d defend that order. What I won’t pretend is that the order is free. Until we get there, I’m getting a lot of leverage out of a setup I’ve spent a year tuning that nobody else here has yet.

And the days ate the space to think. I wrote that the creative, playful time isn’t a reward you earn once the serious work is done, that it is the serious work. Two weeks in, it’s the first thing the calendar takes. One thing helps here, and it’s specific to this industry: golf is seasonal. Clubs are busy now, so we’re busy now. The platform goes quiet over the winter, and that’s when the toolset for the 2027 season gets built. Having a shape to the year is more useful than I expected it to be.

The thing I got most wrong is also the one I’m happiest about. I turned up braced for friction. I expected to have to earn access, argue for scope, make a case for every change. Almost none of that was there, and what resistance I did meet in the first fortnight I’d brought with me.

Two weeks isn’t long enough to conclude much. Ask me again in the winter, when the clubs go quiet and we find out what we actually do with the time.

Making Claude Code shut up (and other customizations that earned their keep)

Johann Böhler — Wed, 24 Jun 2026 10:00:00 +0000

The first thing I did with Claude Code was make it talk less.

Claude Code is Anthropic’s terminal coding assistant — you talk to it, and it reads, writes, and runs code in your project. Out of the box it’s polite. “Certainly! I’d be happy to help you with that. The issue you’re seeing is likely caused by…” I read fast, I pay per token, and I don’t need the warm-up. I switched that off. I run a community plugin, caveman, that strips responses to the bone: no articles, no pleasantries, every bit of technical substance intact. “Bug in auth middleware. Token expiry check uses < not <=. Fix:” — and then the fix.

It takes adjusting. Some of those compressed sentences make you stop and read twice; a fragment can carry more meaning than it first lets on, and you spend the saved second decoding it. But the trade lands well in my favor. I get to the point faster, the context window fills slower, and if a line is genuinely unclear there’s always the escape hatch: ask it to expand. It never minds.

That mode is the smallest possible example of the thing this whole post is about. Claude Code out of the box is generic. It’s built to be reasonable for everyone, which means it’s optimal for no one. The leverage isn’t the model itself — you can’t change how good it is, only which one you run. The leverage is in bending the tool around your own loop.

The trap

Customization isn’t free, and I want to be honest about the bill. You can pour weeks into a setup nobody else can read, including future you.

The tools that took configurability furthest are the ones everyone reveres: vim and git. Deep, powerful, endlessly tunable. And, I’d argue gently, not actually that accessible. The depth is both the point and the price. Vim is the only tool I know with a meme about how to quit it — that should tell us something.

I hear the objection most about git: “but git is so easy.” Is it, though? It’s easy right up until your first real merge conflict, or the afternoon you rebase the wrong thing and quietly rewrite your own history with no clean way back. Yes, you can see where you’re trying to get to. So can someone holding the box for a fifty-thousand-piece puzzle, the finished picture printed right there on the lid. Seeing the goal is not the same as the path being accessible. Those are different claims, and we keep mixing them up.

Here’s the belief, stated plainly instead of as a complaint: a great tool should be as accessible as it can possibly be, and then, having earned that, offer infinite depth to anyone who wants to dig. The accessible part is the whole job, not a consolation prize for beginners. Depth is the bonus you add on top.

My bar for any Claude Code customization is one question: would I hand this to a teammate without an hour of briefing? If the answer is no, it usually doesn’t survive. My stack stays simple and stupid on purpose. Here’s what’s left after that filter.

What earned a slot

The terse output mode. Covered above. The single highest-leverage change, because it touches every response. Less to read, fewer tokens burned, longer-lived context.

The statusline. This matters more than it sounds. I usually have several things going at once, and I lose track of where I am — which repo, which task, how much budget I’ve got left. My statusline shows it all in one strip: the model I’m on, how full the context window is, where I stand against my 5-hour usage limit (Claude Code caps how much you can run in any rolling five-hour window), and my current directory. No clicking, no guessing. I glance down and I know my situation. For anyone juggling more than one thing at a time, it’s the cheapest sanity I’ve bought.

The settings layer. This is where it gets personal, and where the options never end. My config plays a sound when Claude finishes so I can look away and get pinged back. It fires OS notifications. You can have it log the purpose of each session, track tokens and cost, whatever you decide is worth knowing. There’s no “right” setup — the point is that the hooks exist (little commands the tool runs automatically at set moments, like when it finishes) and you bend them to your purpose. Mine is “tell me when you’re done.” Yours might be something else entirely.

None of these is clever. That’s the point. Each one removes a small, daily friction, and none of them needs explaining.

The actual wiring

The sound is a Stop hook in settings.json:

"hooks": {
  "Stop": [{ "hooks": [{
    "type": "command",
    "command": "afplay ~/.claude/sounds/done.mp3",
    "async": true
  }]}]
}

async: true so it never blocks the session, and afplay is just the built-in macOS player — swap in whatever you like.

The statusline is barely more than that. Claude hands your script a blob of JSON on every render; the script prints a line. You point at it once:

"statusLine": {
  "type": "command",
  "command": "bash ~/.claude/statusline.sh"
}

and the script reads whatever fields it cares about off stdin:

input=$(cat)                                                  # session state, as JSON
model=$(jq -r '.model.display_name'                          <<<"$input")
ctx=$(  jq -r '.context_window.used_percentage // 0 | floor' <<<"$input")
fh=$(   jq -r '.rate_limits.five_hour.used_percentage // 0 | floor' <<<"$input")
dir=$(  jq -r '.workspace.current_dir'                       <<<"$input")

From there it’s just drawing strings. Mine renders a little colored bar for each percentage — green, then yellow, then red as it fills — and right-aligns the path, so the strip ends up looking like this:

Opus 4.8  xhigh  · CTX ████░░░░░░ 38%  · 5h ██░░░░░░░░ 21%        ~/dev/golfnext

(xhigh there is just the reasoning-effort level I keep the model at.) That’s the whole thing. No framework, no dependency to keep current. A shell script and a JSON blob.

What I won’t automate

More automation isn’t always a win. Some of it just moves the cost somewhere you can’t see, and those are the ones I leave switched off.

You can wire Claude to lint and format every file the moment it edits it. Sounds tidy. It’s the opposite. If a hook reformats a file right after the model touched it, the model’s picture of that file is now stale — so the next time it works there, it has to re-read the whole thing to catch up. You’ve traded a clean diff for a slower, token-hungrier session. I’d rather it just run the linter once, at the very end, when the thinking is done.

Same logic on automatic model fallback. You can have it silently switch to a smaller model when your first choice is busy. I don’t want that. I pick a model deliberately, usually because the task needs the bigger reasoning model — the one that pauses to work a problem through before answering. If it’s overloaded, I’d rather come back in two hours and write “pick this up again” than have something quietly hand my hard problem to a model that can’t carry it. Convenience isn’t worth a worse answer I didn’t notice I was getting.

The window should be a non-event

People talk a lot about managing the context window — compacting it (having the tool summarize the conversation so far to free up room), watching it, nursing it along. I try to never be in that conversation.

The way I avoid it is structural: push the heavy lifting onto subagents — separate helper instances of Claude Code, each with its own private context — and keep the main thread clean. A subagent goes off, burns its own context reading and searching, and hands back the short answer. The main session stays light. Done right, I almost never reach for compaction, because I never let the window get full in the first place.

But here’s the honest part: I think the fact that any of us has to know this is a smell. Nobody should need to understand context windows to start being productive with this tool. It’s a current limitation wearing the costume of a skill. A few years from now I’d bet it’s abstracted away entirely, and we’ll talk about it the way we talk about managing our own RAM — which is to say, we don’t. I optimize around it today, and I try not to mistake working around a limitation for something worth teaching.

Can I prove it? Not with numbers. I don’t have a clean before-and-after, and I distrust anyone who quotes a tidy percentage for this. What I have is a feel: the window fills slower, the budget stretches further, sessions stay light longer. It’s subjective, and I’d notice the moment it was gone.

How to find your own

The hard part isn’t configuring anything. It’s knowing what’s even possible.

Claude Code moves fast — it feels like ten new commands a week. So fast that the model itself can’t keep up. I’ll ask it about a real slash command — “what does /goal do, can you explain?” — and it has no idea the command exists. There’s something funny about that: the most capable thing I work with often can’t tell you about features that shipped after its training cutoff. It’s behind on itself, in the most literal way. You can’t just ask the model what it can do. You have to go look — read the changelog, skim a guide, point it at the open web where the fresh stuff actually lives.

The next thing I want to try isn’t a setting at all. I keep half a dozen projects in flight, so I’m going to build one small meta-repo: a single place that points at all of them, that anyone — not just me — can navigate. Same instinct as everything else here: if it only works for me, it doesn’t really work.

That’s the whole filter, in the end. Take the two or three things that kill a real, repeated friction. Leave the rest, however clever it looks. The goal was never the most elaborate setup. It was the one you’d still be happy to hand to someone else.

The Loop Debate Is a Bad Word for Autonomy

Johann Böhler — Wed, 24 Jun 2026 00:00:00 +0000

There’s a genre of post going around right now. You’ve probably seen it. “I don’t write prompts anymore — I design loops.” “Loop engineering is the new prompt engineering.” I read these closely — I’m trying to learn this as fast as anyone, and the people writing them are usually well ahead of me. But I keep coming away with the same itch: I can’t quite map the word onto what I actually do all day.

I run Claude Code most days. For people who haven’t met it: Claude Code is Anthropic’s coding agent — you give it a task in the terminal and it reads files, writes code, runs tests, and iterates, instead of just handing you a snippet to paste. The capability is real and I lean on it hard. What trips me up is the vocabulary, so I tried to ground it.

I did the boring thing: I tracked everything. Every real task I ran through Claude Code got two numbers next to it — what it cost in tokens, and a rough estimate of what the same work would have cost by hand, in time. A month of rows. It’s the least glamorous artifact imaginable, and it’s the thing that finally made the “loops” debate click into place for me.

What clicked — for me, at least — is that a lot of the argument is about the wrong word. “Loop” isn’t the thing. Autonomy is. And autonomy doesn’t arrive as a switch you flip; it arrives one task at a time, which, if you were around for the last big architecture argument, should feel oddly familiar.

“Loop” is four different things

Part of why the debate feels muddy is that “loop” is doing at least four jobs at once, and people argue past each other because they’re each holding a different one.

There’s the agent loop — think, act, observe, repeat. This is just how an agent works. It reads the situation, takes an action, looks at the result, decides what’s next. It has always existed. It’s not a technique, it’s the definition.

There’s Ralph — the bash hack. It’s the community’s name for the crudest possible loop: wrap the agent in a literal while loop in your shell and let it re-run the same prompt until it declares itself done. (The name is just folklore; the technique is the point.) Crude, occasionally effective, the duct tape of autonomy.

There are the features — slash-commands like /loop and /goal, baked into tools like Claude Code. They wrap that same idea in something more controlled than a bash one-liner.

And there’s “loop engineering” — the philosophy. The discourse. The posts.

Four different altitudes, one word. No wonder it’s confusing.

But here’s the thing they all share, the line every one of these repeats in its own dialect: goal, verification, stop condition. That trio is the actual substance. Everything else is which layer someone happens to be staring at.

Make it concrete. Take the most boring useful thing I automate: addressing review comments on a pull request.

Goal: resolve every review comment on this PR.
Verification: CI is green, and every comment thread is actually addressed — not “I think I fixed it,” but the check passes and the thread is closed.
Stop condition: no open comments left, or it hits an iteration cap and hands back to me.

That’s a loop. It’s also just a task with a clear definition of done and a rule for when to quit. The trio is the whole game.

And notice what makes that example work: a machine, not me, can tell whether the goal is met — the check is green or it isn’t. That’s what I’ll keep calling verification — an automatic, judgment-free signal that the work is actually done. Hold onto the word. How much of it a task has is the thing that decides everything later.

It’s not loops. It’s autonomy.

Here’s the part it took me a while to see. Read those three criteria again — goal, verification, stop condition — and ask: does anything in them change based on whether I press enter between each step, or a harness (the script or tool wrapping the agent) does it for me? No. Nothing. The goal is the goal, the verification is the verification, the stop condition is the stop condition; they’re identical whether a human advances each iteration or a script does. The only variable is who turns the crank between steps — and that isn’t a question about loops at all. It’s a question about autonomy: how much you trust the thing to keep going without you in the chair.

Which makes sense once you see how little there is to a loop — near enough, it’s this:

while not done:
    observe()              # look at where things stand
    act_toward(goal)       # take the next step
    done = verified()      # the stop condition: is the goal actually met?

That’s the whole thing. So “should I be designing loops” is a bit of a category error — the loop is trivial, a while and an if. The hard parts hide behind the word, and there are two of them. The first: how far are you willing to step back from a running process? That’s trust. The second, the one I almost never see named: once you do step back, where does the thing actually run, and can you afford to run it there? That’s infrastructure — and unlike trust, it isn’t really up to you yet, because the cheap, standard place to run autonomous agents doesn’t exist.

What the work actually costs

That second question — can you actually afford to run it — is the one nobody seems to blog about, probably because almost nobody thinks to measure it. So I did. My day-to-day with Claude Code is attended — I run it on my own machine, with me in the chair. But the number I wanted was the other one: what the same work would cost metered, pay-per-token, the way you’d have to pay to run it in the cloud without me babysitting it. That’s the expensive lane, and it’s the one that decides whether unattended is even on the table. So for a month I logged the metered cost of every real task, next to an honest estimate of how long it would have taken me by hand.

Two hundred and twenty tasks. About $1,360 in metered cost — and, by my own estimate, close to 540 hours of equivalent by-hand work. Five hundred and forty hours is the better part of three months of full-time engineering. It went out the door in one.

Put any reasonable number on an engineer-hour and that metered $1,360 stands against work worth twenty to forty times as much — around thirty at a normal loaded rate, counting salary plus overhead rather than take-home. I don’t need the multiplier to be exact: halve my hour estimates if you think they’re generous and it’s still an order of magnitude.

The shape of the spend matters as much as the size. The median task cost $2.45. Two-thirds of everything came in under five dollars — bug fixes, small features, flaky-CI config, dependency bumps. The expensive runs are rare and they’re the meaty ones: a full feature, built end to end, lands in the tens of dollars, and the biggest single rows are features in the $40–55 range. Stack several rounds of review on one of those and a complete change lifecycle can clear $100. Those are the outliers, not the norm.

The part that decides where to start: I tagged the rows that are pure review-and-fix work — addressing PR comments, fixing a failing build, resolving conflicts. That whole category was under a tenth of the total spend — most tasks a few cents to a couple of dollars, half of them under a dollar. And it rarely needed much from me. The comments are bounded, the fix is usually local, and the verification is already wired: the build is green or it isn’t. It’s the most checkable, lowest-judgment part of the cycle, which makes it the obvious first thing to let run on its own.

The real money leak isn’t the price of any one task. It’s churn — runs that burned effort on something that didn’t need it. A change that should have cost twenty dollars cost a hundred because I let it grind on a problem I should have just steered it through. That waste, not the per-task price, is the thing worth engineering against.

The scary number is mostly a metering artifact

There’s a version of this where someone sees that monthly total and recoils. “You spent how much on an AI?” And I get it — $1,360 a month is a genuinely alarming figure.

But it’s mostly an artifact of how it’s counted, not of what the work is worth — and it isn’t even what I pay. The $1,360 is the metered figure I measured. My actual bill is the flat subscription I run this on: a mid-tier “Max” plan, used at a normal pace — not a hammer-everything-through-the-model, let-me-Google-that-with-Claude-too pace, just steady real work — about €110 a month, call it $120. Same keystrokes, same output, same month of work; the metered figure is roughly ten times the subscription one, purely because of how it’s billed.

And here’s the bit that quietly defuses the whole cost panic: you work attended anyway. You’re sitting there. You’re steering. The expensive, unbounded, “oh god what is it doing” scenario is the unattended one — the agent grinding away on its own while the meter spins. Which is exactly the thing you’re least ready to trust in the first place.

So the two big worries — “it’s too expensive” and “I can’t let it run on its own yet” — turn out to be the same frontier seen from two sides.

So what do you actually build?

Not an autonomous loop — not yet, and not for most of it. What I build instead is a human-triggered chain of skills, where “skill” just means a named, reusable task you can hand the agent, like a saved command. One of mine babysits pull requests: after I open a PR I kick it off, and it watches for the things that need a response — a new round of review comments, a failing build — and works them until the PR is green or it hits something it can’t handle and taps me on the shoulder. I start it; it doesn’t start itself.

The interesting part is what doesn’t run the model. The watching is a plain shell loop polling GitHub every few minutes for a handful of cheap signals — open unresolved comment threads, the CI status, whether the PR’s been approved — and it only wakes the agent when that set actually changes:

# the watcher is dumb and free — no model in this loop
while pr_is_open; do
    signals="$(unresolved_threads)::$(failing_ci)"   # cheap GitHub calls
    if [ -n "$signals" ] && [ "$signals" != "$last" ]; then
        wake_agent "$signals"     # the only line that spends tokens
    fi
    last="$signals"
    sleep 600                     # 10 min; an idle PR costs nothing
done

The agent only spins up when that set changes, and even then it does the bounded thing — read the new threads, fix the worthwhile ones in the working tree, tell a “my code is broken” build apart from an “infra fell over” one — then goes back to sleep. The expensive part, the model, sits gated behind the cheap part, a script that knows how to read a status. That gating is most of the trick to keeping these things affordable.

Mine is the pragmatic version, though, not the gospel one. Point it at someone else’s repo and it needs real guardrails. A PR comment is untrusted input, which turns an open watcher into a prompt-injection surface: someone can leave a comment steering the agent toward something that has nothing to do with the PR, or just spam comments to keep waking it and quietly run up the bill. Past the toy stage you’d want a classifier deciding what’s even worth acting on, and an escalation path — an OS notification, a Slack ping, a ticket — for the things it shouldn’t touch on its own. But you can get a surprising distance on the raw signals alone; “open, unresolved comments plus CI status” is already enough to be genuinely useful.

And the shape generalizes. Another one I keep meaning to finish: a weekly job that scans the open Dependabot and Renovate pull requests, merges and tidies the boring ones where nothing real has to change, and escalates the rest — the bumps that need an actual refactor, or where an API might break under you. Same skeleton every time: a cheap trigger, a bounded job, and a clear line where it hands back to a human. Building those loops, and the small toolkits around them, is quietly becoming its own kind of software engineering — less “prompt the model,” more “design the harness the model runs inside.”

Two rules I’d carve in stone before building any of it. First: release is not a job for the model — it’s your CI/CD. Don’t teach an agent to do the thing your pipeline already does for free, deterministically, with an audit trail; that’s not autonomy; it’s reinventing a solved problem. Second: monitoring is not a job for the model — it’s Sentry and Grafana. Don’t pay a brain to watch a dashboard; wire the alert back to a trigger so the agent gets handed the problem only when something has actually broken. And whatever you build, cap the fix loop — a hard iteration limit plus a human “good enough, ship it” gate — or that $20 fix quietly becomes a $100 one while you’re at lunch.

None of this is timidity. Human-in-the-loop is simply how you start: you loosen the leash one iteration at a time, as your own skills sharpen and, more importantly, as your verification gets good enough that you’d trust the result without standing over it.

We’ve had this exact argument before

If all of this feels familiar, it’s because we ran the entire play a decade ago. It was called microservices, and I was there for it. Quick recap if you missed that era: around 2014, teams started chopping big single applications — “monoliths” — into lots of small, independently deployable services. The loud argument was how small they should be.

The froth is identical. Back then the unanswerable question was “how small is a microservice — can it be 200 lines?” Today it’s “Ralph or /goal, and how many agents?” In both cases it’s a community sizing-debating its way through a thing before anyone yet knows what actually matters.

The good practice predated the name, too. We were splitting systems by domain — clean seams, owned boundaries — long before anyone said “microservices.” And the agent loop plus a verification harness existed long before anyone branded it “loop engineering.” The name showed up and took credit for work people were already doing.

And then it settled. The honest retrospective on microservices isn’t “we revolutionized everything.” It’s “we mostly kept building the way we already built, with cleaner seams.” Most teams went from a monolith to two or five services, not one to two hundred overnight. The change was real and it was undramatic, because most of what we built was already small.

But here’s the correction that actually matters, the part the sizing-debate missed at the time. For microservices, the real delta was never the pattern. It was the substrate. Containers, then the cloud, then Kubernetes made small, independently deployable services cheap and standard to run. The pattern was downstream of the infrastructure — and the infrastructure showed up to meet it.

For loops, we’re only halfway there. The capability substrate has arrived, and it’s the model. One row on my sheet is a feature I’d have budgeted two days of hand-work for, delivered for about fifty dollars. That was flatly impossible two years ago, at any price, with any loop. The loop didn’t change; the thing inside it got good enough to trust with real work. That’s the containers moment — the raw capability landing.

What hasn’t arrived is the rest of the stack. There’s no cheap, standard, safe place to actually run autonomy unattended — no equivalent of the managed cloud and Kubernetes that turned “I have a small service” into “and here’s the obvious, affordable place to run it.” Nothing yet says “let this agent grind on its own overnight without it costing a fortune or going off the rails.”

So: the model is the containers; the Kubernetes hasn’t been built yet. And “loops” — the philosophy, the sizing wars — is the nanoservices froth all over again: the “how absurdly small can we make it?” overreach, playing out on a stack that’s still missing its bottom half.

Autonomy is granular, not a switch

Which brings me back to where I started. You don’t flip from “I watch everything” to “it runs itself.” Nobody went from one service to two hundred in a weekend, and nobody sane is going from attended-everything to autonomous-everything either.

The leash comes off one verifiable task-class at a time, gated by exactly one thing: how checkable the verification is. It’s already happening. A PR-watcher that auto-fixes failed builds is the leash already off — on a narrow, bounded, machine-checkable class where the cost of being wrong is low and a green check tells you the truth. Meanwhile feature design and production changes stay leashed for a long time, maybe forever, because the verification is judgment and judgment doesn’t fit in a CI check.

So when you read “I design loops, not prompts,” understand where it’s coming from. It’s not a lie. But notice who tends to say it: people at the big AI labs — the ones building these models — or with effectively unlimited token budgets, or both. For them the missing substrate isn’t missing; the meter doesn’t apply the way it applies to you. “Just run loops” is a perfectly honest description of their reality. It’s frontier-reporting: true where it’s reported from, with the best tooling and the most checkable problems, sold as a universal prescription it isn’t yet for anyone working against a real budget.

So I’m not tuning out the debate — I’m tuning out the word. I build the attended chain, harden my own skills and verification, and let each task-class earn its slack one check at a time. That’s the part I can act on today, while the rest gets argued out.

Which is the same move that turned out right with microservices: clock the froth, let the sizing wars run, and keep shipping the boring version that actually works.

A clean machine

Johann Böhler — Tue, 23 Jun 2026 00:00:00 +0000

In the last post I set myself a goal for the first ninety days: a five-minute cold start. Fresh laptop to running code in under five minutes — clone the project, run it locally, hit a live endpoint, pass the tests, all before your coffee goes cold. The shortest honest path from a new hire’s first morning to their first real contribution. That’s the on-ramp I want to build for the team at GolfNext, the Danish golf-tech company I’m about to join.

Before I can hand that to anyone else, I owe it to my own machine. A new job means a new MacBook is on the way, so I pointed the same goal at myself first.

The two-year-old bookmark

About two years ago, a dotfiles repo rolled past in my GitHub timeline — the feed of what the people you follow are working on. It belonged to Manuel Brandstetter, a former colleague and one of the best engineers I’ve worked alongside. He took over as lead of scrumlr.io, the open-source retrospective tool I helped build, after I left inovex, the German consultancy where we’d worked together. So when his setup scrolled by, I stopped to look. No grand pitch, just there in passing: everything that makes a laptop his laptop, version-controlled in one place. I remember thinking, clearly and out loud, “I should do that.” Then I didn’t. For two years.

If you’ve never kept dotfiles: they’re the small config files that quietly shape your machine. Your shell setup, your editor settings, your git config — the dozens of little preferences you’d otherwise rebuild by hand, from memory, every time you get a new computer. A dotfiles repo puts them under version control so the machine becomes reproducible instead of hand-crafted and forgotten.

The reason I never got around to it is the boring one: it always felt like an afternoon I could spend on something more urgent. The thing about a brand-new laptop, though, is that it removes the excuse. You’re going to set the machine up anyway. You may as well set it up once, properly, in a way you never have to repeat.

The audit I run every December

There’s a habit I’ve kept for years. Somewhere in the quiet week around Christmas, I sit down and audit my tools. Am I still using the best thing for each job, or just the thing I happened to pick three years ago and never questioned? It’s usually a solo afternoon — reading changelogs, half-remembered Hacker News threads, a bit of “what’s everyone else using now.”

This year had a running start. A few weeks earlier I’d gone looking for something like nvm, but for every runtime, not just Node: Python, Go, Java, the lot. I found mise, which does exactly that, and swapping a drawer full of per-language version managers for a single one was the most satisfying thing I’d done to my setup in months. That small win, I suspect, is what quietly tipped a two-year-old “I should do that” into “do it now.”

So this year I ran the audit as a conversation instead. I pointed Claude — Anthropic’s AI assistant, the same one I’ll be building with at work — at my current setup and asked the blunt version of the question: what here is dated, what’s missing, what would you change, and why. Then I let it research and argue its case.

I kept the result honest by making it a diff. The old setup stayed on my main branch; the reviewed one went on a branch I called cleanup. So every recommendation was a line I could read, accept, or reject, not a black box rewriting my machine while I wasn’t looking. That framing mattered more than I expected. A review you can read line by line is a review you actually trust.

Two things came out of it: a way to treat the whole machine as one repo, and a short list of tools I’d been silly to skip.

chezmoi: the machine as a repo

The manager is chezmoi. It tracks your dotfiles in a git repo and renders them onto any machine you own — chez moi, fittingly, French for “at my place.”

What sold me over a plain folder of symlinks is the model. The files in the repo are the source of truth; you apply them to write the real files into your home directory. Edit, preview the diff, apply, commit. It templates (one file can adapt to a work machine versus a personal one), and it keeps secrets out of the repo entirely — my SSH keys stay inside 1Password, handed to git on demand, never written to a file chezmoi could accidentally commit.

The part that finally delivered on the two-year promise is the bootstrap. On a clean Mac, the whole machine comes back from three commands:

brew install gh chezmoi
gh auth login                              # sign in to GitHub in the browser
chezmoi init --apply bitionaire/dotfiles   # clone + render everything into place

That last line clones the repo, installs my shell framework, lays down every config file, and runs a set of first-time setup scripts. One naming convention does most of the magic: a file called dot_zshrc in the repo becomes ~/.zshrc on the machine. dot_config/ghostty/config becomes ~/.config/ghostty/config. The dot_ prefix is just chezmoi’s way of writing a leading dot without confusing your file browser. Once that clicks, the repo reads like a mirror of your home directory.

The tools the review actually changed

I already ran oh-my-zsh with the powerlevel10k prompt. The review pushed three additions hard, and was right about all three:

Ghostty — a fast, modern terminal. I’d been on the macOS default for years out of pure inertia. Ghostty is quicker, themeable in a plain text file (which means chezmoi can track it), and renders the powerline glyphs my prompt uses without a separate Nerd Font install.
fzf — a fuzzy finder, and the one that changed my day-to-day most. Ctrl-R turns shell history from a blind up-arrow hunt into a live fuzzy search. Ctrl-T drops a file path into whatever you’re typing. Pipe anything into it — git branch | fzf — and you get an interactive picker for free.
zoxide — a smarter cd. It learns the directories you actually use and lets you jump by a fragment of the name. z dot lands me in my dotfiles repo from anywhere on the machine, no matter how deep it’s buried.

None of these are exotic — they’re tools a lot of terminal-heavy people already swear by, and I’d simply never sat down to add them. Wiring them in is a few lines of shell config:

# fzf — fuzzy finder (Ctrl-R history search, Ctrl-T file picker)
command -v fzf >/dev/null 2>&1 && eval "$(fzf --zsh)"

# zoxide — smarter cd (`z ` jumps by frequency + recency)
command -v zoxide >/dev/null 2>&1 && eval "$(zoxide init zsh)"

Automating the parts I used to click through

A fresh Mac isn’t just dotfiles. It’s an afternoon of downloading apps, dragging them to Applications, and clicking through the same System Settings toggles you’ve set on every Mac you’ve ever owned. That’s the part the review automated, and it’s the part I’m proudest of.

Apps come from a single Brewfile — a manifest Homebrew reads to install everything in one shot:

brew bundle --file=Brewfile   # installs every CLI tool, app, and App Store entry

One file lists the command-line tools, the desktop apps (1Password, Firefox, Ghostty, Docker, the editor), and even Mac App Store purchases. New machine, one command, twenty-odd apps install themselves.

Then there are the macOS settings. chezmoi runs setup scripts on first apply, and one of them is just a list of defaults write commands — the scriptable side of System Settings. A taste:

defaults write -g KeyRepeat -int 2                            # fast key repeat
defaults write -g ApplePressAndHoldEnabled -bool false        # hold a key to repeat it
defaults write com.apple.finder AppleShowAllFiles -bool true  # show hidden files
defaults write com.apple.finder _FXSortFoldersFirst -bool true  # folders on top

I’d set every one of these by hand on every Mac for a decade and never thought to write them down — now they’re a file. It isn’t total. Apple deliberately blocks scripting the security-sensitive bits, so granting accessibility permissions and signing into iCloud stays manual. But the dozens of little toggles that used to eat an afternoon now take seconds, and I’ll never have to remember them again.

A good review cuts as much as it adds

The surprise was how much the conversation talked me out of. A tool audit isn’t only about new toys; it’s about noticing the cruft you’ve been carrying.

So the cleanup branch deleted things. The handful of older version managers I’d accumulated, plus a hand-installed Python, all folded into the one mise I’d adopted a few weeks before. A shortcut I’d wired up to work around an old Docker quirk that’s since been fixed — gone. A tangle of work-versus-personal git config I’d accreted across jobs, flattened back to a single identity. Each of those was a small decision I’d made years ago for a good reason, then never revisited once the reason expired.

That’s the real value of doing this with a sparring partner. Left alone, I tend to add. Asked to justify each piece out loud, I finally removed.

What I’m taking from it

The impressive part wasn’t that an AI can write a config file — everyone knows it can now. It was the review. It didn’t hand me a generic “best setup”; it looked at mine, asked what I actually do all day, and argued for changes that fit, with the reasoning attached so I could push back where it was wrong. Less a tool than the December audit I already run, with someone knowledgeable sitting across the table.

And it closed a loop. The five-minute cold start I want to give the GolfNext team is this same thing, scaled up: a new person, a new laptop, and a short path to real work without a week of setup tax. I built the personal version first.

So if you’ve got your own “I should do that” bookmark gathering dust — a repo that once scrolled past in your timeline, maybe — this is your sign. Wait for the next clean machine. Then set it up once. Two years late still beats never.

References

The tools and docs worth bookmarking, roughly in the order they show up above:

chezmoi — dotfiles manager. Start with the quick start and the user guide.
Homebrew and the Brewfile / brew bundle — install apps and CLI tools from one manifest.
oh-my-zsh — Z shell framework, with the powerlevel10k prompt theme.
Ghostty — fast, config-as-text terminal.
fzf — command-line fuzzy finder.
zoxide — a smarter cd that learns your habits.
mise — one version manager for node, python, go, and the rest.
1Password SSH agent — keep private keys out of the repo and off disk.
The repo that started it: Manuel Brandstetter’s dotfiles.

P.S. — a Dock trick that has nothing to do with dotfiles

One freebie for the Mac users who made it this far. It has nothing to do with any of the above, but it’s the kind of small thing that’s quietly pleased me for years: you can drop blank spacers into the Dock to break your apps into clusters. Same defaults write trick as the rest of the post. Run it once per spacer you want:

# full-height spacer (run again for each extra one)
defaults write com.apple.dock persistent-apps -array-add '{tile-data={}; tile-type="spacer-tile";}' && killall Dock

# half-height spacer (run again for each extra one)
defaults write com.apple.dock persistent-apps -array-add '{"tile-type"="small-spacer-tile";}' && killall Dock

Drag the spacers around like any other Dock icon, or drag one off the Dock to remove it. Tiny thing. Makes a crowded Dock feel organized.

A letter to myself, before day one

Johann Böhler — Mon, 22 Jun 2026 00:00:00 +0000

“I may have something of interest to you, Johann. Would be great to connect 👍🏼.”

That’s the whole message. It arrived on LinkedIn out of nowhere, from a recruiter named Joe — which, given how often these things come in under a borrowed first name, might even be his real one. No company, no role, no details. The kind of message you’d normally archive without a second thought.

This one ends with me leaving a job I like, at a company I have nothing bad to say about, for a company whose name Joe wouldn’t even tell me. I had to find that out myself. Well — myself, and an AI.

I’m writing this before my first day of work. I haven’t signed the contract yet; I don’t even know my start date. Writing the company blog before I officially have the job sounds backwards. Maybe it is. I’m doing it anyway, because I’m carrying around more thoughts than I can hold, and because I want a record — something to read back in six months and hold up against whatever actually happened.

So this is two things at once. The story of how a two-line message turned into a job, and a letter to a future version of me.

A confession before we start: I’ve never written a blog post in my life. I’m starting now on purpose — writing pins down ideas that are otherwise just vapor. So here I am, thinking out loud.

From three breadcrumbs to a company

I asked Joe what his message was about. It turned out to be a Lead Engineer role at a small but established company: the first cornerstone of an AI-first development team — one that builds software mostly by directing AI instead of typing every line by hand. Joe wouldn’t name it. He gave me breadcrumbs instead — Danish sports tech, around since 2012, 400+ venues across 18 countries.

So I handed the breadcrumbs to Claude, Anthropic’s AI assistant. In seconds it named the company: GolfNext, in Ry, a short drive from where I live in Denmark. They make the self-service kit golf clubs run on — more on that later.

That little exercise is more or less the job description. If you can point an AI at three vague clues and have it reconstruct the company behind them, that’s the work. So I replied with a fully AI-generated message, openly labeled:

“Full disclosure, Joe: this reply is AI-generated. Felt fitting for an AI-first pitch — and yes, I let the agent do the detective work too. 😄”

They wrote back. A few days later I drove out to Ry and spent an hour at the GolfNext office, and by the time I left I knew I wanted it. The tell was the first thing they said when I sat down: “Let’s just have a chat here and talk openly.” No theater.

Before committing, I wanted to know exactly what I’d be walking into, so I asked. Thomas Herskind, who runs product at GolfNext, sent over an overview of the systems they run today. I read it and wrote back with everything I thought was worth doing first, point by point. It ran long. Very long.

Thomas’s reply was six words. “Congrats on your first novel, Johann!”

I laughed out loud. You learn a lot about a place from how it teases you before you’ve even signed.

The 70 ideas before this one

None of which explains why a two-line message with no details got my attention in the first place. For that, I have to rewind a few months — and first tell you who’s writing, since this is the internet.

I’m a generalist. A full-stack engineer who never minded picking up whatever a project happened to need. Sixteen years in: a lot of backend, a lot of web apps, a few years leading a team, and co-creator of scrumlr, an open-source tool teams use to run retrospectives — those meetings where you look back at what went well and what didn’t. I’ve never been the engineer who loves technology for its own sake. What pulls me is the other end of the wire: the user, the design, the value, the thing that makes somebody’s day a little easier. And getting there without a lot of detours. That’s the CV in a paragraph. The itch is the part it can’t carry.

I’d had an itch for a while to build something of my own. Anything that might grow into a business, really — and an excuse to push Claude as far as it would go and find out how much real software it could actually build. The first project came out of a pet peeve I’d carried across jobs. Release notes — the “what changed” list that’s supposed to be for the people using the software — keep getting dumped into commit messages, the terse notes developers leave each other. “Upgrade ESLint to version 10.” Who is that for? So I built a small product that lets you write proper change entries in plain language, right next to the code, and hand them to the product managers who should own them. Built from scratch in about two weeks — the parts users see, the backend behind them, the pipeline that ships updates on its own. All of it, with AI doing most of the typing.

That felt good enough that I got greedy and reached for something much bigger: an agent that keeps software projects alive. Maintaining them, extending them, mostly on its own, with the release-notes tool as its first patient. That’s where I hit a wall, and the wall taught me more than most of my finished projects did.

Some of it was scope. I’d wrapped a full product around something that should have started as a small experiment. But the deeper lesson was about the tool. Today’s AI is genuinely brilliant at a blank page, and at small, well-bounded changes. It gets shaky the moment you ask it to tear into big chunks of core logic. It starts to hallucinate — confidently inventing things that aren’t there. It never quite cleans up after itself. Old context lingers and creeps back into the next attempt. A build that ambitious needs a clear plan for how you’ll get there before you write a single line, and holding that plan together on my own, in stolen evenings and weekends, just wasn’t something I could pull off. That project is parked, not buried.

So I changed tactics. I put Claude to work as a sparring partner on smaller things, the kind I could finish in a couple of weeks. I’d pitch an idea; it would go research the market and, more often than not, come back with the same answer — crowded, already funded, don’t bother. Painful. Also useful.

After about 70 of those, I stopped pitching and asked the obvious question: so what should I do? The answer was refreshingly blunt. Stop hunting for a clever product. Find someone with a real problem and help them build a software-driven process around it that saves them serious time. And since it knows how I work, it sketched out roughly what that would look like. A few months later, Joe’s two lines landed in my inbox — and the role behind them, once I asked, turned out to be a near-perfect match for that sketch. The message with no details was the thing I’d been told to go find.

What it’s actually about

High time I told you what I’d actually found. GolfNext builds self-service tools and hardware for golf clubs — picture a ball dispenser members work themselves at the range, or a system that takes the fiddly, error-prone business of selling and redeeming vouchers and makes it calm. For years, capable external partners built most of that software, and it carried the company a long way. The shift now, as they laid it out to me, is that GolfNext wants the engineering know-how to live inside the company: a team that understands the whole landscape from the inside, for the kind of steady, long-term growth that comes from owning what you depend on. No verdict on the people who built it so far — just the natural next step for a company that plans to be around for a long time.

I’m one of the first pieces of that. The brief: absorb the landscape — the same one Thomas previewed in that overview — take over development bit by bit, and before long help build a team around it.

Here’s a confession that sounds odd in an engineering blog: I’ve barely written code by hand in months. Call it half a year on my own projects, a couple of months at work. Not because I stopped building. The building just moved up a level. More of my day now goes into directing AI, reviewing what it gives back, and designing the guardrails that keep its output safe and correct. It’s where the craft is heading — and it’s exactly the team GolfNext is asking me to build. Nobody can honestly tell you where all this lands; the ground moves every few weeks. But the direction is clear enough to point at, and pointing at it is the job.

That’s the what. Before the how, there’s a goodbye I owe.

Leaving a good thing

First, the honest part nobody enjoys writing. Saying yes here means leaving Salling Group — one of Denmark’s largest retailers — and I don’t want a single word of this read as a complaint. Salling was the perfect first step when I landed in Denmark: a real culture, people who genuinely look out for each other, work I’m proud of. I shipped things that mattered, under deadlines with no room for error, next to engineers I learned plenty from. I made good friends there. Part of me is sad to go.

The reason I’m moving isn’t a flaw in the place. It’s a difference in what I’m built for. At a company that size, every decision gets weighed by a lot of thoughtful people, which is exactly how a big retailer earns and keeps people’s trust. But it means being close to the wheel is rare, and steering quickly rarer still. I want the wheel. I want to point at a direction and move. That itch is most of why I started building things on the side in the first place, and it’s precisely what this new role hands me. Leaving a good thing for the right reason is still leaving a good thing. Both are true at once.

The goals I’m setting for myself

Now for the how. The wall I hit on that side project is the whole reason the goals below look the way they do. If AI is strongest inside clear boundaries, the answer isn’t to prompt harder. It’s to build a landscape where the boundaries are obvious — where context is cheap to hand over, where a change is easy to scope small, where the guardrails catch what the model gets wrong before a human has to. Because that’s where I think this is all heading: the scarce resource in software becomes how fast anyone — human or AI — can pick up a context they’ve never seen. If a new engineer and a fresh AI session can both understand a service quickly, work can start immediately, by whoever picks it up. If they can’t, every task starts with archaeology. Most of what follows is really about that one sentence.

One disclaimer that matters: I haven’t started yet. These are the standards I’ll hold myself to, not decisions I get to make alone — the order and the priorities get worked out with the people who’ve been running these systems for years.

Make the work visible. This blog is goal one. When you’re building knowledge inside a team, the worst thing you can do is lock it away in private channels and individual heads. Writing it down in the open forces clarity, pulls in good people, keeps everyone honest. So it exists now. Future me: if these posts went quiet, take it as a warning sign.

Rebuild the understanding, not just the access. Taking over from an external team isn’t really about collecting credentials and passwords. It’s about rebuilding the understanding from the inside. So: every account checked and put in my name, every doc read and sharpened until I can operate and release anything in the stack without phoning a friend. That’s the unglamorous half of the ninety days, and it’s the half everything else waits on.

Build a landscape everyone can build in. This is the one I care about most. Concretely:

A five-minute cold start. Fresh laptop to running code: understand the project, run it locally, hit a live endpoint, pass the test suite, all in under five minutes. It’s the on-ramp to building and testing, not a rulebook for how to write code. Future me, this one is measurable — go time it.
Docs that live right next to the code, so context is one directory away instead of one Slack message away.
Automation for anything we’d otherwise do by hand twice.
Technical debt paid down where it’s genuinely in the way — not a spring clean, just the things standing in the road.
A shared kit of prompts and presets for the AI, so everyone starts from the same proven setup instead of rebuilding it each time. That’s what turns “AI-first” into actual shared tooling instead of a slogan.

The point isn’t to be the only people who can build. It’s to be the quality gate that turns a rough idea into something you can trust, and the helping hand that makes building safe and easy for everyone else.

Stay on the keys. I said this to Joe before I’d said it to anyone at GolfNext, because it would save us both time. I’ve led a team before, twenty-four people, and I stepped back to building on purpose. “If ‘Lead’ means setting technical direction while still building, I’m very in. If it means drifting away from the code, I’m the wrong guy.” That line started as a filter for the job. It’s a goal now. Future me: if you’ve drifted, you know what to do about it.

Hire excellent people, and then trust them. Not in the first ninety days, and not my call alone, but it’s where this is headed, and it shapes the early calls. A small team of excellent people needs almost no process. Keep the bar high even when you’re short-handed. That part, at least, isn’t me projecting my reading list onto them: when hiring came up in Ry, they told me they’d rather run short-handed for a few months than bring in the wrong person just to add capacity. It told me more about the place than any pitch could have. Hand people context instead of approvals. Judge the work, not the noise. Default to yes, and stop to debate only at the doors you can’t walk back through. And leave room — real room — to spitball, to argue, to build things that might not work. The creative, playful time isn’t a reward you earn once the serious work is done. In this line of work, it is the serious work.

A compass, not a rulebook

The goals are the plan. Underneath the plan sits a compass, and it’s worth showing you, because it’ll shape how I steer.

What I won’t show up with is a manifesto. I don’t believe a culture can be written into existence. It grows out of its environment and the people in it, day by day, in a thousand small moments nobody writes down — which is why it can only be led by example, never enforced. We’ll work out GolfNext’s actual values together, in the doing. And I mean together in both directions. I’ll arrive with convictions — this post is full of them — but I expect to be changed as much as I change anything, and to pick up ways of working I haven’t even considered yet.

Part of it I owe to inovex, the German consultancy where I spent seven years — the longest stretch of the sixteen. They had a triangle — Employees, Customers, Economy — and they meant every corner of it: fair pay, the freedom to choose the right tools for the job, sane and agile ways of working, genuine care for the people doing the work. Most of that I still hold to. My own emphasis just sits a little differently. Where their triangle puts employee happiness, mine puts Craft. Not because happiness doesn’t matter, but because I’ve come to think it grows out of doing great work together, rather than being something you can aim at head-on.

So the three points I steer by are Customer (the aim — solving the problem people would genuinely miss), Craft (the swing — building it well, and getting better by building it), and Capital (the long game — staying healthy enough to finish the round, and keeping the knowledge in the house so nothing important lives in a single head). Lean too hard on any one and you slice; get all three swinging together and the ball drops.

What I’ve been reading, and what I took from it

A fair number of the goals above — the high bar, the trust, the near-absence of process — I got from No Rules Rules, Reed Hastings and Erin Meyer’s book on how Netflix is run. The argument, compressed: push talent density up until you have a team of excellent people, use candor to keep them honest with each other, and then start taking the rules away — because most rules exist to stop bad outcomes from average performers, and once you haven’t got those, the rules cost more than they save.

The bit I keep coming back to is the expense policy. It comes down to a single instruction: act in the best interest of the company. That looks like a policy about receipts. It isn’t. It’s a statement about who’s responsible. A rulebook hands you an answer somebody else worked out once, for a situation that might not be yours anymore. One instruction hands you the goal and makes you work out the answer for the situation you’re actually standing in. That’s more weight to carry. It’s also what makes you a real part of the thing instead of an executor of other people’s decisions — and it’s where creativity and initiative come from. You don’t get an unexpected good idea out of somebody following steps.

The part that has to be practiced. None of that works without candor, and candor doesn’t come free — for anyone. The pull toward smoothing things over is universal, and caring without saying the thing is the failure mode that feels kind and isn’t. Take away the rules and keep the politeness and you don’t get freedom. You get a team quietly drifting, with everyone guessing.

So I read Radical Candor as well, Kim Scott’s book on exactly this — useful feedback needs both halves at once: you have to actually care about the person, and you have to actually say the thing. Hence this commitment, in writing, where anyone can hold me to it: expect me to be very clear about what I think, what I’ve decided, and why — including when the answer is that I got it wrong.

And yet — not a culture you can copy. One caveat over all of it. I don’t want to import Netflix’s culture wholesale. It grew out of a particular company, in a particular market, at a particular size, and plenty of what makes it work there doesn’t travel. The book’s famous sharp edge travels worst of all: the keeper test, where anyone a manager wouldn’t fight to keep is let go with a generous severance. I’d leave that part behind entirely. Talent density earned by hiring carefully is a different thing from talent density maintained by cutting — and an edge that hard has very American roots. It’s not how I’d want a small team in Denmark to feel. There’s just as much worth taking from how good people at companies like Google or Apple have built and run their teams — and those cultures disagree with Netflix’s in places, on purpose. Ours will be its own thing — worked out in Ry, not copied in from California. The real test of any of this is what everybody does when nobody’s enforcing anything.

Which lands back where the expense policy started. Don’t adopt somebody else’s rulebook. Adopt the habit of asking what’s genuinely best here, right now, with the people we’ve actually got — and stay willing to change the answer when the situation does.

A note to future me

By the time you read this, you’ll know everything I don’t. The start date. Whether those first ninety days went to plan. Which of these goals survived contact with reality, and which were sweetly naive. Some of it will look obvious in hindsight. Some of it will look funny.

I wanted it written down before the job could start shaping my answers — while it’s all still conviction, before it hardens into experience.

Thomas already joked that my first long reply to him read like a novel. Consider this post the sequel. Longer, and this time public. Let’s see how close I got.