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

# Design Philosophy

> The core principles that guide ticket-rs development

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

***

## Fast 🔥

<img src="https://img.shields.io/badge/Performance-Blazing-orange?style=for-the-badge" alt="Performance: Blazing" />

### Single Binary, Zero Dependencies

tk compiles to a **single \~10MB executable** with **zero runtime dependencies**. Drop the binary anywhere and it runs instantly.

```bash theme={null}
# 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

<Tip>
  tk can analyze thousands of issues and compute PageRank scores faster than you
  can blink.
</Tip>

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

<img src="https://img.shields.io/badge/Storage-Git--Backed-blue?style=for-the-badge" alt="Storage: Git-Backed" />

### Markdown + YAML

Issues are stored as **Markdown files** with **YAML frontmatter**:

```markdown theme={null}
---
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

<Check>
  When you `git clone`, you get the entire issue history. No API calls required.
</Check>

### Version Controlled

Issues version **alongside your code**:

```bash theme={null}
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:

```bash theme={null}
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

<img src="https://img.shields.io/badge/AI-Context--Optimized-green?style=for-the-badge" alt="AI: Context-Optimized" />

### Minimal CLI Output

tk is designed for **AI context windows**. Every command outputs the minimum needed:

**Bad (verbose):**

```json theme={null}
{
  "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`:

```bash theme={null}
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.

<Info>
  The entire output of `tk triage` fits in \~500 tokens, giving you actionable
  recommendations without burning your context budget.
</Info>

***

## Zero Daemons

<img src="https://img.shields.io/badge/Architecture-Stateless-red?style=for-the-badge" alt="Architecture: Stateless" />

### No Background Processes

tk has **no daemon**. No background processes. No long-running services.

**Why this matters:**

<CardGroup cols={2}>
  <Card title="No Zombie Processes" icon="skull">
    Daemons can leave orphaned processes that consume resources
  </Card>

  <Card title="No Port Conflicts" icon="network-wired">
    No listening on ports means no conflicts with other tools
  </Card>

  <Card title="No Startup/Shutdown" icon="power-off">
    Instant start, instant finish. No waiting.
  </Card>

  <Card title="No Resource Waste" icon="battery-full">
    Zero CPU/memory when not in use
  </Card>
</CardGroup>

### Stateless by Design

Every command is **stateless**:

```bash theme={null}
# 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.

<Check>You'll never have to hunt down and kill a zombie `tk` process.</Check>

***

## Practical Benefits

These principles translate to real-world advantages:

### For Developers

<Steps>
  <Step title="Clone and Go">
    `git clone` gets you code AND issues. Zero setup.
  </Step>

  <Step title="Work Offline">
    No network required. Full functionality locally.
  </Step>

  <Step title="Fast Workflows">Commands run in milliseconds. No waiting.</Step>

  <Step title="Terminal-Native">
    Stay in your IDE and terminal. No browser context switching.
  </Step>
</Steps>

### For AI Agents

<Steps>
  <Step title="Direct File Access">
    Agents can grep `.tickets/` directly without API calls
  </Step>

  <Step title="Token-Efficient">Minimal output preserves context window</Step>

  <Step title="Structured Commands">
    Predictable CLI interface for automation
  </Step>

  <Step title="No External Dependencies">
    Works in any environment where the binary runs
  </Step>
</Steps>

### For Teams

<Steps>
  <Step title="Git Workflow">
    Issues version with code. Standard git practices apply.
  </Step>

  <Step title="External Sync">
    Bidirectional sync with Linear, GitHub Issues, JIRA
  </Step>

  <Step title="No Infrastructure">
    No databases to manage, no servers to maintain
  </Step>

  <Step title="Easy Onboarding">
    New team members just `git clone` and they're ready
  </Step>
</Steps>

***

## Trade-offs

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

### What We Optimize For

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

### What We Sacrifice

<Warning>
  **Real-time collaboration** — No live updates across team members (use git
  sync instead)
</Warning>

<Warning>
  **Rich UI** — Terminal-first, not a web app (use external trackers if you need
  GUI)
</Warning>

<Warning>
  **Massive scale** — Optimized for \<10k issues per repo, not millions
</Warning>

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

***

## Future-Proof

These principles guide **future development**:

<AccordionGroup>
  <Accordion title="New features must be fast">
    We won't add features that slow down core commands. Millisecond performance is non-negotiable.
  </Accordion>

  <Accordion title="Git remains the source of truth">
    No external databases. Files in `.tickets/` are canonical.
  </Accordion>

  <Accordion title="Zero daemon guarantee">
    We will never add a background process. Stateless execution only.
  </Accordion>

  <Accordion title="Context efficiency first">
    New commands must output minimal, actionable information by default.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="The Journey" icon="book" href="/about/story">
    Read how we got here
  </Card>

  <Card title="Comparison" icon="scale-balanced" href="/about/comparison">
    See how tk compares to alternatives
  </Card>

  <Card title="Graph Analytics" icon="chart-network" href="/concepts/graph-analytics">
    Learn about tk's killer feature
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Install and start using tk
  </Card>
</CardGroup>