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:

```yaml
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.

```yaml
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:

```yaml
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 <path>." Exit 1. |
| Mode file referenced by `--mode` does not exist | Error: "Mode file not found: <path>." 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 <path>." Exit 1. |
| Provider file referenced by `--provider` does not exist | Error: "Provider not found: <name> (looked in <providers_dir>)." Exit 1. |
| Provider file exists but is missing `model_id` | Error: "Provider file <path> 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: <path>." 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 '<name>' not found in any presets.yaml." Exit 1. |
| `presets.yaml` exists but the named preset is not in it | Error: "Preset '<name>' 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 <X>, preset specifies <Y>." 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)