🐜 Codomyrmex

A comprehensive, modular, agentic Python ecosystem for autonomous software engineering, personal AI infrastructure, and multi-agent orchestration.

Codomyrmex is a production-grade library of 128 deeply integrated modules 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 includes 3,000+ Python files, 1,023+ test files, 1,029+ documentation pages, and 36 GitHub Actions workflows.

---

📚 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/	126 dirs	Per-module documentation (README, SPEC, AGENTS, PAI per module)
docs/agents/	4	Agent rules, coordination, autonomous operation
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/	1	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

Loading

---

🗂️ Complete Module Inventory

Every module links directly to its source, docs, config, and scripts directories.

🧠 Core Intelligence Modules

Module	Py	Tests	Docs	Config	Scripts	Description
agents	168	83	📖	⚙️	📜	Multi-provider agent framework (Gemini, Claude, OpenAI, Jules)
cerebrum	32	13	📖	⚙️	📜	Cognitive reasoning engine with chain-of-thought & decision trees
llm	41	20	📖	⚙️	📜	LLM subsystem with OpenRouter, Gemini 2.5 Pro, streaming
orchestrator	46	20	📖	⚙️	📜	Workflow engine, pipeline execution, parallel orchestration
model_context_protocol	27	9	📖	⚙️	📜	MCP tool server, bridge, and protocol implementation
prompt_engineering	10	7	📖	⚙️	📜	Template management, prompt optimization, few-shot patterns
skills	22	11	📖	⚙️	📜	Extensible skill registry and execution engine

🤖 AI & Machine Learning Modules

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

☁️ Infrastructure & DevOps Modules

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

💾 Data & Storage Modules

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

🔒 Security & Identity Modules

Module	Py	Tests	Docs	Config	Scripts	Description
security	47	16	📖	⚙️	📜	Threat detection, vulnerability scanning, audit trails
auth	13	4	📖	⚙️	📜	OAuth, API key, JWT, RBAC authentication
crypto	37	26	📖	⚙️	📜	Cryptographic primitives, hashing, key management
encryption	12	3	📖	⚙️	📜	AES-GCM, signing, KDF, HMAC, key rotation
privacy	4	2	📖	⚙️	📜	PII detection, data anonymization, compliance
defense	4	5	📖	⚙️	📜	Adversarial defense, input sanitization (deprecated)
identity	5	4	📖	⚙️	📜	Digital identity, persona management, biocognitive auth
wallet	16	3	📖	⚙️	📜	Cryptocurrency wallet, key storage, transaction signing

🎨 Multimedia & Visualization Modules

Module	Py	Tests	Docs	Config	Scripts	Description
audio	15	5	📖	⚙️	📜	TTS (edge-tts, pyttsx3), audio processing, transcription
video	12	4	📖	⚙️	📜	Video processing, frame extraction, Veo 2.0 generation
multimodal	2	3	📖	⚙️	📜	Imagen 3 image generation, multi-modal AI pipelines
data_visualization	68	20	📖	⚙️	📜	Matplotlib, Plotly, chart generation, dashboards
meme	57	6	📖	⚙️	📜	Meme generation, template engine, social media formatting
spatial	12	3	📖	⚙️	📜	Geospatial data, coordinate systems, mapping

🏠 Personal AI (PAI) Modules

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

🛠️ Developer Tooling Modules

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

⚙️ Configuration & Operations Modules

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

🧩 Framework & Utility Modules

Module	Py	Tests	Docs	Config	Scripts	Description
utils	17	15	📖	⚙️	📜	CLI helpers, string ops, file utils, decorators
validation	16	7	📖	⚙️	📜	Schema validation, data contracts, type checking
exceptions	13	2	📖	⚙️	📜	Comprehensive exception hierarchy (AI, IO, Git, Config)
events	29	7	📖	⚙️	📜	Event bus, pub/sub, event store, logging listeners
plugin_system	12	7	📖	⚙️	📜	Plugin discovery, lifecycle, dependency injection
dependency_injection	4	2	📖	⚙️	📜	IoC container, service locator, scoped lifetimes
concurrency	17	5	📖	⚙️	📜	Distributed locks, semaphores, Redis locking
compression	8	1	📖	⚙️	📜	gzip, zstd, brotli compression algorithms
templating	8	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	7	📖	⚙️	📜	Test fixtures, runners, coverage utilities
documentation	45	10	📖	⚙️	📜	Docusaurus site, docs generation, quality checks
docs_gen	4	2	📖	⚙️	📜	Automated documentation generation from source
module_template	2	5	📖	⚙️	📜	Canonical template for new module creation
operating_system	10	1	📖	⚙️	📜	OS interaction (macOS/Linux/Windows), filesystem
file_system	2	2	📖	⚙️	📜	File operations, directory walker, permissions
dark	4	2	📖	⚙️	📜	Dark PDF extraction and processing
embodiment	9	1	📖	⚙️	📜	ROS bridge, sensors, actuators (deprecated)
demos	2	1	📖	⚙️	📜	Demo registry and showcase runner
formal_verification	8	2	📖	⚙️	📜	Z3 backend, SMT solver, invariant checking
system_discovery	14	4	📖	⚙️	📜	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	5	📖	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	31	📖	REST/GraphQL API framework
collaboration	30	📖	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	9	📖	Reference implementation examples
pai_pm	6	📖	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

Loading

---

🚀 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 ~474 tools across 129 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

Loading

---

🏗️ Project Structure

codomyrmex/
├── .github/                  # 36 GitHub Actions workflows, templates, docs
├── config/                   # 128 module-specific config.yaml files
├── docs/                     # 1,029+ documentation files across 18 directories
│   ├── 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/              # 126 per-module doc directories
│   ├── 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

Metric	Value
Total Modules	128
Total Python Files	3,000+
Total Test Files	1,023+
Documentation Files	1,029+
GitHub Workflows	36
MCP Tools	474
Testing Policy	Zero-Mock (100% real methods)
Default LLM	Gemini 2.5 Pro
Package Manager	uv
Python Version	≥3.11

---

🔌 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	✅	❌	✅	✅

---

🤖 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

Loading

---

🧪 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

Loading

# 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

Loading

---

🏠 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

Loading

---

⚡ Quick Start

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

# Install (all dev dependencies)
uv sync --all-groups

# Set up environment
cp .env.example .env   # Edit with your API keys

# Run CLI
uv run codomyrmex --help

# Run tests
uv run pytest src/codomyrmex/tests/ -v

# Lint & format
uv run ruff check . && uv run ruff format .

# Dispatch Jules agents
uv run python scripts/agents/mega_swarm_dispatcher.py

See docs/getting-started/ for the full guide.

---

📋 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 (36 total)

Category	Workflows	Description
Core CI/CD	ci.yml, security.yml, release.yml, pre-commit.yml	Lint, test, 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

---

📜 License

MIT License — see LICENSE for details.

---

Built with 🐜 Codomyrmex — The Autonomous Software Colony
_{129 modules · 3,000+ Python files · 1,023+ tests · 1,029+ docs · 36 workflows · Zero-Mock · Production-Grade}