termmirror

AI 에이전트에게 실제 대화형 터미널 세션을 제공하고, 인간이 그 세션을 지켜보고 입력할 수 있는 라이브 웹 뷰를 함께 제공하는 MCP 서버입니다.

대부분의 에이전트 도구는 스스로 종료되는 명령만 실행할 수 있습니다. 프롬프트를 띄우거나, 화면을 다시 그리거나, 키 입력을 기다리는 것은 전부 손이 닿지 않습니다. 설치 프로그램, 비밀번호 인증이 필요한 ssh, pdb, vim, 패키지 관리자의 설정 화면, 그리고 다른 에이전트의 CLI가 그 예입니다. termmirror는 실제 PTY 세션을 계속 열어 두므로 에이전트가 사람처럼 한 번에 한 키 입력씩 세션을 다룰 수 있고, 인간은 곁에서 지켜보다가 필요할 때 개입할 수 있습니다.

한 에이전트가 termmirror를 통해 Claude Code 세션을 구동하고 있습니다. 신뢰 프롬프트를 수락하고, 질문을 던지고, 화면에서 답변을 읽어 냈습니다. 브라우저 뷰는 실시간이며, 거기에 입력하는 내용은 곧바로 같은 터미널로 전달됩니다.

동일한 도구로 처리되는 전체 화면 TUI: 에이전트가 vim을 열고, 파일 끝으로 이동하고, 입력 모드로 전환한 다음 한 줄을 입력했습니다.

기능

• 실제 PTY 세션. node-pty 기반이며 화면 상태를 유지하는 헤드리스 터미널 에뮬레이터가 지원합니다. tmux 등 외부 의존성이 없습니다.

• TUI에 최적화. 대체 화면 감지, 제어 및 탐색 키 인코딩, 소프트 래핑된 줄을 풀어 주는 스크롤백을 지원합니다.

• 안정적인 대기. wait는 프로그램이 응답하고 안정된 후에 반환하므로, 읽은 화면은 입력 전 상태가 아니라 입력을 반영한 상태입니다.

• 라이브 웹 뷰. 실행 중인 모든 세션을 브라우저에서 지켜볼 수 있습니다. 페이지에 입력하면 PTY로 바로 전달되므로, 인간이 이어받았다가 다시 넘겨줄 수 있습니다.

• 에이전트 간 연동. 한 에이전트가 다중 턴 대화를 통해 다른 에이전트의 CLI를 구동할 수 있도록 설계되었습니다.

Related MCP server: ddx-term-mcp

요구 사항

• Node.js 20 이상

• macOS 또는 Linux

설치

git clone https://github.com/Ar9av/termmirror.git
cd termmirror
npm install && npm run build

Claude Code에 서버를 등록합니다:

claude mcp add termmirror -- node /absolute/path/to/termmirror/dist/src/index.js

MCP 클라이언트는 무엇이든 작동합니다. 서버는 stdio를 사용합니다.

사용법

세 가지 도구를 다음 순서로 사용합니다:

send_input  →  wait  →  read_screen

read_screen은 지금 화면의 모습을 그대로 반환합니다. 인쇄된 모든 내용의 로그가 아니라 스크린샷입니다. wait가 이 도구를 유용하게 만듭니다. 프로그램이 응답하고 잠잠해질 때까지 기다리므로 키 입력 후의 상태를 볼 수 있습니다.

도구

대기

idle이 기본값이며 대부분의 경우 올바른 선택입니다. 대화형 프로그램은 작업하는 동안 계속 다시 그리고, 사용자 차례가 되면 조용해지므로, 침묵은 안정적인 완료 신호입니다. 비교할 프롬프트를 노출하지 않는 스피너나 TUI에도 해당합니다. 느린 작업에는 timeout을 늘리세요.

no_output 결과는 입력 이후 아무것도 돌아오지 않았음을 의미합니다. 프로그램이 바쁘게 조용히 작업 중이거나, 입력이 등록되지 않은 것입니다.

예상 텍스트를 알고 있다면 pattern을 사용하세요. 화면 전체를 매칭하며 자신이 입력한 에코도 포함하므로, 방금 입력한 표시가 아니라 프로그램이 출력하는 것을 기다리세요.

세션 시청

첫 번째 세션이 7878 포트에서 로컬 웹 서버를 시작합니다. create_session이 반환한 URL을 열면 세션을 실시간으로 볼 수 있습니다. 페이지에 입력하는 내용은 PTY에 직접 쓰이므로, 인간이 에이전트가 처리해서는 안 되는 비밀번호를 입력하거나 프롬프트에 응답한 다음 제어권을 다시 넘겨줄 수 있습니다. 핸드오프 프로토콜이 아니라 같은 터미널을 반대쪽에서 바라보는 것뿐입니다.

예제

node examples/drive-claude.mjs "what is 2+2? reply with just the number"

한 에이전트가 claude를 시작하고, 신뢰 프롬프트를 수락하고, 질문을 던지고, 화면에서 답변을 읽어 냅니다. 이는 MCP 인터페이스가 제공하는 것과 동일한 도구를 직접 풀어서 작성한 예입니다.

개발

npm run build    # compile TypeScript to dist/
npm test         # build, then run the test suite

이 테스트 스위트는 서버의 나머지 부분이 의존하는 대기 의미론, 키 인코딩, 스크롤백, 웹 뷰의 라이브 스트림 및 입력 인계, 실제 MCP 프로토콜을 통한 종단 간 실행을 다룹니다.

이름에 대한 참고

패키지 이름은 m이 두 개인 termmirror입니다. alias/termirror/는 여기에 의존하는 스텁 패키지로, m이 하나인 표기법이 올바른 위치로 연결되게 합니다.

라이선스

MIT