backlog

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

| Skill | Description | |-------|-------------| | /backlog:tasks | Show the current backlog — pending, active, blocked, overdue tasks | | /backlog:plan | Break down a goal into tasks with dependencies, priorities, and specs | | /backlog:standup | Daily standup — done, in progress, blocked, up next | | /backlog:refine | Groom the backlog — fix vague tasks, missing priorities, broken deps, stale items | | /backlog:spec | Write a spec document for a task before implementation | | /backlog:implement | Pick up a task, read its spec, implement it, mark done | | /backlog:handoff | Prepare for next session — annotate progress, stop active tasks, summarize state |

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

| Event | What it does | |-------|-------------| | SessionStart | Shows pending task count when a session begins | | TaskCreated | Syncs Claude's built-in tasks to the persistent backlog | | TaskCompleted | Marks the matching backlog task as done when Claude completes a built-in task | | SubagentStart | Auto-assigns unassigned pending tasks to the spawned agent |

Tools (MCP)

Tools for full task lifecycle management:

| Tool | Description | |------|-------------| | task_list | Query tasks with filter syntax. Returns JSON array with all fields. | | task_count | Count tasks matching a filter. Same syntax as task_list. | | task_add | Create a new pending task. Only description required; all other fields optional. | | task_log | Record already-completed work directly in completed status. | | task_modify | Partial-update one or more tasks matching a filter. Only provided fields change. | | task_duplicate | Copy an existing task with optional field overrides. | | task_done | Mark a task as completed with end timestamp. | | task_delete | Soft-delete a task. Restorable with task_undo. Use task_purge to permanently remove. | | task_annotate | Add a timestamped note. Use task_doc_write for longer content. | | task_denotate | Remove an annotation by exact text match. | | task_start | Mark a task as actively being worked on. Visible in +ACTIVE queries. | | task_stop | Stop working on a task. Returns it to pending status. | | task_undo | Undo the most recent operation. Can be called repeatedly. | | task_info | Get full JSON details for a single task by ID or UUID. | | task_import | Bulk-create tasks from a JSON array. Atomic batch operation. | | task_purge | Permanently remove a deleted task. Irreversible. | | task_doc_write | Attach/replace a markdown document on a task (specs, notes, context). | | task_doc_read | Read the markdown document attached to a task. | | task_doc_delete | Remove a task's document. Permanent. | | task_archive | Move old completed/deleted tasks to quarterly archive segments. | | task_archive_list | List available archive segments. | | task_archive_load | Load archived tasks for read-only inspection. | | task_projects | List project names with pending/recurring tasks. | | task_tags | List tags with pending/recurring tasks. |

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.

| Variable | Description | |----------|-------------| | TASKDATA | Explicit path to task data directory (overrides auto-derivation) | | TASKDATA_ROOT | Root directory for auto-derived per-project task data | | BACKLOG_NAMESPACE | Explicit collection name (default: tasks) | | BACKLOG_AUTO_NAMESPACE | Set to true to derive collection name from CWD | | BACKLOG_AGENT_ID | Agent ID for multi-writer support (Claude, Gemini, etc.) | | BACKLOG_BACKEND | Storage backend: omit for filesystem (default), s3 for Amazon S3 | | BACKLOG_S3_BUCKET | S3 bucket name (required when BACKLOG_BACKEND=s3) | | BACKLOG_S3_REGION | AWS region (optional if using default credentials) |

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