Codomyrmex v0.1.2: 78-Module Python Toolbox Bridging PAI to Scientific Computing via MCP

[docxology]

We built Codomyrmex (v0.1.2) as an open-source, modular Python development platform — 78 specialized modules that PAI agents consume via MCP. Here's what that looks like concretely.

The Architecture

PAI is the cognitive layer (TypeScript/Bun, ~/.claude/). Codomyrmex is the tool layer (Python, installable via uv). MCP connects them:

PAI (Algorithm v1.5.0 + 38 Skills + 20 Hooks + 13 Agents + 3-tier Memory)
  |
  |  MCP Protocol (stdio or HTTP)
  v
Codomyrmex (78 Python modules)
  |-- PAIBridge      -> reads PAI's own filesystem to discover skills, hooks, agents, memory
  |-- MCP Bridge     -> exposes 18 static tools + auto-discovered module tools
  +-- Trust Gateway  -> gates destructive ops behind explicit approval (UNTRUSTED -> VERIFIED -> TRUSTED)

Source: docs/pai/architecture.md — full component diagram and data flow

What PAI Provides: Cognitive Augmentation

Without PAI, an agent is a stateless function caller. PAI provides the cognitive scaffold:

PAI Component	What It Gives the Agent	Scale
The Algorithm (v1.5.0)	7-phase method: OBSERVE, THINK, PLAN, BUILD, EXECUTE, VERIFY, LEARN	Every prompt
Ideal State Criteria	Binary-testable verification targets — the agent knows when it's done	4-500+ per task
Identity (TELOS)	Who the user is, what matters, what the agent learned last time	Persistent
Memory (WORK/STATE/LEARNING)	Three-tier state that survives across sessions	Persistent
Skills (38)	Domain-specific sub-algorithms (Research, RedTeam, Council, Browser, etc.)	Composable
Hooks (20)	Event-driven behavioral gates (voice, capability recommendation, security)	Automatic
Named Agents (13+)	Typed personalities: Engineer, Architect, Researcher, QATester — each with tools and voice	Parallelizable

This is the "nestmate" augmentation: PAI turns a generic LLM session into a situated agent with method, memory, and judgment.

What Codomyrmex Provides: The Bridge from NL to Tools

Codomyrmex is the continuum from natural language intent to deterministic tool execution:

Natural Language (user prompt)
  -> PAI Algorithm (capability selection, ISC creation)
    -> MCP Bridge (tool routing, trust enforcement)
      -> Codomyrmex Modules:
          coding/static_analysis/  -> PyRefly, Ruff, security scanning
          git_operations/          -> version control automation
          data_visualization/      -> matplotlib charts, reports
          orchestrator/            -> workflow DAG execution
          security/                -> vulnerability scanning, governance
          llm/                     -> multi-provider LLM infrastructure
          agentic_memory/          -> persistent knowledge stores
          cerebrum/                -> case-based reasoning
          ... (78 total)

Every module follows the RASP pattern — README.md, AGENTS.md, SPEC.md, PAI.md — so AI agents can discover what each module offers without parsing source code.

Source: PAI.md — the authoritative bridge document

Algorithm Phase to Module Mapping

Each phase of PAI's Algorithm routes to specific Codomyrmex tools:

Algorithm Phase	Codomyrmex Modules	Example Tool Calls
OBSERVE	system_discovery, search, pattern_matching	list_modules, search_codebase
THINK	cerebrum, graph_rag, agents/theory/	analyze_python, module_info
PLAN	orchestrator, logistics	read_file, json_query
BUILD	coding, agents/ai_code_editing/	write_file
EXECUTE	agents (all providers), git_operations	run_command, run_tests
VERIFY	coding/static_analysis/, security	git_diff, checksum_file
LEARN	agentic_memory, logging_monitoring	pai_awareness, pai_status

Source: docs/pai/workflows.md — bidirectional data flow details

Nesting, Recursion, and Self-Reference

The architecture is reflexive by design:

1. PAIBridge introspects PAI itself. The pai_bridge.py module reads ~/.claude/skills/PAI/SKILL.md, enumerates all skills/hooks/agents/memory stores, and exposes them as structured data. PAI can query its own configuration through Codomyrmex.

2. The MCP Bridge is self-discovering. mcp_bridge.py auto-discovers tools from every module at runtime via discover_all_public_tools(). Add a module, and its functions appear as MCP tools — no registration step.

3. The Trust Gateway gates itself. trust_gateway.py enforces a three-tier model (UNTRUSTED -> VERIFIED -> TRUSTED) where the /codomyrmexVerify and /codomyrmexTrust workflows — themselves exposed via the MCP bridge — control which tools are executable. The verification workflow audits the trust system using the trust system.

4. Universal module proxy. Three meta-tools (list_module_functions, call_module_function, get_module_readme) let a PAI agent discover and invoke any public function from any of the 78 modules — without those modules knowing they're being called via MCP. The tool layer is transparent to itself.

This recursive structure means PAI agents can inspect, extend, and reason about the toolbox they're using — while using it.

Concrete Numbers (v0.1.2)

What	Count
Python modules	78
Static MCP tools	18 (14 safe + 4 destructive)
MCP resources	2
MCP prompts	10
PAI bridge dataclasses	7
Bridge API methods	22
Test suite	25 passing, 5 skipped
RASP docs per module	4 (README, AGENTS, SPEC, PAI)

Get Started

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

Then connect to PAI via MCP.

Full integration docs: docs/pai/ — architecture, tools reference, API, workflows