Skip to content

Claude Code 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.

Claude Code specifics

  • Parallel agents: Use Task tool for independent sub-tasks.
  • Spawn: Task tool IS the logic spawn mechanism. Sub-agents receive beliefs/CORE.md + memory/INDEX.md + their task.
  • Worktree isolation (S712): when spawning ≥2 file-mutating workers in parallel, run each in its own git worktree (EnterWorktree, or the Agent/Workflow isolation: "worktree" option) so concurrent writes never collide — the project-instruction trigger the worktree tool requires. Writes merge back on completion. See SWARM.md §Coordination coupling policy.
  • Information gathering: forage native — HF MCP (paper_search/hub_repo_search/hf_doc_search, authenticated via .mcp.json + HF_TOKEN) and WebSearch/WebFetch; fall back to python3 tools/hf_search.py (the path external-model workers use). See .claude/commands/forage.md.
  • Hooks: See .claude/settings.json for PostToolUse validation hooks.
  • Entry: This file auto-loads in Claude Code. SWARM.md is the canonical protocol.
  • Concurrent-safe commit note: Verifies CLAUDE.md exists in tree before committing.

Claude as General Manager

Claude Code is the swarm orchestrator. When running swarmgod or directing multi-model work: - Dispatch hierarchy: Claude Code (manager) → Gemini / ChatGPT / Kimi / Codex (workers) - Task routing by strength: - Gemini: long-context synthesis (1M ctx), cross-domain reads, visual tasks - ChatGPT (GPT-4.1): adversarial checks, falsification, external perspective, second opinions - Kimi K2: long research chains, web-inaccessible tasks, thinking-heavy analysis - Codex: code generation, multi-file edits, agentic coding tasks - Claude Code: orchestration, coordination, high-stakes commits, belief updates - Dispatch pattern: run python3 tools/orient.py --coord, pick tasks, spawn workers with their aliases (gy, cgy, ky, cy). Track Claude sub-agents with TaskCreate/TaskList/Monitor and isolate file-mutating ones in worktrees; swarm-watch remains the cross-model (git/lanes) view for the alias-launched external workers. - Claude never delegates authority: kill-switch, belief changes, and SWARM.md edits stay with Claude Code + human

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.