terminal-browser: 라이브 웹 페이지를 보여 주는 Claude Code 브라우저 창
/browser로 Claude Code 안의 창에 실제 웹 브라우저를 엽니다. kitty 그래픽 프로토콜로 화면을 그립니다.
권한
- 파일 읽기컴퓨터의 파일을 읽고 디렉터리 목록을 볼 수 있습니다($.fs.read / list / stat / exists).
- 명령어 실행컴퓨터에서 셸 프로그램을 실행할 수 있습니다($.process.run / spawn). 정확히 어떤 프로그램인지는 소스를 확인하세요.
- 네트워크HTTP 요청을 보내거나 MCP 서버와 통신할 수 있습니다($.http.fetch / $.mcp.*).
- 도구 호출 가로채기Claude가 하는 모든 도구 호출을 볼 수 있고(tool.call / tool.check), 이를 차단하거나 변경할 수 있습니다.
- UI 변경Claude Code 화면에 밴드, 패널, 상태 텍스트, 토스트를 그립니다(ui.render / $.ui.*).
- 명령어/도구 추가사용자나 Claude가 호출할 수 있는 새 슬래시 명령어나 도구를 등록합니다($.command.register / $.tool.register).
- 테스트 버전
- v2.1.310
- 마지막 테스트
- 필요 버전
- Claude Code ≥ 2.1.287
- 표시 위치
- 패널
Claude Code 안에서 설치:
/plugin install terminal-browser --marketplace zenbu-labs/terminal-browser이 모드는 무엇을 하나요?
terminal-browser는 Zenbu Labs가 만든 Claude Code 브라우저 모드로, Claude Code 안에서 실제 웹 브라우저를 실행합니다. /browser를 입력하면 대화 옆에 창이 열리고 라이브 페이지가 표시됩니다. /browser example.com을 입력하면 해당 사이트가 로드됩니다. 다시 /browser를 실행하거나 /browser close를 실행하면 닫힙니다. 창 안에서 클릭, 입력, 스크롤을 할 수 있으며 입력은 페이지로 전달됩니다.
실제 렌더링은 별도의 terminal-browser 프로그램에 포함된 Chromium 기반 브라우저가 맡습니다. 플러그인은 이 브라우저를 시작하고, 창 크기와 마우스·키보드 입력을 보내고, 브라우저가 만든 프레임을 이미지로 창에 그립니다. 그래서 Ghostty나 kitty처럼 kitty 그래픽 프로토콜을 지원하는 터미널에서만 동작합니다.
Claude와 함께 웹 앱을 만들 때 유용합니다. 세션을 벗어나지 않고 localhost:3000의 개발 서버를 확인하거나 HTML 보고서를 읽을 수 있습니다. 작성자는 이 플러그인이 아직 변경 중인 함수 훅 API에 의존하므로 실험적이라고 표시해 두었습니다.
설치
설치 블록을 사용하십시오. 작성자의 마켓플레이스를 추가한 뒤 거기서 플러그인을 설치합니다. 또한 PATH에 terminal-browser 프로그램이 있어야 합니다(FAQ 참조). 이미 열려 있던 세션에서는 /reload-plugins를 실행하십시오.
$ install terminal-browser
Claude Code 2.1.287 이상 필요
작성자의 마켓플레이스에서 설치: zenbu-labs/terminal-browser
1.Claude Code 안에서 한 줄로
/plugin install terminal-browser --marketplace zenbu-labs/terminal-browser실행 중인 세션(v2.1.275 이상)에 붙여 넣으세요. Claude Code가 먼저 마켓플레이스 추가 여부를 묻습니다.
2.셸에서 설치
claude plugin marketplace add zenbu-labs/terminal-browser claude plugin install terminal-browser@terminal-browser그런 다음 이미 열려 있는 세션에서 /reload-plugins를 실행하세요.
3.설치하지 않고 사용해 보기
git clone https://github.com/zenbu-labs/terminal-browser claude --plugin-dir ./terminal-browser/claude-code-plugin한 세션에서만 모드를 불러옵니다. 설정에는 아무것도 추가되지 않습니다.
작동 방식
플러그인은 터미널에서 세션이 시작될 때 /browser 명령을 등록합니다. 명령 핸들러는 짧습니다. hooks/register.tsx에 있는 코드는 다음과 같습니다.
on('command.run', { command: 'browser' }, async ($, e) => {
const arg = e.args.trim()
if (arg === 'close' || (!arg && state.open)) {
await closeBrowser($)
return { text: 'Closed terminal-browser' }
}
const opened = await openBrowser($, arg || null)
return { text: opened.ok ? 'Opened terminal-browser' : opened.error }
})브라우저를 처음 열 때 startBridge가 terminal-browser capabilities를 실행해, 설치된 버전이 embedding과 image-frames를 지원하는지 확인합니다. 그다음 terminal-browser claude-bridge launch를 실행하면 로컬 포트와 무작위 토큰이 출력됩니다. 이후의 모든 통신은 그 포트의 127.0.0.1로 HTTP를 통해 이루어지며, 토큰은 bearer 헤더로 전달됩니다.
watchBridge는/state를 롱 폴링하여 새 프레임이 올 때마다$.ui.blit으로 창에 복사합니다. 프레임은 공유 메모리에서 가져오므로 이미지 데이터가 HTTP 응답에 실리지 않습니다.surface.tsx는 키 입력과 마우스 이벤트를 약 20ms마다 모으고, 플러그인이 이를/input으로 보냅니다. 스크롤 휠 이벤트도 같은 경로로 갑니다.- 창 크기 변경은
/size로, 첫 URL은/open으로 보냅니다. - 브라우저가 에이전트에게 전달할 텍스트가 있으면 플러그인이
/inbox/take에서 가져와$.prompt.fill로 프롬프트 입력창에 넣습니다. 브라우저가 스크린샷을 첨부했다면 그 줄도 함께 추가됩니다. Enter를 누르기 전에는 아무것도 전송되지 않습니다.
호스트 이름만 입력하면 https:// URL이 되고, localhost 주소는 http://가 됩니다. 이 처리를 하는 헬퍼는 hooks/urls.ts에 있습니다.
사용자 지정
플러그인에는 agentTool 옵션이 하나 있으며 기본값은 꺼짐입니다. 켜면 플러그인이 open과 close 두 도구를 등록합니다. Claude는 이 도구를 호출해 창에 페이지를 보여 줄 수 있습니다. README에 나온 대로 /config에서 설정하거나 ~/.claude/settings.json의 pluginConfigs 아래에 지정하십시오.
다른 플러그인도 브라우저를 제어할 수 있습니다. 플러그인은 엔진에 $.browser.open({ url })과 $.browser.close()를 추가하고, 타입은 hooks/browser.d.ts에 담아 제공합니다. 이를 이용하면 모드가 창에 페이지를 여는 /tldraw나 /open-pr 같은 명령을 추가할 수 있습니다.
권한 및 안전
저희는 커밋 2165ae7의 claude-code-plugin/에 있는 모든 파일을 읽었습니다. register.tsx, surface.tsx, bridge-protocol.ts, urls.ts, 그리고 타입 파일입니다. 코드는 일반 TypeScript이며 난독화되거나 번들된 코드는 없습니다.
- 명령 실행(
$.process.run):terminal-browser프로그램만,capabilities와claude-bridge launch로 실행합니다. argv 배열 형태이며 제한 시간은 각각 10초와 20초입니다. 개발용 체크아웃에서는../cli/dist/main.js파일이 있으면 대신node ../cli/dist/main.js를 실행합니다. - 네트워크(
$.http.fetch): 위에서 시작한 로컬 브리지인http://127.0.0.1:<port>만 사용하며, 실행마다 새로 발급되는 토큰을 씁니다. README에 따르면 OS가 터미널의 로컬 네트워크 접근을 허용할지 물을 수 있습니다. - 프롬프트 채우기(
$.prompt.fill): 브라우저가 에이전트에게 보낸 텍스트가 입력창에 들어갑니다. 스스로 전송되는 일은 없습니다. - 도구 추가(
$.tool.register): agentTool을 켰을 때만 해당합니다. - 파일을 쓰거나, 설정을 바꾸거나, 대화 기록을 읽지 않습니다.
브라우저 자체는 별도의 terminal-browser 프로그램이며, curl | bash 스크립트로 설치되고 이 플러그인에 포함되어 있지 않습니다. 같은 저장소에 있는 그 프로그램에는 익명 사용 이벤트(실행, 일간 활성, 업그레이드, 크래시 유형)를 PostHog의 EU 엔드포인트로 보내는 코드가 있습니다. DO_NOT_TRACK 또는 TERMINAL_BROWSER_NO_TELEMETRY가 설정되어 있으면 이 코드는 전송을 건너뜁니다. 또한 브라우저는 다른 브라우저와 마찬가지로 사용자가 여는 모든 사이트를 불러옵니다.
- 파일 읽기
- 컴퓨터의 파일을 읽고 디렉터리 목록을 볼 수 있습니다($.fs.read / list / stat / exists).
- 명령어 실행
- 컴퓨터에서 셸 프로그램을 실행할 수 있습니다($.process.run / spawn). 정확히 어떤 프로그램인지는 소스를 확인하세요.
- 네트워크
- HTTP 요청을 보내거나 MCP 서버와 통신할 수 있습니다($.http.fetch / $.mcp.*).
- 도구 호출 가로채기
- Claude가 하는 모든 도구 호출을 볼 수 있고(tool.call / tool.check), 이를 차단하거나 변경할 수 있습니다.
- UI 변경
- Claude Code 화면에 밴드, 패널, 상태 텍스트, 토스트를 그립니다(ui.render / $.ui.*).
- 명령어/도구 추가
- 사용자나 Claude가 호출할 수 있는 새 슬래시 명령어나 도구를 등록합니다($.command.register / $.tool.register).
호환성 및 문제 해결
커밋 2165ae7의 플러그인을 Claude Code 2.1.310에서 claude plugin validate로 검증했습니다. 검증은 플러그인 디렉터리 경고 1건과 함께 통과했습니다. 플러그인에는 테스트가 없어 claude plugin test는 실행하지 않았습니다. 해당 커밋 이후 업스트림 저장소는 진행되었지만 이후 커밋 중 claude-code-plugin/을 건드린 것은 없으므로, 검토한 코드가 여전히 현재의 플러그인입니다. 이 페이지는 표준 등급이며 데모 녹화는 없습니다. 함수 훅이 필요하므로 Claude Code 2.1.287 이상이 필요합니다.
/browser가 "Please install terminal-browser first"라고 하면: 프로그램을 설치하고PATH에 있는지 확인하십시오.- 더 새로운 버전이 필요하다고 하면:
terminal-browser upgrade를 실행하십시오. - 화면이 깨지거나 창이 비어 있으면: 터미널이 유니코드 플레이스홀더를 갖춘 kitty 그래픽을 지원하지 않거나, tmux 등 멀티플렉서 안에 있을 가능성이 큽니다.
- 마우스 위치가 약간 어긋나면: Claude Code가 픽셀 단위 마우스 위치를 알려 주지 않기 때문에 생기는 문제로, README에도 알려진 제한으로 적혀 있습니다.
- 창이 더 넓어지지 않으면: Claude Code가 채팅 영역의 최소 너비를 유지하기 때문입니다.
자주 묻는 질문
- 이 Claude Code 브라우저를 쓰려면 플러그인 외에 필요한 것이 있나요?
- 네. 플러그인은 창을 그릴 뿐이고, 브라우저 자체는 따로 설치하는 terminal-browser 프로그램입니다(curl -fsSL https://terminal-browser.sh/install | bash 또는 brew install terminal-browser). 설치하지 않으면 /browser는 'Please install terminal-browser first'라고 답합니다. 설치된 버전이 너무 오래되었다면 terminal-browser upgrade를 실행하라고 안내합니다.
- 어떤 터미널에서 동작하나요?
- 유니코드 플레이스홀더를 갖춘 kitty 그래픽 프로토콜을 지원하는 터미널에서만 동작합니다. Ghostty, kitty, 그리고 cmux, supacode처럼 libghostty 기반인 터미널이 해당합니다. 다른 터미널에서는 브라우저를 열면 화면이 깨질 수 있다고 README가 경고합니다. tmux 같은 멀티플렉서는 현재로서는 대개 동작하지 않습니다.
- Claude가 스스로 브라우저에서 페이지를 열 수 있나요?
- agentTool 옵션을 켠 경우에만 가능하며, 기본값은 꺼짐입니다. 이 옵션은 모델이 호출할 수 있는 open과 close 도구를 추가합니다. 꺼져 있어도 README에 나온 대로 Claude는 terminal-browser CLI로 분할 창에 브라우저를 열 수 있습니다.
- 브라우저 창은 어떻게 닫나요?
- /browser close를 실행하거나, 창이 열려 있을 때 인수 없이 /browser를 실행하십시오. Claude Code에서 창을 닫으면 terminal-browser에도 브라우저가 닫혔다고 전달됩니다.
- 다른 모드가 브라우저를 열 수도 있나요?
- 네. 플러그인은 다른 플러그인의 훅에서 쓸 수 있도록 $.browser.open({ url })과 $.browser.close()를 추가합니다. README에는 이 방식으로 만든 /tldraw 명령이 예시로 나와 있습니다.
# 관련 모드
추천Agent Profiler
Claude Code 세션의 시간이 모델 대기, 도구, 서브에이전트 중 어디에 쓰였는지 상태 표시줄에 실시간으로 보여 주고 OTLP 트레이스도 내보냅니다.
- 상태 표시줄
- 패널
- 토스트
- 파일 쓰기
- 네트워크
- 도구 호출 가로채기
- UI 변경
- 명령어/도구 추가
v2.1.303에서 테스트됨
추천Agent Radar
실행 중인 서브에이전트마다 프롬프트 위에 한 줄씩: 경과 시간, 도구 수, 현재 작업. /radar 패널도 제공합니다.
- 프롬프트 위
- 패널
- 토스트
- 도구 호출 가로채기
- 프롬프트 읽기
- UI 변경
- 명령어/도구 추가
v2.1.291에서 테스트됨
추천Agent Tree
서브에이전트를 상자로 그리는 사이드 패널. 메인 세션, 어드바이저, 세션 로그도 함께 보여 줍니다.
- 패널
- 상태 표시줄
- 도구 호출 가로채기
- 프롬프트 읽기
- UI 변경
- 명령어/도구 추가
v2.1.310에서 테스트됨
추천Context Inspector
Claude Code 컨텍스트 창을 무엇이 채우는지, 재읽기와 중복이 얼마나 되는지, 압축이 무엇을 남겼는지 보여 줍니다.
- 상태 표시줄
- 패널
- 토스트
- 파일 쓰기
- 도구 호출 가로채기
- 프롬프트 읽기
- UI 변경
- 명령어/도구 추가
v2.1.303에서 테스트됨
더 보기: 패널 및 대시보드, Claude에 추가하는 도구.