Skip to main content

Three Core Flows

Two concepts to understand:

Task - A single job for Caret to complete ("add tests to utils.js"). You describe what you want, Caret plans how to do it, then executes the plan. Tasks run on instances.

Instance - An independent Caret workspace. Each instance runs one task at a time. Create multiple instances to run multiple tasks that work on different parts of your project in parallel.

1. Interactive mode: Plan first, then act​

Start here to see how Caret works. Interactive mode opens a chat session where you can review plans before execution.

caret

Caret opens an interactive session in your current directory. Type your task as a message. Caret enters Plan mode and proposes a step-by-step strategy.

Review or edit the plan in chat. When you're ready, switch to execution:

/act

Caret executes the approved steps—reading files, writing code, running commands. You maintain control throughout the process.

2. Headless single-shot: Complete a task without chat​

Use this for automation where you want a one-liner that just does the work.

caret instance new --default
caret task new -y "Generate unit tests for all Go files"

With the -y (YOLO) flag, Caret plans and executes autonomously without interactive chat. Perfect for CI, cron jobs, or scripts.

Examples:

# Create a complete feature
caret task new -y "Create a REST API for user authentication"

# Generate documentation
caret task new -y "Add JSDoc comments to all functions in src/"

# Refactor code
caret task new -y "Convert all var declarations to const/let"

Monitor your task with:

# View task status
caret task view

# Follow task progress in real-time
caret task view --follow

Press Ctrl+C to exit the view.

ℹ️Note

Run YOLO mode with care on a directory or a clean Git branch. You get speed in exchange for oversight, so be ready to revert if needed.

3. Multi-instance: Run parallel agents​

Multiple instances let you parallelize work on the same project without colliding contexts. Run frontend, backend, and infrastructure tasks simultaneously.

Create your first instance:

caret instance new

This returns an instance address you'll use to target tasks. Attach a task to this instance:

# Frontend work on first instance
caret task new -y "Build React components"

Create a second instance and set it as default in one command:

caret instance new --default

Now you can create tasks without specifying the address—they automatically use the default instance:

# Backend work on the new default instance
caret task new -y "Implement API endpoints"

List all running instances:

caret instances list

Stop all instances when done:

caret instances kill -a
💡Tip

Keep track of instance addresses returned by caret instance new. When scripting multiple agents, store these IDs and direct your tasks to the appropriate instance.

Choosing the right flow​

  • Interactive mode: Best for exploring new problems, learning how Caret works, or when you want to review plans before execution
  • Headless single-shot: Perfect for automation, CI/CD, and tasks where you trust Caret to execute without supervision
  • Multi-instance: Use when you need to parallelize work or maintain separate contexts for different parts of your project
💡Tip

For in-depth commands and flags, check out the CLI reference page for complete documentation on all available options.

Next steps​

CLI reference

Complete command documentation including configuration, instance management, and task commands.

Plan and Act

Deep dive into Plan and Act modes, including when to use each and how to switch between them.

YOLO mode

Understand how YOLO mode works and when to use full automation versus manual approval.

Task management

Learn how Caret tracks and manages tasks, including saving and restoring state from checkpoints.