Sync Your AI Agent's Progress to Todoist So You Always Know What It's Doing

I’ve been running long-lived AI agent tasks in the background for months now. Research pipelines. Code scaffolding jobs. Multi-step automations that touch six different tools before they’re done. And for the longest time, checking on their progress meant scrolling through a wall of chat history, trying to figure out if the agent was still moving or quietly stuck three steps back.

It’s a terrible experience. You’re supposed to be offloading cognitive load — and instead you’ve traded email anxiety for agent anxiety.

So I started testing something. What if the agent logged its own progress, in real time, to a tool you’re already checking every day? What if instead of digging through chat, you opened Todoist and saw exactly what your agent was doing — which steps it finished, what it planned to do next, and whether it got stuck? There’s a reason this works better than it sounds, and I’ll explain the non-obvious part after I walk you through the setup.

Why Long-Running AI Agent Tasks Go Dark

Most AI agents are built for conversation. You ask, they answer. The whole interaction fits in one screen. But when you give an agent a genuinely complex job — build me a full-stack app skeleton, do a deep competitive analysis, run through my entire inbox and triage it — something breaks down.

The agent is working. You just can’t see it.

According to the OpenClaw use case documentation this setup is based on: users running complex, multi-step tasks frequently lose track of completed steps and current agent state. Checking chat logs manually is described as “tedious for background tasks” — and that’s being generous. It’s also error-prone. You might miss a failure. You might not realize the agent is waiting on something. You might interrupt a task that was 80% done because you assumed it had stopped.

The problem isn’t the agent. It’s the visibility layer — or the lack of one. And most people assume fixing this requires some elaborate integration, a custom dashboard, or a third-party plugin. It doesn’t. That’s what I want to show you.

If you’re evaluating what a truly capable AI agent platform can do, visibility into long-running tasks is one of the first things that separates real agents from glorified chatbots.

What Good Agent Visibility Actually Looks Like

Before jumping to implementation, it’s worth being clear about what you’re trying to get. A good visibility system for an AI agent has four distinct jobs:

• State visualization — At any moment, you can see whether a task is in progress, waiting on something, or complete. Not buried in a log. Visible at a glance.

Beacon says: your AI shouldn’t work in the dark — a little light on its progress makes all the difference.

• Externalized reasoning — The agent’s plan is written down somewhere you can read it. Not just “I’m working on it” — the full sequence of intended steps, captured before execution starts.
• Streaming progress — As the agent completes sub-steps, those completions appear in real time. You’re not waiting for a final report; you’re watching the work happen.
• Stall detection — If the agent gets stuck or stops responding, something catches it and notifies you. Not five hours later. Soon.

This is the four-capability framework documented in the OpenClaw Todoist use case. It maps cleanly onto what Todoist already does well: sections for state, task descriptions for plans, comments for logs, and a heartbeat script for stall detection.

The sections look like this in practice:

• 🟡 In Progress — agent is actively working
• 🟠 Waiting — agent is blocked or waiting for input
• 🟢 Done — task is complete

Clean. No new tools to learn. No new dashboard to open. Just Todoist, which you’re probably already checking.

The Part Nobody Expects: Your Agent Builds Its Own Visibility System

Here’s the thing I promised to explain. The counterintuitive part of this setup.

You don’t install anything. You don’t write the scripts yourself. You don’t configure a plugin or find a marketplace integration. You ask the agent to build the visibility system for itself — and it does.

OpenClaw agents can manage their own filesystem and execute shell commands. That means when you give the agent a setup prompt (more on that in a moment), it creates the three scripts it needs, drops them into a folder, and starts using them — all without you touching a terminal.

This is what separates a real agentic AI system from a chatbot. A chatbot answers questions. An agent can be told “build a tool that helps you communicate your own progress” and go build it. The meta-capability here — an agent instrumenting itself — is genuinely different from anything you get with a standard AI assistant.

What the agent builds is a minimal three-script integration against the Todoist REST API v2. Nothing fancy. No external dependencies beyond curl, which is already on any modern system. The agent writes the scripts, runs them, and from that point forward logs its own work into your Todoist project automatically.

Setting This Up: Three Scripts and a Prompt

Here’s what the implementation actually looks like. The agent needs to create three scripts, each handling a different part of the Todoist integration.

Step 1: Configure Your Todoist Project

Create a new Todoist project — call it something like “OpenClaw Workspace” or “AI Agent Tasks”. Inside it, create three sections:

• 🟡 In Progress
• 🟠 Waiting
• 🟢 Done

You’ll need three IDs from Todoist: your API token (from your account settings), the project ID, and the section IDs for each of the three sections. You can find all of these in the Todoist web app or by calling the API directly. Keep these handy — you’ll pass them to the agent.

Step 2: What the Three Scripts Do

The agent will create these scripts itself, but it helps to understand what they do:

• todoist_api.sh — A thin wrapper that handles all communication with the Todoist REST API. Every other script calls this one. It takes an endpoint, an HTTP method, and optional JSON data, then fires the request using curl.
• sync_task.sh — Creates or updates a task and routes it to the correct section based on status. Pass it a task title, a status (“In Progress”, “Waiting”, or “Done”), an optional task ID for updates, a description, and labels.
• add_comment.sh — Posts a progress note as a comment on an existing task. The agent calls this after each sub-step completes.

Step 3: The Setup Prompt

Give your OpenClaw agent this prompt, substituting your actual IDs:

I want you to build a Todoist-based task visibility system for your own runs.

First, create three bash scripts in a 'scripts/' folder:
1. todoist_api.sh (a curl wrapper for Todoist REST API)
2. sync_task.sh (to create or update tasks with specific section_ids for
   In Progress, Waiting, and Done)
3. add_comment.sh (to post progress logs as comments)

Use these variables for the setup:
- Token: [Your Todoist API Token]
- Project ID: [Your Project ID]
- Section IDs: [In Progress ID, Waiting ID, Done ID]

Once created, for every complex task I give you:
1. Create a task in 'In Progress' with your full PLAN in the description.
2. For every sub-step completion, call add_comment.sh with a log of what you did.
3. Move the task to 'Done' when finished.

That’s it. The agent creates the scripts, configures them with your IDs, and is immediately ready to start logging its own work. No server to spin up. No deployment pipeline. The agent does the instrumentation.

From that point forward, every time you give the agent a complex task, it will: post its full plan to Todoist before doing anything, add a comment each time it finishes a sub-step, and move the task to Done when it’s complete. You watch the task fill up with comments in real time.

What the Agent Posts (and When)

The sequencing matters here. The agent should write its full plan into the task description before executing any sub-steps. This is by design — it gives you upfront visibility into what it intends to do, so you can catch a bad plan before five minutes of work has happened on it.

Then, as it works through each step, it posts a comment. Step complete → comment. Another step → another comment. By the time the task moves to Done, you have a full audit trail of what happened, in order, with timestamps.

Where This Integration Can Fall Apart

• Todoist API token exposure — The token is stored in plain text inside todoist_api.sh. This is fine for personal use, but you should never commit these scripts to a public repository. Store the token as an environment variable if you’re sharing the setup with others.
• Comment posting requires Todoist Premium — The Todoist comments API works fine for direct REST calls, but if you’re using Zapier to trigger additional workflows off agent comments, Zapier’s Todoist integration only supports comment-based actions for Premium users.
• Zapier triggers are polling-based, not real-time — If you’re building secondary workflows that react to Todoist updates (like sending a Slack message when a task moves to Done), be aware that Zapier polls for Todoist changes rather than receiving instant webhooks. There’s inherent latency, sometimes several minutes.
• The heartbeat script is not included by default — The stall detection component (a script that checks for tasks that haven’t been updated in too long) needs to be added separately. The setup prompt above covers the core three scripts; the heartbeat is an optional fourth piece you’d need to request explicitly.
• Section IDs are environment-specific — If you recreate your Todoist project or rename sections, the section IDs change and the scripts break silently. Tasks will still be created, but they’ll land in the wrong section or fail to route entirely. Keep a note of your IDs somewhere outside the scripts.

How to Know the Sync Is Actually Working

• When you give the agent a new complex task, a Todoist task appears in 🟡 In Progress within a few seconds — before the agent has done any actual work
• The task description contains the agent’s full plan, not just a task title
• As the agent works, new comments appear on the task — each one describing a completed sub-step
• When the job finishes, the task moves from 🟡 In Progress to 🟢 Done automatically
• If you check the task mid-run, the most recent comment reflects something that happened recently — not the same stuck state from an hour ago

If the task appears but has no description, the agent isn’t writing its plan before starting. Go back to the prompt and make step 1 explicit: “Before doing any work, create a Todoist task with your complete plan in the description.”

If comments stop appearing mid-task, check whether the task is in the 🟠 Waiting section — the agent may be blocked waiting for input you haven’t provided.

This kind of transparent, auditable AI automation is part of what I mean when I talk about AI automation that actually earns your trust — not just runs in the background and hopes for the best.

Your Monday Morning Setup Checklist

1. Create a Todoist project named something obvious like “AI Agent Tasks” — takes about 2 minutes
2. Add three sections inside the project: 🟡 In Progress, 🟠 Waiting, 🟢 Done
3. Collect your three IDs: API token (from todoist.com/app/settings/integrations), project ID, and section IDs for each of the three sections — you can get section IDs by calling https://api.todoist.com/rest/v2/sections?project_id=YOUR_ID in your browser with your token
4. Paste the setup prompt (from the Step 3 section above) into your OpenClaw agent with your real IDs substituted in
5. Verify the scripts exist: ask the agent to list the contents of the scripts/ folder — you should see todoist_api.sh, sync_task.sh, and add_comment.sh
6. Run a test task: give the agent something moderately complex (“research the top 5 open-source task managers and write a comparison”) and watch your Todoist project — a task should appear within 10 seconds
7. If you’re a Todoist Premium user, consider adding a fourth request to the agent: build a heartbeat script that checks for tasks stuck in 🟡 In Progress for more than 30 minutes and posts a notification

Budget about 15-20 minutes for the full setup on the first go. After that, the system runs itself.

What This Changes About Working With AI Agents

• Long-running agent tasks no longer require you to babysit a chat window — Todoist becomes your real-time status board
• The agent’s plan is captured in writing before any work begins, which means you can catch bad assumptions early instead of after five minutes of wasted execution
• Each sub-step completion is logged as a timestamped comment, giving you a full audit trail you can review after the fact
• The entire visibility layer is built by the agent itself — no plugins to install, no dashboards to configure, no third-party tools beyond Todoist
• This pattern scales: once the scripts exist, every subsequent complex task the agent runs gets the same visibility automatically

The deeper point here is about trust. One of the real barriers to delegating meaningful work to a personal AI assistant is not knowing what it’s doing with your time and your data. Visibility doesn’t just make the agent easier to monitor — it makes it easier to trust.

I’m still refining this for longer workflows — specifically the stall detection piece. The heartbeat script exists in rough form but I’m not fully satisfied with how it handles edge cases where the agent is working but just slowly. That’s a follow-up worth its own write-up. Check back.

Frequently Asked Questions

Do I need to be a developer to set this up?

Not really. You’ll need to be comfortable copying and pasting a prompt into your AI agent, and you’ll need to collect three IDs from Todoist (your API token, project ID, and section IDs). The agent writes all the actual scripts. If you can follow a step-by-step setup guide, you can do this.

Does this work with any AI agent, or only OpenClaw?

The bash-script approach documented here is designed for OpenClaw agents, which can manage their own filesystem and run shell commands. Other agent platforms with similar capabilities could use the same pattern, but you’d need to verify they support filesystem access and shell execution. If you’re on BrainRoad’s hosted platform, OpenClaw support is built in.

Do I need Todoist Premium for this to work?

The core setup — task creation, status updates, and comment logging via the REST API — works on Todoist free accounts when using direct API calls. The Premium restriction applies specifically to Zapier’s Todoist integration if you’re building secondary automations through Zapier. For the setup described in this article, free accounts are fine.

What happens if my agent gets stuck? Will Todoist tell me?

The base setup described here handles state visibility and progress logging but doesn’t include automated stall detection by default. To get notified when an agent task goes silent, you’d need to add a heartbeat script — a fourth script that monitors how long tasks have been sitting in 🟡 In Progress without a new comment. You can request this from the agent as an additional setup step.

Is there an alternative to the bash script approach?

Yes. Doist (the company behind Todoist) maintains an official TypeScript library called todoist-ai, which reached v7.10.0 in February 2026. It can be used as a way to connect AI to Todoist tools, or imported into your own project. There’s also a hosted endpoint at https://ai.todoist.net/mcp that AI agents can connect to directly. The bash approach is simpler to understand; the TypeScript library is more suitable for production or team environments.

Sources

• OpenClaw Todoist Task Manager Use Case (GitHub)
• Doist/todoist-ai Repository (GitHub)
• Todoist AI MCP Server (Playbooks)
• Todoist REST API v2 Documentation
• Todoist + Zapier Integration
• TARS: Todoist Integration for AI Agents