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.

Latest published package: agent-maintainer==0.1.0b6, with immutable release evidence. See the upgrade guide for package-index adoption and rollback guidance. This checkout targets the unpublished 0.1.0b7 release candidate; see its candidate notes and evaluation guide.

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 under .verify-logs, and gives agents exact repair commands instead of dumping huge logs into chat.

Read more where it matters:

• Quick start
• New-repository setup skill
• First run walkthrough
• Diagnostics loop
• Tool map
• Dependency risk register
• Security policy
• Support policy
• Contributing
• Code of Conduct

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 actively edits the repo: the agent gets a compact pass/fail summary, 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]==0.1.0b6"

That pin installs the latest published beta. Follow the 0.1.0b6 upgrade guide for safe adoption and rollback guidance.

Initialize a repo:

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

For CI-only adoption without local hooks:

agent-maintainer init --ci-only

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

The 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 with the shortest available completion command:

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. Each track uses generated initializer templates so downstream repos receive the config, workflow, hook, and metadata files for their adoption level without vendoring Agent Maintainer source.

Generated hook configuration keeps commits responsive by running the fast staged profile plus mapped affected Python tests at pre-commit. It preserves the complete local safety gate by running the precommit profile at pre-push. That hook uses the exact outgoing SHAs supplied by pre-commit and fails closed if the pushed local SHA is not the checked-out HEAD or the checkout has staged, unstaged, or untracked changes; invoke it through git push from a clean checkout rather than a ref-less manual hook-stage run. agent-maintainer install installs both Git hook types, and doctor reports either missing hook instead of treating a partial installation as healthy.

Use agent-maintainer init --ci-only when a repo only needs the GitHub Actions verification workflow and config/dev-dependencies.txt, without local hooks or starter policy config.

The hardening track declares Node.js 22 or newer for its optional npm-backed Markdown and TOML tooling instead of silently installing incompatible versions.

Agent and hardening scaffolds render Codex and Claude Code configuration plus every referenced post-edit, PR-wait, stop, and audit wrapper from the same managed-file inventory used by install, update, status, and uninstall. Generated wrappers are checked for byte-for-byte currentness rather than existence alone.

Preview before writing:

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

The preview classifies each destination as add, unchanged, merge, conflict, or skip without requiring force. Apply refuses the whole plan while an unresolved conflict remains, preserves user-owned AGENTS.md, backs up explicit forced replacements, and rolls back earlier writes if a later destination fails.

Presets tune policy:

Read more:

• Quick start
• Legacy ratchet
• Fresh strict
• Team policy templates

Run Profiles

When a repository has .docsync/trace.yml, the local profiles also run DocSync freshness checks so code and documentation claims stay in sync.

Canonical commands:

agent-maintainer verify --profile precommit
agent-maintainer verify --profile full
agent-maintainer verify --profile ci --base-ref origin/main --compare-branch origin/main
agent-maintainer verify --profile security
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.

The verifier invokes DocSync with --write-reports so JSON/SARIF repair artifacts are an explicit integration output. A standalone docsync check remains read-only.

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 attention update
python3 -m agent_maintainer attention top
python3 -m agent_maintainer events summary
python3 -m agent_maintainer events waste
python3 -m agent_maintainer events export --format jsonl
python3 -m agent_maintainer events export --format otel-json
python3 -m agent_maintainer scoring examples list
python3 -m agent_maintainer scoring examples export --format jsonl
python3 -m agent_maintainer verify --profile full --async
python3 -m agent_maintainer wait github-run <run-id>
python3 -m agent_maintainer wait verifier <run-id>
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. Let trusted Stop/SubagentStop hooks cover precommit for the final state. Run just verify-precommit only when hooks are unavailable, bypassed, or a failure needs reproduction.

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 one broad local profile before PR, usually full. Use ci instead when diff/base-ref, workflow, or profile behavior changed; run both only when that overlap is under test. Run security or manual when touching those gates, before release, or when explicitly requested.

7. When GitHub Actions or verifier jobs are still running, use just wait-github <run-id>, just wait-pr <pr-number>, or just wait-verifier <run-id> so the tool owns polling and returns one final repair capsule.

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, release index, 0.1.0b6 release evidence, 0.1.0b6 upgrade guide, 0.1.0b7 candidate notes, 0.1.0b7 evaluation guide.

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.

Known commands validate the complete resolved policy before running behavior. Invalid configuration exits with status 2 and reports the source plus dotted key; help remains available for repair and discovery.

AGENT_MAINTAINER_SOURCE_ROOTS=src,tests python3 -m agent_maintainer doctor

Read more: quick start, configuration reference, 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.

File Baseline Assessment

Inspect simple file facts across configured file groups without changing blocking verifier policy:

python3 -m agent_maintainer assess file-baselines
python3 -m agent_maintainer assess file-baselines --json

This is advisory. It works from explicit include/exclude globs and reports matched files, changed files, changed lines, line-count findings, and compact next commands. It is the broad filetype/path layer for docs, config, tests, TSX, YAML, TOML, or other file groups; language-specific architecture still belongs to provider adapters such as Tach for Python.

Read more:

provider-neutral file baselines.

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, use the checked-in command wrappers so agents do not have to reconstruct long environment-prefixed commands:

just bootstrap
python3 -m agent_maintainer install --dry-run
python3 -m agent_maintainer install
just doctor
just verify-precommit
just verify

bootstrap installs development dependencies only. Hook and pre-commit setup is an explicit, previewable install action.

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

just bootstrap
just refresh-dev-lock

The repository pins direct development tools in config/dev-dependencies.in and uses pip-compile under Python 3.13 to resolve their compatible graph into config/dev-lock.txt. Dependabot groups compatible direct updates; it does not propose isolated transitive-lock edits.

Read more: Release checklist, troubleshooting, roadmap.

Further Reading

• Changelog
• MIT License
• Security
• Support
• Contributing
• Pre-1.0 API support
• Subsystem stability
• 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