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.

🎊 NEW: v3.0 MVP Now Available for Testing!

AgentCodeX v3.0 is a complete platform transformation: MCP-native, platform-agnostic, works with ANY AI (OpenAI, Anthropic, Google, Ollama, local), 3-5x faster execution, production-ready with comprehensive CLI.

Status: ✅ MVP Complete (318/318 story points) - Ready for deployment testing!

What's New in v3.0:

• ✅ 6 MCP Servers - Code (9100), Git (9101), Test (9102), Build (9103), Package (9104), Quality (9105)
• ✅ 23 Python Agents - All agents transformed from markdown to real code modules
• ✅ Complete CLI - 7 commands: execute, config, init, doctor, status, version, help
• ✅ Docker Compose - Full containerized deployment with health checks
• ✅ One-Command Install - ./install.sh handles everything
• ✅ ~45,000+ lines - Production code with >90% test coverage

Try v3.0 MVP:

git clone https://github.com/ScaledMinds/AgentCodeX.git
cd AgentCodeX/v3
./install.sh
agentcodex execute "Build a FastAPI todo list API"

📖 v3.0 Documentation | 🚀 Deployment Guide | 🔧 Troubleshooting

Note: v2.x (below) remains stable and production-ready. v3.0 is currently in MVP/alpha testing phase.

v2.4.2 (Current Stable Release)

✨ 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

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

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

🚀 Quick Start

Installation

npm install -g agentcodex

Create Your First Project

1. Create ideation folder with your vision:

mkdir my-saas/ideation

my-saas/ideation/vision.md:

# My SaaS Vision

We're building an AI-powered customer support platform.

## Features

- AI chatbot for common questions
- Ticket management system
- Analytics dashboard
- Team collaboration

## Users

- Support teams at SaaS companies
- Customer success managers

2. Initialize your project:

agentcodex init
# Or with flags for non-interactive:
agentcodex init --name=my-saas --dev=dev.my-saas.com --prod=my-saas.com

3. Edit your PRD and spawn MAESTRO:

cd my-saas
# Edit docs/ideation/prd.md with your requirements
# Then open in Claude Code and run:
/agentcodex-start

"Initialize project from ./ideation/ folder.
Build complete production-ready application.

Ask me for:
- Domain: mysaas.com
- OpenAI API key: [your key]"

4. Watch 23 agents build your app (~45 minutes):

• ✅ VISIONARY creates comprehensive PRD
• ✅ SCOUT researches competitors and market (4 market docs)
• ✅ ARCHITECT designs system architecture (4 architecture docs)
• ✅ CANVAS creates UI/UX design system (5 design docs)
• ✅ MEMEX indexes all documentation for agent retrieval
• ✅ DATAFORGE creates PostgreSQL + Weaviate schemas
• ✅ FORGE builds FastAPI backend with GPT-5
• ✅ NEXUS builds Next.js frontend with shadcn/ui
• ✅ HARBOR sets up Docker + Traefik + Keycloak
• ✅ VALIDATOR runs tests (95%+ coverage)
• ✅ GUARDIAN performs security scan
• ✅ Deployment to https://dev.mysaas.com

5. Promote to production when ready:

agentcodex promote

Done. Your SaaS is live.

🏗️ Architecture

The 23 Agents (NEW in v2.3: SCOUT + CANVAS)

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 (NEW v2.3)
• 🎨 CANVAS - UI/UX design system documentation (NEW v2.3)

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
• LangChain 0.3.30
• GPT-5 (400k context)
• SQLAlchemy 2.0.x (async)

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 (if needed)
• 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 learns from every project it builds.

How it works:

1. Collect Metrics - After each project, ORACLE gathers:

   • Build duration
   • Agent performance
   • Test coverage
   • Security score
   • User feedback

2. Analyze Patterns - Identifies:

   • Which agents fail most often
   • Common error patterns
   • Optimization opportunities

3. Apply Improvements - Automatically:

   • Updates agent prompts
   • Optimizes workflows
   • Adds code examples

4. Trigger Upgrades - When 10%+ improvement accumulated:

   • Generates changelog
   • Creates upgrade proposal
   • Notifies maintainer
   • Releases new version

Example:

Week 1-4: ORACLE observes FORGE failing 15% of time on async routes
Analysis: Prompt lacks async/await examples
Action: Update FORGE prompt with detailed patterns
Result: Failure rate drops to 2% (+13% improvement)

After 10 projects with cumulative 10%+ improvement → AgentCodeX v2.1 released

📚 Examples

Coming Soon:

• Complete example projects in separate showcase repository
• E-commerce platform
• CRM system
• Analytics dashboard
• Task management SaaS

🛠️ CLI Reference

agentcodex init

Initialize a new AgentCodeX project.

What it does:

1. Prompts for project name and domains (or accepts via flags)
2. Creates complete project structure in current directory
3. Copies all 23 agents, slash commands, and protocols
4. Creates starter PRD in docs/ideation/
5. Initializes git repository
6. Optionally creates GitHub repository and pushes code

Usage:

# Interactive mode
agentcodex init

# Non-interactive mode
agentcodex init --name=my-app --dev=dev.myapp.com --prod=myapp.com

agentcodex promote

Promote development environment to production.

What it does:

1. Runs pre-flight checks (tests, security scan)
2. Builds production Docker images
3. Deploys with zero downtime
4. Performs health checks
5. Notifies on completion

Usage:

agentcodex promote

agentcodex status

Show system and agent status.

What it does:

• Shows environment (dev/prod)
• Lists running services
• Displays agent activity
• Shows recent metrics

Usage:

agentcodex status

agentcodex sync

Sync framework updates to existing projects.

What it does:

1. Detects framework version changes (semantic versioning)
2. Identifies modified/new agents, protocols, templates
3. Creates automatic backup before any changes
4. Updates framework files (preserves custom agents)
5. Provides rollback on failure

Flags:

• --check - Check for updates without applying
• --preview - Show what would change (dry run)
• --force - Skip confirmation prompts

Usage:

# Check for updates
agentcodex sync --check

# Preview changes
agentcodex sync --preview

# Apply updates
agentcodex sync

# Force update (no prompts)
agentcodex sync --force

How it works:

• Framework agents in .claude/agents/ are updated automatically
• Your custom agents in .claude/agents-custom/ are never touched
• Automatic migration for legacy projects (pre-sync system)
• Uses MD5 checksums to detect only changed files (AWS S3 pattern)

agentcodex restore

Restore from automatic sync backups.

What it does:

1. Lists available backups (timestamped snapshots)
2. Shows file count and creation date
3. Restores project to selected backup state
4. Provides rollback for failed syncs

Flags:

• --latest - Restore most recent backup
• --force - Skip confirmation prompt

Usage:

# Interactive restore (select backup)
agentcodex restore

# Restore latest backup
agentcodex restore --latest

# Force restore (no confirmation)
agentcodex restore --latest --force

Note: Backups are created automatically in .agentcodex-backups/ during sync operations. Last 5 backups are kept.

🎓 How It Works

1. You Provide Vision

Create ideation/ folder with your ideas:

• vision.md - What you're building and why
• features.md - What features you want
• Any other context (wireframes, notes, etc.)

2. MAESTRO Orchestrates

MAESTRO reviews your ideation and coordinates all agents:

Sequential Phase:
  VISIONARY → Creates PRD
  ARCHITECT → Designs system
  MEMEX → Indexes knowledge

Parallel Building:
  FORGE + NEXUS + DATAFORGE + HARBOR
  (All build simultaneously)

Parallel Validation:
  VALIDATOR + GUARDIAN + SENTINEL
  (Test, scan, quality check)

Deployment:
  HARBOR → Deploys everything
  CHRONICLE → Sets up monitoring

3. Agents Execute Autonomously

Each agent is an expert:

• FORGE knows FastAPI, async patterns, GPT-5 integration
• NEXUS knows Next.js, React 19, shadcn/ui, accessibility
• HARBOR knows Docker, Traefik, TLS, Keycloak

They work together, sharing context through MEMEX.

4. You Get Production App

45 minutes later:

• ✅ Fully functional application
• ✅ Comprehensive test suite
• ✅ Security hardened
• ✅ Production deployed
• ✅ Monitoring enabled

🔒 Security

AgentCodeX takes security seriously:

• ✅ All dependencies scanned (Trivy)
• ✅ No known vulnerabilities
• ✅ Secrets in environment variables
• ✅ TLS everywhere (Let's Encrypt in prod)
• ✅ JWT authentication
• ✅ Role-based authorization
• ✅ Input validation (Pydantic)
• ✅ SQL injection prevention
• ✅ XSS protection
• ✅ CSRF tokens

GUARDIAN agent performs comprehensive security audit on every build.

📊 Performance

AgentCodeX builds fast, efficient applications:

Build Metrics:

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

Runtime Performance:

• Page load: <500ms P95
• API response: <200ms P95
• Database queries: Optimized with indexes
• Frontend: Server Components where possible

PROBE agent continuously optimizes for performance.

🤝 Contributing

AgentCodeX welcomes contributions!

Ways to Contribute

1. Improve Agent Prompts - Make agents smarter
2. Add Templates - Support more project types
3. Enhance ORACLE - Better learning algorithms
4. Fix Bugs - Report and fix issues
5. Documentation - Improve guides

Development Setup

git clone https://github.com/ScaledMinds/AgentCodeX
cd agentcodex
npm install
npm link

# Test locally
agentcodex --version

See CONTRIBUTING.md for details.

📖 Documentation

Complete Documentation Index - Start here for all documentation

Quick Links

• 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 MVP (October 2025 - COMPLETE! ✅)

• ✅ MCP-Native Architecture - 6 MCP servers (Code, Git, Test, Build, Package, Quality)
• ✅ Platform-Agnostic - Works with ANY AI (OpenAI, Anthropic, Google, Ollama)
• ✅ 23 Python Agents - All agents as real code modules (no markdown)
• ✅ Complete CLI - 7 commands with full functionality
• ✅ Docker Compose - Production-ready containerized deployment
• ✅ One-Command Install - Automated setup with ./install.sh
• ✅ ~45,000+ lines - Production code with >90% test coverage
• ✅ Configuration System - YAML + env variable overrides
• ✅ Health Monitoring - agentcodex doctor command
• ✅ Critical Bug Fix - LLM service multi-source config integration

Status: Ready for deployment testing and real-world validation!

v3.0 Next Phases:

• 📋 Phase 3: LLM Provider Expansion (Q1 2026)

  • Anthropic Claude integration
  • Google Gemini integration
  • Ollama local models
  • Custom LLM adapters

• 📋 Phase 4: Intelligence & Safety (Q1 2026)

  • Oracle MCP (9106) - Advanced learning
  • Guardian MCP (9107) - Enhanced security
  • Cross-project insights
  • Distributed learning

• 📋 Phase 5: Production Polish & Launch (Q2 2026)

  • Web UI (visual project builder)
  • REST/GraphQL API
  • Streaming execution output
  • Resume interrupted executions
  • Beta testing program
  • Official v3.0 production release

v2.4.2 (Current Stable - October 2025)

• ✅ 23 specialized agents (SCOUT + CANVAS)
• ✅ MAESTRO orchestration
• ✅ V4 tech stack (exact versions)
• ✅ Self-improvement (ORACLE)
• ✅ Framework sync system
• ✅ MCP-First Architecture (3 data servers)
• ✅ Complete documentation

v2.5 (Planned - if v3.0 adoption is delayed)

• Visual Builder (web-based project generator)
• Mobile app support (React Native)
• Additional templates (E-commerce, CRM, Analytics)
• Custom tech stack support

💬 Community

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

📄 License

MIT License - See LICENSE file for details.

🙏 Acknowledgments

• Claude Code by Anthropic - Enabling agentic development
• GPT-5 by OpenAI - Powering AI features
• Open Source Community - For the incredible tools we build on

⚡ Get Started Now

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