Repository-native project tracker
Your tasks belong
next to your code.
Workbook keeps project state in Git, beside the work it describes — for you and for the agents you hand work to.
brew install dgoings/tap/workbook
macOS and Linux, Apple Silicon and Intel. Other ways to install →
A tracker with no service behind it
A TODO.md travels with the repository and any agent can read it, but it has no structure, no validation, no dependencies, no useful queries, and no safe way for two people to edit it at once. A hosted tracker has all of that, and asks for an account, an API, a network, and a second place for context to drift away from the code.
Workbook sits in the middle. Task history is a chain of append-only operations stored in Git refs under refs/workbook/, pushed and fetched through the same origin your code already uses. Your checked-out branch never sees them. A disposable SQLite projection makes reads fast, and you can delete it at any time — Git stays canonical.
Travels with the repo
Clone, run one bootstrap command, and the project's tasks are there. No invite, no token, no second source of truth.
JSON is a first interface
Every mutating command takes --json and returns a versioned envelope, so scripts and agents get the same surface you do.
Syncs on its own
Commands fetch, replay onto the fresh tip, and publish the one ref they changed. An unreachable remote is a warning, not a failure.
Get started
Three commands from a fresh clone to a working board.
Install Workbook
From the Homebrew tap, or from source with Go — see below.
$ brew install dgoings/tap/workbookBootstrap a repository
workbook setup creates or validates the project's identity, installs agent documentation into the repo, and exchanges task refs with origin.
$ git clone https://github.com/you/your-project.git
$ cd your-project
$ workbook setup
Project ID: 01JQ8T4W9C7X2M0B6RGDVE5HKZ
Key: WB
Docs: .workbook/guidelines.md written
Sync: completedWork from the terminal
Create, query, and move tasks. workbook board draws a board in your terminal; workbook serve opens the same board in a browser.
$ workbook create "Fix the login redirect" --priority high
$ workbook list
$ workbook board # one column per status
$ workbook serve # the same board, in a browser
$ workbook show WB-14
$ workbook update WB-14 --status in-progressBuilt for coding agents too
An ephemeral agent clones the repo, claims a task remotely, reads its context, does the work, and disappears. workbook next --claim chooses the task and assigns it in the same command, publishing the claim as it goes, so two agents asking at once do not both walk away with the same task.
$ workbook next --claim --json # take the next eligible task
$ workbook show WB-14 --json # read its full context
$ workbook update WB-14 --status in-progress --json
# ... implement ...
$ workbook update WB-14 --status in-review --jsonworkbook setup writes this loop into the repository as managed agent documentation and a Workbook skill, so the agents you point at the project learn it without being told.
Install
Workbook is a single Go binary. Git is the only thing it needs at runtime.
Homebrew
Bottles for macOS and Linux, Apple Silicon and Intel.
$ brew install dgoings/tap/workbookPrebuilt archive
Every release ships macOS and Linux archives with checksums.
$ tar -xzf workbook_<version>_darwin_arm64.tar.gz
$ mv workbook ~/.local/bin/From source
Needs Go 1.26 or newer. Installs to ~/.local/bin, stamped with the commit it came from.
$ git clone https://github.com/dgoings/workbook.git
$ cd workbook
$ ./scripts/install.shThen workbook --help, workbook help <command>, or the command reference for everything else. The architecture notes cover the ref layout, operation packs, and synchronization semantics.