bough

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.