oh-my-hermes: Instructions file for Claude Code

CLAUDE.md

Practical Claude Code guidance for this repo. Product direction, delivery grain, PR report style, evidence boundaries, and commit trailers are defined in AGENTS.md and docs/DIRECTION.md — read those first; this file does not repeat them. CONTEXT.md is the glossary for the OMH ↔ Hermes Agent boundary (which product owns which surface, state root, and TUI); use its terms before reasoning about anything that touches Hermes Agent.

What This Repo Is

oh-my-hermes (OMH) is a Hermes-native wrapper orchestration layer: a deterministic skill catalog, router, and prepared-handoff generator installed next to Hermes Agent. Core omh code makes no LLM, API, or network calls and never patches Hermes. Pure Python 3.11+, zero runtime dependencies. One scoped exception: omh coding fanout dispatch (explicit opt-in) spawns local agent CLIs as subprocesses — those CLIs make their own network calls; omh itself still makes none, and nothing executes without that explicit command.

Build & Test

PYTHONPATH=tests uv run python -m unittest discover -s tests -v   # full suite
PYTHONPATH=tests uv run python -m unittest tests/test_cli.py -v   # one file
uv run python -m compileall -q src tests                          # syntax gate
uv run python -m omh.cli docs workflows --check                   # byte gate
uv run python -m omh.cli docs roles --check                       # byte gate
uv run python -m omh.cli docs claims --check --json               # selected claims
uv run --group lint ruff check src tests                          # static-analysis gate
git diff --check

• Always set PYTHONPATH=tests for unittest; test helpers live at tests root.
• Run the smallest test that proves your claim, then broaden if the touched surface is shared. Full suite before claiming done.
• uv run --group lint ruff check src tests installs the pinned Ruff version from the lint dependency group (declared in pyproject.toml) into the project's uv-managed environment — no globally installed ruff needed. CI runs the identical command as its own step. The initial rule set is Pyflakes (F) only, scoped narrow to stay actionable on a ~135k LOC repo; see the [tool.ruff] block in pyproject.toml for the per-file re-export exclusions and the deliberately-not-yet-enforced broad-exception (BLE001) policy, owned by issue #652.
• That broad-exception policy is a gate, not a comment. tests/test_broad_exception_policy.py re-derives every broad except site in src/ from source and fails when one is not classified as either intentional (the failure is classified and surfaced) or needing the #637 treatment (the failure is relabeled as a normal result). Add the verdict in that file when you add a broad except; do not record hit counts or line numbers in prose, they drift.