file-swarm-agent
Use the enhanced file-swarm agent subsystem for non-patch structured action tasks, including shell, browser, mouse, keyboard, screenshot, wait, and MCP-style tool actions. Trigger when the user asks f
SKILL.md.claude/skills/file-swarm-agent/SKILL.md
GitHubfile-swarm-agent
Use this skill when file-swarm is being used as more than a patch worker and must execute model-planned structured actions.
This skill is separate from $file-swarm:
$file-swarmcontrols guarded code patch workflows.$file-swarm-agentcontrols structured action workflows such as shell/browser/mouse/MCP dry-run tasks.
Core Modules
The latest implementation is in:
src/file_swarm/agent_executor.py
src/file_swarm/rate_limiter.py
src/file_swarm/providers/openai_compatible_provider.py
src/file_swarm/providers/anthropic_provider.py
src/file_swarm/task_planner.py
tests/benchmark_nvidia_v2.py
tests/test_enhanced_agent_benchmark.py
Benchmark outputs are currently stored in:
benchmark_report.md
benchmark_results.json
AgentExecutor
AgentExecutor asks a model to return a JSON array of typed actions, validates the action structure, applies safety checks, and executes or dry-runs actions sequentially.
Supported action types:
shell
browser_open
browser_fetch
mouse_click
mouse_move
mouse_drag
key_type
key_press
key_hotkey
screenshot
mcp_call
wait
Use dry-run mode for benchmark and safety validation. Do not run real mouse, keyboard, browser, or shell actions unless the user explicitly asks for real execution and the target environment is safe.
Safety Rules
Always preserve these guardrails:
- Block destructive commands such as
rm -rf,format,shutdown,reboot, fork bombs, and pipe-to-shell installers. - Keep shell commands inside the configured working directory.
- Cap command output.
- Use per-command timeouts.
- For browser actions, allow only
http://orhttps://URLs. - For MCP
env_get, never expose secrets, API keys, tokens, passwords, or credentials. - Prefer
dry_run=Truein tests and benchmarks.
Model Prompt Contract
When asking a model for actions, require:
[
{"type": "shell", "command": "dir"},
{"type": "mcp_call", "tool": "datetime_now", "args": {}}
]
Rules:
- Return JSON only.
- Include a
typefield on every action. - Use at most 10 actions.
- Use Windows-compatible shell commands on Windows.
- Prefer typed actions over prose.
- Increase
max_tokensand retry once if the model returns an empty response.
Task Routing
Use split_agent_tasks() when a request is not primarily a coding patch task and mentions actions such as:
- run/check/list system commands
- open or fetch a web page
- click/move/type/screenshot
- call MCP tools
- inspect environment safely
- produce a system report
Do not route normal coding requests to agent_worker. Coding work should stay with patch workers under $file-swarm.
Rate Limiting
src/file_swarm/rate_limiter.py provides async rate limiting and retry behavior.
Important behavior:
- NVIDIA endpoints get conservative limiting.
- Mimo and relaxed endpoints are not throttled by default.
- The limiter releases its lock before sleeping, avoiding deadlocks.
- Retry only rate-limit or transient server-busy failures such as 429, 502, and 503.
Use rate limiting in provider calls, not in task planning.
Provider Notes
OpenAICompatibleProvider integrates rate limiting and retry behavior.
AnthropicProvider supports Anthropic-style Messages API endpoints and returns the shared ProviderResult shape.
Provider failures must return:
ProviderResult(ok=False, error="...")
Do not raise raw provider exceptions to the CLI top level.
Never log API keys. Only log key fingerprints.
Benchmark Workflow
Run benchmark code only when explicitly requested:
python tests/benchmark_nvidia_v2.py
The benchmark is designed to be dry-run and side-effect safe.
Inspect:
benchmark_report.md
benchmark_results.json
Report results in this shape:
Model | Pass Rate | Best Category | Avg Latency | Notes
If a model returns 403, timeout, or empty response, report the error clearly and do not fabricate a pass.
Current Benchmark Interpretation
The current benchmark report says:
- Mimo-v2.5 passed the most categories.
- Mimo-v2.5-Pro passed multiple categories but timed out on some tasks.
- Several NVIDIA-hosted model IDs returned 403 in the tested environment.
- Dry-run action execution was used, so no real shell/browser/mouse effects were required for benchmark scoring.
Treat benchmark results as environment-specific, not universal truth.
User-Facing Summary
When this skill is used, summarize:
Agent subsystem: enabled
Task category: shell/browser/mouse/mcp/mixed
Provider/model: <provider> / <model>
Dry run: yes/no
Actions planned: <count>
Actions executed: <count>
Blocked actions: <count>
Rate limiter: enabled/disabled
Result: passed/failed
Evidence files: benchmark_report.md, benchmark_results.json, or run artifacts
Never include raw secrets, bearer tokens, or API key values.