<img src="./.github/5-minute-tour-256.png" alt="Getting started" width="28" height="28" align="center"> Getting started

```bash

Install

npm i -g backlog.md

or: brew install backlog-md

Client guides

<details> <summary><strong>Claude Code</strong></summary>

  claude mcp add backlog --scope user -- backlog mcp start
  

</details>

<details> <summary><strong>Codex</strong></summary>

  codex mcp add backlog -- backlog mcp start
  

</details>

<details> <summary><strong>Gemini CLI</strong></summary>

  gemini mcp add backlog -s user backlog mcp start
  

</details>

<details> <summary><strong>Kiro</strong></summary>

  kiro-cli mcp add --scope global --name backlog --command backlog --args mcp,start
  

</details>

<details> <summary><strong>Cursor / other MCP clients</strong></summary>

Use the manual JSON config below in your client's MCP settings.

</details>

Use the shared backlog server name everywhere. The server finds the active project from your client's MCP roots, and re-resolves when you switch workspace or worktree. A single user-scope server covers every repo.

<details> <summary><strong>Manual config</strong></summary>

{
  "mcpServers": {
    "backlog": {
      "command": "backlog",
      "args": ["mcp", "start"],
      "env": {
        "BACKLOG_CWD": "/absolute/path/to/your/project"
      }
    }
  }
}

Set BACKLOG_CWD to pin the server to one project and stop workspace following. Use it to always target the same backlog, or when your client can't report MCP roots. If your IDE supports custom args but not env vars, you can also use ["mcp", "start", "--cwd", "/absolute/path/to/your/project"]. Until the server finds an initialized project, it serves backlog://init-required.

</details>

[!IMPORTANT] When adding the MCP server manually, add a short instruction to your CLAUDE.md/AGENTS.md files telling agents to read backlog://workflow/overview. This step is not required when using backlog init as it adds these instructions automatically. For CLI-based setups, use backlog instructions overview to fetch the current workflow guidance.

Once connected, agents can read the Backlog.md workflow instructions via backlog://workflow/overview, with detailed guides at backlog://workflow/task-creation, backlog://workflow/task-execution, and backlog://workflow/task-finalization. Use /mcp command in your AI tool (Claude Code, Codex, Kiro) to verify if the connection is working.

---

<img src="./.github/configuration-256.png" alt="Configuration" width="28" height="28" align="center"> Configuration

Backlog.md works with zero configuration. Settings merge from CLI flags, then the project config file (backlog.config.yml when present, otherwise backlog/config.yml or .backlog/config.yml), then built‑in defaults.

Run backlog config with no arguments to launch the interactive wizard (the same experience triggered from backlog init advanced setup). It walks through cross-branch accuracy (checkActiveBranches, remoteOperations, activeBranchDays), Git workflow (autoCommit, bypassGitHooks), ID formatting (zeroPaddedIds), editor integration (defaultEditor), Definition of Done defaults, and Web UI defaults (defaultPort, autoOpenBrowser). Skipping the wizard applies the safe built-in defaults, and rerunning backlog init or backlog config pre-populates prompts with your current values.

For filesystem-only projects (backlog init --no-git), the saved config forces checkActiveBranches=false, remoteOperations=false, and autoCommit=false so CLI, Web, and MCP local-file workflows do not depend on a Git repository.

<img src="./.github/web-interface-256.png" alt="Web Interface" width="28" height="28" align="center"> Web Interface

Launch a web interface for visual task management on the local machine. The server listens on 127.0.0.1 and is not reachable from other devices on the LAN or VPN:

```bash

<img src="./.github/cli-reference-256.png" alt="CLI Reference" width="28" height="28" align="center"> CLI reference

Full command reference covering task management, search, board, docs, decisions, and more: CLI-INSTRUCTIONS.md

Quick examples: backlog, backlog instructions, backlog task create, backlog task list, backlog task edit, backlog milestone add, backlog milestone rename, backlog milestone remove, backlog search, backlog board, backlog browser.

Full help: backlog --help

---

🔧 MCP Integration (Model Context Protocol)

CLI instructions are the default AI setup. MCP remains supported for AI coding assistants like Claude Code, Codex, Gemini CLI and Kiro when you explicitly prefer an MCP connector. You can run backlog init (even if you already initialized Backlog.md) and choose MCP integration, or follow the manual steps below.

Troubleshooting