Caushell Configuration

This document describes Caushell's configuration file location, configuration management commands, and currently supported user configuration fields.

Configuration file location

Caushell looks for the configuration file in this order:

1. $CAUSHELL_CONFIG_PATH
2. $XDG_CONFIG_HOME/caushell/config.yaml
3. ~/.config/caushell/config.yaml

If $CAUSHELL_CONFIG_PATH is set, it must be an absolute path.

Show the current configuration file path:

caushell config path

Initialize, show, and validate

Initialize a new configuration file:

caushell config init

This creates the default configuration file in the configuration directory. If the file already exists, the command returns an error and does not overwrite it.

Show the current configuration file content:

caushell config show

This command outputs JSON containing:

• the resolved configuration path
• whether the configuration file exists
• the original configuration content from the file

Validate whether the configuration is usable:

caushell config validate

If the configuration file does not exist, validate still succeeds because Caushell uses built-in defaults.

Current configuration fields

Field	Values	Default	Purpose
failure_action	allow / need_approval / deny	need_approval	Fallback behavior when Caushell cannot complete analysis
codex.need_approval_mode	block / observe	block	How Codex handles NeedApproval decisions

failure_action

This field defines how Caushell handles a shell action when analysis cannot be completed.

• allow: allow the action when analysis fails
• need_approval: require confirmation when analysis fails
• deny: block the action when analysis fails

Show the current value:

caushell config get failure_action

Change it:

caushell config set failure_action need_approval

codex.need_approval_mode

This field only affects the Codex integration.

Codex hooks currently cannot request user confirmation directly. They can only return allow or reject, so Caushell maps NeedApproval to one of two modes:

• block: block execution when the decision is NeedApproval
• observe: allow Codex to continue while preserving Caushell's decision and reason record

Show the current value:

caushell config get codex.need_approval_mode

Change it:

caushell config set codex.need_approval_mode observe

Deny decisions are always blocked and are not affected by this setting.

Minimal example

This is a minimal configuration:

version: 1
failure_action: need_approval
codex:
  need_approval_mode: block

The default configuration uses need_approval and block.