TUIOS: Go로 작성된 현대적인 터미널 멀티플렉서 및 윈도우 매니저

TUIOS는 Go로 구축된 현대적인 터미널 멀티플렉서(terminal multiplexer)이자 윈도우 매니저(window manager)입니다. 기존 터미널 내에서 여러 개의 터미널 패인(pane), 워크스페이스(workspace), BSP 타일링(tiling), kitty 그래픽 프로토콜 지원, 명령 팔레트(command palette)를 제공하는 vim과 유사한 모달 인터페이스를 제공합니다. 데몬(daemon)이 세션을 활성화 상태로 유지하고, 다른 머신에 있는 세션에 접속하며, 패인 내의 코딩 에이전트(coding agents)들이 자신의 상태를 보고하고 서로 메시지를 주고받을 수 있게 합니다.

Charm 스택(Bubble Tea v2, Lipgloss v2)을 기반으로 구축된 TUIOS는 거의 0에 가까운 유휴 CPU 사용률을 위한 이벤트 기반 렌더링(event-driven rendering), 깜빡임 없는 kitty 이미지 패스스루(flicker-free kitty image passthrough), 그리고 포괄적인 키보드/마우스 상호작용 기능을 특징으로 합니다.

전체 문서는 tuios.dev (호스팅됨) 또는 docs/ 폴더에서 확인할 수 있습니다. 설치 없이 tuios를 사용해 보려면, tuios.dev/learn에서 안내 투어를 진행하세요: 모든 패인에 실습 셸(practice shell)이 포함된 실제 앱을 WebAssembly로 컴파일했습니다.

v0.8.5에서 변경된 내용은 릴리스 노트(release notes)를 참조하세요.

시작하기 (Getting Started): 설치 및 첫 세션
키 바인딩 (Keybindings): 기본 키와 재할당 방법
BSP 타일링 (BSP Tiling): 사전 선택 및 분할 제어를 이용한 타일링
레이아웃 모드 (Layout Modes): BSP, 마스터-스택(master-stack) 및 스크롤링 레이아웃, 집계 뷰(aggregate view), 멀티포커스(multifocus)
설정 (Configuration): 키 바인딩, 테마 및 동작 사용자 정의
훅 (Hooks): 창, 세션 및 에이전트 이벤트에서 셸 명령어 실행
테마 (Themes): 내장 테마와 커스텀 테마 JSON
글리프 세트 (Glyph sets): 크롬(chrome)이 그려지는 문자들
CLI 참조 (CLI Reference): 모든 명령줄 옵션
테이프 스크립팅 (Tape Scripting): 워크플로우 자동화
세션 (Sessions): 데몬 모드, 연결/연결 해제(attach/detach), 다른 머신 및 유지되는 것들
에이전트 (Agents): tuios에서 코딩 에이전트 실행하기: 상태, 인박스(Inbox), 승인(approvals), 플릿(fleets), 다른 머신, 그랜트(grants) 및 MCP
tmux Shim: Claude Code agent 팀과 같이 tmux를 구동하는 도구 실행
제어 프로토콜 (Control Protocol): 데몬을 구동하기 위한 JSON 기반의 동사(verb) 프로토콜
아키텍처 (Architecture): 기술 설계

Homebrew (macOS/Linux):

brew install tuios

Homebrew, ghostty 빌드 (Linux 전용): tuios

libghostty-vt 에뮬레이터로 구축되었습니다. 이는 tuios를 대체합니다.

cask.

brew install gaurav-gosain/tap/tuios-ghostty

Arch Linux (AUR):

yay -S tuios-bin

Nix:

nix run github:Gaurav-Gosain/tuios/v0.8.5#tuios # 릴리스 버전
nix run github:Gaurav-Gosain/tuios#tuios # 최신 main 브랜치
nix run nixpkgs#tuios # nixpkgs 패키지

저장소 이름 뒤에 릴리스 태그를 붙여 해당 버전을 빌드할 수 있습니다. 태그가 없으면 Nix는 main의 최신 커밋을 빌드합니다.

# 빠른 설치 스크립트 (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/Gaurav-Gosain/tuios/main/install.sh | bash
# Go install
...

GitHub Releases: Linux, macOS, Windows, FreeBSD 및 OpenBSD용 사전 빌드 바이너리와 checksums.txt가 제공됩니다.

tuios-ghostty_* 아카이브는 libghostty-vt 에뮬레이터 기반으로 Linux, macOS 및 Windows (amd64 및 arm64)에서 빌드된 tuios입니다.

소스 코드 빌드에는 Go 1.26.6 이상이 필요합니다.

업데이트: 빠른 설치 스크립트나 릴리스 바이너리로 설치한 경우, tuios update가 최신 릴리스를 가져와 적용합니다 (tuios update --check는 보고만 합니다). 그 외의 모든 경우는 해당 바이너리를 소유하는 패키지 관리자를 사용해야 하므로 대신 그것을 사용하세요. tuios update는 어떤 것을 가지고 있는지 감지하여 덮어쓰기 하는 대신 적절한 명령어를 출력합니다.

요구 사항: 트루 컬러(true color) 지원이 되는 터미널. Kitty graphics 및 sixel 지원을 권장합니다 (Ghostty, Kitty, WezTerm).

다중 터미널 패널: 터미널 세션을 생성하고, 크기를 조정하고, 드래그하며, 정리할 수 있습니다.9 작업 공간(Workspaces): 즉시 전환 가능한 독립적인 작업 공간 격리 기능모달 인터페이스(Modal Interface): Vim에서 영감을 받은 창 관리 및 터미널 모드명령어 팔레트(Command Palette): 퍼지 검색이 가능한 액션 런처 (Ctrl+P)런처(Launcher): $PATH의 모든 것을 퍼지 검색합니다.

그리고 설치된 데스크톱 앱들(Alt+Space)을 사용 빈도에 따라 순위화합니다. Enter를 누르면 실행되고, Tab은 입력만 하고 아직 실행하지 않은 명령어로 셸을 열어 인수를 추가할 수 있게 합니다. 앱 아이콘은 터미널이 kitty 그래픽을 지원하는 곳에 그려집니다.

Pane Zoom: z(WM 모드) 또는 Prefix+z로 모든 패널을 확대합니다. 기본적으로 화면의 95%를 차지하며, appearance.zoom_size = 100으로 설정하면 전체 화면이 됩니다. 전체 화면 확대는 공유 경계를 숨기고, 도크바에 Z 표시기를 보여줍니다.

Session Rail: 세션, 터미널, 파일, git 상태 및 에이전트가 있는 사이드바로, 기본적으로 오른쪽에 있습니다 (appearance.sidebar.enabled).

Settings Page: Prefix+,로 앱의 옵션을 변경합니다.

Popups: tuios popup -- fzf는 플로팅 패널에서 명령을 실행하며, 종료되면 닫힙니다.

가이드는 docs/AGENT_STATE.md를 참조하세요.

Agent State: 코딩 에이전트를 실행하는 패널은 제목의 모양과 레일의 한 줄로 작동 상태(작업 중, 대기 중, 완료 또는 오류)를 보여줍니다. tuios integration install은 19개의 하네스(Claude Code, Codex, Gemini CLI, opencode 등)를 연결하여 보고하게 하며, tuios는 프로세스와 화면을 통해 24개 에이전트 CLI를 감지합니다.

Inbox: Prefix+i는 모든 세션과 모든 기기에서 당신을 기다리는 모든 것(승인, 질문, 메일, 오류, 완료된 턴)을 나열합니다. Prefix+o는 가장 오래된 항목으로 이동합니다. 거기서 패널로 가지 않고 프롬프트에 응답할 수 있으며, [agents.approvals]를 사용하여 Claude Code, opencode, Kilo 및 Qwen Code의 권한 요청에 한 번의 키 입력으로 답변합니다.

Questions and Messages: tuios ask-human은 고정된 답변을 가진 질문을 인박스에 넣습니다. 에이전트들은 tuios send-agent-message로 서로 메일을 주고받고, tuios ask-agent는 하나를 물어보고 그 답변을 기다립니다. 프롬프트가 있는 패널에 절대 직접 입력하지 않으며, 당신의 답변은 검증됨으로 표시됩니다.

Fleets: tuios fan은 여러 에이전트에서 하나의 프롬프트를 시작하며, 혼합 하네스 사용이 가능하고 각각 독립적인 git 작업 트리를 가집니다. tuios start-agent

당신 옆에 보조 도구를 하나 시작합니다. 이는 TUI 또는 ACP나 Codex 앱-서버 위에서 헤드리스로 실행될 수 있습니다. group:fan/retry needs:you와 같은 선택자는 전체 그룹을 처리합니다.

Resume: 데몬 재시작 후, Inbox는 실행 중이던 각 에이전트 대화의 재개 여부를 제안합니다.

Pane Grants: tuios를 통해 에이전트 패널이 무엇을 할 수 있는지(read, write, fan, respond, admin) 말하고, --grants로 보조 도구에게 권한을 부여할 수 있습니다.

MCP Server: tuios mcp는 MCP 도구와 동일한 표면을 제공하며, 달리 지정하지 않는 한 읽기 전용으로 에이전트 자신의 세션에 국한됩니다.

tmux Shim: tuios tmux-shim은 Claude Code agent 팀과 같이 tmux를 구동하는 도구를 실행하며, 이들의 패널은 tuios 패널로 열립니다.

Session Stash: tuios stash put은 세션에 대한 파일을 보관하여 다른 에이전트가 여전히 이를 열 수 있게 합니다.

Agent Skill: tuios --skill은 패널 속의 에이전트가 tuios를 구동하기 위해 읽는 간략한 가이드를 출력하며, tuios --skill TOPIC은 나머지 주제들(레시피 포함)을 다룹니다.

Hosts: tuios hosts add는 ssh를 통해 도달하는 다른 머신에 이름을 붙입니다. tuios hosts tailnet은 Tailscale tailnet상의 머신 목록을 나열합니다.

Remote Sessions: tuios attach --host build api는 이 클라이언트에서 다른 머신에 세션을 그립니다. -s HOST:SESSION은 거기에 어떤 명령이든 전송합니다.

Hosted Panes: tuios new-window NAME --host build는 한 패널의 프로세스를 여기에 있는 다른 머신에서 실행합니다.

Global Sessions: tuios new NAME --global은 여러 머신의 패널을 보관합니다. Agents on Other Machines: tuios fan --host build와 tuios start-agent -s build:api는 그곳에 에이전트를 실행하며, 이들의 Inbox 항목은 여기에 표시되고, tuios worktree pull은 그들의 작업을 되돌려 가져옵니다. 각 머신의 [hosts] 정책은 다른 머신들이 무엇을 할 수 있는지 정의합니다.

BSP Tiling: 나선형 레이아웃을 사용한 이진 공간 분할(Binary Space Partitioning) Scrolling Layout: 무한 수평 스트립에 niri 스타일의 컬럼 배치 (문서 참조) Master-Stack Layout: 나머지 패널들을 옆에 쌓고 하나의 마스터 패널을 두는 방식 Smart Auto-Split: 종횡비 인지 분할 (선택 사항) Shared Borders: tmux 스타일의 패널 간 구분선 (--shared-borders) Preselection: 다음 패널이 생성될 위치 제어 Equalize Splits: 모든 분할 비율을 균형 있게 재설정 Vim-Style Copy Mode: hjkl로 10,000줄 스크롤백 탐색, /로 아래 검색, ?로 위 검색, y로 복사 (yank) Multi Copy Mode: 다중 포커스 세트의 모든 패널에서 한 번에 복사 모드. 각 패널에서 v 또는 /V로 검색하고 선택한 후, 일반 텍스트, 마크다운 또는 JSON으로 클립보드나 파일에 모든 선택 내용을 복사 (문서 참조) 마우스 휠 스크롤백: 모드가 입력되지 않은 상태에서도 휠을 돌려 히스토리 스크롤. 타이핑하거나 하단에 도달하면 실시간 출력으로 돌아옴 대화형 스크롤바: 오른쪽 경계를 클릭하거나 드래그하여 스크롤 위치로 이동 가능 선택 자동 스크롤: 패널 위/아래로 선택 영역을 드래그하여 스크롤됨 스크롤백 브라우저: OSC 133 인식 명령/출력 블록 탐색 스크롤 위치 표시기: 하단 경계에 오프셋/총합 표시 Kitty Graphics Protocol: 깜빡임 없는 비디오 재생과 전체 이미지 렌더링 지원. mpv --vo=kitty가 작동하며 (shm 및 base64 모두), youterm도 작동함. Sixel Graphics: Sixel 이미지 패스스루 (실험적, 아직 픽셀 단위 클리핑 없음) Kitty Keyboard Protocol: 점진적 향상(CSI u)으로 푸시/팝/쿼리 지원. Fish 4.x와 호환되며; Shift+인쇄 가능한 문자는 프로토콜을 우회하고 텍스트를 직접 전송함. 동기화된 출력: Mode 2026이 화면 찢어짐(screen tearing) 방지 공유 메모리 지원:t=s mpv의 경우 --vo-kitty-use-shm을 통한 패스스루 애니메이션 프레임: 게스트의 a=f

프레임 편집(frame edits)은 호스트로 전달되므로, 자체 이미지를 패치하는 프로그램은 전체 비트맵 대신 직사각형 영역만 비용을 차지합니다. TUIOS는 재전송만 하는 게스트도 패치합니다. 페인(Panes)에는 호스트가 프레임 편집을 전달하는지 여부가 TUIOS_KITTY_ANIMATION을 통해 알려주는데, 이는 호스트의 응답이 페인으로 다시 전송되지 않기 때문에 게스트 스스로 알 수 없기 때문입니다.터미널 쿼리(Terminal Queries): OSC 4 팔레트, OSC 10-12 색상, CSI 14/16/18t 크기 지정, DA1/DA2실험적 기능(Experimental): Kitty 텍스트 크기 지정 프로토콜 (OSC 66). 기본적인 통과(passthrough)는 작동하지만 스크롤백 및 창 재배치와 관련된 알려진 문제가 있습니다.Kitty 애니메이션 프로토콜(Kitty Animation Protocol): 프레임 전송, 합성, 제어 (a=f, a=a, a=c), 애니메이션 게스트를 위한 손상 패치 스트리밍

데몬 모드(Daemon Mode): 분리/재연결이 가능한 영구 세션 (tmux와 유사)
세션 부활(Session Resurrection): 데몬 재시작 또는 재부팅 후에도 구조 및 작업 디렉터리가 유지된 상태로 세션 복원 (문서)
세션 스위처(Session Switcher): 앱 내 세션 목록 (Prefix+S)
레이아웃 템플릿(Layout Templates): 작업 디렉터리 및 시작 명령과 함께 창 배열 저장/불러오기
레이아웃 CLI: tuios layout list, tuios layout delete, tuios layout export

테이프 스크립팅(Tape Scripting): 터미널 워크플로우 기록 및 재생을 위한 DSL (Domain Specific Language)
테이프 녹화(Tape Recording): 실시간 세션 녹화 (Prefix+T``r)
헤드리스 실행(Headless Execution): tuios tape exec은 실행 중인 데몬 세션에 대해 테이프를 실행합니다.
레이아웃 내보내기(Layout Export): 레이아웃을 공유하기 위해 테이프 스크립트로 변환

위치 키 팝업(Which-Key Popup): 프리픽스 키를 길게 누르면 사용 가능한 조합(chords)이 표시됩니다 (appearance.whichkey_enabled, 문서)
앱 실행기(App Launcher): Alt+Space는 $PATH에 있는 모든 것을 데스크톱 엔트리 이름과 아이콘을 사용하여 빈도순으로 정렬하여 실행합니다
키 바인딩 관리자(Keybind Manager): 앱 내에서 (Prefix+k) 또는 셸에서 tuios keybinds doctor와 tuios keybinds explain <key>를 사용합니다
집계 보기(Aggregate View): 모든 워크스페이스의 모든 창에 대한 검색 가능한 목록과 미리보기 (문서)
멀티포커스(Multifocus): 여러 페인에 동시에 타이핑을 브로드캐스트하며, Ctrl+Shift+클릭으로 선택할 수 있습니다 (문서)

Showkeys Overlay: 프레젠테이션 시 눌린 키 표시Spotlight: 데모 및 녹화용으로 화면의 특정 영역을 밝게 하고 나머지는 어둡게 처리 ([spotlight] config 테이블)Screenshots: 패널을 PNG, SVG, ANSI, HTML 또는 텍스트로 렌더링 가능 (tuios screenshot)Dock Components: 도크에 직접 그린 커스텀 명령어. 이벤트 기반으로 업데이트하거나 실행 중인 명령어 또는 폴링(polling)을 통해 업데이트할 수 있음 (예시)Customizable Keybindings: Kitty 프로토콜 지원의 TOML 설정 파일로 구성Hooks: 창, 작업 공간, 연결 및 에이전트 상태 변경을 포함한 10가지 이벤트에서 셸 명령 실행 가능 (문서 참조)Mouse Support: 휠 스크롤백, 놓으면 복사되는 드래그-선택, 더블 클릭으로 단어 선택 및 트리플 클릭으로 줄 선택, 창 드래그, 크기 조정, 스크롤바 지원SSH Server Mode: 원격 터미널 멀티플렉싱 지원Web Terminal Mode: 브라우저 기반 접근 (별도의 tuios-web 바이너리)Themes: 내장 테마와 JSON을 통한 커스텀 테마를 제공하며, 트루컬러(truecolor), 256색 및 16색에 최적화된 크롬 디자인 지원 (문서 참조)Host Colours: tuios가 터미널로부터 색상을 요청하고, 이를 요청하는 프로그램에 전달하며, 밝기/어둡기 전환을 따라감Backgrounds: 빈 셀을 테마의 배경색 또는 원하는 개별 표면의 사용자 지정 색상으로 채움Motion: none, basic 또는 full (페이드, 작업 중 깜빡임 효과, 컨페티) 중 선택 가능Glyph Sets: 크롬에 그려질 문자를 선택할 수 있음 (문서 참조)