Project Configuration

Share Git-Iris settings across your team using .irisconfig files.

Purpose

Project configs let you:

• Standardize commit style across the team
• Enforce consistent instruction presets
• Configure team-wide model preferences
• Share custom instructions for the project

Security: API Keys Never Stored

.irisconfig files never contain API keys. Each developer uses their own credentials from:

• Personal config (~/.config/git-iris/config.toml)
• Environment variables

This prevents credential leakage when committing .irisconfig to version control.

Creating a Project Config

Via CLI

# From repository root
git-iris project-config --provider anthropic
git-iris project-config --model claude-sonnet-4-5-20250929
git-iris project-config --preset conventional

This creates .irisconfig in your repo root.

Manual Creation

Create .irisconfig:

# Team-shared Git-Iris configuration

# Gitmoji enforcement
use_gitmoji = true

# Default provider (API keys come from personal config)
default_provider = "anthropic"

# Instruction preset
instruction_preset = "conventional"

# Custom instructions for this project
instructions = """
Always mention the ticket number in the format [PROJ-123].
Focus on business impact over implementation details.
"""

# Provider configurations (no API keys)
[providers.anthropic]
model = "claude-sonnet-4-5-20250929"
fast_model = "claude-haiku-4-5-20251001"
token_limit = 150000

Configuration Layering

Settings are merged in this order:

1. Personal config (~/.config/git-iris/config.toml)
2. Project config (.irisconfig)
3. CLI flags

Later settings override earlier ones, except API keys which only come from personal config or environment.

Example Layering

Personal config:

default_provider = "openai"
use_gitmoji = false

[providers.openai]
api_key = "sk-..."
model = "gpt-5.1"

Project config:

default_provider = "anthropic"
use_gitmoji = true
instruction_preset = "conventional"

[providers.anthropic]
model = "claude-sonnet-4-5-20250929"

Effective config:

# From project config
default_provider = "anthropic"
use_gitmoji = true
instruction_preset = "conventional"

# From personal config (API key never in project config)
[providers.openai]
api_key = "sk-..."

# From project config
[providers.anthropic]
model = "claude-sonnet-4-5-20250929"
# API key loaded from personal config or ANTHROPIC_API_KEY env var

Supported Project Settings

Setting	Type	Description
use_gitmoji	Boolean	Enable/disable gitmoji
default_provider	String	Team's preferred provider
instruction_preset	String	Shared instruction preset
instructions	String	Custom project instructions
theme	String	Team's preferred theme

Provider Settings (per provider)

Setting	Type	Description
model	String	Primary model name
fast_model	String	Fast model name
token_limit	Integer	Token limit override
additional_params	Table	Provider-specific params

API keys are excluded from project configs automatically.

Common Use Cases

Conventional Commits Enforcement

use_gitmoji = false
instruction_preset = "conventional"

instructions = """
Use Conventional Commits format strictly.
Include scope in parentheses: feat(api): add endpoint
"""

Ticket Number Requirement

instructions = """
Always include the ticket number in the format [PROJ-123].
If no ticket exists, use [NO-TICKET].
"""

Security-Focused Reviews

instruction_preset = "security"

instructions = """
Pay special attention to:
- Authentication and authorization
- Input validation
- SQL injection risks
- XSS vulnerabilities
"""

Monorepo Configuration

instructions = """
This is a monorepo with multiple packages.
Always specify which package is affected:
- @app/frontend
- @app/backend
- @app/shared
"""

Managing Project Config

View Current Config

git-iris project-config --print

Update Settings

# Change provider
git-iris project-config --provider google

# Change model
git-iris project-config --model gemini-3-pro-preview

# Update token limit
git-iris project-config --token-limit 100000

Edit Manually

# Edit .irisconfig directly
vim .irisconfig

Remove Project Config

# Delete the file
rm .irisconfig

# Or git remove
git rm .irisconfig

Version Control

Should You Commit .irisconfig?

Yes, if:

• Your team wants consistent commit style
• You have project-specific instructions
• You want to standardize on a provider/model

Consider .gitignore if:

• Each developer has different preferences
• The config is purely personal

Recommended .irisconfig

# Commit to version control
use_gitmoji = true
instruction_preset = "conventional"
default_provider = "anthropic"

instructions = """
Project-specific guidelines here.
"""

[providers.anthropic]
model = "claude-sonnet-4-5-20250929"
fast_model = "claude-haiku-4-5-20251001"

# API keys NOT included - loaded from personal config

Team Onboarding

Setup Instructions for New Team Members

1. Install Git-Iris:

   brew install hyperb1iss/tap/git-iris

2. Configure personal API key:

   git-iris config --provider anthropic --api-key YOUR_API_KEY

3. Clone the repo:

   git clone <repo-url>
   cd <repo>

4. Git-Iris auto-detects .irisconfig:

   git-iris gen
   # Uses project config automatically

Troubleshooting

Project Config Not Loading

Check that .irisconfig is in repository root:

git rev-parse --show-toplevel  # Find repo root
ls -la .irisconfig  # Check file exists

API Key Still Required

Project config doesn't include API keys. Set via:

# Personal config
git-iris config --provider anthropic --api-key YOUR_API_KEY

# Or environment variable
export ANTHROPIC_API_KEY="sk-ant-..."

Settings Not Applied

Check layering priority:

# View effective config
git-iris project-config --print

# CLI flags override everything
git-iris gen --provider openai  # Overrides project config

Conflicting Settings

CLI flags take final precedence:

Personal Config -> Project Config -> CLI Flags

Example:

# .irisconfig sets provider = "anthropic"
# But this command uses openai:
git-iris gen --provider openai

Examples

Open Source Project

# .irisconfig for open source contributors

use_gitmoji = true
instruction_preset = "conventional"

instructions = """
Follow our CONTRIBUTING.md guidelines.
Reference issue numbers: Fixes #123
Keep commit messages under 72 characters.
"""

Enterprise Application

# .irisconfig for corporate repo

default_provider = "anthropic"
instruction_preset = "detailed"

instructions = """
Include:
- JIRA ticket: [PROJ-123]
- Affected microservices
- Database migration status
- Feature flag names (if applicable)
"""

[providers.anthropic]
model = "claude-sonnet-4-5-20250929"
token_limit = 150000

Microservice

# .irisconfig for payment-service

instructions = """
This is the payment-service microservice.
All commits should:
- Mention impact on payment flow
- Note PCI compliance implications
- Reference security review if needed
"""

instruction_preset = "security"