# 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

```bash
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)

```bash
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)

```bash
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

```bash
python cli.py --help
```

To start the gateway (after configuring `~/.hermes/config.yaml`):
```bash
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

```bash
# 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*