Extending Git-Iris

Git-Iris is built to be extensible. You can add new capabilities, tools, and Studio modes to enhance Iris's intelligence and expand what she can do.

Extension Points

Git-Iris offers three primary extension mechanisms:

1. Capabilities → What Iris Can Do

Add new tasks Iris can perform (like "generate commit message" or "review code"). Capabilities are defined in TOML files with prompts and output schemas.

→ Adding Capabilities

2. Tools → How Iris Gathers Context

Give Iris new ways to inspect your codebase and gather information. Tools are Rust implementations using the Rig framework's Tool trait.

→ Adding Tools

3. Studio Modes → How Users Interact

Create new interactive TUI modes in Iris Studio for specific workflows. Modes combine state management, event handling, and rendering.

→ Adding Studio Modes

Architecture Overview

flowchart TD
    cap["Capability TOML"]
    agent["Iris Agent"]
    tools["Tools (gather context)"]
    response["Structured Response"]
    studio["Studio Mode"]

    cap -->|"defines task"| agent
    agent -->|"uses"| tools
    tools -->|"produces"| response
    response -->|"displayed in"| studio

How Extensions Work Together

Example: Code Review Capability

1. Capability TOML (review.toml) defines the review task prompt and output format
2. Tools (git_diff, file_read, code_search) provide Iris with code context
3. Output Type (Review in crate::types::Review) structures the review content
4. Studio Mode (Review mode) displays the review with panels for file list, diff, and output

Quick Start

Adding a Simple Capability

1. Create src/agents/capabilities/my_capability.toml
2. Define the prompt and output type
3. Add output type to StructuredResponse enum
4. Register in capability loader

Time: ~30 minutes

Adding a Tool

1. Create src/agents/tools/my_tool.rs
2. Implement the Tool trait
3. Register in tool registry
4. Test with debug mode

Time: ~1 hour

Adding a Studio Mode

1. Add mode variant to Mode enum
2. Create state struct in src/studio/state/modes.rs
3. Implement handler in src/studio/handlers/
4. Implement renderer in src/studio/render/

Time: ~2-4 hours

Development Workflow

# Build with your changes
just build

# Test a capability
just gen-debug

# Test in Studio
just studio

# Run tests
just test

# Lint
just lint

Key Design Principles

1. LLM-First Architecture

The LLM makes intelligent decisions—avoid hardcoded heuristics. Let Iris explore and reason using tools rather than dumping all context upfront.

2. Tool-Based Context Gathering

Tools should be focused and composable. Each tool does one thing well. Iris orchestrates them.

3. Reducer-Centric Event Flow (Studio)

Studio still uses a central reducer for shared workflows and explicit side effects, but it is not a fully pure reducer architecture end-to-end. Handlers and StudioApp also perform some direct UI and coordination updates.

4. Structured Output

Use JSON schemas for parseable responses. Provide clear examples in prompts.

Code Organization

src/
├── agents/
│   ├── capabilities/      # Task definitions (TOML)
│   ├── tools/             # Context gathering (Rust)
│   └── iris.rs            # Main agent implementation
├── studio/
│   ├── state/            # Mode state definitions
│   ├── handlers/         # Input handling
│   ├── render/           # UI rendering
│   └── components/       # Reusable UI components
├── types/                # Output type definitions
└── services/             # Pure operations (no LLM)

Real-World Examples

Throughout the extension guides, we reference real implementations from the codebase:

• Commit Capability: src/agents/capabilities/commit.toml
• Git Tools: src/agents/tools/git.rs
• Commit Mode: src/studio/state/modes.rs → CommitState
• File Read: src/agents/tools/file_read.rs
• Review Mode: Complete mode with state (ReviewState), handler, and renderer

Contributing

Ready to contribute your extension back to Git-Iris? Check out the Contributing Guide for development setup, testing requirements, and PR guidelines.

Need Help?

• Read the Architecture Documentation for system design details
• Check existing capabilities and tools for patterns
• Open an issue on GitHub with questions
• Join the community discussions

Let's build something powerful. ⚡