Backlog.md: Markdown task files that keep AI agents reviewable

The review bottleneck Backlog.md is aimed at

The README states the problem plainly: an agent can produce more plausible code in an hour than a person can carefully read in a day, so the constraint moves from writing code to paying attention to it. You cannot meaningfully review fifteen thousand generated lines in one sitting. You can, however, read a page of task descriptions and acceptance criteria before any code exists.

That is the whole argument for the tool. Backlog.md is a task manager, not an agent and not a code reviewer. It gives the work a shape that a human can approve in small pieces: a spec, then a plan, then a diff. The README calls these three review checkpoints, and the third one is a sizing rule rather than a feature: one task equals one context window equals one pull request, so diffs stay readable.

Who it is for: developers running Claude Code, Codex, Gemini CLI, Kiro or another MCP or CLI compatible assistant against a Git repository, and who want the task ledger to sit next to the code. The README also covers a Git-free mode for non-code projects, but the agent workflow is clearly the intended use.

Markdown files in the repo, not rows in a database

Each task is a plain `.md` file. The project directory defaults to `backlog/`, can be `.backlog/`, or can be set to a project-relative path through `backlog.config.yml` with a key such as `backlog_directory: my-backlog`. Task identifiers come from a configurable prefix set at init time with `backlog init --task-prefix`; the default yields `TASK-1`-style IDs, while the project's own repository uses `back`, which is why its examples show `BACK-1`-style IDs.

Because the tasks are files, Git becomes the history and the audit trail. The README points at the repository's own `backlog/tasks` folder as the full task ledger, and says nearly all of Backlog.md's own code is written by agents working through Backlog.md. That is a credible dogfooding claim, though it is a claim about their process rather than something a reader can verify from the README alone.

The CLI is the entry point. `backlog board` draws a Kanban board in the terminal, `backlog board export` writes shareable Markdown reports, `backlog browser` serves a local web board with drag-and-drop and task editing forms, and `backlog search` does fuzzy matching across tasks, docs and decisions. The README describes the tool as local-first: no server, no account, no telemetry, with remote Git operations optional. The dependency list backs that up in spirit, since the runtime dependencies are a CLI argument parser, a front-matter parser, a fuzzy search library, a terminal UI library and a React stack for the browser view.

Installing Backlog.md and initializing a project

The README gives four install routes: npm, Bun, Homebrew and Nix. The npm path is the one most readers will take. Run it globally so the `backlog` binary is on your PATH:

npm i -g backlog.md

If you would rather not install anything, the README warns about a naming trap with `npx`. The package is called `backlog.md`, and a bare `npx backlog` resolves to an unrelated third-party package, so the full name is required:

npx backlog.md init "My Project"
npx backlog.md board

The same warning does not apply once `backlog.md` is a project dependency, because then `npx backlog` runs the local binary.

Initialization is a wizard. It takes a project name and asks how you want to connect AI tools, offering CLI instructions (the README's recommendation), an MCP connector that can auto-configure Claude Code, Codex, Gemini CLI, Kiro or Cursor, or skip entirely if you only want a task manager:

backlog init "My Awesome Project"

For a folder that is not a Git repository, the README provides an explicit flag. This is the mode to use for personal planning or non-code work:

backlog init "Personal Planning" --no-git

After init, the README's instruction to agents is a single command, `backlog instructions overview`, which the generated instruction file tells them to run. If you pick Cursor with CLI instructions, the README says to select AGENTS.md or pass `--agent-instructions cursor`, and that both target the same AGENTS.md file. It also states that existing AGENTS.md content is preserved and that unrelated user-managed `.cursor/rules` files are neither migrated nor removed.

The three-checkpoint loop with an agent

The README describes a spec-driven loop. You describe an idea and ask the agent to decompose it into small tasks with descriptions and acceptance criteria. The README's own example prompt asks for a search feature in the web view and requests that it be split into Backlog.md tasks. Checkpoint one is reading those descriptions and criteria.

Checkpoint two is the plan. The agent researches the codebase and writes its implementation plan into the task, and you approve or steer before code is written. Checkpoint three is the diff, kept small by the one-task-one-PR rule. Task detail also shows dependencies in both directions, what a task waits on and what waits on it, which is what makes execution order reviewable rather than implied.

Two supporting features matter here. Acceptance criteria give each task verifiable scope, and a reusable Definition of Done checklist is applied to every new task. Without those, a task file is just a note. With them, it is a contract the agent can be held to, and the README treats that as the point of the whole exercise.

One honest gap: the README does not document what happens when an agent ignores its instructions file, or how to detect that a task was marked complete without its acceptance criteria being met. There is no verification step described for that failure mode.

Where Backlog.md is the wrong tool

It is a local-first tool with no server and no account, and that is a boundary rather than a shortcoming. If you need a hosted board that a non-technical stakeholder opens in a browser without cloning anything, `backlog browser` is a local process, not a shared service. There is no described permission model, no role separation, and no cross-repository roll-up. A team tracking work across a dozen repositories will have a dozen task folders.

Git is optional, but the value proposition leans on it. The permanent record of what was attempted and why depends on commits. A `--no-git` project gets a filesystem-only board with no history beyond what your filesystem provides.

The tool also assumes your agents can run shell commands or speak MCP. The README lists Claude Code, Gemini CLI, Codex, Kiro and similar tools. If your assistant cannot execute `backlog instructions overview` or connect over MCP, you are left with a Markdown task manager and a terminal board, which is a smaller product.

Finally, the README does not document rollback for a bad task edit, nor a migration path if you change `backlog_directory` after tasks exist. Treat the directory configuration as a decision to make at init time.

Backlog.md compared with issue trackers and Beads

The obvious alternative is the issue tracker you already have. GitHub Issues, Jira and Linear all store tasks in a remote database and expose them through a web UI and an API. Backlog.md stores them as files in your repository. The practical difference shows up in two places: an agent editing a task is editing a file it already has in its context, with no API call or token, and the task history is the same commit history as the code. The cost is that everything a hosted tracker gives you for free, notifications, saved views, permissions, cross-project search, is either absent or replaced by Git and your shell.

A closer comparison is Beads, which appears in the related search data as `backlog md vs beads`. Both target agent-driven work in a repository. The distinction visible in this material is structural: Backlog.md's unit is a Markdown file with YAML front matter and a task prefix, parsed by `gray-matter` and searched with `fuse.js`, and its interface layer is a terminal board plus a local React browser UI. The README does not describe a sync service, a hosted component or an agent runtime, and neither does the dependency list.

If your team already runs a tracker and your agents can call its API, adding Backlog.md means maintaining two ledgers. The README does not describe an integration that reconciles them, so the realistic choice is one or the other.

Licence, maintenance and upgrade cost

Backlog.md is MIT-licensed, and the licence file sits at the repository root. MIT is permissive: you can use, modify and redistribute it, including in commercial settings, provided the copyright notice and licence text are preserved. That is a summary of the licence's usual terms, not legal advice; read the LICENSE file if the distinction matters to your organisation.

The last push to the default branch was on 2026-09-03, and the most recent release listed is v1.51.0 from 2026-09-02, with v1.50.0 and v1.50.1 in August 2026. The repository is not archived. The `package.json` in the repository shows version 1.52.0, ahead of the last listed release, which is normal for a project that tags after merging.

Upgrade cost is low by design. The npm package ships platform-specific binaries as optional dependencies for darwin and linux on arm64 and x64, plus windows on arm64 and x64, so a global install is a binary swap rather than a build step. The Nix flake supports `x86_64-linux`, `aarch64-linux` and `aarch64-darwin`, and the README notes that the x86_64 Linux package uses Bun's baseline runtime so it also runs on pre-AVX2 processors with AVX support. Intel macOS users are told to use npm, Bun or Homebrew instead, because no Nix package is offered for them. Your real upgrade cost is the task file format: if a release changes front matter fields, your existing Markdown is the migration surface, and the README does not describe a migration command.

Editorial conclusion

Adopt Backlog.md if your agents already produce more code than you can review and you want the task ledger to live in the same repository as the code, under version control, with no server or account. Skip it if you need hosted dashboards, cross-repository reporting or a permission model, because the README describes a local-first tool whose remote Git operations are optional. Verify two things before committing: that `backlog init` writes into the directory layout you expect, and that your agent actually follows `backlog instructions overview` rather than inventing its own workflow.

Frequently asked questions

Official sources

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