Agent Maintainer

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

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

Agent Maintainer helps Python repositories stay maintainable under AI-assisted development. It combines low-noise verification, change budgets, suppression controls, coverage gates, type checks, architecture checks, security checks, and structured diagnostics into one workflow for humans and coding agents.

What This Is

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

What This Is Not

Agent Maintainer is not a runtime AI safety system. It does not moderate model outputs, filter prompts, block jailbreaks, or validate chatbot responses. It is also not a prompt/output moderation framework. Agent Maintainer focuses on repository health during AI-assisted software development.

Quick Start

Install the core toolset:

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

Initialize a repository:

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

Merge config/pyproject.agent-maintainer.toml into your pyproject.toml, tune paths for your repo, then check setup health:

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

First Successful Run

Healthy setup output should be quiet:

PASS

doctor prints one compact PASS, WARN, or FAIL row per setup check. If verification fails, inspect generated diagnostics before changing thresholds or suppressions:

cat .verify-logs/LAST_FAILURE.md

The failure note includes failed checks, relevant artifact paths, and an exact rerun command.

The console command is convenient for local use. Committed automation should use the module entrypoint because it works reliably in editable local-source contexts:

python3 -m agent_maintainer verify --profile precommit

Adoption Tracks

init writes starter files for three adoption levels:

Preview writes before changing a repo:

python3 -m agent_maintainer init --track agent --dry-run

Existing files are not overwritten unless --force is passed.

Policy Presets

--track chooses which files are written. --preset tunes the starter policy in config/pyproject.agent-maintainer.toml:

Example:

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

Common Commands

python3 -m agent_maintainer bootstrap
python3 -m agent_maintainer doctor --strict
python3 -m agent_maintainer guidance
python3 -m agent_maintainer guidance --check
python3 -m agent_maintainer verify --profile fast
python3 -m agent_maintainer verify --profile precommit
python3 -m agent_maintainer verify --profile full
python3 -m agent_maintainer verify --profile ci
python3 -m agent_maintainer verify --profile security
python3 -m agent_maintainer verify --profile manual
python3 -m agent_maintainer report html
python3 -m agent_maintainer hooks status all
python3 -m agent_maintainer hooks install all --dry-run
python3 -m agent_maintainer hooks install claude-code --scope user
python3 -m agent_maintainer ratchet status
python3 -m agent_maintainer ratchet next
python3 -m archguard tach-config --strict-root-module
python3 -m archguard decision-check --base-ref HEAD

Profiles are intentionally stable:

What The Tool Checks

Configuration

Configuration lives in pyproject.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"

mode = "fresh-strict" is for new repositories that can block strict checks on day one. mode = "legacy-ratchet" is for existing repositories where heavier gates should remain opt-in while changed-code discipline ramps up. This repository self-enforces stricter settings than the starter template, including 90 percent total coverage.

Environment overrides use the AGENT_MAINTAINER_* prefix:

AGENT_MAINTAINER_SOURCE_ROOTS=src,tests python3 -m agent_maintainer doctor

Agent Guidance

The generated sidecar gives coding agents current repo policy without copying long instructions into every prompt:

python3 -m agent_maintainer guidance
python3 -m agent_maintainer guidance --check

This writes AGENTS.agent-maintainer.md from [tool.agent_maintainer]. Update configuration first, then regenerate the sidecar.

Optional Tooling

Install extras by adoption level:

python -m pip install "agent-maintainer[core]"
python -m pip install "agent-maintainer[hardening]"
python -m pip install "agent-maintainer[manual]"
python -m pip install "agent-maintainer[all]"

Node-backed tools such as markdownlint-cli2 and Taplo are managed through package.json when a repo opts into the hardening track:

npm ci

Install From Source

For local development on Agent Maintainer itself, clone the repository and run:

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

Further Reading

• MIT License
• Changelog
• Roadmap
• Context safety
• Test intelligence
• Ratcheting
• Cohesive change plans
• Context compression
• Tool map
• First run walkthrough
• Fresh-strict mode
• Legacy-ratchet mode
• Agent client hooks
• Cohesive-change overrides
• Release checklist
• Troubleshooting
• Structure cohesion

Example starter projects:

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