gru: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Gru is a local-first LLM agent orchestrator that autonomously works on GitHub issues using Claude Code. It manages "Minions" (agent sessions) that claim issues, implement fixes, create PRs, and respond to reviews.

Current Phase: V1 - Basic delegation to Claude Code CLI Language: Rust Architecture: Single binary, GitHub as state store, git worktrees for isolation

Build & Development Commands

# Build
just build

# Build with release optimizations
just build-release

# Run tests
just test

# Run tests with output
just test-verbose

# Run linter (with warnings as errors)
just lint

# Automatically fix clippy lints where possible
just fix-clippy

# Format code
just fmt

# Check formatting without modifying
just fmt-check

# Run all checks (format + lint + test + build)
just check

# Install locally
just install

# Clean build artifacts
just clean

# Show project information
just info

Pre-commit Hooks

The project uses git hooks from .githooks/ that automatically run:

• Code formatting check (just fmt-check)
• Linting (just lint)
• Tests (just test)
• Branch protection (blocks commits to main)
• TODO/FIXME warnings (non-blocking)

To enable hooks:

git config core.hooksPath .githooks

When pre-commit hooks fail:

1. Fix the issues using the suggested commands (e.g., just fmt or just fix-clippy)
2. Review the diff with git diff to see what changed
3. Stage the fixed files selectively with git add <files>
4. Never use git add . or git add -A - always stage files explicitly
5. Example workflow:

   git commit -m "Fix bug"
   # Pre-commit hook fails with formatting errors
   just fmt
   git diff              # Review what changed
   git add src/main.rs   # Stage only the files you want to commit
   git commit -m "Fix bug"
   

To bypass in emergencies:

git commit --no-verify