Superconductor

https://super.engineering/docs
Admin
Superconductor is a native macOS workspace for agentic engineering. It organizes projects into...
Tokens:12,150
Snippets:226
Trust Score:4.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Setup Command Example

Source: https://super.engineering/docs/project-config-and-scripts

Configure setup commands to prepare a new worktree, such as installing dependencies. Project settings can disable auto-running setup, allowing manual triggering.

```json
{
  "setup": ["bun install --frozen-lockfile"]
}
```

--------------------------------

### Run Command Example

Source: https://super.engineering/docs/project-config-and-scripts

Define run commands to power the 'run' button, typically used for starting development or preview servers. If no run command is configured, a button to configure it will appear.

```json
{
  "run": ["bun run dev"]
}
```

--------------------------------

### Example Branch Names

Source: https://super.engineering/docs/workspaces-and-branches

Illustrative examples of naming conventions for feature, fix, and refactor branches.

```text
feat/docs-system
fix/api-download-redirect
refactor/sidebar-state
```

--------------------------------

### Example Prompt for Review Checklist

Source: https://super.engineering/docs/automation-recipes

An example of how to use the `sc worktree review-checklist --json` command in a prompt to inspect changed files and identify high-risk review items.

```bash
Run sc worktree review-checklist --json, inspect the changed files, and list the three highest-risk review items.
```

--------------------------------

### Check Provider CLI Installation

Source: https://super.engineering/docs/providers-and-models

Before configuring a provider in Superconductor, ensure the corresponding CLI command runs successfully in your local terminal. This verifies the provider is installed and authenticated correctly.

```bash
codex --help
claude --help
gemini --help
opencode --help
pi --help
```

--------------------------------

### Custom Branch Naming Rule Example

Source: https://super.engineering/docs/branches-and-targets

An example of a custom branch naming rule that includes a ticket prefix, formatted for agent prompts.

```text
{ticket}/{short-description}, kebab-case, e.g. ENG-1234/login-timeout
```

--------------------------------

### Default Project Configuration

Source: https://super.engineering/docs/project-config-and-scripts

Define default setup, run, and teardown commands for a project in the `.superconductor/config.json` file. Superconductor prioritizes the worktree's config file, falling back to the primary worktree if necessary.

```json
{
  "setup": ["bun install"],
  "run": ["bun run dev"],
  "teardown": ["rm -rf tmp/superconductor-preview"]
}
```

--------------------------------

### Example Branch Names

Source: https://super.engineering/docs/branches-and-targets

Common examples of branch names used for features, fixes, and chores.

```git
feat/api-docs
fix/login-timeout
chore/update-fixtures
```

--------------------------------

### Examples of Conventional Commits Branch Names

Source: https://super.engineering/docs/branches-and-targets

Illustrative examples of branch names following the Conventional Commits standard.

```git
feat/api-docs
fix/login-timeout
refactor/sidebar-state
docs/install-guide
chore/update-fixtures
```

--------------------------------

### Authenticate GitLab CLI

Source: https://super.engineering/docs/github-and-gitlab

Install and authenticate the GitLab CLI for GitLab workflows. This command verifies your authentication with GitLab.

```bash
glab auth status
```

--------------------------------

### Inspect Worktree Review Checklist

Source: https://super.engineering/docs/cli-local-api

Get the review checklist for the active worktree in JSON format.

```bash
sc worktree review-checklist --json
```

--------------------------------

### Authenticate GitHub CLI

Source: https://super.engineering/docs/github-and-gitlab

Install and authenticate the GitHub CLI for GitHub workflows. This command checks the current authentication status.

```bash
gh auth status
```

--------------------------------

### Inspect Worktree Status

Source: https://super.engineering/docs/cli-local-api

Get the status of the active worktree in JSON format.

```bash
sc worktree status --json
```

--------------------------------

### Rename Temporary Branch

Source: https://super.engineering/docs/branches-and-targets

Use this command to rename a worktree's temporary branch when starting from a Superconductor-launched terminal. Run this command from within the worktree's terminal.

```bash
sc worktree rename-branch feat/api-docs
```

--------------------------------

### Run Build Command

Source: https://super.engineering/docs/review-changes

Execute the build command for the current repository using Bun.

```shell
bun run build
```

--------------------------------

### Create and Activate Chat Session

Source: https://super.engineering/docs/cli-local-api

Initiate a new chat session with a specified provider and reasoning level, then activate it.

```bash
sc chat new --provider codex --reasoning medium --activate
```

--------------------------------

### Run Crate Test Command

Source: https://super.engineering/docs/review-changes

Execute the 'test-crate sc_git' command using Just.

```shell
just test-crate sc_git
```

--------------------------------

### Create and Activate Chat Session

Source: https://super.engineering/docs/automation-recipes

Create a new chat session with a specified provider and reasoning level, then activate it. The session ID is stored in a variable for subsequent commands.

```bash
SESSION_ID=$(sc chat new --provider codex --reasoning medium --activate)
```

--------------------------------

### Mention a File for Review

Source: https://super.engineering/docs/files-mentions-and-context

Use '@' followed by the file path to reference a specific file in chat sessions for analysis or explanation.

```markdown
Review @src/auth/session.ts and explain why the timeout test is flaky.
```

--------------------------------

### Mention a File for Updates

Source: https://super.engineering/docs/files-mentions-and-context

Use '@' followed by the file path to reference a specific file in chat sessions for making updates or adding information.

```markdown
Update @src/content/docs/docs/cli-local-api.md to include the new worktree commands.
```

--------------------------------

### Check App Connection

Source: https://super.engineering/docs/cli-local-api

Verify that the Superconductor app is running and accessible.

```bash
sc status
```

--------------------------------

### List Superconductor Chat Providers

Source: https://super.engineering/docs/troubleshooting

Command to list available chat providers. Use this to check provider status and enable or authenticate them as needed through Superconductor settings or their respective CLIs.

```bash
sc chat providers

```

--------------------------------

### List Chat Providers

Source: https://super.engineering/docs/cli-local-api

Display available chat providers that can be used with the Superconductor CLI.

```bash
sc chat providers
```

--------------------------------

### Superconductor Local Data Locations

Source: https://super.engineering/docs/settings-privacy-local-data

This table outlines the key directories and files used by Superconductor for storing global settings, local databases, runtime configurations, and CLI tools. Ensure the application is quit before modifying these files.

```text
~/.superconductor/settings.json| Global app and project settings.
```

```text
~/.superconductor/db/superconductor.db| Local knowledge database (file index, history).
```

```text
~/.superconductor/local-api.sock| Unix socket the `sc` CLI connects to.
```

```text
~/.superconductor/local-api.json| Discovery file pointing at the live socket and PID.
```

```text
~/.superconductor/hooks/| Wrapper scripts for shells and agent CLIs.
```

```text
~/.superconductor/bin/sc| The `sc` CLI binary on `PATH`.
```

```text
~/.superconductor/install_id| Random ID for anonymous telemetry. Removed when you opt out.
```

```text
~/.superconductor/session_state.json| Telemetry session state. Removed when you opt out.
```

```text
<project>/.superconductor/config.json| Repository-owned setup, run, and cleanup scripts.
```

--------------------------------

### Send Message and Watch Output

Source: https://super.engineering/docs/cli-local-api

Send a message to a chat session and monitor its output in real-time.

```bash
sc chat send "$SESSION_ID" "Summarize this repository." --watch
```

--------------------------------

### List Chat Sessions

Source: https://super.engineering/docs/cli-local-api

Retrieve a list of existing chat sessions managed by Superconductor.

```bash
sc chat list
```

--------------------------------

### Send Prompt from File to Chat Session

Source: https://super.engineering/docs/automation-recipes

Send the content of a file as a prompt to an active chat session. The `--stdin` flag reads from standard input, and `--watch` streams the output.

```bash
sc chat send "$SESSION_ID" --stdin --watch < prompt.txt
```

--------------------------------

### List Superconductor Chat Sessions

Source: https://super.engineering/docs/troubleshooting

Command to list available chat sessions. The `session_id` returned can be used for further actions. Note that closed tabs are removed from the live session hub.

```bash
sc chat list

```

--------------------------------

### Summarize Code Differences

Source: https://super.engineering/docs/automation-recipes

Request a machine-readable summary of code differences before an agent reviews its work. Use the `--json` flag for parsing. Can be used for the entire worktree or a specific file.

```bash
sc worktree diff-summary --json
```

```bash
sc worktree diff-summary --file src/content/docs/docs/cli-local-api.md --json
```

--------------------------------

### Inspect Worktree Diff Summary

Source: https://super.engineering/docs/cli-local-api

Retrieve a summary of the differences in the active worktree in JSON format.

```bash
sc worktree diff-summary --json
```

--------------------------------

### Verifying Recovered Git Worktree Checkout

Source: https://super.engineering/docs/troubleshooting

Commands to verify the status and log of a newly created Git worktree after recovery. Use `status --short --branch` for a concise status and `log -1 --oneline --decorate` for the latest commit.

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

```

--------------------------------

### Recovering a Deleted Git Worktree

Source: https://super.engineering/docs/troubleshooting

Use this prompt to ask an agent to recover an accidentally deleted Git worktree. It outlines the necessary information and precautions to take before running cleanup commands.

```markdown
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.

```

--------------------------------

### Send Prompt to Chat Session

Source: https://super.engineering/docs/automation-recipes

Send a text prompt to an active chat session and watch the response. The `--watch` flag streams the output.

```bash
sc chat send "$SESSION_ID" "Summarize the current diff." --watch
```

--------------------------------

### Set Tab Title

Source: https://super.engineering/docs/navigation-and-file-workflows

Set the title for the current tab within a Superconductor-launched session.

```shell
sc tab title "Fix Login Redirect"
```

--------------------------------

### Superconductor Settings File Location

Source: https://super.engineering/docs/settings-privacy-local-data

Application settings, including appearance and privacy configurations, are stored in this JSON file. It is recommended to quit Superconductor before directly editing this file.

```text
~/.superconductor/settings.json
```

--------------------------------

### Inspecting Git Worktree Metadata

Source: https://super.engineering/docs/troubleshooting

Commands to inspect Git worktree metadata, branches, and reflogs for recovery purposes. Run these from the main repository checkout.

```bash
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

```

--------------------------------

### Check Superconductor Status

Source: https://super.engineering/docs/troubleshooting

Run this command to check the status of the Superconductor local API. If it fails, ensure the Superconductor app is running and try launching the command from a Superconductor terminal.

```bash
sc status

```

--------------------------------

### Provide Feedback to Agent

Source: https://super.engineering/docs/review-changes

Send feedback to the agent regarding implementation changes, focusing on test coverage and API stability.

```text
The implementation changes the right file, but it does not cover the empty-state case. Add a focused test for that path and keep the public API unchanged.
```

--------------------------------

### Checking Git Reflogs, Stashes, and Unreachable Commits

Source: https://super.engineering/docs/troubleshooting

Commands to examine Git reflogs, stashes, and unreachable commits to find lost worktree data. Use the `--all` flag for reflogs to include all references.

```bash
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

```

--------------------------------

### Set Active Tab Title

Source: https://super.engineering/docs/cli-local-api

Update the title of the active tab within the Superconductor environment.

```bash
sc tab title "Review Auth Fix"
```

--------------------------------

### Remove Stale Superconductor Discovery Data

Source: https://super.engineering/docs/troubleshooting

If `sc status` fails due to a stale socket, remove the discovery file to reset the connection. Relaunch Superconductor after removing the file.

```bash
rm ~/.superconductor/local-api.json

```

--------------------------------

### Inspecting an Unreachable Git Commit

Source: https://super.engineering/docs/troubleshooting

Commands to inspect an unreachable Git commit's details and its containing branches before anchoring it. Use `show --stat` for a summary and `branch --all --contains` to find branches.

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

```

--------------------------------

### Branch Naming Convention Prefixes

Source: https://super.engineering/docs/branches-and-targets

A list of type prefixes used in Conventional Commits for naming branches, indicating the purpose of the branch.

```git
feat/        new feature
fix/         bug fix
refactor/    internal restructuring
docs/        documentation only
chore/       maintenance, dependencies, tooling
test/        tests only
ci/          CI configuration
perf/        performance
style/       formatting only
build/       build system or external deps
```

--------------------------------

### Stream Chat Session Events

Source: https://super.engineering/docs/automation-recipes

Stream events from a live chat session. This is useful for scripts that need to observe the session's activity, including messages, tool usage, and lifecycle events.

```bash
sc chat events "$SESSION_ID"
```

--------------------------------

### Adding a New Worktree from a Recovered Git Commit

Source: https://super.engineering/docs/troubleshooting

Command to create a new Git worktree from a recovered commit. It allows specifying a new branch name and the path for the recovered worktree.

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

```

--------------------------------

### Set Tab Title for Notifications

Source: https://super.engineering/docs/notifications-and-approvals

Use this command to set a tab title when opening a session from a notification, helping to identify the relevant context.

```shell
sc tab title "Review Auth Agent"
```

--------------------------------

### Set Target Branch

Source: https://super.engineering/docs/branches-and-targets

Command to explicitly set the target branch for a worktree. Use this when you intend to change the merge target.

```bash
sc worktree set-target-branch release/2026-05
```

--------------------------------

### Diffing Staged Changes in Stale Worktree Index

Source: https://super.engineering/docs/troubleshooting

Use this command to compare staged changes in a stale worktree's index against the worktree's last HEAD. Requires specifying the GIT_INDEX_FILE environment variable.

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

```

--------------------------------

### Set Tab Title

Source: https://super.engineering/docs/agent-orchestration

Dynamically set the title of the current terminal tab. This can be used by agents to provide better context or identify specific tasks.

```bash
sc tab title "Review API Docs"
```

--------------------------------

### Rename Worktree Branch

Source: https://super.engineering/docs/automation-recipes

Rename a worktree branch to a new name. This command is useful for managing feature branches.

```bash
sc worktree rename-branch feat/docs-review
```

--------------------------------

### Disable Telemetry in Superconductor

Source: https://super.engineering/docs/settings-privacy-local-data

To disable anonymous usage telemetry, navigate to the specified settings path within the application. This action stops further data transmission and removes local telemetry identifiers.

```text
Settings -> Privacy -> Share anonymous usage data
```
Tokens:
Raw