Skip to main content
This guide shows the shortest useful path: connect Notion, mount it as files, edit one page, review the diff, and push.

​
1. Install

Download Locality from the latest finalized GitHub Release. For OS-specific asset names, see Install Locality. macOS uses the DMG release asset:
Linux is supported on Ubuntu 24.04+, Debian 13+, Fedora 40+, openSUSE Tumbleweed, and Linux Mint 22+. Use the Debian, RPM, or AppImage release asset:
DEB and RPM installs enroll the signed Locality repository, so normal apt upgrade, dnf upgrade/yum update, or zypper update runs install later Locality releases. AppImage uses Locality’s desktop self-updater instead. Windows uses the installer release asset:
For CLI workflows, make sure loc is available on your shell path. On macOS direct installs, open the desktop app once and complete onboarding so Locality can install or refresh the terminal command.

​
2. Connect Notion

The browser flow asks which Notion pages or workspaces Locality can access. Locality can only mount content shared with the integration. For local development or CI with a Notion token:

​
3. Mount a workspace

On macOS desktop builds, the app usually creates and opens the File Provider folder for you. The user-visible folder is reported by the app and by loc file-provider open. CLI workspace mount:
Plain-file mount for development or scripts:

​
4. Find a page

Use the desktop locate input for known Notion URLs or page titles, or browse the mounted folders directly:
Open the resolved page.md in an editor, or pass a concrete mounted path to an agent.

​
5. Edit and review

Edit the mounted Markdown file:
Check what Locality sees:
Push a safe reviewed plan:
If the remote changed first, pull before pushing:

​
6. Use Live Mode when appropriate

Live Mode is the desktop background sync loop. When enabled, Locality can pull clean remote updates and push safe local edits without asking an agent to run loc pull or loc push after every small edit. Keep Live Mode conservative:
  • use it for safe, ordinary Markdown edits;
  • expect it to pause for conflicts, destructive plans, unsupported operations, and review-required changes;
  • use loc status and the desktop pending changes view when it pauses.