Troubleshooting

All My Workspaces or Projects Disappeared

Almost always a context mix-up, not data loss. Check, in order:

Organization: updates can switch your active org. Check the org switcher.
Sign-in provider: GitHub and Google logins are separate accounts even with the same email. Sign out and back in with your original provider.
v1 fallback: if the app reverted to the legacy interface, re-enable v2 under Settings → Experimental.

Your worktrees are still on disk at ~/.superset/worktrees/ either way; Superset only deletes them when you delete a workspace.

If you created your account after using v1, update Superset and relaunch it. Current versions import pre-account workspaces that older v2 releases could miss.

Update Button Does Nothing

If the app quits and reopens on the same version, the updater hit a known race (fixed in recent releases). Download a fresh copy from superset.sh/download once; updates work normally after that.

gh, git, or an Agent Works in My Normal Terminal but Not in Superset

Superset terminals differ from Terminal.app in a few specific ways:

PATH shims: Superset puts wrappers in ~/.superset/bin (for status and notifications). If an agent misbehaves, run which -a codex (or claude) to spot duplicate installs on your PATH.
Copied settings: new worktrees copy files like .claude/settings.local.json from your root checkout. If you rotated an API key, old worktrees may still carry the stale one.
Shell: launch commands assume a POSIX shell. fish or nushell as your login shell breaks agent launches.
After an update: terminal sessions are held by a background daemon that outlives the app. If terminals stay broken after an update, quit Superset fully and relaunch; if that doesn't clear it, reboot.

New Workspace Is Missing Dependencies or .env

Workspaces only copy git-tracked files, so node_modules, .env, and build artifacts don't come along.

Fix: add project lifecycle setup commands to .superset/config.json:

{
	"setup": ["bun install", "cp \"$SUPERSET_ROOT_PATH/.env\" .env"]
}

Or ask an agent to do it: the "Set up this project for Superset" sample prompt authors the config for you.

Can't Add a Private Repository

Repo access goes through the GitHub CLI.

Fix: run gh auth status in a terminal. If it fails, gh auth login (you can run it inside Superset), then retry.

Can't Create a Workspace on a Branch

One branch = one workspace. If the branch is already checked out in another workspace (or your root checkout), git won't allow a second worktree on it.

Fix: open the existing workspace, or create a new branch.

Agent Isn't Showing Up in the Launcher

Superset detects installed agents automatically, but each agent can be enabled or disabled.

Fix: check Settings → Agents: confirm the agent is Enabled and its command is correct. Reset to Defaults restores the shipped configuration.

The host machine must be awake, online, and connected to the relay. On the host, enable Settings → Remote Access → Allow remote access to this device via relay (desktop), or run superset start --daemon (CLI).

On iPhone:

One step left means the computer has never connected. Follow the Remote Access setup steps on that computer.
Offline with a last-seen time means it connected before. Check that it is awake, online, and running Superset, then retry.
Can’t check means Superset could not load connection status. Use Try again; this message does not establish that the computer is offline.

See Remote Access for setup.

Automation Run Failed While the Device Was Offline

A run whose target device isn't relay-connected at fire time records as failed, with the offline error shown inline under the run; the schedule advances normally.

Fix: none needed for a one-off. Use Retry all in the Automations list once the device is back online, or retarget the automation to a device that stays online. See Automations.

Still Stuck?

Check the FAQ
Open an issue with steps to reproduce