AutomatosX

Production-ready code intelligence platform with AI agents and workflow orchestration

🎉 v8.0.10 - Ready for npm Publishing (No Warnings)

AutomatosX is a comprehensive code intelligence platform with AI-powered workflow automation:

• Code Intelligence - Tree-sitter AST parsing with SQLite FTS5 search for 44 languages
• AI Agent System - 21 specialized agents for development tasks
• Multi-Provider AI - Claude, Gemini, and OpenAI with automatic fallback
• Workflow Orchestration - ReScript state machines for complex multi-step tasks
• Interactive CLI - ChatGPT-style REPL with natural language interface
• SpecKit Generators - Auto-generate workflows, plans, tests, and project scaffolds
• Iterate Mode - Autonomous retry loops with 10 adaptive strategies
• Validation System - Production-ready type-safe validation (488k ops/sec)

📋 Requirements

• Node.js: v24.x or higher (Download)
• pnpm: v9.0.0 or higher (Install instructions)
• Supported Operating Systems:
  • Ubuntu: 24.04 LTS (Noble Numbat) or later
  • macOS: 26 (Tahoe) or later
  • Windows: 11 or later

Installing pnpm

# Via npm (recommended)
npm install -g pnpm@9

# Via Homebrew (macOS)
brew install pnpm

# Via winget (Windows)
winget install -e --id pnpm.pnpm

# Verify installation
pnpm --version  # Should show 9.x.x

Why pnpm? This project uses pnpm (not npm) because:

• ✅ Better monorepo/workspace support
• ✅ 2-3x faster installations
• ✅ Smaller disk usage (40% reduction)
• ✅ Stricter dependency resolution

See INSTALLATION.md for detailed setup instructions.

🚀 Quick Start (Development)

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

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Link CLI binary (makes 'ax' command available globally)
pnpm run link

# Now you can use the CLI directly:
ax find "getUserById"
ax cli  # Launch interactive mode
ax speckit spec "Build authentication API"

# Or use via npm script:
npm run cli -- find "getUserById"

# Run tests (745+ tests)
npm test

Using the ax Command

After npm install and npm run build, the ax binary is automatically linked globally via the postinstall script. This means you can use:

# These work anywhere on your system:
ax find "Calculator"
ax def "getUserById"
ax flow "handleRequest"
ax cli  # Interactive ChatGPT-style mode

To unlink (if you want to remove the global ax command):

npm run unlink
# Or manually:
npm unlink -g @defai.digital/automatosx

📦 Installation

For End Users (Recommended)

Install globally with npm:

npm install -g @defai.digital/automatosx

# Verify installation
ax --version

# Use the CLI
ax find "getUserById"
ax cli  # Launch interactive mode

For Developers

Clone and build from source:

git clone https://github.com/defai-digital/automatosx.git
cd automatosx
npm install
npm run build
npm link

⚠️ Installation Warnings

Peer Dependency Warnings

When installing AutomatosX, you may see warnings about tree-sitter peer dependencies:

WARN  Issues with peer dependencies found
├─┬ tree-sitter-c 0.24.1
│ └── ✕ unmet peer tree-sitter@^0.22.4: found 0.25.0

These warnings are harmless and can be safely ignored. AutomatosX uses tree-sitter v0.25.0 (latest), while some language parser packages haven't updated their peer dependencies yet. Everything works correctly.

pnpm Build Scripts Warning (pnpm v10+ users)

cp .npmrc.example .npmrc

See [INSTALLATION.md](./INSTALLATION.md#peer-dependency-warnings) for details.

---

See [CLAUDE.md](./CLAUDE.md) for detailed development guide.

## ✨ Core Features

### 1. Code Intelligence Engine
- 🔍 **Multi-language search** - 44 languages including TypeScript, Python, Go, Rust, Java, C++
- ⚡ **Lightning fast** - Query caching delivers 10-100x speedup (<1ms cached, <5ms uncached)
- 🎯 **Advanced filtering** - Filter by language, symbol kind, or file path
- 📊 **Smart indexing** - Batch operations process 2000+ files/sec

### 2. AI Agent System (21 Specialized Agents)
- 🤖 **Engineering Agents** - Backend, Frontend, DevOps, Security, Quality, Testing, Performance, Architecture
- 🔧 **Technical Specialists** - API, Database, Data, DataScience, Mobile, Infrastructure, Standards
- 👔 **Leadership Agents** - Product, CTO, CEO, Writer, Researcher, Community
- 🔄 **Collaboration** - Agent-to-agent delegation and task coordination

### 3. Multi-Provider AI Integration
- 🌐 **Three Providers** - Claude (Anthropic), Gemini (Google), OpenAI
- 🔄 **Automatic Fallback** - Seamless failover with retry logic
- 📊 **Health Monitoring** - Real-time latency and error rate tracking
- ⚙️ **Smart Routing** - Priority-based provider selection

### 4. Workflow Orchestration
- 📋 **YAML/JSON Workflows** - Define complex multi-step processes
- 🔗 **Dependency Management** - Automatic topological sorting and parallel execution
- 💾 **Checkpoint/Resume** - Resume long-running workflows from any point
- 🎯 **ReScript State Machines** - Deterministic execution with type safety

### 5. Interactive CLI Mode ⭐ NEW
- 💬 **ChatGPT-style REPL** - Natural language conversations with AI
- ⚡ **15+ slash commands** - `/agent`, `/workflow`, `/memory`, `/history`, `/save`
- 🎨 **Rich UX** - Syntax highlighting, table formatting, progress indicators
- 💾 **Auto-save** - Persistent conversations in SQLite
- 🔄 **Context-aware** - Pronoun resolution and conversation memory

### 6. SpecKit Auto-Generation ⭐ NEW
- 📝 **Spec Generator** - Natural language → YAML workflows (AI-powered)
- 📊 **Plan Generator** - Execution plans with cost/time estimates
- 🌐 **DAG Generator** - Dependency graphs (ASCII/DOT/Mermaid)
- 🏗️ **Scaffold Generator** - Project structure generation
- 🧪 **Test Generator** - Unit, integration, E2E test suites
- 📚 **ADR/PRD Generators** - Architecture decisions and product requirements

### 7. Iterate Mode ⭐ NEW
- 🔄 **Autonomous Retry** - Intelligent retry loops (max 10 iterations)
- 🎯 **10 Strategies** - Timeout, fallback, parallel, circuit breaker, etc.
- 🛡️ **Safety Levels** - Paranoid, normal, permissive with cost/time limits
- 📊 **Telemetry** - Strategy analytics and recommendations
- 🔍 **Error Analysis** - Classify and detect patterns (9 error types)

### 8. Natural Language Interface ⭐ NEW
- 🗣️ **Natural Commands** - `ax "run security audit"` → workflow execution
- 🎯 **40+ Intent Patterns** - Pattern matching + LLM fallback
- 🔍 **Entity Extraction** - Files, agents, filters, limits
- ❓ **Clarification** - Interactive prompts for ambiguous queries
- 📚 **Learning System** - Learns from user corrections

### 9. Validation System ⭐ NEW
- ✅ **Type-safe Validation** - Zod v4 with 20 schemas
- ⚡ **Ultra-fast** - 488k ops/sec, <0.01ms per operation
- 🎛️ **Feature Flags** - Disabled, log-only, enforce modes
- 📊 **Metrics** - Success rate, latency (P50/P95/P99)
- 🔄 **Sampling** - Gradual rollout (0-100%)
- 🛡️ **Production-ready** - 213 tests passing, deployment scripts

## 🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐ │ Application Layer │ │ CLI • Web UI • LSP Server • VS Code Extension │ └───────────────┬─────────────────────────────────────────────┘ │ ┌───────────┴───────────┬─────────────────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ Workflow │ │ Agent │ │ Code │ │ Engine │──│ System │──│ Intelligence │ │ (Orchestration) │ │ (21 Agents) │ │ (45 Languages) │ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │ │ │ └─────────────────────┴──────────────────────┘ │ ┌─────────────┴──────────────┐ │ │ ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ │ Provider Router │ │ ReScript Core │ │ (Multi-AI) │ │ (State Machines)│ └──────────────────┘ └──────────────────┘ │ │ └─────────────┬──────────────┘ │ ▼ ┌──────────────────┐ │ SQLite Database │ │ (FTS5 + Vector) │ └──────────────────┘

## 🎯 Example Use Cases

### 1. Multi-Agent Code Review
```typescript
// Security, Quality, and Architecture agents collaborate
const runtime = new AgentRuntime(registry, router, db);

await runtime.executeTask({
  type: 'code-review',
  description: 'Comprehensive security and quality review',
  context: { repositoryPath: './src' },
});

2. CI/CD Pipeline Workflow

# workflows/cicd-pipeline.yaml
name: cicd-pipeline
steps:
  - key: security-scan
    agent: security
  - key: run-tests
    agent: testing
    dependsOn: [security-scan]
  - key: deploy
    agent: devops
    dependsOn: [run-tests]

ax workflow execute workflows/cicd-pipeline.yaml

3. Provider Fallback

// Automatically tries Claude → Gemini → OpenAI
const router = new ProviderRouterV2({
  providers: {
    claude: { enabled: true, priority: 1 },
    gemini: { enabled: true, priority: 2 },
    openai: { enabled: true, priority: 3 }
  }
});

const response = await router.request({
  messages: [{ role: 'user', content: 'Explain this code' }]
});

💬 Interactive CLI Mode

AutomatosX includes a ChatGPT-style Interactive CLI for natural language conversations with AI assistants.

Quick Start

# Launch Interactive CLI
ax cli

# Set an agent for specialized help
> /agent BackendAgent

# Ask questions naturally
> how do I implement rate limiting in Express?

# Run workflows
> /workflow run code-review

# Save your session
> /save my-session.json

Features

• 🤖 Natural language conversations with Claude, Gemini, and OpenAI
• ⚡ 13 slash commands for system control and automation
• 💾 Auto-save conversations to SQLite (every 5 messages + on exit)
• 🎯 Agent collaboration with 21 specialized AI personas
• 🔄 Workflow integration for automated development tasks
• ⌨️ Tab autocomplete and command history navigation
• 🎨 Professional UX with color-coded output and loading indicators

Interactive Commands

Example Session

> /agent BackendAgent
✓ Active agent set to: BackendAgent

> how do I implement database connection pooling in Express?

BackendAgent: For Express database connection pooling, I recommend using pg-pool
for PostgreSQL or mysql2 pool for MySQL. Here's a complete example:

[provides detailed code example with connection pool setup]

> what about error handling?

BackendAgent: Good question! For robust error handling with connection pools:

1. Always use try-catch with async/await
2. Implement retry logic for transient errors
3. Set proper timeout values
4. Monitor pool metrics

[provides error handling code examples]

> /save express-db-pooling-session.json
✓ Conversation exported to: express-db-pooling-session.json

> /exit
Saving conversation to database...
✓ Conversation saved
👋 Exiting... Goodbye!

Full Interactive CLI Documentation →

🎨 System Capabilities

Code Intelligence

• 🔍 Multi-language search - Natural language and symbol queries
• 🎯 Advanced filtering - Filter by language, kind, file patterns
• 📊 Smart indexing - Incremental updates, batch processing
• 🌐 Complete ecosystem coverage - DevOps, Messaging, Frontend, Backend, Mobile, ML
• 🎨 Professional UX - Color-coded output, progress indicators, helpful errors
• ⚙️ Flexible configuration - Hierarchical config with environment variables
• 🧪 Production quality - 165 tests passing, 85%+ coverage, zero known bugs

🌍 Supported Languages (45)

Systems & Performance

C, C++, Rust, Go, Zig, Objective-C, AssemblyScript, CUDA (NVIDIA/AMD ROCm HIP)

Frontend & Mobile

TypeScript, JavaScript, HTML, Swift, Kotlin, Dart (Flutter)

Backend & Scripting

Python, Ruby, PHP, Java, Scala, C#, Bash, Zsh, Lua, Groovy, Perl

Functional Programming

Haskell, OCaml, Elm, Elixir, Gleam

Data & Config

SQL, JSON, YAML, TOML, Markdown, CSV

DevOps & Infrastructure

HCL (Terraform), Puppet, Makefile

Messaging & RPC

Thrift (Apache Thrift IDL)

Specialized

Solidity (Ethereum), Verilog, SystemVerilog, Julia, MATLAB, Regex

🚀 Quick Start

Installation

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

# Or use npx (no installation required)
npx @defai.digital/automatosx@latest <command>

Basic Usage

# Index your codebase
ax index ./src

# Search for code
ax find "getUserById"

# Search with filters
ax find "lang:python authentication"

# Find symbol definition
ax def getUserById

# Show index statistics
ax status

📚 Commands

Code Intelligence Commands

Interactive & Natural Language Commands ⭐ NEW

SpecKit Generator Commands ⭐ NEW

Workflow & Agent Commands

🔎 Query Syntax

Natural Language Search

ax find "function that validates email addresses"
ax find "class for user authentication"

Symbol Search

ax find getUserById
ax find UserService

Language Filters

ax find "lang:python authentication"      # Python files only
ax find "lang:typescript getUserById"     # TypeScript files only
ax find "-lang:test handleUser"           # Exclude test files

Kind Filters

ax find "kind:function getUserById"       # Functions only
ax find "kind:class User"                 # Classes only
ax find "-kind:constant MAX_USERS"        # Exclude constants

File Path Filters

ax find "file:src/auth/ login"            # Files in src/auth/
ax find "file:*.ts getUserById"           # TypeScript files only
ax find "-file:*.spec.ts handleUser"      # Exclude spec files

Combining Filters

ax find "lang:python kind:function file:src/ authentication"

⚙️ Configuration

Create automatosx.config.json in your project root:

{
  "languages": {
    "typescript": { "enabled": true },
    "javascript": { "enabled": true },
    "python": { "enabled": true }
  },
  "search": {
    "defaultLimit": 10,
    "maxLimit": 100
  },
  "indexing": {
    "excludePatterns": [
      "**/node_modules/**",
      "**/.git/**",
      "**/dist/**",
      "**/build/**"
    ],
    "maxFileSize": 1048576
  },
  "database": {
    "path": ".automatosx/db/code-intelligence.db"
  },
  "performance": {
    "enableCache": true,
    "cacheMaxSize": 1000,
    "cacheTTL": 300000
  }
}

Environment Variables

Override config values with environment variables:

export AUTOMATOSX_SEARCH_DEFAULT_LIMIT=25
export AUTOMATOSX_DATABASE_WAL=false
export AUTOMATOSX_INDEXING_EXCLUDE_PATTERNS='["**/test/**"]'

📈 Performance

AutomatosX v8.0.0 delivers exceptional performance across all systems:

Performance Tips

1. Use caching - Repeated queries are 10-100x faster
2. Filter early - Use lang:, kind:, file: to narrow results
3. Batch index - Index entire directory at once for best performance
4. Watch mode - Use for active development to keep index updated
5. Monitor cache - Check hit rate with ax status -v

🏗️ Architecture

AutomatosX uses a multi-layer architecture:

┌─────────────────────────────────────┐
│         CLI Layer (Commander)        │
│  (Commands, Args, Output Formatting) │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│      Service Layer (TypeScript)      │
│ (FileService, ConfigLoader, Caching) │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│    Parser Layer (Tree-sitter)        │
│  (TS/JS/Python AST → Symbol Extract) │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│    Database Layer (SQLite FTS5)      │
│ (Files, Symbols, Chunks, Full-Text)  │
└──────────────────────────────────────┘

Key Components:

• Parser Layer: Tree-sitter for AST parsing (44 languages: TypeScript, Python, Go, Rust, Java, C++, and 38 more)
• Database Layer: SQLite with FTS5 for full-text search and BM25 ranking
• Service Layer: FileService orchestrates indexing and search
• Query Router: Intelligent query intent detection (symbol vs natural language)
• Cache Layer: LRU cache with TTL for query result caching
• Configuration: Zod-based validation with hierarchical loading

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test FileService

Test Statistics v8.0.0:

• Total tests: 745+
• Pass rate: 100%
• Coverage: 85%+
• Test categories:
  • Core: 165 tests (Parser, DAO, Service, Cache, Config, CLI)
  • SpecKit: 171 tests (5 generators + utilities)
  • Validation: 213 tests (ADR-014 system)
  • Iterate Mode: 103 tests (strategies, safety, analysis)
  • Natural Language: 30 tests (intent, routing, clarification)
  • ReScript Core: 50 tests (state machines, workflow)
  • Additional: 13+ tests (LSP, Web UI, integrations)

🛠️ Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Build CLI
npm run build:cli

# Run CLI locally
npm run cli -- find "query"

# Run tests
npm test

# Clean build artifacts
npm run clean

📖 Documentation

• P1 Final Action Plan - Comprehensive implementation plan
• CHANGELOG - Version history and release notes
• API Quick Reference - Command reference and examples

🗺️ Roadmap

v8.0.0 (Current - ✅ Complete)

• ✅ 45 programming languages supported
• ✅ 21 specialized AI agents
• ✅ Multi-provider AI (Claude, Gemini, OpenAI)
• ✅ Interactive CLI with natural language interface
• ✅ SpecKit auto-generation (5 generators)
• ✅ Iterate Mode with 10 strategies
• ✅ Validation system (ADR-014)
• ✅ 745+ tests passing (100%)

v8.1.0 (Next - 4-6 weeks)

• API Spec Generator (OpenAPI/Swagger)
• Configuration validation (remaining 12.5% gap)
• Streaming validation for large files
• Custom error messages per validation rule
• User documentation and migration guides
• Performance optimizations

v8.2.0 (Future - 8-12 weeks)

• Automated rollback on high error rates
• Advanced metrics (histograms, time-series)
• Workflow templates library
• Custom strategy plugins
• Multilingual support (i18n)
• Enhanced Web UI dashboard

v9.0.0 (Long-term)

• ML semantic search with hybrid BM25+semantic scoring
• Cross-project search
• Enhanced LSP features
• Protocol Buffers (.proto) support
• Desktop application
• Collaborative workflows
• Enterprise SSO/RBAC

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

📄 License

Apache License 2.0 - Copyright 2025 DEFAI Private Limited

AutomatosX is licensed under the Apache License 2.0. See LICENSE for the full license text.

Commercial Usage

The codebase is Apache 2.0 licensed, free for:

• ✅ Research and academic use
• ✅ Personal use and learning
• ✅ Startups and small businesses (under $2M annual revenue/funding)

Commercial license required for:

• ❌ Enterprises with $2M+ annual revenue or funding
• ❌ Competitive use with DEFAI's commercial API offerings
• ❌ Offering AutomatosX as a managed service or SaaS
• ❌ Embedding in commercial products for distribution

For commercial licensing: Visit https://license.defai.digital/automatox

See COMMERCIAL-LICENSE.md for detailed terms and FAQs.

🙏 Acknowledgments

Built with:

• Tree-sitter - Incremental parsing system
• SQLite - Embedded database with FTS5
• Zod - TypeScript-first schema validation
• Commander.js - CLI framework
• Chalk - Terminal string styling

AutomatosX.0.0 - Production-ready code intelligence

Copyright 2025 DEFAI Private Limited | Apache License 2.0

Made with ❤️ by DEFAI Private Limited