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

```bash

Install

bun 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>

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. Until it finds one, it serves backlog://init-required. A single user-scope server covers every repo.

Manual config

{
  "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"].

[!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 merges the following layers (highest → lowest):

1. CLI flags 2. Project config file: - backlog.config.yml when present - otherwise backlog/config.yml or .backlog/config.yml 3. Built‑ins

Interactive wizard (`backlog config`)

Run backlog config with no arguments to launch the full interactive wizard. This is the same experience triggered from backlog init when you opt into advanced settings, and it walks through the complete configuration surface: - Cross-branch accuracy: checkActiveBranches, remoteOperations, and activeBranchDays. - Git workflow: autoCommit and bypassGitHooks. - ID formatting: enable or size zeroPaddedIds. - Editor integration: pick a defaultEditor with availability checks. - Definition of Done defaults: interactively add/remove/reorder/clear project-level definition_of_done checklist items. - Web UI defaults: choose defaultPort and whether autoOpenBrowser should run.

Skipping the wizard (answering "No" during init) applies the safe defaults that ship with Backlog.md: - checkActiveBranches=true, remoteOperations=true, activeBranchDays=30. - autoCommit=false, bypassGitHooks=false. - zeroPaddedIds disabled. - defaultEditor unset (falls back to your environment). - defaultPort=6420, autoOpenBrowser=true.

For filesystem-only projects, run backlog init --no-git. Backlog.md will not run git init, and 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.

Whenever you revisit backlog init or rerun backlog config, the wizard pre-populates prompts with your current values so you can adjust only what changed.

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

Launch a modern, responsive web interface for visual task management:

```bash

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

Full command reference — 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.