GhostPaw Questlog

@ghostpaw/questlog

Agent tasks as quests that finish only with a written outcome.

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.sh | sh

A unified task and calendar model for Node.js, built on SQLite.

Questlog treats tasks, events, deadlines, recurring commitments, and loose intake as one coherent data model instead of separate systems. It ships as a single prebundled blob with zero runtime dependencies, designed for two audiences at once: human developers working directly in code, and LLM agents operating through a structured tool facade.

MCP server

Every client below starts the same stdio server: ghostpaw-questlog mcp. For npm-based environments, use npx -y @ghostpaw/questlog mcp (Node 24+). Data lives in ~/.ghostpaw/questlog.db unless the GHOSTPAW_QUESTLOG_DB environment variable (absolute path) or --db says otherwise.

Claude Code

claude mcp add ghostpaw-questlog -- ghostpaw-questlog mcp

or as a plugin, which also installs the skill:

/plugin marketplace add GhostPawJS/questlog

/plugin install ghostpaw-questlog@ghostpaw-questlog

Codex CLI (~/.codex/config.toml)

[mcp_servers.ghostpaw-questlog]

command = "ghostpaw-questlog" args = ["mcp"]

Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json) or a project .mcp.json:

{

"mcpServers": { "ghostpaw-questlog": { "command": "ghostpaw-questlog", "args": ["mcp"] } } }

Claude Desktop users can also install server.mcpb from the latest GitHub release. A Dockerfile is included for container hosts: docker build -t ghostpaw-questlog . && docker run -i --rm -v questlog:/data ghostpaw-questlog.

The server speaks MCP 2026-07-28 (stateless, server/discover) and the initialize-based revisions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.

CLI

Install the release binary for ghostpaw-questlog (questlog is an alias).

questlog add "Review release notes" --tag release --due 2030-01-02

questlog list --limit 10 questlog search release notes --limit 5 questlog show 1 questlog start 1 questlog done 1 --outcome "Reviewed changes" questlog list --view quests.resolved --json

add accepts comma-separated tags (--tag a,b) and repeated --tag flags, --objective (defaults to the title), --questline , and --due as YYYY-MM-DD, DD.MM.YYYY, today, tomorrow, +3d, an ISO date-time with timezone, or milliseconds since epoch. Date-only values use local end of day. --objective is the one flag that reads a file: @path, @- for stdin, and @@text for a literal @text (help marks it (@file, @- stdin, @@ literal @)). Every other value, including titles, --outcome and per-tool flags, is literal. list --tag work --tag urgent requires all tags and supports quest views; unknown tags return an empty list.

list defaults to available quests; list --help lists all supported views. Its --limit and --offset paginate text and JSON. JSON data includes total, offset, limit, and hasMore. search --fts enables raw FTS5 syntax; search text is literal by default. search --limit caps matches in both formats. show prints full quest detail. Lists show local due dates, overdue markers, and recorded outcomes. Plain JSON adds ISO UTC siblings for numeric timestamp fields ending in At. done stores --outcome with the finished quest; without it the command asks for one and exits 3.

Revise a title with questlog quest revise --title "New title". Count filtered quests with questlog list --count-by tag|prefix. Find similar open quest titles with questlog list --view quests.duplicates.

Commands print text by default, including hooks, delivery views and each watch tick; call and direct tool commands return the raw tool result as JSON. Use --json for the full tool result and --compact for compact JSON. --db path works before or after the command. Each command accepts --help. Exit codes are 0 for success, 1 for invalid input or a tool error, 2 for usage errors, and 3 when clarification is needed or a quest, delivery, or hook target is not found. An empty hook list prints No hooks ([] with --json). Delivery text timestamps use local time; JSON retains UTC/epoch timestamps. hook label names the database, not an individual target.

questlog skill --short prints the compact cheat sheet; questlog skill --list lists guides. ISO date-times without a zone (for example 2026-10-29T09:00) use the local time zone.

The call command and the per-tool form still reach every tool and parameter:

questlog tools

questlog call capture_rumor '{"title":"Review release notes"}' questlog search_questlog --query "release notes"

questlog mcp starts the stdio server.

The default database is ~/.ghostpaw/questlog.db. Override it with --db or GHOSTPAW_QUESTLOG_DB; top-level help shows the selected path. New database files are reported on stderr. The npm entry requires Node 24+ and exits 2 with an installation hint on older Node versions, including for help and version.

Agent Skill

SKILL.md (repo root) and skills/questlog/SKILL.md follow the Agent Skills format and ship in the npm package. Copy skills/questlog/ into your agent's skills folder, or print it:

ghostpaw-questlog skill > SKILL.md

Install

Release binary (default)

Each line downloads the latest release asset, checks it against the release’s SHA256SUMS and installs it on the PATH (~/.local/bin on Linux/macOS; the Windows script adds its folder to the user PATH).

These lines never edit ~/.profile or other shell startup files: export PATH applies to the current shell only. To keep it in new shells, use the ~/.profile line below.

linux-x64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.sh | sh -s -- --target linux-x64 && export PATH="$HOME/.local/bin:$PATH"

linux-arm64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.sh | sh -s -- --target linux-arm64 && export PATH="$HOME/.local/bin:$PATH"

darwin-arm64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.sh | sh -s -- --target darwin-arm64 && export PATH="$HOME/.local/bin:$PATH"

darwin-x64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.sh | sh -s -- --target darwin-x64 && export PATH="$HOME/.local/bin:$PATH"

windows-x64 (PowerShell; persistently adds its folder to the user PATH):

irm https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.ps1 | iex

Pinned to a release:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.sh | sh -s -- --target linux-x64 --version 0.11.1 && export PATH="$HOME/.local/bin:$PATH"

Also adding ~/.local/bin to ~/.profile (edits ~/.profile once; skipped if it already mentions ~/.local/bin; zsh login shells read ~/.zprofile instead, so use that file name there):

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.sh | sh -s -- --target linux-x64 && { grep -qs '.local/bin' ~/.profile || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile; } && export PATH="$HOME/.local/bin:$PATH"

To skip the persistent Windows user PATH edit (the installer still installs and prints the folder to add):

$env:GHOSTPAW_NO_MODIFY_PATH=1; irm https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.ps1 | iex

$ ghostpaw-questlog --version

questlog 0.11.1 (binary, linux-x64)

Scripts that compare versions should use --version --short or --version --json.

Standalone binaries are available from GitHub Releases.

A session with the 0.9.1 linux-x64 binary against a fresh database:

The same session as an animated GIF.

Other release installers:

mise use -g github:GhostPawJS/questlog

ubi --project GhostPawJS/questlog --exe ghostpaw-questlog --in ~/.local/bin eget GhostPawJS/questlog

For aqua, define a github_release package in aqua.yaml:

registries:

• name: questlog type: local path: questlog-registry.yaml

packages:

• name: GhostPawJS/questlog@v0.8.0 registry: questlog

questlog-registry.yaml:

packages:

• type: github_release repo_owner: GhostPawJS repo_name: questlog asset: ghostpaw-questlog-{{trimV .Version}}-{{.OS}}-{{.Arch}}.tar.gz format: tar.gz replacements: { amd64: x64 } overrides:
• goos: windows asset: ghostpaw-questlog-{{trimV .Version}}-windows-{{.Arch}}.zip format: zip files:
• name: ghostpaw-questlog

Install scripts verify SHA256SUMS. To verify a downloaded archive's build attestation:

gh attestation verify <archive> -R GhostPawJS/questlog

Set GHOSTPAW_VERIFY=attestation for attestation verification in install.sh. Binaries are unsigned; macOS binaries carry an ad-hoc signature. For a browser download on macOS, remove quarantine with xattr -d com.apple.quarantine /path/to/ghostpaw-questlog. Linux binaries require glibc 2.28+; use npx on Alpine. See the binary build workflow.

npx / npm (for npm-based environments)

The npm package requires Node 24+:

npx -y @ghostpaw/questlog --help

npm install -g @ghostpaw/questlog

Library (for harnesses embedding it in code)

npm install @ghostpaw/questlog

import { initQuestlogTables, read, write } from '@ghostpaw/questlog';

See library usage. The library uses built-in node:sqlite with zero runtime dependencies.

Quick Start

import { DatabaseSync } from 'node:sqlite';

import { initQuestlogTables, read, write } from '@ghostpaw/questlog';

const db = new DatabaseSync(':memory:'); initQuestlogTables(db);

// Capture incoming work as a rumor before committing to shape const rumor = write.captureRumor(db, { title: 'Legal says the vendor terms changed',