Skip to main content
Glama
backloghq

backlog

by backloghq

backlog

GitHub stars License: MIT CI Docs

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"
      }
    }
  }
}

Related MCP server: Vibe Board VE

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

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

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 20 tool updatesv1.5.0
    • Changedtask_add12 fields changed
      • changedInput schema / properties / agent / description
        Previous value: -"Agent identity, e.g. 'explorer', 'planner', 'reviewer'"New value: +"Agent identity for tracking task ownership across agent teams. E.g. 'explorer', 'planner', 'reviewer'."
      • changedInput schema / properties / depends / description
        Previous value: -"UUID(s) of tasks this depends on, comma-separated"New value: +"Comma-separated UUIDs of tasks this depends on. Task shows as +BLOCKED until dependencies are completed."
      • changedInput schema / properties / description / description
        Previous value: -"Task description text"New value: +"Task description (required, max 500 chars). Brief summary of what needs to be done."
      • changedInput schema / properties / due / description
        Previous value: -"Due date, e.g. 'tomorrow', '2025-12-31', 'eow'"New value: +"Due date. Accepts: ISO dates ('2025-12-31'), relative ('3d', '2w'), named ('tomorrow', 'friday', 'eow', 'eom'), compound ('now+3d')."
      • changedInput schema / properties / extra / description
        Previous value: -"Additional raw attributes"New value: +"Space-separated additional attributes or +tag/-tag modifiers."
      • changedInput schema / properties / priority / description
        Previous value: -"Priority: H (high), M (medium), L (low)"New value: +"Priority: H (high), M (medium), L (low). Affects urgency score and sort order."
      • changedInput schema / properties / project / description
        Previous value: -"Project name, e.g. 'backend'"New value: +"Project name for grouping (alphanumeric, hyphens, underscores). E.g. 'backend', 'auth-refactor'"
      • changedInput schema / properties / recur / description
        Previous value: -"Recurrence frequency, e.g. 'daily', 'weekly', '2wks', 'monthly'. Requires a due date."New value: +"Recurrence pattern. Requires 'due' to be set. Values: 'daily', 'weekly', 'weekdays', 'biweekly', 'monthly', 'quarterly', 'yearly', or numeric like '3d', '2w'."
      • changedInput schema / properties / scheduled / description
        Previous value: -"Scheduled date — when to start working on the task, e.g. 'monday', 'tomorrow'"New value: +"Scheduled start date — when to begin working. Same date formats as 'due'."
      • changedInput schema / properties / tags / description
        Previous value: -"Tags to apply, as comma-separated list or JSON array. E.g. 'bug,urgent' or '[\"bug\",\"urgent\"]'"New value: +"Tags as comma-separated list or JSON array. E.g. 'bug,urgent' or '[\"bug\",\"urgent\"]'. Used for filtering with +tag/-tag syntax."
      • changedInput schema / properties / until / description
        Previous value: -"End date for recurrence — no instances generated past this date, e.g. '2026-12-31'"New value: +"End date for recurrence — no instances generated past this date. Only meaningful with 'recur'. Same date formats as 'due'."
      • changedInput schema / properties / wait / description
        Previous value: -"Wait date — task hidden until this date"New value: +"Wait date — task is hidden from default views until this date. Same date formats as 'due'."
    • Changedtask_annotate2 fields changed
      • changedInput schema / properties / id / description
        Previous value: -"Task ID number or UUID"New value: +"Task ID number (e.g. '1') or UUID."
      • changedInput schema / properties / text / description
        Previous value: -"Annotation text"New value: +"Annotation text to add. Stored with a timestamp. Keep concise — use task_doc_write for longer content."
    • Changedtask_archive1 field changed
      • changedInput schema / properties / older_than_days / description
        Previous value: -"Number of days. Archive tasks completed/deleted more than this many days ago. Default: 90"New value: +"Archive tasks completed/deleted more than this many days ago. Default: 90. E.g. '30' for tasks older than a month."
    • Changedtask_archive_load1 field changed
      • changedInput schema / properties / segment / description
        Previous value: -"Archive segment name, e.g. '2026-Q1'"New value: +"Archive segment name, e.g. '2026-Q1'. Use task_archive_list to see available segments."
    • Changedtask_count1 field changed
      • changedInput schema / properties / filter / description
        Previous value: -"Filter expression. Leave empty for all pending tasks."New value: +"Filter expression. Same syntax as task_list. Examples: 'status:pending', '+OVERDUE', 'project:backend +bug'. Leave empty for all pending tasks."
    • Changedtask_delete1 field changed
      • changedInput schema / properties / id / description
        Previous value: -"Task ID number or UUID"New value: +"Task ID number (e.g. '1') or UUID of the task to delete."
    • Changedtask_denotate2 fields changed
      • changedInput schema / properties / id / description
        Previous value: -"Task ID number or UUID"New value: +"Task ID number (e.g. '1') or UUID."
      • changedInput schema / properties / text / description
        Previous value: -"Exact annotation text to remove"New value: +"Exact annotation text to remove (case-sensitive). Must match a previously added annotation."
    • Changedtask_doc_delete1 field changed
      • changedInput schema / properties / id / description
        Previous value: -"Task ID number or UUID"New value: +"Task ID number (e.g. '1') or UUID."
    • Changedtask_doc_read1 field changed
      • changedInput schema / properties / id / description
        Previous value: -"Task ID number or UUID"New value: +"Task ID number (e.g. '1') or UUID."
    • Changedtask_doc_write2 fields changed
      • changedInput schema / properties / content / description
        Previous value: -"Document content (markdown)"New value: +"Document content in markdown format. Replaces any existing document on this task."
      • changedInput schema / properties / id / description
        Previous value: -"Task ID number or UUID"New value: +"Task ID number (e.g. '1') or UUID."
    • Changedtask_done1 field changed
      • changedInput schema / properties / id / description
        Previous value: -"Task ID number or UUID"New value: +"Task ID number (e.g. '1') or UUID. Task must be in pending or active status."
    • Changedtask_duplicate8 fields changed
      • changedInput schema / properties / agent / description
        Previous value: -"Agent identity"New value: +"Agent identity for the new task."
      • changedInput schema / properties / description / description
        Previous value: -"New description (overrides original)"New value: +"New description to override the original."
      • changedInput schema / properties / due / description
        Previous value: -"New due date"New value: +"New due date. Pass empty string to clear."
      • changedInput schema / properties / extra / description
        Previous value: -"Additional raw attributes"New value: +"Space-separated additional attributes or +tag/-tag modifiers."
      • changedInput schema / properties / id / description
        Previous value: -"Task ID number or UUID to duplicate"New value: +"Task ID number (e.g. '1') or UUID of the task to copy."
      • changedInput schema / properties / priority / description
        Previous value: -"New priority"New value: +"New priority. Pass empty string to clear."
      • changedInput schema / properties / project / description
        Previous value: -"New project"New value: +"New project. Pass empty string to clear."
      • changedInput schema / properties / tags / description
        Previous value: -"Tags to add or remove, as comma-separated list. E.g. 'frontend,urgent' or '-old,+new'"New value: +"Tags to add (+) or remove (-). E.g. '+frontend,-old'. Applied on top of the copied tags."
    • Changedtask_import1 field changed
      • changedInput schema / properties / tasks / description
        Previous value: -"JSON array of task objects, e.g. '[{\"description\":\"My task\",\"project\":\"foo\"}]'"New value: +"JSON array of task objects. Required field: 'description'. Optional: 'project', 'tags' (string[]), 'priority' (H/M/L), 'due', 'status', 'depends' (UUID[]), 'recur', 'agent', 'uuid' (to set explicit ID). Example: '[{\"description\":\"My task\",\"project\":\"foo\",\"priority\":\"H\"}]'"
    • Changedtask_info1 field changed
      • changedInput schema / properties / id / description
        Previous value: -"Task ID number or UUID"New value: +"Task ID number (e.g. '1') or UUID. Returns an error if no task matches."
    • Changedtask_list1 field changed
      • changedInput schema / properties / filter / description
        Previous value: -"Filter expression. Leave empty for all pending tasks."New value: +"Filter expression to match tasks. Examples: 'status:pending', 'project:backend +bug', 'due.before:tomorrow', '+OVERDUE', '+BLOCKED', 'priority:H', 'agent:explorer'. Combine with 'and'/'or' and parentheses. Leave empty for all pending tasks."
    • Changedtask_log6 fields changed
      • changedInput schema / properties / agent / description
        Previous value: -"Agent identity"New value: +"Agent identity that completed the work."
      • changedInput schema / properties / description / description
        Previous value: -"Task description text"New value: +"Description of the completed work (required, max 500 chars)."
      • changedInput schema / properties / extra / description
        Previous value: -"Additional raw attributes"New value: +"Space-separated additional attributes or +tag modifiers."
      • changedInput schema / properties / priority / description
        Previous value: -"Priority: H/M/L"New value: +"Priority: H (high), M (medium), L (low)."
      • changedInput schema / properties / project / description
        Previous value: -"Project name"New value: +"Project name for grouping."
      • changedInput schema / properties / tags / description
        Previous value: -"Tags to apply, as comma-separated list. E.g. 'done,reviewed'"New value: +"Tags as comma-separated list. E.g. 'done,reviewed'"
    • Changedtask_modify13 fields changed
      • changedInput schema / properties / agent / description
        Previous value: -"Agent identity, e.g. 'explorer', 'planner', 'reviewer'"New value: +"Agent identity. Pass empty string to unassign."
      • changedInput schema / properties / depends / description
        Previous value: -"New dependency UUIDs"New value: +"New dependency UUIDs (comma-separated). Replaces existing dependencies. Pass empty string to clear."
      • changedInput schema / properties / description / description
        Previous value: -"New description text"New value: +"New description text (max 500 chars). Only set if you want to change it."
      • changedInput schema / properties / due / description
        Previous value: -"New due date"New value: +"New due date. Accepts ISO dates, relative ('3d'), named ('friday', 'eow'). Pass empty string to clear."
      • changedInput schema / properties / extra / description
        Previous value: -"Additional raw attributes"New value: +"Space-separated additional attributes or +tag/-tag modifiers."
      • changedInput schema / properties / filter / description
        Previous value: -"Filter to select tasks to modify (ID, UUID, or filter expression)"New value: +"Filter to select tasks. Can be a numeric ID ('1'), UUID, or filter expression ('project:backend priority:H'). Matches may update multiple tasks."
      • changedInput schema / properties / priority / description
        Previous value: -"New priority (empty string to clear)"New value: +"New priority. Pass empty string to clear priority entirely."
      • changedInput schema / properties / project / description
        Previous value: -"New project name"New value: +"New project name. Pass empty string to clear."
      • changedInput schema / properties / recur / description
        Previous value: -"New recurrence frequency"New value: +"New recurrence pattern ('daily', 'weekly', '3d', etc). Pass empty string to clear."
      • changedInput schema / properties / scheduled / description
        Previous value: -"New scheduled date"New value: +"New scheduled start date. Pass empty string to clear."
      • changedInput schema / properties / tags / description
        Previous value: -"Tags to add (+) or remove (-), as comma-separated list. E.g. 'frontend,urgent' or '-old,+new'"New value: +"Tags to add (+) or remove (-). E.g. '+frontend,+urgent' or '-old,+new'. Prefix with + to add, - to remove. Without prefix, tags are added."
      • changedInput schema / properties / until / description
        Previous value: -"End date for recurrence — no instances generated past this date, e.g. '2026-12-31'"New value: +"End date for recurrence. Pass empty string to clear."
      • changedInput schema / properties / wait / description
        Previous value: -"New wait date"New value: +"New wait date. Task hidden from default views until this date. Pass empty string to clear."
    • Changedtask_purge1 field changed
      • changedInput schema / properties / id / description
        Previous value: -"Task ID number or UUID of a deleted task"New value: +"Task ID number (e.g. '1') or UUID. Task must be in 'deleted' status."
    • Changedtask_start1 field changed
      • changedInput schema / properties / id / description
        Previous value: -"Task ID number or UUID"New value: +"Task ID number (e.g. '1') or UUID. Task must be in pending status."
    • Changedtask_stop1 field changed
      • changedInput schema / properties / id / description
        Previous value: -"Task ID number or UUID"New value: +"Task ID number (e.g. '1') or UUID. Task must be currently active (started)."
  2. 24 tool updatesv1.4.0
    • First observedtask_add
    • First observedtask_annotate
    • First observedtask_archive
    • First observedtask_archive_list
    • First observedtask_archive_load
    • First observedtask_count
    • First observedtask_delete
    • First observedtask_denotate
    • First observedtask_doc_delete
    • First observedtask_doc_read
    • First observedtask_doc_write
    • First observedtask_done
    • First observedtask_duplicate
    • First observedtask_import
    • First observedtask_info
    • First observedtask_list
    • First observedtask_log
    • First observedtask_modify
    • First observedtask_projects
    • First observedtask_purge
    • First observedtask_start
    • First observedtask_stop
    • First observedtask_tags
    • First observedtask_undo

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a distinct, clearly separated purpose with explicit cross-references in descriptions (e.g., 'use task_log instead', 'use task_doc_write instead'). No overlapping functionality—CRUD, lifecycle, archival, and document operations are cleanly partitioned.

Naming Consistency5/5

Strict snake_case convention with consistent 'task_' prefix. Sub-resources follow predictable patterns (task_doc_read/write/delete, task_archive_list/load). Verbs are clear and consistently placed (task_add, task_delete, task_modify).

Tool Count4/5

24 tools is above the typical ideal range but justified by the domain complexity. The set covers full task lifecycle, document attachments, archival management, annotations, and discovery without redundancy. Each tool earns its place for a comprehensive backlog system.

Completeness4/5

Excellent coverage of CRUD, status workflow (start/stop/done), soft-delete with purge, annotations, document attachments, and archival. Minor gap: archived tasks are view-only with no restore-to-active operation, though this appears to be an intentional cold-storage design.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    B
    maintenance
    Persistent memory and task board for Claude Code. 14 tools spanning projects, tasks, sessions, and activity logs — backed by Firestore, runs on the free tier. Handoff notes survive context compaction; the next session reads the last handoff and picks up where you stopped.
    14
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    A comprehensive project management and workflow tracking system that integrates with Claude Code via MCP, automatically capturing sessions, tools, agents, and project tasks into a centralized dashboard and database.
    20
    MIT
  • F
    license
    Not graded
    quality
    D
    maintenance
    MCP server for project planning inside Claude. It tracks progress, knows your codebase, and resumes exactly where you left off every session.
    14
    5
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/backloghq/backlog'

If you have feedback or need assistance with the MCP directory API, please join our Discord server