caretta Help

Configuration reference

caretta reads caretta.toml from repository root on each launch. Legacy dev.toml is still supported as fallback.

All fields are optional. Start with defaults and add only required overrides.

Frequently used top-level fields

project_name = "my-project" workflow_preset = "default" bootstrap_agent_files = true bootstrap_snapshot = false use_subscription = false

Agent selection and model defaults

Use --agent per invocation, or persist model preferences in config.

[agent_models] claude = "claude-opus-4-7" codex = "gpt-5-codex"

--model <id> and CARETTA_MODEL can override model choice for one run.

Skill path resolution

When [skills] entries are omitted, caretta resolves skill files in this order:

  1. .caretta/skills/.../SKILL.md (recommended override layout in downstream repos)

  2. assets/skills/.../SKILL.md (bundled source layout)

  3. Materialized bundled copies under OS app-data directory

If both .caretta/skills and assets/skills exist, .caretta/skills wins.

Telemetry opt-out

Disable telemetry with any of these methods:

  • DO_NOT_TRACK=1

  • CARETTA_NO_TELEMETRY=1

  • Config file:

[telemetry] enabled = false

Bot account setup for code review

code-review submits PR reviews through GitHub APIs and requires a bot identity that is separate from the PR author.

Recommended mode: GitHub App credentials:

  • DEV_BOT_APP_ID

  • DEV_BOT_INSTALLATION_ID

  • DEV_BOT_PRIVATE_KEY (path to PEM file)

Alternative mode: second-user PAT:

  • DEV_BOT_TOKEN or DEV_BOT_TOKEN_PATH

Non-secret values can be saved to caretta.toml. Secrets are persisted through OS credential storage, not plaintext config.

Workspace feature

Use --workspace <name> to load context overrides from .caretta/workspaces/<name>/.

  • --workspace none disables workspace selection explicitly.

  • When omitted and workspaces exist, caretta can prompt interactively.

  • Commit only non-secret defaults to VCS.

  • Keep API keys/tokens in environment variables or keychain storage.

  • Prefer explicit workflow_preset in shared repositories.

Last modified: 02 July 2026
Desktop and web UI Architecture