Skip to main content
The agent communicates structured information — task lists, calendar events, email digests, status updates — through Discord embeds. Each embed can include interactive buttons that trigger actions directly or route prompts back to the agent. Buttons survive bot restarts, so you can click them any time.

​
Overview

The agent decides when and what to send — you don’t create embeds manually. Buttons either perform a direct operation (complete a task, delete an event) or open a conversation with the agent through the inquiry system. Embeds sent from background forks or interactive forks are tagged with a footer indicating their source.

​
What embeds include

Each embed has a title and can include body text, a color-coded accent bar, structured fields, and up to five interactive buttons.
ParameterTypeRequiredDefaultDescription
titlestringYes—Embed heading
descriptionstringNo—Body text below the title
colorstringNo"blue"Embed accent color
fieldsarrayNo[]Structured name/value pairs
buttonsarrayNo[]Interactive buttons attached below the embed
criticalbooleanNofalseBypasses per-session limit, busy check, and ping budget in background forks

​
Colors

ValueMeaning
blueInformational (default)
greenSuccess / completion
redUrgent / error
yellowWarning
purpleAccent — also used for fork entry embeds

​
Fields

Fields render as labeled sections within the embed — inline fields appear side-by-side, non-inline fields stack vertically.

​
Buttons

Each button has a label and an optional style (defaults to grey).
StyleAppearance
primaryBlurple (Discord accent)
secondaryGrey
successGreen
dangerRed
Embeds can have up to 5 buttons. Buttons that delete the embed message are labeled “Close”.

​
Button actions

Buttons fall into two categories: direct actions that execute immediately, and inquiry buttons that route a prompt back through the agent.
Direct actions perform a single operation and respond with a temporary message only you can see. No agent involvement. If something goes wrong (for example, a Google API error), the error reason is shown the same way.
ButtonWhat it does
Mark completeMarks a Google Tasks item complete
Delete taskDeletes a Google Tasks item
Delete eventDeletes a Google Calendar event
CloseDeletes the embed message
Button behavior is determined by an action string encoded in the button. Direct actions use patterns like task_done:<task_id>, task_del:<task_id>, event_del:<event_id>, and dismiss. Inquiry buttons use the format agent:<prompt>, where <prompt> is the instruction the agent receives when clicked.

​
Inquiry buttons

When the agent sends an inquiry button, it stores a prompt behind the scenes. Clicking the button sends that prompt to the agent, and the agent responds in your conversation. If the button was sent by a background fork, clicking it opens an interactive fork that resumes from that fork’s session — so you can continue where the background task left off. Otherwise the prompt is processed in your current session. Inquiry buttons expire after 7 days. If you click an expired button, you’ll see an expiration notice.
When the agent creates an inquiry button, the prompt text is persisted to disk with a unique ID. The button’s custom ID encodes this reference. When you click:
  1. Discord dispatches the interaction to the bot
  2. The bot retrieves and removes the stored prompt
  3. If the button came from a background fork, an interactive fork is created to resume that session
  4. The prompt is sent to the agent, which streams its response
Inquiry prompts are stored in ~/.ollim-bot/state/inquiries.json with a 7-day TTL. Expired entries are cleaned up on read.

​
Fork embeds

Forks produce their own embeds at entry and exit, separate from the embeds the agent sends during conversation.

​
Fork entry

When a fork starts (via /fork, an agent action, or an inquiry button), a purple “Forked Session” embed appears with three buttons:
ButtonStyleAction
Save ContextGreenPromotes fork context to the main session
ReportBlurpleExits the fork and sends a summary to the main session
Exit ForkRedDiscards the fork cleanly

​
Fork exit

When a fork ends, a “Fork Ended” embed is sent with a color indicating the exit strategy:
Exit strategyColor
SaveGreen
ReportBlue
Exit (discard)Grey

​
Persistence

Buttons remain functional across bot restarts:
  • Direct action buttons (task operations, dismiss, fork controls) never expire — their data is encoded in the button itself.
  • Agent inquiry buttons expire after 7 days — the stored prompt is cleaned up after that.

​
Background fork behavior

Embeds sent from the main session or interactive forks are always delivered. In background forks, embeds are subject to additional constraints:
  • Ping budget — each embed consumes one ping from the ping budget. When the budget is exhausted, the embed is blocked and the agent is told to use reporting instead.
  • critical: true — bypasses budget limits and busy checks. Use for things you’d be devastated to miss.
  • allow-ping: false — when set in the background fork config, embeds are disabled entirely. critical: true does not override this.
  • Busy state — when you’re mid-conversation, non-critical embeds from background forks are blocked. The agent reports findings to the main session instead.
Background fork embeds include a “bg” footer to distinguish them from main session messages. Interactive fork embeds show “fork”.

​
Next steps

Forks

Interactive and background fork lifecycle, exit strategies, and idle timeout.

Ping budget

How the ping budget controls background fork notifications.

Discord tools

Full reference for all Discord tools including discord_embed.

Slash commands

Discord slash commands for managing forks, permissions, and more.