claude-presets

v2.0.0

Published

21 days ago

Claude Code preset picker and installer

0High
0Medium
0Low

claudes

one command, everything you need to swap between claude code configs. model, effort, permission mode, mcp servers, system prompts, env vars — all in a named preset. config lives in a single yaml file. v2 is a TypeScript CLI for npx claude-presets; the legacy zsh installer remains available.

what the picker looks like out of the box:

  Choose Claude preset:

    1) standard  (s)  · Sonnet 4.6 · max effort · daily coding work
    2) quick     (q)  · Sonnet 4.6 · low effort · fast/cheap edits
    3) plan      (p)  · Opus 4.7 · max effort · plan mode · deep thinking
    4) research  (r)  · Opus 4.7 · max effort · direct · explore/review

  > _

four built-in presets. you pick from the menu or type a name/alias directly. that's the default experience.

after you add your own presets from the examples/ folder, it looks more like this — your custom ones slot in numbered after the built-ins:

  Choose Claude preset:

    1) plan      (p)  · Opus 4.7 · max effort · plan mode · auto-approved
    2) max       (m)  · Opus 4.7 · max effort · skip permissions · yolo
    3) standard  (s)  · Sonnet 4.6 · auto effort · skip permissions · daily
    4) quick     (q)  · Sonnet 4.6 · low effort · skip permissions · fast
    5) review    (rv) · Sonnet · low · read-only PR/code review          [+prompt]
    6) rmcp      (rm) · Opus · max · strict research MCP · grounded      [+mcp +prompt]
    7) wt             · Opus · max · -w --tmux · parallel agent          [fn]

  > [enter = standard] _

items 5–7 are custom presets the user copied from examples/. items marked [+prompt], [+mcp], [fn] have extras attached — more on that below. the [enter = standard] prompt and single-key selection come from the optional enhanced ux layer.

the pitch

settings.json holds one model, one effortLevel, one defaultMode. real work doesn't fit one baseline.

you want sonnet-fast for mechanical edits, opus-deep for architecture, plan mode when you're scoping a feature, a read-only tool subset for PR review, a completely different mcp server set for grounded research, and --bare when you're offline. you could paste 80-char flag strings on every launch. you'll stop doing that after two days.

claudes stores named presets in ~/.config/claudes/claudes.yaml. it shows a numbered picker when you forget names, resolves short aliases (s, q, p), and passes every extra arg through transparently.

install

v2 TypeScript installer. the npm package name is claude-presets:

npx claude-presets install

until that package is published, run the same installer from GitHub or a clone:

npx --yes github:yigitkonur/claudes install

git clone https://github.com/yigitkonur/claudes.git
cd claudes
npm install
npm run build
node dist/cli.js install

legacy installer:

curl -fsSL https://raw.githubusercontent.com/yigitkonur/claudes/main/install.sh | bash

or clone first if you want to inspect before running:

git clone https://github.com/yigitkonur/claudes.git
cd claudes && ./install.sh

the v2 installer is interactive — it'll ask you four things:

core install — installs the runtime, symlinks into ~/.zshrc.d/ or appends to .zshrc
commands + enhanced ux — choose shell commands (claude, claudes, ccp, claude-preset), then optional single-key picker, enter = default preset, claude1..9 shortcuts (see enhanced ux)
preset scheme — pick the recommended 4-slot scheme, keep built-in defaults, configure custom interactively, or skip
finishing up — writes config files and warms the runtime cache

re-running is safe. nothing gets overwritten without asking.

package name vs command names: claude-presets is the npx/npm package. during install you choose which shell commands should open the picker: claude, claudes, ccp, and/or claude-preset. selecting claude is intentional; it shadows the raw command only in your shell, while presets still launch the real Claude Code binary underneath.

the legacy curl installer keeps the older zsh flow: core files, enhanced ux/remap, presets, finish. use v2 for selectable command names.

quick tour

claudes                   # numbered picker — pick with enter
ccp                       # same, if selected during install
claude-preset             # same, if selected during install
claude                    # same, if selected; presets still launch the real claude binary
claudes standard          # launch directly by preset name
claudes s                 # same, via alias
claudes plan --resume     # preset + pass extra flags through to claude
claudes list              # show all presets with markers
claudes show research     # dry-run: print resolved flags without launching
claudes config            # interactive preset & ux manager
claudes config presets    # manage presets only
claudes config ux         # order, default preset, shell commands
claudes test              # run self-tests
claudes help              # full help

built-in presets

four presets ship with claudes. they're intentionally minimal — real customization goes in your ~/.config/claudes/claudes.yaml.

| preset | alias | model | effort | mode | when to use | |---|---|---|---|---|---| | standard | s | sonnet 4.6 | max | default | daily coding, general work | | quick | q | sonnet 4.6 | low | default | fast/cheap edits, trivial ops | | plan | p | opus 4.7 | max | plan | complex scoping, deep thinking | | research | r | opus 4.7 | max | default | code review, architecture, explore |

heads up on permission mode: the built-ins explicitly pass --permission-mode default. if you've set defaultMode: "plan" in ~/.claude/settings.json — common for power users — every launch would otherwise default to plan mode. the explicit flag overrides that. covered in full under cli flag precedence.

the six dimensions

a preset can have any combination of these. only flags is required.

1. `flags` — the flags (required)

a string of cli flags, or a fn: sentinel for function-form presets:

presets:
  mine:
    flags: "--model sonnet --effort high --permission-mode acceptEdits"

anything claude --help recognizes works here: --model, --effort, --permission-mode, --tools, --allowedTools, --disallowedTools, --dangerously-skip-permissions, --bare, --print, --max-budget-usd, etc.

2. `description` — picker label

one line, shows up in the picker and claudes list:

description: "Sonnet · high · my daily driver"

3. `alias` — shortcut key

single-char or short string → preset name:

alias: m

4. `env` — env vars

key/value pairs exported into the claude process only — nothing leaks back to your shell:

env:
  CLAUDE_CODE_MAX_OUTPUT_TOKENS: "32000"
  MAX_THINKING_TOKENS: "48000"

useful for token budget knobs, CLAUDE_ORCHESTRATOR=1, provider-specific vars, anything that's not a cli flag.

5. `mcp` — a scoped mcp server set

path to a .mcp.json-shaped file. claudes expands ~, checks the file exists, then passes --mcp-config <path>:

mcp: "~/.config/claudes/mcp/research-only.json"

combine with --strict-mcp-config in the flags to load only that file's servers (ignores global mcp config). useful when you want a preset that talks to exactly one mcp and nothing else.

6. `prompt` — system-prompt addendum

string appended via --append-system-prompt. cheapest way to scope behavior per-preset:

prompt: "You are in read-only review mode. Do not edit files."

custom presets — how to add your own

edit ~/.config/claudes/claudes.yaml. one file for everything — presets, picker order, default, and shell commands.

a minimum viable preset:

presets:
  mine:
    flags: "--model sonnet --effort high"
    description: "Sonnet · high · my daily driver"
    alias: m

a richer one with all the extras:

presets:
  rmcp:
    flags: "--model opus --effort max --strict-mcp-config"
    description: "Opus · max · strict research mcp"
    alias: rm
    mcp: "~/.config/claudes/mcp/research-only.json"
    prompt: "Cite every non-trivial claim from a scraped source. No fabrication."
    env:
      CLAUDE_CODE_MAX_OUTPUT_TOKENS: "32000"

to remove a built-in preset you don't want:

remove_builtins: [research]

to see what a preset resolves to without launching:

claudes show rmcp
# preset:       rmcp
# flags:        --model opus --effort max --strict-mcp-config
# mcp-config:   /Users/you/.config/claudes/mcp/research-only.json
# prompt:       Cite every non-trivial claim from a scraped source...
# env:          CLAUDE_CODE_MAX_OUTPUT_TOKENS=32000

interactive manager — instead of editing yaml by hand, run claudes config presets. it'll walk you through model/effort/mode, generate the flags, and write the entry for you.

verify everything works — claudes test runs the TypeScript self-tests for YAML parsing, preset resolution, ordering, and flag splitting.

example presets to steal

the examples/ folder has eight legacy .zsh recipes whose flags map directly to YAML presets. copy the name, flags, alias, prompt/env/mcp pieces into ~/.config/claudes/claudes.yaml under the presets: key — or run claudes config presets for the guided wizard.

| file | preset | what it does | |---|---|---| | review.zsh | review | sonnet low + read-only tools + no-edits prompt — pr walkthroughs | | cheap.zsh | cheap | sonnet low + --bare — single-file ops, fewer tokens | | ci.zsh | ci | --print --output-format stream-json --bare --max-budget-usd 1 — local scripts piping to jq | | research-mcp.zsh | rmcp | opus max + strict mcp + anti-fabrication prompt — grounded research | | offline.zsh | offline | --bare + no mcp + no web tools — airplane mode | | audit.zsh | audit | opus max + read-only tools + audit rubric prompt — security walks | | worktree.zsh | wt | fn: — spawns -w <name> --tmux for parallel agents | | pr.zsh | pr | fn: — resolves pr via gh, then --from-pr to resume |

plus examples/mcp/research-only.json — mcp config template for the YAML mcp: field.

function-form presets — the escape hatch

flag strings can't express everything. some presets need to resolve a pr number from gh, pick a worktree name, cd somewhere, or branch on an argument. for those, use the fn: form.

define a zsh function in your shell config, then point a YAML preset at it:

_claudes_preset_worktree() {
  local name="${1:-feat-$(date +%s)}"
  shift 2>/dev/null || true
  command claude -w "$name" --tmux --model opus --effort max "$@"
}

presets:
  wt:
    flags: "fn:_claudes_preset_worktree"
    description: "Opus · max · -w --tmux · parallel agent"

claudes wt feature-auth             # named worktree
claudes wt                          # auto-named feat-<timestamp>
claudes wt refactor-db "start by…"  # name + initial prompt

env still applies for fn: presets. mcp and prompt are ignored — the function owns those if it needs them.

enhanced ux — single-key picker

install the ux layer for a faster daily workflow. the installer asks about this in step 2, or install manually:

# already ran the installer — just answer Y when it asks about enhanced ux
# manual install:
npx claude-presets install

what it adds:

single-key selection — no Enter needed in the picker. press 1, 2, s, p and it launches immediately. much faster than typing the full name.

bare enter = default preset — configure which preset Enter selects (default: standard). the picker shows [enter = standard] as a reminder.

claude1 .. claude9 — jump straight to the nth preset from the cli:

claude1   # → 1st preset in your order
claude3   # → 3rd preset

command aliases — during install, choose any combination of claude, claudes, ccp, and claude-preset. choosing claude intentionally shadows the raw CLI in your shell so the picker opens first; when you launch a preset, the runtime still resolves and executes the real claude binary.

configure all of this interactively:

claudes config ux

or edit the ux: block in ~/.config/claudes/claudes.yaml directly:

ux:
  order: [plan, max, standard, quick]
  default: standard
  remap: warp  # warp | all | none
  commands: [claude, claudes, ccp, claude-preset]

hooks integration — auto-approve plans

if you use plan mode (claudes plan), you probably want plan approvals auto-approved so you don't have to click through the permission prompt every time. the hooks-claude-code repo ships a hook for exactly this.

install it:

bash <(curl -fsSL https://raw.githubusercontent.com/yigitkonur/hooks-claude-code/main/install.sh)

the installer asks you to pick a mode:

classic — auto-approve plan exits instantly and silently. simple.
orchestrator — auto-approve + inject a directive that makes claude execute plans step-by-step with strict completion criteria. better for complex multi-step tasks.

what happens under the hood: the hook wires into the ExitPlanMode PermissionRequest event in ~/.claude/settings.json. whenever claude asks "ok to proceed?", the hook fires and approves automatically.

once installed, a preset like:

presets:
  plan:
    flags: "--model opus --effort max --permission-mode plan"

becomes a fully automated deep-thinking loop — plan → auto-approve → execute, no manual intervention.

uninstall:

bash <(curl -fsSL https://raw.githubusercontent.com/yigitkonur/hooks-claude-code/main/uninstall.sh)

cli flag precedence

the load-bearing mechanic behind all of this. claude code resolves config in this order, highest wins:

cli flags (--model, --effort, --permission-mode, etc.) ← what claudes uses
env vars (ANTHROPIC_MODEL, CLAUDE_CODE_MAX_OUTPUT_TOKENS, etc.)
~/.claude/settings.json
managed/enterprise settings

because cli flags win, a preset overrides your settings.json baseline without touching any files. two sessions with different presets don't interfere.

anti-pattern to avoid: don't mutate settings.json at runtime to swap models mid-session. it doesn't work reliably — claude code doesn't consistently re-read it between turns. pick the right config at launch via claudes. there's also a known bug with the opusplan model alias where it runs sonnet in both phases — another reason to use explicit preset selection.

reference

preset fields

| field | type | purpose | |---|---|---| | flags | string | cli flags, or fn:<zsh_func> | | description | string | one-line label for picker | | alias | string | shortcut that resolves to this preset | | env | map | env vars exported at launch | | mcp | string | path to mcp json, injected as --mcp-config | | prompt | string | appended via --append-system-prompt |

commands

| command | behavior | |---|---| | claudes | interactive picker | | claudes <preset> [args...] | launch preset, extra args pass through | | claudes list / ls | list all presets with markers | | claudes show <preset> | dry-run: print resolved config | | claudes config | interactive preset & ux manager | | claudes config presets | manage presets (add/edit/remove) | | claudes config ux | set order, default preset, shell commands | | claudes install | install shell integration from the npm package | | claudes test | run TypeScript self-tests | | claudes help | full help text |

markers (picker + list)

| marker | meaning | |---|---| | [fn] | function-form preset | | [+env] | preset exports env vars | | [+mcp] | preset loads a --mcp-config | | [+prompt] | preset appends a system prompt |

files

| path | purpose | |---|---| | ~/.local/share/claudes/v2/dist/cli.js | TypeScript runtime compiled to Node.js | | ~/.local/share/claudes/v2/claudes.zsh | zsh shim that calls the Node runtime | | ~/.local/share/claudes/v2/ux.zsh | optional ux layer for claude1..9 | | ~/.config/claudes/claudes.yaml | your config — presets + ux settings | | ~/.config/claudes/.claudes-cache.json | generated cache | | ~/.config/claudes/mcp/ | convention: mcp json files for mcp: preset key | | ~/.zshrc.d/90-claudes.zsh | symlink → v2 shim (if ~/.zshrc.d/ exists) | | ~/.zshrc.d/91-claudes-ux.zsh | symlink → v2 ux shim (if ux layer installed) |

requirements

node 20+ — runs the v2 TypeScript CLI after compilation
zsh 5.0+ — shell integration and legacy fn: preset compatibility
claude code cli 2.1+ — npm install -g @anthropic-ai/claude-code
macOS or Linux

python3 is only needed by the legacy shell installer/runtime.

uninstall

rm -rf ~/.local/share/claudes
rm -f ~/.zshrc.d/90-claudes.zsh ~/.zshrc.d/91-claudes-ux.zsh
# if no ~/.zshrc.d/, remove the source lines from ~/.zshrc starting with:
#   # claudes — https://github.com/yigitkonur/claudes

~/.config/claudes/ is left in place so you don't lose your presets.

contributing

prs welcome for:

more recipes under examples/
bash port as a sibling file
optional fzf picker enhancement
docs improvements

see CONTRIBUTING.md and AGENTS.md before touching core.

claude code — the cli this wraps
hooks-claude-code — auto-approve plan exits and other hooks
awesome-claude-code — curated claude code tooling

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme