CLAUDE.md

Version: v1.3.0 | Last Updated: October 2026

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Development Commands

# Install dependencies (uv recommended)
uv sync

# Set up git submodules (run once after cloning, or after submodule updates)
# Initializes all 5 submodules and installs hermes/evolution Python deps
bash scripts/setup_submodules.sh
# Or via Makefile:
make submodules   # submodules only
make setup        # install + submodules together

# NOTE: Never run `uv sync` inside src/codomyrmex/agents/hermes/evolution/ —
# its `darwinian` optional extra requires a non-PyPI package and will fail locking.
# The setup script handles this correctly via `uv venv --seed` + pip.

# Install with optional module dependencies
uv sync --extra <module-name>    # e.g., uv sync --extra spatial
uv sync --all-extras             # Install all optional dependencies

# Run all tests (no coverage — fast default)
uv run pytest

# Run tests with coverage and the 60% gate (same idea as `make test`).
# Makefile exports HYPOTHESIS_NO_NPY=1; for raw pytest, prefix the command so Hypothesis
# initializes before conftest (see tests/RUNNING_TESTS.md).
HYPOTHESIS_NO_NPY=1 uv run pytest --cov=src/codomyrmex --cov-report=html --cov-fail-under=60

# Pre-tag / release checklist: ruff + ty + full test tree with 60% coverage floor
make verify-release

# Run specific test file or module
uv run pytest tests/unit/<module>/test_<module>.py
uv run pytest -k "test_name"     # Run tests matching pattern

# Code formatting and linting
uv run ruff format src/
uv run ruff check src/
uv run ty check src/

# CLI usage
codomyrmex --help
codomyrmex check                 # Verify environment setup
codomyrmex modules               # List available modules
codomyrmex status                # System status dashboard
codomyrmex shell                 # Interactive shell
codomyrmex workflow list         # List workflows
codomyrmex project list          # List projects
codomyrmex ai generate           # AI code generation
codomyrmex analyze <path>        # Code analysis
codomyrmex build <path>          # Project build
codomyrmex test <module>         # Run module tests
codomyrmex fpf fetch <url>       # FPF fetch/parse/export
codomyrmex skills list           # Skill management

Security Scanning

We use ggshield (GitGuardian) to prevent secret leaks.

# Install ggshield globally via uv
uv tool install ggshield

# Authenticate with GitGuardian
ggshield auth login

# Scan the entire repository for secrets
ggshield scan repo .

# Scan the current staging area before committing
ggshield scan pre-commit

Architecture Overview

Codomyrmex is a modular development platform with 132 top-level modules under src/codomyrmex/ organized in a layered architecture (see docs/reference/inventory.md):

Layer Hierarchy (dependencies flow upward only)

1. Foundation Layer - Core infrastructure used by all modules:
   • logging_monitoring - Centralized structured logging
   • environment_setup - Environment validation, dependency checking
   • model_context_protocol - Standardized LLM communication interfaces
   • terminal_interface - Rich terminal output and formatting
2. Core Layer - Primary capabilities:
   • agents - AI agent framework integrations
   • static_analysis - Code quality, linting, security scanning (in coding/static_analysis/)
   • coding - Code execution sandbox and review
   • llm - LLM infrastructure (Ollama, providers)
   • pattern_matching - Code pattern recognition (in coding/pattern_matching/)
   • git_operations - Version control automation
3. Service Layer - Higher-level orchestration:
   • ci_cd_automation - Pipeline management (includes build automation)
   • documentation - Doc generation
   • containerization - Docker/K8s management
   • orchestrator - Workflow execution
4. Application Layer - User interfaces:
   • cli - Command-line interface (entry point: src/codomyrmex/cli/core.py)
   • system_discovery - Module discovery and health monitoring

Module Structure

Each module is self-contained with standard structure:

• __init__.py - Module exports
• README.md - Module documentation
• API_SPECIFICATION.md - Programmatic interfaces
• MCP_TOOL_SPECIFICATION.md - Model Context Protocol tool definitions
• tests/ - Module-specific tests (unit tests in tests/unit/<module>/)

Key Patterns

• Model Context Protocol (MCP): Standardized interface for AI/LLM integration across modules
• Upward dependencies only: Higher layers depend on lower, preventing circular dependencies
• Lazy module loading: Modules load on-demand to reduce startup time
• Auto-discovery: Modules with an mcp_tools.py submodule using @mcp_tool decorators are automatically discovered and surfaced via the PAI MCP bridge — no manual registration needed. Currently 154 mcp_tools.py files are under src/codomyrmex/ (non-test); see docs/reference/inventory.md.

Extended Modules (auto-discovered via MCP)

Beyond the core layers above, these modules expose MCP tools via @mcp_tool decorators:

• formal_verification - Z3 constraint solving and model checking
• containerization - Docker build, scan, and runtime management
• crypto - Key generation, hashing, hash verification
• events - Event bus with emit, history, and type registry
• search - Full-text, fuzzy, and indexed search
• config_management - Get/set/validate configuration
• cloud - Cloud instance and S3 bucket management
• cerebrum - Case-based reasoning and knowledge retrieval
• performance - Benchmark comparison and regression detection
• scrape - HTML content extraction and text similarity
• maintenance - Health checks and task management
• plugin_system - Plugin discovery and dependency resolution
• relations - Relationship strength scoring
• agents/core - ThinkingAgent reasoning traces and depth control
• agentic_memory - Agent memory store, retrieve, and semantic search
• calendar_integration - Calendar event management and scheduling
• data_visualization - Chart/dashboard generation and HTML export
• email - AgentMail inbox/message/thread management and webhook registration
• git_analysis - Git history analysis, contributor stats, and commit pattern detection
• logging_monitoring - Centralized structured logging and monitoring integration
• collaboration - Multi-user session management and collaborative editing
• documentation - Documentation generation, linting, and publishing workflows
• security - Vulnerability scanning, secret detection, and security auditing
• skills - Skill discovery, listing, and invocation management
• validation - Schema validation, config validation, and validation summaries

PAI Integration

Codomyrmex serves as the toolbox for the PAI system (~/.claude/PAI/). Key integration points:

• Detection: PAI is present when ~/.claude/PAI/SKILL.md exists
• MCP Bridge: src/codomyrmex/agents/pai/mcp_bridge.py exposes 9 static proxy tools + auto-discovered module tools via pkgutil scan of all mcp_tools.py submodules; production sources contain 632 @mcp_tool lines and 154 mcp_tools.py files (132 top-level packages). See docs/reference/inventory.md. The Codomyrmex PAI Skill surfaces dynamic tools with 3 resources and 10 prompts
• Trust Gateway: src/codomyrmex/agents/pai/trust_gateway.py gates destructive tools (write, execute) behind explicit trust
• Workflows: /codomyrmexVerify audits capabilities; /codomyrmexTrust enables destructive tools
• RASP Pattern: Each module has PAI.md alongside README.md, AGENTS.md, SPEC.md — these describe AI capabilities the module offers
• Bridge Doc: /PAI.md is the authoritative document mapping the PAI Algorithm phases to codomyrmex modules
• Agent Mapping: PAI subagent types (Engineer, Architect, QATester) consume codomyrmex agent providers and tools — see src/codomyrmex/agents/PAI.md
• Detailed Reference: docs/pai/ — Architecture, tools, API, workflows for PAI-Codomyrmex integration

Key PAI system references (in ~/.claude/PAI/):

• SKILL.md — Algorithm CORE (v3.5.0)
• PAIAGENTSYSTEM.md — Agent types and delegation
• SKILLSYSTEM.md — Skill architecture
• THEHOOKSYSTEM.md — Hook event patterns

Test Markers

Tests use pytest markers defined in pyproject.toml ([tool.pytest.ini_options]):

• @pytest.mark.unit - Unit tests
• @pytest.mark.integration - Integration tests
• @pytest.mark.slow - Long-running tests
• @pytest.mark.performance - Performance and benchmarking tests
• @pytest.mark.examples - Example validation tests
• @pytest.mark.network - Tests requiring network
• @pytest.mark.database - Tests requiring database access
• @pytest.mark.external - Tests requiring external services
• @pytest.mark.security - Security-related tests
• @pytest.mark.asyncio - Asynchronous tests
• @pytest.mark.crypto - Cryptography tests
• @pytest.mark.orchestrator - Orchestrator/workflow tests

Run specific categories: uv run pytest -m unit

Zero-Mock Policy

This project follows a strict zero-mock/stub/fallback/hardcoded policy:

• No mocking: Tests never use unittest.mock, MagicMock, or pytest-mock. External dependencies use @pytest.mark.skipif guards. Narrow monkeypatch use is allowed for environment-variable isolation (setenv/delenv), chdir, and tmp_path fixtures — not for replacing methods with stubs. See docs/development/testing-strategy.md § Zero-Mock Policy (clarified) and issue #175.
• No production stubs: Production code never returns placeholder/fake data. Unimplemented features raise NotImplementedError.
• No silent fallbacks: Fallback patterns that silently degrade functionality are prohibited. Failures must be explicit.
• No hardcoded values: URLs, ports, and connection strings use os.getenv() with centralized defaults from config_management.defaults.
• No obsolete aliases: Compatibility layers must have documented deprecation timelines or be removed.

Hard-Right Execution Standard

Codomyrmex agents should bias toward the hard right thing over the easy option:

• Prefer real measurements, benchmarks, and full test runs over estimates or assumptions.
• Favour changes that are reversible, well-documented, and auditable, even if they take longer to implement.
• Never trade away correctness, safety, or clarity for short-term convenience or minor performance wins.

Test Skip Policy

Use @pytest.mark.skipif for tests requiring: network access, API keys, or heavy SDKs not installed. Never skip tests for core codomyrmex modules — use uv sync --extra <module> instead. Pattern: skip at module level (not per-test) to keep collection fast.

Dependency Management

All dependencies are managed in pyproject.toml:

• Core dependencies: [project.dependencies]
• Module-specific optional: [project.optional-dependencies.<module>]
• Development tools: [dependency-groups.dev]

Module-specific requirements.txt files are not maintained; do not modify them.

Multi-Agent Git Coordination

When multiple Claude Code instances or AI agents run concurrently, git operations can conflict on .git/index.lock. Follow these rules:

Rules

1. Use --no-verify for all agent commits — pre-commit hooks on 900+ files take 20+ minutes and block the lock
2. Atomic stage+commit: Always git add -A && git commit --no-verify in one shell command to minimize lock time
3. Check lock before writing: Run ls .git/index.lock 2>/dev/null before any git write operation
4. Clear stale locks: If no git process is running (ps aux | grep git) but lock exists > 60s, remove it: rm -f .git/index.lock
5. Large files: Check for files > 50MB before committing (find . -not -path './.git/*' -size +50M). GitHub rejects files > 100MB.
6. Use worktrees for parallel work: Run /codomyrmexWorktree for managed worktree creation — each gets its own index

Quick Reference

# Safe: read-only (no lock needed)
git status; git log; git diff; git show

# Unsafe: acquires lock — coordinate first
rm -f .git/index.lock && git add -A && git commit --no-verify -m "msg"

# Clean stale worktrees
git worktree prune && git branch --list 'worktree-agent-*' | xargs git branch -D 2>/dev/null

See /codomyrmexWorktree for detailed workflow.

GitNexus — Code Intelligence

This project is indexed by GitNexus as codomyrmex (207963 symbols, 302104 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.

Index stale? Run node .gitnexus/run.cjs analyze from the project root — it auto-selects an available runner. No .gitnexus/run.cjs yet? npx gitnexus analyze (npm 11 crash → npm i -g gitnexus; #1939).

Always Do

• MUST run impact analysis before editing any symbol. Before modifying a function, class, or method, run impact({target: "symbolName", direction: "upstream"}) and report the blast radius (direct callers, affected processes, risk level) to the user.
• MUST run detect_changes() before committing to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: detect_changes({scope: "compare", base_ref: "main"}).
• MUST warn the user if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
• When exploring unfamiliar code, use query({search_query: "concept"}) to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
• When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use context({name: "symbolName"}).
• For security review, explain({target: "fileOrSymbol"}) lists taint findings (source→sink flows; needs analyze --pdg).

Never Do

• NEVER edit a function, class, or method without first running impact on it.
• NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
• NEVER rename symbols with find-and-replace — use rename which understands the call graph.
• NEVER commit changes without running detect_changes() to check affected scope.

Resources

CLI

qmd Skill

This project is configured with the qmd skill for local hybrid search of Markdown notes and docs.

=== COGNILAYER (auto-generated, do not delete) ===

CogniLayer v3 Active

Persistent memory is ON. ON FIRST USER MESSAGE in this session, briefly tell the user: 'CogniLayer v3 active — persistent memory is on. Type /cognihelp for available commands.' Say it ONCE, keep it short, then continue with their request.

Memory Tools

You have access to the cognilayer MCP server:

• memory_search(query) — search memory semantically
• memory_write(content) — save important information
• file_search(query) — search project files (PRD, docs...)
• decision_log(query) — find past decisions

When unsure about context or project history, ALWAYS search memory first via memory_search. When you need info from PRD or docs, use file_search INSTEAD of reading the entire file.

VERIFY-BEFORE-ACT — MANDATORY

When memory_search returns a fact marked with ⚠ STALE:

1. ALWAYS read the source file and verify the fact still holds
2. If the fact changed -> update it via memory_write
3. NEVER make changes based on STALE facts without verification

PROACTIVE MEMORY — IMPORTANT

When you discover something important during work, SAVE IT IMMEDIATELY:

• Bug and fix -> memory_write(type="error_fix")
• Pitfall/danger -> memory_write(type="gotcha")
• Exact procedure -> memory_write(type="procedure")
• How components communicate -> memory_write(type="api_contract")
• Performance issue -> memory_write(type="performance")
• Important command -> memory_write(type="command") DO NOT wait for /harvest — session may crash.

RUNNING BRIDGE — CRITICAL

After completing each task AUTOMATICALLY update session bridge: session_bridge(action="save", content="Progress: ...; Open: ...") This is Tier 1 — do it yourself, don't announce, it's part of the job.

Safety Rules — MANDATORY

• Before ANY deploy, push, ssh, pm2, docker, db migration:
  1. ALWAYS call verify_identity(action_type="...") first
  2. If it returns BLOCKED — STOP and ask the user
  3. If it returns VERIFIED — READ the target server to the user and request confirmation

Git Rules

• Commit often, small atomic changes. Format: "[type] what and why"
• commit = Tier 1 (do it yourself). push = Tier 3 (verify_identity).

Project DNA: codomyrmex

Stack: unknown Style: [unknown] Structure: .agent, .benchmarks, .desloppify, .gemini, .github, .gitnexus, .mypy_cache, .pipelines Deploy: [NOT SET] Active: [new session] Last: [first session]

Last Session Bridge

[Emergency bridge — running bridge was not updated] No changes or facts in this session.

=== END COGNILAYER ===