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

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/<repoId>/cards/<cardId>/<slot>, 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

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/<repoId>/cards/<cardId>/<slot> 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

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