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.24.2+.

# 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

Repository Setup

Add .docket/ to your .gitignore to keep the issue database local:

echo ".docket/" >> .gitignore

Note: docket init will remind you to do this if .docket/ is not already ignored.

Database Location

Docket stores its SQLite database at $PWD/.docket/issues.db by default. This means each project gets its own isolated issue database.

Override the location with the DOCKET_PATH environment variable:

export DOCKET_PATH=/path/to/custom/.docket

When set, DOCKET_PATH points to the .docket directory (the database file will be $DOCKET_PATH/issues.db).

Use docket config to verify the resolved database path and whether DOCKET_PATH is active.

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
  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)
scripts/
  qa.sh            End-to-end QA test suite

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.