@opum-ai/quest weekly downloads statistics

quest

A deterministic, LLM-free task tracker CLI — the record layer coding agents and humans write to, and that tools like lore couple to over JSON.

quest is the tracker of record for repository-resident work: tasks, drafts, decisions, and milestones live as plain JSON under .quest/, committed to Git alongside the code they describe. There is no server, no database, and no LLM in quest's core — every command is deterministic, reproducible, and CI/agent-safe (non-interactive by default, stable semantic exit codes, machine-readable --json).

• Built on Bun + TypeScript with an exact-pinned Commander parser; a versioned capability manifest (quest manifest --json) is the live, authoritative description of the command surface.
• Published on npm as @opum-ai/quest (bin quest) with six exact-pinned platform packages, including Windows ARM64.
• The agent bridge is a generated managed block in CLAUDE.md, AGENTS.md, or GEMINI.md (Claude Code, Codex/OpenCode/pi/etc., and Google Antigravity/Gemini CLI respectively) plus quest instructions for just-in-time, task-shaped guidance.

Status: released. The release tag, the qualified workflow artifacts, all seven public @opum-ai/quest* npm packages, and a clean registry install agree on one published version. This file deliberately does not restate that number, and bun run check:packages fails the release if it reappears: a version hand-maintained here goes stale the moment the next release lands, and because README.md ships inside the tarball, the npm page then advertises the wrong one permanently -- version pages are immutable. npm and the repository's tags both show the current version already. Releases are qualified in lockstep with @opum-ai/lore. See docs/reference/quest-cli-release-truth.md.

---

The headline: every write declares who made it

quest never accepts an anonymous write. Every command that mutates a record — task create, task edit, task complete, and the rest — requires an explicit actor declaration:

quest task edit QCLI-1 --status "In Progress" \
  --actor jdnewhouse --actor-kind human

or, when the actor performing the write is an agent rather than the human it answers to:

quest task edit QCLI-1 --status "In Progress" \
  --actor my-agent-session --actor-kind delegated-agent \
  --accountable-human jdnewhouse

A missing --actor-kind is rejected outright ("Tracker writes require an explicit actor declaration"); an invalid value names itself and lists the valid kinds. This is deliberate, load-bearing provenance, not an afterthought — it is what lets a record say not just what changed but who is accountable for it, which matters most exactly when the actor is an autonomous agent.

Tools couple to quest the same way quest couples to Git: by reading its deterministic JSON, never by parsing prose or editing .quest/ files directly. lore is the reference consumer — see Lore dependency and adapter contract evidence.

---

Install

The package and bin are @opum-ai/quest and quest:

# Node / npm
npx @opum-ai/quest --help

# Bun
bunx @opum-ai/quest --help

# Global npm install
npm install -g @opum-ai/quest

The launcher installs only the matching script-free platform package for your OS/architecture, so a current install requires no install-script approval exception. There is no native addon and nothing to compile locally.

Or add it to a project:

bun add -d @opum-ai/quest   # or: npm i -D @opum-ai/quest

The npm package is a dual artifact: a tiny Node .cjs launcher plus a per-platform compiled binary (built with bun build --compile), delivered as optionalDependencies — macOS, Linux, and Windows, each on x64 and arm64.

---

Quickstart

Every command is non-interactive by default and emits stable, semantic exit codes. Output has three modes: pretty (default, color on a TTY), --plain (ANSI-free stable text), and --json (a {schemaVersion, kind, data} envelope on stdout, with errors on stderr as {error_type, message, hint}). The one interactive path is quest init on a bare TTY invocation, which runs a guided setup (project name, task ID prefix, a multi-select for which instruction file(s) to write) — any flag or a non-TTY stdin runs it fully non-interactively instead.

# 1. Initialize a Quest workspace in the current Git worktree.
quest init --name "My Project" --task-id-prefix ABC

# 2. Create a task. Every write needs an actor.
quest task create "Fix the flaky retry loop" \
  --description "Retries don't back off; a burst of failures thundering-herds the API." \
  --acceptance-criteria '["Retry loop applies exponential backoff with jitter"]' \
  --actor jdnewhouse --actor-kind human

# 3. Move it forward.
quest task edit ABC-1 --status "In Progress" --actor jdnewhouse --actor-kind human

# 4. See what's actually ready to work — dependencies resolved, blockers respected.
quest task list --ready --json

# 5. Finish it with evidence, not on faith.
quest task edit ABC-1 --check-ac 1 --actor jdnewhouse --actor-kind human
quest task edit ABC-1 --final-summary "Added exponential backoff with jitter; verified via the retry-storm test." \
  --actor jdnewhouse --actor-kind human
quest task complete ABC-1 --actor jdnewhouse --actor-kind human

--json is the additive-only machine contract:

$ quest task view ABC-1 --json
{
  "schemaVersion": 1,
  "kind": "task.view",
  "data": { "id": "ABC-1", "status": "Done", "title": "Fix the flaky retry loop", "..." : "..." },
  "principal": null
}
```…