Active Note Pointer

The desktop app can expose its currently active workspace note to local tools through a machine-readable sidecar. This is a local, opt-in observation channel; it is off by default and is never synced.

Enable and location

Run Enable active note pointer from the command palette. The desktop app writes:

~/.config/zudotext/<appname>/active-note.json

Disabling the command removes the pointer immediately. The app also removes it when switching workspaces, when no workspace note is active, and during a clean shutdown. A crash may leave the last file behind, so readers must apply the staleness rule below.

Browser, REST, mock, and iOS builds do not support this sidecar.

Version 1 format

{
  "version": 1,
  "app": "modmsg",
  "workspace_id": "workspace-abc123",
  "path": "inbox/1.md",
  "pane_id": "frame-a",
  "view": "edit",
  "updated_at": "2026-08-24T12:34:56.789Z",
  "selection": {
    "start_line": 2,
    "start_column": 0,
    "end_line": 4,
    "end_column": 8
  }
}

path is always a canonical workspace-relative POSIX path. It is never an absolute path and never uses the desktop bridge's synthetic /__workspace__ root. view is one of edit, preview, todo, or mindmap. pane_id identifies the active frameset pane.

selection is optional and appears only for a non-empty selection in the matching active editor. Lines are one-based; columns are zero-based UTF-16 offsets, matching CodeMirror's document positions. The pointer does not duplicate selected note text.

Freshness and atomicity

The app rewrites a live pointer every 10 seconds and promptly when its note, pane, or view changes. Selection changes are captured by the next heartbeat. Treat updated_at older than 30 seconds as stale. A present but stale file means the app may have crashed or been force-quit; it is not evidence that the note remains active.

Every replacement is written to a sibling temporary file, synchronized, and atomically renamed over active-note.json. On Unix platforms the temporary and resulting pointer files use mode 0600, so only the current user can read them.

Strictly read-only contract

External tools must never write to active-note.json. The app does not watch or consume this file, and the next heartbeat overwrites external changes. It is not an IPC command channel and cannot navigate, select, edit, or otherwise drive the app.

Use the workspace ID and relative path only as inputs to separately authorized read/write APIs. Removing or modifying the sidecar does not change the open note.