grits-cli 0.1.4

Git-native, local-first issue tracker CLI and MCP server.
grits-cli-0.1.4 is not a library.

Grits

A Git-native, local-first issue tracker with a Twin Engine architecture:

  • 🤖 Agent Engine: MCP server for AI integration (Antigravity, Claude, etc.)
  • 👀 Visual Engine: VS Code extension with WASM-powered UI

Status: Production Ready (v0.1.2)

Quick Start

Prerequisites

  • Rust (latest stable)
  • Git
  • Node.js 18+ (for VS Code extension)

Option 1: Cargo (Recommended for Rust users)

If you have Rust installed, this is the easiest way. It automatically adds gr to your PATH:

cargo install grits-cli

Option 2: Download Binary

Windows (PowerShell One-Liner):

iwr https://github.com/babybirdprd/grits/releases/latest/download/gr-x86_64-pc-windows-msvc.exe -OutFile gr.exe; mv gr.exe $HOME/.cargo/bin/gr.exe

Manual Download:

  1. Download from GitHub Releases.
  2. Rename to gr (or gr.exe).
  3. Move to a folder in your PATH.

Option 3: Build from Source

If you want to contribute or use the latest main branch:

git clone https://github.com/babybirdprd/grits.git

cd grits

pnpm install

pnpm run build

cargo install --path grits-cli

Initialize a Project

cd your-project

gr onboard

CLI Usage

gr create "Fix login bug" -t bug -p 1         # Create issue

gr list --status open                          # List open issues

gr update abc123 --status in-progress          # Update status

gr close abc123                                # Close issue

gr sync                                        # Sync with Git

Twin Engine Architecture

Grits uses a "Unified State" approach where the Human UI and the AI Agent always stay in sync.

🔗 Tethered Sync

Whenever the AI Agent (via MCP) or the Human (via UI) modifies an issue, Grits automatically:

  1. Auto-Imports changes from the .grits/issues.jsonl file into the database.
  2. Auto-Exports database updates back to the file. This means you can move a card in the Kanban board and the Agent sees it immediately, and vice-versa.

🤖 Agent Engine (MCP Server)

Run the MCP server for AI agent integration:

gr serve-mcp

Available Tools:

Category Tools
CRUD list_issues, create_issue, update_issue, close_issue, get_issue
Contextual find_related_issues, suggest_issue_for_error, infer_issue_from_diff
Bulk bulk_triage, detect_duplicates, cleanup_stale
Workflow get_next_task, link_commit_to_issues, generate_issue_from_todo
Smart Queries search_issues, get_issue_graph, summarize_sprint

Antigravity Configuration (.vscode/mcp.json):

{
    "servers": {
        "grits": {
            "command": "gr",
            "args": ["serve-mcp"]
        }
    }
}

👀 Visual Engine (VS Code Extension)

The extension provides a rich UI for .jsonl issue files:

  • List View: Virtualized spreadsheet with inline editing
  • Kanban View: Drag-and-drop board by status
  • Graph View: Dependency visualization
  • Agenda View: Focus mode for high-priority items

Install Extension:

Download grits-kanban-*.vsix from Releases and:

code --install-extension grits-kanban-0.1.0.vsix

Or build from source:

# From the root directory

pnpm run build


# Then press F5 in VS Code in this workspace

Project Structure

grits/
├── grits-core/         # Core library (WASM-compatible)
│   └── src/wasm.rs     # WASM bridge for UI
├── grits-cli/          # CLI + MCP server
│   └── src/mcp.rs      # MCP tool implementations
├── extension/          # VS Code extension
│   ├── src/            # Extension host code
│   └── webview/        # React UI
├── .vscode/mcp.json    # MCP server config
└── .agent/workflows/   # Agent workflow rules

Documentation

License

MIT