How to open source a side project (what Agency taught me)

The hard part of open sourcing a tool you built for yourself isn’t the licence or the README. It’s that the tool works because of your machine: the software you already installed, the certificates your Mac already trusts, the logs only you know how to read. Find those by installing it somewhere that has never seen your setup, before strangers find them for you.

That’s what happened with Agency, our free desktop app for running several AI coding agents side by side. For three months it had one user, me. I used it every day to run agents in parallel, each in its own git worktree (a separate copy of the project on its own branch), and to review and merge what they produced. My own window has 18 projects in it. From early July, most of Agency was built inside Agency: as of October 2026, 237 of the repository’s 278 merges came from branches an agent worked on.

It did what I needed, and it depended on things I didn’t see until I decided other people should have it.

Why open source it at all?

I started Agency on 18 June as a desktop app for running terminal coding agents locally, with no account and no server behind it. Months of using it convinced me it was worth sharing. I also wanted more than downloads. I want people to fix what bothers them, add the agents they use, and build their own tools around it. That only happens if the code is open, so Agency is Apache-2.0 and lives at github.com/TennnisAI/Agency.

Once I’d decided that, “does it work for me” stopped being the test. The new test was whether it works for someone I’ll never meet, on a machine I’ve never seen, who can’t ask me what a log line means.

What does “ready to share” actually mean?

Strangers can’t read my logs. When Agency broke on my Mac, I opened a terminal and looked. A stranger gets a frozen window. On 7 July I ran a pre-beta review (a bug hunt, a UX pass and a list of what was missing) and fixed the 29 bugs and rough edges it found. Agency now writes log files, catches crashes, shows a dialog when it fails to start, and puts its version and an “Open logs” button in Settings. The bug report template asks for exactly those two things, because a report without them is usually a guess.

My Mac trusted everything I built. A stranger’s Mac trusts nothing. The download is signed and notarized (checked by Apple, so macOS will open it without a scary warning), and the release checklist says to test it on a second Mac or a fresh user account. Your own machine already trusts your certificate, so it can’t tell you whether anyone else’s will.

I only used the agents I use. The first design planned for three agents. The public release detects eleven installed on your machine, from Claude Code and Codex to Kimi Code and DeepSeek Harness. Other people use other agents, and the list had to reflect that before they showed up.

The reasoning lived in my head. Nearly every feature in Agency started as a written design and a task-by-task plan for agents to carry out. I left all of them in the repo’s docs/ folder. If you want to change how Agency merges, or build something that talks to it, you can read why it works the way it does. Some documents exist only for future contributors: one covers what it would take to support GitLab and Bitbucket, and another lists everything a port to another operating system would touch.

People need to know what they’re walking into. CONTRIBUTING.md says Agency is a solo side project and that I usually reply within a week. It says bug reports are the most useful contribution, and that anything substantial should start as an issue, since the design has strong opinions and it’s better to find that out before writing the code.

Version 0.1.0 went public on 6 September, for Apple Silicon Macs only.

The machine that wasn’t a Mac

In July I wrote that list of every place Agency assumed it was on macOS, and assumed leaving macOS would be one big port, for later. On 8 September, two days after the release, I tried building Agency on Linux for the first time.

Most of it was already Linux-clean. The automated tests that run on every change (CI) had been running the core of the app on Ubuntu for weeks: the terminal handling, git, worktrees and merging. Only the outer app shell had never been tried, and every macOS-specific part of it already had a non-macOS version written.

The build stopped on one error:

You can't enable both `gtk3` and `xdg-portal` features at once.

It fires inside a library’s build step before any of Agency’s own code compiles, so it reads like “Linux doesn’t work.” The real cause was two libraries asking for incompatible settings of a third one, rfd, which draws file and message dialogs. Agency only used it for a single error dialog, so switching off its defaults fixed the build and changed nothing on macOS:

rfd = { version = "0.16", default-features = false }

Within 90 minutes, GitHub Actions was building Linux packages (.deb for Debian and Ubuntu, .rpm for Fedora, and a portable AppImage) for both Intel and ARM machines. The first one installed on Debian 12 and refused to start with version `GLIBC_2.39' not found. The build machine had moved to a newer Ubuntu, and the app now expected a newer core system library than Debian ships. Building on the older Ubuntu 22.04 fixed that for every current distribution I target.

The next three days went on problems I would never have seen from my own Mac:

• The first package looked like malware in Ubuntu’s App Center: unknown publisher, placeholder icon, licence unknown, and the description “(none)”. lintian, Debian’s package checker, found five errors, and nothing in the build had ever run it. The release script now runs lintian and the desktop-file validators on every build.
• The window had three title bars stacked on top of each other, because the macOS title bar style doesn’t exist on Linux. The Linux window now draws its own single bar with the menus and window buttons in it.
• A fresh Ubuntu desktop had neither git nor npm. Every machine Agency had run on until then was a developer’s Mac with both installed. Onboarding offered eleven agent installs that began with npm, and “Initialize repository” failed with No such file or directory (os error 2). Onboarding now checks for git, Node.js and the GitHub CLI and installs what’s missing through the system’s package manager. Mac users on a clean machine get the same fix.

Version 0.2.0 shipped on 11 September, five days after the first public release, with a Mac download and six Linux packages built from one release tag. One gap remains as of October 2026: nobody has run the Intel .rpm or AppImage on real hardware yet, because the virtual machine I test in can’t emulate Intel chips. If you’re on Fedora with an Intel or AMD machine, the package is on the releases page and I’d like the bug report.

If you’re about to share a tool you built for yourself

1. Install it somewhere that has never seen your setup. A fresh user account, a clean virtual machine, another operating system. Most of what broke on Linux was invisible from the machine I built it on.
2. Build for the bug report a stranger will send you. Put the version and the log file one click away in the app, and ask for both in the issue template.
3. Try the other platform before you estimate the port. Mine sat in a document for two months and took one feature flag.
4. Leave your design notes in the repo. Contributors can’t build around decisions they can’t see.
5. Say what kind of project it is up front. “Solo, best effort, open an issue first” sets expectations before anyone gets frustrated.

FAQ

Is Agency free? Yes. It’s open source under Apache-2.0, with no account and no server. Download it from the GitHub releases page.

Does it run on Windows? Not yet. Linux turned out to be one feature flag away; Windows is a much bigger port, mostly because of how Agency keeps terminals running in the background.

Which agents does it work with? Any of the eleven coding agent command-line tools it detects, including Claude Code and Codex. The how-to on running several AI coding agents at once covers the workflow, with or without Agency.

Where’s the rest of the story? The Agency case study covers the app, and why we stopped using tmux is the most expensive wrong turn we took building it.

Agency is on GitHub. If you build something around it, open an issue and tell me about it.

We build apps like this at Tennnis. If you’ve got one that needs building, get in touch.