hermes-simplify-swarm - GitLite

KO | EN

gitlite — search

#developer-tools #machine-learning #sql #mcp #mysql #awesome-list #ruby #awesome #kubernetes #chatgpt

hermes-simplify-swarm

(★ 15)

Multi-agent code simplification skill for Hermes Agent. 3 parallel sub-agents (Hygiene, Clarity, Correctness) with risk-tiered application. Inspired by Claude Code's /simplify.

File Explorer

ZIP Download

- - validate.yml
- findings.sample.json
- manifest.json
- README.md
- - go.md
  - python.md
  - rust.md
  - typescript.md
- clarity-agent.md
- concurrency-fix-patterns.md
- corrections.md
- correctness-agent.md
- decisions.md
- hygiene-agent.md
- swarm-triage-pitfalls.md
- score.py
- validate.py
BENCHMARK.md
CHANGELOG.md
CONTRIBUTING.md
LICENSE
README.md
SECURITY.md
SKILL.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

License: MIT Visit
Version Visit
CI Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

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](#how-it-works)
- [The three agents](#the-three-agents)
- [Risk tiers & the approval gate](#risk-tiers--the-approval-gate)
- [Supported languages](#supported-languages)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Configuration](#configuration)
- [Benchmark & testing](#benchmark--testing)
- [Security](#security)
- [Contributing](#contributing)
- [License](#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

| Agent | What it hunts | Examples |
|-------|--------------|---------|
| **Hygiene** (SAFE) | Dead code, AI slop, redundant abstractions, stale state, utility discovery | Unused imports, `as any` casts, pass-through wrappers, duplicate state stores |
| **Clarity** (CAREFUL) | Duplication, naming, structure, consistency, comments | Nested ternaries, `data`/`temp` variables, 80-line functions, mixed arrow/function styles |
| **Correctness** (RISKY) | N+1 queries, memory leaks, concurrency, leaky abstractions, silent failures | ORM queries in loops, unclosed resources, race conditions, empty catch blocks |

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

| Tier | What happens | Examples |
|------|-------------|---------|
| **SAFE** | Applied first, once approved | Unused imports, dead branches, commented-out code, pass-through wrappers |
| **CAREFUL** | Applied one file at a time with test verification | Renames, nested-ternary flattening, extracted helpers, magic-number constants |
| **RISKY** | Flagged for you to decide — never auto-applied | N+1 restructures, public API changes, concurrency fixes, error-handling changes |

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](#configuration)).

## Supported languages

| Language | Coverage |
|----------|----------|
| TypeScript / JavaScript | N+1, leaks, concurrency, silent failures, slop, naming |
| Python | N+1, leaks, concurrency, silent failures, slop, naming |
| Go | N+1, leaks, concurrency, silent failures, slop, naming |
| Rust | Ownership-aware: `unsafe`, ignored `Result`, needless clones, lock-across-await |

Per-language detector catalogues live in
[`references/language-packs/`](references/language-packs/). To add a language
(Zig, Kotlin, Java, C#), see [`CONTRIBUTING.md`](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:

```bash
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:

```yaml
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:

```bash
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`](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`](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`](SECURITY.md). Report vulnerabilities privately, not in a public
issue.

## Contributing

Language packs, detection patterns, and bug reports are welcome — see
[`CONTRIBUTING.md`](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`](references/corrections.md). MIT-licensed; see
[`LICENSE`](LICENSE).

## Credits

Built by [Sahil Saghir](https://github.com/Sahil-SS9) (KENSEI). Inspired by prior
code-simplification research and the Agent Skills open standard. Design rationale
is documented in [`references/decisions.md`](references/decisions.md).

## License

MIT — use it, fork it, ship it.