A multiplayer-first issue tracker for AI coding agents.

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

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.

• 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.

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.

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

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

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

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

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

The repository is also a Pi package containing the ticks skill and the executable Ticks runner extension. Install from git or a local checkout:

pi install git:github.com/pengelbrecht/ticks
pi install -l git:github.com/pengelbrecht/ticks   # project-local
pi install /absolute/path/to/ticks                # local development
pi -e /absolute/path/to/ticks                     # try without installing

Use /ticks-plan <childless-epic-id> or /ticks-plan --requirements "..." for automated model-running planning with zero tracker writes; add --apply only after reviewing the validated waves. Use /ticks-run <epic-id> for a no-model execution preview, /ticks-run <epic-id> --execute to opt in to child execution, /ticks-status [epic-id] for recovery, and /ticks-dashboard --demo or --dump for the control tower. Both apply and execution require a clean non-default branch. See extensions/ticks-runner/README.md for strict schemas, confirmation behavior, configuration, safety boundaries, artifacts, and recovery.

A generic skill install does not activate Pi extension code; use pi install (or pi -e) when the slash commands are needed.

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

tk upgrade

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

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.

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

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

# 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"

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

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

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

# 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.

Access your ticks from anywhere at ticks.sh.

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

• 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

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

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).

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

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

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.

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.

MIT