Troubleshooting

Start with the section that matches the symptom.

App will not launch

• Confirm your system runs macOS 14 or newer.
• Move the app to Applications and launch it from there.
• If macOS blocks the app, approve it through the macOS security prompt when you trust the build.
• Download a fresh build from the download route.

Repository does not open

• Open the repository root rather than a nested subdirectory.
• For a Git project, run git status in the folder from a normal terminal and resolve unreadable or corrupt Git metadata.
• For a plain folder, enable Non-Git projects under Settings → Experimental. System locations, the home folder, and unusually large folders may be blocked or require confirmation.
• If the folder is on another machine, create a remote SSH workspace instead of selecting a path that exists only on that host.

Agent command is missing

The app discovers local commands through your login shell. If an agent CLI is missing:

1. Open your normal terminal.
2. Run the agent command directly.
3. Install or authenticate the agent until it works there.
4. Confirm that the command is in the login-shell PATH, not only in an interactive shell customization.
5. Return to the app and start a new terminal or session.

Remote workspaces discover and run the provider on the remote host. Install and authenticate it there, then verify its non-interactive path as described in Remote workspaces.

Provider opens on the wrong surface

• Check Settings → Agents → Open new agent tabs in for the default Chat UI or Terminal surface.
• Confirm that the selected provider supports Chat UI. Providers without that adapter open in a terminal.
• Existing tabs keep their current surface. Open a new tab after changing the default.
• Check the active global, workspace, and project provider overrides if the selected model or profile differs from your expectation.

See Providers and models for the current support matrix.

Automatic worktree naming did not run

• Confirm Settings → Worktrees → Automatic worktree naming is enabled.
• Start the task with a meaningful prompt; setup or injected context alone does not supply a useful feature name.
• For remote workspaces, confirm that the managed sc CLI is installed and current.
• Rename manually from the worktree menu or with sc worktree rename-branch NEW_NAME when needed.

The sidebar label can differ from the branch name. sc worktree set-label changes only the label.

Diffs look wrong

• Confirm the worktree’s target branch is correct.
• Fetch the latest target branch when your local repository is stale.
• Check the worktree for unrelated changes.
• Review generated files and lockfiles separately.

Git button shows an unexpected action

The Git button is state-driven. Check these in order:

• Uncommitted or staged changes can make Commit, Commit & push, or Create PR/MR take priority.
• Local commits without an upstream require Push before forge-only actions become available.
• Conflicts, failed checks, merge blockers, requested changes, and unresolved review comments can replace the normal merge action.
• A wrong target branch changes comparison and PR/MR context.
• Missing or unauthenticated gh or glab can remove structured forge actions.

Open the button’s dropdown to inspect the available alternatives. See Git actions and pull requests for the complete state table and click routing.

Setup or run command is missing

• Confirm the command exists in .superconductor/config.json or the project’s app settings.
• Validate that run uses the current named-target format when several commands are defined.
• Check whether the project or workspace override replaces the global value.
• Run repository commands from the active task worktree, not automatically from the primary checkout.
• Read the visible setup or run output for the first failing command.

See Project config and scripts for schema, variables, precedence, and trust boundaries.

Deleted a worktree by mistake?

Stop cleanup first. Do not run git gc, git prune, git worktree prune, or other destructive cleanup until you know whether Git still has the work.

The fastest path is to hand the recovery work to an agent with this prompt:

Copy

I accidentally deleted a Git worktree. Please check whether it is recoverable.

Repo path: <absolute repo path>
What I remember: <branch name, feature name, file names, commit message words, or dates>
Desired recovery path: <absolute path for restored worktree>

Important:
- Do not run git gc, git prune, git worktree prune, or destructive cleanup.
- First inspect git worktree metadata, branches, reflogs, stashes, and unreachable commits.
- Check whether any stale worktree index preserves staged changes.
- If you find a matching commit, show me the evidence before creating anything.
- If I approve, create a new recovery branch and add a new worktree from the recovered commit.

To inspect it yourself, start from the main repository checkout, not the deleted worktree path:

Copy

git -C /path/to/repo rev-parse --show-toplevel
git -C /path/to/repo worktree list --porcelain
git -C /path/to/repo branch --all --verbose --no-abbrev

Look for the missing work in reflogs, stashes, stale worktree metadata, and unreachable commits:

Copy

git -C /path/to/repo reflog --all --date=iso
git -C /path/to/repo stash list
git -C /path/to/repo fsck --no-reflogs --unreachable --no-progress

If git worktree list --porcelain shows a stale worktree entry, its index may still preserve staged changes. Use the worktree metadata name under .git/worktrees/ and compare its index against the worktree’s last HEAD:

Copy

GIT_INDEX_FILE=/path/to/repo/.git/worktrees/<metadata-name>/index \
  git -C /path/to/repo diff --cached --stat <worktree-head>

When an unreachable commit looks right, inspect it before you anchor it:

Copy

git -C /path/to/repo show --stat <commit>
git -C /path/to/repo branch --all --contains <commit>

If no branch contains the commit, create a recovery branch and a new worktree from it:

Copy

git -C /path/to/repo worktree add \
  -b recovered/<topic> \
  /path/to/recovered-worktree \
  <commit>

Verify the recovered checkout before you resume work:

Copy

git -C /path/to/recovered-worktree status --short --branch
git -C /path/to/recovered-worktree log -1 --oneline --decorate

sc cannot reach the app

Run:

Copy

sc status

If the command fails to connect:

• Confirm the app is running.
• Launch the command from an app-launched terminal when possible.
• Confirm that sc help identifies the super.engineering CLI. Another executable named sc may be earlier in PATH.
• Restart the app, open a fresh in-app terminal, and retry sc status.
• For a remote workspace, run Test Connection and Install / Update CLI under Remote SSH.

Session not found

Run:

Copy

sc chat list

Use the returned session_id. Closed live tabs no longer appear in sc chat list; recoverable provider history remains available through the app’s History controls and sc history where supported.

Provider not responding

Run:

Copy

sc chat providers

Enable or authenticate the provider in app settings or in the provider’s CLI, depending on the provider.

If the provider works in a normal terminal but not the app, compare login-shell PATH, the selected provider profile, launch flags, permission mode, and the global/workspace/project override chain. For SSH, test from the remote host.

macOS notification does not appear

• Confirm the app’s delivery mode under Settings → Notifications is not Never.
• Check whether Only when unfocused is suppressing an alert while the app is active.
• Enable the app under macOS System Settings → Notifications.
• Check Focus and sound settings for the event type.

The in-app Queue and Timeline work independently of macOS delivery. See Notifications and approvals.

Browser preview does not load

• Confirm the URL or local development server works in another browser.
• Check that the named run target is still running and listening on the expected address.
• Use ⌘L to inspect or replace the current URL and ⌘R to reload.
• For a remote project, remember that the browser runs on your Mac; expose or forward a host-only development server before opening it.

The in-app browser uses macOS WebKit. Site behavior can differ from Chromium-based browsers. See Navigation and file workflows for browser tabs, previews, and annotations.

sc browser command fails

• feature_disabled: enable Settings → Experimental → Browser automation.
• browser_consent_pending: answer the Allow/Deny prompt in the app, then retry the command.
• browser_no_tab: no browser tab is open in that workspace. Run sc browser open <url>.
• browser_stale_ref: the page changed since the snapshot. Re-run sc browser snapshot and use the new ref.
• browser_dialog_open: a page dialog is blocking. Run sc browser dialog accept or sc browser dialog dismiss.

See Agent browser control for the full error table and the unsupported verbs.