My GTD Buddy

A Reminders-native Getting Things Done (GTD) workflow powered by Claude Code. This project implements a streamlined GTD system using Apple Reminders with an intelligent AI skill to orchestrate workflow management.

Table of Contents

• Overview
• Key Features
• Technology Stack
• System Architecture
• GTD Workflow
• Project Structure
• Requirements
• Important Warning
• Setup Guide
• How to Use
• Daily Workflow
• Customization
• Privacy Note

Overview

This is my personal implementation of David Allen's GTD methodology, designed around Apple Reminders with an intelligent Claude Code skill to orchestrate workflows. While I use Apple Reminders, you can adapt this system to work with any todo list app by modifying the shell scripts.

The system focuses on:

• Instant capture — Everything goes to Reminders Inbox first
• Daily planning — Inbox to zero with interactive processing
• Focused execution — Context-aware task selection with energy matching
• Continuous review — AI-driven micro-reviews with project health checks
• Proactive surfacing — AI surfaces relevant info using historical patterns
• Undo support — Safely undo moves and completions

See It In Action: Check out A Day with My GTD System.md — a complete walkthrough from morning to night showing how the system handles real interruptions, context switching, and maintains focus. Also see SCENARIOS.md for recipes for common situations like "Post-Vacation Reset" or "5-Minute Gap".

Key Features

• Apple Reminders native — Uses standard Reminders lists (Inbox, Next Actions, Waiting For, Someday, Projects)
• Calendar integration — macOS Calendar for appointment + task coordination
• Context tags — Location (@home, @office) and energy (#high, #low, #quick) in notes
• Historical patterns — Tracks velocity, peak days, context usage for smarter suggestions
• Project health — Detects orphan projects without next actions
• Waiting nudges — Shows waiting items with age, prompts for follow-ups
• Undo support — Undo last move/complete actions
• Natural language dates — "tomorrow 2pm", "next friday", "Jan 15"
• Batch operations — Declare bankruptcy on stale items
• Terse communication — "Captured: [item]" not "I've successfully added..."

Technology Stack

• Claude Code — AI-powered CLI with Skills support
• Apple Reminders — Native macOS/iOS reminders app
• macOS Calendar — Native calendar app
• yq — YAML processor for robust state management
• AppleScript — Shell scripts wrapping osascript for Reminders/Calendar access

System Architecture

graph TB
    subgraph "Claude Code Skill"
        SKILL[GTD Skill<br/>Workflow Orchestrator]
        PROCESS[Process Mode<br/>Inbox Processing]
        COACH[Coach Mode<br/>Context-Aware Selection]
        REVIEW[Review Mode<br/>Weekly + Project Health]
        HEALTH[Health Mode<br/>System Recovery]

        SKILL --> PROCESS
        SKILL --> COACH
        SKILL --> REVIEW
        SKILL --> HEALTH
    end

    subgraph "Scripts Layer"
        RSCRIPT[reminders.sh<br/>AppleScript Wrapper]
        CSCRIPT[calendar.sh<br/>AppleScript Wrapper]
        SSCRIPT[state.sh<br/>Trend Tracking]
    end

    subgraph "Apple Reminders"
        INBOX[Inbox]
        NEXT[Next Actions]
        WAITING[Waiting For]
        SOMEDAY[Someday]
        PROJECTS[Projects]
    end

    subgraph "macOS Calendar"
        EVENTS[Events]
        FREE[Free Time]
    end

    subgraph "State"
        TRENDS[Weekly Trends]
        PATTERNS[Day Patterns]
        VELOCITY[Processing Velocity]
    end

    SKILL --> RSCRIPT
    SKILL --> CSCRIPT
    SKILL --> SSCRIPT
    RSCRIPT --> INBOX
    RSCRIPT --> NEXT
    RSCRIPT --> WAITING
    RSCRIPT --> SOMEDAY
    RSCRIPT --> PROJECTS
    CSCRIPT --> EVENTS
    CSCRIPT --> FREE
    SSCRIPT --> TRENDS
    SSCRIPT --> PATTERNS
    SSCRIPT --> VELOCITY

GTD Workflow

Workflow Phases

graph LR
    CAPTURE[CAPTURE<br/>Instant<br/>→ Inbox]
    PROCESS[PROCESS<br/>10 min<br/>Inbox → 0]
    COACH[COACH<br/>All Day<br/>Energy-Aware]
    REVIEW[REVIEW<br/>Weekly<br/>5 Parts]

    CAPTURE --> PROCESS
    PROCESS --> COACH
    COACH --> REVIEW
    REVIEW --> CAPTURE

    classDef capture fill:#e1f5fe
    classDef process fill:#f3e5f5
    classDef coach fill:#e8f5e8
    classDef review fill:#fff3e0

    class CAPTURE capture
    class PROCESS process
    class COACH coach
    class REVIEW review

Reminders List Flow

flowchart TD
    START[Idea/Task] --> INBOX[INBOX]
    INBOX --> DECISION{Processing}

    DECISION -->|"y now"| NEXT_FLAG[NEXT ACTIONS<br/>Flagged for today]
    DECISION -->|"y later"| NEXT[NEXT ACTIONS<br/>Ready when needed]
    DECISION -->|"someday"| SOMEDAY[SOMEDAY<br/>Future consideration]
    DECISION -->|"delete"| DELETE[Deleted]

    NEXT_FLAG --> EXECUTE[EXECUTE]
    NEXT --> CONTEXT[Context Filter]
    SOMEDAY --> REVIEW_CYCLE[Weekly Review]

    REVIEW_CYCLE --> NEXT
    CONTEXT --> EXECUTE

Project Structure

.claude/
└── skills/
    └── gtd/
        ├── SKILL.md              # Main orchestrator + routing
        ├── state.yaml            # Trends, patterns, preferences
        ├── modes/
        │   ├── process.md        # Interactive inbox processing
        │   ├── coach.md          # Context + energy-aware selection
        │   ├── review.md         # 5-part weekly review
        │   └── health.md         # System health + recovery
        ├── scripts/
        │   ├── reminders.sh      # Apple Reminders AppleScript wrapper
        │   ├── calendar.sh       # macOS Calendar AppleScript wrapper
        │   └── state.sh          # Trend and pattern tracking (uses yq)
        └── reference/
            └── tools.md          # Complete CLI reference

A Day with My GTD System.md       # Real workflow example
SCENARIOS.md                      # Common scenarios and recipes

Requirements

• macOS — Required for AppleScript integration
• Apple Reminders — Pre-installed on macOS
• macOS Calendar — Pre-installed on macOS
• Claude Code — AI-powered CLI
• yq — Portable command-line YAML processor (brew install yq)

Important Warning

AI systems can make mistakes! This system has direct access to your Reminders and Calendar data. The AI may:

• Accidentally delete or modify reminders
• Move items to wrong lists
• Create duplicate entries
• Mess up calendar events

Recommendations:

• Test with non-critical data first
• Start slowly — Begin with read-only commands
• Use undo — ./scripts/reminders.sh undo reverses last move/complete
• Review AI actions — Always verify, especially for important tasks

Setup Guide

1. Install Prerequisites

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Install yq
brew install yq

2. Clone This Repository

git clone https://github.com/realYushi/my-gtd-buddy.git
cd my-gtd-buddy

3. Set Up GTD Lists in Reminders

Open Apple Reminders and create these lists:

• Inbox — Capture bucket
• Next Actions — Actionable tasks
• Waiting For — Delegated/waiting items
• Someday — Maybe later
• Projects — Multi-step outcomes

Or run the setup script:

./scripts/reminders.sh setup

4. Make Scripts Executable

chmod +x .claude/skills/gtd/scripts/*.sh

5. Verify Setup

cd /path/to/my-gtd-buddy
claude

# Test Reminders connection
> /gtd
# Should show inbox count and health status

# Test specific commands
> process inbox
# Should start interactive inbox processing

Troubleshooting:

• If Reminders access fails: Grant Terminal/Claude access in System Settings → Privacy & Security → Automation
• If Calendar access fails: Grant access in System Settings → Privacy & Security → Calendars
• If state.sh fails: Ensure yq is installed (brew install yq)

How to Use

Natural Language Commands

The GTD skill automatically routes based on intent:

# Processing (→ Process mode)
process inbox
clear inbox
/gtd

# Coaching (→ Coach mode)
what should I do
I'm stuck
help me prioritize
feeling tired

# Review (→ Review mode)
weekly review
how am I doing
review

# Recovery (→ Health mode)
system is a mess
need to reset
cleanup

Proactive AI Behavior

The skill surfaces information using your historical patterns:

• Peak days: "Tuesday is usually a strong day for you"
• Velocity: "You usually process 12 items per session"
• Context: "You do a lot @home — filter those?"
• Trends: "Completions down lately. Overwhelmed?"
• Orphan projects: "3 projects need a next action"
• Stale waiting: "'Email from John' waiting 10 days. Nudge?"

Context-Aware Filtering

# By energy
feeling tired → suggests #low energy tasks
high energy → suggests deep work, creative tasks

# By location
I'm at home → filters for @home tasks

# By time available
I have 15 minutes → suggests #quick tasks

Daily Workflow

Morning (10 minutes)

1. "process inbox" — Interactive inbox processing
2. Answer: "Actionable? When?" → "y later" / "n delete" / "someday"
3. Result: Inbox to zero, Next Actions ready

Throughout Day

1. "what should I do" — Energy + context-aware suggestions
2. "I'm stuck on [task]" — Get unstuck with breakdown
3. Capture interruptions — Added to inbox, process later

Weekly Review (10 minutes)

5 parts:

1. Wins — Celebrate completed items
2. Stuck — Triage stale items (7+ days)
3. Projects — Ensure each has a next action
4. Waiting — Check waiting items, sen