Spark
Sign In
Skill

Display Markdown files in cmux without blank panes

Fixes cmux's markdown pane bug: never move-surface a markdown viewer, open it right the first time or close and reopen fresh.

Get skill
Works with cmux
davidondrej
Maintainer?
91
Spark score
out of 100
Updated 15 days ago
Version 1.0.0
Add to Favorites

Why it matters

Reliably render Markdown files in cmux's right pane without triggering the blank-viewer bug that occurs when moving markdown surfaces between panes.

Outcomes

What it gets done

01

Open Markdown files directly into the correct cmux pane on first try

02

Close conflicting right panes before spawning a fresh Markdown viewer

03

Avoid the move-surface bug that causes blank Markdown rendering

04

Anchor operations to the current workspace without stealing focus

Install

Add it to your toolbox

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/ag-markdown-rendering | bash

Overview

Markdown Rendering in cmux

Works around a cmux bug where moving a markdown viewer into an existing pane via move-surface renders it blank, by either opening markdown fresh into an empty right pane or closing conflicting right panes first. Use it when opening Markdown in cmux shows a blank pane or the wrong layout. Never move-surface a markdown viewer, and never close a pane the user is actively working in.

What it does

Fixes a specific cmux bug: cmux markdown open always spawns a brand-new pane, even with --direction right, and the common workaround of moving that markdown surface into an existing right pane via move-surface renders it blank - the surface keeps type=markdown and looks healthy but shows nothing. This skill gives the two reliable ways around that bug instead of the broken move-surface path.

When to use - and when NOT to

Use it when opening Markdown in cmux shows a blank pane or the wrong layout, or when you need to display a Markdown file in a stable cmux right pane. Never move-surface a markdown viewer - that is exactly the path that bugs out and is the core reason this skill exists. Only close panes that are unused or irrelevant; never close a pane the user is actively working in.

Inputs and outputs

Option A - open it right on the first try, when there is no usable right pane yet: let cmux create one and leave it where it lands, then do NOT move it:

cmux markdown open /abs/path/file.md --direction right --focus false

Option B - if other, unused or irrelevant right panes are in the way, close them first, then open the markdown fresh so it creates its own clean right pane:

cmux list-panes --workspace "$CMUX_WORKSPACE_ID"
cmux list-pane-surfaces --pane pane:NN
cmux close-surface --surface surface:XX     # repeat per surface in that pane
cmux markdown open /abs/path/file.md --direction right --focus false

If it spawned where you wanted it, you're done - no further action needed either way. Output is a markdown viewer rendered in a stable right pane - always anchored to $CMUX_WORKSPACE_ID rather than whichever workspace is visually focused, and opened with --focus false so it doesn't steal the user's focus. There is no way to screenshot or read a markdown surface to verify it rendered; if unsure, ask the user.

Integrations

Wraps cmux's own pane and surface commands (markdown open, list-panes, list-pane-surfaces, close-surface) and is adapted from davidondrej/skills. Verify local paths, tools, credentials, and agent features before acting, and for any commands, remote access, scheduling, browser automation, or file-changing workflows it triggers, get explicit user approval and confirm the target environment first.

Who it's for

Agents and developers working inside cmux who need a markdown file displayed reliably in a right pane, rather than fighting a stray extra pane or a viewer that silently renders blank after being moved.

Source README

Markdown Rendering in cmux

When to Use

  • Use when opening Markdown in cmux shows a blank pane or wrong layout.
  • Use when you need to display a Markdown file in a stable cmux right pane.

The Problem

cmux markdown open defaults to spawning a brand-new pane every time, even with --direction right. The common "fix" - moving the new markdown surface into the existing right pane with move-surface - bugs out: the moved viewer renders BLANK. The surface keeps type=markdown and looks healthy, but shows nothing.

So you get stuck: either a stray extra pane, or a blank viewer after moving it.

The Rule

You have exactly two reliable options. Never move-surface a markdown viewer - that is the path that bugs.

Option A - Open it right on the first try

If there is no usable right pane yet, just let cmux create one and leave it where it lands:

cmux markdown open /abs/path/file.md --direction right --focus false

Do NOT then move it. If it spawned where you want it, you're done.

Option B - Close existing right pane(s), then open fresh

If there are other right panes in the way (and they're unused or irrelevant), close them first, then open the markdown fresh as a new right pane:

### 1. find panes in THIS workspace
cmux list-panes --workspace "$CMUX_WORKSPACE_ID"

### 2. close the unused/irrelevant right pane(s) by closing their surfaces
cmux list-pane-surfaces --pane pane:NN
cmux close-surface --surface surface:XX     # repeat per surface in that pane

### 3. THEN open the markdown fresh — it creates its own clean right pane
cmux markdown open /abs/path/file.md --direction right --focus false

Hard Rules

  • Never move-surface a markdown viewer. It renders blank afterward. This is the core bug this skill exists for.
  • Open it correctly the first time (Option A), OR close the conflicting right pane(s) and open a fresh right pane from scratch (Option B).
  • Only close panes that are unused or irrelevant - never close a pane the user is working in.
  • Always anchor to $CMUX_WORKSPACE_ID; never assume the visually focused workspace.
  • Pass --focus false so you don't steal the user's focus.
  • You can't screenshot/read a markdown surface to verify it. If unsure it rendered, ask the user.

Limitations

  • Adapted from davidondrej/skills; verify local paths, tools, credentials, and agent features before acting.
  • For commands, remote access, scheduling, browser automation, or file-changing workflows, get explicit user approval and confirm the target environment first.

Discussion

Questions & comments · 0

Sign In Sign in to leave a comment.