fbtodo

Watch your coding agent work — its checklist, live, in a pane beside it.

fbtodo displays your Freebuff agent's task list in a side pane while it works. It shows:

• What's done, running, and next — with live timers
• How much time is left — estimates based on your project history
• If it's stuck or waiting — with optional alerts to your phone

No configuration: it reads the list your agent already keeps. Freebuff's list turns up on its own; anything else can push one over stdin — see docs/SOURCES.md.

Installation · Commands · FAQ · Install guide · Settings · Deep docs

See it work

The clip above shows - fbtodo pane in real time. It monitors a scripted session through eight steps, updating continuously until all tasks are marked complete and the session ends—the exact trigger required for the notification bell.

Side-by-Side View

To see how the pane mirrors the active session, here is the side-by-side pairing: the scripted session on the left, and the fbtodo pane tracking it on the right:

Note: The recording script exports animations as lossless WebP files rather than standard video formats. This ensures crisp, pixel-perfect inline rendering directly within GitHub Markdown.

Installation

One line — takes the first method your machine already has (Homebrew, uv, pipx, a plain venv, or a clone), and never runs as root:

curl -fsSL https://raw.githubusercontent.com/TLE47/fbtodo/main/install.sh | sh

Homebrew

brew install TLE47/tap/fbtodo     # brew taps it for you

uv / pipx — an isolated venv, nothing to manage on your PATH:

uvx fbtodo                        # run it once, install nothing
uv tool install fbtodo            # ...or keep it
pipx install fbtodo

From the checkout — no install at all:

brew install tmux                 # or: apt install tmux
git clone https://github.com/TLE47/fbtodo ~/Projects/fbtodo
mkdir -p ~/.local/bin && ln -sf ~/Projects/fbtodo/fbtodo ~/.local/bin/fbtodo
tmux new -s work
fbtodo                            # opens the pane automatically

Requirements: Python 3.9+ and tmux. If the pane does not appear, run fbtodo doctor — it names what is missing. Every route, with pinned versions and how to uninstall, is in docs/INSTALL.md.

Using the fb shortcut (optional)

For a one-word launcher that updates and manages everything:

. ~/Projects/fbtodo/examples/fb.sh    # add this line to ~/.zshrc or ~/.bashrc
fb                                    # now use 'fb' instead of 'fbtodo'

One lazy command:

echo '. ~/Projects/fbtodo/examples/fb.sh' >> ~/.bashrc && source ~/.bashrc && fb

Updating and pinning

Each installer updates itself — brew upgrade fbtodo, uv tool upgrade fbtodo, pipx upgrade fbtodo. To pin a release, name it; the tag is the version:

uv tool install fbtodo==4.30.0
pipx install fbtodo==4.30.0
pipx install "git+https://github.com/TLE47/fbtodo@4.30.0"   # from the tag

No Python dependencies are required, though displaying the pane still needs tmux.

How it works

Your agent writes a todo list (by calling write_todos). fbtodo watches that list and displays it in a side pane. The pane updates in real time as the agent works through tasks.

No configuration needed — fbtodo reads the list your agent already creates. Just make sure your agent is keeping one. You can ask it once per session: "Plan this as a todo list and check off items as you go."

Commands

fbtodo              # watch the pane (default)
fbtodo bar          # show "todos 3/5" in your status bar
fbtodo snap         # print one snapshot
fbtodo status       # show pane info and why it might be empty

Other commands: ledger (forecast vs. actual), why (pane location), pin (resize pane), stop (close watcher), prune (clean up old data).

Run fbtodo -h for all flags.

Customization

Colors

Create ~/.config/fbtodo/theme.json:

{
  "accent": "#89b4fa",
  "active": "#cdd6f4",
  "success": "#a6e3a1"
}

Or use environment variables:

export FBTODO_ACCENT="#89b4fa"
export FBTODO_SUCCESS="#a6e3a1"

Three presets are included in examples/ (Catppuccin, Gruvbox, Nord).

Pane size and position

fbtodo pin --size 24 --side h    # 24 columns wide, beside the session
fbtodo pin --size 12 --side v    # 12 lines tall, below the session
fbtodo pin --list                # show current settings

--size is counted along the split: columns for --side h (the pane sits beside the session) and lines for --side v (below it). The pane remembers your last size and opens that way next time. Default: 12 lines below.

Disable the pane

If you only want the status bar:

export FBTODO_NO_PANE=1
fbtodo bar        # just show "todos 3/5"

Alerts (optional)

Get notifications when your agent finishes, gets stuck, or asks for input:

# Install the notification kit
mkdir -p ~/.config/freebuff-notify
cp scripts/notify/*.py scripts/notify/*.sh ~/.config/freebuff-notify/
chmod +x ~/.config/freebuff-notify/*.sh
~/.config/freebuff-notify/phone.sh --init

See scripts/notify/README.md for details on iMessage and ntfy alerts.

Troubleshooting

FAQ

For developers

Run the test suite:

python3 scripts/fbtodo-selfcheck.py      # full suite (~90-160 seconds)
python3 scripts/fbtodo-selfcheck.py --only local-session   # one test
bash scripts/notify/test-freebuff-notify.sh   # notification tests

License

MIT — see LICENSE.