Sahil-SS9/hermes-simplify-swarm

Simplify Swarm — Multi-Agent Code Simplification

Most code simplification tools check for style and lint violations. Simplify Swarm breaks your diff into risk tiers and cleans with surgical precision.

Three parallel, read-only agents attack the same diff from different angles, then a consolidator merges their findings and applies them in SAFE → CAREFUL → RISKY order — with a hard approval gate so nothing changes until you've seen the report.

• Hygiene hunts dead code, AI slop, pass-through wrappers, and stale state — the stuff that rots silently.
• Clarity goes after duplication, naming rot, nested ternaries, and structural bloat — the stuff that makes your teammates sigh.
• Correctness traces N+1 queries, memory leaks, concurrency races, leaky abstractions, and silent failures — the stuff that breaks at 3am.

Simplify Swarm is harness-agnostic: it follows the open Agent Skills standard and runs on any agent harness or model that can spawn parallel read-only workers and collect structured JSON. The swarm pattern, agent definitions, and language packs are independent of any specific harness.

Contents

• How it works
• The three agents
• Risk tiers & the approval gate
• Supported languages
• Installation
• Quick start
• Configuration
• Benchmark & testing
• Security
• Contributing
• License

How it works

┌──────────────────────────────────────────┐
│         Simplify Swarm Orchestrator       │
│  1. Scope detection (git diff)            │
│  2. Parallel dispatch (3 agents)          │
│  3. Consolidation (merge + dedupe)        │
│  4. Approval gate (HARD STOP)             │
│  5. Tiered application (SAFE→CAREFUL→RISKY)│
└──────────┬───────────┬───────────┬───────┘
           ▼           ▼           ▼
    ┌──────────┐ ┌──────────┐ ┌──────────────┐
    │ Hygiene  │ │ Clarity  │ │ Correctness  │
    │ (SAFE)   │ │(CAREFUL) │ │ (RISKY)      │
    └────┬─────┘ └────┬─────┘ └──────┬───────┘
         └────────────┴──────────────┘
                      ▼
              ┌─────────────┐
              │ Consolidator│
              └─────────────┘

The swarm is read-only during analysis — it finds problems, it doesn't touch your code until you've seen the consolidated report. Opt-in only, no auto-trigger. Run /simplify (or just say "simplify my changes") when you want to know what you actually shipped.

The three agents

Each agent returns structured JSON with a confidence and a risk override, so the consolidator can triage findings — not just merge prose.

Risk tiers & the approval gate

Before the report is shown, the consolidator verifies each high-confidence / RISKY finding against the code itself (re-reading the cited line and both sides of the call chain) and reports a correction rate — how many agent findings survived verification.

The approval gate is hard. After the consolidation report, the swarm stops and asks:

Apply which tiers? [SAFE / SAFE+CAREFUL / all / none / pick items]

Nothing is applied — including SAFE — until you answer. The only exceptions are explicit pre-authorisation ("simplify and apply everything safe") or auto_apply: true in the project config (see Configuration).

Supported languages

Per-language detector catalogues live in references/language-packs/. To add a language (Zig, Kotlin, Java, C#), see CONTRIBUTING.md.

Installation

Simplify Swarm follows the open Agent Skills standard — a SKILL.md plus a references/ directory. Install it wherever your harness loads skills:

git clone https://github.com/Sahil-SS9/hermes-simplify-swarm.git
cp -r hermes-simplify-swarm/SKILL.md hermes-simplify-swarm/references <your-harness-skill-dir>/simplify-swarm/

Check your harness's documentation for where it loads skills from. No dependencies, no config required.

Quick start

"simplify my changes"
/cleanup
"deslop this module"
"/simplify focus on correctness"

The skill auto-detects scope via git diff. Focus modifiers narrow the swarm to one or two agents (focus on safety, focus on readability, focus on performance). Dry run: "simplify but don't change anything".

Configuration

Optional .simplify-swarm.yaml in your project root:

simplify:
  auto_apply: true          # skip approval for SAFE+CAREFUL tiers
  skip_patterns:
    - "*.test.*"
    - "*.generated.*"
  max_file_lines: 800

Benchmark & testing

The repo ships a deterministic validator and a detection benchmark:

python3 scripts/validate.py                          # structure: frontmatter, links, read-only agents
python3 scripts/score.py evals/findings.sample.json  # oracle sanity check (F1 = 1.0)

evals/ contains messy-code fixtures with seeded issues across all four languages, plus negative fixtures (clean code and red-herring guards that must produce zero findings) so scripts/score.py measures precision as well as recall. See BENCHMARK.md for the methodology and honest limitations.

Detection guarantees

• Performance findings need a measurable basis — no raw "this is slow" claims.
• Uncovered swallowed errors are RISKY — an empty catch with no test coverage is flagged RISKY, not auto-applied.
• Negative fixtures guard precision — clean / red-herring code must produce zero findings.
• Verify-before-apply — the consolidator re-reads high-confidence / RISKY findings against the code and reports a correction rate.
• Correction feedback loop — real-world false positives and negatives feed back into better detection, gated on the eval score.

Full scope and owners in BENCHMARK.md → "Detection guarantees".

Security

This is an installable skill, so its own content and the channel that changes it are the attack surface. The threat model, enforced boundaries (read-only analysis, human-in-the-loop application), and contribution-review rules are in SECURITY.md. Report vulnerabilities privately, not in a public issue.

Contributing

Language packs, detection patterns, and bug reports are welcome — see CONTRIBUTING.md. The highest-value contribution is a correction (a real false positive or false negative); the feedback loop that turns corrections into better detection is in references/corrections.md. MIT-licensed; see LICENSE.

Credits

Built by Sahil Saghir (KENSEI). Inspired by prior code-simplification research and the Agent Skills open standard. Design rationale is documented in references/decisions.md.

License

MIT — use it, fork it, ship it.