# @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)

```bash
cd claude-mods/canvas-tui
npm link
```

Then use `canvas-tui` from anywhere on your machine.

### From npm (coming soon)

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

## Usage

```bash
# 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
```bash
# Split pane: Ctrl+Shift+D (Windows/Linux) or Cmd+Shift+D (Mac)
# Or right-click > Split Pane
canvas-tui --watch
```

### tmux
```bash
# 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
```bash
# Split pane: Cmd+D (vertical) or Cmd+Shift+D (horizontal)
canvas-tui --watch
```

### Windows Terminal
```bash
# 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