Skip to content
tszaksPublic

About

A fast, native Mac editor for Markdown and plain text, made to sit next to your AI coding agents.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Margin app icon

Margin

A fast, native Mac editor for Markdown and plain text, made to sit next to your AI coding agents.

CI Latest release MIT license macOS 26 or later

Margin showing a Markdown note with the live preview pane open

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.

Features

  • 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 editing meeting notes in Markdown

Made for AI agents

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 current prints the front file, your cursor and your selection as JSON.
  • Agents can show you a place. margin notes.md:42 opens 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.

Install

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.sh

There is no Homebrew cask yet.

Command line tool

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/margin

Make 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.

Keyboard shortcuts

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.

FAQ

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.

Contributing

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

License

MIT © 2026 Szakacs Media LLC

About

A fast, native Mac editor for Markdown and plain text, made to sit next to your AI coding agents.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages