automaintainer/ docs
Dashboard →

Agent cheatsheet

A single‑page recipe for driving Automaintainer from an agentic CLI (hermes, Claude Code, etc.). Everything an orchestrating agent needs: setup, the full command surface, the JSON contract to branch on, and copy‑paste loops. You can save this page as a skill — or fetch the raw markdown at /docs/agent-cheatsheet.md.

What AM does

You give a repo a bounded objective; a fleet of agents implements it, verifies it (build → test → fix → re‑verify), and opens a merge‑ready PR. Done = verified.

Setup

am-cloud platform is the control CLI. Authenticate with two values (flags or env):

export AM_PANEL=wss://automaintainer.intrane.fr   # or --panel <url>
export AM_API_KEY=amk_...                          # or --api-key <key>

Output is JSON by default (stable schema + exit codes); add --human for text.

Command surface

platform status                                 # account + workers
platform repo list                              # → {repos:[{id,name,enabled,focus}]}
platform repo add <url> --focus <text>          # → {repo:{id,...}}
platform repo set <id> [flags]                  # see flags below
platform repo run <id> [--wait]                 # trigger; --wait polls to terminal
platform repo run --repo <url> [--focus <t>] [--wait]   # one-shot: add-if-missing → run
platform runs [--repo <id>]                     # → {runs:[...]}
platform explore <id>                           # kick a scout (Pro+)
platform candidates <id>                        # → {candidates:[{id,category,title,...}]}
platform candidate run|reject <cid>             # act on a candidate
platform probe --cli <c> [--model <m>]          # → {probe:{ok,reason,latency_ms}}

repo set flags (only the ones you pass are written): --focus · --verify (gate cmd) · --objective · --acceptance · --team (JSON) · --clis (JSON) · --arch-context · --name · --spawn-interval (int) · --explore · --auto-merge · --reviews · --issues · --issue-scout · --pr-watch · --enabled (bools; disable with =false).

JSON contract — what to branch on

Field Where Use
result every response "success" vs error envelope
probe.ok / probe.reason probe gate spend: only run if ok==true
run.status repo run --wait, runs success / verify_failed / success_no_changes / no_op (silent failure) / failed
run.verify_status run passed / failed / skipped
run.pr_url run the merge‑ready PR (empty if none)
candidates[].id candidates feed to candidate run

Run statuses: spawning · running · success · success_no_changes · no_op (agents did nothing — usually a key/balance issue) · verify_failed · pushed · failed. Exit code 0 = success; non‑zero = error (type + message in the JSON).

Recipe 0 — one-shot (the fastest path)

"Use AM to enrich docs/ in this repo, run now" — a single idempotent command that adds the repo if it's new, sets the focus, runs, and waits for the verified PR:

am-cloud platform repo run \
  --repo https://github.com/javimosch/supercli \
  --focus "enrich docs/" --wait
#   → {"run":{"status":"success","verify_status":"passed","pr_url":"…/pull/42"}}

Re-running the same --repo URL reuses the existing repo (no duplicate) and updates the focus. To configure the gate/team/etc. first, use repo set (below), then repo run <id> --wait.

Recipe 1 — maintain a repo (verify before you spend)

# 1. confirm the EXACT model works (avoids silent no-op runs)
am-cloud platform probe --cli pi --model opencode-go/deepseek-v4-flash
#   → {"probe":{"ok":true,"latency_ms":2598}}   # if ok==false, fix the key/balance first

# 2. set the focus + the gate
am-cloud platform repo set r-123 \
  --focus "add a unit test for the untested parseConfig()" \
  --verify "npm ci && npm run test:unit"

# 3. run it and WAIT for the verified result
am-cloud platform repo run r-123 --wait
#   → {"run":{"status":"success","verify_status":"passed","pr_url":"…/pull/42"}}

Recipe 2 — let AM choose the work (explore)

am-cloud platform explore r-123                 # scout proposes bounded work
am-cloud platform candidates r-123              # → pick a candidate id
am-cloud platform candidate run <candidate-id>  # applies its focus+gate and runs

Recipe 3 — self‑healing loop (pseudo)

probe → if !ok: stop, report reason
repo set --focus … --verify …
loop up to N:
  run --wait
  if run.verify_status == "passed":   done → run.pr_url
  if run.status == "no_op":            stop → probe the cli/model (key/balance)
  if run.status == "success_no_changes": refine focus, retry
  else: read run, adjust, retry

Gotchas (save a run)

  • Probe first. A green background probe tests the default model; always probe the exact cli/model you'll use — out of balance is the #1 no‑op cause.
  • Gate runs from the repo root, relative paths only — no cd /abs/path.
  • Objective vs focus: --focus is this run; --objective is a persistent campaign AM keeps working until --acceptance passes.
  • A red gate never auto‑merges — it opens a draft.

Prefer native tool-calls over shelling out? Run the same surface as an MCP server: MCP server (am-cloud mcp, stdio).

Full reference