bough

bough [options]bough command [args]

bough is a terminal coding agent. Each model turn is one JavaScript program, not a list of single tool calls. The program runs in-process; tools.view, tools.patch, tools.bash, tools.spawn, and every MCP tool are ordinary functions, so a patch and the tests that check it can be one step, and the model can branch on results in code.The provider, loop, tools, TUI, web UI, MCP, hooks, and skills are rows in bough.yml. Saving that file mid-session remounts only what changed. Sessions are append-only JSONL under ~/.bough/history. There is no telemetry; the binary talks to the LLM provider you configure, the MCP servers you add, the public models.dev price list, and GitHub when you run bough update.Started inside a git checkout, file tools may write only under that checkout. Started anywhere else, the session is read-only. Skills use the same SKILL.md layout as Claude Code (~/.claude/skills and ./.claude/skills). API keys go in ~/.bough/env (ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, or CEREBRAS_API_KEY).

-c, --continue

Resume the most recent session.

Resume a session by id, or pick from a list.

Read prompts from stdin and print events on stdout. --json emits machine-readable events.

Override a plugin-row field for this run (for example llm.plugin=llm-echo or llm.model=...).

Start a project session whose shell runs in that project's container (macOS / Apple container today).

Local session (default): file tools may write only inside the git checkout bough was started in.

Config file (otherwise ./bough.yml, else ~/.bough/bough.yml, else the embedded default).

Browser UI (alternative to bough serve).

Kernel, MCP, and config diagnostics on stderr (also BOUGH_VERBOSE=1).

Print bough and the version.

Flags, subcommands, and config locations.

./bough.yml or ~/.bough/bough.yml

Plugin rows. Each row has id, plugin, and optional config. Example: set id: llm to plugin: llm-openrouter and config.model.

Environment file for provider API keys.

Startup script that can add tools, commands, and providers.

JavaScript hooks for session-start, user-prompt-submit, pre-code-exec, post-result, and stop. Re-read on every fire.

Append-only session logs.

serve

Web control room for sessions. First visit walks through an API key and a folder.

Print the live plugin-row state table and exit.

Pretty-print the latest session history. --raw prints JSONL.

List sessions, newest first.

Find sessions by content. Prefixes repo:, branch:, and since: narrow results.

Inspect and invoke configured MCP servers.

Compile session logs into a local markdown wiki under ~/.bough/wiki.

Pull/rebuild the binary in place and bounce a running web session.

Restart a recorded --web session.

macOS and Linux only; no Windows build. tools.bash is not sandboxed: it runs as you, with your files, credentials, and network. File tools refuse paths outside the checkout (including via symlinks), but the shell is not similarly confined. Project-session containers currently need macOS. Local sessions have no per-turn file checkpoints, so rewinding the conversation does not undo edits; use git. Headless unknown subcommands exit 2; a turn error exits 1.

bough is a one-person project by Andrey Lukin, written in Go, licensed Apache-2.0. The name is the word for a tree branch (pronounced like "now", /baʊ/): a conversation can fork and the old line stays as a branch.

claude(1), opencode(1), aider(1), git(1)

Source code · Documentation