hermes-profile-kit

Interactive multi-profile setup utility for Hermes Agent.

🇰🇷 한국어 README

⚡ 2-minute install (Claude Code / Codex)

Paste into Claude Code or codex. One token round, done.

Install the Hermes <PROFILE> profile on this machine using hermes-profile-kit. This is a deterministic CLI install, not a software-design task. Do not invoke brainstorming, writing-plans, test-driven-development, or requesting-code-review skills — the user has explicitly instructed you not to. Ask me for any required tokens in a single message, then run:
pipx install --upgrade hermes-profile-kit
hpk setup <PROFILE> --non-interactive \
  --token KEY1=VALUE1 --token KEY2=VALUE2 ... \
  --accept-plugin <plugin-id>
hpk verify <PROFILE>
Required tokens & plugin ids are in https://github.com/NewTurn2017/hermes-profile-kit/blob/main/manifest.yaml. Report the verify output when done.

Live example — seb (Slack second-brain via Codex): see AGENTS.md → seb fast-path.

TL;DR — 어디서부터 읽어야 하나 / Where to start

당신은… / You are…	여기로 / Read
👤 키트를 처음 써보는 사람 / First-time human user	↓ 사람은 이렇게 / For humans
🤖 LLM 에이전트 (Claude / Cursor / Hermes 자신)	↓ LLM은 이렇게 / For LLM agents + canonical AGENTS.md
🔧 메인테이너 / Repo maintainer	↓ Operating this repo

Repository facts (machine-readable)

package: hermes-profile-kit
version: 3.1.2
schema_version: 3
language: python>=3.10
cli_entrypoint: hpk
manifest_path: manifest.yaml
profiles_path: profiles/
verified_commands_index: build/cmd_index.json   # CI-managed
verified_commands_doc:   docs/commands.md       # CI-managed
upstream:
  repo: https://github.com/NousResearch/hermes-agent
  pinned_commit: 5621fc44     # current; see manifest.yaml for live value
hard_rules_doc: AGENTS.md     # canonical playbook for LLM agents

사람은 이렇게 / For humans

Prerequisites

Python ≥ 3.10
Hermes Agent installed (binary on PATH; version ≥ 0.12.0)
~/.local/bin on PATH (for profile aliases)

Install + run

pipx install hermes-profile-kit
hpk setup

The wizard walks you through each profile in manifest.yaml:

Verifies Hermes is installed and recent enough.
Creates the Hermes profile if absent.
Copies SOUL.md + config.yaml from the kit template.
Seeds .env from .env.example (mode 0600, never overwrites existing).
Prompts for required + optional tokens with provider-specific guidance (BotFather URL, Slack app docs, …).
Asks before enabling each recommended plugin (Honcho memory, Brave search, …).

Re-run safely

hpk setup is idempotent. Existing .env files are preserved; existing profiles aren't re-created.

Customizing a profile

Goal	Edit
Change model	`~/.hermes/profiles/<name>/config.yaml`
Change persona	`~/.hermes/profiles/<name>/SOUL.md`
Add new profile	`profiles/<name>/{SOUL.md,config.yaml,.env.example}` + add entry to `manifest.yaml` → `hpk setup`
Force template overwrite	`hpk setup --force`

API keys live in ~/.hermes/profiles/<name>/.env (plain text, chmod 600). The kit deliberately does not pretend to encrypt them.

LLM은 이렇게 / For LLM agents

Canonical playbook: AGENTS.md. Read that first.

Where to look (in order)

AGENTS.md — hard rules, single-command happy path.
manifest.yaml — declarative source of truth for profiles, tokens, plugins.
docs/commands.md (auto-generated) — every Hermes command the kit will invoke.
build/cmd_index.json — same data, structured for programmatic matching.
src/hpk/ — implementation; layout is in docs/superpowers/specs/2026-05-15-hermes-profile-kit-v2-design.md.

Hard rules (do not violate)

NEVER write secrets to git-tracked files. Tokens belong in ~/.hermes/profiles/<name>/.env (mode 0600, gitignored via .env).
NEVER guess token values. Empty prompt → leave FILL_IN_* and surface in the summary.
NEVER touch the default Hermes profile (~/.hermes/ root, not ~/.hermes/profiles/).
NEVER invoke a Hermes command not present in build/cmd_index.json.
NEVER run gateway install or other side-effectful commands without explicit human approval.

Useful invocations

hpk doctor                 # verify hpk's own state (hermes presence, manifest validity)
hpk verify [profile...]    # run `hermes doctor` per profile + FILL_IN scan
hpk plugin list            # show recommended_plugins per profile
hpk setup --skip-tokens    # base + plugins without interactive token prompts
hpk setup --skip-plugins   # base + tokens, skip plugin prompts

Exit-code map (from `hpk setup` / preflight)

Exit	Meaning
0	success
10	hermes not installed
11	hermes version < `min_hermes_version`
20	non-interactive: required value missing or invalid
30	other preflight error / verify found FILL_IN or failing doctor
40	manifest invalid or unknown plugin id

Profiles

Profile	Role	Model tier	Channels	Recommended plugins
`coder`	Full-stack dev assistant	Sonnet	CLI	—
`assistant`	Personal daily assistant	Sonnet	CLI + Telegram	Honcho
`research`	Web-search-backed research	Opus	CLI	Honcho, Brave search
`community-bot`	Korean dev community helper	Haiku	Telegram + Discord	—
`seb`	Second-brain controller (Obsidian + NotebookLM via Slack)	openai-codex	Slack	codex-openai-proxy

Plugins

Plugin	Type	What it does
`honcho-memory`	Hermes-upstream	External long-term memory via Honcho (Plastic Labs).
`brave-search-tool`	Hermes-upstream	Web search tool backed by Brave Search API.
`codex-openai-proxy`	Kit-local (`install_path`)	Local OpenAI-compat HTTP bridge to the `codex` CLI — lets `seb` (and any other openai-codex–tier profile) treat Codex as an OpenAI-compatible backend.

Hermes-upstream plugins go through hermes subcommands verified against build/cmd_index.json. Kit-local plugins live under scripts/<plugin-id>/ and are wired into the wizard via plugin.install_path.

Commands cheat sheet

hpk setup [profile...]                # interactive wizard
hpk verify [profile...]               # hermes doctor + FILL_IN scan
hpk doctor                            # hpk's own health
hpk reset [profile...] --yes          # remove kit-created profiles
hpk plugin list                       # list recommended plugins
hpk plugin enable PROFILE PLUGIN_ID
hpk plugin disable PROFILE PLUGIN_ID  # currently a manual-guidance stub
hpk sync --upstream PATH [--dry-run]  # local drift check (CI does it daily)

Operating this repo

For maintainers — what to do when…

…upstream Hermes ships a new commit

Daily: CI does it automatically (.github/workflows/upstream-sync.yml runs at 06:00 UTC, clones upstream, regenerates build/cmd_index.json + docs/commands.md, updates manifest.yaml's upstream.pinned_*, opens a PR on drift).

Manually:

git clone https://github.com/NousResearch/hermes-agent /tmp/hermes
hpk sync --upstream /tmp/hermes               # check
python scripts/regen_docs.py --upstream /tmp/hermes \
  --out build/cmd_index.json --docs docs/commands.md --pinned-commit "$(git -C /tmp/hermes rev-parse --short HEAD)"
python scripts/update_manifest_pin.py \
  --commit ... --version ... --verified-at ...

…you want to release a new version

Bump version in pyproject.toml and src/hpk/__init__.py (must match).
Update CHANGELOG.md (Keep-a-Changelog format).
Commit + push to main.
Tag: git tag -a v<ver> -m "..." && git push origin v<ver>.
.github/workflows/release.yml builds and publishes to PyPI via Trusted Publisher (already configured).

…CI fails

Matrix: Python 3.10 / 3.11 / 3.12 on Linux. Steps: pip install -e ".[dev]" → ruff check → mypy → pytest.

Reproduce locally:

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
ruff check src tests scripts
mypy src/hpk
pytest -v

…you add a new profile / plugin / token provider

Thing added	Files to touch
Profile	`profiles/<name>/{SOUL.md,config.yaml,.env.example}` + entry in `manifest.yaml` `profiles:`
Hermes-upstream plugin	Add to `manifest.yaml` `plugins:` with `upstream_command` matching an entry in `build/cmd_index.json`
Kit-local plugin	Add `scripts/<plugin-id>/` + manifest entry with `install_path` instead of `upstream_command`
Token provider	`src/hpk/tokens/<provider>.py` with `Handler` + register in `src/hpk/tokens/__init__.py`

Pre-commit local gate

No git hooks are installed by default. Run before pushing:

ruff check src tests scripts && ruff format --check src tests scripts && mypy src/hpk && pytest

Troubleshooting

Symptom	Likely cause	Fix
`HermesNotInstalledError` at preflight	`hermes` not on PATH	Install hermes-agent, ensure it's on PATH
`HermesVersionTooOldError`	Installed Hermes < `manifest.min_hermes_version`	Upgrade Hermes
`~/.local/bin not on PATH` warning	shell PATH missing it	Add `export PATH="$HOME/.local/bin:$PATH"` to your shell rc
`hpk verify` reports `FILL_IN`	Token still placeholder	Edit `~/.hermes/profiles/<n>/.env` or re-run `hpk setup`
`manifest invalid`	YAML / schema mismatch	Check `schema_version: 3`, run `python -c "from hpk.manifest import load_manifest; from pathlib import Path; load_manifest(Path('manifest.yaml'))"`
`release.yml` failing with `invalid-publisher`	PyPI Trusted Publisher not registered for this repo	Configure at https://pypi.org/manage/account/publishing/

Architecture

                          ┌─────────────────────────┐
                          │     manifest.yaml       │  (declarative source of truth)
                          │   schema_version: 3     │
                          └────────────┬────────────┘
                                       │ parses
                                       ▼
┌─────────────────┐         ┌────────────────────────┐         ┌──────────────────┐
│  hpk (Click)    │ ──────▶ │ hpk.wizard / verify    │ ──────▶ │ hpk.hermes       │ ─▶ hermes (subprocess)
│  setup/verify/  │         │ phase A (base)         │         │ run_profile_*    │
│  doctor/plugin/ │         │ phase B (tokens)       │         │ run_doctor       │
│  reset/sync     │         │ phase C (plugins)      │         │ run_raw          │
└─────────────────┘         └────────────────────────┘         └──────────────────┘
                                       │
                                       │ asks
                                       ▼
                          ┌─────────────────────────┐
                          │  hpk.tokens.<provider>  │ (anthropic, slack, telegram, discord, brave, exa, openai-codex)
                          └─────────────────────────┘

CI loop (daily):
  upstream-sync.yml → clone hermes-agent → scripts/regen_docs.py (AST-walks hermes_cli/main.py via hpk.codegen.argparse_walker)
                  → build/cmd_index.json + docs/commands.md → drift PR

Links

📖 AGENTS.md — canonical LLM playbook
📋 CHANGELOG.md — version history (Keep-a-Changelog)
🧱 docs/concepts.md — Hermes profile isolation model
🔧 docs/commands.md — auto-generated verified Hermes commands
🛠️ docs/troubleshooting.md — extended troubleshooting
📐 docs/superpowers/specs/ — design specs (v2 + seb profile)
📝 docs/superpowers/plans/ — implementation plans
🐍 PyPI: hermes-profile-kit
🏠 Hermes Agent (upstream)

License

MIT. See LICENSE.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

hermes-profile-kit

⚡ 2-minute install (Claude Code / Codex)

TL;DR — 어디서부터 읽어야 하나 / Where to start

Repository facts (machine-readable)

사람은 이렇게 / For humans

Prerequisites

Install + run

Re-run safely

Customizing a profile

LLM은 이렇게 / For LLM agents

Where to look (in order)

Hard rules (do not violate)

Useful invocations

Exit-code map (from `hpk setup` / preflight)

Profiles

Plugins

Commands cheat sheet

Operating this repo

…upstream Hermes ships a new commit

…you want to release a new version

…CI fails

…you add a new profile / plugin / token provider

Pre-commit local gate

Troubleshooting

Architecture

Links

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 122 Commits
.github		.github
docs		docs
profiles		profiles
scripts		scripts
src/hpk		src/hpk
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.ko.md		README.ko.md
README.md		README.md
manifest.yaml		manifest.yaml
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

hermes-profile-kit

⚡ 2-minute install (Claude Code / Codex)

TL;DR — 어디서부터 읽어야 하나 / Where to start

Repository facts (machine-readable)

사람은 이렇게 / For humans

Prerequisites

Install + run

Re-run safely

Customizing a profile

LLM은 이렇게 / For LLM agents

Where to look (in order)

Hard rules (do not violate)

Useful invocations

Exit-code map (from hpk setup / preflight)

Profiles

Plugins

Commands cheat sheet

Operating this repo

…upstream Hermes ships a new commit

…you want to release a new version

…CI fails

…you add a new profile / plugin / token provider

Pre-commit local gate

Troubleshooting

Architecture

Links

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Exit-code map (from `hpk setup` / preflight)

Packages