docket

docket

Agent-shaped task tracker with a TDD execution harness, for solo and small-team coding work.

docket is a per-repo task store (single SQLite file, gitignored) plus a curated set of prompt templates that turn an agent's task pickup into a disciplined TDD loop. It complements git and GitHub — it does not replace them.

What docket owns vs. what it delegates

docket owns:

• Structured task definition with first-class acceptance (testable criteria) and deps fields
• A ready queue: the next task whose deps are all done
• Groups: a sequential-execution unit (multiple tasks, one branch, one PR)
• Four authored prompts (tdd-pursuit, create-task, commit, pr) embedded in the binary

docket delegates:

• File-level history → git (git log --grep='\[T-N\]')
• Code review, discussion, approval → GitHub PRs
• Project-level rollup → whatever PM tool you use

The line docket refuses to cross: workflow-engine territory. No formulas, no swarms, no DSLs. Orchestration belongs in the shell that calls docket ready in a loop, not in docket.

Install

Quick install (recommended)

curl -LsSf https://raw.githubusercontent.com/parzival1l/docket/main/install.sh | bash

Detects your platform, downloads the matching binary from the latest GitHub Release, verifies its SHA-256, and drops docket into ~/.local/bin. Re-run any time to update.

Make sure ~/.local/bin is on your $PATH:

export PATH="$HOME/.local/bin:$PATH"

To pin a specific version: bash -s -- --version v0.0.1. To install elsewhere: DOCKET_INSTALL_DIR=/somewhere/bin bash.

From source

git clone https://github.com/parzival1l/docket.git
cd docket
cargo install --path .          # → ~/.cargo/bin/docket

Single static binary. Tier-1 targets: macOS (x86_64, aarch64) and Linux (x86_64, aarch64).

Plugin (Claude Code)

docket ships with a Claude Code plugin that exposes the CLI verbs as slash commands inside an active session — /docket:create-task, /docket:start T-N. The plugin and the CLI are independent installs; the plugin shells out to the docket binary on your $PATH.

Install from inside Claude Code:

/plugin marketplace add parzival1l/docket
/plugin install docket@docket

That registers the marketplace and enables the plugin in ~/.claude/settings.json. Subsequent native sessions pick it up automatically. Update with /plugin marketplace update docket; pick up edits inside an active session with /plugin reload.

See plugin/CONVENTIONS.md for the pattern when adding new commands.

Cutting a release (maintainer)

Releases are tag-driven, but tagging itself is automated. You drive a single human signal — "the next version is X" — and the rest is mechanical.

One-time setup:

cargo install cargo-release

The flow:

# 1. Start a release branch off main
git checkout main && git pull
git checkout -b release/0.0.2

# 2. cargo-release bumps Cargo.toml + Cargo.lock, splits CHANGELOG.md
#    [Unreleased] into a new [0.0.2] - YYYY-MM-DD section, and commits as
#    `release: 0.0.2`. It does NOT push or tag (see release.toml).
cargo release 0.0.2 --execute

# 3. Edit the new ## [0.0.2] section in CHANGELOG.md to fill in entries,
#    then `git commit --amend` (or add a follow-up commit on the branch).

# 4. Push the branch and open a PR
git push -u origin release/0.0.2
gh pr create --title "release: 0.0.2"

Merging the PR fires .github/workflows/auto-tag.yml, which reads the version from Cargo.toml, creates and pushes v0.0.2, then triggers release.yml. That cross-builds all four targets, generates checksums, and publishes a GitHub Release with notes pulled from the matching ## [0.0.2] section of CHANGELOG.md.

To re-release an existing tag (e.g. after fixing the build pipeline): gh workflow run release.yml -f tag=v0.0.2.

See CHANGELOG.md for version history and release.toml for the cargo-release config.

Quick start

cd /path/to/your/repo
docket init                              # creates .docket/db.sqlite, appends .docket/ to .gitignore

docket add "uploader retries failed parts" \
  --acceptance "retries each part up to 3x; succeeds if any part succeeds" \
  --group "uploader-fixes"

docket add "uploader emits per-part metrics" \
  --acceptance "metric uploader_part_total has labels {status, attempt}" \
  --deps T-1 \
  --group "uploader-fixes"

docket ready                              # T-1 only — T-2 is blocked by T-1
docket done T-1                           # T-2 now ready
docket ready                              # T-2 surfaces

CLI