HANDNOTES

Handwriting, photos, voice recordings and typed notes, kept on your own computer. No account, no server, no sync service holding your data.

Quick start

1. Unzip HandNotes-Local.zip. On Windows, right-click it and choose Extract All. Running the installer from inside the zip preview won't work.
2. Run the installer for your system: Install-Windows.bat, Install-Mac.command, or bash install-linux.sh.
3. Open HandNotes from the Desktop icon or your Start Menu / Applications folder. It opens in its own window.
4. Type a note, or go straight to Draw, Camera or Audio. Whatever you save gets attached to the note that's open, or starts a new one.
5. Go to Settings, press Keep data permanently, then Backup now and put that file somewhere safe. Do this every so often.

Installing

The program installs into the system's program folder, with a Desktop icon and a Start menu (or applications menu) icon. Your computer asks once for administrator permission. Your notes are not kept in the program folder: they stay in your own user folder, so an update or reinstall keeps them.

Windows shows a permission prompt (click Yes). Mac and Linux ask for your password when the system folder needs it.

Which browser does it use?

HandNotes is a single web page, so it needs a browser engine to run. The installer looks for Google Chrome first, then Microsoft Edge, Brave, and Chromium, and launches HandNotes in that browser's app mode with its own separate profile. Every Windows 10 and 11 machine has Edge, so Windows always gets the full experience. If no Chromium browser exists on a Mac, it falls back to Safari. On Linux it falls back to your default browser.

The installer remembers which browser it picked. Reinstalling or updating later keeps the same one so your notes stay put.

Security warnings on first run

• Windows may show "Windows protected your PC" because the installer isn't code-signed. Click More info, then Run anyway.
• Mac may say the file "can't be opened because it is from an unidentified developer." Right-click Install-Mac.command, choose Open, then Open again. If macOS still blocks it, open Terminal, type bash (with a space), drag the file into the window, and press Return.
• Linux desktops sometimes mark new launchers as untrusted. Right-click the Desktop icon and choose Allow Launching.

Where your notes live

Notes, drawings, photos and recordings are stored in the browser engine's local database (IndexedDB) inside the HandNotes profile folder the installer created:

• Windows: %LOCALAPPDATA%\HandNotes\profile
• Mac: ~/Library/Application Support/HandNotes/profile
• Linux: ~/.local/share/handnotes/profile

That folder is a database, not a set of readable files. For files you can open in other programs, use Mirror to a folder or Export all (ZIP).

What leaves your computer

Nothing, unless you use one of these on purpose:

• AI tab: sends the open note's text (and transcripts, if that box is checked) to Anthropic, using your own API key.
• Deepgram transcription: sends the recording to Deepgram, using your own key.
• Browser live transcription in Chrome and Edge: the browser streams your voice to Google's or Microsoft's speech service while you record. Set Transcription to Off in Settings for fully offline recording.

Notes tab

Every note as a card, with a thumbnail of its first drawing or photo, its project, tags, and how many attachments it has.

• Search looks through titles, text, tags and recording transcripts as you type.
• Project filter narrows the list to one project.
• Sort by most recently edited, newest created, or title.
• Click a card to open it in the Editor.

Editor tab

• Title, project, tags. Pick "+ New project..." from the project list to create one on the spot. Separate tags with commas.
• Autosave saves 1.5 seconds after you stop typing, and again when you switch tabs. Turn it off in Settings if you'd rather save by hand. The status line at the bottom right shows word count and whether the note is saved.
• Attachments show in a strip under the text. Click a picture to enlarge it. The pen button opens a drawing (or a copy of a photo) in the Draw tab for markup. TXT sends a recording to Deepgram for a transcript. The download button saves the original file.
• Attach adds image or audio files from your computer.
• Markdown downloads the note as a .md file. For the attachments too, use Export all (ZIP) in Settings.
• Delete removes the note and its attachments after asking you to confirm. There is no trash can, so back up regularly.

Layout and appearance (version 2.1)

• Light, Dark and White. Pick one at the top right, in the ... menu, or in Settings > Appearance. Light is the default. Your choice is saved in this browser. The drawing paper stays white in every mode, so saved drawings look the same.
• Workspace list. On a computer your notes are listed on the left, with search, a project filter and sorting. Click a note to open it without leaving the tab you are on. On a phone or small tablet, the menu button at the top left opens the list as a drawer.
• The bar above the tabs shows the open note's project and title. Type in the title to rename the note. Export saves the note as Markdown. Save note saves the note; on the Draw tab it saves the drawing to the note.
• Help, Download for your computer, All tools, Home and Support the training are in the ... menu at the top right.
• Drawing tools (color palette, stroke size, Stylus only, paper) are in the panel on the right. Tools opens or closes it, and the colored dot opens it at the palette. Each section folds up. On a phone the panel slides up from the bottom; close it with Done, the X, Escape, or by tapping outside it.
• Stylus only ignores finger marks while you write with a pen. It is off unless you tick it.
• Focus mode hides everything except the drawing pad and its toolbar. The collapse button in the toolbar, or Escape, brings the rest back.

Draw tab

Built for a pen tablet, a touchscreen with stylus, or a mouse. With a real pen the line gets thicker as you press harder.

• Colors: eleven presets plus a custom color picker.
• Size slider, 1 to 40.
• Eraser paints white at three times the pen size. Press it again, or pick a color, to go back to the pen.
• Paper: blank, ruled, grid, or dots. A blank page takes the new paper right away; once you have drawn, it applies at the next New page.
• Undo / Redo go back up to 30 strokes. Opening or closing panels, focus mode, or turning a phone keeps your undo history.
• New page (bottom of the pad) and Clear drawing (tools panel) clear the canvas, asking first if you haven't saved. Undo brings a cleared page back.
• Save Drawing stores the page as a PNG on the open note. The label next to it tells you which note that is. Saving again after more drawing updates the same attachment rather than making a new one.

The canvas grows when the window grows and never crops what you drew when it shrinks. A drawing that hasn't been saved is lost if you close HandNotes, and it will warn you before closing.

Camera tab

• Start turns on the camera. The first time, the browser asks for permission.
• Capture saves a full-resolution JPEG straight to the open note (or a new one).
• Flip switches front and rear cameras on phones and tablets.
• Stop turns the camera off. Leaving the tab also turns it off.
• Import photo attaches existing pictures from your computer.

Handy for snapping a whiteboard, a paper notebook page, or a document, then marking it up in Draw.

Audio tab

• Record starts recording and shows a live waveform and timer. Press Stop to finish. The recording saves to the open note automatically.
• Live transcript appears while you talk when Transcription is set to Browser (Chrome, Edge, Safari). With Deepgram selected, the transcript arrives a few seconds after you stop.
• Add transcript to note text appends the transcript to the note body so it's searchable and editable. Transcripts are also kept with each recording either way.
• The pill at the top right tells you which transcription mode is active and whether it will work in this browser.

AI tab

Works on whichever note is open. You need your own Anthropic API key (see Settings). You pay Anthropic directly for what you use. A summary of a typical note costs a fraction of a cent on Sonnet or Haiku.

Then Copy, Append to note, Replace note text (asks first), or Use as title. Leave "Include recording transcripts" checked to have the AI read what you dictated too.

Settings tab

Your data

Shows space used. Keep data permanently asks the browser to never clear HandNotes data when disk space runs low. The installed app usually gets this automatically, but press it anyway. Backup, Restore and Export all live here. See Backup and restore.

Mirror to a folder

See below.

Projects

Add projects, rename one by clicking it (all its notes move with it), remove empty ones with the small x, and choose the default project for new notes.

AI

1. Sign in at console.anthropic.com, add a little credit under Billing, and create a key under API Keys.
2. Paste it into Anthropic API key, pick a model, and press Save settings.

Sonnet 5 is fast and handles everything here well. Haiku 4.5 is cheapest. Opus 5.5 is the strongest and costs the most.

Transcription

Browser is free and live, but Chrome and Edge send the audio to their own speech services. Deepgram needs a key from console.deepgram.com and transcribes after you stop, usually with better accuracy and punctuation. Off records audio only and nothing leaves the computer. Set Language with a code like en-US, es-MX or de-DE.

Always press Save settings after changing anything in these sections.

Keyboard shortcuts

Backup and restore

Backup now downloads one .json file holding every note, drawing, photo, recording and setting. API keys are left out unless you tick "Include API keys in backup file." Keep backups on a USB drive, in OneDrive or Dropbox, or anywhere off this computer.

Restore backup reads one of those files and adds its notes to what's already here. Nothing you already have gets deleted. If a note in the backup has the same ID as one here, the backup copy replaces it, and HandNotes tells you how many before it does anything.

Export all (ZIP) makes a ZIP of readable Markdown files, one per note, sorted into project folders, with every attachment in an attachments folder. Obsidian, Typora, VS Code, or any text editor can open them. This is for reading and archiving. Use the JSON backup to restore.

Mirror to a folder

Chrome and Edge only. Press Choose folder and pick a place such as Documents\HandNotes or a OneDrive or Dropbox folder. From then on, each time a note saves, HandNotes writes:

• notes/2026-09-27 Meeting with county clerk__id.md (the file name is set the first time and stays the same if you rename the note)
• attachments/drawing-id.png, photo-id.jpg, audio-id.webm

Mirror all now writes every note at once. Files are only created or updated, never removed, so deleting a note in HandNotes leaves its file in the folder.

For privacy, browsers ask you to re-allow folder access after HandNotes restarts. If the Settings pill says "Needs permission," press Mirror all now and click Allow. Mirroring then continues for that session.

Mirroring goes one direction, from HandNotes to the folder. Editing the Markdown files doesn't change what's in HandNotes.

Moving from the web version

1. Open the web version at jeffapierson.com in the same browser you used before. The updated web version keeps your old notes.
2. Go to Settings and press Backup now.
3. Open the installed HandNotes, go to Settings, press Restore backup, and pick that file.

Drawings and photos from the old version were never actually saved (the assessment explains why), so only typed text carries over from before this update.

Troubleshooting

"Could not open its local database"

Private and incognito windows, and some locked-down work browsers, block local storage. Use the installed app or a normal browser window.

Camera or microphone won't start

• Click the camera icon at the right end of the address bar (or in the app window's menu), and allow access.
• Windows: Settings > Privacy & security > Camera / Microphone, and make sure desktop apps are allowed.
• Mac: System Settings > Privacy & Security > Camera / Microphone, and turn on Chrome or Edge.
• Close Zoom, Teams, or anything else that might be holding the camera.

No live transcript

Firefox has no built-in speech recognition. Chrome and Edge need an internet connection for it. Check the pill on the Audio tab. Switch to Deepgram, or record with Transcription off and type notes yourself.

AI says "invalid x-api-key" or "credit balance is too low"

Re-copy the key from console.anthropic.com (it starts with sk-ant-) and check Billing for credit. "Failed to fetch" means no internet connection.

Deepgram fails

Check the key and your Deepgram balance. If it keeps failing with a network error, use Browser transcription instead.

My notes disappeared

You're probably looking at a different copy of HandNotes (see Where your notes live). The installed app, the web page, and a directly opened HTML file each have their own storage. Open the one you used before, back up, and restore into the one you want to keep.

The window opens in a normal browser tab with toolbars

No Chromium browser was found at install time. Install Chrome or Edge and run the installer again. Back up first if you already have notes in the fallback browser.

Updating

Download the new zip, extract it, and run the installer again. It replaces the app files and leaves your notes alone. Making a backup first costs nothing.

Uninstalling

• Windows: Settings > Apps > Installed apps > HandNotes > Uninstall, or run Uninstall-Windows.bat.
• Mac: run Uninstall-Mac.command.
• Linux: bash uninstall-linux.sh.

The uninstaller removes the app and its shortcuts, then leaves your notes in place unless you type DELETE in capitals when asked. Reinstall later and they come right back.