# bough

> A terminal coding agent where the model writes one JavaScript program per turn instead of calling tools one at a time, enabling batched, branching actions in a single round trip.

bough is an open-source terminal coding agent written in Go, created by Andrey Lukin and released under the Apache-2.0 license. Rather than exposing a list of discrete tools the model calls one at a time, bough gives the model a JavaScript runtime where it writes a full program per turn — patching files, running shell commands, and calling MCP tools as ordinary function calls in the same script. The project reached v0.2.7 as of September 2026 and is described by its author as a one-person project in daily use.

## What It Is

bough is a CLI-first coding agent that implements what the README calls "code mode": the model responds with a JavaScript block, bough executes it, and the output feeds back into the next model turn. This means a single model response can patch a file, run tests, inspect the diff, and branch on the result — all without an extra round trip. The approach is grounded in prior research; the README cites the CodeAct paper (arXiv 2402.01030) and draws comparisons to HuggingFace's smolagents and Cloudflare's Code Mode. bough positions itself closest to Claude Code, opencode, and pi, and deliberately borrows their conventions (AGENTS.md/CLAUDE.md, skills, hooks, MCP, subagents) while differing architecturally.

## The Code-Mode Architecture

The core design decision is that every tool — `tools.view`, `tools.patch`, `tools.bash`, `tools.spawn`, and any MCP tool — is a plain function inside the JavaScript runtime. The model writes one program that can call several of them, loop over results, and conditionally branch, rather than waiting for the agent loop to dispatch each call separately. The author's own session logs (September 2–15, 2026, mostly `openai/gpt-6-astra`) show 735 turns running 5,521 programs that made 10,542 tool calls — 1.9 per program — with 52% of programs making more than one call and 30% using control flow (`if`, `for`, `try`).

## Plugin-First Design

bough is structured as a small kernel where every component is a plugin row in a YAML file:

- **Provider** — Anthropic, OpenAI, OpenRouter, or Cerebras (bring your own key)
- **Loop, tools, TUI, web UI, MCP, hooks, skills** — all replaceable rows
- **Live reload** — saving `bough.yml` mid-session remounts only changed rows; the conversation survives because context is rebuilt from the append-only JSONL session log
- **`init.js`** — adds tools, commands, or whole providers in a few lines without writing Go
- **Go plugins** — new rows can be written in Go for deeper integration

## Three Interfaces

bough ships three ways to interact with it:

- **`bough`** — a terminal UI (built with Bubbletea) with a `/` command palette, `@file` references, `!shell` escapes, `esc esc` to rewind, and `-c` to resume a session
- **`bough serve`** — a web control room showing live transcripts, pending questions, and pasted images; the first visit walks through adding a key and picking a repo
- **`bough --headless`** — stdin-in, events-out mode with `--json` for scripts and benchmarks

Sessions are stored as append-only JSONL under `~/.bough/history`, enabling resume, search, and mid-conversation model switching.

## Safety Model and Known Gaps

File tools are scoped to the git checkout bough started in; `tools.write` and `tools.patch` refuse paths outside it. The shell (`tools.bash`) runs as the user with no sandbox by default. For an enforced boundary, `bough --project <slug>` runs the shell inside a Linux container (Apple `container`, macOS only for now) with per-turn git worktree snapshots and `/undo` support. The README explicitly notes: no Windows build, container sessions require macOS, local sessions have no per-turn file checkpoints, and the usage numbers come from one person's sessions rather than a controlled benchmark.

## Update: v0.2.7

The latest release is v0.2.7, published September 15, 2026. The repository was last pushed on September 18, 2026, indicating active development. The project also ships an LLM wiki feature (`bough wiki install`) that has an agent compile session logs into cited markdown pages of decisions, root causes, and gotchas — readable in `bough serve` with claims shown beside their source log entries.

## Features
- Code mode: model writes one JavaScript program per turn instead of calling tools one at a time
- tools.view, tools.patch, tools.bash, tools.spawn and MCP tools as plain JS functions
- Plugin architecture: every component (provider, loop, tools, TUI, web UI) is a YAML row
- Live reload: saving bough.yml mid-session remounts only changed rows
- Supports Anthropic, OpenAI, OpenRouter, and Cerebras providers
- Append-only JSONL session history with resume, search, and mid-session model switching
- Terminal UI with / palette, @file references, !shell escapes, esc esc rewind
- bough serve: web control room with live transcripts and image paste
- bough --headless: stdin/stdout mode for scripts and benchmarks
- MCP (Model Context Protocol) tool integration
- Hooks: plain JS files that run on session events (session-start, pre-code-exec, post-result, etc.)
- Skills: CLAUDE.md-compatible skill definitions loaded by name in prompts
- Project sessions: shell runs in Linux container with per-turn git worktree snapshots and /undo
- LLM wiki: agent compiles session logs into cited markdown pages
- File tools scoped to git checkout for safety
- init.js for adding tools and providers without writing Go
- No telemetry
- macOS and Linux, x86-64 and arm64

## Integrations
Anthropic Claude, OpenAI, OpenRouter, Cerebras, MCP (Model Context Protocol) servers, Git, Apple container (macOS), Homebrew, Go toolchain, Bun (web UI build), Playwright (web UI tests)

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
v0.2.7

## Links
- Website: https://github.com/andreylukin/bough
- Documentation: https://github.com/andreylukin/bough/blob/main/go/README.md
- Repository: https://github.com/andreylukin/bough
- EveryDev.ai: https://www.everydev.ai/tools/bough