A fast, native Mac editor for Markdown and plain text, made to sit next to your AI coding agents.
Margin opens .md and .txt files and gets out of the way. It never turns your text into rich text, never swaps your quotes for curly ones, and keeps the file exactly as it was: same encoding, same line endings, same last line.
It is also built for working with AI agents such as Claude Code, Codex and Cursor. When an agent edits a file you have open, you see the change at once, and one Cmd-Z undoes it.
- Plain text, kept as it was. UTF-8, UTF-16 (with BOM), Windows-1252 and Mac Roman files are saved back in the same encoding. LF, CRLF and CR line endings are preserved. Smart quotes, smart dashes and auto-correct are off.
- Thin, quiet window. A TextEdit-style window with tabs, find and replace, spell check, and text that always wraps (no sideways scrolling).
- Live Markdown styling while you type: headings, bold, italic, code, links, lists.
- Optional preview pane next to the text. Toggle it with Shift-Cmd-P. Local images show up; scripts never run.
- Status bar with words, characters, line and column, encoding and line ending.
- Autosave. About one second after you stop typing, the file on disk is up to date.
- Light and dark, with native macOS controls.
Margin treats a coding agent as a normal collaborator that happens to write to your files.
- Edits appear live. When an agent (or any other program) changes a file you have open, the new text shows up with no dialog. Undo with Cmd-Z.
- Your typing is always on disk. Margin saves about one second after you stop, so an agent that reads the file sees your latest text.
- Conflicts never lose data. If a file changes on disk while you have unsaved typing, a bar offers Keep Mine or Load Theirs. Margin never overwrites either side silently.
- Agents can see what you are looking at.
margin currentprints the front file, your cursor and your selection as JSON. - Agents can show you a place.
margin notes.md:42opens a file at line 42. - Copy for LLM (Shift-Cmd-C) copies the path, the line numbers and the selected text in a fenced code block, ready to paste into a chat.
Here is real output from margin current, trimmed:
{
"app" : "Margin",
"front" : {
"cursor" : { "column" : 5, "line" : 14 },
"kind" : "markdown",
"lineCount" : 31,
"name" : "release-plan.md",
"path" : "/Users/you/notes/release-plan.md",
"selection" : {
"endLine" : 16,
"startLine" : 14,
"text" : "- [ ] Run the soak test for 48 hours\n- [ ] Tag `v2.4.0`",
"truncated" : false
},
"unsaved" : false
},
"pid" : 4242,
"running" : true,
"schema" : 1,
"updated" : "2026-10-24T14:03:11Z"
}The full guide, with every field, the URL scheme and how conflicts work, is in docs/agents.md.
Margin needs macOS 26 (Tahoe) or later.
Download. Get Margin-<version>.zip from the latest release, unzip it, and drag Margin.app to /Applications. Releases are signed with a Developer ID certificate and notarized by Apple.
Build from source. See docs/building.md. In short:
brew install xcodegen
git clone https://github.com/tszaks/margin.git
cd margin
scripts/install.shThere is no Homebrew cask yet.
The margin command lives inside the app. Either choose Margin > Install Command Line Tool... from the menu, or link it yourself:
mkdir -p ~/.local/bin
ln -s /Applications/Margin.app/Contents/Resources/margin ~/.local/bin/marginMake sure ~/.local/bin is on your PATH (add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc). You can link into /usr/local/bin instead, which is usually on PATH already but may need sudo.
| Command | What it does |
|---|---|
margin |
Open Margin |
margin notes.md |
Open a file |
margin notes.md:42 |
Open a file at line 42 (:42:7 adds a column) |
margin new ideas/today.md |
Create a file (and its folder) if missing, then open it |
margin current |
Print what is open, as JSON |
margin current --path |
Print only the front file's path |
margin current --selection |
Print only the selected text |
To make Margin the app that opens .md and .txt files, run swift scripts/set-default-app.swift from a checkout, or use Finder's Get Info > Open with > Change All.
| Keys | Action |
|---|---|
| Cmd-N | New document |
| Cmd-T | New tab |
| Cmd-O | Open |
| Cmd-S | Save (Margin also saves by itself) |
| Shift-Cmd-S | Duplicate |
| Cmd-F | Find |
| Option-Cmd-F | Find and replace |
| Cmd-G / Shift-Cmd-G | Find next / previous |
| Cmd-E | Use selection for find |
| Cmd-J | Jump to selection |
| Shift-Cmd-C | Copy for LLM |
| Shift-Cmd-P | Show or hide the Markdown preview |
| Cmd-= / Cmd-- / Cmd-0 | Bigger / smaller / actual size text |
| Ctrl-Tab / Shift-Ctrl-Tab | Next / previous tab |
| Ctrl-Cmd-F | Full screen |
The View menu also has Show Line Numbers (off by default) and Use Monospaced Font. Your choices are remembered.
Why not TextEdit?
TextEdit is fine for notes, but it makes you choose between rich text and plain text, it can change quotes and dashes, and it asks questions when a file changes on disk. Margin is plain text only, tells you nothing you do not need, and treats files changing under it (from an agent, a formatter, git checkout) as normal.
Does Margin phone home?
No. There is no analytics, no crash reporting and no update check. Margin makes no network requests of its own. The one exception is the preview pane: if your Markdown document contains an image with an https:// address, the preview loads it, like any web page would. http:// images are blocked, and the preview cannot run script.
Where does Margin keep its settings and data?
- Preferences (font size, line numbers, preview):
~/Library/Preferences/com.szakacsmedia.margin.plist - What is open, for agents:
~/Library/Application Support/Margin/state.json - Window restoration:
~/Library/Saved Application State/com.szakacsmedia.margin.savedState
Your documents stay where they are. Margin does not copy them anywhere.
Will Margin change my files just by opening them? It only writes after you edit. When it saves, it uses the file's own encoding. A file with mixed line endings is saved with its most common style, so every line ends the same way.
Does it open binary files? No. A file that looks binary (it contains NUL bytes) is refused with a message instead of being shown as garbage.
Does it work on older macOS? No. Margin targets macOS 26 and later.
Bug reports and pull requests are welcome. Please read CONTRIBUTING.md first. Security problems go through SECURITY.md. Everyone taking part follows the Code of Conduct.
Docs: agents guide · architecture · building · releasing · changelog
MIT © 2026 Szakacs Media LLC