SwarmCraft
Set up and connectGuide

Docs

Manual setup checklist

Use the experienced or managed-environment path when SwarmCraft Setup cannot own software installation on this machine.

Manual setup checklist

SwarmCraft Setup is the supported default for macOS and Windows. This checklist prepares the tools needed by the extension, including the SwarmCraft CLI and its Node.js runtime.

Use this manual path when your organisation manages software distribution, Setup is unavailable for the machine, or you deliberately want to own each vendor installation.

You own vendor selection, signatures, checksums, elevation, updates, system changes, and repair on this path.

Confirm the platform

Use a supported macOS release on Apple silicon or Intel, or x86-64 Windows 11 23H2 or later. If your organisation manages the machine, follow its approved software catalogue and verification policy.

Install the foundation

Install and verify these vendor-owned tools:

  1. Visual Studio Code
  2. Git
  3. GitHub CLI
  4. Docker Desktop, only when the project requires containers

Keep vendor update mechanisms enabled. SwarmCraft does not replace VS Code, GitHub CLI, Git, Docker, or Marketplace update ownership.

Verify each required command before continuing:

code --version
git --version
gh --version

Install Node.js and the SwarmCraft CLI

In your terminal:

  1. Install a supported Node.js LTS release with npm from Node.js, or use your organisation's approved distribution. The CLI requires Node.js 20.19 or newer; preserve a compatible managed installation.
  2. Check the runtime and install the CLI using the commands for your platform below.
  3. Fully quit VS Code and reopen it after installation or PATH changes. Reloading a window may retain the old environment.

On macOS:

node --version
npm --version
npm install -g @swarmcraftai/cli
swarmcraft --version
swarmcraft operate init --help

On Windows, use native PowerShell; WSL is not required for the SwarmCraft CLI:

node --version
npm.cmd --version
npm.cmd install -g @swarmcraftai/cli
swarmcraft.cmd --version
swarmcraft.cmd operate init --help
Get-Command node, npm.cmd, swarmcraft.cmd
npm.cmd prefix -g

The help must list --session-stdin and --client-surface. On Windows, confirm the approved npm global prefix is on your user PATH and visible to VS Code. The .cmd commands avoid PowerShell script-policy errors without changing execution policy. Your selected AI provider has its own installation and platform requirements.

If installation is restricted or the global prefix is not writable, ask your administrator for an approved Node.js and CLI installation or a user-writable npm prefix. Do not bypass organisational restrictions or replace a managed runtime. Preserve npm registry and authentication settings. A one-off npx invocation does not install the CLI for VS Code.

Create the dedicated profile and install the extension

Create a VS Code profile named SwarmCraft. Install only the exact extension ID SwarmCraft.swarmcraft-vscode-extension into that profile.

Open the Extensions view in VS Code, search for the exact ID SwarmCraft.swarmcraft-vscode-extension, confirm the publisher is SwarmCraft, and select Install.

You can also use the SwarmCraft Marketplace listing or this command:

code --profile SwarmCraft --install-extension SwarmCraft.swarmcraft-vscode-extension

For managed offline installation, use only the VSIX and checksum supplied through your organisation's approved release process.

Connect GitHub CLI

Start GitHub CLI browser authentication:

gh auth login --hostname github.com --git-protocol https --web
gh auth setup-git --hostname github.com
gh auth status --hostname github.com

Use the browser opened by GitHub CLI. Do not put a token in the command or share the one-time browser code. Confirm gh auth status reports the intended active account and secure credential storage.

Set commit identity separately

GitHub authentication does not set the author recorded on commits. Review the current values, then set only what you intend to use:

git config --global user.name
git config --global user.email
git config --global user.name "Your commit name"
git config --global user.email "your-commit-email@example.com"

Open the token-free handoff

Open the dedicated profile and the extension welcome route:

code --profile SwarmCraft "vscode://SwarmCraft.swarmcraft-vscode-extension/setup/welcome"

The URI contains no token, browser code, account data, or repository path.

Install your chosen AI provider

Complete the section for the provider you intend to use. You do not need all three. Each section covers the editor extension and the standalone provider CLI used by one-shot. The provider CLI is separate from both the SwarmCraft CLI and the VS Code extension.

Install the provider CLI in the environment where SwarmCraft runs. Follow the vendor's current macOS or Windows requirements, then fully quit and reopen VS Code after installation or PATH changes.

Connect Codex when you choose it

In VS Code and your terminal:

  1. Install the official Codex extension in your SwarmCraft profile and choose Sign in with ChatGPT with an account that has Codex access.
  2. For one-shot, also install the standalone Codex CLI using the vendor's instructions for your platform. Confirm codex --version succeeds in your terminal.
  3. Run codex login, complete browser sign-in, then run codex login status to confirm the active authentication method. Use ChatGPT sign-in for your plan's included usage; API-key usage is billed separately. See Codex authentication.
  4. Run SwarmCraft: Choose AI Provider and choose Codex. Start or reconcile the relevant SwarmCraft workflow in your trusted repository to generate its skills.
  5. Before one-shot, check swarmcraft one-shot --help lists codex under --agent-provider. Upgrade the SwarmCraft CLI if it does not.

Codex uses .agents/skills/ and commands such as $swarmcraft-do. Reload the workspace if prompted after skills are generated.

Connect GitHub Copilot when you choose it

In VS Code and your terminal:

  1. Install the official GitHub Copilot extension in your SwarmCraft profile and sign in with the GitHub account that has Copilot access.
  2. For one-shot, also install the standalone GitHub Copilot CLI. Its npm installation requires Node.js 22 or newer, even though SwarmCraft's own minimum is lower. Confirm copilot --version succeeds in your terminal.
  3. Run copilot, use /login to complete authentication if needed, then use /user to confirm the intended account. Follow Copilot CLI authentication; organisation-managed access may require the Copilot CLI policy to be enabled.
  4. Run SwarmCraft: Choose AI Provider and choose GitHub Copilot. Start or reconcile the relevant SwarmCraft workflow in your trusted repository to generate its skills.
  5. Before one-shot, check swarmcraft one-shot --help lists copilot under --agent-provider. Upgrade the SwarmCraft CLI if it does not.

Copilot uses .github/skills/ and copied actions such as /do. The gh command installed earlier manages GitHub repository access; one-shot uses the separate copilot command.

Connect Claude Code when you choose it

In VS Code and your terminal:

  1. Install the official Claude Code extension in your SwarmCraft profile and sign in with your Claude subscription.
  2. For one-shot, also install the standalone Claude Code CLI. The extension does not put claude on PATH. Follow Claude's platform requirements, including Git Bash for native Windows where required.
  3. Run claude --version, then claude auth login. Open Claude and use /status to confirm the intended subscription is active. API-key authentication is a separate billing path.
  4. Run SwarmCraft: Choose AI Provider and choose Claude Code. Start or reconcile the relevant SwarmCraft workflow in your trusted repository to generate its skills.
  5. Before one-shot, check swarmcraft one-shot --help lists claude under --agent-provider. Upgrade the SwarmCraft CLI if it does not.

Claude uses .claude/skills/ and commands such as /swarmcraft-do. SwarmCraft preserves an existing CLAUDE.md and Claude settings. Configure the tools Claude may use before unattended runs; SwarmCraft does not grant unrestricted permissions. Claude sign-in is separate from SwarmCraft and GitHub sign-in.

Confirm readiness and sign in

Confirm that:

  • VS Code opened the SwarmCraft profile
  • the SwarmCraft extension is installed and its view opens
  • git --version and gh auth status succeed
  • Node.js/npm and the CLI checks above succeed, and Operate passes its CLI readiness check before asking you to choose a provider
  • your chosen AI extension is installed and signed in; for one-shot, its standalone CLI version and login checks also succeed
  • commit name and email are configured
  • Docker is available only if the project requires containers

Then run SwarmCraft: Sign In and complete SwarmCraft account sign-in in the browser.

Keep account and repository grants separate

SwarmCraft account sign-in happens in your browser. GitHub repository access remains a separate gh auth login grant stored by GitHub CLI. Signing in to SwarmCraft with GitHub does not give the extension repository access, and repository access does not create a SwarmCraft session.

SwarmCraft browser sign-in, GitHub CLI repository access, and Git commit identity are three separate checks. Continue with Sign in and secure your account, then choose a discovery route or connect a ready project.

If a check fails, use Setup and connection recovery. The CLI is required for Operate initialization and validation, Discovery package preparation and validation, and one-shot delivery. Browser sign-in and independent local AI work remain available without it.

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.