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.