Skip to content

Codex Bridge

This repo uses a multi-session protocol. Read SWARM.md for the full protocol. See SWARM.md §Common Bridge Items for signaling, soft-claim, contract validation, concurrent-safe commit, safety, and human interaction protocols. See SWARM.md §Minimum Cycle for the orient→act→compress→handoff loop.

Hard rules (structural, MC-SAFE / I9)

  • No force push. git push --force is HIGH risk. Regular push is LOW.
  • No mass deletion. >20 staged deletions = FAIL in check.sh.
  • No plan mode. orient→act→compress IS the planning mechanism (L-1160).
  • Commit format: [S<N>] what: why — pre-commit hook enforces.
  • Lesson format: max 20 lines, strict header (# L-NNN:); see SWARM.md §step 7.
  • NEVER-REMOVE atom: beliefs/CORE.md, tools/validate_beliefs.py (FM-10).

Swarm Signaling

  • Follow SWARM.md §Swarm Signaling and §Common Bridge Items for swarm signaling: post structured updates with python3 tools/swarm_signal.py post ... and keep tasks/NEXT.md, tasks/SWARM-LANES.md, and related shared state current while you work.

Minimum Swarmed Cycle

  • Follow SWARM.md §Minimum Cycle: run python3 tools/orient.py, python3 tools/task_order.py, python3 tools/question_gen.py, and python3 tools/dispatch_optimizer.py; check recent commits before acting; declare check_mode plus expectation; act, diff, and compress; then finish with python3 tools/sync_state.py, python3 tools/validate_beliefs.py, python3 tools/cell_blueprint.py save, and git push.
  • If the preferred runtime is unavailable, use the documented PowerShell or shell fallbacks from SWARM.md.

Codex specifics

  • Tooling (S712, no MCP): you lack Claude's native HF MCP / WebSearch / worktree tools. Forage with the portable fallback python3 tools/hf_search.py --kind papers|models|datasets|spaces --query "…" --out …; for concurrent writes use claim.py + safe_commit.py (explicit paths, never git add -A). Claude GM uses the native equivalents. See .claude/commands/forage.md and SWARM.md §Coordination coupling policy.
  • Parallel agents: Use sub-agent spawning for independent sub-tasks when the write scopes are disjoint.
  • Entry: This file is the dedicated Codex entry point. SWARM.md is the canonical protocol.
  • Compatibility: AGENTS.md remains in the repo as a compatibility bridge for tools that still look for that filename.

Multi-tool compatibility (F118)

Core state (beliefs, lessons, principles, frontiers) is tool-agnostic markdown + git. Entry files: CLAUDE.md (Claude Code), CODEX.md (Codex), AGENTS.md (agents-format compatibility), .cursor/rules/swarm.mdc + .cursorrules (Cursor), GEMINI.md (Gemini), .windsurfrules (Windsurf), .github/copilot-instructions.md (Copilot). Each bridge file loads SWARM.md and adds tool-specific instructions.