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
Cards are stored under your home directory:
~/.cards/cards-repos/<card-id>/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
The path above is the default. You can store cards elsewhere with environment variables:
CARDS_HOME— overrides the base~/.cardsdirectory.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
A card's repository contains the following files and directories:
~/.cards/cards-repos/<card-id>/
├── CARD.md
├── CARD.meta.json
├── CARD.md.meta.json
├── commits/
│ └── <sha>
├── branches/
│ └── <branch-name>.json
├── plans/
│ └── initial.md
├── comments/
│ └── 01-user-prompt.md
├── attachments/
│ └── schema.sql
└── streams/
└── <streamType>/
├── 75e7a9b0-agent-run.jsonl
└── 75e7a9b0-agent-run.jsonl.meta.jsonFile 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/<sha>, 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/<branch-name>.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/)
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/<sha> 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/)
When an agent runs, its output is written to a JSON Lines (.jsonl) file under streams/<streamType>/. 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
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.
Pricing and plans
Two tiers: a free tier that needs no account, with a local 50-card bank that accrues +5 per week; and Pro at $30 per month for unlimited card creation, flat and not metered.
Actions and agent modes
An action is a named operation that carries a card's context into a configured harness; the default configuration registers four — launch, interview, chat, and captain.