🐜 Codomyrmex

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 modular library of 130 top-level modules under src/codomyrmex/ spanning AI agents, cloud infrastructure, security, finance, multimedia, and more. The repository applies a strict Zero-Mock testing policy to its active suites, while its measured inventory describes the checked-in surface at refresh time rather than proving that every method is complete or production-safe. In the current project environment, the ecosystem exposes 612 runtime MCP tools from 627 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, 36,049 collected tests (uv run python scripts/doc_inventory.py --pytest), 1,204 markdown files under docs/ (recursive; see inventory), and 37 GitHub Actions workflows. These measured values are profile-specific snapshots.

# Install
git clone https://github.com/docxology/codomyrmex.git && cd codomyrmex
uv sync --locked --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?


🧩 130 Top-Level Modules	Packages under `src/codomyrmex/` — modular interfaces with scoped zero-mock tests
🤖 612 Runtime MCP Tools	Complete locked dependency profile; 627 source decorators; see inventory
🧪 36,049 Collected Tests	Current project environment; `uv run python scripts/doc_inventory.py --pytest`; zero-mock policy
🔒 Security First	GitGuardian, SBOM, GGSHIELD pre-commit, detect-secrets integration
🎛️ 13+ Agent Providers	Claude, Gemini, GPT-4o, DeepSeek, Mistral, Jules, Codex, Pi, and more
🔬 ML Research Ready	LoRA, RLHF, DPO, distillation, quantization, NAS, Mamba SSM, autograd
🏠 Personal AI Infrastructure	Email, calendar, finance, wallet, dashboard — full PAI toolbox
📦 PyPI Ready	`uv build` + `twine check` verified, Python 3.11–3.14
🦎 Zero Config to Start	`uv sync` → `codomyrmex doctor` → done

📚 Documentation Hub

Top-Level Documents

Document	Description
docs/README.md	Documentation home — full directory guide
docs/ARCHITECTURE.md	System architecture, dependency layers, design patterns
docs/AGENTS.md	Agent coordination rules and autonomous workflows
docs/SPEC.md	Technical specification, API contracts, schemas
docs/PAI.md	Personal AI Infrastructure integration reference
docs/PAI_DASHBOARD.md	PAI dashboard GUI reference and tab guide
docs/index.md	MkDocs site index and navigation entry point

Documentation Directories

Directory	Files	Description
docs/getting-started/	9	Quick start, installation, setup, tutorials
docs/development/	10	Dev environment, testing strategy, contribution guides
docs/reference/	16	API reference, CLI reference, troubleshooting
docs/modules/	130 pkgs	Per-module documentation (README, SPEC, AGENTS, PAI per module)
docs/agents/	121	Agent rules, coordination, per-provider docs (mirror `src/codomyrmex/agents/`)
docs/integration/	11	External service integration (Google, GitHub, etc.)
docs/deployment/	5	Production deployment guides and checklists
docs/security/	11	Security theory, threat models, audit procedures
docs/pai/	10	PAI dashboard, email, calendar, skill management
docs/bio/	15	Biological & myrmecological perspectives
docs/cognitive/	11	Cognitive science & engineering perspectives
docs/agi/	14	AGI theory, emergence, recursive self-improvement
docs/compliance/	5	Audit reports, policy compliance, SOC2
docs/examples/	8	Code examples, integration demos, walkthroughs
docs/project/	9	Architecture, roadmap, contributing, governance
docs/project_orchestration/	11	Multi-project workflow guides and pipelines
docs/skills/	9	Skill system lifecycle, governance, authoring
docs/plans/	6	Implementation plans and integration roadmaps

📐 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. 130 top-level modules across 10 capability layers — from foundation utilities to ML training primitives.

🧠 Core Intelligence Modules

Module	Py	Tests	Docs	Config	Scripts	Description
`agents`	285	154	📖	⚙️	📜	Multi-provider agent framework (Gemini, Claude, OpenAI, Jules)
`cerebrum`	37	16	📖	⚙️	📜	Cognitive reasoning engine with chain-of-thought & decision trees
`llm`	65	38	📖	⚙️	📜	LLM subsystem with OpenRouter, Gemini 2.5 Pro, streaming
`orchestrator`	66	24	📖	⚙️	📜	Workflow engine, pipeline execution, parallel orchestration
`model_context_protocol`	29	15	📖	⚙️	📜	MCP tool server, bridge, and protocol implementation
`prompt_engineering`	10	12	📖	⚙️	📜	Template management, prompt optimization, few-shot patterns
`skills`	26	17	📖	⚙️	📜	Extensible skill registry and execution engine

🤖 AI & Machine Learning Modules

Module	Py	Tests	Docs	Config	Scripts	Description
`coding`	70	31	📖	⚙️	📜	Code generation, refactoring, analysis, and review agents
`evolutionary_ai`	14	8	📖	⚙️	📜	Genetic algorithms, fitness, selection, genome operators
`graph_rag`	6	7	📖	⚙️	📜	Graph-based retrieval-augmented generation
`vector_store`	7	8	📖	⚙️	📜	Embedding storage, similarity search, FAISS/ChromaDB
`bio_simulation`	13	7	📖	⚙️	📜	Biological colony simulation and genomic population models
`simulation`	4	4	📖	⚙️	📜	General-purpose simulation framework
`quantum`	7	5	📖	⚙️	📜	Quantum computing abstractions and circuit simulation
`fpf`	27	14	📖	⚙️	📜	Feed-Parse-Format pipeline (fetch, parse, section export)

☁️ Infrastructure & DevOps Modules

Module	Py	Tests	Docs	Config	Scripts	Description
`cloud`	83	28	📖	⚙️	📜	Multi-cloud SDK (AWS, GCP, Azure, Infomaniak, Coda.io)
`containerization`	19	9	📖	⚙️	📜	Docker/Podman management, image building, registry
`container_optimization`	4	3	📖	⚙️	📜	Resource tuning and container performance optimization
`ci_cd_automation`	24	12	📖	⚙️	📜	Pipeline building, artifact management, deployment orchestration
`deployment`	16	8	📖	⚙️	📜	Deployment strategies (blue-green, canary, rolling)
`edge_computing`	17	6	📖	⚙️	📜	Edge cluster management, scheduling, health monitoring
`networking`	10	9	📖	⚙️	📜	HTTP clients, WebSocket, gRPC, service mesh
`networks`	4	4	📖	⚙️	📜	Network topology and graph analysis
`cost_management`	6	3	📖	⚙️	📜	Cloud cost tracking, budget alerts, optimization

💾 Data & Storage Modules

Module	Py	Tests	Docs	Config	Scripts	Description
`database_management`	22	16	📖	⚙️	📜	Multi-DB engine (SQLite, PostgreSQL), migrations, ORM
`cache`	24	15	📖	⚙️	📜	Multi-backend caching (Redis, memory, disk), TTL, LRU
`data_lineage`	6	3	📖	⚙️	📜	Data flow tracking, lineage graphs, provenance
`serialization`	7	10	📖	⚙️	📜	JSON, YAML, MessagePack, Protobuf serialization
`documents`	39	16	📖	⚙️	📜	Document processing (PDF, HTML, CSV, XML, Markdown)
`feature_store`	6	5	📖	⚙️	📜	ML feature registry, versioning, and serving
`agentic_memory`	53	47	📖	⚙️	📜	Long-term agent memory, retrieval, and knowledge graphs
`model_ops`	22	13	📖	⚙️	📜	ML model lifecycle, registry, versioning

🔒 Security & Identity Modules

Module	Py	Tests	Docs	Config	Scripts	Description
`security`	51	33	📖	⚙️	📜	Threat detection, vulnerability scanning, audit trails
`auth`	14	7	📖	⚙️	📜	OAuth, API key, JWT, RBAC authentication
`crypto`	37	27	📖	⚙️	📜	Cryptographic primitives, hashing, key management
`encryption`	13	4	📖	⚙️	📜	AES-GCM, signing, KDF, HMAC, key rotation
`privacy`	5	5	📖	⚙️	📜	PII detection, data anonymization, compliance
`defense`	4	6	📖	—	—	Adversarial defense and input sanitization
`identity`	6	6	📖	⚙️	📜	Digital identity, persona management, biocognitive auth
`wallet`	18	7	📖	⚙️	📜	Cryptocurrency wallet, key storage, transaction signing

🎨 Multimedia & Visualization Modules

Module	Py	Tests	Docs	Config	Scripts	Description
`audio`	22	13	📖	⚙️	📜	TTS (edge-tts, pyttsx3), audio processing, transcription
`video`	15	8	📖	⚙️	📜	Video processing, frame extraction, Veo 2.0 generation
`multimodal`	3	4	📖	⚙️	📜	Imagen 3 image generation, multi-modal AI pipelines
`data_visualization`	79	28	📖	⚙️	📜	Matplotlib, Plotly, chart generation, dashboards
`meme`	58	19	📖	⚙️	📜	Meme generation, template engine, social media formatting
`spatial`	18	8	📖	⚙️	📜	3D/4D geometry, coordinate transforms, physics and rendering

🏠 Personal AI (PAI) Modules

Module	Py	Tests	Docs	Config	Scripts	Description
`email`	14	8	📖	⚙️	📜	Gmail, AgentMail providers, SMTP, IMAP
`calendar_integration`	6	3	📖	⚙️	📜	Google Calendar CRUD, event management, scheduling
`finance`	13	5	📖	⚙️	📜	Ledger, payroll, forecasting, tax calculation
`website`	18	23	📖	⚙️	📜	PAI dashboard server, health monitoring, proxying
`market`	5	4	📖	⚙️	📜	Market data, trading signals, portfolio analysis
`logistics`	31	10	📖	⚙️	📜	Task routing, supply chain, resource allocation
`relations`	19	7	📖	⚙️	📜	Contact management, relationship mapping, CRM
`physical_management`	10	7	📖	⚙️	📜	IoT device tracking, physical asset management

🛠️ Developer Tooling Modules

Module	Py	Tests	Docs	Config	Scripts	Description
`cli`	26	7	📖	⚙️	📜	Rich CLI with subcommands for all modules
`ide`	20	12	📖	⚙️	📜	VS Code, Cursor, Antigravity IDE integrations
`git_operations`	34	22	📖	⚙️	📜	Full Git CLI wrapper (branch, merge, stash, submodules)
`git_analysis`	5	5	📖	⚙️	📜	Commit analysis, contributor stats, code churn
`tree_sitter`	12	2	📖	⚙️	📜	AST parsing, code navigation, structural queries
`static_analysis`	4	9	📖	⚙️	📜	Linting, complexity metrics, dead code detection
`terminal_interface`	18	6	📖	⚙️	📜	Rich terminal UI, ANSI rendering, interactive prompts
`scrape`	12	12	📖	⚙️	📜	Web scraping, HTML parsing, sitemap crawling
`search`	6	4	📖	⚙️	📜	Full-text search, fuzzy matching, regex search

⚙️ Configuration & Operations Modules

Module	Py	Tests	Docs	Config	Scripts	Description
`config_management`	17	16	📖	⚙️	📜	Hierarchical config loading, validation, hot-reload
`config_monitoring`	4	3	📖	⚙️	📜	Configuration drift detection and alerting
`config_audits`	5	4	📖	⚙️	📜	Configuration compliance auditing and rule engine
`environment_setup`	5	5	📖	⚙️	📜	Dependency resolution, environment validation
`logging_monitoring`	17	6	📖	⚙️	📜	Structured logging, metrics collection, alerting
`telemetry`	32	20	📖	⚙️	📜	OpenTelemetry traces, spans, exporters
`performance`	20	5	📖	⚙️	📜	Benchmarking, profiling, performance visualization
`maintenance`	12	4	📖	⚙️	📜	Health checks, cleanup, system diagnostics
`release`	8	5	📖	⚙️	📜	Release management, changelog generation, versioning

🧩 Framework & Utility Modules

Module	Py	Tests	Docs	Config	Scripts	Description
`utils`	20	17	📖	⚙️	📜	CLI helpers, string ops, file utils, decorators
`validation`	19	12	📖	⚙️	📜	Schema validation, data contracts, type checking
`exceptions`	13	7	📖	⚙️	📜	Exception hierarchy (AI, IO, Git, config)
`events`	30	17	📖	⚙️	📜	Event bus, pub/sub, event store, logging listeners
`plugin_system`	14	10	📖	⚙️	📜	Plugin discovery, lifecycle, dependency injection
`dependency_injection`	5	4	📖	⚙️	📜	IoC container, service locator, scoped lifetimes
`concurrency`	18	10	📖	⚙️	📜	Distributed locks, semaphores, Redis locking
`compression`	9	4	📖	⚙️	📜	gzip, zstd, brotli compression algorithms
`templating`	14	4	📖	⚙️	📜	Jinja2 templating, code generation templates
`feature_flags`	9	6	📖	⚙️	📜	Feature flag management, rollout strategies
`tool_use`	5	4	📖	⚙️	📜	Tool registration, execution, and discovery
`testing`	15	8	📖	⚙️	📜	Test fixtures, runners, coverage utilities
`documentation`	56	27	📖	⚙️	📜	Docusaurus site, docs generation, quality checks
`docs_gen`	5	4	📖	⚙️	📜	Automated documentation generation from source
`module_template`	2	6	📖	⚙️	📜	Canonical template for new module creation
`operating_system`	10	1	📖	⚙️	📜	OS interaction (macOS/Linux/Windows), filesystem
`file_system`	3	3	📖	⚙️	📜	File operations, directory walker, permissions
`dark`	5	4	📖	⚙️	📜	Dark PDF extraction and processing
`embodiment`	11	3	📖	—	—	ROS bridge, simulated sensors, and actuators
`demos`	3	1	📖	⚙️	📜	Demo registry and showcase runner
`formal_verification`	13	4	📖	⚙️	📜	Z3 backend, SMT solver, invariant checking
`system_discovery`	19	10	📖	⚙️	📜	System introspection, capability detection

🧬 ML Training & Optimization Modules

Module	Py	Docs	Description
`lora`	3	📖	LoRA fine-tuning adapters
`peft`	3	📖	Parameter-efficient fine-tuning
`rlhf`	3	📖	Reinforcement learning from human feedback
`dpo`	3	📖	Direct preference optimization
`distillation`	3	📖	Model distillation and compression
`quantization`	6	📖	Model quantization (INT8, FP16)
`distributed_training`	3	📖	Multi-GPU and distributed training
`autograd`	4	📖	Automatic differentiation engine
`matmul_kernel`	3	📖	Custom matrix multiplication kernels
`softmax_opt`	3	📖	Softmax optimization (FlashAttention-style)
`nas`	3	📖	Neural architecture search
`model_merger`	3	📖	Model merging (TIES, SLERP, DARE)
`slm`	3	📖	Small language model optimization
`ssm`	3	📖	State space models (Mamba)
`eval_harness`	3	📖	LLM evaluation harness
`logit_processor`	3	📖	Logit manipulation and processing
`tokenizer`	4	📖	Custom tokenizer training and management

🔗 Data Pipeline & Infrastructure Modules

Module	Py	Docs	Description
`api`	47	📖	REST/GraphQL API framework
`collaboration`	32	📖	Multi-agent collaboration protocols
`ml_pipeline`	2	📖	ML pipeline orchestration
`data_curation`	3	📖	Dataset curation and cleaning
`synthetic_data`	3	📖	Synthetic data generation
`text_to_sql`	3	📖	Natural language to SQL translation
`semantic_router`	3	📖	Semantic intent routing

🧩 Specialized Modules

Module	Py	Docs	Description
`ai_gateway`	3	📖	AI gateway and API proxy
`aider`	5	📖	Aider AI coding assistant integration
`neural`	7	📖	Neural network primitives
`interpretability`	3	📖	Model interpretability and explainability
`image`	2	📖	Image processing utilities
`examples`	13	📖	Reference implementation examples
`pai_pm`	7	📖	PAI Project Manager server (Bun/TypeScript)
`soul`	4	📖	Biocognitive identity and persona engine

🔬 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 612 merged-runtime tools (130 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/                   # Configuration templates; see inventory for measured files
├── docs/                     # 1,204 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
│   └── ... (16 directories)
├── scripts/                  # 445+ orchestrator scripts
│   ├── agents/               # Jules batch dispatch, harvester
│   ├── maintenance/          # Config generation, health checks
│   └── ... (90+ module scripts)
├── src/codomyrmex/           # Main source (130 modules)
│   ├── agents/               # 285 files
│   ├── llm/                  # 65 files
│   ├── security/             # 51 files
│   └── ... (127 more modules)
├── CHANGELOG.md              # Release history
├── CITATION.cff              # Citation metadata
└── pyproject.toml            # uv-managed project config (uv_build backend)

📊 Aggregate Statistics

Metric	Value
Total Modules	130 (top-level under `src/codomyrmex/`)
Total Python Files	3,000+
Collected tests	36,049 in the current project environment (`uv run python scripts/doc_inventory.py --pytest`)
Documentation Files	1,204 (`*.md` under `docs/`; see inventory)
GitHub Workflows	37
Runtime MCP Tools	612 (merged PAI manifest in the complete locked dependency profile; distinct from 627 production decorator lines)
`mcp_tools.py` files	151 (non-test)
PAI Skills	81 installed
RASP Doc Compliance	Measured by the structure validator; see CI artifacts
Ruff / ty	Run locally; targets in `pyproject.toml`
Testing Policy	Zero-Mock (100% real methods)
Coverage Gate	60% (`fail_under` in `pyproject.toml`; CI + `make test` use `--cov-fail-under=60`; plain `uv run pytest` skips `--cov`; `meme/` omitted from coverage run)
Default LLM	Gemini 2.5 Pro
Package Manager	uv
Python Version	3.11 – 3.14

🔌 LLM Provider Matrix

Provider	Model	Status	Free Tier	Streaming	Tool Use
Google Gemini	gemini-2.5-pro	✅	✅	✅	✅
Google Imagen	imagen-3.0-generate-002	✅	❌	—	—
Google Veo	veo-2.0-generate-001	✅	❌	—	—
OpenRouter	Llama 3.3 70B	✅	✅	✅	✅
OpenRouter	DeepSeek R1	✅	✅	✅	✅
OpenRouter	Google Gemma 3	✅	✅	✅	✅
Anthropic	Claude 3.5 Sonnet	✅	❌	✅	✅
OpenAI	GPT-4o	✅	❌	✅	✅
OpenAI	o1 / o3-mini	✅	❌	✅	✅
Perplexity	sonar-pro	✅	❌	✅	—
Ollama	any local model	✅	✅	✅	✅
Claude 3.7	claude-3-7-sonnet	✅	❌	✅	✅

🤖 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 - 130"]
        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 tests/ -v --tb=short

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

# Lint and format
uv run ruff check .          # lint
uv run ruff format .         # format
uv run ty check --output-format concise src/ scripts/ tests/  # type check

🗺️ Configuration Architecture

See config/ for configuration templates and module-specific settings; counts are maintained in the inventory.

graph TB
    subgraph ConfigRoot["config/"]
        C1["agents/config.yaml"]
        C2["llm/config.yaml"]
        C3["security/config.yaml"]
        Cdots["... see measured inventory"]
    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 --locked --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 tests/ -v --tb=short

# 7. Lint & type-check
uv run ruff check . && uv run ruff format . && uv run ty check --output-format concise src/ scripts/ tests/

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

# 9. Dispatch AI agents
uv run python scripts/agents/jules/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:

Document	Purpose	Links
`README.md`	Human-readable overview	Root README, Docs README
`AGENTS.md`	Agent-readable instructions	Root AGENTS, Docs AGENTS
`SPEC.md`	Technical specification	Root SPEC, Docs SPEC
`PAI.md`	Personal AI integration	Root PAI, Docs PAI

🏗️ `.github/` Directory Overview

This directory powers the GitHub-hosted infrastructure for Codomyrmex.

Workflows (37 total)

Category	Workflows	Description
Core CI/CD	ci.yml, security.yml, release.yml, pre-commit.yml	Lint, full Unix tests, Windows portability, security scan, release
Code Quality	code-health.yml, benchmarks.yml, documentation.yml, documentation-validation.yml	Quality gates, benchmarks, docs
PR Automation	auto-merge.yml, pr-labeler.yml, pr-title-check.yml, pr-conflict-check.yml, pr-coverage-comment.yml, pr-linter-comments.yml	Auto-merge, labeling, coverage
AI Dispatch	gemini-dispatch.yml, gemini-invoke.yml, gemini-review.yml, gemini-triage.yml, gemini-scheduled-triage.yml, jules-dispatch.yml	Gemini and Jules agent orchestration
Maintenance	maintenance.yml, cleanup-branches.yml, lock-threads.yml, workflow-coordinator.yml, workflow-status.yml	Repo health, branch cleanup, status
Community	first-interaction.yml, first-pr-merged.yml, agent-welcome.yml, agent-metrics.yml	Onboarding, agent welcome
Dependencies	dependency-review.yml, dependabot-auto-approve.yml, sbom.yml	Dep review, SBOM generation

Community & Configuration Files

File	Purpose
CONTRIBUTING.md	Contributor guide with PR process and code standards
CODEOWNERS	Auto-assignment of reviewers by file path
PULL_REQUEST_TEMPLATE.md	Standard PR checklist
ISSUE_TEMPLATE/	Bug reports, feature requests, Jules tasks, docs issues
dependabot.yml	Automated dependency update configuration
release-drafter.yml	Auto-generated release notes
FUNDING.yml	GitHub Sponsors configuration
WORKFLOW_IMPROVEMENTS.md	Planned workflow enhancements
WORKFLOW_TESTING_GUIDE.md	Guide for testing GitHub Actions locally

🤝 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 60% 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 --output-format concise src/ scripts/ tests/ before submitting

📜 License

MIT License — see LICENSE for details.

Built with 🐜 Codomyrmex — The Autonomous Software Colony
_{130 modules · 612 runtime MCP tools · 627 decorators · 36,049 tests · 1,204 docs · 37 workflows · Zero-Mock · Evidence-scoped}

Name		Name	Last commit message	Last commit date
.agent		.agent
.agents		.agents
.claude/skills		.claude/skills
.codex		.codex
.cursor/skills		.cursor/skills
.devcontainer		.devcontainer
.github		.github
.jules		.jules
.pipelines		.pipelines
.workflows		.workflows
config		config
data		data
docs		docs
evaluations		evaluations
examples		examples
output		output
projects		projects
scripts		scripts
src		src
tests		tests
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
.gitnexusignore		.gitnexusignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
ASSUMPTION_REGISTER.md		ASSUMPTION_REGISTER.md
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
FUNDING.md		FUNDING.md
INDEX.md		INDEX.md
LICENSE		LICENSE
MODULES.md		MODULES.md
Makefile		Makefile
PAI.md		PAI.md
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
RULES.md		RULES.md
SECURITY.md		SECURITY.md
SKILL.md		SKILL.md
SPEC.md		SPEC.md
TODO.md		TODO.md
docker-compose.yml		docker-compose.yml
index.html		index.html
justfile		justfile
mkdocs.yml		mkdocs.yml
package.json		package.json
pyproject.toml		pyproject.toml
skill.json		skill.json
start_here.sh		start_here.sh
update_tests.py		update_tests.py
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

🐜 Codomyrmex

📋 Table of Contents

✨ Why Codomyrmex?

📚 Documentation Hub

Top-Level Documents

Documentation Directories

📐 System Architecture

🗂️ Complete Module Inventory

🧠 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

🚀 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/ Directory Overview

Workflows (37 total)

Community & Configuration Files

🤝 Contributing

📜 License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

🏗️ `.github/` Directory Overview