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

• 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, editable by hand
• Git-friendly: One file per task means clean diffs and fewer merge conflicts

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

Or build from source:

git clone https://github.com/iheanyi/tasuku.git
cd tasuku && go build -o tk ./cmd/tk
sudo mv tk /usr/local/bin/

cd your-project
tk init                    # Create .tasuku/ directory
tk mcp install             # Enable tk_* tools in your AI editor
tk hooks install           # Context at session start, reminders at end
git add .tasuku/           # Tasks travel with your code

Works with Claude Code, Cursor, Copilot CLI, Codex, and OpenCode. Restart your editor after installing.

MCP Tools (40+ tools, see docs/mcp.md):

• tk_add / tk_list / tk_done - Task management
• tk_learn / tk_decide - Knowledge capture
• tk_context - Load full project state

Slash Commands (Claude Code with plugin):

• /tasuku:pickup - Select and start a task
• /tasuku:complete - Mark done, capture learnings
• /tasuku:reflect - Extract learnings from recent work

tk task list                 # See all tasks
tk task add "New feature"    # Add a task
tk task start <id>           # Start working
tk task done <id>            # Mark complete
tk learn "insight"           # Record a learning
tk ui                        # Terminal UI (j/k to navigate, ? for help)

Full reference: docs/cli.md

Tasks are Markdown files with YAML frontmatter:

.tasuku/
├── tasks/task-id.md      # One file per task
├── archive/              # Archived tasks
├── context/
│   ├── learnings.md      # Recorded insights
│   └── decisions.md      # Architectural decisions
└── index.json            # Auto-generated for fast queries

tk migrate beads           # Convert .beads/ to .tasuku/
tk migrate beads --dry-run # Preview first

Detailed docs in docs/:

• cli.md - Complete CLI commands
• mcp.md - MCP tools and TUI keybindings
• hooks.md - Hook configuration
• plugins.md - Slash commands for AI tools
• storage.md - Storage format

go test ./...           # Run tests
go test -race ./...     # With race detector
go build -o tk ./cmd/tk # Build

MIT