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

Cards does not use a database or a proprietary cloud service. Instead, it relies on your local Git installation.

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/<card-id>/. 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

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

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/<repo-id>/cards/<card-id>/<slot>/.

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

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.