Architecture Overview

Git-Iris is built on an agent-first architecture where intelligent decisions are made by Iris, an LLM-driven agent powered by the Rig framework. Rather than dumping context upfront, Iris dynamically explores codebases using tool calls, gathering precisely what she needs.

Core Philosophy

LLM-First Decision Making

Git-Iris rejects traditional heuristic-based approaches. Instead:

• The LLM makes all intelligent decisions — No hardcoded rules for commit message formatting, code review priorities, or changeset analysis
• Tools provide data, not decisions — Tools like git_diff return structured information; Iris interprets meaning and significance
• Context is dynamic — Iris gathers context through tool calls rather than receiving a massive upfront dump

This design enables Git-Iris to:

• Adapt to any project style without configuration
• Understand semantic changes beyond surface-level diffs
• Scale from tiny commits to massive refactors through intelligent context management

Agent-Tool-Capability Pattern

flowchart LR
    subgraph Agent["IrisAgent"]
        direction TB
        cap[Capabilities]
        tools[Tools]
        cap <--> tools
    end

    cap --> |selects| exec[Multi-turn Execution]
    exec --> output[Structured Output]

The unified agent combines capabilities (task definitions) with tools (context gathering):

Capabilities	Tools	Output Types
commit.toml	git_diff	GeneratedMessage
review.toml	git_log	MarkdownReview
pr.toml	file_read	MarkdownPullRequest
changelog.toml	code_search	MarkdownChangelog
release_notes.toml	parallel_analyze	MarkdownReleaseNotes
chat.toml	workspace	PlainText
semantic_blame.toml	git_diff	String

Execution flow: Capability selects prompt → Iris calls tools (up to 50 turns) → Returns structured JSON

Architecture Components

1. IrisAgent — The Unified Agent

Location: src/agents/iris.rs

A single agent implementation that handles all Git-Iris tasks through capability switching:

pub struct IrisAgent {
    provider: String,
    model: String,
    fast_model: Option<String>,
    current_capability: Option<String>,
    // ...
}

Key responsibilities:

• Load capability TOML files to determine task prompt and output schema
• Attach tools via Rig's builder pattern
• Execute multi-turn agent loops (up to 50 tool calls)
• Parse and validate structured JSON responses
• Handle streaming responses for real-time TUI updates

Why one agent? Simplifies code, enables tool reuse, and provides consistent behavior across all capabilities.

2. Capabilities — Task Definitions

Location: src/agents/capabilities/*.toml

TOML files that define:

• task_prompt — Instructions for Iris on how to approach the task
• output_type — Expected JSON schema (maps to Rust types)

Example from commit.toml:

name = "commit"
description = "Generate commit messages from staged changes"
output_type = "GeneratedMessage"

task_prompt = """
Generate a commit message for the staged changes.

## MANDATORY FIRST STEP
**ALWAYS call `project_docs(doc_type="context")` FIRST**...

## Tools Available
- `git_diff()` - Get staged changes with relevance scores
- `git_log(count=5)` - Recent commits for style reference
...
"""

Capabilities are embedded at compile time using include_str!(), making Git-Iris fully portable.

See: Capabilities Documentation

3. Tools — Information Gathering

Location: src/agents/tools/

Tools are Rig-compatible functions that Iris calls to gather information:

Tool	Purpose
git_diff	Get staged changes with relevance scoring
git_log	Fetch recent commits for style reference
git_status	Repository status
git_changed_files	List of changed files
file_read	Read file contents directly
code_search	Search for patterns/symbols
project_docs	Read README, AGENTS.md, CLAUDE.md
workspace	Iris's persistent notes and task tracking
parallel_analyze	Spawn subagents for large changesets

Tool Registry: The attach_core_tools! macro ensures consistent tool sets across main agents and subagents, preventing drift.

See: Tools Documentation

4. Structured Output — Type-Safe Responses

Location: src/types/

All Iris responses are validated against JSON schemas:

pub enum StructuredResponse {
    CommitMessage(GeneratedMessage),       // { emoji, title, message }
    PullRequest(MarkdownPullRequest),      // { content: String }
    Changelog(MarkdownChangelog),          // { content: String }
    ReleaseNotes(MarkdownReleaseNotes),    // { content: String }
    MarkdownReview(MarkdownReview),        // { content: String }
    // ...
}

Validation and recovery handles malformed LLM output gracefully, attempting repairs before failing.

See: Output Validation Documentation

5. Context Strategy — Relevance Scoring

Location: src/agents/tools/git.rs

Iris adapts her approach based on changeset size:

Size	Criteria	Strategy
Small	≤3 files, <100 lines	Full context for all changes
Medium	≤10 files, <500 lines	Focus on files with >60% relevance
Large	>10 files, >500 lines	Top 5-7 highest-relevance files
Huge	>20 files, >1000 lines	Use parallel_analyze with subagents

Relevance scoring considers:

• Change type (added > modified > deleted)
• File type (source code > config > docs)
• Path patterns (src/ > test/)
• Diff size (substantive changes preferred)
• Semantic patterns (function additions, type definitions)

See: Context Strategy Documentation

Multi-Turn Execution

Iris executes in multi-turn mode, allowing up to 50 tool calls per task:

1. Planning — Iris reads the capability prompt and user request
2. Analysis — Calls tools (git_diff, project_docs, file_read, etc.)
3. Deep Dive — May call parallel_analyze or analyze_subagent for large tasks
4. Synthesis — Returns structured JSON matching the expected schema
5. Validation — Output validator ensures JSON is well-formed

Why 50 turns? Complex tasks like PRs and release notes may require analyzing many files and commits. Iris knows when to stop, so we give generous headroom.

Subagent Architecture

For large changesets, Iris spawns independent subagents via parallel_analyze:

flowchart LR
    main[Main Agent] --> parallel[parallel_analyze]
    parallel --> s1[Subagent 1]
    parallel --> s2[Subagent 2]
    parallel --> s3[Subagent 3]
    s1 --> agg[Aggregated Results]
    s2 --> agg
    s3 --> agg

Example task distribution:

Subagent	Task	Focus
1	Analyze auth/ changes	Authentication module
2	Review API endpoints	REST/GraphQL layer
3	Check database migrations	Schema changes

Each subagent:

• Runs concurrently with its own context window
• Has access to core tools (git_diff, file_read, etc.)
• Returns a focused analysis
• Uses the fast model for cost efficiency

Prevents: Context overflow, token limit errors, information loss

Provider Abstraction

Git-Iris supports multiple LLM providers through Rig's unified interface:

Provider	Default Model	Fast Model
OpenAI	gpt-5.1	gpt-5.1-mini
Anthropic	claude-sonnet-4-5-20250929	claude-haiku-4-5-20251001
Google	gemini-3-pro-preview	gemini-2.5-flash

Provider switching is transparent — the same capabilities and tools work across all backends.

Design Decisions

Why Rig?

• Agent-as-tool composition — Subagents are just tools from the main agent's perspective
• Provider abstraction — Swap between OpenAI/Anthropic/Google seamlessly
• Tool system — Clean trait-based tools with automatic schema generation
• Multi-turn support — Built-in agentic loops with tool calling

Why Capability Switching?

• Single agent codebase — No duplication between commit/review/PR agents
• Shared tool logic — One implementation of git_diff, used everywhere
• Easy testing — Test one agent with different prompts
• Maintainability — Update tool behavior in one place

Why Structured Output?

• Predictable parsing — JSON schemas guarantee parseable responses
• Type safety — Rust types enforce correctness
• Error recovery — Validator can repair common LLM mistakes
• Separation of concerns — LLM focuses on content, not format

Why Multi-Turn?

• Adaptive exploration — Iris decides what to read based on what she learns
• Large changeset support — Can analyze 20+ files through multiple tool calls
• Context efficiency — Only loads files/diffs that are relevant
• Natural workflow — Mimics how humans review code (breadth → depth)

Next Steps

• Agent System — Deep dive into IrisAgent implementation
• Capabilities — How to create custom capabilities
• Tools — Tool development and the tool registry
• Output Validation — JSON schema validation and recovery
• Context Strategy — Relevance scoring and adaptive context