Getting started

This guide walks through creating and running your first agent job: you define the task, watch the agent build, and inspect the exact diff before merging.

New to Cards? Follow the steps below, starting with the Cards Assistant in Step 1. Already comfortable with Git worktrees and CLI coding agents? Skip to Step 2 and create the card by hand.

Step 1: Start the Cards Assistant

The easiest way to begin is to let the Cards Assistant create your first card for you.

1. Click the Cards icon in the VS Code Activity Bar to open the Cards view.
2. Click the Start Cards Assistant (sparkle) button in the view's title toolbar.

The assistant opens a terminal and interviews you one question at a time to design your first card. This requires a coding agent to be configured first — if none is set up, the button opens the Configure Coding Agent wizard so you can set one up.

Step 2: Create a Card

1. Click the Cards icon in the VS Code Activity Bar to open the Cards panel.
2. Click Create Card (or run cards.createCard from the Command Palette).

Cards creates a new card repository at ~/.cards/cards-repos/<card-id>/ and opens the card's description file, CARD.md, in your editor.

Step 3: Define the Task

In CARD.md, describe what you want the agent to do. Keep the description specific:

# Implement User Profile Deletion
Add a 'Delete Account' button to the settings page. 
It must call the `/api/user/delete` endpoint and redirect to `/logout`.
Write unit tests in `user-delete.test.ts`.

Save the file. Cards commits your description to the card repository under the user contributor class.

Step 4: Launch the Agent

Click the Launch button in the Cards panel. Cards runs your configured agent on the card in an isolated copy of your repository and streams its output back to your VS Code panel.

Step 5: Monitor the Progress

The agent begins executing. You can watch its progress in the live stream view (cards.openStreamPanel). The agent will analyze the codebase, write code, run tests, and commit its changes directly to the card's branch.

If the session crashes or is interrupted here, clicking Launch again resumes from the last commit on the card's branch — see Resuming after a crashed session.

Step 6: Inspect the Attribution Tree

Once the agent completes its run, click the Compare icon in the Activity Bar to open the attribution tree, then pick the base and comparison from its title bar.

The tree displays the files the agent modified. Click any file to open a side-by-side diff. Because the agent committed its work in isolation, you see the exact delta between your active branch and the agent's output.

Step 7: Approve and Merge

If the changes look correct:

1. Click Approve Merge in the Cards panel.
2. Cards merges the card's branch into your active branch.
3. The temporary worktree at $CARDS_HOME/worktrees/<repoId>/cards/<cardId>/<slot> is deleted.
4. The card is marked as completed and archived.

Limitations and Trade-offs

• Manual Conflict Resolution: Cards does not automatically resolve merge conflicts. If you made changes to the same files in your active branch while the agent was running, Git will prompt you to resolve the conflicts during the merge step.
• File-Level Attribution: The attribution tree shows which files were modified by the card. It does not attribute individual lines within a file if multiple cards edited the same file.