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

2.8 KiB Raw Permalink Blame History