Weekly Review Agent

A conversational agent that guides you through a complete GTD (Getting Things Done) weekly review — processing all inboxes to zero, reviewing active projects, clarifying next actions, checking calendars, and planning the coming week. Integrates with major task managers, email, and calendars to pull real data into the review.

Supported Platforms & Integrations

Platform	Setup Method	Auth Type	Notes
Todoist	API token	REST API	Pulls projects, tasks, and inbox items for review
Things 3	AppleScript / JSON	Local	Reads inbox, projects, and areas via Shortcuts
Google Calendar	OAuth2	OAuth2	Reviews past and upcoming week calendar entries
Apple Calendar	CalDAV export	Local	Alternative calendar source for review
Gmail / Outlook	IMAP or OAuth2	App password / OAuth	Checks inbox count and flags unprocessed emails
Notion	Integration token	OAuth2	Syncs weekly review notes to a database

When to Use This Agent

• Use this every Friday afternoon or Sunday evening to prepare for the week ahead
• Use this when your task manager inbox has grown beyond 20 unprocessed items
• Use this when you have a nagging feeling that you are forgetting something important
• Use this when multiple projects are active and you need to ensure nothing is stalled
• Use this when you want the full GTD weekly review but struggle to do it without a guide
• Use this when you realize you have not looked at your project list in over a week
• Consider alternatives when you need daily task planning — use an end-of-day reflection skill
• Consider alternatives when you need project management for a team — this is for personal GTD

Agent Persona

You are a methodical, patient productivity partner. You follow the GTD weekly review checklist step by step, never rushing and never skipping. You ask one question at a time and wait for the user to process before moving on. When you notice a project with no next action, you gently flag it. Your tone is supportive but structured — you keep the review on track without being rigid.

Quick Start

Copy
# ~/.claude/agents/weekly-review-agent.yaml
task_manager: todoist
calendar: google_calendar
email_source: gmail
review_day: friday
review_time: "16:00"
review_steps:
  - collect_inboxes
  - process_inbox
  - review_projects
  - review_next_actions
  - review_waiting_for
  - review_someday_maybe
  - review_calendar
  - plan_next_week
history_file: ~/.weekly-review/history.json

First Run Example

Copy
claude agent weekly-review-agent

Expected Output

Weekly Review — Friday, March 13, 2026
========================================

Let's do your weekly review. This should take about 30 minutes.
We will go through 8 steps. Ready?

STEP 1: COLLECT — Get Inboxes to Zero

Let's check your open loops:
  Todoist Inbox: 12 items unprocessed
  Gmail: 34 unread (8 flagged/starred)
  Physical inbox: Do you have papers or notes to process?
  > Yes, 3 sticky notes from meetings this week

Good. Let's process everything. Starting with Todoist inbox.

Item 1 of 12: "Look into new CI/CD pipeline options"
  Is this actionable?
  > Yes
  What's the next physical action?
  > Research GitHub Actions vs CircleCI — write comparison doc
  Which project does this belong to?
  > DevOps Improvements
  Deadline?
  > Next Friday
  [Moved to DevOps Improvements project with next action and due date]

  ... (processes remaining 11 items) ...

Todoist inbox: 0 items. Clean.

STEP 2: REVIEW ACTIVE PROJECTS

You have 8 active projects. Let's check each one.

  1. Search Feature (3 tasks remaining)
     Next action defined: Yes — "Write integration tests"
     Status: On track

  2. DevOps Improvements (5 tasks)
     Next action defined: Yes — just added the CI/CD research
     Status: On track

  3. Q1 Career Development (2 tasks)
     Next action defined: NO — no clear next step
     What's the next action here?
     > Schedule mock interview with Sarah
     [Added as next action with due date Monday]

  ... (reviews remaining projects) ...

All 8 projects reviewed. 2 had missing next actions — now resolved.

STEP 3-7: ... (continues through all review steps) ...

STEP 8: PLAN NEXT WEEK

Based on your review, here are your commitments for next week:

  Monday:    Mock interview with Sarah, Team standup
  Tuesday:   CI/CD research deep work block, Design review
  Wednesday: Write integration tests, 1:1 with manager
  Thursday:  DevOps presentation prep
  Friday:    Weekly review

  Top 3 priorities for the week:
  1. Complete search feature integration tests
  2. CI/CD pipeline comparison document
  3. Schedule Q2 planning meeting

--- REVIEW COMPLETE ---
Duration: 28 minutes
Inbox items processed: 12
Projects reviewed: 8
Next actions clarified: 4
Waiting-for items checked: 3

Saved to: ~/.weekly-review/2026-03-13.md

Conversation Flow

Start Review
    |
    v
Step 1: Collect all inboxes
    |   (task manager, email, physical, notes)
    v
Step 2: Process inbox items one by one
    |   (actionable? -> next action + project + deadline)
    |   (not actionable? -> trash, reference, or someday/maybe)
    v
Step 3: Review each active project
    |   (has next action? on track? stalled?)
    v
Step 4: Review next actions list
    |   (still relevant? contexts correct?)
    v
Step 5: Review waiting-for items
    |   (follow up needed? overdue?)
    v
Step 6: Review someday/maybe list
    |   (promote anything to active? remove stale items?)
    v
Step 7: Review past and upcoming calendar
    |   (anything need prep? conflicts?)
    v
Step 8: Plan next week
    |   (top 3 priorities, key commitments)
    v
Review Summary + Save

Advanced Configuration

Platform-Specific Setup

Todoist Full Integration

Copy
todoist:
  enabled: true
  api_token: "your-todoist-token"
  inbox_project_id: "inbox"
  review_all_projects: true
  check_overdue: true
  check_no_due_date: true
  waiting_for_label: "waiting-for"
  someday_label: "someday-maybe"

Gmail Inbox Check

Copy
gmail:
  enabled: true
  check_unread_count: true
  check_starred: true
  flag_older_than_days: 3
  categories_to_check:
    - primary
    - updates

Full Options Reference

Parameter	Type	Default	Description
task_manager	string	todoist	Primary task management platform
calendar	string	google_calendar	Calendar source for review
email_source	string	gmail	Email platform for inbox count
review_day	string	friday	Preferred day for weekly review
review_time	string	16:00	Target start time for the review
review_steps	list	all 8	Which GTD review steps to include
history_file	string	~/.weekly-review/history.json	Path for review history
process_inbox_interactively	bool	true	Walk through each inbox item with prompts
project_staleness_days	int	7	Days without activity before flagging a project
waiting_for_followup_days	int	5	Days before suggesting follow-up on waiting items
someday_review_frequency	string	weekly	weekly, biweekly, or monthly
calendar_lookback_days	int	7	Days of past calendar to review
calendar_lookahead_days	int	7	Days of upcoming calendar to preview
max_review_minutes	int	45	Soft time limit with warning

Core Concepts

Concept	Purpose	How It Works
Inbox Zero Processing	Clears mental overhead	Every item in every inbox gets a decision: act, delegate, defer, or delete
Next Action Clarity	Prevents project stalls	Every active project must have a clear, physical next action defined
Waiting-For Tracking	Ensures follow-through	Items delegated or dependent on others are reviewed for timely follow-up
Someday/Maybe Review	Keeps dreams alive without clutter	Non-urgent ideas reviewed periodically to promote or prune
Calendar Alignment	Bridges tasks and time	Past week reviewed for loose ends, next week previewed for preparation needs

Architecture

Review Trigger
    |
    v
+-------------------+
| Data Gatherer     |----> Todoist API, Gmail IMAP, Google Calendar
+-------------------+
    |
    v
+-------------------+
| Inbox Processor   |<----> User (item by item decisions)
+-------------------+
    |
    v
+-------------------+
| Project Reviewer  |<----> User (next action verification)
+-------------------+
    |
    v
+-------------------+
| Calendar Scanner  |----> Past week + upcoming week
+-------------------+
    |
    v
+-------------------+
| Week Planner      |----> Top 3 priorities + daily commitments
+-------------------+
    |
    v
+-------------------+
| Review Logger     |----> ~/.weekly-review/YYYY-MM-DD.md
+-------------------+

Workflow Examples

Scenario 1: Heavy Inbox Week

Input: Todoist inbox has 28 items, Gmail has 52 unread

Conversation:
  Agent: "28 inbox items is above your average of 15. Busy week?"
  Processes each item: 12 become next actions, 6 are reference,
  4 go to someday/maybe, 6 are deleted
  Email triage: 8 require action (moved to task manager),
  44 are read/archived

Output:
  Inbox processing time: 18 minutes
  All inboxes at zero
  12 new next actions distributed across 5 projects
  Pattern noted: Most inbox items came from meetings — consider
  processing action items immediately after each meeting

Scenario 2: Stalled Project Detection

Input: Project "Blog Redesign" has had no activity for 14 days

Conversation:
  Agent: "Blog Redesign has been inactive for 2 weeks. Is this
  still an active project?"
  User: "Yes but I got pulled into other priorities"
  Agent: "What's the single next action to move it forward?"
  User: "Review the designer's mockups and give feedback"
  Agent: "When can you do that?"
  User: "Tuesday afternoon"
  [Task created with Tuesday due date]

Output:
  Stalled project reactivated with clear next action and deadline
  Project moved from stalled to active status

Scenario 3: Overcommitted Week Ahead

Input: Calendar shows 22 hours of meetings next week plus 15 task deadlines

Conversation:
  Agent: "Next week looks overcommitted. 22 meeting hours leaves
  roughly 18 hours for actual work, but you have 15 tasks due.
  Let's prioritize."
  Walks through each deadline, identifies 4 that can be pushed
  and 2 meetings that could be declined or shortened

Output:
  Revised week plan: 11 tasks with realistic deadlines
  4 tasks rescheduled to the following week
  2 meeting decline suggestions drafted
  Deep work blocks protected on Tuesday and Thursday mornings

Best Practices

1. Never skip the weekly review — Even a 15-minute abbreviated review is better than none. If time is short, process inboxes and review active projects only. The weekly review is what keeps the GTD system trustworthy.

2. Process inbox items to zero, no exceptions — Leaving items in the inbox "for later" defeats the entire purpose. Every item gets a decision: actionable or not, project or standalone, now or someday.

3. Define next actions as physical verbs — Instead of "handle the proposal," write "open Google Docs and draft the first three sections of the proposal." Physical, concrete next actions eliminate ambiguity.

4. Check your waiting-for list every week — Items you delegate or depend on others for tend to fall through cracks. The weekly review is when you follow up before things become urgent.

5. Time-box the review — Set a 30-45 minute limit. If you have more than 30 inbox items, process the quick decisions first and schedule a separate session for items requiring thought.

Common Issues

1. Review takes over an hour — You are likely processing inbox items too thoroughly. Make quick decisions during the review and schedule deeper thinking for specific task time during the week.

2. Projects accumulate without completion — If you have more than 10 active projects, some need to move to someday/maybe. Limit active projects to what you can realistically advance this month.

3. Todoist API times out with large task lists — If you have thousands of tasks, use the project_filter parameter to limit the review to active projects only rather than scanning the entire account.

Privacy & Data Handling

All review data is stored locally in ~/.weekly-review/. Task manager and email data is pulled read-only from your own accounts and processed in memory. No task descriptions, project names, or email subjects are stored beyond the local review file. API tokens for Todoist, Gmail, and Google Calendar are stored in your local Claude configuration and never shared. Notion integration writes only to your own workspace. You can delete all review history by removing the ~/.weekly-review/ directory at any time.