lifeos-agents: AM Sweep parallel morning agent system¶
- Date: 2026-03-10
- Status: Accepted
- Tags:
workflowtoolingprocessagents
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 ownSPOUSE_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=jsonand 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
LifeOsTechNewslabel; 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
LifeOsTechNewsfilter as discovered - Add GitHub Issues to
phazeight/trusty_terraformas new Terraform work is identified (agent picks up oldest open issue daily) - If daily note template structure changes, verify
## Habitinsertion anchor still exists; updateshared/vault.pyanchor if needed - Monitor
~/.am-sweep.logfor OAuth or API errors
Related¶
- ADR-0006: overnight Gmail triage (predecessor;
shared/vault.pyandshared/google_auth.pywere extracted fromgmail_triage.pyas part of this work) lifeos-agentsrepo: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.