Skip to content

lifeos-agents: overnight Gmail triage into LifeOS daily note

  • Date: 2026-03-10
  • Status: Accepted
  • Tags: workflow tooling process

Context

Email is a daily source of tasks, decisions, and follow-ups. Without a systematic triage process, actionable emails get buried in the inbox and require a full manual review each morning to extract what needs doing.

The existing LifeOS daily note is already the morning landing pad — projects, habits, and daily record all live there. The ideal behavior is for email action items to already be waiting in the daily note when the day begins, with no manual sorting required.

Several constraints shaped the design:

  • Triage must run headlessly via cron — no browser or UI interaction after initial setup
  • The daily note is created by the /daily-note skill and follows a fixed structure (## Daily Record, ## Habit, etc.) — any write must slot in without breaking that structure
  • Email classification needs to be cheap enough to run every day indefinitely; full email bodies are unnecessarily expensive to process
  • The solution should not require a third-party task manager or additional subscriptions

Decision

Build a standalone Python project (lifeos-agents, private GitHub repo) that runs as an overnight cron job to triage Gmail into the LifeOS daily note.

Architecture

Gmail API (readonly)
    │
    ▼
gmail_triage.py  ──►  Claude Haiku (subject + snippet only)
    │
    ▼
## Email Actions section
appended to today's daily note
(0. PeriodicNotes/{year}/Daily/{MM}/YYYY-MM-DD.md)

Key design choices

Separate repo (lifeos-agents), not inside ai_tooling_foundations. This repo is documentation and config patterns. lifeos-agents is a runnable Python application with its own virtualenv, OAuth credentials, and .env. Mixing the two would pollute this repo with application concerns.

Claude Haiku, not a rules-based filter. Simple keyword/sender filtering produces too many false negatives (important emails from unknown senders) and false positives (automated emails that happen to use action-oriented language). Haiku classifies from meaning, not syntax, at a cost well under $0.01 per daily run.

Subject + snippet only, not full email body. 200 characters of snippet plus the subject line is sufficient context for classification in the vast majority of cases. Fetching full bodies would increase API cost and token usage with minimal classification benefit.

No due date inference. An early version attempted to infer due dates from email content. This produced hallucinated dates (wrong years, arbitrary deadlines). Removed entirely — priority (high/medium/low) is the only signal extracted beyond the action description.

Write to daily note, not -1. Capture/. Email action items are today-scoped tasks. Writing to Capture would require a second /inbox-process step to file them, adding friction. The daily note is where the day is actually worked — tasks land there directly, under ## Email Actions, inserted before ## Habit.

Gmail OAuth2 with persisted token. Initial authorization requires a one-time browser flow. After that, token.json is stored locally and refreshed automatically — no browser interaction needed for cron execution.

Cron schedule

30 6 * * *  bash ~/.gmail-triage.sh >> ~/.gmail-triage.log 2>&1

Runs at 6:30 AM daily. Log at ~/.gmail-triage.log.

Idempotency

The script checks for an existing ## Email Actions section before writing. If present, it skips. Safe to run manually at any time without duplicating content.

Alternatives Considered

Option Why Rejected
Write to -1. Capture/ inbox Requires manual /inbox-process step; adds friction for today-scoped tasks
Rules-based sender/keyword filter Too brittle; misses novel important senders; false positives on automated emails
GPT-4o / Claude Sonnet for classification Overkill for subject+snippet triage; 10-100x the cost of Haiku with no meaningful accuracy gain
Todoist or other task manager Additional subscription; tasks would live outside LifeOS vault rather than in the daily note
Full email body fetch Higher cost and token usage; snippet is sufficient for classification intent

Consequences

Positive:

  • Email action items appear in the daily note before the workday begins
  • Zero manual triage step in the morning
  • Gmail API readonly scope — the agent can never send, delete, or modify email
  • Cost is negligible: ~$0.001–0.005 per day at Haiku pricing
  • Idempotent and safe to re-run manually

Negative / Trade-offs:

  • No feedback loop yet — the agent cannot learn which classifications were correct or incorrect over time; accuracy depends entirely on Haiku's judgment
  • OAuth token is stored unencrypted at rest in credentials/token.json (gitignored; local only)
  • If the daily note does not exist at 6:30 AM (e.g. /daily-note skill not yet run), the write is skipped silently — requires the note to exist first
  • Gmail categories (Promotions, Social, Updates) are pre-filtered by query; miscategorized emails in those categories will be missed

Ongoing obligations:

  • Monitor ~/.gmail-triage.log for OAuth refresh failures or API quota errors
  • If Google Cloud project credentials change, re-download credentials.json and re-run the OAuth browser flow to regenerate token.json
  • When the daily note template structure changes, verify the ## Habit insertion anchor still exists

Future work

A scoring system is planned (tracked in lifeos-agents#1): host a lightweight service on Railway with a Postgres database, allow +1/-1 ratings on each flagged email from within the daily note, and average scores per sender/pattern over time to weight future triage results. This avoids a binary skip list and allows gradual signal accumulation.


ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.