Agent-first task management for codebases. Designed for AI agents working alongside humans.

Traditional task management is built for humans pushing updates. Tasuku flips this:

• Pull over push: Agents query when needed, no constant context injections
• Parallel-safe: Per-file locking for multiple agents working simultaneously
• Minimal context: Only load what's needed for the current task
• Human-readable: Markdown files with YAML frontmatter (V4), can be edited by hand
• Git-friendly: One file per task means clean diffs and fewer merge conflicts
• Rich content: Full Markdown support with code blocks, lists, and formatting

git clone https://github.com/iheanyi/tasuku.git
cd tasuku
go build -o tk ./cmd/tk
sudo mv tk /usr/local/bin/  # or add to your PATH

go install github.com/iheanyi/tasuku/cmd/tk@latest

# Initialize in your project
cd your-project
tk init                     # Creates .tasuku/ directory
git add .tasuku/            # Commit tasks so they travel with your code

# Add some tasks
tk task add "Implement user authentication"
tk task add "Write API documentation" --priority high
tk task add "Set up CI pipeline"

# Add subtasks
tk task add "Create login form" --parent implement-user-authentication

# Start working on a task
tk task start implement-user-authentication

# Mark it done
tk task done implement-user-authentication

# See all tasks
tk task list                  # Table view
tk task list --tree           # Hierarchical subtask view
tk task list --format json    # Output as JSON

All list commands support the --format flag:

tk task list --format table  # Default, human-readable
tk task list --format json   # JSON output
tk task list --format yaml   # YAML output

Tasuku supports tab completion for commands, subcommands, flags, and task IDs.

# Bash (Linux)
tk completion bash | sudo tee /etc/bash_completion.d/tk > /dev/null

# Bash (macOS with Homebrew)
tk completion bash > $(brew --prefix)/etc/bash_completion.d/tk

# Zsh
echo 'source <(tk completion zsh)' >> ~/.zshrc

# Fish
tk completion fish > ~/.config/fish/completions/tk.fish

# Generate completion script
tk completion bash > /tmp/tk.bash

# Test in current session
source /tmp/tk.bash

# Install permanently (Linux)
sudo mv /tmp/tk.bash /etc/bash_completion.d/tk

# Install permanently (macOS)
# First install bash-completion: brew install bash-completion@2
tk completion bash > $(brew --prefix)/etc/bash_completion.d/tk
# Add to ~/.bash_profile:
# [[ -r "$(brew --prefix)/etc/profile.d/bash_completion.sh" ]] && source "$(brew --prefix)/etc/profile.d/bash_completion.sh"

# Option 1: Source directly (add to ~/.zshrc)
source <(tk completion zsh)

# Option 2: Install to fpath
tk completion zsh > "${fpath[1]}/_tk"
# Then reload: autoload -Uz compinit && compinit

# Option 3: Custom directory
mkdir -p ~/.zsh/completions
tk completion zsh > ~/.zsh/completions/_tk
# Add to ~/.zshrc before compinit:
# fpath=(~/.zsh/completions $fpath)

tk completion fish > ~/.config/fish/completions/tk.fish
# Fish auto-loads from this directory

After setup, you can tab-complete:

tk <TAB>                    # Shows: task, learning, decision, note, ...
tk task <TAB>               # Shows: list, add, show, start, done, ...
tk task list --<TAB>        # Shows: --format, --status
tk task start <TAB>         # Shows available task IDs
tk learning <TAB>           # Shows: list, add, remove, promote

Completions not working?

• Restart your shell after installing
• Zsh: Run compinit or restart terminal
• Bash: Ensure bash-completion is installed

"command not found: compdef" (Zsh)?

autoload -Uz compinit && compinit

Outdated completions? Regenerate with the same command after upgrading tk.

Start the REST API server:

tk serve http              # Starts on :3000 by default
tk serve http --port 8080  # Custom port

# Create a task
curl -X POST http://localhost:3000/tasks \
  -H "Content-Type: application/json" \
  -d '{"description": "Build login form", "priority": 1}'

# Update status
curl -X PUT http://localhost:3000/tasks/build-login-form \
  -H "Content-Type: application/json" \
  -d '{"status": "in_progress"}'

# Add a learning
curl -X POST http://localhost:3000/learnings \
  -H "Content-Type: application/json" \
  -d '{"learning": "JWT tokens expire after 24 hours"}'

Tasuku can auto-detect your AI tool context file and promote learnings there:

# List learnings
tk learning list

# Promote a learning to auto-detected context file
tk learning promote <learning-id>

# Promote to a specific file
tk learning promote <learning-id> --to .cursorrules

# Keep in Tasuku after promoting
tk learning promote <learning-id> --keep

Auto-detected context files (in priority order):

1. CLAUDE.md - Claude Code
2. GEMINI.md - Gemini
3. .cursorrules - Cursor
4. .github/copilot-instructions.md - GitHub Copilot
5. AGENTS.md - Generic AI agents

If none exist, defaults to creating CLAUDE.md.

Tasuku includes an MCP (Model Context Protocol) server for seamless integration with AI coding tools.

Supported tools:

• Claude Code
• Cursor
• Codex (OpenAI)
• OpenCode
• Gemini
• Any MCP-compatible agent

tk mcp install              # Auto-detect and install to all tools
tk mcp install --tool claude   # Claude Code only
tk mcp install --tool cursor   # Cursor only
tk mcp install --tool codex    # Codex only
tk mcp install --tool opencode # OpenCode only

This adds Tasuku to your tool's settings. Restart your tool to activate.

Note: The MCP server provides all 44 tools to any MCP-compatible agent. Skills (below) are an additional layer for Claude Code that provide guided workflows, but agents without skills support have full access via MCP tools.

Once installed, the agent has access to these tools:

Task Operations:

• tk_list, tk_add, tk_show, tk_edit, tk_delete - CRUD operations
• tk_start, tk_pause, tk_done - Status transitions
• tk_block, tk_unblock - Dependency management
• tk_priority - Set task priority
• tk_find - Search across tasks, notes, learnings
• tk_ready - List tasks ready to work on
• tk_deps - Show task dependency tree
• tk_stats - Project statistics and progress
• tk_health - Project health check with recommendations

Agent Coordination:

• tk_claim, tk_release, tk_owner - Task ownership for multi-agent work
• tk_who - Show tasks claimed by each owner

Tags & Fields:

• tk_tag_add, tk_tag_remove - Manage task tags
• tk_field_set, tk_field_remove - Custom metadata

Time Tracking:

• tk_timer_start, tk_timer_stop, tk_timer_status - Track time spent

Context:

• tk_context - Get full project context
• tk_learn, tk_decide, tk_note - Record knowledge
• tk_suggest - Check if task should persist to Tasuku

Learnings:

• tk_learning_list - List all learnings
• tk_learning_promote - Promote learning to permanent docs
• tk_learning_remove - Remove a learning
• tk_learning_rules - Find "never/always" patterns

Decisions:

• tk_decision_list - List all decisions
• tk_decision_remove - Remove a decision

Notes:

• tk_note_list - List notes for a task
• tk_note_remove - Remove a note

Archiving:

• tk_archive, tk_archive_list, tk_archive_restore - Archive management
• tk_archive_all - Archive all done tasks older than a duration

Rules Sync:

• tk_rules_sync - Sync learnings/decisions to editor rules directories

Claude Code supports the Tasuku plugin for slash command workflows:

Installation:

# In Claude Code, add the marketplace:
/plugin marketplace add https://github.com/iheanyi/tasuku

# Then install the plugin:
/plugin install tasuku

This enables all /tasuku:* commands:

Workflow Commands (Recommended)

Basic Commands

Restart Claude Code after installing for commands to take effect.

If you prefer manual setup, add this to ~/.claude.json:

{
  "mcpServers": {
    "tasuku": {
      "command": "/path/to/tk",
      "args": ["serve", "mcp"]
    }
  }
}

Launch an interactive terminal dashboard:

tk ui

Tasuku provides hooks for automating task management workflows with git and Claude Code.

# Install all hooks (git local + Claude global)
tk hooks install

# Install Claude hooks to project instead of global
tk hooks install --local

# Install only git hooks
tk hooks install --git

# Install only Claude Code hooks (global)
tk hooks install --claude

# Install Claude hooks to project .claude/
tk hooks install --claude --local

# Overwrite existing hooks
tk hooks install --force

Git hooks are always installed locally to .git/hooks/:

• pre-commit: Validates task files before committing
• post-commit: Auto-updates task status based on commit messages

Claude hooks can be global (~/.claude/settings.json) or local (./.claude/settings.json):

Use --local to install to project .claude/ for project-specific configuration.

Tasuku's hooks automatically prompt for knowledge capture at key moments:

1. Session Start: Shows context summary and active tasks
2. During Work: TodoWrite hook suggests persisting important todos
3. After Exploration: SubagentStop prompts for learnings from deep dives
4. Task Completion: MCP tool responses include reflection hints
5. Before Context Loss: PreCompact urgently prompts for decisions/learnings
6. Session End: Stop hook reminds about timers and prompts reflection

This ensures decisions and learnings are captured without manual prompting.

# Display session context summary
tk hooks session

# Check for end-of-session reminders
tk hooks stop-reminder

# Pre-compaction checkpoint (capture before context loss)
tk hooks pre-compact

# Analyze TodoWrite output for project-level tasks
tk hooks todo-check

# Extract tasks from a plan file
tk hooks plan-sync

# Remove all hooks
tk hooks uninstall

# Remove only Claude hooks (global)
tk hooks uninstall --claude

# Remove project-level Claude hooks
tk hooks uninstall --claude --local

Hooks support --quiet, --disable, and --list-features flags for customization:

# List available features
tk hooks prompt-check --list-features
tk hooks todo-check --list-features

# Quiet mode (reduced output)
tk hooks prompt-check --quiet

# Disable specific features
tk hooks prompt-check --disable=shipping_check,scope_warning
tk hooks todo-check --disable=test_failure

prompt-check features:

• Context surfacing: session_continuity, decision_lookup, learning_lookup, task_reference, task_surfacing
• Nudges: rule_detection, bug_detection, work_detection, stuck_detection, shipping_check, learning_capture, decision_capture, scope_warning

todo-check features:

• bugfix_learning, project_task, test_failure, git_commit

Hooks include version tracking to notify you when updates are available:

# At session start, if hooks are outdated:
# ⬆️  Hooks outdated (global): v0.6.0 → v0.6.1
#    Run: tk hooks install --force

# Update hooks
tk hooks install --force
tk hooks install --force --local  # For project-local hooks

Tasuku stores tasks as Markdown files with YAML frontmatter in the .tasuku/ directory:

.tasuku/
├── tasks/
│   └── task-id.md          # Markdown file per task
├── archive/
│   └── old-task.md         # Archived tasks
├── context/
│   ├── learnings.md        # Learnings in Markdown
│   └── decisions.md        # Decisions in Markdown
├── config.json             # Version marker (version: 4)
└── index.json              # Auto-generated index for fast queries

Task file (.tasuku/tasks/task-id.md):

---
status: ready
priority: 2
tags: [backend, api]
blocked_by: []
created_at: 2024-01-04T10:00:00Z
updated_at: 2024-01-04T10:00:00Z
---

# Implement user authentication

Add JWT-based authentication to protect API endpoints.

Support **rich formatting**, `inline code`, and code blocks:

```go
func ValidateToken(token string) (*Claims, error) {
    // Implementation
}

Started investigating authentication middleware options.

### V3 Format (Legacy JSON)

Directory-based JSON format. Use `tk migrate v4` to upgrade.

.tasuku/ ├── tasks/ │ └── task-id.json # JSON file per task ├── archive/ │ └── old-task.json # Completed/archived tasks └── context/ ├── learnings.json # Array of learnings └── decisions.json # Array of decisions

### V2 Format (Legacy)

Single `.tasuku.json` file with all data. Auto-detected for backwards compatibility.
Use `tk migrate v3` then `tk migrate v4` to upgrade.

### Task Statuses

- `ready` - Can be started
- `in_progress` - Currently being worked on
- `blocked` - Waiting on other tasks
- `done` - Completed

### Priority Levels

| Level | Name | Description |
|-------|------|-------------|
| 0 | Critical | Urgent, blocking issues |
| 1 | High | Important, do soon |
| 2 | Normal | Default priority |
| 3 | Low | Can wait |
| 4 | Backlog | Future work |

## Parallel Agent Safety

Tasuku uses `flock` for file locking, making it safe for multiple agents to work simultaneously:

```bash
# Agent 1                    # Agent 2
tk task start auth-task      tk task start api-task
# Both acquire locks safely, no corruption

V3's per-file locking means agents working on different tasks never block each other.

If you have an existing V3 .tasuku/ directory with JSON files:

# Preview the migration
tk migrate v4 --dry-run

# Run the migration (creates backup in .tasuku.v3.bak/)
tk migrate v4

If you have an existing .tasuku.json:

# Preview the migration
tk migrate v3 --dry-run

# Run the migration
tk migrate v3

# Then migrate to V4
tk migrate v4

If you have an existing .beads/ directory:

# Preview the migration
tk migrate beads --dry-run

# Run the migration
tk migrate beads

This converts your Beads issues to Tasuku tasks, preserving:

• Task status mapping (open->ready, in_progress->in_progress, closed->done, blocked->blocked)
• Priority levels
• Dependencies (blocked_by relationships)
• Close reasons as notes

# Run tests
go test ./...

# Run with race detector
go test -race ./...

# Build
go build -o tk ./cmd/tk

MIT