Optimizer skill reference

The detail behind step 1 of the Amdahl Optimizer skill: check setup with setup_status, fix each blocker, create an API key for a server or CI, and read every refusal and ok-false reason.

The Amdahl Optimizer skill keeps its first step short. This page holds the detail it points to. Load it when a call is refused, when you run on a server or in CI, or when ok comes back false.

Check your setup

One read tells you whether this credential can optimize, and what to fix if it cannot. It changes nothing and works on every key and connector.

MCP: the connections tool with {"action": "setup_status"}. It takes no other parameters.
REST: GET https://app.amdahl.ai/api/platform/v1/setup/status.

bash

curl -s https://app.amdahl.ai/api/platform/v1/setup/status \
  -H "X-API-Key: $AMDAHL_KEY" | jq '.data.optimize'

Read optimize:

allowed: true: go ahead and optimize.
allowed: false: blocker names the one thing to fix (table below).
quota: this month's optimizations for API and connector calls, as limit, used, remaining and resets_at. It is null when the caller is not metered.

The same response names the workspace (its name under workspace), who is calling (email and role under caller) and how (auth_method). Use them to confirm the user connected the workspace they meant. The full response is on Connections.

Fix each blocker

`optimize.blocker`	What it means	Tell the user
`missing_scope`	The credential does not carry `messages:execute`. It is a Read only key, a key older than the Optimizer, or a connector authorized before the Optimizer existed.	With a key: create a new key with Access set to Customer agent (steps below). With a connector: disconnect and reconnect Amdahl (in Claude: Settings, then Connectors) and sign in again.
`role_too_low`	Their workspace role is Viewer. Optimizing needs Editor or above.	Ask a workspace admin to raise their role.
`quota_exhausted`	The workspace used this month's API and connector optimizations.	Wait until `quota.resets_at`.

Use an API key on a server or in CI

A server, a CI job or a terminal agent with no Amdahl connector uses the REST API with an API key in the environment variable AMDAHL_KEY.

Check whether the key is available, in the environment or in a .env file in the project folder: test -n "$AMDAHL_KEY" || grep -q '^AMDAHL_KEY=' .env 2>/dev/null && echo set. Never print its value.
If it is not set, the user creates one in their terminal:
- npx @amdahl/cli login, then npx @amdahl/cli keys create --name "Optimizer" --preset agent.
- The terminal shows a code and opens the console. The user types the code there and clicks Approve. The terminal prints the key once; it starts with amdhl_.
- Without a terminal, the user creates it in the console instead: console.amdahl.ai, Settings, then Developer, Create key, with Access kept at Customer agent (the default).
- Save it in a .env file so it lasts beyond this session. Tell the user to open the .env file in their project folder in their editor (create it if there is none) and add one line, AMDAHL_KEY=amdhl_..., with their key in place of amdhl_.... Editing the file keeps the key out of the chat and out of their shell history.
- Make sure .env is listed in .gitignore so the key is never committed. Check it yourself, and if it is missing, ask before adding the line .env to .gitignore.
- Nothing needs restarting: load the file before each call (set -a; [ -f .env ] && . ./.env; set +a).
If the user pastes a key into the chat instead, say once that a key in a chat stays in its history and suggest the environment variable. If they still want to go ahead, use it for this session only, and remind them to revoke it when done (amdahl keys revoke <prefix>, or Settings, then Developer).

No workspace yet? Amdahl is in beta. They can try the optimizer at console.amdahl.ai/try with 25 free runs, which also puts them on the waitlist, or join the waitlist at console.amdahl.ai/new. Amdahl emails them when they are in. If their company already uses Amdahl, an admin there can add them instead.

Codex users who connect over MCP rather than a key: npx @amdahl/cli install codex adds the server with required = true, so Codex waits for Amdahl before it starts. Then codex mcp login amdahl signs in.

Refusals

What you see	What it means	Tell the user
`200` (REST), or the `messages` tool is listed (MCP)	Connected: the key or sign-in works and the workspace answers.	"You're connected. Let's optimize your first email."
`401`	The key is missing, wrong, revoked or expired.	Create a new Customer agent key.
`403`, "Missing required scope(s): messages:execute" (MCP: "optimize requires the messages:execute scope")	The key is Read only, or older than the Optimizer. Over MCP, the connector was authorized before the Optimizer existed.	Create a new Customer agent key, or reconnect the connector.
`403`, `Role "viewer" is below required "editor"`	Their workspace role is Viewer. Optimizing needs Editor or above.	Ask a workspace admin to raise their role.
`429`, `quota_exceeded`	The workspace used this month's optimizations.	Stop the batch. Check `quota.resets_at` with `setup_status`.

When you are not sure which one applies, run the setup check above: optimize.blocker names it.

When `ok` is false

Nothing was rewritten and there is no message. Keep the user's draft.