브라우저 터미널 사용을 위한 CLI 및 확장 프로그램

Chrome extension + local daemon + CLI for executing commands in a browser-hosted terminal and returning structured output + exit codes to your local macOS terminal.

中文文档：README_zh.md

• Agent-first workflow: 로컬 LLM Agent 루프를 실행하지만, 명령은 클라우드 브라우저 터미널에서 실행합니다.
• Cloud-side verifiable execution: 스트리밍 출력 + 종료 코드 일치(exit-code parity)는 원격 실행을 관찰 가능하고 감사 가능한(auditable) 상태로 만듭니다. 로컬 자동화에서도 유용합니다.
• Practical non-local debugging: 복잡한 원격 환경(예: 클라우드 GPU, 컨테이너 클러스터, 배스천 전용 네트워크)에 걸쳐 AI 디버깅에 유용하며, 동시에 긴밀한 로컬 프론티어 모델 루프를 유지할 수 있습니다.

browterm-daemon

localhost에서 (ws://127.0.0.1:17373)

• Chrome MV3 extension으로 다음 기능을 수행합니다:
  • 터미널 탭에 바인딩(binds)됩니다.
  • 감싸진 명령을 주입(injects)합니다.
  • 스트리밍 출력을 캡처하고,
  • 센티넬 마커(sentinel markers)를 사용하여 명령어 종료 코드를 추출합니다.

browterm

CLI로 다음 기능을 수행합니다:

명령을 전송하고,

• 실시간으로 출력을 스트리밍하며,
• 원격 명령의 반환 코드와 함께 종료됩니다.

packages/core

: 프로토콜 계약(protocol contracts) + 마커 래퍼(marker wrapper) + 파서.
packages/bridge

: websocket daemon 및 요청 큐(request queue).
packages/cli

: 로컬 CLI (browterm).
extension

: Chrome extension (MV3).
assets/logo

: 브랜드 로고 에셋 (SVG + 확장 프로그램 아이콘 소스).
assets/diagrams

: 아키텍처 및 런타임 흐름 다이어그램.
DEVELOPMENT.md

: 리포지토리 개발 명령어.

• 로컬 CLI (browterm)는 명령, 타임아웃, 클라이언트 메타데이터를 포함하는 exec 요청을 daemon에 전송합니다. - Bridge daemon은 요청을 인증하고, 큐에 넣고, 단일 활성 실행(single-active execution)을 보장합니다.

• Bridge는 @browser-terminal-use/core를 사용합니다.

• 사용자 명령을 고유한 시작/종료/끝 마커로 래핑합니다. - Chrome 확장 프로그램 서비스 워커가 래핑된 명령을 현재 연결된 터미널 탭으로 라우팅합니다.

• 콘텐츠 스크립트(Content script)는 디버거 API를 우선적으로 사용하여 터미널 UI에 명령 입력을 주입하고, 필요할 경우 합성 입력(synthetic input)으로 폴백합니다.

• 브라우저 터미널은 래핑된 명령을 원격 셸 측에서 실행합니다.

• 확장 프로그램이 출력 스트림을 캡처(웹소켓 우선, DOM 폴백)한 다음 파서가 마커 경계를 분리합니다.

• Bridge는 구문 분석된 청크와 종료 코드를 받고, 출력을 CLI로 스트리밍하며 동일한 원격 반환 코드로 최종화합니다.

• 요청은 데몬 큐(daemon queue)에서 직렬화되어 하나의 터미널 탭에서 명령 간의 오염을 방지합니다.
  --timeout-ms는 서버 측에서 강제되며, 타임아웃이 활성 요청을 종료하고 큐를 언블록합니다. browterm cancel <requestId>는 활성 또는 대기 중인 요청을 중단할 수 있습니다.- 마커 구문 분석에 실패하면 데몬은 무한정 대기하는 대신 캡처/호환성 오류(capture/compatibility error)를 반환합니다.

• macOS와 Node.js 20 이상 (Node 22로 테스트됨).

• Google Chrome (확장 프로그램 로드를 위해 개발자 모드 활성화 필요).

• 대상 브라우저 터미널 페이지에 대한 접근 권한.

npm install -g @browser-terminal-use/bridge @browser-terminal-use/cli

localhost:에서 데몬 실행:

browterm-daemon --host 127.0.0.1 --port 17373

선택적 플래그:

--token <토큰> # 선택 사항, 더 강력한 보안을 위해 사용 (확장 프로그램/CLI와 일치해야 함)
--default-timeout-ms 120000
--max-timeout-ms 600000
...

상태 확인 엔드포인트:

curl http://127.0.0.1:17373/v1/health

• chrome://extensions 열기.
  . - 개발자 모드(Developer mode) 활성화. - 압축 해제된 확장 프로그램 로드(Load unpacked) 클릭. - 저장소 디렉터리 extension/ 선택.

• 확장 프로그램 옵션 페이지 열기.

• 설정: Bridge URL:ws://127.0.0.1:17373/extension

• 저장.

• Chrome에서 웹 터미널 페이지 열기.

• 확장 프로그램을 로드/업데이트한 후 해당 탭을 새로고침합니다.

• 확장 프로그램 아이콘을 한 번 클릭합니다.

• 이렇게 하면 현재 탭이 선호되는 실행 대상(preferred execution target)으로 설정됩니다.

상태 확인:

browterm health

명령 실행:

명령 실행:

browterm exec "uname -a"

JSON 모드:

browterm exec --json "ls -la"

실행 요청 취소:

browterm cancel <requestId>

• CLI는 터미널 출력을 실시간으로 스트리밍합니다.

• CLI는 원격 명령어와 동일한 반환 코드로 종료됩니다.

• Bridge는 요청을 큐에 넣고 한 번에 하나의 명령만 실행합니다.

• 데몬이 실행 중인지 확인합니다.

• 확장 프로그램 옵션 URL을 확인합니다.

• 확장 프로그램 서비스 워커가 활성화되어 있는지 확인합니다 (필요한 경우 확장 프로그램 페이지 열기).

• 터미널 탭을 엽니다.

• 확장 프로그램 아이콘을 클릭하여 탭에 바인딩합니다.

• 터미널 탭을 한 번 새로고침한 후 다시 시도합니다.

• 터미널이 지원하지 않는 websocket 프로토콜/인코딩을 사용할 수 있습니다.

• 탭 재바인딩을 시도하고 다시 실행해 보세요.

• 데몬을 활성화하고 --debug를 사용하여 로그를 검사하세요.

• 확장 프로그램은 신뢰할 수 있는 입력 주입을 위해 Chrome Debugger API를 사용합니다.

• 첫 사용 시, 안정적인 명령어 전달을 허용하는 프롬프트를 승인해야 합니다.

• 파서가 터미널 스트림 프레이밍에서 마커 경계를 명확하게 분리하지 못했습니다.

• 다시 실행해 보세요. 지속된다면 해당 터미널 벤더의 프레이밍 형식에 맞게 래퍼/파서를 조정하세요.

browterm health
browterm exec [--timeout-ms N] [--json] [--request-id ID] "<command>"
browterm cancel <requestId>

전역 옵션:

--host <host> # 기본값 127.0.0.1
--port <port> # 기본값 17373
--token <token> # 선택 사항, 더 강력한 보안을 위해 사용 (데몬/확장 프로그램과 일치해야 함)
...

• 종료 코드는 각 명령어를 고유한 마커로 감싸서 캡처합니다:
  __BT_START_<id>__

__BT_RC_<id>__:<code>

__BT_END_<id>__

• 확장 프로그램은 주로 페이지 websocket 트래픽에서 출력을 캡처합니다.

• DOM 변형(mutation) 캡처는 websocket 캡처를 사용할 수 없을 때의 대체 방법입니다.

• Bridge는 결정론적 동작을 위해 실행 요청(단일 활성 명령어)을 직렬화합니다.

• 데몬은 localhost에만 바인딩됩니다.

• 확장 프로그램과 CLI는 로컬 데몬을 통해서만 통신합니다.

• 확장 프로그램은 안정적인 대상 제어를 위해 명시적인 탭 바인딩이 필요합니다.

• 브라우저 터미널 구현은 다양하며, websocket 인코딩은 일부 제품에서 독점적일 수 있습니다.

• 일부 터미널 UI는 합성 키보드 입력 폴백(fallback)을 차단할 수 있습니다.

• 크로스 오리진 iframe 터미널은 페이지 제약 조건에 따라 관찰 가능성(observability)을 저하시킬 수 있습니다.

• 진정으로 상호작용적인 TUI(Text User Interface)는 완전히 지원되지 않습니다 (현재 모델은 전체 PTY 미러링이 아닌 명령어 지향적입니다).

저장소의 빌드/테스트/실행 명령은 DEVELOPMENT.md를 참조하십시오.