# grite

> The issue tracker that lives in your repo. Built for AI agents. Works for humans.

## What grite is

grite is a repo-local, git-backed issue and task tracking system. Events are appended to `refs/grite/wal` as CBOR-encoded chunks, optionally signed with Ed25519. A local embedded sled database materialises the current state of every issue from those events using deterministic CRDT semantics. The CLI works standalone; an optional daemon keeps the materialised view warm and serialises concurrent access through a Unix domain socket using rkyv zero-copy IPC.

There is no server. There is no hosted database. There are no merge conflicts. Sync is `git fetch` and `git push`. The repository is the source of truth.

## Architecture (verified from the README)

Three layers:

1. **Git WAL** — `refs/grite/wal` is the append-only event log. CBOR-encoded events, content-addressed by 256-bit BLAKE2b hashes, optionally signed by per-actor Ed25519 keys.
2. **Materialised view** — sled embedded key-value store rebuilds issue state from events using CRDT projection (last-write-wins on scalars, commutative-set semantics on labels and links). Periodic snapshots make rebuild O(delta).
3. **CLI / daemon** — `grite` is the user-facing CLI. `grite-daemon` is optional, auto-spawns when beneficial, idle-shuts down after five minutes. flock prevents cross-process database corruption.

The workspace ships six Rust crates:

- `libgrite-core` — events, CRDT projection, hashing, sled storage, Ed25519 signing
- `libgrite-git` — WAL commits, ref sync, snapshots, distributed locks
- `libgrite-ipc` — IPC schemas (rkyv), daemon lock, client/server
- `libgrite-cli` — programmatic API for all CLI operations
- `grite` — CLI binary
- `grite-daemon` — daemon binary

ID types:

- `ActorId` — 128-bit CSPRNG-random, identifies a device or agent
- `IssueId` — 128-bit CSPRNG-random, identifies an issue
- `EventId` — 256-bit BLAKE2b hash, content-addressed and tamper-evident

## Performance (verified)

- Issue create: ~5ms (single event append)
- Issue list with 1,000 issues: ~10ms (sled materialised view query)
- Full rebuild of 10,000 events: ~500ms (WAL replay)
- Snapshot rebuild: ~50ms (snapshot + delta replay)
- Sync of 1,000 new events: ~200ms (git fetch + CRDT merge)
- Context extraction: ~20ms (tree-sitter parse + symbol index)

Memory: CLI ~15MB RSS, daemon ~30MB RSS, ~1KB per issue in sled, ~50KB git overhead per 100 issues.

Concurrency: 50+ concurrent CLI calls via daemon, 100+ agents across machines via per-actor isolation, 1,000+ events per second WAL throughput. Tested with 100,000+ events and 10,000+ issues.

## Features

- Git-native storage in refs/grite/wal
- CRDT-based deterministic merging (LWW + commutative sets)
- Typed dependency DAG with cycle detection (`blocks`, `depends_on`, `related_to`)
- Tree-sitter symbol extraction across 10 languages (Rust, Python, TypeScript, JavaScript, Go, Java, C, C++, Ruby, Elixir)
- Per-actor isolation: each agent or device gets its own ActorId, local database, and signing key
- Optional background daemon, auto-spawn, idle shutdown
- Optional Ed25519 event signing for non-repudiable provenance
- Distributed locking with TTL leases for resource coordination
- Snapshot optimisation for fast rebuild
- Export to JSON, Markdown, or CSV
- `grite doctor` health checks with `--fix` auto-repair
- `--json` output on every CLI command

## For AI coding agents

- `grite init` auto-generates `AGENTS.md` for discoverability
- Persistent task memory across sessions
- Multi-agent coordination via CRDT and distributed locks
- Memory accumulation via `--label memory` issues
- Agent identity via ActorId, optionally signed
- Checkpoint comments for progress audit

## For developers and teams

- Offline-first: every operation works without network
- Branch-aware: issues created on a feature branch stay on that branch
- Worktree support
- Fast queries via sled materialised view
- Health monitoring via `grite doctor`

## Installation

```
curl -fsSL https://raw.githubusercontent.com/neul-labs/grite/main/install.sh | bash
brew install neul-labs/tap/grite
cargo install grite grite-daemon
npm install -g grite-cli
pip install grite-cli
gem install grite-cli
choco install grite
```

Prerequisites: git 2.38 or later.

## Quick start

```
grite init
grite issue create --title "Fix race in WAL append" --body "..."
grite issue list
grite issue comment <id> --body "..."
grite issue update <id> --label bug --label concurrency
grite issue link <a> blocks <b>
grite lock acquire src/wal.rs --ttl 3600
grite issue close <id>
grite sync
grite doctor
grite export --format markdown --since 7d
```

## Design principles

1. Git is the source of truth — all state derivable from refs/grite/*
2. No working tree pollution (except AGENTS.md, by design)
3. Daemon optional — CLI works standalone
4. Deterministic merges — any two valid WALs merge identically
5. Per-actor isolation
6. Agent discoverability via AGENTS.md
7. Offline-first
8. Cryptographic provenance via optional Ed25519

## Honest comparisons

- **vs GitHub Issues**: GitHub Issues is excellent at public inbound surfaces. grite is excellent at the internal task graph and offline-first work. Many teams use both.
- **vs Linear**: Linear is a polished hosted tracker. grite picks a different architecture — your issues live in the repo, sync with git, require zero accounts. Pick on storage model, not on UI taste.

Other adjacent tools mentioned in grite's own docs include Beads and git-bug; grite distinguishes itself with deterministic CRDT merge, agent-first discoverability, embedded sled materialised views, and a multi-language tree-sitter context store.

## Pages

- / — Overview, what grite is, the grite difference, features, architecture, comparisons, FAQ
- /features/ — Every feature by category: git-native storage, event log + CBOR, CRDT merge, Ed25519 signing, CLI + daemon, agent-first design, distribution
- /how-it-works/ — Architecture in one page: append CBOR event to refs/grite/wal, optional Ed25519 signing, sync via git, deterministic CRDT merge, project to state
- /quickstart/ — Install (Cargo, npm, pip, gem, Homebrew, Chocolatey), grite init, create/list/close, sync via git push, optional daemon, wire in an agent
- /use-cases/ — Index of use cases
- /use-cases/ai-coding-agents/ — A durable, shared task graph for agents with conflict-free parallel edits
- /use-cases/offline-issue-tracking/ — Fully offline tracking from the terminal, sync on next push
- /use-cases/monorepo-task-tracking/ — Issues that branch and merge with the code across a monorepo
- /compare/ — Comparisons index
- /compare/github-issues/ — grite vs GitHub Issues
- /compare/linear/ — grite vs Linear
- /compare/beads/ — grite vs Beads
- /faq/ — Server-less operation, conflict-free merge, what's stored in git, signing, agents, install, comparisons
- /glossary/ — CRDTs, event sourcing, git refs, refs/grite/wal, CBOR, Ed25519, deterministic merge, daemon, repo-local
- /about/ — Thesis: the tracker belongs in the repo
- /blog/ — Field notes index
- /blog/issue-tracking-without-leaving-the-editor/
- /blog/agents-as-first-class-issue-authors/
- /blog/your-repo-is-a-better-issue-store/
- /blog/migration-3000-github-issues-in-one-afternoon/
- /contact/ — Contact the grite team

## Identity

grite is a project of Neul Labs (https://neullabs.com). MIT licensed. Source at https://github.com/neul-labs/grite. Documentation at https://docs.neullabs.com/grite/.