Cmux Markdown

Markdown Viewer with cmux

Use this skill to display markdown files in a dedicated panel with rich formatting and live file watching.

Core Workflow

1. Write your plan or notes to a .md file. 2. Open it in a markdown panel. 3. The panel auto-updates when the file changes on disk.

# Open a markdown file as a split panel next to the current terminal
cmux markdown open plan.md

# Absolute path
cmux markdown open /path/to/PLAN.md

# Target a specific workspace
cmux markdown open design.md --workspace workspace:2

When to Use

• Displaying an agent plan or task list alongside the terminal
• Showing documentation, changelogs, or READMEs while working
• Reviewing notes that update in real-time (e.g., a plan file being written by another process)

Live File Watching

The panel automatically re-renders when the file changes on disk. This works with:

• Direct writes (echo "..." >> plan.md)
• Editor saves (vim, nano, VS Code)
• Atomic file replacement (write to temp, rename over original)
• Agent-generated plan files that are updated progressively

If the file is deleted, the panel shows a "file unavailable" state. During atomic replace, the panel attempts automatic reconnection within its short retry window. If the file returns later, close and reopen the panel.

Agent Integration

Opening a plan file

Write your plan to a file, then open it:

cat > plan.md << 'EOF'
# Task Plan

## Steps
1. Analyze the codebase
2. Implement the feature
3. Write tests
4. Verify the build
EOF

cmux markdown open plan.md

Updating a plan in real-time

The panel live-reloads, so simply overwrite the file as work progresses:

# The markdown panel updates automatically when the file changes
echo "## Step 1: Complete" >> plan.md

Recommended AGENTS.md instruction

Add this to your project's AGENTS.md to instruct coding agents to use the markdown viewer:

## Plan Display

When creating a plan or task list, write it to a `.md` file and open it in cmux:

    cmux markdown open plan.md

The panel renders markdown with rich formatting and auto-updates when the file changes.

Routing

# Open in the caller's workspace (default -- uses CMUX_WORKSPACE_ID)
cmux markdown open plan.md

# Open in a specific workspace
cmux markdown open plan.md --workspace workspace:2

# Open splitting from a specific surface
cmux markdown open plan.md --surface surface:5

# Open in a specific window
cmux markdown open plan.md --window window:1

Deep-Dive References

Rendering Support

The markdown panel renders:

• Headings (h1-h6) with dividers on h1/h2
• Fenced code blocks with monospaced font
• Inline code with highlighted background
• Tables with alternating row colors
• Ordered and unordered lists (nested)
• Blockquotes with left border
• Bold, italic, strikethrough
• Links (clickable)
• Horizontal rules
• Images (inline)

Supports both light and dark mode.

Command Reference (cmux Markdown)

Opening a Markdown Panel

cmux markdown open <path>
cmux markdown <path>          # shorthand (implicit "open")

Options

Output

OK surface=surface:8 pane=pane:3 path=/absolute/path/to/file.md

With --json:

{
  "window_id": "...",
  "workspace_id": "...",
  "pane_id": "...",
  "surface_id": "...",
  "path": "/absolute/path/to/file.md"
}

Path Resolution

• Relative paths are resolved against the caller's current working directory.
• ~ is expanded to the home directory.
• The resolved absolute path is returned in the output.

# These are equivalent when run from /Users/me/project
cmux markdown open plan.md
cmux markdown open ./plan.md
cmux markdown open /Users/me/project/plan.md

Panel Behavior

• The panel opens as a horizontal split to the right of the source surface.
• The tab title shows the filename (e.g., plan.md).
• The tab icon is a document icon.
• Content is read-only with text selection enabled.
• The file path is displayed as a breadcrumb at the top of the panel.

Session Persistence

Markdown panels are saved and restored across sessions. On restore, the panel re-reads the file from disk. If the file no longer exists at restore time, the panel is not recreated.

Help

cmux markdown --help
cmux markdown -h

See also:

• live-reload.md

Live Reload Behavior

The markdown panel watches the file on disk and automatically re-renders when it changes. This enables real-time plan tracking as agents or editors update the file.

How It Works

The panel uses a kernel-level file system watcher (DispatchSource with O_EVTONLY) that monitors the file for:

• Write events -- content was modified in place
• Extend events -- content was appended
• Delete events -- file was removed (atomic replace step 1)
• Rename events -- file was moved or renamed

Supported Write Patterns

Atomic File Replacement

Many editors and tools write files atomically: write to a temporary file, then rename it over the original. This shows up as a delete event followed by a new file appearing at the same path.

The panel handles this by:

1. Detecting the delete/rename event 2. Attempting to re-read the file immediately (in case the rename already happened) 3. If the file is missing, wait 500 ms and check again (the new file may not yet be in place) 4. Reconnecting the file watcher to the new inode

File Unavailable State

If the file is deleted and does not reappear within the retry window, the panel shows a "file unavailable" state with the original path. The panel does not close automatically -- the user must close it manually.

If the file later reappears at the same path (e.g., the user recreates it), the panel does NOT automatically reconnect. Close and reopen the panel to pick up the new file.

Performance

• Re-reads are dispatched to the main thread and run synchronously.
• Large files (100KB+) may cause brief UI hitches during re-render. For extremely large markdown files, consider splitting into smaller documents.
• The file watcher runs on a low-priority background queue and has negligible CPU impact.

Tips for Agents

• Write the full plan file first, then open it. This avoids the panel showing a partially written file.
• Append-style updates work well. Adding sections to the end of a file triggers a smooth re-render.
• Overwriting the entire file is fine. The atomic replace handling ensures no data is lost.
• Don't delete and recreate rapidly. If writing a new version, prefer overwriting in place or using atomic replacement.