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

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

!Backlog demo GIF using: backlog board

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

Features

• 📝 Markdown-native tasks -- manage every issue as a plain .md file

• 🤖 AI-Ready -- Works with Claude Code, Gemini CLI, Codex & any other MCP or CLI compatible AI assistants

• 📊 Instant terminal Kanban -- backlog board paints a live board in your shell

• 🌐 Modern web interface -- backlog browser launches a sleek web UI for visual task management

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

• 📋 Rich query commands -- view, list, filter, or archive tasks with ease

• 📤 Board export -- backlog board export creates shareable markdown reports

• 🔒 100 % private & offline -- backlog lives entirely inside your repo and you can manage everything locally

• 💻 Cross-platform -- runs on macOS, Linux, and Windows

• 🆓 MIT-licensed & open-source -- free for personal or commercial use

Five‑minute tour

# 1. Make sure you have Backlog.md installed (global installation recommended) 
bun i -g backlog.md 
or 
npm i -g backlog.md 
or 
brew install backlog-md

# 2. Bootstrap a repo + backlog and choose the AI Agent integration mode (MCP, CLI, or skip)
backlog init "My Awesome Project"

# 3. Create tasks manually  
backlog task create "Render markdown as kanban"

# 4. Or ask AI to create them: Claude Code, Gemini CLI, or Codex (Agents automatically use Backlog.md via MCP or CLI)
Claude I would like to build a search functionality in the web view that searches for:
* tasks
* docs
* decisions
  Please create relevant tasks to tackle this request.

# 5. See where you stand
backlog board view or backlog browser

# 6. Assign tasks to AI (Backlog.md instructions tell agents how to work with tasks)
Claude please implement all tasks related to the web search functionality (task-10, task-11, task-12)
* before starting to write code use 'ultrathink mode' to prepare and add an implementation plan to the task
* use multiple sub-agents when possible and dependencies allow

All data is saved under backlog folder as human‑readable Markdown with the following format task- - .md (e.g. task-10 - Add core search functionality.md).

Web Interface

Launch a modern, responsive web interface for visual task management:

# Start the web server (opens browser automatically)
backlog browser

# Custom port
backlog browser --port 8080

# Don't open browser automatically
backlog browser --no-open

Features:

• Interactive Kanban board with drag-and-drop
• Task creation and editing with rich forms
• Interactive acceptance criteria editor with checklists
• Real-time updates across all views
• Responsive design for desktop and mobile
• Task archiving with confirmation dialogs
• Seamless CLI integration - all changes sync with markdown files

!Web Interface Screenshot

🔧 MCP Integration (Model Context Protocol)

The easiest way to connect Backlog.md to AI coding assistants like Claude Code, Codex, and Gemini CLI is via the MCP protocol. You can run backlog init (even if you already initialized Backlog.md) to set up MCP integration automatically, or follow the manual steps below.

Client guides

[!IMPORTANT] When adding the MCP server manually, you should add some extra instructions in your CLAUDE.md/AGENTS.md files to inform the agent about Backlog.md. This step is not required when using backlog init as it adds these instructions automatically. Backlog.md's instructions for agents are available at /src/guidelines/mcp/agent-nudge.md.

Claude Code

claude mcp add backlog --scope user -- backlog mcp start

Codex

codex mcp add backlog backlog mcp start

Gemini CLI

gemini mcp add backlog -s user backlog mcp start

Use the shared backlog server name everywhere – the MCP server auto-detects whether the current directory is initialized and falls back to backlog://init-required when needed.

Manual config

{
  "mcpServers": {
    "backlog": {
      "command": "backlog",
      "args": ["mcp", "start"]
    }
  }
}

Once connected, agents can read the Backlog.md workflow instructions via the resource backlog://docs/task-workflow. Use /mcp command in your AI tool (Claude Code, Codex) to verify if the connection is working.

CLI reference

Project Setup

backlog init keeps first-run setup focused on the essentials:

• Project name – identifier for your backlog (defaults to the current directory on re-run).
• Integration choice – decide whether your AI tools connect through the MCP connector (recommended) or stick with CLI commands (legacy).
• Instruction files (CLI path only) – when you choose the legacy CLI flow, pick which instruction files to create (CLAUDE.md, AGENTS.md, GEMINI.md, Copilot, or skip).
• Advanced settings prompt – default answer “No” finishes init immediately; choosing “Yes” jumps straight into the advanced wizard documented in Configuration.

You can rerun the wizard anytime with backlog config. All existing CLI flags (for example --defaults, --agent-instructions, or --install-claude-agent true) continue to provide fully non-interactive setups, so existing scripts keep working without change.

Documentation

• Document IDs are global across all subdirectories under backlog/docs. You can organize files in nested folders (e.g., backlog/docs/guides/), and backlog doc list and backlog doc view work across the entire tree. Example: backlog doc create -p guides "New Guide".