SwarmCraft
Set up and connectGuide

Docs

Set up your AI provider

After using SwarmCraft Setup or completing manual setup, install and sign in to the AI provider you will use in VS Code and for one-shot delivery.

Set up your AI provider

Connect your chosen AI provider so SwarmCraft can direct work through your AI assistant. This step follows both SwarmCraft Setup and the manual setup checklist.

You will install and sign in to one provider, select it in SwarmCraft, and check that its tools are ready. Have your SwarmCraft VS Code profile and foundation tools ready before continuing.

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, run claude once in the repository and accept the prompt to trust the folder. Until you do, Claude ignores the repository's .claude/settings.json allow rules and one-shot stages are denied every edit.
  6. 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. It also seeds .claude/settings.json with the tool permissions unattended runs need, adding its rules to any existing settings without removing yours. Review those rules before unattended runs; SwarmCraft does not grant unrestricted permissions. Claude sign-in is separate from SwarmCraft and GitHub sign-in.

For one-shot, SwarmCraft verifies the local Claude subscription login before running. This path rejects API credential flags and does not automatically switch to API billing. Before unattended work, follow Check provider permissions.

Confirm your provider is ready

In VS Code:

  1. Open your SwarmCraft profile and confirm the chosen provider’s extension is installed and signed in.
  2. Open the Command Palette, run SwarmCraft: Choose AI Provider, and confirm the intended provider is selected.
  3. If you will use one-shot, open a terminal and repeat your provider’s version and authentication checks above. Confirm swarmcraft one-shot --help lists your provider under --agent-provider.

You are ready when the editor integration is signed in and the provider you intend to use is selected. One-shot also requires the standalone provider CLI to be available and authenticated in the environment where SwarmCraft runs. If a command is missing, fully quit and reopen VS Code after installation or PATH changes, then use Setup and connection recovery if the check still fails.

Start work with your provider

Complete SwarmCraft account sign-in if needed; it is separate from provider sign-in. Then continue with your chosen workflow:

Start or reconcile the chosen workflow to install its matching skills. Follow Use SwarmCraft AI skills for the commands to use with your provider.