The wymark command

wymark review notes.md

Before editing a markdown file, run `wymark review <path>` in its folder and follow the `_readme` it prints. If the command cannot reach Wymark, edit the file as usual.

{"mcpServers": {"wymark": {"command": "/usr/local/bin/wymark", "args": ["mcp"]}}}

# The `wymark` command

`wymark` asks the running Wymark about a markdown document. It answers from what Wymark keeps: the pending review, the saved versions, git history, and the text from before a write from outside. It never changes a document's text: to do that, edit the file. `cp` and `mv` copy and move a file with its version history.

```
wymark review notes.md
```

## Turn it on, then install it

Settings > Review & comments > **The wymark CLI**. It is off until you turn it on, and while it is off Wymark answers no command. The tour's last slide has the same switch.

Under the switch, **Install the CLI** puts it on your PATH. On macOS this links `/usr/local/bin/wymark` to the command inside the app, and macOS asks for your password when that folder is not yours to write. On Windows it copies `wymark.com` into Wymark's install folder and puts that folder on your `Path`; open a new terminal afterwards.

## Tell an agent to use it

An AI agent runs the command when you ask it to, or when its instructions say to. Once the CLI is installed, Settings shows a sentence for each under **Any agent with a terminal**, with a **Copy** button. The one for the agent's instructions (such as an `AGENTS.md`):

```
Before editing a markdown file, run `wymark review <path>` in its folder and follow the `_readme` it prints. If the command cannot reach Wymark, edit the file as usual.
```

For the setup step by step, see [Connect an AI agent](/docs/guide/connect-an-agent).

## Use it from an MCP client

`wymark mcp` serves the same commands to a tool that speaks MCP, such as an AI coding assistant. Every command above is a tool with the same name and arguments, and answers what the command prints with `--json`. When the tool connects, it is told to read a document's review before editing it, and how comments and replies are written. Wymark must be running with the command turned on, as for the command itself.

Once the CLI is turned on and installed, Settings > Review & comments shows what to copy for each agent: a command to run for Claude Code, a plugin for the Claude desktop app, and an entry for the MCP configuration file of the others. Each names the command by its full path, because a tool started from the Dock does not see your terminal's PATH:

```json
{"mcpServers": {"wymark": {"command": "/usr/local/bin/wymark", "args": ["mcp"]}}}
```

Where it goes depends on the tool:

| Tool | Where |
| --- | --- |
| Claude Code | Run `claude mcp add --scope user wymark -- /usr/local/bin/wymark mcp`, or put the entry in a project's `.mcp.json`. |
| Claude desktop app, and Cowork in it | Add Wymark's plugin: Customize > Plugins > Add > Add marketplace, enter `wymarkapp/wymark`, select Sync, then add Wymark. The plugin starts `/usr/local/bin/wymark mcp`, and comes with your account to Cowork and Claude Code. Or, without the plugin: Settings > Desktop app > Extensions, then **Edit config** under Local MCP servers. It opens `claude_desktop_config.json`: add the server inside its `mcpServers` block, or add the whole entry if the file has none, keeping the file's other settings. Quit Claude Desktop and start it again; the server then shows as Running on that page. Cowork lists it under this computer, and asks before it uses a tool. |
| Cursor | `~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project. |
| Others | The tool's MCP settings. Most take the entry as it is. |

To check it worked, ask the tool to list its MCP tools: there are nine, from `open` to `readme`.

## Wymark must be running

The command asks the app, so the app has to be open with the command turned on. The document does not: a closed document answers from what Wymark saved. When the command cannot reach Wymark, it says so and exits with code 3.

## Commands

| Command | Prints |
| --- | --- |
| `wymark review <path>` | What is pending in the document's review, as `wymark.review/3` JSON. A long review answers with an overview (below); `--full` asks for every change. `--no-readme` leaves out the `_readme` briefing. `--outline`, `--origin`, `--lines` and `--section` read less of it. |
| `wymark versions <path>` | The versions `show` and `diff` can address, newest first. |
| `wymark show <path> --at <ref>` | The body of one version, without its front matter, verbatim. |
| `wymark diff <path> --from <ref> [--to <ref>]` | The difference between two versions of the document, as `wymark.diff/1` JSON. `--to` defaults to `current`. |
| `wymark documents` | The documents you worked on most recently, newest first, and which are open. `--top N` lists N (30 unless told). `--open` lists only the open ones. |
| `wymark cp <source> <dest>` | Copies a document with its version history, as **Duplicate** does. `--fresh` copies the file alone. |
| `wymark mv <source> <dest>` | Moves or renames a document. Its history, and any tab showing it, follow. |
| `wymark readme` | The review briefing on its own, for a tool's instructions. `--short` prints only the start: read the review first, and how comments are written. |
| `wymark mcp` | Serves the commands above to an MCP client. See below. |
| `wymark open <path>...` | Opens the documents in Wymark, starting it if needed. `wymark <path>...` does the same. |

`--json` prints listings and refusals as JSON. `review` and `diff` always print JSON.

`--jq <program>` runs a jq program over the JSON answer of `review`, `diff`, `versions` or `documents` before it is printed, for a tool that cannot pipe the answer to `jq`, such as one using the MCP server. Each result prints on a line of its own, a string as its text, so a text with line breaks spans several lines; `tojson` keeps it on one. Listings are objects, so `.versions[]` and `.documents[]` reach the lists. It is built in (jaq, a jq clone), so `jq` need not be installed. jaq differs from jq in small ways: indexing an object with a number gives `null` rather than an error.

## Reading less of a long review

A review with many changes can run to several times the size of the document. So a bare `review` returns every change only while the answer is short (about 20,000 characters, the briefing not counted). A longer one answers with an overview: `detail` is `overview`, the changes and removals are left out, and `next` says how to read them. Every answer, whole or overview, has `sections`: each section holding changes, removals or comment threads, with its path, its lines and its counts by origin. Each comment thread names its `section` too.

To read only part of a review, or all of it:

| Option | Keeps |
| --- | --- |
| `--full` | Every change, however long the review. A long review piped to another program, such as `jq`, is the overview too, with no `changes`; pass `--full` before the pipe, or use `--jq`. |
| `--outline` | Each change's id, kind, line and origin, and each removal's line and origins, without their text. |
| `--origin incoming` | Only the changes of that origin: `incoming`, `in-app` or `mixed`. `summary` still counts the whole review. |
| `--lines 40-80` | Only the changes, removals and comment threads that start in those lines of the file. |
| `--section "Plan > Budget"` | The same, for the lines of one section: from its heading to the next heading of the same level or higher. |

Any of these options returns every change it keeps, whatever the size, and leaves out the briefing, which the first, bare review carried. `summary` always counts the whole review; a narrowed answer adds `selected`, counting what it kept, and keeps only the `sections` that start in its lines. Read the overview first, then the section or lines you need. A change's id names it in one answer only, so pick by line.

A section is named by its heading's text, or by a path of headings, outermost first, when the text is not unique: `Plan > Budget`. Levels between may be left out, and a `#` run copied from the file is ignored. When several sections match, the command lists their paths instead of guessing. `wymark show <path> --at <ref> --section <heading>` prints just that section of a version.

A relative path is read from the folder the command runs in. A file Wymark has never opened has an empty review.

For `cp` and `mv`, `<dest>` may be a folder, and the file keeps its name there. Neither overwrites: a destination that exists, or that Wymark still keeps another document's history for, is refused. Moving a file with the shell's `mv` also works when the file is unchanged, but `wymark mv` keeps the history whatever the file contains.

`wymark documents` follows the Recents list: the order is when you last edited or looked at a document, so files a tool wrote do not move up. Each line shows the time, then `active` (the tab in front in the frontmost window), `front` (open in the frontmost window) or `open`, then `pending` when its review has changes waiting and `missing` when the file is gone, then the path.

## Version references

| Reference | Means |
| --- | --- |
| `current` | The document as Wymark holds it. |
| `baseline` | What the review is measured against. |
| `12` | Saved version 12, as `wymark versions` lists it. |
| `git:<rev>` | Anything git resolves: `git:HEAD~1`, `git:main`, a commit id. |
| `stored:<id>` | A text Wymark kept from before a write from outside. |

Every version is the document's body. Front matter is not versioned.

`wymark diff notes.md --from baseline` gives the review's changes without what only the review knows: who wrote each change, what it replaced, and where the comments are.

## Exit codes

| Code | Means |
| --- | --- |
| `0` | Success. |
| `1` | The operation failed: no such version, a path that is not a file. |
| `2` | The command line was wrong, a malformed version reference included. |
| `3` | Wymark cannot answer. Open it and run the command again. |

A refusal says what went wrong and what to do about it. It goes to stderr, as JSON with `--json`.

## When it does not answer

- Check which app a command belongs to with `wymark --version`. The dev build installs its own, `wymark-dev`.
- `ls -l /usr/local/bin/wymark` shows where the link points. After moving `Wymark.app`, install the command again from Settings.
- If the switch is on and the command still says Wymark is not running, turn the switch off and on again.