Grit

Grit 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/grit

Features

• Git-native storage - Events stored in refs/grit/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

Grit 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/grit/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/grit

Cargo (Rust):

cargo install grit grit-daemon

npm:

npm install -g @neul-labs/grit

pip:

pip install grit-cli

gem:

gem install grit-cli

Chocolatey (Windows):

choco install grit

From Source

git clone https://github.com/neul-labs/grit.git
cd grit
./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 grit in a git repository
cd your-repo
grit init
# This also creates AGENTS.md with instructions for AI coding agents

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

# List issues
grit issue list

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

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

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

# Run health checks
grit doctor

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

Architecture

Grit uses a three-layer architecture:

+------------------+     +-------------------+     +------------------+
|   Git WAL        | --> | Materialized View | <-- | CLI / Daemon     |
| refs/grit/wal    |     | sled database     |     | grit / grit-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 (grit-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
grit daemon start --idle-timeout 300
grit daemon status
grit daemon stop

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

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

Storage Layout

.git/
  grit/
    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/grit/
  wal                              # Append-only event log
  snapshots/<ts>                   # Periodic snapshots
  locks/<resource_hash>            # Distributed lease locks

Documentation

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

Development

# Build
cargo build

# Run tests
cargo test

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

# Install locally
./install.sh

Design Principles

1. Git is the source of truth - All state derivable from refs/grit/*
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 - grit init creates AGENTS.md so AI coding agents automatically discover grit

License

MIT License - see LICENSE for details.