{
  "markdown": "# backlog\n\n[![GitHub stars](https://img.shields.io/github/stars/backloghq/backlog?style=social)](https://github.com/backloghq/backlog)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/backloghq/backlog/actions/workflows/ci.yml/badge.svg)](https://github.com/backloghq/backlog/actions/workflows/ci.yml)\n[![Docs](https://img.shields.io/badge/docs-backloghq.io-blue)](https://backloghq.io)\n\nPersistent, cross-session task management for Claude Code. Tasks survive sessions so work started by one agent can be picked up by another.\n\nBuilt on [@backloghq/agentdb](https://github.com/backloghq/agentdb) — typed schemas, auto-increment IDs, virtual filters, blob storage. Pure TypeScript, zero native dependencies.\n\n## Install\n\n```\n/plugin marketplace add backloghq/backlog\n/plugin install backlog@backloghq-backlog\n```\n\n### From source\n\n```bash\ngit clone https://github.com/backloghq/backlog.git\ncd backlog && npm install && npm run build\nclaude --plugin-dir /path/to/backlog\n```\n\n### Standalone MCP server\n\nAdd to your project's `.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"backlog\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/agent-teams-task-mcp/dist/index.js\"],\n      \"env\": {\n        \"TASKDATA\": \"/path/to/task-data\"\n      }\n    }\n  }\n}\n```\n\n## Skills\n\n| Skill | Description |\n|-------|-------------|\n| `/backlog:tasks` | Show the current backlog — pending, active, blocked, overdue tasks |\n| `/backlog:plan` | Break down a goal into tasks with dependencies, priorities, and specs |\n| `/backlog:standup` | Daily standup — done, in progress, blocked, up next |\n| `/backlog:refine` | Groom the backlog — fix vague tasks, missing priorities, broken deps, stale items |\n| `/backlog:spec` | Write a spec document for a task before implementation |\n| `/backlog:implement` | Pick up a task, read its spec, implement it, mark done |\n| `/backlog:handoff` | Prepare for next session — annotate progress, stop active tasks, summarize state |\n\n## Agent\n\nThe `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.\n\n## Hooks\n\n| Event | What it does |\n|-------|-------------|\n| `SessionStart` | Shows pending task count when a session begins |\n| `TaskCreated` | Syncs Claude's built-in tasks to the persistent backlog |\n| `TaskCompleted` | Marks the matching backlog task as done when Claude completes a built-in task |\n| `SubagentStart` | Auto-assigns unassigned pending tasks to the spawned agent |\n\n## Tools (MCP)\n\nTools for full task lifecycle management:\n\n| Tool | Description |\n|------|-------------|\n| `task_list` | Query tasks with filter syntax. Returns JSON array with all fields. |\n| `task_count` | Count tasks matching a filter. Same syntax as task_list. |\n| `task_add` | Create a new pending task. Only description required; all other fields optional. |\n| `task_log` | Record already-completed work directly in completed status. |\n| `task_modify` | Partial-update one or more tasks matching a filter. Only provided fields change. |\n| `task_duplicate` | Copy an existing task with optional field overrides. |\n| `task_done` | Mark a task as completed with end timestamp. |\n| `task_delete` | Soft-delete a task. Restorable with task_undo. Use task_purge to permanently remove. |\n| `task_annotate` | Add a timestamped note. Use task_doc_write for longer content. |\n| `task_denotate` | Remove an annotation by exact text match. |\n| `task_start` | Mark a task as actively being worked on. Visible in +ACTIVE queries. |\n| `task_stop` | Stop working on a task. Returns it to pending status. |\n| `task_undo` | Undo the most recent operation. Can be called repeatedly. |\n| `task_info` | Get full JSON details for a single task by ID or UUID. |\n| `task_import` | Bulk-create tasks from a JSON array. Atomic batch operation. |\n| `task_purge` | Permanently remove a deleted task. Irreversible. |\n| `task_doc_write` | Attach/replace a markdown document on a task (specs, notes, context). |\n| `task_doc_read` | Read the markdown document attached to a task. |\n| `task_doc_delete` | Remove a task's document. Permanent. |\n| `task_archive` | Move old completed/deleted tasks to quarterly archive segments. |\n| `task_archive_list` | List available archive segments. |\n| `task_archive_load` | Load archived tasks for read-only inspection. |\n| `task_projects` | List project names with pending/recurring tasks. |\n| `task_tags` | List tags with pending/recurring tasks. |\n\n## Filter Syntax\n\n```\nstatus:pending                    # all pending tasks\nproject:backend +bug              # bugs in backend project\npriority:H due.before:friday      # high priority due before friday\n+OVERDUE                          # overdue tasks\n+ACTIVE                           # tasks currently being worked on\n+BLOCKED                          # tasks blocked by dependencies\n+READY                            # actionable tasks (past scheduled date)\nagent:explorer                    # tasks assigned to the explorer agent\n( project:web or project:api )    # boolean with parentheses\ndescription.contains:auth         # substring match\n```\n\nSupports 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`).\n\n## Task Docs\n\nAttach markdown documents (specs, context, handoff notes) to any task:\n\n```\ntask_doc_write  id:\"1\"  content:\"# Spec\\n\\nBuild the auth flow.\\n\"\ntask_doc_read   id:\"1\"\ntask_doc_delete id:\"1\"\n```\n\nWriting a doc adds a `+doc` tag and `has_doc:yes`, so agents can discover tasks with docs:\n\n```\ntask_list filter:\"+doc\"\ntask_list filter:\"has_doc:yes\"\n```\n\n## Agent Identity\n\nTasks support an `agent` field for tracking which agent owns a task:\n\n```\ntask_add  description:\"Investigate bug\"  agent:\"explorer\"\ntask_list filter:\"agent:explorer status:pending\"\n```\n\n## Project Isolation\n\nEach 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.\n\n| Variable | Description |\n|----------|-------------|\n| `TASKDATA` | Explicit path to task data directory (overrides auto-derivation) |\n| `TASKDATA_ROOT` | Root directory for auto-derived per-project task data |\n| `BACKLOG_NAMESPACE` | Explicit collection name (default: `tasks`) |\n| `BACKLOG_AUTO_NAMESPACE` | Set to `true` to derive collection name from CWD |\n| `BACKLOG_AGENT_ID` | Agent ID for multi-writer support (Claude, Gemini, etc.) |\n| `BACKLOG_BACKEND` | Storage backend: omit for filesystem (default), `s3` for Amazon S3 |\n| `BACKLOG_S3_BUCKET` | S3 bucket name (required when `BACKLOG_BACKEND=s3`) |\n| `BACKLOG_S3_REGION` | AWS region (optional if using default credentials) |\n\n### Multi-Writer Support\n\nBacklog supports concurrent access from multiple processes (e.g., Claude Desktop and Gemini CLI) sharing the same data. To enable this:\n1. Assign a unique `BACKLOG_AGENT_ID` to each process (e.g., `claude`, `gemini`).\n2. When an agent ID is set, the engine uses per-agent write logs, avoiding file locks.\n3. Each process automatically calls `refresh()` before operations to pick up changes from other agents.\n\n### Namespacing\n\nIf 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:\n\n1. **Manual**: Set `BACKLOG_NAMESPACE=my-project` to use a specific collection name.\n2. **Automatic**: Set `BACKLOG_AUTO_NAMESPACE=true` to have Backlog automatically derive a collection name from your current working directory (e.g. `my-app-a1b2c3d4`).\n\n**Example Configuration (`.claude/settings.json`):**\n\n```json\n{\n  \"mcpServers\": {\n    \"backlog\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/backlog/dist/index.js\"],\n      \"env\": {\n        \"TASKDATA\": \"/home/user/.backlog\",\n        \"BACKLOG_AUTO_NAMESPACE\": \"true\",\n        \"BACKLOG_AGENT_ID\": \"claude-desktop\"\n      }\n    }\n  }\n}\n```\n\nBoth methods allow multiple projects to share the same storage backend while maintaining isolated, project-specific backlogs.\n\n### S3 Backend\n\nStore task data in S3 for team sharing or cloud persistence. Requires `@backloghq/opslog-s3`:\n\n```bash\nnpm install @backloghq/opslog-s3\n```\n\nConfigure via environment variables in `.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"backlog\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/backlog/dist/index.js\"],\n      \"env\": {\n        \"TASKDATA\": \"my-project/tasks\",\n        \"BACKLOG_BACKEND\": \"s3\",\n        \"BACKLOG_S3_BUCKET\": \"my-team-backlog\",\n        \"BACKLOG_S3_REGION\": \"us-east-1\"\n      }\n    }\n  }\n}\n```\n\nWhen using S3, `TASKDATA` becomes the key prefix in the bucket instead of a filesystem path.\n\n## Docker\n\n```bash\ndocker build -t backlog .\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}' \\\n  | docker run --rm -i backlog\n```\n\n## Development\n\n```bash\nnpm install\nnpm run build          # compile TypeScript\nnpm run lint           # run ESLint\nnpm test               # run tests\nnpm run test:coverage  # run tests with coverage\nnpm run dev            # watch mode\n```\n\n## Community\n\n- [GitHub Discussions](https://github.com/backloghq/backlog/discussions) — questions, ideas, show & tell\n- [Issue Tracker](https://github.com/backloghq/backlog/issues) — bug reports and feature requests\n- [Documentation](https://backloghq.io) — full docs, skills reference, filter syntax\n\nIf backlog is useful to you, consider giving it a star — it helps others find the project.\n\n## License\n\nMIT\n",
  "bytes": 9889,
  "sha": "2dad2672a6488bbce5e67f314f5b69a4429e9acb97955dd4d96a1d747047d6c0",
  "repo_slug": "backloghq/backlog",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_backloghq_backlog_backlog_9b48a3b8/readme"
}