tracker

Tracker

A command-line project management tool inspired by Pivotal Tracker, with an interactive TUI.

For the children. Thanks to all my friends and colleagues for the memories.

Features

• Story Management: Create, edit, and track features, bugs, and chores
• Workflow States: Prescriptive workflow (unscheduled → unstarted → started → finished → accepted)
• Velocity Tracking: Automatic calculation based on completed iterations
• Iteration Planning: Organize work into time-boxed iterations
• Interactive TUI: Full-featured terminal user interface with Bubble Tea
• Human-readable Data: YAML config and JSONL storage

Installation

go install github.com/cboone/tracker/cmd/tracker@latest

Or build from source:

git clone https://github.com/cboone/tracker
cd tracker
go build -o tracker ./cmd/tracker

Quick Start

# Initialize a new project
tracker init "My Project"

# Add stories
tracker add "User authentication" -t feature -p 3 -l auth -l mvp
tracker add "Fix login crash" -t bug -l urgent
tracker add "Setup CI" -t chore

# Move to backlog and start working
tracker move 1 backlog
tracker start 1

# Complete the workflow
tracker finish 1
tracker accept 1

# Check status
tracker status

# Open interactive TUI
tracker

Commands

Project Management

Story CRUD

Add Flags

• -t, --type: Story type (feature, bug, chore)
• -p, --points: Story points (0, 1, 2, 3, 5, 8)
• -l, --label: Labels (repeatable)
• -d, --description: Description
• --panel: Initial panel (icebox, backlog)

Workflow

Iterations

Interactive TUI

Run tracker without arguments to open the interactive interface.

Keyboard Shortcuts

Story Types

Workflow States

┌─────────────┐   ┌─────────────┐   ┌──────────┐   ┌─────────────┐   ┌──────────┐
│ unscheduled │──▶│  unstarted  │──▶│ started  │──▶│  finished   │──▶│ accepted │
│  (icebox)   │   │  (backlog)  │   │          │   │             │   │  (done)  │
└─────────────┘   └─────────────┘   └──────────┘   └─────────────┘   └──────────┘
                                                          │
                                                          │ reject
                                                          ▼
                                                   ┌─────────────┐
                                                   │  rejected   │
                                                   └─────────────┘

Note: Chores skip the finished state and go directly from started to accepted.

Panels

Data Storage

All data is stored in the .tracker/ directory:

• config.yaml: Project configuration
• stories.jsonl: Story data in JSON Lines format

Example Config

name: "My Project"
velocity: 8
iteration_length: 1
point_scale: [0, 1, 2, 3, 5, 8]
iteration_start: "2024-01-13"

Example Story

{"id":1,"type":"feature","title":"User login","state":"started","points":3,"labels":["auth"],"panel":"backlog","position":1,"created_at":"...","updated_at":"..."}

Velocity

Velocity is automatically calculated as the average points completed over the last 3 iterations.

Development

Prerequisites

• Go 1.25 or later

Building

go build -o tracker ./cmd/tracker

Testing

This project uses Go's built-in testing for unit tests and scrut for end-to-end CLI tests.

# Run Go unit tests
go test ./...

# Run Go unit tests with verbose output
go test -v ./...

# Run Go unit tests with coverage
go test -cover ./...

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run Scrut end-to-end tests
scrut test tests/e2e/

Linting

go vet ./...

Project Structure

cmd/tracker/     # Application entry point
internal/
  cli/           # Command-line interface (Cobra commands)
  config/        # Configuration handling
  domain/        # Core domain types (Story, Iteration, Velocity)
  storage/       # Data persistence (JSONL)
  tui/           # Terminal UI (Bubble Tea)

License

MIT