butai docs 1.3.0

Getting started#

Install butai, open a project, run an agent, and review your changes.

This manual describes butai 1.3.0. The installation instructions use the latest stable release.

1. Install#

On Linux or macOS:

curl -fsSL https://butai.dev/install.sh | sh
butai --version

The installer downloads the binary for your platform and installs it in /usr/local/bin or ~/.local/bin. If butai is not found, add the installation directory to your PATH; see Troubleshooting.

On Windows, under WSL2#

Install WSL from PowerShell with wsl --install, then run the commands above inside the Linux shell. Keep projects in the Linux filesystem, such as ~/projects, and run butai in that distribution.

For the experimental native build, see Windows downloads and setup.

2. Open a project#

cd ~/Projects/my-app
butai

butai attaches to your latest session or creates one with the current directory as its first workspace. It starts the background daemon automatically.

Each project has a tab. The left sidebar lists AGENTS, PROCESSES, and SYSTEM information. The right sidebar shows CHANGES in Git. The center stage shows the selected agent, process output, file, or diff.

3. Move around#

Key Action
alt-a / alt-p / alt-g Focus AGENTS, PROCESSES, or CHANGES
j / k Move through a sidebar
enter Open the selected item on the stage
alt-esc Return from the stage to the surrounding interface
? Open help when the stage is not focused
alt-d Detach from butai

When the stage is focused, ordinary keys go to the program running there. Use alt-esc before using sidebar shortcuts. If your terminal intercepts Alt, use the prefix key (Ctrl-b by default); see Keyboard shortcuts.

4. Put an agent to work#

Press alt-a, then A to choose an agent, or a to start the pinned agent. Press enter on its row and use it as you would in a terminal.

Install your agent CLI separately. The available agents are configured with [[agents]] blocks in ~/.butai/config.toml; see Agent configuration.

The sidebar shows whether an agent is working, idle, or needs your input. If its status is wrong, see Troubleshooting.

5. Bring up your dev server and tests#

Create .butai.toml in your project root:

[[processes]]
name = "dev"
cmd = "npm run dev"
ready = "Local:"

[[processes]]
name = "test"
cmd = "npm test -- --watch"

Replace these commands with the ones your project uses. ready is text to look for in the command's output; the process changes from run to ok when it appears.

Project configuration is read when a workspace is created. If it is already open, close it with alt-x (confirmation required), then reopen it with alt-n.

Select a process and press enter to view output, r to restart, or x to stop it. See Processes for more options.

6. Review and commit#

Press alt-g to focus CHANGES.

Key Action
d View the selected file's diff
s / u Stage / unstage the selected file
c Commit staged changes
C Stage everything and commit
p Push
g Open the Git menu

In a diff, use ] and [ to move between hunks and space to stage a hunk. See Git for partial staging, branches, worktrees, and other operations.

7. Walk away and come back#

Press alt-d to detach. Your agents and processes keep running in the background. To reconnect:

butai

If the daemon itself restarts, butai restores saved workspaces and relaunches processes. A process's in-memory state does not survive a restart.

If a crash leaves your terminal displaying mouse codes, run butai reset.

8. From another machine#

With butai installed on the remote machine, connect over SSH:

ssh dev-box butai

Replace dev-box with your SSH host. See Remote access to keep local and remote workspaces in the same workbench.

9. Driving it from a script#

The CLI can list workspaces as JSON:

butai ws ls --json

See Agent automation for reading panes, sending input, and waiting for an agent. The command-line reference lists every command and flag.

Where to go next#

    ↑↓ move ↵ open esc close