Repository navigation
Home
github-actions[bot] edited this page Oct 28, 2026
·
15 revisions
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.
The README is the overview; these pages are the detail. Start with the terms: bothy uses a handful of them precisely, and the rest of the documentation assumes them.
| term | what it means here |
|---|---|
| workspace | what bothy opens: three panes in one terminal window. Not a project and not a directory, though it is opened in one |
| pane | one region of the window. The file browser across the top, the agent and a shell below. Three panes is the invariant: a stack that cannot produce them is not a bothy stack |
| session | a running workspace you can walk away from. Detach with Ctrl-o d, come back with bothy attach, and it has carried on without you. Closing the window ends it instead. One per project directory, named after it |
| slot | a job to be filled, not a program. There are five: terminal, mux, browser, editor, agent. You say which program fills each |
| provider | a program that can fill a slot, described by one TOML file — how to detect it, fetch it, configure it. zellij fills the mux slot; yazi fills the browser slot |
| mux | short for multiplexer: the thing that splits one terminal into panes and keeps them running after you disconnect. Zellij, today |
| profile | the layout: which panes, what size, which slot goes where. Three ship — cockpit (the default, three panes), editor, minimal
|
| capability | something a stack can or cannot provide: panes, sessions, theme, isolation, images. bothy doctor reports each as available or not, because no amount of configuration adds a capability the stack does not have |
| passthrough | using your own config for a tool instead of bothy's. Name the slot, not the program |
| box | a toolbox or distrobox container. It shares your home directory but keeps its own installed packages. toolbox creates them; bothy remembers which box each project belongs in |
| confine | running the agent in a container with your project mounted and the rest of $HOME not. Opt-in, never automatic |
| the lock |
bothy.lock — the version and checksum of every tool bothy would fetch. Nothing is downloaded that is not pinned here |
Two directories, and it is worth knowing which is which:
~/.local/share/bothy/ bothy's own — configuration it generates, tools it fetched
~/.config/bothy/ yours — settings, palette, overrides
- Your first session — the panes, and leaving without losing the session.
- Installing — every channel, and what each one checks.
- Commands — all nineteen, with their flags.
- The tower — every running agent in one window, and answering one.
- Toolboxes — which box a project opens in, and managing the ones you have.
- Connecting — a workspace on another machine, with nothing installed on it.
- The doctor — reading a report, and why a capability comes back unavailable.
- Troubleshooting — the common failures, by symptom.
- Profiles — the three layouts that ship, and writing your own.
- Swapping parts, and theming — the five slots and the palette.
- The watermark — an image behind the terminal, off unless you ask.
- Security — what bothy verifies, and what it deliberately does not.
-
Walling off the agent — setting up
bothy confine. - What you can depend on — the stability contract.
- Where it runs — which terminals and stacks, and what is untested.
- What happens when you type bothy — the run, in order.
Every decision is numbered in docs/decisions.md, with
what was given up and what was refused.
Generated from wiki/ in the main repository. Edits made here are
overwritten; corrections belong in a pull request.