Troubleshooting and limitations¶

Does Mellow run on Windows?¶

Not natively; the built-in terminal is Unix-only for now. Inside WSL, install the Linux build.

macOS says it can't check the app for malicious software¶

You downloaded the archive in a browser. The builds are not yet signed by Apple, so macOS may block browser downloads. Install with Homebrew or the install script instead. Do not disable system security protections to run an unverified download.

A shortcut does nothing¶

Your terminal may keep that key for itself (on macOS, most terminals keep Cmd keys). F1 and the command palette (Ctrl+P) show only keys your terminal can send, and every action is in the palette.

I want my terminal's own text selection back¶

Start Mellow with mellow --no-mouse, and your terminal handles the mouse.

The status line cut a message short¶

Long messages end in … there. Show recent messages in the palette (Ctrl+P) lists them in full, newest first, including errors from Git, language servers and formatters.

Where did my unsaved changes go after a crash?¶

Open the same file (or folder) again and choose [R] Restore. Recovery copies are kept, readable only by you, in ~/.local/state/mellow.

Several unsaved drafts from one crash each get a tab. Press A (or click Discard all) to discard them together. A draft that holds only blank space is removed without asking. Press Esc to decide later: an unnamed draft is offered again next time, and a draft of a named file keeps the dialog open, because editing that file would replace the saved draft.

Why does Go to symbol not open in my terminal?¶

Go to symbol uses Ctrl+Shift+O, and terminals without the kitty keyboard protocol send that as Ctrl+O, which opens a file. Use Go to symbol from the palette (Ctrl+P), which works everywhere. See Keys.

What happens to a large copy over SSH?¶

When Mellow has no system clipboard, it sends copies through your terminal's clipboard (OSC 52). Copies up to 256 KB go that way. Larger copies stay inside Mellow, and the status line says so, so a slow connection is not flooded.

What if a save is written in place?¶

Some files, such as ones mounted into a container, cannot be replaced. Mellow then writes the new text into the same file, and the status line says Saved in place. If the machine crashes during that write, the file can be damaged; the recovery journal keeps a copy of your text until the save succeeds.

Can Mellow damage my files?¶

Ordinary saves use atomic replacement: the new text is written to a temporary file and moved into place, to reduce the risk of partial writes. Filesystem-specific fallbacks exist, so this is not a universal durability guarantee or a replacement for backups. If a file changed on disk since you opened it, Mellow asks before overwriting. Files that are not UTF-8, or larger than 100 MiB, are refused rather than mangled.

Does Git in Mellow do anything risky?¶

It uses your system git. Pull is fast-forward only, push never forces, and Revert never deletes untracked files. Fetch, pull, push and commit run in the background with a progress line; "Cancel Git operation" in the palette stops them.

Does Mellow send my code anywhere?¶

AI requests send the disclosed context to the configured provider. Opt-in inline suggestions also send nearby code after typing pauses. Git fetch/pull/push and installed language-server processes can use the network. Core file editing works offline.

Is it free?¶

Yes. Mellow is open source under the Apache-2.0 license.

Where do I report a bug?¶

On GitHub issues. For security problems, follow the security policy.

`mellow`: command not found¶

Check where you installed the binary with command -v mellow. The release installer defaults to ~/.local/bin; Cargo normally uses ~/.cargo/bin. For the release installer's default, try this in your current shell:

export PATH="$HOME/.local/bin:$PATH"
mellow --version

If that works, add the same export to the appropriate startup file for your shell. If several versions are installed, command -v mellow shows which one runs. Avoid reinstalling repeatedly before checking PATH.

Completion or go to definition is missing¶

Install the matching language server, ensure its executable is on the PATH inherited by Mellow, and reopen the file. Use Language server status or Restart language server in the palette. Server capabilities vary; syntax highlighting alone does not imply an LSP server is running. In the audit candidate, explicitly trust workspace execution before starting an installed server. Files over 5 MiB do not use language servers.

Format on save did not change my file¶

It is off by default. Enable it in Settings, install a supported formatter and read the status line after saving. A missing, failed or timed-out formatter leaves the original text saved. Format document is a separate language-server command and may not be supported by your server.

Project search missed a match¶

Check the workspace folder, Git ignore rules and the search summary. The search uses unsaved text for discovered open files and disk content for the others. It skips binary, unreadable and over-limit files and stops at its scan/result limits. The audit candidate supports .mellow/search.json filters/limits and includes named unsaved open files; unnamed drafts have no project path. See project search behavior.

Git pull or push failed¶

Mellow uses system Git and your existing repository setup. Check git status and git remote -v in your shell. Authentication prompts are disabled in the editor's Git subprocesses; resolve authentication through your normal shell workflow. A diverged branch cannot be pulled with the editor's fast-forward-only operation. Review the repository in your shell rather than assuming Mellow will merge or force-push it.

What files and platforms are supported?¶

Files must be UTF-8 and at most 100 MiB. Files over 5 MiB open with reduced functionality, without parsing or language servers. Native Windows is not supported; WSL uses the Linux build. The audit candidate preserves supported ownership/group, ACLs and extended attributes during replacement and refuses metadata transitions it cannot preserve. Saving an existing multiply linked file is refused with Save As guidance, so other hard links are never silently split. Save As creates an independent file and never replaces a newly appearing target. Symlink saves target the resolved file. Bind-mount in-place fallback retains its partial-write risk and is reported. Conflict checks cannot serialize an uncooperative external writer through the last check/rename interval; keep backups and review disk conflicts. Filesystem and platform validation limits are in the audit tracker.

When reporting a problem, include the Mellow version, OS/architecture, terminal name, command used and a small synthetic reproduction. Remove credentials and private file contents. Live language-server and AI compatibility is not exhaustively tested, so include the server/provider and version when relevant.