skynet/small-scripts
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(claude-profile): add provider selection (model + endpoint + credentials)

Browse Source 
Introduces provider files (`data/claude-profile/providers/*.yaml`) that
bundle model ID, API base URL, API key source, and extra env vars. Phase 2.5
(provider selection) added between mode selection and launch, with a default
derived from the mode's driver field so existing Anthropic usage is unchanged.

Ships 5 providers: anthropic-haiku/sonnet/opus/opus-1m and minimax-sonnet.
MiniMax token decrypted from agent-runtimes SOPS env, stored at
~/.claude-secrets/minimax-auth-token. Adding new providers = one YAML file,
no script changes.

58 dryrun tests passing (up from 37).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Paul O'Reilly
2026-04-23 18:16:22 +12:00
parent 5a1b4b14bc
commit a11051e0a8
10 changed files with 362 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
specs/claude-profile.spec.md
View File

@@ -2,7 +2,7 @@
## Purpose
Launch Claude Code with a named configuration profile and an engagement mode. The profile selects which `~/.claude-*` config directory to use; the engagement mode bundles a driver model, subagent policy, async tolerance, and workflow stance into a preset that the driver model adopts at session start.
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
@@ -22,19 +22,20 @@ claude-profile [OPTIONS] [PROFILE] [-- CLAUDE_ARGS...]
| Flag | Description |
|------|-------------|
| `--mode <NAME>` | Skip the mode picker and use the named mode (`chat`, `quick`, `deep`, `hybrid`, `orch`). |
| `--preset <NAME>` | Use a named preset from the active profile's `presets.yaml`. Sets profile, mode, and any preset-defined defaults in one shot. |
| `--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` and `--project` — the preset defines all of those. Passing both is an error.
- `--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 three phases: **profile selection**, **mode selection**, **launch**. Each phase has an interactive path (prompt the user) and a non-interactive path (CLI flag or config file).
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
@@ -55,28 +56,38 @@ The script runs in three phases: **profile selection**, **mode selection**, **la
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. Resolve the mode's `driver` frontmatter field through the **Driver mapping** table below to a concrete model ID.
6. Execute `claude --model "<resolved-model-id>" --append-system-prompt "$context_plus_mode" "${CLAUDE_ARGS[@]}"`.
7. On exit, the existing WezTerm reset trap runs.
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 mapping
### Driver-to-provider defaults
The `driver` field in mode frontmatter uses a logical name; the launcher maps it to the full Claude model ID before passing to `claude --model`. Full IDs are used (not aliases) to remove ambiguity about which model version is selected.
When no `--provider` is given, the default provider is derived from the mode's `driver` field:
| Frontmatter `driver` | `--model` argument |
| Mode `driver` | Default provider |
|---|---|
| `haiku` | `claude-haiku-4-5-20251001` |
| `sonnet` | `claude-sonnet-4-6` |
| `opus` | `claude-opus-4-6` |
| `opus-1m` | `claude-opus-4-6[1m]` |
| `haiku` | `anthropic-haiku` |
| `sonnet` | `anthropic-sonnet` |
| `opus` | `anthropic-opus` |
| `opus-1m` | `anthropic-opus-1m` |
If the frontmatter specifies an unknown driver, the launcher errors with the list of valid values and exits 1. The mapping table lives in the launcher script as a constant; updating it is the only change needed when new model versions are released.
This preserves backwards-compatible behaviour: launching without `--provider` behaves exactly as before.
### Mode follow-up questions
@@ -85,7 +96,6 @@ Each mode declares which questions are relevant. Asked in order; only those not
| 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 |
| **Driver override?** (force a specific Claude model) | quick, deep | mode default | Overrides the `driver` field; resolved through the Driver mapping table and passed to `claude --model` |
| **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` |
@@ -112,6 +122,27 @@ 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:
@@ -122,6 +153,7 @@ Written on every launch, overwritten each time. Read by:
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
@@ -163,9 +195,15 @@ orch-overnight:
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. Other fields default to the mode's defaults if omitted.
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
@@ -187,17 +225,39 @@ When `--dryrun` (or `-n`) is passed, claude-profile resolves all values exactly
```
$ claude-profile --dryrun --preset deep-cluster
[dryrun] Profile: oreillyit (~/.claude-oreillyit)
[dryrun] Mode: deep (Sonnet driver, Opus via named workflows)
[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 file)
[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.
```
@@ -207,13 +267,19 @@ In dryrun mode the interactive prompts are still shown, so the user can walk thr
| Case | Handling |
|---|---|
| `~/dev/claude/small-scripts/data/claude-profile/modes/` does not exist | Error: "Mode files directory not found at <path>. Reinstall claude-profile or check the repo location." Exit 1. |
| Mode file referenced by `--mode` does not exist | Error listing the available modes. Exit 1. |
| `~/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. |
| `presets.yaml` does not exist and `--preset` was given | Error: "No presets.yaml found at <path>." Exit 1. |
| `presets.yaml` exists but the named preset is not in it | Error listing available preset names. 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: --preset already specifies a mode." 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. |
@@ -255,10 +321,17 @@ Launching: oreillyit / deep / cluster-bootstrap (from preset deep-cluster)
**Direct — profile + mode flag**
```
$ claude-profile oreillyit --mode quick --project small-scripts
Launching: oreillyit / quick / 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
@@ -274,8 +347,8 @@ $ claude-profile --mode quick --project small-scripts -- --resume
## Out of scope (for v1)
- Multi-session coordination (parallel claude-profile launches against the same profile)
- Mid-session mode switching from inside Claude Code (handled by a separate `switch mode` skill, not claude-profile itself)
- Editing mode files in place (mode files are read-only data; customisation happens via `presets.yaml`)
- 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)
- Mid-session driver model swaps (the harness pins the model at launch via `--model`; switching mid-session requires relaunching)
- Pinning the model used by named custom subagents at the harness level (those are controlled by the subagent's own definition file under `subagents[name].model`; the Agent tool's per-call `model` parameter is unaffected and remains how mode prose instructs the driver to escalate)
- 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)