Grite

Grite is a repo-local, git-backed issue/task system designed for coding agents and humans. It keeps an append-only event log in git refs, builds a fast local materialized view, and never writes tracked state into the working tree.

Documentation: docs.neullabs.com/grite

Features

• Git-native storage - Events stored in refs/grite/wal, synced with git fetch/push
• CRDT-based merging - Deterministic conflict resolution, no manual merge needed
• Dependency DAG - Typed issue relationships (blocks, depends_on, related_to) with cycle detection and topological ordering
• Context store - Tree-sitter-powered symbol extraction across 10 languages, with distributed sync between agents
• Per-actor isolation - Each agent/device gets its own actor ID and local database
• Optional daemon - Auto-spawns for performance, not required for correctness
• Ed25519 signing - Optional cryptographic signatures on events
• Team coordination - Distributed locks for coordinated workflows

Use Cases

Grite serves different audiences with distinct workflows:

See Use Cases for detailed workflows and examples.

Installation

Quick Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/neul-labs/grite/main/install.sh | bash

This downloads the pre-built binary for your platform and installs to ~/.local/bin/.

Package Managers

Homebrew (macOS/Linux):

brew install neul-labs/tap/grite

Cargo (Rust):

cargo install grite grite-daemon

npm:

npm install -g @neul-labs/grite

pip:

pip install grite-cli

gem:

gem install grite-cli

Chocolatey (Windows):

choco install grite

From Source

git clone https://github.com/neul-labs/grite.git
cd grite
./install.sh --source

Prerequisites

• Git 2.38+
• nng library (for IPC)

Ubuntu/Debian:

sudo apt install libnng-dev

macOS:

brew install nng

Windows: The nng library is bundled with the pre-built binaries.

Quick Start

# Initialize grite in a git repository
cd your-repo
grite init
# This also creates AGENTS.md with instructions for AI coding agents

# Create an issue
grite issue create --title "Fix login bug" --body "Users can't login"

# List issues
grite issue list

# Add a comment
grite issue comment <issue-id> --body "Working on this"

# Close an issue
grite issue close <issue-id>

# Sync with remote (auto-rebases on conflict)
grite sync

# Run health checks
grite doctor

# Rebuild database (fast mode with snapshots)
grite rebuild --from-snapshot

Architecture

Grite uses a three-layer architecture:

+------------------+     +-------------------+     +------------------+
|   Git WAL        | --> | Materialized View | <-- | CLI / Daemon     |
| refs/grite/wal    |     | sled database     |     | grite / grite-daemon     |
| (source of truth)|     | (fast queries)    |     | (user interface) |
+------------------+     +-------------------+     +------------------+

Crate Structure

ID Types

IDs are stored as byte arrays internally and displayed as lowercase hex strings.

Daemon

The daemon (grite-daemon) is optional and provides:

• Auto-spawn - Automatically starts on first CLI command
• Idle shutdown - Stops after 5 minutes of inactivity (configurable)
• Concurrent access - Multiple CLI calls handled efficiently
• Warm cache - Keeps materialized view ready for fast queries

# Manual daemon control
grite daemon start --idle-timeout 300
grite daemon status
grite daemon stop

# Force local execution (skip daemon)
grite --no-daemon issue list

The daemon uses filesystem-level locking (flock) to prevent database corruption from concurrent access.

Storage Layout

.git/
  grite/
    config.toml                    # Repo-level config (default actor, lock policy)
    actors/
      <actor_id>/
        config.toml                # Actor config (label, public key)
        sled/                      # Materialized view database
        sled.lock                  # flock for exclusive access
        daemon.lock                # Daemon ownership marker

refs/grite/
  wal                              # Append-only event log
  snapshots/<ts>                   # Periodic snapshots
  locks/<resource_hash>            # Distributed lease locks

Documentation

Full documentation is available at docs.neullabs.com/grite.

Development

# Build
cargo build

# Run tests
cargo test

# Run with debug logging
RUST_LOG=debug cargo run --bin grite -- issue list

# Install locally
./install.sh

Design Principles

1. Git is the source of truth - All state derivable from refs/grite/*
2. No working tree pollution - Never writes tracked files (except AGENTS.md for agent discoverability)
3. Daemon optional - CLI works standalone, daemon is performance optimization
4. Deterministic merges - CRDT semantics, no manual conflict resolution
5. Per-actor isolation - Multiple agents can work independently
6. Agent discoverability - grite init creates AGENTS.md so AI coding agents automatically discover grite

License

MIT License - see LICENSE for details.