crumbs

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).