What is Ticket?
A license to speed for AI agents.
Git-backed issue tracking that puts developers in the driver's seat.
The Problem
AI agents need long-term memory and a way to coordinate work. But existing solutions put up roadblocks: JIRA and Linear require API tokens, rate limits, and external dependencies. SQLite and JSONL solutions lead to sync conflicts and daemon processes. Complex CLIs burn through context windows with verbose output.
We wanted something that lives in git with no external dependencies. Something that uses human-readable files — Markdown and YAML — that agents can grep and edit directly. A minimal, token-efficient CLI that doesn't burn context on verbose output. Graph analytics for smart prioritization. And it had to work in sandboxed environments like Claude Code web where you can't always fetch binaries.
The Journey
Learning from Beads
Steve Yegge's Beads pioneered AI-native issue tracking. It got a lot right: git-backed storage, a tight CLI, and the core insight that AI agents need structured memory to coordinate work effectively. We used it heavily and learned a ton.
After months of daily use, we ran into friction points. The daemon that keeps SQLite in sync is clever, but we found ourselves fighting zombie processes and merge conflicts. Working with multiple .beads/ directories in monorepos required workarounds. And sandboxed environments couldn't always fetch GitHub releases.
Discovering Ticket
Then we found wedow/ticket — a single bash script that got everything right:
"Tickets are markdown files with YAML frontmatter in .tickets/. This allows AI agents to easily search them for relevant content without dumping ten thousand character JSONL lines into their context window."
No daemons. No databases. Just files.
Why Rust?
Bash works, but we wanted to floor it. Graph analytics like PageRank, betweenness centrality, and critical path analysis — inspired by beads_viewer. Direct Python bindings via Maturin instead of subprocess overhead. Cross-platform binaries that ship as a single executable with no runtime dependencies. And type safety to catch bugs at compile time, not in production.
Architecture
How It Works
1 Clone and Go
git clone gives you everything — code AND tickets. No API keys, no external queries, no setup. The complete project state is in the repo. Every developer and AI agent gets the full context instantly.
2 Local Agents
Each developer has their own local AI agent (Claude Code, Cursor) working directly with their cloned repo. Run tk triage to identify blockers, tk ready to see what's unblocked, tk priority for PageRank recommendations — all locally, all offline-capable.
3 External Sync
PMs and designers create issues in Linear, GitHub Issues, or JIRA. tk sync keeps external trackers and local .tickets/*.md files in sync bidirectionally. Non-technical team members use the tools they know, developers and AI agents work in git.
4 Git Workflow
Push commits (code + ticket updates) to GitHub. Other team members pull and get the latest state automatically. Tickets are versioned, diffable, and mergeable just like code. No special tooling needed — it's just git.
5 AI-Powered Triage
AI agents run graph algorithms to understand project health. PageRank surfaces issues that unblock the most work. Critical path analysis identifies timeline bottlenecks. Betweenness centrality finds key issues that many paths flow through. The tk triage command combines all analytics into actionable recommendations.
Issue File Format
Issues are markdown files in .tickets/ with YAML frontmatter. The filename is the issue ID (e.g., tk-abc123.md), and timestamps are derived from git metadata.
---
status: open
type: feature
priority: 1
deps: [tk-def456]
labels: [backend, auth]
---
# Add user authentication
Implement OAuth2 login flow with Google and GitHub providers.
## Acceptance Criteria
- [ ] Google OAuth working
- [ ] GitHub OAuth working
- [ ] Session persistenceThis format is greppable, diffable, and AI-friendly. No verbose JSON, no binary formats. Just markdown that humans and machines can read and edit directly.
Graph Analytics
PageRank Priority
Issues that unblock the most work bubble to the top. Based on the same algorithm Google uses to rank web pages, but for your dependency graph.
Critical Path
Find the longest chain of dependencies to understand timeline constraints. Know which sequence of tasks determines your project's minimum duration.
Betweenness Centrality
Identify bottleneck issues that many dependency paths flow through. These are your project's choke points — clear them first.
Ready Work
Find issues with no open blockers. These are your green lights — work that can start immediately without waiting on anything else.
Design Philosophy
Fast
Single executable, no runtime dependencies. Compiles to native code and runs anywhere. No speed limits.
Git-Native
Tickets are markdown files with YAML frontmatter. No databases, no sync daemons, no merge conflicts. Just files you can grep, edit, and version control.
Token-Efficient
Minimal, structured output designed for AI context windows. No verbose help text, no unnecessary formatting. Every token counts.
Zero Daemons
No background processes. No zombie daemons to hunt down. Just run the command and get results instantly.