# Overview (/docs/overview) Cards keeps the entire lifecycle of a job—its description, plans, comments, transcripts, and commits—in a durable, local Git repository. ## Git-Native Architecture [#git-native-architecture] Cards does not use a database or a proprietary cloud service. Instead, it relies on your local Git installation. ### The Card Repository [#the-card-repository] Every job you create is a "Card." Each Card is a standalone Git repository stored on your local disk at `~/.cards/cards-repos//`. This directory contains: * `CARD.md`: The task description and intent. * `CARD.meta.json`: Metadata about the job status and configuration. * `plans/`: The step-by-step implementation plans. * `comments/`: The conversation logs between you and the agent. * `attachments/`: Files attached to the card. * `streams/`: Session transcripts and event streams, grouped by stream type. * `commits/`: Per-commit attribution entries, one file per commit SHA. * `branches/`: Per-branch state, one JSON file per branch. ### Contributor Classes and Commit Attribution [#contributor-classes-and-commit-attribution] Every write to a card repository is committed automatically. Cards attributes these commits to one of three contributor classes: 1. `user`: Commits representing your manual edits to the task description or plans. 2. `agent`: Commits representing the agent's updates, plans, and output. 3. `system`: Commits representing automated transitions, such as starting or pausing a job. This creates a traceable audit trail of the entire collaboration. ### Isolated Worktrees [#isolated-worktrees] When you launch an agent, Cards does not run it in your active working directory. Instead, it creates a Git worktree at `$CARDS_HOME/worktrees//cards///`. The agent executes its tasks, runs tests, and modifies files inside this isolated directory. This prevents the agent from interfering with your uncommitted changes or active branch. The agent commits its progress to a card-specific branch. ### The Attribution Tree [#the-attribution-tree] In VS Code, Cards projects the agent's commits as an **Attribution Tree**, opened from the **Compare** icon in the Activity Bar. You can inspect the net changes file-by-file, view side-by-side diffs, and approve the changes before they are merged into your active branch. # Installation (/docs/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 [#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](#2-link-your-agent-cli). ## 1. Install the Extension [#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 [#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: ```json { "cards.defaultCodingAgent": "claude-code-cli" } ``` ## Limitations and Trade-offs [#limitations-and-trade-offs] > * **Local Execution Only**: The extension runs locally. Your code and agent transcripts never leave your local machine. # Getting started (/docs/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](#step-2-create-a-card) and create the card by hand. ## Step 1: Start the Cards Assistant [#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 [#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//` and opens the card's description file, `CARD.md`, in your editor. ## Step 3: Define the Task [#step-3-define-the-task] In `CARD.md`, describe what you want the agent to do. Keep the description specific: ```markdown # 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 [#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 [#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](/docs/troubleshooting-and-support#1-resuming-after-a-crashed-session). ## Step 6: Inspect the Attribution Tree [#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 [#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//cards//` is deleted. 4. The card is marked as completed and archived. ## Limitations and Trade-offs [#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. # Common workflows (/docs/common-workflows) Cards uses Git worktrees and local configuration files to run parallel tasks and resume interrupted sessions without polluting your main working directory. ## Running Parallel Tasks [#running-parallel-tasks] When you need to fix a critical bug on your main branch while an agent is performing a large refactor, you do not need to pause or stash your work. Because Cards runs each agent in an isolated Git worktree under `$CARDS_HOME/worktrees//cards//`, you can run multiple cards concurrently: 1. Create Card A for the refactor and click **Launch**. 2. Create Card B for the bug fix and click **Launch**. 3. Continue working in your primary VS Code window. Both agents execute in their respective worktrees, committing to their own branches. Once they finish, you can review and merge each card independently. ## Resuming an Interrupted Session [#resuming-an-interrupted-session] If an agent session is interrupted—due to a network timeout, rate limits, or an explicit cancellation: 1. Open the interrupted card in the Cards panel. 2. Click **Launch** again. Cards detects the existing worktree at `$CARDS_HOME/worktrees//cards//` and the last commit on the card's branch. The agent resumes execution from the exact state of the last commit, preventing token waste from restarting the entire task. ## Limitations and Trade-offs [#limitations-and-trade-offs] > * **Resource Contention**: Running multiple agents concurrently increases local CPU and memory usage. It can also cause you to hit rate limits on your LLM provider. # Pricing and plans (/docs/pricing-and-plans) Cards has two plans: a free tier and Pro. The free tier works the moment you install the extension — no account and no internet required — and gives you a local bank of cards to create. When you need to create cards without limits, Pro is a flat **$30 per month**. Everything else about how Cards works is identical on both plans. ## The free tier [#free-tier] The free tier requires no account, sign-up, or internet connection. The extension tracks card creation locally on your machine. ### How the local bank works [#how-the-local-bank-works] * **Initial Allocation**: A new installation starts with a bank of **50 cards**. * **Accrual**: The bank accrues **+5 cards per week**, up to a maximum cap of **50 cards**. * **Enforcement**: When the bank is exhausted, you cannot create new cards until it refills. You can still read, edit, and run actions on any card already on disk. There are no time limits or feature gates on the free tier. The default actions, stream renderers, and local Git-backed history work exactly as they do on Pro. ## Pro [#pro] Pro costs **$30 per month** per seat, billed through the dashboard. * **Unlimited Card Creation**: The local bank and weekly accrual limits no longer apply. * **Flat Rate**: We do not meter your card usage, API calls, or workspaces. There are no overages or monthly quotas. * **License Activation**: There are two ways to activate Pro: * **Automatic (online)**: [Register the extension](/docs/troubleshooting-and-support#registration) to activate Pro automatically and keep your license current. * **Manual (offline)**: Paste a license code that begins with `CARDS_v1_` into the **Cards License** panel and choose **Apply license**. The code is validated locally on your machine and needs no internet connection. ## Grant program [#grant-program] We provide free Pro access to individuals who qualify under three categories: * **Students**: Active enrollment in an accredited educational institution. * **OSS Maintainers**: Active maintainers of established open-source projects. * **Nonprofits**: Staff working at registered non-profit organizations. Grants are applied to your identity after a manual application review. While a grant is active, you get Pro features at no cost. ## Cancellation [#cancellation] Because every card is a local Git repository, cancelling your subscription does not delete or lock your data. If you cancel: 1. Pro ends at the close of your billing cycle. 2. The extension falls back to the free tier. 3. Your local card bank is restored (starting at its last tracked level, up to the 50-card cap). 4. You retain full read-write access to all existing cards on your disk. # Cards and content (/docs/cards-and-content) A card is a local, Git-backed directory on disk that contains all content, history, and metadata for a single coding-agent job. Storing this data in a dedicated Git repository keeps your agent's workspace history isolated from your primary project repository. ## Location on disk [#location] Cards are stored under your home directory: ```bash ~/.cards/cards-repos// ``` Every card directory is initialized as a standalone Git repository. When the extension or an agent modifies a file within this directory, the changes are committed to track the job's evolution. ### Customizing the location [#custom-location] The path above is the default. You can store cards elsewhere with environment variables: * `CARDS_HOME` — overrides the base `~/.cards` directory. * `XDG_DATA_HOME` / `XDG_CONFIG_HOME` — respected when set, following the XDG base directory convention. * `CARDS_WORKTREES_DIR` — overrides where card worktrees are placed. ## Directory layout [#layout] A card's repository contains the following files and directories: ``` ~/.cards/cards-repos// ├── CARD.md ├── CARD.meta.json ├── CARD.md.meta.json ├── commits/ │ └── ├── branches/ │ └── .json ├── plans/ │ └── initial.md ├── comments/ │ └── 01-user-prompt.md ├── attachments/ │ └── schema.sql └── streams/ └── / ├── 75e7a9b0-agent-run.jsonl └── 75e7a9b0-agent-run.jsonl.meta.json ``` ### File reference [#file-reference] | File / Directory | Purpose | Format | | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------- | | `CARD.md` | The task description. Explains the intent (the "why"). | Markdown (no frontmatter) | | `CARD.meta.json` | The canonical card metadata (id, title, status, tags, gates, parent branch). | JSON | | `CARD.md.meta.json` | A sidecar file holding metadata for `CARD.md`. | JSON | | `commits/` | Tracks the project workspace commits associated with this card. One entry file per attributed commit, named `commits/`, mapping SHAs to card attribution. | One file per SHA | | `branches/` | Tracks the branches and worktrees associated with this card. One JSON entry per branch, named `branches/.json`. | JSON files | | `plans/` | Holds the implementation steps (the "how"). | Markdown files (prefixed with `plans/`) | | `comments/` | Holds the conversation history and messages between you and the agent. | Markdown files (prefixed with `comments/`) | | `attachments/` | Holds external files, mock data, or reference documents. | Binary or text files | | `streams/` | Holds live agent session transcripts and their metadata sidecars. | `.jsonl` files and `.jsonl.meta.json` sidecars | ### How commits are tracked (`commits/`) [#how-commits-are-tracked-commits] When an agent commits code in your project's worktree, the Cards toolchain captures the commit SHA and writes a per-commit entry file at `commits/` in the card's repository. This maintains a clear link between the card and the actual code changes without polluting your project's git history with card metadata. ### How transcripts are streamed (`streams/`) [#how-transcripts-are-streamed-streams] When an agent runs, its output is written to a JSON Lines (`.jsonl`) file under `streams//`. A matching `.jsonl.meta.json` sidecar file tracks the stream's metadata, including the task slug, active status, and line count. Cards watches this directory and broadcasts live updates to the VS Code UI. ## Git hooks and metadata integrity [#integrity] The card repository uses a custom pre-commit hook to maintain integrity: * **Commit Validation**: The hook ensures that any commit to the card repository conforms to the expected structure, preventing accidental manual edits from corrupting the agent's history. # Actions and agent modes (/docs/actions-and-agent-modes) An action is a named shell command executed against a card's context. It configures the workspace, sets up the environment, and launches an external agent harness (such as Claude Code or Codex CLI). ## How actions execute [#how-it-works] When you trigger an action, the Cards toolchain performs the following steps: 1. **Worktree Materialization**: Cards creates a Git worktree of your project codebase. This keeps the agent's file modifications isolated from your active working directory. 2. **Environment Setup**: Cards injects a small set of context variables into the shell session — including the card's id (`CARD_ID`), the path to the materialized worktree (`WORKSPACE_PATH`), and the repository root — so the harness knows which card and code it is operating on. 3. **Process Spawning**: Cards spawns the configured shell command (e.g., `claude` or `codex`) with its working directory set to the materialized worktree. ```mermaid flowchart LR A[Card Context] -->|launches| B[Project Worktree
Isolated Branch] B -->|executes| C[Agent Harness
Claude / Codex] ``` ## Default actions [#default-actions] Cards registers four default actions: ### 1. Launch (`launch`) [#1-launch-launch] Runs the agent against the task. The agent reads the task description in `CARD.md`, analyzes the codebase, plans its changes, and writes code to complete the task. Launch can run interactively or in the background. ### 2. Interview (`interview`) [#2-interview-interview] Launches the agent in an interactive session. The agent reviews the task description and asks you clarifying questions about the requirements, design decisions, or constraints before making any changes. ### 3. Chat (`chat`) [#3-chat-chat] Opens an interactive chat session with the agent inside the project worktree. Use this for ad-hoc queries, debugging help, or manual guidance. ### 4. Captain (`captain`) [#4-captain-captain] Delegates work to free-form subagents. The agent loads the `runtime:captain` skill and follows its routing instructions, breaking the task into subtasks it routes to specialized subagents. Captain can run interactively or in the background (background launch requires the Claude coding agent). ## Execution modes [#execution-modes] Actions run in one of two execution modes: * **Interactive**: you and the agent work together in a live session, exchanging messages as it goes. * **Background**: the agent runs unattended to completion. Among the default actions, **Launch** and **Captain** support background mode. ## Invoking actions [#invocation] Invoke actions from the VS Code UI: 1. Open the **Cards** panel in the Activity Bar. 2. Select a card from the list. 3. Click the icon for the action you want to run (e.g., **Launch** or **Interview**). 4. View the live output in the stream view. ## Worktree materialization and ignored paths [#worktree-materialization] Each materialized worktree is provisioned from one path policy, decided before any git-ignored path is linked: * **Share (default)** — git-ignored paths matched by neither policy file are symlinked into the worktree, so the agent sees the same files as the source checkout. * **Omit** — paths matching `.worktreeignore` at the repository root are never provisioned. * **Copy** — paths matching `.worktreeinclude` at the repository root are copied as real files, so the agent can edit them without touching the source. Use `.worktreeignore` for generated outputs that should not appear in the worktree (build artifacts, caches), and `.worktreeinclude` for git-ignored files the agent needs as editable copies. Both files use gitignore-style patterns. Omit wins over copy; a copy rule for a file under an ignored directory (for example `dist/bundle.js` under an ignored `dist/`) prevents the directory symlink and copies only the selected files. The policy is re-evaluated on every materialization, and an unreadable or invalid file stops worktree creation before any matching path is linked. ## Under the hood: Limitations [#limitations] * **Relies on an external harness**: Cards orchestrates and drives the agent harness, but it is not the harness itself and does not make LLM API calls on its own. If the underlying CLI tool (e.g., `claude`) is missing from your system or lacks API keys, the action will fail. * **Dependency on Git**: Because actions rely on Git worktrees, the project must be a valid Git repository with a clean state or committed history. # Lifecycle, status, and gates (/docs/lifecycle-status-and-gates) A card's lifecycle is governed by its status and gates. These markers track progress and enforce quality gates before code is written or merged. ## Status values [#status] A card is always in one of five states: * **`todo`**: The task is defined but work has not started. * **`active`**: An agent is actively executing an action against the card. * **`needs_review`**: The agent has finished its run and is awaiting human review of the changes. * **`done`**: The task is complete and changes are merged. * **`archived`**: The card is archived and hidden from the active list. ## Configuring gates [#configuring-gates] Each gate has two controls on the card detail panel: the **Plan** toggle and the **Merge Request** toggle. Use each toggle to require the gate, and the matching **Approve** action to approve it. The merge gate cannot be approved until the plan gate is approved. A card's gates are represented by four fields: ```json { "gates": { "planRequired": true, "planApproved": false, "mergeRequestRequired": true, "mergeApproved": false } } ``` ### Gate definitions [#gate-definitions] | Gate | Description | | :------------------------- | :--------------------------------------------------------------------------- | | **`planRequired`** | If `true`, the agent must submit a plan for approval before writing code. | | **`planApproved`** | Set to `true` when you approve the agent's plan. | | **`mergeRequestRequired`** | If `true`, the agent must request a merge review before completing the card. | | **`mergeApproved`** | Set to `true` when you approve the code changes. | ## Advisory gates [#advisory] Both the plan gate and the merge gate are **advisory**. They are checkpoints that prompt for your approval at the right moment — they do not hard-block a status transition. * **Plan gate** (`planRequired` / `planApproved`): when a plan is required but not yet approved, an autonomous agent is expected to halt and ask for input before writing code. * **Merge gate** (`mergeRequestRequired` / `mergeApproved`): when a merge review is requested but not yet approved, you are prompted to review and approve before completing the card. Both gates are off by default, and you stay in control of whether to require them. ## Approving a card's merge gate [#approval] To approve changes and complete a card: 1. Open the card in the VS Code **Cards** panel. 2. Review the code changes in the **Attribution Tree** (derived from the card's `commits/` directory). 3. Click **Approve Merge** to approve the merge gate. 4. Transition the card's status to **Done**. # Attribution and version control (/docs/attribution-and-version-control) Cards records each write to a card under a distinct Git author identity, and projects a card's commits as a visual attribution tree. ## Contributor identities [#contributor-identities] Every write to a card repository is committed under one of three Git author identities — a name and email address that says who made the change: * **`user `**: Commits initiated by a human developer. * **`agent `**: Commits generated by the AI agent during an active session. This is the default identity. * **`system `**: Automated commits created by the Cards platform (e.g., status transitions or metadata updates). Because each commit carries its own author identity, you can read directly from a card's history who was responsible for any given change. ## The attribution tree [#the-attribution-tree] The attribution tree is a separate view: it projects a card's workspace commits against your active worktree, so you can see the net changes a card has made to your files. As you work, commits made against a card are tracked for that card, and the tree renders the combined result. The tree is opened from the **Compare** icon in the Activity Bar (the left-hand rail of icons in VS Code). Selecting that icon opens the Compare view; pick a card and expand its tree to see the files the card has touched. Click any file to open a side-by-side diff: the editor compares the current state (right pane) against the pre-card state (left pane). How each file opens depends on its state: * **Uncommitted working tree edits** stay editable — you are looking at the live file and can change it. * **Files that match the card's tip commit** (unchanged since then) are also editable. * **Files that have changed since the card's tip commit** open as read-only, so you do not accidentally overwrite concurrent work. * **Deleted files** are always read-only. ## Limitations [#limitations] The attribution tree operates at the file level. It does not provide line-by-line git blame attribution if multiple cards or contributors edit the same file. # Sessions and streams (/docs/sessions-and-streams) An agent execution run is a session. Its real-time, append-only log is a stream. Cards records every session on disk and streams the active output to your editor. ## On-Disk Persistence [#on-disk-persistence] All streams are saved directly in the card repository: * **Path**: `streams/{streamType}/{filename}.jsonl` * **Naming**: `{filename}` follows the pattern `{uuid}-{agentId}.jsonl` (e.g., `01906a5a-4b03-4924-b6c7-56035d6000bd-claude.jsonl`). * **Metadata**: A sibling `{filename}.meta.json` file stores the stream's state: ```json { "title": "Fixing type errors in database schema", "sessionId": "01906a5a-4b03-4924-b6c7-56035d6000bd", "taskContent": "Run typecheck and fix any errors under packages/db", "slug": "fixing-type-errors", "lineCount": 142, "createdAt": "2026-06-29T16:30:00.000Z", "isActive": true } ``` ## Live Streaming [#live-streaming] Cards watches the `streams/` directory. When an agent writes to a `.jsonl` file, Cards: 1. Reads the new bytes appended since the last update. 2. Streams each completed line to your editor in real time. 3. Parses the output for a `slug` or `taskContent`. 4. Updates the `lineCount` and metadata in the `.meta.json` sidecar. If the stream is new (uncommitted), Cards opens a live tab in the editor. When the agent exits, the live tab finalizes. ## Versioning and Checkpoints [#versioning-and-checkpoints] To ensure your session history is preserved: * **Pre-commit**: Cards automatically stages all local stream files before any commit. * **Post-commit**: Cards commits the active stream and its metadata into the card repository using the message format `Checkpoint stream: {sessionId}.jsonl (workspace {sha})`. ## Limitations [#limitations] > Streams are append-only. Manually editing a `.jsonl` file can corrupt the line count and offset cursors, causing Cards to miss new lines or desynchronize. # Configuration, rules, and scopes (/docs/configuration-rules-and-scopes) Cards configures its actions, renderers, and agent behavior across two main surfaces: 1. **SDK Configuration**: TypeScript configurations (e.g., `settings.config.ts`) compiled using the Cards SDK CLI to generate `settings.json`. This defines custom actions (`defineAction`) and renderers. 2. **Runtime Skills**: Markdown files that provide instructions and context directly to the agent. A runtime skill lives at `public/claude/runtime/skills/{name}/SKILL.md` (for example, `public/claude/runtime/skills/interview/SKILL.md`), and is loaded during resolution from your project and global directories. ## The Three-Layer Loading Order [#the-three-layer-loading-order] Cards resolves and merges settings from three layers. Each layer merges into the previous: 1. **Default**: Shipped with the Cards extension. 2. **User**: Global settings at `~/.cards/settings.json` (resolves via `$CARDS_HOME` or `$XDG_CONFIG_HOME`). 3. **Project**: Local settings at `{repoPath}/.cards/settings.json`. ## Scopes are environments [#scopes-are-environments] In Cards, a "**scope**" is an **environment** — a named configuration block (for example `default` or `development`). When you do not name one, `default` is used. Each environment carries its own **actions** (the buttons that appear on a card) and, optionally, its **streams** (renderers). There is no separate rules or scopes file: environments in `settings.json` are the scope mechanism. ## Merging and Overriding Rules [#merging-and-overriding-rules] Cards merges configurations at the **environment name** level: * **Environment-Level Replacement**: If a project-level configuration defines an environment name that already exists in the user-level configuration, the project-level definition **completely replaces** the user-level definition. It does not deep-merge the actions or properties. * **Overriding Warnings**: When a replacement occurs, the server logs a warning noting that the project environment overrides the user environment of the same name. * **Path Resolution**: To resolve relative command and icon paths (for example a path written with `${workspaceRoot}` or `${extensionPath}`), the server remembers which layer supplied the winning environment and resolves paths relative to that layer's directory. ## What you can configure [#what-you-can-configure] These are the surfaces you are meant to edit. Installer-managed files are called out so you leave them alone. ### VS Code settings (`cards.*`) [#vs-code-settings-cards] * `cards.defaultCodingAgent` — the default coding agent for card actions (`""`, `"claude-code-cli"`, or `"codex-cli"`). Usually set by the Configure Coding Agent wizard. * `cards.tree.enableDragAndDrop` — enable drag-and-drop in the Attribution Tree view (default `true`). * `cards.tree.confirmDragAndDrop` — confirm before a drag-and-drop move (default `true`). * `cards.hooksLogFile` — path for the hooks log file (defaults to `{workspace}/.cards/logs/cards-default-configuration-hooks.log`). * `cards.agentInstallManifest` — installer-managed. **Do not edit manually.** ### Cards `settings.json` [#cards-settingsjson] This is the real "configuration, rules, and scopes" surface. It is merged across the three layers above (default → user → project), with environments replaced by name rather than deep-merged. * **User**: `~/.cards/settings.json` * **Project**: `{repoPath}/.cards/settings.json` Each environment defines: * `actions` — the per-card buttons, each with an `id`, `name`, optional `description` and `icon`, a `command`, and optional `supportsBackgroundMode` / `allowConcurrent` flags. Icon paths support `${workspaceRoot}` and `${extensionPath}`. * `command` — the command to run, with an optional `timeout` (default 30000 ms). * `streams` — optional renderer definitions (`wwwRoot`, an optional `entrypoint` defaulting to `index.html`, and optional size limits). You author this file with the SDK and compile it (see below) rather than hand-writing every field. ### Per-project instruction files [#per-project-instruction-files] * `{repoPath}/AGENTS.md` — free-form Markdown prepended to the Codex session. This is the only free-form per-project instruction file Cards itself consumes. * `CLAUDE.md` — loaded by the Claude CLI itself; Cards does not parse it. **Installer-managed — do NOT hand-edit:** `~/.codex/config.toml`, `~/.codex/cards.config.toml`, `~/.codex/cards-assistant.config.toml`, and the Claude plugin/marketplace files (`settings.json` marketplace keys, `known_marketplaces.json`, `marketplace.json`). ### Worktree path policy files [#worktree-path-policy-files] * `{repoPath}/.worktreeignore` — gitignore-style patterns for git-ignored paths that are **omitted** from card worktrees (generated outputs, caches). Omit wins over copy. * `{repoPath}/.worktreeinclude` — gitignore-style patterns for git-ignored paths that are **copied** into card worktrees as real files (local environment files the agent needs to edit). A copy rule prevents the ignored ancestor directory from being symlinked; only the selected files are copied. Both files are read from the repository root and re-evaluated on every worktree materialization. Git-ignored paths matching neither file keep the default behavior: they are shared into the worktree as symlinks. An unreadable or invalid file stops worktree creation before any matching path is linked. ### Environment variables [#environment-variables] You can set these to relocate or tune Cards: * `CARDS_HOME` — override the `~/.cards` location. * `XDG_DATA_HOME` / `XDG_CONFIG_HOME` — standard XDG overrides. * `CARDS_WORKTREES_DIR` — where worktrees are created. * `CLAUDE_CONFIG_DIR`, `CODEX_HOME` — agent config locations. * `CARDS_HOOKS_LOG_FILE`, `CARDS_LOG_DIR` — logging destinations. * `CARDS_DEBUG=1` — enable debug logging. * `CARDS_SKIP_HOOK=1` — skip the git hook for a run. * `CARDS_REQUEST_TIMEOUT_MS` — request timeout. * `CARDS_DISCOVERY_PATH` — discovery path override. ## Compiling Your Configuration [#compiling-your-configuration] To compile a TypeScript configuration file into the required `settings.json` format, run: ```bash cards-sdk build -c settings.config.ts -o .cards ``` ## Limitations [#limitations] **Note:** Because environment configurations do not deep-merge, defining a custom action in your project's `default` environment requires you to redeclare all other actions from the user or default layers if you want to retain them. # Permissions and safety (/docs/permissions-and-safety) Security is divided between **Cards** (which governs metadata, plans, and merge gates) and the **agent harness** (which governs system access, file modifications, and network requests). Cards does not sandbox the agent's execution. It relies on a three-tier validation system for metadata and Gated workflows. ## The Three Tiers of Cards Validation [#the-three-tiers-of-cards-validation] Cards protects the integrity of the card repository using three enforcement tiers: ### 1. API Validation [#1-api-validation] The Cards server validates the card repository's schema and integrity whenever metadata is written to `CARD.meta.json`. ### 2. Git-Hook Validation [#2-git-hook-validation] A pre-commit hook runs locally before each commit is finalized. It is fail-closed; if any validation fails, the commit is rejected. The hook enforces the following rules: * **Metadata Integrity**: Rejects the commit if `CARD.meta.json` is malformed. * **Mermaid Syntax**: If a committed `.md` file contains a Mermaid diagram, Cards validates it and rejects the commit if the diagram is unreachable or its syntax is invalid. * **Merge Gate Reset**: If the commit adds new files to the `commits/` directory, the hook automatically resets `gates.mergeApproved` to `false` in `CARD.meta.json`. * **Plan Gate Reset**: If a new plan file is added under the `plans/` directory, the hook automatically resets `gates.planApproved` to `false` in `CARD.meta.json`. ### 3. Skill Convention [#3-skill-convention] Convention-level rules govern how agents interact with the project workspace, such as using temporary branches or sharing worktrees. ## Harness-Level Permissions [#harness-level-permissions] The agent harness (e.g., Claude Code or Codex) is responsible for sandboxing and executing commands. Because the harness runs as a subprocess under your local user account, it has the same system access as your shell. You must configure file-system boundaries, network allowlists, and command-approval prompts directly in the harness configuration (for Claude Code, in `.claude/settings.json` or `~/.claude/settings.json`). ## Limitations [#limitations] > **Caution:** Bypassing the Git hooks (e.g., via `git commit --no-verify` or setting `CARDS_SKIP_HOOK=1`) will allow unvalidated metadata or invalid Mermaid syntax into the repository. This can break the Cards UI and cause the server to reject subsequent sync operations. # Privacy and data (/docs/privacy-and-data) Cards is designed around a local-first architecture. Your source code, card histories, and agent conversation transcripts remain on your local machine under your direct control. ### Local-First Data Flow [#local-first-data-flow] Cards stores all work objects locally. The hosted dashboard at `cards.management` only processes account identity, licensing, billing, and team memberships. ```mermaid graph TD A[Your Local Machine] <-->|1. HTTPS Licensing & Billing| B[cards.management / Polar] A <-->|2. HTTPS API Tokens| C[Model Provider e.g., Anthropic] subgraph Local Storage D[Source Code] E[Card Repositories ~/.cards/cards-repos/] F["Isolated Worktrees ~/.cards/worktrees/<repoId>/cards/<cardId>/<slot>"] end ``` ### Data Flow and Storage Locations [#data-flow-and-storage-locations] | Data Type | Description | Location | Transmitted To | | :---------------------- | :-------------------------------------------------------------------------------------- | :----------------------------------- | :------------------------------------------- | | **Source Code** | Your project files and repositories. | Local Disk | None (Stays Local) | | **Card Content** | Descriptions (`CARD.md`), plans (`plans/` directory), comments, and history. | `~/.cards/cards-repos//` | None (Stays Local) | | **Agent Transcripts** | The step-by-step logs and tool execution history. | `~/.cards/cards-repos//streams/` | None (Stays Local) | | **Licensing & Billing** | User account (authenticated via WorkOS), subscription tier, and active seat allocation. | `cards.management` database | WorkOS (identity), Polar (payment processor) | | **Inference Tokens** | Prompts and responses sent during agent runs. | Local Agent Harness | Model Provider (direct connection) | ## Local-first guarantees [#local-first-guarantees] 1. **Zero codebase exposure:** Cards never reads or transmits your source code to our servers. All parsing, context gathering, and diff generation happen locally in the extension and your local Git installation. 2. **Offline-ready card history:** Because each card is a local Git repository, you can view, edit, and search your card history completely offline. 3. **Direct model provider traffic:** The Cards extension does not proxy your LLM requests. The agent harness connects directly to your configured model provider (such as Anthropic or OpenAI) using your API keys. Your data is subject to the terms of service and data retention policies of the provider you select. ## Managing backups [#managing-backups] Because Cards does not sync your data to a cloud service, you are responsible for backing up your card history. ### Backing up card repositories [#backing-up-card-repositories] All cards are stored in `~/.cards/cards-repos/`. You can include this directory in your standard system backup routine (e.g., Time Machine, Arq, or restic). ## Disabling telemetry [#disabling-telemetry] The Cards extension collects anonymous usage diagnostics to help us identify performance bottlenecks. We never collect source code, card text, filenames, or API keys. To opt out of all telemetry: 1. Open your VS Code Settings (`Ctrl`+`,` or `Cmd`+`,`). 2. Search for `Telemetry: Telemetry Level`. 3. Set the level to `off` (or `crash` to only send crash reports). # What Cards does not do (/docs/boundaries) Cards is a work surface and context manager for building with agents. It orchestrates and controls agent runs—spawning your harness as a subprocess, injecting context and hooks, and owning the session lifecycle—but it is not a governance or policy control system, not an autonomous execution engine (the Factory/Jules/Devin style that owns the agent end to end), not the agent harness itself, and not a deployment platform. Establishing clear boundaries prevents integration conflicts and keeps you in control of your development environment. ### Architectural Coordinator [#architectural-coordinator] Cards operates as a coordinator between you, your local Git repository, and your chosen agent harness. It prepares the context, manages the workspace isolation, spawns the harness as a subprocess, and logs the history, but it leaves the agent's tool loop and model inference to that harness and its provider. ### Responsibility Matrix [#responsibility-matrix] | Feature | Handled By | What Cards Does NOT Do | | :----------------------- | :----------------------------------------------- | :-------------------------------------------------------------------------------------------------------- | | **Agent Execution** | Agent Harness (e.g., Claude Code, Codex) | Cards does not run the agent loop, manage tool-calling logic, or handle agent planning. | | **Inference & Models** | Model Provider (e.g., Anthropic, OpenAI, Ollama) | Cards does not host models, manage model weights, or provide LLM APIs. | | **Data Storage** | Local Filesystem (`~/.cards/`) | Cards does not store your codebase or card content in the cloud. | | **Workflow Enforcement** | Git / User Decisions | Cards does not enforce custom git workflows, branch naming rules, or code reviews outside the merge gate. | | **App Building** | Compiler / Bundler / IDE | Cards is not a low-code app builder or code-generation engine. | | **Deployment** | CI/CD (e.g., GitHub Actions, Vercel) | Cards does not deploy code, run production builds, or manage hosting. | ## What Cards does NOT do [#what-cards-does-not-do] ### 1. Host models or manage inference [#1-host-models-or-manage-inference] Cards does not run LLMs. You must configure your own API keys or run a local model server (such as Ollama). The agent harness you select makes all inference calls directly. ### 2. Control the agent loop [#2-control-the-agent-loop] Cards does not decide how the agent solves a task. It does not select which tools the agent calls or how it handles errors. The extension simply launches the agent CLI as a subprocess and streams its output. ### 3. Store card content in the cloud [#3-store-card-content-in-the-cloud] We do not host your card descriptions, plans, or transcripts. If you delete the local `~/.cards/` directory without a backup, your card history is permanently lost. ### 4. Enforce gates beyond its two optional approval gates [#4-enforce-gates-beyond-its-two-optional-approval-gates] Cards has exactly two gates, both optional and off by default: * The **plan gate** (`planRequired` / `planApproved`) blocks a card from moving from `todo` to `active` until the plan is approved. * The **merge gate** (`mergeRequestRequired` / `mergeApproved`) blocks a card from reaching `done`—and prevents the agent's worktree branch from merging into your active branch—until the merge is approved. Both gates default to off, so cards progress without enforcement unless you opt in. Beyond these: * Cards does not block you from editing files, committing code manually, or running commands outside the extension. * Cards does not enforce branch protection rules, linting checks, or test suites on your main repository. You can configure your own Git hooks or CI/CD pipelines to handle these checks. ### 5. Live-pairing or collaboration [#5-live-pairing-or-collaboration] Cards is not a collaborative editing tool. It does not support real-time multi-user editing of the same card or worktree. Each card represents a local job run by a single local user and their agent subprocess. # Troubleshooting and support (/docs/troubleshooting-and-support) Most troubleshooting in Cards involves inspecting local Git repositories, checking the extension's status, or managing local files. When an agent session crashes, a card won't move to Done, or a Git worktree fails to clean itself up, you need a direct path to restore your workspace without losing your progress. ## Common troubleshooting steps [#common-troubleshooting-steps] ### 1. Resuming after a crashed session [#1-resuming-after-a-crashed-session] If the agent subprocess exits abruptly (due to a model timeout, network interruption, or local process crash), the card may remain in the `active` state but the session stream will stop. **To resume the session:** 1. Open the card in the Cards panel. 2. Click the **Launch** button again. 3. Cards detects the existing card-specific Git branch and resumes the session. It does not overwrite your previous progress or history. *** ### 2. Can't move a card to Done [#2-cant-move-a-card-to-done] A card moves freely between states (`todo`, `active`, `needs_review`, `done`, `archived`) — there is no permanent "stuck" state. If you can't move a card to `done`, the optional **Merge Gate** is enabled for it. **Why this happens:** The Merge Gate is an **optional** gate that is **off by default**. When you enable it for a card, the card must pass through `needs_review` and have its merge approved before it can transition to `done`. The gate never permanently blocks a card: when it's active, the **Mark as Done** action offers a **"Mark as done anyway?"** override, and confirming it approves the merge and completes the transition in one step. **To resolve this:** 1. Open the card details panel. 2. Review the changes in the **Attribution Tree**. 3. Click **Approve Merge** to merge the changes into your active branch, or click **Discard Changes** to clean up the worktree. 4. Move the card to `done`. If the Merge Gate is still enabled, choose **"Mark as done anyway?"** when prompted to override it. *** ### 3. Cleaning up orphaned worktrees [#3-cleaning-up-orphaned-worktrees] If VS Code closes unexpectedly while an agent is running, the Git worktree created for that card may remain on disk under `~/.cards/worktrees//cards///`. This can cause Git conflicts or lock files when you attempt to run new actions. **To clean up orphaned worktrees:** * **From the Cards panel:** 1. In the Cards panel, open **More Actions** and select **View Worktrees** (also available as the **Cards: View Worktrees** command). 2. Find the orphaned worktree in the list and click **Remove**. If a worktree is broken rather than orphaned, use **Repair** instead. * **Via the terminal:** If the in-panel action does not resolve the issue, you can prune the worktrees manually from your project repository: ```bash # Run this inside your project directory git worktree prune ``` *** ### 4. Registration and licensing problems [#registration] If Cards shows a **Trial** or **Blocked** status, or card creation is paused until you register or enter a license code, the fastest fix is to apply your license code directly. This works **offline** — the code is verified locally and never needs an internet connection. **To activate with a license code (offline):** 1. Run **Cards: Show License Status** from the Command Palette to open the license panel. 2. Expand **Replace license code**. 3. Paste your `CARDS_v1_...` code. 4. Click **Apply license**. The code is validated locally on your machine, so this path requires no connectivity or proxy access. **Online alternatives (these do require connectivity):** * **Register in the browser:** Run **Cards: Register** to complete browser-based registration against `cards.management`. * **Refresh the license:** Run **Cards: Refresh License** to re-verify your seat with the server. * **Corporate proxy settings:** If you use the online paths from behind a corporate proxy, verify that your VS Code proxy settings are configured correctly and that `https://cards.management` is whitelisted. (The offline license-code path above is unaffected.) *** ### 5. Worktree is missing files or contains unexpected symlinks [#5-worktree-is-missing-files-or-contains-unexpected-symlinks] When a card action materializes a worktree, every git-ignored path gets one decision: unmatched paths are **shared** as symlinks, paths matching `.worktreeignore` are **omitted**, and paths matching `.worktreeinclude` are **copied** as real files. A file-level `.worktreeignore` pattern under a fully-ignored directory removes the whole directory from the worktree (a symlinked directory cannot be partially omitted); use a copy rule for the file if the rest of the directory must remain. Inside `node_modules` in a workspaces repo, the same rule keeps the package usable instead: the package becomes a real directory with the ruled path absent and its other files symlinked, so writes at the ruled path cannot reach the source. **To resolve this:** 1. Check `.worktreeignore` and `.worktreeinclude` at the repository root — both use gitignore-style patterns, and omit wins over copy. 2. Verify both files are readable and valid. Worktree creation fails closed when either file is unreadable or invalid — nothing is linked until the config is fixed. 3. The policy is re-evaluated on every launch, so after editing either file, run the action again to apply the change. A launch whose worktree setup fails closed (for example, an unreadable config file) removes its partially-created worktree automatically — the directory, its git registration, and the branch the failed run created — before surfacing the error, so the retry starts from a clean slate. A branch that existed before the failed launch is left untouched. If cleanup itself fails, the error message names the leftover directory; remove it with the `remove-worktree` command before re-running. *** ## Viewing diagnostics [#viewing-diagnostics] If you encounter an unexplained error, start with the server status view to inspect the extension's health. 1. Open the Command Palette (`Ctrl`+`Shift`+`P` or `Cmd`+`Shift`+`P`). 2. Run **Cards: Show Server Status** to review the current state of the Cards server and surface error conditions. 3. If you need help, run **Cards: Report Issue** to package up the relevant details and reach the team. ## Where to get support [#where-to-get-support] * **GitHub Issues:** Submit bug reports and reproduction steps on [our GitHub repository](https://github.com/goodfoot-io/cards.management). * **Email Support:** For billing, licensing, or account issues, contact us at [support@cards.management](mailto:support@cards.management). # Glossary and reference (/docs/glossary-and-reference) Use this page as a reference for Cards terminology, state values, and configuration schemas. ## Core concepts glossary [#core-concepts-glossary] * card — The durable, local Git-backed work object representing a single agent task. It is stored as a standalone Git repository on your local disk. * card-repo — The local Git repository under `~/.cards/cards-repos//` that stores a card's description, plan, comments, and session history. * workspace — The active project repository that you open in VS Code. This is where your production code lives and where the agent's work will eventually be merged. * worktree — An isolated filesystem checkout of the workspace repository (located under `~/.cards/worktrees//`) where the agent executes its tasks and runs tests in isolation. * description — The human-authored objective of a card, stored as `CARD.md` in the card-repo. This file seeds the initial context for the agent. * CARD.meta.json — The metadata sidecar file at the root of the card-repo, storing status, gates, tags, repositoryId, parentBranch, environment, and relations. * plan — An agent-authored outline of the steps required to complete the card's objective, stored in the `plans/` directory of the card-repo (one or more `.md` files). * session — A single execution run of an agent action against a card (e.g., running the launch action). * stream — The live-updating log of agent activity, terminal outputs, and tool calls rendered in the card details webview. * action — A configured command (e.g., `interview`, `launch`, `chat`) that runs your agent harness with specific context. * merge gate — The safety checkpoint where you review the agent's worktree commits in the Attribution Tree and approve merging them into the workspace. *** ## State and configuration reference [#state-and-configuration-reference] ### Card status values [#card-status-values] Cards transition through a closed set of status values. You cannot add custom status values. | Status | Phase | Description | | :------------- | :----------- | :------------------------------------------------------------------------------------ | | `todo` | Planning | The card has been created and described, but no agent session has run. | | `active` | Execution | An agent session is currently running, or has run and left uncommitted changes. | | `needs_review` | Verification | The agent has completed its task and is waiting for you to approve the merge gate. | | `done` | Completion | The changes have been merged into the workspace and the worktree has been cleaned up. | | `archived` | Archive | The card is archived and hidden from the active list. | ### Contributor classes [#contributor-classes] Every comment, plan edit, or action in a card's history is attributed to a specific contributor class. | Class | Entity | Description | | :------- | :------------------ | :------------------------------------------------------------------ | | `user` | You (the developer) | Manually authored comments, description edits, and action triggers. | | `agent` | The coding agent | Automated plan updates, code edits, and tool execution logs. | | `system` | The Cards extension | Automated lifecycle events, worktree creations, and merge logs. | ### Default actions [#default-actions] These are the standard actions shipped with the extension. You can define custom actions in your `settings.config.ts` using the SDK. | Action | Purpose | | :---------- | :--------------------------------------------------------------------- | | `interview` | Refines the card description by asking clarifying questions. | | `launch` | Starts the agent harness in the isolated worktree to execute the plan. | | `chat` | Starts an open-ended conversation with the agent in the worktree. | ### Card gate fields [#card-gate-fields] Card gates are configured per-card and stored in `CARD.meta.json` at the root of the card-repo. All gates are advisory checkpoints that guide the workflow but do not hard-block status transitions. | Field | Type | Description | | :--------------------- | :-------- | :--------------------------------------------------------------------------- | | `planRequired` | `boolean` | If `true`, the agent must submit a plan for approval before writing code. | | `planApproved` | `boolean` | Set to `true` when you approve the agent's plan. | | `mergeRequestRequired` | `boolean` | If `true`, the agent must request a merge review before completing the card. | | `mergeApproved` | `boolean` | Set to `true` when you approve the code changes. |