Bramble

Bramble is a terminal UI for managing AI-assisted software engineering workflows. It orchestrates multiple parallel AI sessions across git worktrees, supporting both an interactive TUI and background tmux execution modes.

Key Features

• Dual execution modes — run AI sessions in-process (TUI mode) or in background tmux windows
• Multi-provider support — Claude, Codex, and Agy backends with auto-detection
• Worktree management — create, switch, sync, and delete git worktrees from the UI
• Parallel sessions — run planners and builders side-by-side on the same worktree
• Multi-repo support — manage sessions across multiple repositories in a single instance
• Session persistence — full JSONL recording with history browsing and replay
• Cost tracking — per-session token counts and USD estimates
• IPC interface — CLI commands to create sessions, send notifications, and integrate with external tools

Installation

Quick install (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/bazelment/yoloswe/main/scripts/install.sh | bash

This installs both bramble and wt to ~/.local/bin.

Homebrew

brew install bazelment/tap/bramble
brew install bazelment/tap/wt

Install script options

# Install only bramble
curl -fsSL https://raw.githubusercontent.com/bazelment/yoloswe/main/scripts/install.sh | bash -s -- --tool bramble

# Install a specific version
curl -fsSL https://raw.githubusercontent.com/bazelment/yoloswe/main/scripts/install.sh | bash -s -- --version v2026.03.29

# Install to a custom directory
curl -fsSL https://raw.githubusercontent.com/bazelment/yoloswe/main/scripts/install.sh | bash -s -- --dir /usr/local/bin

Quick Start

bramble                              # auto-detect mode (TUI or tmux)
bramble --session-mode tui           # force TUI mode
bramble --session-mode tmux          # force tmux mode

Session Modes

TUI Mode

TUI mode runs AI sessions in-process and renders output directly in the terminal using a rich BubbleTea-based interface. This is the default when not inside a tmux session.

When to use: Interactive work where you want to see AI output in real time and send follow-up prompts inline.

Tmux Mode

Tmux mode launches each AI session in its own tmux window. Bramble manages the window lifecycle and monitors session state from the TUI.

When to use: Running multiple long-lived sessions in parallel, especially when you want to switch between them or let them run in the background.

Key tmux features:

• Automatic tmux window creation per session
• Window monitoring and idle detection
• Pane capture for inspecting session output from the TUI ([v] in command center)
• Notifications via visual bell when sessions need attention
• Windows remain open on error for debugging

UI Overview

Main View

The main view shows the selected worktree's session output with a status bar and navigation controls.

Command Center (Alt-C)

A full-screen dashboard showing all sessions across all worktrees. Press [v] to toggle inline preview of tmux pane content, or [p/b/c] to start a new planner/builder/codetalk session on the selected worktree.

Session Types

• Planner (p) — AI planning sessions for task decomposition and design
• Builder (b) — AI implementation sessions that write code

Keybindings

Multi-Repo Support

Bramble can manage sessions across multiple repositories. Use Alt-R to switch between repos. Each repo maintains its own worktree list, session state, and configuration.

IPC Commands

A running Bramble instance exposes a Unix domain socket for external integration:

# Check if Bramble is running
bramble ping

# Create a new session
bramble new-session --type builder --branch feature/my-task --prompt "Implement X"

# Create a session on a specific repo
bramble new-session --type planner --repo my-other-repo --prompt "Design Y"

# Create a session with a new worktree
bramble new-session --type builder --create-worktree --branch feature/foo --from main

# List active sessions
bramble list-sessions

# Capture text from a tmux session pane
bramble capture-pane

# Notify Bramble that a session needs attention
bramble notify

Subagents

A session can spawn another session as its subagent. Pass --parent; inside a Bramble-spawned session it defaults to $BRAMBLE_SESSION_ID, so the flag is usually implicit.

# Spawn a Codex subagent on the parent's own worktree
bramble new-session --type codetalk --model gpt-5.5 --prompt "Explain the session lifecycle"

# Give it a worktree of its own instead
bramble new-session --type builder --create-worktree --branch fix/foo --prompt "..."

# Spawn a top-level session even from inside one
bramble new-session --no-parent --type planner --prompt "..."

# See just your own subagents
bramble list-sessions --parent=

With no --branch and no --worktree, a subagent works on its parent's worktree — the usual "helper on the same branch" case.

When a subagent finishes a turn, Bramble may drop a single disposable line into its parent's pane:

[bramble] subagent activity — check your run directory

It names no subagent, no status and no path on purpose: anything it carried could be read later and be wrong. It is a hint, not a delivery — dropped whenever the parent is busy or holds a draft, never queued and never retried. The record is what the lane itself wrote (a .done file, a commit, a branch), read back with bramble list-sessions and git, which is also what verifies it.

Backends differ in how Bramble learns a turn ended: Claude and Codex are given a completion hook, and Cursor — which has neither a notify flag nor a working CLI hook — has its idleness read off its pane. Agy has neither, so a subagent on that is only seen to finish when its window closes.

Because a session's status comes from Bramble's own view rather than the agent's cooperation, it is accurate whatever backend ran — which is what makes Codex, Cursor and Agy usable as subagents, none of which can be given a reporting instruction as reliably as Claude.

Messaging a session

send-input writes into a session's tmux pane immediately. That is right for a deliberate interrupt, but if the recipient is mid-turn the text lands in its next prompt, stripped of the context that made it make sense — and a TUI-mode session has no pane at all.

bramble send-input --session-id <id> --submit --text "also check the tests"

--queue is refused. Holding a message until the recipient looked idle meant guessing readiness from a pane and keeping undeliverable mail on disk; both halves misfired, and queues accumulated for days before replaying after a restart. To reach a subagent without interrupting it, wait for its status to go idle (bramble list-sessions) and then send.

Configuration

Settings are stored in ~/.bramble/settings.json:

{
  "theme_name": "dark",
  "enabled_providers": ["claude", "codex", "agy"],
  "repos": {
    "my-repo": {
      "on_worktree_create": ["./scripts/setup-worktree.sh"],
      "on_worktree_delete": ["./scripts/cleanup-worktree.sh"]
    }
  }
}

Themes

Switch between available themes with a live preview from the theme picker.

Per-Repo Hooks

Configure shell commands that run automatically on worktree lifecycle events:

• on_worktree_create — runs after a new worktree is created
• on_worktree_delete — runs before a worktree is deleted

Session Persistence

Sessions are recorded in JSONL format and stored in ~/.bramble/sessions/<repo>/<worktree>/. You can replay session logs with the built-in log viewer:

bazel run //bramble/cmd/logview -- path/to/session.jsonl

CLI Flags

Utility Tools

Development

To build from source (requires Bazel):

# Build
bazel build //bramble

# Run
bazel run //bramble

# Run with flags
bazel run //bramble -- --session-mode tui

# Run tests
bazel test //...

Architecture

Bramble follows an MVC architecture:

bramble/app/          VIEW        BubbleTea TUI components
bramble/session/      CONTROLLER  Session lifecycle, runners, persistence
bramble/sessionmodel/ MODEL       Canonical types, output parsing, observers
bramble/ipc/          IPC         Unix socket protocol for CLI integration
bramble/replay/       REPLAY      Multi-format log parsing (Claude, Codex, raw JSONL)

See docs/design/sessionmodel-architecture.md for a deep dive into the data pipeline.

Environment Variables