Repository homepage: the canonical entry for stars and forks is the root README.md. Stats sync: intro copy, badges, aggregate tables, and footer counts must match the root README and docs/reference/inventory.md (refresh via uv run python scripts/doc_inventory.py and pytest --collect-only as documented there).

🐜 Codomyrmex

AI-Native Modular Coding Workspace

Modular, agentic Python workspace for software engineering, personal AI infrastructure, and multi-agent orchestration.

Codomyrmex is a production-grade library of 128 top-level modules under src/codomyrmex/ spanning AI agents, cloud infrastructure, security, finance, multimedia, and more — all built on a strict Zero-Mock testing policy ensuring every method is real, tested, documented, and functional. The ecosystem exposes 600 production @mcp_tool lines in Python sources for Claude, Gemini, GPT, and any Model Context Protocol client (docs/reference/inventory.md). It includes 3,000+ Python files, 34,334 collected tests (uv run pytest src/codomyrmex/tests/ --collect-only -q --no-header --override-ini='addopts=' --import-mode=importlib), 1,164 markdown files under docs/ (recursive; see inventory), and 37 GitHub Actions workflows.

# Install
git clone https://github.com/docxology/codomyrmex.git && cd codomyrmex
uv sync --all-groups

# Verify
uv run codomyrmex doctor --all

📋 Table of Contents

• Documentation Hub
• System Architecture
• Module Inventory
• Module Dependency Architecture
• Agent Orchestration Pipeline
• Project Structure
• Aggregate Statistics
• LLM Provider Matrix
• Agent Dispatch Architecture
• Testing Philosophy
• Configuration Architecture
• Personal AI Dashboard
• Quick Start
• Documentation Standards
• GitHub Actions Workflows
• License

✨ Why Codomyrmex?

📚 Documentation Hub

Top-Level Documents

Documentation Directories

📐 System Architecture

graph TB
    subgraph Core["🧠 Core Intelligence"]
        LLM["LLM Subsystem"]
        Agents["Agent Framework"]
        Cerebrum["Cerebrum Reasoning"]
        Orchestrator["Orchestrator"]
        MCP["Model Context Protocol"]
    end

    subgraph AI["🤖 AI & ML"]
        EvolutionaryAI["Evolutionary AI"]
        GraphRAG["Graph RAG"]
        PromptEng["Prompt Engineering"]
        VectorStore["Vector Store"]
        Coding["Coding Agents"]
        Skills["Skills Engine"]
    end

    subgraph Infra["☁️ Infrastructure"]
        Cloud["Cloud (AWS/GCP/Azure)"]
        Containerization["Containerization"]
        CICD["CI/CD Automation"]
        Deployment["Deployment"]
        EdgeComputing["Edge Computing"]
        Networking["Networking"]
    end

    subgraph Data["💾 Data & Storage"]
        DB["Database Management"]
        Cache["Cache Layer"]
        DataLineage["Data Lineage"]
        Serialization["Serialization"]
        Documents["Documents"]
        FeatureStore["Feature Store"]
    end

    subgraph Security["🔒 Security"]
        Auth["Authentication"]
        Crypto["Cryptography"]
        Encryption["Encryption"]
        Privacy["Privacy"]
        Defense["Defense"]
        Identity["Identity"]
    end

    subgraph Media["🎨 Multimedia"]
        Audio["Audio"]
        Video["Video"]
        Multimodal["Multimodal"]
        DataViz["Data Visualization"]
        Meme["Meme Generator"]
    end

    subgraph PAI["🏠 Personal AI"]
        Email["Email"]
        Calendar["Calendar"]
        Finance["Finance"]
        Wallet["Wallet"]
        Website["Website"]
        PAIDash["PAI Dashboard"]
    end

    subgraph DevTools["🛠️ Developer Tools"]
        CLI["CLI"]
        IDE["IDE Integration"]
        GitOps["Git Operations"]
        GitAnalysis["Git Analysis"]
        TreeSitter["Tree-sitter"]
        StaticAnalysis["Static Analysis"]
        Terminal["Terminal Interface"]
    end

    Core --> AI
    Core --> Infra
    Core --> Data
    Core --> Security
    Core --> Media
    Core --> PAI
    Core --> DevTools

    LLM --> Agents
    Agents --> Orchestrator
    Orchestrator --> MCP
    MCP --> Skills

🗂️ Complete Module Inventory

Every module links directly to its source, docs, config, and scripts directories.
128 top-level modules across 10 capability layers — from foundation utilities to ML training primitives.

🧠 Core Intelligence Modules

🤖 AI & Machine Learning Modules

☁️ Infrastructure & DevOps Modules

💾 Data & Storage Modules

🔒 Security & Identity Modules

🎨 Multimedia & Visualization Modules

🏠 Personal AI (PAI) Modules

🛠️ Developer Tooling Modules

⚙️ Configuration & Operations Modules

🧩 Framework & Utility Modules

🧬 ML Training & Optimization Modules

🔗 Data Pipeline & Infrastructure Modules

🧩 Specialized Modules

🔬 Module Dependency Architecture

graph LR
    subgraph Foundation["Foundation Layer"]
        Utils["utils"]
        Exceptions["exceptions"]
        Events["events"]
        Validation["validation"]
        Config["config_management"]
    end

    subgraph DataLayer["Data Layer"]
        DB["database_management"]
        Cache["cache"]
        Serial["serialization"]
        Docs["documents"]
        Memory["agentic_memory"]
    end

    subgraph AILayer["AI Layer"]
        LLM["llm"]
        Agents["agents"]
        Cerebrum["cerebrum"]
        RAG["graph_rag"]
        VS["vector_store"]
        PE["prompt_engineering"]
    end

    subgraph InfraLayer["Infrastructure Layer"]
        Cloud["cloud"]
        Container["containerization"]
        Deploy["deployment"]
        CICD["ci_cd_automation"]
        Net["networking"]
    end

    subgraph SecurityLayer["Security Layer"]
        Auth["auth"]
        Crypto["crypto"]
        Encrypt["encryption"]
        Identity["identity"]
        Privacy["privacy"]
    end

    subgraph AppLayer["Application Layer"]
        Orch["orchestrator"]
        MCP["model_context_protocol"]
        CLI["cli"]
        Website["website"]
        PAI["email + calendar"]
    end

    Foundation --> DataLayer
    Foundation --> SecurityLayer
    DataLayer --> AILayer
    SecurityLayer --> AILayer
    AILayer --> AppLayer
    InfraLayer --> AppLayer
    DataLayer --> InfraLayer

🚀 Agent Orchestration Pipeline

sequenceDiagram
    participant User
    participant CLI
    participant Orchestrator
    participant MCP as MCP Server
    participant Agents
    participant LLM as LLM Provider
    participant Tools

    User->>CLI: codomyrmex run --task "analyze codebase"
    CLI->>Orchestrator: Create workflow
    Orchestrator->>MCP: Register available tools
    MCP->>Tools: Discover ~600 tools (128 top-level modules)
    Orchestrator->>Agents: Dispatch agent
    Agents->>LLM: Generate completion (Gemini 2.5 Pro)
    LLM-->>Agents: Response + tool calls
    Agents->>MCP: Execute tool calls
    MCP->>Tools: Run git_analysis, static_analysis, etc.
    Tools-->>MCP: Results
    MCP-->>Agents: Tool outputs
    Agents-->>Orchestrator: Completed task
    Orchestrator-->>CLI: Display results
    CLI-->>User: Formatted output

🏗️ Project Structure

codomyrmex/
├── .github/                  # 37 GitHub Actions workflows, templates, docs
├── config/                   # 128 module-specific config.yaml files
├── docs/                     # 1,164 markdown files (recursive); see inventory
│   ├── ARCHITECTURE.md       # System architecture
│   ├── AGENTS.md             # Agent coordination
│   ├── SPEC.md               # Technical specification
│   ├── PAI.md                # Personal AI reference
│   ├── PAI_DASHBOARD.md      # PAI dashboard reference
│   ├── index.md              # MkDocs site index
│   ├── getting-started/      # 9 quick-start docs
│   ├── development/          # 10 dev guides
│   ├── modules/              # Per-module doc directories (see inventory for counts)
│   ├── security/             # 11 security guides
│   ├── agi/                  # 14 AGI theory docs
│   └── ... (18 directories)
├── scripts/                  # 445+ orchestrator scripts
│   ├── agents/               # Jules batch dispatch, harvester
│   ├── maintenance/          # Config generation, health checks
│   └── ... (90+ module scripts)
├── src/codomyrmex/           # Main source (128 modules)
│   ├── agents/               # 168 files
│   ├── llm/                  # 41 files
│   ├── security/             # 47 files
│   ├── tests/                # 1,023+ test files (zero-mock)
│   └── ... (122 more modules)
├── CHANGELOG.md              # Release history
├── CITATION.cff              # Citation metadata
└── pyproject.toml            # uv-managed project config (uv_build backend)

📊 Aggregate Statistics

🔌 LLM Provider Matrix

🤖 Agent Dispatch Architecture

graph TD
    subgraph Dispatch["Agent Dispatch Layer"]
        Jules["Jules CLI v0.1.42"]
        GeminiCLI["Gemini CLI v0.22.5"]
        Claude["Claude Code"]
        Codex["Codex CLI"]
    end

    subgraph Orchestration["Orchestration"]
        BatchDispatch["jules_batch_dispatch.sh"]
        MegaSwarm["mega_swarm_dispatcher.py"]
        Harvester["mega_swarm_harvester.py"]
    end

    subgraph Targets["Target Modules - 126"]
        M1["agentic_memory"]
        M2["agents"]
        Mdots["..."]
        M95["website"]
    end

    MegaSwarm --> Jules
    BatchDispatch --> Jules
    Jules --> Targets
    GeminiCLI --> Targets
    Claude --> Targets
    Harvester --> Jules
    Harvester -->|"Pull and Apply"| Targets

🧪 Testing Philosophy

See docs/development/testing-strategy.md for the full guide.

graph LR
    subgraph Policy["Zero-Mock Policy"]
        direction TB
        R1["Real methods only"]
        R2["Real file I/O"]
        R3["Real network calls"]
        R5["No unittest.mock"]
        R6["No MagicMock"]
    end

    subgraph Layers["Test Layers"]
        Unit["Unit Tests - 800+ files"]
        Integration["Integration Tests"]
        E2E["End-to-End Validation"]
    end

    Policy --> Layers

# Run all tests
uv run pytest src/codomyrmex/tests/ -v --tb=short

# Run a specific module
uv run pytest src/codomyrmex/tests/unit/llm/ -v

# Lint and format
uv run ruff check .          # lint
uv run ruff format .         # format
uv run ty check src/         # type check

🗺️ Configuration Architecture

See config/ for all 128 module configurations.

graph TB
    subgraph ConfigRoot["config/"]
        C1["agents/config.yaml"]
        C2["llm/config.yaml"]
        C3["security/config.yaml"]
        Cdots["... 128 total"]
    end

    subgraph Scripts["scripts/"]
        S1["agents/orchestrator.py"]
        S2["llm/demo.py"]
        S3["security/audit.py"]
        Sdots["... 445+ scripts"]
    end

    subgraph Source["src/codomyrmex/"]
        Src1["agents/"]
        Src2["llm/"]
        Src3["security/"]
        SrcDots["..."]
    end

    C1 -.->|"YAML load"| S1
    C2 -.->|"YAML load"| S2
    C3 -.->|"YAML load"| S3
    S1 -->|"import"| Src1
    S2 -->|"import"| Src2
    S3 -->|"import"| Src3

🏠 Personal AI Dashboard

See docs/pai/ for the full PAI reference.

graph LR
    subgraph Dashboard["PAI Dashboard localhost:3000"]
        Overview["Overview Tab"]
        EmailTab["Email Tab"]
        CalendarTab["Calendar Tab"]
        SkillsTab["Skills Tab"]
        AgentsTab["Agents Tab"]
    end

    subgraph Backend["Backend Services"]
        Gmail["Gmail API"]
        GCal["Google Calendar API"]
        MCP2["MCP Tool Server"]
        AgentAPI["Agent Dispatch API"]
    end

    subgraph External["External Services"]
        Google["Google Workspace"]
        Jules2["Jules Agents"]
        Gemini["Gemini 2.5 Pro"]
    end

    Dashboard --> Backend
    Backend --> External

⚡ Quick Start

# 1. Clone
git clone https://github.com/docxology/codomyrmex.git && cd codomyrmex

# 2. Install (all dev dependencies via uv)
uv sync --all-groups

# 3. Configure environment
cp .env.example .env   # Add GEMINI_API_KEY, ANTHROPIC_API_KEY, etc.

# 4. Verify installation
uv run codomyrmex doctor --all

# 5. Explore
uv run codomyrmex --help
uv run codomyrmex modules        # List all top-level modules
uv run codomyrmex status         # Live system status

# 6. Run tests
uv run pytest src/codomyrmex/tests/ -v --tb=short

# 7. Lint & type-check
uv run ruff check . && uv run ruff format . && uv run ty check src/

# 8. Start PAI dashboard
uv run python scripts/pai/dashboard.py

# 9. Dispatch AI agents
uv run python scripts/agents/mega_swarm_dispatcher.py

New here? Start with the Quick Start Guide or dive into Agent Operations.

📋 Documentation Standards

Every module follows the RASP documentation pattern:

🏗️ .github/ Directory Overview

This directory powers the GitHub-hosted infrastructure for Codomyrmex.

Workflows (37 total)

Community & Configuration Files

🤝 Contributing

We welcome contributions! Please read CONTRIBUTING.md for standards, the Zero-Mock testing policy, PR workflow, and coding guidelines.

Key requirements:

• All tests must use real implementations (Zero-Mock policy — no unittest.mock or MagicMock)
• Coverage must not drop below the 40% gate in pyproject.toml ([tool.coverage.report] and pytest addopts)
• All new modules need README.md, AGENTS.md, SPEC.md, and PAI.md (RASP pattern)
• Run uv run ruff check . and uv run ty check src/ before submitting

📜 License

MIT License — see LICENSE for details.

Copyright © 2025–2026 The Codomyrmex Contributors (@docxology)

Built with 🐜 Codomyrmex — The Autonomous Software Colony
_{128 modules · 600 MCP tools · 34,334 tests · 1,164 docs · 37 workflows · Zero-Mock · Production-Grade}