backlog

Persistent, cross-session task management for Claude Code. Tasks survive sessions so work started by one agent can be picked up by another.

Built on @backloghq/agentdb — typed schemas, auto-increment IDs, virtual filters, blob storage. Pure TypeScript, zero native dependencies.

Install

/plugin marketplace add backloghq/backlog
/plugin install backlog@backloghq-backlog

From source

git clone https://github.com/backloghq/backlog.git
cd backlog && npm install && npm run build
claude --plugin-dir /path/to/backlog

Standalone MCP server

Add to your project's .claude/settings.json:

{
  "mcpServers": {
    "backlog": {
      "command": "node",
      "args": ["/path/to/agent-teams-task-mcp/dist/index.js"],
      "env": {
        "TASKDATA": "/path/to/task-data"
      }
    }
  }
}

Skills

Agent

The task-planner agent can be auto-invoked by Claude when someone needs to plan work. It reads the codebase, decomposes goals into tasks with dependencies, and writes specs for complex items.

Hooks

Tools (MCP)

Tools for full task lifecycle management:

Filter Syntax

status:pending                    # all pending tasks
project:backend +bug              # bugs in backend project
priority:H due.before:friday      # high priority due before friday
+OVERDUE                          # overdue tasks
+ACTIVE                           # tasks currently being worked on
+BLOCKED                          # tasks blocked by dependencies
+READY                            # actionable tasks (past scheduled date)
agent:explorer                    # tasks assigned to the explorer agent
( project:web or project:api )    # boolean with parentheses
description.contains:auth         # substring match

Supports attribute modifiers (.before, .after, .by, .has, .not, .none, .any, .startswith, .endswith), tags (+tag, -tag), virtual tags (+OVERDUE, +ACTIVE, +BLOCKED, +READY, +TAGGED, +ANNOTATED, etc.), and boolean operators (and, or).

Task Docs

Attach markdown documents (specs, context, handoff notes) to any task:

task_doc_write  id:"1"  content:"# Spec\n\nBuild the auth flow.\n"
task_doc_read   id:"1"
task_doc_delete id:"1"

Writing a doc adds a +doc tag and has_doc:yes, so agents can discover tasks with docs:

task_list filter:"+doc"
task_list filter:"has_doc:yes"

Agent Identity

Tasks support an agent field for tracking which agent owns a task:

task_add  description:"Investigate bug"  agent:"explorer"
task_list filter:"agent:explorer status:pending"

Project Isolation

Each project gets its own task data automatically. When used as a plugin, task data lives in ~/.claude/plugins/data/backlog/projects/<project-slug>/. When used standalone, set TASKDATA explicitly.

Multi-Writer Support

Backlog supports concurrent access from multiple processes (e.g., Claude Desktop and Gemini CLI) sharing the same data. To enable this:

1. Assign a unique BACKLOG_AGENT_ID to each process (e.g., claude, gemini).
2. When an agent ID is set, the engine uses per-agent write logs, avoiding file locks.
3. Each process automatically calls refresh() before operations to pick up changes from other agents.

Namespacing

If you want to use a single TASKDATA directory (like a shared S3 bucket or a global ~/.backlog folder) for multiple projects, you can use namespaces to keep tasks separate:

1. Manual: Set BACKLOG_NAMESPACE=my-project to use a specific collection name.
2. Automatic: Set BACKLOG_AUTO_NAMESPACE=true to have Backlog automatically derive a collection name from your current working directory (e.g. my-app-a1b2c3d4).

Example Configuration (.claude/settings.json):

{
  "mcpServers": {
    "backlog": {
      "command": "node",
      "args": ["/path/to/backlog/dist/index.js"],
      "env": {
        "TASKDATA": "/home/user/.backlog",
        "BACKLOG_AUTO_NAMESPACE": "true",
        "BACKLOG_AGENT_ID": "claude-desktop"
      }
    }
  }
}

Both methods allow multiple projects to share the same storage backend while maintaining isolated, project-specific backlogs.

S3 Backend

Store task data in S3 for team sharing or cloud persistence. Requires @backloghq/opslog-s3:

npm install @backloghq/opslog-s3

Configure via environment variables in .claude/settings.json:

{
  "mcpServers": {
    "backlog": {
      "command": "node",
      "args": ["/path/to/backlog/dist/index.js"],
      "env": {
        "TASKDATA": "my-project/tasks",
        "BACKLOG_BACKEND": "s3",
        "BACKLOG_S3_BUCKET": "my-team-backlog",
        "BACKLOG_S3_REGION": "us-east-1"
      }
    }
  }
}

When using S3, TASKDATA becomes the key prefix in the bucket instead of a filesystem path.

Docker

docker build -t backlog .
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  | docker run --rm -i backlog

Development

npm install
npm run build          # compile TypeScript
npm run lint           # run ESLint
npm test               # run tests
npm run test:coverage  # run tests with coverage
npm run dev            # watch mode

Community

• GitHub Discussions — questions, ideas, show & tell
• Issue Tracker — bug reports and feature requests
• Documentation — full docs, skills reference, filter syntax

If backlog is useful to you, consider giving it a star — it helps others find the project.

License

MIT