bb-tui

module

v0.1.0 Latest Latest Go to latest Published: Sep 19, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/bborn/bb-tui

Links

Open Source Insights

README ¶

bb-tui

A terminal UI for bb, ported from the TaskYou TUI.

The board, thread view, composer, filters, saved views and command palette are TaskYou's, running against bb: threads instead of tasks, read from bb's API instead of from a local database.

The board

Threads are grouped by what they are doing, and a thread reads as a conversation — replies rendered as markdown, tool calls collapsed to a line each, with a composer underneath.

A thread

/ offers the project's skills and @ its files, both from bb.

Skill completion

Install

With Go:

go install github.com/bborn/bb-tui/cmd/bb-tui@latest

With Homebrew:

brew install --cask bborn/tap/bb-tui

Or take a binary from the releases page — macOS and Linux, arm64 and amd64.

From source:

git clone https://github.com/bborn/bb-tui && cd bb-tui
go build -o bin/bb-tui ./cmd/bb-tui

Run

bb-tui

bb has to be running. bb-tui finds its server through BB_SERVER_URL, then ~/.bb/bb-app-runtime.json, then http://127.0.0.1:38886. TUI-local state — themes, saved views, keybindings — lives in ~/.bb-tui/; everything about threads comes from bb and is never written locally.

Keys

key	does
`←` `→`	change column
`↑` `↓`	move within a column, or scroll a thread
`B` `P` `L` `D`	jump to Queued / Running / Waiting on you / Idle
`enter`	open a thread
`i`	write a message
`shift+↑` `shift+↓`	previous/next message
`ctrl+↑` `ctrl+↓`	previous/next thread
`ctrl+l`	jump to the latest message
`ctrl+g`	quote the message being read into the composer
`ctrl+t`	mouse capture on/off, for select and copy
`y`	answer an approval or question
`r`	retry a failed turn
`n`	new thread
`/`	filter; `V` saved views; `ctrl+p` palette

In the composer: enter sends, shift+enter is a newline, / offers skills, @ offers files, ctrl+o picks the model, ctrl+y the permission mode, ctrl+v attaches an image from the clipboard.

Screenshots

scripts/screenshots.sh regenerates them with VHS from an invented workspace (internal/bbstore/demo.go), so the images contain nobody's threads and need no bb server. bb-tui --demo opens that workspace directly.

Checking it without a terminal

bin/bb-tui --debug-state --keys "enter,shift+up" [--view]

Drives the real model headlessly and prints the view tree as JSON, or the rendered frame with --view.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
bb-tui command
internal
agentsend Package agentsend delivers a prompt to a task's live agent.	Package agentsend delivers a prompt to a task's live agent.
ai Package ai provides LLM-powered command interpretation for task management.	Package ai provides LLM-powered command interpretation for task management.
autocomplete Package autocomplete provides LLM-powered ghost text suggestions for task input.	Package autocomplete provides LLM-powered ghost text suggestions for task input.
bbapi
bbstore
completion Package completion holds the one authoritative implementation of "this task is finished".	Package completion holds the one authoritative implementation of "this task is finished".
config Package config provides application configuration from database.	Package config provides application configuration from database.
db Package db provides SQLite database operations.	Package db provides SQLite database operations.
events Package events provides a simple hook-based event system for task lifecycle events.	Package events provides a simple hook-based event system for task lifecycle events.
executor Package executor runs Claude Code tasks in the background.	Package executor runs Claude Code tasks in the background.
executorlock Package executorlock provides a per-task, cross-process "spawn lock" that serializes the check-window-then-start-executor critical section shared by the daemon executor and every ty TUI detail view.	Package executorlock provides a per-task, cross-process "spawn lock" that serializes the check-window-then-start-executor critical section shared by the daemon executor and every ty TUI detail view.
github Package github provides GitHub integration for querying PR status.	Package github provides GitHub integration for querying PR status.
handshake Package handshake is the daemon↔client version contract.	Package handshake is the daemon↔client version contract.
hooks Package hooks provides a system for executing scripts on task events.	Package hooks provides a system for executing scripts on task events.
mcp Package mcp provides an MCP (Model Context Protocol) server for workflow tools.	Package mcp provides an MCP (Model Context Protocol) server for workflow tools.
pipeline Package pipeline builds multi-step "workflow" tasks: a single goal is broken into a small DAG of step tasks that run on one shared git branch and advance automatically.	Package pipeline builds multi-step "workflow" tasks: a single goal is broken into a small DAG of step tasks that run on one shared git branch and advance automatically.
qmd Package qmd provides a client for QMD semantic search.	Package qmd provides a client for QMD semantic search.
reaper Package reaper finds and kills task side processes (dev servers, watchers, build daemons) that outlive the tmux window they were started in.	Package reaper finds and kills task side processes (dev servers, watchers, build daemons) that outlive the tmux window they were started in.
registry Package registry is the discovery half of TaskYou's plugin story.	Package registry is the discovery half of TaskYou's plugin story.
routine Package routine implements named, managed headless agent runs.	Package routine implements named, managed headless agent runs.
server Package server provides the SSH server using Wish.	Package server provides the SSH server using Wish.
taskfilter Package taskfilter parses the structured token grammar shared by every surface that filters tasks: the TUI filter bar, saved views, `ty list --view`, and the HTTP API.	Package taskfilter parses the structured token grammar shared by every surface that filters tasks: the TUI filter bar, saved views, `ty list --view`, and the HTTP API.
taskref Package taskref resolves the ways people name a task: "5187", "#5187", a task branch such as "task/5187-fix-login", or a GitHub PR URL.	Package taskref resolves the ways people name a task: "5187", "#5187", a task branch such as "task/5187-fix-login", or a GitHub PR URL.
tasksummary
textutil Package textutil holds small string helpers shared across ty.	Package textutil holds small string helpers shared across ty.
tmuxctl Package tmuxctl builds TaskYou's tmux commands and says which server each one goes to.	Package tmuxctl builds TaskYou's tmux commands and says which server each one goes to.
tmuxtest Package tmuxtest keeps tests off the live tmux server.	Package tmuxtest keeps tests off the live tmux server.
tuireload Package tuireload coordinates cooperative reloads through the task database.	Package tuireload coordinates cooperative reloads through the task database.
ui Package ui provides the terminal user interface.	Package ui provides the terminal user interface.
web Package web provides a lightweight HTTP server for the TaskYou kanban board.	Package web provides a lightweight HTTP server for the TaskYou kanban board.
web/ui Package ui serves the embedded TaskYou web frontend — the same React app the desktop shell renders, so browser and desktop share one codebase.	Package ui serves the embedded TaskYou web frontend — the same React app the desktop shell renders, so browser and desktop share one codebase.