---
title: "Todo list for pane agents"
description: "The todo_list tool for pi in a herdr pane: pi-todo-list's state machine with the list kept in a file per working directory under ~/.local/state/foxline/todo-list/, so it survives new sessions; how to load it on pi 0.84.x (FOX9_TODO_LIST=1 pi -e ..., or just install-fox9-todo-list-local). Not part of the voice loadout."
type: "living"
source: "catalog/pi/extensions/fox9-todo-list/README.md"
verified: "2026-11-14"
group: "The brain"
---

> **Living doc**, checked against the code 2026-11-14

fox9-todo-list — `todo_list` for pane pis

[@fitchmultz/pi-todo-list](https://github.com/fitchmultz/pi-todo-list) 0.6.1 (MIT) with one change: the list lives in
a file, not in the session, so a new session in the same worktree opens the same list. The list is a 0600 JSON file
under `~/.local/state/vulpine/todo-list/`, one per working directory (`<dir name>-<digest of the full path>.json`).
`VULPINE_TODO_LIST_FILE` names another file.

- Statuses are `pending | in_progress | completed`. The mutations are `add / update / move / start / pause / complete /
  reopen / remove / clear_completed`, plus an atomic `batch` of up to 100, nesting, and a paged `list` of open items.
- The extension registers the tool, a `/todos` command (`/todos all` includes completed items) and a footer status.
- Every call takes a lock file (`<list>.lock`, stale after 15 s), so two pane agents on one list keep each other's
  changes. A file that cannot be read is moved aside (`<list>.unreadable-<time>`), and the agent is told.
- After a compaction, the next turn gets one bounded summary of the open items as a hidden message.

**Gate.** It loads in a Pi running in a herdr pane (`HERDR_ENV=1` and a `HERDR_PANE_ID` like `w1:p3`), or anywhere with
`VULPINE_TODO_LIST=1`. Otherwise it registers nothing. It is **not** part of the voice loadout: the brain has its own
`pi_todo`.

## Loading it in Pi

One-off, in any terminal or herdr pane:

    VULPINE_TODO_LIST=1 pi -e catalog/pi/extensions/fox9-todo-list/index.ts

Installed for every Pi in a herdr pane on this machine (a directory extension, auto-discovered, `/reload` picks it up):

    just install-fox9-todo-list-local      # → ~/.pi/agent/extensions/fox9-todo-list/{index.ts,todo-state.ts,LICENSE}

Then ask the pane agent: "put 'fix the fleet-probe timeout' on the todo list", "what's open?", "start the first
one". A new Pi session in the same directory still has the items. `/todos` shows the list without a model call.

