Guides

Practical guides

Test with the public sandbox first

The Shimpilot sandbox repository is an inspectable public test surface with provider migration fixtures. Read the scenario matrix first so you know which calls should be classified and which safe controls should remain untouched.

Anthropic scans inspect Node.js and Python calls whose model is a literal or locally resolvable constant. Retired Claude model IDs become findings. In Manual mode Shimpilot can propose the reviewed replacement and open a validated Draft PR; your team reviews model behavior and merges it.

For Supabase v1→v2, inspect the separate disposable provider fixture and run its public scan. It includes reviewed auth, client options, mutation response, and Realtime examples. Automatic mode may draft simple literal createClient option moves for human merge. Select Manual for auth, RLS-sensitive writes, and Realtime. Supabase never auto-merges.

For AWS, scan a disposable JavaScript/TypeScript repository with recognized SDK v2 clients and a committed supported lockfile or exact dependency version. Eligible ES-module/.promise() calls can produce a focused Draft PR using modular v3 service packages in either mode. Callback, streaming, DocumentClient marshalling, Lambda contracts, and complex configuration require review. No AWS credentials are needed for static scanning; Shimpilot does not execute cloud API calls. Your team must validate cloud behavior and merge the PR.

1. 1. Inspect: review the fixtures, expected scenarios, and CI workflow on GitHub.
2. 2. Scan: run the public sandbox scan without signing in.
3. 3. Isolate: use GitHub's template action to create your own disposable copy.
4. 4. Connect narrowly: install the GitHub App for that repository only.
5. 5. Verify: inspect the findings, queue a migration, and review the Draft PR and validation evidence in GitHub.

Monitoring an API provider

Provider monitoring is enabled per provider, not per repository — connecting a repository automatically includes it in monitoring for every provider it depends on. Each provider's monitoring health (Healthy, Degraded, Failing, or Disabled) is visible from your dashboard's Providers page, derived from real check timestamps rather than estimated.

Understanding an affected call site

Each affected call site on a change's detail page shows the file, line, and enclosing function, plus an explanation of exactly why it was classified the way it was — a directly matched operation, a possible match with lower confidence, or a call site sharing a function with a confirmed match. Evidence is always traceable back to a real dependency record, never asserted without it.

Reviewing a migration

Every migration's detail page shows the originating API change, the affected code, a summary of what the patch does, the files changed, and the validation results — AST, typecheck, tests, and rescan — each marked passed only if it actually passed. Use the linked Draft PR to review the diff itself before merging.

Choosing a migration mode

Each monitored repository uses one of two clear workflows:

• Manual — Shimpilot detects the change, generates a migration proposal, validates required gates, and opens a Draft PR. Your team reviews and merges that PR in GitHub; Shimpilot then verifies the merged default branch.
• Automatic — Shimpilot performs the same generation and validation flow, observes GitHub CI, and may continue through repair and merge when every plan, rule, and safety gate allows it.

Handling validation failures

If a generated patch fails typecheck, tests, or the post-patch rescan, Shimpilot blocks the pull request and records the exact reason rather than opening a pull request anyway. Blocked migrations remain visible with next steps. Before a PR exists, choose Repair & retry migration to prepare a fresh Manual Draft PR against the current branch. The worker attempts bounded compiler repairs, then reruns required validation and the source rescan. This does not change your organization's selected mode or bypass a blocker. If an attempt already has a PR, review that PR's checks instead. A repository is only verified fixed after merge and post-merge validation.

Set up Ask Shimpilot

Chat runs in the Next.js web deployment. Provider keys configured only on Render workers do not enable chat on Vercel. Saved conversations can still be read when no provider is configured; new questions and retries remain paused.

1. Open your Vercel project's Settings → Environment Variables and select the environment you are deploying, usually Production.
2. Copy one existing server-side provider configuration from Render: GROQ_API_KEY and your GROQ_MODEL override if used, or ANTHROPIC_API_KEY plus any ANTHROPIC_BASE_URL andANTHROPIC_MODEL overrides. An Anthropic-compatible proxy must use its matching endpoint, credentials, and model. One provider is enough.
3. Redeploy the web app so the new environment variables take effect. Keep Render's existing worker configuration.
4. Return to Ask Shimpilot and choose Check setup, then send a question. The setup check detects configuration presence without calling a paid model; the question checks authentication and model availability.