Repository-native project tracker

Your tasks belong
next to your code.

Workbook keeps project state in Git,
alongside 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, but 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 task state persists across any branch, any worktree, sandboxed, etc. Edits from your teammates sync automatically in the background. The Go CLI is fast and works at the speed of git, and it's offline-native.

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.

Independent, automated sync

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/workbook

Bootstrap 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:        completed

Work from the terminal

workbook serve gives you a human-friendly interface.
Or create, query, and move tasks directly from the CLI.

$ workbook create "Fix the login redirect" --priority high
$ workbook list
$ workbook serve            # interact in a browser
$ workbook show WB-14
$ workbook update WB-14 --status in-progress

Built for coding agents too

Workbook is designed specifically to be freindly in high-throughput, parallel agentic development. workbook next --claim is a deterministic rubric that chooses the next task to work on, 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. In a sandbox, an agent clones the repo, runs `workbook sync`, claims a task, reads its context, does the work updates the board, and disappears.

workbook 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.

JSON is a first-class interface

Every mutating command takes --json and returns a versioned envelope, so scripts and agents get the same surface you do.

Extremely fast performance

No grepping through giant TODO.md files. No multi-round trip MCP commands. Workbook meets agents where they are: on the command line. Save time, save tokens.

$ 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 --json

Install

Workbook is a single Go binary. Git is the only thing it needs at runtime.

Desktop app

Workbench discovers repositories, imports them as projects, and puts every board in one window. Installing it installs the CLI it bundles. macOS builds are signed and notarized, so the app opens like any other download.

Homebrew

Bottles for macOS and Linux, Apple Silicon and Intel.

$ brew install dgoings/tap/workbook

Prebuilt 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.sh

Then workbook --help, workbook help <command>, or the command reference for everything else. The architecture notes cover the ref layout, operation packs, and synchronization semantics.

Your tasks belong next to your code.