Backlog CLI

Track project work using simple CLI and AI assistance. Organize tasks, epics, bugs, and debt across domains, with seamless local AI integration.

A comprehensive CLI tool and MCP server for managing project backlogs. Works standalone via command line or integrates directly with AI tools like Claude Code, Codex, Cursor, Windsurf, and any MCP-compatible client.

Skip to Quick Setup

Key Advantages

Simplicity: Zero-config initialization with smart defaults Organization: Domain-based structure keeps work discoverable Flexibility: Support for tasks, epics, bugs, features, and technical debt AI-Native: 10 MCP tools enable AI agents to manage backlogs directly

Simple Setup & Operation

• One command init - backlog init creates everything you need
• Smart ID generation - Type-prefixed sequential IDs (SUB-TASK-0001, SUB-BUG-0001)
• Subdirectory-friendly - Run from anywhere in your repo, auto-finds .backlog/
• Git-aware user identity - Auto-detects your name/email for assignments

Flexible Work Item Types

• Tasks - Standard work items for implementation
• Epics - Large initiatives that group related work
• Bugs - Issues that need fixing
• Features - New functionality requests
• Debt - Technical debt and refactoring work

Kanban-Style Workflow

• Status lifecycle - backlog → ready → in-progress → review → done
• Blocking support - Mark items as blocked with reason
• Story points - Fibonacci estimation (1, 2, 3, 5, 8, 13, 21)
• Epic relationships - Link items to parent epics

AI Agent Integration

• 10 MCP tools - Complete CRUD + workflow operations for AI agents
• Works with any MCP client - Claude Code, Codex, Cursor, Windsurf, Cline, etc.
• AGENTS.md generation - Auto-generated summary for AI context
• User identity management - Configured assignee used automatically by AI

Complete Feature Set

Core Backlog Management

• Create items interactively or programmatically with templates
• List and filter by type, status, domain, priority, or assignee
• Search across all items with relevance scoring
• Show full item details with frontmatter and content
• Update fields via MCP (backlog_update) or by editing frontmatter directly (CLI backlog update is not implemented)

Status Workflow

• Start - Begin work (backlog/ready → in-progress, sets started_at)
• Done - Complete work (sets completed_at, clears blocked)
• Block/Unblock - Mark items as blocked with reason
• Assign - Set or clear item assignee

Organization & Discovery

• Domain-based folders - Group by area (auth, frontend, backend, etc.)
• Type-specific templates - Different templates for tasks, bugs, epics
• Epic hierarchy - Link items to parent epics via epic_id
• Relationship graph - Visualize epic/related connections (ASCII, DOT, JSON)

Configuration & Validation

• Customizable ID format - PRJ-TASK-0001, SUB-BUG-0001, etc.
• Priority levels - low, medium, high, critical
• Fibonacci points - 1, 2, 3, 5, 8, 13, 21
• Validation rules - Check for missing sections, blocked without reason

Working with AI Agents

Backlog CLI is designed for seamless AI collaboration. Once configured, you can ask your AI assistant to manage backlog items using natural language.

Why Use AI for Backlog Management?

• Faster documentation - AI creates items from conversation context
• Consistent format - AI follows templates automatically
• Instant search - AI finds relevant items before suggesting work
• Automatic relationships - AI links related items and epics
• Work estimation - AI can suggest story points based on scope

Natural Language Examples

Once the MCP server is configured, you can simply ask:

Creating items:

"Create a task to implement user authentication in the auth domain"

"Add a bug for the login button not working on mobile"

"Create an epic for the new payment system with 3 child tasks"

"Add some tech debt for refactoring the database queries"

Querying items:

"What tasks are in progress?"

"Show me all high-priority bugs"

"What items are blocked right now?"

"List all tasks under the payment epic"

Updating items:

"Start working on task 1"

"Mark bug 3 as done"

"Block task 5 because we're waiting for the API spec"

"Assign all auth tasks to me"

Workflow management:

"What should I work on next?"

"How many story points are in the current sprint?"

"Show me items that have been in review for too long"

The AGENTS.md Summary

The AGENTS.md file is a special summary designed specifically for AI agents. It provides:

Instant Context

• Complete catalog of all items organized by domain
• Status overview (how many in-progress, blocked, done)
• Recent items for quick reference

AI-Optimized Format

• Structured for fast parsing by language models
• Includes epic relationships and blocked status
• Tags and metadata for semantic search

Always Current

• Regenerate anytime with backlog summary
• Only updates when items actually change (unless --force)
• Tracks last generation timestamp

How AI Uses AGENTS.md

When you ask an AI assistant about your project's backlog:

1. AI reads .backlog/AGENTS.md for complete item context
2. AI understands what work is planned, in progress, or blocked
3. AI avoids suggesting duplicate work
4. AI references relevant items when discussing features

Example AGENTS.md content:

# Backlog Summary

> Auto-generated summary for AI agents. Last updated: 2024-01-30T10:30:00Z

## Overview

- **Total items:** 23
- **Backlog:** 10
- **In Progress:** 5
- **Blocked:** 2
- **Done:** 6

## By Domain

### auth (5 items)

- [SUB-TASK-0001] Implement JWT authentication (in-progress) [8 pts]
- [SUB-BUG-0002] Fix session timeout issue (ready) [3 pts]
- [SUB-EPIC-0001] OAuth integration (backlog)
  ...

### backend (8 items)

- [SUB-TASK-0003] Add caching layer (in-progress) [5 pts]
- [SUB-DEBT-0001] Refactor database queries (backlog) [13 pts]
  ...

## Quick Reference

| ID            | Title                        | Type | Status      | Priority |
| ------------- | ---------------------------- | ---- | ----------- | -------- |
| SUB-TASK-0001 | Implement JWT authentication | task | in-progress | high     |
| SUB-BUG-0002  | Fix session timeout issue    | bug  | ready       | critical |

...

## Blocked Items

- SUB-TASK-0005: Waiting for API specification
- SUB-BUG-0003: Depends on infrastructure team

Generating the Summary

# Generate/update AGENTS.md
backlog summary

# Force regeneration (updates timestamp even if unchanged)
backlog summary --force

Via MCP:

{ "name": "backlog_summary", "arguments": { "force": true } }

Best Practices for AI Collaboration

1. Initialize user identity first

   backlog user setup

   This ensures AI-created assignments use your real name/email.

2. Keep AGENTS.md in version control The summary helps all team members' AI assistants stay consistent.

3. Reference items in prompts "According to SUB-EPIC-0001, we need OAuth. How should we start?"

4. Let AI validate before starting work Ask: "Validate all blocked items and show missing reasons"

5. Use domains consistently Well-organized domains help AI find relevant context faster.

Quick Setup

Prerequisites

• Node.js >= 20.19.0

Installation

Using npx (no install required):

# Runs the `backlog-cli` binary from the `backlog-cli` package
npx backlog-cli init
npx backlog-cli new task
npx backlog-cli list

Global installation:

npm install -g backlog-cli

# Now use 'backlog' command anywhere
backlog init
backlog new task
backlog list

Initialize Your Project

# Initialize with auto-detected prefix from package.json
backlog init

# Or specify a custom prefix
backlog init --prefix PRJ

This creates:

.backlog/
├── config.yaml           # Configuration
├── templates/
│   ├── task.md           # Task template
│   ├── epic.md           # Epic template
│   ├── bug.md            # Bug template
│   ├── feature.md        # Feature template
│   └── debt.md           # Tech debt template
└── general/              # Default domain folder

Configure User Identity

Set up your identity for item assignments:

# Auto-detect from git config
backlog user setup

# Or specify manually
backlog user setup --name "Your Name" --email "[email protected]"

CLI Usage

Creating Items

# Interactive mode (prompts for details)
backlog new task

# Non-interactive with options
backlog new task --title "Implement login" --domain auth --priority high

# Create different types
backlog new epic --title "Payment System"
backlog new bug --title "Button not clickable"
backlog new feature --title "Dark mode support"
backlog new debt --title "Refactor API layer"

# With story points and epic
backlog new task --title "Add validation" --points 5 --epic SUB-EPIC-0001

Listing & Viewing

# List all items
backlog list

# Filter by status
backlog list --status in-progress

# Filter by type
backlog list --type bug

# Filter by domain
backlog list --domain auth

# Filter by priority
backlog list --priority high

# Show blocked items
backlog list --blocked

# Show specific item (by ID or number)
backlog show 1
backlog show SUB-TASK-0001

# Search across all items
backlog search "authentication"

Status Workflow

# Start working on an item
backlog start 1

# Mark as done
backlog done 1

# Block with reason
backlog block 1 --reason "Waiting for API spec"

# Unblock
backlog unblock 1

# Assign to someone
backlog assign 1 "John Doe"

# Clear assignment
backlog unassign 1

Updating Items

backlog update is not implemented yet. For now, edit the item’s markdown frontmatter directly.

Relationships

# View relationship graph
backlog graph
backlog graph --format dot  # For GraphViz
backlog graph --format json # For programmatic use

Validation & Summary

# Validate all items
backlog validate

# Validate specific item
backlog validate --id 1

# Generate AGENTS.md summary
backlog summary

# Force regeneration
backlog summary --force

MCP Integration

The MCP server allows AI tools to manage backlog items directly through the Model Context Protocol. The server exposes 10 tools over stdio transport.

Starting the MCP Server

# Global install
backlog mcp

# Using npx (no install required)
npx backlog-cli mcp

Claude Code

# Add MCP server (recommended — uses npx, no global install needed)
claude mcp add backlog -- npx backlog-cli mcp

# Or if installed globally
claude mcp add backlog -- backlog mcp

# Verify it's registered
claude mcp list

# Remove when no longer needed
claude mcp remove backlog

Once added, just talk to Claude naturally:

You: "Create a task to add dark mode support in the frontend domain"
You: "What bugs are currently in progress?"
You: "Mark task 3 as done"

Codex (OpenAI)

# Add MCP server
codex mcp add backlog -- npx backlog-cli mcp

# Or if installed globally
codex mcp add backlog -- backlog mcp

# Verify
codex mcp list

Then use naturally in your Codex sessions:

You: "List all high-priority items in the auth domain"
You: "Create a bug report for the broken login flow"

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": ["backlog-cli", "mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "backlog": {
      "command": "backlog",
      "args": ["mcp"]
    }
  }
}

Cursor / Windsurf / Cline / Other MCP Clients

Most MCP clients use the same JSON configuration format. Add to your MCP settings:

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": ["backlog-cli", "mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Key settings for any MCP client:

• Command: npx (or backlog if installed globally)
• Args: ["backlog-cli", "mcp"] (or ["mcp"] if global)
• CWD: Your project root (where .backlog/ exists or should be created)

Available MCP Tools

| Tool | Description | | -------------------- | -------------------------------------------------- | | backlog_list | List items with optional type/status/domain filter | | backlog_get | Get item by ID (full or numeric shorthand) | | backlog_create | Create new item (non-interactive) | | backlog_update | Update frontmatter and/or content | | backlog_search | Search by free-text query | | backlog_summary | Generate/update AGENTS.md | | backlog_validate | Validate items and return issues | | backlog_graph | Get relationship graph (JSON or DOT) | | backlog_user_setup | Configure user identity for assignments | | backlog_user_show | Display current user configuration |

MCP Tool Examples

List in-progress tasks:

{ "name": "backlog_list", "arguments": { "status": "in-progress", "type": "task" } }

Create a new bug:

{
  "name": "backlog_create",
  "arguments": {
    "title": "Login button unresponsive on mobile",
    "type": "bug",
    "domain": "frontend",
    "priority": "high",
    "content": "## Description\n\nThe login button does not respond to taps on iOS Safari...\n\n## Steps to Reproduce\n\n1. Open app on iPhone\n2. Navigate to login page\n3. Tap login button\n\n## Expected Behavior\n\nButton should trigger login flow"
  }
}

Start working on an item:

{
  "name": "backlog_update",
  "arguments": { "id": "1", "status": "in-progress" }
}

Block an item:

{
  "name": "backlog_update",
  "arguments": {
    "id": "1",
    "blocked": true,
    "blocked_reason": "Waiting for API spec"
  }
}

Item Record Format

Items are stored as Markdown files with YAML frontmatter:

---
id: SUB-TASK-0001
title: Implement JWT Authentication
type: task
status: in-progress
domain: auth
priority: high
points: 8
tags: [security, api]
epic_id: SUB-EPIC-0001
assignee: John Doe
blocked: false
created_at: 2024-01-28T10:00:00.000Z
started_at: 2024-01-29T09:00:00.000Z
---

## Description

Implement JWT-based authentication for the API...

## Context

We need stateless authentication for horizontal scaling...

## Acceptance Criteria

- [ ] JWT tokens issued on login
- [ ] Tokens validated on protected routes
- [ ] Refresh token mechanism implemented

Item Types

| Type | ID Format | Use Case | | ------- | ------------- | ------------------------------- | | task | SUB-TASK-0001 | Standard implementation work | | epic | SUB-EPIC-0001 | Large initiatives grouping work | | bug | SUB-BUG-0001 | Issues that need fixing | | feature | SUB-FEAT-0001 | New functionality requests | | debt | SUB-DEBT-0001 | Technical debt and refactoring |

Status Lifecycle

backlog → ready → in-progress → review → done
              ↑_________________|
           (can move back)

Items can also be blocked at any status (except done).

Priority Levels

• low - Can wait, nice to have
• medium - Normal priority (default)
• high - Should be done soon
• critical - Needs immediate attention

Story Points (Fibonacci)

• 1 - Trivial, few hours
• 2 - Small, less than a day
• 3 - Medium, about a day
• 5 - Large, a few days
• 8 - Very large, about a week
• 13 - Epic-sized, needs breakdown
• 21 - Too large, must be broken down

Folder Structure

.backlog/
├── config.yaml           # Project configuration
├── user.yaml             # User identity (git-ignored)
├── AGENTS.md             # Auto-generated AI summary
├── templates/
│   ├── task.md           # Task template
│   ├── epic.md           # Epic template
│   ├── bug.md            # Bug template
│   ├── feature.md        # Feature template
│   └── debt.md           # Tech debt template
├── auth/                 # Domain: auth
│   ├── SUB-TASK-0001-jwt-auth.md
│   └── SUB-BUG-0002-session-timeout.md
├── frontend/             # Domain: frontend
│   └── SUB-FEAT-0001-dark-mode.md
├── backend/              # Domain: backend
│   └── SUB-DEBT-0001-refactor-queries.md
└── general/              # Default domain
    └── SUB-EPIC-0001-payment-system.md

Configuration Reference

.backlog/config.yaml:

version: 1
project-name: my-project
id-prefix: SUB
domains:
  - auth
  - frontend
  - backend
  - general
default-domain: general
types:
  - task
  - epic
  - bug
  - feature
  - debt
statuses:
  - backlog
  - ready
  - in-progress
  - review
  - done
priorities:
  - low
  - medium
  - high
  - critical
default-status: backlog
default-priority: medium
templates:
  task: templates/task.md
  epic: templates/epic.md
  bug: templates/bug.md
  feature: templates/feature.md
  debt: templates/debt.md
summary:
  auto-generate: false
  include-recent: 10

Configuration Options

| Key | Description | Default | | ------------------ | --------------------------- | --------------------------------------------- | | project-name | Project identifier | From package.json | | id-prefix | Prefix for all IDs | SUB | | domains | Available domain categories | [general] | | default-domain | Domain when not specified | general | | types | Available item types | [task, epic, bug, feature, debt] | | statuses | Available status values | [backlog, ready, in-progress, review, done] | | priorities | Available priority levels | [low, medium, high, critical] | | default-status | Status for new items | backlog | | default-priority | Priority for new items | medium | | templates | Template file paths by type | - |

Development

npm install
npm run build
node bin/backlog.js --help

npm run build        # Build TypeScript
npm run dev          # Watch mode
npm test             # Run tests
npm run test:watch   # Tests in watch mode
npm run lint         # Lint code
npm run check        # Lint + type check

Local Testing

npm link
backlog --help       # Now available globally
npm unlink -g backlog-cli  # When done

License

MIT - see LICENSE

Created by Kurdin