Backlog.md

Markdown‑native Task Manager & Kanban visualizer for any Git repository

AI agents write the code. You review the tasks: before, during, and after.

npm i -g backlog.md

Backlog.md turns any folder into a self‑contained project board powered by plain Markdown files and a zero‑config CLI.

Why Backlog.md in the AI era

AI agents can now produce more plausible code in an hour than you can carefully read in a day. The bottleneck is no longer writing code. It's your attention. You can't meaningfully review 15,000 generated lines in one sitting, but you can read a screenful of task specs with acceptance criteria before any code exists, and push back while a misunderstanding is still one sentence, not a rebuilt feature.

Backlog.md structures agent work around three review checkpoints:

1. Review the spec: the agent decomposes your idea into tasks with descriptions, acceptance criteria, and milestones before implementation starts.
2. Review the plan: the agent researches your codebase and writes its implementation plan into the task. Approve it or steer before any code is written.
3. Review the code: one task = one context window = one PR. Diffs stay a size a human can actually read.

Afterwards, the completed tasks remain in Git as a permanent record of what was attempted and why, legible to you, your team, and the next agent.

Dogfooded: nearly all of Backlog.md's own code is written by AI agents working through Backlog.md itself. The full task ledger lives in this repo's backlog folder.

📺 See it in action: Devoxx Belgium 2025 · AI Engineer Code Summit 2025

Features

• 🤖 AI-ready -- works with Claude Code, Gemini CLI, Codex, Kiro & any other MCP or CLI compatible AI assistant

• 📝 Markdown-native tasks -- every task is a plain .md file in your repo

• ✅ Acceptance criteria & Definition of Done -- verifiable scope per task, plus a reusable DoD checklist for every new task

• 🎯 Milestones & dependencies -- structure bigger efforts and make execution order reviewable, with task detail showing what a task waits on and what waits on it

• 📊 Terminal Kanban -- backlog board paints a live board in your shell; backlog board export creates shareable markdown reports

• 🌐 Web UI -- backlog browser serves a local Kanban board with drag-and-drop and task editing forms

• 🔍 Search -- fuzzy search across tasks, docs & decisions with backlog search

• 🔒 Local-first -- no server, no account, no telemetry; tasks are plain files in your repo, and remote Git operations are optional

• 💻 Cross-platform (macOS, Linux, Windows) · 🆓 MIT-licensed & open-source

Getting started

# Install
npm i -g backlog.md
# or: bun add -g backlog.md
# or: brew install backlog-md
# or: nix run github:MrLesk/Backlog.md

# Initialize in any Git repo
backlog init "My Awesome Project"

# Or initialize without Git for local/non-code projects
backlog init "Personal Planning" --no-git

[!TIP] Running one-off with npx? This tool's npm package is named backlog.md, so use the full name: npx backlog.md init "My Project", npx backlog.md board. Without an install, npx backlog resolves to an unrelated third-party npm package — not this tool. (With backlog.md installed as a project dependency, npx backlog runs the local binary as usual.)

Run with Nix

Run Backlog.md directly from the repository flake:

nix run github:MrLesk/Backlog.md -- --version

Or install the named package into your Nix profile:

nix profile install github:MrLesk/Backlog.md#backlog-md

The Nix flake supports x86_64-linux, aarch64-linux, and aarch64-darwin. The x86_64 Linux package uses Bun's baseline runtime so it also works on pre-AVX2 processors with AVX support. Intel macOS users can use the npm, Bun, or Homebrew installation instead.

The init wizard will ask how you want to connect AI tools:

• CLI instructions (recommended): creates a short instruction file that tells agents to run backlog instructions overview.
• MCP connector: optionally auto-configures Claude Code, Codex, Gemini CLI, Kiro or Cursor for teams that prefer MCP.
• Skip: no AI setup; use Backlog.md purely as a task manager.

For Cursor with CLI instructions, select AGENTS.md or pass --agent-instructions cursor; both use the same AGENTS.md target. Backlog.md preserves existing AGENTS.md content and does not migrate or remove unrelated user-managed .cursor/rules files.

Everything is stored as human-readable Markdown in a project-local backlog folder such as backlog/, .backlog/, or a custom project-relative path configured through backlog.config.yml (e.g. backlog_directory: my-backlog). Task IDs use a configurable prefix (backlog init --task-prefix): the default produces TASK-1-style IDs, while this repository uses back, so examples below show BACK-1-style IDs. Git is optional: backlog init --no-git creates a filesystem-only project.

Working with AI agents

This is the recommended flow for Claude Code, Codex, Gemini CLI, Kiro and similar tools, following the spec‑driven AI development approach. After running backlog init, agents should start by running backlog instructions overview. Work in this loop:

Step 1: Describe your idea. Tell the agent what you want to build and ask it to split the work into small tasks with clear descriptions and acceptance criteria.

🤖 Ask your AI Agent:

I want to add a search feature to the web view that searches tasks, docs, and decisions. Please decompose this into small Backlog.md tasks.

[!NOTE] Review checkpoint #1: read the task descriptions and acceptance criteria.

Step 2: One task at a time. Work on a single task per agent session, one PR per task. Good task splitting means each session can work independently without conflicts. Make sure each task is small enough to complete in a single conversation. You want to avoid running out of context window.

Step 3: Plan before coding. Ask the agent to research and write an implementation plan in the task. Do this right before implementation so the plan reflects the current state of the codebase.

🤖 Ask your AI Agent:

Work on BACK-10 only. Research the codebase and write an implementation plan in the task. Wait for my approval before coding.

[!NOTE] Review checkpoint #2: read the plan. Does the approach make sense? Approve it or ask the agent to revise.

Step 4: Implement and verify. Let the agent implement the task.

[!NOTE] Review checkpoint #3: review the code, run tests, check linting, and verify the results match your expectations.

If the output is not good enough: clear the plan/notes/final summary, refine the task description and acceptance criteria, and run the task again in a fresh session.

Working without AI agents

Use Backlog.md as a standalone task manager from the terminal or browser.

# Create and refine tasks
backlog task create "Render markdown as kanban"
backlog task edit BACK-1 -d "Detailed context" --ac "Clear acceptance criteria"

# Track work
backlog task list -s "To Do"
backlog task list --json | jq '.tasks[] | .id'
backlog task edit BACK-1 --comment "Can we split the UI work into a separate PR?" --comment-author @sara
backlog search "kanban"
backlog board

# Work visually in the browser
backlog browser

You can switch between AI-assisted and manual workflows at any time; both operate on the same Markdown task files. Just prefer Backlog.md commands (CLI/MCP/Web) over hand-editing task files, so field types and metadata stay consistent.

Read commands support stable, versioned JSON for scripts and integrations. Use --json with task list, task view, the task shorthand, and search. JSON mode is noninteractive a