pi-irc-messenger: Instructions file for Codex

Project: Pi IRC Messenger

A pi-coding-agent extension enabling IRC communication for AI agents.

Project Context

Type: TypeScript pi-coding-agent extension
Purpose: Connects agents to IRC servers for multi-agent collaboration
Framework: pi-coding-agent Extension API (@mariozechner/pi-coding-agent)

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for pi extension development.

Architecture

• Singleton Pattern: One IRC client per session (module-level ircClient)
• Event-Driven: Pure async with irc-framework events, no Promise wrappers
• Message Routing: DMs → sendUserMessage() (steering), Channel → sendMessage() (followUp)
• Config Storage: ~/.pi/agent/irc/config.json for profiles/servers

Source Structure

src/
├── index.ts      # Main extension (tools, events, client management)
├── types.ts      # TypeScript interfaces (IRCServer, IRCProfile, IRCConfig, IRCState)
└── profiles.ts   # Profile/config loading (read-only access)

Key Interfaces

IRCServer    { host, port, ssl? }
IRCProfile   { server, nick, username?, realname?, channels, nickservPass?, autoConnect? }
IRCConfig    { servers: Record<string, IRCServer>, profiles: Record<string, IRCProfile> }
IRCState     { connected, host, port, nick, channels, profileName? }

Extension API Patterns

Registering Tools

pi.registerTool({
  name: "tool_name",
  label: "Human Label",
  description: "...",
  parameters: Type.Object({ ... }),  // @sinclair/typebox
  async execute(_toolCallId, params, _signal, _onUpdate, ctx) { ... }
});

Registering CLI Flags

pi.registerFlag("flag-name", { description: "...", type: "string", default: "" });
const value = pi.getFlag("flag-name");

Sending Messages

// Steering (triggers agent turn)
pi.sendUserMessage(content, { deliverAs: "steer" });

// Follow-up (context only, optional turn trigger)
pi.sendMessage({ customType: "...", content, display: true, details: {...} }, { triggerTurn: false });