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

• Confirm the folder is a git repository.
• Run git status in the folder from a normal terminal.
• Confirm the repository has no unresolved git operation in progress.
• Open the repository root rather than a nested subdirectory.

Agent command is missing

Superconductor runs local commands. 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. Return to Superconductor and start a new terminal or session.

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.

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:

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:

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:

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:

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:

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:

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

Verify the recovered checkout before you resume work:

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

Local API cannot connect

Run:

sc status

If the command fails to connect:

• Confirm the Superconductor app is running.
• Launch the command from a Superconductor terminal when possible.
• When the discovery file points at a stale socket, quit Superconductor, remove the stale discovery data, relaunch the app, and retry sc status:

rm ~/.superconductor/local-api.json

Session not found

Run:

sc chat list

Use the returned session_id. The live session hub drops closed tabs.

Provider not responding

Run:

sc chat providers

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