Skip to content

lifeos-agents: AM Sweep parallel morning agent system

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

Context

The overnight Gmail triage (ADR-0006) solved the inbox problem — actionable emails appear in the daily note before the workday begins. But email is only one input stream. A useful morning system also needs to account for:

  • The day's calendar events, including events from multiple Google accounts and a spouse's shared calendar
  • Tech newsletters that accumulate overnight and should be digested rather than read individually
  • Active Obsidian projects that risk going stale without daily nudges
  • An ongoing personal infrastructure project (Terraform modules) that needs consistent daily progress

Each of these requires different data sources, different APIs, and different Claude prompts. Running them sequentially in a single script would be slow and would couple unrelated concerns. The output also needed to be compact enough to scan in seconds — not a wall of text.

Decision

Build an "AM Sweep" orchestrator (am_sweep.py) in the existing lifeos-agents repo that runs four specialized agents in parallel and writes a single compact ## AM Sweep section to today's daily note.

Architecture

am_sweep.py (orchestrator)
    │
    ├── Pre-auth: get_google_service(ALL_SCOPES) before thread pool starts
    │
    └── ThreadPoolExecutor(max_workers=4)
            │
            ├── calendar_agent.py ──► Google Calendar API (all owned + spouse calendars)
            │                         └──► Claude Haiku: day overview + triage
            │
            ├── newsletter_agent.py ──► Gmail API (LifeOsTechNews label, unread only)
            │                           └──► Claude Haiku: tech digest
            │
            ├── projects_agent.py ──► Obsidian vault (1. Projects/*.README.md)
            │                         └──► Claude Haiku: one nudge per active project
            │
            └── terraform_agent.py ──► GitHub API (oldest open issue)
                                       └──► Claude Haiku: approach summary
                                       └──► Posts daily work note as issue comment

Task triage framework (Green/Yellow/Red/Gray)

Calendar events and implied tasks are classified into four categories by Claude Haiku, shown inline in the daily note with color indicators:

  • 🟢 Green — Claude/AI can handle fully (draft email, prep agenda, create a note, do research)
  • 🟡 Yellow — AI gets 80% done, user finishes (sensitive message draft, partial research needing judgment)
  • 🔴 Red — Needs the user's brain or physical presence (meetings, calls, strategic decisions)
  • ⬜ Gray — Not actionable today

Calendar routing

Google Calendar data comes from multiple sources. Rather than relying on accessRole heuristics (which proved unreliable), calendar IDs are explicitly assigned via environment variables:

  • MY_CALENDAR_IDS — events always triaged as user's own
  • SPOUSE_CALENDAR_IDS — events classified by Claude as HERS (FYI only) or FAMILY (joint, added to user's triage)

This handles secondary Gmail accounts, shared family calendars, and spouse calendars cleanly without guessing.

OAuth scope management

Both Gmail and Calendar are needed. All agents share one token.json via a superset ALL_SCOPES = [gmail.readonly, calendar.readonly]. The orchestrator pre-authenticates with ALL_SCOPES before spinning up the thread pool — this prevents agents from racing each other to write a token with the wrong scopes during initial setup.

Key design choices

ThreadPoolExecutor, not sequential execution. Four agents × ~2-3 seconds each = ~10 seconds sequentially. In parallel, total wall time is ~6 seconds (bounded by the slowest agent). Python's concurrent.futures.ThreadPoolExecutor is sufficient — no async framework needed for this use case.

One failed agent must never kill the others. Each agent catches its own exceptions and returns {status: "error", ...}. The orchestrator has a backstop try/except per future. A failed calendar agent should not prevent the newsletter digest from appearing.

Compact output, detail lives elsewhere. The daily note is a quick-scan artifact, not a reference document. The Terraform agent posts its full daily analysis as a comment on the GitHub issue; only the issue number, title, and one-sentence summary appear in the note. Newsletter bullets are 3-6 lines max. Project nudges are one sentence each.

Unread-only newsletters. The newsletter agent filters is:unread — if the user has already read an email it appears in the label, there's no point re-summarizing it. Date window spans yesterday + today to capture morning arrivals.

Full email body, not snippet. Initial implementation used format=metadata (200-char snippet). Claude correctly identified it had insufficient context to summarize. Changed to format=full with recursive plain-text body extraction (falls back to stripped HTML). Capped at 3,000 chars per newsletter.

Idempotency + --force. The section header ## AM Sweep is checked before running agents. If it exists, the run skips unless --force is passed. This makes the script safe to re-run manually without duplicating content. --force removes the existing section and rewrites it.

Cloud-ready from day one. All config via environment variables (no hardcoded paths beyond the vault default). --output=json flag prints machine-readable results to stdout for future webhook/Railway consumption without writing to the vault.

Output format in daily note

## AM Sweep

*7:15 AM · 🟢 AI handles · 🟡 AI starts, you finish · 🔴 Needs you · ⬜ skip today*

### Today
[2-3 sentence day overview]

- [ ] 🟢 Prep agenda for 3:30 PM call
- [ ] 🔴 3:30 PM meeting with Lucas and Jayson
- [ ] 🔴 6:00 PM soccer evaluations

**Megan:** 11:30 AM Lunch call with Lauren

### Tech News
- bullet from newsletter digest

### Projects
- **project-name:** one-sentence nudge

### Terraform
- [#1](url) Module title — one sentence summary

Trigger

Manual shell script (scripts/am_sweep.sh) for now. Designed for eventual migration to a scheduled cloud job (Railway or Digital Ocean) using the --output=json interface.

Alternatives Considered

Option Why Rejected
Sequential agent execution ~10s vs ~6s; more importantly, couples unrelated agents — one failure blocks all
Async/await with asyncio Overkill; agents are I/O-bound but not high-frequency; ThreadPoolExecutor is simpler and sufficient
Separate cron jobs per agent Would produce multiple note writes; harder to coordinate a single coherent section
Full email body always Token cost; newsletters are the only agent that needs body content; calendar/projects don't
Store triage in Todoist / task manager Tasks would live outside the vault; breaks the single-source-of-truth daily note pattern

Consequences

Positive:

  • Morning setup time drops from ~5 minutes of manual review to a single command and 6-second wait
  • All four information streams (calendar, news, projects, infra) surface in one place without context-switching between apps
  • Each agent is independently testable: --agents calendar --dry-run
  • Cloud migration path is clear; only --output=json and a scheduler needed
  • Terraform agent creates a daily audit trail on GitHub Issues automatically

Negative / Trade-offs:

  • Pre-auth step is an interactive browser flow on first run or after scope changes — cannot be fully automated without a service account
  • Newsletter quality depends entirely on what's in the LifeOsTechNews label; requires ongoing Gmail filter curation
  • Spouse calendar classification (HERS vs FAMILY) is Claude's judgment call — occasionally wrong; no feedback loop yet
  • Project nudges are generated cold each day from README previews; agent has no memory of what was nudged previously, may repeat suggestions

Ongoing obligations:

  • Add new newsletter senders to Gmail LifeOsTechNews filter as discovered
  • Add GitHub Issues to phazeight/trusty_terraform as new Terraform work is identified (agent picks up oldest open issue daily)
  • If daily note template structure changes, verify ## Habit insertion anchor still exists; update shared/vault.py anchor if needed
  • Monitor ~/.am-sweep.log for OAuth or API errors
  • ADR-0006: overnight Gmail triage (predecessor; shared/vault.py and shared/google_auth.py were extracted from gmail_triage.py as part of this work)
  • lifeos-agents repo: phazeight/lifeos-agents (private)
  • Terraform module library: phazeight/trusty_terraform (private)

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