terminal-browser

terminal-browser
터미널 안에서 실행되는 진짜 브라우저

CleanShot.2026-07-29.at.10.31.38.mp4

설치
curl (macOS & Linux):
curl -fsSL https://terminal-browser.sh/install | bash

참고: 버전을 업그레이드하려면 terminal-browser upgrade 를 실행하세요

Homebrew (macOS & Linux):
brew install terminal-browser

Windows
Windows에 설치하려면 WSL을 사용해야 합니다. kitty 그래픽을 지원하는 터미널도 Windows에서는 매우 제한적입니다. 다음은 Windows 내부에서 terminal-browser가 작동하는 것으로 제가 테스트한 터미널들입니다:

https://noctty.com/

curl -fsSL https://terminal-browser.sh/install | bash
Claude code 플러그인
설치 방법은 여기

사용법
terminal-browser # 브라우저 실행
terminal-browser open <url> # 지정한 url로 브라우저 열기
terminal-browser --split right # 오른쪽 분할 창에서 브라우저 열기
terminal-browser open --ssh <user@host> <url> # 모든 네트워크 요청을 원격 서버를 통해 수행
terminal-browser open --transparent <url> # 배경색이 없는 페이지에서는 터미널 배경이 비쳐 보임
terminal-browser ls # 열려 있는 브라우저 목록
terminal-browser action # 열려 있는 terminal-browser와 상호작용하기 위한 agent-browser 호환 cli
terminal-browser upgrade # 최신 버전으로 업그레이드

사용 사례:

코딩 에이전트와 웹사이트를 같은 터미널 탭에 둘 수 있습니다
에이전트가 열려 있는 terminal-browser와 완전히 상호작용할 수 있어, 에이전트에게 웹을 사용할 수 있는 능력을 부여합니다
에이전트에게 HTML 계획서를 만들게 한 뒤 terminal-browser에서 열도록 요청할 수 있으며, 그러면 에이전트 옆의 분할 창에서 자동으로 열립니다
terminal-browser는 SSH를 통해 작동하므로 원격 머신에서 실행 중인 웹사이트를 쉽게 미리 볼 수 있습니다

단축키

동작
macOS
Linux

종료
ctrl+q 또는 ctrl+c
ctrl+q

새 탭
cmd+t
ctrl+t

다음 / 이전 탭
ctrl+tab / ctrl+shift+tab 또는 cmd+alt+right / cmd+alt+left
ctrl+tab / ctrl+shift+tab 또는 ctrl+pagedown / ctrl+pageup

URL 편집
cmd+l
ctrl+l

명령 팔레트
cmd+p
ctrl+k 또는 alt+k

페이지 내 찾기
cmd+shift+f
ctrl+shift+f

다음 / 이전 일치 항목
enter / shift+enter
enter / shift+enter

새로고침
cmd+r
ctrl+r

뒤로 / 앞으로
cmd+[ / cmd+] 또는 ctrl+[ / ctrl+]
ctrl+[ / ctrl+]

확대 / 축소 / 초기화
터미널의 확대/축소 단축키
터미널의 확대/축소 단축키

Devtools
cmd+shift+i 또는 f12
ctrl+shift+i 또는 f12

Devtools 콘솔
cmd+alt+j
ctrl+alt+j

복사 / 붙여넣기 / 잘라내기
cmd+c / cmd+v / cmd+x
ctrl+c / ctrl+v / ctrl+x

페이지 녹화 (시작/중지)
ctrl+r
ctrl+shift+r

녹화 검토 완료
ctrl+enter
ctrl+enter

요소 선택 시작 (에이전트로 전송)
ctrl+g
ctrl+g

팝업 / 오버레이 닫기
escape
escape

어떻게 작동하나요?
ghostty, kitty, cmux, vscode 등 다수를 포함해 kitty 그래픽 프로토콜을 지원하는 터미널은 터미널에서 실행 중인 프로그램이 터미널에 픽셀을 표시할 수 있게 해줍니다. 우리는 이 기능을 사용해 chromium이 생성한 픽셀을 표시합니다.

우리는 electron의 오프스크린 렌더링 API를 사용해 chromium이 GPU에서 직접 생성한 픽셀을 읽습니다. 웹사이트가 시각적으로 변경될 때마다 terminal-browser는 변경된 영역만 덮는 작은 패치만 터미널로 전송합니다. 이러한 선택 덕분에 terminal-browser는 프레임을 하나도 떨어뜨리지 않고 부드럽게 렌더링할 수 있습니다.

브라우저 엔진이 시작되어 터미널에 픽셀을 표시한 후에는, 웹사이트가 실제로 작동하려면 사용자 입력을 읽을 수 있어야 합니다. terminal-browser는 터미널로부터 마우스 클릭, 마우스 위치, 키보드 이벤트를 수신한 뒤, 그 데이터를 기반으로 chromium에 합성 이벤트를 전송합니다. 터미널에서 가져올 수 없는 사용자 입력 이벤트의 경우, 백그라운드 swift 앱을 사용해 운영체제에서 직접 (비침투적으로) 입력 이벤트를 수신합니다. 이것이 terminal-browser가 부드러운 스크롤을 구현하고 트랙패드 이벤트를 수신할 수 있게 해주는 것입니다 (무한 캔버스가 있는 웹사이트도 terminal-browser 안에서 훌륭하게 작동합니다!)

브라우저의 외부 UI는 rust 위에 구축된 그래픽 엔진을 사용해 구현됩니다. 실제 UI는 커스텀 react 렌더러를 사용해 react 안에서 정의되며, 이를 통해 typescript로 브라우저의 UI를 구축할 수 있습니다. 외부 브라우저의 UI와 브라우저 콘텐츠 자체는 모두 rust 엔진 내부의 동일한 공유 캔버스에 그려지며, 이를 통해 브라우저 위에 UI를 레이어링할 수 있습니다.

여기서 설명한 기본 로직은 터미널에서 여러분만의 그래픽 애플리케이션을 구축하는 데 사용할 수 있는 javascript 라이브러리로 추상화되었습니다 - pixel

SSH
ssh를 통해 terminal-browser를 사용하는 권장 방법은 terminal-browser --ssh <ssh arguments> 를 실행하는 것입니다.

대안은 ssh로 접속한 머신에서 terminal-browser를 직접 실행하는 것입니다. 이 방법도 작동하지만:

웹사이트가 그리는 모든 프레임을 네트워크로 전송해야 합니다
웹사이트가 반응하기 전에 모든 사용자 입력이 네트워크로 전송되어야 합니다
일부 추가 최적화를 놓칩니다

terminal-browser --ssh 는 웹사이트를 로컬 기기에서 실행하고, 브라우저가 만드는 모든 네트워크 요청을 ssh를 통해 원격 머신으로 프록시하기만 함으로써 이를 개선합니다. 즉, 원격 머신의 localhost에서 실행 중인 어떤 웹사이트든 로컬 기기에서 로드할 수 있습니다.

임베디드 모드
terminal-browser는 기존 TUI 내부에 임베딩하는 것을 지원합니다. 참조 구현은
examples/embedded 를 참고하세요

텔레메트리
terminal-browser는 얼마나 많은 사람들이 프로젝트를 사용하는지 확인할 수 있게 해주는 의사 익명 사용 이벤트를 수집하며, 이는 프로젝트를 개선하는 데 매우 유용한 정보입니다.

텔레메트리는 다음 중 하나로 비활성화할 수 있습니다:

DO_NOT_TRACK=1
TERMINAL_BROWSER_NO_TELEMETRY=1
일반 설정 GUI에서 비활성화
terminal-browser config set telemetry.usage off

전송되는 모든 데이터는 ~/.local/state/terminal-browser-*/logs/telemetry.jsonl 에 추가되므로, 민감하거나 식별 가능한 정보가 기기를 떠나지 않는지 감사할 수 있습니다.

terminal-browser는 terminal-browser가 시작에 실패하거나 내부적으로 예기치 않은 오류가 발생할 경우 크래시 리포트도 수집합니다. 이는 다음 중 하나로 비활성화할 수 있습니다:

DO_NOT_TRACK=1
TERMINAL_BROWSER_NO_TELEMETRY=1
일반 설정 GUI에서 비활성화
terminal-browser config set telemetry.crashReports off

pixel/ 을 사용하는 경우 텔레메트리는 절대 활성화되지 않으며 비활성화할 것도 없습니다.

로드맵

linux 지원 ✅
디자인 모드 ⏳
chrome 확장 ⏳

기여하기

PR 설명은 사람이 작성하고 잘 설명해야 하며, 그렇지 않으면 닫습니다
PR을 만들 때 동기(motivation)가 설명에 명확히 정의되어야 합니다
머지될 가능성을 높이려면 PR 크기를 최소화하세요

terminal-browser의 로컬 개발 환경을 설정하는 권장 방법은 코딩 에이전트에게 요청하는 것입니다.

터미널 지원
terminal-browser는 터미널이 구현할 수 있는 API를 제공하며, 이를 통해 terminal-browser가 자신이 실행 중인 터미널을 안정적으로 스크립팅할 수 있습니다. 이를 통해 terminal-browser는 새 창 열기, 창 분할, 코딩 에이전트로 텍스트 전송, 창 포커스가 가능합니다. 이 API를 구현한 터미널에서는 terminal-browser를 더 통합된 방식으로 실행할 수 있습니다.

터미널에서 API 구현하기
터미널은 unix 소켓에서 수신 대기하고 terminal-browser에게 자신의 위치를 알려줌으로써 API를 구현합니다:

실행 시 unix 소켓에서 수신 대기합니다 (예: $TMPDIR/<your-app-id>.terminal-browser.sock ). 같은 사용자의 연결만 허용하세요.
생성하는 모든 셸의 환경에 TERMINAL_BROWSER_TERMINAL_SOCKET=<socket path> 를 설정하세요.
요청을 처리하세요. terminal-browser가 터미널에 무언가를 필요로 할 때마다 여러분의 소켓에 연결하고, 개행으로 끝나는 JSON 요청을 쓰고, 개행으로 끝나는 JSON 응답을 기다립니다. 응답을 쓴 후에는 연결을 닫으세요. 모든 요청은 자체 연결을 가지므로 유지할 세션 상태가 없습니다.

요청은 실행할 메서드, 그 params, 그리고 누가 요청하는지를 담은 JSON 객체입니다. caller 는 terminal-browser를 실행한 프로세스입니다:

{ "id" : " <unique string> " , "method" : " <name> " , "params" : { ... }, "caller" : { "pid" : 12345 , "cwd" : " /path " } }
같은 id와 함께 result 또는 error 로 응답하세요:

{ "id" : " <same id> " , "result" : { ... } }
{ "id" : " <same id> " , "error" : { "message" : " ... " } }
첫 번째 요청은 항상 hello 입니다. 응답에서 구현하는 메서드 목록을 나열하면, terminal-browser는 빠뜨린 메서드에 의존하는 모든 기능을 비활성화합니다:

→ { "method": "hello", "params": { "protocol": 1 } }
← { "result": { "name": "my-terminal", "methods": ["getCurrentPane", "split", "listPanes", "neighbor", "sendText", "pasteKey", "focusPane"] } }
pane은 { "id": string, "tab": string } 입니다. id 는 창에 대한 안정적인 식별자이며, tab 은 화면에 함께 표시되는 모든 창이 공유합니다

API:

메서드
params
결과
기능

getCurrentPane
{ tty, cwd }
{ pane } 또는 { pane: null }
ls , new-tab , --split 이 어디로 갈지 선택

split
{ from: pane, direction, command: string[], size, tty }
{}
--split

listPanes
{ tty }
{ panes: [{ id, tab, tty, command }] }
코딩 에이전트의 창 찾기

neighbor
{ from: pane, direction }
{ pane } 또는 { pane: null }
기존 브라우저 옆에 열기

sendText
{ pane, text }
{}
페이지 콘텐츠를 코딩 에이전트로 전송

pasteKey
{ pane }
{}
이미지를 코딩 에이전트로 전송

focusPane
{ pane }
{}
브라우저와 에이전트 사이를 이동

추가 참고 사항:

direction 은 right , left , down , up 중 하나입니다. size 는 새 창이 차지해야 할 공간의 비율( 0.4 ) 또는 기본값을 사용하려면 null 입니다.
split 은 새 창에서, 호출자의 cwd에서 command (argv 배열, 셸용으로 직접 인용하세요)를 실행해야 합니다.
getCurrentPane 은 호출자의 tty 를 받지만, 호출자는 어떤 창도 소유하지 않은 중첩 pty(멀티플렉서, 코딩 에이전트 래퍼) 아래에 있을 수 있습니다. tty와 일치하는 창이 없으면 caller.pid 의 조상들을 거슬러 올라가 그 체인에서 tty가 가장 먼저 나타나는 창을 반환하세요.
listPanes 항목은 창의 tty와 포그라운드 프로세스의 명령줄을 담으며, 알 수 없으면 null 입니다.
pasteKey 는 브래킷 붙여넣기가 아닌 리터럴 ctrl+v 키 입력(바이트 0x16 )을 전달해야 하며, 그래야 코딩 에이전트가 이를 키로 처리하고 클립보드를 읽습니다.

클라이언트 측, 즉 terminal-browser가 모든 결과에 대해 받아들이는 정확한 스키마는 shared/src/terminal-socket.ts 에 있습니다. 모든 메서드에 응답하는 node로 작성된 최소 터미널은 shared/test/terminal-socket.test.js 의 fakeTerminal 이며, 좋은 시작점입니다.

내장 지원
터미널이 이 API를 자체적으로 구현하지 않는 경우, terminal-browser는 pixel/packages/pixel/src/terminal/terminals 에 위치한 내장 구현을 제공합니다: ghostty, kitty, wezterm, cmux, tmux, vscode, tty7, herdr, supacode. 이들은 위의 소켓 메서드와 동일한 작업을 pixel/packages/pixel/src/terminal/terminal.ts 의 Terminal 인터페이스로, 각 터미널 자체의 스크립팅 cli를 사용해 구현합니다. 다른 터미널이나 멀티플렉서에 대한 지원을 추가하려면, Terminal 을 구현하는 파일을 그곳에 추가하고 terminals/index.ts 에 등록하세요.

Discord
감사의 말

kitty 그래픽 프로토콜을 개발한 kitty 프로젝트
awrit - 터미널 안에 chromium을 임베딩하려는 첫 번째 시도