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.

• 📝 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"

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

• 📋 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

# 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. Find what you need
backlog search "markdown" or just backlog search for interactive filters

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

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

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

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

• Project name – identifier for your backlog (defaults to the current directory on re-run).
• Agent instruction files – pick which AI Agent 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.

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

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'
  • Append notes: backlog task edit 7 --append-notes $'Added X\nAdded Y'
• 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.

Find tasks, documents, and decisions across your entire backlog with fuzzy search:

Search features:

• Fuzzy matching -- finds "authentication" when searching for "auth"
• Interactive filters -- refine your search in real-time with the TUI
• Live filtering -- see results update as you type (no Enter needed)

Full help: backlog --help

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

Run backlog config with no arguments to launch the full interactive wizard. This is the same experience triggered from backlog init when you opt into advanced settings, and it walks through the complete configuration surface:

• Cross-branch accuracy: checkActiveBranches, remoteOperations, and activeBranchDays.
• Git workflow: autoCommit and bypassGitHooks.
• ID formatting: enable or size zeroPaddedIds.
• Editor integration: pick a defaultEditor with availability checks.
• Web UI defaults: choose defaultPort and whether autoOpenBrowser should run.

Skipping the wizard (answering “No” during init) applies the safe defaults that ship with Backlog.md:

• checkActiveBranches=true, remoteOperations=true, activeBranchDays=30.
• autoCommit=false, bypassGitHooks=false.
• zeroPaddedIds disabled.
• defaultEditor unset (falls back to your environment).
• defaultPort=6420, autoOpenBrowser=true.

Whenever you revisit backlog init or rerun backlog config, the wizard pre-populates prompts with your current values so you can adjust only what changed.

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.

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.

This board was automatically generated by Backlog.md

Generated on: 2025-10-06 19:51:05

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