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.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

• 🔒 100 % private & offline -- backlog lives entirely inside your repo

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

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

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

• 🤖 AI-ready CLI -- "Claude, please take over task 33"

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

• 💻 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  
bun/npm i -g backlog.md or brew install backlog-md

# 2. Bootstrap a repo + backlog  
backlog init "My Awesome Project"

# 3. Capture work  
backlog task create "Render markdown as kanban"

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

# 5. Create tasks using Claude-code, Gemini, Codex or Jules
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.

# 6. Assign tasks to AI
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 an implementation plan
* 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-<task-id> - <task-title>.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

The web interface provides:

• Interactive Kanban board with drag-and-drop functionality
• Task creation and editing with rich forms and validation
• Interactive acceptance criteria editor with checklist controls and instant persistence
• Real-time updates as you manage tasks
• Responsive design that works on desktop and mobile
• Archive tasks with confirmation dialogs
• Seamless CLI integration - changes sync with your markdown files

CLI reference

Project Setup

The backlog init command provides comprehensive project setup with interactive prompts for:

• Project name - identifier for your backlog
• Auto-commit - whether to automatically commit task changes to git
• Default editor - editor command for opening tasks (detects from environment)
• Remote operations - enable/disable fetching tasks from remote branches
• Web UI settings - port and browser auto-open preferences
• Agent guidelines - AI agent instruction files (CLAUDE.md, .cursorrules, etc.)
• Claude Code agent - optional Backlog.md agent for enhanced task management (defaults to not installed; opt-in during init or pass --install-claude-agent true)

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 <id> work across the entire tree. Example: backlog doc create -p guides "New Guide".

When re-initializing an existing project, all current configuration values are preserved and pre-populated in prompts, allowing you to update only what you need.

Task Management

Multi‑line input (description/plan/notes)

The CLI preserves input literally; \n sequences are not auto‑converted. Use one of the following to insert real newlines:

• Bash/Zsh (ANSI‑C quoting)
  • Description: backlog task create "Feature" --desc $'Line1\nLine2\n\nFinal paragraph'
  • Plan: backlog task edit 7 --plan $'1. Research\n2. Implement'
  • Notes: backlog task edit 7 --notes $'Completed A\nWorking on B'
• POSIX sh (printf)
  • backlog task create "Feature" --desc "$(printf 'Line1\nLine2\n\nFinal paragraph')"
• PowerShell (backtick)
  • backlog task create "Feature" --desc "Line1nLine2nnFinal paragraph"`

Tip: Help text shows Bash examples with escaped \\n for readability; when typing, $'\n' expands to a newline.

Draft Workflow

Board Operations

Statistics & Overview

Web Interface

Documentation

Decisions

Agent Instructions

Maintenance

Full help: backlog --help

Configuration

Backlog.md merges the following layers (highest → lowest):

1. CLI flags
2. backlog/config.yml (per‑project)
3. ~/backlog/user (per‑user)
4. Built‑ins

Configuration Commands

Available Configuration Options

Note: Set remoteOperations: false to work offline. This disables git fetch operations and loads tasks from local branches only, useful when working without network connectivity.

Git Control: By default, autoCommit is set to false, giving you full control over your git history. Task operations will modify files but won't automatically commit changes. Set autoCommit: true if you prefer automatic commits for each task operation.

Git Hooks: If you have pre-commit hooks (like conventional commits or linters) that interfere with backlog.md's automated commits, set bypassGitHooks: true to skip them using the --no-verify flag.

Performance: Cross-branch checking ensures accurate task tracking across all active branches but may impact performance on large repositories. You can disable it by setting checkActiveBranches: false for maximum speed, or adjust activeBranchDays to control how far back to look for branch activity (lower values = better performance).

Date/Time Support: Backlog.md now supports datetime precision for all dates. New items automatically include time (YYYY-MM-DD HH:mm format in UTC), while existing date-only entries remain unchanged for backward compatibility. Use the migration script bun src/scripts/migrate-dates.ts to optionally add time to existing items.

Sharing & Export

Board Export

Export your Kanban board to a clean, shareable markdown file:

# Export to default Backlog.md file
backlog board export

# Export to custom file
backlog board export project-status.md

# Force overwrite existing file
backlog board export --force

# Export to README.md with board markers
backlog board export --readme

# Include a custom version string in the export
backlog board export --export-version "v1.2.3"
backlog board export --readme --export-version "Release 2024.12.1-beta"

Perfect for sharing project status, creating reports, or storing snapshots in version control.

📊 Backlog.md Project Status (v1.10.0)

This board was automatically generated by Backlog.md

Generated on: 2025-09-06 23:32:46

License

Backlog.md is released under the MIT License – do anything, just give credit. See LICENSE.