Configuration

Overview

Caret is configured via caret.config.json in your project root. This file controls which detectors are active, their thresholds, notification channels, and intervention behavior.

Create a default config with:

caret init

Config file location

Caret looks for config in this order:

1. ./caret.config.json (project root)
2. ~/.config/caret/config.json (user-level)
3. Built-in defaults

Project-level config takes precedence over user-level config.

Full schema

{
  "version": 1,
  "project": "my-app",
  "detectors": {
    "scope_drift": {
      "enabled": true,
      "threshold": 2.0,
      "intervention": "alert"
    },
    "retry_loops": {
      "enabled": true,
      "max_retries": 3,
      "intervention": "alert"
    },
    "cost_runaway": {
      "enabled": true,
      "multiplier": 5,
      "intervention": "alert"
    },
    "destructive_actions": {
      "enabled": true,
      "intervention": "block",
      "allow_patterns": []
    },
    "approach_drift": {
      "enabled": true,
      "max_diff_lines": 500,
      "intervention": "alert"
    },
    "hallucination": {
      "enabled": true,
      "intervention": "alert"
    }
  },
  "notifications": {
    "desktop": true,
    "slack_webhook": null,
    "email": null
  },
  "daemon": {
    "port": 4199,
    "log_level": "info"
  },
  "llm_evaluation": {
    "enabled": false,
    "model": "claude-3-haiku",
    "max_cost_per_session": 0.10
  }
}

Detectors

Each detector can be configured independently:

Detector	Key config	Default intervention
Scope drift	threshold: 2.0	alert
Retry loops	max_retries: 3	alert
Cost runaway	multiplier: 5	alert
Destructive actions	allow_patterns: []	block
Approach drift	max_diff_lines: 500	alert
Hallucination	—	alert

Intervention options: "log", "alert", "context", "block"

Notifications

{
  "notifications": {
    "desktop": true,
    "slack_webhook": "https://hooks.slack.com/...",
    "email": "team@example.com"
  }
}

Desktop notifications use the system notification API. Slack webhooks send a formatted message with session details. Email notifications are sent via the Caret API.

Thresholds

Thresholds control when detectors fire. Lower thresholds mean stricter supervision:

• Strict: scope_drift.threshold: 1.0, retry_loops.max_retries: 2
• Default: scope_drift.threshold: 2.0, retry_loops.max_retries: 3
• Relaxed: scope_drift.threshold: 4.0, retry_loops.max_retries: 5

Advanced options

LLM evaluation: Enable Tier 3 detection for higher accuracy drift detection. This uses a lightweight LLM call and costs approximately $0.01 per evaluation.

{
  "llm_evaluation": {
    "enabled": true,
    "model": "claude-3-haiku",
    "max_cost_per_session": 0.10
  }
}

Daemon port: Change the local daemon port if 4199 conflicts with another service:

{
  "daemon": {
    "port": 4200
  }
}