A lightweight, terminal-first issue tracker built for teams that live in the CLI and work alongside AI agents. No database, no web UI — just structured Markdown files, a single ./task script, and git.
New here? Check out SETUP.md to install docket in your repo in under five minutes.
Most issue trackers are built around the browser. docket is built around the terminal — and around the reality that AI agents (Claude, Gemini, Copilot, Codex) are now doing a meaningful share of the work. It gives humans and agents a shared, consistent interface for picking up tasks, tracking ownership, and handing work off cleanly.
- Plain files — issues are Markdown, ownership is YAML, history is git
- Agent-native — lease-based claiming prevents agents from stomping each other
- Zero infrastructure — runs anywhere
bunruns, no server required - AI-assisted ingestion — dump rough notes into a scratchpad, let
./task ingestturn them into structured issues - Worktree-friendly — keep docket on an orphan
tasksbranch while running./taskfrom your repo root
# Install (see SETUP.md for full instructions)
curl -fsSL https://raw.githubusercontent.com/yfernandes/docket/refs/heads/main/scripts/setup.sh | bash
# Create an issue
./task new backend "Add rate limiting to cart endpoint"
# Or create a PRD-shaped issue
./task new product "Checkout v2 PRD" --template prd
# Triage it, then claim it and start working
./task triage add-rate-limiting-to-cart-endpoint ready-for-agent
./task claim add-rate-limiting-to-cart-endpoint --owner you
# Close it when done
./task close add-rate-limiting-to-cart-endpoint./task <command>
| Command | What it does |
|---|---|
list |
Browse issues — filterable by scope/status, --json mode |
new <scope> <title> |
Create an issue from a template |
claim <id> |
Take ownership, mark in-progress, auto-commit |
triage <id> |
Update the issue triage status |
release <id> |
Hand a task back to open |
close <id> |
Mark done, archive issue file, commit |
ingest |
Turn scratchpad bullets into issue files via AI |
render |
Rebuild the Active / Agent Queue sections of flow.md |
doctor |
Expire stale agent leases, surface drift |
lint |
Validate all system invariants |
Full usage: ./task help
- Drop rough notes into
flow.md → ## Issue Scratchpad - Run
./task ingestto formalize them into issue files - Run
./task list --status needs-triageto find fresh issues ./task triage <id> ready-for-agentwhen the issue is ready for pickup./task claim <id>to take ownership./task close <id>when done — or./task release <id>to hand back
Use --template <name> with new or ingest when the issue body should use
issues/templates/<name>.md instead of the default issue.md. For example,
./task ingest --template prd routes scratchpad bullets into the PRD shape.
| File | Role |
|---|---|
flow.md |
Daily tracker — your living view of the day |
assignments.yaml |
Source of truth for task ownership |
issues/<scope>/<slug>.md |
Structured issue files |
issues/templates/*.md |
Templates used by new and ingest |
skills/README.md |
Agent skill index and install map |
skills/agents/*.md |
Preconfigured skills for common AI agents |
skills/use-task-cli.md |
Generic fallback skill for unlisted agents |
Built-in scopes: backend, frontend, libs, cms — add more by creating folders under issues/.
Built-in templates:
| Template | Use case |
|---|---|
issue |
Default implementation/slice issue shape |
prd |
PRD issue shape for product requirements |
The recommended install keeps docket files in ./tasks/, an orphan git
worktree on a separate tasks branch, with a repo-root symlink at ./task.
When invoked through that symlink, the CLI still stages and commits inside the
task worktree. This keeps task-state commits out of the main application branch
while letting humans and agents use the short ./task ... command everywhere.
task claim, release, close, ingest, and other mutating commands commit
only docket-managed paths from the task worktree. If git staging or commit
fails, the CLI restores the touched task files before surfacing the error.
To update an existing install:
curl -fsSL https://raw.githubusercontent.com/yfernandes/docket/refs/heads/main/scripts/update.sh | bashRun the updater from the docket worktree itself (tasks/) or from the main repo
root if ./task points at that worktree. It warns before overwriting
distro-managed files. It updates task, root docs, skills/, scripts/, and
issues/templates/, but it does not overwrite flow.md, assignments.yaml,
live issues, backlog files, or archives.
Point your agent at the matching file in skills/agents/ and it will know how
to find, claim, release, and close tasks autonomously. Agent claims require a
--lease <minutes> so ./task doctor can expire abandoned work automatically.
Preconfigured skills are included for Claude Code, Codex, Gemini CLI, GitHub
Copilot, Cursor, Aider, Continue, and Windsurf. See skills/README.md for the
full matrix.
Claude Code — add to CLAUDE.md:
## Task system
@tasks/skills/agents/claude-code.mdCodex — add to AGENTS.md:
## Task system
Read `tasks/skills/agents/codex.md` before selecting, claiming, or closing
docket tasks.Gemini CLI — add to .gemini/GEMINI.md:
## Task system
@tasks/skills/agents/gemini-cli.mdSee SETUP.md for the full install matrix.
./task is the only sanctioned way to mutate task state. Never hand-edit assignments.yaml, the Active/Agent Queue sections of flow.md, or issue frontmatter — the CLI handles consistency and git commits atomically. Direct edits break invariants silently.
See RULES.md for the full invariant spec and STRUCTURE.md for the file layout.
Issues and PRs welcome. docket is a Bun/TypeScript script with no build step — clone, edit task, and run it directly.
git clone https://github.com/yfernandes/docket
cd docket
bun task helpMIT