> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ticket-rs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# The Journey

> How we got here: from Beads to a bash script to a Rust-powered issue tracker

ticket-rs didn't appear out of nowhere. It's the result of learning from other tools, identifying pain points, and building something better.

***

## The Problem

AI agents need **long-term memory** to coordinate work effectively. But existing solutions put up roadblocks:

<CardGroup cols={2}>
  <Card title="JIRA & Linear" icon="cloud">
    API tokens, rate limits, constant browser context switching.
  </Card>

  <Card title="SQLite Files" icon="database">
    Merge conflicts, zombie daemons, background processes to fight.
  </Card>

  <Card title="Complex CLIs" icon="terminal">
    Verbose output burning through AI context windows.
  </Card>

  <Card title="No Git Integration" icon="code-branch">
    Issues live separately from code, making versioning difficult.
  </Card>
</CardGroup>

We wanted something simpler. Something that **lives in git** with zero external dependencies. Human-readable files — Markdown and YAML — that agents can grep and edit directly.

For developers, this means **less context switching**. You live in the terminal and IDE, not bouncing between browser tabs.

***

## Learning from Beads

Steve Yegge's [Beads](https://github.com/steveyegge/beads) pioneered AI-native issue tracking. It got a lot right:

<Check>Git-backed storage — issues versioned with code</Check>
<Check>Tight CLI — fast, focused commands</Check>

<Check>
  Core insight — AI agents need structured memory to coordinate work
</Check>

I used Beads for months and it was fantastic. But then friction started showing up:

### The Friction Points

<Warning>
  **SQLite daemon** — Clever, but led to zombie processes and merge conflicts
</Warning>

<Warning>
  **Monorepo challenges** — Multiple `.beads/` directories required workarounds
</Warning>

<Warning>
  **Sandboxed environments** — Couldn't fetch GitHub releases in environments
  like Claude Code web
</Warning>

<Warning>
  **Feature creep** — As the project grew (sometimes changing 50k lines per day
  through "vibe coding"), it added features I didn't need while missing ones I
  did
</Warning>

Beads proved the concept. Now we needed something more focused and portable.

***

## Discovering ticket

That's when I stumbled on [wedow/ticket](https://github.com/wedow/ticket) — a **single bash script** that nailed it:

<Info>
  > "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."
</Info>

**Exactly.**

* ✅ No daemons
* ✅ No databases
* ✅ Just files
* ✅ Version controlled alongside your code

This was the right architecture. Simple, elegant, and it **just worked**.

***

## Why Rust?

Bash works great, but I wanted to **floor it**. Here's what I wanted to add:

### 1. Graph Analytics

Inspired by [beads\_viewer](https://github.com/Dicklesworthstone/beads_viewer), I wanted powerful graph algorithms:

* **PageRank** — Surface issues that unblock the most work
* **Betweenness centrality** — Identify bottleneck issues
* **Critical path analysis** — Understand project timelines

These algorithms are computationally intensive. Rust gives us the performance to run them instantly.

<Card title="Learn More" icon="chart-network" href="/concepts/graph-analytics">
  See how graph analytics help you prioritize work
</Card>

### 2. Native Python Bindings

Instead of subprocess overhead (running `tk` via shell from Python), we can use **Maturin** to create native Python bindings:

```python theme={null}
from ticket_py import Ticket

# Direct function calls, no subprocess
tk = Ticket()
issues = tk.list_issues()
tk.create_issue("Add auth", priority=1)
```

This makes tk a **library** as well as a CLI.

### 3. Cross-Platform, Single Binary

Rust compiles to:

* A single **\~10MB executable**
* **Zero runtime dependencies**
* Native performance on every platform

Compare that to:

* Node.js requires a runtime installation
* Python requires interpreter + dependencies
* Bash has inconsistent behavior across platforms

### 4. Type Safety

Rust's compiler catches bugs **before** they hit production:

```rust theme={null}
// This won't compile - caught at build time
let priority: Priority = "invalid"; // ❌ Type error

// This is safe - types enforced
let priority = Priority::High; // ✅
```

No more runtime errors from typos or invalid data.

### 5. Sandboxed Environment Support

Because tk is a single binary with no dependencies, it works in **restricted environments**:

* [Claude Cowork](https://claude.com/resources/tutorials/claude-cowork-a-research-preview)/[Claude Code web](https://claude.ai/code)
* Docker containers (minimal base images)
* CI/CD runners (no setup required)
* Air-gapped systems (no external downloads)

Just drop the binary and go.

***

## The Result

ticket-rs combines the best of all these approaches:

<Steps>
  <Step title="Beads' Vision">
    Git-backed, AI-native issue tracking with structured memory
  </Step>

  <Step title="ticket's Simplicity">
    Markdown + YAML files, no daemons, no databases
  </Step>

  <Step title="Rust's Performance">
    Blazing speed, type safety, cross-platform single binary
  </Step>

  <Step title="Graph Analytics">
    PageRank, critical path, betweenness centrality for smart prioritization
  </Step>
</Steps>

***

## Design Decisions

### Why Markdown + YAML?

**Human-readable and machine-friendly.** AI agents can grep, developers can diff, git can merge.

```markdown theme={null}
---
status: open
priority: 1
deps: [tk-abc123]
---

# Add authentication

Implement OAuth2 flow.
```

This is vastly better than:

* JSON blobs (verbose, not human-friendly)
* Binary databases (can't grep or diff)
* External APIs (requires network, credentials, rate limits)

### Why Local-First?

Your project's issues should **travel with your code**. When you `git clone`, you get:

* ✅ Source code
* ✅ Issue history
* ✅ Dependency graph
* ✅ Complete context

No API calls. No external services. **Full offline capability.**

### Why Zero Daemons?

Background processes create problems:

* Zombie processes that need manual cleanup
* Port conflicts
* Resource consumption when idle
* Startup/shutdown complexity

tk is **stateless**: run the command, get results, done. No lingering processes.

***

## Evolution Timeline

<Steps>
  <Step title="2025 Q4">
    Used Beads, hit friction points with SQLite daemon and monorepos
  </Step>

  <Step title="2025 Q4">
    Discovered wedow/ticket, validated the markdown + YAML approach
  </Step>

  <Step title="2025 Q4">
    Started ticket-rs prototype in Rust, added graph analytics
  </Step>

  <Step title="2025 Q4">
    Added GitHub/Linear sync, MCP server, Python bindings
  </Step>

  <Step title="2026 Q1">
    Production-ready release, Claude Code integration, comprehensive docs
  </Step>
</Steps>

***

## What's Next?

ticket-rs is **production-ready**, but the journey continues:

<CardGroup cols={2}>
  <Card title="More Integrations" icon="plug">
    GitLab, Azure DevOps, Jira, Asana
  </Card>

  <Card title="Advanced Analytics" icon="chart-line">
    Velocity tracking, burndown charts, time estimates
  </Card>

  <Card title="Team Features" icon="users">
    Assignees, mentions, notifications
  </Card>

  <Card title="AI Enhancements" icon="robot">
    Auto-triage, smart estimates, dependency suggestions
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Philosophy" icon="lightbulb" href="/about/philosophy">
    Understand the design principles behind tk
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Install tk and create your first issue
  </Card>

  <Card title="Graph Analytics" icon="chart-network" href="/concepts/graph-analytics">
    Learn how tk prioritizes work automatically
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/ticket-rs/ticket">
    Star the project and contribute
  </Card>
</CardGroup>