Skip to main content
When something seems off, start here:
doctor checks your binary, PATH, session, your AI tool’s hooks, proxy config (in managed mode), and connectivity, and prints a suggested fix for anything that fails. It only checks the tool(s) your session actually uses. Most issues below are things doctor will point you straight at.

​
My events aren’t being captured

This is almost always because your editor isn’t running inside the captured workspace. Capture is scoped to the workspace folder by design.
1

Confirm the event count is actually zero

The event count should climb as you send prompts and edit files. If it’s moving, capture is working.
2

Open your tool from the workspace, in a new window

Capture is tied to the workspace folder. Claude Code hooks live in <workspace>/.claude/settings.local.json and Cursor’s in <workspace>/.cursor/hooks.json; Codex is captured by watching its transcript for work done in the workspace. A window opened before promptster start, or started from a different directory, isn’t captured.
Fully quit and reopen your tool if it was already running — or re-run promptster start --restart, which offers to restart it for you.
3

Re-run doctor

Check that the rows for your tool’s hooks (or transcript capture) pass. If they don’t, re-run promptster start from inside the workspace.
Terminal commands are only captured when run inside the workspace directory. Commands you run elsewhere are intentionally ignored.

​
Signing in to the AI

Assessments run in one of two modes, and start sets up the right one for you. Managed proxy (default). Your AI tool is routed through the Promptster proxy, so you don’t sign in to the model yourself and you don’t need a paid plan of your own.
  • With Claude Code you do not need to /logout of a personal Max/Pro subscription — the proxy is wired through Claude Code’s apiKeyHelper, which out-ranks a logged-in subscription automatically.
  • The one thing that breaks the proxy is an Anthropic key exported in your shell — it out-ranks the helper:
    If either is set (often left over from your own projects or an older Promptster session), clear it for the session, then reopen your tool:
    After setup, promptster start runs a tiny proxy smoke test — if that succeeded, your auth is good.
Your own subscription. Some assessments have you use your own Claude Code, Codex, or Cursor sign-in instead of the proxy. doctor tells you which mode you’re in. In this mode:
  • Sign in to your tool exactly as you normally would — there’s no proxy to smoke-test.
  • Promptster captures through your tool’s transcript, so an exported ANTHROPIC_* key won’t break capture. Everything else — hooks, explain, done — works the same.

​
I got a 401 / “authentication” error on my first prompt

Two likely causes, in order:
  1. A shell-exported ANTHROPIC_* key is overriding the proxy. Run eval "$(promptster env --clear)", then reopen your editor. (See above.)
  2. Your session has expired. If your key’s time window has passed, the proxy stops accepting it and the helper emits no token. Run promptster doctor — it explicitly checks for an expired session. If expired, you’ll need a fresh key from the hiring team.
Run promptster doctor first; it distinguishes these for you.

​
My internet dropped

Keep working — the CLI records each event to a local buffer as it happens, so a brief disconnection won’t interrupt your editor. Once you’re back online, check that the server is receiving events:
The event count reflects what the server has actually received. If you were offline during promptster done, the upload step will have failed loudly (it won’t falsely report success) — just re-run promptster done once you’re reconnected.

​
Can I pause and come back later?

Yes. Your session stays open until you run promptster done or the time limit runs out. You can close and reopen your editor, restart your machine, and pick up where you left off — just remember to reopen the editor from the workspace directory so hooks reload. To resume, cd into your workspace and check where things stand:

​
What happens when the time limit runs out?

If your assessment has a time limit, it’s enforced server-side: when the window closes, your session is auto-submitted with whatever you’ve done so far. You won’t lose work that was already captured. Run promptster brief to see your remaining time, and submit with promptster done before the buzzer if you can — a deliberate submission is cleaner than an automatic one.

​
I switched computers mid-assessment

Promptster records a lightweight device fingerprint at consent, start, and submission to help reviewers confirm continuity (see Privacy & Data). Working across machines isn’t forbidden, but it’s visible — if you must switch, it’s worth a quick /explain note saying why. Your session and hooks live on a specific machine in a specific workspace, so you’d need to set the workspace up again on the new machine; reach out to the hiring team if you’re unsure.

​
Recovering from a broken setup

If hooks, the proxy, or the session file get into a confused state, reset and start clean:
This tears down the session, hooks, shell hook, RC source lines, and proxy config, and sweeps leftover ~/.promptster state — while keeping the installed binary, so you don’t have to reinstall. It works even when the session file is corrupt. Then:
For a full uninstall (binary included), use promptster reset --purge.
reset and abort do not submit your work or complete the assessment. If you meant to submit, use promptster done. If you’ve already done meaningful work and a reset would lose it, contact the hiring team before wiping anything.

​
The promptster command isn’t found

The binary installs to ~/.promptster/bin. Make sure it’s on your PATH:
Add that to your ~/.zshrc or ~/.bashrc to make it stick, then restart your shell. See Install.

​
promptster start says my CLI is too old

The CLI checks for a minimum supported version on start. Update it and try again:

​
Still stuck?

Run promptster doctor and copy its full output, then contact the hiring team or email [email protected]. The doctor output tells us exactly what’s misconfigured.