Hermes Souls

Hermes Souls is a small registry and installer for Hermes-specific SOUL.md persona packages and convention packs.

Reference model:

• Gallery of installable persona packages.
• Each package ships soul.json, SOUL.md, IDENTITY.md, STYLE.md, and AGENTS.md.
• Convention packs ship convention.json, CONVENTION.md, and AGENTS.md.
• CLI install is designed for npx @dantelabs/hermes-souls install owner/name.
• Cloudflare Pages hosts the static registry. Pages Functions expose a small API.

Local Development

npm install
npm run dev

Build

npm run build

CLI

npx @dantelabs/hermes-souls list
npx @dantelabs/hermes-souls search coding
npx @dantelabs/hermes-souls show hermes/surgical-engineer
npx @dantelabs/hermes-souls install hermes/surgical-engineer
npx @dantelabs/hermes-souls conventions
npx @dantelabs/hermes-souls install-convention hermes/secret-hygiene
npx @dantelabs/hermes-souls bundles
npx @dantelabs/hermes-souls install-bundle hermes/starter --use hermes
npx @dantelabs/hermes-souls doctor
npx @dantelabs/hermes-souls version

By default the CLI writes to ~/.hermes/souls/<name>/. Override it with:

npx @dantelabs/hermes-souls install hermes/surgical-engineer --workspace ./souls

Activate a soul for Hermes:

npx @dantelabs/hermes-souls use hermes/surgical-engineer

This writes the full package to ~/.hermes/souls/<name>/, then merges IDENTITY.md, SOUL.md, and STYLE.md into ~/.hermes/SOUL.md. Existing SOUL.md files are backed up before overwrite.

Equivalent install-and-activate form:

npx @dantelabs/hermes-souls install hermes/ops-guardian --use hermes

Hermes can also read project-level AGENTS.md, but this CLI does not overwrite project instructions by default. To write the selected soul's workflow rules to the current directory:

npx @dantelabs/hermes-souls use hermes/ops-guardian --write-agents

Use a custom Hermes home:

HERMES_HOME=/custom/hermes npx @dantelabs/hermes-souls use hermes/doc-editor

Use a remote registry instead of the package-bundled data:

npx @dantelabs/hermes-souls list --registry https://hermes.dante-labs.com
npx @dantelabs/hermes-souls install surgical-engineer --registry https://hermes.dante-labs.com
npx @dantelabs/hermes-souls doctor --registry https://hermes.dante-labs.com

You can also set HERMES_SOULS_REGISTRY=https://hermes.dante-labs.com.

Install a convention pack:

npx @dantelabs/hermes-souls show-convention hermes/cli-baseline
npx @dantelabs/hermes-souls install-convention hermes/cli-baseline
npx @dantelabs/hermes-souls install-convention hermes/request-routing

By default convention packs write to ~/.hermes/conventions/<name>/. Passing --write-agents writes the convention's project-level AGENTS.md into the current directory after backing up any existing file.

Install a curated bundle:

npx @dantelabs/hermes-souls show-bundle hermes/starter
npx @dantelabs/hermes-souls install-bundle hermes/starter --use hermes

Bundles install one soul under ~/.hermes/souls/<name>/ and the selected conventions under ~/.hermes/conventions/<name>/.

Registry API

Cloudflare Pages Functions expose:

GET /api
GET /api/health
GET /api/schema
GET /api/souls
GET /api/souls/:owner/:name
GET /api/souls/:owner/:name/SOUL.md
GET /api/souls/:owner/:name/IDENTITY.md
GET /api/souls/:owner/:name/STYLE.md
GET /api/souls/:owner/:name/AGENTS.md
GET /api/conventions
GET /api/conventions/:owner/:name
GET /api/conventions/:owner/:name/CONVENTION.md
GET /api/conventions/:owner/:name/AGENTS.md
GET /api/bundles
GET /api/bundles/:owner/:name

The list endpoint returns compact metadata. The detail endpoint returns the full package, including SOUL.md, IDENTITY.md, STYLE.md, and AGENTS.md body text.

Cloudflare Pages

The project is prepared for Cloudflare Pages:

• Build command: npm run build
• Output directory: dist
• Functions directory: functions
• Suggested custom domain: hermes.dante-labs.com

If the Cloudflare token lacks Pages permissions, connect the Git repository in the Cloudflare dashboard, then use this project configuration.

Local Pages runtime:

npm run build
npm run pages:dev

Direct deploy when the token has Pages permission:

npm run deploy

Reference Research

Migration notes are in docs/research/clawsouls-reference.md.

The current implementation follows these reference ideas:

• Soul packages are portable markdown plus soul.json metadata.
• SOUL.md, IDENTITY.md, STYLE.md, and AGENTS.md have distinct jobs.
• Hermes activation maps the merged persona into ~/.hermes/SOUL.md.
• AGENTS.md is project-level and therefore opt-in for overwrites.

Verification

npm run check
npm run test
npm run build
npm run pack:dry