이 mod 소개

Claude Code 2.1.289에서 테스트했습니다(0.1.2 이전에는 2.1.288). Markdown 레이아웃, Ghostty 이미지 픽셀(로컬, herdr 0.9.3 내부, Air에서 SSH로 연결한 경우), 연속 동영상 프레임, 재생 제어, 전송 전 붙여넣기 미리보기 바, 답변의 이미지 경로를 눌러 미리보기를 여는 동작을 실제로 확인했습니다. mosh는 텍스트 화면만 동기화하므로 이미지 픽셀을 표시하지 못합니다. Air에서 원격으로 클립보드를 전달하는 동작과 다른 Claude Code 버전은 검증하지 않았습니다. 자세한 내용은 호환성과 검증 기록을 참고하세요.

실행 요구 사항과 시험 사용

Mods를 사용할 수 있는 Claude Code, 대화형 터미널, 그리고 Claude를 실행하는 호스트에 설치된 Node.js 20+, ffmpeg, ffprobe가 필요합니다. Node는 Claude 프로세스의 PATH에 있어야 하며, 미디어 도구는 /opt/homebrew/bin, /usr/local/bin, /usr/bin에서 찾습니다. 테스트 환경은 Node 26.8.1, ffmpeg／ffprobe 9.0.2였고 모든 Node／codec 버전을 검증한 것은 아닙니다.

Yarn, node_modules, MCP server, 브라우저, HTTP port는 필요하지 않습니다. 먼저 권한과 데이터 경계를 읽은 다음, 확보해서 신뢰할 수 있는 프로젝트 디렉터리에서 불러오세요.

GitHub에서 설치(권장)

코드는 andrew54068/claude-plugins의 tui-preview-mod/에 공개되어 있으며 기존 andrew54068 marketplace를 사용하므로 private repo 접근 권한이 필요하지 않습니다. 설치와 Node／ffmpeg／ffprobe 준비는 Claude를 실행하는 호스트에서 해야 합니다. Air가 SSH로 Pro의 Claude를 사용할 때 이 도구가 필요한 곳은 Pro입니다. 공식 marketplace 설명

Claude에서 다음 순서로 실행합니다.

/plugin marketplace add andrew54068/claude-plugins
/plugin install tui-preview-mod@andrew54068
/reload-plugins
/preview README.md

andrew54068이 이미 등록되어 있다면 소스를 다시 추가하지 마세요. 먼저 shell에서 claude plugin marketplace update andrew54068을 실행한 뒤 설치하면 됩니다.

이전에 tui-preview-mod@preview-mods를 설치했다면 /plugin의 Installed → 이전 plugin → Configure에서 저장된 roots와 autoPreview를 먼저 적어 두세요. 그런 다음 같은 이름의 Mod가 동시에 로드되지 않도록 이전 plugin을 제거합니다. 제거하면 이전 plugin이 저장한 options는 삭제되지만 다른 plugin이나 marketplace에는 영향을 주지 않습니다.

/plugin uninstall tui-preview-mod@preview-mods

그 다음 tui-preview-mod@andrew54068을 설치하고 Configure에서 기록한 설정을 다시 적용하세요. 특히 autoPreview를 false로 해 두었다면 반드시 복원해야 하며, 그렇지 않으면 기본값 true로 돌아갑니다. andrew54068은 marketplace 이름이고 tui-preview-mod은 plugin 이름이며, 이 버전은 0.1.3입니다. 이전 preview-mods 소스는 남겨도 됩니다. 소스를 바꾸는 것은 Mod 스위치를 우회하는 방법이 아닙니다.

GitHub 설치는 외부 플러그인을 가져오는 방법만 바꾸며 /preview가 반드시 동작한다고 보장하지 않습니다. 명령이 여전히 없으면 /plugin에서 mods active를 확인하고 shell에서 claude plugin test를 실행해 로드 제한을 살펴보세요. 조직 정책이나 Anthropic의 Mod 스위치가 계속 거부할 수 있습니다. 공식 진단

설치하지 않고 로컬 개발 시험하기

claude --version
node --version
ffmpeg -version
ffprobe -version
claude plugin validate --strict /absolute/path/to/claude-plugins/tui-preview-mod/.claude-plugin/plugin.json
claude plugin validate /absolute/path/to/claude-plugins/.claude-plugin/marketplace.json
claude --plugin-dir /absolute/path/to/claude-plugins/tui-preview-mod

이 방식은 해당 Claude session에만 적용되고 전역으로 설치하지 않습니다. 들어간 뒤 /plugin으로 tui-preview-mod이 로드되었는지 확인하세요. 조직 정책이나 rollout 상태 때문에 Mods가 계속 차단될 수 있습니다. 거부 메시지를 성공으로 간주하거나 정책을 우회하지 마세요. 공식 Mods 설명

plugin manifest는 tui-preview-mod/.claude-plugin/에 있고 marketplace manifest는 repository 루트의 .claude-plugin/에 있습니다. 파일을 따로 지정하세요. repository 디렉터리만 검증하면 marketplace를 선택하게 되어 Mod의 hooks／calls를 놓칩니다. 기존 marketplace에는 metadata warnings가 있으므로 새 plugin의 strict validation과 혼동하지 마세요.

사용법

| 명령 | 동작 | | --- | --- | | /preview notes.md | 네이티브 Markdown 페이지로 표시 | | /preview images/photo with spaces.jpg | 이미지를 표시하며 경로의 공백은 유지 | | /preview "videos/demo clip.mp4" | 소리 없이 실제 연속 프레임으로 동영상을 재생 | | 답변 속 content/a.png를 한 번 클릭 | 같은 preview pane을 열며, 아래 설명처럼 전체 화면 인터페이스가 필요 | | /preview pasted | 현재 session에서 최근 완료된 붙여넣기 이미지 미리보기를 열기 | | /preview close | pane을 닫고 디코더 프로세스를 중지 | | /preview on, /preview off | 이번 로드에서 자동 붙여넣기／Read 이미지 미리보기를 전환 | | /preview | 사용법을 표시 |

경로는 기본적으로 현재 session.root() 안으로 제한됩니다. 추가 디렉터리는 /plugin의 tui-preview-mod 설정에 절대 경로로 명시해야 하며 최대 32개를 사용합니다. autoPreview는 다시 로드할 때의 기본값을 제어하고 on/off는 이 설정을 저장하지 않습니다. off여도 명시적인 경로 미리보기는 막지 않습니다.

동영상은 p로 재생／일시정지, h로 5초 앞으로 이동, l로 5초 뒤로 이동, r로 다시 재생, x 또는 Esc로 닫습니다. Markdown은 h/l이나 버튼으로 페이지를 넘깁니다. 먼저 pane에 키보드 포커스를 주고, 네이티브 Ctrl-X Tab으로 포커스를 바꾸세요.

답변 속 경로 클릭하기

전체 화면 인터페이스(CLAUDE_CODE_NO_FLICKER=1 또는 /tui fullscreen)에서는 Claude 답변의 이미지·동영상 경로가 링크로 그려지고 한 번 클릭하면 preview pane이 열립니다. 상대 경로는 session.root()를 기준으로 하고, 절대 경로는 허용된 roots 안에 있어야 합니다.

• Cmd+click은 터미널이 처리합니다: Ghostty가 macOS로 파일을 열기 때문에 Mod는 이 클릭을 받지 못합니다. 한 번 클릭하세요. Ctrl／Alt+click은 Claude Code의 원래 열기 방식 그대로입니다.
• 미디어 경로가 언급된 답변만 다시 그리며 나머지는 네이티브 방식으로 그립니다. 저장된 메시지나 모델 입력은 바꾸지 않습니다. 다시 그린 뒤 선택할 수 없는 링크(vscode://, mailto:, Email 등)가 답변에 있으면 전체 답변을 네이티브로 그립니다.
• 클릭하기 전에는 파일을 읽지 않습니다. 클릭 후에는 /preview <path>와 같은 디렉터리·크기·형식 검사를 수행합니다.
• Claude Code가 선택 가능한 링크를 그릴 수 있는 터미널에서만 답변을 다시 그립니다. Ghostty, iTerm2, WezTerm, kitty, Alacritty, Warp, VS Code 1.72+, tmux 3.4+ 등이 해당하며 2.1.289와 같은 방식으로 판단합니다. Terminal.app과 herdr(TERM_PROGRAM=herdr)는 대상이 아니므로 네이티브로 그립니다. herdr에서 FORCE_HYPERLINK=1을 설정하면 경로를 선택할 수 있습니다. 자세한 내용은 사용자 지정 API와 herdr를 보세요.
• 답변을 다시 그리지 않으려면 /plugin 설정에서 clickablePaths를 false로 지정하세요.

네이티브 붙여넣기 이미지가 현재 composer에 들어오면 미리보기 바가 약 500ms마다 갱신됩니다. 썸네일은 최대 2개이고 나머지는 이미지 버튼으로 명시적으로 로드해야 합니다. Read inline과 composer는 자동 디코딩 슬롯 2개를 공유하며, 전면 pane은 별도의 명시적 작업입니다. Mod는 입력이나 prompt를 바꾸지 않고 prompt를 제출하지도 않으며 Read가 모델에 보내는 내용도 바꾸지 않습니다. 붙여넣기가 끝나지 않았거나 읽기에 실패했거나 자동 미리보기가 꺼져 있으면 /preview pasted에 사용할 스냅샷이 없을 수 있습니다. 이미지 버튼으로 다시 시도할 수 있습니다. 구현

형식과 제한

| 항목 | 제한／동작 | | --- | --- | | Markdown: .md, .markdown | UTF-8, 2 MiB; 페이지당 최대 9000 문자 단위, 터미널 제어 문자는 제거 | | 이미지: PNG, JPEG, WebP, GIF | 원본 32 MiB; GIF는 첫 프레임만 사용 | | 동영상: MP4, MOV, WebM, MKV | 원본 2 GiB; 디코딩 가능 여부는 설치된 ffmpeg에 좌우 | | 모든 이미지／동영상 출력 | PNG, 최대 640×360, 프레임당 최대 2 MiB | | 동영상 재생 | 8 fps, 무음; 원본 앞 600초만 미리 보고 탐색도 이 범위로 제한 |

URL, 장치, FIFO, 범위를 벗어난 파일, 파일 symlink는 지원하지 않습니다. PNG bytes는 네이티브 Image／ui.blit에 전달하고, 터미널이 픽셀을 그리지 못하면 네이티브 대체 텍스트를 표시할 수 있습니다. 독립 플레이어가 아니며 원격 Claude가 없는 SSH 파일 브라우저도 제공하지 않습니다. helper

사용자 지정 API와 herdr

settings에서 사용자 지정 ANTHROPIC_BASE_URL／ANTHROPIC_AUTH_TOKEN을 사용하거나 herdr 안에서 Claude를 실행할 때 다음 명령으로 시작합니다.

claude --settings '{"env":{"DISABLE_TELEMETRY":"1","CLAUDE_CODE_FORCE_TERMINAL_IMAGES":"1","FORCE_HYPERLINK":"1"}}'

| 설정 | 이유 | 비용 | | --- | --- | --- | | DISABLE_TELEMETRY=1 | 사용자 지정 API를 쓰면 Claude Code는 이 프로세스의 Mods 스위치를 flag service에서 가져오지 않고 다른 프로세스가 ~/.claude.json에 쓴 이전 값을 사용합니다. 이전 값이 꺼져 있으면 /preview가 나타나지 않습니다 | 해당 session의 실험 기능은 내장 기본값으로 바뀌고(예: Artifact 도구를 활성화하지 않음) 텔레메트리도 보내지 않습니다 | | CLAUDE_CODE_FORCE_TERMINAL_IMAGES=1 | herdr가 보고하는 터미널 이름은 libghostty라 Claude Code가 인식하지 못해 이미지를 끕니다 | 터미널이 Kitty 이미지를 지원하지 않으면 빈 화면이 그려집니다 | | FORCE_HYPERLINK=1 | 답변의 경로를 클릭 가능한 링크로 만듭니다 | 모든 링크가 터미널 하이퍼링크 출력으로 바뀝니다 |

herdr는 0.9.3 이상이 필요합니다. kitty_graphics = true로 설정해도 0.8.x에서는 직접 전송한 Kitty 이미지가 빈 화면입니다. Ghostty에서 직접 실행할 때는 사용자 지정 API인 경우에만 첫 번째 설정이 필요합니다.

매번 --settings를 붙이고 싶지 않다면 첫 번째 설정을 ~/.claude/settings.json의 env에 넣고 나머지 두 개만 herdr 안에서 export하세요(herdr의 pane에는 HERDR_ENV가 있습니다).

if [[ -n $HERDR_ENV ]]; then
  export CLAUDE_CODE_FORCE_TERMINAL_IMAGES=1 FORCE_HYPERLINK=1
fi

cc-switch처럼 settings.json을 다시 쓰는 도구를 사용할 때는 도구가 저장하는 설정에도 env와 enabledPlugins를 넣어야 합니다. 그렇지 않으면 provider를 바꿀 때 사라집니다.

SSH

파일이 있는 원격 호스트에서 Claude Code + 이 Mod + Node／ffmpeg／ffprobe를 실행하고 client 터미널에서 확인합니다. 기존의 신뢰할 수 있는 SSH 연결을 사용하면 되며 Mod용 port를 열 필요는 없습니다.

ssh your-trusted-host
claude --plugin-dir /absolute/path/on/remote/claude-plugins/tui-preview-mod

Air에서 SSH로 Pro의 herdr에 연결해 위 명령으로 시작하면 Air의 Ghostty에서 이미지 픽셀이 표시됩니다. SSH를 사용해도 client 클립보드가 자동으로 server 클립보드가 되지는 않습니다. 이미지가 실제로 원격 Claude composer에 들어가야 미리 볼 수 있는 첨부가 됩니다.

mosh는 텍스트 화면만 동기화하고 Kitty 이미지 프로토콜을 전달하지 않으므로 mosh로는 픽셀이 보이지 않습니다. pane, 키, 클릭은 계속 사용할 수 있습니다. Air에서 픽셀을 봐야 하면 SSH를 사용하세요.

업데이트와 제거

shell에서 GitHub catalog와 plugin을 업데이트한 뒤 Claude를 다시 시작해 반영합니다.

claude plugin marketplace update andrew54068
claude plugin update tui-preview-mod@andrew54068

대화형 /plugin에는 update 하위 명령이 없습니다. Installed 페이지의 Update now로 업데이트할 수도 있지만 /plugin update는 사용하지 마세요.

marketplace는 유지하고 plugin만 제거합니다: /plugin uninstall tui-preview-mod@andrew54068. 이 Mod를 지우려고 andrew54068 marketplace 전체를 삭제하지 마세요. 다른 plugin에도 영향을 줍니다. shell에서 같은 작업을 하려면 앞의 /를 빼고 plugin 앞에 claude를 붙입니다. 기본이 아닌 scope로 설치했다면 제거할 때도 같은 --scope를 지정하세요.

--plugin-dir로만 시험한 경우 다음에는 해당 인자를 빼면 됩니다. 공식 marketplace 설명

개발과 문서

개발에는 Yarn Classic을 사용합니다. yarn run check는 Node/helper core만 검증합니다. 네이티브 Mod에는 claude plugin test .와 runtime에서 타입을 생성한 뒤의 Mod typecheck도 필요합니다. 전체 명령은 CONTRIBUTING을 확인하세요.

• 번체 중국어 연구 보고서: Mod를 선택한 이유와 SSH·권한 절충안.
• SECURITY: 일반 Mods 권한, 이 프로젝트의 footprint, 디코딩 제한.
• 장치 안전 검사: 릴리스 전 읽기 전용 검사 6개와 남은 위험 2개.
• 호환성, 검증 기록: 실제 테스트, 자동 테스트, 미검증 영역의 경계.

MIT License입니다. LICENSE를 참고하세요.