convez.ai
AgenteAutomaçãoIntermediário
kazuph

Yunomi — Interface de Revisão Human-in-the-Loop para Workflows de IA

kazuph/yunomi

Porta de aprovação human-in-the-loop para workflows de IA, sem config

Ver no GitHub
BomPluginScore · de 0 a 100

Ferramenta de aprovação interativa que permite que agentes de IA apresentem relatórios estruturados (Markdown, CSV, diffs) para revisão humana via navegador. O fluxo é simples: agente executa `npx yunomi`, abre interface web para o humano revisar, comentar e aprovar, retornando o veredito como YAML estruturado. Construída inteiramente em MoonBit, sem dependências globais.

Instalação

$npx convez-ai kazuph/yunomi

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
21
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 2 semanas
Versão
v2.6.2
Issues abertas
1
Contribuidores
2

Casos de uso

  • Agentes de IA apresentarem mudanças de código para revisão humana
  • Revisar relatórios gerados, diffs e dados tabulares com anotações
  • Criar loops de feedback estruturado entre IA e humano em pipelines de automação

Veredito

Yunomi resolve um problema real: como agentes de IA entregam trabalho para aprovação humana de forma digna e estruturada. Design minimalista (zero config, apenas `npx yunomi`) e suporte robusto a formatos (Markdown, CSV, diffs) fazem desta uma ferramenta pragmática para quem constrói workflows colaborativos AI+humano.

README

A tradução para o português deste README ainda está na fila.


Installation: none. Just tell your AI — "run npx yunomi" — and it will know what to do.

A yunomi(湯のみ)is the everyday Japanese teacup: no handle, no saucer, warm in both hands. Tea served in one always arrives the same way — set down gently in front of you, with a slight bow and a single word: douzo — "here you go."

The story

yunomi was not built so humans can demand "show me what you did." It is the opposite gesture.

When an AI agent finishes a piece of work, it shouldn't just say "done." It should brew a report — what changed, why, the evidence, the test results — pour it into a cup, and set it down in front of you:

npx yunomi REPORT.md

Douzo. 🍵

Your browser opens. You read at your own pace. You leave comments; you approve — or you hand the cup back. The agent waits the way good service waits: quietly, until you decide. When you submit, yunomi exits and hands your verdict back to the agent as structured YAML, and the loop continues until you say it's good.

In the vibe coding era, humans no longer read every diff. We review the work itself: intent, changes, and proof. yunomi is the moment of handoff between AI work and human judgment — served politely, every single time.

Getting started (the only step)

Tell your AI agent:

"From now on, run npx yunomi when you finish your work."

That's it. When the agent runs npx yunomi with no arguments, yunomi prints a skill document that teaches the agent everything: how to write a good report, how to serve it, how to read your verdict, and how to loop until you approve. The agent will then offer to install yunomi as a permanent skill — answer yes once, and you never have to mention it again.

No global install. No plugin setup. No config. The tea serves itself.


yunomi (formerly reviw) is a lightweight browser-based tool for reviewing and annotating Markdown reports, tabular data, text, and diff files. Built entirely in MoonBit (zero hand-written JavaScript). Supports CSV, TSV, plain text, Markdown, and unified diff formats. Comments are output as YAML to stdout.

Features

File Format Support

  • CSV/TSV: View tabular data with sticky headers, column freezing, filtering, and column resizing
  • Markdown: Side-by-side preview with synchronized scrolling, click-to-comment from preview
  • Diff/Patch: GitHub-style diff view with syntax highlighting, collapsible large files (500+ lines), and binary files sorted to end
  • Text: Line-by-line commenting for plain text files

Mermaid.js Diagrams

  • Auto-detect and render Mermaid diagrams in Markdown files
  • Click any diagram to open fullscreen viewer with minimap
  • Zoom with mouse wheel (centered on cursor position, up to 10x)
  • Pan with mouse drag
  • Trackpad pinch-to-zoom and touch gesture support
  • Shift+scroll zoom for Windows users
  • Dark mode support for thumbnails
  • Highlights corresponding source line after closing fullscreen
  • Syntax error display in toast notifications

Media Sidebar

  • Thumbnail gallery of all images and videos in the left sidebar
  • Click any thumbnail to scroll to the corresponding media and highlight it
  • ArrowUp/ArrowDown to jump between media, Escape to clear the selection
  • Numbered badges for quick identification

Media Embed Discipline (AI-friendly)

  • yunomi file.md refuses to start (exit 1) when media files are written as [text](path) links instead of ![alt](path) embeds
  • The error lists every violation with line numbers and ready-to-apply fixes, so AI agents can self-correct and retry

Media Fullscreen

  • Click images in Markdown preview to open fullscreen viewer
  • Click videos to open fullscreen playback with YouTube-like keyboard shortcuts (Space/K, J/L, arrow keys, 0-9)
  • Click anywhere (including the image/video itself) to close the fullscreen overlay
  • Clicking media automatically highlights the corresponding source line in the Markdown panel
  • Video timeline settings with adjustable scene detection sensitivity

UI Features

  • Theme toggle: Switch between light and dark modes
  • Preview-only mode: Hide source panel for wide preview reading
  • Heading toggle: Collapse/expand sections by clicking heading arrows
  • Multi-file support: Open multiple files simultaneously on separate ports
  • Drag selection: Select rectangular regions or multiple rows for batch comments
  • Real-time updates: Hot reload on file changes via SSE
  • Comment persistence: Auto-save comments to localStorage with recovery modal
  • Image attachment: Attach images to comments and submit dialog (paste with Cmd/Ctrl+V)
  • Selected-lines copy: Copy button in comment dialog to copy selected line text
  • Keyboard shortcuts: Cmd/Ctrl+Enter to open submit modal
  • Multi-tab sync: Submit from any tab closes all tabs for the same file
  • Server detection: Reuse existing server instead of starting a new one (via lock files)
  • Tab activation (macOS): Automatically activates existing browser tab via AppleScript
  • Review history: File-based persistent review history
  • details/summary support: HTML details/summary tags rendered as collapsible sections

Output

  • YAML format with file, mode, row, col, value, and comment text
  • Overall summary field for review notes
  • Image attachments included as base64 data

Installation

You usually don't need one — see Getting started. If you prefer a global command:

npm install -g yunomi

Or run directly with npx:

npx yunomi <file>

Usage

# No arguments: print the skill document for AI agents
yunomi

# Single file
yunomi <file> [--port 4989] [--encoding utf8|shift_jis|...]

# Multiple files (each opens on consecutive ports)
yunomi file1.csv file2.md file3.tsv --port 4989

# Diff from stdin
git diff HEAD | yunomi

# Diff file
yunomi changes.diff

Options

  • --port <number>: Specify starting port (default: 4989)
  • --encoding <encoding>: Force specific encoding (auto-detected by default)
  • --no-open: Prevent automatic browser opening
  • --skill: Print the skill document for AI agents
  • --help, -h: Show help message
  • --version, -v: Show version number

Workflow

  1. Browser opens automatically (macOS: open / Linux: xdg-open / Windows: start)
  2. Click cells/lines to add comments, or drag to select multiple
  3. Use Cmd/Ctrl+Enter or click "Submit & Exit" to output comments
  4. Comments are printed as YAML to stdout

Screenshots

Markdown View with Media Sidebar

Markdown View with Media Sidebar

Preview-only Mode

Preview-only Mode

Heading Toggle

Heading Toggle

Comment Dialog with Image Attachment

Comment Dialog

Video Fullscreen with Timeline Thumbnails

Video Fullscreen

Mermaid Fullscreen with Minimap

Mermaid Fullscreen

Submit Review Dialog with Image Attachment

Submit Review Dialog

CSV View

CSV View

Diff View

Diff View

Output Example

file: data.csv
mode: csv
reason: button
at: '2025-11-26T12:00:00.000Z'
comments:
  - row: 2
    col: 3
    text: This value needs review
    value: '150'
summary: Overall the data looks good, minor issues noted above.

Claude Code Plugin

This repository also serves as a Claude Code plugin marketplace. The plugin integrates yunomi into Claude Code workflows with task management and review automation.

Note: the plugin was renamed from reviw-plugin to yunomi-plugin in v2.0.0. If you installed the old plugin, remove it and install yunomi-plugin@yunomi-plugins.

Installation

# In Claude Code
/plugin marketplace add kazuph/yunomi
/plugin install yunomi-plugin@yunomi-plugins

Install Skills with npx skills

Use 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.

# Preview what will be installed
npx skills add https://github.com/kazuph/yunomi --list

# Install all yunomi skills globally for Codex
npx skills add https://github.com/kazuph/yunomi -g -a codex -s '*' --copy -y

# Install all yunomi skills globally for Codex and OpenCode
npx skills add https://github.com/kazuph/yunomi -g -a codex -a opencode -s '*' --copy -y

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.

Claude Code plugin commands and hooks are installed through the Claude Code plugin flow above, not through npx skills.

Plugin Directory Structure

plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata (name, version, description)
├── agents/
│   ├── report-builder.md     # Report generation agent
│   ├── e2e-health-reviewer.md    # E2E test health check
│   ├── review-code-quality.md    # Code quality review
│   ├── review-security.md        # Security audit
│   ├── review-a11y-ux.md         # Accessibility & UX
│   ├── review-figma-fidelity.md  # Design fidelity
│   ├── review-copy-consistency.md # Text consistency
│   └── review-e2e-integrity.md   # E2E test integrity
├── skills/
│   ├── ask/
│   │   └── SKILL.md          # Requirements elicitation skill
│   ├── bucho/
│   │   └── SKILL.md          # Manager orchestration skill
│   ├── do/
│   │   └── SKILL.md          # Task start skill
│   ├── done/
│   │   └── SKILL.md          # Task completion skill
│   ├── exit-notifier/
│   │   ├── SKILL.md          # Background task exit notification skill
│   │   └── scripts/
│   │       └── watch-exit-notify.sh
│   ├── tiny-do/
│   │   └── SKILL.md          # Lightweight task start skill
│   ├── tiny-done/
│   │   └── SKILL.md          # Lightweight task completion skill
│   ├── validate-report/
│   │   └── SKILL.md          # Internal REPORT.md validation helper
│   ├── artifact-proof/
│   │   └── SKILL.md          # Evidence collection skill
│   └── webapp-testing/
│       ├── SKILL.md          # Web testing skill
│       ├── scripts/          # Helper scripts
│       └── examples/         # Usage examples
├── hooks/
│   └── hooks.json            # Hook definitions
├── hooks-handlers/
│   └── completion-checklist.sh  # UserPromptSubmit handler
└── README.md

Components Overview

TypeNameDescription
Task Skill/yunomi:doStart a task - create worktree with git wt, plan, register todos
Task Skill/yunomi:doneComplete checklist - run 7 review agents, collect evidence, start review
Task Skill/yunomi:tiny-doStart a smaller task with the lightweight workflow
Task Skill/yunomi:tiny-doneFinish a smaller task with lightweight review
Task Skill/yunomi:buchoOrchestrate Claude Code and Codex in manager mode
Agentreport-builderPrepare reports and evidence for user review
Agentreview-code-qualityCode quality: readability, DRY, type safety, error handling
Agentreview-securitySecurity: XSS, injection, OWASP Top 10, secrets detection
Agentreview-a11y-uxAccessibility: WCAG 2.2 AA, keyboard nav, UX flow
Agentreview-figma-fidelityDesign: token compliance, visual consistency
Agentreview-copy-consistencyCopy: text consistency, tone & manner, i18n
Agentreview-e2e-integrityE2E: user flow reproduction, mock contamination
Agente2e-health-reviewerE2E: goto restrictions, record assertions, hardcoding
Skillartifact-proofCollect evidence (screenshots, videos, logs)
Skillexit-notifierNotify the current tmux / Herdr pane when background tasks exit, including captured stdout/stderr
Skillwebapp-testingBrowser automation and verification with Playwright
HookPreToolUseRemind to review before git commit/push
HookUserPromptSubmitInject completion checklist into AI context

Task Skills

Bundled task skills

SkillPurpose
askClarify requirements, scope, constraints, and success criteria before implementation
buchoOrchestrate Claude Code and Codex as a managed team through tmux
check-yourselfForce real verification instead of assumptions or lightweight spot checks
commit-and-pushGenerate a commit message, create the commit, push it, and confirm a clean git state
doStart the full task workflow with worktree setup, planning, and review preparation
doneRun the full completion workflow with evidence collection and yunomi-based review
exit-notifierReport background task completion and captured stdout/stderr back into the current tmux / Herdr pane
openOpen files, artifacts, and URLs with macOS open
tiny-doStart a smaller task with the lightweight workflow
tiny-doneFinish a smaller task with the lightweight completion flow
validate-reportInternal helper used by done to validate REPORT.md against artifact-proof reporting rules

/yunomi:do <task description>

Starts a new task with proper environment setup.

What it does:

  1. Creates a git worktree using git wt for isolated development (feature/<name>, fix/<name>, etc.)
  2. Sets up .artifacts/<feature>/ directory for evidence
  3. Creates REPORT.md with plan and TODO checklist
  4. Registers todos in TodoWrite for progress tracking

Directory structure created:

<worktree>/                   # e.g., .worktree/feature-auth/
└── .artifacts/
    └── <feature>/            # e.g., auth (from feature/auth)
        ├── REPORT.md         # Plan, progress, evidence links
        ├── images/           # Screenshots
        └── videos/           # Video recordings

Task resumption: When a session starts or after context compaction, the skill checks for existing worktrees (via git wt) and resumes from REPORT.md.

/yunomi:done

Validates completion criteria before allowing task completion.

Checklist enforced:

  • Build succeeded (no type/lint errors)
  • Development server started and working
  • Verified with webapp-testing skill
  • Evidence collected in .artifacts/<feature>/
  • Report created with artifact-proof skill
  • Reviewed with yunomi (foreground mode)
  • User approval received

Prohibited:

  • Saying "implementation complete" without verification
  • Committing/pushing before yunomi review
  • Reports without evidence

Agents

Review Agents (7 agents run in parallel)

When /yunomi:done is executed, 7 review agents run simultaneously and append their findings to REPORT.md:

AgentFocusOutput Section
review-code-qualityReadability, DRY, type safety, error handlingCode Quality Review
review-securityXSS, injection, OWASP Top 10, secretsSecurity Review
review-a11y-uxWCAG 2.2 AA, keyboard nav, focus managementA11y & UX Review
review-figma-fidelityDesign tokens, visual consistencyFigma Fidelity Review
review-copy-consistencyText consistency, i18n, tone & mannerCopy Consistency Review
review-e2e-integrityUser flow reproduction, mock contaminationE2E Integrity Review
e2e-health-reviewergoto restrictions, record assertionsE2E Health Review

Total score: Each agent scores X/5, combined for X/35 total.

Invocation (parallel):

Task tool with 7 parallel calls:
  subagent_type: "review-code-quality"
  subagent_type: "review-security"
  subagent_type: "review-a11y-ux"
  subagent_type: "review-figma-fidelity"
  subagent_type: "review-copy-consistency"
  subagent_type: "review-e2e-integrity"
  subagent_type: "e2e-health-reviewer"

report-builder

Specialized agent for preparing review materials (runs after review agents).

Role:

  • Organize implementation into a structured report
  • Calculate total review score (X/35)
  • Collect and arrange evidence (screenshots, videos)
  • Prepare REPORT.md for yunomi review
  • Parse yunomi feedback and register as todos

Invocation:

Task tool with subagent_type: "report-builder"

Skills auto-loaded: artifact-proof


Skills

artifact-proof

Manages evidence collection for visual regression and PR documentation.

Features:

  • Screenshots and videos under .artifacts/<feature>/
  • Playwright integration for automated capture
  • Git LFS setup for video files
  • PR image URLs with commit hashes (persist after branch deletion)

yunomi integration:

# Open report in yunomi (foreground required)
npx yunomi .artifacts/<feature>/REPORT.md

# With video preview
open .artifacts/<feature>/videos/demo.webm
npx yunomi .artifacts/<feature>/REPORT.md

webapp-testing

Browser automation toolkit using Playwright.

Features:

  • TypeScript Playwright Test (@playwright/test)
  • Playwright configuration with webServer support
  • Screenshot and video capture
  • Console log and network request monitoring
  • CDP integration for advanced debugging

Quick verification:

node -e "const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('http://localhost:3000', { waitUntil: 'networkidle' });
  await page.screenshot({ path: '/tmp/webapp.png', fullPage: true });
  await browser.close();
})();"

Hooks

PreToolUse (Bash matcher)

Triggers when git commit or git push is detected.

Message: Reminds to run /yunomi:done and review with yunomi before committing.

UserPromptSubmit

Injects completion checklist into every AI response context.

Purpose: Prevents "implementation complete" claims without proper verification. The checklist is always visible to the AI, ensuring consistent enforcement of completion criteria.


Workflow

/yunomi:do <task description>
    ↓
Create worktree + Plan + TodoWrite
    ↓
Implementation (via subagents)
    ↓
Build & Verify (webapp-testing)
    ↓
/yunomi:done
    ↓
┌─────────────────────────────────────────────┐
│  7 Review Agents (parallel execution)       │
│                                             │
│  review-code-quality ──┐                    │
│  review-security ──────┤                    │
│  review-a11y-ux ───────┼──→ REPORT.md      │
│  review-figma-fidelity ┤    (append)        │
│  review-copy-consistency                    │
│  review-e2e-integrity ─┤                    │
│  e2e-health-reviewer ──┘                    │
└─────────────────────────────────────────────┘
    ↓
report-builder (organize + score)
    ↓
Collect evidence (artifact-proof)
    ↓
npx yunomi opens report (foreground)
    ↓
User comments → Submit & Exit
    ↓
Register feedback to Todo
    ↓
Fix → Re-review until approved
    ↓
Commit & PR (only after approval)

Completion Criteria

StageContentStatus
1/3Implementation completeDo not report yet
2/3Build, start, verification completeDo not report yet
3/3Review with yunomi → User approvalNow complete

Design Philosophy

The plugin enforces human-in-the-loop development:

  1. No shortcuts: Mocks, bypasses, and skipped verifications are prohibited
  2. Evidence required: Every completion claim must have screenshots/videos
  3. User approval: Only the user can mark a task as complete
  4. Context preservation: Heavy operations run in subagents to prevent context exhaustion

.artifacts Directory Policy

The .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.

# Add to .gitignore (recommended)
echo ".artifacts" >> .gitignore

Why ignore by default:

  • Screenshots and videos can be large (especially screen recordings)
  • Evidence is primarily for the review process, not permanent documentation
  • Keeps repository size manageable

If you need to commit specific evidence:

Use git add --force to explicitly add files you want to preserve:

# Force add specific evidence files
git add --force .artifacts/feature/images/final-screenshot.png
git add --force .artifacts/feature/REPORT.md

# Or force add an entire feature's evidence
git add --force .artifacts/feature/

For video files, use Git LFS to avoid bloating the repository:

git lfs track "*.mp4" "*.webm" "*.mov"
git add .gitattributes
git add --force .artifacts/feature/videos/demo.mp4

This approach gives you full control: ignore by default, commit only what matters.

Development

yunomi is written entirely in MoonBit and compiled to JavaScript.

# Build
cd v2 && moon build --target js --release

# Run tests
cd v2 && moon test --target js

# Package for npm (builds MoonBit + copies to dist/)
npm run prepack
  • Source: v2/src/ (MoonBit)
  • Build output: dist/server/server.js, dist/ui/ui.js
  • Plugin: plugin/ directory

License

MIT

Ver o original no GitHub

Bom para

Relacionados