hermes-agent/BOOT.md

BOOT.md — Hermes Agent

Fast path from clone to productive. Target: <10 minutes.

---

1. Prerequisites

Tool	Why
Git	Clone + submodules
Python 3.11+	Runtime requirement
uv	Package manager (install: curl -LsSf https://astral.sh/uv/install.sh | sh)
Node.js 18+	Optional — browser tools, WhatsApp bridge

---

2. First-Time Setup

git clone --recurse-submodules https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent.git
cd hermes-agent

# Create venv
uv venv .venv --python 3.11
source .venv/bin/activate

# Install with all extras + dev tools
uv pip install -e ".[all,dev]"

Common pitfall: If uv is not on PATH, the setup-hermes.sh script will attempt to install it, but manual uv install is faster.

---

3. Smoke Tests (< 30 sec)

python scripts/smoke_test.py

Expected output:

OK: 4 core imports
OK: 1 CLI entrypoints
Smoke tests passed.

If imports fail with ModuleNotFoundError, re-run: uv pip install -e ".[all,dev]"

---

4. Full Test Suite (excluding integration)

pytest tests/ -x --ignore=tests/integration

Integration tests require a running gateway + API keys. Skip them unless you are testing platform connectivity.

---

5. Run the CLI

python cli.py --help

To start the gateway (after configuring ~/.hermes/config.yaml):

hermes gateway run

---

6. Repo Layout for Agents

Path	What lives here
cli.py	Main entrypoint
hermes/	Core agent logic
toolsets/	Built-in tool implementations
skills/	Bundled skills (loaded automatically)
optional-skills/	Official but opt-in skills
tests/	pytest suite
scripts/	Utility scripts (smoke tests, deploy validation, etc.)
.gitea/workflows/	Forge CI (smoke + build)
.github/workflows/	GitHub mirror CI

---

7. Gitea Workflow Conventions

• Push to main: triggers ci.yml (smoke + build, < 5 min)
• Pull requests: same CI + notebook CI if notebooks changed
• Merge requirement: green smoke tests
• Security scans run on schedule via .github/workflows/

---

8. Common Pitfalls

Symptom	Fix
No module named httpx	uv pip install -e ".[all,dev]"
prompt_toolkit missing	Included in [all], but install explicitly if you used minimal deps
CLI hangs on start	Check ~/.hermes/config.yaml exists and is valid YAML
API key errors	Copy .env.example → .env and fill required keys
Browser tools fail	Run npm install in repo root

---

9. Quick Reference

# Reinstall after dependency changes
uv pip install -e ".[all,dev]"

# Run only smoke tests
python scripts/smoke_test.py

# Run syntax guard
python scripts/syntax_guard.py

# Start gateway
hermes gateway run

---

Last updated: 2026-04-07 by Bezalel