Permark

PerMark

AI speeds the work. Your vision steers it.

A Markdown app to read and review what your AI agents write, and steer the work through its documents.

It opens every Markdown file as a clean page, shows what your agents change while they write, and lets you keep or revert each change.

Created and maintained by Edelmar Schneider.

Get PerMark: Microsoft Store (Windows) · GitHub Releases (Windows, macOS, Linux)

Where to start · Try it · Install · Use with an AI agent · Shortcuts · What's new · Contributing

Free and open source (MIT or Apache-2.0) · No account, no telemetry · Windows, macOS and Linux (tested by hand on Windows)

---

Where to start

Build with AI agents?Got a .md file?

Your agents write the plans, specs and reports. Your job is to read them, judge them and steer. Open the project folder in PerMark and keep it next to your terminal.

Watch. Changed passages glow while your agent writes, and dots mark what changed since you last read it. See what your AI writes Decide. Keep or revert each change, and leave comments an agent can mark done. Decide what stays Connect. Any MCP agent can see where you are, per project, and only when you turn it on. Use with an AI agent

Your AI, a colleague or a download gives you a .md file. Open it with PerMark and read it as a page, not a wall of symbols.

Read it. Tables, diagrams, math and properties on a clean page. Fix it as it looks, and keep notes that save themselves. Beautiful to read, easy to edit Open what is around it. Config files as sheets, data, pictures, audio and video. Markdown at the center Get it. From the Microsoft Store or GitHub, for Windows, macOS and Linux. Install

Either way, PerMark works with any AI tool, or with none. It follows changes whatever program writes the files: an AI agent, an editor or git. It is a unified document workspace (UDW): Markdown at the center, with the config, data and code files around it.

Try it in a minute

1. Install. Get PerMark from the Microsoft Store or from GitHub Releases.
2. Open. Choose a folder as a project (Ctrl+O), or a single .md file (Ctrl+Shift+O). It opens in View, as a clean page.
3. Watch. Let your agent write in that folder. Changed passages glow. Press Ctrl+Shift+L for Follow mode, and PerMark opens each document while the agent writes it.

📖 Beautiful to read, easy to edit

Every Markdown file opens as a clean page, with its tables, diagrams, math and properties. Edit it as it looks, and keep notes that save themselves.

• A clean page. GitHub-flavored Markdown with tables, task lists, footnotes, alerts and description lists. Code blocks are highlighted for about 190 languages. In a project, links open inside the app, with Back and Forward, like a wiki.
• Diagrams and math, written as text. Mermaid and PlantUML diagrams are drawn inside PerMark, with no Java and no server. Math shows as formulas.
• Front matter as a properties card. View shows it as a clean card. In Edit, you change its values one by one, and the rest of the file stays as it is.
• Made for long reading. A light, dark or system theme, with softer light tones (Paper, Sage, Gray). Three reading widths, an outline to jump between sections, and Focus mode (Ctrl+Alt+F), which leaves only the page.
• View, Edit, Source. One switch in the header. View is for reading. Edit changes the page as it looks, with a toolbar and a / block menu. Source shows the raw file, every byte, with find and replace and go to line. A switch beside the modes draws a Mermaid or PlantUML diagram next to its text while you type (off until you turn it on).
• Honest about Edit. Edit keeps math, diagrams, HTML and footnotes as written: Edit in Source opens them. Edit does not draw pictures that are files next to the document; View and Source do.
• Notes that save themselves. Click Notes, next to Settings, or press Ctrl+Shift+N for a new note from anywhere in PerMark, and type. No name to choose, no folder to pick, no save prompt. Notes are plain Markdown files you own, and Copy puts a drafted prompt on the clipboard as exact Markdown.

⚡ See what your AI writes

See what your AI writes while it writes, and what changed since you last looked.

• Changed passages glow. The open document reloads while an agent writes, and keeps your place. Changed blocks glow, and removed blocks leave a marker you can expand.
• Live changes. A feed lists every file that changed, one entry per file. Show all changes, only yours, or only those from outside.
• Follow mode (Ctrl+Shift+L) opens the Markdown document being written. It waits while you edit.
• Unread dots, like mail. A dot marks each Markdown document that changed since you last read it, and folders count them. Alt+U opens the next one.
• Since last visit. One list of what changed while the project was closed: Changed, New or Removed. It compares the content of your documents, so it works without git, and it still shows the changes after the agent has committed.
• Worktrees too. Linked git worktrees are found and watched, so agents working in parallel branches show up as well.

PerMark sees the changes in your folder, whatever program makes them. It tells you whether a change came from you or from outside.

✅ Decide what stays

You decide what stays: keep or revert each change, comment on any passage, and share a project with an agent only when you turn it on.

• Review, change by change. When a document changed since you last read it, a quiet bar says how many changes there are. Review shows each one in place: block by block in Markdown, line by line in code, logs, data and config files. Choose Keep or Revert for each (K, R), or for all at once. Compare with what you last read, or with the last commit.
• Comments an agent can mark done. Select a passage and press C. With the agent connection on, your agent reads your open comments and marks them done with a reply. Send to agent copies them as a prompt for any agent chat. Comments are yours alone.
• Only what you changed is saved. Edit and Source rewrite only the blocks you changed. Every other byte stays as its author, or agent, wrote it.
• Reload theirs or Keep mine (overwrite). If an agent changes a file while you edit it, you choose, for the whole document.
• Git in plain words. Letter badges, with a legend that says what each letter means. Compare with your last visit or with the last commit. PerMark only reads git: it never commits, stages or creates a repository.
• Find anything, to the section. Search everywhere (Ctrl+T) finds files, sections, tags and commands in one box. Give any file tags and a one-line description; the ones you add in the app never touch your files.
• Links follow your files. Move or rename a file, and PerMark shows each link it will update before it changes them. Ctrl+Z in the Explorer takes it back.

🧩 Markdown at the center, not alone

Markdown leads, and many files around it open too: config files as clean sheets, data and code, pictures, audio and video.

• Config files as clean sheets. TOML, YAML, INI, .env, .properties and ignore files open as sections, keys and values, with comments as captions. Change a value, and only those bytes change. Secret values are masked in the sheet. Sheets edit values, not keys. YAML flow style is read-only, and a file over 256 KB or 3,000 rows shows as plain text.
• TOON. .toon files, the compact data format made for AI, open as tables and cards and can be edited in place. The Converter turns JSON, XML, YAML, CSV and TOML into TOON or another format, shows the estimated token saving of each choice, and never writes over the original.
• AI files, recognized. AGENTS.md, CLAUDE.md, SKILL.md, Cursor rules (.mdc), llms.txt, prompt files, and model and dataset cards open with no setup.
• Prompt blocks. XML-like prompt tags such as <context> and <instructions> fold as blocks, and the Markdown inside still renders. {{name}} variables are marked, and @path references link to the file.
• JSON, XML, code and plain text open with highlighting. A very large text file opens at once.
• Pictures, audio and video open in the app (not every audio or video format plays). Other files open with the program your system has for them. Programs and scripts are never run from a click.
• Token count: how many tokens a document, a section or a folder takes. Exact for OpenAI's tokenizers, marked as approximate for Claude and Gemini. It asks before it downloads a tokenizer's vocabulary.
• Your editor, at the line. A path like src/main.rs:42 that names a file of the project is a link: it opens your own editor at that line.

Many features are plugins, and every plugin is on from the start. Turn off what you do not need in Settings → Plugins; a plugin that is off leaves nothing behind.

Questions people ask

"Git diff already shows me the changes."

Git diff compares with the last commit. PerMark also shows what changed since you last read each document, even after the agent has committed, and you keep or revert each change.

"Does it replace my code editor?"

No. PerMark is for the documents around the code. Open in external editor takes you to your own editor at the place you are reading.

"What does the agent get, and how do I stop it?"

Sharing is off in every project until you turn it on. The agent reads, shows you a place and marks comments done. It never edits through PerMark. Details in Use with an AI agent.

"Does it go online?"

No account, no telemetry, no tracking. PerMark goes online only to check for its own updates (installer versions; the Store and snap update it instead), and when you ask: a picture from the web, or the optional token-count vocabulary. Your documents never leave your computer through PerMark. An AI agent you connect is a separate program: what it sends online is up to that agent. The Windows installers may also download Microsoft's WebView2 component while they install, if your computer does not have it.

What PerMark is not

• Not a code editor. No completion, refactoring, build, run or debug. Real code work opens in your own editor.
• Not an agent. It does not run, host or replace your AI. It shows what your AI writes, and you decide what stays.
• Not tested by hand on macOS or Linux. PerMark 0.6 was tested by hand on Windows; the macOS and Linux builds are checked automatically.

Why Markdown

Markdown was made for readers. So is PerMark. It was designed in 2004 so that plain text reads well as it is. Today, AI tools write it too, for the same reason: it is structured enough for a machine and clear enough for a person.

It is also an opinion: many documents that live in Word or PDF today would be better as Markdown. They would be smaller, comparable line by line in git, readable by any AI, and never locked inside one app.

Install

Windows, macOS and Linux. PerMark 0.6 was tested by hand on Windows; the macOS and Linux builds are checked automatically. Installers are not code-signed, so your system shows a warning the first time you install or open it.

Copies from GitHub check for updates when they start and once a day, and offer to download and restart. The Microsoft Store and the snap update their copies themselves. PerMark becomes your default app for Markdown only if you choose it: it asks once, with Markdown files checked and other types unchecked. On Windows, you confirm the choice in Windows Settings.

Coming from TrailMark? The command is now permark. If an agent is set up with the old trailmark command, run the setup lines from Settings → Integration → Agent connection again. PerMark 0.6 no longer renames old .trailmark/ folders: update to 0.5.8 before you update to 0.6.

Command line

permark                  # start PerMark: your last windows and tabs come back
permark .                # open the current folder as a project
permark docs/plan.md     # open a single file
permark --notes          # open the Notes

On Windows and macOS, permark is not on your PATH after an install from GitHub, so use the full path of the program, or add it yourself. The Microsoft Store and snap versions put permark on your PATH.

Build from source

You need Rust, Node.js 24 and the Tauri prerequisites. The program lives in app/, and app/rust-toolchain.toml pins the Rust version, which rustup installs for you.

git clone https://github.com/EdelmarSchneider/permark.git
cd permark/app
npm ci
npm run tauri build   # or: npm run tauri dev

Use with an AI agent

PerMark can tell an AI agent what you are looking at, the way a code editor tells it the open file. Say "rewrite this paragraph" or "go through my comments", and the agent knows which document, which section and which words you mean. It works with any tool that speaks the Model Context Protocol (MCP).

What it shares, and how it stays in your hands:

• Off until you turn it on, per project. Choose Share this project with agents in Settings → Integration → Agent connection, or run Agent connection: turn on from the command palette. Nothing inside a project can turn it on.
• Local. It talks only to programs on your computer and opens no network port.
• Read, never edit. The agent sees where you are, what you selected, what changed, your comments and the notes you shared one by one. It reads, shows you a place and marks comments done. It never edits a file through PerMark.
• Your limits. You choose what it may do, group by group. Files in .aiignore never reach an agent. Secret values are hidden by their key names; a secret inside ordinary text is not recognized, so list such files in .aiignore.
• Visible. While the connection is on, the status bar shows Agent. Click it to see what is shared and the latest requests.

Connect in two lines. Turn the connection on, then add PerMark to your agent as an MCP server. Settings → Integration → Agent connection shows these lines with the right path for your copy, and a Copy button.

# Claude Code
claude mcp add permark -- "<path to PerMark>" mcp

{ "mcpServers": { "permark": { "command": "<path to PerMark>", "args": ["mcp"] } } }

The second form fits any other MCP client. With the connection on, Hand off to agent copies one line for your prompt, so the agent asks PerMark what you did instead of rereading the project.

What an agent can do: the 13 tools

Answers are short on purpose: a header line, then tab-separated rows, so an agent spends few tokens. A project's .permark/ folder can narrow what an agent may do, never widen it. When PerMark is closed, the other tools still work from the files, and open starts it. With the connection off, every tool says so and explains how to turn it on.

Add what you are reading to every prompt: permark context

permark context prints where you are as one short line and exits, for tools that can run a command before each prompt:

Viewing docs/plan.md › Plan › Rollout (lines 40-62), selected (lines 44-46): 'ship it on Friday', 2 comments open.

In Claude Code, a UserPromptSubmit hook in .claude/settings.json (or your user settings) adds it to every prompt:

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "\"<path to PerMark>\" context" }] }
    ]
  }
}

When there is nothing to say (the connection is off, or PerMark is not open), the command prints nothing, so a hook never adds noise to a prompt. A project with a .permark/ folder also has .permark/local/agent-context.json while the connection is on: the same answer as a file, for a script or a tool without MCP. It holds the open document, the section on screen and your selected text, and any program running as you can read it, as can a folder-sync tool that watches the project. It stays out of git and is deleted when the connection is turned off.

Keyboard shortcuts

The ten that matter most. On macOS, use Cmd where this README says Ctrl (except Ctrl+Tab and Ctrl+Shift+Tab).

All of them, and you can change them, in Settings → Keyboard shortcuts.

All default shortcuts

Reading and navigating

Tabs

Review

Editing

Notes and the Explorer

What's new and ideas being explored

PerMark 0.6 rebuilt the whole program. Every release is in the CHANGELOG.

• 0.6.2: a Notes button next to Settings, keys to hide and show the side bars, files dropped from your file manager copy into the project or open as tabs, Move to window for a tab, and every plugin on from the start.
• 0.6.1: every folder, file and Notes gets a tab, and your windows and tabs come back when PerMark starts.
• 0.6.0: many windows in one app, a full Settings page, a Plugins page and keys you can change.
• Config files and TOON as clean sheets, AI files recognized with no setup, and prompt blocks.
• Review of code and text files, line by line, with keep or revert.
• An agent connection with 13 tools, permission groups, .aiignore and Hand off to agent.

Ideas being explored, no promises: a home for structured work with AI, such as spec-driven development, for the projects that want it; ready-made ways of working to adopt, such as Spec Kit templates; and a shared place where people and always-on agents follow and review the work together, with the person in charge.

Tech

PerMark is a Tauri 2 app. The core is written in Rust: rendering (comrak and ammonia), file watching (notify), git (the one on your computer, or a built-in libgit2 when there is none), the search index and the block-preserving saves. The interface is Svelte 5 and TypeScript in the system webview, with CodeMirror 6 (Source) and Milkdown (Edit).

Contributing

Issues and pull requests are welcome. The project uses git-flow (develop for integration, feature/* branches) and a strict quality gate:

cd app
npm run check   # version, rustfmt, prettier, build, clippy -D warnings, svelte-check, cargo test, vitest

See CONTRIBUTING.md before opening a pull request. It also explains how to fix or add a translation.

License

Copyright (c) 2026 Edelmar Schneider. Licensed under either of MIT or Apache-2.0, at your option.

"PerMark" and its logo are trademarks of Edelmar Schneider: forks are welcome under a different name. See TRADEMARKS.md.