CLI Tasks - Scrum/Kanban Task Management

A command-line task management system that uses Markdown files as storage. Perfect for both human developers and AI agents working on projects.

Install

Build from source (requires Go 1.22+):

git clone https://github.com/GuitarWag/clitasks.git
cd clitasks
make install        # puts `tasks` in $GOBIN (or $GOPATH/bin)

Or build a local binary:

make build          # produces bin/tasks

To verify it works:

tasks --version

Claude Code Skill

To add the skill to Claude Code (for enhanced AI task management):

# Install globally for all projects
tasks claude -g

# Or install locally for current project only
tasks claude

Codex CLI Skill

To add the skill to Codex CLI (OpenAI's coding agent):

# Install globally for all projects
tasks codex -g

# Or install locally for current project only
tasks codex

Features

• Markdown-based storage: Tasks are stored in human-readable .md files
• Kanban board: Organize tasks in TODO, IN PROGRESS, DONE, and BLOCKED columns
• Rich task metadata: Priority, assignee, tags, due dates, descriptions
• CLI interface: Fast and efficient command-line operations
• Interactive TUI: Beautiful terminal UI with keyboard navigation
• Real-time filtering: Search tasks across all columns instantly
• Quick actions: Keyboard shortcuts for common operations
• AI-friendly: Both humans and AI agents can read and edit the same task board
• Portable: No database required, just a simple Markdown file

Usage

Interactive TUI (Recommended for Daily Use)

Launch the beautiful Terminal UI for visual task management:

tasks tui

Features:

• 📊 Column-based kanban view with color coding
• ⌨️ Keyboard navigation with arrow keys or Vim-style (hjkl)
• ✏️ In-place editing of tasks
• 🔍 Real-time filtering across all columns
• ⚡ Quick actions menu for status changes
• 📋 Task details shown on selection

See TUI_GUIDE.md for complete documentation.

Command-Line Interface

For scripts, automation, or quick operations:

Initialize a Board

tasks init --name "My Project" --description "Project task board"

This creates a tasks.md file in the current directory.

Add Tasks

# Basic task
tasks add "Implement login feature"

# Task with full metadata
tasks add "Fix authentication bug" \
  -d "JWT tokens are expiring too quickly" \
  -p high \
  -a alice \
  -t backend,security \
  --due 2026-02-15

Options:

• -d, --description <desc>: Task description
• -p, --priority <priority>: Priority (low|medium|high|critical)
• -a, --assignee <name>: Assignee name
• -t, --tags <tags>: Comma-separated tags
• --due <date>: Due date (YYYY-MM-DD)

View Tasks

# View kanban board
tasks board

# List all tasks
tasks list

# List with filters
tasks list --status todo
tasks list --priority high
tasks list --assignee alice
tasks list --tags backend

# Show detailed task information
tasks show T-ML31897Y-TKP

Update Tasks

# Update task details
tasks update T-ML31897Y-TKP \
  -t "Implement authentication API" \
  -p critical \
  -a bob

# Move task to different status
tasks move T-ML31897Y-TKP in-progress

# Shortcuts for common status changes
tasks start T-ML31897Y-TKP     # Move to in-progress
tasks complete T-ML31897Y-TKP   # Move to done
tasks block T-ML31897Y-TKP      # Move to blocked

Delete Tasks

tasks delete T-ML31897Y-TKP

Board Information

tasks info

Board Statistics

# View comprehensive statistics
tasks stats

Shows:

• Status breakdown (TODO, IN PROGRESS, DONE, BLOCKED)
• Priority distribution
• Assignee workload
• Completion rate

Export Data

# Export as JSON (default)
tasks export

# Export as CSV
tasks export --format csv

# Export summary
tasks export --format summary

# Save to file
tasks export --format json -o backup.json
tasks export --format csv -o report.csv

Note: --format is long-only because the root -f short flag is reserved for --file.

Using Custom File

By default, tasks are stored in tasks.md. You can specify a different file:

tasks -f project-tasks.md board
tasks --file sprint-1.md add "New feature"

# Or use environment variable
export TASK_BOARD_FILE=my-tasks.md
tasks board

Markdown Format

The task board is stored in a human and AI-readable Markdown format:

# Board: Project Alpha
> Description: Main development board
> Created: 2026-02-01T00:58:17.796Z | Updated: 2026-02-01T00:58:22.510Z

## TODO

- [ ] [T-ABC123] **Implement user authentication** `priority:high` `assignee:alice` `tags:backend,security` `due:2026-02-15`
  > Add JWT-based authentication system
  > Created: 2026-02-01T00:58:22.510Z | Updated: 2026-02-01T00:58:22.510Z

## IN PROGRESS

- [>] [T-DEF456] **Create database schema** `priority:medium` `assignee:bob` `tags:backend,database`
  > Design and implement PostgreSQL schema
  > Created: 2026-02-01T00:58:22.510Z | Updated: 2026-02-01T00:58:22.510Z

## DONE

- [x] [T-GHI789] **Setup project repository** `priority:high` `assignee:alice` `tags:devops`
  > Initialize Git repo and CI/CD
  > Created: 2026-02-01T00:58:22.510Z | Updated: 2026-02-01T00:58:22.510Z

## BLOCKED

- [!] [T-JKL012] **Deploy to production** `priority:critical` `assignee:bob` `tags:devops,deployment`
  > Waiting for infrastructure approval
  > Created: 2026-02-01T00:58:22.510Z | Updated: 2026-02-01T00:58:22.510Z

Use Cases

For Human Developers

# Morning routine: check what's on the board
tasks board

# Start working on a task
tasks start T-ABC123

# Check your assigned tasks
tasks list --assignee yourname

# Mark task as complete
tasks complete T-ABC123

For AI Agents

AI agents can use the same CLI commands:

# AI reads the board to understand current work
tasks board

# AI creates a task for work it's about to do
tasks add "Implement error handling" -a claude -t backend

# AI updates task status as it works
tasks start T-XYZ789
# ... do work ...
tasks complete T-XYZ789

AI agents can also directly read/parse the tasks.md file to understand the project context.

For Teams

# View team workload
tasks list --detailed

# Check blocked items
tasks list --status blocked

# Filter by sprint tag
tasks list --tags sprint-1

# View critical items
tasks list --priority critical

# View board statistics
tasks stats

# Export data for reporting
tasks export --format csv -o sprint-report.csv
tasks export --format json -o tasks-backup.json

Development

make build         # bin/tasks
make test          # go test ./... -race
make lint          # golangci-lint
make run ARGS="board"   # go run ./cmd/tasks board

The canonical SKILL.md lives at the repo root and is embedded into the binary via go:embed. make sync-skill (run automatically by make build and make test) copies it into internal/cli/SKILL.md. If you run go test ./... directly on a clean checkout, run make sync-skill first so the embed file exists.

Layout:

• cmd/tasks/ — binary entry
• internal/model/ — Task / Board types
• internal/storage/ — Markdown parser + atomic writer
• internal/board/ — Board service
• internal/export/ — JSON / CSV / summary
• internal/cli/ — Cobra commands (and embedded SKILL.md)
• internal/tui/ — Bubble Tea program

License

ISC