\n\n---\n\n# reviw\n\nA lightweight browser-based tool for reviewing and annotating tabular data, text, Markdown, and diff files. Built entirely in [MoonBit](https://www.moonbitlang.com/) (zero hand-written JavaScript). Supports CSV, TSV, plain text, Markdown, and unified diff formats. Comments are output as YAML to stdout.\n\n## Features\n\n### File Format Support\n- **CSV/TSV**: View tabular data with sticky headers, column freezing, filtering, and column resizing\n- **Markdown**: Side-by-side preview with synchronized scrolling, click-to-comment from preview\n- **Diff/Patch**: GitHub-style diff view with syntax highlighting, collapsible large files (500+ lines), and binary files sorted to end\n- **Text**: Line-by-line commenting for plain text files\n\n### Mermaid.js Diagrams\n- Auto-detect and render Mermaid diagrams in Markdown files\n- Click any diagram to open fullscreen viewer with minimap\n- Zoom with mouse wheel (centered on cursor position, up to 10x)\n- Pan with mouse drag\n- Trackpad pinch-to-zoom and touch gesture support\n- Shift+scroll zoom for Windows users\n- Dark mode support for thumbnails\n- Highlights corresponding source line after closing fullscreen\n- Syntax error display in toast notifications\n\n### Media Sidebar\n- Thumbnail gallery of all images and videos in the left sidebar\n- Click any thumbnail to scroll to the corresponding media and highlight it\n- ArrowUp/ArrowDown to jump between media, Escape to clear the selection\n- Numbered badges for quick identification\n\n### Media Embed Discipline (AI-friendly)\n- `reviw file.md` refuses to start (exit 1) when media files are written as `[text](path)` links instead of `` embeds\n- The error lists every violation with line numbers and ready-to-apply fixes, so AI agents can self-correct and retry\n\n### Media Fullscreen\n- Click images in Markdown preview to open fullscreen viewer\n- Click videos to open fullscreen playback with YouTube-like keyboard shortcuts (Space/K, J/L, arrow keys, 0-9)\n- Click anywhere (including the image/video itself) to close the fullscreen overlay\n- Clicking media automatically highlights the corresponding source line in the Markdown panel\n- Video timeline settings with adjustable scene detection sensitivity\n\n### UI Features\n- **Theme toggle**: Switch between light and dark modes\n- **Preview-only mode**: Hide source panel for wide preview reading\n- **Heading toggle**: Collapse/expand sections by clicking heading arrows\n- **Multi-file support**: Open multiple files simultaneously on separate ports\n- **Drag selection**: Select rectangular regions or multiple rows for batch comments\n- **Real-time updates**: Hot reload on file changes via SSE\n- **Comment persistence**: Auto-save comments to localStorage with recovery modal\n- **Image attachment**: Attach images to comments and submit dialog (paste with Cmd/Ctrl+V)\n- **Selected-lines copy**: Copy button in comment dialog to copy selected line text\n- **Keyboard shortcuts**: Cmd/Ctrl+Enter to open submit modal\n- **Multi-tab sync**: Submit from any tab closes all tabs for the same file\n- **Server detection**: Reuse existing server instead of starting a new one (via lock files)\n- **Tab activation (macOS)**: Automatically activates existing browser tab via AppleScript\n- **Review history**: File-based persistent review history\n- **details/summary support**: HTML details/summary tags rendered as collapsible sections\n\n### Output\n- YAML format with file, mode, row, col, value, and comment text\n- Overall summary field for review notes\n- Image attachments included as base64 data\n\n## Installation\n\n```bash\nnpm install -g reviw\n```\n\nOr run directly with npx:\n\n```bash\nnpx reviw \n```\n\n## Usage\n\n```bash\n# Single file\nreviw [--port 4989] [--encoding utf8|shift_jis|...]\n\n# Multiple files (each opens on consecutive ports)\nreviw file1.csv file2.md file3.tsv --port 4989\n\n# Diff from stdin\ngit diff HEAD | reviw\n\n# Diff file\nreviw changes.diff\n```\n\n### Options\n- `--port `: Specify starting port (default: 4989)\n- `--encoding `: Force specific encoding (auto-detected by default)\n- `--no-open`: Prevent automatic browser opening\n- `--help, -h`: Show help message\n- `--version, -v`: Show version number\n\n### Workflow\n1. Browser opens automatically (macOS: `open` / Linux: `xdg-open` / Windows: `start`)\n2. Click cells/lines to add comments, or drag to select multiple\n3. Use Cmd/Ctrl+Enter or click \"Submit & Exit\" to output comments\n4. Comments are printed as YAML to stdout\n\n## Screenshots\n\n### Markdown View with Media Sidebar\n\n\n### Preview-only Mode\n\n\n### Heading Toggle\n\n\n### Comment Dialog with Image Attachment\n\n\n### Video Fullscreen with Timeline Thumbnails\n\n\n### Mermaid Fullscreen with Minimap\n\n\n### Submit Review Dialog with Image Attachment\n\n\n### CSV View\n\n\n### Diff View\n\n\n## Output Example\n\n```yaml\nfile: data.csv\nmode: csv\nreason: button\nat: '2025-11-26T12:00:00.000Z'\ncomments:\n - row: 2\n col: 3\n text: This value needs review\n value: '150'\nsummary: Overall the data looks good, minor issues noted above.\n```\n\n## Claude Code Plugin\n\nThis repository also serves as a Claude Code plugin marketplace. The plugin integrates reviw into Claude Code workflows with task management and review automation.\n\n### Installation\n\n```bash\n# In Claude Code\n/plugin marketplace add kazuph/reviw\n/plugin install reviw-plugin@reviw-plugins\n```\n\n### Install Skills with `npx skills`\n\nUse this route when you want the task skills in Codex, OpenCode, Cursor, or other agent environments that support `npx skills`. For Claude Code, use the plugin installation flow above.\n\n```bash\n# Preview what will be installed\nnpx skills add https://github.com/kazuph/reviw --list\n\n# Install all reviw skills globally for Codex\nnpx skills add https://github.com/kazuph/reviw -g -a codex -s '*' --copy -y\n\n# Install all reviw skills globally for Codex and OpenCode\nnpx skills add https://github.com/kazuph/reviw -g -a codex -a opencode -s '*' --copy -y\n```\n\n`npx skills` distributes the skill directories under `plugin/skills/`. With `-a codex -g --copy`, the skills are copied into Codex's global skills directory at `~/.agents/skills/`. If `~/.agents/skills` is a symlink, the copied files land in the symlink target.\n\nClaude Code plugin commands and hooks are installed through the Claude Code plugin flow above, not through `npx skills`.\n\n### Plugin Directory Structure\n\n```\nplugin/\nāāā .claude-plugin/\nā āāā plugin.json # Plugin metadata (name, version, description)\nāāā agents/\nā āāā report-builder.md # Report generation agent\nā āāā e2e-health-reviewer.md # E2E test health check\nā āāā review-code-quality.md # Code quality review\nā āāā review-security.md # Security audit\nā āāā review-a11y-ux.md # Accessibility & UX\nā āāā review-figma-fidelity.md # Design fidelity\nā āāā review-copy-consistency.md # Text consistency\nā āāā review-e2e-integrity.md # E2E test integrity\nāāā skills/\nā āāā ask/\nā ā āāā SKILL.md # Requirements elicitation skill\nā āāā bucho/\nā ā āāā SKILL.md # Manager orchestration skill\nā āāā do/\nā ā āāā SKILL.md # Task start skill\nā āāā done/\nā ā āāā SKILL.md # Task completion skill\nā āāā exit-notifier/\nā ā āāā SKILL.md # Background task exit notification skill\nā ā āāā scripts/\nā ā āāā watch-exit-notify.sh\nā āāā tiny-do/\nā ā āāā SKILL.md # Lightweight task start skill\nā āāā tiny-done/\nā ā āāā SKILL.md # Lightweight task completion skill\nā āāā validate-report/\nā ā āāā SKILL.md # Internal REPORT.md validation helper\nā āāā artifact-proof/\nā ā āāā SKILL.md # Evidence collection skill\nā āāā webapp-testing/\nā āāā SKILL.md # Web testing skill\nā āāā scripts/ # Helper scripts\nā āāā examples/ # Usage examples\nāāā hooks/\nā āāā hooks.json # Hook definitions\nāāā hooks-handlers/\nā āāā completion-checklist.sh # UserPromptSubmit handler\nāāā README.md\n```\n\n### Components Overview\n\n| Type | Name | Description |\n|------|------|-------------|\n| **Task Skill** | `/reviw:do` | Start a task - create worktree with git wt, plan, register todos |\n| **Task Skill** | `/reviw:done` | Complete checklist - run 7 review agents, collect evidence, start review |\n| **Task Skill** | `/reviw:tiny-do` | Start a smaller task with the lightweight workflow |\n| **Task Skill** | `/reviw:tiny-done` | Finish a smaller task with lightweight review |\n| **Task Skill** | `/reviw:bucho` | Orchestrate Claude Code and Codex in manager mode |\n| **Agent** | `report-builder` | Prepare reports and evidence for user review |\n| **Agent** | `review-code-quality` | Code quality: readability, DRY, type safety, error handling |\n| **Agent** | `review-security` | Security: XSS, injection, OWASP Top 10, secrets detection |\n| **Agent** | `review-a11y-ux` | Accessibility: WCAG 2.2 AA, keyboard nav, UX flow |\n| **Agent** | `review-figma-fidelity` | Design: token compliance, visual consistency |\n| **Agent** | `review-copy-consistency` | Copy: text consistency, tone & manner, i18n |\n| **Agent** | `review-e2e-integrity` | E2E: user flow reproduction, mock contamination |\n| **Agent** | `e2e-health-reviewer` | E2E: goto restrictions, record assertions, hardcoding |\n| **Skill** | `artifact-proof` | Collect evidence (screenshots, videos, logs) |\n| **Skill** | `exit-notifier` | Notify the current tmux / Herdr pane when background tasks exit, including captured stdout/stderr |\n| **Skill** | `webapp-testing` | Browser automation and verification with Playwright |\n| **Hook** | PreToolUse | Remind to review before git commit/push |\n| **Hook** | UserPromptSubmit | Inject completion checklist into AI context |\n\n---\n\n### Task Skills\n\n#### Bundled task skills\n\n| Skill | Purpose |\n|------|---------|\n| `ask` | Clarify requirements, scope, constraints, and success criteria before implementation |\n| `bucho` | Orchestrate Claude Code and Codex as a managed team through tmux |\n| `check-yourself` | Force real verification instead of assumptions or lightweight spot checks |\n| `commit-and-push` | Generate a commit message, create the commit, push it, and confirm a clean git state |\n| `do` | Start the full task workflow with worktree setup, planning, and review preparation |\n| `done` | Run the full completion workflow with evidence collection and reviw-based review |\n| `exit-notifier` | Report background task completion and captured stdout/stderr back into the current tmux / Herdr pane |\n| `open` | Open files, artifacts, and URLs with macOS `open` |\n| `tiny-do` | Start a smaller task with the lightweight workflow |\n| `tiny-done` | Finish a smaller task with the lightweight completion flow |\n| `validate-report` | Internal helper used by `done` to validate `REPORT.md` against artifact-proof reporting rules |\n\n#### `/reviw:do `\n\nStarts a new task with proper environment setup.\n\n**What it does:**\n1. Creates a git worktree using git wt for isolated development (`feature/`, `fix/`, etc.)\n2. Sets up `.artifacts//` directory for evidence\n3. Creates `REPORT.md` with plan and TODO checklist\n4. Registers todos in TodoWrite for progress tracking\n\n**Directory structure created:**\n```\n/ # e.g., .worktree/feature-auth/\nāāā .artifacts/\n āāā / # e.g., auth (from feature/auth)\n āāā REPORT.md # Plan, progress, evidence links\n āāā images/ # Screenshots\n āāā videos/ # Video recordings\n```\n\n**Task resumption:** When a session starts or after context compaction, the skill checks for existing worktrees (via `git wt`) and resumes from `REPORT.md`.\n\n#### `/reviw:done`\n\nValidates completion criteria before allowing task completion.\n\n**Checklist enforced:**\n- [ ] Build succeeded (no type/lint errors)\n- [ ] Development server started and working\n- [ ] Verified with `webapp-testing` skill\n- [ ] Evidence collected in `.artifacts//`\n- [ ] Report created with `artifact-proof` skill\n- [ ] Reviewed with reviw (foreground mode)\n- [ ] User approval received\n\n**Prohibited:**\n- Saying \"implementation complete\" without verification\n- Committing/pushing before reviw review\n- Reports without evidence\n\n---\n\n### Agents\n\n#### Review Agents (7 agents run in parallel)\n\nWhen `/reviw:done` is executed, 7 review agents run simultaneously and append their findings to `REPORT.md`:\n\n| Agent | Focus | Output Section |\n|-------|-------|----------------|\n| `review-code-quality` | Readability, DRY, type safety, error handling | Code Quality Review |\n| `review-security` | XSS, injection, OWASP Top 10, secrets | Security Review |\n| `review-a11y-ux` | WCAG 2.2 AA, keyboard nav, focus management | A11y & UX Review |\n| `review-figma-fidelity` | Design tokens, visual consistency | Figma Fidelity Review |\n| `review-copy-consistency` | Text consistency, i18n, tone & manner | Copy Consistency Review |\n| `review-e2e-integrity` | User flow reproduction, mock contamination | E2E Integrity Review |\n| `e2e-health-reviewer` | goto restrictions, record assertions | E2E Health Review |\n\n**Total score:** Each agent scores X/5, combined for X/35 total.\n\n**Invocation (parallel):**\n```\nTask tool with 7 parallel calls:\n subagent_type: \"review-code-quality\"\n subagent_type: \"review-security\"\n subagent_type: \"review-a11y-ux\"\n subagent_type: \"review-figma-fidelity\"\n subagent_type: \"review-copy-consistency\"\n subagent_type: \"review-e2e-integrity\"\n subagent_type: \"e2e-health-reviewer\"\n```\n\n#### `report-builder`\n\nSpecialized agent for preparing review materials (runs after review agents).\n\n**Role:**\n- Organize implementation into a structured report\n- Calculate total review score (X/35)\n- Collect and arrange evidence (screenshots, videos)\n- Prepare `REPORT.md` for reviw review\n- Parse reviw feedback and register as todos\n\n**Invocation:**\n```\nTask tool with subagent_type: \"report-builder\"\n```\n\n**Skills auto-loaded:** `artifact-proof`\n\n---\n\n### Skills\n\n#### `artifact-proof`\n\nManages evidence collection for visual regression and PR documentation.\n\n**Features:**\n- Screenshots and videos under `.artifacts//`\n- Playwright integration for automated capture\n- Git LFS setup for video files\n- PR image URLs with commit hashes (persist after branch deletion)\n\n**reviw integration:**\n```bash\n# Open report in reviw (foreground required)\nnpx reviw .artifacts//REPORT.md\n\n# With video preview\nopen .artifacts//videos/demo.webm\nnpx reviw .artifacts//REPORT.md\n```\n\n#### `webapp-testing`\n\nBrowser automation toolkit using Playwright.\n\n**Features:**\n- TypeScript Playwright Test (`@playwright/test`)\n- Playwright configuration with webServer support\n- Screenshot and video capture\n- Console log and network request monitoring\n- CDP integration for advanced debugging\n\n**Quick verification:**\n```bash\nnode -e \"const { chromium } = require('playwright');\n(async () => {\n const browser = await chromium.launch();\n const page = await browser.newPage();\n await page.goto('http://localhost:3000', { waitUntil: 'networkidle' });\n await page.screenshot({ path: '/tmp/webapp.png', fullPage: true });\n await browser.close();\n})();\"\n```\n\n---\n\n### Hooks\n\n#### PreToolUse (Bash matcher)\n\nTriggers when `git commit` or `git push` is detected.\n\n**Message:** Reminds to run `/reviw:done` and review with reviw before committing.\n\n#### UserPromptSubmit\n\nInjects completion checklist into every AI response context.\n\n**Purpose:** Prevents \"implementation complete\" claims without proper verification. The checklist is always visible to the AI, ensuring consistent enforcement of completion criteria.\n\n---\n\n### Workflow\n\n```\n/reviw:do \n ā\nCreate worktree + Plan + TodoWrite\n ā\nImplementation (via subagents)\n ā\nBuild & Verify (webapp-testing)\n ā\n/reviw:done\n ā\nāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā\nā 7 Review Agents (parallel execution) ā\nā ā\nā review-code-quality āāā ā\nā review-security āāāāāāā¤ ā\nā review-a11y-ux āāāāāāāā¼āāā REPORT.md ā\nā review-figma-fidelity ā¤ (append) ā\nā review-copy-consistency ā\nā review-e2e-integrity āā¤ ā\nā e2e-health-reviewer āāā ā\nāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā\n ā\nreport-builder (organize + score)\n ā\nCollect evidence (artifact-proof)\n ā\nnpx reviw opens report (foreground)\n ā\nUser comments ā Submit & Exit\n ā\nRegister feedback to Todo\n ā\nFix ā Re-review until approved\n ā\nCommit & PR (only after approval)\n```\n\n### Completion Criteria\n\n| Stage | Content | Status |\n|-------|---------|--------|\n| 1/3 | Implementation complete | Do not report yet |\n| 2/3 | Build, start, verification complete | Do not report yet |\n| 3/3 | Review with reviw ā User approval | Now complete |\n\n### Design Philosophy\n\nThe plugin enforces **human-in-the-loop** development:\n\n1. **No shortcuts:** Mocks, bypasses, and skipped verifications are prohibited\n2. **Evidence required:** Every completion claim must have screenshots/videos\n3. **User approval:** Only the user can mark a task as complete\n4. **Context preservation:** Heavy operations run in subagents to prevent context exhaustion\n\n### `.artifacts` Directory Policy\n\nThe `.artifacts/` directory stores screenshots, videos, and reports generated during development. **By default, this directory should be added to `.gitignore`** to prevent repository bloat from large media files.\n\n```bash\n# Add to .gitignore (recommended)\necho \".artifacts\" >> .gitignore\n```\n\n**Why ignore by default:**\n- Screenshots and videos can be large (especially screen recordings)\n- Evidence is primarily for the review process, not permanent documentation\n- Keeps repository size manageable\n\n**If you need to commit specific evidence:**\n\nUse `git add --force` to explicitly add files you want to preserve:\n\n```bash\n# Force add specific evidence files\ngit add --force .artifacts/feature/images/final-screenshot.png\ngit add --force .artifacts/feature/REPORT.md\n\n# Or force add an entire feature's evidence\ngit add --force .artifacts/feature/\n```\n\n**For video files**, use Git LFS to avoid bloating the repository:\n\n```bash\ngit lfs track \"*.mp4\" \"*.webm\" \"*.mov\"\ngit add .gitattributes\ngit add --force .artifacts/feature/videos/demo.mp4\n```\n\nThis approach gives you full control: ignore by default, commit only what matters.\n\n## Development\n\nreviw is written entirely in [MoonBit](https://www.moonbitlang.com/) and compiled to JavaScript.\n\n```bash\n# Build\ncd v2 && moon build --target js --release\n\n# Run tests\ncd v2 && moon test --target js\n\n# Package for npm (builds MoonBit + copies to dist/)\nnpm run prepack\n```\n\n- Source: `v2/src/` (MoonBit)\n- Build output: `dist/server/server.js`, `dist/ui/ui.js`\n- Plugin: `plugin/` directory\n\n## License\n\nMIT\n","readmeFilename":"README.md"}
![\"reviw](\"https://raw.githubusercontent.com/kazuph/reviw/main/assets/logo.svg\"){kind=logo}
\n![\"npm](\"https://img.shields.io/npm/v/reviw.svg\")
\n ![\"license\"](\"https://img.shields.io/npm/l/reviw.svg\")
\n ę„ę¬čŖ\n