PerMark v0.7.0

PerMark is a free, open-source unified document workspace: one place to read, write and organize Markdown and
the files around it, and to steer AI projects through their documents. AI speeds the work. Your vision steers it.
It works with any AI tool, or none: it only relies on your files and git.

Added

• Projects inside a folder. When a folder you open holds other projects (folders with their own git repository or their own PerMark settings), a quiet note under the file list says so once and offers to include them, to choose, or No thanks; a short message with Undo follows your answer and then closes by itself. Included projects are followed from that folder: their changes and unread documents show there, and the file list marks each one with a project icon next to its folder name (and its short name when that is different). Resting the pointer on it, or choosing Project details in its menu, shows a small card about it. The new Settings > Projects inside lists every project found, included or not, with a filter, buttons to include or leave out all the projects listed, and for each included project its details and rules: hidden files, the agent, notifications, and its name and description. Projects that went missing can be located again or removed from the list, with Undo. When new projects appear, the note says where they are; when the folder's project list can't be read, the note says so and shows you the problem. The Changes panel says which project a change belongs to and lists projects that appear, move or go away (a project that went missing opens its place in Settings), and the Search panel can look in the whole folder or only in the project of the open document, and its search box says which. Before you answer, the note and the Choose page say that the list is saved in the folder (.permark/projects.toml), so it travels with it; a project's name and description are saved in that project's own .permark/project.toml, as the fields say. A folder without projects looks exactly as before, and a folder opens as fast with a long project list as without one: PerMark reads the projects right after the folder shows.
• Git for each project inside a folder. An included project with its own git repository now keeps its own git status in the folder that includes it: its changed files belong to that project, no longer to the outer folder, and comparing one of its documents with "the last commit" uses the project's own repository. PerMark reads each project's branch from its files at once and asks git about changes only when they matter (the project's files change, or you look at the project), a few projects at a time, so a folder with dozens of projects stays fast. PerMark also notes each project's first commit in the folder's project list, so a project you moved or renamed while PerMark was closed is found again the next time you open the folder: PerMark asks you first, naming the folder it found ("Is tools/new-app the project hub-x that was at hubs/hub-x?"), because copies of a repository look the same to it, then says what it did and puts you on that folder in the file list. A copy you said no to is never offered as the moved project, and when you answer that a folder is a new project, PerMark remembers it and does not ask again, also after a restart. In the file list, each such project shows its branch in gray after its name, with a small branch mark so it reads apart from the project's own short name, also before the project's first commit (or what git is doing there, such as REBASING, which is never cut short, or, when it is not on a branch, the commit it is at with a commit mark, its meaning in the tooltip), a warning mark when git can't read the project, and an open project marks its changed files as the outer folder's files are marked; in a narrow sidebar the branch steps aside. Its card adds the branch, the changes to send and to get as of the last fetch (↑ ↓), how many files changed and its last commit ("No commits yet" in a new repository), and a screen reader hears these when the card opens. Wherever a label such as MERGING or REBASING appears, its tooltip and screen readers say what it means in plain words, such as "A merge was started in git and isn't finished yet." Settings > Projects inside shows the branch and the number of changed files on each row ("Checking git…" while PerMark is still asking), and the status bar follows the project of the document you are reading, with the project's short name before its branch; choosing "Changes since: the last commit" there applies to that project's files too. When git is not available, no branch is shown anywhere and Settings says so once.
• Each project keeps its own reading state. In a folder that includes other projects, what you have read, your comments, the tags and descriptions you add, the folders you silence and the record of what you did now belong to the project the file is in. They are saved where that project keeps its own PerMark data: its .permark/ folder when it has one, otherwise your profile. So you see the same unread documents, comments and silenced folders whether you open the project on its own or from the folder that includes it, and the same tags you add from now on. What the folder already knew about a project's files (what you read, comments, silenced folders) is copied into that project's private data the first time you open the folder with this version or include the project; the project's own entries win, and the folder's own copy stays as it was, ready again if you leave the project out. Something added in the folder while a project was left out, such as a new comment, is copied too when you include the project again, and something you removed inside the project does not come back. Tags and descriptions the folder already kept for a project's files stay in the folder's own .permark/meta.toml and still show there; PerMark does not write them into the project's shared files. A folder silenced in the outer folder stays silenced inside its projects unless a project says otherwise. When a project without a .permark/ folder moves, its saved state moves with it. A folder can now also name its official tags and project categories, with their colors and icons, in .permark/vocabulary.toml. Where it does, every tag in the Tags tab, the tag editor and the tags under a document's title carries a small mark that says whether it is official, local to one project, or unlisted (found only in files); the shape of the mark and its words say it, not only its color, and the Tags tab explains the three marks at its top and also lists the official tags no file uses yet. A local or unlisted tag can be made official with the "Make official" button on its row or in its color and icon menu: PerMark first says what this does and which file it writes, and does nothing until you confirm. A project's category is offered from the official list as you type (the official names are also written under the field; any other name is kept as you write it), shows the same mark, and can be made official the same way. Settings > Projects inside lists the official tags and categories: you can add one (with Undo), rename one, remove one (PerMark asks first) or change its color and icon, and the color and icon menu of an official tag leads there. PerMark changes only that entry of the file; the tags written in your documents and the categories of your projects stay as they are. Each included project's details say how many of its own tags count as local. A project's card now also counts its open comments next to its unread documents, and each count opens the Unread or Comments tab showing only that project. Tags written at the top of documents (front matter) now come from the same background reading as search, so PerMark no longer reads a large folder twice for them, and they show at once the next time you open it.
• The right panel can show its views one above the other or as tabs. The outline and Live changes share the right panel, one above the other by default, with a line between them that you can drag (or move with the arrow keys) to give one more room. Each view has a ⋯ menu to move it up or down, show it as a tab next to the other, close it, or reset the layout; "Reset the right panel layout" is also in the command list. Your layout is the same in every folder; which views are open is kept for each folder. When a document has no headings, Live changes takes the whole height. With only one view, the panel looks as before.
• In the outline, a small dot now marks each section that just changed: while an agent writes, and while you review the changes in a document. Screen readers hear "changed" with the heading.
• The file list's menu now also opens from the keyboard, with Shift+F10 or the Menu key, at the row you are on.
• Go to a recent place... in the command palette lists the last 30 places you visited in this window, newest first, the same list as the menu of the Back and Forward buttons. Type a few letters to narrow it, and press Enter to go back to that place.
• In the Notes tab, Ctrl+Shift+S moves the note you have open to a project (Move to project...), like "Save as" in other apps. Outside the Notes tab the key does nothing.
• The status bar now says Live: off when the folder you opened can't report its changes (for example when the system ran out of watches), so PerMark can't follow them as they happen. On Windows, WSL folders (such as \\wsl.localhost\...) now always say so, instead of silently showing no new changes; network shares and mapped network drives keep following changes live. It shows on the Live button itself when that button is there. Click it, or press Enter on it, to read why and what to do; the Live changes panel says it too, and screen readers hear it when it happens.
• Search results now show the same marks as the file list: the unread dot and the git letter, with their meaning in plain words when you rest the pointer on them. They appear in the Search panel, Quick open and Search everywhere.
• The Unread tab says that its list starts with the newest change.
• AI agents have their own place in Settings. Sharing a project with your AI agent is now set up in Settings > AI agents, no longer among the editor and update settings. The section says whether sharing is on for this project and what an agent can see, with one button, Share this project with agents. Once it is on, the steps to connect your agent are right below, Claude Code first, each with a Copy button, and the choices of what agents may do are folded under one line that says how many are allowed. The settings menu behind the gear button shows the agent connection's state in one row with Set up…, and the agent item in the status bar leads to the section too. Nothing turns on by itself: sharing stays off for each project until you press the button. With the Agent connection plugin off, the section and its row are gone.
• A project that holds files for AI agents (such as AGENTS.md, CLAUDE.md or a .claude folder) now shows one quiet note under the file list, once, offering to share what you read with your agent. Set up… opens Settings > AI agents, where you decide; No thanks closes the note. Either answer is remembered for that project in your profile, and the note never comes back; it does not appear either if you already turned sharing on yourself.
• Wrap long lines. Long lines in text files, logs and other files shown as text, in Source mode and in the review of code now wrap to the width of the window, so a log with very long lines reads without scrolling sideways. A wrapped line goes on a little to the right, and its line number shows once, on its first row; copying still gives the lines as they are in the file. It is on by default; turn it off in Settings > Reading > Wrap long lines, or switch it with Alt+Z (⌥Z on macOS, except while typing) or the command "Wrap long lines (on | off)", and the line at the top of the window stays in place. Very large files still open at once: even a single line of several megabytes shows only the rows on screen. Code blocks in a Markdown page keep their own sideways scroll.

Changed

• A document now counts as read after three seconds on screen, or as soon as you scroll it yourself, as in PerMark 0.5. Before, one second was enough, so a document that follow mode or a tab switch showed only for a moment lost its unread dot. The same rule decides when a code file counts as seen for the review of changes. Alt+U and the Unread tab now go from the newest change to the oldest, like new mail; before, they went in the order of the file names.
• Every installer now includes THIRD-PARTY-NOTICES.md, the licenses of the open-source software inside PerMark (Rust libraries, interface packages, fonts and libgit2), as free software asks. It is made again for each release from the versions that release contains, and sits in PerMark's own folder next to the program.
• When a folder you share with an agent holds other projects, the agent no longer sees the files inside them until you include those projects (see Projects inside a folder above); this holds for projects in visible folders too. For a project you include, the private files of its own .aiignore and [agent] settings are hidden from the agent as well as the folder's, and you can turn the agent off for that project alone. A project you open on its own keeps the files its outer folder hides from agents hidden. A project you said no to stays left out, even if the folder's project list names it later (the Changes panel tells you, and you can include it in Settings). While PerMark is still reading a folder it has just opened, the agent waits a moment instead of seeing it half read.
• Live changes are easy to find when they matter. In a folder with a git repository or with files for AI agents (such as AGENTS.md, CLAUDE.md or a .claude folder), the Live changes panel now shows by itself below the outline, so you see what an agent writes without looking for it. Close it once and PerMark remembers that for this folder; this also means that folders you already use show it once after this update. In a folder where nothing like that is found and nothing changes outside PerMark, such as your own notes, nothing new appears and the status bar no longer shows the gray "Live" item. From the first time something else changes a file there (an agent, a sync tool, a colleague), the "Live" item appears and stays for that folder, but the panel does not open by itself. The "Live" item counts the changes you have not seen yet ("Live · 3"), its dot is easier to see and stays lit for 30 seconds after a change, and the count clears when you look at the changes. The Live changes panel says when the last change happened, explains what it is for while it is still empty, and has a Follow button, so you can turn on follow mode without knowing its key. The note that says documents changed also offers Follow, and it stays while your pointer or keyboard is on it. While follow mode is on and you edit, the status bar says it is paused until you go back to reading.
• The Project section of the settings is now called This folder, so it reads apart from Projects inside in folders that hold other projects.
• When you create a new file in the file list, a line under the name field now says that .md is added and that a name ending in .txt makes a plain text file. A name with another ending now gets the plain message "End the name with .md or .txt."
• New project… now asks first when the folder you choose already has files in it, and says why in plain words: PerMark adds a .permark folder there, and your files are left as they are. Choose another folder… takes you back to the folder picker, which opens at the folder you chose. An empty folder is still set up and opened at once. In this question and in the Initialize PerMark question, the button that changes nothing now starts selected, so pressing Enter by mistake adds nothing.
• Code references such as docs/plan.md:12 or src/main.rs:40 now open where they make sense. A file PerMark can show (Markdown, text, settings and data files, pictures) opens in PerMark at that line, with the place tinted for a moment, and Back returns you to where you were. Code opens in your editor at the line when you have chosen one; when you haven't, PerMark shows the file at the line and says once how to choose an editor, instead of showing an error. Ctrl+click (Cmd+click on macOS) or Ctrl+Enter opens any reference in your editor. The tooltip of a reference says what a click does.
• The JetBrains choice in Settings > Editing > External editor is now called "JetBrains (IntelliJ, PyCharm, …)".

Removed

• Word suggestions beside the caret in Edit. Source still suggests files, headings and words as you type.
• The Ctrl+Shift+T key for the Tags view. Show the tags is still in the command palette, and you can give it a key in Settings > Keyboard shortcuts.
• The offer to set up PerMark in a git repository you open. Settings > This folder still has Initialize PerMark.
• The Explorer's Always select the opened file switch: the file list always shows the document you open.
• The folder menu on the project name at the top of the Explorer. Tabs and the + menu open, switch and close folders.

Fixed

• On Windows, folders on a network share or in WSL now show their usual path, such as \\wsl.localhost\Ubuntu-24.04\home\me\notes, in the list of recent folders, in the Notes "Move to a project" list and everywhere else PerMark shows a path. Before, these paths started with \\?\UNC\. Folders you opened this way before keep their reading state and appear once in the recent list.
• On Windows, a project folder can be renamed or deleted right after you close it. Before, a git check PerMark had started there could still be running for a moment, so Windows said the folder was in use.
• In text files, logs and other files shown as text, a password, key or token on a very long line (more than 4,000 characters, such as a minified config or a long log line) is now hidden like everywhere else, with long lines wrapped or not; with the syntax highlighting plugin turned off, such values are now hidden on every line too. Before, they showed in plain text.
• Screen readers now say what the marks on files mean, such as "Unread" or "Modified: this file changed since your last visit.", in the file list, the document header and search results. Before, they read only the letter or the dot.
• Small gray text in Quick open, Search everywhere and the command palette (folder names, group titles, "You are here") is easier to read.
• In the Windows installer, the list of file types to open with PerMark is no longer cut off or covered by the welcome text, in any of the six languages (it showed worst in Chinese, where the list heading was hidden behind the boxes and "Properties" lost its last letters). The welcome text is shorter, the sentence that says Windows asks you to confirm in its Settings now heads the list, and every box has room for its words. Thanks to the reporter of issue #58.
• Code files and code blocks no longer hide ordinary values as if they were passwords. Before, any name with "key", "token" or "auth" in it was enough, so a game's keys.left = true or keyJump showed masks all over the file. Now PerMark hides a value only when its name really names a secret (such as API_KEY, password, client_secret or GITHUB_TOKEN), and under such a name it hides the value whenever it could be one: in .env lines, connection strings, Authorization headers and curl commands too. Code like true, a function call or a sentence stays visible. It also hides well-known token formats wherever they appear, whatever their name (OpenAI, Anthropic, GitHub, GitLab, AWS, Google, Slack, Stripe and Hugging Face keys, web tokens), and the lines of a private key, also when only part of the key is shown. Agents get the same masks as you do.
• In the git pop-up of the status bar, the arrow keys now move between the two "Changes since" choices, Escape takes you back to the git item instead of losing your place, and a label such as MERGING is easier to read in the light theme.
• Esc now closes the review of changes, as the Done button's tooltip says. It still closes a menu, a dialog or a text field first when one of them is open.
• In a folder without git, "Compare with: the last commit" in the review is now shown as unavailable, and choosing it says why next to it. Before, it seemed to switch but kept showing the same changes.
• When you open the review from its bar with the keyboard, your keys now go to the review's own buttons; when you close it, they go back to the page, which shows a focus frame. Before, they were lost and the next Tab skipped the review's buttons.
• The Ctrl+Alt+E command is now called "Open Source mode" in the command list and the keyboard shortcuts, which is what it does. It was called "Switch between Edit and Source".
• Screen readers now read each checklist box in a document together with its task, not only "checkbox, checked".
• After you drop files onto the file list, the question that asks Copy here or Move here now takes the keyboard, so Enter copies at once.
• When you switch to another tab while the question about files you dropped on the file list is open, the question now waits in its own tab until you answer it, also when you click another tab. Before, it closed without a word and nothing was copied. If the question can no longer be answered, for example because another project opened in that tab, a notice says that nothing was added.
• "Choose a tokenizer" in the status bar is easier to read in the light themes.
• Small gray text is easier to read in the light and dark themes: the "EXPLORER" heading, the time a document was saved, the names of a document's properties, the outline heading and the app name.
• When a folder you open holds other projects in folders that its own .gitignore leaves out (for example a workspace that ignores projects/, where each project has its own git repository), PerMark now follows what changes inside those projects as it happens: the Changes list, the highlights of changed passages, follow mode, unread markers, search and the file list stay current, and open documents reload. Projects you add, remove or rename while the folder is open now appear or go away without opening the folder again. Before, everything inside them stayed as it was when the folder was opened.
• A project you included keeps its place when you rename its folder or move it to another folder inside the opened folder while PerMark is open, also in Windows File Explorer: it stays included under its new name, and the Changes panel shows one "moved" line. Before, PerMark took it for a project that went away and a new one that appeared, and offered to include it again. This also holds when the system reports the move in two parts, as macOS sometimes does: PerMark waits about two seconds before it says that a project went away, so a move never shows as a project that went away and a new one, not even for a moment. When you change only the capital letters of its name, the project list follows the new spelling. Locate… for a project that went missing now opens the folder picker in the folder where the project was, or in the opened folder when that one is gone too, instead of the last folder the system picker showed.
• Closing a tab or a window, or opening another folder in it, no longer gets stuck when PerMark is still reading a large folder for search. Before, that could happen now and then, and the folder was never let go.
• When a question about files you dropped on the file list had to close because another project opened in that tab, the notice now says why and names the project, and that you can drop the items again. When you drop again, that notice goes away, so it no longer stands next to the result of the new drop. After you answer the question, your keys go to the file list when they had no place before (a drop from another app), instead of being lost.
• When you close the review of changes with Done or Esc while changes are still in it, a short message now offers Review again, which opens the review at the change you were on. The message stays until you dismiss it (its button, or Esc while it has the keyboard), open another document or open the review again, which also takes you back to that change. Before, one stray Esc was enough to lose the review: the bar that offered the changes did not come back, and opening the review again started at the first change.
• When you open the review of changes from the command palette, your keys now go to the review's own buttons, as they do when you open it from its bar. Before, they went back to the file list.
• In the review, the arrow keys now move between the two "Compare with" choices, which take one Tab stop instead of two, and screen readers now hear when the comparison changes and how many changes there are to review.
• The # link of a heading is no longer cut off at the edge of the page or hidden under the side panel when it has the keyboard: it then shows just left of the heading, and the heading text does not move.
• In the command palette, you can now type a shortcut, such as ctrl+alt+e (or ⌥⌘E on a Mac), to find the command on those keys.
• Changing a setting of a project no longer puts it at the top of .permark/config.toml, above the comments that explain the file: the comments stay first and the setting goes below them. Clearing the setting again leaves the comments as they were.
• In a row of choices in the settings (such as the theme), Alt, Ctrl or Shift with an arrow key no longer changes the choice; only the arrow keys alone do.
• The back and forward side buttons of the mouse work again: they go back and forward through the documents you viewed, like Alt+Left and Alt+Right and the Back and Forward buttons. They work while you read, in Edit and Source, and with the pointer over the side panels; they do nothing while a dialog or the search box is open.
• In a window with a single file, links to other documents work again: a link to a Markdown or text file in the same folder, or in a folder below it, opens in the same tab, and Back and Forward take you between them; the tab and the window title name the file you are reading. A link that leads outside the file's folder says so and offers to open the nearest folder that holds both files, showing the linked document there. A link to a folder, or to a file PerMark doesn't show itself, says that it opens when the folder is open, with a button that opens it. Code references such as docs/plan.md:12 work in these windows too, for files in the same folder or below.
• When an agent names itself in a request, PerMark now always shows and records that name. Before, the name it gave when it connected could sometimes replace it a moment later.
• Agents now read a whole file more reliably. The description of the agent's read tool now says plainly that leaving out the part reads the whole file; some smaller AI models used to ask for a part called "none" or "all" and got nothing back.
• On Windows, renaming, moving or deleting a project folder right after PerMark stopped asking git about it (for example after you close the folder or leave the project out) no longer fails because the folder is "in use". Before, a git program that PerMark had stopped could keep running in that folder for a few seconds.

Known limits

• PerMark 0.7 was tested by hand on Windows. The macOS and Linux versions are built and checked by the project's CI and have not been tested by hand yet.
• Some network file systems do not report changes, and PerMark cannot always tell. If new files do not appear in such a folder, reopen it. For folders inside WSL, PerMark knows this and shows Live: off in the status bar.
• Edit mode still does not draw pictures that are files next to the document (View and Source do).
• In a very large folder that holds many projects, PerMark can use more memory while idle than in a small one (we measured 300 to 380 MB on such a folder, against a goal of 250 MB).
• Secret values written in some forms are not masked yet: a password inside a curl -u argument, a .netrc file, a call such as setPassword(...), a Markdown table cell, or a multi-line password: | value.

Install

Platform	Download
Windows	the -setup.exe installer (recommended). The .msi stays for updating copies that were installed from a 0.5 .msi
macOS	the universal .dmg (Apple silicon and Intel)
Linux	the .AppImage, .deb or .rpm

PerMark updates itself: when a new version is out, it offers a one-click "Restart to update".

The app is not code-signed yet

The installers are unsigned, so your system warns you the first time. They are built by GitHub Actions
from the tagged commit, and the in-app updates are verified with a signature.

Windows (SmartScreen). If you see "Windows protected your PC", click More info, then Run anyway.

macOS (Gatekeeper). If macOS says it can't verify PerMark, open System Settings, Privacy & Security,
scroll to the Security section and click Open Anyway. On older macOS versions you can right-click the
app and choose Open instead. From a terminal: xattr -dr com.apple.quarantine /Applications/PerMark.app.

Linux. Make the AppImage executable (chmod +x PerMark_*.AppImage) and run it, or install the .deb / .rpm.