simple-backlog 0.2.0

Local-first task manager: markdown files in git, MCP + CLI, per-type schemas, deterministic + LLM validator

simple-backlog

Local-first task manager: markdown files in git, MCP + CLI, per-type schemas, deterministic + LLM validator.

Why

Your tasks live as plain markdown files in your repo — no server, no account, no sync. A flexible schema engine lets every project define its own task types with custom statuses, fields, and guarded transitions. Claude (and any MCP client) gets full read/write access via a typed tool API.

Quickstart

uvx simple-backlog init         # bootstrap config + docs/backlog/
backlog task create task --title "First task"
backlog task list
backlog task transition TASK-... in_progress

Install

# Run once without installing:
uvx simple-backlog init

# Install permanently:
uv tool install simple-backlog
# or:
pipx install simple-backlog

MCP Setup (Claude Desktop / Code)

Add to your MCP client config:

{
  "mcpServers": {
    "backlog": {
      "command": "uvx",
      "args": ["simple-backlog", "serve-mcp"]
    }
  }
}

Configuration

.simple-backlog.yml at repo root. Example:

backlog_dir: docs/backlog
types:
  task:
    statuses: [backlog, in_progress, done, cancelled]
    initial_status: backlog
    fields:
      done_summary:
        type: string
        required: false
    transitions:
      - from: in_progress
        to: done
        gates:
          - kind: require_field
            field: done_summary

Git Hooks

backlog install-hooks   # installs pre-commit validation
backlog uninstall-hooks

Commands

backlog init                        # bootstrap
backlog task create <type>          # create task
backlog task list                   # list tasks
backlog task show <id>              # show task
backlog task transition <id> <to>   # change status
backlog task link <from> <to> --kind blocks
backlog validate --all              # validate repo
backlog fix --all                   # auto-repair
backlog search "query"
backlog serve-mcp                   # start MCP server

Shortcuts: backlog new, backlog ls, backlog show, backlog done, backlog wip

Design

See docs/plans/2026-05-28-simple-backlog-design.md for full design.

Contributing

Python 3.11+, uv, TDD. Run pytest and ruff check src/.