Agents stop improvising
Each task carries a description, acceptance criteria, and an implementation plan. The agent states what it will do before it writes a line of code, and you read it before it runs.
MIT licensed · data stays in your repo
Keep AI agents working in your repo, with every step reviewable
Backlog.md stores tasks, acceptance criteria, implementation plans, and execution notes as Markdown files in your repository. No database, no black box. Agents break down and execute the work, you approve at three checkpoints.
$
npm i -g @kuwork/backlog.md
No account needed Works offline macOS, Linux, Windows
back-208 Add paste as markdown support in Web UI
back-267 Add agent instruction version metadata
back-346 Add milestone completion archival workflow
back-347 Add milestone editing in Web UI
back-348 Redesign All Tasks page with table layout
back-353 Add documentation field to task object
back-361 Add label based filtering to task list views
back-367 Add Final Summary field to tasks
back-239 Auto link tasks to documents and decisions
back-354 Project Definition of Done defaults
Every
agent
run
leaves
something
you
can
review.
Tasks
are
readable
Markdown,
progress
is
a
reviewable
Git
diff,
knowledge
compounds
into
a
searchable
Wiki.
Agents can write code.
Who tells them what to do next
Hand a requirement to an agent and it will produce a function that runs. But it does not know what comes next, does not know where the boundary is, and will not tell you which calls it made on your behalf. Once the context grows, the direction drifts, and you spend an afternoon reading what it changed.
The fix
Turn agent work into reviewable tasks
Every task is a Markdown file with a description, acceptance criteria, and an implementation plan. The agent writes down what it will do before it writes code, and waits for your approval. Tasks move into version control with the code, so they can be diffed, reviewed, searched, and archived.
Why Backlog.md
Four concrete outcomes: direction holds, review has handles, data stays local, knowledge accumulates.
Three review gates
Spec, plan, and result are approved separately. A wrong direction stops before the first line of code, not after a thousand line diff.
Your data never leaves the machine
Everything is stored in local Markdown files inside the project. No cloud account, no subscription, works offline, and Git is optional.
Every session compounds
The LLM wiki turns tasks, docs, and decisions into a queryable project memory. Switch session or switch people, and the context does not have to be rebuilt from zero.
Backlog.md builds itself with Backlog.md
Every step of this project, from idea to release, is recorded in its own backlog directory. The numbers
below come from the current state of the repository, not from sample data: task files count the
tasks, completed and archive/tasks directories, and wiki pages
count everything under wiki except the mirrored source material in sources.
885
Task files in the repo
805
Tasks marked done
883
Nodes in the task graph
238
Wiki pages distilled
Progress you can see
See the progress, and see the connections
The statistics page spreads a year of delivery into a heatmap and distribution charts. Open any task and its dependencies, subtasks and milestone unfold into a relationship graph on the spot. Both read the same Markdown files — no separate reporting system.
Activity analytics: a year of work at a glance
- Completion heatmap — every day of the past year laid out, so cadence and gaps show up at once
- Status and priority distribution — the to-do / in-progress / done split next to the high, medium and low priority mix
- Cycle time and effort — average cycle time, average effort and overdue counts, all derived from the date fields in the task files
Relationship graph: one task's whole neighbourhood
- The open task sits at the centre — BACK-521 fans out to its 14 subtasks, its upstream dependency chain and the milestone it belongs to
- One line style per relation — solid for depends-on, dashed for parent task, dotted for milestone membership, with the legend above the graph
- Keep drilling — click to focus a neighbour, double click to open that task, walking out up to 4 hops and 80 nodes by default
How it works
Three steps, and you can stop at any one
Every step leaves a file in the repository, so pausing, changing your mind, or handing the work to another agent never loses state.
Initialize a backlog
Run one command inside any Git repository and pick CLI instructions or MCP for your agent. You can also skip AI and use it as a plain task manager.
backlog init "My Awesome Project"
Let the agent decompose and plan
Describe the idea. The agent creates tasks with acceptance criteria, researches the codebase, writes the implementation plan, then stops for your approval.
Review point: read the description and acceptance criteria first, then approve the plan
Review the result and capture it
Read the diff, run the tests, check the acceptance criteria. Once it passes, write the summary and the knowledge lands in the Wiki as input for the next step.
One task per session, one task per commit
Interface
Every view, nothing leaves your repository
The board, the Gantt chart and the task table read and write the Markdown files directly; graph queries run against the graph derived from those files; a SQL block queries a DuckDB database registered inside the project. They all read and write the repository directly — nothing is exported elsewhere.
01 Board
Drag and drop board, status at a glance
backlog browser groups task cards by status. Drag a card to move it, and the change is written straight back to the Markdown file.
02 Gantt
See slippage the moment you open it
Planned dates draw the outline, actual dates fill the bar, across five time grains, so slippage shows up immediately.
03 Task views
Hundreds of tasks, still one search away
Switch between table, board, and tree views, filter by status, label, assignee, or milestone, and run fuzzy search across tasks, docs, and decisions.
04 Graph queries
Ask who blocks whom, get the answer
Run read only Cypher against the project knowledge graph once a data source is configured, with results shown as a table or a graph.
05 Data queries
Numbers in your docs never go stale
Write a SELECT inside a Markdown body and the reading view executes it live, rendering a result table you can copy as Markdown, export as CSV or page through.
06 Charts
Turn relations and data into diagrams
The data query (05) output can be charted directly: feed its results into a Mermaid or ECharts block and the reading view renders it in place — flowcharts, sequence diagrams, or interactive charts — from the same data your docs, board, and Wiki already use.
07 File preview
Office and PDF, right where they live
Preview Word, Excel, PPT, and PDF files inside the repository without exporting — layout, tables, and slides render in place, no download, no third party tab.
State machine
You define the flow
The tool does not dictate how a task moves. Which statuses connect and which ones close the loop is drawn by you, in settings — for engineering work, and just as well for news analysis, paper writing or any non-coding process.
State machine editor: draw your own transitions
- Live transition tree — add or remove statuses and edges in settings and the tree redraws beside you
- Terminal states marked — which statuses close the loop and which can still move, so nothing stalls halfway
-
Hook into changes —
onStatusChangeruns a shell command on transition, for checks, notifications or sync - Not just for code — news analysis can move unread → excerpted → drafted → reviewed, a paper can move topic → outline → draft → submitted; non-engineering work gets the same control
Memos
What you think of, you keep
Write it down without breaking focus. Notes live in the repository next to tasks and docs, searchable, backlinked and archivable.
Memos: write it down without breaking focus
- Three views, same notes — a feed by time, a calendar by month, and a pinboard wall of cards
- #tags and @tasks resolved inline — notes link themselves into the knowledge graph, with backlinks
-
Archive, never delete — hover to move a note into
archive/memosand keep the history
Features
Terminal, web interface, MCP, and CLI all read and write the same Markdown files, so you can switch at any time.
- Local Markdown tasks — every item is a plain .md file you can diff, review, and search
- Built for agents — works with Claude Code, Gemini CLI, Codex, Kiro, and any assistant that can call a CLI or MCP server
- Terminal board — backlog board renders the current board right in the shell
- LLM wiki knowledge base — an AI maintained pairing notebook with ingestion, query, and health checks
- Memos quick notes — feed, calendar, and pinboard views with inline tags and task links
- Graph queries — read only Cypher over the graph of tasks, docs, dependencies, and links
- Live query blocks — embed read only SQL or Cypher in any Markdown body and render results in place
- Chart blocks — mermaid and echarts fenced blocks for flowcharts and data charts, theme aware
- File preview — high fidelity DOCX, XLSX, PPTX, and PDF preview inside the web interface
- Definition of done defaults — a project wide checklist attached to every new task
- Board export — backlog board export writes a shareable Markdown report
- MIT licensed — free for personal and commercial use, on macOS, Linux, and Windows
Plug into the agents you already use
The CLI is the default way in, so any agent that can run a command can start working. If you prefer MCP,
backlog init configures it for you.
Claude Code
Codex
Gemini CLI
Kiro
Cursor
Kimi Code
MCP connector
Terminal
Web interface
Docs and resources
From the quick start to graph queries, the docs live in the same repository as the project.
User manual
A 52-page structured manual: install and init, task management, board, web interface, AI integration, graph and data queries.
Read the user manualWiki knowledge base
The project's own LLM wiki: concepts, decisions, patterns, and execution records — a working example of the knowledge capture workflow.
Read on GitHubCLI reference
Complete command reference: tasks, search, board, docs, decisions, milestones, memos and graph commands.
Read on GitHubAdvanced configuration
Every configuration key: cross-branch checks, auto-commit, ID formatting, editor integration, and default definition of done.
Read on GitHubFrequently asked questions
No. Everything lives in the local backlog folder inside your project. There is no cloud account, no subscription, and it works offline.
Tasks are Markdown files in your repository. They enter version control with the code, so they can be diffed, reviewed, searched, and archived. It is also built for agents, with CLI instructions and an MCP interface so an agent can work the tasks directly while a human reviews the checkpoints.
Anything that can run a command or speak MCP, including Claude Code, Codex, Gemini CLI, Kiro, and Cursor. CLI instructions are the recommended path: the agent runs backlog instructions overview and gets the current workflow guide.
Inside the project backlog directory, backlog/ or .backlog/ by default, configurable to another project relative path in backlog.config.yml. Tasks themselves are plain Markdown files you can read.
Yes. The terminal commands and the web interface both work on their own, and every change stays in sync with the Markdown files. You can move between manual and AI assisted work at any time.
Run backlog init inside an existing repository. With no Git, use backlog init --no-git to create a file system only project, which turns off cross branch checks, remote operations, and auto commit.
CLI instructions are the default recommendation, since backlog instructions overview returns the workflow guide for the installed version instead of a stale copy. If you prefer MCP, backlog init can configure Claude Code, Codex, Gemini CLI, Kiro, or Cursor for you.
No. It binds to 127.0.0.1 by default, so only the local machine can reach it. Use backlog browser --host 0.0.0.0 only when you need LAN access, and note that the API is unauthenticated.
Yes. Tasks enter version control with the code, so your normal review flow applies. Auto commit is off by default, which suits teams that want control over history. Solo or automated workflows can turn it on for one commit per action.
MIT licensed. Free for personal and commercial use, as long as you keep the attribution.
macOS, Linux, and Windows. Install with npm, bun, Homebrew, or Nix.
Run backlog agents --update-instructions in your project, then pick the files to update (AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md). It writes the current version's Backlog.md instruction block into each selected file while preserving anything you added outside that managed block. Re-running backlog init updates these files too; if a file has no Backlog.md block yet, the command adds one.
Two bundled Agent Skills: llm-wiki-for-backlog turns your backlog sources into a queryable project knowledge base (wiki); task-migration-architect analyzes upstream changes and drives task-based branch merges in fork projects. Install them with backlog wiki install <agent> and backlog migrate install <agent>, where <agent> is claude, codex, or agents. Use --force to overwrite an existing skill, or --dry-run to preview without writing.
Claude Code / Desktop (.claude/skills/), OpenAI Codex CLI (.codex/skills/), and the generic Agents directory (.agents/skills/) — all three link to one shared copy, falling back to a direct copy on Windows. After a Backlog.md upgrade, re-run the install command with --force to refresh the skill to the new version; no manual edits needed.
Install in five minutes, delete it whenever you want
MIT licensed, data in your own repository, no account, no cloud dependency. Install it and run backlog init once to see what it does.
The same package installs with bun: bun add -g @kuwork/backlog.md