Backlog.md: Markdown Task Files as the Review Surface for AI Agents

The problem is review bandwidth, not code generation

The README states the premise directly: agents can produce more plausible code in an hour than a person can carefully read in a day, so the bottleneck moves from writing to reviewing. Backlog.md is aimed at that gap. It is for developers and small teams who already drive an AI assistant against a Git repository and who want the unit of work to be a written task with acceptance criteria rather than a chat transcript. The project structures agent work around three checkpoints named in the README: reviewing the spec before implementation, reviewing the plan the agent writes into the task after researching the codebase, and reviewing the code with the rule that one task equals one context window equals one pull request. The intended reader is someone who wants to push back on a misunderstanding while it is still one sentence. It is not a general-purpose issue tracker for organisations that need assignment rules, SLAs or cross-repo dashboards.

Tasks are files, and the repository is the database

Every task is a plain .md file stored in a project-local folder. The README names the default locations as `backlog/` or `.backlog/`, and a custom project-relative path can be set in `backlog.config.yml` under the key `backlog_directory`. Task identifiers use a configurable prefix set at init time with `backlog init --task-prefix`. The default produces `TASK-1`-style IDs, while this repository uses `back`, so its own examples read `BACK-1`. That detail matters more than it looks: because IDs are short strings embedded in filenames and commit messages, changing the prefix later is a rename across the ledger, not a settings toggle. Git is optional. `backlog init --no-git` creates a filesystem-only project, which the README frames as suitable for local or non-code planning. The stated posture is local-first: no server, no account, no telemetry, with remote Git operations optional. Two consequences follow. First, review history is Git history, so the audit trail is whatever your branching model produces. Second, there is no central index, which is why search is a CLI concern (`backlog search`, described as fuzzy search across tasks, docs and decisions) rather than a server-side query.

Three ways to look at the same files

The tool reads one on-disk format through three surfaces. `backlog board` paints a Kanban board in the terminal. `backlog board export` produces shareable Markdown reports, which keeps the reporting artefact in the same format as the source data. `backlog browser` serves a local Kanban board with drag-and-drop and task editing forms, so the web view writes back to the same Markdown files rather than to a separate store. Beyond the board, the README lists acceptance criteria and a Definition of Done checklist that can be reused for every new task, plus milestones and dependencies where task detail shows what a task waits on and what waits on it. Those dependency edges are the part worth scrutinising during evaluation. Ordering information that lives inside individual task files has to be reconciled when two people edit different files on different branches, and the README does not describe a merge or conflict-resolution mechanism for that case. Treat the dependency view as a reading aid for a single working session, not as a scheduler.

Getting it running, and the npx trap

Installation is a global package: `npm i -g backlog.md`, or `bun add -g backlog.md`, or `brew install backlog-md`, or `nix run github:MrLesk/Backlog.md`. Then `backlog init "My Awesome Project"` inside a Git repository, or `backlog init "Personal Planning" --no-git` for a filesystem-only project. The README carries an explicit warning about one-off use: the npm package is named `backlog.md`, so `npx backlog.md init "My Project"` and `npx backlog.md board` are the correct forms. Running `npx backlog` without an install resolves to an unrelated third-party npm package. If `backlog.md` is installed as a project dependency, `npx backlog` runs the local binary normally. 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 runs on pre-AVX2 processors with AVX support, and Intel macOS users are pointed at npm, Bun or Homebrew instead. The init wizard then asks how to connect AI tools, offering CLI instructions (recommended, which writes a short instruction file telling agents to run `backlog instructions overview`), an MCP connector that can auto-configure Claude Code, Codex, Gemini CLI, Kiro or Cursor, or Skip for use purely as a task manager. For Cursor with CLI instructions, the README says to select AGENTS.md or pass `--agent-instructions cursor`, both targeting the same file, and that existing AGENTS.md content is preserved while unrelated user-managed `.cursor/rules` files are neither migrated nor removed.

The agent loop depends on instructions the agent actually reads

The recommended flow is spec-driven. After `backlog init`, agents are told to start with `backlog instructions overview`. The loop is: describe the idea and ask the agent to decompose it into small tasks with descriptions and acceptance criteria; read those before implementation; work one task per agent session with one pull request per task; and let the agent write its implementation plan into the task after researching the codebase. The design assumption is that a task file is small enough to read in full and specific enough that a diff produced against it stays reviewable. That assumption is doing a lot of work. The README asserts the one-task-one-context-window-one-PR equivalence but does not describe enforcement. Nothing in the material indicates the CLI rejects a task whose diff grows past a threshold, so task granularity remains a discipline enforced by whoever writes the decomposition prompt. The README does note the project is dogfooded, with nearly all of its own code written by agents working through Backlog.md, and points to the `backlog/tasks` folder in the repository as the full task ledger. That ledger is the most useful thing to read before adopting, because it shows what the maintainers consider a well-sized task rather than describing it.

Where the Markdown-in-Git model stops being the right choice

The failure mode is collaboration shape, not task volume. Files in a repository inherit the repository's access model, so anyone who can read the repo can read the backlog, and anyone who can push can edit any task. There is no per-task permission, no notification, and no server-side state, which is consistent with the stated local-first design but rules out the case where a non-engineering stakeholder needs a filtered view without repository access. Concurrency is the second boundary. Two agents working the same repository on separate branches will each write task files, and the material describes no locking or reservation command, so the practical guard is human sequencing of agent sessions, which is exactly what the one-task-per-session guidance asks for. Third, the reporting surface is thin by design: `backlog board export` writes Markdown, so anything resembling velocity charts or time-in-column metrics has to be computed from the files. Finally, the dependency and milestone features are descriptive. If your need is a dependency graph that blocks work automatically, this is the wrong tool, and a hosted tracker is the better fit. The honest comparison is with a hosted issue tracker plus a separate agent integration. There, the task record lives in a service, agents reach it through an API, and humans get permissions, notifications and dashboards for free. Backlog.md inverts that: the record lives in the repository, agents reach it by reading files and running CLI commands, and every collaboration feature that a service provides has to be supplied by Git and by your team's process. The trade is deliberate and the README states it as local-first, but it means the migration cost in the other direction, from Backlog.md to a hosted tracker, is a data export you would have to write yourself, since the source format is Markdown files rather than a documented interchange schema.

Licence, releases and what maintaining this costs

Backlog.md is MIT-licensed, which permits commercial use, modification and redistribution provided the copyright notice and licence text are retained. That is the whole of the licence implication here; questions about your own obligations belong with counsel. The release cadence visible in the supplied material is frequent: v1.51.0 on 2026-09-02, v1.50.1 on 2026-08-10, and v1.50.0 on 2026-08-09, with the last push to the default branch on 2026-09-03. Frequent minor releases are a maintenance cost for anyone pinning a version, because upgrading means re-reading release notes for changes to the on-disk task format, the config keys in `backlog.config.yml`, or the instruction file the init wizard writes. Upgrading the global npm package is one command, but the artefacts that matter are the Markdown files and the agent instruction file, and those are edited by your team and by agents. The material does not describe a migration command or a format-version marker in task files, so before a major upgrade the practical check is to diff a task file created by the new version against one created by the version you run now. The other recurring cost is the instruction file itself: because agents are directed to `backlog instructions overview`, the quality of agent behaviour tracks the quality of that generated text, and it changes between releases. Pin the version in CI, and re-read that file after each upgrade rather than assuming the agent loop is unchanged.

Editorial conclusion

Adopt Backlog.md if you already run Claude Code, Codex, Gemini CLI or a similar assistant against a Git repository and want the task list to live in that same repository as reviewable Markdown. Skip it if you need hosted boards, cross-team permissions, or reporting beyond what `backlog board export` produces. Before committing, verify two things in your own environment: that `npx backlog.md init` resolves to this package rather than the unrelated `backlog` package on npm, and that the instruction file the init wizard writes (AGENTS.md or the CLI instructions variant) does not conflict with rules your team already keeps for Cursor.

Official sources

1. License: MIT
2. MrLesk/Backlog.md on GitHub
3. Project website
4. README
5. Releases