Metadata-Version: 2.4
Name: slopcut
Version: 0.2.0
Summary: Cut the residue out of AI-generated patches: find the edits a repair actually needs and drop the rest
Author: slopcut contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/ujjwalredd/slopcut
Project-URL: Documentation, https://github.com/ujjwalredd/slopcut#readme
Project-URL: Issues, https://github.com/ujjwalredd/slopcut/issues
Project-URL: Source, https://github.com/ujjwalredd/slopcut
Keywords: ai,claude-code,code-quality,delta-debugging,developer-tools,patch-minimization
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: bench
Requires-Dist: matplotlib; extra == "bench"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# slopcut

Coding agents rarely clean up every failed attempt. When an agent tries three fixes
and the third one works, code from the first two can remain in the diff. The resulting
patch becomes the union of every hypothesis the agent tried, while the lines that
actually fixed the bug are buried inside it.

slopcut finds those two lines. It reads the session, then repeatedly asks: *do the
tests still pass without this group of edits?*

```
$ slopcut

session   0f3ab21e-session.jsonl
tests     python -m pytest -q
patch     47 lines across 12 edits in 4 attempts

  superseded  -3 edits (free, never reached the patch)
  scratch     -1 files (1 test run): repro_bug.py
  attempt     -5 edits
  file        -2 edits

result    47 -> 9 lines (81% removed), 2 edits remain
cost      9 test runs (2 cached)
```

The default mode writes nothing. Search and validation happen in a temporary Git
worktree, leaving the active working tree untouched.

## Install

Install it as an isolated command-line tool:

```bash
uv tool install slopcut
# or
pipx install slopcut
# or
pip install slopcut
```

slopcut requires Python 3.9 or newer and Git. The `pip` command must belong to
Python 3.9 or newer; check with `pip --version`.

To add the Claude Code command, register this repository as a plugin marketplace:

```bash
claude plugin marketplace add ujjwalredd/slopcut
claude plugin install slopcut@slopcut
```

The plugin calls the installed `slopcut` executable. After installation, run
`/slopcut` in Claude Code after a session where the agent edited code.

## Use

```bash
slopcut                              # dry run: show what it would remove
slopcut --apply                      # write the minimized patch (backs up first)
slopcut --level edit                 # search harder
slopcut --test "cargo test --lib"    # when the test command cannot be inferred
slopcut --session run.traj --session-format swe-agent
slopcut --json                       # machine-readable
```

By default, slopcut reads the most recent Claude Code session for the current
repository, finds the test command the agent ran, and prints a minimized diff.

### How hard to search

| `--level` | removes | relative cost |
|---|---|---|
| `attempt` | whole abandoned attempts | cheapest |
| `hybrid` | attempts, then whole files | middle |
| `edit` **(default)** | individual edits | ~10 test runs |

`edit` is the default because it is the only level that reaches the verified minimum;
the benchmark below measures it at 100% recovery for around ten test runs. The coarser
levels save a few runs and stop short of the minimum, so reach for `hybrid` or
`attempt` only when a single test run is genuinely expensive, such as a slow
integration suite or a container rebuild.

`--exhaustive` repeats each level until nothing more comes out. It almost never
finds anything the single pass missed, so it is off by default.

## How it works

1. **Read the session** into attempts. Each attempt is a batch of edits followed by
   a test run. Everything else, including file reads, searches, and navigation, is dropped
   because it cannot affect the patch.
2. **Drop superseded edits.** If removing an edit leaves the final tree
   byte-identical, it was overwritten later and never reached the patch. Pure string
   work, zero test runs.
3. **Drop agent-created files.** One test run tries to discard files the agent
   created for debugging, such as reproduction scripts and temporary harnesses.
4. **Search coarse to fine:** attempt, file, then edit. Remove a unit, run the tests,
   keep the removal only if it passes *and* the patch got smaller. One success at the
   top level kills an entire abandoned attempt for the price of a single test run.

Candidates are rebuilt by replaying the surviving edits onto a clean checkout instead
of splicing the diff. If an edit depends on something that was removed, the test run
can reject that candidate.

## Benchmark

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/charts/flagship-dark.png">
  <img alt="Recovery per method, split by whether the slop is separable from the fix, tangled inside its hunk, or depended on by it. slopcut reaches the verified minimum in all three; delta debugging removes nothing when slop is tangled; the last-attempt heuristic removes nothing when the fix needs an earlier attempt." src="docs/charts/flagship-light.png">
</picture>

900 tasks across Python, JavaScript and Go, every one carrying an oracle certificate
proving no shorter patch passes. 2,700 method runs, zero errors, nothing broken.

| | separable | tangled | linked | test runs | exact minimum |
|---|---:|---:|---:|---:|---:|
| **slopcut `--level edit`** | **100%** | **100%** | **100%** | 10.2 | **100%** |
| delta debugging over hunks | 81% | **0%** | 61% | 2.8 | 12% |
| keep last attempt only | 74% | 77% | **0%** | 1.0 | 0% |

Averages hide the finding, so this splits recovery by how the slop is arranged. Delta
debugging is cheap and respectable on slop that occupies its own hunks, but it cannot
separate a leftover edit from the fix when the two share a hunk, so it removes nothing
there. The one-test-run trick of keeping only the last attempt is decent until the fix
calls something an earlier attempt introduced, when dropping that attempt breaks the
repair and everything has to stay.

Each baseline fails somewhere different, and the failures are total rather than
partial. slopcut reads the session, so it can tell two edits apart even when the diff
cannot, and it reaches the verified minimum in every condition, for about four times
the test runs of delta debugging.

The v0.2 benchmark has two tracks and does not combine them into one score.

The synthetic track measures recovery against a known optimum across Python,
JavaScript/TypeScript, and Go. An independent verifier checks that the base fails,
the full repair passes, the claimed optimum passes, every required edit is necessary,
and no shorter edit subset passes.

The real-session track measures patch reduction and test preservation on recorded
agent repairs of public open-source bugs. It cannot establish an exact optimum or
semantic equivalence. Real-session headline results will not be published until the
public corpus contains at least 10 eligible sessions in each ecosystem and 30 total.

That collection gate has not been met yet, so the chart above is a synthetic result and
nothing more. It says the search finds the minimum whenever one exists; it says nothing
about how much slop your agent actually leaves behind, which only the real-session
track can answer.

Reproduce the synthetic track locally, oracle verification included:

```bash
pip install -e '.[bench]'
python -m bench reproduce \
  --manifest bench/corpus/v2/manifest.json \
  --out bench/out/v2 \
  --synthetic-only
```

Or exercise the whole pipeline in a couple of minutes with `--smoke` in place of
`--synthetic-only`.

Dropping both flags runs the release reproduction, which fails closed until the
real-session corpus meets its gate. A successful run emits raw observations, oracle
certificates, a versioned summary, environment metadata, checksums, a report, and the
scorecard in SVG and PNG.

The methodology, corpus rules, metrics, and exclusion policy are documented in
[BENCHMARK.md](BENCHMARK.md). [REPRODUCING.md](REPRODUCING.md) contains the clean
checkout procedure.

## Real-world behavior

The benchmark measures the search, not how much slop an agent produces. Sessions
that went directly to the fix have nothing to remove, and slopcut reports that result
plainly. An already minimal patch is a successful outcome.

The wins concentrate in the messy sessions: long ones, ones where the agent went down
a wrong path first, ones that left a `repro.py` behind.

## Limitations

- **The test suite defines required behavior.** slopcut can remove behavior that the
  configured tests do not cover. Limited coverage can therefore produce aggressive
  reductions. Every minimized diff should be reviewed before it is applied.
- **Flaky tests can authorize a bad removal.** slopcut checks the baseline before
  starting, but it cannot catch a test that fails 1 run in 20.
- **The smallest unit is one edit.** Redundancy *inside* a single edit is out of reach.
- **Reconstruction can drift.** slopcut rebuilds the patch from the session. Manual
  edits and changes made by unsupported tools can leave the reconstruction incomplete.
  slopcut detects this condition and refuses to apply the result.
- **Adapters:** Claude Code, plus SWE-agent and bash-only scaffolds. Adding one is
  small: emit `(file, before, after)` in order, grouped by test run.

## Contributing

See the
[contribution guide](https://github.com/ujjwalredd/slopcut/blob/main/CONTRIBUTING.md).
Start with `pip install -e '.[dev]' && pytest`.

Two numbers decide whether a change to the search is good: recovery must not drop,
and test runs must not rise.

## Security

slopcut executes test commands on the local machine. Inferred commands come from the
selected Claude Code transcript, so repositories and session files are trusted inputs.
The `--test` option can provide an explicit command. Candidate patches are isolated
in a Git worktree, but test processes are not containerized or sandboxed. See
[the security policy](https://github.com/ujjwalredd/slopcut/blob/main/SECURITY.md)
for the full trust model and private reporting process.

## Releasing

Maintainers can find the release checklist and PyPI Trusted Publishing setup in
[the release guide](https://github.com/ujjwalredd/slopcut/blob/main/RELEASING.md).

## Credits

The trajectory-minimization idea comes from
[TRIM: Reducing AI-Generated CodeSlop via Agent Trajectory Minimization](https://arxiv.org/abs/2607.18161)
(Mathai et al., 2026), which is well worth reading.

## License

MIT
