Use SwarmCraft in VS Code

SwarmCraft's delivery loop runs from the VS Code activity-bar view. You move one ticket at a time across the board, copy the right AI action command, give that command to your assistant, and let the packet file keep VS Code and the SwarmCraft project board in sync.

Before you start

Sign in before you try to move tickets or copy commands. If you have not done that yet, follow Sign in and set up MFA, then come back to this guide.

You should also have the repository open in VS Code and connected to SwarmCraft. If the extension is not pointing at the right workspace folder, follow Connect SwarmCraft to your project.

SwarmCraft supports both GitHub Copilot and Codex handoff commands. Copilot is the default. To switch a workspace, run SwarmCraft: Choose AI Provider and choose either GitHub Copilot or Codex. Copilot uses /plan, /do, /check, /review, and /test prompt commands. Codex uses $swarmcraft-plan, $swarmcraft-do, $swarmcraft-check, $swarmcraft-review, and $swarmcraft-test skills.

If you need to bootstrap and run an entire project board from the terminal, install the SwarmCraft CLI and follow Run one-shot with the CLI. After the CLI is installed and signed in, SwarmCraft: Run One-Shot with CLI can launch the CLI from VS Code. VS Code remains the best place for interactive ticket-by-ticket work.

1. Read the project lanes

Open the SwarmCraft activity-bar view in VS Code. The extension shows your unlocked projects and their ticket lanes:

The normal path is:

• Todo: work that has not started
• Doing: implementation work
• Checking: validation work
• Reviewing: human review support
• Done: completed work committed to the repository

Each ticket moves one lane at a time. The extension creates and updates a packet file in your repository so the AI agent has the exact ticket goal, checklist, notes, and current lane.

2. Move your first ticket to Doing

Right-click the next ticket in Todo, then choose Move to Doing.

This does three things:

1. Moves the ticket into the Doing lane.
2. Creates or refreshes the local packet file under .swarmcraft/projects/.
3. Opens the packet file and copies the implementation command to your clipboard when possible.

If VS Code asks you to trust the workspace before SwarmCraft writes packet files, grant trust only for repositories you trust.

3. Copy the SwarmCraft command

If the command was not copied automatically, or if you need it again, right-click the linked Doing ticket and choose Copy SwarmCraft Command.

The copied command points your AI assistant at the packet file. The command format depends on the selected AI provider.

For GitHub Copilot, Doing looks like this:

/do ticket=.swarmcraft/projects/<project>/<ticket>.md

For Codex, Doing looks like this:

$swarmcraft-do ticket=.swarmcraft/projects/<project>/<ticket>.md

The primary SwarmCraft actions are:

SwarmCraft seeds both provider adapter sets into trusted repositories when it can map one unlocked project to the selected workspace. Copilot uses .github/prompts and .github/skills. Codex uses .agents/skills. The packet file under .swarmcraft/projects/ remains the shared execution contract for both providers.

The plan and test actions do not add new SwarmCraft board lanes. plan can help you draft a provisional Todo packet or review whether an existing plan has gone stale. test can add testing evidence to a packet or draft a testing-focused Todo packet. Sync promotion still happens through the extension's packet sync workflow.

4. Choose the implementor agent

Open your AI chat in VS Code and choose the SwarmCraft Implementor role agent if it is available. If you are using Codex, use the copied $swarmcraft-do command with the seeded Codex skill instead. The stable handoff is the do action command; role agents are helpers for the lane work.

The implementor agent reads the packet, inspects the relevant code, makes the smallest useful implementation change, runs focused validation, updates the packet, and moves the packet lane to checking when the work is ready.

5. Paste the command into chat

Paste the copied implementation command into the agent chat and send it.

Keep the packet file open while the agent works. The packet is the shared record between the ticket, the agent, and the repository.

6. Allow commands carefully

If this is your first time using an AI agent inside VS Code, it may ask for permission before running terminal commands.

Choose the approval level you are comfortable with. Allow all commands in this session is faster, but approving individual commands gives you more control while you are learning the workflow.

Read the command before approving it. If you do not understand what the agent wants to run, ask the AI assistant to explain the command and why it is needed.

7. Watch the ticket move automatically

When the implementor finishes successfully, it updates the packet file. The SwarmCraft extension watches supported packet-file changes and syncs them back to the project board. That means you can watch the ticket move in the browser as the packet moves from doing to checking.

The extension syncs supported packet changes such as checklist completion, notes, agent updates, packet linkage, and adjacent lane moves. If the browser board is open, it should reflect those updates without you manually copying status back into SwarmCraft.

8. Repeat the same pattern for Checking

Once the ticket is in Checking, right-click the linked ticket and choose Copy SwarmCraft Command again.

For Copilot, this time the command is:

/check ticket=.swarmcraft/projects/<project>/<ticket>.md

For Codex, it is:

$swarmcraft-check ticket=.swarmcraft/projects/<project>/<ticket>.md

Choose the SwarmCraft Checker agent, paste the command into chat, and let it validate the work. The checker should run focused tests or checks, update the Checking checklist, add validation notes, and move the packet to reviewing when the work passes.

If checking fails, the checker can move the packet back to doing with feedback. Copy the implementation command again, return to the implementor, and fix the issue before checking again.

9. Repeat the same pattern for Reviewing

Once the ticket is in Reviewing, copy the command again. For Copilot, it is:

\review ticket=.swarmcraft/projects/<project>/<ticket>.md

For Codex, it is:

$swarmcraft-review ticket=.swarmcraft/projects/<project>/<ticket>.md

Choose the SwarmCraft Reviewer agent and paste the command into chat.

The reviewer agent helps you understand what changed, what validation evidence exists, and what still needs a human decision. Read the packet, the review notes, and any relevant project documentation before approving checklist items. If something is unclear, ask the AI assistant to explain the change, summarize the affected files, or walk through the risk.

The reviewer should not move the packet to done. It prepares the review and tells you when the ticket is ready for the extension's final Move to Done action.

10. Move the reviewed ticket to Done

After the reviewer has recorded your approval and says the packet is ready, right-click the Reviewing ticket and choose Move to Done.

The first time you do this in a workspace, SwarmCraft shows a commit warning:

This warning means SwarmCraft is about to create a local Git commit in your repository before it moves the ticket to Done. The commit message is based on the ticket, for example:

Complete <ticket-id>: <ticket title>

Confirm the commit only when you are happy with the reviewed changes. If you cancel, the ticket stays in Reviewing.

The full loop

For each ticket, the VS Code workflow is:

1. Move Todo to Doing.
2. Copy the implementation command and run the implementor workflow.
3. Let the packet sync move the ticket to Checking.
4. Copy the checking command and run the checker workflow.
5. Let the packet sync move the ticket to Reviewing.
6. Copy the review command and run the reviewer workflow.
7. Read the review material, ask questions when needed, and approve only what you understand.
8. Use the extension's Move to Done action to create the final local commit and complete the ticket.

Use SwarmCraft: Copy Plan Command from the project when you need to draft a new packet or check an existing plan before work starts. Use SwarmCraft: Copy Test Command from a project or linked packet when you want the assistant to add system-level coverage without changing the lane model.

Why packet files matter

Packet files keep the goal, staged checklist, notes, agent update, and current lane in the repository alongside the code. That makes review easier and keeps the project board grounded in the same working copy you are editing.

When you want more context on build and validation expectations, continue with Build the project.

Keep moving ticket by ticket

Be patient with the AI agents while they work. They may need to inspect files, run checks, ask for command approval, or explain a tradeoff before the ticket can move forward. That is normal.

Your job as the owner-operator is to keep the workflow honest: read the packet, ask questions when something is unclear, approve only what you understand, and keep moving each ticket across the board. SwarmCraft gives you the lanes, packet files, and agents, but you stay in control of the process.

Work the board one ticket at a time. Build, check, review, commit, then take the next ticket. By the end, you are not just watching software get built. You are learning how to own the focused workflow your team actually needs and shape it with confidence.