Skills for using yaks (yx) — TODO list CLI for software teams
npx claudepluginhub mattwynne/yaksSkills for mapping, preparing, and working on yaks
mattwynneIt is in the doing of the work that we discover the work that we must do
-- Woody Zuill, https://agilemaxims.com
yx (yaks) is a command-line tool for managing a shared TODO list
as a tree of nested goals. It's designed for teams — humans and AI
agents working together on the same codebase.
Everyone on the team works from the same yak map. Changes sync through git with zero merge conflicts, so you never have to coordinate who's updating the plan.
Simple. Everything is a yak. No epics, stories, tasks, bugs, or chores. No priority fields, assignees, or estimates. Three states: todo, wip, done. Use tags and custom fields to model your own workflow.
Collaborative. Yaks uses event sourcing on a hidden git ref.
Changes from any branch, clone, or worktree merge automatically —
no conflicts, no coordination, no extra infrastructure. If you can
git push, you can share yaks.
Delightful. We've designed the ergonomics for both humans and agents. Robots get fogiving command and argument aliases to allow for clumsy assumptions, and JSON output as standard. Humans get a thoughtful, responsive UX with fuzzy name matching, tab completion and useful, thought-out views of the map.
yx add Fix the bug # Add a new yak
yx add Buy milk --under Fix the bug # Nest under a parent
yx context Fix the bug # Add context/notes
yx show Fix the bug # Show yak details
yx ls # Show the tree
yx state Fix the bug wip # Mark as work-in-progress
yx done Fix the bug # Mark as complete
yx sync # Sync with teammates
yx rm Fix the bug # Remove a yak
yx prune # Remove all done yaks
The name comes from yak shaving — when you set out to do task A but discover you need B first, which requires C. A Yak Map captures this emergent structure as a tree.
It's the same idea as a Mikado Graph or a Discovery Tree, but I like calling it a Yak Map, because yak shaving is what we do all day in software.
Add instructions to your CLAUDE.md or AGENTS.md telling your
agent to use yx commands.
yx ls --format json # Discover work
yx state "fix the bug" wip # Claim a yak
echo "notes" | yx field "fix the bug" progress # Store notes
yx done "fix the bug" # Complete work
yx sync # Sync with teammates
Multiple agents can update the yak map simultaneously. The event-sourced CRDT merge means their changes never conflict.
Beads is a powerful issue tracker built for AI agents. It has 81 fields per task, 19 dependency types, a SQL/Dolt database, and workflow templates. If you want a comprehensive system for orchestrating agents, it's impressive.
Yaks takes the opposite approach. It's a sharp, simple tool that trusts teams to self-organise:
Yaks grew out of years of practice with XP, mob programming, and collaborative planning on human teams. Beads grew out of the single-user-multi-agent workflow. Different roots, different trade-offs.
curl -fsSL https://raw.githubusercontent.com/mattwynne/yaks/main/install.sh | bash
The installer downloads the latest release, validates the checksum
and installs the binary in /usr/local/bin. It also installs shell
completions so you can tab-complete yak names.
See CONTRIBUTING.md for development setup, testing, and mutation testing instructions.