← All projects
Case study, Mac app
Bosco
A traffic warden for Claude Code agents. It draws every Git project on the Mac as a tree, warns an agent before it overwrites another agent's work, and merges branches one at a time.
- Role
- Design and development
- Platform
- macOS 13+, Apple Silicon and Intel
- Built with
- Swift, AppKit, three.js, Claude Code hooks, MCP
Download Bosco ↓See the landing page
Preview build, not yet notarised by Apple. If macOS blocks the first launch, open System Settings, Privacy & Security, and click Open Anyway. Needs Git; Claude Code is what it coordinates.
169automated tests, plus runs with real Claude Code sessions in a throwaway repository
0.09 sfor the warden to answer an agent before it writes a file
0pushes: Bosco only works on the Mac, and main moves when you say so
The problem
Parallel agents overwrite each other.
I run several Claude Code agents on the same project, each on its own branch. Each one sees only its branch. When two of them merged at the same time, the second erased what the first had fixed, and I only found out because another agent complained. I went back to a single chat. Before Bosco I kept the peace by hand, with a Markdown table of who was touching which file and rules every agent had to remember to read. Bosco is that table, kept automatically and enforced.
What I built
One forest, seven ways to keep agents apart.
The forest
Every Git project found on the Mac is a tree: the trunk is main, a branch is a branch, a tuft of leaves is a commit. A list called Today names what needs attention across all projects. Bosco reads Git and never changes your files on its own.
Who is working, and where
A light sits on each branch where a Claude Code session is working. Nothing has to be connected for this: Claude Code writes its sessions to disk and Bosco reads their folder and branch. When two branches touch the same file, a red thread joins them.
The collision, before the merge
Bosco test-merges every pair of branches with git merge-tree, which touches no working folder. If the merge would fail today, sparks run along the thread and the agent is told before it writes. Commands that cannot overlap, like a build, pass through a lantern: one agent runs, the others wait.
The merge queue
Agents stop merging on their own. When one is done it runs bosco pronto, and Bosco merges one branch at a time into a collection branch inside its own working folder. A branch that does not fit goes back to the agent that wrote it. main moves only when you click.
A branch, and its pull request
Open a branch to read its commits and what it changes, then merge it, prune it or protect it, each with a two-click confirmation. If the project is on GitHub and gh is installed, the open pull request shows on the branch. Bosco uses gh's own login and writes nothing to GitHub.
How Claude connects
The first launch explains the three levels honestly. Seeing agents needs nothing. The warden is three hooks added to Claude Code's settings, after a backup. The MCP server lets Claude ask who is touching a file and declare itself done, so nobody has to relay messages between chats.
Settings as a terminal
Command-K opens Bosco's own terminal, where the settings live as commands: turn the guard on for a project, list branches and pull requests, reserve a build command, replay the growth. It runs Bosco's commands, not a shell.
The landing page
The page runs the app itself.
The window at the top of the landing page is not a picture: it is the same page the Mac app shows, with example data, and three chapters drive it as you scroll. Below it, two animated Git graphs tell the same story twice, without Bosco and with it. The screenshots on this page were captured from that same build.
Key decisions
Seven decisions that shaped it.
- Fail open. If Bosco is closed, slow or its registry is more than two minutes old, the hooks let everything through. An agent must never be stuck because a helper app is not running.
- Hooks read one file. The warden that Claude Code calls never runs Git and never opens the network. It reads a registry the app rewrites every few seconds, which is why it answers in 0.09 seconds.
- Merge somewhere else. Merges happen on a collection branch in a working folder Bosco owns. Your folder and the agents' folders are never touched, there is no force and no push, and main advances only on a two-click confirmation.
- Let Claude close the collision. When a branch does not fit, one click opens a headless Claude Code session in a folder Bosco owns, with the merge left half done. It may only read, edit and commit there. Bosco then shows what changes, and a person accepts or discards it. In the trial run it kept both agents' lines.
- Plan before anyone starts. You write the goal, a read-only Claude Code session splits it into tasks that touch different files, and Bosco launches one agent per task with its files already reserved. Preventing the collision is cheaper than resolving it.
- Predict with git merge-tree. A real trial merge of two branches, computed on Git objects only. It says whether today's merge would fail, and on which files, without checking anything out.
- One page for app, site and film. The interface is one HTML file with a three.js scene. The Mac app serves it from inside its bundle, the landing page embeds it with example data, and the screenshots come from it. The app is built with swiftc, with no Xcode project.
What I learned
Only real sessions find the real bugs.
The automated tests were green long before the thing worked. Running real Claude Code sessions in a throwaway repository showed that on a loaded Mac the registry was already old by the time it was written, so the warden quietly let everything through. The fix was one line, stamping the registry when a pass ends instead of when it starts, and no unit test would have asked the question.
What's next
Version 0.3 is a preview. Next, a week of real work.
Bosco is signed with a development certificate and not yet notarised by Apple. It updates itself: the app checks a signed file on this site and installs a new version with one click. Before calling it 1.0 it has to survive a week of real work with several agents on a real project, and learn to coordinate agents other than Claude Code.
Projects, branches, files and agents shown are example data made for presentation. The tree shapes come from real Git histories with names and commit titles removed.