PlanCake

User Manual

Welcome to PlanCake

PlanCake lets you read Markdown files comfortably and leave notes right where they belong. It shows a file the way it is meant to be read: real headings, lists, tables and code blocks instead of hash signs and asterisks. It was made for the long implementation plans that AI coding assistants write — often 800 lines and more — but it works with any Markdown file.

Reading is half of reviewing. The other half is saying what you think: “this step is wrong,” “do this one first.” In PlanCake you click the paragraph, list item, heading, table row or code block you want to comment on, or press Enter on it, and type your note. PlanCake writes it straight into the Markdown file, right after that block, between a pair of markers. You never count lines or work out where the note goes — PlanCake knows which lines of the file each block came from. Whoever reads the file next, a colleague or an AI assistant such as Claude, finds your notes exactly where they belong.

A few things to know up front. PlanCake is not a text editor: apart from your notes and task-list checkboxes, it never changes the text of a document. There is nothing to save — every note is in the file the moment you confirm it. PlanCake runs on Windows 10 and 11 (64-bit), and everything in it works equally well with the mouse, from the keyboard alone, and with a screen reader.

Quick start

  1. Open a plan: start PlanCake from the Start menu and drag a Markdown file onto its window, or press Ctrl+O and choose the file. From a command prompt, plancake plan.md does the same.
  2. Read it. Headings, lists, tables and code show up formatted; scroll with the mouse wheel or the arrow and page keys.
  3. When you reach something you want to comment on, click it. From the keyboard, press Alt+Shift+Down Arrow or Alt+Shift+Up Arrow to move from block to block until it is outlined, then press Enter. The Add note dialog opens with the cursor in the note box.
  4. Type your note and press Enter, or click OK. The note appears right after the block, and the status bar says “Note added”. It is already in the file.
  5. Carry on reading and adding notes. When you are done, close the window — there is nothing to save.

Installing PlanCake

PlanCake comes in two forms: an installer, which sets everything up for you, and a portable version, which runs from any folder, including a USB stick. Both work the same way once running; they differ only in where PlanCake keeps its settings. Download either one from the PlanCake website.

With the installer

Run the installer and follow its steps. Besides PlanCake itself, it takes care of what PlanCake needs to run: it installs the .NET 10 Desktop Runtime and the Microsoft Edge WebView2 Runtime if your computer does not have them yet. It also adds PlanCake to your PATH, so the plancake command works in any new PowerShell or Command Prompt window.

Your settings are kept in %APPDATA%\Oire\PlanCake.

The installer adds PlanCake to the Start menu, together with a shortcut to this manual in the language you chose for the installer.

PlanCake is not signed with a code-signing certificate. The first time you run the installer, or plancake.exe from the portable zip, Windows SmartScreen may show “Windows protected your PC” and an unknown publisher. To go on, choose More info, then Run anyway.

The portable version

Unpack the zip file into any folder and run plancake.exe from there. The zip includes an empty folder named userdata next to plancake.exe; as long as that folder is there, PlanCake keeps its settings inside it and writes nothing to your user profile. Delete or rename the userdata folder and PlanCake goes back to using %APPDATA%\Oire\PlanCake.

The portable version does not install anything, so your computer needs the .NET 10 Desktop Runtime and the Microsoft Edge WebView2 Runtime already. Windows 11 comes with WebView2; if it is missing, PlanCake tells you so when it starts and offers to open the download page.

To use the plancake command with the portable version, either type its full path or add its folder to your PATH yourself.

Uninstalling PlanCake

Uninstall PlanCake from Apps in Windows Settings, or with Uninstall PlanCake in the Start menu. The uninstaller takes PlanCake off your PATH and asks whether to remove your settings and logs as well; your Markdown files and the notes in them are never touched. The portable version installs nothing: to remove it, delete its folder.

If you work in a standard Windows account and an administrator types their password to allow the uninstall, the uninstaller runs as that administrator and looks for the administrator's settings, not yours, so it does not ask about them. Your settings and logs then stay in %APPDATA%\Oire\PlanCake and %LOCALAPPDATA%\Oire\PlanCake; delete those folders yourself if you no longer need them.

A shorter command: pk

If you open plans from the command line all day, you can give PlanCake a two-letter name. PlanCake does not set this up for you; it is one line in your own shell profile.

After that, pk plan.md opens a plan, and every command in Working from the command line works with pk in place of plancake.

The main window

The window has a menu bar at the top, the document on the left, the notes list on the right, and a status bar at the very bottom. The title bar shows the name of the open file, for example plan.md - PlanCake.

To give the document or the notes list more room, drag the border between them. From the keyboard, choose Wider notes list or Narrower notes list in the View menu: each moves the border by a tenth of the width the two share, to a round figure — from 32 percent, for example, the list becomes 40 percent wide, or 30 percent. The status bar tells you the new share, such as “Notes list 40%”. Neither side can shrink away: the list stays at least about 150 pixels wide and the document about 200. At that limit the border stays put, and the status bar repeats the current share. Both commands are unavailable while the notes list is hidden.

PlanCake remembers the window’s size and place, whether it was maximized, the width of the notes list and the zoom: the next window opens the same way, on a screen that is still there. The very first window fits the screen it opens on.

The document

This is your Markdown file, formatted. When PlanCake opens a file, it starts at the top. Your notes appear inside the document too, each right after the block it belongs to and set apart from the text of the plan, so you can see at a glance what is yours.

The notes list

The notes list gathers every note in the file in one place, in the order they appear. It has three columns:

Note
The first sentence of the note, on one line, without Markdown punctuation. The column takes all the width the other two leave. Rest the mouse pointer on a row to see the whole note.
Lines
Where the note sits in the file: 12 for a one-line note, 12-14 for a longer one.
Block
The first sentence of the block the note follows, so you know what it is about without going there. In both columns, a very long sentence is shortened at a comma, colon or dash where it can be.

To go to a note in the document, press Enter on its row or double-click it; focus moves to the note. To delete a note, select it and press Delete; the selection then moves to the nearest remaining note, so you never lose your place in the list. Right-click a row, or press the Applications key or Shift+F10, for a menu with Edit note and Delete note.

If you would rather have the whole window for the document, choose Notes list in the View menu. It hides the list, and choosing it again shows it; the status bar says “Notes list hidden” or “Notes list shown”. PlanCake remembers the choice: this is the same switch as Show the notes list in Settings, so new windows open the same way, and other open windows follow as soon as you switch to them.

Moving between the document and the list

Click wherever you want to work, or press F6 to jump between the document and the notes list. If the list has no notes, the status bar says “No notes”.

Tab works too: pressing Tab past the last link or checkbox in the document takes you into the notes list, and Shift+Tab from the first one does the same. From the list, Tab and Shift+Tab take you back to the document.

When the notes list is hidden, both F6 and Tab keep you in the document. F6 moves focus; it does not bring a hidden list back. Use View, Notes list for that.

Status messages

Nothing PlanCake does happens silently. Every change — a note added, a task checked, a file reloaded, a download finished — is confirmed by a short message in the status bar at the bottom of the window, such as “Note added” or “File reloaded”. The message stays there until the next one replaces it.

Questions PlanCake asks

When PlanCake asks you a yes-or-no question — delete this note? check this task? reload this file? — pressing Escape answers No, and so does closing the question with its close button. You can always back out without choosing anything.

In the other dialogs — Add note, Settings, Open from link — Escape is the Cancel button: it closes the dialog and discards what you typed. In Keyboard shortcuts and About PlanCake, Escape simply closes them.

Using a screen reader

PlanCake was built with screen readers in mind, and a few details are worth knowing if you use one:

Opening a file

Plans reach you in many ways: a file on disk, a path someone pasted in a chat, a link to GitHub. PlanCake can open all of them directly, without you saving anything first. Whichever way you use, a newly opened file always starts at the top.

When no file is open, the window lists the ways to open one, with their keys. A large file can take a moment to open: if it takes more than half a second, or the file is larger than 1 MB, PlanCake shows the Opening a file dialog with a progress bar. Press Escape or click Cancel to stop; the file you had open stays as it was.

From the command line

Type plancake followed by the file:

plancake docs\plans\001-plan.md

A window opens with that file. Type just plancake for an empty window. You can also drag a Markdown file onto plancake.exe or a shortcut to it.

From the Open dialog or by dragging

Drag a Markdown file from File Explorer and drop it onto the PlanCake window. Or press Ctrl+O, or choose Open in the File menu: the standard Windows Open dialog shows Markdown files (.md and .markdown); switch the file type to All files to see everything.

From the clipboard

Press Ctrl+V in the PlanCake window, or choose Open from clipboard in the File menu. PlanCake looks at what you copied:

If the clipboard holds anything else, the status bar says “The clipboard holds no Markdown file or link.”

Say a colleague sends you a link to a plan on GitHub. Press Ctrl+L, or choose Open from link in the File menu. The Link box is already filled in if the clipboard holds a link; otherwise paste or type it. Press Enter or click OK to download; press Escape or click Cancel to give up.

The status bar shows “Downloading from github.com...” and, when the download is done, where the file was saved; then the plan opens. Downloads go to your Windows Downloads folder under the file's own name, always as a Markdown file: a link to a file of another type gets .md added, so tool.bat is saved as tool.bat.md and can never run. Like a browser, PlanCake marks the file as downloaded from the internet; if a file of that name is already there, PlanCake adds a number, such as plan (2).md, the way a browser does. Because the downloaded file is an ordinary file on your disk, your notes are saved in it like in any other.

A few things to know about links:

One window per file

Each file gets its own window, and a file is never open in two windows at once. If you open a file that is already open in another PlanCake window — from the command line, the clipboard, anywhere — PlanCake brings that window to the front instead of opening a second one. This way two windows can never write conflicting notes into the same file.

Reading a document

Moving around

Scroll with the mouse wheel or the scroll bar, or use the arrow keys, Page Up, Page Down, Home and End. Tab moves from link to link and from checkbox to checkbox. Select text with the mouse and copy it with Ctrl+C as in any other program; finishing a selection never opens the note dialog.

To work on a particular block from the keyboard — a paragraph, heading, list item, table row, code block or note — press Alt+Shift+Down Arrow for the next block and Alt+Shift+Up Arrow for the previous one, or choose Next block and Previous block in the Notes menu. The block gets an outline and scrolls into view. Press Enter to add a note to it (or edit it, if it is a note), or the Applications key for its menu. At the start or the end of the document, the status bar says “No more blocks”.

The move starts from the block or note you last worked on or moved to. If there is none yet, Alt+Shift+Down Arrow goes to the first block you can see and Alt+Shift+Up Arrow to the last. In the notes list, these keys move to a block in the document and put you there.

Click a link, or press Enter on it, and PlanCake does what makes sense for where it points:

PlanCake remembers the files you opened in a window and where you were in each, like the history of a browser. Press Alt+Left Arrow or Backspace, or choose Back in the View menu, to go back to the previous file, exactly at the spot you left it. Alt+Right Arrow or Forward goes forward again. At the ends of the history, the status bar says “No previous file” or “No next file”. If a file in the history has since been deleted, PlanCake says so and skips it.

Opening a file in any other way — with Ctrl+O, by dragging, from the clipboard, from a link — also adds it to the history, so Back always brings you back to what you were reading before.

Zooming

To make the text larger, press Ctrl+Plus; to make it smaller, press Ctrl+Minus. The keys on the numeric keypad work too, and so do Zoom in and Zoom out in the View menu. Each step changes the size by 10 percent, between 50 and 300 percent, and the status bar shows the new size, for example “Zoom 120%”. Press Ctrl+0 to go back to 100 percent. The next window you open starts at the same zoom.

The document's language

PlanCake keeps two languages apart: the language of its menus and dialogs, and the language the document is written in. Switching the interface to French does not make an English plan French. The document language matters when the plan is read aloud (see Using a screen reader) and helps PlanCake recognize old file encodings (see Files that are not in UTF-8).

New documents use the Document language from Settings, English unless you change it. To set another language for one particular file, choose Document language in the View menu and pick it. This applies to the open file only; the next file you open uses the language from Settings again.

Leaving notes

Adding a note

  1. Click the paragraph, heading, list item, table row or code block you want to comment on. The block under the mouse pointer is highlighted, so you can see which one a click adds a note to. From the keyboard, move to it with Alt+Shift+Down Arrow or Alt+Shift+Up Arrow (see Moving around) and press Enter. The Add note dialog opens. It shows the beginning of the block under Note on, so you can check you picked the right one, and puts the cursor in the Note box.
  2. Type your note. To start a new line inside it, press Ctrl+Enter.
  3. Press Enter or click OK to save; press Escape or click Cancel to give up. OK stays unavailable while the box is empty, and pressing Enter then says “Type a note first.”

PlanCake writes the note into the file at once, right after the block. The document updates, the status bar says “Note added”, and the new note is where you are now. It also appears in the notes list.

A single click is all it takes; double-clicking does nothing more than a single click. Selecting text with the mouse does not open the dialog, so you can still select and copy text as usual.

If you prefer Enter to make a new line and Ctrl+Enter to save, change Enter in the note dialog in Settings. If you would like a click or Enter on a block to open a menu rather than the dialog — for example, because you often click to place yourself and add notes by accident — change Enter or a click on a block. Both are described in Notes settings.

You can also add a note through the context menu: right-click a block, or press the Applications key or Shift+F10 on it, and choose Add note.

Editing a note

Click the note in the document, or move to it with F9 or Alt+Shift+Down Arrow and press Enter. The same dialog opens, titled Edit note and filled with the note's text. Change it and save; the status bar says “Note edited”.

You can also open a note for editing from the notes list, through the context menu, or with Edit note in the Notes menu.

Deleting notes

To delete one note, select it in the notes list and press Delete. Or right-click the note, in the document or in the list, or press the Applications key or Shift+F10 on it, and choose Delete note. PlanCake asks “Delete this note?” and shows its text; click Yes or press Enter. The status bar says “Note deleted”. If you would rather not be asked every time, turn off Ask before deleting a note in Settings.

To remove every note from the file at once — say, after the plan's author has worked through all of them — choose Delete all notes in the Edit menu. PlanCake always asks first, with the number of notes, whatever the setting says.

Moving from note to note

Press F9 for the next note and Shift+F9 for the previous one, or use Next note and Previous note in the Notes menu. In the document, this takes you to the note; in the notes list, it moves the selection. After the last note or before the first, the status bar says “No more notes”.

Undoing a change

Press Ctrl+Z to undo and Ctrl+Y to redo, or use Undo and Redo in the Edit menu. This covers everything PlanCake writes: adding, editing and deleting notes, deleting all notes, and checking or unchecking tasks. The status bar tells you what was undone or redone, for example “Undone: note added” or “Redone: task checked”, and “Nothing to undo” when there is nothing left.

Undo works only while the file still holds what PlanCake last wrote. If something else has changed the file since, PlanCake does not undo over that change; it says “The file changed, so there is nothing more to undo or redo.”

Formatting inside a note

You can use Markdown in a note: emphasis, inline code, links, lists, even a code block. In the document the note is shown formatted, while the file keeps exactly what you typed.

Two exceptions keep the plan's structure intact. A heading you type in a note is shown as bold text, not as a real heading, so your notes never mix with the plan's own headings. And HTML tags you type are shown as plain text.

A note cannot contain its own closing marker, [/usernote] by default, because that would end it early. If you use a single marker with no closing one (see Notes settings), a note cannot contain that marker, because it would start a second note. If you type either, PlanCake keeps the dialog open and tells you why.

What a note looks like in the file

Notes are plain text in your Markdown file, wrapped in two markers. A note on a paragraph looks like this:

Back up the database before you run the migration.
[usernote]Also back up the uploads folder.[/usernote]

Anyone who opens the file in a text editor, and any tool that reads it, sees your notes. You can even write notes by hand in the same form, and PlanCake shows them like its own. To use different markers, see Notes settings.

Markers inside code are not notes: between backticks, as in `[usernote]`, or in a code block. Nor are markers in raw HTML: inside an HTML comment, <!-- … -->, or in a <pre>, <script>, <style> or <textarea> block, from its opening tag to its closing one. If the Opening marker itself starts with <!--, markers inside comments still count as notes. A plan or a manual that shows the markers as an example keeps them as they are, and the window and the commands all leave them alone. PlanCake itself never writes a note inside code: a note on a code block goes on the line after it.

Copying the text of a block

To copy a paragraph, list item or other block without its Markdown punctuation, right-click it, or press the Applications key or Shift+F10 on it, and choose Copy block text. The status bar says “Block text copied”.

Checking off tasks

Many plans contain checklists — lines such as - [ ] Write the tests in the file. PlanCake shows them as real checkboxes, so you can tick off steps as you go without opening an editor.

  1. Click the checkbox, or press Space or Enter on it.
  2. PlanCake asks “Mark this task as done? The file on disk will be changed.” (or “Mark this task as not done? The file on disk will be changed.” for a checked task) and shows the task. Click Yes or press Enter. If you answer No, the checkbox stays exactly as it was.
  3. PlanCake writes [x] or [ ] on that one line of the file. You stay on the checkbox, and the status bar says “Task checked” or “Task unchecked”.

If you check tasks often and don't need the question, turn off Ask before checking or unchecking a task in Settings. Ctrl+Z undoes a check like any other change.

A task with sub-tasks, some done and some not, is shown as partially checked. That is only a display: Markdown has no third state, so nothing is written for it. Checking such a task marks only that task itself as done — the lines of its sub-tasks are never touched.

When the file changes outside PlanCake

A plan under review rarely stands still: an AI assistant updates it, a colleague edits it, version control brings in a new revision. PlanCake notices when the open file changes on disk and reloads it at once. The status bar says “File reloaded”, and you stay where you were reading — the page is updated in place rather than jumping back to the top.

If you would rather decide yourself, set When the file changes on disk to Ask before reloading it in Settings. PlanCake then asks whether to reload. If you say No, it tells you that F5 reloads the file whenever you are ready.

If the file is deleted, renamed or moved away, PlanCake tells you, and note commands are unavailable until the file is back. When it reappears at the same place, PlanCake says it is back and reloads it.

PlanCake never overwrites a change it has not seen. Suppose the file changes while you are typing a note. When you save, PlanCake refuses to write, shows the file as it is now, and says “The file changed. Please try again.” Nothing is lost on either side: add your note again, and it goes into the current version of the file.

Files that are not in UTF-8

Almost every Markdown file today is in UTF-8. Older files, especially in languages such as Russian or Hebrew, are sometimes saved in a legacy Windows encoding instead. PlanCake opens and shows them correctly, but by default it does not write to them: the file opens read-only, and PlanCake tells you so, naming the encoding, for example “This file is not in UTF-8, so it was opened read-only as Windows-1251. Notes cannot be added to it. To convert it to UTF-8, turn on converting files that are not UTF-8 in the settings.”

To add notes to such files, turn on Convert to UTF-8 on opening in the Advanced settings. PlanCake then converts each such file to UTF-8 the moment you open it and tells you, for example “The file was converted from Windows-1251 to UTF-8.” Only the encoding changes; the text and the line endings stay the same.

Sometimes PlanCake cannot tell for sure which encoding a file uses. Such a file always stays read-only, whatever the setting says: “The encoding of this file could not be recognized, so it was opened read-only and is never changed. Notes cannot be added to it.” This is a firm rule. Writing a file that was not read correctly would destroy the characters PlanCake could not make out, and PlanCake never does that.

The Document language setting is one of the clues PlanCake uses to recognize a legacy encoding, so setting it to the language your old files are written in helps.

Settings

Press Ctrl+Comma, or choose Settings in the File menu. The settings are on three tabs, General, Notes and Advanced; click a tab, or move between them with Ctrl+Tab and Ctrl+Shift+Tab. Click OK to apply your changes — they take effect at once, without restarting PlanCake — or Cancel (Escape) to discard them.

General

Interface language
The language of menus, dialogs and messages: English, Русский (Russian), Українська (Ukrainian), Français (French), עברית (Hebrew) or Deutsch (German). System default, the default, follows your Windows language, and uses English if Windows is in a language PlanCake does not have. In Hebrew, the whole window is laid out right to left. You can also switch it from Interface language in the View menu. This setting does not change the document language.
Document language
The language PlanCake assumes a newly opened document is written in. Default: English. It never follows the interface language or Windows. See The document's language.
When the file changes on disk
Reload it (the default) reloads the file as soon as something else changes it. Ask before reloading it asks you first. See When the file changes outside PlanCake.
Ask before deleting a note
On by default. Turn it off to delete single notes without a question. Delete all notes always asks.
Ask before checking or unchecking a task
On by default. Turn it off to check tasks with a single click or key press.
Show the notes list
On by default. Turn it off to hide the notes list in this window and in every other one. It is the same switch as Notes list in the View menu: changing one changes the other.
Check for updates on startup
On by default. PlanCake checks once when it starts and stays silent unless there is a new version.
Check for updates in the background
How often PlanCake checks again while it keeps running: Once a day, Every 3 days, Once a week (the default), Once a month or Never. Never turns off only these repeated checks, not the check on startup.

Notes

Opening marker
The text a note starts with in the file. Default: [usernote]. It cannot be empty, cannot start or end with a space or a double quotation mark, and cannot contain a line break.
Closing marker (leave empty for a single marker that runs to the end of the line)
The text a note ends with. Default: [/usernote]. It follows the same rules and must differ from the opening marker. If you leave it empty, a note runs from the opening marker to the end of its line; notes are then always one line long, and any line breaks you type in a note become spaces. If the markers break one of these rules, the line under them says why, starting with “Error:”, and a screen reader reads it out as soon as you pause typing.
Enter or a click on a block
Adds a note (the default) opens the Add note dialog. Opens the context menu shows the block's menu instead, where you choose Add note or Copy block text; choose this if you find yourself adding notes by accident. A click or Enter on an existing note always opens it for editing, and a right-click, the Applications key and Shift+F10 always open the menu.
Enter in the note dialog (Ctrl+Enter does the other)
Saves the note is the default. Starts a new line suits long notes with several paragraphs. Whichever you choose, Ctrl+Enter does the other thing.

Advanced

Convert to UTF-8 on opening
Off by default, so files in legacy encodings open read-only and are never changed. Turn it on to have PlanCake convert a file that is not in UTF-8 to UTF-8 without a byte order mark (BOM) when you open it, so you can add notes. The conversion rewrites the file on disk. A file whose encoding PlanCake cannot recognize is never converted. See Files that are not in UTF-8.

Working from the command line

PlanCake can also work without a window. Four commands read the notes in a file, check whether any are left, remove them all, or export the file to HTML. They are made for scripts and for AI assistants: Claude uses them to read your notes on a plan and to confirm every one has been dealt with.

Every command follows the same pattern:

plancake <command> <file> [options]

Type plancake --help for the list of commands, or plancake list --help for the options of one command. Output is UTF-8 without a byte order mark. Errors go to the error output, with exit code 1. A mistyped command, such as plancake chek, is such an error too (“Unrecognized command: chek. Did you mean check?”), rather than a window opening on a file that does not exist.

Exit codes
CodeMeaning
0The command succeeded. For check: the file has no notes.
1Something went wrong: the file is missing or cannot be read, an option is wrong, the output cannot be written.
3Only from check: the file still has notes.

The list, check and export commands never change your Markdown file. Only clear does.

Listing the notes

plancake list plan.md

This prints one line per note: the note's lines, the lines of the block it follows, the beginning of that block, and the note itself. Lines are numbered from 1, as in a text editor. Line breaks inside a note are shown as a slash.

43-43 after 41-42 "Back up the database before you run the migration.": Also back up the uploads folder.

A note before the first block of the file follows no block, and its line says so:

1-1 at the start: Read the whole plan before you start.

This format is meant for scripts, so its fixed words and punctuation — “after”, “at the start”, the dash, the quotation marks — stay in English whatever your interface language is.

Add --json for JSON: a list of objects with the fields noteStartLine, noteEndLine, blockStartLine, blockEndLine, blockKind, blockExcerpt and text. Line numbers start at 1. The blockKind is one of paragraph, heading, listItem, code, tableRow, or start for a note before the first block, whose blockStartLine and blockEndLine are null and whose blockExcerpt is empty. Add -o (or --output) and a file name to write the result to a file instead of the screen:

plancake list plan.md --json -o notes.json

Export notes in the File menu saves the same JSON from the window.

Checking whether notes remain

plancake check plan.md

This prints the number of notes, such as 2 notes, and ends with exit code 0 when there are none, 3 when there are some, and 1 when the file could not be read. A script can tell the three cases apart: done, notes still open, something broke.

Clearing every note

plancake clear plan.md

This removes every note from the file and prints how many it removed, for example Removed 2 notes. For a file in a legacy encoding, clear follows the conversion setting: when conversion is off, or the encoding cannot be recognized, it refuses to change a file that has notes and explains why. Add --convert to convert such a file to UTF-8 for this run whatever the setting says; a file whose encoding cannot be recognized is still never changed.

plancake clear old-plan.md --convert

Exporting to HTML

plancake export plan.md -o plan.html

This writes a standalone web page of the document with its notes clearly marked, to share with someone who does not use PlanCake. The page has its styles built in and contains no scripts. The -o option is required. The page's language is the Document language from Settings; to use another, add --lang and a language code, such as --lang fr. The page title is the document's first heading, or the file name if it has none. Pictures that are files on your computer, such as ![Diagram](diagram.png) next to the plan, are put inside the page, so it shows them wherever it is opened; one larger than 10 MB, or on another computer's network share, is not. Pictures from the web stay links to the web.

Using other markers for one run

By default the commands use the markers from Settings. To use other ones for a single run, add:

--open-marker <text>
The marker a note starts with.
--close-marker <text>
The marker a note ends with.
--single-token
Notes have no closing marker and end with their line. This cannot be combined with --close-marker.
plancake check plan.md --open-marker "!NOTE!" --single-token

PowerShell and cmd do not wait

PlanCake is a Windows program with a window, and an interactive PowerShell or Command Prompt does not wait for such programs to finish. When you type a command at the prompt, the prompt may come back before the output appears; the output then shows up below it. It is complete — just late.

Output that is piped or captured is always complete, because the shell waits for it. That is the case in bash, when you pipe into another command, and in Claude's own tool calls.

In PowerShell scripts there is one trap: assigning the output to a variable is not piping. $notes = plancake list plan.md does not wait, and it leaves $LASTEXITCODE empty. Pipe the command instead, or run it through cmd:

$notes = plancake list plan.md | Out-String
plancake check plan.md | Out-Host
$LASTEXITCODE

cmd /c "plancake check plan.md"

Reviewing a plan with Claude

Here is how the pieces fit when Claude writes a plan and asks you to review it. You open the plan with pk plan.md, read it, and leave notes wherever you disagree or want changes. When you tell Claude you are done, it runs plancake list plan.md --json to read your notes with the exact blocks they refer to, reworks the plan, and removes the notes it has dealt with. plancake check plan.md confirms nothing is left.

If you use the Debussy plugins for Claude Code, their manual-review step reads notes marked with the markers in Debussy's noteMarkers setting, where a pair of markers is written as open...close. PlanCake's default markers, [usernote] and [/usernote], fit that convention as they are. See Debussy's documentation for how to set it up; its source is on GitHub.

Keyboard and mouse reference

These shortcuts are fixed; they cannot be changed. You can also see all of them in PlanCake itself: choose Keyboard shortcuts in the Help menu.

Anywhere in the window

Shortcuts that work in the document and in the notes list
ActionShortcut
Open a fileCtrl+O
Open from the clipboardCtrl+V
Open from a linkCtrl+L
Open the file in your text editorCtrl+E
SettingsCtrl+Comma
UndoCtrl+Z
RedoCtrl+Y
Switch between the document and the notes listF6 or Shift+F6
Next noteF9
Previous noteShift+F9
Next block in the documentAlt+Shift+Down Arrow
Previous block in the documentAlt+Shift+Up Arrow
Zoom inCtrl+Plus or Ctrl+Numpad Plus
Zoom outCtrl+Minus or Ctrl+Numpad Minus
Reset zoomCtrl+0
Back to the previous fileAlt+Left Arrow, or Backspace outside a text box
Forward to the next fileAlt+Right Arrow
Reload the fileF5
User manualF1
About PlanCakeShift+F1
Close the windowAlt+F4

In the document

Keys and mouse actions in the document
ActionKeyboardMouse
Move to the next or previous blockAlt+Shift+Down Arrow, Alt+Shift+Up ArrowNot needed: click the block
Add a note after a block, or edit a noteEnterClick (a double-click does nothing more)
Open the menu of a block or a noteApplications or Shift+F10Right-click
Check or uncheck a taskSpace or EnterClick the checkbox
Follow a linkEnterClick

In the notes list

Keys and mouse actions in the notes list
ActionKeyboardMouse
Go to the note in the documentEnterDouble-click
Delete the noteDeleteRight-click, then Delete note
Move to the next or previous block in the documentAlt+Shift+Down Arrow, Alt+Shift+Up ArrowNot needed: click the block
Open the menu of the noteApplications or Shift+F10Right-click

In the note dialog

Keys in the Add note and Edit note dialog, with the default setting
ActionShortcut
Save the noteEnter, or click OK
Start a new lineCtrl+Enter
CancelEscape, or click Cancel

If you set Enter in the note dialog to Starts a new line, Enter and Ctrl+Enter swap.

Click a menu name, press Alt or F10 to reach the menu bar, or open a menu directly: Alt+F for File, Alt+E for Edit, Alt+V for View, Alt+N for Notes, Alt+H for Help. Commands that do not apply at the moment — Undo with nothing to undo, Next note in a file without notes — are unavailable.

File menu
CommandShortcutWhat it does
OpenCtrl+OOpens a Markdown file from your disk.
Open from clipboardCtrl+VOpens the file, path or link you copied.
Open from linkCtrl+LDownloads a Markdown file from the web and opens it.
Open in editorCtrl+EOpens the file in the program Windows uses for Markdown files, when you want to change the plan's text itself. If that program is PlanCake itself, or there is none, the file opens in the program Windows uses to edit it, or else in Notepad.
Export notesNoneSaves all notes of the file, with the blocks they follow, as a JSON file. PlanCake never reads it back; it is a copy for other tools.
SettingsCtrl+CommaOpens the settings.
ExitAlt+F4Closes the window.
Edit menu
CommandShortcutWhat it does
UndoCtrl+ZUndoes the last note or task change.
RedoCtrl+YMakes the undone change again.
Delete all notesNoneRemoves every note from the file, after asking.
View menu
CommandShortcutWhat it does
Notes listNoneShows or hides the notes list. Checked while the list is shown. The choice is saved, the same as Show the notes list in Settings.
Switch paneF6Moves focus between the document and the notes list.
Wider notes listNoneGives the notes list a tenth more of the width it shares with the document. Unavailable while the list is hidden.
Narrower notes listNoneGives the document a tenth more of that width. Unavailable while the list is hidden.
Interface languageNoneA submenu to switch the language of PlanCake's menus and dialogs. The choice is saved.
Document languageNoneA submenu to set the language of the open document, for this file only.
Zoom inCtrl+PlusMakes the text larger.
Zoom outCtrl+MinusMakes the text smaller.
Reset zoomCtrl+0Goes back to 100 percent.
BackAlt+Left ArrowGoes back to the previous file, at the spot you left.
ForwardAlt+Right ArrowGoes forward to the next file.
ReloadF5Reads the file from disk again.
Notes menu
CommandShortcutWhat it does
Edit noteNoneOpens the note you are on, in the document or the list, for editing.
Delete noteNoneDeletes the note you are on.
Next noteF9Moves to the next note.
Previous noteShift+F9Moves to the previous note.
Next blockAlt+Shift+Down ArrowMoves to the next block or note in the document.
Previous blockAlt+Shift+Up ArrowMoves to the previous block or note in the document.
Help menu
CommandShortcutWhat it does
User manualF1Opens this manual in your web browser, in your interface language when it is available.
Keyboard shortcutsNoneLists every shortcut.
Check for updatesNoneChecks for a new version right now.
About PlanCakeShift+F1Shows the version, with a link to PlanCake on GitHub, a Copy info button and a Licenses button, which opens PlanCake's license and the notices of the third-party components it includes in Notepad.

Open a context menu by right-clicking, or with the Applications key or Shift+F10.

Context menu commands
WhereCommands
On a block in the documentAdd note, Copy block text
On a note in the documentEdit note, Delete note
On a note in the notes listEdit note, Delete note

Keeping PlanCake up to date

PlanCake checks for new versions when it starts and then once a week, and stays quiet unless it finds one. When there is a new version, a window describes it and offers to install it; you can also skip that version or be reminded later. You can change how often PlanCake checks, or turn the checks off, in General settings.

If you have several plans open, only one window does these automatic checks, so you are not offered the same update several times.

To check right away, choose Check for updates in the Help menu. PlanCake tells you the result, for example “PlanCake is up to date.”

Your data and privacy

Your notes are in your files

PlanCake has no database and no hidden files for your notes: every note is plain text inside the Markdown file it belongs to. Whatever backs up your files — version control, cloud sync, a copy on a USB stick — backs up your notes with them. To give someone your notes, give them the file.

Settings and logs

Your settings are in one text file, PlanCake.cfg:

To take your settings to another computer, copy that file to the same place there. The same folder holds a logs folder, which records what PlanCake did and helps when you report a problem. The working files of the document view are kept in %LOCALAPPDATA%\Oire\PlanCake with the installer, and in the same userdata folder in the portable version. Deleting these folders resets PlanCake to its defaults and never touches your Markdown files or the notes in them.

What goes over the network

PlanCake connects to the internet only for two things: downloading a file when you open one from a link, and checking for updates. It sends no usage data anywhere.

Troubleshooting

My notes disappeared, or they show up as plain text

This happens when the note markers in Settings no longer match the ones the notes were written with. PlanCake reads only the markers set now, so older notes look like ordinary text. They are still in the file, unchanged. Set the markers back to the ones the notes use — [usernote] and [/usernote] by default — and they are notes again.

I cannot add notes: the file is read-only

The file is not in UTF-8. Turn on Convert to UTF-8 on opening in the Advanced settings and open the file again. If PlanCake says the encoding could not be recognized, the file stays read-only whatever you do; open it in a text editor, save it as UTF-8, and open it in PlanCake again.

If PlanCake instead says the file is no longer there, it was deleted, renamed or moved while open. Put it back, or open it from its new place.

PlanCake says “The file changed. Please try again.”

Something else changed the file between the moment you started and the moment PlanCake went to write. PlanCake refused to overwrite that change and now shows the current version. Repeat what you were doing.

I keep adding notes by accident when I click

Set Enter or a click on a block to Opens the context menu in the Notes settings. A click on a block then shows its menu, and you add a note only when you choose Add note. If you added one by accident already, press Ctrl+Z.

F6 does nothing

The notes list is hidden. F6 moves between the document and the list but does not show the list. Choose Notes list in the View menu first.

PlanCake says it needs the Microsoft Edge WebView2 Runtime

PlanCake uses WebView2 to show documents. If it is missing, PlanCake says so when it starts and asks whether to open the download page. Answer Yes, install the Evergreen Runtime from that page, and start PlanCake again. The installer version of PlanCake installs WebView2 for you, so this usually concerns the portable version on Windows 10.

Opening a file brings up another window instead

That file is already open in another PlanCake window, and PlanCake keeps one window per file. The existing window comes to the front, with your place in it unchanged.

A link will not open

PlanCake opens only Markdown files. If it says the link leads to a web page, find the link to the file itself — on most sites, a Raw link. GitHub file links work as they are. Downloads also stop after 30 seconds and are limited to 10 MB.

PlanCake says a note runs to the end of the file

A note in the file has an opening marker but no closing one — usually a note typed by hand. PlanCake treats everything after the marker as part of that note. Press Ctrl+E to open the file in your editor and add the closing marker. Until then, PlanCake does not edit or delete that note, and Delete all notes removes nothing, because the rest of the file would go with it. Nor does it add a note to the last block before that note, which would become part of it.

Command-line output appears after the prompt, or $LASTEXITCODE is empty

Interactive PowerShell and cmd do not wait for PlanCake to finish. Pipe the command, for example plancake check plan.md | Out-Host, or run it with cmd /c. See PowerShell and cmd do not wait.

PlanCake says the settings could not be saved

PlanCake could not write its settings file, for example because the folder is read-only or another program has the file open. Your changes still apply until you close PlanCake. Once the cause is gone, change the settings again.

How do I report a problem?

Open About PlanCake with Shift+F1 or from the Help menu and click Copy info; the dialog says “Copied”. This puts your PlanCake version and Windows details on the clipboard. Paste them into a new issue on PlanCake's GitHub page, together with what you did and what happened.

Attach errors.log from the logs folder too (with any numbered ones beside it, such as errors_001.log), and PlanCake.log if you are asked for it. The logs folder is %APPDATA%\Oire\PlanCake\logs with the installer, and userdata\logs next to plancake.exe in the portable version. The logs name the files you opened and the web addresses you downloaded from, without the values in their queries, but never hold the text of your files or your notes.