crumbs

crumbs-light crumbs-dark

A local task sharing CLI for AI coding agents. Multiple agents working on the same project can share a task list through a SQLite database with WAL mode for concurrent access.

Installation

Quick Install

curl -fsSL https://raw.githubusercontent.com/stordahl/crumbs/main/install.sh | bash

This downloads the latest release binary for your platform and installs it to /usr/local/bin (or ~/.local/bin if not writable).

Build from Source

Requires Bun.

bun install
bun run build
mv crumbs /usr/local/bin/

Usage

crumbs <command> [options]

Commands

`add <title>`

Add a new task.

crumbs add "Implement user authentication"
crumbs add "Fix login bug" --priority 2
crumbs add "Refactor API" --notes "Focus on error handling"

Options:

  • --priority <n> - Task priority (higher = more important)
  • --notes <text> - Additional notes

`list`

List all tasks for the current project.

crumbs list
crumbs list --status pending
crumbs list --status in_progress
crumbs list --json

Options:

  • --status <status> - Filter by status (pending, in_progress, completed)
  • --json - Output as JSON (useful for programmatic access)

`claim <id>`

Claim a task by setting its status to in_progress.

crumbs claim abc123

`complete <id>`

Mark a task as completed.

crumbs complete abc123

`update <id>`

Update a task's title, priority, or notes.

crumbs update abc123 --title "New title"
crumbs update abc123 --priority 3
crumbs update abc123 --notes "Updated notes"

Options:

  • --title <text> - New title
  • --priority <n> - New priority
  • --notes <text> - New notes

`remove <id>`

Remove a task.

crumbs remove abc123

`clear`

Clear tasks from the current project.

crumbs clear                    # Clear all tasks
crumbs clear --status completed # Clear only completed tasks

Options:

  • --status <status> - Only clear tasks with this status

`export`

Export tasks to JSON or CSV.

crumbs export
crumbs export --format json
crumbs export --format csv

Options:

  • --format <fmt> - Output format (json or csv, default: json)

`init`

Initialize a project (optional - projects are created automatically).

crumbs init
crumbs init --name my-project

Options:

  • --name <name> - Explicit project name

`install`

Install a Claude Code skill that teaches AI agents how to use crumbs for task management.

crumbs install

This creates .claude/skills/crumbs/SKILL.md in the current directory. Claude Code will automatically load this skill when relevant, or users can invoke it directly with /crumbs.

Global Options

  • --project <name> - Override the project (default: derived from current directory)
  • --help, -h - Show help
  • --version, -v - Show version

Project Scoping

By default, tasks are scoped to the current working directory. The directory path is hashed to create a stable project ID. Use --project <name> to override this behavior and work with a named project from any directory.

# These commands work on the same project regardless of cwd
crumbs list --project shared-tasks
crumbs add "Task" --project shared-tasks

Data Storage

The database is stored at ~/.config/crumbs/crumbs.db. SQLite WAL mode is enabled for safe concurrent access by multiple agents.

Agent Integration

To teach your AI agents how to use crumbs, run the install command in your project:

crumbs install

This installs a Claude Code skill at .claude/skills/crumbs/SKILL.md. Claude will automatically use it when coordinating multi-agent work, or you can invoke /crumbs directly.

Contributing

Development instructions for AI agents working on this codebase are in AGENTS.md (also available as CLAUDE.md symlink).