grimoire

Install

Install the release binary; the installer verifies SHA256SUMS. Add ~/.local/bin to PATH.

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/grimoire/main/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

On Windows, use install.ps1 from the same repository; it also verifies SHA256SUMS.

CLI cheat sheet

State: DB = --db / GHOSTPAW_GRIMOIRE_DB / ~/.ghostpaw/grimoire.db; root = --root / GHOSTPAW_GRIMOIRE_ROOT / ~/.ghostpaw/grimoire. Git history lives at <ROOT>/.grimoire-git; override with --git-dir or GHOSTPAW_GRIMOIRE_GIT_DIR. A spell is <chapter>/<name>/SKILL.md with optional scripts/, references/, and assets/. Copy the folder to export it. Rank counts distinct commits per spell: Uncheckpointed 0, Apprentice 1–2, Journeyman 3–5, Expert 6–9, Master 10+. Search uses multiple terms across names, descriptions, and bodies with stemming and fuzzy metadata matching. Inscribe conflicts when the destination exists; --force replaces it. Identical content and no-change hone return no_op. Hone accepts positional paths and --paths. Both --note-ids and --note_ids work for hone and draft submit. Inspect shows rollback hashes in history. Updates require hone to checkpoint changes. Spell --content accepts @file, @- for stdin and @@ for a literal leading @; every other value is literal. A final - reads JSON stdin (including spell inscribe <name> -). --now accepts epoch milliseconds, ISO 8601 date-time, and YYYY-MM-DD. Inspect history and catalogue dates are ISO. Write results are compact; --verbose includes full spell content. review index --format prompt returns only the formatted block in data. Output: --json, --compact, --quiet. Exit codes: 0 success/no_op, 1 tool error, 2 usage, 3 not found/clarification, 4 conflict, 70 internal error. Catalogue health fields measure honing pressure; recently sealed spells may score zero. Dormancy has a 14-day grace period after the first seal.

ghostpaw-grimoire search 'post image VPS'
ghostpaw-grimoire search 'set up a recurring reminder'
ghostpaw-grimoire review index
ghostpaw-grimoire review index --format prompt
ghostpaw-grimoire inspect ops/verify-release
ghostpaw-grimoire spell inscribe verify-release --content @SKILL.md --chapter ops
ghostpaw-grimoire spell inscribe verify-release --force --content @SKILL.md --chapter ops
ghostpaw-grimoire spell inscribe verify-release -
ghostpaw-grimoire spell update ops/verify-release --content @-
ghostpaw-grimoire spell hone ops/verify-release --message 'Add recovery' --note-ids 3
ghostpaw-grimoire spell hone --paths ops/verify-release --note_ids 3
ghostpaw-grimoire note drop 'Checksum mismatch' --source failure --domain ops
ghostpaw-grimoire review notes
ghostpaw-grimoire catalogue run --now 2026-10-28
ghostpaw-grimoire draft submit 'Release checks' --rationale 'Capture evidence' --note-ids 3 --chapter ops
ghostpaw-grimoire draft approve 1
ghostpaw-grimoire spell shelve ops/verify-release
ghostpaw-grimoire spell unshelve ops/verify-release
ghostpaw-grimoire spell move ops/verify-release ops/verify-checksum
ghostpaw-grimoire spell rollback ops/verify-release deadbeef
ghostpaw-grimoire spell repair ops/verify-release
ghostpaw-grimoire spell repair-all
ghostpaw-grimoire spell delete ops/verify-release
ghostpaw-grimoire scout adopt ./skills --chapter imported
ghostpaw-grimoire skill --list
ghostpaw-grimoire skill search-and-retrieve-spells
ghostpaw-grimoire tools
ghostpaw-grimoire describe hone_spell

Grimoire manages local procedural knowledge as spells, notes, and drafts. Search before creating a spell. Inspect before updating, then hone to seal revisions. Preserve provenance and use scouting only when external acquisition is intended.

Calling tools

MCP: connect to ghostpaw-grimoire, then call a tool by name with its JSON arguments.

CLI: ghostpaw-grimoire call <tool> '<JSON object>' or ghostpaw-grimoire <tool> --parameter value.

Inspect schemas with ghostpaw-grimoire describe <tool>. Use --db <path> to select a database.

search_grimoire

Search spell names, descriptions, and bodies.

Read-only.

Example: ghostpaw-grimoire call search_grimoire '{"query":"post image VPS"}'

review_grimoire

Review chapters, health, resonance, notes, drafts, validation, provenance, or index.

Read-only.

Example: ghostpaw-grimoire call review_grimoire '{"view":"index"}'

inspect_grimoire_item

Inspect spell content, tier, resonance, validation, provenance, and history.

Read-only.

Example: ghostpaw-grimoire call inspect_grimoire_item '{"path":"ops/verify-release"}'

inscribe_spell

Create a spell from SKILL.md content (YAML frontmatter and Markdown).

Writes: writes_state.

Example: ghostpaw-grimoire call inscribe_spell '{"name":"verify-release","content":"---\nname: verify-release\ndescription: Verify release checksums\n---\nCheck SHA256SUMS before installing.\n"}'

update_spell

Write new content to an existing spell, leaving the change uncommitted.

Writes: writes_state.

Example: ghostpaw-grimoire call update_spell '{"path":"ops/verify-release","content":"---\nname: verify-release\ndescription: Verify release checksums\n---\nCheck SHA256SUMS and retry if the digest differs.\n"}'

hone_spell

Seal pending spell changes into a git commit, advancing spell ranks.

Writes: writes_state.

Example: ghostpaw-grimoire call hone_spell '{}'

manage_spell

Archive, restore, move, delete, repair, or roll back spells.

Writes: writes_state.

Example: ghostpaw-grimoire call manage_spell '{"action":"repair_all"}'

drop_note

Record an observation for later cataloguing.

Writes: writes_state.

Example: ghostpaw-grimoire call drop_note '{"content":"Verify the build before release.","source":"practice"}'

manage_draft

Submit, approve, or dismiss spell drafts.

Writes: writes_state.

Example: ghostpaw-grimoire call manage_draft '{"action":"submit","title":"Release checks","rationale":"Capture checksum verification","chapter":"ops","noteIds":[1]}'

run_catalogue

Maintain health, route notes, cluster orphans, and score honing pressure.

Writes: writes_state.

Example: ghostpaw-grimoire call run_catalogue '{}'

scout_skills

Scout, search, adopt, and update spells from external sources.

Writes: writes_state.

Example: ghostpaw-grimoire call scout_skills '{"action":"search","query":"pdf"}'

Workflow guides

• ghostpaw-grimoire skill search-and-retrieve-spells: Find relevant spells by query, then inspect candidates without scanning the entire grimoire.
• ghostpaw-grimoire skill inscribe-spells-correctly: Create new spells with correct structure, always searching first to avoid duplicates.
• ghostpaw-grimoire skill evolve-spell-through-tiers: Guide a spell through tier progression by meeting structural requirements at each gate.
• ghostpaw-grimoire skill hone-spell-from-evidence: The complete evidence-backed refinement flow: check readiness, gather notes, edit, seal, and distill consumed notes.
• ghostpaw-grimoire skill maintain-grimoire-health: Run systematic health maintenance: catalogue, review, remediate stale/dormant/oversized spells.
• ghostpaw-grimoire skill distill-notes-into-spells: Process accumulated notes into new spells via the draft pipeline.
• ghostpaw-grimoire skill scout-and-adopt-skills: Discover external skills from the ecosystem, evaluate candidates, adopt them into the grimoire with provenance.
• ghostpaw-grimoire skill reconcile-upstream-updates: Check for upstream changes on adopted spells and decide whether to auto-apply, manually reconcile, or keep local evolution.
• ghostpaw-grimoire skill reorganize-spell-chapters: Restructure chapter layout by moving, shelving, and unshelving spells to achieve balanced organization.
• ghostpaw-grimoire skill resolve-validation-failures: Systematically diagnose and fix structural validation failures across the grimoire.
• ghostpaw-grimoire skill archive-and-prune-spells: Identify dead weight and retire it using the correct archival action.
• ghostpaw-grimoire skill decompose-oversized-spells: Find better abstractions before splitting oversized spells.
• ghostpaw-grimoire skill handle-edge-cases-gracefully: Diagnose unexpected states by reading before mutating, following tool error recovery hints, and refusing to guess.

Principles

• Search before writing. Preserve provenance. Seal changes after review.

Without the binary

For npm-based environments (Node 24+), run tools with npx -y @ghostpaw/grimoire ....

Harnesses embedding it in code can import @ghostpaw/grimoire as a library.