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.

Running inside sandboxed agent harnesses

Inside a Codex CLI --sandbox workspace-write session, the database and its parent directory must be inside a writable root, including SQLite's -wal and -shm side files. A default DB under ~/.ghostpaw outside those roots can fail with SQLITE_CANTOPEN or EPERM (often exit 70; directory creation failures may exit 2), even when normal shell permissions allow access. Put the DB inside the workspace with --db ./state/questlog.db, or set GHOSTPAW_QUESTLOG_DB="$PWD/state/questlog.db" for CLI/MCP use.

To use an external DB directory, add it when starting the OpenAI Codex CLI (replace with its absolute path):

codex exec --sandbox workspace-write --add-dir <dir-with-db> "Run the GhostPaw CLI"

Alternatively, set sandbox_workspace_write.writable_roots in ~/.codex/config.toml before starting the session:

[sandbox_workspace_write]

writable_roots = ["/absolute/dir-with-db"]

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 prints a usage hint (--outcome '...') and exits 2.

drop [--reason text] (also quest abandon ) abandons a quest and records the reason; the default is "Abandoned via CLI." Quest actions are revise and abandon. Create quests with questlog add " " --tag x; unsupported quest actions such as create, new, or add print this guidance and exit 2. Top-level --help leads with add, list, start, done, due, and drop. Advanced commands for rumors, unlocks, rewards, hooks, and repeatables remain available in its advanced section.

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