todopi.
GitHub

THE AGENT TASK LEDGER

Your agent’s work,
still here tomorrow.

A task ledger for AI coding agents. Plain Markdown in your repo, ready for the next session or agent.

Install todopiSee how it works
The first session writes the task to .todopi/tasks/; the next session reads it and continues.

THE WORKFLOW 01 — 04

Give the task.
Keep the thread.

You describe the work. Your agent uses todopi to leave a trail the next session can actually follow.

  1. 01

    Describe the work

    Tell your coding agent what needs doing, in your own words.

  2. 02

    The agent records it

    It creates and claims a task in your repository, with criteria and dependencies when needed.

  3. 03

    Progress stays in a file

    Notes and task state live in plain Markdown. If a task has a verify command, done runs it before closing.

  4. 04

    Another session picks it up

    todopi prime gives the next agent a starting point, even after context is lost.

A file, not a memory.

Here’s a small example from a local todopi 0.2.0 run. The ID and dates belong to that example, not to your project.

AGENT ACTIVITY
# Agent creates a task with a check
$ todopi add "Fix export crash" \
    --ac "Export handles an empty trip" \
    --verify "npm test"

# Finds ready work and claims it
$ todopi ls --ready
tp-54p4m0  ready   Fix export crash
$ todopi claim tp-54p4m0

# Saves progress for the next session
$ todopi note tp-54p4m0 \
    "Found a missing empty-state check."

# Next session reads the task ledger
$ todopi prime
.todopi/tasks/tp-54p4m0.md EXCERPT
---
id: "tp-54p4m0"
title: "Fix export crash"
status: "in_progress"
verify: "npm test"
---

## Acceptance Criteria

- [ ] Export handles an empty trip

Excerpt from an example task; the file also records its assignee, timestamps and log. Agents write through the CLI; you can inspect the Markdown with your editor or Git.

Connect your agent.

Install todopi, then connect your agent in a repository.

01 INSTALL
curl -fsSL https://todopi.com/install.sh | sh

Already have Node.js 20+? npm install --global todopi

02 IN YOUR REPO
todopi init --setup claude

Use codex, opencode, pi, cursor, or gemini instead of claude for another agent. Review and trust new hooks when your agent asks. Commit the files setup creates.

The useful parts, in your repo.

Plain Markdown

One task per file under .todopi/. Read it with the tools you already use.

Know what’s ready

Tasks can depend on other tasks. todopi ls --ready shows what can be picked up now.

Verification when set

Set a verify command on a task and done runs it. An override requires a recorded reason.

A few practical answers.

Do I have to manage tasks myself?

No. Tell your agent what you want done. It creates, claims, updates, and closes tasks with the todopi CLI; you can review the ledger at any time.

Does todopi upload my repository data?

todopi itself makes no network requests and sends no telemetry. A task’s optional, user-configured verify command runs according to its own behavior and may use the network. The first time todopi runs verification in a repository, you must trust that repository.

What happens when I switch agents?

Connect each agent you use to the same repository. They read the same task files. todopi prime shows the current work and where to find the rest.