Docs
The CLI, the agent skill
and MCP
One command to submit, one to retrieve the patch. Every step in between — what gets uploaded, when credits are spent — is shown to you and confirmed before it happens.
pipx install autooptminstalls into an isolated environmentautooptm loginapprove this machine in your browserautooptm run . --entrypoint train.pyfree estimate; asks before chargingInstall
autooptm is a command-line tool; install it into an isolated environment with pipx or uv tool. Homebrew Python on macOS and recent Debian / Ubuntu releases reject a bare pip install into the system environment; both of these methods work around that.
$ pipx install autooptm # or $ uv tool install autooptm $ autooptm --help
The MCP server needs one extra dependency: pipx install 'autooptm[mcp]'.
Sign in
autooptm login opens your browser so you can approve this machine. The terminal then receives a 30-day token, renewed on every use and stored at ~/.config/autooptm/token.
$ autooptm login signed in as you@example.com; token saved to ~/.config/autooptm/token (valid 30 days, and it slides on use) # a server with no browser: print the approval URL, open it anywhere $ autooptm login --no-browser # or the email code (QQ / 163 mail work): one command sends it, the next verifies $ autooptm login --email you@example.com $ autooptm login --email you@example.com --code 482913 $ autooptm balance 12.4 credits (≈ $12.4) $ autooptm logout
CI and scripts: API keys
Where a browser is not available, use an API key. The key is shown only once. Default scopes are read,submit; unlock spends credits and must be granted explicitly. Set it as AUTOOPTM_TOKEN and the CLI picks it up automatically.
$ autooptm keys create "CI pipeline" --scopes read,submit --expires-in-days 90 $ autooptm keys list $ autooptm keys revoke <keyId> $ export AUTOOPTM_TOKEN=ao_…
A complete run
run takes a public Git URL or a local directory and handles the entire flow: packaging, the free estimate, confirming whether to continue, waiting for results, and quoting the patch price. If your connection drops, the job keeps running on our side; wait reattaches to it.
Mirror the command you normally run: the entry script goes in --entrypoint, the remaining arguments in --args. Leave the GPU on auto to run on an RTX 4090; choose RTX5090 if your model does not fit; choose CPU if the program uses no GPU, in which case there is no machine charge at all.
A local directory is inventoried on your machine first. You are asked about weights, data, large files and very large directories one by one, and nothing is uploaded until you confirm. See what gets uploaded.
A static scan that finishes in seconds; none of your code runs and nothing is charged. It reports the expected speedup and its range, then asks whether to continue.
Answer y and the 2-credit analysis deposit is taken, credited in full against the patch and returned when no speedup is found or the failure is ours. Answer n, or don't answer, and the job stays at the estimate, free of charge.
When the run finishes, it reports the measured end-to-end speedup and the patch price. unlock confirms once more before charging and writes autooptm.patch; git apply does the rest. Under 1.10× no patch is sold and the deposit comes back.
$ autooptm run . --entrypoint train.py --workload training --gpu auto skipped: .git (1), __pycache__ (14) y = into the code archive · n = leave out · d = upload as the private dataset instead (sandbox only, 7 days, up to 1 GB, one per run) checkpoints/ weight files: 2, 1.9 GB (.pt×2) include? [y/N/d] n data/ crowded directory: 1204 files, 310 MB (0 of 1204 files are code) include? [y/N/d] d data/ goes up as the dataset, unpacked at ./data packing 87 files, 1.4 MB before compression: src/ 62 files 1.1 MB configs/ 14 files 38 KB train.py 1 files 12 KB dataset: /home/you/repo/data -> ./data in the sandbox upload? [Y/n] y job 7f3c2a1b queued estimate: expected 1.6x · range 1.2x - 2.3x · lossless 1.4x next: autooptm decide 7f3c2a1b continue (takes the deposit, credited against the unlock) autooptm decide 7f3c2a1b stop (free) continue? takes the analysis deposit (2 credits), credited against the unlock. [y/N] y … 1.61x (937.8s -> 582.5s) patch: locked. unlock for 4.6 credits (autooptm unlock 7f3c2a1b) report: https://api.autooptm.com/api/my/reports/… $ autooptm unlock 7f3c2a1b Unlock spends 4.6 credits. Continue? [y/N] y $ git apply autooptm.patch
autooptm wait <jobId> resumes waiting, autooptm status <jobId> checks its status, autooptm estimate <jobId> shows the estimate again.What gets uploaded
A local directory is scanned and packaged on your machine. You decide what goes into the code archive:
| Category | Handling |
|---|---|
| .git, caches, virtualenvs, editor state | Skipped, noted once on a skipped: line: __pycache__, .venv, node_modules, wandb, .idea, .DS_Store and the like. |
| Weight filesasked | .pt .pth .ckpt .safetensors .onnx .npz .bin .gguf and similar, listed per directory, excluded by default. |
| Data filesasked | Images, audio, video, tables, .npy / .h5 / .pkl, archives and similar, listed per directory, excluded by default. |
| Any file over 8 MBasked | Listed individually, excluded by default. |
| A directory with over 200 filesasked | Listed with its file count, size and share of code. Included by default when at least half is code (e.g. src/), excluded otherwise (e.g. outputs/). |
Each group takes one of three answers: y to include it in the code archive, n to leave it out, or d to upload it as the private dataset. The dataset travels through a separate channel: sandbox only, deleted after seven days, up to 1 GB, and extracted at the same relative path so your command does not change. One dataset per run. Once you have answered, the packing list is printed, and nothing is uploaded until you confirm. The code archive is capped at 64 MB compressed.
# only show the list; nothing leaves the machine $ autooptm run . --entrypoint train.py --dry-run # answer from the command line instead of the prompts $ autooptm run . --entrypoint train.py --include checkpoints --exclude outputs --yes # send a directory as the dataset, unpacked at ./data in the sandbox $ autooptm run . --entrypoint train.py --dataset ./data --dataset-path data --yes
--yes, run prints the list and stops (exit 1). Preview with --dry-run first, then submit with --include / --exclude and --yes.Command reference
| Command | What it does | Flags |
|---|---|---|
| run SOURCE | Submit a public Git URL or a local directory and wait for completion. The free estimate runs first and asks before continuing; --no-wait returns immediately after submission. | --entrypoint main.py--workload training|inference--gpu auto|RTX4090|RTX5090|CPU--args "…"--setup FILE--git-ref REF--model opus|glm--lang zh|en--dataset DIR_OR_ARCHIVE--dataset-path ./data--include PATH--exclude PATH--dry-run--no-estimate--no-wait--yes |
| wait JOB | Resume waiting on a job after a dropped connection or --no-wait. If the job is parked at the estimate, you are asked again whether to continue. | --yes--timeout SECONDS |
| estimate JOB | Show the free estimate again: expected value, range, the lossless tier and the review notes. | |
| decide JOB continue|stop | Answer the estimate. continue takes the 2-credit deposit, stop is free; no answer within seven days counts as stop. | --yes |
| status JOB | Show a job's current state, speedup and price. | |
| unlock JOB | Pay the quoted credits and download the patch. Confirms before charging; you never pay more than the quote. | --yes--out autooptm.patch |
| cancel JOB | Stop a queued or running job. A cancelled run is not charged. | |
| balance | Show available credits. | |
| datasets | List datasets this account has uploaded that have not yet expired; each can be reused directly by its key. | |
| login | Sign in by approving this machine in the browser, or use --email to sign in with an emailed code. | --no-browser--email ADDR--code NNNNNN--role … |
| logout | Remove the locally saved token. | |
| keys create|list|revoke | Manage API keys for CI and scripts. | create NAME --scopes read,submit,unlock --expires-in-days N |
| install-skill | Install the Claude Code skill into this machine's skills directory (see below). | --dest DIR |
Claude Code skill
The skill ships with the package, so there is nothing else to download. Once the CLI is installed and signed in, a single command installs it into Claude Code's skills directory:
$ pipx install autooptm $ autooptm login $ autooptm install-skill installed autooptm-optimize -> ~/.claude/skills/autooptm-optimize/SKILL.md # somewhere else, e.g. a project-level skills directory $ autooptm install-skill --dest ./.claude/skills
Then open your repository in Claude Code and say "speed this repo up with AutoOptm", or invoke /autooptm-optimize. The skill guides Claude Code through the entire flow:
Find the command that runs training or inference end to end, asking you when unsure.
--dry-runAn agent has no interactive terminal, so it first lists what would be uploaded and what stays out, and submits with --include and --yes only after you agree.
It runs decide continue only with your explicit approval; otherwise the job stays at the free estimate.
It reports the speedup and the price, waits for your approval before running unlock, then runs git apply.
pipx install autooptm, autooptm login and autooptm install-skill again; the token does not travel with the skill.MCP
Claude Code, Cursor or any MCP client can call it directly. Install the package with the mcp extra and register autooptm-mcp in the client's configuration:
$ pipx install 'autooptm[mcp]' $ autooptm login
{
"mcpServers": {
"autooptm": { "command": "autooptm-mcp" }
}
}
Tools: optimize_submit, optimize_estimate, optimize_decide, optimize_status, optimize_wait, optimize_cancel, unlock_patch, download_patch, account_balance. The rules match the CLI: optimize_submit parks at the free estimate, only optimize_decide takes the deposit, and unlock_patch needs the user's explicit confirmation. Submitting a local directory returns upload, listing what was packed and what was left out; resubmit with include to add a group back.
Environment and scripts
| AUTOOPTM_TOKEN | An API key or login token; when set, the locally saved token file is ignored. |
| AUTOOPTM_API | The API base URL; defaults to https://api.autooptm.com. |
| XDG_CONFIG_HOME | Parent of the token file's directory; defaults to ~/.config. |
Non-interactive behavior
Every step that spends credits or uploads files requires explicit consent, which a script gives with --yes. Without it: run on a local directory prints the list and exits 1 without uploading; once the estimate is in, run prints parked at the estimate and exits 0, and the job waits free of charge until you answer with decide; unlock refuses. Transient errors (rate limits, network hiccups) are retried automatically; a submit, which must never be duplicated, is resent only when the server explicitly asks to retry later.