hoimin

hoimin is a mutation testing CLI for Python, designed for AI agents to improve tests locally within explicit resource budgets. It makes small changes to copies of your source and runs your tests to find behavior they do not check.

An agent investigates selected survivors, adds tests grounded in the intended behavior, and verifies the improvement. Humans provide specification decisions and review changes. Mutation scores are diagnostic observations; equivalent mutants and specification-permitted changes make them unsuitable as a standalone quality target. hoimin targets local work and provides no mutation-score or regression CI gate. A completed run exits successfully even when mutants survive; inspect the JSONL events to choose the next test improvement. For repository documentation, start with the user guide or development guide.

See the product principles. See also the documentation for installation, the agent workflow, resource limits, and command references.

Install

Install from PyPI with uv:

uv tool install --python 3.14 hoimin

Wheels support Python 3.14 and 3.15 and support macOS Apple Silicon, Linux x86_64 (glibc), and Windows x86_64. Use --python 3.15 to install with Python 3.15. Python 3.15 lazy imports and unpacking in comprehensions are supported. Import-dependent mutations are conservative when lazy binding identity cannot be established. Run uv tool update-shell if hoimin is not on PATH, then open a new shell.

Quick start

From your project directory, use a Python environment with passing tests and their dependencies installed. Choose the OS memory policy first, then replace src/calc.py with an existing file:

hoimin run --root . --file src/calc.py -- python -m pytest -q

Everything after -- is your project's test command. hoimin runs it once as a baseline, then for each selected mutation. Have your agent investigate a small batch of survivors for missing assertions or test cases; a survivor alone does not establish a test defect. macOS and Linux without delegated cgroups require --allow-best-effort-memory before --; macOS memory is not capped. See the resource limits.

See the usage reference for selectors and configuration, the step-by-step plan/verify workflow for a Git-independent example with a before/after test improvement, and results, or run hoimin --help. For questions and bug reports, see the reporting guide. External Issues and pull requests are not accepted.

Licensed under Elastic License 2.0. See licensing details.

Startup cleanup reports

hoimin run and hoimin verify summarize startup cleanup in disk.janitor (JSON/JSONL schema 10). Output includes bounded ordinary root retention details, failures and unfinished cleanup diagnostics. The summary separates roots from deleted entries and reports bounded scan/detail omissions. It does not estimate remaining roots or freed disk space. See the compatibility notice.