# Clawdie + Hermes-FreeBSD Integration Plan

## What we have

**hermes-bsd** (code.smilepowered.org/clawdie/hermes-bsd): A clean-room MIT-licensed
FreeBSD compatibility layer for Hermes Agent, forked from upstream NousResearch.
Four targeted patches (setup.py, uninstall.py, voice_mode.py, install script).
No LGPL encumbrance — pure MIT, same as upstream.

**Key facts:**

- Runs on FreeBSD without emulation or containers
- CLI, Telegram gateway, TUI all functional on FreeBSD
- `scripts/install-freebsd.sh` provides native installation
- Core agent logic is platform-agnostic Python — same codebase as upstream Hermes
- Gaps: no FreeBSD wheels for faster-whisper (voice), no clipboard implementation

## Why this matters for Clawdie

Currently OSA (FreeBSD 15 host) runs Codex CLI for ISO builds and cargo validation.
hermes-osa now runs on OSA as the always-on orchestrator (previously OSA had none and orchestration ran on debby). Adding
hermes-osa to OSA gives us:

| Capability               | Before        | After                     |
| ------------------------ | ------------- | ------------------------- |
| Hermes on FreeBSD        | ❌ None       | ✅ Native                 |
| ISO-side agent           | ❌ Codex only | ✅ Hermes + Codex         |
| layered-soul on FreeBSD  | ❌ No         | ✅ Via adapters/hermes.md |
| Headroom on FreeBSD      | ❌ No path    | ✅ Python works natively  |
| Colibri + Hermes co-host | ❌ Linux only | ✅ Both on FreeBSD        |
| Telegram gateway on OSA  | ❌ No         | ✅ Direct from FreeBSD    |

## Phased integration

### Phase 1: Standalone test (OSA side)

1. Install Hermes on OSA via `sh scripts/install-freebsd.sh` from hermes-bsd
2. Configure with a provider (DeepSeek or OpenRouter)
3. Verify basic functionality: terminal execution, file ops, web search
4. Test Telegram gateway on OSA
5. Document what works and what doesn't on FreeBSD 15

### Phase 2: Identity injection

1. Clone `layered-soul` on OSA
2. Load SOUL.md, USER.md, IDENTITY.md, AGENTS.md as profile context
3. Verify hermes-osa operates with the same identity as Hermes on debby
4. Test: can hermes-osa on OSA read the same skills as Hermes on debby?

### Phase 3: Colibri co-hosting

1. Both hermes-osa and colibri-daemon run on OSA simultaneously
2. hermes-osa can issue socket commands to the daemon (`cmd_status`, etc.)
3. Headroom sidecar runs on OSA (Python works natively)
4. Test: ISO build triggered by hermes-osa, results reported via Telegram

### Phase 4: ISO shipping

1. Add hermes-osa to Clawdie ISO package list
2. Pre-configure with layered-soul identity
3. Install as a FreeBSD service alongside colibri-daemon
4. First-boot wizard optionally sets up Hermes

## Agent matrix (expanded)

| Agent         | Host    | Harness                 | OS             | Model       | Role                      |
| ------------- | ------- | ----------------------- | -------------- | ----------- | ------------------------- |
| Hermes        | debby   | Hermes Agent (upstream) | Debian 13      | DeepSeek v4 | Secondary + soul backup (intermittent) |
| Zot           | debby   | Zot RPC                 | Debian 13      | GLM-5.1     | Coding, media             |
| Claude        | domedog | Claude Code             | Linux          | Claude      | Verification, review      |
| Codex         | osa     | Codex CLI               | FreeBSD 15     | GPT         | ISO builds, validation    |
| **hermes-osa** | **osa** | **Hermes Agent (FreeBSD)** | **FreeBSD 15** | **TBD**     | **Native FreeBSD agent**  |

## Gaps to close (from FreeBSD audit)

| Gap                            | Severity | Fix                                          |
| ------------------------------ | -------- | -------------------------------------------- |
| faster-whisper wheels          | Medium   | Build from source, or skip voice on FreeBSD  |
| Clipboard support              | Low      | Implement xclip/xsel equivalent for FreeBSD  |
| Docker/Singularity backends    | Low      | Skip — Colibri provides jail-based isolation |
| Platform detection in setup.py | Medium   | Add FreeBSD branches (upstreamable)          |

## Files to touch

| File                                            | Change                                   |
| ----------------------------------------------- | ---------------------------------------- |
| `layered-soul/memories/curated/agent-roster.md` | Add hermes-osa row                        |
| `layered-soul/AGENTS.md`                        | Add hermes-osa to agent references        |
| `layered-soul/docs/CONNECT-HERMES-SOUL.md`      | Document FreeBSD agent source connection |
| `clawdie-ai/docs/` (or handoff)                 | Agent matrix expansion note              |
| `colibri/docs/AGENTS.md`                        | Note FreeBSD-side Hermes availability    |