mdview

Markdown, rendered right where you are already looking.

Click a .md path Claude mentions and read the file beside the conversation, with headings, tables, code and
pictures. Then point at any block and tell Claude what to change.

English · 中文

A markdown file rendered in a pane beside the Claude Code conversation

Why

Claude writes its plans, reports and notes as markdown files and gives you the path. Reading one used to mean leaving
the session for an editor or a browser, and editing it meant describing a spot in a file you could not see.

mdview is a Claude Code mod that closes that loop. Paths
become links. A click opens the file in a pane beside the conversation, drawn by Claude Code's own markdown renderer, so
a plan reads like the reply it came from. When something needs to change, you point at the block and say so. Claude
makes the edit, and the pane redraws as it lands.

Highlights


One click to read	A `.md` path that names a real file gets a `↗`, whether it is in backticks, bare, a markdown link or run into Chinese text. Links appear in replies, under `Read` / `Write` / `Edit` rows and under your own prompts. `path:42` and `path#heading` land on the spot
A reader, not a dump	Sections with a Contents list (`t`), Find (`f`), long files in parts (`p` `n`), links between files followed in place, and Back (`b`)
Pictures in the terminal	The terminal's own sharp picture in Ghostty, kitty and iTerm2 3.7+, and colored half blocks anywhere else. PNG, JPEG, GIF and HEIC all work
Point, then edit	Hover a block and it lights up with a `✎`. Say what to change and press Enter; Claude gets the file, the lines and how they begin, and the block shows how the edit is going
Live	A file Claude writes redraws at once; one changed elsewhere within 1.5 s
Your viewer, per terminal	A click opens mdview's pane, Warp's own Markdown viewer split beside the session, or the app macOS opens `.md` with. `/md mode` switches
More than markdown	Any text file opens as highlighted code with line numbers. Common HTML and too-wide tables are turned into something a terminal can show
Claude can show you	Ask to see a file and Claude opens it with `mcp__mdview__show`: in the pane, or in Warp's viewer in Warp

See it work

Point at a block, say the change

A hovered block with its edit bar, and the prompt it sent to Claude

Hover a paragraph, list, table, code block or picture. It lights up, and a ✎ shows at its right end.

Click ✎ and type the change, such as make it a checklist. Enter sends it as your prompt, naming the file,
the lines and how they begin.

Claude edits. A line under the block follows the edit, as Claude Code hangs a result under its row:
✶ Waiting for Claude… while another turn runs, ✶ Claude is editing… once its own starts, then Updated when Claude
wrote the file, or No changes made. The pane redraws in place, and the line goes a few seconds later. Send several and
each keeps its own line; a prompt that cannot be sent says why.

If the file shifts under an open bar, the bar follows its block; if the block is gone, the bar closes.

Install

Needs Claude Code 2.1.287 or later (the release that brought mods; tested on 2.1.300), in the fullscreen layout
(/tui fullscreen), the only layout where a click reaches a mod. Mods are early access, and their API may change
between releases.

/plugin marketplace add xuanji86/claude-mdview
/plugin install mdview@claude-mdview

From a clone instead

git clone https://github.com/xuanji86/claude-mdview ~/Desktop/claude-mdview

Then add it to ~/.claude/settings.json (several folders separate with :):

{ "env": { "CLAUDE_CODE_PLUGIN_DIRS": "~/Desktop/claude-mdview" } }

Or load it for one session only: claude --plugin-dir ~/Desktop/claude-mdview.

Use


Click a `↗` path	Opens it, where your setting says (see Configure)
`/md <path>[#heading\|:line]`	Opens any file in the pane; `/md` alone reopens the last one
`/md mode [choice]`	Switches what a click opens in this terminal; alone, moves to the next choice
Esc · `q`	Closes the pane
`b`	Back to the file you came from
`t` · `f`	Contents · Find (Enter again for the next match)
`p` · `n`	Previous · next part of a long file, also at the foot of each part
`w`	In Warp: this file in Warp's own viewer
Hover → `✎`	Edit that block with Claude

The pane lists its keys in one dim row under the file's name, each a click away too. They work while the pane holds the
keyboard, which it takes when it opens over an empty prompt; a click on the pane gives the keyboard back to it.

Configure

In /config, the rows Click opens and Click opens (Warp). /md mode sets the same values.

Setting	Choices	Default
`clickOpens`	`pane`: mdview's pane · `app`: the app macOS opens `.md` files with	`pane`
`clickOpensInWarp`	`warp`: Warp's Markdown viewer, split to the right · `pane` · `app`	`warp`

If the app or Warp cannot open a file, the click falls back to the pane. The app always opens at the top of the file;
:line works in Warp's viewer and in the pane. To change the app, use Finder: Get Info › Open with › Change All.

Terminals

Terminal	Pictures	A click opens, by default
Ghostty, kitty	Sharp: the terminal's own picture	mdview's pane
iTerm2 3.7+	Sharp, with `CLAUDE_CODE_FORCE_TERMINAL_IMAGES=1` set for iTerm2 only (see below). Without it, half blocks	mdview's pane
Warp	Half blocks in the pane; sharp in Warp's own viewer	Warp's viewer, split to the right
Others	Colored half blocks (`▀`, two pixels a cell)	mdview's pane

Claude Code draws pictures only in terminals it trusts to place them: kitty and Ghostty. iTerm2 3.7 supports the same
kitty graphics protocol, Unicode placeholders included, so it can be switched on there. Put it in ~/.zshrc for iTerm2
alone:

[[ $TERM_PROGRAM == iTerm.app ]] && export CLAUDE_CODE_FORCE_TERMINAL_IMAGES=1

Do not set it for Warp: Warp has no Unicode placeholders yet
(warpdotdev/Warp#6210), and forcing pictures garbles the screen.
Formats other than PNG, and every half-block picture, go through macOS's sips; without it you see their alt text.

What it can reach

mdview reads, draws, and acts only when you ask it to. claude plugin validate . prints every hook and call it makes.

It	When
reads a file	its path is in the conversation (to see that it exists), or you open it
runs `sips`	it draws a picture other than a PNG, or any picture as half blocks: into a file under `$TMPDIR` (a half-block one is removed once read)
runs `open`	you click with `app` or `warp` chosen, for markdown files only. The model's show tool never uses it, so it cannot launch a script or an app
sends a prompt	you press Enter in a `✎` bar, and only with the text you typed
changes a setting	you run `/md mode`

It makes no network requests, stores nothing across sessions, and calls no model of its own.

Limits

No true fullscreen. A mod's pane docks beside the transcript, which keeps a minimum width; mdview asks for all the
rest.
Clicks need the fullscreen layout. On the main screen, use /md.
A terminal draws text. Math, mermaid and heading sizes show as written. Warp's own viewer does draw mermaid.
Redrawn replies. A reply with a clickable path is drawn by mdview, so copying it brings its ⏺ along.
Size. One markdown element holds at most 10,000 characters and a pane about 100,000, so long files come in parts.
Early access. The mods API may change between Claude Code releases.

Develop

claude plugin validate .
claude plugin test .            # 38 tests
python3 assets/make_previews.py # the README pictures

A saved file reloads the mod in every session that loads it from this folder.

claude-mdview