Skip to content
Back to search

imark

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/migsilva89--imark/badge.svg)](/listings/migsilva89--imark)

HTML

<a href="/listings/migsilva89--imark"><img src="/api/listings/migsilva89--imark/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

brew install --cask migsilva89/imark/imark

Or download the [latest release](../../releases/latest) and drag `Imark.app` into `/Applications`. The disk image is signed and notarised, so it opens without a Gatekeeper warning.

macOS 14 or later. Imark checks once a day when you leave the option on in Settings. When a new version exists, click **Install and Relaunch** — the app downloads it, verifies both signatures, replaces itself and opens again.

To make it the default for `.md`: launch it with no document open and click **Make Imark the default for .md**, or use the same item in the **Imark** menu. Once it is the default, both quietly disappear.

From a terminal

**Imark ▸ Install the imark Command…** links `imark` into `/usr/local/bin`, or into `~/.local/bin` when that first one belongs to root — the alert says which, before it writes anything.

imark notes.md            # opens it in the copy already running
imark notes notes.md      # the notes somebody left in it, as text
imark skills              # agent presence and skill/command status
imark skills install      # install missing files and update shipped copies
imark skills update       # update existing shipped copies only

The skills commands run without opening a window. They use the same setup as the app for Claude Code and Codex, preserve edited files, and never install plugins or change agent settings. Status distinguishes missing, current, outdated and edited files, and lists unsupported agents it finds. `imark skills --help` explains the commands. Exit code 1 means missing or outdated files for a present agent, no supported agents, or an error; 2 means invalid arguments. Edited files are kept and do not cause a non-zero exit.

A document already open comes forward instead of opening twice. This is separate from making Imark the default for `.md` on purpose: `open notes.md` should still go to your editor.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines
  1. {
  2. "name": "imark",
  3. "owner": {
  4. "name": "migsilva89"
  5. },
  6. "metadata": {
  7. "description": "Review plans, diffs and documents in Imark, the offline macOS markdown reader.",
  8. "version": "0.7.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "imark",
  13. "source": "./plugin",
  14. "description": "Review plans, diffs and documents in Imark. The agent writes markdown, you comment on it in the app, and your notes come back — through the file, with no server in between."
  15. }
  16. ]
  17. }
README.md · README · 365 lines
  1. <p align="center">
  2. <img src=".github/assets/app-icon.png" width="128" height="128" alt="Imark app icon">
  3. </p>
  4. <h1 align="center">Imark ®</h1>
  5. <p align="center">
  6. <strong>Native Markdown reader for macOS.</strong><br><br>
  7. Double-click a <code>.md</code> file and it opens rendered, reloads itself while you<br>
  8. edit, and previews in the Finder with the space bar. Comment on a phrase and the<br>
  9. note goes into the file itself. Nothing leaves the machine.
  10. </p>
  11. <p align="center">
  12. <img src="https://img.shields.io/badge/macOS-14%2B-blue?style=flat-square" alt="macOS 14 or later">
  13. <img src="https://img.shields.io/badge/Swift-6-orange?style=flat-square" alt="Swift 6">
  14. <img src="https://img.shields.io/badge/network-updates%20only-brightgreen?style=flat-square" alt="Network: update checks and downloads only, can be turned off">
  15. <img src="https://img.shields.io/badge/size-7%20MB-lightgrey?style=flat-square" alt="7 MB download">
  16. <img src="https://img.shields.io/badge/licence-MIT-blue?style=flat-square" alt="MIT licence">
  17. <a href="https://buymeacoffee.com/migsilva?utm_source=github-imark">
  18. <img src="https://img.shields.io/badge/Buy%20me%20a%20coffee-%E2%98%95-FFDD00?style=flat-square" alt="Buy me a coffee">
  19. </a>
  20. </p>
  21. https://github.com/user-attachments/assets/e4f23bf3-06c9-4151-9f9a-601e3c86451a
  22. <p align="center"><em>A 37-second tour, with sound: comments, the editor, Quick Look, and reviewing an agent's plan.</em></p>
  23. > [!NOTE]
  24. > Imark opens reading, and reading is what it is for. The switch in the toolbar turns it into an editor for the file you already have open — see [Editing](#editing) — and comments go into the document itself, as HTML comments, so they travel with it.
  25. ## What it does
  26. - **Editing, when you ask for it** — one switch in the toolbar, and the page becomes the file: line numbers, Markdown in colour, a bar beside every line you have changed, `⌘S` to write it. Reading is the state it opens in
  27. - **Comments in the file** — select, comment, edit or delete, and the note lives in the document as an HTML comment, so it survives being emailed, committed, or opened in anything else. `⌘Z` undoes any of it
  28. - **Task lists you can tick** — press the box on a `- [ ]` item and the tick is saved to the `.md` file, so the document goes back with your choice in it
  29. - **Quick Look previews** — the space bar in the Finder renders the document, not raw text, using the same engine as the app
  30. - **Live reload** — saving in your editor updates the view in under 300ms, keeping your scroll position, and it survives the delete-and-rename that editors call an atomic save
  31. - **Foldable outline** — headings in the sidebar, with sections you can collapse; past twenty entries it opens folded, so a changelog is one row per version
  32. - **Outline rail** — a tick per heading down the edge of every document, tapering around the pointer, with a card that names the section before you commit to going there
  33. - **Wiki-links** — `[[note]]` resolves against the folder and opens in the same window, with back and forward history
  34. - **The folder and the recents** — every `.md` beside the open document, plus the last five you opened from anywhere else
  35. - **Everything GitHub-flavoured** — tables, task lists, footnotes, front matter as a header card you can put away from the View menu, syntax highlighting, Mermaid diagrams, KaTeX maths
  36. - **Actions on a selection** — comment on it, translate it on device, or search the web for it in your default browser
  37. - **Find with a counter** — `⌘F` highlights every hit and tells you which one you are on
  38. - **Tabs** — several documents in one window, with everything macOS gives a tabbed app: `⌘⇧[` and `⌘⇧]`, drag a tab out, Merge All Windows
  39. - **Offline where it counts** — documents render with every request blocked by a content security policy, KaTeX fonts embedded, remote images refused on purpose
  40. ## Screenshots
  41. | Document window | Quick Look preview |
  42. |:---:|:---:|
  43. | ![A document window with the outline sidebar and syntax-highlighted code](.github/assets/imark-window.png) | ![The Finder preview panel, with the outline rail down the left edge](.github/assets/imark-quicklook.png) |
  44. Both are rendering [`testdata/showcase.md`](testdata/showcase.md). For the full
  45. sweep — every construction, every kind of comment, and enough headings that the
  46. outline folds itself — open [`testdata/everything.md`](testdata/everything.md).
  47. <p align="center">
  48. <img src=".github/assets/quicklook.gif" width="720" alt="Pressing the space bar in Finder and stepping through markdown files in the preview panel">
  49. </p>
  50. <p align="center"><em>Space bar in the Finder. No app to open first.</em></p>
  51. <p align="center">
  52. <img src=".github/assets/imark-rail.png" width="520" alt="The rail tapering around the pointer, with a card naming the section and quoting its first line">
  53. </p>
  54. <p align="center"><em>The rail: one tick per heading, in the window and in the Finder's preview panel alike. Click to jump, or press and drag to scrub.</em></p>
  55. ## Install
  56. ```bash
  57. brew install --cask migsilva89/imark/imark
  58. ```
  59. Or download the [latest release](../../releases/latest) and drag `Imark.app` into `/Applications`. The disk image is signed and notarised, so it opens without a Gatekeeper warning.
  60. macOS 14 or later. Imark checks once a day when you leave the option on in
  61. Settings. When a new version exists, click **Install and Relaunch** — the app
  62. downloads it, verifies both signatures, replaces itself and opens again.
  63. To make it the default for `.md`: launch it with no document open and click **Make Imark the default for .md**, or use the same item in the **Imark** menu. Once it is the default, both quietly disappear.
  64. ### From a terminal
  65. **Imark ▸ Install the imark Command…** links `imark` into `/usr/local/bin`, or
  66. into `~/.local/bin` when that first one belongs to root — the alert says which,
  67. before it writes anything.
  68. ```bash
  69. imark notes.md # opens it in the copy already running
  70. imark notes notes.md # the notes somebody left in it, as text
  71. imark skills # agent presence and skill/command status
  72. imark skills install # install missing files and update shipped copies
  73. imark skills update # update existing shipped copies only
  74. ```
  75. The skills commands run without opening a window. They use the same setup as
  76. the app for Claude Code and Codex, preserve edited files, and never install
  77. plugins or change agent settings. Status distinguishes missing, current,
  78. outdated and edited files, and lists unsupported agents it finds.
  79. `imark skills --help` explains the commands. Exit code 1 means missing or
  80. outdated files for a present agent, no supported agents, or an error; 2 means
  81. invalid arguments. Edited files are kept and do not cause a non-zero exit.
  82. A document already open comes forward instead of opening twice. This is separate
  83. from making Imark the default for `.md` on purpose: `open notes.md` should still
  84. go to your editor.
  85. ## Editing
  86. The toolbar has one switch: an eye and a pencil. The eye is the app you know —
  87. nothing on screen offers to change the file. The pencil replaces the page with
  88. the document as text, in a plain editor: line numbers, Markdown in colour, a bar
  89. in the gutter beside every line that differs from the file on disk, and the
  90. system's own find bar with its counter and its replace field.
  91. `⌘S` writes it. Until you do, **live reload stands still** — following the file
  92. is the reason this app exists and also the one thing that could erase what you
  93. typed, so while there is anything unsaved the window stops watching. The close
  94. button carries the system's edited dot, *Revert* throws the buffer away and reads
  95. the file again, and closing the window or opening another document asks first.
  96. A save cannot land on somebody else's work: it goes through the same check every
  97. comment does, and if the file moved since Imark read it the save is refused and
  98. says so. `⌘Z` afterwards puts the document back the way it was.
  99. *Open in…* stays in the toolbar while you edit, with Cursor, VS Code, Zed,
  100. Sublime — and Claude and ChatGPT — so the moment a change is bigger than a line,
  101. the file goes to something built for it. Imark runs nothing on your machine and
  102. asks nothing of your accounts; when you come back, the reader is where you left
  103. it, and the notes are still in the file.
  104. ## Comments
  105. <p align="center">
  106. <img src=".github/assets/comment.gif" width="720" alt="Selecting a block, writing a note in the popover, and the note appearing in the margin">
  107. </p>
  108. <p align="center"><em>Comment on anything. The note goes into the <code>.md</code> file.</em></p>
  109. <p align="center">
  110. <img src=".github/assets/imark-comments.png" width="620" alt="A phrase underlined in the text, a dot in the margin, and a card floating over the right margin with the note">
  111. </p>
  112. If you only want to read, deselect **Show controls for adding comments** in
  113. Settings. The moving **+**, block highlights, and Comment action disappear;
  114. notes already in a file remain visible.
  115. Select a phrase, press the speech bubble, write, press `↵`. The quoted words get
  116. underlined, a dot appears in the margin, and clicking either opens the note. Pick
  117. one of five colours while writing it, or change it later. The card carries **Edit**
  118. and **Delete**, and `⌘Z` undoes any of it — writing, editing or deleting.
  119. Without a selection there is a **+** in the margin, level with whatever the
  120. pointer is beside. On a list or a table it offers the **item or the cell** you
  121. are level with rather than the whole block — an agent's twenty-item list is
  122. twenty things to disagree with, not one — and the note quotes that item, so the
  123. file says which one it meant to anyone who reads it without the app.
  124. The note is stored **inside the `.md` file**, as an HTML comment:
  125. ```markdown
  126. Rows move in batches of 500, and the deadline is generous but achievable.
  127. <!-- imark quote="generous but achievable" by="john" at="2026-08-02T14:31Z"
  128. Achievable with which team? This needs a number, not an adjective.
  129. -->
  130. ```
  131. Which means it travels with the document instead of living in a database only
  132. this app can read:
  133. | Where | What you see |
  134. |---|---|
  135. | **Imark** | the words underlined, a dot in the margin, the note on click |
  136. | **Cursor, VS Code, Vim** | the block above, verbatim, right under the paragraph |
  137. | **GitHub, any renderer** | nothing — HTML comments are invisible |
  138. | **`grep`, `cat`** | the note, with the quote it refers to beside it |
  139. The `quote=` is what makes the note legible in raw text: someone opening the file
  140. in Vim can see what it refers to without counting lines. If the quoted words are
  141. later edited away the note goes **orphan** — still visible, still attached to its
  142. block, marked as having lost its anchor. There is no fuzzy matching, because a
  143. note in the wrong place is worse than a note without an exact one.
  144. Four ways to get at them, because they answer different questions. The count in
  145. the status bar opens **the list** — every note at once, out of the document.
  146. `⌘⇧C` opens them all **in place**, each under its own block. `⌘'` and `⌘⇧'`
  147. **step** through one at a time. And a rail down the left edge marks **where**
  148. they are, so three clustered in one section is visible at a glance.
  149. **File › Export Comments as Text…** writes a copy — not the document — with every
  150. note turned into a blockquote, for the review the other person has to read on
  151. GitHub:
  152. ```markdown
  153. Rows move in batches of 500, and the deadline is generous but achievable.
  154. > **john, 2 Aug 2026** on *“generous but achievable”*
  155. >
  156. > Achievable with which team? This needs a number, not an adjective.
  157. ```
  158. ## Reviewing an agent's work
  159. A plan from a coding agent is markdown. So is a diff, once it is wrapped in a
  160. fenced block. Because comments live in the file, an agent can hand you a
  161. document, you can annotate it in Imark, and the agent can read your notes back
  162. out — with no server, no port and nothing installed on the other side. The file
  163. is the whole bridge.
  164. <p align="center">
  165. <img src=".github/assets/review.gif" width="720" alt="Pressing Send Back in the toolbar, and the agent picking the notes up in the terminal">
  166. </p>
  167. <p align="center"><em>Send Back, and the agent reads your notes back.</em></p>
  168. A document under review gets two buttons in the toolbar, **Approve** and **Send
  169. Back**, and pressing either one ends the wait on the other side. Closing the
  170. window without pressing one asks first, because something is waiting for an
  171. answer and closing is not an answer.
  172. The buttons appear on a document an agent asked to have reviewed, and nowhere
  173. else: the agent leaves a small file in `~/.imark/pending` naming the document
  174. before opening it, and Imark writes the decision beside that file. Every other
  175. `.md` opens exactly as it always did.
  176. [`plugin/`](plugin/README.md) is a Claude Code plugin that does this:
  177. ```
  178. /imark:imark-review PLAN.md # review a markdown document
  179. /imark:imark-notes PLAN.md # notes you already left
  180. ```
  181. Launched with no document, Imark offers to **set itself up for the coding agents
  182. on your machine** — one skill, written into each one's `skills` folder. The alert
  183. names every file before writing it, and undoing it is deleting those. Claude Code
  184. and Codex read the same `SKILL.md`; only Claude Code also takes the two loose
  185. commands. They tell the agent to run `imark notes` and `imark review`, the same
  186. commands you type, and to fall back to the script inside the app only when
  187. `imark` is not on its PATH.
  188. Those files are copies, so a new version of Imark brings them forward on its
  189. first launch and says which ones it rewrote. A copy you edited yourself is never
  190. overwritten — Imark only replaces a file that still matches something it shipped,
  191. and tells you the rest were left alone.
  192. ## What it touches
  193. | Where | What, and when |
  194. |---|---|
  195. | The `.md` you are reading | when you save an edit or a comment. Written to a temporary file beside it and moved into place; it refuses to save at all if the document changed on disk since Imark read it |
  196. | `~/.imark/pending` | while an agent is waiting on a review: which document, and what you decided. Deleted when the agent reads it |
  197. | `~/Library/Preferences/pt.miguelsilva.imark.plist` | your settings — theme, text size, width, the update check |
  198. | `/usr/local/bin/imark`, or `~/.local/bin/imark` | only if you ask for the `imark` command. One symlink into the app, named in the alert first. Deleting it undoes it |
  199. | `~/.claude/skills`, `~/.codex/skills`, … | only if you accept the offer to set up your coding agents, and only the files the alert names. A new version rewrites those same files once, on its first launch, unless you edited them |
  200. | The network | one request a day to GitHub for the signed update feed. If you click **Install and Relaunch**, Imark downloads the signed and notarised disk image from the same release. No document or identifier is sent, and Settings turns the automatic check off |
  201. > [!IMPORTANT]
  202. > Editing and comments are the two ways Imark writes to your documents. Both
  203. > refuse to save if the file changed on disk since Imark read it. `⌘Z` puts the
  204. > last change back, and `⇧⌘Z` redoes your typing while editing. If Imark ever
  205. > damages a file, [open an issue](../../issues/new?template=bug_report.yml)
  206. > before anything else — that is the one bug worth interrupting whatever else is
  207. > happening.
  208. ## Keyboard shortcuts
  209. | | | | |
  210. |---|---|---|---|
  211. | `⌘O` | Open | `⌘F` | Find, prefilled with the selection |
  212. | `⌘W` | Close window | `⌘G` / `⌘⇧G` | Next / previous hit |
  213. | `⌘\` | Toggle sidebar | `←` / `→` | Fold / unfold outline section |
  214. | `⌘[` / `⌘]` | Back / forward | `⌘R` | Reload |
  215. | `⌘+` / `⌘-` / `⌘0` | Text size | `⌘⇧R` | Reveal in Finder |
  216. | `⌘P` | Print or export PDF | `⌘⇧C` | Show all comments |
  217. | `⌘'` / `⌘⇧'` | Next / previous comment | `⌘Z` | Undo the last change |
  218. | `⌘E` | Reading or editing | `⌘S` | Save the file |
  219. | `⌘X` / `⌘C` / `⌘V` | Cut, copy, paste | `⇧⌘Z` | Redo your typing |
  220. | `⌘/` | This table, in the app | | |
  221. `⌘/` opens the same list inside the app, built by reading the menu bar rather
  222. than from a copy of this table — which is also how it stays right on keyboards
  223. where macOS remaps the keys. On a Portuguese layout, Back and Forward are `⌘Ç`
  224. and `⌘~`, not `⌘[` and `⌘]`.
  225. ## Building from source
  226. Requires Xcode 16 or later and Node 20.
  227. ```bash
  228. git clone https://github.com/migsilva89/imark.git
  229. cd imark
  230. cd renderer && npm ci && cd ..
  231. ./build.sh
  232. ```
  233. That builds the JavaScript bundle, compiles the Swift, assembles `Imark.app` and
  234. installs it to `/Applications`. `npm ci` is not optional: the rendered output is
  235. generated, not committed, and `build.sh` refuses to assemble an app with a blank
  236. window.
  237. | | |
  238. |---|---|
  239. | `./build.sh` | build and install |
  240. | `./build.sh --debug` | fast compile, for iterating |
  241. | `./build.sh --no-install` | leave it in `dist/` |
  242. | `IMARK_INSTALL_DIR=~/Applications ./build.sh` | install elsewhere |
  243. Swift 6 with AppKit and no external Swift dependencies, around a WKWebView that
  244. only ever renders; markdown-it, highlight.js, Mermaid and KaTeX are bundled
  245. offline with esbuild. [`CONTRIBUTING.md`](CONTRIBUTING.md) has the layout of the
  246. repository, the test suites and how to run them.
  247. ## FAQ
  248. ### Why does the Quick Look extension need the network entitlement?
  249. It does not use the network. WebKit refuses to start its WebContent process
  250. inside a sandboxed app extension without `com.apple.security.network.client`,
  251. even when every byte is served from a local scheme. The panel stays blank without
  252. it, with no error and no log entry.
  253. ### What does `⌘Z` undo?
  254. While reading: the last change to the document — a note written, edited or
  255. deleted — up to ten deep. Each one is a snapshot of the whole file taken before
  256. the change.
  257. While editing: the typing, like any editor, with `⇧⌘Z` to put it back. The two
  258. never mix, because putting a whole document back is not what `⌘Z` means with a
  259. caret on screen.
  260. Either way it only covers changes Imark made; edits from your own editor are your
  261. editor's to undo.
  262. ### What happens if two people comment on the same words?
  263. The second note gets an `nth="2"` so it anchors to the right occurrence. Notes on
  264. the same paragraph stack down the margin rather than landing on top of each
  265. other.
  266. ## Support the project
  267. Imark is free and stays free. If it saves you time, you can [buy me a coffee](https://buymeacoffee.com/migsilva?utm_source=github-imark) — it keeps the next release coming.
  268. ## Security, contributing, licence
  269. Imark is a personal project, maintained by one person. Issues get answered and
  270. pull requests are welcome —
  271. [`CONTRIBUTING.md`](CONTRIBUTING.md) says what is out of scope before you spend a
  272. weekend on it — but there is no support promise and no release schedule. For
  273. anything that looks like a security problem, [`SECURITY.md`](SECURITY.md) says
  274. where to send it instead of the issue tracker.
  275. Everything Imark bundles is permissive — MIT, ISC, BSD, Unlicense — with no
  276. copyleft anywhere in the tree. Several require their copyright notice to travel
  277. with the binary, so [`THIRD-PARTY.md`](THIRD-PARTY.md) is generated from what
  278. esbuild actually put in the bundle, on every build, and the same list ships
  279. inside the app: **Imark › About Imark** shows it.
  280. Imark itself is [MIT](LICENSE) — use it, change it, redistribute it, just keep
  281. the copyright notice.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.