cicaddy

Platform-agnostic AI agent for running AI workflows in CI pipelines, with MCP tool integration and multi-step execution engine.

Features

• Multi-provider AI: Gemini, OpenAI, Claude (direct API and Vertex AI for both Gemini and Claude)
• Sub-agent delegation: AI-powered triage with parallel specialized sub-agents
• MCP integration: Connect to any MCP-compatible tool server
• Multi-step execution: Token-aware execution engine with recovery
• YAML task definitions: DSPy-based task configuration
• Notifications: Slack and email notification support
• HTML reports: Customizable analysis report generation
• Extensible agents: Registry-based agent factory for custom agents

Installation

# Recommended install (includes Vertex AI support for Gemini and Claude)
pip install 'cicaddy[vertex]'

# Base install (Gemini via Vertex AI and standalone API key providers)
pip install cicaddy

Quick Start

# Run with environment file
cicaddy run --env-file .env

# Run with CLI arguments
cicaddy run --ai-provider gemini-vertex --agent-type task --log-level DEBUG

# Show configuration
cicaddy config show --env-file .env

# Validate configuration
cicaddy validate --env-file .env

Configuration

Configure via environment variables or .env file. Vertex AI with Application Default Credentials (ADC) is the recommended default, following Google Agent Platform security hardening guidelines that favor ADC over standalone API keys.

# AI Provider (Gemini via Vertex AI — uses Google Cloud ADC, no API key needed)
AI_PROVIDER=gemini-vertex
AI_MODEL=gemini-3.5-flash
GOOGLE_CLOUD_PROJECT=your-gcp-project
# GOOGLE_CLOUD_LOCATION=global  # optional, defaults to "global"

# AI Provider (Claude via Vertex AI — uses Google Cloud ADC, no API key needed)
# AI_PROVIDER=anthropic-vertex
# AI_MODEL=claude-sonnet-4-6
# ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project
# GOOGLE_CLOUD_LOCATION=global

# AI Provider (Gemini — standalone API key)
# AI_PROVIDER=gemini
# AI_MODEL=gemini-3-flash
# GEMINI_API_KEY=your-key-here

# Agent
AGENT_TYPE=task
TASK_TYPE=scheduled_analysis

# MCP Servers (JSON array)
MCP_SERVERS_CONFIG=[]

# Notifications
SLACK_WEBHOOK_URL=https://hooks.slack.com/...

# DSPy Task File (takes precedence over AI_TASK_PROMPT)
AI_TASK_FILE=tasks/dora_report.yaml

DSPy Task Definition (YAML)

Instead of raw prompt strings (AI_TASK_PROMPT), define structured tasks in YAML with typed inputs, expected outputs, MCP tool constraints, and reasoning strategy. Set AI_TASK_FILE to your task file path.

See examples/dora_metrics_task.yaml for a complete DORA metrics analysis task using DevLake MCP, and examples/templates/report_template.html for the HTML report template.

Key schema fields:

Sub-Agent Delegation (v0.8.0+)

Enable AI-powered sub-agent delegation with DELEGATION_MODE=auto. An AI triage step analyzes the context, selects specialized sub-agents (security, architecture, performance, etc.), runs them in parallel with sibling awareness (each agent knows what others cover), and aggregates results.

# Add to your .env
DELEGATION_MODE=auto
MAX_SUB_AGENTS=3

cicaddy run --env-file .env

Built-in review agents: security-reviewer, architecture-reviewer, api-reviewer, database-reviewer, ui-reviewer, devops-reviewer, performance-reviewer, general-reviewer. Custom agents can be defined via YAML files in .agents/delegation/.

See docs/sub-agent-delegation.md for full configuration, built-in agent details, custom agent YAML format, and tool filtering. See examples/delegation/ for example configurations.

Extending with Platform Plugins

cicaddy discovers platform plugins automatically via Python entry_points. Plugins can register agents, CLI args, env vars, config sections, validators, and a settings loader — without modifying cicaddy itself.

1. Define plugin callables (my_plugin/plugin.py):

def register_agents():
    from cicaddy.agent.factory import AgentFactory
    from my_plugin.agent import MergeRequestAgent, detect_agent_type

    AgentFactory.register("merge_request", MergeRequestAgent)
    AgentFactory.register_detector(detect_agent_type, priority=40)

def get_cli_args():
    from cicaddy.cli.arg_mapping import ArgMapping
    return [
        ArgMapping(cli_arg="--mr-iid", env_var="CI_MERGE_REQUEST_IID",
                   help_text="Merge request IID"),
    ]

2. Register in pyproject.toml:

[project.entry-points."cicaddy.agents"]
my_platform = "my_plugin.plugin:register_agents"

[project.entry-points."cicaddy.cli_args"]
my_platform = "my_plugin.plugin:get_cli_args"

[project.entry-points."cicaddy.settings_loader"]
my_platform = "my_plugin.config:load_settings"

3. Install and run — plugins are discovered automatically:

pip install cicaddy my-cicaddy-plugin
cicaddy run --env-file .env

Available plugin groups: cicaddy.agents, cicaddy.cli_args, cicaddy.env_vars, cicaddy.config_sections, cicaddy.validators, cicaddy.settings_loader.

Official Plugins

License

Apache-2.0