App Settings Tool

The app_settings MCP tool lets agents read and write an allowlisted set of RepoPrompt's global preferences — appearance, prompt packaging, edit-format defaults, preferred models, the Context Builder agent/model, MCP server behavior, and the global Code Maps toggle — without opening the Settings UI. Anything dangerous, secret, or workspace-specific is deliberately not exposed.

tip

Companion pages: Use this page for the MCP/JSON surface. For the same controls from a shell, see App Settings from the CLI. For the in-app UI equivalents, see Settings Reference.

When to Use It

• Match the user's preferred appearance or prompt packaging before building a copy preset.
• Flip mcp.auto_start from setup scripts so RepoPrompt's listener launches with the app.
• Reset models.planning_model to null so RepoPrompt falls back to defaults.
• Temporarily disable Code Maps globally via code_maps.globally_disabled during large refactors.
• Toggle edit-format defaults (editing.file_edit_format) before sending an edit-producing request.

Operations

op	Selectors	Purpose
list	optional group	Browse the allowlist catalog. Each entry includes the current value and, for keys that have them, options_available: true.
get	exactly one of key, keys, group	Read one or more setting values. Selectors are mutually exclusive.
set	key and value	Update exactly one setting. keys and group are rejected on set.
options	key, optional agent, limit, detailed	List candidate values for keys that advertise options_available: true (today: the model settings).

Parameters

Parameter	Type	Notes
op	list | get | set | options	Required.
group	string	ui | prompt_packaging | editing | models | context_builder | mcp | code_maps. Used by list and as a selector for get.
key	string	Fully-qualified key (e.g. ui.appearance_mode). Required for set; optional selector for get.
keys	array of string	Multi-key selector for get. Mutually exclusive with key and group.
value	boolean | number | string | null	Required on set. Accepted types match the entry's declared type in the catalog.
agent	string	For options on model settings: filter candidates to one CLI backend (e.g. claudeCode, codexExec, gemini).
limit	integer	For options: maximum number of candidates returned (1–200, default 60).
detailed	boolean	For options: include descriptions and model metadata in each candidate.

Groups

The allowlist is organized into seven groups so an agent can browse narrowly before reaching for set. If you are not sure about the exact key, type, or allowed values, call list first; set validates strictly and rejects unknown or out-of-range values without partial application.

ui — Appearance and chrome

Key	Type	Details
ui.appearance_mode	string enum	System | Light | Dark. App appearance mode.
ui.show_tooltips	boolean	Whether RepoPrompt shows app tooltips.
ui.enable_keyboard_shortcuts	boolean	Global keyboard shortcuts. New/changed shortcuts may only take effect after reopening a window.

prompt_packaging — How prompts are assembled

Key	Type	Details
prompt_packaging.prompt_sections_order	JSON string array	Serialized ordering of prompt sections; must contain each prompt section exactly once. Call {"op":"list","group":"prompt_packaging"} first and read the allowed_items array for this key to get the canonical list of prompt section raw values before sending set.
prompt_packaging.duplicate_user_instructions_at_top	boolean	Whether user instructions are duplicated at the top of packaged prompts.
prompt_packaging.file_path_display_option	string enum	Full | Relative. How file paths are displayed in packaged context.
prompt_packaging.selected_files_sort_method	string enum	nameAscending | nameDescending | tokenAscending | tokenDescending.
prompt_packaging.include_datetime_in_user_instructions	boolean	Whether packaged user instructions include the current date/time.

editing — Edit-format defaults

Key	Type	Details
editing.file_edit_format	string enum	Diff | Whole | None. Preferred edit format for edit-producing requests.
editing.allow_diff_models_to_rewrite	boolean	Whether diff-oriented models may fall back to whole-file rewrites when needed.
editing.complex_edit_strategy	string enum	Single query | Parallel split | Sequential split.

models — Model selection and inference defaults

Key	Type	Details
models.preferred_compose_model — Built-in Chat Model	string | null	Preferred Built-in Chat model raw identifier, if set. Advertises options_available: true. Set null to clear.
models.planning_model — Oracle Model	string | null	Preferred Oracle model raw identifier, if set. Advertises options_available: true. Set null to clear.
models.sync_chat_model_with_oracle — Sync Built-in Chat with Oracle	boolean	Whether the Built-in Chat model is kept in sync with the Oracle model.
models.temperature	number	Range 0.0–2.0. Only applied when models.temperature_enabled is true.
models.temperature_enabled	boolean	Whether the global temperature is sent with model requests.
models.custom_planning_prompt — Custom Oracle System Prompt	string	Custom system prompt used by the Oracle. Empty string restores the built-in default.

context_builder — Context Builder agent & model

Key	Type	Details
context_builder.agent	string enum	CLI agent used by the Context Builder MCP tool. Allowed values come from the installed discover backends (for example claudeCode, codexExec, gemini); call list and read allowed_values for the current set. Writes preserve that backend's remembered model when one exists, or fall back to its default.
context_builder.model	string | null	Model raw identifier used by the Context Builder MCP tool. Reads and writes the remembered model for the currently selected context_builder.agent; set null to clear that slot. Advertises options_available: true; by default, op=options scopes candidates to the current backend.

mcp — MCP server preferences

Key	Type	Details
mcp.auto_start	boolean	Whether the MCP listener auto-starts when RepoPrompt launches. Does not immediately stop or start the current listener.
mcp.show_model_presets	boolean	Whether MCP model preset recommendations are shown.

code_maps — Global Code Maps toggle

Key	Type	Details
code_maps.globally_disabled	boolean	When true, Code Maps are globally disabled and the MCP get_code_structure tool is suppressed.

Examples (MCP JSON)

Each example shows the arguments object passed to app_settings:

// Browse the full catalog (values always included)
{ "op": "list" }

// Inspect one group
{ "op": "list", "group": "ui" }

// Batch read a few keys
{ "op": "get", "keys": ["ui.appearance_mode", "mcp.auto_start"] }

// Toggle a boolean
{ "op": "set", "key": "ui.show_tooltips", "value": false }

// Update an enum
{ "op": "set", "key": "ui.appearance_mode", "value": "Dark" }

// Clear an optional model (null is valid for nullable keys)
{ "op": "set", "key": "models.planning_model", "value": null }

// Change a numeric setting
{ "op": "set", "key": "models.temperature", "value": 1.25 }

// Switch the Context Builder agent (remembered model is preserved)
{ "op": "set", "key": "context_builder.agent", "value": "codexExec" }

// List candidate models for the current Context Builder backend
{ "op": "options", "key": "context_builder.model" }

// Narrow candidates to one CLI backend
{ "op": "options", "key": "models.planning_model", "agent": "codexExec", "limit": 25 }

Error Behavior

• Unknown keys: Rejected with a clear error. Call list (or list with a group) to discover the correct key.
• Wrong types: Booleans, numbers, strings, and null are each validated against the entry's declared type.
• Out-of-range values: Numeric ranges (e.g. models.temperature 0.0–2.0) and enum values are enforced.
• No partial application: Validation fails closed — if any check fails, nothing is written.
• One key per set: Passing keys or group on set is rejected.

Safety & Deliberately Excluded

This surface is intentionally narrow. The following are not reachable through app_settings and must be managed in the Settings UI:

• API credentials for any provider.
• MCP tool ACLs and agent permission documents.
• Workspace approvals and workspace-scoped chat/copy settings.
• Agent-mode scalars and model override dictionaries.
• Internal/migration-style flags and experimental toggles.

If a preference is dangerous, secret, or workspace-specific, it is kept UI-only by design. Agents can still discover what is reachable with op=list.

See Also

• App Settings from the CLI — the same allowlist via rp-cli.
• MCP Tools Reference — schemas for every MCP tool.
• Settings Reference — the in-app Settings UI equivalents.
• MCP Server Overview — IDE-for-agents framing and capability map.