01 Storage
Events live in git refs, not your working tree
Issues are an append-only event log under refs/grite/wal, CBOR-encoded, optionally Ed25519-signed. Your working tree stays clean. Code review never has to scroll past tracker noise.
v1 · MIT Filed under: developer tools / issue tracking
The issue tracker that lives in your repo.
Built for AI agents. Works for humans.
Grite stores issues as an append-only event log inside git refs (refs/grite/wal), keeping your working tree pristine while enabling seamless multi-agent collaboration through deterministic CRDT-based conflict resolution. No servers. No databases. No merge conflicts. Just git.
$ curl -fsSL https://raw.githubusercontent.com/neul-labs/grite/main/install.sh | bash
~5ms
append an issue to the WAL
~10ms
list 1,000 issues from sled
~50ms
rebuild state from latest snapshot
10
languages with symbol extraction
§ 0
What is grite?
grite is a repo-local, git-backed issue and task tracker built for AI coding agents and humans. Issues are stored as an append-only event log inside git refs (refs/grite/wal), CBOR-encoded, optionally Ed25519-signed, and merged deterministically via CRDTs. No server, no database, no merge conflicts — just git.
It ships as a single CLI (grite) plus an optional daemon, installs from six package managers, and needs nothing but git 2.38 or later. Read how it works, browse the features, or jump to the quickstart.
At a glance
- ▸No server, no database. Issues live in a git ref.
- ▸No merge conflicts. Deterministic CRDT merge.
- ▸Six install channels. Cargo, npm, pip, gem, Homebrew, Chocolatey.
- ▸One dependency. git 2.38+. MIT licensed.
An issue is a git event
The same grite command that creates an issue appends a CBOR event to the WAL. Nothing else in your repo moves.
You run
$ grite issue create \ --title "Race in WAL append" \ --label bug --label concurrency issue 0c3a · created
What lands in git
$ git for-each-ref refs/grite/wal a1c9… commit refs/grite/wal # one CBOR event appended, # content-addressed, syncs on git push, # working tree untouched
§ A
The grite difference
Not an opinion — a different storage model. Everything below falls out of one decision: put the issues in git refs.
| Traditional trackers | grite | |
|---|---|---|
| Storage | External database | Git refs in your repo |
| Sync | API calls | git fetch / git push |
| Offline | Requires connectivity | Works entirely offline |
| Multi-agent | Rate limits, auth tokens | CRDT merge, no conflicts |
| Working tree | N/A | Completely clean |
| History | Audit logs (optional) | Immutable event log (built-in) |
| Agent-native | Bolted-on integrations | Designed for agents from day one |
What the architecture buys you
A handful of well-understood primitives — git refs, sled, CRDTs, Ed25519 — composed in a way that makes issue tracking native to development instead of an external concern.
02 Sync
If you can git push, you can sync
No API keys, no service accounts, no third-party uptime. Pull the WAL when you fetch, push it when you push. The CRDT merge is deterministic, so concurrent edits never produce conflicts.
03 Agents
AGENTS.md is generated on init
grite init writes the standard discoverability file. Any AI agent that follows the convention finds grite immediately, with no configuration, and treats it as persistent memory across sessions.
04 Coordination
Distributed locks across agents
Claim src/parser.rs for thirty minutes; any other agent that asks for the same lock sees it is taken and picks a different task. TTL leases mean a crashed agent never deadlocks the queue.
05 Context
Tree-sitter symbol extraction in 10 languages
Rust, Python, TypeScript, JavaScript, Go, Java, C, C++, Ruby, Elixir. Agents can ask "what calls this function?" and create issues that quote the relevant code, not vague prose.
06 Performance
Materialised view via embedded sled
List 1,000 issues in ~10ms. Create one in ~5ms. The git WAL is truth; sled is the fast cache. Periodic snapshots rebuild state in ~50ms instead of replaying the entire log.
§ C
Who it is for
See the deeper use cases — AI coding agents, offline tracking, and monorepo coordination.
AI coding agents
Task decomposition, multi-agent coordination, persistent memory. Agent A claims a refactor; Agent B sees the lock and picks something else. Memory issues survive across sessions and are visible to every future agent.
Solo developers
Offline issue tracking from inside the terminal. Open issues on a plane, sync when you land. Personal knowledge base of architectural decisions that travels with the repo.
Small teams
Distributed coordination through the git remote you already use. No new infrastructure, no accounts to provision. Issues branch and merge alongside the code they describe.
Security & compliance
Sensitive issues never leave your infrastructure. Ed25519 signatures provide cryptographic proof. The append-only WAL is tamper-evident — any modification breaks the hash chain.
DevOps & release
Track deployment steps as a typed dependency DAG. Coordinate rollbacks with distributed locks. Store post-mortems with full context. Generate changelogs from closed issues between releases.
Teams who hate Jira
No project picker. No workflows to configure. No state that lives in a third party. One CLI, one log, one merge rule.
Architecture, in one screen
Three layers that separate storage, query, and interface. The WAL is truth; sled is the fast cache; the daemon is a performance optimisation, not a requirement.
+---------------------+ +----------------------+ +---------------------+
| Git WAL | --> | Materialized view | <-- | CLI / Daemon |
| refs/grite/wal | | sled database | | grite / grite-daemon|
| (source of truth) | | (fast queries) | | (user interface) |
+---------------------+ +----------------------+ +---------------------+
| | |
v v v
Append-only CRDT projection IPC via Unix
event log with LWW + set domain sockets
CBOR-encoded semantics (rkyv zero-copy) 01 · WAL
Every issue mutation is appended as a CBOR-encoded event, content-addressed by a 256-bit BLAKE2b hash. Optional Ed25519 signatures bind events to per-actor keys.
02 · Sled view
Embedded key-value store materialises current issue state from the WAL. CRDT projection with last-write-wins on scalars and commutative-set semantics on labels and links.
03 · CLI / daemon
CLI works standalone. The daemon auto-spawns to keep the cache warm and serialise concurrent calls, and idle-shuts down after five minutes. flock prevents cross-process corruption.
§ E
Honest comparisons
Two real alternatives, picked because public facts let us draw fair rows. No straw men.
grite vs GitHub Issues
→GitHub Issues is the default for public projects and the inbound surface most teams cannot replace. Grite is the internal task graph you reach for when you want offline-first, repo-local state and CRDT merge for parallel agents.
grite vs Linear
→Linear is a polished hosted tracker with strong product workflow. Grite is a different architecture entirely — your issues live in the repo, sync with git, and require zero accounts. Pick on storage model, not on UI taste.
grite vs Beads
→Beads is the most-cited git-native tracker for AI agents, backed by an embedded Dolt database. Grite stores the same kind of issues as pure git refs with a CRDT log — no database, git as the only dependency. Pick on substrate.
Questions, answered straight
More on the full FAQ.
+ Where does grite actually store issues?
Inside your git repository, in refs under refs/grite/wal. The WAL is an append-only, CBOR-encoded event log. A local sled database holds a materialised view of issue state for fast queries. The sled cache can be deleted at any time and rebuilt from the WAL — git refs are the only source of truth.
+ Do I need to run a server or daemon?
No server. The daemon (grite-daemon) is optional and only exists to keep the materialised view warm and serialise concurrent CLI calls. The CLI works standalone and auto-spawns the daemon when it would help. The daemon idle-shuts down after five minutes by default.
+ How are conflicts handled when two agents edit the same issue?
Grite uses CRDT semantics — last-write-wins on scalar fields, commutative-set semantics on labels and dependencies. Any two valid WALs can merge, the result is the same regardless of merge order, and no edit is silently dropped.
+ What stops a malicious agent from rewriting history?
The WAL is content-addressed: every EventId is a BLAKE2b hash of the event payload. Modifying any byte invalidates the chain. Optional Ed25519 signatures bind each event to a per-actor key, giving non-repudiable provenance for compliance and audit.
+ Does grite replace GitHub Issues?
It can. For repo-local work it is faster, offline-first, and agent-native. Teams that need a public bug reporting surface often keep GitHub Issues for inbound reports and use grite for the internal task graph. Grite can export to JSON, Markdown, or CSV to feed downstream systems.
+ How does it perform at scale?
Tested with 100,000+ events and 10,000+ issues. Sled gives O(1) lookups by issue ID. Materialised-view rebuild is O(delta) past the most recent snapshot. The WAL appends at 1,000+ events per second locally.
+ Which install path is canonical?
curl -fsSL ... | bash is the one-line installer. Homebrew, cargo, npm (grite-cli), pip (grite-cli), gem (grite-cli), and chocolatey are all supported. Pre-built binaries for Linux, macOS (Intel/ARM/Universal), and Windows are on the releases page. The only runtime dependency is git 2.38 or later.
+ Is it production-ready?
Grite is MIT licensed, has stable APIs across six Rust crates, and is shipped via crates.io, npm, PyPI, RubyGems, Homebrew, and Chocolatey. The architecture has been engineered around well-understood primitives — git refs, sled, CRDTs, Ed25519 — rather than novel ones.
Explore the docs
Every section of the site, one click away. Start anywhere.
Reference
Features
→Every capability by category — git-native storage, event log + CBOR, CRDT merge, Ed25519 signing, CLI + daemon, and agent-first design.
Architecture
How it works
→The whole architecture on one page: append a CBOR event to refs/grite/wal, sync via git, and project state with a deterministic CRDT merge.
Get started
Quickstart
→Install from any of six package managers, run grite init, create and close your first issues, sync via git push, and wire in an agent.
Use cases
Use cases
→AI coding agents, offline issue tracking, and monorepo task tracking — the concrete workflows grite was built to serve.
Compare
Comparisons
→Honest, fact-based comparisons against GitHub Issues, Linear, and Beads. Pick on storage model, not on UI taste.
Concepts
Glossary
→Plain-language definitions of the primitives grite is built on — CRDTs, event sourcing, git refs, CBOR, Ed25519, and deterministic merge.
Answers
FAQ
→Server-less operation, conflict-free merge, what is stored in git, signing, agents, install paths, and how grite compares.
Writing
Field notes
→Engineering writing from the grite team on git-native tracking, agent authorship, migrations, and staying inside the editor.
Project
About
→The thesis behind grite — why the issue tracker belongs inside the repository it describes, and who builds it.
Begin
Put the tracker back in the repo.
One install, one init, zero accounts. The next time you git push, your issues go too.
Three lines to first issue
$ brew install neul-labs/tap/grite $ grite init $ grite issue create --title "..."