docs

One page. Everything it does.

docket is a single static binary over one SQLite file per repo. Every list and show command takes --json, so any agent that can run a shell can use it.

Install

macOS and Linux (x86_64, aarch64). The installer detects your platform, downloads the matching binary from the latest GitHub Release, verifies its SHA-256, and drops docket into ~/.local/bin. Re-run it to update.

$ curl -LsSf https://docket.parzival.computer/install.sh | bash

Make sure ~/.local/bin is on your $PATH. Pin a version with bash -s -- --version v0.0.4; install elsewhere with DOCKET_INSTALL_DIR=/somewhere/bin.

From source

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

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

That's dispatch. Any agent in any terminal runs docket ready --json, takes the first task, does it, runs docket done. Deps unblock the next one. No orchestrator, no model calls.

CLI

Every list/show command supports --json for agent consumption. Task ids are rendered T-N; commands accept both T-7 and 7.

Verb	Purpose
`docket init`	Create .docket/db.sqlite in the current repo, append .docket/ to .gitignore
`docket add <title>`	Create a task--body --acceptance --deps --priority --group --kind --backlog
`docket ls`	List tasks (hides backlog)--status --group --kind --json
`docket show T-N`	Full task with body, acceptance, deps with resolved states--json
`docket ready`	Tasks with status=open and all deps done — the dispatch queue (ignores backlog)--json
`docket blocked`	Inverse of ready: tasks with unmet deps (debug view; ignores backlog)--json
`docket backlog`	List tasks parked in the backlog--group --kind --json
`docket promote T-N`	Move a task from backlog to open
`docket status T-N <state>`	Set status: backlog, open, in_progress, done, or any string
`docket done T-N`	Convenience for docket status T-N done
`docket rm T-N`	Delete a task
`docket prompt <name>`	Print an embedded prompt: create-task, commit, pr, tdd-pursuit
`docket group new <name>`	Create a group--branch --description
`docket group ls`	List groups with done/total task counts--json
`docket group show <name>`	Group detail + its tasks--json
`docket group close <name>`	Mark a group closed

Schema

Two tables in .docket/db.sqlite. No archive, no audit, no comments, no labels.

tasks(id, title, body, acceptance, deps, status, priority, kind, group_id, created_at, updated_at)
groups(id, name UNIQUE, branch_name, description, state, created_at)

id is integer-incrementing; rendered as T-N.
deps is a JSON array of integer task ids, e.g. [3, 5]. The only link type is blocks.
status follows backlog → open → in_progress → done by convention. backlog is a parked state, invisible to ls, ready and blocked. blocked is computed from unmet deps, never stored.
priority is 0..4, default 2 — lower is more urgent. ready returns most urgent first.
kind defaults to feature; bug and chore are the other known kinds.
group_id is nullable — tasks don't have to be in a group.

Groups

A group is a batch of tasks that ship together: one branch, one PR. Tasks in a group run sequentially on that branch, so there's nothing to coordinate against — no locks, no claims. docket group close marks it finished; the PR body is aggregated from the tasks' acceptance.

The single bridge between docket and git is the [T-N] tag in commit messages. git log --grep='\[T-3\]' shows what changed for a task. docket does not track files, SHAs, or PR URLs — git already does.

Plugin (Claude Code)

Thin wrappers over the CLI, so they run instantly with no model turn. Requires docket on your $PATH. Install from inside Claude Code:

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

/docket:create-task: turn a one-line ask into a task with testable acceptance criteria
/docket:start T-N: pick up a task: mark in_progress, load its acceptance into the session

Update with /plugin marketplace update docket; pick up edits in an active session with /plugin reload.

Where data lives

.docket/db.sqlite: per-repo, gitignored by docket init. Per-developer state, no binary merge conflicts.
~/.local/bin/docket: the binary. Nothing else is written to your home directory.
git log --grep='\[T-N\]': the activity log. Done tasks stay in tasks with status=done.

No servers, no accounts, no network calls. Project-level rollup belongs to whatever PM tool you already use.