Settings Reference

Magia stores all settings in a JSON file under the application data directory. Every setting has a sensible default so the app works out of the box — you only need to change what matters to you.

Settings file location (macOS):

~/Library/Application Support/sh.magia.com/settings.json

Settings are also accessible through the Settings panel (Cmd+,).

Editor

Settings that control the built-in CodeMirror editor.

Setting	Key	Type	Default	Description
Editor preference	`editorPreference`	`"in-app" \| "vscode" \| "cursor" \| "zed" \| "sublime" \| "system"`	`"in-app"`	Which editor to use when opening files. `"in-app"` uses the built-in editor; other values launch the named external editor.
Minimap	`minimapEnabled`	`boolean`	`true`	Show the minimap scrollbar overview in the editor gutter.
Font size	`editorFontSize`	`number`	`13`	Editor font size in pixels.
Font family	`editorFontFamily`	`string`	`"JetBrains Mono"`	Editor font family. Any monospace font installed on the system can be used.
Line height	`editorLineHeight`	`number`	`1.4`	Editor line height multiplier.

Terminal

Settings for the integrated xterm.js terminal.

Setting	Key	Type	Default	Description
Font size	`terminalFontSize`	`number`	`13`	Terminal font size in pixels.
Font family	`terminalFontFamily`	`string`	`"JetBrains Mono"`	Terminal font family. Any monospace font installed on the system can be used.
Cursor style	`terminalCursorStyle`	`"block" \| "bar" \| "underline"`	`"bar"`	Terminal cursor shape.
Cursor blink	`terminalCursorBlink`	`boolean`	`true`	Whether the terminal cursor blinks.
Line height	`terminalLineHeight`	`number`	`1.0`	Terminal line height multiplier.
Shell	`terminalShell`	`string \| null`	`null`	Path to the shell executable. `null` means auto-detect from `$SHELL` or the system default.

UI / Appearance

Settings that control the visual appearance and general UI behavior.

Setting	Key	Type	Default	Description
Theme mode	`themeMode`	`"dark" \| "light" \| "system"`	`"dark"`	Color scheme. `"system"` follows the OS preference.
Theme ID	`themeId`	`string`	`"magia"`	The active theme identifier. Custom themes register their own IDs.
Chat font size	`chatFontSize`	`number`	`14`	Font size for chat messages in pixels.
Chat line height	`chatLineHeight`	`number`	`1.5`	Line height multiplier for chat messages.
Chat font family	`chatFontFamily`	`string`	`"Noto Sans"`	Font family for chat messages.
Title suggestions	`titleSuggestionsEnabled`	`boolean`	`true`	Automatically suggest session titles based on the first prompt.
Close behavior	`closeBehavior`	`"minimize_to_tray" \| "quit"`	`"minimize_to_tray"`	What happens when you close the main window.
Confirm before quit	`confirmBeforeQuit`	`boolean`	`true`	Show a confirmation dialog before quitting when sessions are active.
Workspaces	`workspacesEnabled`	`boolean`	`true`	Enable the workspaces feature.
Workspace display mode	`workspaceDisplayMode`	`"tabs" \| "sidebar"`	`"tabs"`	How workspace sessions are displayed — as tabs or in a sidebar.
Watchdog timeout	`watchdogTimeoutSecs`	`number`	`15`	Seconds without output before the session watchdog considers an agent stalled.
Developer mode	`developerMode`	`boolean`	`false`	Unlock developer tools and feature flags. See Feature Flags.

Provider

Settings that control which LLM provider is used.

Setting	Key	Type	Default	Description
Default provider	`defaultProvider`	`"claude" \| "gemini" \| "codex"`	`"claude"`	The provider used for new sessions. Only providers enabled in `PROVIDER_FLAGS` are selectable.
Provider binary paths	`providerBinaryPaths`	`Record<string, string>`	`{}`	Override the auto-detected CLI binary path for a given provider. Key is the provider ID (e.g. `"claude"`), value is the absolute path. Empty string reverts to auto-detect.

Permissions

Settings that control which actions agents are allowed to take without asking.

Setting	Key	Type	Default	Description
Permission preset	`permissionPreset`	`"acceptEdits" \| "default" \| "dontAsk" \| "plan" \| "auto" \| "bypassPermissions"`	`"default"`	Global permission policy for agent tool use. See below for preset descriptions.
Tool permissions	`toolPermissions`	`ToolPermission[]`	`[]`	Per-tool overrides. Each entry has `toolName: string` and `autoApprove: boolean`.

Permission Presets

Preset	Description
`acceptEdits`	Automatically accept all file edits; prompt for other actions.
`default`	Prompt for all potentially destructive or network actions.
`dontAsk`	Auto-approve most actions; only prompt for high-risk operations.
`plan`	Agent plans actions and shows them before executing.
`auto`	Fully autonomous — agent executes without prompts.
`bypassPermissions`	Disable all permission checks. Use with caution.

Voice / STT

Settings for the speech-to-text (Whisper) voice input feature.

Setting	Key	Type	Default	Description
Voice input enabled	`voiceInputEnabled`	`boolean`	`false`	Enable microphone-based voice input.
Whisper model	`whisperModel`	`string`	`"base"`	The Whisper model size to use (`"tiny"`, `"base"`, `"small"`, `"medium"`, `"large"`). Larger models are more accurate but slower.
Whisper language	`whisperLanguage`	`string`	`"auto"`	BCP-47 language code for transcription (e.g. `"en"`, `"es"`). `"auto"` enables automatic language detection.
Audio device ID	`whisperDeviceId`	`string`	`""`	ID of the input audio device. Empty string uses the system default microphone.
STT engine	`sttEngine`	`string`	`"auto"`	Speech-to-text engine. `"auto"` picks the best available engine.

Notifications

Settings that control in-app and system notification behavior.

Setting	Key	Type	Default	Description
Notifications enabled	`notificationsEnabled`	`boolean`	`true`	Master switch for all notifications.
Desktop notifications	`desktopNotificationsEnabled`	`boolean`	`true`	Send OS-level desktop notifications.
Sound enabled	`notifSoundEnabled`	`boolean`	`true`	Play a sound with notifications.
Session completed	`notifSessionCompleted`	`boolean`	`true`	Notify when an agent session finishes successfully.
Session error	`notifSessionError`	`boolean`	`true`	Notify when an agent session encounters an error.
Agent waiting	`notifAgentWaiting`	`boolean`	`true`	Notify when an agent is waiting for user input.
System updates	`notifSystemUpdates`	`boolean`	`true`	Notify when a new version of Magia is available.

Memory

Settings for the memory and reflection system.

Setting	Key	Type	Default	Description
Memory enabled	`memoryEnabled`	`boolean`	`true`	Enable the persistent memory system.
Reflections enabled	`reflectionsEnabled`	`boolean`	`true`	Enable automatic memory reflections (summaries of past sessions).
Sync interval	`syncIntervalMinutes`	`number`	`10`	How often (in minutes) memory is synced to disk.
Retention period	`memoryRetentionDays`	`number`	`90`	Number of days to keep memory entries before pruning.
Max size	`memoryMaxSizeMb`	`number`	`50`	Maximum size of the memory store in megabytes.
Reflection interval	`reflectionIntervalMinutes`	`number`	`120`	How often (in minutes) the reflection process runs.
Observation mode	`observationMode`	`"off" \| "post-session" \| "live"`	`"live"`	When to run memory observations. `"live"` observes during sessions; `"post-session"` observes after.
Observation interval	`observationIntervalMinutes`	`number`	`10`	Interval in minutes for live observation checks.
Observation model	`observationModel`	`string`	`"haiku"`	Model name used to generate observations.
Observation provider	`observationProvider`	`string`	`"claude"`	Provider used for observations.
Side question model	`sideQuestionModel`	`string`	`"haiku"`	Model used for side questions during observation.
Observation system prompt	`observationSystemPrompt`	`string \| null`	`null`	Custom system prompt for the observation model. `null` uses the built-in default.
Reflection system prompt	`reflectionSystemPrompt`	`string \| null`	`null`	Custom system prompt for the reflection model. `null` uses the built-in default.

Telemetry

Settings for OpenTelemetry, crash reporting, and analytics. See Telemetry for a full explanation of what data is collected and how to opt out.

Setting	Key	Type	Default	Description
OTel enabled	`otelEnabled`	`boolean`	`true`	Enable the local OpenTelemetry collector. Metrics are only sent to an external endpoint if `MAGIA_OTEL_ENDPOINT` is set at build time.
OTel collector port	`otelCollectorPort`	`number`	`4318`	HTTP port for the local OTLP collector. Agent processes export to this port.
Metric export interval	`otelMetricExportIntervalMs`	`number`	`5000`	How often (ms) metrics are flushed from the collector.
Logs export interval	`otelLogsExportIntervalMs`	`number`	`2000`	How often (ms) log records are flushed from the collector.
Log user prompts	`otelLogUserPrompts`	`boolean`	`false`	Include user prompt text in OTel log records. Disabled by default to avoid leaking sensitive content.
Log tool details	`otelLogToolDetails`	`boolean`	`false`	Include tool call arguments and results in OTel log records.
Crash reporting	`crashReportingEnabled`	`boolean`	`true`	Send crash reports to Sentry. Only active when `MAGIA_SENTRY_DSN` is set at build time. Self-builds are always silent.
Analytics	`analyticsEnabled`	`boolean`	`true`	Send anonymous usage analytics to PostHog. Only active when `MAGIA_POSTHOG_KEY` is set at build time. Self-builds are always silent.

Updates

Settings that control the auto-update behavior.

Setting	Key	Type	Default	Description
Auto-check updates	`autoCheckUpdates`	`boolean`	`true`	Periodically check for new releases and show a banner when one is available.
Update channel	`updateChannel`	`string`	`"stable"`	Which release channel to follow. `"stable"` for official releases; `"nightly"` for pre-release builds.
Dismissed version	`dismissedUpdateVersion`	`string \| null`	`null`	Version string the user has dismissed from the update banner. Managed automatically.