Grove AGENTS.md

AGENTS.md

Guidelines for coding agents working in the Grove codebase.

Project Overview

Grove is a terminal UI (TUI) for managing multiple Claude Code agents with git worktree isolation. Built with Rust using ratatui for the UI, tokio for async runtime, and git2 for git operations.

Build/Lint/Test Commands

cargo build                    # Development build
cargo build --release          # Production build
cargo test                     # Run all tests
cargo test test_name           # Run a single test by name
cargo test -- --nocapture      # Run tests with output visible
cargo clippy --all-targets --all-features -- -D warnings  # Lint
cargo fmt -- --check           # Format check
cargo fmt                      # Auto-format
cargo run -- /path/to/repo     # Run the application

Code Style Guidelines

Error Handling

Use anyhow for error handling:

use anyhow::{Context, Result, bail};

fn load_config() -> Result<Config> {
    let content = std::fs::read_to_string(&path)
        .context("Failed to read config file")?;
    Ok(toml::from_str(&content).context("Failed to parse config")?)
}

Async Patterns

#[tokio::main]
async fn main() -> Result<()> { /* ... */ }

let (action_tx, mut action_rx) = mpsc::unbounded_channel::<Action>();
tokio::spawn(async move { let _ = tx.send(Action::UpdateStatus { ... }); });

Module Organization

Each module has a mod.rs that re-exports public items:

// src/agent/mod.rs
pub mod detector;
pub mod manager;
pub mod model;
pub use detector::detect_status;
pub use manager::AgentManager;
pub use model::{Agent, AgentStatus};

Naming Conventions

• Functions/variables: snake_case (select_next, agent_list)
• Types/traits: PascalCase (AppState, AgentStatus)
• Constants: SCREAMING_SNAKE_CASE (MAX_BUFFER_SIZE)

Serde Patterns

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Config {
    #[serde(default)]
    pub gitlab: GitLabConfig,
    #[serde(skip)]
    pub git_status: Option<GitSyncStatus>,  // Runtime-only
}