# Configuration reference See the [README](../README.md) for installation and shortcuts. ## Files `` is normally `~/.pi/agent`. BMS uses Pi's `getAgentDir()`, so it respects `PI_CODING_AGENT_DIR`. | File | Contents | | --- | --- | | `/models.json` | Pi model definitions | | `/models.bms.json` | BMS model overlay | | `/bms-settings.json` | Write mode, result placement, and provider filters | | `/bms-usage.json` | Selection counts and recency | | `/bms-model-metadata.json` | Effort capability hints and their source | | `/settings.json` | User defaults and per-model effort preferences | | `/.pi/settings.json` | Project defaults | ## Model write modes Choose the write mode through Ctrl+O → Options in `/bms`, then Ctrl+S to save. - Overlay mode, the default, leaves `models.json` unchanged and writes edits to `models.bms.json`. - Direct mode writes add, update, and delete operations to `models.json`. Pi does not load the overlay itself. BMS merges it over `models.json` by provider and model ID, then registers the merged providers through Pi's extension API. Overlay fields win for duplicate models. BMS automatically renames its old `models.local.json` overlay to `models.bms.json`. Deleting an inherited model in overlay mode writes a tombstone: ```json { "id": "model-id", "bmsDeleted": true } ``` Remove that entry from `models.bms.json` to restore the inherited model. Model files are re-read before writes and saved through a temporary file and rename. This does not provide a shared lock against other applications. Provider filters affect only `/bms`. They do not change Pi's `/model` picker or model definitions. Default-assignment menus ignore the filters and also include authenticated Pi registry models. ## Picker layout `bms-settings.json` accepts `resultPlacement: "below"` or `"above"`. Missing or invalid values use `"below"`, matching Pi command completion. In above mode the best match is the bottom row, immediately above search; arrow keys follow physical screen direction. Searchable assignment menus use the same preference. Forms retain their normal top-to-bottom field order. The search field is part of a temporary custom interaction in Pi's editor area. BMS does not replace the normal editor factory. Enter loads the selected model; Esc returns to the editor. Up to six results are shown at a time, with scrolling for the rest. ## Defaults and precedence Default settings are independent of the model write mode. | Setting | Native Pi settings field | | --- | --- | | Pi model | `defaultProvider`, `defaultModel` | | Global fallback effort, configured in BMS Defaults | `defaultThinkingLevel` | | Per-model preferred effort | `modelThinkingLevels["provider/model"]` | | Subagent fallback | `subagents.defaultModel`, `subagents.defaultThinking` | | Role override | `subagents.agentOverrides..model` and `.thinking` | The defaults menu starts in user scope. Project scope requires a trusted project. Pi defaults use the working directory's `.pi/settings.json`. Agent defaults use the project root resolved by `pi-subagents`, which may differ in nested repositories. The menu shows the paths. Project settings and provider-specific role overrides may take precedence. BMS shows override sources and warns when a saved Pi default would be shadowed. Saving a Pi default sets the selected model's `modelThinkingLevels` preference in the chosen scope without changing `defaultThinkingLevel` or other models' preferences. Automatic removes only the selected model's preference. Configure fallback effort in BMS Defaults. The scope selector chooses user or trusted-project settings. For agent roles: - **Inherit parent model** writes `model: "inherit"`. - **Remove model override** restores agent-definition and fallback rules. - **Automatic** or **Remove effort override** removes that scope's effort preference. It does not force parent effort inheritance. `pi-subagents` has no separate persistent setting for that. - **Off** is an explicit effort level, not inheritance. Changing the Pi default also switches the main session. Subagent assignments do not switch it or increment usage counts. Cancelled or failed model switches leave saved defaults unchanged. If Pi clamps an effort, BMS asks before saving the applied level. Run `/reload` after changing agent defaults or per-model effort preferences. Running children keep their existing configuration, and subagent model-scope policies still apply at launch. Resumed Pi sessions restore their recorded model and effort. Test startup defaults in a fresh session without CLI model or effort overrides. Settings writes preserve unrelated fields, reject malformed JSON, and use atomic rename. A `.bms-lock` file serializes BMS settings writers only. After a crash, remove a stale lock only after checking that no BMS writer is active. Updates across model definitions, settings, and capability metadata are not a multi-file transaction. ## Effort levels and metadata BMS uses explicit provider effort lists when supplied, then native Pi capability restrictions where available. Otherwise it offers Pi's standard levels and labels provider support as unverified: ```text off, minimal, low, medium, high, xhigh, max ``` The metadata adapter recognizes `supported_reasoning_efforts`, `supported_thinking_levels`, and `reasoning_efforts` containing Pi effort names. A generic reasoning flag or `supported_parameters: ["reasoning_effort"]` does not specify supported levels. Add/update lets you edit the available levels and choose an optional per-model preferred effort. Non-reasoning models offer only `off`; correct the reasoning flag first if the endpoint metadata is wrong. BMS makes no paid model probes. Capability hints guide menus. They do not change provider adapters or prove an endpoint honors a level. Pi may clamp effort or map it to a token budget. Provider errors remain visible rather than triggering a model fallback. BMS blocks capability edits that conflict with directly pinned defaults in the inspected user/project settings. Update those defaults first. This check does not audit every inherited agent definition or settings file elsewhere on disk. When adding or updating models, BMS tries these metadata sources in order: 1. `GET {baseUrl}/model/info` for LiteLLM proxies. 2. `GET {baseUrl}/models/{id}` for OpenAI-style and proxy-specific fields. 3. The public LiteLLM model cost map on GitHub. These requests are best-effort. Missing metadata falls back to name-based heuristics and editable defaults for context window, output limit, reasoning support, and input types. ## Optional pi-subagents integration [pi-subagents](https://github.com/nicobailon/pi-subagents) is a separate Pi extension. BMS configures its saved model and effort defaults; it does not install it or launch agents to discover roles. Discovery was originally tested with `0.79.0` and has now been checked against `0.82.1`. BMS supports both the older root entry point and the newer `bundle/index.js` package layout. Discovery still uses internal discovery/runtime modules because the public agents API does not expose role discovery. Future incompatible versions may need an adapter update. The package must be resolvable from BMS or `/npm/node_modules`. Discovery includes built-in, package, user, project, and runtime roles when supported by the installed API. Untrusted project agents and settings are excluded. External runner roles are shown read-only; configure their models through the runner's own settings. If discovery fails, the menu offers **Agent discovery details** with the error. Main Pi defaults remain usable. ## Usage ranking Only models loaded with Enter in `/bms` count toward ranking. BMS sorts by selection count, then recency, then alphabetically. Default assignments, `/model`, model cycling, and session restores do not count. BMS prunes statistics for models missing from the effective configuration when the picker opens. Ctrl+R clears all usage statistics. ### Usage display Ctrl+O → Options provides three independent settings. Press Ctrl+S to save. | Option | JSON key | Default | | --- | --- | --- | | Color-code usage | `colorCodeUsage` | `true` | | Show total selections | `showUsageCounts` | `false` | | Usage palette | `usagePalette` | `"icon"` | These keys live in `/bms-settings.json`. Existing settings files inherit the defaults. Disabling colors or hiding totals does not stop recording selections or change sorting. With totals off, the USES column is removed entirely. The Icon palette uses blue `#5BA7FF`, amber `#FFB13D`, and orange `#FF6B3D`. The Theme palette uses the active Pi theme's `thinkingLow`, `thinkingMedium`, and `thinkingHigh` roles. Theme hues and their distinctness depend on the theme. Usage colors stay visible on the keyboard-highlighted row; its background and chevron still follow Pi's selection theme. Icon colors are approximated on 256-color terminals. Color tiers use a dynamic logarithmic scale: ```text strength = log(1 + model selection count) / log(1 + highest selection count) ``` The maximum comes from all configured, enabled models before search filtering. Zero selections stay neutral. Positive strengths up to one-third use the low color, up to two-thirds use medium, and the rest use high. Equal counts get equal colors; if all counts are zero, everything stays neutral. A single used model gets the high color even after its first selection: colors express relative lifetime preference, not an absolute amount or recent activity. Colors can change as other models accumulate selections or providers are hidden. Searching does not rescale them.