{"id":"paseo-markdown-viewer","repo":"opsb/paseo-markdown-viewer","url":"https://github.com/opsb/paseo-markdown-viewer","name":"paseo-markdown-viewer","description":"Read-only markdown side panel for Paseo: tabs, live file updates, and follow mode for files agents edit.","categories":["productivity","developer-tools"],"platforms":[],"caveats":["Follow mode opens tabs when the editing agent's conversation is on screen; hidden conversations catch up when viewed.","Files written through shell heredocs are not detected by follow mode; use bin/open-markdown for those.","Show in Finder reveals the file on macOS; other platforms open the containing folder."],"images":[],"health":{"manifestValid":true,"hasReadme":true,"hasLicense":true,"hasTests":false,"hasTypecheckScript":true,"updatedRecently":true},"scannedAt":"2026-09-15T21:25:30.956Z","addedAt":"2026-09-15T19:52:27Z","version":"0.1.0","security":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-09-15T21:22:49.488Z","commit":"9a19dfe2837c7e4a510ed767fa89c920c3ad4195"},"license":"MIT","paseoVersionRequirement":">=0.8.0","manifest":{"id":"paseo-markdown-viewer","requirements":{"paseo":">=0.8.0"}},"repoMeta":{"stars":0,"defaultBranch":"main","pushedAt":"2026-09-15T18:03:52Z"},"owner":{"login":"opsb","avatarUrl":"https://avatars.githubusercontent.com/u/46232?v=4"},"installNotesHtml":"
Open a workspace, press ⌘K, and choose Open markdown viewer, or type /md README.md in the\ncomposer.
","limitationsNotesHtml":"
\n
Follow mode acts when the requesting agent's conversation is on screen, which it is when you are\nworking with that agent. A hidden conversation opens its tabs when next viewed.
\n
Files an agent writes through a shell heredoc appear as shell commands, not edits, and are not\nfollowed. Use bin/open-markdown for those.
\n
Show in Finder reveals the file on macOS. Other platforms open the containing folder.
\n
Follow-mode settings are stored through Paseo's settings API. The 0.8.0 SDK gives the daemon no\nhandle to read them, so the daemon reads the persisted document directly.
\n
","readmeText":"# Paseo Markdown Viewer\n\nA [Paseo](https://paseo.sh) plugin that adds a read-only **Markdown** panel to every workspace. Open\nany markdown file in a tab, watch it update the moment it changes on disk, and let the panel follow\nthe files your agents write.\n\nRequires **Paseo 0.8 or newer**.\n\n## What it does\n\n- **Tabbed viewer.** Each file has its own tab. Headings, lists, task boxes, tables, fenced code,\n block quotes, links, Obsidian wikilinks and YAML frontmatter all render with React Native\n primitives, so the panel works on desktop, in the browser and on phones, in every Paseo theme.\n- **Live updates.** The daemon watches each open file with the operating system's file events and\n the panel re-reads within milliseconds of a save, including atomic saves that rename a temporary\n file over the original.\n- **Follow mode.** When an agent writes or edits a markdown file, that file gets a tab. The tab waits\n in the background with a green dot until you look at it, mirroring how Paseo marks agents with\n changes. Paseo normalises tool calls across providers, so this works with any agent.\n- **Unread dots.** Left of every tab: a ring for the tab you are viewing, green for a file changed\n since you last viewed it, grey otherwise. Hidden tabs are watched too.\n- **Show in Finder.** Reveals the current file in the daemon machine's file manager.\n- **Explicit opens.** `/md ` in the composer, an **Open markdown viewer** Command Center item,\n and a `bin/open-markdown ` script agents can run to show you a file.\n\n## Install\n\nEnable trusted plugins on the daemon, then:\n\n```bash\npaseo plugin add opsb/paseo-markdown-viewer\npaseo plugin ls\n```\n\nOpen a workspace, press **⌘K**, and choose **Open markdown viewer**, or type `/md README.md` in the\ncomposer.\n\n## Using the panel\n\n| Action | How |\n| --- | --- |\n| Open a file | Type a path in the toolbar and press return. Relative paths resolve against the workspace; absolute and `~/` paths are accepted as typed. |\n| Open from the composer | `/md docs/plan.md` opens a tab and brings the panel forward. No prompt is sent to the agent. |\n| Switch or close tabs | Tap a tab; tap its `×` to close. Closing the active tab moves to its neighbour. |\n| Reveal on disk | **Show in Finder** in the document footer. |\n\n### Follow mode\n\nTwo switches in the toolbar, shared by every client of the daemon:\n\n| Switch | Default | Effect |\n| --- | --- | --- |\n| **Follow agents** | on | Files an agent writes or edits open as background tabs with an unread dot. |\n| **Bring forward** | off | Followed files also raise the panel itself. |\n\n### Letting an agent open a file\n\nFrom inside a Paseo agent, where `PASEO_AGENT_ID` is set:\n\n```bash\n/bin/open-markdown docs/decision.md\n```\n\nThe script drops a small JSON request into `$PASEO_HOME/plugin-data/paseo-markdown-viewer/inbox/`.\nThe daemon turns it into a row in that agent's conversation, and the row opens the tab and brings\nthe panel forward. No network port is opened.\n\n## How it works\n\n- Files are read by the daemon over plugin RPC. Relative paths are confined to the workspace\n directory, following symlinks, and only `.md`, `.markdown` and `.mdx` files up to 2 MB are served.\n- Change detection is a daemon-side directory watcher plus a content hash, surfaced to the panel as\n a long poll that resolves the instant the content differs. Paseo has no daemon-to-app push\n channel for plugins, and the long poll rides Paseo's own connection, so it works through the relay\n and on mobile.\n- Follow mode subscribes to every live agent's timeline on the daemon and appends one plugin-owned\n row per agent when a markdown write or edit completes. The row's renderer opens the tab.\n\n## Limitations\n\n- Follow mode acts when the requesting agent's conversation is on screen, which it is when you are\n working with that agent. A hidden conversation opens its tabs when next viewed.\n- Files an agent writes through a shell heredoc appear as shell commands, not edits, and are not\n followed. Use `bin/open-markdown` for those.\n- **Show in Finder** reveals the file on macOS. Other platforms open the containing folder.\n- Follow-mode settings are stored through Paseo's settings API. The 0.8.0 SDK gives the daemon no\n handle to read them, so the daemon reads the persisted document directly.\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck\npaseo plugin install /absolute/path/to/paseo-markdown-viewer\npaseo plugin reload paseo-markdown-viewer\npaseo plugin logs paseo-markdown-viewer\n```\n\nLayout follows the Paseo plugin contract: `index.client.tsx` and `client/` run in the app,\n`index.server.ts` and `server/` run in the daemon subprocess, `shared/` holds the Zod contracts.\n\n## License\n\nMIT\n"}