Backlog Board with Global AI MCP Server

A minimalist backlog tracking system for developers and local AI agents. It runs as a globally installed tool, keeps a registry of projects on your machine, and gives each registered project its own SQLite backlog database.

Built with Bun + Vite + SolidJS + Tailwind CSS v4 + SQLite (bun:sqlite) + ElysiaJS.

Development

Install dependencies:

bun install

Run the API and SolidJS dashboard in watch mode:

bun run dev

Build the package:

bun run build

Install on Your Machine

This tool requires Bun.

bun --version

Install Bun if needed:

curl -fsSL https://bun.sh/install | bash

Install Backlog globally with npm:

npm install -g @augustalex/backlog

Ask your coding agent to finish setup:

Install `@augustalex/backlog` globally with npm, then run `backlog setup-agent` and follow its instructions.

Or run the setup guide yourself:

backlog setup-agent

setup-agent creates/verifies the global backlog home at ~/.backlog, writes global AI instructions, detects supported local AI apps, and prints exact next steps. By default it is guide-first and does not edit third-party app configs.

After reviewing the plan, apply supported AI app setup:

backlog setup-agent --apply --apps core

This registers the current repository, backs up files before editing them, configures supported detected MCP clients, and tells you what to restart. Use backlog doctor --json and backlog mcp-smoke-test to verify setup.

Configure AI Apps Globally

Project-local MCP configs are unreliable across current AI apps. Configure one global MCP server per app instead. backlog setup-agent --apply --apps core supports Codex, Claude Code, and Google Antigravity where they are detected.

Use the JSON printed by backlog init or backlog setup-agent, or add an equivalent global MCP entry:

{
  "mcpServers": {
    "project-backlog": {
      "command": "node",
      "args": ["/absolute/path/to/@augustalex/backlog/dist/mcp-node-wrapper.cjs"]
    }
  }
}

After that, agents can use setup_instructions, list_projects, get_current_project, and select_project before using ticket tools.

Add a Repository as a Project

From the repository root:

backlog add-project

Or name it explicitly:

backlog add-project --name "My App"

This registers the repository in the global project registry, creates that project's database under ~/.backlog/projects/<project-id>/backlog.db, updates AGENTS.md with backlog instructions, and adds a .agents/skills/project-backlog/SKILL.md skill when the repository already uses .agents/skills.

Useful project commands:

backlog list-projects
backlog select-project <id|name|absolute-path>

Dashboard

Start the dashboard:

backlog start

The dashboard opens at http://localhost:18284 and includes a project selector for registered projects.

MCP Tools

The global project-backlog MCP server exposes:

• setup_instructions() - show setup guidance and structured setup status.
• upgrade_instructions() - show instructions to upgrade the global backlog package.
• get_agent_workflows() - retrieve the recommended agent automation prompts and loop workflows (Solve 1, Solve all, Continuous mode).
• list_projects() - list registered projects.
• get_current_project() - show the active project.
• select_project(identifier) - select by project id, exact name, or absolute path.
• list_tickets(status?) - list tickets, optionally filtered by status.
• get_ticket(id) - get one ticket with comments and revision source context.
• create_ticket(title, description, status?, revision_of_ticket_id?) - create a ticket.
• update_ticket(id, title?, description?, status?, priority?, revision_of_ticket_id?) - update a ticket.
• delete_ticket(id) - delete a ticket.
• list_comments(ticket_id) - list ticket comments.
• create_comment(ticket_id, author, content) - add a ticket comment.
• open_dashboard() - open the web dashboard.

Agent workflow:

1. Call get_current_project.
2. If needed, call select_project with the repository path, id, or name.
3. Pick the highest-priority backlog ticket.
4. If the ticket has revision_of_ticket_id, call get_ticket and read the included source ticket and source comments before implementing.
5. Set the ticket to in_progress and complete the work.
6. When complete, set it to done and add a summary comment.

Data Location

Backlog stores global config and project databases in ~/.backlog by default.

For tests or custom setups, set:

BACKLOG_HOME=/path/to/backlog-home

BACKLOG_DB_PATH is still supported as an override for one-off database targeting.