Installation

Setting up agent environments often requires installing local daemons, configuring databases, or uploading code to third-party cloud services. Cards avoids this. It runs entirely within your editor and works out-of-the-box on any local Git repository without modifying your workspace.

Prerequisites

Before installing Cards, verify that your environment has:

• VS Code 1.105.1 or later (or a compatible VS Code-based IDE).
• Node.js 22 or later installed.
• Git 2.34.0 or later installed.
• An active project directory initialized as a Git repository.
• A local agent CLI tool installed. Cards expects either claude or codex on your PATH:
  • Claude Code: npm i -g @anthropic-ai/claude-code (provides the claude command).
  • Codex: npm i -g @openai/codex (provides the codex command).
• On Windows, enable Developer Mode (Settings > System > For developers > Developer Mode). Cards stages worktrees and the marketplace using symlinks, which Windows blocks without Developer Mode.

New to Cards? Follow steps 1 and 2 below, using the Configure Coding Agent wizard to link your CLI. Already have claude or codex on your PATH and comfortable editing VS Code settings? Skip the wizard and set cards.defaultCodingAgent directly in settings.json — see the alternative under Step 2.

1. Install the Extension

Install the VS Code extension to manage cards from your editor:

1. Open the Extensions view in VS Code (Ctrl+Shift+X or Cmd+Shift+X).
2. Search for Cards (published by goodfoot).
3. Click Install.

If you use Cursor, Windsurf, or VSCodium, you can install the extension from the Open VSX registry.

2. Link your Agent CLI

Cards coordinates the agent but does not include the agent executable. You link Cards to your local agent installation:

1. Open the VS Code Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
2. Run the command: Cards: Configure Coding Agent (cards.configureAgent).
3. Select your agent (e.g., claude-code-cli or codex-cli).
4. Specify the absolute path to your agent executable if prompted.

Alternatively, edit your VS Code settings.json manually to set your default agent:

{
  "cards.defaultCodingAgent": "claude-code-cli"
}

Limitations and Trade-offs

• Local Execution Only: The extension runs locally. Your code and agent transcripts never leave your local machine.