Repository navigation
Commands
One entry per command: what it does, and its flags. Anything with a page of its own is linked from its entry rather than explained twice.
bothy opens the workspace, bothy tower watches every agent at once, and
bothy doctor reports what is wrong. The rest are occasional.
bothy --help prints the same list.
Opens the workspace in the current directory: file browser across the top, the agent and a shell below. First run fills any gaps first — it lists what is missing, asks before downloading, then opens.
| flag | |
|---|---|
--dir <path> |
open somewhere other than the current directory |
--profile <name> |
use a layout profile other than the configured one |
--window |
always open a new Ghostty window |
--in-place |
always run in the terminal you are already in |
Closing the window ends the session, which is what closing a window usually means. Nothing written down is affected: the agent keeps its own transcript, so its conversation resumes with that agent's own command. What is lost is whatever turn was in flight.
Inside a container the multiplexer client would otherwise outlive the terminal
that opened it — podman exec ignores the hangup — and a session with a client
on it is refused, which used to mean the project could not be opened again. If
one is left behind anyway, by a crash or a kill, the next launch ends it and
says so:
bothy: reclaimed bothy-work from a closed window
A session someone is actually looking at is still refused; see [ADR-042] (https://github.com/lampseen/bothy/blob/main/docs/decisions.md) for how it tells the two apart.
--window and --in-place override bothy's own judgement for one run. It
normally decides by asking whether your terminal carries the Kitty keyboard
protocol an agent needs. To make the
override permanent, bothy config set workspace.launch here (or window); the
flags still win for a single run.
Reattach to this project's session, which has gone on without you. With no argument it picks the session for the current directory.
Which sessions are running, marking the one you are in and the ones nothing is looking at — and which have stopped but are still kept:
bothy-api the one you are in
bothy-notes detached
1 stopped, kept so it can be resurrected:
polite-galaxy
Clear them with 'bothy ls --prune'.
detached means the session is running with no window on it. That happens
when you detach with Ctrl-o d, which is the point of detaching. Closing a
window ends its session instead, so it will not appear here at all. When the
multiplexer cannot be reached, bothy reports that rather than reporting an empty
list.
A stopped session is one whose server is gone but whose layout zellij kept —
after a reboot or a crash, mostly, since the ordinary ways of ending a session
remove it outright. Attaching brings the layout back, though not quite as it
was: commands come back suspended behind "Waiting to run", and a profile changed
since then is ignored. Nothing removes them on their own, so they accumulate.
--prune deletes the stopped ones and refuses anything still running.
Ends a session without attaching to it. With no name, this directory's session.
$ bothy kill bothy-notes
ended bothy-notes
Nothing is left behind — the same end state as pressing Ctrl-q inside it. It
refuses the session you are currently in, because that is what Ctrl-q is for,
and refuses one that has already stopped, because that is what
bothy ls --prune is for.
The bindings most used in a session. They are Zellij's, not bothy's, and bothy does not change them.
One window showing every running agent, so several sessions can be watched from
one place. Each row mirrors one session's agent pane. Type into a mirror and the
line goes to that agent; type /take and the pane becomes that session, for a
prompt a sentence cannot answer. bothy composes nothing of its own either way.
| flag | |
|---|---|
--mirror <session> |
watch one session and nothing else |
--every <duration> |
the refresh interval |
--no-expand |
leave your panes as they are, at the cost of thin mirrors |
--restore |
collapse agent panes a closed terminal left expanded |
The tower — reading a mirror, answering an agent, taking one over, and why it expands the panes it watches.
Which toolbox this project opens in, and why:
$ bothy box
~/code/api
box dev
because this project is recorded for it
The reason matters as much as the name: several rules can decide it, and the one that answered is the one to change.
bothy box |
which box this project uses, and which rule chose it |
bothy box ls |
every box, whether it is running, and the sessions in it |
bothy box use <name> |
move this project to another box (host for none) |
bothy box stop <name> |
stop a box nothing is using |
bothy box create <name> |
make one, use it, offer to install the tools |
bothy box rm <name> |
delete one, and say where its projects open now |
Sessions are read from the process table, not from bothy's record, so a session
somewhere unexpected is listed where it actually is. use and rm end a
running session first and say so; --yes answers for you.
Toolboxes has the rules, the first-run prompt, and what happens on a machine with no toolboxes.
Opens the workspace against another machine. The file browser shows its files, the shell pane is a login session on it, and the agent can reach it the same way you can.
$ bothy connect <client>
directory on <client> [/]: /srv/api
ssh key, if that host needs one named [none]:
<client> mounted at ~/.local/share/bothy/cache/remotes/<client>
bothy puts nothing on the machine you connect to. It needs sshfs on your own
machine and refuses with the install command if it is missing. --dir sets
the directory without being asked; bothy connect edit <client> changes what was
remembered.
Inside the workspace, on <command> runs something on that machine in the
right directory — the agent needs it because the paths on the two machines
differ. Connecting explains all of it.
Runs the agent pane in a rootless podman container, with the project directory
and the agent's credentials mounted and nothing else from $HOME. Opt-in;
there is no setting that turns it on. See
Walling off the agent — including what it deliberately
does not stop.
Checks the workspace, with a fix attached to each failure. The doctor explains the output, the severities and the capability grouping.
Which tools are in use, which version, where each came from — bothy's own copy
or one already on your PATH — and, for the ones bothy fetched, where the
pinned checksum came from:
✓ fd a faster find 10.5.0 supplied by bothy pin: download
✓ ripgrep a faster grep 15.2.0 supplied by bothy pin: upstream
pin: upstream means the checksum in bothy.lock matched one the project
published, so the release cannot have been changed after publication.
pin: download means the project publishes no checksum, so the pin is the hash
of what bothy downloaded on the day it was pinned. Neither says the release
itself is good; see Security.
Prints the Zellij layout bothy would launch, generated from the profile, for checking what a profile produces before opening it.
bothy config # print the whole config
bothy config get <key> # one value
bothy config set <key> <value>
bothy config edit # open it in $EDITOR
bothy config path # where the file isconfig.toml carries schema = 1, which is bookkeeping rather than a setting —
config set refuses it. Unrecognised keys warn rather than fail, and bothy doctor names a retired key's replacement.
Writes the configs from your settings, then runs the doctor against the result.
Run it after changing a setting, or after replacing the binary. --dry-run
shows what it would write.
Every generated file says it is bothy's and names where to put your own changes.
Prints a blank eleven-token palette to fill in. Point bothy at the result with
bothy config set theme.palette <path>.
Prints the completion script for a shell. With --install, writes it where that
shell looks for it.
$ bothy completion bash --install
wrote ~/.local/share/bash-completion/completions/bothy
this is outside bothy's tree -- 'bothy uninstall' will not remove it,
but 'bothy completion bash --remove' will.
You need this only if bothy came from the install script, Homebrew or
go install. dnf, apt, pacman and the AUR place these files themselves.
Installing covers the zsh fpath line and why the
file sits outside bothy's tree.
Prints a .desktop launcher that opens the workspace in a directory.
--install writes it; --remove deletes it. It lands outside bothy's tree by
necessity, so bothy uninstall names it rather than removing it.
The version, and whether it is a release or a source build.
Which pinned tools have newer releases upstream. Reports; it does not upgrade.
The pins live in bothy.lock.
Works out how this copy was installed and prints the right command for it —
brew, dnf, apt, go install, the script, or a source build. It prints;
it does not upgrade.
Removes bothy's tree and the binary, and names what it leaves rather than
leaving you to find them. --dry-run shows what would go.
Installing lists what stays behind, and why.