Xgen Dex Cli

XGEN 에이전트를 쓰는 세 가지 방법.

앱 데스크톱	CLI 터미널	VS Code 확장 편집기 사이드바

	무엇	받는 것
앱	데스크톱 앱. 대화 · 오버레이 아바타 · 브라우저 제어 · 워크스페이스 동기화	Windows .exe · macOS .dmg · Linux .AppImage / .deb
CLI	터미널. 대화형 UI 와 일회성 명령, 스크립트에서 쓰는 JSON 출력	npm — xgen-dex-cli
VSCode 확장	편집기 안에서 대화. 사이드바 + 명령 팔레트	.vsix

셋 다 같은 XGEN 서버에 붙고, 같은 계정·같은 에이전트를 봅니다. 로컬 도구(셸 · 파일 · MCP 서버)도 같은 것을 씁니다.

모든 파일은 Releases 에서 받습니다. 같은 태그의 셋은 함께 검증된 조합입니다.

---

앱 설치

Windows

XGen-Dex-Setup-<버전>.exe 를 실행합니다.

서명되지 않은 빌드라 SmartScreen 이 막을 수 있습니다 — 추가 정보 → 실행 을 누르면 됩니다.

macOS

XGen-Dex-<버전>.dmg 를 열고 XGen-Dex.app 을 응용 프로그램 으로 끕니다.

첫 실행은 아이콘을 우클릭 → 열기 로 해야 합니다(그냥 더블클릭하면 "확인되지 않은 개발자" 로 막힙니다). 그래도 "손상되었기 때문에 열 수 없습니다" 가 뜨면 터미널에서:

xattr -dr com.apple.quarantine "/Applications/XGen-Dex.app"

Linux

# deb (Ubuntu / Debian) — 권장. 앱 목록과 자동 업데이트가 함께 붙습니다.
sudo dpkg -i XGen-Dex-<버전>.deb
sudo apt-get -f install          # 의존성이 빠졌다는 말이 나오면

# AppImage — 설치 없이 실행
chmod +x XGen-Dex-<버전>.AppImage
./XGen-Dex-<버전>.AppImage

처음 실행하면

서버 주소(예: https://xgen.example.com)와 계정을 입력합니다. 기본 서버는 들어 있지 않습니다 — 각자의 XGEN 배포를 가리키세요.

사설 인증서를 쓰는 사내 서버라면 설정 → 일반 → 서버 에서 사설 인증서 허용 을 켭니다. SSO 를 쓴다면 같은 자리에서 켜고 경로를 지정합니다.

---

CLI 설치

Node.js 20 이상이 필요합니다.

npm i -g xgen-dex-cli

dex 와 xgen-dex 두 이름으로 설치됩니다.

npm 레지스트리에 나갈 수 없는 사내망이라면 Releases 의 xgen-dex-cli-<버전>.tgz 를 받아 설치합니다:

npm i -g ./xgen-dex-cli-<버전>.tgz

쓰기

dex                                              # 대화형 터미널 UI
dex profile set corp --server https://xgen.example.com
dex login --email [email protected]
dex agents list
dex chat --agent <workflow-id>

에이전트에게 이 컴퓨터의 셸과 파일을 열어 주려면 로컬 도구를 켭니다. 기본은 꺼져 있습니다.

dex tools enable --cwd ~/work --allow ~/work
dex tools list                                   # 무엇이 노출되는지

새 버전이 나왔는지 확인하고 올립니다.

dex update            # 있으면 설치, 없으면 최신이라고 알려 줍니다
dex update --check    # 확인만

스크립트에서 쓸 때는 --json(단일 결과) 또는 --jsonl(채팅 이벤트 스트림)을 붙입니다. 전체 명령은 dex --help.

한글 입력

macOS 에서는 시스템 입력기를 그대로 사용하고 Caps Lock 으로 한/영을 전환합니다. 시스템 설정 → 키보드 → 텍스트 입력 → 편집에서 Caps Lock 키로 ABC 전환을 켜 주세요. CLI 가 Ctrl+Space를 별도로 처리하지 않으므로 macOS 입력 소스 단축키와 상태가 이중으로 바뀌지 않습니다.

Linux와 Windows에서는 조합을 CLI 안에서 합니다 — 터미널의 IME 에 맡기지 않습니다. 잘 되는 터미널도 있지만 종류마다 다르고, SSH 나 tmux 를 거치면 아예 오지 않습니다. 표준 두벌식이고, 받침이 넘어가는 자리(간 + ㅏ → 가나)와 백스페이스로 되짚는 자리(한 → 하 → ㅎ)가 실제 IME 와 같습니다. Caps Lock 이 켜져 있어도 같은 글자가 나옵니다.

Linux와 Windows의 CLI 자체 한/영 모드는 이 중 아무 것으로나 바꿉니다:

키	어디서
Ctrl+Space	어디서나
Shift+Space	어디서나 — 리눅스 입력기의 오랜 한/영 자리
Alt+Space	어디서나 — 한국어 자판의 한/영 키가 오른쪽 Alt 자리라 엄지로 닿습니다
Ctrl+L	터미널이나 tmux 가 Ctrl+Space 를 먼저 채갈 때
한/영 키, Caps Lock	아래 참고

지금 어느 쪽인지는 입력창 왼쪽(한 / EN)과 아래 상태바([한] / [EN])에 늘 보입니다. 한국어 로케일이면 한글로 시작하고, 한 번 바꾸면 그 선택을 기억합니다.

한/영 키와 Caps Lock 이 되는 곳 — 이 키들은 글자를 만들지 않아서, 보통은 터미널이 앱에 알려 주지 않습니다. Kitty 키보드 프로토콜 을 아는 터미널(kitty · ghostty · WezTerm · foot · 최근 Alacritty · Konsole 등)에서만 그 키들이 도착하고, 그럴 때는 한/영 키(오른쪽 Alt 자리)와 Caps Lock 이 그대로 한/영 전환이 됩니다. 이름으로 아는 터미널이면 바로 켜고, 아니면 시작할 때 물어봐서 되는 경우에만 켜므로 모르는 터미널에서는 아무 일도 일어나지 않습니다(DEX_NO_KITTY=1 로 끌 수 있습니다).

macOS처럼 OS 입력기를 쓰는 경우, 입력기가 만들어 준 한글은 CLI 조합기를 거치지 않고 그대로 들어갑니다.

로그인 정보는 어디에 저장되나

OS 키체인이 있으면 거기, 없으면 사용자 데이터 폴더의 소유자 전용(0600) 파일입니다. 헤드리스 서버나 컨테이너처럼 키링이 없는 곳에서도 그대로 동작합니다. 지금 어느 쪽인지는 dex status 가 알려 줍니다.

키링이 매번 암호를 물어 성가시면 DEX_NO_KEYCHAIN=1 로 파일 저장을 강제할 수 있습니다.

---

VSCode 확장 설치

확장은 대화를 직접 하지 않고 CLI 엔진을 자식 프로세스로 띄워 씁니다. CLI 가 없으면 확장이 처음 켜질 때 물어보고 같은 버전으로 깔아 줍니다 — 미리 설치해 두어도 됩니다.

1. VS Code → 확장 → … → VSIX에서 설치
2. xgen-dex-vscode-<버전>.vsix 선택

또는 터미널에서:

code --install-extension xgen-dex-vscode-<버전>.vsix

VS Code 1.95 이상이 필요합니다.

쓰기

명령 팔레트(Ctrl/Cmd+Shift+P)에서 XGEN Dex 로 시작하는 명령을 씁니다 — 서버 프로필 설정 → 로그인 → Agent와 대화 순서입니다.

dex 가 PATH 에 없거나 다른 위치에 있으면 설정에서 지정합니다:

설정	뜻
xgenDex.cliPath	dex 실행 파일 경로. 비우면 PATH 와 npm 전역 폴더에서 찾습니다
xgenDex.profile	쓸 서버 프로필. 비우면 CLI 의 현재 프로필

---

업데이트

앱은 스스로 확인합니다 — 설정 → 일반 → 업데이트. Windows 와 Linux 는 앱 안에서 설치까지 하고, macOS 는 서명 문제로 새 .dmg 를 받아 열어 주기까지 합니다(끌어다 놓는 것은 직접).

기본은 이 저장소의 Releases 를 보지만, 사내망처럼 GitHub 에 나갈 수 없는 곳에서는 같은 화면에서 XGEN 으로 바꿔 자기 서버의 다운로드 센터를 보게 할 수 있습니다.

CLI 는 dex update 로 확인하고 올립니다 — 최신이면 그렇다고만 말합니다. 전역 npm 설치가 아니면 자동으로 올리지 않고 무엇을 하면 되는지 알려 줍니다.

확장은 자동 업데이트가 없으니 새 .vsix 로 다시 설치하세요.

---

개발

packages/protocol   XGEN 서버와 말하는 법. 의존 0.
packages/engine     이 기기에서 실제로 하는 일 — 로컬 도구 · MCP · 서버 브리지.
packages/rpc        엔진을 다른 프로세스에 빌려주는 JSON-RPC.

apps/desktop        Electron
apps/cli            Ink 터미널 UI + 명령
apps/vscode         웹뷰 + CLI 엔진 (RPC)

구조와 그 규칙은 ARCHITECTURE.md.

준비

Node.js 20 이상.

npm install                        # packages/* + apps/cli + apps/vscode
npm --prefix apps/desktop install  # 데스크톱은 따로 (electron + 네이티브 FUSE)

리눅스에서 데스크톱을 빌드하려면 FUSE 헤더가 필요합니다(워크스페이스 가상 드라이브):

sudo apt-get install libfuse-dev fuse3 pkg-config

apps/desktop 이 npm workspace 밖인 이유는 electron 과 네이티브 바인딩이 루트로 호이스팅되면 electron-builder 가 패키징할 때 어긋나기 때문입니다. 대신 세 앱 모두 @dex/* 를 경로 별칭으로 소스 번들 합니다 — 심링크도 버전 올림도 없습니다.

실행

npm --prefix apps/desktop run dev        # 데스크톱 (핫 리로드)
npm --prefix apps/cli run build && node apps/cli/dist/cli.js
npm --prefix apps/vscode run watch       # 확장 — F5 로 디버그 창

검사

npm run contracts   # 앱이 코어를 우회하지 않는지
npm test            # 전 워크스페이스
npm --prefix apps/desktop test

npm run contracts 는 앱이 코어를 우회하는 곳이 없는지 기계가 확인합니다 — 서버 경로를 직접 부르거나, WebSocket 을 직접 열거나, 패키지가 electron 을 알거나, 확장 번들에 엔진이 섞이는 일. 규칙과 그 이유는 scripts/contracts/check.mjs 안에 적혀 있습니다.

빌드와 배포

GitHub Actions 가 합니다. PR 마다 검사를 돌리고, 태그를 밀면 세 산출물을 만들어 하나의 Release 에 올리고 CLI 를 npm 에 배포합니다.