sb-tracker 0.1.0

A minimal, standalone issue tracker for individuals. No git hooks, no complex dependencies, just one JSON file.

SB Tracker - Simple Beads

A lightweight, standalone task tracker that stores state in a local .sb.json file. Perfect for individuals and agents to maintain context and track long-running or multi-step tasks without external dependencies.

Features

• Zero Dependencies: Pure Python, uses only stdlib (json, os, sys, datetime)
• Standalone: One JSON file stores all state locally
• Hierarchical Tasks: Support for sub-tasks with parent-child relationships
• Priority Levels: Tasks support P0-P3 priority levels
• Task Status Tracking: Open/closed status with timestamps
• Dependencies: Link tasks with blocking dependencies
• Audit Log: Track all changes to each task with timestamps
• JSON Export: Machine-readable output for integration
• Compaction: Archive closed tasks to keep context efficient

Installation

From PyPI (when published)

pip install sb-tracker

From Source

git clone https://github.com/sirius-cc-wu/sb-tracker.git
cd sb-tracker
pip install -e .

Quick Start

Initialize a new task tracker:

sb init

Add a task:

sb add "My first task"
sb add "High priority task" 0 "This is urgent"

List tasks:

sb list              # Show open tasks
sb list --all        # Show all tasks
sb list --json       # Machine-readable output

Complete a task:

sb done sb-1

Commands

Create and Modify

• init: Initialize .sb.json in the current git repository root
• add <title> [priority] [description] [parent_id]
  • Example: sb add "Setup database" 1 "Configure PostgreSQL" sb-1
• update <id> [field=value ...]
  • Fields: title, desc, p (priority), parent
  • Example: sb update sb-1 p=0 desc="New description"
• dep <child_id> <parent_id>: Add a blocking dependency
  • Example: sb dep sb-2 sb-1 (sb-2 blocked by sb-1)

List and Search

• list [--all] [--json]: Show open (or all) tasks with hierarchy
• ready [--json]: Show tasks with no open blockers
• search <keyword> [--json]: Search titles and descriptions

Reporting and Maintenance

• show <id> [--json]: Display task details with audit log
• promote <id>: Generate Markdown summary of task and sub-tasks
• stats: Overview of progress and priority breakdown
• compact: Archive closed tasks to save space
• done <id>: Mark task as closed
• rm <id>: Permanently delete task

Workflow

For Individual Sessions

1. Breakdown: Create tasks with hierarchies for complex work

   sb add "Implement feature X"                    # Creates sb-1
   sb add "Write unit tests" 1 "" sb-1             # Creates sb-1.1
   sb add "Write integration tests" 1 "" sb-1      # Creates sb-1.2
   

2. Execute: Focus on high-priority ready tasks

   sb ready  # Show tasks with no blockers
   

3. Track Progress: Update as you complete steps

   sb done sb-1.1
   sb done sb-1.2
   

4. Report: Generate summary when handing off

   sb promote sb-1
   

Task ID Format

• Root tasks: sb-1, sb-2, etc.
• Sub-tasks: sb-1.1, sb-1.2, sb-1.1.1, etc.
• Parent relationship: Use parent ID in add or update

Priority Levels

• P0: Critical, blocking everything
• P1: High priority, do soon
• P2: Normal priority (default)
• P3: Low priority, nice to have

Database Format

Tasks are stored in .sb.json (found in git repository root) with this schema:

{
  "issues": [
    {
      "id": "sb-1",
      "title": "Task title",
      "description": "Optional description",
      "priority": 1,
      "status": "open",
      "depends_on": ["sb-2"],
      "parent": "sb-1",
      "created_at": "2026-02-04T18:40:10.692Z",
      "closed_at": "2026-02-04T19:40:10.692Z",
      "events": [
        {
          "type": "created",
          "timestamp": "2026-02-04T18:40:10.692Z",
          "title": "Task title"
        }
      ]
    }
  ],
  "compaction_log": []
}

Examples

Hierarchical Task Breakdown

$ sb add "Build authentication system"
Created sb-1: Build authentication system (P2)

$ sb add "Design schema" 1 "" sb-1
Created sb-1.1: Design schema (P1)

$ sb add "Implement login endpoint" 1 "" sb-1
Created sb-1.2: Implement login endpoint (P1)

$ sb add "Write tests" 2 "" sb-1
Created sb-1.3: Write tests (P2)

$ sb list
ID           P  Status       Deps       Title
sb-1         2  open                    Build authentication system
sb-1.1       1  open                      Design schema
sb-1.2       1  open                      Implement login endpoint
sb-1.3       2  open                      Write tests

Blocking Dependencies

$ sb add "Deploy to production" 1
Created sb-2: Deploy to production (P1)

$ sb dep sb-2 sb-1
Linked sb-2 -> depends on -> sb-1

$ sb ready
No issues found matching criteria.

$ sb done sb-1.1
Updated sb-1.1 status to closed

$ sb done sb-1.2
Updated sb-1.2 status to closed

$ sb done sb-1.3
Updated sb-1.3 status to closed

$ sb done sb-1
Updated sb-1 status to closed

$ sb ready
ID           P  Status       Deps       Title
sb-2         1  open                    Deploy to production

Task Reporting

$ sb promote sb-1
### [sb-1] Build authentication system
**Status:** closed | **Priority:** P2

#### Sub-tasks
- [x] sb-1.1: Design schema
- [x] sb-1.2: Implement login endpoint
- [x] sb-1.3: Write tests

#### Activity Log
- 2026-02-04: Created
- 2026-02-04: Status: open -> closed

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Troubleshooting

.sb.json not found

The tracker looks for .sb.json starting from the current directory and walking up the directory tree until it finds a .git directory (to keep data project-local). If not found, it creates .sb.json in the current working directory.

To initialize:

cd /your/project
sb init

Task not found error

Make sure you're using the correct task ID:

$ sb list --json   # See all task IDs

Compaction

Archive old tasks to reduce token context:

sb compact

This moves all closed tasks to a compaction_log and keeps them accessible via list --all or list --json.