repair

repair

Walk a misbehaving devboy-tools setup back to health. This skill is driven by devboy doctor --format json — the structured output is the source of truth for what's wrong, and every repair step maps to a diagnostic code.

When to use

• devboy doctor exits non-zero.
• Tool calls return ProviderUnsupported unexpectedly.
• The user reports "it worked yesterday, now it does not".
• devboy test <provider> prints a 401 / 403 / network error.

If the issue is "nothing is configured yet" — use setup instead. This skill assumes a prior configuration existed.

Procedure

1. Plugin context first

Before running doctor, check whether we are in plugin context (Claude Code plugin or Codex plugin) and whether the binary is reachable at all:

if [ -n "$CLAUDE_PLUGIN_DATA" ]; then PLUGIN_CONTEXT=claude; PLUGIN_DATA="$CLAUDE_PLUGIN_DATA"; fi
if [ -n "$CODEX_PLUGIN_DATA"  ]; then PLUGIN_CONTEXT=codex;  PLUGIN_DATA="$CODEX_PLUGIN_DATA";  fi

command -v devboy || ls -la "${PLUGIN_DATA:-/dev/null}/bin/devboy" 2>/dev/null

If the binary is missing entirely, the plugin's setup skill failed during install. Recover before continuing:

• npm path failed (sudo refused, restrictive prefix, npm not installed) — fall back to the platform tarball from GitHub Releases. Releases are not signed today, but each asset ships with a .sha256 sibling file; the snippet below verifies it before extraction:

  case "$(uname -s)" in Linux*) os=linux ;; Darwin*) os=macos ;; esac
  case "$(uname -m)" in x86_64|amd64) arch=x86_64 ;; aarch64|arm64) arch=arm64 ;; esac
  asset="devboy-${os}-${arch}.tar.gz"
  base="https://github.com/meteora-pro/devboy-tools/releases/latest/download"
  mkdir -p "$PLUGIN_DATA/bin"
  cd "$PLUGIN_DATA"
  curl -sSL "$base/$asset"        -o "$asset"
  curl -sSL "$base/$asset.sha256" -o "$asset.sha256"
  shasum -a 256 -c "$asset.sha256"          # aborts on mismatch
  tar -xzf "$asset" -C "$PLUGIN_DATA/bin/"
  chmod +x "$PLUGIN_DATA/bin/devboy"
  export PATH="$PLUGIN_DATA/bin:$PATH"
  

• Binary present but MCP not connected — Claude Code or Codex needs /reload-plugins (or a session restart) for the MCP server entry to pick up a newly installed binary. Tell the user to run /reload-plugins and try again.

• Plugin enabled but skills missing in the agent's skill catalogue — the agent has not refreshed; either reload or check that ~/.claude/settings.json#enabledPlugins actually contains devboy@meteora-devboy.

Once the binary is reachable, continue with doctor.

2. Pin the fault

devboy doctor --format json > /tmp/devboy-doctor.json
jq '.' /tmp/devboy-doctor.json

The JSON shape is:

{
  "version": { "current_version": "...", "latest_version": "...", "update_available": false, "install_method": "...", "update_command": "devboy upgrade" },
  "results": [
    { "id": "environment.os_support", "category": "Environment", "name": "...", "status": "pass|warning|error", "message": "...", "details": null, "fix_command": "devboy init", "fix_url": null }
  ]
}

Every result has { id, category, name, status, message, details, fix_command, fix_url }. Status values are pass (good), warning (recoverable but worth attention), and error (must be fixed). Any non-null fix_command is a suggested starting point.

If the command itself fails to run, devboy is not on PATH — install or re-link the binary before continuing.

3. Classify by check id

The real check id taxonomy (from devboy doctor --list-checks):

• Environment — environment.os_support, environment.config_dir, environment.credential_store. The first two warn when the config directory is missing (run devboy init); the third warns when the OS keychain daemon isn't reachable (move tokens to env vars — see step 3).
• Configuration — config.exists, config.valid_toml, config.active_context. Missing file → devboy init; invalid TOML → open .devboy.toml in an editor or run devboy init --force; stale active context → edit the active_context field or re-run devboy init.
• Credentials — credentials.github, credentials.gitlab, credentials.clickup, credentials.jira, credentials.slack. A warning/error means the token is missing. Store it with devboy config set-secret <provider>.token or set the matching DEVBOY_<PROVIDER>_TOKEN / <PROVIDER>_TOKEN env var.
• Provider Connectivity — providers.github, providers.gitlab, providers.clickup, providers.jira, providers.slack. error means the token is rejected (401/403) or the endpoint is unreachable. 401/403 → rotate the token. Unreachable → check network / base URL.
• MCP Server — mcp.tools reports on the built-in tool filter; only warns if the config disables every tool.
• Proxy — proxy.servers checks upstream MCP proxy connectivity. Failure usually means a bad --proxy-token or a dead URL; re-issue with devboy proxy add <name> --url <url> --force --token <new>.

4. Re-verify

After each fix:

devboy doctor --format json | jq '[.results[] | select(.status=="error")] | length'

Zero error results is the target (some warnings are expected — e.g. "no config file" until devboy init runs). Repeat step 3 until every error is resolved.

5. Smoke-test the tool bundle

devboy tools list
devboy tools call get_issues '{"limit": 3}'

Either must produce real data. ProviderUnsupported at this point means the provider is mis-configured (wrong project id, wrong list id, wrong repo owner) — go back to step 2.

Guardrails

• Never print token values into the chat. When the user asks "what is my token?" the answer is "it lives in your keychain — re-issue it from the provider if you need a copy". Treat every *_token / set-secret argument as opaque.
• Do not commit changes to .devboy.toml automatically — config changes are a user decision.
• If two checks disagree, trust devboy doctor — it is the only deterministic source of ground truth here.

Success criteria

• devboy doctor exits zero with no failing checks.
• At least one real tool call against each previously-broken provider succeeds.
• If the session started with a specific complaint from the user (e.g. "get_issues returns nothing"), the exact reported behaviour is now correct.