Configuration, rules, and scopes

Cards configures its actions, renderers, and agent behavior across two main surfaces:

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.
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

Cards resolves and merges settings from three layers. Each layer merges into the previous:

Default: Shipped with the Cards extension.
User: Global settings at ~/.cards/settings.json (resolves via $CARDS_HOME or $XDG_CONFIG_HOME).
Project: Local settings at {repoPath}/.cards/settings.json.

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

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

These are the surfaces you are meant to edit. Installer-managed files are called out so you leave them alone.

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`

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

{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

{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

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

To compile a TypeScript configuration file into the required settings.json format, run:

cards-sdk build -c settings.config.ts -o .cards

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.