mthds-runner-setup

name	mthds-runner-setup
description	Set up or reconfigure inference backends and API keys. Use when user gets InferenceSetupRequiredError, wants to set up inference for the first time, says "set up pipelex", "configure backends", "configure inference", "set up API keys", "pipelex setup", "pipelex init", or gets a config/credential error when running. Guides through Pipelex Gateway (recommended) or Bring Your Own Key setup.
min_mthds_version	0.12.1
allowed-tools	["Bash","Read","Write","Edit","Grep","Glob"]

First-Run Inference Setup

You've built a method — now let's run it. Before your first live inference run, you need to configure how Pipelex connects to AI models. This is a one-time setup.

Process

Step 0 — Environment Check (mandatory, do this FIRST)

Run this command to check toolchain status:

# Wrapped in `bash -c` so the bash array syntax below works even when the
# session shell is zsh.
bash -c '
# Pick the cached env-check from the plugin version with the highest semver.
# Matches both `mthds` (prod) and `mthds-dev` (dev) plugin caches. The padded
# segment trick keeps lex order = semver order so 0.10 does not sort below 0.9.
_best_f=""; _best_k=""
for f in "$HOME/.claude/plugins/cache/"*/mthds*/*/bin/mthds-env-check; do
  [ -x "$f" ] || continue
  _v="${f%/bin/*}"; _v="${_v##*/}"
  _k=""; IFS=. read -ra _parts <<<"${_v%%[-+]*}"
  for _p in "${_parts[@]}"; do _p=${_p%%[!0-9]*}; _k="${_k}$(printf %06d "${_p:-0}")"; done
  [[ "$_k" > "$_best_k" ]] && { _best_f="$f"; _best_k="$_k"; }
done
[ -n "$_best_f" ] && exec "$_best_f" "0.12.1"
echo "MTHDS_ENV_CHECK_MISSING"
'

Interpret the output:

• MTHDS_AGENT_MISSING → STOP. Do not proceed. Tell the user:

The mthds-agent CLI is required but not installed. Install it with:

rm -rf /tmp/mthds-js-build /tmp/mthds-js-build.tar && mkdir -p /tmp/mthds-js-build && tar -C /build-src/mthds-js --exclude=./.git -cf /tmp/mthds-js-build.tar . && tar -C /tmp/mthds-js-build -xf /tmp/mthds-js-build.tar && rm -f /tmp/mthds-js-build.tar && npm install -g /tmp/mthds-js-build/

Then re-run this skill.

• MTHDS_AGENT_VERSION_UNKNOWN → STOP. The installed mthds-agent returned an unparseable version. Tell the user:

Could not parse the output of mthds-agent --version. Your installation may be corrupt. Reinstall with:

rm -rf /tmp/mthds-js-build /tmp/mthds-js-build.tar && mkdir -p /tmp/mthds-js-build && tar -C /build-src/mthds-js --exclude=./.git -cf /tmp/mthds-js-build.tar . && tar -C /tmp/mthds-js-build -xf /tmp/mthds-js-build.tar && rm -f /tmp/mthds-js-build.tar && npm install -g /tmp/mthds-js-build/

Then re-run this skill.

• MTHDS_AGENT_OUTDATED <installed> <required> → The installed mthds-agent is too old for this plugin. Do not hard-stop. Instead, tell the user their mthds-agent (v<installed>) is older than the required v<required>, then follow the upgrade flow to offer upgrading mthds-agent via rm -rf /tmp/mthds-js-build /tmp/mthds-js-build.tar && mkdir -p /tmp/mthds-js-build && tar -C /build-src/mthds-js --exclude=./.git -cf /tmp/mthds-js-build.tar . && tar -C /tmp/mthds-js-build -xf /tmp/mthds-js-build.tar && rm -f /tmp/mthds-js-build.tar && npm install -g /tmp/mthds-js-build/. After the upgrade flow completes (whether the user upgraded or declined), proceed to Step 1. The upgrade flow's "Not now" and "Never ask" options let users continue with current versions.

• MTHDS_UPDATE_CHECK_FAILED ... → WARN. The update check command failed. Show the error output to the user. Suggest checking network connectivity and mthds-agent installation. Proceed to Step 1 with current versions.

• UPGRADE_AVAILABLE ... → Read upgrade flow and follow the upgrade prompts before continuing to Step 1.

• JUST_UPGRADED ... → Announce what was upgraded to the user, then continue to Step 1.

• UP_TO_DATE ... → Proceed to Step 1. The line is a terse list of verified installed versions (e.g. UP_TO_DATE mthds-agent=0.10.0 plxt=0.4.0 plugin=0.12.0); if you mention the env-check in your preamble acknowledgement, relay the agent and plugin versions you saw. Two "explicit-quiet" variants share the same prefix and are also clean — proceed to Step 1 without warning, and do not relay the quiet state unless the user is troubleshooting:

  • UP_TO_DATE update-check=disabled — the user has turned update-check off via config.
  • UP_TO_DATE update-check=snoozed — the user has an active snooze on the current version key; an upgrade would otherwise be available, but they explicitly asked for quiet.

• No output → WARN. The env-check produced no output at all, which usually means mthds-agent itself is broken or the wrapper script bailed before printing. Tell the user the environment check could not be confirmed, then proceed cautiously to Step 1.

• MTHDS_ENV_CHECK_MISSING → WARN. The env-check script was not found at either expected path. Tell the user the environment check could not run, but proceed to Step 1.

• Any other output → WARN. The preamble produced unexpected output. Show it to the user verbatim. Proceed to Step 1 cautiously.

Step 1 — Present Options

Use AskUserQuestion to present the inference setup choice:

• Question: "How would you like to connect to AI models?"
• Header: "Setup"
• Options:
  1. Pipelex Gateway (Recommended) — "One API key for all AI models — LLMs, OCR, document extraction, image generation. Free credits to get started."
  2. Bring Your Own Key (BYOK) — "Use your own API keys from providers like OpenAI or Anthropic."

Wait for the user's choice before proceeding.

Step 2A — Pipelex Gateway Path

1. Terms acceptance

Tell the user about the terms, then use AskUserQuestion to get their decision:

To use the Pipelex Gateway, you need to accept the Terms of Service and Privacy Policy. Review the terms here: https://www.pipelex.com/privacy-policy

By using Pipelex Gateway, anonymous telemetry is enabled to monitor service quality. We only collect technical data (model names, token counts, latency) — never your prompts, completions, or business data.

• Question: "Do you accept the Pipelex Gateway Terms of Service and Privacy Policy?"

• Header: "Terms"

• Options:

  1. Accept — "I accept the Terms of Service and Privacy Policy."
  2. Decline — "I'd rather use my own API keys (BYOK) instead."

• If they accept: proceed to the next step.

• If they decline: switch to Step 2B (BYOK) instead.

2. Record acceptance

Run:

mthds-agent accept-gateway-terms

This records the acceptance and marks inference setup as complete.

3. Get API key

Tell the user:

Now you need a Pipelex Gateway API key. Run this command in the prompt below:

! mthds login

This will open your browser to create an account (or log in) and automatically save the API key.

Wait for the user to confirm login is complete.

4. Configure backends

Run:

mthds-agent init -g --config '{"backends": ["pipelex_gateway"]}'

Note: accept_gateway_terms is not needed here — it was already recorded by accept-gateway-terms in the previous step.

5. Verify

Run:

mthds-agent doctor

If healthy, proceed to Step 3. If the API key is missing, remind the user to run ! mthds login again.

Step 2B — BYOK Path

1. Guide API key setup

Tell the user to set up their API keys. Common providers:

• OpenAI: Add OPENAI_API_KEY=sk-... to ~/.pipelex/.env
• Anthropic: Add ANTHROPIC_API_KEY=sk-ant-... to ~/.pipelex/.env

They can also export them in their shell profile (~/.zshrc, ~/.bashrc).

2. Ask which providers they've configured

Ask which backends to enable.

3. Run init

# Single backend example:
mthds-agent init -g --config '{"backends": ["openai"]}'

# Multiple backends example:
mthds-agent init -g --config '{"backends": ["openai", "anthropic"], "primary_backend": "anthropic"}'

When pipelex_gateway is not among the backends, accept_gateway_terms is not needed. When 2+ backends are selected without pipelex_gateway, primary_backend is required.

4. Configure credentials

Guide the user to add their API keys to ~/.pipelex/.env:

• OpenAI: OPENAI_API_KEY=sk-...
• Anthropic: ANTHROPIC_API_KEY=sk-ant-...

If the user prefers an interactive setup, tell them to run pipelex init inference in their own terminal (not through Claude Code).

5. Verify

Run mthds-agent doctor to confirm keys are valid and configuration is healthy.

Step 3 — Success

Once the doctor reports healthy:

Your inference setup is complete! You can now run your methods with live AI inference.

Then re-run the method that originally triggered this setup (if known), or suggest /mthds-run.

Reference

• Error Handling — read when CLI returns an error to determine recovery
• MTHDS Agent Guide — read for CLI command syntax or output format details