SwarmCraft

SwarmCraft brings your project board and packet workflow into VS Code so you can pull work from the board, create linked packet files in your repository, keep updates in sync, and jump into the matching web views when needed.

Install

1. Download VS Code from https://code.visualstudio.com/download.
2. Install SwarmCraft from the Marketplace: https://marketplace.visualstudio.com/items?itemName=SwarmCraft.swarmcraft-vscode-extension.
3. Or install it directly from the command line:

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

4. Open the local repository you want to connect to SwarmCraft.

Sign In

SwarmCraft uses the same authenticated account model as the web app.

1. Finish account setup and MFA enrollment in the SwarmCraft web app if you have not done that already.
2. Open the SwarmCraft activity-bar view in VS Code.
3. Run SwarmCraft: Sign In.
4. Complete the MFA challenge if prompted.
5. Run SwarmCraft: Choose Repo and select the local repository folder you want the extension to use.

After sign-in, the extension stores the session in VS Code Secret Storage and refreshes it on startup or before board and packet commands when the access token is near expiry. If SwarmCraft is temporarily unreachable, the saved session stays on the machine so the next refresh can retry.

If you need the full walkthrough, use these guides:

• Install guide: https://swarmcraft.ai/docs/install-and-connect/download-vscode-and-install-swarmcraft
• Sign in and MFA: https://swarmcraft.ai/docs/install-and-connect/sign-in-and-set-up-mfa
• Connect SwarmCraft to your project: https://swarmcraft.ai/docs/install-and-connect/connect-swarmcraft-to-your-project

What You Can Do

• Sign in with your SwarmCraft account using VS Code Secret Storage for session tokens.
• View unlocked project boards in the SwarmCraft activity-bar view.
• Open project boards and tickets in the SwarmCraft web app.
• Choose which local repository folder the extension should use.
• Seed shared SwarmCraft repo guidance plus Copilot and Codex adapter files when one unlocked project maps unambiguously to the selected trusted repository.
• Create linked packet files under .swarmcraft/projects/ for supported tickets.
• Copy provider-aware SwarmCraft action commands for planning, implementation, checking, review, and testing.
• Open, reveal, and sync linked packet files from the board.
• Drag tickets within a lane to reorder them and move them one adjacent lane at a time.
• Keep packet notes, checklists, and supported lane changes in sync with SwarmCraft.
• Launch the installed SwarmCraft CLI for one-shot project-board runs from VS Code.

AI Action Commands

SwarmCraft exposes five primary AI actions. These are the visible user workflow; diagnostic and seed-audit helpers are maintainer/support tools, not default customer actions.

Use SwarmCraft: Copy Plan Command or SwarmCraft: Copy Test Command from a project when one unlocked project maps to the selected trusted workspace. When a ticket has a linked packet, use SwarmCraft: Copy SwarmCraft Command from the tree context menu to copy the right do, check, or review command for the current lane. SwarmCraft: Copy Test Command is also available from linked packet tickets.

The copied format follows the selected swarmcraft.aiProvider setting:

• copilot copies /plan, /do, /check, /review, and /test commands for .github/prompts.
• codex copies $swarmcraft-plan, $swarmcraft-do, $swarmcraft-check, $swarmcraft-review, and $swarmcraft-test skill invocations for .agents/skills.

Use SwarmCraft: Choose AI Provider to switch the workspace between Copilot and Codex. SwarmCraft seeds the prompt and skill files these commands rely on, but the packet file remains the execution contract.

Seeded Guidance Files

SwarmCraft separates the shared packet contract from provider-specific adapters:

• .swarmcraft/AGENTS.md, .swarmcraft/project.instructions.md, .swarmcraft/project.context.md, and .swarmcraft/agents/*.instructions.md are shared guidance for every AI surface.
• .swarmcraft/projects/<project>/<ticket>.md packet files are the source of truth for ticket scope, checklist progress, notes, agent updates, and supported lane movement.
• .github/prompts/plan.prompt.md, do.prompt.md, check.prompt.md, review.prompt.md, and test.prompt.md are Copilot command wrappers.
• .github/skills/swarmcraft-* are Copilot skills for the same five primary actions.
• .github/agents/swarmcraft-implementor.agent.md, swarmcraft-checker.agent.md, and swarmcraft-reviewer.agent.md are optional Copilot role agents for the lane work.
• .agents/skills/swarmcraft-* are Codex skills for the same five primary actions.
• .codex/agents contains optional Codex role-agent examples for the lane work.
• .codex/config.example.toml documents optional local Codex setup. Do not commit .codex/config.toml if it contains local paths, credentials, or machine-specific values.

If a provider cannot find its adapter files, use the shared .swarmcraft files and packet path as the contract, then reseed or repair the missing provider-specific files.

Key Commands

• SwarmCraft: Sign In
• SwarmCraft: Sign Out
• SwarmCraft: Refresh
• SwarmCraft: Choose Repo
• SwarmCraft: Choose AI Provider
• SwarmCraft: Move to Doing
• SwarmCraft: Open File
• SwarmCraft: Copy SwarmCraft Command
• SwarmCraft: Copy Plan Command
• SwarmCraft: Copy Test Command
• SwarmCraft: Sync Packet
• SwarmCraft: Open Board
• SwarmCraft: Run One-Shot with CLI
• SwarmCraft: Open in Web

Configuration

The extension reads three workspace or user settings:

• swarmcraft.apiBaseUrl: API base URL used for extension requests. Default: https://swarmcraft.ai/api
• swarmcraft.webBaseUrl: browser origin used when commands open SwarmCraft routes. Default: https://swarmcraft.ai
• swarmcraft.aiProvider: provider used when copying SwarmCraft packet commands. Default: copilot

Most users should leave these defaults unchanged.

Support

• Support workspace: https://swarmcraft.ai/login?next=%2fapp%2fsupport
• Product site: https://swarmcraft.ai