Guidelines

How to actually use Fettle, and why every fix is safe by construction.

The safe loop

  1. 01
    Diagnose
    Fettle turns trace data into metrics + findings, each routed to fix / coach / patch.
  2. 02
    Isolate
    Codex edits a throwaway copy of the agent — never your live code.
  3. 03
    Gate
    A benchmark (a machine-checkable definition of “fixed”) decides merge vs rollback.
  4. 04
    Merge or roll back
    Only --apply on a passing gate touches the real agent. Everything is reversible.

Commands

fettle checkHealth-check every agent Fettle knows about and list what needs attention.
fettle fix <id>Repair bugs — stale tool schemas, broken calls, retry storms.
fettle coach <id>Refactor to a better professional workflow and explain the change.
fettle patch <id>Close security holes — prompt-injection exposure, leaked secrets.
fettle watchArm the guardian: maintain idle agents automatically on an interval.

Flags

--dry-run

Show the exact plan Fettle would hand to Codex, without running anything. Zero cost.

--apply

Merge the fix into the real agent — but only if the benchmark gate passes.

--bypass-sandbox

Run Codex without its OS sandbox. Use when the host sandbox is unavailable (e.g. it clashes with antivirus on Windows).

A typical run

fettle check
fettle fix support-bot --dry-run     # inspect the plan
fettle fix support-bot --apply       # fix, gate, merge