132 lines
2.8 KiB
Markdown
132 lines
2.8 KiB
Markdown
# 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*
|