docket: a directory you dispatch background work into and take results from

A docket is a directory. You dispatch commands into it — each runs in the background with its output captured — and you take their results back out when they're ready. When a job finishes, docket runs a configured notify hook so its owner learns a result is waiting, then inspects and takes results at leisure.

This little package is experimental, made to power pictl's team skill for coordinating messages between pi agents, but docket knows nothing about pi, agents, or LLMs. It runs commands, captures their output, and fires a notify hook — that's it. It's the small, algorithmic core of an asynchronous work queue.

Two important properties:

• No daemon. The work of waiting for a job is done by the OS (one detached process per job); notify is performed by the completing job itself.
• State lives on disk. A job's state (running/ready/taken/canceled) is derived purely from marker files, so every command reflects the true current state and a dispatched job survives the process that launched it.

Installation

npm install -g @geraschenko/docket
docket --help

[!NOTE] docket runs on Linux and macOS only — it uses POSIX process groups and signals to supervise and tear down jobs, and has no native Windows support. Node 22 or newer is required.

Quickstart

# Create a docket and point $DOCKET_DIR at it. Every command below resolves the
# docket from $DOCKET_DIR (or an explicit --docket <dir>).
export DOCKET_DIR=$(docket init --notify 'echo "ready: $(docket ready)" >> /tmp/docket.log')

# Dispatch a command; it returns immediately with the job id.
id=$(docket dispatch "sleep 1; echo hello")

docket status            # <id>  running  pid <pid>  sleep 1; echo hello
sleep 2
docket ready             # <id>  ready  exit 0  sleep 1; echo hello

# Take the result: prints captured stdout, marks the job taken.
docket take "$id"        # -> hello
docket status            # <id>  taken

A dispatched command is a single shell string run via sh -c, so pipes and quotes work as written. Both the command and the notify hook run with DOCKET_DIR set in their environment and with the working directory inherited from the dispatch call, so a hook like docket status | some-notifier resolves the docket without an explicit --docket.

When several jobs finish at once, docket coalesces their completions: a burst of finishes never fires overlapping notify procedures, but the owner is always told about the last finisher.

A failing job surfaces its stderr and exit code, but take itself still exits 0 — the job's failure is in the output, not in docket's exit status.

cancel cancels a running job to tear down its whole process tree (SIGTERM, then SIGKILL after a grace window).

take and cancel accept a unique id prefix — job ids are kept prefix-free, so a complete id is never ambiguous and a short prefix usually suffices.

status --json / ready --json emit the job list as a JSON array (untruncated commands, ISO 8601 timestamps) for scripts; the schema evolves additively, so existing fields never change meaning.

docket gc deletes taken and canceled jobs older than a threshold (--older-than takes 0 or e.g. 12h, 7d; default 7d), and deletes the docket directory itself when nothing in it has changed within the threshold and no running or ready job (or unexpected file) remains. Blocked docket deletion is reported with per-job detail; --force overrides it, and --dry-run previews without deleting.

Shell completion

docket completion install     # add the completion hook to your shell (bash only)
docket completion uninstall   # remove it

Completion covers subcommand and flag names.