Configuring Claude

A Claude session is a claude process. actor.sh sets a couple of defaults, interprets one key itself, and forwards everything else to the binary as flags. This guide covers all three.

What actor.sh sets and interprets

• permission-mode = auto is applied by default to every Claude session, so agents can act without prompting for each tool. Override it like any other key (below).
• use-subscription is interpreted by actor.sh, not forwarded. When true, actor.sh removes ANTHROPIC_API_KEY from the agent's environment so Claude uses your subscription login instead of an API key.
• The role prompt becomes Claude's --append-system-prompt, layering the session's identity on top of Claude's own system prompt. See Roles.

Forwarding flags to claude

Any other config key is forwarded to the claude binary as a CLI flag. A multi-character key model becomes --model; its value follows. So setting

defaults "claude" {
    config model "claude-sonnet-4-6"
}

launches Claude sessions with --model claude-sonnet-4-6. actor.sh keeps no allow-list: any flag your installed claude accepts can be set this way.

Three places to set config

Pick the scope that fits:

1. All Claude sessions — a defaults "claude" block in settings.kdl:

   defaults "claude" {
       use-subscription #true
       config permission-mode "auto"
   }
   

2. A class of session — a role's config block, so only sessions created with that role get it.

3. One session, one flag — forward a raw argument to the binary for a single session with --arg:

   actor new spike --arg --model --arg claude-opus-4-8
   

   And --use-subscription is a first-class flag on actor new.

Cancelling an inherited value

A more specific layer can switch off a key set by a broader one with the #null cancel marker — see Actor Settings. The full precedence order is documented there too.

For a compact table of the keys, see the Config reference.