데스크탑 앱

macOS, Windows, Linux용 sophonz ADE — 이 컴퓨터의 tmux 세션과 계정의 다른 머신을 한 창에서.

데스크톱 앱 Sophonz는 st를 품은 터미널입니다. 열면 바로 이 컴퓨터의 tmux 세션이 나오고 계정에 올린 다른 머신의 세션도 같은 창에서 엽니다.

데스크탑 브라우저와 달리 앱은 st를 직접 다룹니다. 이 컴퓨터에서 st가 실행 중이 아니면 앱이 띄웁니다. 머신 목록과 문서, 지표는 사이드바에 있습니다. 앱을 닫아도 에이전트와 tmux 세션은 그대로 남습니다.

받는 법

다운로드에서 이 컴퓨터에 맞는 파일을 받습니다. macOS는 DMG, Windows는 설치 프로그램, Linux는 압축 파일이고 늘 최신 버전입니다. 버전마다 바뀐 것은 같은 페이지의 변경 기록에 있습니다.

버전별 파일과 SHA256SUMS 는 https://dl.sophonz.io/apps/desktop/<버전>/ 에 있습니다. 받은 파일은 이렇게 확인합니다.

sha256sum -c SHA256SUMS --ignore-missing

st를 따로 설치하지 않아도 됩니다. 앱 안에 st가 들어 있습니다. 이미 설치한 st가 PATH에 있으면 그쪽을 먼저 씁니다.

macOS

DMG를 열면 Sophonz 앱과 응용 프로그램 폴더가 나란히 보입니다. 앱을 폴더로 끌어 넣으면 설치됩니다. DMG와 앱 모두 Apple Developer ID로 서명하고 공증까지 받아서 Gatekeeper 경고 없이 열립니다.

Homebrew로도 설치할 수 있습니다(Apple Silicon 전용):

brew trust --tap sophonz-labs/tap
brew install --cask sophonz-labs/tap/sophonz

Homebrew는 자기 것이 아닌 tap을 불러오기 전에 확인을 받으므로 brew trust를 먼저 실행합니다. 앱이 스스로 업데이트하므로 brew upgrade는 건드리지 않습니다.

Intel Mac용 빌드는 없습니다. 안에 든 st에 Intel용 빌드가 없기 때문입니다.

Windows

설치 프로그램(-windows-x64-setup.exe)을 실행합니다. 사용자 단위로 설치되어 관리자 권한이 필요 없고 %LOCALAPPDATA%\Programs\Sophonz 에 들어가 시작 메뉴와 앱 제거 목록에 나옵니다.

아무것도 설치할 수 없는 PC라면 포터블(-windows-x64.zip)을 받습니다. 아무 폴더에 풀고 sophonz-terminal.exe 를 실행하면 됩니다. 같은 폴더의 st.exe 는 그대로 둡니다. 포터블도 스스로 업데이트합니다.

설치 프로그램과 그 안의 두 실행 파일 모두 Azure Artifact Signing으로 서명돼 있고 서명자는 INOBS Inc.입니다. 파일 속성의 디지털 서명 탭에서 확인할 수 있습니다.

Linux

tar.gz를 풀면 실행 파일과 .desktop 파일, 아이콘이 나옵니다. 실행 파일을 PATH 에 두고 메뉴에 띄우려면 .desktop 파일을 ~/.local/share/applications 에 넣습니다.

Vulkan이 없는 가상 머신이나 원격 데스크톱에서는 앱이 뜨지 않습니다. Alpine(musl)에서는 안에 든 tmux가 실행되지 않으니 배포판의 tmux를 설치합니다.

업데이트

앱이 스스로 새 버전을 확인하고 업데이트합니다. 새 버전이 있으면 타이틀 바 오른쪽에 Update to vX.Y.Z 가 뜹니다. 누르면 받아서 체크섬과 서명(macOS는 Developer ID, Windows는 서명자 INOBS Inc.)을 확인한 뒤 바꿔 넣고 다시 엽니다. 체크섬이나 서명이 맞지 않으면 바꾸지 않고 이유를 알려 줍니다. 지금 버전이 더 이상 쓸 수 없을 만큼 오래됐으면 같은 자리에 빨간 Update required 가 뜹니다.

자동 확인은 설정에서 끌 수 있습니다. 바로 확인하려면 설정의 Check now, 계정 메뉴의 Check for updates, macOS 메뉴 막대의 Sophonz → Check for Updates… 중 하나를 누릅니다. 앱 안에 든 st도 함께 바뀝니다. 이미 실행 중인 st 에이전트는 건드리지 않고 앱이 다음에 띄울 때부터 새 st를 씁니다.

앱 안의 st에는 st upgrade 를 하지 않습니다. 서명된 앱 묶음을 고치게 되기 때문입니다. st를 따로 최신으로 쓰려면 설치대로 PATH 에 설치합니다.

업데이트한 뒤 처음 열면 What's New 가 한 번 뜹니다. 마지막으로 쓰던 버전 이후의 릴리스가 최신순으로 나옵니다. macOS에서는 Sophonz → What's New 나 Help → What's New 로 언제든 열 수 있습니다.

화면

• 타이틀 바. 맨 위 줄입니다. 사이드바 버튼, 로고, 단축키 버튼, 탭(터미널, 문서, 지표, 에이전트 그래프, 설정), UI 모드 전환, 업데이트 알림이 있습니다. 끌면 창이 움직이고 두 번 누르면 최대화와 원래 크기를 오갑니다.
• 이 컴퓨터. 사이드바는 머리글 없이 이 컴퓨터의 머신 줄에서 시작합니다. 그 아래에 이 컴퓨터의 tmux 세션이 있고, 세션마다 그 세션의 tmux 창이 한 단 들여 나옵니다. 앱 0.1.33부터는 다른 세션의 줄을 누르면 그 세션으로 가고(열려 있지 않으면 엽니다), 지금 앞에 있는 세션을 누르면 창 목록이 접히거나 펼쳐집니다. 작은 ▾/▸는 어느 줄이든 접고 폅니다. 세션 줄을 두 번 누르면 그 세션이 열립니다. 창 줄을 누르면 그 세션이 열리면서 그 창이 보입니다. 세션 이름 아래 한 줄에는 그 세션에서 벌어지는 일이 나옵니다. 묻거나 일하는 에이전트가 몇인지, 서브에이전트가 몇 개 실행 중인지, 가장 바쁜 에이전트가 무엇을 하는지가 나오고, 세션을 접어도 보입니다. 머신 줄의 ▦ QR 은 이 머신을 폰에서 여는 QR이고, st url 과 같은 링크입니다. 에이전트의 서브에이전트와 워커는 그 창 줄 아래에 나무로 나옵니다(에이전트 데려오기).
• Other machines. 로그인한 계정에 올라간 다른 머신입니다. 로그인과 링크와 같은 길로, 컨트롤 플레인을 거쳐 엽니다. 머신 줄에 포인터를 올리면 ▦ 가 나와 그 머신의 QR을 보여 줍니다. 이 QR은 머신의 계정 링크(link.sophonz.io/m/<slug>)라서 키가 들어 있지 않고, 같은 계정에 로그인한 폰에서 열립니다.
• Documents. 머신마다 그 머신의 문서를 볼트처럼 보여 줍니다. 폴더는 트리로 펼쳐지고, [[링크]], 임베드, 콜아웃, 속성이 그대로 보입니다. 칸을 나눌 수 있고, 칸마다 Reading, Live preview, Source 중 하나로 봅니다. 고친 내용은 저절로 그 머신에 저장됩니다. 폴더와 링크를 쓰려면 그 머신에 st 0.3.86 이상이 있어야 합니다. 앱 0.2.0부터는 그 머신의 st(0.4.0 이상)에 볼트가 있으면 이 줄이 Doc으로 바뀌고, 모든 세션의 문서를 담은 그 볼트를 탭 하나로 엽니다.
• Metrics. 머신마다 지난 10분의 메모리, 스왑, CPU입니다.
• 계정. 사이드바 맨 아래의 아바타입니다. 로그인할 때 쓴 Google이나 GitHub 사진이 뜨고 없으면 이름 첫 글자가 뜹니다. 누르면 Settings, Check for updates, Sign out 이 있습니다.

머신마다 이름 앞에 머신 아이콘이 붙습니다. 온라인이면 보통 색이고 오프라인이거나 아직 연결 전이면 흐립니다. 메모리, 스왑, AI 사용량은 사이드바가 아니라 창 맨 아래 상태 바에 있습니다.

지금 보고 있는 칸의 세션은 왼쪽 가장자리에 표시가 붙고 이름이 굵게 나옵니다. 앞에 있는 줄(그 세션의 창, 세션을 접었으면 세션 줄)은 회색 바탕에 밝은 테두리가 둘립니다. 앱 0.1.33부터는 이 앱에서 앞에 띄운 창만 강조되고, 다른 클라이언트(폰이나 다른 attach)가 앞에 띄운 창은 강조되지 않습니다. 칸 안을 누르면 그 칸이 앞에 있는 칸이 됩니다. 칸의 채팅을 눌러도 마찬가지입니다. 창의 폴더가 GitHub 저장소 안에 있으면 사이드바와 탭에서 창 이름 앞에 저장소 소유자(조직이든 개인이든)의 아바타가 붙습니다(st 0.3.75 이상). 이 컴퓨터의 에이전트가 질문이나 권한 요청에서 멈추면 그 창 줄과 탭, 세션 줄에 ? 가 붙습니다. 포인터를 올리면 에이전트가 무엇을 묻는지 보입니다.

컨트롤 플레인(link.sophonz.io)이 응답하지 않으면 타이틀 바와 Other machines 위에 노란 Offline 이 뜹니다. 이 컴퓨터 줄에는 · offline 이 붙고 다른 머신은 상태 없이 흐려집니다. 오프라인인 동안에도 계속 다시 확인하고, 이 컴퓨터의 세션은 그대로 씁니다.

머신 줄을 누르면 그 머신을 접고 폅니다. 머신 줄에 포인터를 올리면 오른쪽 끝에 ✎ 가 보이고 누르면 계정에 올라간 머신 이름을 바꿉니다. 폰 앱에서 바꾼 이름과 같은 이름입니다. Use hostname 을 누르면 이름을 지우고 호스트 이름으로 돌아갑니다. 이름 바꾸기는 로그인했을 때만 됩니다.

머신의 st가 최신 버전보다 오래되면 그 머신 줄에 받을 버전이 ↑ v0.3.87 처럼 붙습니다. 이 컴퓨터든 계정의 다른 머신이든 마찬가지입니다. 이것을 누르거나 줄을 오른쪽 클릭해 Update st to … 를 고르면, 앱이 먼저 확인을 받고 새 버전에서 달라지는 점을 보여 줍니다. 업데이트하는 동안에는 줄에 진행 단계(확인, 내려받기, 검증, 전환)가 나옵니다. 링크는 바뀌지 않고 세션도 계속 실행됩니다. 새 버전이 시작되지 않으면 이전 버전으로 돌아갑니다. 끝나면 잠깐 Updated to v… 가 보입니다. 여기서 업데이트할 수 없는 머신은 그 이유와 함께 그 머신에서 실행할 명령을 알려 줍니다. Homebrew로 설치했다면 brew upgrade st 다음에 st restart, 로그인하지 않은 머신이거나 이 방법으로 올릴 수 없을 만큼 오래된 st라면 st upgrade 입니다. 폰 앱에서 하는 업데이트와 같은 방식입니다(갱신).

사이드바는 ⌘B(Windows와 Linux는 Ctrl+Shift+B)나 타이틀 바 왼쪽 버튼으로 접고 펴며 오른쪽 가장자리를 끌어 너비를 바꿉니다. 접은 상태와 너비, 접어 둔 머신은 다음에도 그대로입니다.

macOS에서는 메뉴 막대도 씁니다. iTerm2처럼 Sophonz(정보, 업데이트 확인, What's New, 설정, 단축키, 종료), File(Open, Save, Archive Project…, 0.1.43부터), Shell(새 세션과 새 창, 분할, 옆에 열기, 닫기, 닫은 탭 다시 열기, 창 이름 바꾸기, 이 머신의 QR), Edit, View(사이드바, 모드, 글자 크기, 문서, 지표, 에이전트 그래프, 터미널과 채팅), Window(최소화, 창 모두 합치기, 탭과 pane 고르기, pane 크기, 세션과 칸 이동), Help(이 문서, What's New, 단축키)로 나뉩니다. 메뉴 옆에 보이는 키가 실제 단축키입니다. Windows와 Linux에는 메뉴 막대가 없고 같은 동작을 단축키와 화면의 버튼으로 씁니다.

상태 바

창 맨 아래의 얇은 바에는 지금 보고 있는 칸의 머신이 나옵니다. 열린 칸이 없으면 이 컴퓨터가 나옵니다.

• 왼쪽은 AI 사용량. 그 머신에서 쓰는 코딩 에이전트(Claude, Codex, Gemini)의 플랜 한도입니다. 에이전트마다 칩이 하나씩 있고, 칩에는 가장 많이 찬 한도를 그린 막대와 한도 구간(5h, week 등)마다 쓴 비율이 나옵니다. st가 몇 분마다 각 서비스에서 읽어 둔 값입니다. 이 머신은 1분마다 다시 읽고, 다른 머신은 계정의 머신 목록에 실린 값을 씁니다. st의 기준(보통 80%, 95%)을 넘으면 노랑, 빨강으로 바뀝니다. 칩에 포인터를 올리면 플랜과 한도마다 다시 차는 시각이 보입니다. 로그아웃했거나 읽지 못한 에이전트는 빠집니다.
• 오른쪽은 메모리와 스왑. 지금 사용률과, 지난 10분 동안의 스왑 추이를 그린 작은 선이 나옵니다. 점선은 st가 경고하는 선이고 경고나 위험 상태면 글자와 선이 노랑, 빨강으로 바뀝니다. 누르면 그 머신의 지표 탭이 열립니다.

왼쪽을 누르면 온라인인 모든 머신의 사용량과 메모리를 한꺼번에 보여 주는 팝오버가 열립니다. 거기서 머신 이름을 누르면 그 머신의 지표 탭이 열립니다.

탭

타이틀 바의 탭 하나가 터미널 하나(또는 나란히 놓은 여러 칸)입니다. 탭은 끌어서 다른 탭 위에 놓으면 그 자리로 옮겨지고, ⇧⌘←, ⇧⌘→(Windows와 Linux는 Ctrl+Shift+PgUp, Ctrl+Shift+PgDn)로 한 칸씩 옮길 수도 있습니다.

앞에 있는 탭을 닫으면 그 전에 보던 탭으로 돌아갑니다. 닫은 탭은 ⇧⌘T(Windows와 Linux는 Ctrl+Alt+Shift+T)로 다시 엽니다. 앱을 켠 동안 닫은 탭을 20개까지 기억하고 칸 배치째 엽니다. 그사이 끝난 세션은 빼고, 전부 끝났으면 그렇다고 알려 줍니다.

탭 줄은 스크롤되지 않습니다. 탭이 다 들어가지 않으면 들어가는 탭만 보이고 나머지는 줄 끝의 N more ⌄ 버튼 뒤에 있습니다. 버튼을 누르면 전체 탭 목록이 나오고, 그중 하나가 알림을 원하면 버튼에 점이 붙습니다. 앞에 있는 탭은 늘 보이며, 들어갈 수 있는 마지막 탭 자리에 대신 나옵니다.

탭을 창 밖으로 끌어 놓으면 그 탭만 새 창으로 엽니다. 앱의 다른 창 위에 놓으면 그 창으로 들어가고, Window → Merge All Windows 는 모든 창의 탭을 한 창에 모읍니다. macOS에서 탭을 끌면 창이 아니라 탭이 움직이고, 창은 타이틀 바의 빈 곳을 끌어 옮깁니다.

⌘W(Windows와 Linux는 Ctrl+Shift+W)는 앱 창을 닫습니다. 창이 하나뿐이면 앱을 끄지 않고 앞에 있는 탭을 닫습니다. 어느 쪽이든 세션은 계속 실행됩니다. pane을 닫는 키는 ⌥⌘W(Windows와 Linux는 Ctrl+Alt+W)입니다.

뒤에 있는 탭의 터미널이 벨을 울리면 그 탭 이름 옆에 점이 붙습니다. 그 탭을 열면 사라집니다.

UI 모드에서 칸 위의 tmux 창 탭을 두 번 누르면 그 창의 이름을 바꿉니다. 사이드바에서는 창 줄을 두 번 누르거나, 포인터를 올리면 나오는 ✎ 를 누르거나, 줄을 오른쪽 클릭해 Rename window… 를 고릅니다. 아직 칸에 열지 않은 창도 이렇게 바꿀 수 있습니다. 메뉴 막대의 Shell → Rename Window… 는 지금 창의 이름을 바꾸고 클래식 모드에서도 됩니다. tmux의 창 이름을 바꾸는 것이라 폰을 비롯해 그 세션을 보는 모든 화면에 새 이름이 보입니다.

다시 열 때

앱을 다시 열면 닫을 때의 탭이 그대로 돌아옵니다. 탭 순서, 앞에 있던 탭, 탭마다 나란히 놓은 칸과 그 크기까지입니다. 그사이 끝난 세션의 칸은 빠지고 남은 칸이 자리를 나눠 갖습니다. 응답하지 않는 머신(꺼져 있거나 오프라인)의 칸은 남겨 두고 다시 연결되기를 기다립니다.

창도 닫을 때의 자리에서 열립니다. 같은 화면, 같은 위치와 크기, 최대화했으면 최대화한 채로입니다. 업데이트 뒤에 새 버전이 열릴 때도 같습니다. 그 화면이 없어졌으면 주 화면 가운데에 기본 크기로 엽니다. 전체 화면이었으면 전체 화면 전의 창 자리로 엽니다.

나란히 보기

한 탭 안에 터미널을 여러 칸으로 나란히 놓을 수 있습니다. ⌘\ 은 오른쪽, ⌥⌘\ 은 아래에 같은 세션을 한 칸 더 엽니다. 칸마다 tmux 뷰가 따로라서 같은 세션의 두 칸이 서로 다른 창을 보여 줍니다. 사이드바에서 세션을 ⌥-클릭하면 다른 세션이나 다른 머신의 세션을 지금 칸 옆에 엽니다.

칸 사이 선을 끌어 크기를 바꾸고 포인터가 들어간 칸이 포커스를 받습니다. ⌃⌘=(Windows와 Linux는 Ctrl+Alt+=)는 지금 탭의 칸을 모두 같은 크기로 돌립니다. 키보드로 칸이나 pane을 옮겨 가면 간 곳의 테두리가 잠깐 밝아집니다. 설정의 Dim inactive views 를 켜면 포커스가 없는 칸이 흐려집니다. 칸을 닫으면 연결만 끊고 세션은 그대로 둡니다.

Windows에서는 psmux에 세션 그룹이 없어 같은 세션의 두 칸이 같은 창을 보여 줍니다.

링크와 파일

터미널 안의 링크는 ⌘-클릭(Windows와 Linux는 Ctrl-클릭)하면 바로 브라우저에서 열립니다. 키를 누르고 있으면 포인터 아래 링크에 밑줄이 생기고 왼쪽 아래에 실제로 열릴 주소가 보입니다. 링크를 그냥 누르면 작은 메뉴가 열리고 Open link 와 Copy link 중에서 고릅니다.

프로그램이 표시한 링크(OSC 8)를 먼저 찾고, 없으면 글자로 적힌 https://, http://, file:// 주소를 찾습니다. 터미널이 줄을 넘긴 주소는 한 링크로 잇고, pane 경계에서 끊습니다. Claude Code처럼 상자 안에서 프로그램이 직접 줄을 바꾼 주소도 한 링크로 잇습니다.

열리는 것은 웹(http, https)과 메일(mailto), 그리고 이 머신의 터미널에서만 file:// 입니다. 그 밖의 주소는 열지 않고 not opened 와 함께 주소만 보여 줍니다.

글로 적힌 Markdown 파일 경로(docs/plan.md, ~/notes/a.md)도 링크입니다. ⌘-클릭(Linux는 Ctrl-클릭)하면 문서로 열립니다. 경로는 터미널이 실행되는 곳의 파일을 가리키므로 이 머신의 터미널에서만 되고, Windows에서는 안 됩니다.

Finder나 탐색기에서 파일을 이 머신의 터미널로 끌어다 놓으면 따옴표로 감싼 경로가 입력됩니다. 여러 개면 공백으로 나뉩니다.

Compose

칸 머리의 ✎ Compose 나 ⇧⌘E(Windows와 Linux는 Ctrl+Shift+K)는 메시지를 써서 터미널에 한 번에 보내는 칸을 엽니다. 폰 앱과 같습니다. Upload to machine… 은 파일을 머신에 올리고 그 경로를 글에 넣고, Insert from Documents… 는 머신의 st 문서 하나를 넣고, Insert text file… 은 이 컴퓨터의 텍스트 파일을 넣습니다. 스크린샷 같은 이미지를 복사해 두었다면 칸에 ⌘V(Windows와 Linux는 Ctrl+V)로 바로 붙여 넣을 수 있습니다. 이미지가 머신에 올라가고 그 경로가 글에 들어가므로, 에이전트에게 화면을 그대로 보여 줄 수 있습니다. Send ⌘↩(Windows와 Linux는 Send Ctrl+Enter)로 보내고, Type only 는 Enter 없이 쳐 두기만 합니다. 초안은 보낼 때까지 머신, 세션, 창마다 남습니다.

채팅으로 보기

Claude Code나 Codex가 실행되는 창은 칸 위에 Terminal | Chat 전환이 생깁니다. Chat 을 누르거나 ⇧⌘J(Windows와 Linux는 Ctrl+Alt+Shift+J), View → Terminal / Chat 을 쓰면 그 에이전트의 대화를 폰 앱처럼 말풍선으로 봅니다.

도구 호출은 결과와 diff를 품은 채 접혀 있고 누르면 펼쳐집니다. 에이전트가 고르라고 묻는 질문은 카드로 나옵니다. 아래 입력 칸에 쓰고 Enter 를 누르면 st를 거쳐 에이전트에게 그대로 입력됩니다. 줄을 바꾸려면 Shift+Enter 입니다. 에이전트가 일하는 동안에는 Stop 으로 멈춥니다. 터미널은 채팅 아래에서 계속 연결돼 있고, 터미널에서만 답할 수 있는 질문이면 터미널로 돌아가라고 알려 줍니다.

에이전트 그래프

세션 안에서 에이전트가 다른 에이전트에게 일을 맡기면 그 관계를 그래프로 봅니다. Claude 에이전트 팀(tmux 모드)의 리더와 팀원, 에이전트가 띄운 서브에이전트가 위에서 아래로 이어지고, 일하는 동안 계속 바뀝니다. 카드마다 이름과 하는 일, 상태(working, needs input, done 등), 경과 시간이 나옵니다. 입력을 기다리는 에이전트는 노란 테두리로 표시됩니다.

⇧⌘G(Windows와 Linux는 Ctrl+Alt+Shift+G)나 View → Agent Graph 는 지금 칸의 그래프를 탭으로 엽니다. 이 머신의 st가 그래프를 지원하면 칸 위에 ◇ Agents 표시가 늘 있고 에이전트가 일을 맡기기 전까지는 흐립니다. 위임이 생기면 ◇ Agents N 으로 밝아지고 입력을 기다리는 에이전트가 있으면 노랗게 바뀝니다.

그래프 머리의 This session 은 지금 tmux 창의 에이전트를, All sessions 는 그 머신의 모든 세션을 보여 줍니다. All sessions 는 사이드바의 머신마다, View 메뉴에도 있습니다. 일하는 에이전트는 굵은 강조색 테두리와 숨 쉬듯 깜박이는 점으로 표시되고 머리에 몇 개가 일하는지 나옵니다.

열면 모든 카드가 한 화면에 들어오게 맞춥니다. 스크롤이나 빈 곳 끌기로 화면을 옮기고 Ctrl+스크롤이나 ⌃=, ⌃-, ⌃0(Windows와 Linux는 Ctrl+=, Ctrl+-, Ctrl+0), 그래프의 − % + ⤢ 버튼으로 확대합니다. 카드는 끌어서 옮기면 세션마다 그 자리에 남고, Reset layout 으로 처음 배치로 돌아갑니다.

pane이 있는 카드를 누르면 그 세션의 그 창과 pane으로 갑니다. ⌥를 누른 채 누르면 지금 칸 옆에 엽니다. 서브에이전트처럼 pane이 없는 카드를 누르면 오른쪽에 설명과 상태, 시작 시각, 그리고 그 서브에이전트의 대화가 실시간으로 나옵니다. 읽기만 됩니다. 거기서 부모 에이전트의 터미널로 바로 갈 수 있습니다.

오케스트레이션의 워커도 그래프에 나옵니다. 코디네이터에서 워커로 굵은 초록 선이 이어지고, 끝난 워커의 카드에는 요약이 나옵니다. 에이전트 카드를 끌어 다른 에이전트 카드 위에 놓으면 그 에이전트의 워커가 되고 나누던 대화는 그대로 이어집니다. 포인터 아래 카드가 강조되고 위에 Make <워커> a worker of <코디네이터> 가 뜹니다. 놓을 수 없는 카드는 빨갛게 바뀌고 이유가 나옵니다(에이전트 데려오기과 같은 경우입니다). 워커 카드에 포인터를 올리면 보이는 Release 로 놓아 줍니다. 다른 세션에 있는 상대도 그 세션 이름과 함께 카드로 나오고, 지금 창의 에이전트 수에는 들어가지 않습니다. 그 머신의 st가 그래프를 지원하지 않으면 st upgrade 를 하라고 알려 줍니다.

다른 머신과 나눈 일도 같은 그래프에 들어갑니다. 이 머신 코디네이터의 다른 머신 워커는 그 아래 초록 선으로 붙고, 그 워커의 워커와 서브에이전트도 이어집니다. 이 머신 워커의 코디네이터가 다른 머신에 있으면 그 코디네이터 카드가 위에 붙습니다. 이런 카드는 이름 앞에 머신 아이콘과 머신 이름(CI Mac · 2-1-273)이 붙고, 상태와 질문 표시는 그 머신의 것을 그대로 보여 줍니다. 누르면 그 머신의 그 창이 열립니다. 다른 머신의 워커 카드도 Release 로 놓아 주고, 끌어서 이 머신 에이전트 카드에 놓으면 데려옵니다. 다른 머신의 카드 위에 놓아 데려오는 것은 그래프에서는 안 되고 사이드바에서 합니다. 꺼진 머신의 에이전트는 그래프에 들어가지 않습니다.

그래프 머리의 History를 누르면 옆에 실행의 기록이 최신순으로 열립니다. 핸드오프마다 누가 누구에게 언제 무엇을 넘겼는지, 워커마다의 결과, 트리의 변경이 나옵니다(0.1.39 이상). 카드를 고르면 그 에이전트의 일만 보입니다. 한 줄을 누르면 그 핸드오프 문서가 열리고, 문서가 없어졌거나 바뀌었으면 st가 보관한 사본이 열립니다. 실행을 파일 하나로 저장해 다시 열 수도 있습니다. 실행을 파일 하나로를 보세요(File → Open / Save / Archive Project…, 0.1.43 이상).

자기 worktree를 받아 시작한 워커(st 0.3.84 이상)에는 그래프에 Changes 가 생깁니다. 누르면 그 워커의 diff와 아직 커밋하지 않은 파일, 워커가 남긴 요약이 탭으로 열리고, Merge 를 누르면 그 브랜치가 코디네이터의 체크아웃에 병합됩니다. 같은 과제를 여러 워커에게 한꺼번에 줬다면 탭에 워커들이 나란히 놓여 비교할 수 있고, Use this one 으로 하나를 병합하면 나머지는 닫힙니다. 자세한 내용은 오케스트레이션에 있습니다.

터미널 위 Agents 카드

이 컴퓨터의 칸에서 창의 에이전트가 다른 에이전트에게 일을 맡기고 있거나 누군가의 워커면, 칸 모서리에 작은 Agents · N 카드가 뜹니다. 처음 자리는 오른쪽 위입니다. 코디네이터부터 워커, 서브에이전트, 팀원이 들여쓰기 나무로 나오고 줄마다 상태 점과 종류가 있습니다. 지금 칸이 보여 주는 에이전트는 강조색입니다.

• 줄을 누르면 그 에이전트로 갑니다. pane이 있는 에이전트면 그 창과 pane으로 가고, 칸이 채팅이면 그 에이전트의 채팅을 엽니다.
• 서브에이전트나 팀원을 누르면 칸이 그 대화로 바뀝니다. 읽기만 됩니다. 칸 위에 ← 부모 버튼과 SUBAGENT 표시가 붙고, ← 부모 를 누르면 부모 에이전트로 돌아갑니다.
• 다른 머신의 워커와 코디네이터도 같은 나무에 머신 아이콘과 <머신> · <이름> 으로 나옵니다. 누르면 그 머신의 그 창이 열립니다.
• 카드 머리를 누르면 접힙니다.
• 카드가 가리는 곳이 있으면 머리의 ✛ 를 누릅니다. 누를 때마다 오른쪽 위, 오른쪽 아래, 왼쪽 아래, 왼쪽 위 순서로 모서리를 옮겨 갑니다.
• 카드를 아예 띄우지 않으려면 설정의 Agent peek view 를 끕니다. 같은 그래프는 에이전트 그래프 탭(⇧⌘G)에서 계속 봅니다.

브라우저의 웹 터미널(데스크탑 레이아웃)에도 같은 카드가 있고 ✛ 와 Agent peek view 도 같습니다. st 0.3.92부터는 그 카드와 그래프에 계정의 다른 머신에서 실행되는 에이전트도 나오고, 누르면 그 창이 열립니다. 오프라인인 머신의 에이전트는 흐리게 나옵니다.

에이전트 데려오기

사이드바에서 에이전트가 실행되는 창 줄을 끌어 다른 에이전트의 창 줄에 놓으면, 끈 에이전트가 놓은 줄 에이전트의 워커가 됩니다. 새로 띄우지 않으므로 나누던 대화가 그대로 이어집니다. 데려온 워커에게 일을 맡기는 법과 같은 일을 명령으로 하는 법은 오케스트레이션의 데려오기에 있습니다.

• 놓을 수 있는 줄 위에 오면 그 줄 전체가 강조되고 오른쪽 끝에 Drop here 가 붙습니다. 포인터 아래 쪽지에 무엇이 되는지(Make api-tests a worker of planner)가 나옵니다.
• 놓을 수 없는 줄은 빨간 테두리와 Can't drop 이 붙고, 쪽지에 빨간 글씨로 이유가 나옵니다. 자기 자신(… can't be its own worker), 자기 워커와 그 아래(… works under …: it would go round), 이미 그 코디네이터의 워커(… already works for …), 워커 위에 에이전트가 넷을 넘게 되는 곳(Too deep: at most 4 agents may be above a worker)입니다. 거기 놓으면 아무것도 바뀌지 않고 사이드바 맨 위에 이유가 나옵니다.
• 에이전트가 없는 줄과 줄 사이 빈 곳에는 아무 표시도 없습니다.
• 놓으면 결과가 사이드바 맨 위에 한 줄로 잠깐 나옵니다.

코디네이터 카드

데려오면 코디네이터와 그 워커가 사이드바에서 카드 하나로 묶이고, 카드는 트리로 그려집니다(앱 0.1.33 이상). 코디네이터에서 워커마다 가는 안내선이 내려갑니다. 카드 바탕은 에이전트 색이 아니라 중립적인 회색이고, 에이전트 색은 점과 아이콘에만 남습니다. 카드 안의 줄에는 claude 같은 명령 이름을 다시 쓰지 않아서 이름이 그 자리를 씁니다.

• 코디네이터 줄 이름 뒤에 coordinator 표시가 붙습니다.
• 같은 머신의 워커 창은 카드 안, 코디네이터 줄 아래로 옮겨 그려집니다. 줄 앞에 상태 점, 아래 둘째 줄에 <에이전트> · <세션> · window N · ⑂ <브랜치> 가 나옵니다. 세션은 코디네이터와 다를 때만, 브랜치는 워커에게 자기 worktree가 있을 때만 붙습니다. 코디네이터의 세션을 접어 두면 워커는 제자리에 나오고 ↳ <코디네이터> 가 붙습니다.
• 코디네이터 줄 아래 ⑂ N workers 알약이 워커를 접고 폅니다. 접혀 있어도 수가 보이고, 워커 하나라도 묻고 있으면 ?, 일하고 있으면 점이 붙습니다. 접은 상태는 코디네이터마다 기억합니다.
• 워커가 자기 워커를 거느리면 그 워커는 카드 안에서 한 단계 진한 상자가 되고, 그 팀은 상자 안에서 한 단계 더 들어갑니다. 팀장 줄의 이름 뒤에는 team of N 이 붙습니다. 그래프 카드와 터미널 위 Agents 카드에도 같은 team of N 이 붙습니다. 팀 표시는 st 0.3.88 이상이 필요합니다.
• 코디네이터가 사라진 워커(pane이 닫혔거나 tmux가 다시 시작된 경우)는 목록에 남아 ⚠ 와 함께 어느 코디네이터가 사라졌는지 보여 주고, Release 가 붙습니다. tmux가 다시 시작돼도 워커가 에이전트를 따라가려면 st 0.3.88 이상이 필요합니다.
• 에이전트가 띄운 Claude Code 서브에이전트는 그 에이전트 줄 아래 ◦ N subagents 알약에 모입니다. 하나라도 실행 중이면 펼쳐지고 다 끝나면 접힙니다. 서브에이전트 줄에는 subagent 표시와 종류, 걸린 시간이 붙고, 누르면 그 칸에 서브에이전트의 대화가 열립니다. 서브에이전트는 끌어서 데려오거나 놓아 줄 수 없습니다.
• UI 모드의 창 탭에는 카드가 없어서 코디네이터 탭에 워커 수(2↓), 워커 탭에 ↳ 가 붙습니다.

놓아 주기

워커의 창 줄을 오른쪽 클릭하고 Release from <코디네이터> 를 고릅니다. 줄은 사이드바의 제자리로 돌아가고 그 세션은 데려오기 전의 대화로 남습니다. 그래프에서는 워커 카드의 Release 를 누릅니다.

다른 머신의 워커

계정에 올린 다른 머신의 에이전트도 같은 방법으로 데려옵니다. 사이드바에서 다른 머신 아래의 에이전트 창 줄을 끌어 이 머신 에이전트의 줄에 놓거나, 그 반대로 놓습니다. 양쪽 머신에 st 0.3.85 이상이 필요하고, 워커가 될 에이전트가 있는 머신에서 st orch accept-remote on 을 켜 둬야 합니다. 명령으로 하는 법은 오케스트레이션의 다른 머신의 워커에 있습니다.

• 코디네이터 카드 안. 다른 머신의 워커는 같은 머신 워커 다음에 나오고, 이름 뒤에 작은 화면 모양의 머신 표시가 붙습니다. 둘째 줄은 <에이전트> · window N · <머신> 입니다. 누르면 그 머신의 그 창이 열립니다. 알약의 수에도 들어가고(⑂ 3 workers (1 elsewhere)), 포인터를 올리면 어느 머신인지 나옵니다.
• 워커가 있는 머신 아래. 그 워커의 창 줄은 그 머신 아래 제자리에 있고, 같은 머신 표시와 초록색 ↳ <코디네이터> · <머신> 가 붙습니다.
• 놓아 주기. 오른쪽 클릭의 Release from <코디네이터> 나 그래프의 Release 로 머신이 같을 때처럼 놓아 줍니다. 그 머신의 st가 처리합니다.
• 코디네이터가 사라진 워커. 다른 머신 워커의 코디네이터 pane이 없어지면(에이전트가 끝났거나 tmux가 pane 번호를 다시 매겼을 때) 그 워커는 경고색 ⚠ 와 함께 코디네이터가 있던 머신 아래에 나오고, 둘째 줄 끝에 its coordinator %0 is gone 이 붙습니다. 줄의 Release 로 놓아 주거나, 그 워커 머신 아래의 창 줄을 다시 끌어 에이전트 줄에 놓아 데려옵니다.

아직 되지 않는 것은 이렇습니다.

• 그래프에서 다른 머신의 카드 위에 놓아 데려오기. 사이드바에서 합니다.
• 다른 머신 워커의 Changes 와 대화 보기.
• 꺼져 있는 머신. 그 머신의 에이전트는 카드와 그래프에 나오지 않습니다.

브라우저의 웹 터미널(st 0.3.92 이상)은 계정의 다른 머신에서 실행되는 에이전트를 자기 st로 5초마다 읽어 Agents 카드와 그래프에 넣습니다. 하나를 누르면 그 머신의 창이 열립니다. 오프라인인 머신의 에이전트는 흐리게 나옵니다. 사이드바에는 자기 머신의 세션만 나오므로, 코디네이터가 다른 머신에 있는 워커 줄에는 ↳ <coordinator> · <machine> 표시가 붙습니다.

로그인

로그인은 st login 과 같습니다. 앱이 코드를 보여 주고 브라우저에서 승인하면 끝납니다. 앱에서 로그인하면 이 컴퓨터도 계정에 올라갑니다.

계정 정보는 st와 같은 파일(~/.sophonz/auth.json)을 씁니다. 그래서 앱에서 로그아웃하면 이 컴퓨터의 st도 로그아웃됩니다. 앱은 로그아웃 전에 이 점을 한 번 더 묻습니다. 로그인하지 않으면 Other machines 는 비어 있고, 이 컴퓨터의 세션은 그대로 씁니다.

UI 모드와 클래식 tmux

오른쪽 위 버튼(⌘U, Windows와 Linux는 Ctrl+Shift+U)으로 둘을 오갑니다.

• UI 모드. tmux 창이 탭이 되고 pane 조작은 버튼과 단축키가 됩니다. tmux 상태줄은 이 앱의 화면에서만 숨깁니다. 이 컴퓨터의 터미널은 마우스로도 다룹니다. 포인터가 들어간 pane이 활성 pane이 되고 pane 경계를 끌어서 크기를 바꿉니다. 텍스트를 고르려면 Shift를 누른 채 끕니다.
• 클래식 tmux. tmux를 그대로 보여 줍니다. 프리픽스 키와 상태줄도 평소대로입니다.

마우스 조작과 방향 단축키는 이 컴퓨터의 세션에서만 됩니다. 다른 머신의 세션에서는 pane 크기를 바꿀 수 없습니다.

창의 한 pane이 확대돼 있으면 칸 위에 Zoomed · show all panes 가 뜹니다. 확대된 동안에는 pane이 하나로 보여 경계를 끌 수 없습니다. 누르면 확대를 풀고 모든 pane을 보여 줍니다.

단축키

iTerm2의 tmux 통합을 따릅니다. tmux 창은 탭이고 세션은 창입니다. 전체 목록은 로고 옆 Shortcuts 버튼(⌘/)에 있습니다.

macOS에서 Ctrl 조합은 전부 tmux로 갑니다. 한글 입력 상태에서도 Ctrl, Option 조합은 두벌식 자판의 같은 자리 영문 키로 보냅니다. Ctrl+ㅠ 가 Ctrl+B 가 되어 tmux 프리픽스 키가 그대로 듣습니다.

설정

⌘,(Windows와 Linux는 Ctrl+,)로 엽니다. 맨 위 검색 칸에 치면 이름이나 설명에 그 말이 든 항목만 남습니다.

• Terminal font. 글꼴, 글자 크기, 줄 간격.
• Look. 터미널 테마(폰 앱과 같은 네 개, 그리고 iterm2colorschemes.com에서 받은 .itermcolors 파일이나 같은 키의 JSON을 + Import…로 넣은 것. 가져온 테마는 계정에 남아 웹 터미널에서도 같습니다. 파일 형식, 앱 색, 내려받을 테마는 테마에 있습니다), 앱 모양, 사이드바 글자 크기(Sidebar text size, 12–20px, 기본 15px), 커서, 커서 깜박임(Blinking cursor, 기본 켬). 깜박이는 것은 포커스가 있는 터미널의 커서뿐이고 입력하거나 출력이 들어오는 동안에는 멈춰 있습니다.
• Behavior. 스크롤백, 선택하면 복사, 포커스 없는 칸 흐리게(Dim inactive views), 터미널 위 Agents 카드 띄우기(Agent peek view), 에이전트가 일하는 동안 잠들지 않기(Keep awake while an agent works), 시작 모드(UI mode).
• Option as Meta. macOS에만 있습니다.
• Updates. 자동 업데이트와 Check now.

설정은 ~/.sophonz/desktop/settings.json 에 저장되고 로그는 ~/.sophonz/desktop/desktop.log 에 남습니다.

Keep awake while an agent works 는 기본으로 켜져 있습니다. 이 컴퓨터에서 코딩 에이전트가 일하는 동안 컴퓨터가 잠들지 않게 합니다. 노트북이 작업 도중에 잠들면 에이전트도 같이 멈추기 때문입니다. 앱이 뒤에 있어도 계속 확인하고, 일하는 에이전트가 없으면 다시 잠들 수 있게 놓아 줍니다. 화면은 꺼질 수 있습니다.

알아 둘 것

• Windows는 psmux 위에서 실행됩니다. 설치에 적은 제약이 그대로입니다. 세션 그룹이 없어 데스크탑과 폰이 같은 창을 봅니다.
• 한글 입력. macOS에서는 안정적입니다. Windows와 Linux의 입력기는 아직 실제 기기에서 확인하는 중입니다.
• 같은 창을 여러 화면에서 보면 가장 최근에 움직인 쪽이 창 크기를 정합니다. 멀티플렉서의 window-size 와 같습니다. 이 컴퓨터의 세션은 앱이 컴퓨터에서 쓰던 pane 비율을 기억해 둡니다. 폰이 창을 줄였다가 앱으로 돌아오면 그 비율로 되돌립니다.
• 한글이나 선 문자가 _ 로 보이면 이 컴퓨터의 st가 UTF-8 로케일 없이 시작된 것입니다. 사이드바에 안내가 뜹니다. 터미널 앱에서 st restart 를 한 번 하면 됩니다. 앱이 직접 st를 띄울 때는 UTF-8 로케일을 붙여 띄웁니다.