@reneza/ats-adapter-ticktick

Turn your TickTick into your agent's context layer. Reference adapter for Agentic Task System — wraps TickTick's OpenAPI v1 (plus optional local qdrant + nomic-embed via Ollama) into the ATS adapter contract so agents can find / read / link / update tasks and notes via a single CLI surface.

Why this exists

TickTick has thousands of your durable notes plus an excellent mobile capture flow. What it's missing is an agent-native retrieval layer tuned for how agents query (not how humans type). This adapter adds:

• Wiki layer — designate a project (default: "Permanent Notes") as your knowledge base. find / get / url / links operate on it.
• Hybrid retrieval — pure TickTick semantic search misses short note titles; this adapter exposes the dense vector path so @reneza/ats-core's parallel fan-out can fuse it with keyword + title-fuzzy. Result on a 5-question agent bench: 60% top-1 / 80% recall@5, vs 20% / 40% for dense alone.
• Agent-data notes — fenced ```json blocks inside notes, extracted via --extract json for cron / agent consumption. Single source of truth, mobile-editable, no schema migration.

Install

npm install -g @reneza/ats-cli @reneza/ats-adapter-ticktick
ats config use ticktick
ats auth login          # prints TickTick OAuth URL + exchange command
ats find "deployment runbook"

For semantic / hybrid retrieval, also run a local qdrant + Ollama with nomic-embed-text:

docker run -d --name qdrant -p 6333:6333 qdrant/qdrant:latest
docker run -d --name ollama -p 11434:11434 ollama/ollama:latest
docker exec ollama ollama pull nomic-embed-text
ats sync vector

Nomic retrieval prefixes are opt-in because stored documents and queries must be migrated together. Build a separate collection and metadata manifest before enabling them:

ATS_TICKTICK_VECTOR_COLLECTION=ticktick_tasks_nomic_prefixed \
ATS_TICKTICK_VECTOR_META="$HOME/.local/share/ats/vector-index-meta-nomic-prefixed.json" \
ATS_TICKTICK_NOMIC_PREFIXES=1 \
ats sync vector --full

Use the same three variables for subsequent search commands. Do not enable only the query prefix against an existing unprefixed collection.

What this adapter implements

All six required methods of the ATS adapter contract:

• listProjects() — TickTick projects via Open API v1
• listTasksInProject(projectId) — active tasks in a project
• getTask(projectId, taskId) — full task body
• createTask(input) — POST /open/v1/task
• updateTask(projectId, taskId, patch) — POST /open/v1/task/{id}
• urlFor({projectId, taskId}) — https://ticktick.com/webapp/#p/<proj>/tasks/<task> deep links

Plus auth lifecycle (authStatus / authLogin / authExchange for OAuth) and the optional searchByQuery (TickTick's substring-only native search).

Adapter ships with the wiki helpers (notes.find/get/url/links), capture-time relevance enrichment (--relevance), and the Qdrant + Ollama integration through its rich task extension. Its contract-level optional method is searchByQuery; the local-cache adapter additionally exposes bulkFetch.

Repo + docs

• Repo: https://github.com/renezander030/agentic-task-system
• Wiki conventions: https://github.com/renezander030/agentic-task-system/blob/main/docs/wiki-conventions.md
• Adapter interface: https://github.com/renezander030/agentic-task-system/blob/main/docs/adapter-interface.md

License

MIT