Overview

What bothy is, the problem it solves, and when to use it.

bothy gives each git worktree its own development environment. A worktree is one checkout of a repository, in its own directory. The environment has two parts: the tools that the project needs, such as node or python, and the services that it runs against, such as postgres or redis.

You describe the project one time, in a bothy.yaml file that you commit. When you cd into a worktree, bothy puts the tools on your PATH, starts the services on private ports, and exports variables such as DATABASE_URL that point at them. When you leave, bothy stops the services and gives your PATH back.

There are no containers and no virtual machines. Every tool and every service is a plain process on your machine.

The problem

A project needs more than its code. It needs one version of node, a postgres, a redis and a dev server. Most teams solve this one time per machine:

  • You install postgres with brew, and it listens on port 5432.
  • You install node with a version manager, and you hope that it is the right version.
  • You copy a .env from a teammate, and it points at localhost:5432.

This works for one checkout. It stops working when you have two at the same time:

  • Two dev servers want the same port, and the second one fails to start.
  • Two branches share one database. A migration on one branch breaks the other branch.
  • A test run on one branch deletes the data that another branch uses.
  • A tool that a project needs is on your machine, but not on the machine of a teammate, or in CI.

You get two checkouts at the same time more often now. You keep a second worktree for a review. You run three agent sessions, each on its own branch. Each of them needs a complete stack, and the stacks must not touch each other.

What bothy does

bothy gives every worktree its own copy of everything:

part what bothy does
Tools Puts the exact package versions from bothy.yaml on your PATH, inside the worktree only.
Services Starts each service, waits until it is ready, and stops it when you leave.
Ports Gives each service a port that no other worktree uses.
Data Gives each service a data directory that no other worktree uses.
Variables Exports the ports and URLs, so your code finds the services.

A second worktree of the same repository gets new ports and new data. The two stacks run at the same time and cannot reach each other. The cd is the whole setup.

In this session, a cd into app starts its postgres and redis. A second worktree, app-review, gets its own postgres on another port. The shell then leaves app. Its services keep running for the grace period of 60 seconds, and then bothy stops them.

When to use bothy

Use bothy if one or more of these is true:

  • You work on more than one branch at the same time, with git worktree or with separate clones.
  • You run coding agents in parallel, and each agent needs a database and a dev server.
  • Your project needs services, and you want a new contributor to get them with one command.
  • You want the same tool versions on your machine, on the machine of a teammate, and in CI.
  • You use Docker Compose only to run a database on your laptop, and you want plain processes instead.

bothy is probably not the right tool in these cases:

  • Your project has no services and one version of each tool is enough. A version manager such as mise does this job.
  • You must run the same container images that you deploy. Use Docker Compose.
  • You develop on Windows outside WSL2, or on an Intel Mac. bothy has no release for these machines.

How bothy works

bothy has four parts. You do not manage any of them by hand.

  • The bothy command. You run it, and the shell hook runs it for you.
  • The shell hook. It is one line in your shell’s rc file. At each prompt, it tells bothy which worktree you are in, and exports the variables.
  • The daemon. It is a background process, bothyd, that starts when you need it. It starts the services, keeps their ports and data, and stops them when the last shell leaves the worktree.
  • Nix. Nix is a package manager that installs exact package versions side by side. bothy uses it to get each tool and each service binary. bothy installs Nix for you, and you do not write any Nix.

bothy.yaml is the only file that you write. bothy keeps its state in ~/.local/state/bothy, outside your repository.

bothy is in beta

The daemon, the CLI, the schema and the Nix support work today, and bothy runs its own development and CI. Until version 1.0, these things can change between releases:

  • The fields of bothy.yaml.
  • The names, flags and output of the commands, including the JSON of --json.
  • Where bothy keeps its state on disk.

The install script always installs the latest release. Before you update, read what the release changed. If you build scripts or CI steps on the output of bothy, use the --json forms, and expect to change them when bothy changes.

Where to go next

  • Install puts bothy and Nix on your machine.
  • Getting started takes you from an empty project to two worktrees that run at the same time.
  • Configuration explains every field of bothy.yaml.
  • CI runs the same environment in GitHub Actions and other CI systems.