questline

questline

A durable work queue, CLI/TUI, SDK, and small HTTP API for CLI coding agents — Claude Code, pi, codex, or anything with a print mode. Queue tasks, run them through your agent, and keep state in SQLite even if a terminal, daemon, or machine crashes.

Execution guarantees

Questline is at-least-once, not exactly-once. Database state transitions are fenced by versioned leases, so a stale worker cannot overwrite a quest after another session reclaims it. External side effects performed by the agent process are not fenced by SQLite; make agent tasks idempotent or protect them with your own locks when they touch external systems.

• Leases with fencing — every claim gets a generation token; stale complete/fail callbacks are rejected.
• Heartbeats + reclamation — if a worker stops heartbeating, another session may reclaim the quest.
• Lease-loss cancellation — local executors receive an AbortSignal; spawned process groups are terminated so reclaimed quests do not keep producing side effects.
• Graceful shutdown — daemon/TUI/CLI shutdown sends SIGTERM to child process groups, waits a grace window, escalates to SIGKILL, then marks unfinished owned quests interrupted.
• Retries are bounded with exponential backoff. Retryable execution failures do not fail dependents; terminal failed/cancelled dependencies do.

Install

npm install -g questline     # needs node >= 22

Quick start

cd your-project
questline add build "Write unit tests for src/parser.ts" --name tests
questline run                # claims + executes via your agent, prints result preview
questline dash               # TUI: ↑↓ select · ←→ filter · / search · ⏎ details · r/R/x

Queue several and let the daemon drain them:

questline add explore "Map this codebase" --priority 5
questline add build "Fix the flaky test" --max-attempts 3
questline add review "Review the diff" --depends q-abc12345
questline daemon             # runs everything, respecting priority/deps/backoff

The executor: bring your own agent

By default quests run through Claude Code: claude -p "<task>". Configure any agent in ~/.questline/config.json (global) or <project>/.questline.json (per project). Config files are JSONC: comments and trailing commas are accepted, but invalid config now fails loudly with file/line details.

{
  "executor": { "command": ["claude", "-p", "{task}"], "timeoutMs": 900000 },
  "executors": {
    "review": { "command": ["claude", "-p", "--model", "opus", "{task}"] }
  }
}

Placeholders: {task} (includes context), {context}, {project}, {role}, {id}, {name}. The command runs with the quest's project as cwd; stdout is the stored result in text mode; exit 0 = done, non-zero or timeout = failed (and retried if attempts remain).

Structured JSONL executor protocol

Set "protocol": "questline-jsonl" on an executor to emit machine-readable output and telemetry. Each stdout line is one JSON envelope:

{"protocol":"questline/1","type":"output","text":"partial result\n"}
{"protocol":"questline/1","type":"telemetry","provider":"anthropic","model":"claude-sonnet","turns":2,"tokens":1234,"costUsd":0.08,"lastActivity":"editing"}
{"protocol":"questline/1","type":"result","ok":true}

Telemetry values are cumulative. Stderr remains diagnostic text. Malformed JSONL, unknown event types, duplicate/missing result events, or non-zero exits fail the attempt.

Output artifacts

Large stdout/stderr is streamed to files instead of being silently truncated. SQLite stores a bounded head/tail preview plus artifact metadata. Defaults:

{
  "artifactDir": "~/.questline/artifacts",
  "executor": {
    "maxInlineOutputBytes": 262144,
    "outputPreviewBytes": 16384,
    "terminateGraceMs": 5000
  }
}

questline show <id> displays attempt telemetry, recent events, result/error previews, and full artifact paths.

Commands

Command	Summary
add <role> "task"	--name --priority N --context TEXT --depends id1,id2 --max-attempts N --not-before ISO --dedupe-key KEY --retain --group ID
list / show <id>	queue table (--json) / full detail with telemetry, events, artifacts, and preview
run [id]	claim next eligible (or a specific quest) and execute now
daemon	drain continuously; Ctrl-C terminates workers and releases cleanly
dash	interactive TUI
cancel / retry / consume <id>	cancel pending/running work / requeue failed work / release a retained result's dedupe key
pause / resume	durable project queue pause; running quests continue, new claims and recurrence materialization stop
group create/list/show/cancel/retry	first-class quest groups
pipeline list/run <name>	enqueue configured DAG pipelines atomically
recurring add/list/pause/resume/remove	cron-style recurring quests
events / runs <id>	audit journal / per-attempt telemetry
health [--json] [--all-projects]	database integrity plus project health, dependency issues, stale schedulers, overdue work
export / import / backup	JSON archive round-trip and SQLite VACUUM INTO backup
api --port N	local HTTP API: /health, /quests, /pause, /resume
completion	shell completion snippet

Dependencies

Dependencies are AND-gates: every dependency must be done before a quest can run. Questline rejects nonexistent dependencies, cross-project dependencies, self-dependencies, and dependency cycles. If a dependency becomes terminally failed or cancelled, queued/interrupted dependents fail immediately with failureKind: "dependency". Requeueing the root revives dependency-failed descendants; independently failed descendants stay failed.

Pipelines

Pipelines live in config and are enqueued as one group in a single transaction:

{
  "pipelines": {
    "plan-build-review": {
      "steps": {
        "plan": { "role": "plan", "task": "Plan {project}" },
        "build": { "role": "build", "task": "Implement the plan", "dependsOn": ["plan"] },
        "review": { "role": "review", "task": "Review the result", "dependsOn": ["build"] }
      }
    }
  }
}

Run with questline pipeline run plan-build-review.

Recurring quests

questline recurring add nightly-review \
  --cron "0 2 * * *" \
  --timezone America/New_York \
  --role review \
  --task "Review today's diff" \
  --catch-up one
questline daemon

Cron expressions are standard five-field (minute hour dom month dow). Next-run times are computed with IANA timezones and DST via cron-parser (civil time in the given zone; default UTC). The scheduler materializes due occurrences while it owns the scheduler lease. Supported catch-up modes: one, all, skip.

Config reference

{
  "dbPath": "~/.questline/quests.sqlite",
  "artifactDir": "~/.questline/artifacts",
  "maxHistory": 500,
  "leaseTtlMs": 120000,
  "heartbeatMs": 30000,
  "maxAttempts": 1,
  "backoffBaseMs": 30000,
  "scheduler": {
    "pollMs": 5000,
    "maxConcurrent": 2,
    "roleConcurrency": { "review": 1 }
  },
  "executor": {
    "command": ["claude", "-p", "{task}"],
    "timeoutMs": 900000,
    "protocol": "text",
    "terminateGraceMs": 5000,
    "maxInlineOutputBytes": 262144,
    "outputPreviewBytes": 16384
  },
  "notifications": {
    "command": ["osascript", "-e", "display notification \"{name}: {state}\" with title \"questline\""]
  }
}

Validation rejects unknown keys, invalid numbers, empty executor commands, and heartbeat intervals greater than or equal to the lease TTL.

Quests are per-project (keyed by the directory you run commands in), stored in one SQLite database (WAL). Compatible with the pi-fairy-tales quest journal — set dbPath to ~/.pi/agent/fairy-tales-quests.sqlite and questline and pi share one queue.

SDK

Questline exports a stable ESM SDK; no dist/* imports are required:

import {
  QuestStore,
  QuestRuntime,
  QuestScheduler,
  executeQuest,
  loadConfig,
  startHttpApi
} from "questline";

Published packages include main, exports, and TypeScript declarations.

License

MIT