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-zero

Run it inside Claude Code after adding the marketplace with /plugin marketplace add LeeJuOh/claude-code-zero.

Contents

Discovered from source

Skills 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

  1. Prerequisites: command -v mo >/dev/null 2>&1. If missing, tell the user brew install k1LoW/tap/mo and stop.

  2. Project key: git rev-parse --show-toplevel (fallback: $PWD).

  3. 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.

  4. 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.
  5. Shutdown: mo --shutdown -p $PORT

  6. Verify: re-run mo --status --json 2>/dev/null and confirm the port is gone. Report the result:

    • Success → "Stopped mo on :$PORT. Config preserved — run /claw-mo-up to restart."
    • Still present → warn the user (rare; orphaned process) and suggest kill <pid> using the PID from status.

Gotchas

  • Config is preserved — shutdown only stops the server, it doesn't delete the project config. /claw-mo-up will 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 --shutdown exits silently — that's why this skill checks --status --json first 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:

  1. Ask which group (show existing groups)
  2. Ask the glob pattern
  3. If server running: mo --no-open -w "$PATTERN" -t "$GROUP" -p $PORT
    • Otherwise skip the runtime step
  4. Update config file
  5. Confirm

Remove pattern:

  1. Show current patterns per group
  2. Ask which to remove
  3. If server running: mo --unwatch "$PATTERN" -t "$GROUP" -p $PORT
    • mo accepts either the original glob or the absolute path form reported by --status
  4. Update config file
  5. 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:

  1. curl -s "http://localhost:$PORT/_/api/groups" → list files in each group
  2. Ask which file
  3. mo --close "$(realpath file)" -t "$GROUP" -p $PORT
  4. No config update needed (ad-hoc file, not a pattern)

Refresh (re-scan):

  1. mo --restart -p $PORT (no prompt, safe)
  2. Verify with mo --status --json and report new file counts
  3. This is the fix when docs exist on disk but don't appear in mo — same mechanism /claw-mo-up uses by default.

Reset session:

  1. printf 'y\n' | mo --clear -p $PORT
  2. Ask: "Restart with saved config now?" (equivalent to /claw-mo-up)
  3. If yes, run the per-group start sequence from config

Stop a server:

  1. Show all running servers (from mo --status --json) with their ports and projects
  2. Ask which to stop (by number or port)
  3. mo --shutdown -p $PORT
  4. Confirm — note that config is preserved so /claw-mo-up can restart it later

Toggle autosync:

  1. Read current autosync field (default true if absent)
  2. Show current state: Autosync is ON — .md writes by Claude are added to mo automatically.
  3. AskUserQuestion: flip it?
  4. Update config file only — no runtime call needed; the hook reads the config on each fire
  5. 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 --restart over --clear for rescans — restart preserves session; clear destroys the backup. The old "just clear everything" reflex wipes state that didn't need wiping.
  • Only --clear prompts for confirmation — pipe printf 'y\n'. --restart, --shutdown, --close, --unwatch do 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-up will 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 --restart runs.
  • "Stop a server" only stops the process — config and backup are preserved so /claw-mo-up can restart it later.
  • mo --unwatch accepts both relative globs and absolute paths (the form --status shows). 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)
  • Examples:
    • /claw-mo-open docs/spec.md
    • /claw-mo-open plans/ --group plans
    • some-tool | /claw-mo-open - --group scratch

Steps

  1. Parse $ARGUMENTS:

    • Detect --stdin or 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 to default)
  2. Prerequisites: command -v mo >/dev/null 2>&1.

  3. Project key: git rev-parse --show-toplevel (fallback: $PWD).

  4. Read config from ${CLAUDE_PLUGIN_DATA}/config.json.

  5. Check running server: mo --status --json → is a server on $PORT?

  6. 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-up would 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-up unless config is updated
  7. 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-up behavior first (restart if server reappears mid-flight), then retry step 7
    • No config → quick-open with auto-config:
      1. Auto-assign port: echo $((6300 + $(echo "$PROJECT_ROOT" | cksum | cut -d' ' -f1) % 100))
      2. Start mo:
        • File: mo --no-open -p $PORT "$(realpath file.md)"
        • Dir: mo --no-open -p $PORT "$(realpath dir)" (mo converts dir → dir/*.md watch)
        • Stdin: cat | mo --no-open -p $PORT
      3. Save minimal config to ${CLAUDE_PLUGIN_DATA}/config.json:
        { "PROJECT_ROOT": { "port": PORT, "groups": { "default": ["*.md"] } } }
        
      4. Tell the user: "Saved a minimal config. Run /claw-mo-setup to customize watch groups."
  8. 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 prefix stdin-.

    Directory mode: no single file to link to; use http://localhost:$PORT/$GROUP.

  9. Open browser using the cmux-preferred logic from shared.md (reuse existing surface if one targets this port).

  10. 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 realpath before 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-up unless persisted through /claw-mo-setup or /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 /GROUP still 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 | mo requires stdin to not be a TTY. Fine when a pipe is present; fails silently if Claude somehow passes an interactive stdin. The shell pipe cat | mo forces non-TTY.
  • Quick-open saves a minimal config so /claw-mo-up, /claw-mo-down, and /claw-mo-manage can 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

  1. Prerequisites check

    • command -v mo >/dev/null 2>&1 → if missing: brew install k1LoW/tap/mo, stop
    • If $CMUX_SURFACE_ID is 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.
  2. Detect project root: git rev-parse --show-toplevel (fallback: $PWD)

  3. 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
  4. Scan markdown files:

    find "$PROJECT_ROOT" -name '*.md' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/vendor/*' 2>/dev/null | wc -l
    

    Warn if 500+.

  5. 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
    
  6. 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 example raw/articles/**/*.md but not raw/**/*.md when raw/repos/** dominates)
    • If root .md files exist, suggest group default with *.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
  7. 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.
    
  8. Save config to ${CLAUDE_PLUGIN_DATA}/config.json (create file if needed, merge if exists). Use v2 groups format. Include "autosync": true on new entries so PostToolUse adds newly-written .md files to the running mo server without /claw-mo-up.

  9. 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-up will 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."

Gotchas

  • **/*.md can 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/**/*.md that 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-up reconciles by detecting drift and running printf 'y\n' | mo --clear then 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 — Skip mo --restart when 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-up is only needed to (a) start mo for the first time in a session, (b) recover from a silent fsnotify miss via mo --restart, or (c) reconcile a drifted runtime to saved config. Routine new-file visibility does not require a restart anymore.

  1. Prerequisites: command -v mo >/dev/null 2>&1. If missing, tell user brew install k1LoW/tap/mo and stop.

  2. Project key: git rev-parse --show-toplevel (fallback: $PWD).

  3. Read config from ${CLAUDE_PLUGIN_DATA}/config.json. If no entry for this project, tell the user to run /claw-mo-setup and stop.

  4. v1 migration: If the entry has patterns instead of groups, migrate to groups format and save back.

  5. Probe server: mo --status --json 2>/dev/null. Extract the server whose port matches $PORT.

  6. 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 --reuse flag was passed: skip restart, reuse as-is.

    (c) Server running, live differs from config (treat config as source of truth):

    1. Show a concise diff (groups added/removed, patterns changed) so the user sees why a clear is happening
    2. printf 'y\n' | mo --clear -p $PORT
    3. Start per group as in (a)
    4. Mention that ad-hoc runtime edits were discarded; persist via /claw-mo-manage or /claw-mo-setup next time
  7. Open browser — prefer cmux whenever reachable. $CMUX_SURFACE_ID alone is not a reliable signal:

    • cmux path ($CMUX_SURFACE_ID set OR command -v cmux):

      1. cmux list-pane-surfaces to inspect existing surfaces
      2. If a surface already targets localhost:$PORT, reuse it: cmux browser "surface:N" navigate "http://localhost:$PORT" (keep the surface: prefix)
      3. Otherwise cmux browser open "http://localhost:$PORT" (or open-split for first-time split layout)
    • Fallback: open "http://localhost:$PORT"

  8. 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 --restart is cheap (<1s), preserves the session, and forces a full re-scan. The old "reuse silently" behavior hid missing files.
  • Always --no-open when 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 --restart does NOT prompt — safe to call directly. Only --clear needs printf 'y\n' |.
  • /claw-mo-up is the reconcile point: ad-hoc runtime-only edits belong in /claw-mo-manage or /claw-mo-setup if they should persist.
  • Prefer cmux over open whenever cmux is reachable. $CMUX_SURFACE_ID may be unset even inside a cmux pane (nested shells). Check command -v cmux too.
  • Reuse cmux surface before browser open — open stacks duplicate tabs. Pass the exact identifier (e.g., surface:4, not 4).
  • Autosync vs. /claw-mo-up: the PostToolUse hook handles routine new-file visibility for files Claude writes. /claw-mo-up remains 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-up as 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

Sponsors

Details

Marketplace
LeeJuOh/claude-code-zero
Source
plugins/claw-mo
Category
Community

More from LeeJuOh/claude-code-zero

All 12