AutomatosX

From Idea to Production in Minutes: The AI Workforce Platform with Persistent Memory

AutomatosX is the only AI CLI that combines declarative workflow specs, policy-driven cost optimization, and a persistent AI workforce. Write a YAML spec, and AutomatosX generates your entire project—plans, infrastructure, tests, and execution—while remembering everything and optimizing every API call.

Status: ✅ Production Ready v6.0.1 | Oct 2025 | 23 Specialized Agents | Spec-Kit 87.5% Complete | Policy-Driven Routing | Auto-Generation

🚀 The Complete AI Workflow Platform

AutomatosX is the only AI platform that gives you:

⚡ Quick Start: 60 Seconds to Your First Workflow

# 1. Install AutomatosX
npm install -g @defai.digital/automatosx

# 2. Initialize your project
cd your-project && ax init

# 3. Create a workflow spec in natural language
ax spec create "Build user authentication with database, API, JWT, security audit, and tests"

# AutomatosX automatically:
#   ✅ Generates a complete project spec (.specify/)
#   ✅ Creates execution plan with cost estimates
#   ✅ Generates DAG for parallel execution
#   ✅ Scaffolds project structure
#   ✅ Generates comprehensive tests
#   ✅ Executes with policy-optimized routing
#   ✅ Tracks all decisions with trace logging

# 4. View the generated plan
ax gen plan workflow.ax.yaml

# 5. Execute the workflow (with cost optimization)
ax run workflow.ax.yaml

Result: Complete authentication system with database, API, security audit, and tests—generated and executed in minutes, not days.

🗣️ Recommended: Natural Language Interface

AutomatosX is designed to work seamlessly with AI assistants using natural language commands. This is the recommended way to use AutomatosX:

Use with Claude Code, Gemini CLI, or OpenAI Codex

# In Claude Code
"Please work with ax agent backend to implement user authentication"
"Ask the ax security agent to audit this code for vulnerabilities"
"Have the ax quality agent write tests for this feature"

# In Gemini CLI
"Use ax to help me find and fix bugs in the authentication system"
"Work with ax agent data to optimize the database queries"

# In OpenAI Codex
"Collaborate with ax agent frontend to build the login UI"
"Use ax agent devops to set up CI/CD pipeline"

Why Natural Language?

• ✅ Conversational: Talk to AI assistants like teammates
• ✅ Context-aware: AI assistants maintain full conversation context
• ✅ Flexible: No need to remember exact command syntax
• ✅ Integrated: Works directly in your AI assistant workflow
• ✅ Powerful: Combines AI assistant capabilities with AutomatosX's memory and orchestration

Behind the Scenes

When you say "work with ax agent backend", the AI assistant:

1. Calls ax run backend "your task" with the appropriate context
2. AutomatosX routes to the optimal provider based on policy
3. Persistent memory ensures no context is lost
4. Results are returned to your AI assistant
5. The conversation continues naturally

This natural language interface is how we expect users to work with AutomatosX daily.

CLI-Only Mode (No API Access Required)

If you only have CLI tools installed and no API access (no API keys or restricted network), you can force CLI-only mode:

# Set environment variable to enforce CLI-only mode
export AUTOMATOSX_CLI_ONLY=true

# Now all providers will use CLI integration (subprocess), never API
ax run backend "implement user authentication"

When to use CLI-only mode:

• ✅ You have codex, gemini, or claude CLI tools installed
• ✅ You don't have API keys configured
• ✅ You're behind a corporate firewall blocking API access
• ✅ You want to avoid API connection attempts and retries

What it does:

• Forces openai provider to use CLI subprocess mode (codex command)
• Prevents OpenAI SDK API calls even if configured for SDK mode
• Eliminates "Unable to connect to API" errors and retry loops

Note: This only affects OpenAI provider. Claude and Gemini providers always use CLI mode by default.

🎯 What Makes AutomatosX Different?

Traditional AI Workflows

# ❌ Manual coordination
codex "Design auth system"
# → Copy/paste output

codex "Implement API from this design: [paste design]"
# → Repeat context, pay for duplicate tokens

codex "Write tests for this code: [paste code]"
# → Lost context, higher costs, manual orchestration

# Result: Slow, expensive, repetitive

AutomatosX Workflows

# ✅ Declarative, automated, optimized
ax spec create "Build auth system with API, tests, and security audit"

# Result: Complete system generated and executed automatically
#   - Persistent memory eliminates context repetition
#   - Policy routing saves 60-80% on API costs
#   - Parallel execution completes 3-5x faster
#   - Auto-generated tests provide 60%+ baseline coverage

📋 NEW: Spec-Kit Integration (v6.0+)

The game-changing feature that makes AutomatosX the most powerful AI workflow platform.

1. Define Your Workflow in YAML

# workflow.ax.yaml
metadata:
  id: user-auth-system
  name: User Authentication System

# Policy-driven routing: Optimize for cost
policy:
  goal: cost
  constraints:
    cost:
      maxPerRequest: 0.01
      maxDaily: 0.50
    latency:
      p95: 5000

actors:
  - id: backend
    agent: backend
    description: Implement JWT authentication API

  - id: security
    agent: security
    description: Audit authentication implementation

  - id: quality
    agent: quality
    description: Generate comprehensive test suite

2. Generate Everything Automatically

# Generate execution plan with cost estimates
ax gen plan workflow.ax.yaml
# Output: Execution plan with phases, costs ($0.003-$0.008), risks

# Generate DAG for parallel execution
ax gen dag workflow.ax.yaml --format mermaid
# Output: Dependency graph with change detection hash

# Scaffold complete project structure
ax gen scaffold workflow.ax.yaml
# Output: Full directory structure, configs, READMEs

# Generate comprehensive test suite
ax gen tests workflow.ax.yaml
# Output: Unit, integration, E2E tests with policy assertions

3. Execute with Policy Optimization

# Run workflow with cost optimization
ax run workflow.ax.yaml

# AutomatosX automatically:
#   1. Filters providers by cost constraint ($0.01/request)
#   2. Selects cheapest provider (Gemini: $0.000125/1K tokens)
#   3. Executes actors in optimal order
#   4. Logs all decisions to trace file
#   5. Stays within budget ($0.50/day)

4. Debug with Complete Visibility

# View all routing decisions
ax providers trace --follow

# Output (real-time):
# 18:26:49  POLICY       gemini-cli      goal=cost, passed=2/3
# 18:26:50  SELECTION    gemini-cli      3 candidates → policy-based selection
# 18:26:51  EXECUTION    gemini-cli      ✓ 1234ms, $0.000375

The Complete Workflow:

# From idea to production in one command
ax spec create "Build e-commerce checkout with Stripe, inventory, and fraud detection" \
  && ax run workflow.ax.yaml

# AutomatosX handles:
#   ✅ Cost optimization (saves 60-80% vs Claude/GPT)
#   ✅ Parallel execution (3-5x faster)
#   ✅ Persistent memory (zero context repetition)
#   ✅ Auto-generated tests (60%+ coverage)
#   ✅ Complete observability (trace every decision)

💰 Policy-Driven Cost Optimization

AutomatosX is the only AI platform with built-in cost optimization. Define your budget and constraints—AutomatosX automatically routes every request to the optimal provider.

How It Works

# Set your constraints in the spec
policy:
  goal: cost  # Options: cost, latency, reliability, balanced

  constraints:
    cost:
      maxPerRequest: 0.01    # Max $0.01 per request
      maxDaily: 1.00         # Max $1.00 per day

    latency:
      p95: 5000              # Max 5 seconds at P95

    privacy:
      allowedClouds: [gcp]   # Only Google Cloud providers

AutomatosX Routes Intelligently:

Real Savings:

# Traditional workflow (all Claude)
Task 1: $0.015  (Claude)
Task 2: $0.018  (Claude)
Task 3: $0.012  (Claude)
Total: $0.045

# AutomatosX workflow (policy-optimized)
Task 1: $0.001  (Gemini - cost goal)
Task 2: $0.002  (Gemini - cost goal)
Task 3: $0.001  (Gemini - cost goal)
Total: $0.004  (91% savings!)

Debug Your Costs:

# See why each provider was selected
ax providers trace

# View provider metadata and pricing
ax providers info gemini-cli
# Shows: Cost, latency, reliability, features

# List providers sorted by cost
ax providers list --sort cost

🧠 Persistent Memory: Context That Never Expires

AutomatosX never forgets. Every conversation, decision, and piece of code is automatically indexed in a local SQLite database with full-text search. Future tasks get perfect context automatically.

The Problem with Traditional AI

# Day 1: Design a calculator
codex "Design a calculator with add/subtract"
# → Response: [Calculator design]

# Day 2: Implement it (context lost!)
codex "Implement the calculator"
# → Error: "What calculator? Please provide context."
# → You waste time and money re-explaining

AutomatosX Solution

# Day 1: Design
ax run product "Design a calculator with add/subtract"
# → Automatically saved to memory

# Day 2: Implement (context auto-injected!)
ax run backend "Implement the calculator"
# → Memory finds "calculator" design from Day 1
# → Backend agent gets full context automatically
# → Zero context repetition, zero wasted tokens

Memory Features

• Speed: < 1ms search with SQLite FTS5
• Cost: $0 (no embedding APIs)
• Privacy: 100% local (data never leaves your machine)
• Search: ax memory search "calculator"
• Export: ax memory export > backup.json

🤝 Multi-Agent Orchestration

Stop micromanaging AI. Give a high-level goal to one agent, and AutomatosX creates a plan, delegates tasks, and orchestrates a team of specialists.

How It Works

# 1. Give a high-level goal
ax run product "Build complete user authentication"

# 2. Product agent analyzes and delegates
# Output:
# "I'll design auth with JWT and OAuth2.
#
#  @backend Please implement the JWT authentication API.
#  @security Please audit the implementation for vulnerabilities.
#  @quality Please write integration tests."

# 3. AutomatosX executes automatically
#    - Backend implements API
#    - Security audits code
#    - Quality writes tests
#    - All in parallel, all with full context

23 Specialized Agents

Each agent is an expert in their domain:

See all 23 agents | Create custom agents

🏗️ Architecture: How It All Fits Together

┌─────────────────────────────────────────────────────────────┐
│  1. YAML Spec (workflow.ax.yaml)                           │
│     • Define actors, policy, constraints                    │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  2. Spec-Kit Generation (ax gen)                           │
│     • Plan: Cost estimates, resource requirements, risks    │
│     • DAG: Dependency graph with change detection hash      │
│     • Scaffold: Complete project structure                  │
│     • Tests: Unit, integration, E2E with policy assertions  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  3. Policy Evaluation (PolicyEvaluator)                     │
│     • Filter providers by constraints (cost, latency,       │
│       privacy, reliability)                                 │
│     • Score providers by optimization weights               │
│     • Select optimal provider                               │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  4. Router Execution (Router)                               │
│     • Load providers in policy order                        │
│     • Execute with selected provider                        │
│     • Fallback on failure                                   │
│     • Log all decisions to trace file                       │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  5. Memory & Context (MemoryManager)                        │
│     • Index: Save response to SQLite FTS5                   │
│     • Retrieve: Search < 1ms for future tasks               │
│     • Inject: Auto-add context to prompts                   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  6. Observability (RouterTraceLogger)                       │
│     • Log: JSONL trace to .automatosx/logs/                │
│     • View: ax providers trace --follow                     │
│     • Debug: Complete visibility into all decisions         │
└─────────────────────────────────────────────────────────────┘

📚 Real-World Examples

Example 1: E-Commerce Checkout System

# checkout.ax.yaml
metadata:
  id: ecommerce-checkout
  name: E-Commerce Checkout System

policy:
  goal: balanced  # Balance cost, speed, reliability
  constraints:
    cost:
      maxPerRequest: 0.02
      maxDaily: 2.00
    latency:
      p95: 3000

actors:
  - id: backend
    agent: backend
    description: Implement Stripe integration and inventory management

  - id: security
    agent: security
    description: Implement fraud detection and PCI compliance checks

  - id: quality
    agent: quality
    description: E2E tests for checkout flow with Stripe test mode

# Generate and execute
ax gen plan checkout.ax.yaml    # See cost: $0.012-$0.018
ax gen scaffold checkout.ax.yaml # Create project structure
ax gen tests checkout.ax.yaml    # Generate test suite
ax run checkout.ax.yaml          # Execute with cost optimization

# Result:
#   - Complete Stripe integration
#   - Fraud detection system
#   - PCI compliant
#   - 60%+ test coverage
#   - Total cost: $0.015 (vs $0.20 with Claude)

Example 2: Microservices API

# Natural language workflow
ax spec create "Build microservices API with user service, auth service, API gateway, and Docker deployment"

# AutomatosX generates:
#   - Service architecture design
#   - Three microservices in parallel
#   - API gateway with rate limiting
#   - Docker compose configuration
#   - Integration tests
#   - Documentation

# Execute with policy routing
ax run workflow.ax.yaml

# Monitor costs and decisions
ax providers trace --follow

🎨 Advanced Features

Parallel Execution

# Execute tasks in parallel for 3-5x speedup
ax spec run --parallel

# AutomatosX automatically:
#   - Builds dependency graph
#   - Runs independent tasks concurrently
#   - Waits for dependencies before starting
#   - Aggregates results

Checkpoints & Resume

# Long-running workflows save checkpoints
ax spec run --resumable

# Interrupt anytime (Ctrl+C)
# Resume from last checkpoint
ax resume <run-id>

# List all runs
ax runs list

Cost Tracking

# View costs by provider
ax cost

# View costs by time period
ax cost --period daily
ax cost --period weekly
ax cost --period monthly

# View costs by agent
ax cost --agent backend

Change Detection

# Generate DAG with hash
ax gen dag workflow.ax.yaml -o dag.json

# DAG stores spec hash for change detection
# If spec changes, AutomatosX warns you before execution
ax run dag.json
# → Warning: Spec has changed. Regenerate DAG? (Y/n)

📖 Documentation

Getting Started

• Quick Start Guide - Get running in 5 minutes
• Installation - Detailed installation instructions
• Configuration - Configure providers and settings

Core Features

• Spec-Kit Integration - Complete workflow automation
• Policy-Driven Routing - Cost/latency optimization
• Persistent Memory - Context management
• Multi-Agent Orchestration - Team coordination

Advanced

• Custom Agents - Create your own specialists
• Provider Configuration - Add AI providers
• Trace Debugging - Debug with trace logs
• Cost Optimization - Maximize savings

Reference

• Agent Directory - All 23 agents
• CLI Reference - All commands
• YAML Spec Reference - Complete spec format
• API Documentation - TypeScript API

🏆 Why AutomatosX Wins

Bottom Line: AutomatosX is the only platform that combines declarative workflows, cost optimization, persistent memory, and multi-agent orchestration in one tool.

🚦 Production Readiness

✅ 87.5% Complete - Spec-Kit integration production ready ✅ 2,458 Tests Passing - Comprehensive test coverage ✅ TypeScript Strict Mode - Type-safe codebase ✅ Zero Resource Leaks - Clean shutdown guaranteed ✅ Cross-Platform - macOS, Windows, Ubuntu ✅ Local-First - No cloud dependencies, 100% private

💻 Installation

NPM (Recommended)

npm install -g @defai.digital/automatosx
ax --version  # v6.0.1

Requirements

• Node.js: >= 20.0.0
• AI Providers: At least one:
  • Gemini CLI (recommended - cheapest)
  • OpenAI Codex (fastest)
  • Claude Code (most capable)

➡️ Full Installation Guide

🗺️ Roadmap

Completed (v6.0.0 - v6.0.1)

• ✅ Spec-Kit Integration (87.5%)
  • ✅ Plan generation
  • ✅ DAG generation
  • ✅ Scaffold generation
  • ✅ Test generation
• ✅ Policy-Driven Routing
  • ✅ Cost/latency/privacy constraints
  • ✅ Provider metadata registry
  • ✅ Multi-factor scoring
• ✅ Router Trace Logging
  • ✅ JSONL format
  • ✅ Real-time following
  • ✅ Color-coded CLI

Coming Soon (v6.1.0)

• ⏳ Regeneration Detector
  • Automatic spec change detection
  • Regeneration prompts
• ⏳ Cost-Aware Router
  • Pre-execution cost warnings
  • Budget protection
• ⏳ Enhanced Parallel Execution
  • Resource-aware scheduling
  • Priority-based execution

View Full Roadmap

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repo
git clone https://github.com/defai-digital/automatosx.git
cd automatosx

# Install dependencies
npm install

# Run in dev mode
npm run dev -- run backend "test task"

# Run tests
npm test

# Run type checking
npm run typecheck

# Build
npm run build

📄 License

Apache 2.0 - See LICENSE for details.

🌟 Star Us on GitHub

If AutomatosX saves you time and money, give us a star! ⭐

⭐ Star on GitHub

📧 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@defai.digital
• Twitter: @defai_digital

🎯 TL;DR

# Install
npm i -g @defai.digital/automatosx

# Create workflow from natural language
ax spec create "Build auth system with API, tests, security audit"

# Execute with cost optimization
ax run workflow.ax.yaml  # 60-80% cheaper than Claude/GPT

# Debug with trace logs
ax providers trace --follow

# Result: Production-ready auth system in minutes

AutomatosX: The only AI platform with declarative workflows, cost optimization, persistent memory, and multi-agent orchestration.

Try it now: npm i -g @defai.digital/automatosx

Made with ❤️ by DeFAI Digital