Backlog：面向 AI 编码代理的任务与上下文管理器

一款本地优先、供人类和 AI 共同使用的任务与上下文管理器。一个数据库，让你的编码代理直接读写。

网站 · 文档 · MCP 设置 · 更新日志

---

大多数 AI 编码代理在对话结束的那一刻就会丢失状态。它们的“记忆”是一个长达 50 万 token 的线程，既浪费订阅费用，第二天又会忘记项目内容。

Backlog 将任务队列和代理学到的所有内容从聊天中移出，放入一个 Backlog 数据库，让你的代理直接读写。任务、计划、文档和记忆都存储在一个 SQLite 文件中，由你的 CLI、Web UI 和所有代理共享。每条写入都会标记执行者（例如 human:alice、ai:claude-code、ai:semgrep），让你清楚知道谁做了什么。

最终形成了 代理循环：生成一个全新的子代理，加载项目上下文，获取一个任务，制定计划，执行任务，然后退出，接着再重复这一过程。四个并行会话，吞吐量约相当于一个开发者运行单个代理的 12 倍，每个任务的成本比长线程约低 10 倍。

一个队列。多个代理。每条写入都有归属。

---

获取适用于 macOS 或 Linux（arm64 和 amd64）的预编译二进制文件：

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -L https://github.com/mazen160/backlog/releases/latest/download/backlog_${OS}_${ARCH}.tar.gz | tar xz
sudo mv backlog /usr/local/bin/

或从源码安装：

go install github.com/mazen160/backlog/cmd/backlog@latest

这是一个单体二进制文件，无需任何依赖，也无需安装运行时。

---

一切运行在你的 Shell 中。backlog init 创建 Backlog DB。每条命令将写入归属到操作者。

backlog web 直接从同一个 Backlog DB 提供一个干净、可内联编辑的仪表盘。从 CLI 或 AI 代理创建的任务会立即显示在这里，并带有完整的归属信息。

将 Backlog 接入 Claude Code、Cursor、Codex 或 OpenCode。你的代理的写入会进入与你的 Shell 相同的数据库，并完全归属给执行它们的 AI。

---

一个循环就是一个工作单元：挑选 → 计划 → 执行 → 审查 → 归属。Backlog 存储队列，记录每一个步骤，并防止多个代理会话互相干扰。

每个任务生成一个全新的子代理，只加载它所需的上下文。平均会话可以控制在 5 万 token 以内，而不是长线程的 50 万 token。同样的质量，但成本大幅降低。

---

# 1. 在你的项目目录中创建工作区
backlog init

# 2. 添加项目
backlog project add "我的应用" --alias app

# 3. 创建一些任务
backlog task add -p app -t "修复登录超时" --type bug --priority P2
backlog task add -p app -t "添加速率限制" --type feature --priority P3

# 4. 查看待办
backlog task list

# 5. 开始处理 TASK-1
backlog task move TASK-1 --status doing

# 6. 附加版本化计划
backlog plan add --task TASK-1 --title "修复计划" \
  --content "1. 增加超时\n2. 添加测试"

# 7. 完成
backlog task move TASK-1 --status done

这就是整个工作流程，完全在你的机器上运行。无需创建账户，无需托管或付费服务。

一旦安装了技能（backlog install-skills），代理就可以直接从提示中执行相同的操作。在 Claude Code 中：

> 查看 app 中的开放任务，并开始处理最上面的一个

⏺ 我会检查开放任务并开始处理最上面的一个。

⏺ Bash(backlog task list -p app --status todo)
  ⎿  TASK-1  修复登录超时   bug   P2   todo
     TASK-2  添加速率限制   feat  P3   todo

⏺ Bash(backlog task move TASK-1 --status doing --as ai:claude-code)
  ⎿  ✓ TASK-1 → doing

⏺ Bash(backlog comment add --task TASK-1 "我接下这个任务，先复现超时问题。" --as ai:claude-code)
  ⎿  ✓ 已为 TASK-1 添加评论

⏺ 已开始 TASK-1（修复登录超时，P2）。现在正在复现超时。

详细的分步设置，请查看入门指南。

---

连接你的编码代理

backlog install-skills 会将一套现成的技能放入 Claude Code、Cursor、Codex 和 OpenCode。之后，你的代理可以通过 CLI 直接驱动 Backlog。无需运行服务器，无需配置 MCP。

它会安装以下技能：

技能	功能
backlog	核心循环：加载上下文，获取任务，制定计划，执行，并归属每条写入。
/backlog-memory	加载项目的任务、计划、文档和记忆到会话中（learn），或在工作完成后持久保存最新快照（store）。
/backlog-enhance-tasks	丰富简单工单的标题和描述，并起草计划。
/backlog-loop	获取最顶部的任务并不断优化，直到审查子代理认为它完成。
/backlog-goal	接受一个完整目标，将其拆分为工单，并从头到尾推动看板。

更偏好工具调用？Backlog 也支持 MCP。参见 MCP 服务器。

---

以下是 Backlog 中使用的词汇快速总览。完整细节见核心概念。

术语	定义
工作区（Workspace）	包含 backlog.db（以及 config.toml）的目录。所有项目、任务、计划和评论都存储在这个 SQLite 文件中。由 backlog init 创建。
配置文件（Profile）	指向工作区的命名指针，注册在 ~/.config/backlog/config.toml 中，这样你无需输入路径即可切换工作区。
项目（Project）	工作区内按名称组织的任务组，通过简短 别名（例如 api）标识。别名是你传递给 -p / --project 的参数。
任务（Task）	工作单元。拥有类型、状态、优先级和操作者；以 TASK-N 引用。
计划（Plan）	附加到任务的版本化 Markdown 文档。每次编辑都会创建一个新的不可变版本；完整历史可读。
评论（Comment）	追加式、带操作者属主的任务备注。
标签（Label）	用于筛选任务的每项目标签。
文档（Doc）	附加到 项目（而非任务）的版本化 Markdown 文档：Runbook、ADR、设计笔记。
记忆（Memory）	自由形式、可标记、可修改的备注，用于跨会话代理上下文。
操作者（Actor）	每条写入都标有 human:name 或 ai:name。
活动（Activity）	追加式工作区写入日志。

---

• 本地优先。 Backlog DB 位于你的代码旁边。随仓库提交，或不必（由你决定）。
• 单一二进制。 约 17 MB 的静态二进制，无需安装或保持其他东西运行。
• JIRA 风格引用。 任务为 TASK-1、TASK-2 等，终端中不会出现 UUID。
• 版本化计划。 每次计划编辑都会创建不可变版本。完整历史始终可读。
• 操作者归属。 每条写入均标有 human:name 或 ai:name。筛选、审计、追溯。
• 持久化项目上下文。 记忆、文档和计划存储在数据库中，全新的代理会话可加载完整画面，无需重新扫描代码库。
• 代理技能。 backlog install-skills 将现成技能放入 Claude Code、Cursor、Codex 和 OpenCode；你的代理无需额外配置即可驱动队列和自身记忆。
• MCP 服务器。 可选择通过 MCP 接入，适用于偏好工具调用的代理。
• 全文搜索。 backlog task list --search "injection*" 以毫秒级运行。
• 工作流健康报告。 backlog activity analyze 和 backlog doctor project 可揭示并行代理会话中的周期时间、停滞工作和弱关闭任务。
• 批量导入发现结果。 支持结构化 JSON 摄取，适配安全扫描器和 AI 代理。
• Web UI。 backlog web 从同一个 Backlog DB 提供简洁的仪表盘。
• 多种导出格式。 JSON、CSV 或 Markdown。
• HTTP API。 内嵌服务器，用于脚本和集成。
• 默认私密。 一切保留在你的机器上，Backlog 不会收集任何关于你的信息。

---

命令	描述
backlog init	创建 Backlog 工作区
backlog project add/list/show/update/archive	管理项目
backlog task add/list/show/update/move/archive	管理任务
backlog plan add/update/show/history	任务上的版本化计划
backlog comment add/list	任务评论
backlog label create/attach/detach	每项目标签
backlog memory add/list/append	跨会话项目记忆
backlog doc add/list/show/update/history	版本化项目文档
backlog attachment add/list/fetch/delete	附加到任务或文档的文件
backlog activity / activity analyze	审计跟踪与项目工作流健康报告
backlog doctor project	对某个项目进行停滞、孤立和弱关闭工作的诊断
backlog import-findings <file.json>	从扫描器/代理批量导入
backlog import <other.db>	合并另一个工作区
`backlog export --format json	csv
backlog sync	将 backlog.json 与数据库同步
backlog mcp serve	启动 MCP stdio 服务器（可选）
backlog install-skills	将代理技能安装到 Claude Code、Cursor、Codex、OpenCode
backlog web	启动 Web UI
`backlog doctor check	backup`
backlog schema	打印所有负载类型的 JSON Schema
backlog profile add/list/set-default	命名工作区快捷方式

完整参考：CLI 参考。

---

每条命令都接受 --as kind:name。如果不指定，操作者默认为 human:$USER。

backlog task add -p app -t "调查内存泄漏" --as human:alice

backlog plan add --task TASK-1 --title "内存分析计划" \
  --content "对 /api/v2/search 端点运行 pprof" \
  --as ai:claude-code

backlog task list --actor-kind ai
backlog task list --actor-name alice

Backlog DB 中的每一行都记录了写入它的操作者。审计成本为零。

---

技能是连接代理的最简单方式。如果你更倾向于 MCP 工具调用，Backlog 也可以作为 MCP 服务器运行。将任何兼容 MCP 的 AI 助手直接连接到你的待办事项：

backlog mcp serve --as ai:claude-code --db /path/to/backlog.db

Claude Code (~/.claude.json)：

{
  "mcpServers": {
    "backlog": {
      "command": "backlog",
      "args": ["mcp", "serve", "--as", "ai:claude-code"],
      "env": { "BACKLOG_DB": "/path/to/backlog.db" }
    }
  }
}

适用于 Cursor、Codex 和 OpenCode 的设置：MCP 指南。

---

安全扫描器和 AI 代理可以将结构化 JSON 文件写入并批量导入：

cat > findings.json << 'EOF'
{
  "version": 1,
  "project": "app",
  "items": [
    {
      "title": "/search 中的 SQL 注入",
      "type": "vulnerability",
      "priority": "P1",
      "source": "semgrep",
      "plans": [{ "title": "修复", "body": "使用参数化查询。" }]
    }
  ]
}
EOF

backlog import-findings findings.json --as ai:semgrep

每个发现结果都成为一个任务。每个任务都归属于发现它的扫描器。

---

当多个代理针对同一队列关闭任务时，一个空的待办列表并不意味着工作质量很高。两项只读报告可以告诉你实际情况：

# 这个项目在过去一周的趋势如何？
backlog activity analyze --project app --since 7d

按任务类型划分的周期时间、状态转换延迟（todo→doing，doing→done）、各操作者的在制品数量、重新打开的工作、错误跟进、标签变动以及人工与 AI 的关闭比例。一份报告，无需仪表盘。添加 --json 即可通过管道引入你自己的系统。

A local-first task and context manager for humans and AI. One database your coding agents read and write directly.

Website · Docs · MCP setup · Changelog

---

Most AI coding agents lose state the moment a chat ends. Their "memory" is a 500k-token thread that costs you a subscription and forgets the project the next morning.

Backlog moves the queue, and everything the agent learns, out of the chat and into a Backlog DB your agents read and write directly. Tasks, plans, docs, and memory live in one SQLite file that your CLI, your web UI, and every agent share. Every write is signed by the actor that made it (human:alice, ai:claude-code, ai:semgrep), so you always know who did what.

The result is the agentic loop : spawn a fresh subagent, let it load the project's context, pull a task, plan, ship, and exit, then do it again. Four parallel sessions, ~12× the throughput of one developer running one agent, ~10× cheaper per task than a long-running thread.

One queue. Many agents. Every write attributed.

---

Grab a pre-built binary for macOS or Linux (arm64 + amd64):

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -L https://github.com/mazen160/backlog/releases/latest/download/backlog_${OS}_${ARCH}.tar.gz | tar xz
sudo mv backlog /usr/local/bin/

Or install from source:

go install github.com/mazen160/backlog/cmd/backlog@latest

It's one binary with no dependencies and no runtime to install.

---

Everything runs from your shell.backlog init creates the Backlog DB. Every command attributes the write to the actor who made it.

backlog web serves a clean, inline-editable dashboard from the same Backlog DB. Tasks created from a CLI or an AI agent show up here instantly with full attribution.

Wire Backlog into Claude Code, Cursor, Codex, or OpenCode. Your agent's writes land in the same database your shell reads from, fully attributed to the AI that made them.

---

A loop is one unit of work: pick → plan → ship → review → attribute. Backlog stores the queue, attributes every step, and keeps multiple agent sessions from stepping on each other.

Each task spawns a fresh subagent with only the context it needs. The average session fits in under 50k tokens instead of the 500k a long-running thread bloats into. Same quality, dramatically cheaper.

---

# 1. Create a workspace in your project directory
backlog init

# 2. Add a project
backlog project add "My App" --alias app

# 3. Create some tasks
backlog task add -p app -t "Fix login timeout" --type bug --priority P2
backlog task add -p app -t "Add rate limiting" --type feature --priority P3

# 4. See what's open
backlog task list

# 5. Start working on TASK-1
backlog task move TASK-1 --status doing

# 6. Attach a versioned plan
backlog plan add --task TASK-1 --title "Fix plan" \
  --content "1. Increase timeout\n2. Add test"

# 7. Done
backlog task move TASK-1 --status done

That's the whole workflow, and it runs entirely on your machine. There's no account to create and no service to host or pay for.

Once the skills are installed (backlog install-skills), an agent does the same from a prompt. In Claude Code:

> show me the open tasks in app and start the top one

⏺ I'll check the open tasks and start the top one.

⏺ Bash(backlog task list -p app --status todo)
  ⎿  TASK-1  Fix login timeout   bug   P2   todo
     TASK-2  Add rate limiting   feat  P3   todo

⏺ Bash(backlog task move TASK-1 --status doing --as ai:claude-code)
  ⎿  ✓ TASK-1 → doing

⏺ Bash(backlog comment add --task TASK-1 "Picking this up. Reproducing the timeout first." --as ai:claude-code)
  ⎿  ✓ comment added to TASK-1

⏺ Started TASK-1 (Fix login timeout, P2). Reproducing the timeout now.

For step-by-step setup, see Getting Started.

---

Connect your coding agent

backlog install-skills drops a set of ready-made skills into Claude Code, Cursor, Codex, and OpenCode. From there your agent drives Backlog through the CLI directly. No server to run, no MCP to configure.

The skills it installs:

Skill	What it does
backlog	The core loop: load context, pick a task, plan, ship, and attribute every write.
/backlog-memory	Load a project's tasks, plans, docs, and memory into the session (learn), or persist a fresh snapshot when the work is done (store).
/backlog-enhance-tasks	Flesh out a thin ticket's title and description, and draft a plan.
/backlog-loop	Pull the top task and iterate on it until a reviewer sub-agent agrees it's done.
/backlog-goal	Take a whole goal, break it into tickets, and work the board end to end.

Prefer tool calls? Backlog also speaks MCP. See MCP server.

---

A quick glossary of the vocabulary used throughout Backlog. Full detail in Core Concepts.

Term	What it is
Workspace	A directory holding a backlog.db (and a config.toml). Every project, task, plan, and comment lives in that one SQLite file. Created by backlog init.
Profile	A named pointer to a workspace, registered in ~/.config/backlog/config.toml, so you can switch workspaces without typing paths.
Project	A named group of tasks inside a workspace, identified by a short alias (e.g. api). The alias is what you pass to -p / --project.
Task	The unit of work. Has a type, status, priority, and actor; addressed as TASK-N.
Plan	A versioned markdown document attached to a task. Every edit creates a new immutable version; the full history stays readable.
Comment	An append-only, actor-attributed note on a task.
Label	A per-project tag for filtering tasks.
Doc	A versioned markdown document attached to a project (not a task): runbooks, ADRs, design notes.
Memory	A free-form, taggable, mutable note for cross-session agent context.
Actor	The human:name or ai:name attributed to every write.
Activity	An append-only log of every write across the workspace.

---

• Local-first. The Backlog DB sits next to your code. Commits with your repo, or doesn't (your call).
• Single binary. A ~17 MB static binary with nothing else to install or keep running.
• JIRA-style refs. Tasks are TASK-1, TASK-2, … No UUIDs in your terminal.
• Versioned plans. Every plan edit creates an immutable version. Full history is always readable.
• Actor attribution. Every write is signed human:name or ai:name. Filter, audit, blame.
• Persistent project context. Memory, docs, and plans live in the DB, so a fresh agent session loads the full picture instead of re-reading the codebase.
• Agent skills. backlog install-skills drops ready-made skills into Claude Code, Cursor, Codex, and OpenCode; your agent drives the queue and its own memory with no extra wiring.
• MCP server. Optionally plug in over MCP, for agents that prefer tool calls.
• Full-text search. backlog task list --search "injection*" runs in milliseconds.
• Workflow health reports. backlog activity analyze and backlog doctor project surface cycle time, stale work, and weakly-closed tasks across parallel agent sessions.
• Bulk findings import. Structured JSON intake for security scanners and AI agents.
• Web UI. backlog web serves a clean dashboard from the same Backlog DB.
• Export anywhere. JSON, CSV, or Markdown.
• HTTP API. Embedded server for scripts and integrations.
• Private by default. Everything stays on your machine, and Backlog collects nothing about you.

---

Command	Description
backlog init	Create a Backlog workspace
backlog project add/list/show/update/archive	Manage projects
backlog task add/list/show/update/move/archive	Manage tasks
backlog plan add/update/show/history	Versioned plans on tasks
backlog comment add/list	Comments on tasks
backlog label create/attach/detach	Per-project labels
backlog memory add/list/append	Cross-session project memory
backlog doc add/list/show/update/history	Versioned project docs
backlog attachment add/list/fetch/delete	Files attached to tasks or docs
backlog activity / activity analyze	Audit trail and project workflow-health report
backlog doctor project	Lint a project for stale, orphaned, and weakly-closed work
backlog import-findings <file.json>	Bulk import from scanners/agents
backlog import <other.db>	Merge another workspace
`backlog export --format json	csv
backlog sync	Reconcile backlog.json with DB
backlog mcp serve	Start MCP stdio server (optional)
backlog install-skills	Install agent skills into Claude Code, Cursor, Codex, OpenCode
backlog web	Serve the web UI
`backlog doctor check	backup`
backlog schema	Print JSON Schema for all payload types
backlog profile add/list/set-default	Named workspace shortcuts

Full reference: CLI Reference.

---

Every command accepts --as kind:name. Without it, the actor defaults to human:$USER.

backlog task add -p app -t "Investigate memory leak" --as human:alice

backlog plan add --task TASK-1 --title "Memory profiling plan" \
  --content "Run pprof on /api/v2/search endpoint" \
  --as ai:claude-code

backlog task list --actor-kind ai
backlog task list --actor-name alice

Every row in the Backlog DB carries the actor that wrote it. Audit trails are free.

---

Skills are the simplest way to connect an agent. If you'd rather use MCP tool calls, Backlog also runs as an MCP server. Connect any MCP-compatible AI assistant directly to your backlog:

backlog mcp serve --as ai:claude-code --db /path/to/backlog.db

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "backlog": {
      "command": "backlog",
      "args": ["mcp", "serve", "--as", "ai:claude-code"],
      "env": { "BACKLOG_DB": "/path/to/backlog.db" }
    }
  }
}

Setup for Cursor, Codex, and OpenCode: MCP guide.

---

Security scanners and AI agents can write a structured JSON file and bulk-import:

cat > findings.json << 'EOF'
{
  "version": 1,
  "project": "app",
  "items": [
    {
      "title": "SQL injection in /search",
      "type": "vulnerability",
      "priority": "P1",
      "source": "semgrep",
      "plans": [{ "title": "Fix", "body": "Use parameterized queries." }]
    }
  ]
}
EOF

backlog import-findings findings.json --as ai:semgrep

Every finding becomes a task. Every task is attributed to the scanner that found it.

---

When several agents are closing tasks against the same queue, an empty backlog doesn't mean the work was done well. Two read-only reports tell you whether it actually was:

# How is this project trending over the last week?
backlog activity analyze --project app --since 7d

Cycle time by task type, status-transition latency (todo→doing, doing→done), WIP by actor, reopened work, bug follow-ups, label churn, and the human-vs-AI close ratio. One report, no dashboard required. Add --json to pipe it into your own.

# What did the agents close badly?
backlog doctor project --project app

Flags stale doing tasks, tasks created but never started, tasks closed with no plan or completion evidence, and final-audit tasks marked done while earlier work is still open. Every issue carries a severity, a code, and the evidence behind it, so the next agent (or you) can fix it instead of rediscovering it.

---

Page	Description
Getting Started	Install, init, first task, plans, agent skills
Core Concepts	Workspaces, projects, tasks, plans, actors, profiles
CLI Reference	Every command and flag with examples
MCP	Wire into Claude Code, Cursor, Codex, OpenCode
Skills	The five embedded agentic-loop skills
HTTP API	Routes exposed by backlog web
Working Across Sessions	Three-day cross-session walkthrough

---

git clone https://github.com/mazen160/backlog
cd backlog
make build      # build binary
make test       # run all tests
make fmt        # gofmt
make vet        # go vet
make cover      # test + coverage report

See CONTRIBUTING.md for the full guide.

---

If Backlog saves you a context window, please star the repo. It's the only signal that tells me to keep building it in the open.

Share what you build:

---

The Backlog DB is an embedded SQLite store with WAL mode, full-text search (FTS5), and atomic backups. Backlog itself is written in Go and ships as a single static binary.

---

The project is currently licensed under MIT License.

---

Mazin Ahmed