Skip to main content
ticket-rs is built on four core principles. Every feature and design decision is evaluated against these pillars.

​
Fast 🔥

Performance: Blazing

​
Single Binary, Zero Dependencies

tk compiles to a single ~9MB executable with zero runtime dependencies. Drop the binary anywhere and it runs instantly. 
# Download
curl -fsSL https://ticket-rs.io/install.sh | sh

# Use immediately
tk --version
No interpreter. No runtime. No package managers. Just native code.

​
Rust Performance

Written in Rust for maximum speed:
  • Graph algorithms run in milliseconds, not seconds
  • File I/O is optimized for SSD performance
  • Zero-cost abstractions mean no runtime overhead
  • Memory-safe without garbage collection pauses
tk can analyze thousands of issues and compute PageRank scores faster than you can blink.

​
Works Everywhere

Cross-platform native binaries for:
  • macOS (Apple Silicon + Intel)
  • Linux (x86_64 + ARM64)
  • Windows (x86_64)
And because there are no dependencies, tk works in:
  • Docker containers
  • CI/CD runners
  • Air-gapped systems
  • Sandboxed environments (Claude Code web)

​
Git-Native

Storage: Git-Backed

​
Markdown + YAML

Issues are stored as Markdown files with YAML frontmatter: 
---
status: open
type: feature
priority: 1
deps: [tk-abc123]
labels: [backend, auth]
---

# Add user authentication

Implement OAuth2 login flow.

## Acceptance Criteria

- [ ] Google OAuth
- [ ] GitHub OAuth
- [ ] Session persistence
This format is:
  • ✅ Human-readable — Open in any text editor
  • ✅ Machine-friendly — AI agents can grep and parse
  • ✅ Diff-friendly — See changes in git log
  • ✅ Merge-friendly — Git handles conflicts naturally

​
No Databases

No SQLite. No PostgreSQL. No MongoDB. Just files. This means:
  • ✅ No merge conflicts from binary database files
  • ✅ No schema migrations
  • ✅ No daemon processes
  • ✅ No database corruption
When you git clone, you get the entire issue history. No API calls required.

​
Version Controlled

Issues version alongside your code: 
git log -- .tickets/tk-abc123.md
See the full history:
  • When was the issue created?
  • Who changed the status?
  • What were the previous descriptions?
All the power of git applies to your issues.

​
Branch with Your Code

Create a feature branch, create related issues in .tickets/, work on both together: 
git checkout -b feature/auth
tk create "Add OAuth flow" -t feature
# ... make code changes ...
git add .
git commit -m "Add OAuth + create issue"
When the branch merges, the issues come along. Issues and code stay synchronized.

​
Token-Efficient

AI: Context-Optimized

​
Minimal CLI Output

tk is designed for AI context windows. Every command outputs the minimum needed: Bad (verbose): 
{
  "status": "success",
  "timestamp": "2026-01-18T12:34:56Z",
  "data": {
    "issues": [
      {
        "id": "tk-abc123",
        "title": "Add auth",
        "status": "open",
        "created_at": "2026-01-15T10:00:00Z",
        "updated_at": "2026-01-18T11:00:00Z",
        ...
      }
    ]
  }
}
Good (minimal): 
tk-abc123 [P1] Add auth
This saves hundreds of tokens per command.

​
Structured Format Options

When you need machine-readable output, use --format json: 
tk list --format json | jq '.[] | select(.priority == 0)'
But the default is human and AI friendly.

​
Context Engineering > Fine-Tuning

We think of AI models more like CPUs now. You don’t fine-tune your CPU for each task — you give it the right instructions. Same with AI:
  • Give it minimal, relevant context
  • Use structured output when needed
  • Avoid verbose, redundant information
tk’s output is optimized for this workflow.
The entire output of tk triage fits in ~500 tokens, giving you actionable recommendations without burning your context budget.

​
Zero Daemons

Architecture: Stateless

​
No Background Processes

tk has no daemon. No background processes. No long-running services. Why this matters:

No Zombie Processes

Daemons can leave orphaned processes that consume resources

No Port Conflicts

No listening on ports means no conflicts with other tools

No Startup/Shutdown

Instant start, instant finish. No waiting.

No Resource Waste

Zero CPU/memory when not in use

​
Stateless by Design

Every command is stateless: 
# Run command
tk list

# Get results immediately
# No lingering process
The command:
  1. Reads files from .tickets/
  2. Performs computation
  3. Outputs results
  4. Exits
That’s it. Clean, simple, predictable.

​
Works in Sandboxed Environments

Because there’s no daemon, tk works in restricted environments where background processes aren’t allowed:
  • Claude Code web
  • Serverless functions
  • CI/CD containers
  • Strict security policies
Just run the command and get results.
You’ll never have to hunt down and kill a zombie tk process.

​
Practical Benefits

These principles translate to real-world advantages:

​
For Developers

1

Clone and Go

git clone gets you code AND issues. Zero setup.
2

Work Offline

No network required. Full functionality locally.
3

Fast Workflows

Commands run in milliseconds. No waiting.
4

Terminal-Native

Stay in your IDE and terminal. No browser context switching.

​
For AI Agents

1

Direct File Access

Agents can grep .tickets/ directly without API calls
2

Token-Efficient

Minimal output preserves context window
3

Structured Commands

Predictable CLI interface for automation
4

No External Dependencies

Works in any environment where the binary runs

​
For Teams

1

Git Workflow

Issues version with code. Standard git practices apply.
2

External Sync

Bidirectional sync with Linear, GitHub Issues, JIRA
3

No Infrastructure

No databases to manage, no servers to maintain
4

Easy Onboarding

New team members just git clone and they’re ready

​
Trade-offs

Every design decision involves trade-offs. Here’s what we optimize for and what we sacrifice:

​
What We Optimize For

Speed — Millisecond response times
Simplicity — Single binary, no dependencies
Portability — Works everywhere Rust compiles
Offline — Zero network required for core features
Git integration — Issues version with code

​
What We Sacrifice

Real-time collaboration — No live updates across team members (use git sync instead)
Rich UI — Terminal-first, not a web app (use external trackers if you need GUI)
Massive scale — Optimized for <10k issues per repo, not millions
These trade-offs are intentional. We’re building for developers and AI agents who live in the terminal, not for project managers who need dashboards.

​
Future-Proof

These principles guide future development:
We won’t add features that slow down core commands. Millisecond performance is non-negotiable.
No external databases. Files in .tickets/ are canonical.
We will never add a background process. Stateless execution only.
New commands must output minimal, actionable information by default.

​
Next Steps

The Journey

Read how we got here

Comparison

See how tk compares to alternatives

Graph Analytics

Learn about tk’s killer feature

Quickstart

Install and start using tk