Install

Hand one sentence to your agent and it sets OpenMarkdown up for you — checks your machine, wires in the tools, and opens your first note. Or do any of it by hand below.

← back to home

Paste one sentence

Give this to any agent that can read a URL. It reads this page and does the rest — the URL is the single thing that stays current, so the sentence never goes stale.

Read openmarkdown.dev/install to install OpenMarkdown and open my first note

That's the whole install for most people. Want to see or run the steps yourself? They're below — pick your agent.

First: install the app

OpenMarkdown's tools are the desktop app — the MCP server is openmd mcp, your local app in server mode. Downloading an app and granting it permissions is something only you can do, so this step is yours and comes first; your agent picks up from there.

Download and install the app. Grab the latest release for your platform — macOS (.dmg, drag to Applications), Linux (AppImage), or Windows (.exe). The agent steps below are macOS and Linux — on Windows the app is a native editor with agent co-editing coming soon (or run the Linux build under WSL to get it today).
Turn on the openmd CLI. In the app: Settings → System integration → Install the command-line tool. That drops openmd on your PATH.
Check it. Run openmd status — it should answer.

If openmd isn't on your PATH yet, one of two things is true — both quick to fix. You have the app but the CLI is off → open OpenMarkdown → Settings → System integration → Install the command-line tool. You don't have the app yet → install it (step 1 above), then turn on the CLI. Once openmd status answers, paste the sentence again and your agent carries on. A missing openmd just means this step isn't finished — nothing is wrong; your agent can't download the app or grant its permissions (that needs your hands), so it points you back here rather than guess or try to install the app itself.

Then: connect your agent

Claude Code gets the full plugin — the seven MCP tools and a skill that teaches it when to use them. Every other agent connects the same MCP server (the tools); the skill is Claude Code–only. The runtime is identical either way: plain openmd mcp over stdio.

What you're actually installing. The MCP wiring just points your agent at openmd mcp — the local app you installed a moment ago, no new binary downloaded. The Claude Code plugin adds Markdown only (a skill + three slash commands); no hooks, no scripts that run on their own, no network calls, and no "run any shell command" tool — the eight tools touch only your Markdown files and the app's own menu commands. It's all open: read the plugin/ source before you install it — that's the front door, not a detour. A careful agent that checks first finds no hooks and no network, and can go ahead.

Claude Code

Full plugin — the seven MCP tools plus the skill.

Hand it the sentence (it installs the plugin and opens your first note):

Read openmarkdown.dev/install to install OpenMarkdown and open my first note

Or run it yourself:

claude plugin marketplace add OpenMarkdown-dev/OpenMarkdown-releases
claude plugin install openmarkdown@openmarkdown

Want the tools only, without the skill? claude mcp add openmd -- openmd mcp

Codex

Connects the seven MCP tools. The skill is Claude Code–only, so Codex won't load it — the tools work the same.

One line:

codex mcp add openmd -- openmd mcp

Or by hand in ~/.codex/config.toml:

[mcp_servers.openmd]
command = "openmd"
args = ["mcp"]

Gemini CLI

Connects the seven MCP tools. The skill is Claude Code–only, so Gemini won't load it — the tools work the same.

One line:

gemini mcp add openmd openmd mcp

Or by hand in ~/.gemini/settings.json:

{
  "mcpServers": {
    "openmd": { "command": "openmd", "args": ["mcp"] }
  }
}

opencode

Connects the seven MCP tools. The skill is Claude Code–only, so opencode won't load it — the tools work the same.

No add command — set it in opencode.json (project) or ~/.config/opencode/opencode.json (global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "openmd": { "type": "local", "command": ["openmd", "mcp"], "enabled": true }
  }
}

Any MCP client

Anything that speaks MCP can spawn the server. Point it at openmd mcp over stdio — no arguments, no network.

{ "command": "openmd", "args": ["mcp"] }

That's the whole contract: a stdio server named openmd running openmd mcp. Consult your client's docs for where its config lives.

Finally: your first note

You don't have to make one. On its first launch OpenMarkdown already seeded a curated Welcome note — a real file at ~/OpenMarkdown/Welcome.md — and opened it: a two-part walkthrough you can work through on your own, whose second half hands your agent "copy this to your agent" prompts. So "open my first note" means one specific thing: your agent opens that same file — not a new one, not your oldest existing note — and, when you ask, demos any section right inside it, you and it writing in the same file while the app just renders it. Here's the exact host-neutral script it follows.

# First-run guide — open the Welcome, don't build one

Agent-facing runbook for the very first thing to do once OpenMarkdown's plugin/MCP is installed and verified. Your job is small and specific: **open the Welcome note the app already seeded** and hand the user into it. You are not building an onboarding — the app did that.

This file is the single source of truth for that handoff. The install runbook page (`openmarkdown.dev/install`) inlines this same file so non-Claude MCP hosts get the identical steps — so keep everything here host-neutral (only the seven MCP tools, no Claude-Code-specific verbs).

**Where the Welcome comes from:** on its first launch OpenMarkdown seeds `~/OpenMarkdown/Welcome.md` (a curated, two-part onboarding note) and opens it. That file is the onboarding — a real file on the user's disk, with the human-facing lesson and, in its second half, per-section *"copy this to your agent"* prompts. Your role at first run is to **open that same file**, not to author your own.

**Prerequisite:** `openmd` is on PATH. The seven MCP tools may not be *live in this session* yet — and that changes how you open the note, not whether you do:

- **Tools live** → `open_file` / `reveal` the Welcome as below.
- **Not live because the plugin was just installed this session** (a host loads a plugin's MCP server + skill only when its session starts) → **do not stop, and do not claim you can't help.** Open the note with `openmd ~/OpenMarkdown/Welcome.md` directly. Then, at the end, tell the user how to load the full tools **without a restart**: on Claude Code that is **`/reload-plugins`** (the user types it — an agent cannot), which loads the MCP server, skill, and `/openmarkdown` commands into this same session.
- **`openmd` itself missing** (not on PATH) → *that* is the one stop condition: the app + CLI aren't set up yet; finish install first (see the runbook).

## Ask first (consent gate)

Before opening anything, ask one light line in chat and wait for the answer:

> "Installed. Want me to open your Welcome note and get you started? (yes / later)"

- **Skip the ask** if the sentence that triggered this install already asked to open a note (e.g. "…and open my first note"). That is consent — open it now.
- **"later"** → do **not** steal focus (no `reveal`). Say: "Your Welcome is at `~/OpenMarkdown/Welcome.md` — open it or ping me whenever." **Never create a note of your own**, and never open one of the user's existing files to stand in for it. Stop here.
- **"yes"** → open it.

## Open the seeded Welcome

`open_file` `~/OpenMarkdown/Welcome.md`, then `reveal` it so the app comes to the front. This is the file the app seeded on first launch — **open it, never author your own, and never open the user's oldest existing note in its place** ("open my first note" means *this* curated Welcome).

If `~/OpenMarkdown/Welcome.md` doesn't exist — the default notes dir is already there but was created some other way (an existing user), so the app never seeded it — do not manufacture a curated note. Open the default notes directory (or say where it is) and let the user pick up from there.

## Hand off

Once it's open, one line in chat, then get out of the way:

> "That's your Welcome — a real file on your disk; the app just renders it. Walk through it yourself, or ask me to demo any section for you."

The Welcome's first part teaches the basics with nothing but the user and the editor. Its second part is the agent half: each section carries a *"copy this to your agent"* prompt the user can hand to you. So the felt moment isn't a fixed script you perform up front — it happens **on demand**, when the user asks.

## Demo a section on request

When the user asks you to run one of the Welcome's sections (e.g. "turn this CSV into a table", "take me to where we build the hero"), do exactly that with the MCP tools — `read_section` / `write_section` to edit in place, `reveal` to move their view, `get_context` to see what they've selected. Each section already says what it shows; you're just the agent it points to. No separate beat script, no keeper note to seed — the file is already there, and you act on it when invited.