ticks

ticks

A multiplayer-first issue tracker for AI coding agents.

curl -fsSL https://ticks.sh/install | sh
tk init
tk ready

Why Ticks?

The Problem

AI coding agents lose context between sessions. They forget what they were working on, what's blocked, and what they discovered along the way. Traditional issue trackers like GitHub Issues aren't designed for this—they're slow to query, require network access, and aren't optimized for agent workflows.

Ticks gives agents persistent memory that survives session restarts, context compaction, and even switching between different AI tools. Issues live in your repo as simple JSON files, tracked by git, queryable in milliseconds.

Why Not GitHub Issues?

• Speed: tk ready returns in ~35ms with 1000 issues. GitHub API calls take seconds.
• Offline: Works without network access.
• Agent-native: Commands like tk next and --json output are designed for agents.
• Git-tracked: Issues travel with your code. Branch, merge, fork—issues come along.
• Multiplayer: Built-in owner scoping for multi-agent collaboration.

GitHub recently added dependencies and sub-issues, but the API latency makes it impractical for agents that need to check status frequently.

Why Ticks Over Beads?

Ticks is a radically simpler alternative to beads. Both solve the same core problem—giving AI agents persistent memory across sessions—but with different tradeoffs.

Ticks is multiplayer-first: designed for teams where multiple developers each have their own agents. Commands show your issues by default (tk ready vs tk ready --all), making it natural for a team to share a repo without stepping on each other's work.

Both support multi-agent workflows via git worktrees—ticks' lack of a daemon is actually an advantage here, as beads' daemon doesn't work correctly with worktrees. The difference is ticks adds owner scoping for teams of humans, not just teams of agents.

Benchmarks

With 1000 issues, median times (ms):

Choose ticks if you want:

• Team-friendly multiplayer with owner scoping
• Simple flat files you can cat and debug
• No daemon, no SQLite, no infrastructure
• Git-native conflict resolution
• Minimal agent integration (add tk snippet to AGENTS.md, CLAUDE.md, or both)

Choose beads if you need:

• Advanced multi-agent coordination
• Automatic context injection via hooks

Install

Shell script (macOS/Linux)

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

PowerShell (Windows)

irm https://raw.githubusercontent.com/pengelbrecht/ticks/main/install.ps1 | iex

From source

go install github.com/pengelbrecht/ticks/cmd/tk@latest

Skill (Claude Code / Codex)

The tk binary tracks issues; the ticks skill is what lets your agent plan and orchestrate epics. Install it once:

npx skills add pengelbrecht/ticks

Quick Start

tk init                                    # Initialize in a git repo
tk create "Fix auth timeout" -t bug -p 1   # Create an issue
tk ready                                   # See what's ready to work on
tk next                                    # Get the single next task

tk update <id> --status in_progress        # Claim work
tk note <id> "Investigating token expiry"  # Log progress
tk close <id> --reason "Fixed"             # Complete

Upgrading

tk upgrade

Agent Integration

Run tk snippet to get runner-neutral content for AI agent integration:

tk snippet >> AGENTS.md   # Codex and other AGENTS.md-aware tools
tk snippet >> CLAUDE.md   # Claude Code

For epic execution, the distributable skill includes a shared orchestration protocol plus Claude Code and Codex adapters. Tick files, notes, branches, and worktrees are the handoff format, so one runner can plan an epic and the other can execute or resume it.

This tells agents to use ticks for persistent tracking instead of TodoWrite.

The tk next command is particularly useful for agents:

tk next              # Next ready task
tk next --epic       # Next ready epic
tk next EPIC_ID      # Next ready task in a specific epic

Agent-Human Workflow

Ticks supports structured handoff between agents and humans. Tasks can be routed to humans for approval, input, review, or manual work—and returned to agents with feedback.

Awaiting States

Creating Tasks for Humans

# Task requiring approval before closing
tk create "Update auth flow" --requires approval

# Task assigned directly to human
tk create "Configure AWS credentials" --awaiting work

Human Workflow

# See what needs attention
tk list --awaiting
tk next --awaiting

# Review and respond
tk show <id>
tk approve <id>
tk reject <id> "Soften the error messages"

Notes for Feedback

tk note <id> "Use Stripe for payments" --from human

Commands

All commands support --help for options and --json for machine-readable output.

TUI

tk view

• j/k or arrows: navigate
• space/enter: fold/unfold epics
• /: search
• z: focus on epic
• a: approve awaiting tick
• x: reject awaiting tick
• q: quit

Web Board

# Serve the current repo
tk board

# Board on a specific port (fails if the port is busy)
tk board -p 8080

# Serve a different repo
tk board /path/to/repo

# Expose on all interfaces (LAN / Docker)
tk board --host 0.0.0.0

# Serve the UI from disk for hot reload (development)
tk board --dev

Opens a web kanban board at http://localhost:3000 with real-time updates. Built with Lit web components and Shoelace UI.

• Drag-free kanban columns: Blocked, Agent Queue, In Progress, Needs Human, Done
• Real-time SSE updates when ticks change
• Mobile-responsive with tab navigation
• Keyboard navigation (hjkl, ? for help)
• PWA support for offline use

The board binds 127.0.0.1 (loopback) by default so it is only accessible from the local machine. Use --host 0.0.0.0 to expose it on all network interfaces. Without -p/--port, the board starts at port 3000 and takes the first free port. See internal/tickboard/ui/README.md for development docs.

Cloud Sync

Access your ticks from anywhere at ticks.sh.

Setup

1. Get a token from https://ticks.sh/settings
2. Add to ~/.ticksrc:

   token=your-token-here
   

3. Start the board with the --cloud flag:

   tk board --cloud
   

How It Works

• tk board --cloud connects to a Cloudflare Durable Object
• File changes sync to cloud in real-time (~50ms)
• Cloud UI edits sync back to local
• Works offline—changes queue and sync on reconnect

Privacy

• Ticks stored in Cloudflare Durable Objects
• Only accessible with your token
• Project isolation enforced
• No telemetry or analytics

Dependency Graph

See parallelization opportunities for an epic:

tk graph <epic-id>

Output shows tasks organized into "waves"—groups that can be executed in parallel:

Epic: Implement auth
Stats: 5 tasks, 3 waves, max 2 parallel

Wave 1 (ready now) (2 parallel)
  ○ abc P1 Design database schema
  ○ def P2 Set up OAuth provider

Wave 2
  ⊘ ghi P1 Implement user model ← abc

Wave 3
  ⊘ jkl P2 Integration tests ← ghi

Critical path: 3 waves (minimum sequential steps)

Use --json for machine-readable output (useful for agents planning parallel work).

Search and Filtering

tk list --label-any backend,auth --all
tk list --title-contains "auth" --all
tk list --status in_progress
tk ready --owner alice

Multiplayer

Commands show your issues by default. Use --all to see everyone's:

tk ready --all       # All ready tasks
tk next --all        # Next task from anyone
tk list --all        # All issues

Assign work with --owner:

tk create "Review API" --owner alice
tk list --owner bob

Environment Variables

How It Works

Each issue is a JSON file in .tick/issues/<id>.json. Git handles merges naturally since different issues are different files. For the rare case of conflicting edits to the same issue, ticks provides a custom merge driver that intelligently combines changes.

Acknowledgements

Ticks is inspired by beads by Steve Yegge, which pioneered the idea of giving AI coding agents persistent memory through git-tracked issue management. Ticks takes a simpler approach to the same problem.

License

MIT