@@ -147,7 +147,7 @@ Implementation details:
147147
148148 ### Configured MCP tools
149149
150-When `settings.json` includes `mcp.servers`, mini-coder keeps those Streamable HTTP MCP endpoints in runtime state, connects enabled ones when needed, and imports their advertised tools.
150+When the effective startup settings include `mcp.servers`, mini-coder keeps those Streamable HTTP MCP endpoints in runtime state, connects enabled ones when needed, and imports their advertised tools.
151151
152152 Implementation details:
153153
@@ -781,21 +781,21 @@ add tests for undo_
781781
782782 ### Commands
783783
784-| Command | Description …
785-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- …
786-| `/model` | Interactive model selector. The list includes built-in models plus any custom OpenAI-compatible models discovered from `settings.json`. Switching models mid-session is allowed — pi-ai's context is model-agnostic. The `readImage` tool is re-evaluated (added/removed based on the new model's capabilities). The status bar updates immediately, and the selected model is persisted immediately as the user's global default. The session record's `model` field is not updated (it reflects …
787-| `/session` | Interactive session manager (list, resume). Sessions scoped to CWD. …
788-| `/new` | Start a new session. Clears conversation, resets cost/token counters. …
789-| `/fork` | Fork the current conversation into a new session. Copies the full message history, continues from here independently, and appends a UI-only `Forked session.` notice in the new session. The original session is preserved. …
790-| `/undo` | Remove the last conversational turn from history: the most recent user message and all assistant/tool messages that followed in that turn. Persisted UI messages are not part of turns and are not removed by `/undo`. Context-only — does not revert filesystem changes. …
791-| `/reasoning` | Toggle display of model thinking/reasoning content in the log. The new on/off state is persisted immediately and restored on launch. When no setting exists yet, reasoning defaults to shown. …
792-| `/verbose` | Toggle [verbose tool rendering](#verbose-tool-rendering) for shell previews/results, read previews/results, grep previews/results, edit previews, and edit errors. Successful edit results stay compact regardless of this setting. Todo tool results always render in full. …
793-| `/mcp` | Interactive MCP server selector. Lists configured MCP servers with their current on/off state. Selecting a server toggles it for future turns, persists the new on/off state immediately, and appends a UI-only notice with the exact tool delta, for example `Disabled MCP server "docs" (-3 tools).` Turning a server on reconnects it on demand; turning it off disconnects it. `/mcp` still does not add, remove, or reload server definitions. …
794-| `/todo` | Append the current session todo list to the conversation pane as a UI-only checklist block. The message is persisted with the session, excluded from model context, and does not create a session by itself when no session exists yet. …
795-| `/login` | Interactive OAuth login. Shows a selector with available OAuth providers and their login status (logged in / not logged in). Selecting a provider starts the browser-based OAuth flow. Uses pi-ai's OAuth registry. Credentials are persisted to the app data directory and used for provider discovery on subsequent launches. …
796-| `/logout` | Interactive OAuth logout. Shows a selector with logged-in OAuth providers. Selecting one clears its saved credentials. …
797-| `/effort` | Interactive effort selector. Shows the four reasoning levels (`low`, `medium`, `high`, `xhigh`) with the current level highlighted. Updates the status bar immediately, and the selected effort is persisted immediately as the user's global default. The session record's `effort` field is not updated (it reflects the initial choice, like `/model`). …
798-| `/help` | List available commands, including the current on/off state of `/reasoning`, `/verbose`, and configured MCP servers, plus loaded AGENTS.md files and discovered skills. …
784+| Command | Description …
785+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- …
786+| `/model` | Interactive model selector. The list includes built-in models plus any custom OpenAI-compatible models discovered from the loaded settings. Switching models mid-session is allowed — pi-ai's context is model-agnostic. The `readImage` tool is re-evaluated (added/removed based on the new model's capabilities). The status bar updates immediately, and the selected model is persisted immediately as the user's global default. The session record's `model` field is not updated (it refl …
787+| `/session` | Interactive session manager (list, resume). Sessions scoped to CWD. …
788+| `/new` | Start a new session. Clears conversation, resets cost/token counters. …
789+| `/fork` | Fork the current conversation into a new session. Copies the full message history, continues from here independently, and appends a UI-only `Forked session.` notice in the new session. The original session is preserved. …
790+| `/undo` | Remove the last conversational turn from history: the most recent user message and all assistant/tool messages that followed in that turn. Persisted UI messages are not part of turns and are not removed by `/undo`. Context-only — does not revert filesystem changes. …
791+| `/reasoning` | Toggle display of model thinking/reasoning content in the log. The new on/off state is persisted immediately and restored on launch. When no setting exists yet, reasoning defaults to shown. …
792+| `/verbose` | Toggle [verbose tool rendering](#verbose-tool-rendering) for shell previews/results, read previews/results, grep previews/results, edit previews, and edit errors. Successful edit results stay compact regardless of this setting. Todo tool results always render in full. …
793+| `/mcp` | Interactive MCP server selector. Lists configured MCP servers with their current on/off state. Selecting a server toggles it for future turns and appends a UI-only notice with the exact tool delta, for example `Disabled MCP server "docs" (-3 tools).` Turning a server on reconnects it on demand; turning it off disconnects it. For globally configured servers, the new on/off state is persisted immediately. Repo-local server definitions loaded from `<git-root>/.mini-coder/settings.j …
794+| `/todo` | Append the current session todo list to the conversation pane as a UI-only checklist block. The message is persisted with the session, excluded from model context, and does not create a session by itself when no session exists yet. …
795+| `/login` | Interactive OAuth login. Shows a selector with available OAuth providers and their login status (logged in / not logged in). Selecting a provider starts the browser-based OAuth flow. Uses pi-ai's OAuth registry. Credentials are persisted to the app data directory and used for provider discovery on subsequent launches. …
796+| `/logout` | Interactive OAuth logout. Shows a selector with logged-in OAuth providers. Selecting one clears its saved credentials. …
797+| `/effort` | Interactive effort selector. Shows the four reasoning levels (`low`, `medium`, `high`, `xhigh`) with the current level highlighted. Updates the status bar immediately, and the selected effort is persisted immediately as the user's global default. The session record's `effort` field is not updated (it reflects the initial choice, like `/model`). …
798+| `/help` | List available commands, including the current on/off state of `/reasoning`, `/verbose`, and configured MCP servers, plus loaded AGENTS.md files and discovered skills. …
799799
800800 Commands are discoverable when the input starts with `/`: pressing `Tab` in that state switches from file-path autocomplete to interactive command select/filter.
801801
@@ -857,38 +857,46 @@ This means headless one-shot runs appear in normal `/session` history for that w
857857 On launch, mini-coder:
858858
859859 1. Discovers built-in providers (env vars, OAuth tokens).
860-2. Loads user settings from `~/.config/mini-coder/settings.json`.
861-3. Discovers user-configured custom OpenAI-compatible providers from `settings.json`.
860+2. Loads global user settings from `~/.config/mini-coder/settings.json`.
861+3. If the current working directory is inside a git repo, loads `<git-root>/.mini-coder/settings.json` as a repo-local read-only overlay.
862+ - Missing or invalid content in either settings file is treated as "no settings from that file" rather than a fatal startup error.
863+ - Repo-local values win on collisions.
864+ - `customProviders` is merged by provider `name` instead of replacing the whole array. Same-name repo-local entries override global ones.
865+ - `mcp.servers` is merged by server `name` instead of replacing the whole array. Same-name repo-local entries override global ones.
866+4. Discovers user-configured custom OpenAI-compatible providers from the effective settings.
862867 - Each entry is queried at `${baseUrl}/models`.
863868 - Each returned model is added to the launch's available model list as `provider/model`, where `provider` is the configured custom provider name.
864- - Invalid entries are dropped while loading settings. Duplicate custom provider names keep the first entry.
869+ - Invalid entries are dropped while loading settings. Duplicate custom provider names within the same settings source keep the first entry.
865870 - If an endpoint is unreachable, returns a non-2xx response, or the custom provider name conflicts with an already-available built-in provider, startup continues and a warning is added to the UI log.
866-4. Loads user-configured MCP servers from `settings.json`.
871+5. Loads user-configured MCP servers from the effective settings.
867872 - Each entry must provide a `name` and Streamable HTTP endpoint `url`. It also stores an `enabled` flag; older entries that omit it default to enabled.
868- - Invalid entries are dropped while loading settings. Duplicate MCP server names keep the first entry.
873+ - Invalid entries are dropped while loading settings. Duplicate MCP server names within the same settings source keep the first entry.
869874 - Startup connects only servers whose `enabled` flag is on. Imported MCP tool names are exposed to the model as `<serverName>__<toolName>`.
870875 - Disabled servers stay listed in runtime state so `/mcp` can reconnect them on demand later in the same app run.
876+ - Servers whose effective definition comes from the repo-local overlay stay read-only. `/mcp` can toggle them during the current app run, but only globally configured servers persist new enabled states back to `~/.config/mini-coder/settings.json`.
871877 - If an enabled server URL is invalid, the endpoint is unreachable, or the server exposes no tools, startup continues and a warning is added to the UI log.
872-5. Selects the startup model, effort, reasoning visibility, and verbose mode from those settings when available.
878+6. Selects the startup model, effort, reasoning visibility, and verbose mode from those effective settings when available.
873879 - `defaultModel`: if the saved provider/model is currently available, use it; otherwise fall back to the first available model for this launch.
874880 - `defaultEffort`: if valid, use it; otherwise fall back to `medium`.
875881 - `showReasoning`: if present, use it; otherwise fall back to `true`.
876882 - `verbose`: if present, use it; otherwise fall back to `false`.
877-6. Loads AGENTS.md files and skills.
878-7. Selects the launch mode:
883+7. Loads AGENTS.md files and skills.
884+8. Selects the launch mode:
879885 - Interactive TUI when `stdin` and `stdout` are both TTYs and `-p` was not provided.
880886 - Headless one-shot mode otherwise.
881-8. In interactive mode, renders the UI with an empty conversation log, a minimal `mini-coder` empty-state banner (showing the packaged version when available, otherwise a simple dev label), and the status bar populated.
882-9. Starts a new session only when a prompt is actually submitted (no 0-message sessions in the DB).
887+9. In interactive mode, renders the UI with an empty conversation log, a minimal `mini-coder` empty-state banner (showing the packaged version when available, otherwise a simple dev label), and the status bar populated.
888+10. Starts a new session only when a prompt is actually submitted (no 0-message sessions in the DB).
883889
884890 The empty-state banner is only shown while the conversation log has no messages. In headless mode, stdout is reserved for the final assistant text response by default, with any lightweight non-JSON activity snippets going to stderr, or NDJSON event output when `--json` is used.
885891
886892 ## User settings persistence
887893
888-mini-coder persists global user defaults in `~/.config/mini-coder/settings.json`.
894+mini-coder persists global user defaults in `~/.config/mini-coder/settings.json`. When launched inside a git repo, it also reads `<git-root>/.mini-coder/settings.json` as a repo-local read-only overlay for that app run.
889895
890896 ### Stored settings
891897
898+The global settings file and the optional repo-local overlay use the same JSON shape.
899+
892900 ```json
893901 {
894902 "defaultModel": "anthropic/claude-sonnet-4",
@@ -914,20 +922,24 @@ mini-coder persists global user defaults in `~/.config/mini-coder/settings.json`
914922
915923 ### Semantics
916924
917-- Settings are **global to the user**, not scoped per project, repository, or session.
918-- `/model`, `/effort`, `/reasoning`, and `/verbose` persist their new values immediately when changed.
925+- Global defaults are persisted in `~/.config/mini-coder/settings.json`.
926+- When launched inside a git repo, mini-coder also loads `<git-root>/.mini-coder/settings.json` as a repo-local read-only overlay for that app run.
927+- The effective settings are built by loading the global file first and then overlaying the repo-local file. Repo-local values win on collisions.
928+- `customProviders` is merged by provider `name` instead of replacing the whole array. Same-name repo-local entries override global ones.
929+- `mcp.servers` is merged by server `name` instead of replacing the whole array. Same-name repo-local entries override global ones.
930+- `/model`, `/effort`, `/reasoning`, and `/verbose` persist their new values immediately to the global settings file only.
919931 - If `defaultModel` is saved but unavailable at startup (for example, missing credentials), mini-coder keeps the saved preference unchanged and uses a runtime fallback model for that launch.
920-- Invalid or missing settings file content is treated as "no saved settings" rather than a fatal startup error.
932+- Invalid or missing content in either settings file is treated as "no settings from that file" rather than a fatal startup error.
921933 - `/new`, `/fork`, and `/session` do not modify global settings.
922934 - Session records remain historical: their `model` and `effort` fields reflect the values active when that session was created, not the current global defaults.
923-- `customProviders` is an optional array of user-configured OpenAI-compatible endpoints, typically local model servers.
935+- The effective `customProviders` list is an optional array of user-configured OpenAI-compatible endpoints, typically local model servers.
924936 - Each `customProviders` entry has a `name`, `baseUrl`, and optional `apiKey`. The `name` becomes the provider prefix shown in model ids such as `lm-studio/qwen3-coder`.
925937 - Unreachable or invalid custom providers do not block startup; mini-coder skips them and shows a warning in the interactive log.
926938 - Custom providers are discovered only at startup. There is currently no interactive slash command to add or remove them.
927-- `mcp.servers` is an optional array of user-configured Streamable HTTP MCP endpoints.
939+- The effective `mcp.servers` list is an optional array of user-configured Streamable HTTP MCP endpoints.
928940 - Each `mcp.servers` entry has a `name`, `url`, and `enabled` flag. `name` must be a simple identifier (`A-Z`, `a-z`, `0-9`, `_`, `-`) because it becomes the imported tool prefix, for example `docs__search`. Older entries that omit `enabled` default to `true` when loaded.
929941 - Invalid MCP entries are dropped while loading settings. Invalid MCP URLs are skipped immediately. Enabled MCP servers that are unreachable or tool-less do not block startup; mini-coder skips them and shows a warning in the interactive log.
930-- MCP server definitions are loaded at startup. `/mcp` can toggle configured servers on or off for future turns during the current app run, and that on/off state is persisted back to `settings.json`. Turning a server on reconnects it on demand; turning it off disconnects it. There is still no interactive slash command to add, remove, or reload server definitions.
942+- MCP server definitions are loaded at startup. `/mcp` can toggle configured servers on or off for future turns during the current app run. For servers defined only in global settings, that on/off state is persisted back to `~/.config/mini-coder/settings.json`. Servers whose effective definition comes from the repo-local overlay are read-only and their toggles last only until the app exits. Turning a server on reconnects it on demand; turning it off disconnects it. There is still no interactive …
931943 - Only MCP tools are imported today; MCP prompts and resources are not surfaced yet.
932944
933945 ## Session persistence