clsh 소개
최근 개발 생태계에서는 Claude Code, Aider와 같은 터미널 기반의 AI 코딩 에이전트가 필수적인 도구로 자리 잡아가고 있습니다. 이러한 AI 도구들은 대규모 코드 리팩토링이나 여러 파일에 걸친 복잡한 작업을 수행할 때 매우 유용하지만, 작업이 완료되기까지 꽤 오랜 시간이 소요되는 경우가 많습니다. 개발자가 잠시 커피를 내리거나 산책을 다녀오는 동안, 에이전트가 예기치 않은 오류로 멈춰 있거나 사용자의 커밋 승인을 기다리느라 작업이 중단된 채 방치되는 상황이 종종 발생합니다. 외부에서 모바일 기기의 SSH 앱으로 접속하여 상태를 확인하려 해도, iOS나 안드로이드의 기본 키보드에는 Ctrl, Esc, 방향키, Opt 등의 필수적인 특수 키가 부족하여 git diff를 확인하거나 에이전트의 프롬프트를 조작하는 데 극심한 피로감을 유발합니다.
이러한 모바일 터미널 환경의 본질적인 한계를 극복하기 위해 등장한 오픈소스 도구가 바로 clsh입니다. clsh는 macOS에서 실행 중인 실제 터미널 환경을 스마트폰, 태블릿, 데스크톱의 웹 브라우저로 실시간 스트리밍해 주는 매우 직관적이고 가벼운 애플리케이션입니다. 단순한 터미널 에뮬레이션 흉내를 내는 것이 아니라 node-pty를 활용해 실제 PTY(가상 터미널) 세션을 구동하므로, 복잡하고 화려한 Claude Code의 TUI(터미널 사용자 인터페이스)가 모바일 화면에서도 깨짐 없이 완벽하게 렌더링됩니다.
가장 눈에 띄는 핵심 차별점은 모바일 터미널 작업의 가장 큰 장애물이었던 키보드를 처음부터 새로 설계했다는 점입니다. clsh는 스마트폰 브라우저 하단에 MacBook 스타일의 6열 개발자 전용 커스텀 키보드를 제공합니다. 이 덕분에 개발자는 언제 어디서든 모바일 기기로 터미널에 접속하여, 진행 중인 AI 에이전트의 세션을 모니터링하고, 변경된 코드를 확인한 뒤 Ctrl+C를 눌러 작업을 취소하거나 엔터를 눌러 커밋을 승인하는 등의 작업을 데스크톱과 동일한 감각으로 이어갈 수 있습니다.
기존에도 모바일 기기에서 원격으로 서버나 PC에 접속하기 위해 Blink Shell, Termux, ttyd, Wetty와 같은 훌륭한 터미널 환경이나 SSH 클라이언트들이 존재했습니다. 하지만 이 도구들은 대부분 무거운 원격 개발 환경을 가정하거나, 모바일 OS의 기본 키보드를 그대로 사용한다는 맹점이 있었습니다. 기본 키보드에서 단축키나 특수 문자를 입력하려면 여러 번의 스와이프나 메뉴 이동을 거쳐야만 했습니다.
반면 clsh는 개발자가 오직 '자신의 로컬 쉘'에 빠르고 편리하게 접근하는 데에만 초점을 맞췄습니다. 복잡한 클라우드 가입이나 플랫폼 종속적인 앱 설치를 요구하지 않고, 브라우저 환경 위에 완전히 독립적인 커스텀 모바일 키보드를 띄웁니다. 따라서 기존 SSH 앱들이 해결하지 못한 '모바일 타이핑의 불편함'을 획기적으로 해소하며, 개발자는 노트북 앞을 떠난 상태에서도 완벽한 터미널 조작성을 보장받게 됩니다.
clsh의 주요 기능 및 특징
모바일 최적화 커스텀 개발자 키보드
clsh를 실용적으로 만들어주는 가장 핵심적인 기능은 터치스크린에 특화된 커스텀 키보드 인터페이스입니다. 기본 iOS 키보드를 대체하여 하단에 배치되는 이 키보드는 Fn, Ctrl, Cmd, Opt, 화살표, Esc 등 터미널 조작에 필수적인 모든 키를 제공합니다. 또한 스마트폰 화면의 특성상 여러 키를 동시에 꾹 누르고 있는 것이 어렵다는 점을 고려해, 모디파이어 키(Modifier Keys)가 한 번 누르면 활성화 상태를 유지하는 '스티키(Sticky)' 기능을 구현하여 조작성을 극대화했습니다. 덤으로 6가지의 다양한 키보드 스킨을 제공해 사용자의 취향에 맞게 커스터마이징할 수도 있습니다.
Session Grid를 통한 다중 작업 모니터링
여러 개의 터미널 세션을 띄워놓고 작업하는 개발자를 위해, clsh는 모바일 화면에서도 직관적으로 여러 작업을 파악할 수 있는 'Session Grid' 뷰를 지원합니다. 이는 스마트폰 화면에서 작동하는 시각적인 tmux와 같은 역할을 합니다. 각 세션의 실시간 진행 상황을 그리드 형태의 프리뷰로 한눈에 확인할 수 있으며, 자세히 보고 싶은 특정 세션의 화면을 탭하면 즉시 확대되어 터미널 제어 화면으로 진입합니다.
tmux 기반의 강력한 세션 유지력 (Session Persistence)
클라우드 환경이 아닌 로컬 Mac에서 작동하는 시스템인 만큼, 네트워크 변경이나 로컬 장비의 상태 변화에 대응하는 것이 중요합니다. 시스템에 tmux가 설치되어 있는 경우, clsh는 생성되는 세션들을 tmux 내부로 래핑(Wrapping)하여 실행합니다. 이를 통해 노트북의 덮개를 닫고 이동하거나 백엔드 서버가 재시작되더라도 세션이 종료되지 않고 백그라운드에 안전하게 보존되며, 언제든 스마트폰으로 다시 접속해 끊김 없이 작업을 이어갈 수 있습니다.
경량화된 최신 웹 기술 스택
Phone / Tablet / Browser
│
│ HTTPS (WebSocket)
▼
┌──────────────┐
│ Tunnel │ ngrok (static URL) / SSH (localhost.run) / Wi-Fi
└──────┬───────┘
▼
┌──────────────────────┐
│ clsh agent │ ← runs on your machine
│ ├── PTY 0: zsh │
│ ├── PTY 1: claude │
│ ├── PTY 2: ... │
│ └── up to 8 sessions │
└──────────────────────┘
흥미롭게도 약 55개의 소스 파일로 구성된 이 프로젝트 코드의 90% 이상은 개발자가 Claude Code와 대화하며 만들어낸 결과물입니다. TypeScript 모노레포(Monorepo) 구조로 깔끔하게 구성되어 있습니다.
- 프론트엔드 (클라이언트): React로 구축되었으며, 터미널 화면의 정확한 렌더링을 위해 업계 표준인
xterm.js라이브러리를 채택했습니다. - 백엔드 (로컬 서버): Express와 Node.js 기반으로 실행되며, 단순한 출력의 시뮬레이션이 아닌
node-pty를 활용한 실제 운영체제 수준의 PTY 터미널 세션을 관리합니다. - 통신 아키텍처: 프론트엔드와 백엔드 간의 빠른 키 입력 및 화면 렌더링을 지연 없이 처리하기 위해 WebSocket을 통한 양방향 I/O 통신을 사용합니다. 외부 접속 시에는 ngrok이나 SSH 역방향 터널링(예: localhost.run)을 활용해 로컬 환경을 안전한 HTTPS로 노출시킵니다.
clsh 설치 및 초기 환경 설정
복잡한 의존성 설치나 회원가입 절차가 전혀 필요 없습니다. 클라우드 의존성 없이 로컬 장비 내에서 모든 데이터가 처리됩니다. 터미널에서 다음 명령어들을 활용하여 즉시 시작할 수 있습니다.
-
초기 설정:
npx clsh-dev setup명령어를 입력하면 네트워크 터널링 방법 등의 설정을 안내받을 수 있으며, 설정값은~/.clsh/config.json파일에 저장됩니다. -
서버 실행: 설정 후
npx clsh-dev명령어만 입력하면 백엔드 에이전트와 웹 서버가 동시에 구동되며 외부에서 접속할 수 있는 환경이 열립니다.
라이선스
clsh 프로젝트는 MIT 라이선스로 공개 및 배포되고 있어 개인 및 상업적 목적으로 자유롭게 활용하고 수정할 수 있습니다.
clsh 공식 홈페이지
clsh 프로젝트 GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 