A lightweight JSONL-based issue tracker with CLI and React UI
npm install @markmdev/pebbleA lightweight, JSONL-based issue tracker with CLI and React UI.
- Simple storage: Append-only JSONL file enables full history
- Git-like discovery: Auto-discovers .pebble/ directory upward
- JSON-first output: JSON by default, --pretty for human-readable
- Dependencies: Block issues on other issues, cycle detection
- React UI: View issues, filter, sort, dependency graph visualization
``bash`
npm install -g @markmdev/pebble
After installation, the pb command is available globally.
`bashCreate your first issue (auto-initializes .pebble/ directory)
pb create "Fix login bug" -t bug -p 1
Commands
$3
| Command | Description |
|---------|-------------|
|
pb ready | Issues with no open blockers |
| pb blocked | Issues with open blockers |
| pb list [options] | List issues with filters |
| pb show | Full issue details |$3
| Command | Description |
|---------|-------------|
|
pb create | Create an issue |
| pb update | Update issues (supports batch) |
| pb claim | Set status to in_progress (shorthand) |
| pb close | Close issues (supports batch) |
| pb reopen | Reopen an issue |$3
| Command | Description |
|---------|-------------|
|
pb dep add | Add blocking dependency |
| pb dep remove | Remove dependency |
| pb dep list | Show dependencies |
| pb dep tree | Show dependency tree |$3
| Command | Description |
|---------|-------------|
|
pb comments add | Add a comment |
| pb graph [--root id] | Show dependency graph |
| pb ui [--port 3333] | Serve React UI |Options
$3
-
--pretty — Human-readable output (default: JSON)
- --help — Show help$3
-
-t, --type — Issue type: task, bug, epic (default: task)
- -p, --priority — Priority: 0=critical, 4=backlog (default: 2)
- -d, --description — Description
- --parent — Parent issue ID$3
-
--status — Filter by status
- --type — Filter by type
- --priority — Filter by priority
- --parent — Filter by parent$3
-
--status — Set status
- --priority — Set priority
- --title — Set title
- --description — Set descriptionData Model
$3
`typescript
{
id: string; // PREFIX-xxxxxx
title: string;
type: 'task' | 'bug' | 'epic';
priority: 0-4; // 0=critical, 4=backlog
status: 'open' | 'in_progress' | 'blocked' | 'closed';
description?: string;
parent?: string; // Parent issue ID
blockedBy: string[]; // IDs of blocking issues
comments: Comment[];
createdAt: string;
updatedAt: string;
}
`$3
All data is stored in
.pebble/issues.jsonl as append-only events:
- create — New issue
- update — Field changes
- close — Close with reason
- reopen — Reopen with reason
- comment — Add commentUI Features
The React UI (
pb ui) provides full CRUD capabilities with real-time updates:- Issue List: Hierarchical view (epics with children), sorting, filtering, search
- Create Issues: "New Issue" button opens creation dialog
- Inline Editing: Click title to edit, status/priority dropdowns, description editing
- Issue Actions: Close/reopen, add comments, manage blockers
- Dependency Graph: Interactive visualization with parent-child and blocker edges
- History View: Timeline of all events, filterable by type
- Real-time Sync: Changes from CLI automatically appear in UI via SSE
- Breadcrumbs: Navigation trail for easy orientation
Business Rules
1. Ready: Non-closed issue where all
blockedBy issues are closed
2. Blocked: Issue has at least one open blocker
3. Epic close: Cannot close epic if any child is not closed
4. Cycle detection: Cannot create circular dependencies
5. ID resolution: Partial IDs work (case-insensitive prefix match)Development
`bash
Install dependencies
npm installBuild
npm run buildRun tests
npm testType check
npm run typecheck
``MIT