small-scripts/specs/claude-profile.spec.md

claude-profile

Purpose

Launch Claude Code with a named configuration profile, an engagement mode, and a provider. The profile selects which ~/.claude-* config directory to use; the engagement mode bundles a driver model, subagent policy, async tolerance, and workflow stance; the provider determines the model ID, API endpoint, and credentials.

Usage

claude-profile [OPTIONS] [PROFILE] [-- CLAUDE_ARGS...]

Arguments

Argument	Default	Description
PROFILE	(interactive picker)	Name of a profile under ~/.claude-<PROFILE>/. Pass default to use ~/.claude/.
CLAUDE_ARGS	(none)	Arguments after -- are passed through to claude unchanged.

Options

Flag	Description
--mode <NAME>	Skip the mode picker and use the named mode (chat, quick, deep, hybrid, orch).
--provider <NAME>	Skip the provider picker and use the named provider (e.g. anthropic-sonnet, minimax-sonnet).
--preset <NAME>	Use a named preset from the active profile's presets.yaml. Sets profile, mode, provider, and any preset-defined defaults in one shot.
--project <NAME>	Pre-select a project (skips the project question for modes that ask it).
--dryrun, -n	Print all resolved values and the command that would be executed; do not launch claude, do not write active-mode.env or last-mode.
--help, -h	Show usage.

Mutual exclusion

• --preset is mutually exclusive with --mode, --provider, and --project — the preset defines all of those. Passing both is an error.
• A positional PROFILE combined with --preset is allowed only if the preset's profile field matches; mismatch is an error.

Behaviour

The script runs in four phases: profile selection, mode selection, provider selection, launch. Each phase has an interactive path (prompt the user) and a non-interactive path (CLI flag or config file).

Phase 1 — Profile selection

1. If --preset <name> is given, read the preset from the global presets file (see "File contracts" below) and use its profile field. Skip the rest of phase 1.
2. Else if PROFILE is given as a positional argument, use it directly.
3. Else (interactive): list profiles by scanning ~/.claude-* directories, display a numbered menu, prompt for selection. Default selection is default (~/.claude/).
4. Resolve the profile to a directory: default → ~/.claude/; otherwise ~/.claude-<NAME>/.
5. If the directory does not exist, error and exit 1.
6. Export CLAUDE_CONFIG_DIR=<resolved>.
7. Emit the WezTerm theme escape sequence for the profile (existing behaviour, unchanged).

Phase 2 — Mode selection

1. If --preset is given, use the preset's mode and any other fields (project, time horizon, async, autoloop). Skip the rest of phase 2.
2. Else if --mode <name> is given, use it and proceed to mode-specific questions (project, async, etc., depending on the mode).
3. Else (interactive): list available modes by scanning <repo>/data/claude-profile/modes/*.md, display a numbered menu with each mode's tag and the first sentence of its ## Purpose section. Default selection is the contents of $CLAUDE_CONFIG_DIR/last-mode (if present), else quick.
4. After the mode is chosen, ask only the questions relevant to that mode (see "Mode follow-up questions" below). Skip questions already answered by CLI flags.
5. Validate the chosen mode file exists at <repo>/data/claude-profile/modes/<name>.md. If not, error and exit 1.
6. Read the mode file's frontmatter to extract driver, tag, async_ok, autoloop, plan_mode_auto, spec_driven.

Phase 2.5 — Provider selection

1. If --preset is given, use the preset's provider field (if present) or derive the default from the mode's driver field. Skip the rest of phase 2.5.
2. Else if --provider <name> is given, use it.
3. Else (interactive): derive the default provider from the mode's driver field (see "Driver-to-provider defaults" below). List available providers from <repo>/data/claude-profile/providers/*.yaml, display a numbered menu, prompt for selection. Default is the driver-derived provider, so pressing Enter preserves existing Anthropic behaviour.
4. Validate the chosen provider file exists at <repo>/data/claude-profile/providers/<name>.yaml. If not, error and exit 1.
5. Read the provider file to extract model_id, base_url, api_key_env, api_key_file, and extra_env.

Phase 3 — Launch

1. Write the resolved values to $CLAUDE_CONFIG_DIR/active-mode.env (key=value, one per line, see "File contracts").
2. Write the chosen mode name to $CLAUDE_CONFIG_DIR/last-mode.
3. Read the mode file's prose body (everything after the frontmatter) and append it to the context that context-load produces. The mode body becomes part of --append-system-prompt.
4. Set CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 (existing behaviour).
5. If the provider has a base_url, export ANTHROPIC_BASE_URL=<value>.
6. If the provider has api_key_env and api_key_file, read the key from the file and export it as <api_key_env>=<value>. Error if the file is missing.
7. Export any extra_env entries from the provider file.
8. Execute claude --model "<provider.model_id>" --append-system-prompt "$context_plus_mode" "${CLAUDE_ARGS[@]}".
9. On exit, the existing WezTerm reset trap runs.

Driver-to-provider defaults

When no --provider is given, the default provider is derived from the mode's driver field:

Mode driver	Default provider
haiku	anthropic-haiku
sonnet	anthropic-sonnet
opus	anthropic-opus
opus-1m	anthropic-opus-1m

This preserves backwards-compatible behaviour: launching without --provider behaves exactly as before.

Mode follow-up questions

Each mode declares which questions are relevant. Asked in order; only those not already supplied via CLI flags are prompted for.

Question	Asked in modes	Default	Drives
Time horizon? (minutes / hours / overnight)	deep, hybrid, orch	hours	Recorded in active-mode.env; the model adapts ScheduleWakeup cadence
Async OK? (yes / no)	deep, hybrid	mode default (yes for both)	Overrides async_ok
Auto-loops? (yes / no, confirms /loop 2m /orchestrate)	orch	yes	Overrides autoloop

chat and quick ask no questions interactively.

Project selection is intentionally NOT asked by claude-profile. The existing CLAUDE.md session-start flow handles project selection once claude is running. claude-profile accepts --project <name> as a non-interactive override (for presets and scripted launches), which writes CLAUDE_PROJECT into active-mode.env. A future CLAUDE.md update will read that field and skip its own picker when set; until then, supplying --project will result in the CLAUDE.md picker still appearing — the user can confirm the same project. This is a documented v1 limitation.

File contracts

Mode files — <repo>/data/claude-profile/modes/<name>.md

YAML frontmatter (machine-readable) + markdown body (read by the driver model). Required frontmatter fields:

name: <short name, matches filename>
tag: <status-line tag, ≤8 chars>
driver: <haiku|sonnet|opus|opus-1m>
async_ok: <yes|no>
autoloop: <none|"/loop 2m /orchestrate"|other slash command>
plan_mode_auto: <yes|no>
spec_driven: <yes|no>
escalates_to: <none|opus>  # used by statusline to render →Opus arrow

The body must include sections (in order): ## Purpose, ## Driver constraint, ## Subagent policy, ## Reasoning posture, ## Async policy, ## Workflow stance, ## Auto-fire at session start, ## Status line format, ## Escalation triggers, ## Out of scope, ## On context wipe (/clear). ## Named workflows available is optional.

Provider files — <repo>/data/claude-profile/providers/<name>.yaml

Plain YAML (no frontmatter). Required field: model_id. All other fields are optional.

name: minimax-sonnet            # unique identifier, matches filename
display: MiniMax (Sonnet)       # shown in the interactive picker
model_id: claude-sonnet-4-20250514  # passed to claude --model
base_url: https://api.minimax.io/anthropic  # exported as ANTHROPIC_BASE_URL (omit for Anthropic)
api_key_env: ANTHROPIC_AUTH_TOKEN           # env var name for the API key (omit for Anthropic)
api_key_file: ~/.claude-secrets/minimax-auth-token  # file containing the raw token value
extra_env:
  CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: "1"
  DISABLE_PROMPT_CACHING: "1"
  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"

Anthropic providers need only name, display, and model_id — Claude Code handles Anthropic auth via its own config.

Adding a new provider = one new YAML file in providers/. No script changes required.

Active mode env — $CLAUDE_CONFIG_DIR/active-mode.env

Written on every launch, overwritten each time. Read by:

• The status-line script (to render the mode tag)
• CLAUDE.md session-start hook (to re-apply the mode after /clear)

CLAUDE_MODE=deep
CLAUDE_MODE_TAG=deep
CLAUDE_DRIVER=sonnet
CLAUDE_PROVIDER=anthropic-sonnet
CLAUDE_ESCALATES_TO=opus
CLAUDE_PROJECT=cluster-bootstrap
CLAUDE_TIME_HORIZON=hours
CLAUDE_ASYNC_OK=yes
CLAUDE_AUTOLOOP=none
CLAUDE_PLAN_MODE_AUTO=yes
CLAUDE_SPEC_DRIVEN=yes
CLAUDE_MODE_FILE=/home/paul/dev/claude/small-scripts/data/claude-profile/modes/deep.md

Last mode — $CLAUDE_CONFIG_DIR/last-mode

Single line: the mode name. Used as the default in the next interactive picker.

Last project per mode — $CLAUDE_CONFIG_DIR/last-mode-project-<mode>

Single line: the project name last used with this mode. Per-mode so switching modes doesn't lose the previous mode's project context.

Presets — $CLAUDE_CONFIG_DIR/presets.yaml

Per-profile, user-edited. Each preset is a named bundle of answers to the picker:

deep-cluster:
  profile: oreillyit
  mode: deep
  project: cluster-bootstrap
  time_horizon: hours
  async: yes

quick-skills:
  profile: oreillyit
  mode: quick
  project: custom-claude-skills

orch-overnight:
  profile: oreillyit
  mode: orch
  project: ai-image-gen
  time_horizon: overnight
  autoloop: yes

quick-minimax:
  profile: oreillyit
  mode: quick
  provider: minimax-sonnet
  project: small-scripts

The profile field is required. provider defaults to the driver-mapped Anthropic provider if omitted. See data/claude-profile/presets.yaml.example for a full example.

Status line integration

The status-line script (~/.claude/status/statusline.sh) reads $CLAUDE_CONFIG_DIR/active-mode.env when CLAUDE_CONFIG_DIR is set. It uses CLAUDE_DRIVER and CLAUDE_ESCALATES_TO to build the model bracket, and CLAUDE_MODE_TAG to prefix the topic:

[Sonnet→Opus] deep · cluster-bootstrap: M10 Gitea CI | 23% ctx

• escalates_to: opus → [Sonnet→Opus] (shows escalation path)
• escalates_to: none → [Sonnet] (no arrow)
• Mode tag is prepended to the topic with · separator

If active-mode.env is missing or CLAUDE_CONFIG_DIR is unset, the status line falls back to the full model display name from the session JSON with no mode tag.

Dryrun behaviour

When --dryrun (or -n) is passed, claude-profile resolves all values exactly as it would in a real run, then prints them and exits 0 — no claude invocation, no file writes.

$ claude-profile --dryrun --preset deep-cluster
[dryrun] Profile:         oreillyit (~/.claude-oreillyit)
[dryrun] Mode:            deep
[dryrun] Mode file:       ~/dev/claude/small-scripts/data/claude-profile/modes/deep.md
[dryrun] Driver:          sonnet
[dryrun] Provider:        anthropic-sonnet (Anthropic (Sonnet))
[dryrun] Model ID:        claude-sonnet-4-6
[dryrun] Project:         cluster-bootstrap
[dryrun] Time horizon:    hours
[dryrun] Async OK:        yes
[dryrun] Autoloop:        none
[dryrun] Would write:     ~/.claude-oreillyit/active-mode.env
[dryrun] Would write:     ~/.claude-oreillyit/last-mode
[dryrun] Would execute:   claude --model claude-sonnet-4-6 --append-system-prompt "<context+mode>"
[dryrun] Context length:  4823 chars (3104 from context-load + 1719 from mode body)
[dryrun] No changes made.

Dryrun with MiniMax provider:

$ claude-profile --dryrun oreillyit --mode quick --provider minimax-sonnet
[dryrun] Profile:         oreillyit (~/.claude-oreillyit)
[dryrun] Mode:            quick
[dryrun] Mode file:       ~/dev/claude/small-scripts/data/claude-profile/modes/quick.md
[dryrun] Driver:          sonnet
[dryrun] Provider:        minimax-sonnet (MiniMax (Sonnet))
[dryrun] Model ID:        claude-sonnet-4-20250514
[dryrun] Base URL:        https://api.minimax.io/anthropic
[dryrun] API key env:     ANTHROPIC_AUTH_TOKEN (from ~/.claude-secrets/minimax-auth-token)
[dryrun] Project:         <not set, will be picked by CLAUDE.md>
[dryrun] Time horizon:    <not asked in this mode>
[dryrun] Async OK:        no
[dryrun] Autoloop:        none
[dryrun] Would execute:   claude --model claude-sonnet-4-20250514 --append-system-prompt "<context+mode>"
[dryrun] No changes made.

In dryrun mode the interactive prompts are still shown, so the user can walk through the picker without committing.

Edge cases

Case	Handling
~/dev/claude/small-scripts/data/claude-profile/modes/ does not exist	Error: "Mode files directory not found at ." Exit 1.
Mode file referenced by --mode does not exist	Error: "Mode file not found: ." Exit 1.
Mode file has malformed frontmatter (missing required field)	Error naming the missing field and the file path. Exit 1.
data/claude-profile/providers/ does not exist	Error: "Providers directory not found at ." Exit 1.
Provider file referenced by --provider does not exist	Error: "Provider not found: (looked in <providers_dir>)." Exit 1.
Provider file exists but is missing model_id	Error: "Provider file is missing required field: model_id." Exit 1.
Provider has api_key_file but the file does not exist at launch	Error: "Provider API key file not found: ." Exit 1.
--provider not given	Default provider derived from mode's driver field; interactive picker shown with that as the default.
presets.yaml does not exist and --preset was given	Error: "Preset '' not found in any presets.yaml." Exit 1.
presets.yaml exists but the named preset is not in it	Error: "Preset '' not found in any presets.yaml." Exit 1.
Preset's profile field references a non-existent profile	Error. Exit 1.
--preset and --mode both given	Error: "mutually exclusive". Exit 1.
--preset and --provider both given	Error: "mutually exclusive". Exit 1.
Positional PROFILE and --preset profile field disagree	Error: "Profile mismatch: positional , preset specifies ." Exit 1.
last-mode file is missing or contains an unknown mode	Fall back to quick as the default.
Two parallel sessions launched against the same profile	Both write to the same active-mode.env — last writer wins. Documented limitation; not addressed in v1.
CLAUDE_CONFIG_DIR already set in the environment when claude-profile starts	Ignored; claude-profile sets it from the resolved profile, overriding whatever was inherited.
Mode file body is empty (frontmatter only)	Error: "Mode file has no body — nothing to load into the system prompt." Exit 1.

Examples

Interactive — full picker

$ claude-profile
Claude Code profiles:
  1) default (~/.claude)
  2) oreillyit (~/.claude-oreillyit)
Choose profile [1]: 2

Engagement modes:
  1) chat   — No project, just conversation
  2) quick  — One small focused job in a known project
  3) deep   — Hard design or debugging problem
  4) hybrid — Haiku driver, Opus on demand
  5) orch   — Decompose work and dispatch container agents
Choose mode [quick]: 3

Time horizon? [hours]: 
Async OK? [yes]: 

Launching: oreillyit / deep
[Claude Code starts; the existing CLAUDE.md project picker runs next]

Direct — preset

$ claude-profile --preset deep-cluster
Launching: oreillyit / deep / cluster-bootstrap (from preset deep-cluster)
[Claude Code starts]

Direct — profile + mode flag

$ claude-profile oreillyit --mode quick --project small-scripts
Launching: oreillyit / quick / anthropic-sonnet / small-scripts
[Claude Code starts]

Direct — MiniMax provider

$ claude-profile oreillyit --mode quick --provider minimax-sonnet
Launching: oreillyit / quick / minimax-sonnet
[Claude Code starts with ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN set]

Dryrun — verify a preset

$ claude-profile --dryrun --preset deep-cluster
[dryrun] ...

Pass-through to claude

$ claude-profile --mode quick --project small-scripts -- --resume
[passes --resume to claude]

Out of scope (for v1)

• Multi-session coordination (parallel claude-profile launches against the same profile)
• Mid-session mode or provider switching from inside Claude Code (handled by a separate switch mode skill; requires relaunching)
• Editing mode or provider files in place (they are read-only data; customisation happens via presets.yaml)
• Network/remote profiles (everything is local)
• SOPS-encrypted provider credentials at launch time (credentials are stored as plaintext in ~/.claude-secrets/; SOPS decryption is handled by the agent-runtimes container harness for headless agents)
• Pinning the model used by named custom subagents at the harness level (those are controlled by the subagent's own definition file; the Agent tool's per-call model parameter is unaffected)