Codomyrmex

Version: v1.0.0 | Status: Active | Last Updated: February 2026

A modular, extensible coding workspace designed for AI development workflows

Codomyrmex integrates tools for building, documenting, analyzing, executing, and visualizing code across multiple languages. Built with modularity and AI integration at its core, it provides a comprehensive platform for modern software development.

What is Codomyrmex?

Codomyrmex is a modular development platform that brings together 91 specialized modules for code analysis, AI-assisted development, build automation, documentation, and more. Each module is self-contained, well-tested, and can be used independently or composed together for complex workflows.

Key Features

🤖 AI-Powered Development - Built-in support for Large Language Models via Model Context Protocol (MCP)
🧩 Modular Architecture - 91 independent, composable modules with clear interfaces
🔍 Code Analysis - Static analysis, pattern matching, security scanning, and quality metrics
🏗️ Build & Deploy - Multi-language builds, CI/CD automation, container management
📊 Visualization - Data visualization, 3D/4D spatial modeling, and interactive plots
📚 Documentation - Automated documentation generation, API specs, and tutorials
🔒 Security First - Built-in security scanning, vulnerability detection, and compliance checking
🌐 Polyglot Support - Language-agnostic interfaces supporting Python, JavaScript, Go, Rust, Java
🕸️ Network Analysis - Graph algorithms and network modeling capabilities
🧪 Simulation - Agent-based modeling and system dynamics simulations

Why Codomyrmex?

Modularity First: Self-contained modules with clear boundaries - use what you need, when you need it
AI Integration: Seamless integration with LLMs through standardized Model Context Protocol
Professional Quality: Comprehensive testing (≥80% coverage), documentation, and security practices
Easy to Extend: Well-documented module system makes it simple to add new capabilities
Production Ready: Battle-tested modules with stable APIs and comprehensive error handling

Quick Start

Get started with Codomyrmex in minutes:

# Clone the repository
git clone https://github.com/docxology/codomyrmex.git
cd codomyrmex

# Install with uv (recommended)
uv sync

# Launch interactive shell
./start_here.sh

New to Codomyrmex? Start with the Quick Start Guide or explore executable examples.

Documentation Hub

Codomyrmex documentation is organized into focused guides for different needs:

🚀 Getting Started

Guide	Description
Quick Start	Get up and running in 5 minutes
Installation	Detailed installation instructions
Setup	Environment configuration
Tutorials	Step-by-step learning paths

🏗️ Architecture & Design

Guide	Description
Architecture	System design and principles
Module Overview	Understanding the module system
Contributing	How to contribute to Codomyrmex
Project Roadmap	Current priorities and future plans

💻 Development

Guide	Description
Environment Setup	Development environment configuration
Testing Strategy	Testing approach and best practices
Documentation Guide	Writing documentation
uv Usage Guide	Package management with uv

📚 Reference

Guide	Description
API Reference	Complete API documentation
CLI Reference	Command-line interface
Orchestrator	Workflow orchestration
Performance	Performance optimization
Troubleshooting	Common issues and solutions

🚢 Deployment & Operations

Guide	Description
Production Deployment	Production deployment guide
Security	Security best practices
Migration Guide	Upgrading between versions

🔌 Integration

Guide	Description
Integration Overview	External service integration
Examples	Working code examples
Project Orchestration	Multi-project workflows

AGENTS.md | Agent coordination protocols |
PAI.md | Personal AI Infrastructure |
SPEC.md | Functional specification |

📚 Examples & Tutorials

Codomyrmex provides comprehensive examples to help you get started quickly:

🛠️ Hands-on Examples

Basic Usage - Core module interactions
Advanced Workflows - Multi-module orchestration
Agent Demos - AI-assisted coding examples

📖 Documentation Examples

Orchestration Patterns - How to build complex pipelines
Integration Guides - Connecting to external services
Tutorial Series - Step-by-step learning paths

🧪 Executable Demos

Run these from the root using uv run python:

uv run scripts/documentation/examples/basic_usage.py
uv run scripts/documentation/examples/advanced_workflow.py

Quick Links:

📚 Source Code - Browse all modules
📖 Full Documentation - Complete documentation
🎯 Module Documentation - Per-module guides
💻 Scripts - Utility and automation scripts

📑 Table of Contents

What is Codomyrmex?
- Key Features
- Why Codomyrmex?
Quick Start
Documentation Hub
Installation & Setup
System Architecture
Getting Started Workflow
Architecture
- Layered Design Principles
Core Modules
Explore Modules
Module Quick Reference
Common Use Cases
Project Structure
Key Concepts
Documentation
Development
Contributing
Security
License

System Architecture

graph TB
    subgraph userInterfaces ["User Interfaces"]
        CLI["CLI (codomyrmex)"]
        Shell["Interactive Shell"]
        API["API Endpoints (FastAPI)"]
    end

    subgraph coreServices ["Core Services Layer"]
        Discovery["System Discovery"]
        Status["Status Reporting"]
        Terminal["Interactive Terminal"]
    end

    subgraph aiIntelligence ["Module Layer - AI & Intelligence"]
        AICode["AI Code Editing"]
        MCP["Model Context Protocol"]
        LLM["LLM Infrastructure"]
        Ollama["Ollama (Local LLM)"]
    end

    subgraph analysisQuality ["Module Layer - Analysis & Quality"]
        StaticAnalysis["Static Analysis"]
        PatternMatch["Pattern Matching"]
        Coding["Coding & Review"]
        Security["Security"]
        Perf["Performance Monitoring"]
    end

    subgraph buildDeploy ["Module Layer - Build & Deploy"]
        Git["Git Operations"]
        Docs["Documentation Generation"]
        APIDocs["API Documentation"]
        APIStd["API Standardization"]
        CICDAuto["CI/CD Automation"]
        Container["Container Management"]
    end

    subgraph visualizationData ["Module Layer - Visualization & Data"]
        DataViz["Data Visualization"]
        Spatial["Spatial (3D/4D)"]
    end

    subgraph infrastructure ["Module Layer - Infrastructure"]
        Database["Database Management"]
        ConfigMgmt["Config Management"]
        PhysMgmt["Physical Management"]
        Events["Event System"]
        PluginSys["Plugin System"]
        Cloud["Cloud Integration"]
        Networking["Networking"]
    end

    subgraph extensions ["Module Layer - Extensions"]
        ModTemplate["Module Template"]
        ToolUse["Tool Use"]
        Meme["Meme (Info Dynamics)"]
        SysDiscovery["System Discovery"]
        Cerebrum["Cerebrum (Reasoning)"]
        FPF["FPF (Functional)"]
        IDE["IDE Integration"]
        Networks["Networks"]
        Simulation["Simulation"]
    end

    subgraph foundation ["Foundation Layer"]
        Logging["Logging & Monitoring"]
        Environment["Environment Setup"]
        TerminalInterface["Terminal Interface"]
    end

    %% User Interface connections
    CLI --> Discovery
    Shell --> Terminal
    API --> Status

    %% Service Layer connections
    Discovery --> AICode
    Discovery --> StaticAnalysis
    Discovery --> CICDAuto
    Status --> DataViz
    Terminal --> Shell

    %% Module interconnections
    AICode --> Coding
    AICode --> MCP
    AICode --> Ollama
    AICode --> LLM
    StaticAnalysis --> CICDAuto
    StaticAnalysis --> PatternMatch
    StaticAnalysis --> Coding
    StaticAnalysis --> Security
    PatternMatch --> AICode
    PatternMatch --> Coding
    Perf --> Coding
    Perf --> CICDAuto
    CICDAuto --> Git
    CICDAuto --> Docs
    CICDAuto --> Container
    Docs --> StaticAnalysis
    APIDocs --> APIStd
    CICDAuto --> Security
    Container --> PhysMgmt
    Container --> Events
    DataViz --> Spatial
    Database --> CICDAuto
    Database --> Events
    ConfigMgmt --> Environment
    Events --> PluginSys
    PluginSys --> ModTemplate
    SysDiscovery --> ModTemplate
    SysDiscovery --> ToolUse
    Meme --> ToolUse
    Meme --> Events

    %% Foundation connections (all modules depend on foundation)
    AICode -.-> Logging
    StaticAnalysis -.-> Logging
    Coding -.-> Logging
    Security -.-> Logging
    Perf -.-> Logging
    Git -.-> Logging
    Docs -.-> Logging
    APIDocs -.-> Logging
    APIStd -.-> Logging
    CICDAuto -.-> Logging
    Container -.-> Logging
    DataViz -.-> Logging
    Spatial -.-> Logging
    Database -.-> Logging
    ConfigMgmt -.-> Logging
    PhysMgmt -.-> Logging
    Events -.-> Logging
    PluginSys -.-> Logging
    ModTemplate -.-> Logging
    ToolUse -.-> Logging
    SysDiscovery -.-> Logging
    Discovery -.-> Logging
    Status -.-> Logging
    Terminal -.-> Logging

    AICode -.-> Environment
    StaticAnalysis -.-> Environment
    Coding -.-> Environment
    Security -.-> Environment
    Perf -.-> Environment
    Git -.-> Environment
    Docs -.-> Environment
    APIDocs -.-> Environment
    APIStd -.-> Environment
    CICDAuto -.-> Environment
    Container -.-> Environment
    DataViz -.-> Environment
    Spatial -.-> Environment
    Database -.-> Environment
    ConfigMgmt -.-> Environment
    PhysMgmt -.-> Environment
    Events -.-> Environment
    PluginSys -.-> Environment
    ModTemplate -.-> Environment
    ToolUse -.-> Environment
    SysDiscovery -.-> Environment
    Discovery -.-> Environment
    Status -.-> Environment
    Terminal -.-> Environment

    AICode -.-> TerminalInterface
    MCP -.-> TerminalInterface
    Ollama -.-> TerminalInterface
    LLM -.-> TerminalInterface
    Discovery -.-> TerminalInterface
    Status -.-> TerminalInterface
    Terminal -.-> TerminalInterface
    Events -.-> TerminalInterface
    PluginSys -.-> TerminalInterface
    SysDiscovery -.-> TerminalInterface

Module Dependency Graph

graph TD
    subgraph foundation ["Foundation Layer"]
        Logging["logging_monitoring"]
        Env["environment_setup"]
        MCP["model_context_protocol"]
        Terminal["terminal_interface"]
    end

    subgraph core ["Core Layer"]
        Agents["agents"]
        StaticAnalysis["static_analysis"]
        Coding["coding"]
        DataViz["data_visualization"]
        PatternMatch["pattern_matching"]
        GitOps["git_operations"]
        Security["security"]
        LLM["llm"]
        Performance["performance"]
    end

    subgraph service ["Service Layer"]
        Documentation["documentation"]
        API["api"]
        CICD["ci_cd_automation"]
        Container["containerization"]
        ConfigMgmt["config_management"]
        Database["database_management"]
        Logistics["logistics"]
        PhysMgmt["physical_management"]
    end

    subgraph specialized ["Specialized Layer"]
        SysDiscovery["system_discovery"]
        ModuleTemplate["module_template"]
        Spatial["spatial"]
        Meme["meme"]
        Events["events"]
        PluginSys["plugin_system"]
        ToolUse["tool_use"]
        Networks["networks"]
        Simulation["simulation"]
    end

    %% Foundation dependencies (minimal)
    Env --> Logging

    %% Core layer dependencies
    Logging --> Agents
    Logging --> StaticAnalysis
    Logging --> Coding
    Logging --> DataViz
    Logging --> PatternMatch
    Logging --> GitOps
    Logging --> Security
    Logging --> LLM
    Logging --> Performance

    Env --> Agents
    Env --> Coding
    Env --> Security
    Env --> Performance

    MCP --> Agents
    MCP --> LLM

    Terminal --> Agents
    Terminal --> Coding

    StaticAnalysis --> Coding
    PatternMatch --> Coding
    Security --> Coding

    %% Service layer dependencies
    Logging --> Documentation
    Logging --> API
    Logging --> CICD
    Logging --> Container
    Logging --> ConfigMgmt
    Logging --> Database
    Logging --> Logistics
    Logging --> PhysMgmt

    Env --> CICD
    Env --> Container
    Env --> ConfigMgmt
    Env --> Database
    Env --> PhysMgmt

    Agents --> CICD
    Agents --> Documentation
    Agents --> Logistics

    StaticAnalysis --> CICD

    Coding --> CICD

    DataViz --> Documentation
    DataViz --> API

    GitOps --> CICD
    GitOps --> Logistics

    Security --> CICD
    Security --> Container

    Performance --> CICD
    Performance --> Container

    Documentation --> Logistics
    CICD --> Logistics
    Container --> Logistics
    ConfigMgmt --> Logistics
    Database --> Logistics

    %% Specialized layer dependencies
    Logging --> SysDiscovery
    Logging --> ModuleTemplate
    Logging --> Spatial
    Logging --> Events
    Logging --> PluginSys
    Logging --> ToolUse
    Logging --> Networks
    Logging --> Simulation

    Env --> SysDiscovery
    Env --> ModuleTemplate
    Env --> Events
    Env --> PluginSys

    SysDiscovery --> ModuleTemplate
    SysDiscovery --> ToolUse
    DataViz --> Spatial
    Events --> PluginSys
    PluginSys --> ModuleTemplate
    Meme --> Events
    Meme --> ToolUse

Workflow Execution Architecture

graph TD
    User[👤 User Request] --> Orchestrator[🎯 Project Orchestrator]

    Orchestrator --> DAGBuilder[DAG Builder]
    DAGBuilder --> WorkflowDAG[Workflow DAG]

    WorkflowDAG --> ParallelExecutor[Parallel Executor]
    ParallelExecutor --> TaskRunner1[Task Runner 1]
    ParallelExecutor --> TaskRunner2[Task Runner 2]
    ParallelExecutor --> TaskRunner3[Task Runner 3]

    TaskRunner1 --> Module1[Codomyrmex Module]
    TaskRunner2 --> Module2[Codomyrmex Module]
    TaskRunner3 --> Module3[Codomyrmex Module]

    Module1 --> Results1{Results}
    Module2 --> Results2{Results}
    Module3 --> Results3{Results}

    Results1 --> Aggregator[Result Aggregator]
    Results2 --> Aggregator
    Results3 --> Aggregator

    Aggregator --> Reporter[📊 Status Reporter]
    Reporter --> User

    %% Feedback loop for iterative workflows
    Reporter --> Orchestrator

Multi-Stage Build Architecture

graph TD
    subgraph sourceCode ["Source Code"]
        AppCode["Application Code"]
        Dependencies["Dependencies"]
        ConfigFiles["Configuration"]
    end

    subgraph buildStages ["Build Stages"]
        Builder["Builder Stage: Install dependencies, Compile code, Run tests, Create artifacts"]
        Runtime["Runtime Stage: Copy artifacts, Configure runtime, Set permissions, Define entrypoint"]
    end

    subgraph output ["Output"]
        OptimizedImage["Optimized Image: Minimal layers, Security hardened, Cached efficiently"]
    end

    AppCode --> Builder
    Dependencies --> Builder
    ConfigFiles --> Builder
    ConfigFiles --> Runtime

    Builder --> Runtime
    Runtime --> OptimizedImage

    Builder -.->|"Remove build tools, Clean cache"| OptimizedImage
    Runtime -.->|"Add runtime deps, Configure app"| OptimizedImage

Installation & Setup

Prerequisites

Python ≥3.10
uv (recommended) or pip

Installation Options

Option 1: Using uv (Recommended)

git clone https://github.com/docxology/codomyrmex.git
cd codomyrmex
uv sync

Option 2: Using pip

git clone https://github.com/docxology/codomyrmex.git
cd codomyrmex
uv pip install -e .

Verify Installation

# Launch interactive shell
./start_here.sh

# Or use the CLI directly
codomyrmex --help

# Discover available modules
uv run python -c "from codomyrmex.system_discovery import SystemDiscovery; SystemDiscovery().discover_modules()"

For detailed installation instructions, see the Installation Guide.

Getting Started Workflow

Typical user journey with Codomyrmex:

flowchart TD
    Start([Start]) --> Install{Install Codomyrmex}

    Install -->|uv sync| Config["Configure Environment"]
    Install -->|uv pip install| Config

    Config --> Setup["Environment Setup"]
    Setup --> Discover["Discover Modules"]

    Discover --> Choose{Choose Workflow}

    Choose -->|CLI Usage| CLI["Use CLI Commands"]
    Choose -->|Interactive| Interactive["Launch Interactive Shell"]
    Choose -->|API| API["Use REST API"]

    CLI --> Modules["Work with Modules"]
    Interactive --> Modules
    API --> Modules

    Modules --> Dev{Development Tasks}

    Dev -->|Code Analysis| Analysis["Static Analysis Code Review"]
    Dev -->|Build & Deploy| Build["CI/CD Automation & Deployment"]
    Dev -->|AI Assistance| AI["AI Code Editing Pattern Matching"]
    Dev -->|Visualization| Viz["Data Visualization 3D Modeling"]
    Dev -->|Infrastructure| Infra["Container Management Database Operations"]

    Analysis --> Extend["Extend & Customize"]
    Build --> Extend
    AI --> Extend
    Viz --> Extend
    Infra --> Extend

    Extend --> Contrib{Contribute Back}

    Contrib -->|Bug Reports| Issues["File Issues in GitHub"]
    Contrib -->|Features| PR["Create Pull Requests"]
    Contrib -->|Documentation| Docs["Improve Documentation"]

    Issues --> End([End])
    PR --> End
    Docs --> End

    Modules --> End

Architecture

Layered Design Principles

Codomyrmex follows a layered architecture that ensures clean separation of concerns and prevents circular dependencies. Each layer builds upon the layers below it, creating a stable foundation for complex workflows.

Key Architectural Decisions:

Upward Dependencies Only: Higher layers depend on lower layers, never the reverse
Foundation Services: Core infrastructure used by all modules
Clear Layer Boundaries: Each layer has distinct responsibilities
Modular Composition: Modules can be used independently or combined

Layer Responsibilities:

Foundation Layer: Provides essential services (logging, environment, terminal, MCP)
Core Layer: Implements primary development capabilities (analysis, execution, AI, visualization)
Service Layer: Orchestrates complex workflows and integrations (build, docs, CI/CD, orchestration)
Application Layer: User interfaces and system coordination (CLI, shell, API, discovery)

See detailed architecture documentation for design principles and module relationships.

Core Modules

Codomyrmex modules are organized in a layered architecture where higher layers depend on lower layers, preventing circular dependencies:

graph TD
    subgraph applicationLayer ["Application Layer"]
        InteractiveShell["Interactive Shell"]
        SystemDiscovery["System Discovery & Orchestration"]
        CLI["Command Line Interface"]
    end

    subgraph serviceLayer ["Service Layer"]
        AICodeEditing["AI Code Editing"]
        Documentation["Documentation Generation"]
        StaticAnalysis["Static Analysis & Quality"]
        Orchestrator["Orchestrator"]
        CICDAutomation["CI/CD Automation"]
        APIDocumentation["API Documentation"]
        Containerization["Container Management"]
        DatabaseManagement["Database Management"]
        ConfigManagement["Config Management"]
    end

    subgraph coreLayer ["Core Layer"]
        CodeExecution["Code Execution Sandbox"]
        DataVisualization["Data Visualization & Plotting"]
        PatternMatching["Pattern Matching"]
        GitOperations["Git Operations & Version Control"]
        CodeReview["Code Review"]
        OllamaIntegration["Ollama Integration"]
        LanguageModels["Language Models"]
        SecurityAudit["Security Audit"]
        Performance["Performance Monitoring"]
        Spatial["Spatial (3D/4D)"]
        PhysicalManagement["Physical Management"]
    end

    subgraph foundationLayer ["Foundation Layer"]
        LoggingMonitoring["Logging & Monitoring"]
        EnvironmentSetup["Environment Setup"]
        ModelContextProtocol["Model Context Protocol"]
        TerminalInterface["Terminal Interface"]
    end

    %% Dependencies flow upward (dotted lines show "depends on")
    InteractiveShell -.-> SystemDiscovery
    CLI -.-> SystemDiscovery
    SystemDiscovery -.-> LoggingMonitoring
    SystemDiscovery -.-> EnvironmentSetup
    SystemDiscovery -.-> TerminalInterface

    AICodeEditing -.-> LoggingMonitoring
    AICodeEditing -.-> EnvironmentSetup
    AICodeEditing -.-> ModelContextProtocol
    AICodeEditing -.-> TerminalInterface
    AICodeEditing -.-> CodeExecution
    AICodeEditing -.-> PatternMatching

    Documentation -.-> LoggingMonitoring
    Documentation -.-> CICDAutomation
    Documentation -.-> StaticAnalysis

    StaticAnalysis -.-> LoggingMonitoring
    StaticAnalysis -.-> PatternMatching
    StaticAnalysis -.-> CodeReview

    Orchestrator -.-> LoggingMonitoring
    Orchestrator -.-> CICDAutomation
    Orchestrator -.-> Documentation

    CICDAutomation -.-> GitOperations
    CICDAutomation -.-> SecurityAudit
    CICDAutomation -.-> LoggingMonitoring

    APIDocumentation -.-> LoggingMonitoring
    APIDocumentation -.-> Documentation

    Containerization -.-> PhysicalManagement
    Containerization -.-> LoggingMonitoring

    DatabaseManagement -.-> LoggingMonitoring
    DatabaseManagement -.-> CICDAutomation

    ConfigManagement -.-> EnvironmentSetup
    ConfigManagement -.-> LoggingMonitoring

    CodeExecution -.-> LoggingMonitoring
    DataVisualization -.-> LoggingMonitoring
    PatternMatching -.-> LoggingMonitoring
    PatternMatching -.-> EnvironmentSetup
    GitOperations -.-> LoggingMonitoring
    CodeReview -.-> LoggingMonitoring
    CodeReview -.-> StaticAnalysis
    OllamaIntegration -.-> LoggingMonitoring
    OllamaIntegration -.-> EnvironmentSetup
    LanguageModels -.-> LoggingMonitoring
    LanguageModels -.-> EnvironmentSetup
    SecurityAudit -.-> LoggingMonitoring
    Performance -.-> LoggingMonitoring
    Spatial -.-> LoggingMonitoring
    PhysicalManagement -.-> LoggingMonitoring

Foundation Layer

Essential infrastructure used by all other modules:

Module	Purpose	Key Features
logging_monitoring	Centralized logging system	Structured logging, multiple formats, aggregation
environment_setup	Environment validation	Dependency checking, API key management, setup automation
model_context_protocol	AI communication standard	Standardized LLM interfaces, tool specifications
terminal_interface	Rich terminal interactions	Colored output, progress bars, interactive prompts

Core Functional Modules

Primary capabilities for development workflows:

Module	Purpose	Key Features
agents	Agentic framework integrations	AI code editing, task management, various providers
static_analysis	Code quality analysis	Linting, security scanning, complexity metrics
coding	Code execution & review	Safe sandbox execution, automated code review
data_visualization	Charts and plots	Static/interactive plots, multiple formats
pattern_matching	Code pattern analysis	Pattern recognition, dependency analysis
git_operations	Version control automation	Git workflows, branch management, commit automation
security	Security scanning	Vulnerability detection, compliance checking, threat assessment
llm	LLM infrastructure	Model management, local/remote providers (Ollama), benchmarking
performance	Performance monitoring	Profiling, optimization, benchmarking

Service Modules

Higher-level services that orchestrate core modules:

Module	Purpose	Key Features
documentation	Documentation generation	Website generation, API docs, tutorial creation
api	API infrastructure	OpenAPI/Swagger specs, standardization, documentation
ci_cd_automation	CI/CD pipeline management	Pipeline orchestration, deployment automation
containerization	Container management	Docker lifecycle, Kubernetes orchestration
database_management	Database operations	Schema management, migrations, backups
config_management	Configuration management	Environment setup, secret management, validation
logistics	Logistics and orchestration	Workflow orchestration, task management, scheduling

Specialized Modules

Advanced capabilities for specific domains:

Module	Purpose	Key Features
spatial	Spatial modeling (3D/4D)	Scene creation, rendering, geometric operations, world models
physical_management	Physical system simulation	Hardware monitoring, resource management
system_discovery	System exploration	Module discovery, capability detection, health monitoring
module_template	Module creation templates	Scaffold generation, template management
events	Event system	Message passing, pub/sub patterns, event logging
plugin_system	Plugin architecture	Extension loading, plugin management, interfaces
tool_use	Tool use	Tool invocation, management, and orchestration

Explore Modules

Codomyrmex includes 91 modules organized in a layered architecture. Each module is self-contained with comprehensive documentation, API specifications, usage examples, and security considerations.

Browse all available modules organized by layer and category:

Foundation Layer

Essential infrastructure used by all other modules:

logging_monitoring - Centralized logging system with structured logging, multiple formats, and aggregation
environment_setup - Environment validation, dependency checking, API key management, and setup automation
model_context_protocol - AI communication standard with standardized LLM interfaces and tool specifications
terminal_interface - Rich terminal interactions with colored output, progress bars, and interactive prompts

Core Layer

Primary capabilities for development workflows:

agents - Agentic framework integrations with AI code editing, task management, and various providers
static_analysis - Code quality analysis with linting, security scanning, and complexity metrics
coding - Code execution and review with safe sandbox execution and automated code review
data_visualization - Charts and plots with static/interactive plots and multiple formats
pattern_matching - Code pattern analysis with pattern recognition and dependency analysis
git_operations - Version control automation with Git workflows, branch management, and commit automation
security - Security scanning with vulnerability detection, compliance checking, and threat assessment
llm - LLM infrastructure with model management, local/remote providers (Ollama), and benchmarking
performance - Performance monitoring with profiling, optimization, and benchmarking
cache - Multi-level caching with pluggable backends
validation - Input validation and schema enforcement
serialization - Data serialization formats
utils - Common utility functions
auth - Authentication and authorization
templating - Template rendering engine
prompt_engineering - Prompt engineering and optimization

Service Layer

Higher-level services that orchestrate core modules:

documentation - Documentation generation with website generation, API docs, and tutorial creation
api - API infrastructure with OpenAPI/Swagger specs, standardization, and documentation
ci_cd_automation - CI/CD pipeline management with pipeline orchestration and deployment automation
containerization - Container management with Docker lifecycle and Kubernetes orchestration
database_management - Database operations with schema management, migrations, and backups
config_management - Configuration management with environment setup, secret management, and validation
logistics - Logistics module with orchestration, task management, and scheduling
orchestrator - Workflow execution and task orchestration
testing - Test framework and automation
deployment - Deployment automation and strategies
collaboration - Team collaboration tools
concurrency - Concurrent execution and threading

Specialized Layer

Advanced capabilities for specific domains:

spatial - Spatial modeling (3D/4D) with scene creation, rendering, geometric operations, and world models
physical_management - Physical system simulation with hardware monitoring and resource management
system_discovery - System exploration with module discovery, capability detection, and health monitoring
module_template - Module creation templates with scaffold generation and template management
events - Event system with message passing, pub/sub patterns, and event logging
plugin_system - Plugin architecture with extension loading, plugin management, and interfaces
tool_use - Tool invocation, management, and orchestration
cerebrum - Advanced reasoning and inference engine
fpf - Functional Programming Framework
ide - IDE integration and protocol support
cloud - Cloud provider integrations (AWS, GCP)
networking - Networking utilities
scrape - Web scraping capabilities
encryption - Data encryption utilities
compression - Data compression utilities

AI & Intelligence Layer

Advanced AI/ML capabilities and intelligent systems:

agentic_memory - Long-term agent memory and recall
graph_rag - Graph-based retrieval augmented generation
model_ops - ML model lifecycle management
evolutionary_ai - Evolutionary algorithms and genetic programming
prompt_engineering - Prompt engineering and optimization

Security & Cognitive Layer

Identity, privacy, and cognitive defense systems:

identity - Multi-persona management and bio-cognitive verification
wallet - Self-custody key management and natural ritual recovery
defense - Active defense against cognitive exploits
market - Anonymous economic coordination and reverse auctions
privacy - Data minimization and mixnet routing
finance - Financial operations and tracking

Media & Content Layer

Media processing and content management:

audio - Audio processing and transcription
video - Video processing and analysis
documents - Document processing and extraction
dark - Dark mode utilities for PDFs and interfaces
website - Website generation and management
skills - Skill management and registration
examples - Example code and demonstrations
tests - Centralized test suites

Observability & Operations Layer

Monitoring, telemetry, and operational tooling:

telemetry - Telemetry data collection
feature_flags - Feature flag management
cli - Command-line interface (entry point)
embodiment - Physical/robotic embodiment interfaces

See Source Code Index for complete module listing and Module System Overview for detailed architecture.

Module Quick Reference

Category	Modules
Foundation	logging_monitoring • environment_setup • model_context_protocol • terminal_interface
Core	agents • llm • static_analysis • coding • pattern_matching • security • data_visualization • git_operations • performance • cache • validation • serialization • utils • auth • templating • prompt_engineering
Service	documentation • api • ci_cd_automation • containerization • database_management • config_management • logistics • orchestrator • testing • deployment • collaboration • concurrency
Specialized	spatial • physical_management • system_discovery • module_template • events • plugin_system • tool_use • cerebrum • fpf • ide • cloud • networking • networks • simulation • scrape • encryption • compression
AI & Intelligence	agentic_memory • graph_rag • model_ops • evolutionary_ai • prompt_engineering
Security & Cognitive	identity • wallet • defense • market • privacy • finance
Media & Content	audio • video • documents • dark • website • skills • examples • tests
Observability & Operations	telemetry • feature_flags • cli • embodiment

Common Use Cases

Development Workflows

Code Analysis Pipeline: Static analysis → Code review → Security scan
AI-Assisted Development: AI code editing with pattern matching for code refactoring
Build & Deploy: CI/CD automation → Container management

Research & Analysis

Data Science Workflow: Coding → Data visualization → Performance monitoring
System Exploration: System discovery → Pattern analysis → Documentation generation

Production Operations

Infrastructure Management: Database operations → Configuration management → Physical monitoring
Quality Assurance: Security scanning → Performance benchmarking → Automated testing

See executable examples for working demonstrations of these workflows.

Project Structure

codomyrmex/
├── /src/codomyrmex/          # Core source modules
│   ├── /src/codomyrmex/coding/              # Code interaction and sandboxing
│   ├── /src/codomyrmex/coding/static_analysis/ # Code quality analysis
│   ├── /src/codomyrmex/logging_monitoring/  # Centralized logging
│   └── ...                  # 91 modules total
├── /scripts/                 # Maintenance and automation utilities
│   ├── /scripts/documentation/       # Documentation maintenance scripts
│   ├── /scripts/development/         # Development utilities
│   ├── /scripts/examples/            # Example scripts and demonstrations
│   └── ...                  # 30+ module orchestrators
├── /docs/                    # Project documentation
│   ├── /docs/getting-started/     # Installation and quickstart guides
│   ├── /docs/modules/             # Module system documentation
│   ├── /docs/project/             # Architecture and contributing guides
│   └── /docs/reference/           # API reference and troubleshooting
├── /src/codomyrmex/tests/    # Test suites
│   ├── /src/codomyrmex/tests/unit/                # Unit tests
│   └── /src/codomyrmex/tests/integration/         # Integration tests
├── /config/                  # Configuration templates and examples
│   ├── /config/examples/            # Configuration examples
│   └── /config/templates/           # Configuration templates
├── /cursorrules/             # Coding standards and automation rules
│   ├── /cursorrules/modules/             # Module-specific rules
│   ├── /cursorrules/cross-module/        # Cross-module coordination rules
│   └── /cursorrules/file-specific/       # File-specific rules
├── /projects/                # Project workspace and templates
│   └── /projects/test_project/        # Example project structure
└── /output/                 # Generated output and reports

Repository Organization

graph TD
    subgraph corePlatform ["Core Platform"]
        CoreSrc["src/codomyrmex/ 91 Modules"]
        CoreScripts["scripts/ Automation & Orchestration"]
        CoreTests["src/codomyrmex/tests/ Unit & Integration Tests"]
    end

    subgraph docsConfig ["Documentation & Config"]
        Docs["docs/ User & Developer Guides"]
        Config["config/ Templates & Examples"]
        Rules["cursorrules/ Coding Standards"]
        Projects["projects/ Project Templates"]
    end

    subgraph examplesOutput ["Examples & Output"]
        ModuleExamples["scripts/[module]/examples/ Module Examples"]
        Output["output/ Generated Reports"]
        ScriptsExamples["scripts/examples/ General Examples"]
    end

    CoreSrc --> Docs
    CoreScripts --> Docs
    CoreTests --> Docs
    Config --> CoreSrc
    Rules --> CoreSrc
    Projects --> CoreScripts
    ModuleExamples --> CoreSrc
    ScriptsExamples --> CoreScripts
    CoreSrc --> Output
    CoreScripts --> Output

Key Concepts

Modular Architecture

Each module is self-contained with:

Own dependencies (managed in pyproject.toml)
Tests (tests/)
API documentation (API_SPECIFICATION.md)
MCP tool definitions (MCP_TOOL_SPECIFICATION.md)
Agent integration (AGENTS.md)
Technical specification (SPEC.md)
PAI integration (PAI.md)

See module system overview for detailed module architecture and relationships.

Model Context Protocol (MCP)

Standardized interface for AI integration:

Tool specifications for LLM interactions
Consistent parameter schemas
Provider-agnostic design
Full documentation in each module's MCP_TOOL_SPECIFICATION.md

See MCP documentation for technical specifications and implementation details.

Layered Dependencies

Modules organized to prevent circular dependencies:

Foundation Layer: Base services (logging, environment, terminal)
Core Layer: Functional capabilities (analysis, execution, visualization)
Service Layer: Orchestration and integration
Application Layer: User interfaces (CLI, interactive shell)

Signposting

Navigation Links:

Self: Codomyrmex Root
Key Artifacts:
- Agent Guide - Technical documentation for AI agents
- Personal AI Infrastructure - PAI documentation and capabilities
- Functional Spec - Functional specification
- Security - Security policies
Children:
- Source Code - All modules and implementations
- Documentation - User and developer guides
- Scripts - Automation and orchestration utilities
- Configuration - Configuration templates

Documentation

Comprehensive documentation for users, developers, and contributors. All documentation is organized in the docs/ directory.

Getting Started

Quick Start Guide - Get up and running in 5 minutes
Installation Guide - Detailed installation instructions
Setup Guide - Environment configuration and setup
Tutorials - Step-by-step tutorials including Creating a Module

Architecture & Design

Architecture Overview - System design and principles
Module System - Module architecture and relationships
Module Dependencies - Dependency graph and relationships
Module Relationships - How modules interact

Development Resources

Contributing Guide - Development guidelines and workflow
Development Environment - Setting up your development environment
Testing Strategy - Testing approaches and best practices
Documentation Guide - How to write and maintain documentation
UV Usage Guide - Using uv for package management

Integration

Integration Guide - Integrating Codomyrmex with other systems
External Systems - Integration with external services
Fabric AI Integration - AI integration patterns

Reference

API Reference - Complete API documentation
CLI Reference - Command-line interface documentation
Troubleshooting - Common issues and solutions
Migration Guide - Upgrading and migrating
Performance Guide - Performance optimization
Security Guide - Security best practices

Deployment

Deployment Guide - Production deployment instructions
Production Setup - Production environment configuration

Workflow Orchestration

Project Lifecycle - Managing project workflows
Workflow Configuration - Workflow schemas
Task Orchestration - Task management
Logistics Module - Orchestration, task management, and scheduling

Examples

Example Scripts - Working examples and demonstrations
Basic Examples - Simple usage examples
Integration Examples - Integration patterns
Orchestration Examples - Workflow examples

See Documentation Hub for complete documentation index.

Development

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/codomyrmex --cov-report=html

# Run specific test suite
uv run pytest src/codomyrmex/tests/unit/
uv run pytest src/codomyrmex/tests/integration/

Code Quality

# Format code
uv run black src/

# Lint code
uv run ruff check src/

# Type checking
uv run mypy src/

Module Development

See Creating a Module Tutorial for detailed guidance on developing new modules.

Contributing

We welcome contributions! Please see our Contributing Guide for:

Code standards and best practices
Development workflow
Pull request process
Testing requirements
Documentation guidelines

Security

Security is a priority. See SECURITY.md for:

Vulnerability reporting
Security best practices
Module-specific security considerations

License

This project is licensed under the MIT License - see the LICENSE file for details.

Data Flow Architecture

graph TD
    subgraph dataSources ["Data Sources"]
        UserInput["User Input: Commands, Code, Config"]
        FileSystem["File System: Source Code, Data Files"]
        APIs["External APIs: GitHub, Docker Hub, PyPI"]
        Databases["Databases: Local/Remote DBs"]
    end

    subgraph processingPipeline ["Processing Pipeline"]
        InputParser["Input Parser: CLI Args, Config Files"]
        ModuleOrchestrator["Module Orchestrator: Workflow Coordination"]
        DataTransformers["Data Transformers: Analysis, Processing"]
        OutputGenerators["Output Generators: Reports, Visualizations"]
    end

    subgraph storagePersistence ["Storage & Persistence"]
        LocalStorage["Local Storage: JSON, CSV, Images"]
        RemoteStorage["Remote Storage: Cloud Services, Git"]
        CacheLayer["Cache Layer: In-Memory, Redis"]
    end

    subgraph consumption ["Consumption"]
        TerminalOutput["Terminal Display: Rich Text, Tables"]
        FileOutputs["File Outputs: Reports, Exports"]
        WebInterfaces["Web Interfaces: Dashboards, APIs"]
    end

    UserInput --> InputParser
    FileSystem --> InputParser
    APIs --> DataTransformers
    Databases --> DataTransformers

    InputParser --> ModuleOrchestrator
    ModuleOrchestrator --> DataTransformers
    DataTransformers --> OutputGenerators

    OutputGenerators --> LocalStorage
    OutputGenerators --> RemoteStorage
    OutputGenerators --> CacheLayer

    LocalStorage --> TerminalOutput
    RemoteStorage --> FileOutputs
    CacheLayer --> WebInterfaces

    %% Bidirectional data flow
    CacheLayer -.->|"Read/Write"| DataTransformers
    LocalStorage -.->|"Read/Write"| ModuleOrchestrator

Module Interaction Workflow

graph TD
    subgraph entryPoints ["Entry Points"]
        CLI["CLI Command"]
        InteractiveShell["Interactive Shell"]
        APIEndpoint["REST API"]
        ConfigFile["Config File"]
    end

    subgraph orchestrationLayer ["Orchestration Layer"]
        SystemDiscovery["System Discovery: Module Loading"]
        Orchestrator["Orchestrator: Workflow Planning"]
        TaskScheduler["Task Scheduler: Parallel Execution"]
    end

    subgraph coreProcessing ["Core Processing Modules"]
        AICode["AI Code Editing: Generation, Refactoring"]
        StaticAnalysis["Static Analysis: Quality Metrics"]
        Code["Code Execution & Review"]
        Security["Security: Vulnerability Scanning"]
    end

    subgraph infrastructureModules ["Infrastructure Modules"]
        GitOps["Git Operations: Version Control"]
        CICDAuto["CI/CD Automation: Builds & Deployment"]
        ContainerMgmt["Container Management: Docker, K8s"]
        DatabaseMgmt["Database Management: Migrations, Queries"]
    end

    subgraph outputVisualization ["Output & Visualization"]
        DataVisualization["Data Visualization: Charts, Plots"]
        Documentation["Documentation: API Docs, Guides"]
        Reporting["Reporting: Status, Metrics"]
    end

    CLI --> SystemDiscovery
    InteractiveShell --> SystemDiscovery
    APIEndpoint --> Orchestrator
    ConfigFile --> TaskScheduler

    SystemDiscovery --> Orchestrator
    Orchestrator --> TaskScheduler

    TaskScheduler --> AICode
    TaskScheduler --> StaticAnalysis
    TaskScheduler --> Code
    TaskScheduler --> Security

    AICode --> GitOps
    StaticAnalysis --> CICDAuto
    Code --> ContainerMgmt
    Security --> DatabaseMgmt

    GitOps --> DataVisualization
    CICDAuto --> Documentation
    ContainerMgmt --> Reporting
    DatabaseMgmt --> DataVisualization

    DataVisualization --> Reporting
    Documentation --> Reporting

    %% Cross-module dependencies
    AICode -.->|"Code Review"| StaticAnalysis
    StaticAnalysis -.->|"Security Scan"| Security
    CICDAuto -.->|"Container Build"| ContainerMgmt
    GitOps -.->|"Version Control"| CICDAuto

Development Workflow Architecture

flowchart TD
    subgraph planningPhase ["Planning Phase"]
        Requirements["Requirements Analysis"]
        Design["Design Architecture"]
        Planning["Planning Task Breakdown"]
    end

    subgraph developmentPhase ["Development Phase"]
        CodeGeneration["Code Generation AI-Assisted"]
        Implementation["Implementation Manual Coding"]
        Testing["Testing Unit & Integration"]
        CodeReview["Code Review Automated & Manual"]
    end

    subgraph qualityAssurance ["Quality Assurance"]
        StaticAnalysis["Static Analysis Linting, Metrics"]
        Security["Security Vulnerability Checks"]
        PerformanceTesting["Performance Testing Benchmarking"]
        Documentation["Documentation API Docs, Guides"]
    end

    subgraph integrationPhase ["Integration Phase"]
        BuildProcess["Build Process Compilation, Packaging"]
        Deployment["Deployment Container, Cloud"]
        Monitoring["Monitoring Logs, Metrics"]
        FeedbackLoop["Feedback Loop Issue Tracking"]
    end

    Requirements --> Design
    Design --> Planning
    Planning --> CodeGeneration
    Planning --> Implementation

    CodeGeneration --> Testing
    Implementation --> Testing
    Testing --> CodeReview
    CodeReview --> StaticAnalysis

    StaticAnalysis --> Security
    Security --> PerformanceTesting
    PerformanceTesting --> Documentation

    Documentation --> BuildProcess
    BuildProcess --> Deployment
    Deployment --> Monitoring
    Monitoring --> FeedbackLoop

    FeedbackLoop --> Requirements

    %% Tool integration
    CodeGeneration -.->|"AI Code Editing"| Testing
    Testing -.->|"Test Runners"| CodeReview
    StaticAnalysis -.->|"Linting Tools"| Security
    BuildProcess -.->|"CI/CD"| Deployment
    Monitoring -.->|"Logging"| FeedbackLoop

Dependencies Overview

graph TD
    subgraph coreDeps ["Core Dependencies"]
        CorePy["Python ≥3.10 Runtime Environment"]
        CoreUV["uv Package Manager"]
        CorePyTest["pytest Testing Framework"]
    end

    subgraph aiMLDeps ["AI/ML Dependencies"]
        AIDocker["Docker Container Runtime"]
        AIModels["Ollama Local Models"]
        AIAPI["OpenAI/Anthropic API Keys"]
    end

    subgraph devDeps ["Development Dependencies"]
        DevBlack["Black Code Formatter"]
        DevRuff["Ruff Linter"]
        DevMyPy["MyPy Type Checker"]
        DevPreCommit["Pre-commit Hooks"]
    end

    subgraph optDeps ["Optional Dependencies"]
        OptKubernetes["Kubernetes Orchestration"]
        OptDatabases["PostgreSQL/MySQL Database Servers"]
        OptCloud["AWS/GCP/Azure Cloud Providers"]
    end

    CorePy --> CoreUV
    CoreUV --> CorePyTest
    CorePy --> DevBlack
    CorePy --> DevRuff
    CorePy --> DevMyPy
    CorePy --> DevPreCommit

    CorePy --> AIDocker
    AIDocker --> AIModels
    CorePy --> AIAPI

    CorePy --> OptKubernetes
    CorePy --> OptDatabases
    CorePy --> OptCloud

Module Maturity Levels

pie title Module Development Status (February 2026)
    "Production Ready" : 15
    "Beta" : 20
    "Alpha" : 30
    "Stub/Planning" : 15

Level	Description	Example Modules
Production Ready	Fully tested, documented, stable APIs	logging_monitoring, environment_setup, terminal_interface
Beta	Core functionality complete, API stabilization	agents, static_analysis, coding
Alpha	Basic functionality, APIs may change	spatial, physical_management, system_discovery
Planning	Requirements gathering, initial design	Future specialized modules

Key Metrics

Lines of Code: ~100K+ across 91 modules
Test Coverage: ~28% (measured)
Module Count: 91 core modules
Language Support: Python, JavaScript, Go, Rust, Java
AI Integration: 5+ LLM providers supported
Documentation: 200+ pages across all modules

Links

Repository: github.com/docxology/codomyrmex
Issues: github.com/docxology/codomyrmex/issues
Documentation: codomyrmex.readthedocs.io (coming soon)
PyPI: pypi.org/project/codomyrmex/ (coming soon)
Docker Hub: hub.docker.com/r/docxology/codomyrmex (coming soon)

Built with a focus on modularity, clarity, and professional development practices.

Navigation Links

Documentation: Reference Guides
All Agents: AGENTS.md
Functional Spec: SPEC.md
Source Index: src/README.md

Example Usage

# CLI usage (primary entry point)
codomyrmex check                 # Verify environment setup
codomyrmex modules               # List available modules
codomyrmex status                # System status dashboard
codomyrmex shell                 # Interactive shell

# Python API usage
uv run python -c "
from codomyrmex.system_discovery import SystemDiscovery
sd = SystemDiscovery()
sd.discover_modules()
"

Name		Name	Last commit message	Last commit date
Latest commit History 223 Commits
.agent/workflows		.agent/workflows
.claude/Plans		.claude/Plans
.github		.github
config		config
cursorrules		cursorrules
docs		docs
examples		examples
plugins		plugins
projects		projects
scripts		scripts
src		src
testing		testing
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
INDEX.md		INDEX.md
LICENSE		LICENSE
Makefile		Makefile
PAI.md		PAI.md
README.md		README.md
SECURITY.md		SECURITY.md
SPEC.md		SPEC.md
TO-DO.md		TO-DO.md
dirs.txt		dirs.txt
index.html		index.html
package.json		package.json
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
start_here.sh		start_here.sh
uv.lock		uv.lock

License

docxology/codomyrmex

Folders and files

Latest commit

History

Repository files navigation

Codomyrmex

What is Codomyrmex?

Key Features

Why Codomyrmex?

Quick Start

Documentation Hub

🚀 Getting Started

🏗️ Architecture & Design

💻 Development

📚 Reference

🚢 Deployment & Operations

🔌 Integration

📚 Examples & Tutorials

🛠️ Hands-on Examples

📖 Documentation Examples

🧪 Executable Demos

System Architecture

Module Dependency Graph

Workflow Execution Architecture

Multi-Stage Build Architecture

Installation & Setup

Prerequisites

Installation Options

Verify Installation

Getting Started Workflow

Architecture

Layered Design Principles

Core Modules

Foundation Layer

Core Functional Modules

Service Modules

Specialized Modules

Explore Modules

Foundation Layer

Core Layer

Service Layer

Specialized Layer

AI & Intelligence Layer

Security & Cognitive Layer

Media & Content Layer

Observability & Operations Layer

Module Quick Reference

Common Use Cases

Development Workflows

Research & Analysis

Production Operations

Project Structure

Repository Organization

Key Concepts

Modular Architecture

Model Context Protocol (MCP)

Layered Dependencies

Signposting

Documentation

Getting Started

Architecture & Design

Development Resources

Integration

Reference

Deployment

Workflow Orchestration

Examples

Development

Running Tests

Code Quality

Module Development

Contributing

Security

License

Data Flow Architecture

Module Interaction Workflow

Development Workflow Architecture

Dependencies Overview

Module Maturity Levels

Packages