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

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.

Default actions

Cards registers four default actions:

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)

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)

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)

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

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

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

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

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