It stands plain as a wardrobe, what we know,
Have always known, know that we can’t escape,
Yet can’t accept. One side will have to go.
— Philip Larkin, “Aubade”
A terminal workspace assembled from tools you already have. One command opens a file browser, an agent and a shell in one window, configured and checked.
cd ~/some-project
bothy
That is the entire idea. It is not a large one. Most of the effort went into making sure it did nothing else, and it still occasionally has to be reminded.
bothy looks at what you already have. If the tools are there, it uses them and tells you so. If some are missing, it lists them and guides you trough obtaining them Then it writes its configs into a folder of its own, points each tool there for exactly as long as the session lasts, arranges the panes, and opens the window. Afterwards it tells you what is broken, if anything is, and what to do about it.
When you close the window, everything is as it was. When you uninstall it, the folder it wrote goes, and it names the few things it cannot remove for you.
The same thing in order, with the reasons for the order, is what happens when you type it.
You need git, and curl or wget. Everything else bothy brings, or tells you how to get. A terminal that can draw images — Ghostty, Kitty, WezTerm — makes previews real pictures rather than block art, and an AI agent is optional, though it is what the middle pane is for (and sort of the point).
curl -fsSL https://raw.githubusercontent.com/bspeelm/bothy/main/bootstrap/install.sh | shNo root, nothing layered onto the host, so this works unchanged on Silverblue and inside Toolbx. Then, from any directory:
bothyThe first run lists what you are missing, asks before downloading anything, then opens the window. It is not fast. It does not need to be; you will do this once.
There are six ways in — dnf, apt, Homebrew, Go, source — and each verifies what it fetched differently. All of them, and what checks what. What bothy downloads and what that proves.
Three of them matter:
bothy |
open the workspace |
bothy doctor |
what is wrong, and what to type (--json for machines) |
bothy config set <key> <value> |
change a setting |
There are fifteen. All of them, with their flags, and how to read a doctor report.
~/.local/share/bothy/ bothy's things: configs, and any tool it fetched
~/.config/bothy/ your things: settings, palette, overrides
Nothing else. Not ~/.config/yazi, not ~/.vimrc, not ~/.bashrc, not your
git config. bothy writes into its own folder and, when it launches, points each
tool there — with environment variables that last for that session and then do
not.
The second folder is yours. Put it in git, clone it on the next machine, run
bothy, and you have the same room.
bothy uninstall removes the first folder and the binary, and names the three
things it leaves rather than leaving you to find them.
Using your own tool config instead of bothy's · what uninstall leaves, and why.
bothy has five slots — terminal, multiplexer, browser, editor, agent — and each
is a name in a config file. Change one, run bothy install, and it tells you
what that stack can and cannot give you.
The agent slot runs a command with everything you can reach: every repository,
~/.ssh, your shell history. That is the same access it would have if you
started it by hand, so bothy is not making it worse — but bothy owns the
launch, which is a position to make it better.
bothy confine runs the agent pane in a rootless podman container. Nothing
else changes: the same layout, the same file browser, the same shell.
It is opt-in and there is no setting that turns it on. Never type the command and nothing about bothy is different.
Stops: every other project, ~/.ssh, ~/.aws, your shell history, the
rest of $HOME. Verified, not assumed — from inside the pane those paths do
not exist.
Does not stop, on purpose:
| the agent's own credentials | mounted, or it cannot log in and the wall protects nothing you wanted. The paths come from the agent's own file in slots/; for one bothy has not learned, set agent.credentials |
| the network | the agent calls its API; that is the job. This is a filesystem wall, not a network one |
| the project directory | mounted writable, because editing it is the point |
If the credentials are missing the agent starts and says "Not logged in" rather than failing — that is the agent's behaviour, not bothy's.
Setting it up, the toolbox case, configuration and cleanup.
Linux and macOS. Fedora, Ubuntu, Debian and Arch are installed, exercised and uninstalled in containers on every release, and macOS on a real Mac — that is what supported means here. Silverblue and the Debian derivatives get advice bothy cannot test in a container, and says so.
Which terminals, which stacks, and what is untested.
- A plugin marketplace or extension API
- A bundle of the tools. It downloads their official releases and checks them, which is different, and the difference is the point
- An LSP or debugger manager
- A background service, an auto-updater, or a collector of telemetry. It does not run when you are not looking, and has nothing to report if it did
- A manager for your agent's config, keys or hooks. Those are yours, and so are the consequences
- A sandbox. The agent runs as you, in your repository, with your permissions. Its edits and commits are real and are not bothy's to undo. Uninstalling removes bothy — its tools, its configs — and nothing the agent did
- A Flatpak. Flathub does not accept command-line software, and bothy downloads its tools as it goes, which Flatpak packaging was invented to prevent
It is a room. You go in, the work happens, you leave, and it keeps nothing of yours.
Within a major version: the config.toml keys, the profile and palette
schemas, the two directories, and the doctor --json shape. config.toml
carries schema = 1.
I will continue to make tweaks and push maintenance builds, but these are the features it ships with and most likely will stick with.
What that obliges, and what is deliberately not covered.
See docs/adding-a-provider.md. Adding a tool
bothy fetches is one config file. Adding one it configures is a file and some
templates. Only the multiplexer needs Go, because it reads the layout and
writes something else; if anything else seems to, stop and say so — that is a
bug in the provider format, not in you.
What it is aiming at is in docs/north-star.md. Why
things are the way they are is recorded in
docs/decisions.md.
The plan for the project is in docs/PLAN.md, and has survived contact with
the project better than most plans do, which is to say partially.
I wanted an easy way to make my development setup portable — all of the things I use and nothing I don't. It started as a cheatsheet I'd hand to an agent to set up the configuration; that's still in the docs if you're curious, and it's probably where this should have stopped. But while working on another project I felt the pull to go through every step of shipping something with a fully open AI workflow, and this was about as low-stakes a candidate as it gets.
I designed the architecture and the constraints and made the decisions, while Claude planned and executed within them. The decisions are recorded in docs/decisions.md, and the rules Claude worked under are in CLAUDE.md.
Claude wrote most of this code. I've since reviewed the load-bearing paths and the tests, with particular attention to the sensitive bits: the install script, the uninstall path, and the container invocation. The rest is verified by process — the test suite, the code and comment budgets enforced in the Makefile, and audits by AI systems other than the one that wrote the code.
To say it plainly: this is a small, zero-stakes project where keeping iterations fast while manufacturing the rigor was the point. Learning to use these tools can still produce something useful, and that is where we find ourselves.
A longer account of how this was built is here.
MIT — see LICENSE.
The built-in palette is Dracula,
also MIT. bothy does not bundle the tools it installs. It downloads their
official releases, checks them, and each keeps its own licence.
NOTICE lists them all, as is only right.