claude-mods/canvas-tui/README.md

@claude-mods/canvas-tui

Beta - Under active development. Features may change.

Terminal canvas for Claude Code - live markdown preview in split panes.

Works with any terminal that supports split panes: Warp, tmux, iTerm2, Windows Terminal, and more.

Installation

From claude-mods repo (local)

cd claude-mods/canvas-tui
npm link

Then use canvas-tui from anywhere on your machine.

From npm (coming soon)

npm install -g @claude-mods/canvas-tui

Usage

# Watch default location (.claude/canvas/content.md)
canvas-tui --watch

# Watch specific directory
canvas-tui --watch ./my-canvas

# Watch specific file
canvas-tui --file ./draft.md

# Disable mouse scroll capture (keyboard only)
canvas-tui --watch --no-mouse

# Show help
canvas-tui --help

Terminal Setup

Warp

# Split pane: Ctrl+Shift+D (Windows/Linux) or Cmd+Shift+D (Mac)
# Or right-click > Split Pane
canvas-tui --watch

tmux

# Split horizontally and run canvas
tmux split-window -h 'canvas-tui --watch'

# Or split vertically
tmux split-window -v 'canvas-tui --watch'

# From existing tmux session, split current pane
# Ctrl+B then % (horizontal) or " (vertical)

iTerm2

# Split pane: Cmd+D (vertical) or Cmd+Shift+D (horizontal)
canvas-tui --watch

Windows Terminal

# Split pane: Alt+Shift+D
# Or use wt command:
wt split-pane --horizontal canvas-tui --watch

Controls

Key	Action
Up/Down	Scroll line by line
Page Up/Down	Scroll by page
g	Go to top
G	Go to bottom
q / Ctrl+C	Quit
r	Refresh
Mouse wheel	Scroll (terminal-dependent)

Note: Mouse wheel scrolling works in iTerm2, Terminal.app, and most xterm-compatible terminals. In Warp, use arrow keys or Warp's native scrollbar instead.

Integration with Claude Code

This TUI works with the /canvas command in Claude Code:

1. Run /canvas start --type email in Claude Code
2. Open a split pane in your terminal
3. Run canvas-tui --watch in the split pane
4. Claude writes content, you see live preview

File Structure

.claude/canvas/
├── content.md      # Shared content (Claude writes, TUI renders)
└── meta.json       # Session metadata

Requirements

• Node.js >= 18.0.0
• Terminal with ANSI color support

License

MIT