Sales · objections to revisit
Use the prospect audience ID configured in your workspace. Narrow a calls or themes block to passages containing a literal phrase.
{
"audience": "prospect",
"textContains": "too expensive"
}Make room for your way of working
Build pages. Make them yours.
Start with a modFor Oatmeal v0.1.40 or later on macOS · Mod API 2
01 / The essentials
A mod can add real pages to Oatmeal’s sidebar. Each page combines text, metrics, signals, themes, and source notes in a layout you choose. Review investor questions, research findings, operations handoffs, or customer feedback.
Use notes and transcripts from the tools you already work with. The page runs on the recipient’s current Oatmeal workspace. You share its layout and rules; each person supplies their own sources.
Start in the visual builder: select a trusted built-in widget, configure it, then review the page. Mods use Oatmeal’s five built-in blocks. They do not run arbitrary code or add custom CSS, HTML, network connections, or entirely new component types.
02 / Install a mod
With Oatmeal v0.1.40 or later installed on your Mac, double-click a .mod file. macOS launches Oatmeal and opens its review flow. You can also import it from Settings → Mods. If needed, use Finder’s Open With → Oatmeal.
Check the mod’s name, version, pages, filters, and signal rules. Opening a file does not install it. After you choose Install disabled, the mod starts disabled.
Its custom pages appear in the sidebar. Select a page and check its results against source evidence. Disable or remove the mod from Settings → Mods whenever you need.
Legacy .oatmeal-mod.json imports remain supported, including API 1 filtered views and correction suggestions. Custom sidebar pages require API 2. A mod does not bypass Oatmeal’s license requirements.
If a different mod already uses the same ID, review the existing installation before explicitly replacing or removing it. A new file never silently overwrites your setup.
03 / A starting point
A customer listening page for GTM and customer success teams. Bring possible complaints, blockers, and other friction into a focused review, alongside recurring themes and the calls behind them. Start with the customer audience in your workspace and a recent date range; review candidate evidence, open the source call, then decide who should follow up.
The saved customer audience filter narrows the host scope. Signal rules identify escalation, product friction, onboarding, and commercial blockers; the theme and call feeds narrow to those rule matches. Replace the customer audience ID if your workspace uses a different one.
These are heuristic early-warning candidates. A keyword match can miss context, sarcasm, or a resolved issue, and an unmentioned issue will not appear. Severity is a label chosen by the mod author, not a verified risk score. Read the evidence before acting.
Starter version 2.0.1 · Oatmeal 0.1.48+
04 / Another starting point
Prepare a finance or investor meeting follow-up from your own notes and transcripts. Review passages about capital and liquidity, performance and outlook, governance and diligence, and follow-up wording beside the source meetings.
The starter leaves the page audience unrestricted within your current host scope. Its signal feeds separate capital/liquidity and performance/outlook from governance/diligence and follow-ups; the calls feed keeps the wider page scope for context. Narrow account, speaker, or dates with the page controls before reviewing a meeting. Use Edit mod for filters you want to share.
Choose the relevant workspace and dates first. A mention of revenue, runway, or a covenant is a candidate to read, not a verified figure, investment recommendation, commitment, or risk score. Historical, negated, and resolved statements can match. Check figures and timing against the source and current financial records.
Starter version 2.0.1 · Oatmeal 0.1.48+
05 / Build & share
For example: which questions from this week’s investor meetings need a follow-up? Decide the sources and evidence you need before adding widgets.
Choose Create page in Settings → General → Mods. Name the mod and page, then choose Text, Metrics, Signals, Themes, or Calls from Widgets. Select a widget on the canvas to edit its title, content, and filters in the Widget settings inspector.
Drag a widget’s grip before another widget or to the end. Use the grip’s arrow keys or Move earlier / Move later buttons without dragging. Drag the bottom corner to resize: width snaps to Quarter, Third, Half, or Full (3, 4, 6, or 12 columns); height snaps to Compact, Standard, or Tall (160, 280, or 420px). Width/Height selectors and the resize handle’s arrow keys offer the same controls. Widgets pack into rows and stack on narrow screens; long content scrolls inside a sized widget.
Sized widgets require Oatmeal 0.1.48 or later. Older pages keep their widths and natural height until resized.
Expand Page settings for the description, icon, filters, and Add page / Duplicate page controls. Build up to four pages in one mod, with at most 40 blocks per page. Expand Keyword signal rules to add literal keywords and severity labels. Use Edit mod to revise an installed setup, or Advanced: complete mod JSON for precise control.
Preview layout is available in the builder and install review. It uses the page renderer with no workspace data: feeds show empty states and counts show zero. It does not verify rules or financial facts. Choose Review page mod and inspect every page, filter, and keyword rule. Choose Install disabled for a new mod, or Replace and disable for an edit. Enable it separately when ready, test a narrow scope, and open the evidence. Back to editor preserves the reviewed draft.
Choose Export .mod in Settings → Mods and send that file to a teammate. Choose Export JSON to keep an editable copy. Each file is a versioned snapshot: later edits do not update someone else’s installed copy. Increase the version for an update and keep the same mod ID; recipients review replacement explicitly.
X, Escape, and Cancel close an untouched draft immediately. A changed draft asks you to Keep editing or Discard draft, including after returning from review. Closing never installs a mod or changes the installed setup. Drafts last only for the open settings session; they are not saved across reloads.
A .mod is a ZIP archive containing exactly one root file, manifest.json. It is not a JSON file renamed to .mod. Use Oatmeal’s export so the package matches its validator. The importer reads the manifest in memory; a mod does not install files elsewhere on your Mac.
For a separate variation, use a new mod ID. Recipients may need to adapt audience and theme IDs to their own workspace before enabling it.
06 / API 2 reference
This JSON example defines a complete sidebar page. The customer audience must exist in your workspace; substitute your configured ID. This sized example requires Oatmeal 0.1.48 or later and is separate from the downloadable starters. Prefer the visual builder for everyday changes; use JSON for precise configuration or assistant-authored drafts.
{
"format": "oatmeal-mod",
"apiVersion": 2,
"id": "customer-follow-up",
"version": "2.0.0",
"name": "Customer follow-up",
"description": "Requests and friction to review with your customer team.",
"signalDefinitions": [
{
"id": "friction",
"label": "Possible friction",
"keywords": [
"blocked",
"workaround",
"frustrating"
],
"match": "any",
"severity": "high"
}
],
"hooks": [
{
"hook": "sidebar.page",
"id": "follow-up",
"label": "Customer follow-up",
"icon": "messages",
"filter": {
"audience": "customer"
},
"rows": [
{
"id": "overview",
"blocks": [
{
"id": "totals",
"type": "metrics",
"title": "In this view",
"span": 12,
"height": "compact",
"items": [
{
"id": "calls",
"label": "Calls",
"measure": "calls"
}
]
}
]
},
{
"id": "friction",
"blocks": [
{
"id": "friction",
"type": "signals",
"title": "Worth a closer look",
"span": 12,
"height": "tall",
"filter": {
"signalIds": [
"friction"
]
},
"limit": 12,
"sort": "severity"
}
]
},
{
"id": "requests",
"blocks": [
{
"id": "request-calls",
"type": "calls",
"title": "Calls with requests",
"filter": {
"requestsOnly": true
},
"span": 12,
"height": "standard",
"limit": 10,
"sort": "recent"
}
]
}
]
}
]
}| Field | What it does |
|---|---|
format / apiVersion | Use "oatmeal-mod" and the number 2. |
id / version | Stable mod ID; version with three numeric parts, such as 1.0.0 (up to three digits per part). |
name / description | A short name and plain-language description of what the mod does. |
signalDefinitions | Optional array of local keyword definitions; defaults to empty. See Signal definitions. |
hooks | Array of 1–20 hooks. API 2 adds sidebar.page; existing view.filters and classification.proposed hooks remain supported. |
| Field | What it does |
|---|---|
hook / id / label | Use "sidebar.page", a unique hook ID, and the name shown in the sidebar. |
icon | layout, messages, activity, flag, or chart. Defaults to layout. |
description / filter | Optional page description and query. The query narrows the host’s current scope. |
rows | 1–12 rows, each with an id and 1–4 blocks. Up to 40 blocks per page; up to four pages per mod. |
blocks[].span | An integer from 1–12, default 12. Each row uses a 12-column grid; spans in a row must total at most 12. The visual editor offers Quarter (3), Third (4), Half (6), and Full (12); all spans 1–12 remain valid. On small screens, blocks stack in manifest order. |
blocks[].height | Optional compact (160px), standard (280px), or tall (420px). Omit for natural height. Requires Oatmeal 0.1.48 or later; older apps reject this field safely. |
blocks[].id / title / filter | Every block needs an ID and type. A title and additional query are optional. |
The example uses three Full-width widgets in separate rows. Use two Half-width widgets (6 + 6 columns) to make a paired row. Set spans explicitly; two default spans of 12 will not fit in one row.
| Field | What it does |
|---|---|
text | text: plain text, 1–4,000 characters. Use it for context or review instructions. HTML is escaped. |
metrics | items: 1–8 metrics, each with id, label, measure, and optional filter. Measures: calls, accounts, evidence, requests, signals. |
signals | Keyword-matched evidence. sort: severity (default) or recent. |
themes | Recurring themes in matching evidence. sort: evidence (default) or calls. |
calls | Conversations represented in matching evidence. sort: recent (default) or signals. |
limit | For signals, themes, and calls: 1–100 items, default 20. |
IDs start with a lowercase letter and contain lowercase letters, digits, or hyphens, up to 64 characters. Hook and signal IDs must be unique in the mod; row, block, and metric IDs must be unique in their page. Labels are 1–160 characters; descriptions are at most 500.
API 2 JSON is limited to 64 KiB; API 1 keeps its 16 KiB limit. A .mod archive is limited to 96 KiB, with at most 64 KiB of inflated manifest content. Unknown fields, invalid references, duplicate IDs, and overfull rows fail validation. Archives cannot include extra files, nested paths, links, encryption, or ZIP64 content.
07 / Filters & evidence
Filters apply in order: current host workspace and filters → page → block → metric. Every level intersects the previous one using AND. A mod cannot widen the active workspace, dates, or speaker exclusions. Different values for the same field can produce an empty result.
An enabled page also has live controls for visible-text search, account, speaker, dates, keyword rule, and severity. Account and speaker match exact names, ignoring case and extra spacing. These controls narrow the current view; they do not edit the saved mod or its exported file. Clear page filters resets only these page controls, so host exclusions and saved page rules still apply. An invalid date range shows no results until corrected.
| Field | What it does |
|---|---|
audience | A configured audience ID. "all" adds no restriction. |
conversationKind | all, one-on-one, group, or unknown. all adds no restriction. |
participant | Participant label, up to 160 characters; requires conversationKind: "one-on-one". |
requestsOnly | true keeps request evidence; false adds no restriction and does not undo an existing requests filter. |
from / to | Dates in YYYY-MM-DD format. The start must not follow the end. They narrow the host’s date range. |
textContains | A literal text phrase, 1–160 characters, matched against visible evidence. |
account / speaker | Exact account or speaker name, up to 160 characters. Names are normalized for case, Unicode, and whitespace. A speaker filter selects that speaker’s visible passages; it cannot restore an excluded speaker. |
themeIds / signalIds | 1–20 IDs. Theme IDs must exist in Oatmeal; signal IDs must refer to definitions in this mod. |
severities | One or more of low, medium, high, critical; narrows matched signal evidence. |
Values inside one ID or severity array combine with OR. Different query fields combine with AND. Empty or duplicate-filled arrays are invalid. A block’s list limit changes how much it displays, not a neighboring metric’s count.
{
"page": {
"audience": "customer"
},
"block": {
"from": "2026-10-01",
"to": "2026-10-31"
},
"metric": {
"requestsOnly": true
}
}This illustrates three filter objects, not a complete manifest. If the host is set to a shorter date range, the shorter range still wins.
evidence counts visible evidence items; requests counts those marked as requests; calls counts represented conversations. accounts counts distinct, nonempty normalized account names, so missing names are not an extra account. signals counts definition/evidence matches: one passage can match several definitions.
Calls, themes, and signal matches derive from the remaining visible evidence. Follow evidence links back to the original passage or call before deciding on a follow-up. Excluded speakers do not reappear through keyword matching, and the mod does not scan hidden full transcripts to fill a gap. No matches means no matching visible evidence, not proof that no customer has an issue.
08 / Signal definitions
{
"id": "friction",
"label": "Possible friction",
"keywords": [
"blocked",
"workaround",
"frustrating"
],
"match": "any",
"severity": "high"
}Each definition needs an id, label, 1–32 literal keywords (1–80 characters each), and a severity of low, medium, high, or critical. Keywords must be unique after normalization. An optional description explains the rule. A mod can define up to 20 signals.
match: "any" (the default) needs one keyword or phrase in an evidence item. match: "all" needs every keyword in that same item. Matching normalizes Unicode and letter case and respects word or phrase boundaries. Keywords are not regular expressions.
One definition produces at most one hit per evidence item, even when several of its keywords match. A second definition can match that item too. Severity comes directly from the author’s rule; it is not inferred from the customer’s sentiment, account value, or likelihood to churn.
09 / More ways to use mods
Start with one of these query fragments as a page, block, or metric filter. Audience IDs below are examples; replace them with your configured IDs. Define any referenced signals first.
Use the prospect audience ID configured in your workspace. Narrow a calls or themes block to passages containing a literal phrase.
{
"audience": "prospect",
"textContains": "too expensive"
}Combine customer requests with an onboarding phrase. Pair a calls block with a requests metric to plan follow-ups.
{
"audience": "customer",
"requestsOnly": true,
"textContains": "onboarding"
}Create a local integration-friction signal definition first, with phrases such as “manual entry” and “duplicate records”. These are review candidates, not clinical judgments.
{
"signalIds": [
"integration-friction"
],
"severities": [
"high",
"critical"
]
}A vertical-specific page changes how existing evidence is arranged and selected. It does not add a CRM connection, clinical inference, a new classifier, or automatic outreach.
11 / Limits & privacy
Exported packages contain configuration. Oatmeal does not automatically bundle your conversation corpus, transcripts, cached evidence, or stored credential contents. Recipients supply their own workspace and sources; sharing a mod does not give anyone access to yours.
Export includes everything you type into the manifest. Text blocks, labels, descriptions, and keywords can contain customer data or credentials if you paste them there. Configuration is readable: review all text before sharing.
Existing Oatmeal features, such as connected AI chat or optional classification, keep their own data flows and license boundaries. A mod does not change those settings. Read data and privacy details for those separate features.
Build your first page