# External Integrations

**Analysis Date:** 2026-03-28

## APIs & External Services

**None.** This project has zero external API calls, no network dependencies, and no HTTP requests. All communication is local filesystem-based IPC.

## Data Storage

**Databases:**
- None. No database of any kind.

**File Storage:**
- Local filesystem only
  - Owlery directory: `$HOME/.claude/owlery/`
  - Each agent ("owl") gets a perch directory: `$HOME/.claude/owlery/<id>/`
  - Perch contents:
    - `inbox/` - Directory holding `*.msg` files (timestamped: `<epoch>-<random>.msg`)
    - `ready` - Sentinel file indicating the owl is listening (created by `setup`/`poll --setup` in `owl.sh` lines 57, 70)
    - `info.json` - Metadata with `owl_id`, `started`, `mode`, `pid` (written by `poll` at `owl.sh` line 75)
  - Message format: first line is `__REPLY_TO__:<sender-id>`, rest is body (`owl.sh` `_write_msg` function, line 32)

**Caching:**
- None

## Authentication & Identity

**Auth Provider:**
- None. No authentication mechanism. Any process with filesystem access to `$HOME/.claude/owlery/` can read/write messages.
- Agent identity is purely convention-based: agents pick short string IDs (e.g., `deployah`, `waffle`) with no verification.

## Monitoring & Observability

**Error Tracking:**
- None. Errors are printed to stdout/stderr and surfaced to the calling Claude Code agent.

**Logs:**
- No logging framework. Script outputs status lines (`READY:`, `SENT:`, `REPLIED:`, `STOPPED:`, `CLEANED:`, `ACTIVE:`, `NO_PERCH:`, `STALE:`) that Claude Code agents parse.

## CI/CD & Deployment

**Hosting:**
- Local machine only. Installed to `~/.claude/skills/owl/` per `docs/DEPLOY.md`.

**CI Pipeline:**
- None. No CI/CD configuration detected.

**Deployment method:**
- Manual copy: `cp SKILL.md owl.sh ~/.claude/skills/owl/ && chmod +x ~/.claude/skills/owl/owl.sh`
- Portable bundle: `tar czf owl-skill.tar.gz SKILL.md owl.sh`

## Environment Configuration

**Required env vars:**
- `OWL` - Set in `~/.claude/settings.json`, value is `bash <absolute-path-to-owl.sh>`. Used by Claude Code agents to invoke the script.
- `HOME` - Standard OS variable. Used internally by `owl.sh` line 5 to resolve owlery path.

**Secrets location:**
- No secrets. No API keys, tokens, or credentials.

## Webhooks & Callbacks

**Incoming:**
- None. Message delivery is file-based polling (1-second interval loop in `_poll_once`, `owl.sh` line 46).

**Outgoing:**
- None.

## Host Platform Integration

**Claude Code Skills System:**
- `SKILL.md` frontmatter (lines 1-5) registers the skill with Claude Code using `name` and `description` fields
- Claude Code loads `SKILL.md` as agent instructions when users invoke owl-related commands
- The `$OWL` environment variable bridges Claude Code agent context to the bash script
- `docs/SKILL_SPEC-LIVE.md` describes a planned "Live Agent" extension that would add persistent agents with Psyche/Spine architecture on top of the owl messaging primitives

## Process Management

**PID tracking:**
- `owl.sh` records the polling process PID in `info.json` (`owl.sh` line 75)
- `_check_alive` (`owl.sh` lines 17-26) uses `kill -0` to verify whether a polling process is still running
- `list` command (`owl.sh` lines 112-139) auto-cleans stale perches where the PID is dead

---

*Integration audit: 2026-03-28*