# Agentic Todoist

Give your agent a real task backend.

Agentic Todoist is a reusable skill for connecting an AI agent to Todoist through the official API, then letting that agent help capture, organize, review, and administer your task system without forcing you to manually design your day every morning.

Instead of building yet another task app, this skill turns Todoist into the operational memory layer your agent can actually maintain.

## Why This Exists

Most people do not need more task lists. They need a task system that can keep up with them.

Todoist is already excellent at holding tasks, projects, sections, labels, reminders, and due dates. The missing layer is an agent that can help decide what belongs where, what matters today, what should wait, and what should be safely tucked away for later.

This skill gives that agent full API-backed access to Todoist, with guardrails for destructive actions and a preference document that teaches the agent how you like your system to work.

## What It Does

- captures tasks quickly through natural language
- reads and updates Todoist projects, sections, labels, reminders, filters, and tasks
- supports full administrative control through the official Todoist API
- uses a preferences document so each user can define their own workflow
- uses a governance document to help the agent decide what should happen today, what can wait, and when to ask before changing things
- keeps dangerous changes visible by requiring review before deletes, mass edits, or broad completions
- supports both Codex and OpenClaw runtime variants

## The Core Idea

You keep Todoist as the source of truth.

Your agent gets the ability to operate it.

Your preferences file tells the agent how you want Todoist used.

Your governance document helps the agent make daily planning decisions without turning your task system into a giant hand-sorted dashboard.

That means you can still create custom Todoist views, boards, and sections when you want them, but the agent can handle the routine sorting, prioritizing, capture cleanup, and daily review work.

## Preferences, Not Hardcoded Defaults

This skill is intentionally not personal to one user.

On setup, the agent should ask where your Todoist preferences file should live. That file can describe things like:

- which projects are active
- what sections mean in your workflow
- how small the Today list should stay
- what belongs in backlog versus someday
- when the agent should move tasks for you
- when the agent should pause and ask first

The public skill stays reusable. Your private preferences stay local.

## Governance For Daily Decisions

The goal is not just API access. The goal is better decisions.

A governance document can define how the agent should help decide:

- what should be done today
- what should move to tomorrow or later
- what is truly overdue
- what should be captured but not shown on the Today page
- which changes are safe to make automatically
- which changes need user approval

This is especially useful for people who get overwhelmed by large task inventories but still want to capture everything.

## Runtime Variants

- `variants/codex/`
- `variants/openclaw/`

Each variant contains runtime-specific instructions and the same core Todoist API helper.

## Authentication

The skill uses Todoist's official API.

Set one of these environment variables, or point `TODOIST_ENV_FILE` at a local secrets file:

- `TODOIST_API_TOKEN`
- `TODOIST_API_KEY`
- `TODOIST_TOKEN`
- `TODOIST_ACCESS_TOKEN`

Do not commit real tokens to this repository.

## Public Repo Boundary

This repository is intentionally kept clean:

- no private preference files
- no private planning notes
- no personal file paths
- no real Todoist tokens
- no local journal data

Bring your own preferences file. The skill provides the API control layer and the decision framework.