Getting started
This guide gets you from a fresh machine to your first successful caretta run.
Prerequisites
Before installing caretta, ensure you have:
ghauthenticated (gh auth login).At least one supported agent CLI available on
PATH.Git configured for repository operations.
Supported agent names for --agent include:
claudeclinecodexcopilotcursorgeminijuniexai
Install from the release script
The installer auto-detects OS/architecture and installs to ~/.local/bin by default.
To change the destination path:
Verify installation
Run your first command
Launch the desktop app:
Run a workflow from terminal:
Preview available presets:
First configuration checkpoint
Create a minimal caretta.toml in your repository root only if you need to override defaults. For many projects, no config file is required.
Example:
For full options and bot setup details, see Configuration reference.
Common first-run issues
gh is not authenticated
Run:
Agent binary is missing
Install and authenticate your selected agent CLI, then re-run with --agent <name>.
Need non-destructive preview
Use:
to inspect planned behavior without performing supported side effects.