Features

Available Beta

Item Types

Seven item types cover every kind of work:

Type	Purpose
`epic`	Large initiative grouping multiple items
`story`	User-facing functionality
`task`	Technical work, not directly visible to users
`bug`	Something is broken
`rework`	Refactoring or improvement of existing code
`decision`	Architecture or product decision to document
`idea`	Not yet refined - capture it before it escapes

joy add epic "Recipe Management"
joy add story "Add a recipe" --parent CB-0001 --priority high
joy add bug "Login fails on empty password" --priority critical
joy add decision "Use SQLite for local storage"

Status Workflow

Items move through a defined lifecycle:

new -> open -> in-progress -> review -> closed
         \                      |
          +---> deferred <------+

joy status CB-0002 open
joy start CB-0002                # Shortcut: set to in-progress
joy submit CB-0002               # Shortcut: set to review
joy close CB-0002                # Shortcut: set to closed
joy reopen CB-0002               # Reopen a closed or deferred item

Dependencies

Define what must be done before something else can start:

joy deps CB-0002 --add CB-0003   # CB-0002 depends on CB-0003
joy deps CB-0002                 # List dependencies
joy deps CB-0002 --tree          # Show full dependency tree
joy ls --blocked                 # Show items with unfinished dependencies

Joy detects circular dependencies and refuses to create them.

Milestones

Plan releases and track progress toward delivery targets:

joy milestone add "MVP" --date 2026-04-01
joy milestone link CB-0002 CB-MS-01
joy milestone show CB-MS-01      # Progress, risks, blocked items
joy roadmap                      # Full roadmap tree view

Children inherit their parent's milestone automatically.

Releases

Generate release snapshots from the event log:

joy release create patch         # Next patch version
joy release create minor         # Next minor version
joy release show                 # Preview the next release
joy release ls                   # List all releases

Event Log

Every command produces a structured, timestamped event committed to Git:

joy log                          # Last 20 events
joy log --since 7d               # Last 7 days
joy log --item CB-0005           # Events for a specific item

AI Integration

joy ai setup                     # Configure AI tool integration
joy project member add ai:claude@joy --capabilities "implement,review"

AI actions are traced in the event log with delegation chains showing who authorized each action.

Project Configuration

Layered configuration: personal overrides, project defaults, and built-in fallbacks:

joy config                       # Show all resolved values
joy config set output.emoji true # Set a personal override
joy project set language de      # Change project language

Commit-Msg Hook

Installed via joy init. Enforces that every commit message references at least one item ID:

git commit -m "feat(db): add migration CB-0005"     # OK
git commit -m "chore: bump dependencies [no-item]"   # OK (explicit opt-out)
git commit -m "fix typo"                              # REJECTED

Coming Next Planned

TUI

Interactive terminal UI for browsing and editing the backlog. Keyboard-driven, real-time navigation.

Notifications

Get notified about status changes, mentions, blocked items, and milestone risks.

Advanced Search

Full-text search across item titles, descriptions, and comments with regex support.

Custom Fields

Define project-specific fields on items for domain-specific tracking needs.

On this page