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