MHoroszowski/ticktick-agent-skill

O que ticktick-agent-skill faz?

Skill de agente host-agnóstico para TickTick — CLI em Bun/TS (bin/ticktick) + SKILL.md + Workflows/ para qualquer ecossistema de agente de IA (PAI, Claude Code, MCP customizado). Encapsula ticktick-client (biblioteca da API v2 não oficial). Suporte a duas contas (--account live|test). Tarefas, projetos, tags, subtarefas aninhadas, lembretes com tempo e geofencing, seções, operações em lote.

---

Visão Geral

Este skill permite que agentes de IA interajam programaticamente com o TickTick por meio de uma CLI robusta e scripts de automação. Ele foi projetado para ser independente de plataforma, funcionando com qualquer agente que suporte a execução de scripts (como Claude Code, Cursor, Codex, etc.).

Funcionalidades

• Gerenciamento de Tarefas: Criar, listar, atualizar e concluir tarefas.
• Projetos e Seções: Organizar tarefas em projetos e seções.
• Tags e Subtarefas: Adicionar tags e criar subtarefas aninhadas.
• Lembretes: Lembretes baseados em tempo e geofencing.
• Operações em Lote: Realizar ações em massa de forma eficiente.
• Duas Contas: Alternar entre contas de produção (live) e teste (test) usando a flag --account.

Instalação

Certifique-se de ter o Bun instalado (v1.0.0+).

git clone https://github.com/MHoroszowski/ticktick-agent-skill.git
cd ticktick-agent-skill
bun install

Configure as variáveis de ambiente (crie um arquivo .env na raiz do projeto):

TICKTICK_USERNAME_LIVE=seu_email_de_producao
TICKTICK_PASSWORD_LIVE=sua_senha_de_producao
TICKTICK_USERNAME_TEST=seu_email_de_teste
TICKTICK_PASSWORD_TEST=sua_senha_de_teste

Uso da CLI

A ferramenta principal é o script bin/ticktick. Exemplos de uso:

Comandos Básicos

# Criar uma nova tarefa
bin/ticktick task create "Comprar mantimentos" --project "Casa" --tags "urgente"

# Listar todas as tarefas de um projeto
bin/ticktick task list --project "Trabalho"

# Marcar tarefa como concluída
bin/ticktick task complete <task-id>

Usando Conta de Teste

bin/ticktick --account test task create "Tarefa de teste"

Lembretes com Geofencing

bin/ticktick task create "Ir ao mercado" --reminder-time "10:00 AM" --geofence-lat -23.5505 --geofence-lng -46.6333 --geofence-radius 100

Uso com Agentes de IA

Para Claude Code

Coloque o conteúdo deste SKILL.md no arquivo de skills do seu projeto (.claude/skills/claude-code/SKILL.md).

Para Cursor

Adicione o skill através das configurações de skills do Cursor.

Para Uso Genérico (MCP ou Scripts)

Invoque o script bin/ticktick diretamente a partir do seu agente ou script de automação.

Estrutura do Projeto

ticktick-agent-skill/
├── bin/
│   └── ticktick          # CLI principal
├── src/
│   ├── client/           # Wrapper da API ticktick-client
│   ├── commands/         # Implementação dos comandos
│   └── utils/            # Utilitários (config, helpers)
├── workflows/            # Scripts de workflow para agentes
├── SKILL.md              # Documentação do skill
├── package.json
└── tsconfig.json

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou pull requests no repositório GitHub.

Licença

MIT