gtasks-todo-manager

Overview

This skill enables Claude Code agents to manage to-do items across multiple Google accounts through the Google Tasks API. It provides comprehensive task management including creating, updating, completing, and organizing tasks, as well as managing task lists and aggregating views across accounts.

The skill uses a BYOC (Bring Your Own Credentials) model where users provide their own Google Cloud OAuth credentials, ensuring security and privacy.

CLI Location

The CLI is located in the scripts subdirectory of this skill's base directory. When this skill is loaded, you receive a "Base directory for this skill" path. The CLI path is:

{base_directory}/scripts/cli.js

All CLI commands in this skill's documentation assume you are running them from the scripts directory or using the full path.

Before Any Operation

IMPORTANT: Before performing any operation with this skill, you MUST complete the following checks in order:

1. Verify Authentication

Always verify authentication first:

node scripts/cli.js auth validate

If this command fails, proceed to the Setup operation.

2. Check for Config Migrations

After authentication succeeds, check if the config needs migration:

cat ~/.config/gtasks-todo-manager/config.json | jq -r '.schemaVersion // "unversioned"'

Current schema version: 0.3.2

If the result is unversioned or an older version, proceed to the Migrations operation before continuing with the requested operation.

Operations

For common natural-language workflows, read the matching workflow reference first:

User Intent	Workflow Reference
Set up OAuth credentials and authenticate accounts	Setup Workflow
Add a task	Add Task Workflow
Complete a task	Complete Task Workflow
List or filter tasks	List Tasks Workflow
Suggest tasks for today	Today Workflow
List, create, rename, or delete task lists	Task Lists Workflow
Show cross-account summary statistics	Summary Workflow
Initialize a project task list	Project Init Workflow
Show project task-list association	Project Status Workflow

Use these workflow references to interpret request details, then use the operation references below for the concrete CLI/API behavior.

User Intent	Operation Reference
Migrate config schema after skill update	Migrations
Set up OAuth, add/remove accounts, fix auth issues	Setup
Create, update, complete, delete, or move tasks	Tasks
Create, rename, delete, or list task lists	Task Lists
View tasks across accounts, get summary statistics	Aggregation
Get prioritized task suggestions for today	Suggestions
Associate task lists with git projects, manage project associations	Projects

IMPORTANT: You MUST read the appropriate operation reference before executing any operation. Do not improvise instructions.

Supported Capabilities

Category	Operations
Authentication	OAuth setup, credential validation, token refresh
Account Management	Add, remove, list accounts; set default; check status
Task Lists	List, create, rename, delete task lists
Tasks	List, create, update, complete, delete, move, reparent tasks
Subtasks	Create, reparent, view hierarchy, move with subtasks
Cross-Account	Aggregate views, filter by account, summary statistics
Task Suggestions	Prioritized task suggestions for daily focus
Projects	Associate task lists with git repos, cross-workstation sync

Reference Documentation

• Google Tasks API Reference - SDK reference and code examples
• Config Schema - Configuration file structure
• Task Schema - Task and TaskList data structures