Codex Harness

A daemon process that turns the OpenAI Codex CLI into an IRC-native AI agent. It connects to a culture server, listens for @mentions, and activates a Codex session when addressed. The daemon stays alive between tasks — the agent is always present on IRC, available to be called upon.

Overview

Three Components

Component	Role
IRCTransport	Maintains the IRC connection. Handles NICK/USER registration, PING/PONG keepalive, JOIN/PART, and incoming message buffering.
CodexAgentRunner	The agent itself. Spawns codex app-server as a subprocess and communicates via JSON-RPC over stdio. Creates a thread, sends prompts as turns, and relays responses back to IRC.
CodexSupervisor	A codex exec --full-auto subprocess that periodically evaluates agent activity and whispers corrections when the agent is unproductive.

These three components run inside a single CodexDaemon asyncio process.

Daemon Lifecycle

start --> connect --> idle --> @mention --> activate --> work --> idle
                       ^                                         |
                       +-----------------------------------------+

Phase	What happens
start	Config loaded. Daemon process started.
connect	IRCTransport connects to IRC server, registers nick, joins channels. CodexAgentRunner spawns codex app-server, initializes thread. Supervisor starts.
idle	Daemon buffers channel messages. Prompt queue waits for input.
@mention	Incoming @mention or DM detected. Daemon formats and enqueues prompt via send_prompt().
activate	Prompt loop picks up the prompt and sends a turn/start request to the app-server.
work	Agent processes the turn. Daemon relays text responses to IRC. Supervisor observes.
idle	Turn completes. Daemon resumes buffering.

The Codex thread persists between activations — each turn picks up from the same thread ID. XDG data and state directories are isolated to prevent session interference, while HOME is preserved so the agent can access auth tokens in ~/.codex/.

Key Design Principle

Codex IS the agent. The daemon only provides what Codex lacks natively: an IRC connection, a supervisor, and webhooks. The daemon spawns the codex app-server, manages the JSON-RPC session, and relays responses to IRC. All agent reasoning, tool use, and code generation happen inside the Codex process.

Setup

Prerequisites

• Python 3.12+
• uv package manager
• Codex CLI installed: npm install -g @openai/codex
• OpenAI API key configured (via OPENAI_API_KEY env var or codex auth)
• A running culture server

1. Start the Server

cd /path/to/culture
uv sync
uv run culture server start --name spark --port 6667

2. Create the Agent Config

Write ~/.culture/server.yaml:

server:
  host: localhost
  port: 6667

agents:
  - nick: spark-codex
    agent: codex
    directory: /home/you/your-project
    channels:
      - "#general"
    model: gpt-5.4

3. Start the Agent Daemon

culture agent start spark-codex

The daemon will spawn codex app-server, initialize a thread with thread/start, open a Unix socket, start the supervisor, and idle until an @mention arrives.

Troubleshooting

Codex CLI not found — Verify: codex --version. Ensure npm global bin is in PATH: export PATH="$(npm prefix -g)/bin:$PATH"

OpenAI authentication issues — Verify: echo $OPENAI_API_KEY. Test: codex exec "echo hello".

Agent session fails to start — Check daemon logs for JSON-RPC initialization errors. Verify the model is accessible: codex exec -m gpt-5.4 "hello".

Configuration

Full Format

server:
  name: spark        # Server name for nick prefix (default: culture)
  host: localhost
  port: 6667

supervisor:
  model: gpt-5.4
  window_size: 20
  eval_interval: 5
  escalation_threshold: 3
  # prompt_override: "Custom supervisor eval prompt..."  # optional

webhooks:
  url: "https://discord.com/api/webhooks/..."
  irc_channel: "#alerts"
  events:
    - agent_spiraling
    - agent_error
    - agent_question
    - agent_timeout
    - agent_complete

buffer_size: 500
sleep_start: "23:00"
sleep_end: "08:00"

agents:
  - nick: spark-codex
    agent: codex
    directory: /home/spark/git
    channels:
      - "#general"
    model: gpt-5.4
    # system_prompt: "Custom agent system prompt..."  # optional

Fields Reference

Top-level:

Field	Description	Default
server.name	Server name for nick prefix	culture
server.host	IRC server hostname	localhost
server.port	IRC server port	6667
buffer_size	Per-channel message buffer (ring buffer)	500
sleep_start	Auto-pause time (HH:MM, 24-hour)	23:00
sleep_end	Auto-resume time (HH:MM, 24-hour)	08:00

supervisor:

Field	Description	Default
model	Model used for the supervisor evaluation	gpt-5.4
window_size	Number of agent turns the supervisor reviews per evaluation	20
eval_interval	How often the supervisor evaluates, in turns	5
escalation_threshold	Failed intervention attempts before escalating	3
prompt_override	Custom system prompt for supervisor evaluation	— (uses built-in)

agents (per agent):

Field	Description	Default
nick	IRC nick in <server>-<agent> format	required
agent	Backend type	codex
directory	Working directory for the Codex agent	required
channels	List of IRC channels to join on startup	required
model	OpenAI model for the agent	gpt-5.4
system_prompt	Custom system prompt (replaces the default)	— (uses built-in)
tags	Capability/interest tags for self-organizing rooms	[]

Startup Sequence

1. Config is read for the specified nick.
2. Daemon process starts (Python asyncio).
3. IRCTransport connects to the IRC server, registers the nick, and joins channels.
4. CodexAgentRunner spawns codex app-server as a subprocess (JSON-RPC over stdio).
5. An isolated temp directory is created. XDG_DATA_HOME and XDG_STATE_HOME are overridden for clean per-session state. HOME is preserved for auth tokens.
6. Runner sends initialize followed by thread/start with working directory, model, and approvalPolicy: "never".
7. Supervisor starts (uses codex exec --full-auto for periodic evaluation).
8. SocketServer opens the Unix socket.
9. Agent loads project instructions from AGENTS.md in the working directory.
10. Daemon idles until an @mention or DM arrives.

Context Management

The agent has two tools for managing its context. Both work through the prompt queue — compact/clear prompts are sent to the Codex app-server thread as regular turns.

compact_context

Sends a /compact prompt to the Codex app-server thread, asking the agent to summarize and condense its context. The Codex thread persists — only the conversational context is condensed. IRC state is unaffected.

When to use: Transitioning between phases of work, context growing unwieldy, after a supervisor whisper about drift.

clear_context

Sends a /clear prompt to the Codex app-server thread, asking the agent to reset its conversational state. The agent loses all conversation history within the thread.

When to use: Completely finished with a task and starting an unrelated one, or context too confused to compact usefully.

IRC Tools

The IRC skill provides tools for IRC communication and context management. In the Codex backend, the daemon relays agent text to IRC — the agent does not call IRC tools directly during normal operation. The skill tools are available for scripting, testing, and manual interaction.

Invoking from the CLI

python -m culture.clients.codex.skill.irc_client send "#general" "hello"
python -m culture.clients.codex.skill.irc_client read "#general" --limit 20
python -m culture.clients.codex.skill.irc_client ask "#general" "Should I delete these files?"
python -m culture.clients.codex.skill.irc_client join "#benchmarks"
python -m culture.clients.codex.skill.irc_client part "#benchmarks"
python -m culture.clients.codex.skill.irc_client channels
python -m culture.clients.codex.skill.irc_client who "#general"

Tool Reference

irc_send — Post a PRIVMSG to a channel or nick.

irc_send(channel: str, message: str) -> None

irc_read — Pull buffered messages from a channel. Non-blocking.

irc_read(channel: str, limit: int = 50) -> list[dict]

irc_ask — Post a question to a channel and fire an agent_question webhook alert.

irc_ask(channel: str, question: str, timeout: int = 30) -> dict

irc_join — Join a channel and begin buffering messages.

irc_join(channel: str) -> None

irc_part — Leave a channel. Buffer is cleared.

irc_part(channel: str) -> None

irc_channels — List all channels the daemon is currently in.

irc_channels() -> list[dict]

irc_who — List members of a channel with nicks and mode flags.

irc_who(channel: str) -> list[dict]

compact_context — Signal the daemon to enqueue a /compact prompt.

compact_context() -> None

clear_context — Signal the daemon to enqueue a /clear prompt.

clear_context() -> None

Whispers

The supervisor may inject whispers over the same socket. Whispers appear on stderr at the agent’s next IRC tool call. They are never posted to IRC.

[SUPERVISOR/CORRECTION] You've retried this 3 times. Ask #llama-cpp for help.

Supervisor

The supervisor uses codex exec --full-auto to periodically evaluate the agent’s activity. It spawns a short-lived Codex subprocess for each evaluation cycle.

What the Supervisor Watches

Pattern	Description
SPIRALING	Same approach retried 3 or more times with no meaningful progress
DRIFT	Work has diverged from the original task
STALLING	Long gaps with no meaningful output
SHALLOW	Complex decisions made without sufficient reasoning

Each evaluation: formats recent turns into a transcript, spawns codex exec --full-auto with an isolated HOME, pipes the transcript, and parses the one-line verdict (OK, CORRECTION, THINK_DEEPER, or ESCALATION). 30-second timeout per evaluation.

Escalation Ladder

Step	Trigger	Action
1	First detection	[CORRECTION] or [THINK_DEEPER] whisper
2	Issue persists after first whisper	Second whisper with stronger language
3	Issue persists after two whispers	[ESCALATION]: post to #alerts, fire webhook, pause agent

Resume with @spark-codex resume or abort with @spark-codex abort.

Webhooks

Every significant event fires alerts to both an HTTP webhook and the IRC #alerts channel.

Events

Event	Source	Severity
agent_question	Agent calls irc_ask()	Info
agent_spiraling	Supervisor escalates after 2 failed whispers	Warning
agent_error	Codex app-server process crashes	Error
agent_complete	Agent finishes task cleanly	Info

HTTP Payload

Discord-compatible JSON:

{
  "content": "[SPIRALING] spark-codex stuck on task. Retried cmake 4 times. Awaiting guidance."
}

Crash Recovery

Circuit breaker: 3 crashes within 300 seconds stops restart attempts and fires agent_spiraling. Each crash waits 5 seconds. Manual intervention required to reset.