SwarmCraft
Set up and connectGuide

Docs

Use SwarmCraft Setup

Review this machine, apply only the approved foundation changes, connect GitHub, set commit identity, and enter the dedicated SwarmCraft VS Code profile.

Use SwarmCraft Setup

SwarmCraft Setup is the recommended way to prepare a supported macOS or Windows machine. It detects first, explains every proposed change, and preserves working tools and settings.

Check whether your Setup version lists Node.js and npm and SwarmCraft CLI among its required tools. If it does not, complete the manual CLI setup checks before starting Operate, preparing a Discovery Package, or using one-shot delivery.

Before you start

  • Download the signed installer for macOS or Windows 11 from SwarmCraft Setup.
  • Close work you cannot afford to interrupt before approving an action that requires elevation or restart.
  • Keep access to the GitHub account you want to connect.

When your installer offers the CLI dependency actions, review the user installation under .swarmcraft/tools. Setup preserves compatible existing tools and installs missing dependencies without administrator access or permanent PATH changes. Install Node.js/npm first, then the CLI. An existing managed installation stays with its current distributor; follow the manual checklist if your organisation controls updates.

Restart required means an installed tool is not visible in the current environment. Confirm the approved PATH, fully quit and reopen Setup and VS Code, then run detection again. A failed or cancelled installation cannot complete readiness.

Review this machine

Open Setup and let its read-only inspection finish. Required tools are Visual Studio Code, Git, GitHub CLI, Node.js/npm, the SwarmCraft CLI, the dedicated SwarmCraft VS Code profile, and the SwarmCraft extension. Docker Desktop remains optional until a project requires containers. Setup does not reinstall, downgrade, or adopt an already-ready tool.

Setup read-only machine review showing required tools ready and Docker as optional

Review and apply changes

Select Review and apply only after checking the action scope, third-party terms, elevation requirement, and restart implications. Setup applies one approved action at a time and inspects the machine again afterward.

Setup review-and-apply state showing install scope, third-party terms, elevation, and the approved action

An operating-system or vendor prompt may remain open while an action runs. Do not start the action again; finish or cancel that prompt, then let Setup re-detect the machine.

Connect GitHub

Continue to the GitHub connection step. Setup starts GitHub CLI's browser authentication and verifies the resulting keyring-backed connection without displaying or storing the credential.

Setup GitHub connection step before browser authentication, with no code or credential shown

Paste the one-time code only into the GitHub page opened by GitHub CLI. This repository grant is separate from signing in to your SwarmCraft account later in VS Code.

Set your Git identity

Enter the name and email that should be recorded on commits. This identity is separate from GitHub sign-in and does not replace another profile's Git configuration.

Setup Git commit identity step with empty name and email fields

Enter SwarmCraft

Review the final connection summary, then select Open SwarmCraft in VS Code. Setup opens the dedicated profile at the extension welcome screen with no token, account data, or repository path in the handoff URI.

Setup final readiness summary with GitHub and Git identity configured and the VS Code handoff enabled

In VS Code, confirm the SwarmCraft view opens, then sign in to your SwarmCraft account through the browser. Then complete your chosen AI provider’s setup, including its standalone CLI for one-shot. A repository or project is not connected yet.

Run Setup again safely

You can run Setup again after an update, cancellation, restart, or repair. It re-detects live state and proposes only outstanding work. A ready second run is a no-op.

If Setup reports a partial result, cancellation, insecure credential storage, offline state, unsupported environment, or required restart, use Setup and connection recovery. Use the Manual setup checklist when your organisation owns software distribution or you deliberately want to manage each vendor installation.

Continue with everyday work

If you chose Operate, after your machine and chosen AI provider are ready and signed in, Use Operate to capture your work. That walkthrough starts from a local operation folder; you do not need to connect an application project.