backlog-md-py 0.3.0

Standalone Python compatibility implementation of Backlog.md

backlog-md-py

backlog-md-py is a standalone Python implementation of the local-file Backlog.md task workflow. It keeps Backlog.md projects as Markdown files on disk, while providing a Python CLI, Python helper functions, SDK-free MCP server, singleton daemon for multi-agent setups, browser board, and optional Textual TUI.

Use it when you want Backlog.md-compatible project tracking from Python tooling or local agents without requiring a Node or Bun runtime.

Status And Safety

This project is in beta. The audited compatibility inventory reports the documented local-file CLI, Python helper, MCP, daemon, browser-board, and TUI surfaces as implemented for the current baseline. Beta means the supported contract is ready for real project integration after validation, but it is not yet a 1.0 API freeze.

The source of truth remains the backlog/ Markdown directory in each project. Before live mutation in a consuming project, run copied-repository smoke tests and review the resulting diff. See the stability policy for the supported contract and release gate.

Do not alias backlog-py to backlog unless the target project has made an explicit project cutover decision.

Quick Start

For released versions, install from PyPI:

python -m pip install backlog-md-py

For unreleased commits, install from GitHub:

python -m pip install "git+https://github.com/rmusser01/backlog-md-py.git"

Run the CLI against a Backlog.md project:

backlog-py --help
backlog-py --cwd /path/to/project task list --plain
backlog-py --cwd /path/to/project board
backlog-py --cwd /path/to/project browser --port 6420 --no-open
backlog-py compat status

For a safe first run, start with a scratch 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 board

Interfaces At A Glance

• CLI: backlog-py --cwd /path/to/project ...
• Python module entry point: python -m backlog_py ...
• Python helpers: import from backlog_py.mcp and backlog_py.storage.project
• MCP stdio: backlog-py-mcp
• Multi-agent singleton daemon: backlog-py daemon ensure
• Browser board: backlog-py --cwd /path/to/project browser --port 6420
• Optional TUI: install backlog-md-py[tui], then run backlog-py --cwd /path/to/project tui

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

Agent And MCP Use

backlog-py-mcp is included by default and provides SDK-free MCP stdio mode:

backlog-py-mcp

For multi-agent environments, prefer one local singleton daemon and let MCP clients connect through it:

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

See integration.md for CLI, Python helper, and MCP configuration, and singleton-daemon.md for daemon setup and rollback guidance.

How It Fits Together

All interfaces resolve a Backlog.md project, parse Markdown-backed records, and delegate mutations to shared core services that preserve unowned Markdown sections and serialize writes with local filesystem locks. The daemon is a process-reuse and coordination layer, not a separate database. The optional SQLite index is disposable read acceleration; Markdown remains authoritative.

See architecture.md for a contributor-oriented system map.

Documentation

Start with the documentation index. The most commonly used references are:

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

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.