This is the shortest package-first path for trying Agent Maintainer in a Python repository.
Install the core dependency set:
python -m pip install "agent-maintainer[core]"For source-checkout development on Agent Maintainer itself, use an editable install instead:
python -m pip install -e ".[core]"Run the initializer from the target repository:
agent-maintainer init --track core --preset existing-appFor CI-only adoption without local hooks:
agent-maintainer init --ci-onlyPreview the files first with --dry-run:
agent-maintainer init --track core --preset existing-app --dry-runPreview classifies every destination as ADD, UNCHANGED, MERGE, CONFLICT,
or SKIP and never requires --force. Apply is all-or-nothing when unresolved
conflicts remain. Supported dependency, package metadata, Codex, and Claude
files merge without deleting unrelated content; existing AGENTS.md is
preserved. Explicitly forced conflicts are backed up under Git-private
.git/agent-maintainer/backups/init/<transaction>/ storage with rollback
instructions. Non-Git targets fall back to .agent-maintainer/backups/init/.
The initializer writes starter files:
config/pyproject.agent-maintainer.tomlconfig/dev-dependencies.txt.pre-commit-config.yaml.github/workflows/verify.yml
Merge the starter TOML into your root pyproject.toml, then tune source, test,
package, and coverage paths for the repository.
Run:
agent-maintainer doctor
agent-maintainer verify --profile precommitA healthy verification run is intentionally quiet:
PASS
If verification fails, inspect the bounded repair note first:
cat .verify-logs/LAST_FAILURE.mdFailure notes point at a run-scoped directory under .verify-logs/runs/, so a
later hook run does not overwrite details needed to repair the failure.
Use core for ordinary Python repositories.
Use agent when Codex, Claude Code, or another coding agent actively edits the
repo.
Use hardening when the repo should also start with docs/config hygiene and
security-adjacent starter files.
Read more: