backlog-md-py

backlog-md-py is a Python implementation of the local-file Backlog.md task workflow. It manages project tasks as plain Markdown files and lets you work with them from the CLI, Python code, AI agents over MCP, a browser board, or a terminal UI — no Node or Bun runtime required. New here? The Quick Start below runs entirely in a scratch directory, so nothing touches a real project until you point it at one.

What Is Backlog.md?

Backlog.md keeps a project's tasks, documents, decisions, and milestones as plain Markdown files under a backlog/ directory inside the project. The Markdown files are the source of truth: they diff, review, and commit with your code, so humans and AI agents can both read and update them without a hosted service or database.

backlog-md-py implements that workflow as a standalone Python package. Use it when you want Backlog.md-compatible project tracking from Python tooling or local agents. For the upstream concept and ecosystem, see Backlog.md.

Features

The plain CLI and MCP tools are the recommended automation surfaces. The browser board and TUI are human-facing project navigation surfaces.

Quick Start

1. Install

python -m pip install backlog-md-py

Optional extras and unreleased installs:

python -m pip install "backlog-md-py[tui]"   # terminal UI
python -m pip install "git+https://github.com/rmusser01/backlog-md-py.git"   # unreleased commits

2. Try it in a scratch project

Start in an empty scratch directory so nothing touches a real project:

mkdir -p /tmp/backlog-md-py-demo
backlog-py --cwd /tmp/backlog-md-py-demo init --defaults --no-git
backlog-py --cwd /tmp/backlog-md-py-demo task create "Try backlog-md-py" --plain
backlog-py --cwd /tmp/backlog-md-py-demo task list --plain
backlog-py --cwd /tmp/backlog-md-py-demo task edit task-1 --notes "Edited in a scratch project." --plain
backlog-py --cwd /tmp/backlog-md-py-demo board   # press q to exit

Then look inside /tmp/backlog-md-py-demo/backlog/ — every record you just created is a plain Markdown file you can read and diff.

3. Point at a real project

Start with read-only commands:

backlog-py --cwd /path/to/project task list --plain
backlog-py --cwd /path/to/project task <id> --plain
backlog-py --cwd /path/to/project board

Then the human-facing surfaces:

backlog-py --cwd /path/to/project browser --port 6420 --no-open
backlog-py --cwd /path/to/project tui   # requires the tui extra

Before running mutation commands (task create, task edit, task archive, and friends) against a real project, smoke-test on a copy and review the diff — see Safety and compatibility.

4. Use it with AI agents (MCP)

Run the SDK-free MCP stdio server:

backlog-py-mcp

For multi-agent setups, run one shared daemon and let MCP clients connect through it:

backlog-py daemon ensure
backlog-py daemon status --json

To generate Backlog.md instruction blocks for common agent files:

backlog-py --cwd /path/to/project agents --update-instructions

See integration.md for MCP client configuration and singleton-daemon.md for daemon lifecycle details.

Safety And Compatibility

The supported 2.x contract is the behavior documented in the compatibility inventory, stability policy, and parity docs. A few rules keep adoption safe:

• Markdown files under backlog/ remain the source of truth; the daemon is a process-reuse and coordination layer, and the optional SQLite index is disposable read acceleration — neither is a separate database.
• Before live mutation in a consuming project, run copied-repository smoke tests and review the resulting diff. See cutover-validation.md.
• Do not alias backlog-py to backlog unless the target project has made an explicit project cutover decision.

See the stability policy for the full supported contract and release gate.

Documentation

Start with the documentation index. Common references:

• Getting started
• Integration guide
• Architecture guide
• Stability policy
• Singleton daemon guide
• Cutover validation checklist
• Changelog
• Contributing guide
• Release process

Development

Use Python 3.11, 3.12, or 3.13. Create a local virtual environment with uv and install editable development dependencies:

uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install -e ".[dev]"

Run the focused agent-critical gate or the full test suite:

uv run --extra dev python -m pytest tests/test_agent_critical_matrix.py -v
uv run --extra dev python -m pytest tests -v

See CONTRIBUTING.md for the contributor workflow and architecture.md for the source layout.

License

GPL-3.0-only. See LICENSE.