vibemin 1.2.0

AI coding tools are very good at adding code. They are less disciplined about taking it back out. Vibemin treats your Git diff as a search space and your tests as a contract, repeatedly removing candidate lines until every remaining unit has earned its place.

Tests are the contract. The diff is negotiable.

$ vibemin --feature-base origin/main \
    --check "pytest -q" \
    --check "ruff check ."

[001] PASS  retained=11844  1.42s
[027] fail  retained=10320  1.31s
[149] PASS  retained=9620   1.26s

Removed 2,224 of 11,844 diff units in 149 checks; 9,620 remain.

Vibemin runs locally in a disposable Git worktree. It never sends your code anywhere, and it only updates the real checkout after the result has passed every required check.

Quick start

No Python required

Install the checksummed standalone binary on macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/francescoVaglienti/vibemin/main/scripts/install-binary.sh | sh

Self-contained executables are published for macOS, Linux, and Windows on the Releases page. Git is the only runtime prerequisite.

Python package

Install directly from GitHub with uv:

uv tool install git+https://github.com/francescoVaglienti/vibemin.git

From the repository containing your changes:

vibemin \
  --check "npm test -- --run" \
  --check "npm run lint" \
  --check "npm run typecheck"

Or minimize the complete feature branch from its merge-base with main:

vibemin --feature-base origin/main \
  --check "pytest -q" \
  --check "ruff check ."

The verified result is written back as working-tree changes, ready to review and commit. Add --dry-run to inspect what Vibemin would remove without changing the checkout.

Built for agentic code

How it works

1. Read the diff. Vibemin turns inserted and deleted lines into removable units.
2. Build a sandbox. Candidate patches run in a temporary detached Git worktree.
3. Search by subtraction. Groups of units are removed using delta debugging.
4. Verify every candidate. Tests, linters, type checks, and output contracts decide what survives.
5. Apply once. Only the final verified patch is written to your checkout.

The result is 1-minimal under the supplied checks: no remaining individual unit was shown to be removable. It is not a claim that the implementation is globally shortest, and weak checks can still permit an incorrect reduction.

Safety model

Green unit tests alone do not prove that tests, lockfiles, or rendered output survived. Vibemin protects the easy-to-game parts of a patch by default.

These defaults prevent misleading wins such as deleting assertions until the suite passes, removing CSS because a non-visual build stays green, or drifting a lockfile away from its manifest. Vibemin reports every protected file as fixed context.

Recipes

Minimize selected paths

vibemin src/new-feature \
  --check "npm test -- --run tests/new-feature.test.ts" \
  --check "npm run lint"

Minimize a whole feature

--feature-base finds the merge-base, so unrelated target-branch history is excluded. Use --base REF when you want an exact baseline instead.

vibemin --feature-base origin/main \
  --check "pytest -q" \
  --final-check "pytest -q tests/integration"

Reduce tests without weakening them

Preserve the collected test inventory when simplifying test bodies:

vibemin tests --reduce-tests \
  --check "pytest -q" \
  --preserve-output "pytest --collect-only -q | sed '/collected in/d'"

When intentionally merging overlapping cases, collection output must change. Protect the mutation score or killed-mutant set instead:

vibemin tests --reduce-tests \
  --check "pytest -q" \
  --test-strength-check "./scripts/check-mutation-baseline"

Coverage alone does not preserve assertion strength.

Preserve a rendered contract

vibemin web/src --allow-visual-changes \
  --check "npm run build" \
  --preserve-output "./scripts/render-reference-screenshot --hash"

--preserve-output records deterministic stdout and stderr from the first verified candidate and requires an exact match from every smaller one. It also works well for API schemas, generated interfaces, and CLI snapshots.

Validate dependency changes

vibemin pyproject.toml uv.lock --allow-dependency-changes \
  --check "pytest -q" \
  --dependency-check "uv lock --check"

Preview without applying

vibemin --dry-run \
  --check "pytest -q" \
  --check "ruff check ."

CLI essentials

Run vibemin --help for the complete command reference.

Guardrails and limitations

• Staged changes are rejected so the index and working tree cannot diverge unexpectedly.
• Symlinks and changed directories or submodules are currently rejected.
• Ignored local files such as .env, .venv, and node_modules are not copied into the temporary worktree. Prefer globally available tools or shared package-manager caches.
• Checks must be non-mutating and run from the root of the temporary worktree.
• Untracked, non-ignored files are included. Files outside explicit path arguments remain available as fixed context.
• Binary files and empty-file changes are atomic reduction units.

Always review the final diff. Vibemin knows only what the checks prove.

Use it with your coding agent

Vibemin is a standalone CLI; no AI subscription or agent is required. The optional Agent Skill teaches your existing coding agent when to minimize a patch and which test, security, TypeScript, visual, and lockfile guardrails to preserve.

git clone https://github.com/francescoVaglienti/vibemin.git
cd vibemin
./scripts/install-user.sh

The installer detects claude, codex, copilot, and gemini executables and their local configuration directories. One match is selected automatically; several matches produce a choice prompt. With no detected agent, Vibemin installs as a standalone CLI and does not create an agent skill directory.

For scripts and unattended setup, make the choice explicit:

./scripts/install-user.sh --agent standalone
./scripts/install-user.sh --agent all
./scripts/install-user.sh --agent claude
./scripts/install-user.sh --agent codex
./scripts/install-user.sh --agent copilot
./scripts/install-user.sh --agent gemini

The skill is based on the open Agent Skills format. Codex, Copilot, and Gemini share the same personal skill location, so the installer does not create three duplicate copies. An explicit agent choice is safe even when that host is absent: the skill is simply ready for its next launch.

In standalone mode you run vibemin directly and supply the checks on the command line; there is no model, API key, or agent involved:

vibemin --check "pytest -q" --check "ruff check ."

Development

git clone https://github.com/francescoVaglienti/vibemin.git
cd vibemin
uv run --with pytest pytest -q
uv run --with ruff ruff check .
uv run --with ruff ruff format --check .

The suite favors integration evidence over internal implementation tests: it exercises real Git repositories, runs release executables end to end, and makes Vibemin minimize its own source while its focused test suite acts as the oracle.

Source installs target Python 3.10+ and have no runtime dependencies. Release executables bundle their own Python runtime.

License

MIT © Francesco Vaglienti