MobileCLI/mobilecli

Claude Code, Codex, Gemini CLI 및 모든 터미널 세션을 실시간으로 휴대폰에 스트리밍하세요. 소파에 앉아서 도구 호출 (tool calls)을 승인할 수 있습니다. 어디에서나 개발 머신의 파일을 탐색하고 편집하세요.

대규모 리팩터링 (refactor)을 위해 Claude Code를 실행합니다. 커피를 만들러 갑니다. 20분 후에 돌아와 보니, 실행 2분 만에 도구 승인 (tool approval) 단계에서 막혀 있는 것을 발견합니다.

이런 일은 AI 코딩 어시스턴트 (AI coding assistants)를 사용할 때 끊임없이 발생합니다. 이들은 강력하지만 인간의 개입 (human in the loop)이 필요합니다. 하지만 그 인간이 반드시 책상에 묶여 있을 필요는 없습니다.

MobileCLI는 사용자가 제어하는 네트워크 경로를 통해 터미널을 휴대폰으로 스트리밍합니다. AI 어시스턴트가 질문을 하거나, 도구 접근 권한을 요청하거나, 작업을 완료하면 푸시 알림 (push notification)을 받게 됩니다. 알림을 탭하여 컨텍스트 (context)를 읽고, 승인 또는 거부를 선택한 뒤 하던 일로 돌아가면 됩니다.

터미널 스트림은 로컬 데몬 (local daemon)에 의해 WebSocket을 통해 제공됩니다. 모바일 클라이언트는 auth-v2 QR 자격 증명 (credentials)과 페어링되며, 데몬이 세션, 터미널 출력, 파일 시스템 데이터 또는 푸시 토큰 등록 (push-token registration)을 보내기 전에 챌린지-응답 핸드셰이크 (challenge-response handshake)를 통해 소유권을 증명합니다. MobileCLI 터미널 릴레이 (terminal relay)나 계정 시스템은 존재하지 않지만, 푸시 알림은 Expo의 푸시 서비스 (push service)를 통해 전달되며, 데몬은 신뢰할 수 있는 LAN, Tailscale 네트워크 또는 보호된 커스텀 엔드포인트 (custom endpoint)를 통해서만 접근 가능해야 합니다.

curl -fsSL https://mobilecli.app/install.sh | bash

이 macOS/Linux 설치 프로그램은 일치하는 GitHub Release 아카이브를 다운로드하고, 압축을 풀기 전에 해당 릴리스의 SHA256SUMS.txt 매니페스트 (manifest)를 통해 검증한 후, 바이너리 (binary)를 PATH에 추가합니다. Windows 사용자는 GitHub Releases의 .zip 파일을 이용하거나 Cargo를 통해 설치해야 합니다. 체크섬 (checksum)은 게시된 릴리스 매니페스트와 비교하여 손상되었거나 변조된 아카이브로부터 보호합니다. 더 강력한 공급망 보안 (supply-chain assurance)을 원한다면 소스 코드를 검사하거나 Cargo를 사용하여 소스에서 직접 빌드하세요.

기타 설치 방법

# crates.io에서 설치
cargo install mobilecli
# 소스에서 설치
...

mobilecli setup

mobilecli setup

이 명령은 데몬 (daemon)을 시작하고, 연결 모드를 저장하며, 새로운 모바일 자격 증명 (credential)을 생성하고, QR 코드를 표시합니다. MobileCLI iOS 앱을 열고 Scan QR Code를 탭하면 연결됩니다. QR 코드는 ws:// 또는 wss:// URL, 장치 ID/이름 메타데이터, 자격 증명 ID, 서버 ID, 그리고 일회용 페어링 토큰 (one-time pairing token)을 인코딩합니다. 데스크톱에는 원본 토큰이 아닌 유도된 검증기 (derived verifier)만 저장됩니다.

mobilecli claude # Claude Code
mobilecli codex # OpenAI Codex
mobilecli -n "DB Migration" claude # 이름이 지정된 세션
...

이제 휴대폰에 터미널 출력이 실시간으로 표시됩니다. 그대로 자리를 뜨셔도 됩니다.

MobileCLI는 두 가지 구성 요소로 이루어져 있습니다: 개발 머신에서 실행되는 **Rust 데몬 (daemon)**과 휴대폰에서 실행되는 React Native 앱입니다.

내 머신 (Your Machine)          내 휴대폰 (Your Phone)
┌─────────────────────────────────┐ ┌───────────────────────────┐
│ mobilecli daemon (Rust) │ WebSocket │ MobileCLI App │
...

데몬은 각 세션에 대해 PTY (pseudo-terminal, 가상 터미널)를 할당하고, WebSocket을 통해 바이트 출력을 스트리밍하며, 휴대폰의 키보드 입력을 다시 PTY로 전달합니다. 모바일 앱은 번들로 포함된 xterm.js 인스턴스를 사용하여 스트림을 렌더링하며, 전체 ANSI 색상, 커서 위치 지정, 그리고 대체 화면 버퍼 (alternate screen buffer)를 지원합니다.

여러 AI 어시스턴트를 동시에 실행하십시오. 세션 (Sessions) 탭에는 실시간 상태 표시기와 함께 모든 활성 및 과거 세션이 표시됩니다. 길게 눌러 세션의 이름을 변경하거나 닫을 수 있습니다. + 버튼을 탭하면 휴대폰에서 직접 새로운 CLI를 생성할 수 있습니다 — Claude Code, OpenAI Codex 또는 일반 쉘 (shell) 등.

세션은 데몬 재시작 후에도 유지됩니다. 앱을 닫았다가 다시 돌아와도 전체 스크롤백 히스토리 (scrollback history)와 함께 세션이 그대로 남아 있습니다.

데몬은 각 세션에서 어떤 AI 어시스턴트가 실행 중인지 자동으로 식별하고, 출력을 파싱하여 도구 승인 프롬프트 (tool approval prompts), 계획 검토 (plan reviews), 질문과 같은 대기 상태 (wait states)를 감지합니다.

CLI	대기 상태 감지 (Wait-state Detection)	감지 항목
Claude Code	ANSI 출력 파싱 (ANSI output parsing)	도구 호출 (Tool calls), 계획 검토 (plan reviews), 질문 (questions), 완료 (completion)
OpenAI Codex	출력 패턴 매칭 (Output pattern matching)	승인 프롬프트 (Approval prompts), 완료 신호 (completion signals)
Gemini CLI	프롬프트 감지 (Prompt detection)	Yes/No 프롬프트, 입력 요청 (input requests)
Shell	일반 (Generic)	수동 상호작용이 포함된 전체 터미널

대기 상태 (wait state)가 감지되면, 데몬 (daemon)이 사용자의 휴대폰으로 푸시 알림을 보냅니다. 앱을 계속 열어두거나 세션을 지켜볼 필요가 없습니다. 사용자의 주의가 필요한 순간 즉시 알림을 받게 됩니다.

터미널 뷰는 WebView 내부에서 실행되는 전체 xterm.js 5.3 인스턴스입니다:

256색 ANSI (256-color ANSI) 렌더링 및 정확한 커서 위치 지정
스크롤 가능한 히스토리 (Scrollable history) — 출력을 위로 스크롤할 수 있으며, 하단의 새로운 콘텐츠를 따라 자동 스크롤됩니다.
터치 키보드 (Touch keyboard) — Esc, 화살표 키 (CLI 히스토리용), 붙여넣기, 파일 첨부 버튼을 제공하는 툴바 포함
반응형 크기 조정 (Responsive resize) — 터미널 크기가 휴대폰/태블릿 화면에 맞춰 조정되며, 새로운 크기를 PTY로 전송하여 출력이 올바르게 재흐름 (reflow) 됩니다.
기본적으로 데스크톱 안전 (Desktop-safe by default) — 모바일 크기 조정 시 데스크톱 터미널 창의 물리적 크기를 강제로 변경하지 않고도 자식 PTY의 크기를 변경합니다 (MOBILECLI_DESKTOP_RESIZE_POLICY=mirror 설정 시 기존의 미러링 방식 복구)
낮은 지연 시간 (Low latency) — LAN을 통한 WebSocket 스트리밍은 일반적으로 10ms 미만입니다.

Files 탭을 통해 개발 머신의 파일 시스템 (filesystem)에 직접 접근할 수 있습니다:

탐색 (Browse) 브레드크럼 (breadcrumb) 내비게이션, 파일 크기 및 수정 시간을 통해 디렉터리 탐색
검색 (Search) 전체 프로젝트 트리에서 파일 이름으로 검색
편집 (Edit) 저장/실행 취소/다시 실행 (Save/Undo/Redo), 마크다운 (Markdown) 서식 단축키 (굵게, 기울임꼴, 코드, H1, 목록, 링크) 및 구문 인식 (syntax awareness) 기능을 갖춘 내장 에디터로 파일 편집
생성 (Create) 휴대폰에서 새로운 파일 및 폴더 생성
파괴적인 작업은 선택 사항으로 유지 (Destructive actions stay opt-in) — 삭제 및 이름 변경은 데몬 (daemon) 설정에서 기본적으로 비활성화되어 있으며, 설정 또는 구성 검토 중에 명시적으로 활성화해야 합니다.
업로드 (Upload) 휴대폰에서 사진, 파일 또는 카메라 캡처를 개발 머신으로 업로드 — 데몬이 이를 저장하고 데스크톱 경로를 반환하므로 터미널에 바로 붙여넣을 수 있습니다.
Git 통합 (Git integration) — 파일 목록에 Git 상태 표시기가 표시됩니다.

알림은 현재 iOS 앱을 위한 Expo의 푸시 알림 서비스 (push notification service)를 통해 전달됩니다. 데몬은 다음과 같은 경우에 푸시를 보냅니다:

• AI CLI가 대기 상태에 진입할 때 (도구 승인, 계획 검토, 질문)
• 세션이 종료되거나 나갈 때
• 오래 걸리는 명령이 완료될 때

푸시 토큰 (push token)은 WebSocket 연결을 통해 등록된 후, 데몬이 Expo의 푸시 API를 호출하는 데 사용됩니다. 알림 페이로드 (payload)에는 알림 제목/본문 및 세션 ID가 포함되며, 전체 터미널 스트림은 포함되지 않습니다.

MobileCLI는 터미널 스트리밍 경로를 셀프 호스팅 (self-hosted) 방식으로 유지하지만, 현재 iOS 푸시 알림 경로는 Expo의 클라우드 푸시 서비스를 사용합니다.

MobileCLI 터미널 릴레이 없음 (No MobileCLI terminal relay). 터미널 출력은 구성된 네트워크 경로를 통해 데몬에 의해 제공됩니다.
계정 없음 (No accounts). 회원가입, 이메일, OAuth가 필요하지 않습니다.
텔레메트리 없음 (No telemetry). 데몬은 아무것도 수집하지 않습니다.
Auth-v2 페어링 (Auth-v2 pairing). 각 모바일 앱은 SecureStore에 페어링 토큰을 저장하며, 세션 또는 터미널 데이터를 받기 전에 챌린지-응답 (challenge-response) 증명을 통해 인증합니다. 모바일 액세스를 교체하거나 취소하려면 mobilecli pair --rotate 또는 mobilecli credentials revoke <credential_id>를 사용하세요.
네트워크 격리 여전히 중요 (Network isolation still matters). 포트 9847을 유지하세요.

신뢰할 수 있는 LAN (Local Area Network), Tailnet, 방화벽 허용 목록(allowlist), 또는 보호된 커스텀 엔드포인트(custom endpoint) 상에서 사용하세요. 퍼블릭 인터넷(public internet)에 직접 노출하지 마십시오. 제한된 리소스 (Bounded resources). 데몬(daemon)은 리소스 고갈을 방지하기 위해 동시 연결 수, 채널 버퍼 크기 및 세션 수를 제한합니다.

사용자의 터미널 스트림은 MobileCLI가 운영하는 서버를 거치지 않습니다. 푸시 알림(push notifications)이 활성화된 경우, Expo는 알림 제목/본문 및 세션 ID를 수신합니다. Tailscale 또는 커스텀 원격 URL을 구성하면 트래픽은 해당 네트워크 제공자 또는 엔드포인트를 따릅니다.

모드	작동 방식	설정
LAN	신뢰할 수 있는 WiFi/이더넷을 통한 WebSocket. 가장 빠르고 간단함.	mobilecli setup 중 자동 감지
Tailscale	WireGuard 기반의 메시 VPN (mesh VPN). 데몬을 퍼블릭 인터넷에 노출하지 않고 Tailnet을 통해 접속.	mobilecli setup → Tailscale IP 선택
Custom URL	프라이빗 리버스 프록시(reverse proxy) 또는 TLS 터미네이터(terminator)와 같은 자체 보호된 ws:// 또는 wss:// 엔드포인트.	설정 중 URL 제공

대부분의 사용자에게는 LAN 모드만으로 충분합니다. 터미널을 열고, QR 코드를 스캔하면 끝입니다.

mobilecli [OPTIONS] [COMMAND]
세션 명령:
mobilecli Start default shell with streaming
...

데몬은 로그인 시 자동으로 시작되도록 등록할 수 있습니다:

플랫폼	메커니즘	명령
Linux	systemd 사용자 서비스 (user service)	mobilecli autostart install
macOS	launchd 에이전트 (agent)	mobilecli autostart install
Windows	작업 스케줄러 (Task Scheduler)	mobilecli autostart install

Windows 참고: 가시적인 터미널 창을 위한 사용자 세션 실행에 관한 중요한 세부 사항은 docs/WINDOWS_SETUP.md를 참조하세요.

모든 새로운 터미널 세션을 자동으로 래핑(wrap)하려면:

mobilecli shell-hook install

이 명령은 .bashrc, .zshrc, config.fish 또는 PowerShell $PROFILE에 한 줄의 명령어를 추가합니다. 새로 여는 모든 셸은 자동으로 휴대폰으로 스트리밍됩니다. 일시적으로 이를 우회하려면:

MOBILECLI_NO_AUTO_LAUNCH=1 bash

플랫폼	아키텍처	상태
Linux	x86_64, aarch64	완벽 지원
macOS	Intel, Apple Silicon	완벽 지원
Windows	x86_64	완벽 지원

플랫폼	상태
iOS (iPhone + iPad)	App Store에서 이용 가능 — MobileCLI 다운로드
Android	개발 중

CLI 데몬 (daemon)은 오픈 소스이며 영구적으로 무료입니다 (MIT 라이선스).

모바일 앱은 무료 티어와 선택 사항인 Pro 업그레이드를 제공합니다:

무료 (Free)	Pro
실시간 터미널 스트리밍	무제한 세션
...	무료 (Free) $19.99/년 또는 $29.99 평생 소장

모든 설정은 ~/.mobilecli/에 저장됩니다:

파일	용도
config.json	기기 식별 정보 및 연결 모드/URL
sessions.json	유지되는 세션 메타데이터 (이름, 히스토리)
daemon.pid	실행 중인 데몬의 프로세스 ID (Process ID)
daemon.port	활성 WebSocket 포트 (기본값: 9847)
daemon.log	디버그 로그 출력

cd cli
cargo build # 디버그 빌드 (Debug build)
cargo run -- setup # 설정 마법사 실행 (Run setup wizard)
...

데몬은 tokio를 기반으로 구축된 약 7,000줄의 비동기 (async) Rust 코드로 구성되어 있습니다.

주요 모듈:

모듈	라인 수	역할
daemon.rs	2,700	WebSocket 서버, 세션 생명주기 (lifecycle), 파일 시스템 브릿지
protocol.rs	550	모든 클라이언트/서버 메시지 유형 (serde JSON)
shell_hook.rs	530	크로스 플랫폼 셸 통합 (bash/zsh/fish/PowerShell)
autostart.rs	560	systemd / launchd / 작업 스케줄러 (Task Scheduler) 등록
pty_wrapper.rs	490	PTY 할당, I/O 스트리밍, 시그널 (signal) 처리
detection.rs	390	AI CLI 핑거프린팅 (fingerprinting) 및 대기 상태 (wait-state) 파싱
setup.rs	570	대화형 마법사, QR 생성, 네트워크 감지
main.rs	450	CLI 인자 파싱 (argument parsing) 및 명령 디스패치 (command dispatch)

모바일 앱은 별도의 리포지토리(repository)에 있습니다:

cd mobile
npm install
npx expo start # 개발 서버 (iOS 시뮬레이터를 실행하려면 'i'를 누르세요)
...

핵심 기술: Expo Router (내비게이션), xterm.js 5.3 (WebView 내 터미널 렌더링), expo-secure-store (자격 증명 저장), RevenueCat (구독).

MobileCLI/
├── cli/ # Rust 데몬 (daemon) + CLI 래퍼 (wrapper)
│ └── src/
...

모바일 앱에서 연결할 수 없는 경우

동일한 네트워크인가요? 휴대폰과 컴퓨터가 동일한 WiFi/LAN에 연결되어 있거나, 둘 다 Tailscale에 연결되어 있어야 합니다.

데몬 (Daemon)이 실행 중인가요? mobilecli status를 실행하여 확인하세요. 실행 중이 아니라면 mobilecli daemon으로 시작할 수 있습니다.

방화벽 문제인가요? 포트 9847 (또는 ~/.mobilecli/daemon.port에 명시된 포트)이 인바운드 TCP를 허용하는지 확인하세요.

재페어링 (Re-pair): mobilecli pair를 실행하여 새로운 QR 코드를 표시하고 다시 스캔하세요.

로그 확인: ~/.mobilecli/daemon.log에서 연결 시도 및 연결 오류를 확인할 수 있습니다.

푸시 알림이 오지 않는 경우

• iOS 설정에서 MobileCLI의 알림이 활성화되어 있는지 확인하세요.
• 푸시 토큰은 WebSocket auth-v2 핸드셰이크 (handshake)가 완료된 후 자동으로 등록됩니다. Config 탭에 "connected" 상태가 표시되는지 확인하세요.
• 알림을 위해서는 데몬이 실행 중이어야 합니다. 컴퓨터를 재부팅한 경우 데몬이 다시 실행되었는지 확인하세요 (mobilecli autostart install을 사용하면 이 작업이 자동으로 처리됩니다).

터미널 디스플레이 문제

• MobileCLI는 ANSI 256색을 완벽하게 지원하는 xterm.js를 사용합니다. CLI에서 TERM=xterm-256color가 설정되어 있는지 확인하세요 (이는 기본값입니다).
• 터미널은 휴대폰 화면에 맞춰 자동으로 크기가 조정됩니다. TUI 애플리케이션 (htop 또는 vim 등)은 자동으로 이에 적응해야 합니다.
• 데스크톱 터미널의 기하학적 구조 (geometry)는 기본적으로 유지됩니다. 데스크톱 창 크기 조절을 명시적으로 미러링(mirror)하고 싶다면 MOBILECLI_DESKTOP_RESIZE_POLICY=mirror와 함께 실행하세요.
• Linux의 경우, Konsole과 같은 데스크톱 터미널이 정상적인 드래그 선택 클립보드 동작을 유지할 수 있도록 tmux 마우스 모드가 기본적으로 비활성화되어 있습니다. tmux 마우스 기능을 다시 활성화하려면 MOBILECLI_TMUX_MOUSE=on mobilecli를 사용하세요.