dida365-agent

<h1 align="center">dida365-agent</h1>

<p align="center"> <strong>Let AI agents manage your Dida365 / TickTick — CLI · Skill · MCP</strong> </p>

<p align="center"> <a href="https://pypi.org/project/dida365-agent/"><img src="https://img.shields.io/pypi/v/dida365-agent" alt="PyPI"></a> <a href="https://pypi.org/project/dida365-agent/"><img src="https://img.shields.io/pypi/dm/dida365-agent" alt="Downloads"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="License"></a> <img src="https://img.shields.io/badge/python-3.12+-blue?logo=python&logoColor=white" alt="Python 3.12+"> </p>

<p align="center"> English | <a href="README_zh.md">中文</a> </p>

Let AI agents manage Dida365 / TickTick tasks, projects, tags, and habits through natural language. Three form factors: a lightweight CLI, a ready-to-install Agent Skill, and a standard MCP Server.

No install required — run it directly with uvx. Supports both Dida365 (China) and TickTick (International), switchable with one env var.

---

Features

<table> <tr><td><b>Full task management</b></td><td>Create, update, complete, delete, and move tasks with priority, tags, dates, reminders, recurrence, and checklist items — plus batch operations.</td></tr> <tr><td><b>Projects & queries</b></td><td>CRUD projects (list / kanban / timeline views), filter by project, date, priority, tag, and status, and review completed tasks.</td></tr> <tr><td><b>V2 advanced power</b></td><td>Server-side full-text search, tag management, habit check-ins, project folders, parent/child tasks, task pinning — capabilities the official Open API doesn't cover.</td></tr> <tr><td><b>Three form factors</b></td><td>CLI (run-and-exit, saves resources and context), Agent Skill (one-command install with built-in methodology), MCP Server (long-running, tool calls).</td></tr> <tr><td><b>Dual platform</b></td><td>Switch between Dida365 (China) and TickTick (International) with <code>DIDA365_REGION</code>.</td></tr> <tr><td><b>Agent-friendly</b></td><td>Structured JSON to stdout by default, errors to stderr with non-zero exit codes — easy for agents to parse and orchestrate.</td></tr> </table>

---

Quick Start

Option 1: Use the CLI directly

No install needed — run with uvx (requires uv). First prepare credentials per the configuration guide and write them to .env:

# Browser OAuth (saves token, ~180 days)
uvx dida365-agent dida auth login

# List all projects
uvx dida365-agent dida project list

# Create a high-priority task due tomorrow
uvx dida365-agent dida task create --title "Review PR" --project <projectId> \
  --priority 5 --due-date "2026-05-30T18:00:00+0800"

# Full-text search (V2)
uvx dida365-agent dida search "meeting"

After installing locally (uv tool install dida365-agent), use the shorter dida command.

Option 2: Use as an Agent Skill

Install the Skill in any Skill-compatible AI tool (Claude Code, Cursor, etc.) and drive it with natural language:

# Install the Skill
npx skills add linhai0872/dida365-agent

Then just describe what you need in the AI chat:

Tidy up my unfinished tasks for today, list the high-priority ones, and move the overdue ones to the "Later" project

The Skill recognizes intent, fills in missing details, and assembles dida commands automatically — no manual parameters required.

Option 3: As an MCP Server

Exposes 44 tools as a standard MCP Server for Claude Code, Cursor, Windsurf, etc. See MCP Server integration.

---

Documentation

Doc	Contents
CLI Reference	All commands, parameters, conventions
Configuration	Credentials, enabling V2, env vars, token lifecycle
MCP Server	Local / source / Docker deployment, AI tool config

---

Development

uv sync                              # Install dependencies
uv run python -m pytest tests/       # Run tests
uv run ruff check src/ tests/        # Lint
uv run dida --help                   # Run the CLI locally

License

MIT

Acknowledgments

• Dida365 / TickTick Open API
• FastMCP · Typer · Model Context Protocol