docket

Docket

Issue tracking for AI and humans.

Docket is a local-first, SQLite-backed CLI issue tracker that lives inside your repository. It provides enterprise-grade issue tracking without requiring a server, network connection, or third-party service.

Docket serves two audiences equally: human developers who want a fast, beautiful terminal experience with rich styling, and AI coding agents that need structured, machine-readable output to plan and execute work. Every command renders colorful, styled output by default and clean, parseable JSON with --json. Neither mode is an afterthought. Both are first-class.

Installation

Quick Install

curl -fsSL https://raw.githubusercontent.com/ALT-F4-LLC/docket/main/scripts/install.sh | sh

This installs the latest nightly build to $HOME/.local/bin.

Customize with environment variables:

# Install a specific version
DOCKET_VERSION=v1.0.0 curl -fsSL https://raw.githubusercontent.com/ALT-F4-LLC/docket/main/scripts/install.sh | sh

# Install to a custom directory
DOCKET_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/ALT-F4-LLC/docket/main/scripts/install.sh | sh

Agent Skill Setup

If you're working with Docket through an AI coding agent, also install the companion skill so the agent has the full CLI workflow and command reference available without re-deriving usage from --help output. Copy this repo's skills/docket/SKILL.md into your agent's skill directory:

# Claude Code (project-scoped)
mkdir -p .claude/skills/docket && cp skills/docket/SKILL.md .claude/skills/docket/SKILL.md

# Codex (project-scoped)
mkdir -p .agents/skills/docket && cp skills/docket/SKILL.md .agents/skills/docket/SKILL.md

# Opencode (project-scoped)
mkdir -p .opencode/skills/docket && cp skills/docket/SKILL.md .opencode/skills/docket/SKILL.md

See Drop-in Skill for what the skill teaches.

From Source

Requires Go 1.26.0+ (toolchain go1.26.5).

# Build the binary to ./bin/docket
make build
./bin/docket --help

# Install to $GOPATH/bin
make install

Quick Start

# Initialize a new issue database in the current directory
docket init

# Create an issue with priority and type
docket issue create -t "Build auth module" -p high -T feature

# Create a sub-issue that depends on the first
docket issue create -t "Set up database schema" -p high -T task --parent DKT-1
docket issue link add DKT-2 depends-on DKT-1

# See what's ready to work on (unblocked, sorted by priority)
docket next

# View the Kanban board
docket board

AI agents: add --json to any command for structured, machine-readable output:

docket next --json
docket issue list --json -s todo -s in-progress

Why Docket?

• No servers, no network — everything is a local SQLite file in .docket/. Works offline, on planes, in CI.
• AI-native from day one — every command supports --json with a consistent envelope. Agents can create, query, plan, and update issues without parsing human text.
• Dependency-aware planning — docket next and docket plan use a DAG to surface only unblocked, work-ready issues. No stale sprint boards.
• Zero configuration — docket init and you're done. No accounts, no tokens, no YAML.
• Portable data — the .docket/ directory travels with your repo. Clone it, fork it, archive it.

AI Agent Integration

Every command supports --json for structured, machine-readable output. All JSON responses use a consistent envelope:

Success: {"ok": true, "data": { ... }, "message": "..."}

Error: {"ok": false, "error": "...", "code": "NOT_FOUND"}

Error codes: GENERAL_ERROR (exit 1), NOT_FOUND (exit 2), VALIDATION_ERROR (exit 3), CONFLICT (exit 4).

Recommended Agent Workflow

1. Read the backlog — docket next --json to get unblocked, priority-sorted issues.
2. Pick an issue — docket issue show DKT-N --json to read full details, sub-issues, and relations.
3. Work on it — docket issue move DKT-N in-progress --json to signal you've started.
4. Complete it — docket issue close DKT-N --json when done, or docket issue move DKT-N review --json if it needs review.
5. Check what's next — docket next --json again. Dependencies auto-resolve; newly unblocked work appears.

Configuring Claude Code

Add to your project's CLAUDE.md:

Use `docket` for issue tracking. Always pass `--json` when reading or updating issues.
Run `docket next --json` to find work. Move issues to `in-progress` before starting.

Configuring Other Agents

Any agent that can run shell commands works with Docket. Point it at docket next --json to discover work items, and use docket issue show <id> --json to get full context before starting a task. The consistent JSON envelope (ok, data, error, code) makes parsing straightforward in any language.

Drop-in Skill

skills/docket/SKILL.md is a thorough reference teaching the full Docket CLI workflow and command/flag reference in one file, so your agent doesn't need to re-derive usage from --help output. See Agent Skill Setup in the Installation section above for where to drop it in for Claude Code, Codex, and Opencode.

docket issue create --json -t "Build auth module" -p high -T feature --parent DKT-3

{
  "ok": true,
  "data": {
    "id": "DKT-12",
    "parent_id": "DKT-3",
    "title": "Build auth module",
    "description": "",
    "status": "backlog",
    "priority": "high",
    "kind": "feature",
    "assignee": "",
    "labels": [],
    "created_at": "2026-02-13T18:30:00Z",
    "updated_at": "2026-02-13T18:30:00Z"
  },
  "message": "Created DKT-12"
}

docket next --json

{
  "ok": true,
  "data": {
    "issues": [
      {
        "id": "DKT-7",
        "title": "Set up database schema",
        "status": "todo",
        "priority": "high",
        "kind": "task",
        "assignee": "",
        "labels": [],
        "created_at": "2026-02-13T18:30:00Z",
        "updated_at": "2026-02-13T18:30:00Z"
      }
    ],
    "total": 1
  }
}

docket plan --json --root DKT-3

{
  "ok": true,
  "data": {
    "phases": [
      {
        "phase": 1,
        "issues": [
          {
            "id": "DKT-7",
            "title": "Set up database schema",
            "priority": "high",
            "status": "todo"
          }
        ]
      }
    ],
    "total_issues": 5,
    "total_phases": 3,
    "max_parallelism": 2
  }
}

docket issue list --json -s todo -s in-progress -p high

--json        Structured JSON output (for agents and scripts)
--quiet, -q   Suppress non-essential output

Configuration

Database Location

Docket keeps ONE shared SQLite store at ~/.docket/issues.db, serving every project on the machine. Each repository is a project in that store, keyed by a worktree-stable identity (the git common directory), so every worktree of a repository — including throwaway ones — reads and writes the same issues.

Resolution order, checked on every invocation:

1. DOCKET_PATH — points directly at a .docket directory (the database file is $DOCKET_PATH/issues.db). The escape hatch for custom layouts and for reaching a legacy repo-local store.
2. A repo-local .docket/issues.db — discovered by walking up from the current directory to the worktree root. Pre-global stores keep working exactly as before, now from subdirectories too. Create one deliberately with docket init --local (and gitignore it).
3. ~/.docket — the shared store. docket init creates it.

Use docket config to see the resolved store, its source (env / local / global), the execution root, and the project identity.

Instance configuration (workflows, schemas, contracts, fragments, policy) is read from an ordered list of roots, and activation registers and pins the union of what they hold:

With the shared store, ~/.docket/config/ is the corpus every project draws from and a repository's own .docket/config/ adds to it — so a repo that ships nothing needs no .docket/ directory at all, and a linked worktree resolves the same files as the checkout beside it. A root that does not exist is skipped; a root that is a broken symlink is an error, because a broken install must not look like having no config. A workflow, schema, or pinned file offered by two roots with different bytes refuses the activation and names both paths — which is what makes "first root wins" a rule rather than a coin flip.

docket workflow init writes into the repository's root, never the shared one.

Consolidating legacy per-repo stores

Move an old repo-local database into the shared store with export/import — colliding ids are remapped automatically, nothing is dropped:

DOCKET_PATH=/path/to/repo/.docket docket export -f repo.json
cd /path/to/repo && docket import repo.json

Multiple projects, one store

Issue ids (DKT-N) stay globally unique across projects, so an id names one issue machine-wide. docket project set-prefix VOR gives a project its own display voice — issues render and parse as VOR-N there, while DKT-N and bare numbers keep working everywhere, because the number is the identity. docket project list shows the store's projects. Lists, boards, plans, labels, workflows, schemas, and engine configuration are scoped to the invoking project; docket config set writes a per-project override, or a store-wide default with --global. The event feed (docket events list) is project-scoped too — store-level events like trust changes always show — with --all-projects for the whole stream.

Statuses

Issues follow a Kanban workflow with five statuses:

Priorities

Issue Types

Issue ID Format

Issues use the DKT-N format (e.g., DKT-1, DKT-42). The DKT prefix is constant and IDs auto-increment within each database. Commands accept both the full prefixed form (DKT-5) and the bare number (5).

Architecture

cmd/
  docket/          Entry point (main.go)
internal/
  cli/             Cobra command definitions (one file per command)
  config/          Configuration resolution (DOCKET_PATH, defaults)
  db/              SQLite queries and migrations
  engine/          Run activation, claims, gates, and the dispatch saga
  exec/            Registered-command execution with env policy and capture
  filter/          Shared filtering helpers
  model/           Domain types (Issue, Status, Priority, Activity, etc.)
  output/          JSON envelope writer (ok/data/error/code)
  planner/         DAG builder, topological sort, phase planner
  render/          Lipgloss-based terminal rendering (tables, board, graphs)
  schema/          Payload validation and the ordered_enum annotation
  testsupport/     Helpers shared across the repo's test packages
  trust/           User-level allowlist of commands Docket may execute
  watch/           Live-updating watch output
  workflow/        Workflow-definition grammar and matching
scripts/
  qa.sh            End-to-end QA test suite (drives scripts/qa/)

Contributing

Development Setup

git clone https://github.com/ALT-F4-LLC/docket.git
cd docket
make build          # Build to ./bin/docket
make test           # Run unit tests
make lint           # Run staticcheck + go vet
make clean          # Remove build artifacts

Running the QA Suite

The QA suite exercises the full CLI end-to-end:

./scripts/qa.sh                       # Run all sections
./scripts/qa.sh --verbose             # Show all results, not just failures
./scripts/qa.sh ./bin/docket G        # Run a single section (with prerequisites)

Guidelines

• One file per command in internal/cli/ (e.g., issue_create.go, board.go).
• Every command must support --json using the shared output.Writer envelope.
• Terminal styling uses lipgloss via helpers in internal/render/.
• Add QA checks to scripts/qa.sh for any new command or flag.

License

Apache 2.0. See LICENSE for the full text.