bothy

README

bothy

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.

What happens when you type it

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.

Install

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 | sh

No root, nothing layered onto the host, so this works unchanged on Silverblue and inside Toolbx. Then, from any directory:

bothy

The 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.

Commands

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.

What it touches

~/.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.

Swapping parts

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.

Swapping parts, and theming.

Walling off the agent

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.

What it stops, and what it does not

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.

Where it runs

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.

What bothy is not

• 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.

What you can depend on

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.

Contributing

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.

Authorship

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.

Credits and licence

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.

Documentation

Overview

Package bothy carries the data files compiled into the binary.

Templates and profiles are embedded rather than installed alongside the binary so that `bothy` is genuinely one file: there is no data directory to keep in sync, and no way for a partially-copied install to produce a partially-configured workspace.

This lives at the repository root because go:embed can only reach downwards from the package that declares it.

Index

• Variables
• func Lock() []byte

Variables

var Profiles embed.FS

Profiles holds the shipped layout profiles.

var Slots embed.FS

Slots holds the declarative tool and provider definitions. A tool bothy can supply is a file in here and nothing else — see docs/adding-a-provider.md.

var Templates embed.FS

Templates holds every config template, keyed by its path under templates/.

Functions

func Lock

func Lock() []byte

Lock returns the embedded lockfile.