Agent Maintainer

Maintainability checks and repair-loop diagnostics for AI-assisted Python repositories.

Agent Maintainer is in beta. The core workflow is usable today, but starter files and defaults may change as it is tested across more Python repository layouts.

Agent Maintainer helps coding agents make smaller, safer, more reviewable code changes. It wraps your existing quality tools in low-noise profiles, adds change-budget and ratchet discipline, writes bounded diagnostics to .verify-logs, and gives agents exact repair commands instead of dumping huge logs into the chat.

Read more where it matters: quick start, first run walkthrough, diagnostics loop, tool map.

What It Is

Agent Maintainer is a repository maintenance control layer for AI-assisted software development. It checks whether changes are small enough to review, test-backed, type-checked, covered, diagnosable, and aligned with repository structure.

It is strongest when an AI agent is actively editing your repo: the agent gets a compact pass/fail summary, a run id, failed checks, and exact next commands while raw evidence stays in run-scoped artifacts.

Quick Start

Install the core toolset:

python -m pip install "agent-maintainer[core]"

Initialize a repo:

agent-maintainer init --track core --preset existing-app

Merge config/pyproject.agent-maintainer.toml into your pyproject.toml, tune paths, then run:

agent-maintainer doctor
agent-maintainer verify --profile precommit

A healthy verification run is intentionally quiet:

PASS

If it fails, read the bounded repair note first:

cat .verify-logs/LAST_FAILURE.md

That note links to run-scoped logs and gives exact expansion/rerun commands.

Best First Experience: Try A Fresh Strict Repo

The clearest way to feel the value is to let an agent build something new under strict settings before entropy starts.

python -m pip install "agent-maintainer[core]"
agent-maintainer init --track agent --preset strict-new-repo

Then ask your coding agent to build a small package, add tests, and finish by running:

python3 -m agent_maintainer verify --profile precommit

The strict preset turns on the pressure that matters for AI-generated code: small functions, covered behavior, low complexity, no broad suppressions, architecture ownership, and test-backed source changes.

Deeper reads: fresh-strict, agent hooks, generated guidance.

Adoption Tracks

init separates files written from policy strictness.

Preview before writing:

agent-maintainer init --track agent --preset ai-agent-heavy --dry-run

Presets tune policy:

Read more: quick start, legacy ratchet, fresh strict, team policy templates.

Run Profiles

Canonical commands:

python3 -m agent_maintainer verify --profile precommit
python3 -m agent_maintainer verify --profile full
python3 -m agent_maintainer verify --profile ci --base-ref origin/main --compare-branch origin/main
python3 -m agent_maintainer verify --profile security
python3 -m agent_maintainer verify --profile manual

Read more: tool map, diagnostics repair loop, verification cadence.

Supported Checks And Scans

Agent Maintainer does not replace these tools. It coordinates them, gives them stable profiles, captures artifacts, and turns failures into bounded repair context.

Read more: optional gates, supported scans and agent use, ecosystem provider status, multi-ecosystem reviewability policy,

mutation testing, architecture policy, test intelligence.

Ratcheting: Improve Existing Repos Without Freezing Them

Legacy repos usually cannot become strict overnight. Agent Maintainer separates new regressions from old debt:

• changed-code coverage can block new untested work;
• suppression budget blocks new broad noqa, type: ignore, and coverage escapes;
• file-length and structure checks can warn before they block;
• ratchet commands rank the next repair targets;
• mutation target/result ratchets keep high-value mutation testing focused.

Useful commands:

python3 -m agent_maintainer ratchet status
python3 -m agent_maintainer ratchet next
python3 -m agent_maintainer test-intel mutation-results
python3 -m agent_maintainer test-intel mutation-sweep

Read more: ratcheting, mutation testing, cohesive change plans.

How Agents Should Use It

For agent-heavy repos, install the agent track and commit the generated guidance:

agent-maintainer init --track agent --preset ai-agent-heavy
python3 -m agent_maintainer guidance

Then agents should follow this loop:

1. Read AGENTS.md and AGENTS.agent-maintainer.md.
2. Make a small, coherent change.
3. Run focused tests while editing.
4. Run python3 -m agent_maintainer verify --profile precommit before finishing.
5. If verification fails, inspect .verify-logs/LAST_FAILURE.md and use the suggested context command instead of dumping raw logs.
6. For larger work, run full, ci, security, and manual once before PR.

Helpful repair commands:

python3 -m agent_maintainer context failures --limit 20
python3 -m agent_maintainer context log pyright --tail 120
python3 -m agent_maintainer repair-plan
python3 -m agent_maintainer report html

Read more: agent hooks, context safety, diagnostics repair loop.

Trust Model

Agent Maintainer is designed to be safe to try:

• MIT licensed and open source.
• Package-first; downstream repos should not vendor src/agent_maintainer.
• Local-first verification; normal checks run against your repo and local tool outputs.
• Hooks no-op outside repos with [tool.agent_maintainer].
• Output is bounded; raw logs live in .verify-logs/runs/<run-id>/.
• Secret scan artifacts are treated as sensitive/redacted diagnostics.
• CI uses least-privilege permissions and package-index publishing uses trusted publishing.
• This repo dogfoods strict settings, Python 3.11-3.14 compatibility, release checks, mutation ratchets, OSV, SBOM, licenses, docs/config hygiene, Codex hooks, and Claude Code hooks.

Read more: Release checklist, troubleshooting, 0.1.0b4 release notes.

Configuration

Configuration can live in pyproject.toml or in a neutral Agent Maintainer config file. Python repos should usually keep using [tool.agent_maintainer] in pyproject.toml; mixed or future non-Python repos can use .agent-maintainer/config.toml or agent-maintainer.toml.

[tool.agent_maintainer]
mode = "custom"
architecture_tool = "import-linter"
source_roots = ["src"]
test_roots = ["tests"]
package_paths = ["src"]
coverage_source = ["src"]
require_tests = true
coverage_fail_under = 80
diff_cover_fail_under = 90

[tool.agent_maintainer.diagnostics]
enabled = true
log_dir = ".verify-logs"
run_history_limit = 10

Precedence is built-in defaults, mode defaults, file config, environment variables, then CLI flags. When multiple file configs exist, pyproject.toml [tool.agent_maintainer] wins; otherwise .agent-maintainer/config.toml wins over agent-maintainer.toml. Environment overrides use the AGENT_MAINTAINER_* prefix.

AGENT_MAINTAINER_SOURCE_ROOTS=src,tests python3 -m agent_maintainer doctor

Read more: quick start, structure cohesion, tool map.

Setup Recommendations

Ask Agent Maintainer to inspect the repo before choosing a track and preset:

python3 -m agent_maintainer assess setup
python3 -m agent_maintainer assess setup --json

The advisor recommends core, agent, or hardening; a starting preset; optional gates that match repository evidence; and follow-up prompts a coding agent should answer before tightening config.

Read more: setup advisor.

Reviewability Assessment

Inspect changed files by provider ecosystem and role without changing blocking policy:

python3 -m agent_maintainer assess reviewability
python3 -m agent_maintainer assess reviewability --json

This is advisory. In the current beta, blocking reviewability gates remain Python-backed while TypeScript/JavaScript policy adapters mature.

Read more:

multi-ecosystem reviewability policy.

Technical Debt Score

Generate an advisory maintenance-risk scorecard:

python3 -m agent_maintainer assess debt
python3 -m agent_maintainer assess debt --json
python3 -m agent_maintainer report html

The score is lower-is-better and decomposes into reviewability, tests/coverage, type/style, architecture, dependencies/security, docs/config hygiene, diagnostics, and ratchet/mutation maturity. It writes JSON and Markdown artifacts under .verify-logs and appears in the verification summary and HTML report when present.

Read more: Technical Debt Score.

Install From Source

For local development on Agent Maintainer itself:

git clone https://github.com/douglasmonsky/agent-maintainer.git
cd agent-maintainer
python -m pip install -e ".[core]"
agent-maintainer --help

Normal downstream repositories should use the package-first init flow rather than copying src/agent_maintainer into application source trees.

Local Development

For this repo:

PYTHONPATH=src python3 -m agent_maintainer bootstrap
PYTHONPATH=src python3 -m agent_maintainer doctor --strict
PYTHONPATH=src python3 -m agent_maintainer verify --profile precommit
PYTHONPATH=src python3 -m agent_maintainer verify --profile full

Refresh the pinned dev lock after changing config/dev-dependencies.txt:

PYTHONPATH=src python3 -m agent_maintainer bootstrap
.venv/bin/python -m pip freeze --exclude-editable | sort > config/dev-lock.txt

Read more: Release checklist, troubleshooting, roadmap.

Further Reading

• Changelog
• MIT License
• Context compression
• Cohesive change plans
• Roadmap blueprint index

Example starter projects:

• Fresh-strict example
• Legacy-ratchet example
• Context-safe ratchet proof example
• Cohesive change-plan proof example
• Test-intelligence proof example

Measured fixture case studies:

• Split large legacy file
• Context-safe ratchet repair