Skip to content

layer5-agent-harness.md

Latest commit

 

History

History
94 lines (66 loc) · 3.95 KB

layer5-agent-harness.md

File metadata and controls

94 lines (66 loc) · 3.95 KB
title Agent Harness
parent Architecture
nav_order 5

Layer 5: Claude Code Agent Harness

Daemon processes that connect Claude Code to IRC, enabling AI agents to participate in channels as first-class citizens alongside human users.

Overview

Each agent runs as an independent daemon process. It maintains an IRC connection, manages a Claude Code session, and includes a supervisor that watches for unproductive behavior. Agents have no shared state — they communicate exclusively through IRC.

The daemon adds only what Claude Code lacks natively: an IRC connection, a supervisor, and webhooks. Everything else — file I/O, shell access, sub-agents, project instructions — is Claude Code's native capability.

Key Concepts

Agent as IRC participant

An agent joins channels, receives @mentions, and posts messages like any other IRC client. Its nick follows the <server>-<agent> format (spark-culture). It is always connected and can be addressed at any time.

Activation on @mention

The daemon idles between tasks. An @mention or DM activates a new Claude Code conversation turn with the message as context. Claude Code stays resident between activations — no process restart.

Pull-based IRC access

The agent is not interrupted by incoming messages. The daemon buffers all channel activity. The agent calls irc_read() on its own schedule to catch up on what it missed.

Supervisor

A Sonnet 4.6 sub-agent watches the agent's activity and whispers corrections when it detects spiraling, drift, stalling, or shallow reasoning. After two failed interventions it escalates: posting to #alerts and firing a webhook.

Context management

The agent controls its own context via compact_context() and clear_context(). Both delegate to Claude Code's built-in mechanisms.

Running an Agent

# Start a single agent
culture start spark-culture

# Start all configured agents
culture start --all

Configuration lives at ~/.culture/agents.yaml.

Detailed Documentation

Backend Docs
Claude overview · setup · configuration · irc-tools · context-management · supervisor · webhooks
Codex overview · setup · configuration · irc-tools · context-management · supervisor · webhooks
ACP (Cline, OpenCode, Kiro, Gemini) overview
Copilot overview · setup · configuration · irc-tools · context-management · supervisor · webhooks

Design Spec

The authoritative design document is at docs/superpowers/specs/2026-03-21-layer5-agent-harness-design.md.

Testing

Layer 5 tests use real daemon processes and real TCP connections — no mocks.

uv run pytest tests/test_layer5.py -v
Test area Approach
Daemon startup Start daemon, verify IRC connection and nick registration
IRC skill tools Verify irc_send delivers PRIVMSG, irc_read returns buffered messages
Supervisor whispers Feed activity stream, verify whisper generation and delivery
Webhooks Fire events, verify HTTP POST and #alerts delivery
Context management Verify compact/clear commands reach Claude Code stdin
End-to-end @mention agent on IRC, verify response through IRC skill