# Owl Native Binary — Conceptual Overview

## What it is

A single compiled binary (`owl.exe`) that handles all agent messaging. You point `$OWL` and `$LIVE` at it and everything works the same as the bash scripts, just faster.

## Owl messaging (agent-to-agent communication)

When an agent starts listening (`poll`), the binary spins up a small TCP server on localhost and registers its address in a shared SQLite registry. Other agents can discover it there.

**Sending a message:** The binary looks up the target in the registry. If the target is online, it delivers directly over TCP — sub-second. If the target is offline, the message goes into a per-agent SQLite spool with a 30-minute TTL. When the target comes back online and starts polling, it drains its spool first, then listens for live TCP connections.

**Other owl commands** (setup, list, stop, cleanup, etc.) work on the filesystem — creating/removing perch directories, reading info.json files, checking which agents are alive.

## Live agents (Self + Psyche system)

**Starting a live agent** (`live start`) does two things: registers a Self perch for you, and spawns a Psyche as a separate `claude` CLI process. The Psyche runs in a wrapper loop inside the binary — it polls for messages, injects the current timestamp, and pipes everything to `claude -p --resume` so the Psyche accumulates context across invocations.

**Commune** sends a status update to your Psyche. **Pulse** is when the Psyche decides you might have forgotten something and nudges you. **Timed pulse** lets you schedule a one-shot reminder at a future time — the Psyche spawns a background sleep-then-deliver process.

## Spine/Touch (supervision)

**Spine** is an optional supervisor you boot when running multiple live agents. It spawns **Touch**, a lightweight health checker that scans every 5 minutes for dead Psyche processes. If Touch finds one, it tells Spine, Spine verifies it's really dead (not just between polls), and notifies the affected Self agent so they can revive.

## Fallback

The original bash scripts still work. Switching back is just re-pointing the env vars. The native binary produces byte-identical output, so skills and agent prompts don't need changes.