← 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
Live
federicomonaco.com/projects/bosco/site ↗

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.

Bosco, example project
Thirty seconds of the app itself, on example projects: a tree grows, three agents light up, a collision is predicted, the queue merges. Tap or click to play and pause.
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 whole forest of example projects, with the Today list on the left naming two agents on the same file and three agents at work

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.

One tree with three lights on its branches, a red thread between two of them, and the Work in progress panel listing each agent's branch and files

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.

Sparks along the thread between two branches that would not merge, a lantern on the branch running the build, and the panel naming the file in conflict

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 collection with one branch ready for the trunk, one branch sent back to be fixed and one waiting in the queue

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 open in the side panel with its last commits, the count of changed files and a button to open pull request 12

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.

The first-launch guide on the step How Claude connects, with the three levels and switches for the warden hooks and the MCP server

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.

The Bosco terminal open over the forest after the commands stato, rami, guardia on and riservati

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.