Skip to content
Back to search

dibs

MarketplaceWorks with Claude CodeGitHub

dibs task tracking skill for Claude Code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/arobida--dibs/badge.svg)](/listings/arobida--dibs)

HTML

<a href="/listings/arobida--dibs"><img src="/api/listings/arobida--dibs/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

dibs needs [Node.js](https://nodejs.org) 26 or later. Run the CLI without installing it:

npx -y @dibs.ai/dibs create "Write tests"
npx -y @dibs.ai/dibs list

To keep a `dibs` command on your PATH, run `npm i -g @dibs.ai/dibs`.

Run the commands from any folder. Without a `.dibs/` folder, the CLI uses a temp store keyed on the current folder, so tasks persist across calls in that folder. To keep tasks in the project, create a `.dibs/` folder or set `DIBS_TRUST=1`.

Then connect your agent:

| Agent | What it gets | Setup | |---|---|---| | Pi | Task tools, `/todos` command, task panel | [agents/pi](agents/pi/README.md) | | Claude Code | `dibs` skill, MCP tools, task panel | [agents/claude-code](agents/claude-code/README.md) | | Codex | `dibs` skill, MCP tools | [agents/codex](agents/codex/README.md) | | opencode | `dibs` skill, MCP tools, task panel | [agents/opencode](agents/opencode/README.md) | | Cursor | `dibs` skill, MCP tools | [agents/cursor](agents/cursor/README.md) |

Pi loads dibs as a library. Every other agent runs the CLI through `npx -y @dibs.ai/dibs`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 26 lines
  1. {
  2. "name": "dibs",
  3. "description": "dibs task tracking skill for Claude Code.",
  4. "owner": {
  5. "name": "arobida",
  6. "url": "https://github.com/arobida"
  7. },
  8. "plugins": [
  9. {
  10. "name": "dibs",
  11. "version": "0.1.0",
  12. "description": "Track multi-step work as tasks with the dibs CLI (skill for Claude Code).",
  13. "license": "MIT",
  14. "author": {
  15. "name": "arobida",
  16. "url": "https://github.com/arobida"
  17. },
  18. "source": "./",
  19. "strict": false,
  20. "mcpServers": "./agents/claude-code/.mcp.json",
  21. "skills": [
  22. "./agents/shared/skills/"
  23. ]
  24. }
  25. ]
  26. }
README.md · README · 132 lines
  1. # dibs
  2. dibs is a task store that several coding agents share. Pi, Claude Code, Codex, opencode and Cursor read and write the same JSONL file per project, so a task one agent creates shows up in the others. Agents reach the store through the `dibs` CLI, an MCP server (`dibs mcp`), or the Pi extension, and optional adapters sync it with Dex and Things 3.
  3. ## Quick start
  4. dibs needs [Node.js](https://nodejs.org) 26 or later. Run the CLI without installing it:
  5. ```sh
  6. npx -y @dibs.ai/dibs create "Write tests"
  7. npx -y @dibs.ai/dibs list
  8. ```
  9. To keep a `dibs` command on your PATH, run `npm i -g @dibs.ai/dibs`.
  10. Run the commands from any folder. Without a `.dibs/` folder, the CLI uses a temp store keyed on the current folder, so tasks persist across calls in that folder. To keep tasks in the project, create a `.dibs/` folder or set `DIBS_TRUST=1`.
  11. Then connect your agent:
  12. | Agent | What it gets | Setup |
  13. |---|---|---|
  14. | Pi | Task tools, `/todos` command, task panel | [agents/pi](agents/pi/README.md) |
  15. | Claude Code | `dibs` skill, MCP tools, task panel | [agents/claude-code](agents/claude-code/README.md) |
  16. | Codex | `dibs` skill, MCP tools | [agents/codex](agents/codex/README.md) |
  17. | opencode | `dibs` skill, MCP tools, task panel | [agents/opencode](agents/opencode/README.md) |
  18. | Cursor | `dibs` skill, MCP tools | [agents/cursor](agents/cursor/README.md) |
  19. Pi loads dibs as a library. Every other agent runs the CLI through `npx -y @dibs.ai/dibs`.
  20. ## CLI
  21. ```sh
  22. npx -y @dibs.ai/dibs --help
  23. ```
  24. | Command | Effect |
  25. |---|---|
  26. | `list [--query q] [--human u\|me]` | List tasks |
  27. | `ready [--human u\|me]` | List tasks with no open blockers |
  28. | `create <name> [--description d] [--parent id] [--blocked-by a,b] [--human u]` | Create a task |
  29. | `start <id> [--force]`, `complete <id> [--result r] [--force]` | Change status; `start` and `complete` refuse a task another live owner claimed unless `--force` is given |
  30. | `edit <id> [--name n] [--description d] [--blocked-by a,b] [--human u]` | Edit a task; `--human ""` clears the human |
  31. | `import <file>`, `export [file]` | Read or write todo.txt |
  32. | `sync` | Sync with the adapters enabled in config; an adapter that another process is syncing prints `skipped` and is not waited for |
  33. | `link <id>`, `resolve <url>` | Make or follow a `dibs://<project-id>/<task-id>` link |
  34. | `panel [current\|project\|completed] [--mine a,b]` | Print the task panel |
  35. | `mcp` | Serve the task tools over MCP (stdio) |
  36. | `scope project\|global`, `migrate .dibs\|.agents/dibs` | Move the store (see [Storage](#storage)) |
  37. Every command takes `--global` (use this project's store under `~/.dibs/projects/`) and `--json`. Ids accept a unique prefix: `start a1b` works when only one id starts with `a1b`.
  38. The CLI finds the project by walking up from the current directory to the nearest folder that holds a `.dibs/`, `.agents/dibs/` or `.pi-do/` folder, so commands work from any subfolder. The home folder and `~/.dibs` never count. That folder is the project for trust, the store, the project name and registration. `DIBS_TRUST=1` trusts the current directory without such a folder. An untrusted directory gets the temp store.
  39. | Variable | Effect |
  40. |---|---|
  41. | `DIBS_AGENT` | Names the agent that creates a task (`created_by`) |
  42. | `DIBS_USER` | Sets your GitHub user; otherwise `git config github.user` or `gh` supplies it |
  43. | `DIBS_TRUST=1` | Trusts the current directory |
  44. | `DIBS_SESSION` | Names the CLI claim owner (`cli:<id>`) and keys the temp store, which otherwise uses the current folder |
  45. | `DIBS_SCOPE`, `DIBS_FILE` | Override `scope` and `file` from config |
  46. | `DIBS_HOME` | Moves `~/.dibs` |
  47. `start` claims the task for the CLI session as `cli:` followed by `DIBS_SESSION`, `DIBS_AGENT` or `cli`. A CLI claim lasts until `complete` or `--force`, even after the CLI exits. `ready` hides tasks with a live claim. Pi and MCP claims last while their process lives.
  48. ## Tasks
  49. Each task is one JSON object per line:
  50. | Field | Value |
  51. |---|---|
  52. | `id`, `name`, `completed`, `started_at` | Always present |
  53. | `priority` | A-Z |
  54. | `created`, `completed_date` | YYYY-MM-DD |
  55. | `description`, `result` | Free text |
  56. | `parent` | Id of the parent task |
  57. | `blocked_by` | Ids of tasks that must complete first; never synced to adapters |
  58. | `claimed_by` | Owner of a started task: `cli:<name>` for the CLI, `<session>:<pid>` for Pi and MCP; never synced or exported |
  59. | `created_by` | Agent name, or `@user` for a human |
  60. | `human` | GitHub username of the human in the loop; `create` defaults it to you |
  61. `+projects`, `@contexts` and other `key:value` tags stay in `name`. The schema is `Task` in [`src/core/todo.ts`](src/core/todo.ts).
  62. Export writes each task as a [todo.txt](https://github.com/todotxt/todo.txt) line, carrying the dibs fields as `dibsid:`, `dibsstart:`, `dibsdesc:`, `dibsparent:`, `dibsresult:`, `dibsby:`, `dibshuman:` and `dibsblocked:` tags. Import reads those tags back and skips `dibsid:`s already in the store. Export does not overwrite an existing file.
  63. ## Storage
  64. | Scope | Todos file |
  65. |---|---|
  66. | `project` (default for trusted projects) | `.dibs/todos/<project>.todos.jsonl`, or under `.agents/dibs/` if that folder exists |
  67. | `global` | `~/.dibs/projects/<project>.<id>/todos/<project>.todos.jsonl` |
  68. | `temp` (and untrusted projects) | The same layout under `$TMPDIR/dibs/<session-hash>/.dibs/`, keyed on the current folder unless `DIBS_SESSION` is set; the OS may remove it |
  69. `<project>` is the name of the project folder (see [CLI](#cli)). On first use dibs creates the store folder with a `config.json` and a todos file. A permanent store starts with a `Hello World` task, and so does a temp store on the run that creates `~/.dibs/`; other temp stores start empty.
  70. The project's `config.json` holds its id and its settings, and stays in the project in both scopes. The id keys the project's record in `~/.dibs/projects/projects.jsonl` (`id`, `name`, `path`, `scope`, `created`). Only `global` scope creates a folder under `~/.dibs/projects/`.
  71. `scope project|global` moves the `todos/` and `sync/` folders between the project and `~/.dibs/projects/<name>.<id>/`. `migrate .dibs|.agents/dibs` moves the whole project store folder. Both run only in trusted projects and refuse to overwrite existing todos.
  72. ## Configuration
  73. `config.json` is JSONC, so comments and trailing commas are allowed. dibs reads `~/.dibs/config.json`, then the project's `config.json`, then the environment; each later source overrides the earlier one.
  74. ```json
  75. {"adapters": {"dex": {"sync": true}}, "scope": "project"}
  76. ```
  77. | Key | Value |
  78. |---|---|
  79. | `adapters` | Per-adapter options for `dex` and `things`: `sync` (boolean) and `human` (`"me"` or a GitHub username; only tasks with that `human` sync, and tasks with no human stay local) |
  80. | `scope` | `project` (default), `global` or `temp`; read only from the global config or `DIBS_SCOPE` |
  81. | `file` | An explicit todos file that overrides `scope`; `~/` expands, and relative paths resolve from the working directory |
  82. Each `config.json` that dibs writes starts with a `$schema` URL pinned to the dibs version that wrote it, so editors check every option; reads never rewrite it. The schema is [`schema.json`](schema.json), and each adapter's options are in `src/core/adapters/<name>/<name>.schema.json`.
  83. Changing `scope` or `file` selects a different store without moving tasks; use export and import to carry them over. Invalid config raises an error.
  84. ## Adapters
  85. Adapters sync the dibs store both ways with another todo app. Pi and the MCP server sync every enabled adapter before each task list and after each change; the CLI syncs only on `dibs sync`. When another process is already syncing an adapter, the new run skips it instead of waiting. Each README covers connecting, synced fields and limits:
  86. - [Dex](src/core/adapters/dex/README.md)
  87. - [Things 3](src/core/adapters/things/README.md)
  88. ## Documentation
  89. - Agent setup: [Pi](agents/pi/README.md), [Claude Code](agents/claude-code/README.md), [Codex](agents/codex/README.md), [opencode](agents/opencode/README.md), [Cursor](agents/cursor/README.md)
  90. - The skill agents follow: [`agents/shared/skills/dibs/SKILL.md`](agents/shared/skills/dibs/SKILL.md)
  91. - Adapters: [Dex](src/core/adapters/dex/README.md), [Things 3](src/core/adapters/things/README.md)
  92. - Release notes: [CHANGELOG.md](CHANGELOG.md)
  93. - Development, project structure and releases: [CONTRIBUTING.md](CONTRIBUTING.md)
  94. dibs is MIT licensed.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.