hermes-howto: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this Hermes Agent tutorial repository.

Project Overview

Hermes How To is a tutorial repository for Hermes Agent features. This is documentation-as-code — the primary output is markdown files organized into numbered learning modules, not an executable application.

Architecture: Each module (01-14) covers a specific Hermes Agent feature with copy-paste templates, Mermaid diagrams, and examples. The build system validates documentation quality and generates an EPUB ebook.

Common Commands

Pre-commit Quality Checks

All documentation must pass four quality checks before commits (these run automatically via pre-commit hooks):

# Install pre-commit hooks (runs on every commit)
pre-commit install

# Run all checks manually
pre-commit run --all-files

The four checks are:

1. markdown-lint — Markdown structure and formatting via markdownlint
2. cross-references — Internal links, anchors, code fence syntax (Python script)
3. mermaid-syntax — Validates all Mermaid diagrams parse correctly (Python script)
4. link-check — External URLs are reachable (Python script)
5. build-epub — EPUB generates without errors (on .md changes)

Development Environment Setup

# Install uv (Python package manager)
pip install uv

# Create virtual environment and install Python dependencies
uv venv
source .venv/bin/activate
uv pip install -r scripts/requirements-dev.txt

# Install Node.js tools (markdown linter and Mermaid validator)
npm install -g markdownlint-cli
npm install -g @mermaid-js/mermaid-cli

# Install pre-commit hooks
uv pip install pre-commit
pre-commit install

Testing

Python scripts in scripts/ have unit tests:

# Run all tests
pytest scripts/tests/ -v

# Run with coverage
pytest scripts/tests/ -v --cov=scripts --cov-report=html

# Run specific test
pytest scripts/tests/test_build_epub.py -v

Code Quality