GhostPaw Souls

@ghostpaw/souls

Agent identity as an essence plus evidence-backed traits, refined only when the evidence agrees.

npm install @ghostpaw/souls

Prompt evolution engine for cognitive identity. Stores identity as narrative essence plus evidence-backed traits, with structured level-up, crystallization-gated refinement, and full rollback. Not a prompt template library. Not a configuration manager. An evolutionary algorithm for how agents think.

Release binary with no runtime needed; library and npm usage require Node 24+. Zero runtime dependencies.

MCP server

Every client below starts the same stdio server: ghostpaw-souls mcp. For npm-based environments, use npx -y @ghostpaw/souls mcp. Identity and evidence live in ~/.ghostpaw/souls.db unless the GHOSTPAW_SOULS_DB environment variable (absolute path) or --db says otherwise.

Claude Code

claude mcp add ghostpaw-souls -- ghostpaw-souls mcp

or as a plugin, which also installs the skill:

/plugin marketplace add GhostPawJS/souls

/plugin install ghostpaw-souls@ghostpaw-souls

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

[mcp_servers.ghostpaw-souls]

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

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

{

"mcpServers": { "ghostpaw-souls": { "command": "ghostpaw-souls", "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-souls . && docker run -i --rm -v souls:/data ghostpaw-souls.

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

ghostpaw-souls search [query] [--soul-id N --tags TAG --limit N]

ghostpaw-souls review ghostpaw-souls soul create --essence TEXT --description TEXT ghostpaw-souls soul show|update|retire|awaken [flags] ghostpaw-souls shard drop --source LABEL --soul-ids N [flags] ghostpaw-souls shard drop-batch --shards JSON ghostpaw-souls shard reveal ghostpaw-souls refinement add|attune [flags] ghostpaw-souls refinement revise|revert|reactivate [flags] ghostpaw-souls refinement cite ghostpaw-souls level validate|up|revert [flags] ghostpaw-souls mcp|skill|tools|describe|call|completions|version|help

Use ghostpaw-souls skill --short for a compact cheat sheet, skill for full parameter tables, and skill --list to list runnable workflow guides.

Global flags can appear anywhere: --db , --json, --quiet, --compact, --help/-h, --version/-V/-v, --no-color. NO_COLOR is accepted; output uses no terminal colors. Noun-verb commands print the full tool result as JSON with --json or when stdout is piped. Terminal output shows the summary and payload. --quiet suppresses stdout. --compact removes JSON indentation.

Use help soul, soul --help or soul create --help for schema-derived help. Array flags repeat and kebab-case flags map to schema properties. Values are literal, including a leading @. Only soul create|update --essence reads a file: @path (relative to the working directory), @- for stdin and @@text for a literal @text. Help marks it (@file, @- stdin, @@ literal @); an empty or unreadable path exits 2. -- ends flags. A positional -, or piped stdin with no arguments, reads a JSON object; explicit flags override its fields. Database selection uses --db, GHOSTPAW_SOULS_DB, then ~/.ghostpaw/souls.db.

Errors go to stderr. With --json, usage and internal errors also print {ok:false,error:{code,message}} to stdout. Tool results retain their full shape. Legacy tools [--json], describe , call [JSON|-] and --parameter value keep their existing exit codes. completions bash, completions zsh and completions fish print shell scripts.

ghostpaw-souls soul create Reviewer --essence "Read carefully." --description "Review identity" --db /tmp/souls-example.db --json

ghostpaw-souls soul show 1 --db /tmp/souls-example.db --json ghostpaw-souls review list --db /tmp/souls-example.db --json

Search reads behavioral shards. Creating a soul does not add searchable shards; use shard drop to deposit observations. Core commands work offline.

Agent Skill

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

ghostpaw-souls 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/souls/main/install.sh | sh -s -- --target linux-x64 && export PATH="$HOME/.local/bin:$PATH"

linux-arm64:

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

darwin-arm64:

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

darwin-x64:

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

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

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

Pinned to a release:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/souls/main/install.sh | sh -s -- --target linux-x64 --version 0.4.5 && 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/souls/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 user PATH edit (the installer prints the folder to add):

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

$ ghostpaw-souls --version

souls 0.4.5 (binary, linux-x64)

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

A session with the 0.4.0 linux-x64 binary against a fresh database (output piped through jq to keep it short):

The same session as an animated GIF.

Other release installers:

mise use -g github:GhostPawJS/souls

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

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

registries:

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

packages:

• name: GhostPawJS/souls@v registry: souls

souls-registry.yaml:

packages:

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

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

gh attestation verify <archive> -R GhostPawJS/souls

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-souls. Linux binaries require glibc 2.28+; use npx on Alpine. See the binary build workflow.

Sizes for 0.4.0 (Node 26.12.1 inside each binary):

The npm package is 930 KB unpacked and needs Node 24+. Every release is installed and run on ubuntu-24.04, macos-15 and windows-2025 by the install check.

Release install checks run on ubuntu-24.04, macos-15 and windows-2025.

npx / npm (for npm-based environments)

The npm package requires Node 24+:

npm install -g @ghostpaw/souls

npx -y @ghostpaw/souls --help

Library (for harnesses embedding it in code)

npm install @ghostpaw/souls

import { initSoulsTables, read, write } from '@ghostpaw/souls';

See Quick Start for library usage.

Quick Start

import { DatabaseSync } from 'node:sqlite';

import { initSoulsTables, read, write } from '@ghostpaw/souls';

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

const soul = write.createSoul(db, { name: 'Reviewer', essence: 'I review code by reading for intent before scanning for bugs.', description: 'Code review specialist', });

write.addTrait(db, soul.id