backlog
Persistent, cross-session task management for Claude Code. 24 tools, 7 skills, and hooks that sync Claude's built-in tasks to a durable back
Open source Open in the app JSON README (API)
About
Persistent, cross-session task management for Claude Code. 24 tools, 7 skills, and hooks that sync Claude's built-in tasks to a durable backlog. Zero external dependencies.
Details
- Kind
- Plugins
- Topic
- Developer tools
- Publisher
- backloghq
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 5
- Forks
- 2
- Open pull requests
- 1
- Last push
- 2026-05-30T12:50:23Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
backloghq/backlog/backlog
README
# backlog
[](https://github.com/backloghq/backlog)
[](https://opensource.org/licenses/MIT)
[](https://github.com/backloghq/backlog/actions/workflows/ci.yml)
[](https://backloghq.io)
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](https://github.com/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
```bash
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`:
```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`):**
```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`:
```bash
npm install @backloghq/opslog-s3
```
Configure via environment variables in `.claude/settings.json`:
```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
```bash
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
```bash
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](https://github.com/backloghq/backlog/discussions) — questions, ideas, show & tell
- [Issue Tracker](https://github.com/backloghq/backlog/issues) — bug reports and feature requests
- [Documentation](https://backloghq.io) — 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