| name | bits |
| description | Track and manage work items, tasks, issues, and todos with dependencies using bits. Use when user needs to create tasks, track progress, manage blockers, find ready work, claim/release tasks, close completed work, or organize multi-step projects. Triggers on "bits", "task", "issue", "backlog", "blockers", "dependencies", "what's ready", "track this", "add to my list", "what should I work on". |
| user-invocable | false |
| argument-hint | [command or task description] |
| allowed-tools | ["Bash(bits:*)","Bash(git:*)","Read"] |
Bits Task Tracking
Bits Are Immutable
Once created, bits cannot be updated. This means:
- No checkboxes in descriptions (you can't check them off)
- No sub-tasks in descriptions (you can't mark them complete)
- No progress tracking within a single bit
Instead: Create more bits. They're free. Break work into atomic pieces and link them with dependencies using bits dep <id> <blocker-id>.
bits add "Implement auth" -d "- [ ] Add login\n- [ ] Add logout\n- [ ] Add session"
bits add "Add login endpoint" -d "POST /login with JWT" --json
bits add "Add logout endpoint" -d "POST /logout invalidates token" --json
bits add "Add session middleware" -d "Validate JWT on protected routes" --json
bits dep <logout-id> <login-id>
bits dep <session-id> <login-id>
When to Use
| Scenario | Tool |
|---|
| Multi-step work with dependencies | bits |
| Tasks that block other tasks | bits |
| Tracking progress across sessions | bits |
| Simple one-off checklist | TaskCreate |
| Quick session-scoped todos | TaskCreate |
Commands
| Task | Command |
|---|
| Find ready work | bits ready --json |
| Create task | bits add "Title" -d "Description" --json |
| Start work | bits claim <id> |
| Pause work | bits release <id> |
| Complete work | bits close <id> "reason" |
| View details | bits show <id> |
| List tasks | bits list |
Run bits --help for full reference.
Dependencies
bits add "Feature B" --json
bits dep bits-abc123 bits-blocker
Tasks with unresolved dependencies won't appear in bits ready.
Session Commands
| Command | Purpose |
|---|
bits session claim | Claim primary session (reads stdin) |
bits session release | Release session (reads stdin) |
bits session prune | Manual cleanup of stale sessions |
bits session hook | Stop hook with session ownership check |
bits session compact | Output drain context after compaction (for hooks) |
Drain Commands
| Command | Purpose |
|---|
bits drain claim | Activate drain mode |
bits drain release | Deactivate drain mode (fails if tasks remain) |
bits drain release --force | Suspend drain mode (for replan/escalation) |
Task Description Format
# Context
What this task solves and why.
# Acceptance Criteria
Concrete conditions that must be true when done:
- Criterion 1
- Criterion 2
# Verification Commands
- `mise run lint`
- `mise run test`
Do not use checkboxes in descriptions — bits are immutable so checkboxes cannot be checked off. State criteria as plain text.
Do NOT Close If
- Tests failing
- Implementation partial
- Unresolved errors
Instead: Create new blocker bits and add them as dependencies.
