todoing

Tasks that live in your repo. No servers. No databases. Just git.

---

todoing is a local, file-based task manager built for the AI era. It stores every task as a markdown file with YAML frontmatter — fully git-trackable, editor-friendly, and agent-native. No API keys, no cloud, no lock-in.

If your ideas, plans, and to-dos should live next to your code, todoing is for you.

Why todoing?

	todoing	GitHub Issues	Linear	Notion	Todoist
Stored in-repo	✅	❌	❌	❌	❌
Git-trackable	✅	❌	❌	❌	❌
Offline-first	✅	❌	❌	❌	❌
AI-agent-friendly CLI	✅	❌	❌	❌	❌
Zero setup	✅	❌	❌	❌	❌
Markdown native	✅	❌	❌	❌	❌

Install

uv tool install todoing     # recommended: isolated environment
pipx install todoing        # or via pipx
pip install todoing         # or classic pip

Requires Python 3.11+.

Quickstart

todoing add "Ship the MVP"
todoing add "Write integration tests" -l testing -s in_progress
todoing ls

# (#2) [testing] {🏃} Write integration tests
# (#1) [] {⏳} Ship the MVP

That's it. A .todoing/ directory is created in your repo root. Add it to git. You're done.

How it works

Each task is a markdown file in .todoing/tasks/. A JSON index makes listing and searching instantaneous. Everything is plain text — your editor, grep, and git diff all work natively.

.todoing/
  tasks/
    1.md    # markdown with YAML frontmatter
    2.md
    ...
  index.json    # auto-rebuilt, never committed alone

---
id: 1
title: Ship the MVP
added_at: 2026-05-01T10:00:00
status: in_progress
labels: [p0, feature]
---

Long-form description here. Supports
multi-paragraph markdown body.

Commands

add — Create a task

todoing add "Refactor auth module" -l p1 -l backend -s todo -b "Current approach is brittle."
# (#4) Refactor auth module

ls — List tasks

todoing ls                  # all tasks, newest first
todoing ls -n 5             # latest 5
todoing ls -s in_progress   # filter by status
todoing ls -l p0 -l backend # filter by labels (AND)
todoing ls -q auth          # search by title/body/labels/status
todoing ls -r               # oldest first

see — View a task

todoing see 4               # raw markdown to stdout
todoing see "#4"            # # prefix is optional

status — Change status

todoing status 4 in_progress
todoing status 4 done

Statuses: todo ⏳ , in_progress 🏃 , done ✅ , cancelled ❌

label — Add or remove labels

todoing label 4 +p0               # add p0
todoing label 4 -- -backend       # remove backend (-- separator needed)
todoing label 4 +bug --clear      # clear all, then add bug

body / append — Edit descriptions

todoing body 4 "Full rewrite of the auth flow."     # replace body
todoing append 4 "Also update token refresh logic."  # append to body

delete — Remove a task

todoing delete 4 --force       # skip confirmation

edit — Open in $EDITOR

todoing edit 4                 # humans only; AI agents use body/append

reindex — Rebuild the index

todoing reindex                # recovery command; rarely needed

Built for AI agents

todoing is designed for AI coding agents to drive via CLI. Commands are single-shot, output is parseable, and the $EDITOR-based edit command has scriptable alternatives (body, append, status, label).

todoing ls -n 5                     # agent checks current work
todoing status 3 in_progress        # agent starts a task
todoing append 3 "Fixed in a1b2c3d" # agent records progress
todoing status 3 done               # agent completes task

No prompts, no TUI, no friction.

Self-dogfooding

todoing tracks its own development. Every feature, fix, and idea for todoing itself is a task inside .todoing/tasks/. The tool builds the tool.

Development

git clone https://github.com/bllyanos/todoing
cd todoing
uv sync
source .venv/bin/activate
python -m pytest

License

MIT