
claw-mo
Manage mo markdown viewer sessions: autosync new Claude-written .md via PostToolUse hook, group-based organization, restart-on-up for fsnotify-miss recovery, file deep-linking, stdin pipe support, cmux browser integration, per-project watch patterns, port isolation
- version
- 2.8.2
- GitHub stars
- 52
Install
/plugin install claw-mo@claude-code-zeroRun it inside Claude Code after adding the marketplace with /plugin marketplace add LeeJuOh/claude-code-zero.
Contents
Discovered from sourceSkills 5
claw-mo-down
Stop the mo markdown viewer server for the current project, with accurate reporting of whether it was actually running.
For config schema and --shutdown semantics: read ${CLAUDE_PLUGIN_ROOT}/references/shared.md
Steps
-
Prerequisites:
command -v mo >/dev/null 2>&1. If missing, tell the userbrew install k1LoW/tap/moand stop. -
Project key:
git rev-parse --show-toplevel(fallback:$PWD). -
Read config from
${CLAUDE_PLUGIN_DATA}/config.json. If no entry for this project, tell the user no mo server is configured for this project and stop. -
Check actual running state:
mo --status --json 2>/dev/null. Look for a server whose port matches$PORT.- Not running: tell the user "mo is not running on :$PORT (nothing to stop). Config preserved." and stop.
- Running: continue to step 5.
-
Shutdown:
mo --shutdown -p $PORT -
Verify: re-run
mo --status --json 2>/dev/nulland confirm the port is gone. Report the result:- Success → "Stopped mo on :$PORT. Config preserved — run
/claw-mo-upto restart." - Still present → warn the user (rare; orphaned process) and suggest
kill <pid>using the PID from status.
- Success → "Stopped mo on :$PORT. Config preserved — run
Gotchas
- Config is preserved — shutdown only stops the server, it doesn't delete the project config.
/claw-mo-upwill restart with the same groups. - Backup file is preserved too — next start auto-restores the session. Use
/claw-mo-manage→ Reset session (which runs--clear) if you want a clean slate. - If no server is running on that port,
mo --shutdownexits silently — that's why this skill checks--status --jsonfirst and reports accurately instead of always saying "shut down". - Don't shut down a server belonging to another project — the config key is project-scoped, so this skill only touches the port registered for the current project key.
claw-mo-manage
Interactive management hub for mo markdown viewer. Shows current state and lets the user choose what to do — including a safe "refresh" that re-scans the filesystem without destroying the session.
For config schema, HTTP API, --restart vs --clear semantics, and CLI wrappers (--unwatch, --close): read ${CLAUDE_PLUGIN_ROOT}/references/shared.md
Steps
1. Gather State
Check prerequisite first: command -v mo >/dev/null 2>&1. If missing, tell the user to install and stop.
Then in parallel:
mo --status --json— all running servers- Read
${CLAUDE_PLUGIN_DATA}/config.json— all configured projects - Get current project key:
git rev-parse --show-toplevel
For the current project, extract the live group→patterns mapping from the JSON output and compare it against saved config. Mark the session out of sync if they differ.
2. Display Dashboard
mo server status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
● project-a :6342 running docs(12) plans(3) default(2)
● project-b :6367 running specs(5)
○ project-c :6315 stopped
Current project: project-a (:6342)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Match config entries to running servers for accurate status (● / ○). Also list any running servers found by mo --status --json that aren't in config (user may have started them manually).
If the current project's configured mapping and live mapping differ, show an explicit warning:
⚠ current project is out of sync
configured: {docs: [docs/**/*.md], default: [*.md]}
live: {docs: [/abs/path/docs/*.md], default: [/abs/path/*.md]}
what this means:
- the running mo session is not watching the same patterns as saved config
- the next `/claw-mo-up` will clear this runtime and rebuild it from saved config
recommended actions:
- if saved config is correct → Server control → Reset session (or just run /claw-mo-up)
- if saved config is outdated → Modify patterns/groups (add/remove), or re-run /claw-mo-setup
3. Ask What to Do
Use AskUserQuestion with a two-step approach to stay within the 4-option limit:
First question — category:
Options:
1. Modify patterns/groups (add, remove, rename)
2. Files (add, remove from view)
3. Server control (refresh, stop, reset, restart)
If "Modify patterns/groups" → second question:
Options:
1. Add pattern to a group
2. Remove pattern from a group
3. Add new group
4. Remove group
If "Files" → second question:
Options:
1. Add a file to a group (ad-hoc, like /claw-mo-open)
2. Close a file currently open in mo
If "Server control" → second question:
Options:
1. Refresh (re-scan filesystem, keep session) — runs `mo --restart`
2. Reset current session (clear saved state + restart empty, then rebuild from config)
3. Stop a server
4. Toggle autosync for this project (PostToolUse hook)
If the session is out of sync and the user chose "Modify patterns/groups", recommend Reset first so later changes apply on top of a known-good runtime.
4. Handle Each Action
All runtime mutations should use the mo CLI when there is a CLI equivalent (-w/--unwatch/--close/--restart). Fall back to the HTTP API only when no CLI path exists. Config file updates happen after the runtime mutation succeeds.
Add pattern:
- Ask which group (show existing groups)
- Ask the glob pattern
- If server running:
mo --no-open -w "$PATTERN" -t "$GROUP" -p $PORT- Otherwise skip the runtime step
- Update config file
- Confirm
Remove pattern:
- Show current patterns per group
- Ask which to remove
- If server running:
mo --unwatch "$PATTERN" -t "$GROUP" -p $PORT- mo accepts either the original glob or the absolute path form reported by
--status
- mo accepts either the original glob or the absolute path form reported by
- Update config file
- Confirm
Add group:
Ask group name and one initial pattern → start it via mo -w ... -t name -p $PORT if running → update config
Remove group:
Show groups, ask which → mo --unwatch for every pattern in that group (group disappears when it has no files or patterns) → update config (remove group key)
Add file (ad-hoc):
Delegate to /claw-mo-open logic (HTTP API POST to /_/api/groups/$GROUP/files). Warn this is runtime-only unless persisted.
Close a file:
curl -s "http://localhost:$PORT/_/api/groups"→ list files in each group- Ask which file
mo --close "$(realpath file)" -t "$GROUP" -p $PORT- No config update needed (ad-hoc file, not a pattern)
Refresh (re-scan):
mo --restart -p $PORT(no prompt, safe)- Verify with
mo --status --jsonand report new file counts - This is the fix when docs exist on disk but don't appear in mo — same mechanism
/claw-mo-upuses by default.
Reset session:
printf 'y\n' | mo --clear -p $PORT- Ask: "Restart with saved config now?" (equivalent to
/claw-mo-up) - If yes, run the per-group start sequence from config
Stop a server:
- Show all running servers (from
mo --status --json) with their ports and projects - Ask which to stop (by number or port)
mo --shutdown -p $PORT- Confirm — note that config is preserved so
/claw-mo-upcan restart it later
Toggle autosync:
- Read current
autosyncfield (defaulttrueif absent) - Show current state:
Autosync is ON — .md writes by Claude are added to mo automatically. - AskUserQuestion: flip it?
- Update config file only — no runtime call needed; the hook reads the config on each fire
- Confirm new state
5. Loop or Exit
After each action, show the updated dashboard and ask if they want another action. Exit when done.
Gotchas
- Prefer
mo --restartover--clearfor rescans — restart preserves session; clear destroys the backup. The old "just clear everything" reflex wipes state that didn't need wiping. - Only
--clearprompts for confirmation — pipeprintf 'y\n'.--restart,--shutdown,--close,--unwatchdo not prompt. - Config is desired state — always update config AND runtime (CLI or API) together when making a persistent change.
- Compare full live group→patterns mapping to config before assuming a running server is reusable — matching port or group names alone isn't enough.
- If session is out of sync, prefer Reset before multiple runtime edits; otherwise stale groups/patterns persist and
/claw-mo-upwill discard your runtime edits on the next invocation. - Group names must be simple lowercase — they become URL path segments.
- If the server is not running, only update config — skip CLI/API calls.
- "Close a file" only removes it from the view — the file on disk is untouched and will be re-added if it matches a watch pattern and
mo --restartruns. - "Stop a server" only stops the process — config and backup are preserved so
/claw-mo-upcan restart it later. mo --unwatchaccepts both relative globs and absolute paths (the form--statusshows). Either works.- Autosync is read per fire, not cached: flipping it takes effect on the next
Write|Edit|MultiEdit— no need to restart mo or reload Claude. The hook re-reads config.json every invocation, so the toggle is effectively live.
claw-mo-open
Add a specific file, directory, or piped markdown content to the running mo server and open the browser directly on that file.
For config schema, HTTP API, deep-linking, and browser opening: read ${CLAUDE_PLUGIN_ROOT}/references/shared.md
Arguments
$ARGUMENTS— one of:- File path:
docs/spec.md - Directory:
docs/(added as a watch pattern) -or--stdin: read markdown from stdin (e.g.,cat notes.md | /claw-mo-open -)- Optional
--group <name>to pin the target group (otherwise auto-detected)
- File path:
- Examples:
/claw-mo-open docs/spec.md/claw-mo-open plans/ --group planssome-tool | /claw-mo-open - --group scratch
Steps
-
Parse
$ARGUMENTS:- Detect
--stdinor a bare-→ stdin mode - Otherwise resolve file/dir path with
realpath - Extract
--group; if absent, auto-detect from config (match the file path against each group's patterns, fall back todefault)
- Detect
-
Prerequisites:
command -v mo >/dev/null 2>&1. -
Project key:
git rev-parse --show-toplevel(fallback:$PWD). -
Read config from
${CLAUDE_PLUGIN_DATA}/config.json. -
Check running server:
mo --status --json→ is a server on$PORT? -
If server is running AND config exists — verify sync before mutating:
- Compare live group→patterns to saved config (see
shared.md) - If drifted: tell the user that
/claw-mo-upwould clear+rebuild this runtime; ask whether to resync first or add into the drifted runtime - If they resync: clear, restart from config, then continue
- If they decline: continue but warn the change won't survive the next
/claw-mo-upunless config is updated
- Compare live group→patterns to saved config (see
-
Add the content based on mode:
(a) File path, server running:
curl -s -X POST "http://localhost:$PORT/_/api/groups/$GROUP/files" \ -H 'Content-Type: application/json' \ -d "{\"path\": \"$(realpath file.md)\"}"(b) Directory, server running:
curl -s -X POST "http://localhost:$PORT/_/api/patterns" \ -H 'Content-Type: application/json' \ -d "{\"pattern\": \"$(realpath dir)/**/*.md\", \"group\": \"$GROUP\"}"(c) Stdin, server running: mo's single-instance detection pushes stdin content to the running server automatically:
cat | mo --no-open -p $PORT -t "$GROUP"(d) Server NOT running:
- Has config → perform
/claw-mo-upbehavior first (restart if server reappears mid-flight), then retry step 7 - No config → quick-open with auto-config:
- Auto-assign port:
echo $((6300 + $(echo "$PROJECT_ROOT" | cksum | cut -d' ' -f1) % 100)) - Start mo:
- File:
mo --no-open -p $PORT "$(realpath file.md)" - Dir:
mo --no-open -p $PORT "$(realpath dir)"(mo converts dir →dir/*.mdwatch) - Stdin:
cat | mo --no-open -p $PORT
- File:
- Save minimal config to
${CLAUDE_PLUGIN_DATA}/config.json:{ "PROJECT_ROOT": { "port": PORT, "groups": { "default": ["*.md"] } } } - Tell the user: "Saved a minimal config. Run
/claw-mo-setupto customize watch groups."
- Auto-assign port:
- Has config → perform
-
Resolve deep-link URL — try to open directly on the added file, not just the group:
File mode:
FILE_ID=$(curl -s "http://localhost:$PORT/_/api/groups" | python3 -c " import sys, json, os target = '$(realpath file.md)' for g in json.load(sys.stdin): for f in g.get('files', []): if f.get('path') == target: print(f['id']); break ") URL="http://localhost:$PORT/$GROUP" [ -n "$FILE_ID" ] && URL="$URL?file=$FILE_ID"Stdin mode: mo generates
stdin-<hash>.md. Look up its ID the same way, matching by name prefixstdin-.Directory mode: no single file to link to; use
http://localhost:$PORT/$GROUP. -
Open browser using the cmux-preferred logic from
shared.md(reuse existing surface if one targets this port). -
Report — what was added (path or
stdin-<hash>.md), which group, whether the session was reused/resynced, the resolved URL.
Gotchas
- HTTP API needs absolute paths — always
realpathbefore sending. - Compare live to config before reusing a running session — matching port or group names alone doesn't prove correctness.
- Drift warning is a feature, not a chore: runtime-only additions get wiped by the next
/claw-mo-upunless persisted through/claw-mo-setupor/claw-mo-manage. - Directory args ≠ watch patterns at the API layer: the HTTP API requires you to form the glob (
dir/**/*.md) explicitly. mo's CLI does that conversion for free when you pass a dir as a positional arg — that's why quick-open uses the CLI form. - Deep-linking falls back gracefully: if the file ID lookup fails (file just added, async), opening
/GROUPstill works and the new file will appear in the sidebar via SSE. - Stdin content dedupes by hash: piping the same content twice reuses the existing entry (
stdin-<hash>.md). cat | morequires stdin to not be a TTY. Fine when a pipe is present; fails silently if Claude somehow passes an interactive stdin. The shell pipecat | moforces non-TTY.- Quick-open saves a minimal config so
/claw-mo-up,/claw-mo-down, and/claw-mo-managecan find the session. - If the group doesn't exist in mo yet, the API creates it. The group name becomes a URL path segment — keep it simple lowercase.
- Adding a file already in mo is safe — dedup by path.
claw-mo-setup
Configure mo markdown viewer with group-based watch patterns for the current project.
For config schema, port logic, and groups: read ${CLAUDE_PLUGIN_ROOT}/references/shared.md
Steps
-
Prerequisites check
command -v mo >/dev/null 2>&1→ if missing:brew install k1LoW/tap/mo, stop- If
$CMUX_SURFACE_IDis not set: mention that cmux (https://cmux.dev) provides a built-in browser panel alongside the terminal — ideal for viewing docs while coding. Brief one-liner, don't push.
-
Detect project root:
git rev-parse --show-toplevel(fallback:$PWD) -
Check existing config: Read
${CLAUDE_PLUGIN_DATA}/config.json. If an entry exists for this project:- Show current groups and port
- Ask: "Config already exists — update existing groups or start fresh?"
- Update: Skip to step 6 with current groups pre-populated (user can add/remove/rename)
- Start fresh: Continue from step 4
-
Scan markdown files:
find "$PROJECT_ROOT" -name '*.md' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/vendor/*' 2>/dev/null | wc -lWarn if 500+.
-
List directories with .md files:
find "$PROJECT_ROOT" -name '*.md' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/vendor/*' 2>/dev/null | sed "s|$PROJECT_ROOT/||" | cut -d/ -f1 | sort -u -
Suggest groups based on the directories found in step 5:
- For each directory found, get the file count and suggest a group named after that directory:
find "$PROJECT_ROOT/DIRNAME" -name '*.md' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/vendor/*' 2>/dev/null | wc -l - If a top-level directory is huge, do not blindly suggest
DIRNAME/**/*.md. Inspect one level deeper and propose narrower subgroups when that better matches the actual content (for exampleraw/articles/**/*.mdbut notraw/**/*.mdwhenraw/repos/**dominates) - If root
.mdfiles exist, suggest groupdefaultwith*.md - Use the actual directory name as the group name — don't rename or merge unless obvious (e.g., a single top-level dir with 1 file might be skipped)
- Always show file counts so the user can see what each pattern covers, and explicitly call out directories you are excluding because the watch scope would be too large
- For each directory found, get the file count and suggest a group named after that directory:
-
AskUserQuestion: Present suggested groups and port together. Example:
Detected these groups in your project: - docs: docs/**/*.md (23 files) - plans: plans/*.md (5 files) - default: *.md (3 files) Port: 6342 (auto-assigned from path hash) Proceed with these? Let me know if you want to add, remove, or change anything. -
Save config to
${CLAUDE_PLUGIN_DATA}/config.json(create file if needed, merge if exists). Use v2groupsformat. Include"autosync": trueon new entries so PostToolUse adds newly-written .md files to the running mo server without/claw-mo-up. -
Offer to start: "Setup complete! Want me to start the server with
/claw-mo-up?"- If a mo server is already running on
$PORT(e.g., from a previous setup in this project), note that/claw-mo-upwill apply the new config by clearing and rebuilding — since configured patterns changed, this is expected. - Also mention: "Autosync is on by default — when I write .md files here they'll show up in mo automatically while the server is running. Turn off per project via
/claw-mo-manage→ Server control → Toggle autosync."
- If a mo server is already running on
Gotchas
**/*.mdcan explode: Projects with vendored code may contain thousands of .md files. Always show the count before accepting broad patterns. Guide users toward specific directory patterns.- Large top-level directories need one more pass: If a directory contains a massive subtree, inspect its immediate children before suggesting patterns. Otherwise Claude tends to recommend broad watches like
raw/**/*.mdthat swamp mo with irrelevant files. - Group names become URL paths: Keep them simple lowercase, no spaces or special chars.
- Changing config while a server is running:
/claw-mo-upreconciles by detecting drift and runningprintf 'y\n' | mo --clearthen rebuilding. Tell the user this is the expected side effect of reconfiguring, not a bug. - autosync defaults to true: every new config entry ships with
"autosync": true. The field is only read by the PostToolUse hook; no runtime effect when the server is stopped. Users can disable per project via/claw-mo-manage.
claw-mo-up
Bring up the mo markdown viewer for the current project and open the browser. When a server is already running, restart it by default so new files on disk become visible (fsnotify can silently miss events).
For config schema, decision tree, --restart vs --clear semantics, and browser opening: read ${CLAUDE_PLUGIN_ROOT}/references/shared.md
Arguments
$ARGUMENTS(optional)--reuse— Skipmo --restartwhen live matches config. Use this when the running session is known-good and the user explicitly wants zero interruption.
Steps
[!NOTE] With autosync enabled (default),
/claw-mo-upis only needed to (a) start mo for the first time in a session, (b) recover from a silent fsnotify miss viamo --restart, or (c) reconcile a drifted runtime to saved config. Routine new-file visibility does not require a restart anymore.
-
Prerequisites:
command -v mo >/dev/null 2>&1. If missing, tell userbrew install k1LoW/tap/moand stop. -
Project key:
git rev-parse --show-toplevel(fallback:$PWD). -
Read config from
${CLAUDE_PLUGIN_DATA}/config.json. If no entry for this project, tell the user to run/claw-mo-setupand stop. -
v1 migration: If the entry has
patternsinstead ofgroups, migrate togroupsformat and save back. -
Probe server:
mo --status --json 2>/dev/null. Extract the server whose port matches$PORT. -
Branch on state — see the decision tree in
shared.md:(a) No server on this port → start per group sequentially:
mo --no-open -w 'pattern1' -w 'pattern2' --target groupName -p $PORT mo --no-open -w 'pattern3' --target anotherGroup -p $PORT(b) Server running, live matches config:
- Default:
mo --restart -p $PORT— fresh fsnotify scan, session preserved. This is the main fix for the "docs exist on disk but don't show up in mo" class of bug. - If
--reuseflag was passed: skip restart, reuse as-is.
(c) Server running, live differs from config (treat config as source of truth):
- Show a concise diff (groups added/removed, patterns changed) so the user sees why a clear is happening
printf 'y\n' | mo --clear -p $PORT- Start per group as in (a)
- Mention that ad-hoc runtime edits were discarded; persist via
/claw-mo-manageor/claw-mo-setupnext time
- Default:
-
Open browser — prefer cmux whenever reachable.
$CMUX_SURFACE_IDalone is not a reliable signal:-
cmux path (
$CMUX_SURFACE_IDset ORcommand -v cmux):cmux list-pane-surfacesto inspect existing surfaces- If a surface already targets
localhost:$PORT, reuse it:cmux browser "surface:N" navigate "http://localhost:$PORT"(keep thesurface:prefix) - Otherwise
cmux browser open "http://localhost:$PORT"(oropen-splitfor first-time split layout)
-
Fallback:
open "http://localhost:$PORT"
-
-
Report what actually happened:
started/restarted (fresh scan)/reused as-is/cleared + rebuilt (config drift)- active groups + file counts (from
mo --status --json) - the URL
Gotchas
- Restart is the default because fsnotify can silently miss file creation events (new subdirectories, high load, macOS FSEvents coalescing).
mo --restartis cheap (<1s), preserves the session, and forces a full re-scan. The old "reuse silently" behavior hid missing files. - Always
--no-openwhen starting mo — the skill controls browser opening separately. - Start groups sequentially, not in parallel — the first invocation must start the server before others can add to it.
- mo auto-restores previous sessions from its backup file. A matching port alone does not guarantee a correct session. Always compare the full live group→patterns mapping to config; if it drifts, clear and rebuild.
- mo status reports absolute patterns; config stores relative globs. Normalize config patterns to absolute paths under the project root before comparing, and sort within each group so ordering differences don't create false mismatches.
mo --restartdoes NOT prompt — safe to call directly. Only--clearneedsprintf 'y\n' |./claw-mo-upis the reconcile point: ad-hoc runtime-only edits belong in/claw-mo-manageor/claw-mo-setupif they should persist.- Prefer cmux over
openwhenever cmux is reachable.$CMUX_SURFACE_IDmay be unset even inside a cmux pane (nested shells). Checkcommand -v cmuxtoo. - Reuse cmux surface before
browser open—openstacks duplicate tabs. Pass the exact identifier (e.g.,surface:4, not4). - Autosync vs.
/claw-mo-up: the PostToolUse hook handles routine new-file visibility for files Claude writes./claw-mo-upremains the fix when (a) mo isn't running yet, (b) fsnotify missed something an external editor wrote, or (c) config drifted. Don't run/claw-mo-upas a reflex on every new file — it's cheap but not free.
Related Commands
/claw-mo-setup— initial project configuration (patterns, groups)/claw-mo-down— stop the mo server/claw-mo-manage— modify patterns, check status, refresh
Hooks 1
Sponsors
Details
- Marketplace
- LeeJuOh/claude-code-zero
- Source
- plugins/claw-mo
- Category
- Community