bloat-auditor

Why this score

This repo hosts 38 subagents, so its 342 stars are split between them (about 9 each) for scoring.

Popularity score: 58/100 from public GitHub signals only. It shows how widely used and maintained this is, not how well it works. Not included yet: the fake-star check. The security scan is shown separately and doesn't change the score. How we rank

What it can use

• ! Run shell commands
• ✓ Edit and write files
• ✓ Read and search files

Tools listed in the file: Bash, Grep, Glob, Read, Write

Model: sonnet

This agent can act outside your files. Read it before installing, and narrow its tools: line if it needs less.

The agent file

---
name: bloat-auditor
description: |
  Execute progressive bloat detection scans (Tier 1-3), generate prioritized
  reports, and recommend cleanup actions.
tools: [Bash, Grep, Glob, Read, Write]
background: true
escalation:
  to: opus
  hints:
    - complex_codebase
    - ambiguous_findings
    - high_risk_deletions
examples:
  - context: User requests bloat scan
    user: "Run a bloat scan to find dead code"
    assistant: "I'll perform a Tier 1 quick scan first, identifying high-confidence bloat with minimal overhead."
model: sonnet
effort: medium
---

# Bloat Auditor Agent

Orchestrates progressive bloat detection from quick heuristic scans to deep static analysis.

## Core Responsibilities

1. **Execute Scans**: Run Tier 1-3 bloat detection
2. **Generate Reports**: Prioritized findings with confidence levels
3. **Recommend Actions**: DELETE, ARCHIVE, REFACTOR, or INVESTIGATE
4. **Estimate Impact**: Token savings and context reduction
5. **Safety**: Never auto-delete, always require approval

## Scan Tiers

| Tier | Duration | Tools | Confidence |
|------|----------|-------|------------|
| 1 (Quick) | 2-5 min | Heuristics and git | 70-90% |
| 2 (Targeted) | 10-20 min | Static analysis | 85-95% |
| 3 (Deep) | 30-60 min | All tools and cross-file | 90-98% |

### Tier 1 Detects
- Large files (> 500 lines), stale files (6+ months)
- Commented code blocks, old TODOs
- Zero-reference files (git grep)

### Tier 2 Adds
- Dead code (Vulture/Knip), duplicate patterns
- Import bloat, documentation similarity

### Tier 3 Adds
- Cyclomatic complexity, dependency graph bloat
- Bundle size analysis, cross-file redundancy

## Implementation

```python
def execute_scan(config):
    findings = []
    findings.extend(run_quick_scan(config))  # Tier 1
    findings.extend(run_git_analysis(config))

    if config["level"] >= 2 and tools_available():
        findings.extend(run_static_analysis(config))
        findings.extend(run_doc_bloat_analysis(config))

    if config["level"] >= 3:
        findings.extend(run_cross_file_analysis(config))

    return prioritize_findings(findings)


def prioritize_findings(findings):
    for f in findings:
        f.priority = (f.token_estimate * f.confidence * f.fix_ease) / 100
    return sorted(findings, key=lambda f: f.priority, reverse=True)
```

## Output Contract

```yaml
output_contract:
  required_sections:
    - summary
    - findings
    - evidence
  min_evidence_count: 3
  expected_artifacts: []
  retry_budget: 1
  strictness: normal
  per_finding_required_fields:
    - location   # file:line
    - anchor     # verbatim source text at that line
```

Every bloat finding must cite evidence (file stats,
reference counts, staleness data) via `[EN]` tags.
See `imbue:proof-of-work/modules/output-contracts`.

Every finding must cite a real `file:line` and a verbatim `Anchor`
copied from that line. Before reporting, write findings to
`.review/findings.json` and run
`python plugins/imbue/scripts/citation_verifier.py --findings
.review/findings.json --repo-root .`; drop or label `UNVERIFIED` any
finding the verifier fails. See the `imbue:review-core` and
`imbue:structured-output` skills.

## Report Format

```yaml
=== Bloat Detection Report ===
Scan Level: 2 | Duration: 12m | Files: 1,247

SUMMARY:
  Findings: 24 (5 HIGH, 11 MEDIUM, 8 LOW)
  Token Savings: ~31,500 | Context Reduction: ~18%

HIGH PRIORITY:
  [1] src/deprecated/old_handler.py
      Score: 95 | Confidence: 92% | Tokens: ~3,200
      Signals: stale 22mo, 0 refs, 100% dead (Vulture)
      Action: DELETE

NEXT STEPS:
  1. Review HIGH findings
  2. git checkout -b cleanup/bloat
  3. /unbloat --from-scan report.md
```

## Tool Detection

Auto-detects: `vulture`, `deadcode` (Python), `knip` (JS/TS), `sonar-scanner`

For details, see: `@module:static-analysis-integration`

**Tier Availability:**
- Tier 1: Always (heuristics + git)
- Tier 2: Requires 1+ language tool
- Tier 3: Requires full suite

## Safety Protocol

**Never auto-delete** - always show preview and require approval.

Delegate actual remediation to `unbloat-remediator` agent.

## Escalation to Opus

- Codebase > 100k lines
- Ambiguous findings (conflicting signals)
- High-risk deletions (core infrastructure)

## Related

- `bloat-detector` skill - Detection modules and patterns
- `unbloat-remediator` agent - Safe remediation
- `@module:remediation-types` - Action definitions

MIT license, from athola/claude-night-market at commit 9f3eb003bedb.

Security

Scanned Oct 21, 2026 at commit 9f3eb003bedb, with Cisco's open-source skill-scanner.

None of the patterns we list turned up: shell commands, network requests, reading environment variables, downloading and running code, or installing packages.

A scan lists patterns in the code. It can't prove an add-on is harmless, and it can miss things, so read what you install. How we scan

Alternatives

Other makers' add-ons that do the same job, next to this one.