Cadence

There are thousands of todo CLIs. Cadence is the one built for an AI agent to run as a first-class user, not a bolted-on chat wrapper on top of a human tool — and it turns git, which you already have installed, into the undo/history/audit/sync layer instead of building a bespoke (and weaker) version of all four.

What that buys you, concretely:

Hand your agent a messy brain-dump and get tracked subtasks back. cadence decompose 12 --into "book flights" "book hotel" "pack" (or the decompose_task MCP tool) turns one vague task into real, independently completable children — no more one giant to-do that never gets checked off.
Ask "why did this get bumped to top priority" and get a real answer. Every reprioritise, schedule, and edit is a git commit under the hood, so the answer is git log/git blame on your own task store, not a guess or a feature nobody built.
Undo a bad agent action instantly, with the same guarantee git gives your code. cadence undo reverts the last change — yours or your agent's — because it is a git revert, not a bespoke undo stack that only covers some operations.
Keep two devices' task lists in sync without running a server. cadence sync pulls and pushes against a git remote you already control (a repo, a USB stick, anything git can reach) — no account, no hosted backend, no uptime to worry about.

The plan is to publish Cadence as a public, installable, open-source project by 6 November 2026. That date is a delivery commitment, not an estimate.

Status

Published on PyPI as cadence-todo — install with pip install cadence-todo. It builds, runs, and is tested from a fresh clone, and CI is green on a clean GitHub-hosted runner (see the finish-line checklist below for what's still outstanding). See docs/bakeoff.md for the five candidate concepts we researched, the evidence behind each, and which one we chose and why, and docs/human-surface.md for the CLI's binding design spec.

Install

pip install cadence-todo

Every line below is a real CLI command, run yourself, no agent required — this is the whole bet: every change to your list, yours or an agent's, comes with a legible reason and a clean undo, because it's backed by the same git you already trust for code, not a bespoke history feature Cadence invented and might get wrong. Real output, cadence-todo 0.2.9, NO_COLOR=1:

$ cadence add "Plan Mara's 30th birthday party"
Added #1: Plan Mara's 30th birthday party

$ cadence decompose 1 --into "Book a venue" "Order a cake" "Send invites"
Decomposed #1 into 3 subtasks: #2, #3, #4

$ cadence reprioritise 2 high --reason "venue books up fastest"
Reprioritised #2 (none → high): Book a venue

$ cadence why 2
#2 Book a venue — history (newest first):

  -  high     just now     Reprioritised (none → high)
                       "venue books up fastest" — you, via CLI

  -  none     just now     Created as subtask of #1 (Plan Mara's 30th birthday
                           party)

No reason was recorded for this change. Reasons are optional —
pass --reason "..." (CLI) or a `reason` argument (MCP tool call)
to leave one next time.

$ cadence undo
Undid: Reprioritised #2 (none → high) undone: Book a venue

That why line is the payoff: a straight answer to "why did this change," without you ever opening git, a hidden folder, or asking your agent to explain itself. cadence list and cadence done <id> work exactly the way you'd expect from any todo CLI — full command reference below.

By default tasks live in ~/.cadence/cadence.db (a local SQLite file) with a git-backed history alongside it. Set CADENCE_DB_PATH to point at a scratch file instead (used by the test suite and useful for an agent that wants an isolated store).

Start the MCP server (agent surface) over stdio, exposing tools such as add_task, list_tasks, complete_task, schedule_task, decompose_task, reprioritise_task, undo, and sync_tasks with structured JSON returns:

cadence mcp

Building from source

git clone https://github.com/dominicplouffe/Cadence.git
cd Cadence
pip install -e .
pip install pytest
pytest -q

What "agentic-first" means here

Primary interface is agent-legible by design. An agent that has never read the docs should be able to work out what each tool does, what it returns, and what it did wrong, from the interface itself.
A human surface is not optional. A capability that exists only for agents is half-built, and so is one that exists only for humans.
Local-first bias. We prefer something a person installs with a single command and owns the data of, over a hosted multi-tenant web app.

The finish line

Three things must be true and independently checkable by someone outside this company, on or before the committed date:

Published on a public package registry, installable with one command.
CI on a clean GitHub-hosted runner goes green on the full suite, including an end-to-end test that installs the published artifact and drives it.
A committed transcript exists of an agent with no access to this repository completing a fixed ten-step script using only the published package.

Contributing

Not yet open for external contributions — the project is pre-publication. Once published, this section will describe how to build from a fresh clone, run the test suite, and submit changes.

License

MIT — see LICENSE.

Metadata

Release files for cadence-todo 0.2.11

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cadence-todo 0.2.11
File	Size	Uploaded	Provenance
cadence_todo-0.2.11.tar.gz	66.2 kB	Aug 30, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for cadence-todo 0.2.11
File	Interpreter	ABI	Platform	Reset
cadence_todo-0.2.11-py3-none-any.whl 46.7 kB Aug 30, 2026 Without provenance	Python 3	none	any	Details

Total release size: 112.9 kB

Release files / cadence_todo-0.2.11.tar.gz

Download URL	cadence_todo-0.2.11.tar.gz
Size	66.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`75f2589477d985fb3bca3483a031061ad637b63d9663dfd7485d943de43f9d50`
BLAKE2b-256 checksum How to use checksums	`69ca37821a9c5a76699f1c3c9b3db3cbef571953a319aa221b1c67b9c0d737a3`
Upload date	Aug 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / cadence_todo-0.2.11-py3-none-any.whl

Download URL	cadence_todo-0.2.11-py3-none-any.whl
Size	46.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8cfd0df31dd027d8a5f091bfa7134a8f2a2c8b00ab6d86a912875f721c7efb40`
BLAKE2b-256 checksum How to use checksums	`9e340c9d5b378989fe062dc11e8bb474b2f902061aae37ee8102ef77de6ac00c`
Upload date	Aug 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Security for cadence-todo 0.2.11

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.