KanVibe Mobile: 휴대폰에서 같은 작업 이어가기
KanVibe Mobile은 KanVibe Desktop에 연결하는 iOS·Android 앱입니다. 작업 상태를 확인하고, 같은 태스크의 터미널에 입력하고, 저장된 PC를 전환할 수 있습니다. 저장소와 실행 중인 프로세스는 연결한 PC에 그대로 남습니다.
Mobile 터미널 호환성: herdr, tmux, zellij, terminal 세션을 모두 지원합니다. Herdr 세션은 이 기능이 포함된 Desktop 빌드가 필요하며, 원본 격자를 유지한 채 스크롤로 읽습니다.


Mobile을 빌드하고 Desktop을 준비하세요
Mobile은 현재 소스에서 빌드해 사용합니다. iOS 또는 Android 개발 환경을 준비하고 FVM으로 mobile/.fvmrc에 고정된 Flutter 버전을 설치하세요. KanVibe 저장소를 받은 뒤 실행합니다.
cd mobile
fvm install
fvm flutter pub get
fvm flutter run
기기 선택 안내가 나오면 연결한 휴대폰이나 시뮬레이터를 고릅니다. iOS 빌드에는 macOS와 현재 모바일 의존성이 요구하는 Xcode 버전이 필요합니다. 최신 도구 버전, 릴리스 서명, 푸시 설정은 Mobile 개발자 README를 확인하세요.
사용할 PC에 Desktop을 설치하고 실행해 둡니다. Mobile 연결을 지원하는 Desktop 빌드가 필요하며, 터미널 탭 추가·화면 크기 조절·알림함도 각각 해당 기능이 포함된 Desktop 빌드에서 동작합니다.
휴대폰에서 저장한 PC 주소와 포트에 접근할 수 있어야 합니다. 같은 로컬 네트워크를 쓰거나, 외부에서는 Tailscale 같은 사설 네트워크를 사용하세요. 인터넷으로 푸시를 받았다고 PC 터미널에 자동으로 연결되는 것은 아닙니다.
연결 코드를 한 번 입력하세요
- Desktop에서 설정 → 모바일 연결 → 연결 코드 만들기를 누릅니다.
- Mobile에서 데스크탑 주소, 포트, 6자리 연결 코드를 입력합니다. 포트는 패키지된 Desktop 앱이면 9746, 개발 빌드면 19746입니다. 이 포트는 암호화되며, Mobile은 연결할 때 Desktop 인증서 지문을 고정합니다. **PC 이름 (선택)**은 비워 둬도 됩니다.
- 연결을 누르면 보드가 열립니다. 기기의 보안 저장소에 연결 정보를 보관하므로 다음부터 코드를 다시 입력할 필요가 없습니다.
코드는 5분 뒤 만료되고 한 번만 사용할 수 있습니다. 만료되었거나 이미 사용했다면 새 코드를 만드세요. 실제 휴대폰에서는 localhost 대신 PC의 네트워크 주소를 입력합니다. 주소는 macOS 시스템 설정 → 네트워크에서 보거나, PC에서 ipconfig getifaddr en0을 실행해 확인합니다.
확인이 필요한 태스크를 찾으세요
휴대폰에서는 상태별 목록을 세로로, 태블릿에서는 칸반 열을 가로로 보여줍니다. 같은 Desktop 태스크와 프로젝트 색상을 사용합니다.
- 프로젝트 필터에서 프로젝트를 검색하고 여러 개 선택합니다. 본 프로젝트를 고르면 같은 호스트의 연결된 worktree 태스크도 함께 표시합니다.
- 태스크를 누르면 상세 화면과 터미널이 열립니다. 상세 화면의 상태 버튼으로 작업 상태를 바꿀 수 있습니다.
- 새 태스크에서 프로젝트와 베이스 브랜치를 골라 후속 작업을 만듭니다. 열어 둔 태스크의 상단에서도 새 태스크를 만들 수 있습니다.
- DONE으로 옮겨도 브랜치, worktree, 터미널 세션은 유지됩니다. 자원을 정리하는 동작은 별도의 태스크 삭제입니다.

실행 중인 터미널에 입력하세요
터미널 탭 하나가 pane 하나를 보여줍니다. 탭을 골라 출력을 읽고, 터미널을 눌러 키보드를 연 뒤 실제 세션에 입력하세요. 탭 바 오른쪽의 **+**를 누르면 현재 태스크에 셸 탭을 추가합니다.
손가락으로 스크롤해 이전 출력을 읽을 수 있습니다. 마우스 입력을 받는 전체 화면 프로그램에서는 상하 스와이프가 휠 입력으로 전달됩니다(Herdr 제외, Herdr는 항상 화면만 스크롤합니다). 지원하는 tmux와 일반 terminal 세션은 휴대폰 화면, 회전, 키보드 크기에 맞춰 터미널 크기를 조절합니다. 이때 PC의 같은 터미널 크기도 바뀌며, 탭을 벗어나거나 앱을 배경으로 보내면 PC에 맞는 크기로 돌아갑니다. Herdr, Zellij와 이전 Desktop 빌드에서는 원본 격자를 유지하고 가로·세로 스크롤을 제공합니다.
오래 실행할 작업에는 Herdr, tmux, zellij 같은 세션을 사용하세요. 일반 terminal 셸은 Desktop이 직접 실행하므로 Desktop 앱을 종료하면 유지되지 않습니다.
저장한 PC 사이를 전환하세요
보드 상단의 PC 이름을 눌러 연결된 PC 목록을 엽니다. PC 추가로 다른 컴퓨터를 연결하고 알아보기 쉬운 이름을 붙이세요. 저장된 PC를 누르면 코드를 다시 입력하지 않고 해당 보드로 전환합니다.
프로젝트 필터는 앱 실행 중 PC마다 따로 유지합니다. PC가 꺼져 있으면 목록으로 돌아가 다른 PC를 고르세요. 보드는 선택한 PC의 태스크를 보여주며, 여러 PC의 태스크를 하나로 합치지는 않습니다.

연결된 PC에서 PC를 삭제하면 저장된 연결을 제거하고 해당 PC에서도 이 기기의 연결을 해제합니다. 다른 PC의 연결은 유지합니다. PC에 닿지 못했다면 나중에 해당 Desktop 설정에서도 이 기기를 지워 주세요. 현재 PC를 삭제한 뒤에는 다음 PC를 직접 고릅니다.
알림함에서 작업으로 이동하세요
보드의 알림 버튼은 선택한 PC의 Desktop 알림함을 엽니다. 배지는 읽지 않은 알림 수입니다. 전체 / 안 읽음 필터, 개별 읽음 처리, 모두 읽음을 지원하며, Desktop과 Mobile이 최근 100개 알림과 읽음 상태를 공유합니다.
태스크 알림을 누르면 읽음 처리하고 최신 태스크를 엽니다. 이미 삭제된 태스크라면 안내를 표시합니다. 태스크가 없는 알림도 내용은 확인할 수 있으며, Desktop 전용 후속 작업은 Desktop에서 진행합니다.

전경 갱신과 백그라운드 푸시는 조건이 다릅니다
앱을 사용하는 동안에는 저장된 PC에 인증된 WebSocket으로 연결합니다. Hook 이벤트로 태스크 상태를 갱신하고 시스템 알림을 표시할 수 있습니다. 다른 PC에서 온 알림을 누르면 그 PC와 태스크로 이동할 수 있습니다.
앱을 배경으로 보내거나 화면을 잠그면 이벤트·터미널 소켓을 닫습니다. 백그라운드 알림에는 모바일 Firebase/APNs 설정과 Desktop의 푸시 중계 설정이 모두 필요하며, OS 알림 권한도 허용해야 합니다. 해당 설정이 없는 소스 빌드에서도 앱과 전경 WebSocket 갱신은 사용할 수 있습니다. 필요하다면 푸시 설정 안내를 따르세요.
새 hook 이벤트를 보내려면 PC가 실행 중이어야 합니다. 푸시를 누른 뒤 태스크 조회와 터미널 입력은 저장한 PC 주소로 직접 연결합니다. Android에서 앱을 강제 종료했다면 다시 열기 전까지 푸시를 받지 못합니다. 백그라운드 실행과 알림 전달은 OS의 제약을 받으며, 백그라운드에서 터미널 연결을 계속 유지하는 방식은 아닙니다.
연결이 되지 않을 때 확인하세요
| 증상 | 확인할 내용 |
|---|---|
| ”코드가 맞지 않거나 만료되었습니다” | 오타를 확인한 뒤, 5분 만료·1회 사용 조건에 맞게 새 코드를 만듭니다. |
| ”이미 등록된 PC입니다” | 다시 연결하지 말고 연결된 PC 목록에서 그 PC를 고릅니다. |
| PC에 연결하지 못함 | Desktop 실행 여부, 주소·포트, 로컬 네트워크나 Tailscale 경로, 방화벽을 확인합니다. |
| 알림은 오지만 태스크가 열리지 않음 | 현재 휴대폰 네트워크에서 저장된 PC 주소에 접근할 수 있어야 합니다. |
| ”이 태스크에는 터미널 세션이 없습니다” 또는 터미널을 쓸 수 없음 | Mobile 지원 Desktop 빌드인지 확인하세요. Herdr가 설치되지 않았다는 안내가 나오면 Desktop에서 Herdr 세션을 연결해 설치하세요. 프로젝트나 브랜치가 없는 태스크는 누락된 세션을 자동 복구할 수 없습니다. |
| 백그라운드 알림이 오지 않음 | Firebase/APNs, Desktop 중계 설정, OS 권한, Android 강제 종료 여부를 확인합니다. |
| 알림의 태스크를 찾을 수 없음 | 태스크가 삭제되었거나 PC 연결이 해제되었을 수 있습니다. 보드나 PC 목록에서 현재 작업을 고릅니다. |