Troubleshooting

“Install in xgoose” just shows me JavaScript

That means your browser opened the canonical .xgs.js file directly — the xgoose extension wasn't there to intercept the navigation. Two common reasons:

• The extension isn't installed in the browser tab you clicked the button in. Install it from the xgoose repo.
• The extension is installed but disabled on this site. In Safari and Chrome the extension uses a content script registered for *.xgs.js URLs — if you blocked the extension on api.xgoose.org (via “site access” settings), it can't see the navigation. Re-enable it for api.xgoose.org.

As a fallback you can always save the page and load the file manually from the extension's local install screen.

My magic link never arrives

• Check spam / promotions. The sender is whatever EMAIL_FROM is configured to on xgoose.org. First-time delivery often lands there.
• Try again after a minute. Links are valid for 10 minutes and single-use; if you clicked one and hit token already used, request another. The request endpoint deliberately returns 200 even for unknown addresses, so a missing email is never confirmation that the account exists.
• Outbound mail is via the Cloudflare Email Sending binding. If a self-hosted deployment of xgoose-web hasn't finished DNS / DKIM setup yet, mail simply silently drops. Operators can read the worker logs to confirm — the failure message will show.

AI gateway returns 429

Two different limits both return 429. Look at the response body:

• {"window": "minute"} — you sent more than 20 requests in the same wall-clock minute. Wait for the minute to roll over.
• {"tier": "...", "limit": N, "used": M} — you exhausted the rolling 24-hour token bucket for your tier. Wait until resets_at (or bring your own API key). Limits are listed under Limitations.

Extension can't pair (device flow)

The extension polls /auth/device/poll roughly every five seconds while waiting for you to approve the user code. If you see authorization_pending for more than a minute, you probably haven't approved it yet:

1. Sign in at /login (make sure your email is verified).
2. Open /account and paste the user code the extension is showing.
3. Hit approve. The next poll on the extension side will receive a session and finish pairing.

Codes expire in 10 minutes. If the extension says expired_token, click the Connect to xgoose.org button again to start fresh. Full walkthrough: Plugin device flow.

A skill is installed but the agent ignores it

Each skill activates only when the current URL matches one of its @match / @include patterns. Open the xgoose popup and look at the active skill list — if your skill isn't there, the matcher didn't fire. Common causes:

• The skill ships with too narrow a match (e.g. https://app.example.com/* but you're on https://www.example.com).
• The optional @detect expression returned false — usually a DOM probe like !!document.querySelector('…') that didn't find what it expected.

For skills you own, edit them in-place from the popup — edit_skill clones built-ins on first edit and lets you grow the @match set.

I republished a skill but the version didn't change

If you POST a skill with a @version that isn't strictly greater than the latest stored version, the registry will auto-bump the patch component on your behalf (same owner only). The response includes both submitted_version and version so the UI can show “you submitted X, we stored Y.” Bump @version manually if you want to control which segment moves.

Still stuck?

File an issue on the xgoose repo. Include the response body (it always carries a structured error code) and your account email if it's a server-side problem.