krew-cli: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents (Codex, Copilot, etc.) when working with code in this repository.

Project Overview

krew-cli is a multi-AI-agent collaborative CLI tool written in Rust. Users chat with multiple LLMs (GPT, Claude, Gemini, etc.) simultaneously in one terminal using @ addressing and # whisper (private messages). See PDD for product design and TDD for technical design.

Build & Development Commands

# Build
cargo build                    # Debug build
cargo build --release          # Release build

# Run
cargo run                      # Run the CLI (krew-cli crate)

# Test
cargo test                     # Run all tests
cargo test -p krew-core        # Run tests for a specific crate
cargo test test_name           # Run a single test by name

# Lint & Format
cargo fmt --all                # Format all code
cargo fmt --all -- --check     # Check formatting (CI)
cargo clippy --all-targets --all-features -- -D warnings  # Lint with warnings as errors

# Check (fast compile check without codegen)
cargo check --all-targets

IMPORTANT: Always run cargo fmt --all and cargo clippy --all-targets --all-features -- -D warnings before committing.

Architecture

Cargo workspace with 6 crates under crates/:

krew-cli          CLI entry + TUI (clap, ratatui)
  └── krew-core   Session management, Agent Loop, routing, slash commands
        ├── krew-llm      LLM provider abstraction (OpenAI/Anthropic/Google/OpenAI-Compatible)
        ├── krew-tools    Tool system (8 built-in tools) + MCP client
        ├── krew-storage  TOML session persistence (.krew/sessions/)
        └── krew-config   TOML config loading (.krew/settings.toml)

Key Design Patterns

• Agent Loop: Serial execution per reply_order — each agent completes its full loop (including tool calls) before the next starts, so later agents see earlier agents' responses.
• Message routing: @name addressing + #name whisper (private messages). Whisper messages are only visible to target agents; others see placeholders.
• Built-in tools enforce path boundary — all file operations must be within session cwd.
• Error types: anyhow for application-level errors (krew-cli, krew-core), thiserror for library crate error definitions (krew-llm, krew-tools, krew-storage, krew-config).