JSPM

backlog.md

1.5.9
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 3513
  • Score
    100M100P100Q134436F
  • License MIT

Package Exports

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (backlog.md) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

    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

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

    5-minute tour 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 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

    Web Interface Screenshot

    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 CLI reference

    Project Setup

    Action Example
    Initialize project backlog init [project-name] (creates backlog structure with interactive configuration)
    Re-initialize backlog init (preserves existing config, allows updates)

    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

    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

    Action Example
    Create task backlog task create "Add OAuth System"
    Create with description backlog task create "Feature" -d "Add authentication system"
    Create with assignee backlog task create "Feature" -a @sara
    Create with status backlog task create "Feature" -s "In Progress"
    Create with labels backlog task create "Feature" -l auth,backend
    Create with priority backlog task create "Feature" --priority high
    Create with plan backlog task create "Feature" --plan "1. Research\n2. Implement"
    Create with AC backlog task create "Feature" --ac "Must work,Must be tested"
    Create with notes backlog task create "Feature" --notes "Started initial research"
    Create with deps backlog task create "Feature" --dep task-1,task-2
    Create sub task backlog task create -p 14 "Add Login with Google"
    Create (all options) backlog task create "Feature" -d "Description" -a @sara -s "To Do" -l auth --priority high --ac "Must work" --notes "Initial setup done" --dep task-1 -p 14
    List tasks backlog task list [-s <status>] [-a <assignee>] [-p <parent>]
    List by parent backlog task list --parent 42 or backlog task list -p task-42
    View detail backlog task 7 (interactive UI, press 'E' to edit in editor)
    View (AI mode) backlog task 7 --plain
    Edit backlog task edit 7 -a @sara -l auth,backend
    Add plan backlog task edit 7 --plan "Implementation approach"
    Add AC backlog task edit 7 --ac "New criterion,Another one"
    Add notes backlog task edit 7 --notes "Completed X, working on Y"
    Add deps backlog task edit 7 --dep task-1 --dep task-2
    Archive backlog task archive 7

    Draft Workflow

    Action Example
    Create draft backlog task create "Feature" --draft
    Draft flow backlog draft create "Spike GraphQL" → backlog draft promote 3.1
    Demote to draft backlog task demote <id>

    Board Operations

    Action Example
    Kanban board backlog board (interactive UI, press 'E' to edit in editor)
    Export board backlog board export [file] (exports Kanban board to markdown)
    Export with version backlog board export --export-version "v1.0.0" (includes version in export)

    Web Interface

    Action Example
    Web interface backlog browser (launches web UI on port 6420)
    Web custom port backlog browser --port 8080 --no-open

    Configuration

    Action Example
    Config editor backlog config set defaultEditor "code --wait"
    Enable auto-commit backlog config set autoCommit true
    View config backlog config list

    Documentation

    Action Example
    Create doc backlog doc create "API Guidelines"
    Create with path backlog doc create "Setup Guide" -p guides/setup
    Create with type backlog doc create "Architecture" -t technical
    List docs backlog doc list
    View doc backlog doc view doc-1

    Decisions

    Action Example
    Create decision backlog decision create "Use PostgreSQL for primary database"
    Create with status backlog decision create "Migrate to TypeScript" -s proposed

    Agent Instructions

    Action Example
    Update agent files backlog agents --update-instructions (updates .cursorrules, CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md)

    Maintenance

    Action Example
    Cleanup done tasks backlog cleanup (move old completed tasks to completed folder)

    Full help: backlog --help

    Configuration 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:

    Key Purpose Default
    default_assignee Pre‑fill assignee []
    default_status First column To Do
    statuses Board columns [To Do, In Progress, Done]
    date_format ISO or locale yyyy-mm-dd
    default_editor Editor for 'E' key Platform default (nano/notepad)
    default_port Web UI port 6420
    auto_open_browser Open browser automatically true
    remote_operations Enable remote git operations true
    auto_commit Automatically commit task changes false
    zero_padded_ids Pad all IDs (tasks, docs, etc.) with leading zeros (disabled)

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

    This board was automatically generated by Backlog.md

    Generated on: 2025-07-25 21:04:15

    To Do In Progress Done
    task-203 - Show meaningful description in web kanban
    (Assignees: none, Labels: frontend, enhancement)    		 └─ task-24.1 - CLI: Kanban board milestone view
    (Assignees: @codex, Labels: none)    		 task-205 - Fix Claude Code agent trying to use slash commands instead of backlog CLI
    (Assignees: @claude, Labels: bug, agent)
    task-201 - Add configurable git hooks bypass option
    (Assignees: none, Labels: enhancement, git)    		 task-204 - Add Experimental Claude Code backlog.md agent integration to init command
    (Assignees: @claude, Labels: cli, integration, dx)
    task-200 - Add Claude Code integration with workflow commands during init
    (Assignees: none, Labels: enhancement, developer-experience)    		 task-202 - Fix editor integration regression with Helix and other interactive editors
    (Assignees: none, Labels: bug, regression, editor)
    task-183 - Add ordinal field for custom task ordering in web UI
    (Assignees: none, Labels: none)    		 task-199 - Add version parameter to board export command
    (Assignees: none, Labels: none)
    task-181 - Add statistics dashboard to web UI
    (Assignees: none, Labels: none)    		 task-198 - Fix markdown content overflow beyond screen width
    (Assignees: none, Labels: none)
    task-180 - Add statistics overview command to CLI with TUI interface
    (Assignees: none, Labels: none)    		 task-197 - Fix decision page refresh showing blank screen
    (Assignees: none, Labels: none)
    task-175 - Add hour and minute to all dates in drafts, tasks, documents, decisions
    (Assignees: none, Labels: none)    		 task-196 - Add NixOS packaging support
    (Assignees: none, Labels: none)
    task-172 - Order tasks by status and ID in both web and CLI lists
    (Assignees: none, Labels: none)    		 task-191 - Migrate from Bun.spawn to Bun shell API
    (Assignees: @gemini, @claude, Labels: refactoring, developer-experience)

    License

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