git-slop 0.10.0

A language-agnostic token defragmenter for human-and-agent software development.

Git Slop is an open-source, local-first Rust tool that finds where token distribution and fragmentation make a repository expensive to load, reason about, and safely change. It turns tracked files and Git history into deterministic health reports and bounded maintenance plans for people and coding agents.

Models matter. Repository shape is part of the inference bill too.

Git Slop does not try to determine whether AI wrote your code. It measures the repository that exists.

Quick Start

Install with Homebrew on macOS or Linux:

brew install coreycoto/tap/git-slop

Then run Git Slop inside any Git repository:

git slop init
git slop find
git slop health
git slop explain --top 5

init creates a repo-owned configuration and ignore rules. find performs the analysis once; the other commands read the generated report without rescoring it. Run from a full-history checkout when age, churn, coupling, and stewardship evidence matter.

The health dashboard points to the next useful command. After reviewing a finding, ask Git Slop for a bounded maintenance proposal:

git slop explain --path src/example.rs
git slop plan --path src/example.rs

A plan is evidence for human review. It does not edit code, invoke a model, or mutate Git or GitHub.

What Git Slop Makes Visible

Repositories become expensive in more than one way. Git Slop keeps those costs separate so maintainers can see why something surfaced.

Signal	Question it helps answer
Context load	Which files and folders consume too much working context?
Maintenance pressure	Which expensive surfaces are old, volatile, or repeatedly revised?
Fragmentation	Where is one concept duplicated, scattered, or leaking across boundaries?
Coordination	Which paths repeatedly change together or carry a broad blast radius?
Verification	Which hotspots have weak nearby test or test-co-change evidence?
Navigation, stewardship, and drift	Where is knowledge hard to find, ownership concentrated, or terminology diverging?

The stable hotspot score uses deterministic context, age, and churn evidence. Coordination and structural overlays remain separate supporting evidence; they cannot silently inflate slop_score or change git slop check.

A hotspot is not a correctness verdict or an automatic refactor order. It is a place where the cost of future work deserves investigation.

From Evidence to Bounded Work

Measure: git slop find inventories tracked text files and mines local Git history.
Orient: git slop health summarizes repository shape and recommends deterministic drill-down commands.
Investigate: show and explain connect a hotspot to the evidence that surfaced it.
Bound: plan proposes small maintenance slices with explicit scope, exclusions, and verification evidence.
Decide and verify: a person chooses the work, a human or coding agent implements it, then reruns find and uses check or compare to measure the result.

Git Slop remains observational throughout that loop. The repository owner keeps the judgment.

Report Bundle

Every successful find writes the same four-file bundle to .slop/latest/ and a timestamped copy under .slop/runs/:

Artifact	Purpose
`report.json`	Versioned machine contract for automation
`report.yaml`	Equivalent machine data for YAML consumers
`summary.md`	Detailed detector and overlay evidence
`health.md`	Concise repository-health dashboard for people and CI

Routine generated output stays untracked. Commit .slop/config.yaml and .slop/.gitignore when a repository intentionally adopts Git Slop; see the .slop directory policy.

Install

The examples below pin the 0.10.0 release identity. Use each command only after that exact version is published on the requested distribution surface; documentation or a source tag is not proof that every surface is available.

See Installation for availability, provenance, upgrades, and contributor setup.

Homebrew (macOS and Linux)

brew install coreycoto/tap/git-slop

Cargo (Crates.io)

cargo install git-slop --version 0.10.0 --locked

Scoop (Windows)

scoop bucket add coreycoto https://github.com/coreycoto/scoop-bucket
scoop install coreycoto/git-slop

Verify an installed release and its source provenance:

git-slop version
git-slop build-info --format json

The executable is git-slop. When it is on PATH, Git also accepts git slop.

GitHub Actions

Use a full-history checkout for complete history-derived evidence:

permissions:
  contents: read

steps:
  - uses: actions/checkout@v7
    with:
      fetch-depth: 0
  - uses: coreycoto/git-slop@v0.10.0

The Action is advisory by default. It verifies the native release, writes the health dashboard to the job summary, emits at most 10 annotations, and uploads only health.md for 14 days. Enforcement, larger artifacts, and pull request comments are explicit opt-ins. See GitHub Action.

Command Map

Command	Purpose
`git slop init`	Create repo-local config, ignore rules, and state directories
`git slop find`	Analyze the repository and write a fresh report bundle
`git slop health`	Render the human or CI health view from an existing report
`git slop show`	Inspect one file or folder record
`git slop explain`	Explain a path, relationship, cluster, or the top findings
`git slop plan`	Propose bounded maintenance slices from reviewed evidence
`git slop check`	Apply the stable detector gate
`git slop compare`	Compare two existing reports without rerunning analysis
`git slop sarif`	Export action-queue findings as SARIF 2.1.0
`git slop version`	Print the installed version
`git slop build-info`	Print machine-readable package and source provenance

See the Command Guide for selectors, formats, prompt packs, CI thresholds, and examples.

Working With Coding Agents

Git Slop does not require an LLM. When an agent handoff is useful, explain and plan can write deterministic prompt packs containing bounded evidence and explicit scope. The repository also ships a portable Git Slop Agent Plugin for installation, reporting, review, planning, and adoption workflows.

Start with git slop doctor; see Troubleshooting, Configuration Recipes, the neutral Worked Example, and the 0.10.0 upgrade notes.

Trust Boundaries

The local Git Slop CLI does not:

send repository data to a hosted service
use an LLM to score files or change detector truth
claim to detect AI authorship
assign an overall code-quality grade
treat a finding as proof that code is wrong
rewrite source, tests, Git history, or GitHub state
make autonomous refactoring decisions

These constraints are product architecture, not disclaimers. Read the Vision for the deeper thesis and planned policy-guided advice layer.