Permissions and safety
Security is divided between Cards (which governs metadata, plans, and merge gates) and the agent harness (which governs system access, file modifications, and network requests).
Cards does not sandbox the agent's execution. It relies on a three-tier validation system for metadata and Gated workflows.
The Three Tiers of Cards Validation
Cards protects the integrity of the card repository using three enforcement tiers:
1. API Validation
The Cards server validates the card repository's schema and integrity whenever metadata is written to CARD.meta.json.
2. Git-Hook Validation
A pre-commit hook runs locally before each commit is finalized. It is fail-closed; if any validation fails, the commit is rejected. The hook enforces the following rules:
- Metadata Integrity: Rejects the commit if
CARD.meta.jsonis malformed. - Mermaid Syntax: If a committed
.mdfile contains a Mermaid diagram, Cards validates it and rejects the commit if the diagram is unreachable or its syntax is invalid. - Merge Gate Reset: If the commit adds new files to the
commits/directory, the hook automatically resetsgates.mergeApprovedtofalseinCARD.meta.json. - Plan Gate Reset: If a new plan file is added under the
plans/directory, the hook automatically resetsgates.planApprovedtofalseinCARD.meta.json.
3. Skill Convention
Convention-level rules govern how agents interact with the project workspace, such as using temporary branches or sharing worktrees.
Harness-Level Permissions
The agent harness (e.g., Claude Code or Codex) is responsible for sandboxing and executing commands.
Because the harness runs as a subprocess under your local user account, it has the same system access as your shell. You must configure file-system boundaries, network allowlists, and command-approval prompts directly in the harness configuration (for Claude Code, in .claude/settings.json or ~/.claude/settings.json).
Limitations
Caution: Bypassing the Git hooks (e.g., via
git commit --no-verifyor settingCARDS_SKIP_HOOK=1) will allow unvalidated metadata or invalid Mermaid syntax into the repository. This can break the Cards UI and cause the server to reject subsequent sync operations.
Configuration, rules, and scopes
How Cards loads, merges, and overrides configuration layers, and the complete set of settings you can edit across project and user boundaries.
Privacy and data
Review our local-first privacy architecture: how card data stays on your local disk, how licensing is managed, and how token traffic flows directly to your model provider.