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

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

# Make sure you have Backlog.md installed
bun/npm i -g backlog.md

# 1. Bootstrap a repo + backlog
backlog init hello-

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

# 3. See where you stand
backlog board view

# 4. Working with AI
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.

All data is saved under backlog folder as human‑readable Markdown with the following format task-<task-id> - <task-title>.md (e.g. task-12 - Fix typo.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
• 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

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

Draft Workflow

Board Operations

Web Interface

Configuration

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

Key options:

Note: Set remote_operations: 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, auto_commit is set to false, giving you full control over your git history. Task operations will modify files but won't automatically commit changes. Set auto_commit: true if you prefer automatic commits for each task operation.

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

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

📊 Backlog.md Project Status (automatically generated by Backlog.md)

Generated on: 2025-07-15 17:22:56

License

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