Google Tasks Client - GTD Task Manager

A Ruby-based Google Tasks client implementing Getting Things Done (GTD) methodology with comprehensive task management features, interactive mode, and automated workflows.

🚀 Features

Full GTD Implementation - Complete Getting Things Done workflow with grooming, review, and planning
Daily Time-Blocking - Agenda feature schedules today's tasks in 30-minute focused work slots
Interactive Mode - Context-aware shell for efficient task management
Smart Scheduling - Quick date selection (today, tomorrow, next week)
Task Classification - Priority and department-based organization
Search & Filter - Find tasks across all content
OAuth Authentication - Secure Google account integration
Automatic Pagination - Handles thousands of tasks seamlessly

📋 Setup

1. Install Dependencies

bundle install

2. Google OAuth Setup

Go to Google Cloud Console
Create/select project and enable Google Tasks API
Create OAuth client ID credentials (Desktop application)
Add http://localhost:9090/oauth2callback as redirect URI
Download JSON file as oauth_credentials.json in project root

3. Authentication

# First-time login (opens browser)
./bin/tasker login

# All subsequent commands use stored tokens automatically
./bin/tasker lists

🎯 Getting Things Done (GTD) Workflow

Grooming Command - Complete GTD Workflow

The grooming command is the centerpiece of the GTD implementation, automatically organizing your task backlog.

What it does:

Finds tasks needing attention - All uncompleted tasks that are overdue or have no due date
Review Phase - Forces classification of unreviewed tasks with priority/department
Planning Phase - Schedules all tasks with quick date selection

Interactive Mode:

./bin/tasker interactive
> use "My Tasks"
> grooming

Console Mode:

./bin/tasker grooming LIST_ID

Example Grooming Session:

🧹 Starting GTD Grooming Workflow
List: ⭐️ CEO Tasks
============================================================

📋 Gathering tasks for grooming...
Found 8 tasks needing grooming:
  1. Prepare quarterly report (No due date)
  2. Call client about project (Overdue)
  3. Review team feedback (No due date)
  ...

📝 REVIEW PHASE: 3 tasks need review first
----------------------------------------

🔍 Reviewing task 1 of 3:
Title: Prepare quarterly report
Notes: (empty)

Select Priority:
  1. 🔥 Hot - Urgent/critical tasks
  2. 🟢 Must - Important/required tasks  
  3. 🟠 Nice - Nice to have/optional tasks
  4. 🔴 NotNow - Deferred/not current priority

Enter priority number (1-4): 2

Select Department:
  1. 🧩 Product - Product development tasks
  2. 📈 Business - Business operations/strategy
  3. 📢 Marketing - Marketing and promotion
  4. 🔒 Security - Security/compliance tasks
  5. 👩‍💼 Others - General/administrative tasks
  6. None - Skip department classification

Enter department number (1-6): 2

✅ Review completed for: Prepare quarterly report

📅 PLANNING PHASE: Scheduling 8 tasks
----------------------------------------

📋 Planning task 1 of 8:
Title: Prepare quarterly report
Classification: 🟢Must 📈Business
Current due date: (none)

Select when to schedule this task:
  1. Today
  2. Tomorrow
  3. Next Monday
  4. Next Tuesday
  5. Next Wednesday
  6. Next Thursday
  7. Next Friday
  8. Remove current date
  9. Skip this task

Enter your choice (1-9): 5
✅ Scheduled for: Wednesday, August 27, 2025 at 09:00

🎉 GTD Grooming completed!
All 8 tasks have been processed.

Agenda Command - Daily Time-Blocking

The agenda command transforms your daily task list into a focused work schedule using time-blocking methodology.

What it does:

Finds today's tasks - All uncompleted tasks with due date = today
Priority sorting - Orders by priority: 🔥Hot → 🟢Must → 🟠Nice → 🔴NotNow → Unclassified
30-minute time slots - Creates focused work blocks starting from current time (rounded to next 30-min)
Interactive scheduling - Confirm each time slot or skip tasks
Daily agenda summary - Final schedule for focused execution

Interactive Mode:

./bin/tasker interactive
> use "My Tasks"
> agenda

Console Mode:

./bin/tasker agenda LIST_ID

Example Agenda Session:

📅 Starting Daily Agenda Time-Blocking
List: 💼 Work Tasks
============================================================

📋 Gathering today's tasks...
Found 4 tasks for today:
  1. ○ Review quarterly report
  2. 🔥Hot Prepare client presentation  
  3. 🟢Must Schedule team meeting
  4. 🟠Nice Update project documentation

📊 Tasks ordered by priority:
  1. 🔥Hot Prepare client presentation
  2. 🟢Must Schedule team meeting
  3. ○ Review quarterly report
  4. 🟠Nice Update project documentation

⏰ Scheduling tasks in 30-minute time blocks starting from 14:30
------------------------------------------------------------

📋 Time Slot 1: 14:30-15:00
Task: 🔥Hot Prepare client presentation
Classification: 🔥Hot 📈Business
Schedule this task for 14:30-15:00? (y/n/s=skip): y
✅ Scheduled: Prepare client presentation
   Time: 14:30-15:00

📋 Time Slot 2: 15:00-15:30  
Task: 🟢Must Schedule team meeting
Schedule this task for 15:00-15:30? (y/n/s=skip): y
✅ Scheduled: Schedule team meeting
   Time: 15:00-15:30

============================================================
📅 TODAY'S AGENDA SUMMARY
============================================================
14:30-15:00 | 🔥Hot Prepare client presentation
15:00-15:30 | 🟢Must Schedule team meeting
16:00-16:30 | ○ Review quarterly report

🎯 Ready for focused work! 3 tasks scheduled.
💡 Tip: Use 30-minute focused work sessions with 5-minute breaks between tasks.

💻 Interactive Mode

Launch interactive mode for the best task management experience:

./bin/tasker interactive

Global Commands

Command	Description	Example
`help`	Show available commands	`help`
`lists`	List all task lists	`lists`
`use <list_name/number>`	Switch to list context	`use "My Tasks"` or `use 1`
`exit-list`	Exit current list context	`exit-list`
`exit` / `quit`	Exit interactive mode	`exit`

List Context Commands

Available when you've selected a list with use

Command	Description	Example
`tasks [--completed] [--limit N]`	Show tasks in current list	`tasks --limit 10`
`create <title>`	Create new task	`create "Review documentation"`
`complete <task_id/number>`	Mark task completed	`complete 1`
`delete <task_id/number>`	Delete task	`delete 2`
`show <task_id/number>`	Show full task details	`show 1`
`edit <task_id/number>`	Edit task (title, notes, due date)	`edit 3`
`search <text>`	Search uncompleted tasks	`search "report"`
`plan <task_id/number>`	Quick schedule task	`plan 1`
`review <task_id/number>`	Classify task priority/department	`review 2`
`agenda`	Time-blocking - schedule today's tasks in 30-min slots	`agenda`
`grooming`	GTD workflow - review & schedule tasks	`grooming`

Interactive Examples

Basic Task Management:

> lists
Available task lists:
  1. 📋 Personal Tasks
  2. 💼 Work Projects  
  3. 🛒 Shopping List

> use 2
Switched to list context: 💼 Work Projects

[💼 Work Projects] > tasks
Tasks in 💼 Work Projects: (12 total)
  1. ○ Finish project proposal
  2. ○ Schedule team meeting
  3. ✓ Update documentation

[💼 Work Projects] > create "Prepare presentation slides"
Created task: Prepare presentation slides (ID: abc123)

[💼 Work Projects] > plan 4
Planning task: Prepare presentation slides
Current due date: (none)

Select when to schedule this task:
  1. Today
  2. Tomorrow
  3. Next Monday
...
Enter your choice (1-9): 7
Task scheduled for: Friday, August 29, 2025 at 09:00

Task Review & Classification:

[💼 Work Projects] > review 1
Reviewing task: Finish project proposal

Select Priority:
  1. 🔥 Hot - Urgent/critical tasks
  2. 🟢 Must - Important/required tasks
...
Enter priority number (1-4): 1

Select Department:
  1. 🧩 Product - Product development
  2. 📈 Business - Business operations
...
Enter department number (1-6): 1

Task classification updated:
Priority: 🔥Hot
Department: 🧩Product
Task updated successfully!

Search and Edit:

[💼 Work Projects] > search "presentation"
Searching for tasks containing: "presentation"
List: 💼 Work Projects

Found 2 matching tasks:
1. Prepare presentation slides
   ID: abc123
2. Review presentation feedback
   ID: def456

[💼 Work Projects] > edit 1
Editing task: Prepare presentation slides

Current values:
  Title: Prepare presentation slides
  Notes: (none)
  Due: 2025-08-29 09:00
  Status: needsAction

Title [Prepare presentation slides]: Prepare Q3 presentation slides
Notes [(none)]: Include budget analysis and team metrics
Due date (YYYY-MM-DD HH:MM or 'clear') [2025-08-29 09:00]: 

Task updated successfully!

🖥️ Console Commands

All commands support --credentials path/to/file.json for custom OAuth files.

Basic Operations

# Authentication
./bin/tasker login              # First-time OAuth login
./bin/tasker logout            # Clear stored tokens

# Task Lists
./bin/tasker lists             # List all task lists
./bin/tasker lists --limit 5   # Show first 5 lists
./bin/tasker create-list "New List"  # Create task list
./bin/tasker delete-list LIST_ID     # Delete task list

# Tasks
./bin/tasker tasks LIST_ID                    # Show all tasks
./bin/tasker tasks LIST_ID --completed        # Include completed
./bin/tasker tasks LIST_ID --limit 20         # Limit results

# Task Management
./bin/tasker create-task LIST_ID "Task title"
./bin/tasker create-task LIST_ID "Task title" --notes "Details" --due "2025-01-15"
./bin/tasker complete-task LIST_ID TASK_ID
./bin/tasker update-task LIST_ID TASK_ID --title "New title" --notes "Updated"
./bin/tasker delete-task LIST_ID TASK_ID

# GTD Workflow
./bin/tasker agenda LIST_ID      # Time-block today's tasks in 30-minute slots
./bin/tasker grooming LIST_ID    # Complete GTD grooming workflow
./bin/tasker interactive         # Launch interactive mode

🏗️ Ruby API

require_relative 'lib/google_tasks_client'

# Initialize
client = GoogleTasksClient.new
# or: client = GoogleTasksClient.new('custom_credentials.json')

# Task Lists
task_lists = client.list_task_lists
new_list = client.create_task_list('My List')
client.delete_task_list(list_id)

# Tasks
tasks = client.list_tasks(list_id)
tasks_with_completed = client.list_tasks(list_id, show_completed: true)

# Task Operations
task = client.create_task(list_id, 'Title', notes: 'Notes', due: '2025-01-15T10:00:00.000Z')
client.update_task(list_id, task_id, title: 'New Title', notes: 'Updated')
client.complete_task(list_id, task_id)
client.delete_task(list_id, task_id)

# Get specific task
task = client.get_task(list_id, task_id)

🎨 Task Classification System

Priority Levels

🔥 Hot - Urgent/critical tasks requiring immediate attention
🟢 Must - Important/required tasks that must be completed
🟠 Nice - Nice to have/optional tasks when time permits
🔴 NotNow - Deferred tasks not currently prioritized

Department Categories

🧩 Product - Product development and feature work
📈 Business - Business operations, strategy, and growth
📢 Marketing - Marketing, promotion, and outreach
🔒 Security - Security, compliance, and risk management
👩‍💼 Others - General administrative and miscellaneous tasks

⚡ Quick Planning Options

When using plan or during grooming, choose from:

Today - Schedule for today at 9:00 AM
Tomorrow - Schedule for tomorrow at 9:00 AM
Next Monday-Friday - Schedule for next occurrence at 9:00 AM
Remove current date - Clear existing due date
Skip - Leave unchanged (grooming only)

Smart weekday logic: If it's already the target weekday after 9 AM, schedules for the following week.

🗂️ Files Structure

tasker/
├── oauth_credentials.json    # Google OAuth credentials (you provide)
├── token.yaml               # Stored access tokens (auto-created)
├── CLAUDE.md                # Development instructions
├── lib/
│   ├── google_tasks_client.rb   # Google Tasks API wrapper
│   └── interactive_mode.rb      # Interactive shell & GTD workflows
└── bin/
    └── tasker               # Main CLI executable

🔍 Debug Mode

Enable detailed logging for troubleshooting:

DEBUG=1 ./bin/tasker interactive
DEBUG=1 ./bin/tasker grooming LIST_ID

📦 Dependencies

google-apis-tasks_v1 - Google Tasks API client
googleauth - Google OAuth 2.0 authentication
thor - CLI framework for console commands
launchy - Browser automation for OAuth flow

🎯 GTD Methodology

This application implements core Getting Things Done principles:

Capture - Quickly create tasks with create command
Clarify - Use review to classify tasks with priority/department
Organize - grooming workflow systematically processes backlogs
Reflect - search and filtered tasks views for regular review
Engage - plan command for quick scheduling and execution

The grooming workflow ensures no task falls through the cracks by forcing review of unclassified items and scheduling of all overdue/unscheduled tasks in a single session.

Happy Task Management! 🎉

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
bin		bin
lib		lib
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
README.md		README.md
oauth_credentials.json.example		oauth_credentials.json.example
pod_to_job.yaml		pod_to_job.yaml
test_auth.rb		test_auth.rb
test_input.rb		test_input.rb
test_interactive.rb		test_interactive.rb
test_review.rb		test_review.rb
test_review_direct.rb		test_review_direct.rb

glassity/tasker

Folders and files

Latest commit

History

Repository files navigation

Google Tasks Client - GTD Task Manager

🚀 Features

📋 Setup

1. Install Dependencies

2. Google OAuth Setup

3. Authentication

🎯 Getting Things Done (GTD) Workflow

Grooming Command - Complete GTD Workflow

Interactive Mode:

Console Mode:

Example Grooming Session:

Agenda Command - Daily Time-Blocking

Interactive Mode:

Console Mode:

Example Agenda Session:

💻 Interactive Mode

Global Commands

List Context Commands

Interactive Examples

Basic Task Management:

Task Review & Classification:

Search and Edit:

🖥️ Console Commands

Basic Operations

🏗️ Ruby API

🎨 Task Classification System

Priority Levels

Department Categories

⚡ Quick Planning Options

🗂️ Files Structure

🔍 Debug Mode

📦 Dependencies

🎯 GTD Methodology

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages