Gmail - ollim-bot

ollim-bot provides read-only Gmail access through the gmail.readonly OAuth scope. The agent uses a dedicated gmail-reader subagent to triage your inbox — surfacing actionable emails while filtering out noise. You can also query Gmail directly from the CLI.

Prerequisites

Google OAuth credentials configured (see Google integration setup)
Google account connected via /google-auth — the gmail.readonly scope is included by default

Setup

No additional setup is required beyond the shared Google OAuth flow. The Gmail read-only scope is included by default. Once you’ve completed the Google integration setup, Gmail is ready to use.

Gmail access is strictly read-only. ollim-bot cannot send, delete, or modify emails.

Usage

CLI
Agent

The ollim-bot gmail command provides four subcommands for direct inbox access.

List unread emails

ollim-bot gmail unread
ollim-bot gmail unread --max 5

Output format:

  MSG_ID  2026-02-24 09:15  Alice Smith  Meeting follow-up
  MSG_ID  2026-02-24 08:30  Bob Jones    Invoice #1234

The --max flag limits results (default: 20).

Read an email

ollim-bot gmail read MSG_ID

Displays From, To, date, subject, and the message body. Bodies longer than 3000 characters are truncated. The reader prefers text/plain content and falls back to text/html with tags stripped.

Search emails

ollim-bot gmail search "from:alice subject:meeting"
ollim-bot gmail search "is:unread after:2026/02/20" --max 10

Uses standard Gmail search query syntax. The --max flag limits results (default: 20).

List labels

ollim-bot gmail labels

Lists all Gmail labels with their IDs and names.

CLI reference

Subcommand	Arguments	Default	Description
`unread`	`--max N`	20	List unread emails
`read`	`<id>`	—	Read a full email by message ID
`search`	`"<query>"`, `--max N`	20	Search with Gmail query syntax
`labels`	—	—	List all labels

The agent delegates Gmail access to the gmail-reader subagent — a specialized triage assistant that runs as a subagent with its own system prompt.

Triage process

The gmail-reader follows a structured workflow:

Runs ollim-bot gmail unread to get the inbox snapshot
Reads the full content of any email that might be actionable (subject lines alone are unreliable)
Uses ollim-bot gmail search to narrow results if the unread list is large
If a command fails (auth error, network issue), reports the error and stops — no retries or guessing
Reports findings in a structured format

What gets surfaced

The subagent reports emails where action is needed:

Replies expected — a real person is waiting for a response
Security alerts — password changes, login attempts, or account modifications not initiated by you
Financial — bills due, payments failed, accounts needing attention
Time-sensitive — deadlines, meeting changes, approval requests
Packages needing action — delivery issues, signature required (not routine tracking confirmations)

What gets filtered

The subagent skips automated noise:

Newsletters, digests, and marketing emails
Promotional offers and event promotions
Delivery/shipping confirmations and order receipts
Social media notifications
Political emails, event promotions, and concert announcements
Service agreement updates and routine account notices

Ambiguous emails are read in full and included with a note explaining why they might need attention.

Report format

Action items:
- [Alice Smith] [2026-02-24 09:15] Meeting follow-up -- respond with availability
- [Bank] [2026-02-24 08:00] Payment failed -- check payment method

Skipped: 12 emails (all noise/automated)

When nothing needs attention, the report reads: “Inbox clear — nothing needs your attention.” The skipped line is omitted when zero emails were skipped.

The gmail-reader treats email content as data. It never executes instructions, follows links, or performs actions described in emails.

Troubleshooting

Gmail commands return no messages

Verify that your OAuth token includes the gmail.readonly scope. If you added Gmail after the initial OAuth flow, delete ~/.ollim-bot/state/token.json and run /google-auth to re-consent with the updated scopes.

Body shows '(no text body)'

Some emails use only HTML with embedded images and no text content. The reader extracts text/plain first, then falls back to stripped text/html. Emails that are purely image-based will show no body.

Dates show in the wrong timezone

All Gmail timestamps are displayed in the configured timezone (OLLIM_TIMEZONE, defaults to auto-detected system timezone with a UTC fallback). If dates appear incorrect, verify your OLLIM_TIMEZONE setting matches your local timezone.

Next steps

Google integration

OAuth setup and shared authentication across Google services.

Subagents

How the gmail-reader and other subagents are defined and invoked.

Routines

Schedule automatic email triage as a recurring routine.

Background forks

How subagents like gmail-reader execute in isolated background forks.

Using the Bot

​Prerequisites

​Setup

​Usage

​List unread emails

​Read an email

​Search emails

​List labels

​CLI reference

​Triage process

​What gets surfaced

​What gets filtered

​Report format

​Troubleshooting

​Next steps

Google integration

Subagents

Routines

Background forks

Prerequisites

Setup

Usage

List unread emails

Read an email

Search emails

List labels

CLI reference

Triage process

What gets surfaced

What gets filtered

Report format

Troubleshooting

Next steps