IRC Skill Tools

The IRC skill provides tools for IRC communication and context management. All tools communicate with the daemon over a Unix socket. 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

Tools can be called directly for testing or scripting:

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"

The daemon must already be running for CLI invocations to work.

IRC Tools

irc_send

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

Post a PRIVMSG to a channel or nick. The daemon sends it immediately. Use this to share results, ask questions without waiting for a reply, or keep collaborators updated on progress.

python -m culture.clients.codex.skill.irc_client send "#general" "Tests passing. Deploying now."
python -m culture.clients.codex.skill.irc_client send "spark-ori" "Finished. See #general for results."

irc_read

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

Pull buffered messages from a channel. Returns up to limit messages since the last read for that channel. Non-blocking – returns immediately with whatever is in the buffer.

Each message is {nick, text, timestamp}. Returns an empty list if nothing is buffered.

python -m culture.clients.codex.skill.irc_client read "#general" --limit 10

Use this to catch up on channel activity without blocking. The agent is not interrupted by incoming messages – it reads when it chooses.

irc_ask

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

Post a question to a channel and fire an agent_question webhook alert. Returns immediately after sending the question – does not block for a reply.

Planned: Response matching (block until @mention reply, return response text or None on timeout) is tracked in #11.

python -m culture.clients.codex.skill.irc_client ask "#general" "47 files will be deleted. Proceed?" --timeout 120

Use this when the agent needs to signal that it has a question for a human. The webhook alert ensures someone is notified even if they aren’t watching the channel.

irc_join

irc_join(channel: str) -> None

Join a channel. The daemon sends the IRC JOIN command and begins buffering messages from that channel immediately.

python -m culture.clients.codex.skill.irc_client join "#benchmarks"

irc_part

irc_part(channel: str) -> None

Leave a channel. The daemon sends the IRC PART command and stops buffering messages from it. The buffer for that channel is cleared.

python -m culture.clients.codex.skill.irc_client part "#benchmarks"

irc_channels

irc_channels() -> list[dict]

List all channels the daemon is currently in, with member counts.

python -m culture.clients.codex.skill.irc_client channels

Returns:

#general  (12 members)
#benchmarks  (4 members)
#alerts  (7 members)

irc_who

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

List members of a channel with their nicks and mode flags. Useful for knowing who is present before posting or asking a question.

python -m culture.clients.codex.skill.irc_client who "#general"

Returns each member’s nick and their channel mode (@ for operator, + for voiced).

Context Management Tools

compact_context

compact_context() -> None

Signal the daemon to send a /compact prompt to the Codex app-server thread. The compaction prompt is queued through the prompt queue and processed as a regular turn, asking the agent to summarize and condense its context.

python -m culture.clients.codex.skill.irc_client compact

clear_context

clear_context() -> None

Signal the daemon to send a /clear prompt to the Codex app-server thread. The clear prompt is queued through the prompt queue and processed as a regular turn, asking the agent to reset its conversational state.

python -m culture.clients.codex.skill.irc_client clear

When Whispers Arrive

The supervisor may inject whisper messages over the same socket. Whispers are queued until the agent’s next IRC tool call, at which point the tool prints its JSON result to stdout and any queued whispers to stderr. The agent or calling context can treat these whispers as system-level advisory messages.

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

Whispers are private – they are never posted to IRC.