Backlog.md stores project tasks as Markdown files in a Git repository and presents them in a terminal Kanban board.
2
AI agents follow a workflow that moves from task creation to an implementation plan, code review, and completion against acceptance criteria.
3
Small, well-defined tasks give agents less work to hold in context and make it easier to correct or roll back an implementation.
Summary
Alex Gavrilescu presents Backlog.md, an open-source MIT tool for managing software tasks from the terminal. Tasks are Markdown files stored in a Git repository, with metadata, descriptions, acceptance criteria, implementation plans, and completion details. The tool provides a terminal Kanban board, a web interface, CLI commands, and an MCP server for AI agents. Gavrilescu demonstrates a workflow where an agent first searches existing tasks, creates a new task, writes an implementation plan, implements the code, and checks the definition of done. Humans review the task after creation, review the plan before coding, and review the finished code. He argues that splitting large features into atomic tasks helps prevent context-window problems, keeps implementations within scope, and makes failed work easier to revise. Backlog.md can work with agents such as Claude, Gemini, and Kuso, and it does not require a separate database, API, account, or service.
A terminal Kanban board keeps task details beside the work
Gavrilescu built Backlog.md after failing to find a terminal Kanban board. Its interface shows To Do, In Progress, and Done columns, with task descriptions and acceptance criteria available directly in the terminal. Completed tasks can include implementation notes. The board is backed by Markdown files in the repository. Each file has front matter containing fields such as task ID, title, labels, and other metadata, followed by the task description and acceptance criteria.
Clear requirements give both people and agents a testable target
Before asking an agent to build the move mode, Gavrilescu writes down the interaction rules. Pressing M toggles move mode and highlights the current task. The up and down arrows reorder it within a column, while the left and right arrows change its status. Pressing M or Enter commits the move, and Escape cancels it. The footer must show the controls. He treats the acceptance criteria as a review point because they reveal whether the agent understood the intended feature before any code is written.
The agent learns the project workflow before creating a task
When asked to create the task, Claude first searches for existing tasks and reads how Backlog.md works. Gavrilescu compares this to onboarding a developer who has just joined the project. The resulting task contains a purpose statement, a description, and acceptance criteria. The purpose explains that move mode should let users reorder tasks within columns and move them between status columns through keyboard navigation, without CLI commands or direct file editing.
An implementation plan gives a second chance to correct the direction
After the task is created, the agent produces an implementation plan. It can inspect the documentation, search the codebase, and determine which files need changes. The plan includes an architecture overview, implementation steps, and a list of files to modify. Gavrilescu calls this the second important review step. A senior engineer can inspect the proposed direction before the agent writes code and correct a misunderstanding while the cost of changing course is still low.
MCP resources teach agents how to use the task system
Backlog.md exposes an MCP server with resources and tools. Its resources explain the workflow, including how to create tasks, which fields are required or optional, how to execute a task, when to set it to In Progress and assign it, and how to complete it by checking acceptance criteria and the definition of done. MCP tools let agents search tasks, view task details, create tasks, update tasks, and change acceptance criteria. CLI commands remain available for older agents.
The workflow separates human intent from agent execution
A human can describe the feature in ordinary language, then ask an agent to create the task and fill the required sections. Once the task exists, the agent can receive a simple instruction such as, "Hey Claude, can you please implement task 316?" The agent uses the description, acceptance criteria, and plan to implement the feature. In the demonstration, the new move command works, the task can be moved between columns, and an incorrectly completed task can be returned to In Progress.
Atomic tasks limit context and make failed work easier to restart
Gavrilescu says Markdown tasks enable a form of context engineering. A task can define how much an agent should implement in one session, which reduces the chance of running out of context and limits unwanted extra features. If a task goes wrong, the team can change its description or acceptance criteria and ask the agent to start again from the implementation plan. Unit tests can check whether the acceptance criteria are met.
The workflow has three review points. After task creation, a human checks the description and acceptance criteria to see whether the agent understood the intent. The implementation plan is reviewed next, with attention to whether the agent is taking the right technical direction. The finished code is reviewed at the end. Gavrilescu also says multiple tasks can be developed in parallel with Git worktrees when they have no dependencies.
Git storage makes the project shareable without another service
Backlog.md is an open-source MIT CLI tool with a terminal UI and a web interface. Agents can use MCP or CLI commands, and the tool runs across common operating systems. It does not require extra APIs, databases, tools, or accounts. Tasks stored in a Git repository can be shared with a team, and Backlog.md checks task status even when a task has been updated on another branch. Gavrilescu says agents wrote 99% of Backlog.md, while he wrote the instructions and first three tasks.
