Skip to main content

Settings — view or change your per-developer preferences

One place for every per-developer setting. The store is ~/.bewith/config.json; all reads, writes, and the fallback resolution live in the deterministic helper scripts/bewith-config.sh (code-before-model — this skill never hand-edits JSON, it calls the helper).

The same settings are reachable three ways, all backed by the one config: this /settings command (and /lang, /role), the SwiftBar ⚙️ menu, and a local HTML page.

The settings​

KeyValuesNotes
languageen | heConversation language. Empty falls back to defaultLanguage.
defaultLanguageen | heThe fallback when language is unset. Default en.
roledev | productCapability-discovery filter (see /role).
docsPatha pathWhere the platform docs/clone live (optional; auto-detected when empty).
notify.enabledtrue | falseNotifications on/off. Stored in ~/.bewith/notify.env.
notify.bannerauto | always | offLocal banner behaviour.
notify.soundtrue | falsePlay a sound with the banner.
notify.soundNamea macOS sounde.g. Glass, Ping.
notify.soundFilea pathCustom audio file (overrides soundName).

Hard rule, always: the conversation may be in language, but all written artifacts (code, comments, commits, PRs, docs, memory, tickets) stay in English regardless. Example content inside an artifact may be in the relevant language.

Locating the helper​

Run the helper at whichever path resolves first:

CFG="${CLAUDE_PLUGIN_ROOT:-}/scripts/bewith-config.sh"
[ -f "$CFG" ] || CFG="scripts/bewith-config.sh"      # platform repo checkout
bash "$CFG" <subcommand> [args]

Argument forms​

FormEffect
/settingsPrint the table of every setting with its effective value and source, then how to change each. Runs bewith-config.sh list.
/settings set <key> <value>Validate and persist. Runs bewith-config.sh set <key> <value>. Rejects invalid values with a one-line error.
/settings openOpen the local HTML settings page (read-only view + the commands to change each). Runs bewith-config.sh open.

<key> is one of the rows above (language, defaultLanguage, role, docsPath, or notify.<sub>).

Steps Claude runs​

/settings (no args)​

  1. Resolve the helper path (above).
  2. Run bash "$CFG" list and show the output verbatim.
  3. Remind the developer of the shortcuts (/lang, /role) and that /settings open shows the HTML page.

/settings set <key> <value>​

  1. Resolve the helper path.
  2. Run bash "$CFG" set <key> <value>.
  3. Relay the result line. If it exited non-zero, relay the validation error and the valid values — do not retry with a guessed value.
  4. For language/role, note that the change takes effect for the next session (the SessionStart hooks read the config at session start); use /lang … --session or /role … --session for an immediate 4-hour override in this session.

/settings open​

  1. Resolve the helper path; run bash "$CFG" open.
  2. It writes and opens file://…/bewith-settings.html (macOS). Relay the path; on a non-macOS host, print the path so the developer can open it.

How the settings are consumed​

  • Conversation language — the conversation-language.sh SessionStart hook resolves language (via this same helper) and injects the directive to converse in it (artifacts stay English).
  • Role — the capability-awareness.sh SessionStart hook reads config.json .role (session override → config → user_role.md fallback → dev).
  • Notify — notify-attention.sh sources ~/.bewith/notify.env, which the helper writes when you set notify.*.

Resolution is delegated to the helper so there is exactly one implementation of the fallback chain (session override → config → default). Keep this doc and the helper in sync; the helper is the spec for behaviour.

Migration (existing settings keep working)​

config.json is the new source of truth. On first creation the helper migrates the legacy role from user_role.md. During the transition the helper keeps the legacy files in sync — set role write-throughs to user_role.md, and notify.* writes to notify.env — so hooks that still read the old files behave correctly.

Cross-references​