Command line

Install the engine from the repository (Rust 1.89+ and Git are required):

cargo install --git https://github.com/djsydney04/repo_maintainer --locked

Install your chosen coding agent and the tools named in your project checks on that worker. New configurations use Codex; configure its account before running. The engine runs locally on macOS or Linux.

Three commands to start

cd /path/to/repository
repo-maintainer init
# Edit .maintainer.yml: task, editable files, setup and checks.
repo-maintainer check
repo-maintainer run --task task.md

init keeps existing configuration. check makes no inference request. run appends the task file to the repository's configured instructions; it preserves editable paths, agent budgets and validation settings. Without --task, it uses the configured task. Task files must contain 1–64000 UTF-8 bytes.

Automation

repo-maintainer check --repo /path/to/repository --json
repo-maintainer run --repo /path/to/repository --task task.md --json
printf '%s' 'Fix the empty search state and add a regression test.' | repo-maintainer run --task - --json

--task - reads task text from stdin. --json supports run and check; it prints a single versioned JSON object to stdout. Progress and error text use stderr. Exit codes are 0 for success, 2 for a blocked run with retained results, and 1 for an operational error. Argument syntax errors are reported by the argument parser before JSON execution starts.

Use --config PATH to select a configuration. Relative config paths resolve against --repo; relative task and output paths resolve against the caller's working directory. --output PATH chooses an empty directory for artifacts. Otherwise each run gets a unique .maintainer-output/run-* directory.

What a run guarantees

The source is a temporary clone of committed HEAD. A changed proposal is applied to a fresh checkout and independently validated with the configured commands. Failed checks return blocked, retain the patch, and never change the original checkout. An unchanged proposal skips independent patch validation.

The output directory contains result.json, report.json, proposal.patch, events.jsonl, and preparation/agent evidence. A successful changed proposal also has validation.json. Review artifacts before applying a patch; no local command publishes a PR unless you explicitly use the separate publishing stage.

Read the result contract. The lower-level setup, prepare, agent, collect, apply, validate, publish and notify commands remain available for custom orchestration.

Script-generated requests

A script can emit JSON containing config and an optional task. No YAML is needed:

python make_request.py | repo-maintainer run --request - --json
repo-maintainer check --request request.json --json

Example request.json:

{
  "config": {
    "version": 2,
    "agent": {"allow_paid": true},
    "validation": {"checks": [{"name": "tests", "command": ["npm", "test"]}]}
  },
  "task": "Repair one reproducible bug and add a regression test."
}

For check, omit task. Requests are limited to 320 KB, configuration to 256 KB, and task text to 64000 UTF-8 bytes. Unknown request fields are rejected. Do not combine request with config or task flags. The engine parses JSON; it does not execute a configuration file as code. Run your trusted script yourself and pipe its output, or use an SDK.

Hosted runs

Use repo-maintainer cloud --help for hosted submission, status, cancellation and artifact downloads. CLI and GitHub automation explains credentials, YAML task files, JSON responses and the hosted preview availability limits.