file-swarm
Use file-swarm to run Codex-controlled, OpenAI-compatible, file-level coding swarms. Trigger when a coding task should be split into guarded patch workers, when the user asks for multi-model or multi-
SKILL.md.claude/skills/file-swarm/SKILL.md
GitHubfile-swarm
Use file-swarm as a patch-only coding swarm controlled by Codex.
Core principle:
Codex sets rules.
Workers produce patches.
file-swarm enforces guardrails.
Tests validate.
Codex decides whether to apply.
Do not bypass Patch Guard by editing target repo files directly unless the user explicitly asks for manual implementation.
Integrated Skill Pair
Use this skill together with $file-swarm-agent when the request mixes coding and structured actions.
- Use
$file-swarmfor guarded file-level coding patches. - Use
$file-swarm-agentfor non-patch actions such as shell diagnostics, browser fetches, screenshot plans, mouse/keyboard dry-runs, and MCP-style tool calls. - Keep coding work in patch workers unless the user explicitly asks for real action execution.
- Keep action work in dry-run mode unless the user explicitly approves side effects.
Decision rule:
Coding task that should change repository files -> file-swarm patch worker
System/browser/mouse/MCP task that should execute or simulate actions -> file-swarm-agent
Mixed request -> run patch workflow first, then action dry-run/benchmark/report as supporting evidence
Quick Start
Run from the target repository root:
file-swarm init --repo .
file-swarm preflight --repo .
file-swarm codex-contract "<user task>" --repo .
file-swarm auto "<user task>" --repo . --parallel 2 --dry-merge
file-swarm summary --run <run_id> --for-codex
Apply only when codex_summary.md recommends it and guard reports passed:
file-swarm apply --run <run_id> --allow-dirty
Repair failed or rejected tasks:
file-swarm repair --run <run_id>
Live Checks
Never call a live slot without a configured environment variable API key.
file-swarm preflight --repo . --live
file-swarm smoke-test --repo . --live
Rules:
preflight --livesendsReply with OK.to enabled keyed slots.smoke-test --livemust receive a real unified diff patch from the provider.- Live smoke-test must fail if the model returns prose or non-diff text.
- Never print or write full API keys; use fingerprints only.
Task Allocation
Let file-swarm split tasks when possible. Prefer file-level task boundaries:
- One task owns one coherent file or tightly coupled file group.
- Keep
allowed_filesas small as possible. - Tests can be a separate task when they touch a dedicated test file.
- UI/design text can be a separate task from domain logic.
- Never let workers edit config, lockfiles,
.env, dependencies, or unrelated files unless hard constraints explicitly allow it.
Good task split:
task_001 -> src/clicker_core.py -> domain logic and safety rules
task_002 -> src/clicker_ui.py -> designed presentation helpers
task_003 -> tests/test_clicker_*.py -> behavior and integration tests
Avoid:
task_001 -> entire repository
task_002 -> package manager files
task_003 -> duplicate ownership of task_001 files
Model And Slot Assignment
Model slots live in:
.swarm/config/model_slots.yaml
Each enabled slot has:
idproviderbase_urlorbase_url_envapi_key_envallowed_modelsdefault_model
Dispatch behavior:
--parallel Nlimits global worker concurrency.- A slot is leased before worker start.
- Busy slots are skipped during selection.
- One slot cannot serve two workers at the same time.
- If no slot is free, tasks wait instead of reusing a busy slot.
NVIDIA To Mimo Failover
Default live coding route:
1. NVIDIA GLM primary: z-ai/glm-5.1
2. NVIDIA auxiliary models: Kimi, Qwen, DeepSeek when configured
3. Mimo Pro super-brain: mimo-v2.5-pro on /anthropic
4. Mimo multimodal worker: mimo-v2.5 on /anthropic
5. Mimo /v1 compatibility slot, only if it returns non-empty text
Use these endpoints in model_slots.yaml:
NVIDIA: https://integrate.api.nvidia.com/v1
Mimo preferred: https://token-plan-cn.xiaomimimo.com/anthropic
Mimo compatibility: https://token-plan-cn.xiaomimimo.com/v1
Failover is automatic for patch workers when a slot returns:
rate_limit
timeout
connection_error
empty_response
api_error_status_429
api_error_status_502
api_error_status_503
When this happens:
- Release the failed slot immediately.
- Exclude that slot from the current task retry.
- Acquire the next eligible, keyed, preflight-ready slot.
- Record
slot_failoverintimeline.jsonl. - Prefer Mimo
/anthropicover Mimo/v1. - Treat Mimo
/v1empty chat text asempty_response, not success.
Do not retry side-effecting agent_worker tasks on another slot automatically.
Showing Which Model Did What
After auto, inspect these files:
.swarm/runs/<run_id>/dispatch_report.json
.swarm/runs/<run_id>/dispatch_report.md
.swarm/runs/<run_id>/timeline.jsonl
.swarm/runs/<run_id>/transcripts/task_xxx.meta.json
.swarm/runs/<run_id>/codex_summary.md
Report model/task mapping to the user in this shape:
task_001: src/clicker_core.py
slot: mock1
model: mock-model
provider: mock
status: passed
task_002: src/clicker_ui.py
slot: nvidia_glm_slot
model: glm-...
provider: openai_compatible
status: passed
Use dispatch_report.json as source of truth for:
task_idslot_idmodelprovideris_mockstatusmodified_filesprovider_okprovider_error
Use timeline.jsonl to verify:
slot_acquiredworker_startedworker_finishedslot_released
Worker Input Requirements
Every worker input must include:
- user request
- task id and task type
- assigned files
- allowed files
- read-only context files
hard_constraints.yamlinterface_contract.yaml- repo map
- instruction to return unified diff only
Workers must not write files directly. They only return patches.
Patch Guard Rules
Patch Guard must reject:
- empty patches
- patches outside
allowed_files .envor.env.localpackage.jsonpyproject.tomlrequirements.txt- lockfiles
- absolute paths
- file deletions unless explicitly allowed
- suspected secrets or API keys
Only guard-passed patches can enter final.patch.
Codex Decision Checklist
Before applying:
- Read
.swarm/runs/<run_id>/codex_summary.md. - Confirm
hard_constraints_loaded: yes. - Confirm
interface_contract_loaded: yes. - Confirm
guard_rejected_tasks: 0. - Confirm
final_patch_generated: yes. - Confirm
final_patch_empty: no. - Confirm
recommend_apply: yesoryes_with_caution. - Read
validation_report.mdif present.
Do not apply when:
recommend_apply: no- guard rejected any task
- final patch is empty
- contracts were missing
- merge conflict occurred
- critical worker failed
Apply Safety
Default apply requires a clean git worktree.
file-swarm apply --run <run_id>
Use --allow-dirty only when the user expects local changes:
file-swarm apply --run <run_id> --allow-dirty
git apply is the default method. Do not use fallback apply unless explicitly requested:
file-swarm apply --run <run_id> --allow-fallback-apply
After apply, inspect:
.swarm/runs/<run_id>/apply_report.md
.swarm/runs/<run_id>/validation_report.md
Repair Loop
Use repair when guard or validation failed:
file-swarm repair --run <run_id>
file-swarm summary --run <run_id> --for-codex
Repair input must include:
- original task
- original patch
- guard violation
- validation error summary
- hard constraints
- interface contract
If repair cannot run, it must write:
repair_status: skipped
reason: ...
or:
repair_status: failed
reason: ...
Recommended User-Facing Report
After a run, summarize:
Run: <run_id>
Mode: mock/live/mixed
Tasks: <completed>/<total>
Guard: <passed> passed, <rejected> rejected
Models used: <model list>
Slots used: <slot list>
Modified files: <file list>
Recommend apply: <yes/no/yes_with_caution>
Reason: <summary reason>
Next command: <apply/repair/summary command>
Then include a compact task table:
task_id | file(s) | slot | model | provider | status
Never include API keys, bearer tokens, or raw provider credentials.