ticktickmcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A Python client library for the TickTick API with two implementations:

1. OAuth Client (ticktick_setup.py) - Uses the ticktick-py library with a monkey-patched fix for the deprecated /user/signin endpoint
2. REST API Client (ticktick_rest_api.py) - Direct REST API implementation using OAuth 2.0

Both implementations create a health and marriage tracking system with recurring tasks, milestones, and weekly check-ins.

Development Commands

# Install dependencies
pip install -r requirements.txt

# Add individual tasks (RECOMMENDED for daily use)
python add_task.py "Task title" --content "Description" --priority 5 --due today
python add_task.py "Task title" --project Health --priority 3

# Add task with long description
python add_task.py "Task title" --content "$(cat <<'EOF'
Multi-line description here
With bullet points:
- Item 1
- Item 2
EOF
)"

# Test REST API authentication only
python ticktick_rest_api.py --auth

# Create a test task to verify REST API works
python ticktick_rest_api.py --test

# Run full setup (REST API) - Creates entire Health & Marriage system
python ticktick_rest_api.py --setup

# View status (REST API)
python ticktick_rest_api.py --status

# DEPRECATED - OAuth client (broken, re-authenticates every time)
# python ticktick_setup.py --setup
# python test_ticktick_auth.py

Authentication Architecture

Environment Variables (.env file)

All scripts require credentials in .env:

• TICKTICK_CLIENT_ID - From developer.ticktick.com/manage
• TICKTICK_CLIENT_SECRET - From developer.ticktick.com/manage
• TICKTICK_REDIRECT_URI - Must be http://127.0.0.1:8080
• TICKTICK_USERNAME - TickTick account email
• TICKTICK_PASSWORD - TickTick account password

OAuth Flow Differences

ticktick_setup.py (ticktick-py library):

• Uses ticktick-py library with monkey-patched _login method
• Monkey patch at lines 29-39 fixes the /user/signin → /user/signon endpoint change
• Caches token in .token-oauth file
• OAuth handled by the library's OAuth2 class
• Browser authorization flow managed by library