Project config and scripts

Project scripts turn repository-specific setup and development commands into worktree-aware controls. Store shared commands in the repository or keep personal commands in app project settings.

Repository config

Create this file at the project root:

.superconductor/config.json

A basic configuration looks like this:

{
  "setup": ["bun install --frozen-lockfile"],
  "run": ["bun run dev"],
  "teardown": ["docker compose down"]
}

The app reads the current worktree’s config first. If it is absent, it reads the main checkout’s config. This lets a task test a script change from its own branch while older worktrees continue to use the main copy.

For each supported field, repository config overrides app project settings when the field is present. An omitted field falls back to the corresponding app setting.

Script phases

Phase	When it runs	Allowed owner
`setup`	While preparing a new worktree, automatically or on demand	Repository config or app project settings
`run`	When you start a named run target	Repository config or app project settings
`pre_cleanup`	Before deletion; a nonzero exit can stop cleanup	App project settings only
`teardown`	During worktree deletion	Repository config or app project settings
`post_cleanup`	After the worktree is removed	App project settings only

pre_cleanup and post_cleanup are intentionally user-owned because they run automatically around deletion. If those keys appear in repository config, the app does not use them as automatic cleanup hooks.

Setup

Commands in one phase run in order. For example:

{
  "setup": [
    "bun install --frozen-lockfile",
    "bun run generate"
  ]
}

Setup runs in the new worktree. If it modifies tracked files, those edits become part of the worktree diff.

App project settings add setup controls that do not belong in repository policy:

Run setup automatically or require a manual start.
Run in the foreground or background.
Initialize Git submodules.
Symlink the main checkout’s .env into the worktree.
Clear setup output automatically after completion.

Do not commit secrets to repository config. Use environment management appropriate to the project.

One run target

The legacy array form remains valid:

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

It creates one run target named Run. Multiple commands in the array execute sequentially as one target.

Multiple named run targets

Use object entries when a project has several services, watchers, or previews:

{
  "run": [
    {
      "name": "web",
      "commands": ["bun run dev"],
      "default": true
    },
    {
      "name": "worker",
      "commands": ["bun run worker:dev"]
    },
    {
      "name": "tests",
      "commands": ["bun run test:watch"]
    }
  ]
}

Each entry accepts:

name: the label shown in the run controls.
commands: one or more commands, joined in order with &&.
default: optional; marks the initial target.

Use distinct, descriptive names. The right panel exposes the configured targets, shows each process’s state and output, and can keep several named services available within the same worktree.

When no run target exists, the panel offers Configure run script, which opens project settings.

Press outside a browser tab to start the active run target, falling back to the configured default and then the first target. In a browser tab, the same shortcut reloads the page.

Script variables

Insert these environment variables from app project settings or type them into a command:

Variable	Value
`$SUPERCONDUCTOR_ROOT_PATH`	Absolute path to the main repository root
`$SUPERCONDUCTOR_WORKSPACE_NAME`	Current workspace name, which is the worktree directory name
`$SUPERCONDUCTOR_WORKSPACE_PATH`	Absolute path to the current worktree directory

Quote path variables in shell commands because repository and worktree paths may contain spaces:

ln -sf "$SUPERCONDUCTOR_ROOT_PATH/.env" "$SUPERCONDUCTOR_WORKSPACE_PATH/.env"

Teardown and cleanup

Use teardown for a repository-defined service stop or local runtime cleanup:

{
  "teardown": [
    "docker compose down",
    "rm -rf tmp/app-preview"
  ]
}

Use personal app settings for guards or machine-specific cleanup:

pre_cleanup can verify that important work was pushed or stop deletion by returning a nonzero exit.
post_cleanup can remove machine-local state after the worktree path is gone.

The app first stops run processes it owns, then follows the configured cleanup sequence. Read Worktree cleanup before adding destructive commands.

Config or app settings?

Use repository config when a command is safe, reviewable project policy that every contributor should share. Use app project settings when a command is personal, contains machine-specific paths, depends on secrets, or runs automatically as a cleanup guard.

After changing config, create or reopen a worktree and confirm the resolved targets before relying on them in cleanup or automation.