Get ticks running in minutes

01 Install

ticks ships as a single Go binary with no runtime dependencies. Install with the one-liner — macOS and Linux:

curl -fsSL https://ticks.sh/install | sh

Verify the install:

tk --version

Add the ticks skill

The tk binary handles issue tracking. The ticks skill is what teaches Claude Code or Codex to plan epics and orchestrate agent swarms. Install it once per machine:

npx skills add pengelbrecht/ticks

Your agent picks it up automatically the next time you ask it to plan or run an epic.

02 Issue-Tracker Foundation

ticks stores issues as JSON files directly in your repository under .tick/. There is no external service to set up — just initialize and start tracking.

Initialize a repo

cd my-project
tk init          # creates .tick/ — commit it to git

Create and move issues

# Create a new issue with a title
tk create "Fix login bug"

# List tasks that are ready to work on
tk ready

# Pull the next ready issue onto your plate
tk next

# List all open issues
tk ls

Common status transitions

• tk create "Title" — new issue in backlog
• tk ready — list tasks that are ready to work on
• tk next — claim the top-priority ready issue (in-progress)
• tk close <id> --reason "..." — close as completed
• tk block <id> <blocker-id> — declare that <id> is blocked by <blocker-id>

For the full command reference, see the GitHub README.

03 Orchestration: Running Agent Swarms

ticks shines when you have an epic — a collection of related ticks — and want multiple AI agents to work on them in parallel, each in its own isolated git worktree, then integrate wave by wave.

Plan an epic

Create a parent epic tick and break it down into child ticks with dependencies. Once installed (see step 01), the ticks skill can help you plan:

# Create parent epic
tk create "Redesign auth flow" --type epic

# Add child ticks that belong to the epic
tk create "Set up DB schema" --parent <epic-id>

Visualize the dependency graph

Before dispatching agents, print the wave structure so you can see which ticks can run in parallel and which must wait:

tk graph <epic-id>

Output example:

Dispatch one agent per wave

The ticks skill loaded in Claude Code handles this for you. For each wave, it spawns one Claude Code agent per tick, each working in an isolated git worktree so they cannot conflict:

# The ticks skill runs inside Claude Code — just tell it:
# "run the next wave of epic <epic-id>"
#
# Under the hood it does something equivalent to:
git worktree add ../.ticks-worktrees/abc tick/auth/abc
git worktree add ../.ticks-worktrees/def tick/auth/def
# ... one worktree per tick in the wave

Integrate wave by wave

After each wave completes, review and merge the worktrees in dependency order before proceeding to the next wave:

# Review each worktree's diff, run tests, then merge
git merge tick/auth/abc
git merge tick/auth/def

# Close ticks, then trigger Wave 2
tk close abc --reason "Completed: DB schema landed"
tk close def --reason "Completed: auth middleware landed"

The ticks skill tracks which waves have been integrated and what is still pending, so you can hand off and resume at any point without losing context.

Learning loop: retro → promote → reuse

When an epic closes, run a structured retro that harvests what worked and what broke, then promotes those learnings into .tick/learnings.md and any relevant repo docs. Every future planning pass and implementer reads this durable, version-controlled memory — so the same mistakes don't repeat across epics and the orchestration improves over time.

04 Watching Progress

Use the board to see all ticks move through their columns in real time while agents work.

tk board         # opens a web board at localhost:3000

The board updates live as agents move ticks through their columns — blocked, ready, in progress, needs human, done.