CodeOptiX

Agentic Code Optimization & Deep Evaluation for Superior Coding Agent Experience

Built by Superagentic AI, Powered by GEPA and Bloom

🚀 Get Started ⚡ Quick Start 📦 View on GitHub

🔍 What is CodeOptiX?¶

CodeOptiX is the universal code optimization engine that improves coding agent experience with deep evaluations and optimization.

When AI coding agents dazzle with impressive code but leave you wondering about quality, maintainability, security, and reliability, CodeOptiX ensures proper behavior through evaluations, reflection, and self-improvement. Powered by GEPA optimization and Bloom scenario generation.

🚀 Key Capabilities¶

• 🔍 Deep Behavioral Evaluation - Comprehensive testing against security, reliability, and quality behaviors
• 🧬 GEPA Optimization Engine - Genetic-Pareto Evolution for automatic agent improvement
• 🌸 Bloom-Style Scenario Generation - Intelligent test case creation for thorough evaluation
• 🎯 Multi-Agent Support - Works with Claude Code, Codex, Gemini CLI, and custom agents
• 🔧 Multi-Provider LLM Support - OpenAI, Anthropic, Google, and Ollama (local models included!)
• ⚡ CI/CD Integration - Automated quality gates and GitHub Actions support

📋 Open Source Limitations¶

The open source version provides core evaluation capabilities. Advanced features like agent evolution and optimization have limited support. For full optimization capabilities tailored to your needs, please get in touch.

🚀 Quick Start (30 Seconds)¶

# 1. Install
pip install codeoptix

# 2. Option A: Use Ollama (No API key!)
ollama serve
codeoptix eval \
  --agent basic \
  --behaviors insecure-code \
  --llm-provider ollama

# 2. Option B: Use cloud provider (requires API key)
export OPENAI_API_KEY="your-key-here"
codeoptix eval \
  --agent basic \
  --behaviors insecure-code \
  --llm-provider openai

That's it! You've just run your first quality check.

✨ Key Features¶

👥 Who Uses CodeOptiX?¶

codeoptix eval --agent claude-code --behaviors insecure-code

codeoptix ci --agent codex --behaviors insecure-code --fail-on-failure

codeoptix ci \
  --agent claude-code \
  --behaviors insecure-code,vacuous-tests \
  --config .codeoptix/config.yaml

🏗️ How It Works¶

CodeOptiX follows a simple Observe → Evaluate → Reflect → Evolve workflow:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Observe   │ --> │  Evaluate   │ --> │  Reflect    │ --> │   Evolve    │
│             │     │             │     │             │     │             │
│ Capture     │     │ Measure     │     │ Generate    │     │ Optimize    │
│ agent       │     │ against     │     │ insights    │     │ prompts     │
│ behavior    │     │ behaviors   │     │ on failures │     │ with GEPA   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

1. Observe¶

Capture agent behavior (code, tests, traces) from any coding agent.

2. Evaluate¶

Measure behavior against configurable specifications (security, test quality, plan alignment).

3. Reflect¶

Generate actionable insights on failures with root cause analysis.

4. Evolve¶

Optimize agent prompts using GEPA (Genetic-Pareto) for continuous improvement.

🚀 Usage Modes¶

Mode 1: Local Check (Primary)¶

When: You're ready to test your code after completing a feature/task

# Single behavior (recommended for getting started)
codeoptix eval \
  --agent claude-code \
  --behaviors insecure-code \
  --llm-provider openai

# Multiple behaviors
codeoptix eval \
  --agent codex \
  --behaviors insecure-code,vacuous-tests,plan-drift \
  --config examples/configs/basic.yaml

Features:

• ✅ Regression testing
• ✅ Code quality evaluation
• ✅ Multi-LLM critique (optional different model judge)
• ✅ Security scanning
• ✅ Optimization suggestions

Mode 2: CI/CD Integration (Primary)¶

When: Teams want automated quality gates

# CI/CD optimized command
codeoptix ci \
  --agent codex \
  --behaviors insecure-code \
  --fail-on-failure \
  --output-format summary

Features:

• ✅ GitHub Actions integration
• ✅ Proper exit codes for automation
• ✅ Summary and JSON output formats
• ✅ Fail-fast behavior
• ✅ PR comments (coming soon)

Mode 3: ACP Integration (Quality Bridge)¶

When: Users want quality checks integrated into editor workflow

# Register CodeOptiX as ACP agent
codeoptix acp register

# Use as quality bridge
codeoptix acp bridge --agent-name claude-code --auto-eval

# Multi-agent judge
codeoptix acp judge \
  --generate-agent claude-code \
  --judge-agent grok \
  --prompt "Write secure code"

Features:

• ✅ Quality bridge for editors (Zed, JetBrains, Neovim, VS Code)
• ✅ Multi-agent judge (generate with one, judge with another)
• ✅ Intelligent agent orchestration
• ✅ Real-time quality feedback
• ✅ Automatic code extraction

📋 Built-in Behaviors¶

CodeOptiX includes three built-in behavior specifications:

codeoptix eval --behaviors insecure-code

codeoptix eval --behaviors vacuous-tests

codeoptix eval --behaviors plan-drift --context plan.json

💡 Example Use Cases¶

Security Auditing¶

Ensure your agent never writes insecure code:

codeoptix eval \
  --agent claude-code \
  --behaviors insecure-code \
  --fail-on-failure

Test Quality Validation¶

Verify your agent generates meaningful tests:

codeoptix eval \
  --agent codex \
  --behaviors vacuous-tests \
  --config examples/configs/single-behavior-vacuous-tests.yaml

Requirements Alignment¶

Check that your agent follows requirements:

codeoptix eval \
  --agent gemini-cli \
  --behaviors plan-drift \
  --context requirements.json

CI/CD Quality Gates¶

Automated quality checks in your pipeline:

codeoptix ci \
  --agent codex \
  --behaviors insecure-code,vacuous-tests \
  --fail-on-failure \
  --output-format summary

📦 Installation¶

Using pip¶

pip install codeoptix

Using uv (Recommended)¶

uv pip install codeoptix

From Source¶

git clone https://github.com/SuperagenticAI/codeoptix.git
cd codeoptix
pip install -e .

📚 Documentation¶

Getting Started¶

• Installation - Set up CodeOptiX
• Quick Start - Your first evaluation (free with Ollama!)
• Single Behavior Quickstart - Simple API key-based testing
• Your First Evaluation - Step-by-step guide

Core Concepts¶

• Overview - Understanding CodeOptiX
• Agent Adapters - Connecting to agents
• Behavior Specifications - Defining behaviors
• Evaluation Engine - Running evaluations
• Reflection Engine - Understanding results
• Evolution Engine - Improving agents
• ACP Integration - Editor integration

Guides¶

• CLI Usage - Command-line interface (including ci command)
• Python API - Use CodeOptiX in Python
• Configuration - Advanced configuration
• GitHub Actions - CI/CD integration
• ACP Integration - ACP protocol integration
• Custom Behaviors - Create custom behaviors

Advanced¶

• GEPA Integration - Genetic-Pareto optimization
• Bloom Integration - Scenario generation
• Error Handling - Handle errors gracefully

🎓 Example Configurations¶

We provide ready-to-use configuration files:

• examples/configs/single-behavior-insecure-code.yaml - Security checks only
• examples/configs/single-behavior-vacuous-tests.yaml - Test quality only
• examples/configs/single-behavior-plan-drift.yaml - Requirements alignment only
• examples/configs/ci-cd.yaml - Optimized for CI/CD pipelines
• examples/configs/basic.yaml - Minimal configuration

See examples/configs/ directory in the repository for configuration examples.

🏆 Why CodeOptiX?¶

🚀 Get Started Now¶

📞 Support & Community¶

• 📖 Documentation
• 💬 GitHub Issues
• 💬 GitHub Discussions

📄 License¶

Apache License 2.0. See LICENSE for details.

🤖 About Superagentic AI¶

CodeOptiX is proudly built by Superagentic AI - Advancing the future of AI agent optimization and autonomous systems.

Our Mission¶

We're pioneering intelligent agent optimization technologies to enhance developer productivity and code quality. CodeOptiX represents our commitment to building tools that make AI coding assistants more reliable, efficient, and trustworthy.

Explore More¶

• Visit Superagentic AI - Learn about our mission and vision
• Our GitHub - Discover our other AI agent projects