CLI commands.

Find the context

Manage tracked work

Replace <ID> with a real ID from your task list. Ask your agent to start the task, make and check the change, and update the affected docs before closing it.

To close without completion, use docket task close <ID> --without-completion --note "Reason". Review the checks and changed files before completing a task.

Pickup and closure

A named Task start moves that Task to in-progress, sets the checkout-local active marker and returns context. A named Epic start returns outcome: "route" with the docket-epic procedure. It changes no status or active marker and selects no child. The agent reads that procedure, checks the live graph and chooses eligible children. Add --compact for the bounded packet; follow its requiredReads before implementation.

Prepare the Outcome or Disposition and reconcile docs before task close. Then refresh discovery, run the required checks and make the task-linked closure commit. Close retains active lifecycle state and returns closure.cleanup.args; run those arguments after substituting the actual commit SHA. Guarded cleanup has this form, with values from your pickup and closure receipts:

docket task stop <ID> --workflow-token <pickup-token> --after-commit <closure-commit-sha> --json

The guard checks the matching Task and pickup token, committed terminal source, task trailer and commit ancestry. It does not prove acceptance or integration. For a pause or handoff before completion, omit --after-commit.

Parallel tracked work

in-progress is stored task status; it does not mean an agent is running. Each checkout has one .docket/active-task marker. Starting the same ID resumes it. An explicitly authorized hand-off runs docket task stop <active-ID> --workflow-token <pickup-token> --json and then docket task start <ID> --json in the same checkout. Two concurrent tracked writers use separate linked Git worktrees and distinct branches. Untracked direct work does not make simultaneous editing in one checkout safe.

When docket task start <ID> --json encounters another active ID, it exits nonzero with error.code: "active-task-conflict". The response names activeTaskId and requestedTaskId, offers an explicitly authorized handoff, and includes an isolation path, branch, starting point, git worktree add recipe, issues and agent prompt. An unresolved task file or starting point makes isolation.command null; resolve it before creating a worktree. Adapt the branch to project naming guidance. The agent must also ensure the starting commit contains the requested task and relevant guidance, and plan for later integration.

Paste this prompt into a second agent chat, replacing <ID> with the task you want it to start:

Start Docket task <ID> alongside the current work. Check existing authority before asking for approval, preserve the original checkout and task marker, and use a separate working copy when authorized. Check overlapping edits separately and continue independent ready work. Lead with the recommended next action; include the checkout, branch and starting commit as supporting details.

The agent checks existing authority before asking for worktree approval. Applicable host instructions can authorize routine reversible isolation within your requested scope; you can also authorize one worktree or a session's conflicts directly. A lower-priority confirmation default adds no new gate. To save an automatic-isolation preference, explicitly ask the agent to record it in existing project guidance: “For this project, when a requested Docket task conflicts with another active task, automatically create a separate linked worktree and start the requested task there. Leave the original checkout untouched and tell me which worktree and branch you use.” Ask it to remove that preference when you want confirmation again. A one-time approval does not save it; installation and upgrade do not enable it. Isolation authority covers the new worktree and named pickup only. All operations, including MCP calls, must target the new checkout; changing shell directory does not retarget an existing MCP server.

A separate working copy protects files but does not settle two chats editing the same page. Establish a current baseline and one agreed writer or a reconciliation plan for affected edits. If one epic child must wait, the agent checks the current ready list and continues independent authorized work in an authorized checkout. For example, an independent reference-page pilot can proceed while another chat finishes editing the active-work pilot page.

For a documentation cleanup, the next action can be stated simply: “I recommend doing the cleanup in a separate working copy so the current feature work can continue. I’ll start with the independent reference page and defer the shared pilot page until its ongoing edits are settled. You’ll review both pilots before broader cleanup.” If isolation authority is missing, add one direct question about creating that working copy, followed by the concrete path, branch, starting commit and named task. Explain any required approval source once; later status replies should state the next action.

docket lint --json reports source-line warnings for hard-wrapped prose. Keep paragraphs and simple list items on one source line and let the renderer wrap them. docket lint --strict exits nonzero on warnings as well as errors. Lint never rewrites source or rejects a browser save; use the reported path and line to review existing prose while preserving intentional Markdown breaks and structure.

Ordinary wiki documents

docket document create --input <json-file> --json exclusively creates an ordinary Reference, Spec or Playbook. The JSON contains path (relative to the configured bundle), type, title, body, and optional description and tags. Paths must end in .md; reserved pages, guidance, tracked-work, workflow, decision and extension locations are excluded. The engine adds a timestamp and rejects existing paths without overwriting them.

docket document read <path> --json returns a complete editable body, title, description and source version. docket document edit <path> --input <json-file> --json accepts {expectedVersion, patch}; the patch accepts body, section, title and description. Do not combine a complete body replacement with a section edit. A stale source version conflicts. Run docket index and docket lint --json after authoring. See the complete wiki example.

To update one level-one section, first read it with docket document read <path> --section "Current state" --json. Use the returned whole-source version in an edit input file:

{
  "expectedVersion": "<version from document read>",
  "patch": {
    "section": { "heading": "Current state", "body": "Replacement content." }
  }
}

The section body excludes its heading and cannot contain another level-one section. A missing section is inserted, duplicate headings are refused, and body: null removes the section. A section read is not a complete body draft.

Record a decision

docket decision create --title "…" --context "Context and alternatives" --decision "Accepted choice and rationale" --consequences "Tradeoffs" --json writes a Decision under decisions/ with a timestamp and status: accepted. Optional --description and --tags supply metadata. Omitted body sections receive placeholders; complete them before treating the record as finished. The result contains id and path. Run docket index and docket lint --json afterward.

The ID prefix is ids.decision_prefix in docket.yaml (default DEC); its sequence is independent of project work IDs when the prefixes differ. Identical prefixes share occupied IDs and aliases. Linked Git worktrees coordinate both creation commands through one allocation lock, and occupied destinations are never overwritten. task create --type accepts only Task or Epic. Decision recording does not start or stop tracked work, change its active marker, or select project guidance. See the decision example.

Move a wiki page

Use docket document move-plan <from> <to> --json with bundle-relative paths for an ordinary Reference, Spec or Playbook. Inspect paths, replacements, blockers and warnings. Save {"from":"reference/old.md","to":"reference/topic/new.md","expectedVersion":"<plan.version>"} as a JSON file, then run docket document move-apply --input move.json --json. A title-only change uses document edit and keeps the path. Case-only, protected/owned or occupied destinations are refused.

The engine repairs parsed inline/image/reference-definition destinations, preserves fragments, rebases relative outbound links and refreshes the index. Labels, code and metadata remain unchanged. A changed bundle snapshot, including a new incoming reference, invalidates the plan. Affected HTML/frontmatter/owned links require explicit reconciliation; code, non-Markdown and outside references are unmanaged. Check the new page, search and docket lint --json after completion.

A partial failure returns state: recovery_required and exits nonzero. Keep its token and run docket document move-recover <token> --json. Original and planned bytes remain in <bundle>/.docket-moves/<token>.json; recovery validates the journal and refuses unrelated changes. Treat journals as local recovery material, retain until verified and review before committing or archiving. These commands never commit, start work or select guidance. See the everyday example.

Task progress across worktrees

docket task progress [ID] --json reads a bounded combined view of saved task files in linked worktrees and pinned versions in locally available refs. Omit --json for source-labelled human output. The result includes observation time, coverage diagnostics, conflicts, pickup markers and integration evidence. Tasks existing only elsewhere have localStatus: null; their observations do not create editable local tasks. task list and ready preserve recorded status and canonical ordering while adding relevant progress flags. Use task progress to discover foreign-only tasks or inspect partial coverage. The everyday guide explains refresh and integration behavior.

Maintain & browse

After an upgrade, review workflow differences marked review. JSON includes a reviewRequired path list. A current origin stamp does not prove that current instructions arrived; compare retained text with the shipped workflow and preserve confirmed project requirements.

Use docket --help or docket task create --help for the exact flags in your installed version. Add --json where supported for programmatic output. Check docket --version when using an installed release; its capabilities may differ from this source reference.

Local telemetry

Telemetry is off by default and requires enrollment per checkout. Observations stay outside your repository on this computer; Docket never uploads them. Document contents, prompts, search terms, and file paths are excluded.

Check the current telemetry state:

docket telemetry status

Optional: enable local telemetry for this checkout:

docket telemetry enable

Inspect the observations collected so far:

docket telemetry report

Optional: stop collecting new observations:

docket telemetry disable

Only if you intend to remove this checkout’s enrollment and retained observations:

docket telemetry delete

report summarizes observed operation counts, latency, errors, and sampled runtime memory. disable stops collection; delete removes this checkout’s enrollment and retained observations. Reports you export yourself remain yours to manage.

Agent overview: GitDocket 0.6.4

GitDocket 0.6.4 returns a bounded live briefing from docket overview --json, with omitted counts and source paths. Use docket overview --json --full for the previous JSON model and to refresh the written project briefing. Scripts that depend on the old response must add --full.