Troubleshooting

Not covered here? In the app, choose Help, then Request Support. It opens the form in Settings, General, and attaches your StateSync version and system. Or write to support@statesync.net.

An agent is not found, or will not launch

Installed through a version manager

A desktop app does not inherit your shell's setup, so an agent installed under nvm, asdf, pyenv or similar can be invisible to StateSync even though the agent runs fine in a terminal. Installing the agent globally usually fixes this. If not, send support the path your terminal prints for which <agent> on macOS and Linux, or where <agent> on Windows.

Installed but signed out

The agent's row in Settings, under Providers & agents, says Needs signing in. Press Sign in, finish the agent's own login, and the row moves to Ready to use. Signed in outside StateSync? Press Re-check.

Sign-in or update will not work from StateSync

Depending on how an agent was installed, StateSync sometimes cannot sign it in or update it through the normal buttons. Sign in or update from a terminal instead: open the terminal in StateSync, then run the agent's own login command from the table below. When it finishes, press Re-check on the agent's row in Settings. An agent can be updated the same way, using the update steps on its help page.

For Claude Code, Pi, Droid and Grok, running the command opens the sign-in in your browser the first time.

Sign-in will not complete

• A sign-in code is valid for 10 minutes. If the code has expired, ask for a new one.
• Device approval happens in your browser. Make sure the browser it opens is signed in to the same account.
• A work email filter sometimes holds the code. Check quarantine before assuming it was not sent.

An update will not install

StateSync will not restart to update while an agent is running, or while a task that just finished is still being saved, because restarting would stop that work. Let the agents finish, then press Restart StateSync to update again.

Dictation does not start

• Check StateVoice is switched on in Settings, under StateVoice, and a speech model is downloaded.
• Another app may already use the same shortcut. Set a different one.
• Press Test beside the microphone. No level means StateVoice is not hearing that microphone: pick another.
• On an older NVIDIA graphics card, or one without CUDA support, the CUDA runtime will not work. Install the Vulkan runtime instead, under Advanced voice settings.

VS Code opens a plain terminal

The StateSync app has to be running and signed in on the same computer. Start it, then open a new terminal. Remote windows, over SSH, WSL or a Dev Container, are not supported.

The saving looks wrong

The saving is measured per task, and one task is not a benchmark. Short tasks save least, and a very small task may save nothing at all. The published figures describe work of a realistic length, and every task in that run is on the evidence page, wins and losses.

If the usage on your account page looks wrong, write to support rather than guessing. We would rather look at the records with you than speculate.

StateSync stopped saving

Your weekly allowance has run out, and the app says so. Your agents keep working as normal. The saving comes back when the next week starts, or straight away if you move up a plan. Plans and usage has the detail.

Known issues

Problems we already know about, with a way round where there is one, are on the known issues page.