Repo-Local Backlog Board

A minimalist backlog tracking system for developers and AI agents. Backlog is installed locally in each repository and stores its data in a committed .backlog folder.

It requires Node.js >= 20 and has zero runtime dependencies.

Quick Start (AI-First)

Tell your AI coding agent (e.g., Antigravity, Claude Code, etc.):

Install @augustalex/backlog as a dev dependency, and run backlog setup-agent.

Once installed, you can command your agent with these simple prompts:

• Open the Web UI: "open the backlog UI"
• Add a task: "add 'your task description' to the backlog"
• Work on the backlog: "work on the backlog"

AI-First Install in a Repository

Ask your coding agent:

Install @augustalex/backlog as a dev dependency, and run backlog setup-agent.

The agent should first use the repository's package manager to install the package locally, then run the package-manager local setup command. backlog setup-agent then:

• Detects the npm-compatible package manager.
• Confirms @augustalex/backlog is installed as a local dev dependency, or installs it if missing.
• Creates .backlog/tasks, .backlog/images, and .backlog/AGENTS.md.
• Adds a short pointer to .backlog/AGENTS.md from AGENTS.md.
• Creates a setup commit for package files, AGENTS.md, and .backlog.

After setup, agents should use the printed package-manager local commands from the repository root. For npm projects, those commands are:

npm exec -- backlog start
npm exec -- backlog mcp
npm exec -- backlog commit

Do not use one global MCP server for many repositories. Configure each AI app to run the printed MCP command from the repository root so the MCP server is project-specific.

Example MCP config shape for an npm project:

{
  "command": "npm",
  "args": ["exec", "--", "backlog", "mcp"],
  "cwd": "/absolute/path/to/repository"
}

AI-First Update in a Repository

Ask your coding agent:

Update the local @augustalex/backlog dev dependency using this repository's package manager, rerun the local Backlog setup-agent command through the package manager, follow the printed instructions, and commit the package files plus refreshed AGENTS.md/.backlog changes.

Rerunning setup-agent after an update refreshes .backlog/AGENTS.md, the root AGENTS.md pointer, and printed MCP/setup guidance for the installed version.

Data Format

Backlog data is repository-local and intended to be committed:

.backlog/
  AGENTS.md
  tasks/
    task-0001-example.md
  images/
    <hash>-screenshot.png

Each task is a Markdown file with YAML frontmatter:

---
id: "task-0001-example"
title: "Example"
status: backlog
priority: 0
revision_of: null
images: []
created_at: "2026-06-08T10:00:00.000Z"
updated_at: "2026-06-08T10:00:00.000Z"
---

Task details in Markdown.

Comments are appended inside the task file. Images are stored under .backlog/images and tracked from task frontmatter.

Web UI

Start the web UI:

npm exec -- backlog start

The web UI opens at http://localhost:47321. It works against the current repository’s .backlog folder and includes a save button that commits only .backlog changes. The web UI is intended for humans; the primary product surface for agents is the repo-local CLI and MCP server.

MCP Tools

Run the repo-local MCP server from the repository root:

npm exec -- backlog mcp

The MCP server exposes:

• setup_instructions() - show repo-local setup and usage instructions.
• next_ticket() - select the highest-priority backlog task with full context.
• start_ticket(id) - mark a task in_progress.
• complete_ticket(id, summary) - add a summary comment and mark a task done.
• list_tickets(status?) - list tasks, optionally filtered by status.
• get_ticket(id) - get one task with comments, revision context, and attachment URIs.
• get_attachment(id) - retrieve a task image attachment.
• create_ticket(title, description, revision_of?) - create a backlog task.
• update_ticket(id, title?, description?, priority?, revision_of?) - update task content or metadata; use start_ticket and complete_ticket for workflow status changes.
• delete_ticket(id) - delete a task and unshared owned images.
• create_comment(id, content) - append an Agent-authored task comment without completing it.
• commit_backlog(message?) - commit only .backlog changes.
• open_ui() - open the web UI.

Agent workflow:

1. Fetch the next task with next_ticket.
2. If no task is returned, report that the backlog is empty.
3. Read the returned task, comments, revision context, and attachment metadata.
4. Start the task with start_ticket.
5. Complete the work and verify it.
6. Complete the task with complete_ticket, then call commit_backlog.

CLI

backlog setup
backlog setup-agent
backlog start
backlog mcp
backlog commit [message]
backlog delete --super <task-id>
backlog reset

backlog setup-agent is the AI setup command. Run it through the repository's package manager after installing the package as a dev dependency; the canonical post-setup commands are the package-manager local commands printed by setup.

backlog commit stages and commits only .backlog.

backlog delete --super <task-id> is CLI-only. It requires a clean worktree and attempts a git-history rewrite for the task file and owned image paths. Review remotes carefully before force-pushing rewritten history.