# Hermes Gitea & Agent Development Ecosystem Manual

**Version 1.0 | June 21, 2026**

This manual documents the full Hermes AI Agent Development setup on Gitea. It covers repositories, the role-based multi-agent system, workflows, the critical verified operations protocol, and how to work within it. Maintained as part of your personal-agent-os knowledge base.

## 1. Introduction & Philosophy

The Hermes ecosystem uses layered repositories for clear separation of concerns:

- **core-planning (Ty_Tech/core-planning):** Read-only strategic planning. High-level decisions, project charters, architecture. This is the single source of truth for "what we're doing and why."
- **personal-agent-os (Tony_tech/personal-agent-os):** Active workspace. Knowledge base, projects, automation patterns, agent config. This is where Leonard builds.
- **hermes-agent (Tony_tech/hermes-agent):** Hermes installation, config, skills, plugins. Local agent infrastructure.
- **thornhill-website (Tony_tech/thornhill-website):** Production website for Thornhill Construction.
- **veripath (Tony_tech/veripath):** Legal/verification projects.

## 2. Multi-Agent System

### Roles
- **Leonard:** VPS agent (primary builder). Runs on VPS, has access to `personal-agent-os`, VPS tools, and SSH tunnels.
- **Jimmy:** Local agent (primary executor). Runs on laptop, handles local tasks, coordinates with Leonard.
- **Charlie:** Voice/creative agent. Handles TTS, voice workflows, creative content.

### Communication
- **Agent discussion board:** `00_system/agent-discussion.md` for cross-agent coordination
- **Agent comms inbox/outbox:** `agent-comms/` folder in `personal-agent-os` for structured messaging
- **Sync bot:** Automated bidirectional sync between agents via Gitea hooks

### Rules
- Leonard builds alone by default
- MoA only when Leonard flags a real design fork
- Jimmy handles local PC tasks, voice, TTS
- All agents share the same Obsidian vault for context

## 3. Verified Operations Protocol

### Model Switching
1. Check what's running: `hermes status`
2. Switch model: `hermes model <model-name>` (session-scoped)
3. Persist switch: `hermes config set model.default <model-id>`
4. Add fallback: `hermes fallback add <model-id>`
5. Verify: `hermes status` should show new model as primary

### Cron Jobs
1. List jobs: `hermes cron list`
2. Create: `hermes cron create --name <name> --prompt "<prompt>" --schedule "<cron>"`
3. Update: `hermes cron update --id <id> --prompt "<new-prompt>"`
4. Run: `hermes cron run --id <id>`
5. Check: `hermes cron log --id <id>`

### Git Sync
1. Local changes → `git add -A && git commit -m "update" && git push`
2. Vault sync cron runs every 6h: `vault-sync` job
3. Never commit secrets (`.gitignore` protects `ORK.txt`, `VPS.txt`)

## 4. Local Setup

### Models
- **LFM2.5-2.6B:** Primary local model. Runs on port 1920. ~2.1GB VRAM.
- **FreeToken:** Manual launch only. `ft.exe serve --model-path C:/models/gpt-oss-20b --port 1919`
- **Brother 5090:** Tailnet fallback. Qwen3.6 27B MTP at 100.64.0.2:8084

### Hermes Desktop
- Auto-starts via `Hermes Desktop.lnk` in Windows Startup
- Built locally with `hermes desktop --build-only`
- Bot mode built-in, profiles visible as bots

### Voice
- Wake word: "hey Jimmy" via sherpa
- Edge TTS AriaNeural provider
- Auto-TTS enabled, barge-in enabled

## 5. Project Tracking

Projects tracked in `04_projects/<slug>/`:
- `status.md` — current status, phase, priorities
- `decisions.md` — key decisions with rationale
- `notes.md` — working notes

Active projects listed in `HOME.md` (max 3 primary).

## 6. Security Notes

- **Never commit secrets to git.** Secrets live in environment variables or `.gitignore`'d files.
- **Gitea tokens** should be rotated periodically.
- **SSH tunnels** must be used for VPS services accessible from the laptop.
- **Public repos** must be audited for accidental credential exposure.

## 7. Troubleshooting

### Model not responding
- Check port: `netstat -ano | grep :<port>`
- Check process: `tasklist | grep -i <model-name>`
- Check GPU: `nvidia-smi`
- Try manual API call: `curl http://localhost:<port>/v1/models`

### Cron not running
- Check job status: `hermes cron list`
- Check logs: `hermes cron log --id <id>`
- Check cron schedule syntax

### Vault sync failing
- Check git remote: `git remote -v`
- Check `.gitignore` is protecting secrets
- Check Gitea repo exists and is accessible

## 8. Future Improvements

- [ ] Add health check cron for all services
- [ ] Build agent-to-agent messaging via Gitea webhooks
- [ ] Create project dashboard (auto-generated from status.md files)
- [ ] Implement automated vault consolidation with better quality checks
- [ ] Add RAG query interface to Hermes desktop