Adapters

Inbound and outbound adapters that connect Irrlicht to the outside world.

Inbound Adapters (Event Sources)

Inbound adapters drive events into the application. Each watches a specific agent's transcript files or process activity and emits session lifecycle events that the core state machine consumes.

Claude Code Adapter

  • Package: core/adapters/inbound/agents/claudecode/
  • Watches: ~/.claude/projects/**/*.jsonl
  • Uses the shared fswatcher with a flat directory structure
  • Adapter name in session state: "claude-code"

Codex Adapter

  • Package: core/adapters/inbound/agents/codex/
  • Watches: ~/.codex/sessions/ (deep nesting: YYYY/MM/DD/*.jsonl)
  • Uses the shared fswatcher with recursive directory watching
  • Adapter name: "codex"
  • Model detection from ~/.codex/config.toml

Pi Adapter

  • Package: core/adapters/inbound/agents/pi/
  • Watches: ~/.pi/agent/sessions/ (nested: --<cwd-dashed>--/*.jsonl)
  • Uses the shared fswatcher with recursive directory watching
  • Adapter name: "pi"
  • Model detection from ~/.pi/agent/settings.json
  • JSONL v3 format with session header, tree-structured entries, and multi-provider support

Process Scanner

  • Package: core/adapters/inbound/agents/processscanner/
  • Polls pgrep -x claude every 1 second
  • Creates pre-sessions (proc-<pid>) before transcripts exist
  • CWD discovery via lsof
  • Suppresses ghost pre-sessions when a real transcript exists

Shared File System Watcher

  • Package: core/adapters/inbound/agents/fswatcher/
  • Built on fsnotify (kqueue on macOS)
  • Recursive directory watching
  • Event types: EventNewSession, EventActivity, EventRemoved
  • Max age filtering
  • Race condition handling for new directories

Gas Town Orchestrator

  • Package: core/adapters/inbound/orchestrators/gastown/
  • Watches daemon state file + polls gt CLI
  • Role detection from session CWD paths
  • State model: global agents, codebases, worktrees, workers, work units

Outbound Adapters (System Integration)

Outbound adapters handle persistence, process monitoring, real-time communication, and other side effects that flow out of the core.

Filesystem Repository

  • Package: core/adapters/outbound/filesystem/
  • Persists session state as JSON files
  • Atomic writes via temp file + rename
  • Location: ~/Library/Application Support/Irrlicht/instances/

Process Watcher

  • Package: core/adapters/outbound/process/
  • kqueue EVFILT_PROC NOTE_EXIT monitoring
  • ~1ms exit detection latency
  • Periodic liveness sweep as fallback

WebSocket Hub

  • Package: core/adapters/outbound/websocket/
  • Fan-out to all connected clients
  • Non-blocking sends (drops slow subscribers)
  • Message types: session_created / session_updated / session_deleted, orchestrator_state

Git Resolver

  • Package: core/adapters/outbound/git/
  • Branch detection (strips worktree- prefix)
  • Project name from git-common-dir (worktree-aware)
  • CWD extraction from transcript tail (last 32KB)

Metrics Collector

  • Package: core/adapters/outbound/metrics/
  • Wraps TranscriptTailer
  • Extracts model, tokens, tool state, cost

mDNS Advertiser

  • Package: core/adapters/outbound/mdns/
  • Bonjour/Zeroconf service advertisement
  • Service type: _irrlicht._tcp
  • Includes hostname and IPv4 in TXT records

Logger

  • Package: core/adapters/outbound/logging/
  • Structured JSON logging
  • Auto-rotation at 10MB, 5 files retained

Writing a New Adapter

To add support for a new agent, follow these steps:

  1. Create a new package under core/adapters/inbound/agents/
  2. Implement the AgentWatcher interface
  3. Use the shared fswatcher for file-based agents
  4. Register the adapter in main.go