kbtz-tools

kbtz

A task tracker and workspace for coding agents. Backed by SQLite, designed for concurrent multi-agent workflows.

The name comes from "kibitz" -- to watch and offer commentary.

• See the status of all agents and tasks in one place — a terminal workspace shows a live task tree with status indicators for every running agent
• Press Tab to chat with the next agent that needs input — jump straight to the agent waiting for your attention, review its work, and move on
• Tasks and notes are under your control — work is tracked in a SQLite database you own, not hidden inside agent context windows
• Structure work with dependencies — parent/child and blocking relationships between tasks so agents work in the right order
• Unblocked tasks immediately get their own agent — when a task's dependencies are satisfied, the workspace claims it and spawns a new session automatically

kbtz has three components:

• kbtz-workspace — A terminal workspace with a built-in multiplexer. Manages concurrent agent sessions against a shared task database with a tmux-like interface for monitoring and interacting with them.
• kbtz-tmux — An alternative orchestrator that uses tmux as the session substrate. Same task orchestration, but delegates window management to tmux.
• kbtz — The underlying CLI that agents use to interact with the task database: creating tasks, setting dependencies, claiming work, and adding notes.

Install

cargo install --path kbtz             # task tracker CLI
cargo install --path kbtz-workspace   # workspace manager (built-in multiplexer)
cargo install --path kbtz-tmux        # workspace manager (tmux-based)

kbtz-workspace

kbtz-workspace is a terminal workspace manager that orchestrates multiple AI agent sessions against a shared kbtz task database. It automatically claims tasks, spawns agent sessions in PTYs, monitors their lifecycle, and reaps them when tasks complete — giving you a tmux-like interface over a fleet of concurrent agents.

Usage

kbtz-workspace [OPTIONS]

Flag	Default	Description
--db <path>	$KBTZ_DB or ~/.kbtz/kbtz.db	Path to kbtz database
-j, --concurrency <N>	4	Max concurrent agent sessions
--prefer <text>		FTS preference hint for task selection
--command <cmd>	claude	Command to run per session
--manual		Disable auto-spawning; use s to spawn manually

Screens

The workspace has three screens:

Task tree — the default view. Shows all non-done tasks in a tree with session status indicators. Navigate tasks, zoom into sessions, and manage task state (pause, done, force-unassign).

Task sessions — full-screen view of a single agent's PTY. The agent's terminal output fills the screen with a status bar on the last line. You interact directly with the agent (e.g. Claude Code) as if it were a normal terminal session.

Manager session — a dedicated session (not tied to any task) with an interactive agent for manipulating the task list: creating tasks, reparenting, blocking/unblocking, etc. Press c from the task tree to open.

Task tree keybindings

Key	Action
j / k, Up / Down	Navigate tasks
Enter	Zoom into session
s	Spawn session for selected task
r	Restart (kill and respawn) session
c	Switch to manager session
Space	Collapse/expand subtree
p	Pause/unpause task
d	Mark task done
U	Force-unassign task
Tab	Jump to next session needing input
?	Help
q / Esc	Quit (releases all sessions)

Task session keybindings

All commands use a Ctrl-B prefix (like tmux):

Key	Action
^B t	Return to task tree
^B c	Switch to manager session
^B n	Next session
^B p	Previous session
^B Tab	Jump to next session needing input
^B [	Enter scroll mode
^B ^B	Send literal Ctrl-B to agent
^B ?	Show help
^B q	Quit

Page Up and left-click also enter scroll mode.

Scroll mode

Scroll mode freezes the session output and renders the frozen viewport directly over the current screen with mouse tracking disabled. This enables:

• Scrolling via keyboard (j/k, arrows, PgUp/PgDn, g/G)
• Native text selection via click-drag, with copy using your terminal's native shortcut (Ctrl+Shift+C on Linux, Cmd+C on macOS)

Key	Action
q / Esc	Exit scroll mode
k / Up	Scroll up 1 line
j / Down	Scroll down 1 line
PgUp / PgDn	Scroll by page
g	Jump to top of scrollback
G	Jump to bottom and exit scroll mode

Session lifecycle