Skip to content

Environment variables

Audience: anyone changing caret's settings from the shell or from the launchd agent or systemd unit that runs caret.

A variable with a config file key overrides that key, so precedence is env var > config file > default. caret ignores an invalid value for one of those variables, such as one out of bounds, and uses the config file's value instead. It logs a warning when it starts. A blank value counts as unset.

The installed service doesn't see your shell

The installed background service runs with the environment caret install captured when you chose Keep it running: HOME, CLAUDE_CONFIG_DIR, XDG_STATE_HOME, XDG_CONFIG_HOME, XDG_CACHE_HOME, XDG_DATA_HOME, CARET_CONFIG_FILE, CARET_PORT, and CARET_AGENT, plus CARET_SUPERVISED=1. A later export reaches each review and caret serve, but not the installed service. To change one there, export it and re-run caret install from that shell, keeping caret running. CARET_HEARTBEAT_MS, CARET_LOG_MAX_SIZE, and CARET_LOG_KEEP never reach the installed service; set their config keys instead.

Env var Config key Default Purpose
CARET_PORT daemon.port 42718 The port the background service listens on.
CARET_TIMEOUT review.timeout_s 3600 How long, in seconds, caret waits for your decision before it turns the plan down.
CARET_IDLE_MS daemon.idle_ms 60000 How long (ms) an on-demand background service waits with no review open before it exits.
CARET_HEARTBEAT_MS daemon.heartbeat_ms 8000 How long (ms) a waiting review holds one request open before it asks again.
CARET_LOG_MAX_SIZE logging.max_size 5242880 Size in bytes at which caret archives a log.
CARET_LOG_KEEP logging.keep 10 Gzipped archives kept per log.
CARET_CONFIG_FILE — unset Path to the config file, in place of the usual one (see Which file caret reads).
XDG_STATE_HOME — ~/.local/state caret keeps its state under $XDG_STATE_HOME/caret/: logs, the plan formatter, and unresolved reviews, which come back after a restart for a week after their last change.
CARET_AGENT — claude Which agent host's adapter caret speaks: claude, opencode, pi, or codex (provisional). The OpenCode plugin and pi extension set it themselves.
CARET_SUPERVISED — unset The installed service's launchd agent or systemd unit sets it to 1. The background service then stays running with no review open, and rotates its own daemon-stderr.log.
CARET_RUMDL_BIN — unset Path to a rumdl binary for plan formatting, in place of caret's download. caret uses it only when it reports the pinned version, v0.3.4; otherwise caret downloads its own. For offline installs, or to reuse a system rumdl.
CARET_OPENCODE_BIN — unset Absolute path to the caret binary the OpenCode plugin runs, in place of the one in the @macintacos/caret package. Points an OpenCode install at a local build.
CARET_OPENCODE_NO_UPDATE_CHECK — unset Any value stops the OpenCode plugin's daily check for a newer caret, and the toast it shows.
CARET_PI_BIN — unset Absolute path to the caret binary pi's extension runs, in place of the one in the @macintacos/caret package. Points a pi install at a local build.