Inbox
The inbox/ directory is where external events arrive as files — broker fills, price alerts, webhook payloads, and system messages. The agent triages them on each run.
The inbox/ directory is the desk's event queue: every fill confirmation, price alert, system message, and inbound webhook lands there as a markdown file, ready for the agent to triage.
What arrives in the inbox
Fills — when a venue confirms that an order was executed, Qoc writes a fill record to inbox/. The record includes venue, symbol, side, quantity, fill price, and timestamp.
Alerts — price-level alerts and risk-guard violations triggered by the Qoc runtime appear as alert files. A pre-trade guard that blocked an order also writes a blocked-order alert here.
Messages — messages forwarded from connected channels (email digests, broker announcements) land in inbox/ so the agent can summarise or act on them.
Webhook events — any payload delivered to the desk's webhook endpoint is written as an inbox item. The agent can then route, filter, or act on the event as defined in the related issue or schedule.
Example fill file
---
kind: fill
status: new
symbol: AAPL
side: buy
quantity: 50
fill_price: 211.43
order_id: ord-2026-07-05-001
venue: alpaca-live
filled_at: 2026-07-05T14:32:07Z
---
## Fill summary
Order **ord-2026-07-05-001** filled: bought 50 shares of AAPL at 211.43
on alpaca-live. Slippage vs. limit: 0.02 USD/share.Inbox item lifecycle
| Status | Meaning | Next transition |
|---|---|---|
new | Item has just arrived; not yet read by the agent. | Agent picks it up → open |
open | Agent has read the item and is acting on it. | Agent finishes → done |
done | Agent has processed the item; no further action needed. | Archived by qoc snapshot or manually |
snoozed | Deferred by the agent or by you until a later run. | Re-queued automatically on next run |
blocked | Item requires human input before the agent can continue. | You update it or open a linked issue |
How the agent triages the inbox
On each scheduled or manual run, the agent scans inbox/ for items with status: new. It reads each item, determines the appropriate action (update an entity, open an issue, log to research, acknowledge and close), performs the action, and updates the item's status.
Fill items are matched to their corresponding order file in orders/executed/ and the entity file for the symbol is updated with the trade note.
Alert items that require immediate attention can trigger a new issue automatically if the related schedule has on_alert: open_issue configured.
Write to the inbox manually
You can drop any markdown file with valid frontmatter into inbox/ and the agent will triage it on the next run. This is useful for forwarding an external note or flagging something for the agent to research without opening a full issue.
Inbox is not a durable message bus
Items in inbox/ are local files. If the desk is offline when a webhook arrives, Qoc buffers the payload and writes it once the desk is back up. Do not rely on sub-second delivery for time-critical signals.
Inspect the inbox
# See all new items
qoc status --inbox
# Print a specific item
cat inbox/2026-07-05-fill-AAPL-BUY-001.md
# Grep for blocked items
grep -rl 'status: blocked' inbox/