Task tracking for AI-assisted development.

Pebbles is a command-line bug/task tracker designed to integrate with opencode and both Git and Jujutsu version control. It manages work items through their lifecycle while automatically handling workspaces.

git clone https://github.com/drusellers/pebbles
cd pebbles
cargo build --release
# Binary is at target/release/pebbles

# Initialize pebbles in your project
pebbles init

# Create a new change
pebbles new "Fix login validation"

# View all changes
pebbles list

# Show change details
pebbles show <id>

# Start working (auto-runs /implement)
pebbles start <id>

# Or create an isolated workspace
pebbles start <id> --isolate

# Open TUI without auto-running /implement
pebbles start <id> --wait

# Create changes from text file (intake)
pebbles intake features.txt

# Plan and break down a change into actionable steps
pebbles plan <id>

# Delete a change
pebbles delete <id>

# When done, mark complete
pebbles done <id>

Pebbles follows a simple status flow:

Draft → Approved → InProgress → Review → Done
                      ↓           ↓
                   Blocked    (reject back to InProgress)
                      ↓
                   Paused

1. Draft: New changes start here. Use for ideas and rough specs.
2. Approved: Change is ready to be worked on. (pebbles approve <id>)
3. InProgress: Work has started with pebbles start <id>:
   • Default: Works in current directory, auto-runs /implement
   • --isolate: Creates an isolated workspace (recommended for large changes)
   • --wait: Opens opencode TUI without auto-running /implement
4. Done: Work is complete. (pebbles done <id>)

Create .pebbles/config.toml to customize behavior:

[work]
skip_permissions = true  # Skip opencode permission prompts
auto_implement = true    # Auto-run implement command

[vcs]
prefer = "auto"  # auto, git, jujutsu

[editor]
# Uses $EDITOR environment variable by default
# command = "vim"

• EDITOR - Editor to use when editing changes (overrides config)
• PEBBLES_CHANGE - Set when running from a workspace
• PEBBLES_VCS - The detected version control system

Changes are stored in .pebbles/db.json as a human-readable JSON database.

When you run pebbles start <id>, it:

1. Creates a workspace (ws-<id>/) if --isolate is specified
2. Sets PEBBLES_CHANGE=<id> environment variable
3. Launches opencode with the change context
4. Auto-runs /implement (unless --wait is specified)

The .opencode/commands/ directory contains:

• implement.md - Guide for AI implementation
• describe.md - Commit message generator

The intake command allows you to create multiple related changes from a single text input. This is useful for importing feature requests, bug reports, or planning documents.

# Read from a file
pebbles intake features.txt

# Read from STDIN
cat features.txt | pebbles intake

The text is passed to opencode, which will:

1. Parse the content to identify a parent/top-level issue
2. Identify all child/sub-tasks
3. Create the parent change
4. Create all child changes linked to the parent

This creates a hierarchical structure of related work items.

Use the block command to mark one change as dependent on another:

# Mark change-456 as blocked by change-123
pebbles block change-456 change-123

Use unblock to remove a dependency:

pebbles unblock change-456 change-123

The plan command uses AI to break down a change into actionable steps:

# Plan the current change or specify an ID
pebbles plan
pebbles plan <id>

# Open in TUI without auto-running /plan
pebbles plan --wait

This creates a detailed implementation plan as a child change.

When working inside a workspace:

# Show the current change
pebbles current

# Show workspace status
pebbles status

# Edit the current change in your editor
pebbles edit

# Filter by status
pebbles list --status inprogress

# Filter by priority
pebbles list --priority high

# Filter by changelog type
pebbles list --changelog feature

# Sort by different fields
pebbles list --sort priority
pebbles list --sort created --reverse

# Flat list instead of tree view
pebbles list --flat

# Skip permission prompts
pebbles start <id> --skip-permissions

# Verbose output
pebbles start <id> --verbose

# Verify all acceptance criteria are checked
pebbles done <id> --auto

# Force mark done even if criteria not met
pebbles done <id> --force

MIT