AgentCodeX

The World's First Self-Improving Agentic Development Framework

Build production-ready applications from ideation to deployment in minutes—not weeks. AgentCodeX orchestrates 23 specialized AI agents that autonomously design, build, test, and deploy your application while continuously learning and improving.

🎊 v3.0.0-beta.1 Released - Platform-Agnostic AI Development is HERE!

AgentCodeX v3.0 is a complete platform transformation: Platform-agnostic (works with ANY AI), MCP-native architecture, Guardian safety system, Oracle learning engine, 3-5x faster, and 100% test coverage!

Status: ✅ BETA RELEASED (493/493 story points | 100% test coverage | Zero errors/warnings)

What's New in v3.0.0-beta.1

Core Transformation:

• ✅ Platform Independence - No longer tied to Claude Code! Works with OpenAI, Anthropic, Ollama (local), any LLM
• ✅ Dual-Mode Architecture - Direct API ($900+/mo) OR CLI-integrated ($20-40/mo) - you choose
• ✅ Cost Flexibility - From $0 (local Ollama) to $900+ (enterprise APIs)
• ✅ 3-5x Performance - Python modules instead of markdown agents

Intelligence & Safety:

• ✅ Guardian MCP (Port 9107) - Prevents disasters, detects secrets, creates backups
• ✅ Oracle MCP (Port 9106) - Gets smarter with every execution, pattern recognition
• ✅ 8 MCP Servers - Code, Git, Test, Build, Package, Quality, Oracle, Guardian
• ✅ 23 Python Agents - All high-performance modules (no markdown)

Quality & Scale:

• ✅ 100% Test Coverage - 250 tests, all passing, comprehensive validation
• ✅ ~65,000+ lines - Production code, fully tested and documented
• ✅ Complete CLI - 7 commands for full project lifecycle
• ✅ Docker Compose - Production-ready orchestration

Multi-LLM Support:

• ✅ OpenAI API - GPT-4, GPT-3.5
• ✅ Anthropic API - Claude 3 Opus/Sonnet/Haiku
• ✅ Ollama - Local LLMs (Llama2, Mistral, CodeLlama)
• ✅ Claude Code CLI - Integrated mode
• ✅ OpenAI Codex - Codex integration

Installation (v3.0 Beta)

# From PyPI (recommended for testing)
pip install -i https://test.pypi.org/simple/ agentcodex==3.0.0b1

# Or from source
git clone https://github.com/ScaledMinds/AgentCodeX.git
cd AgentCodeX/v3
./install.sh

Quick Start (v3.0)

# Initialize your project
agentcodex init --name=my-app

# Configure your LLM provider
export OPENAI_API_KEY="your-key"
# or
export ANTHROPIC_API_KEY="your-key"
# or use Ollama locally (no key needed)

# Execute autonomous development
agentcodex execute "Build a FastAPI todo list API with PostgreSQL"

# Check status
agentcodex doctor

# Run tests
cd my-app && pytest

📖 v3.0 User Guide | 🚀 Deployment Guide | 🔧 Troubleshooting | 📦 Manual Release

Beta Testing

v3.0.0-beta.1 is ready for beta testing! We're looking for feedback on:

• Multi-LLM provider experiences
• Guardian safety system effectiveness
• Oracle learning recommendations
• Performance improvements
• Documentation clarity

Report issues: GitHub Issues

Migration from v2.x: See Migration Guide (coming soon)

v2.4.2 (Current Stable - Production Ready)

v2.x remains stable and production-ready. No changes required for existing users.

npm install -g agentcodex

See v2.x documentation below for v2 usage.

✨ What is AgentCodeX?

AgentCodeX is a revolutionary framework that combines:

🤖 23 Specialized AI Agents - Each expert in their domain (backend, frontend, DevOps, security, market research, UI/UX design, etc.)

🧠 MAESTRO Orchestrator - Supreme autonomous coordinator that manages all agents

🔮 ORACLE Meta-Learner - Self-improvement engine that makes the framework smarter with every project

🛡️ GUARDIAN Safety System - Prevents dangerous operations, detects secrets, creates automatic backups

📦 V4 Tech Stack - Production-ready stack with exact versions (Next.js 15.5, FastAPI 0.118.0, Python 3.13, etc.)

⚡ 7-Command CLI - Minimal human interaction, maximum automation

🚀 Architecture (v3.0)

The 8 MCP Servers

MCP (Model Context Protocol) - Microservice architecture for tool operations:

1. Code MCP (9100) - File operations, AST parsing, code search
2. Git MCP (9101) - Version control operations
3. Test MCP (9102) - Test execution (pytest, jest, etc.)
4. Build MCP (9103) - Compilation and bundling
5. Package MCP (9104) - Dependency management
6. Quality MCP (9105) - Linting, formatting, security scans
7. Oracle MCP (9106) - Learning, pattern recognition, recommendations
8. Guardian MCP (9107) - Safety validation, secret detection, backups

The 23 Agents

Tier 1: Strategic Intelligence

• 🎯 MAESTRO - Supreme orchestrator, coordinates everything
• 🔮 ORACLE - Self-improving meta-learner
• 💡 VISIONARY - Transforms ideas into requirements
• 🏛️ ARCHITECT - Designs bulletproof architecture
• 🧠 MEMEX - Maintains project knowledge

Tier 2: Core Builders

• ⚒️ FORGE - Backend master (FastAPI + GPT-5)
• 🎨 NEXUS - Frontend architect (Next.js + React)
• 🗄️ DATAFORGE - Database sculptor (PostgreSQL + Weaviate)
• 🚢 HARBOR - DevOps captain (Docker + Traefik)

Tier 3: Integration & Quality

• 🔌 CONDUIT - API gateway specialist
• 🔗 TETHER - Integration engineer
• 🛡️ SENTINEL - Code quality guardian
• 🔒 GUARDIAN - Security sentinel
• ✅ VALIDATOR - Test automation expert
• 🔍 SCOUT - Market research & competitor analysis
• 🎨 CANVAS - UI/UX design system documentation

Tier 4: Operations & Intelligence

• ⚡ PROBE - Performance optimizer
• 📚 SCRIBE - Documentation master
• 🔥 PHOENIX - Self-healing system
• 📊 CHRONICLE - Observability engineer
• 🧹 JANITOR - Maintenance expert
• 🚀 COURIER - CI/CD pipeline master
• 🌍 STEWARD - Environment manager

Tech Stack (V4 - October 2025)

Backend:

• Python 3.13
• FastAPI 0.118.0
• SQLAlchemy 2.0.x (async)
• LangChain 0.3.30 (optional)
• GPT-5 (400k context)

Frontend:

• Next.js 15.5 (App Router)
• React 19.2
• TypeScript 5.x
• Tailwind CSS 3.4.x
• shadcn/ui

Databases:

• PostgreSQL 16.10
• Weaviate 1.33.0 (vector DB)

Infrastructure:

• Docker + Docker Compose
• Traefik 3.5.2 (reverse proxy + TLS)
• Keycloak 26.4.0 (auth)

Observability:

• Prometheus 2.x
• Grafana 11.x
• Loki 3.x

🎯 What You Get

Every AgentCodeX project includes:

✅ Complete Backend API

• FastAPI with async/await
• GPT-5 integration (optional)
• PostgreSQL database
• Vector search (Weaviate)
• OpenAPI documentation
• 95%+ test coverage

✅ Modern Frontend

• Next.js App Router
• Server Components
• shadcn/ui components
• Dark mode support
• Fully responsive
• TypeScript strict mode

✅ Production Infrastructure

• Docker Compose for dev & prod
• Traefik with automatic TLS
• Keycloak authentication
• Health checks
• Auto-restart policies

✅ Observability

• Prometheus metrics
• Grafana dashboards
• Structured logging (Loki)
• Error tracking

✅ CI/CD Pipelines

• GitHub Actions workflows
• Automated testing
• Security scanning
• Zero-downtime deployments

✅ Comprehensive Documentation

• Product Requirements Document
• System Architecture (C4 diagrams)
• API Specification
• Database Schema
• Deployment Guide

🔮 Self-Improvement (ORACLE)

AgentCodeX v3.0 learns from every execution through the Oracle MCP.

How it works:

1. Log Executions - Oracle records:

   • Commands executed
   • Files modified
   • Errors encountered
   • Success/failure outcomes

2. Recognize Patterns - Identifies:

   • Common command sequences
   • Frequent error patterns
   • Successful workflows
   • Optimization opportunities

3. Provide Recommendations - Suggests:

   • Best practices for current context
   • Error resolutions based on history
   • Optimized command sequences
   • Preventive measures

4. Cross-Project Learning - Aggregates:

   • Insights across multiple projects
   • Team-wide best practices
   • Industry pattern library

Example:

Project 1-5: Oracle observes async/await pattern succeeds 95% when following specific structure
Analysis: Identifies optimal async FastAPI patterns
Action: Recommends these patterns for new async routes
Result: New projects have 98% success rate on async implementations

🛡️ Guardian Safety System

AgentCodeX v3.0 prevents disasters before they happen.

What Guardian Protects Against:

1. Dangerous Commands

   • rm -rf / and variations
   • DROP DATABASE without confirmation
   • Force push to main branch
   • Destructive git operations

2. Secret Exposure

   • AWS credentials
   • GitHub tokens
   • OpenAI API keys
   • Database passwords
   • Private keys

3. Destructive Operations

   • Mass file deletions
   • Database migrations without backup
   • Production deployments without tests

How Guardian Works:

Before ANY file/database/git operation:
1. Guardian MCP validates the operation
2. Checks against dangerous patterns
3. Scans for secrets in changes
4. Creates automatic backup if risky
5. Provides risk assessment + recommendations
6. Blocks if score > threshold OR creates backup and proceeds

Automatic Backups:

• Created before risky operations
• Stored with metadata
• Easy rollback via Guardian client
• Retention policy configurable

📚 Documentation

Complete Documentation Index - Start here for all documentation

v3.0 Documentation

• User Guide - Complete v3.0 usage guide
• Launch Readiness - Beta program details
• Deployment Guide - Production deployment
• Troubleshooting - Common issues
• Test Results - 100% coverage report
• Manual Release Guide - Publishing instructions
• CHANGELOG - What's new in v3.0.0-beta.1

v2.x Documentation

• What is AgentCodeX? - Overview for newcomers
• Quick Start - Build your first app
• Complete Workflow - How all 23 agents work together
• CLI Reference - All commands
• Tech Stack V4 - Technology versions
• Philosophy - Design principles
• Agent Definitions - All 23 agent files

🗺️ Roadmap

v3.0.0-beta.1 (October 2025) - ✅ RELEASED

All 16 Sprints Complete - 493/493 Story Points Delivered

• ✅ 8 MCP Servers - Complete microservice architecture
• ✅ 23 Python Agents - High-performance modules
• ✅ Multi-LLM Support - OpenAI, Anthropic, Ollama, Claude Code, Codex
• ✅ Dual-Mode Architecture - API or CLI integrated
• ✅ Guardian Safety System - Comprehensive protection
• ✅ Oracle Learning System - Self-improvement engine
• ✅ 100% Test Coverage - 250 tests, all passing
• ✅ Complete CLI - 7 commands
• ✅ Docker Compose - Production orchestration

Status: Ready for beta testing!

v3.0.0 GA (April 2026)

• Web UI dashboard
• Additional LLM providers (Gemini, Mistral)
• Cloud deployment templates (AWS, GCP, Azure)
• Enhanced monitoring
• Plugin system
• Community extensions

v2.4.2 (Current Stable)

• ✅ 23 specialized agents
• ✅ MAESTRO orchestration
• ✅ V4 tech stack
• ✅ Self-improvement (ORACLE)
• ✅ Framework sync system
• ✅ MCP-First Architecture

🤝 Contributing

AgentCodeX welcomes contributions!

Ways to Contribute

1. Beta Testing v3.0 - Try it, break it, report it
2. Improve Agent Prompts - Make agents smarter
3. Add LLM Adapters - Support more providers
4. Enhance Documentation - Improve guides
5. Fix Bugs - Report and fix issues

Development Setup

git clone https://github.com/ScaledMinds/AgentCodeX
cd AgentCodeX

# v2.x development
npm install
npm link

# v3.x development
cd v3
./install.sh

See CONTRIBUTING.md for details.

📊 Performance

v3.0 Performance Metrics

• Agent Response: <3 seconds (was 10-15s in v2.x)
• MCP Latency: <100ms average
• Token Processing: 50-100 tokens/sec
• Memory Usage: <2GB (without local LLMs)
• Docker Images: <500MB each

Build Metrics

• Time to deployment: ~45 minutes
• Test coverage: 95%+ (enforced)
• Security score: 100/100 (required)

🔒 Security

AgentCodeX v3.0 takes security seriously:

Built-in Protection:

• ✅ Guardian MCP prevents dangerous operations
• ✅ Secret detection (AWS, GitHub, OpenAI, etc.)
• ✅ Automatic backups before risky changes
• ✅ TLS everywhere (Let's Encrypt in prod)
• ✅ JWT authentication
• ✅ Role-based authorization

Code Security:

• ✅ Dependencies scanned (Trivy)
• ✅ No known vulnerabilities
• ✅ Input validation (Pydantic)
• ✅ SQL injection prevention
• ✅ XSS protection
• ✅ CSRF tokens

💬 Community

• GitHub Discussions: Ask questions, share projects
• Issues: Report bugs, request features
• Discord: Join the community (coming soon)
• Twitter: @agentcodex (coming soon)

📄 License

MIT License - See LICENSE file for details.

🙏 Acknowledgments

• Anthropic - For Claude and Claude Code
• OpenAI - For GPT-4 and GPT-5
• Ollama - For local LLM support
• Open Source Community - For the incredible tools we build on

⚡ Get Started Now

v3.0 (Beta)

pip install -i https://test.pypi.org/simple/ agentcodex==3.0.0b1
agentcodex init --name=my-app
agentcodex doctor

v2.x (Stable)

npm install -g agentcodex
agentcodex init

# Edit docs/ideation/prd.md
# Open in Claude Code
# Run: /agentcodex-start

Build production apps in minutes, not months.

🚀 The future of development is agentic. The future is AgentCodeX.

Made with 🤖 by BJ Urban

Documentation • Agents • Issues • v3.0 User Guide