Settings & files on disk
Where Mel stores settings, tab configs, and conversations.
Mel's settings are saved in ~/.mel/settings.json (%APPDATA%\mel\config\settings.json on Windows), a plain JSON file you can edit by hand. All of Mel's configuration is plain JSON and TOML you can read, edit, back up, or check into a dotfiles repo. Two roots matter: ~/.mel/ for settings and ~/.local/share/mel/ for data.
~/.mel/ — settings
| Path | What it holds |
|---|---|
settings.json | The unified settings store behind the Settings UI — appearance, AI, features, SSH, and agent-permission defaults. Written whenever you change a setting; safe to edit by hand (missing fields fall back to defaults). |
tab_configs/*.toml | Your tab configs — one TOML recipe per file. Every valid file appears in the + menu; a file that fails to parse shows there as a ⚠ "failed to parse" row instead. |
tab_settings.json | The sidebar rail's state: whether it's shown, density, primary info, subtitle, and hover details. See Tab customization. |
repos.json | The tracked-repository registry used by repo-type tab-config parameters and the + menu's worktree entries. |
default_tab_config | A one-line marker holding the path of the config bound to the new-tab key. Delete it (or right-click the config) to go back to plain new tabs. |
MEL.md | Your instructions for every project — see Rules and MEL.md. |
skills/, prompts/, mcp.json | Your own skills, saved prompts and MCP servers — see the Library. A project keeps its own in .mel/ at its root. |
worktrees/<repo>/<branch> | Git worktrees Mel creates from the + menu — real git worktree add checkouts, one directory per branch. |
settings.json keys
The keys you're most likely to edit by hand. A missing key takes its default. A few keys (the theme names, the Auto mode, the permission words and the command lists) also fall back to their default on a value Mel doesn't know. Anything else that doesn't parse, such as broken JSON or a number written as text, makes Mel start with every setting at its default, and the next change in Settings writes a fresh file, so keep a copy before you edit by hand.
| Key | Default | Settings page | What it does |
|---|---|---|---|
theme | "dark" | Appearance | dark, light or system |
theme_dark / theme_light | "dark" / "light" | Appearance | Which theme each mode paints (themes) |
zoom | 1.0 | Appearance | UI scale, 0.8 to 1.5 |
font_size | 15 | Appearance | Text size in points |
cursor_type / cursor_blink | "bar" / true | Appearance | bar, block or underline; whether it blinks |
show_block_dividers | true | Appearance | The hairline between blocks |
compact_block_header | false | Appearance | Fold the folder and time into the command row |
dim_inactive_panes / focus_follows_mouse | false / false | Appearance | Pane focus behaviour |
max_blocks | 5000 | Features | Blocks kept per session (100 to 5000) |
agent_first | true | Features | New tabs and splits open in the agent |
restore_session / warn_on_quit | true / true | Features | Reopen your layout; ask before quitting with work running |
right_click_paste | false | Features | Right-click pastes |
notif_toast_secs / desktop_notifications | 6 / true | Features | How long a notice stays; desktop notifications |
beta_updates | false | Features | Receive beta updates |
ai_ghost | true | AI | AI command suggestions |
autodetect_shell_in_agent | true | AI | Run shell-shaped input in the shell |
show_input_hints / thinking_auto_open | true / true | AI | Input hints; open the Thoughts section while the model thinks |
default_model_base / default_auto_bias | "auto" / "responsive" (Balanced) | Agent mode, AI | The model new conversations start on, and the Auto mode |
edits_mode / commands_mode / perm_agents | ask / ask / ask | Agent mode | Permissions |
cmd_allow / cmd_deny | [] / built-in list | Agent mode | Command allowlist and denylist (regular expressions) |
ask_readonly_commands | false | Agent mode | Ask before read-only commands too |
rules_enabled | true | Knowledge | Send your Drive rules |
voice_enabled | true | AI | Voice input |
ssh_melt | true | Melt | Ctrl+Enter melts an SSH session |
melt_added / melt_denied | [] / [] | Melt | Commands that open, or never open, full screen |
cli_toolbar and the rich_input_* keys | see CLI agents | Third party CLI agents | The coding-agent toolbar and Rich Input |
line_numbers / auto_save / auto_open_review | absolute / false / false | Editor and Code Review | Editor gutter, auto-save, open review on the first change |
project_explorer / global_file_search / explorer_hidden_files | true / true / false | Editor and Code Review | The Tools panel's views |
sync_conversations | true | Privacy | Back conversations up to your account |
keybindings | {} | Keyboard shortcuts | Your own keys, by action |
~/.local/share/mel/ — data
| Path | What it holds |
|---|---|
accounts/<account>/conversations/ | Saved agent conversations as JSON, written after every turn — one history per account (local when you're signed out). These power the recents list, the conversations panel, conversation minis, and the Prompts sources in command history. Signing out hides that account's history; signing back in shows it again. |
drive/ | Mel Drive: folders as directories, objects by extension — .workflow.json, .prompt.json, .env.json, .notebook.md. |
Practical notes
- Everything is created on demand — deleting a file resets that piece to defaults on next launch.
- Tab configs and Drive objects are the most rewarding to version-control: they're the parts you author.
- Provider API keys are never stored in any of these files. On a paid plan the agent uses the keys Mel's relay holds server-side; a key you add yourself (Settings → AI → Provider API keys) is kept in the OS keychain, or in a file only you can read on Linux.
- On Windows the settings folder is
%APPDATA%\mel\configrather than~/.mel, and Mel's data lives under%APPDATA%\mel. WhereXDG_DATA_HOMEis set, the data folder is$XDG_DATA_HOME/melinstead of~/.local/share/mel.
Related
- Appearance — the settings behind
settings.json - Sessions — how saved conversations show up in scrollback
FAQ
Where are Mel's settings stored? In ~/.mel/settings.json on macOS and Linux and %APPDATA%\mel\config\settings.json on Windows. Open settings file (the </> button in Settings) opens it.
Can I keep my Mel settings in a dotfiles repo? Yes. Copy or link settings.json and your tab_configs/ folder. Your provider keys are not in these files.
What happens if I make a typo in settings.json? If the file stops being valid JSON, Mel opens with default settings and rewrites the file at your next change in Settings. Keep a copy before editing by hand.