Overview
The conversation system has three layers:- Discord interface (
bot.py) — receives messages, manages reactions and typing indicators, handles interrupt-on-new-message - Agent loop (
agent.py) — routes messages to the Claude Agent SDK client, prepends context (timestamp and background updates), manages the session - Streamer (
streamer.py) — streams agent output to Discord with throttled edits and multi-message overflow
Talking to ollim-bot
Send a direct message to the bot. Only the bot owner (resolved viaapplication_info() at startup) can interact — messages from other
users are silently ignored, and guild messages are dropped.
The bot requires the message_content intent to read DM content. This is configured at startup:
Message flow
When you send a message, the bot processes it through a fixed sequence:Check for interrupt
If the agent is currently responding (the async lock is held), the bot calls
agent.interrupt() to cancel the in-progress response before proceeding.Resolve reply context
If your message is a reply to a previous message:
- Reply to a fork message — the bot looks up the fork session ID via
lookup_fork_session()and starts an interactive fork that resumes from that session. - Reply to a regular message — the bot prepends quoted context from the referenced message (plain text from
.content, or title + description + fields from the first embed). Quoted text is truncated to 500 characters.
Acquire lock and dispatch
The bot acquires the agent lock, sends a typing indicator, and dispatches the message to
stream_chat(). The agent prepends a timestamp (Pacific timezone) and any pending background updates to your message before sending it to the Claude API.Stream response
The agent’s response streams back to Discord in real time. See Streaming responses below.
Interrupt-on-new-message means you can always course-correct mid-response. Send a follow-up message and the bot drops what it was doing to address your latest input. You can also interrupt manually with the
/interrupt slash command.Images
The bot reads image attachments from your message and forwards them to the agent as base64-encoded content blocks. Supported formats are detected by magic bytes (not file extension):| Format | Magic bytes |
|---|---|
| JPEG | FF D8 FF |
| PNG | 89 50 4E 47 |
| GIF | 47 49 46 38 |
| WebP | 52 49 46 46 (RIFF) |
Streaming responses
Agent responses stream to Discord progressively. The streamer accumulates text deltas and flushes them to a Discord message on a throttled schedule:| Parameter | Value | Purpose |
|---|---|---|
FIRST_FLUSH_DELAY | 0.2s | Initial delay before the first message, allowing tokens to accumulate |
EDIT_INTERVAL | 0.5s | Time between message edits, respecting Discord’s rate limits |
MAX_MSG_LEN | 2000 | Discord’s character limit per message |
Session persistence
ollim-bot maintains a single persistent session with the Claude Agent SDK. The session ID is stored at~/.ollim-bot/state/sessions.json and is resumed on every bot restart.
Every message builds on the full conversation history. The SDK handles auto-compaction when the context grows too large — ollim-bot detects this by tracking session ID changes and logs a compacted event with the parent session ID for lineage tracking.
Session lifecycle events are recorded in ~/.ollim-bot/state/session_history.jsonl:
| Event | Trigger |
|---|---|
created | First message after startup with no prior session |
compacted | SDK auto-compacted the session (new session ID, parent tracked) |
swapped | Fork promoted to main session via save action |
cleared | User ran /clear |
interactive_fork | Interactive fork created |
bg_fork | Background fork created |
isolated_bg | Isolated background fork (no history) |
/clear to reset the conversation entirely — this drops the current session, deletes the session ID, and starts fresh. Use /compact to compress context without losing the session.
Next steps
Slash commands
All commands available during conversations — model switching, context management, forks, and more.
Forks
Branch conversations into isolated contexts for focused exploration.
How ollim-bot works
Deeper look at the agent loop, session model, and context flow.
Streaming & Discord
Technical details of how responses stream to Discord.