Skip to content
BranchesTags

Repository files navigation

SpaceVibe Deck

SpaceVibe Deck for Linux

Terminal desktop nhẹ dành cho Claude Code, OpenAI Codex và Gemini CLI.
Bản port Linux có split pane, Plank launcher, SIXEL pet và tích hợp Codex qua Cockpit.

Linux Tauri 2 xterm.js 6 MIT License

Đây là bản Linux mở rộng từ dự án gốc mxrsv/spacevibe-deck. Phần port và tích hợp trong repository này tập trung vào Linux Mint/Ubuntu.

Tính năng chính

  • PTY thật chạy login shell, kế thừa PATH, alias và dotfiles của người dùng.
  • Chia nhiều terminal theo chiều dọc/ngang, kéo thả để đổi vị trí và thay đổi kích thước.
  • Mở workspace theo thư mục hoặc mở terminal trực tiếp tại thư mục home, không cần chọn folder.
  • Tự phát hiện Claude Code, Codex và Gemini CLI trong interactive login shell.
  • Giao diện thích ứng Linux: shortcut dùng Ctrl, native window chrome và desktop launcher.
  • Codex pet hoạt động qua SIXEL trong xterm.js.
  • Welcome card Codex kiểu Claude: pet nằm trong khung, hiển thị runtime và thư mục hiện tại.
  • Không hiển thị pet nổi trùng lặp khi Codex chạy bên trong Deck.
  • Nhận diện Codex ngay cả khi chạy qua wrapper Cockpit bash -> node -> codex.
  • Tương thích IBus Bamboo theo từng ứng dụng: dùng ForwardKeyEvent I để chữ đi thẳng vào terminal thay vì nằm trong bong bóng Pre-edit.
  • Hỗ trợ gõ tiếng Việt, Unicode grapheme, truecolor, tìm kiếm scrollback và mở link/file.
  • Có gói Debian .deb, desktop entry và terminfo spacevibe-sixel đi kèm.

Yêu cầu

Chạy gói .deb

  • Ubuntu 22.04+, Linux Mint 21+ hoặc bản Debian tương đương.
  • WebKitGTK 4.1 và các runtime dependency do dpkg/apt quản lý.
  • Một shell hợp lệ trong biến môi trường SHELL.

Build từ source

  • Node.js 20+ và npm.
  • Rust stable cùng Cargo.
  • Các dependency Tauri 2 cho Linux.

Trên Ubuntu/Linux Mint:

sudo apt update
sudo apt install -y \
  build-essential curl file libayatana-appindicator3-dev librsvg2-dev \
  libssl-dev libwebkit2gtk-4.1-dev wget

Cài đặt

Build và cài gói Debian

git clone https://github.com/DevOpsLogistics/Terminal_setup.git
cd Terminal_setup
npm install
npm run tauri -- build --bundles deb
sudo dpkg -i "src-tauri/target/release/bundle/deb/SpaceVibe Deck_0.9.0_amd64.deb"

Nếu dpkg báo thiếu dependency:

sudo apt --fix-broken install

Sau khi cài, mở SpaceVibe Deck từ application menu hoặc chạy:

spacevibe-deck

Chạy chế độ phát triển

npm install
npm run tauri dev

Chỉ build frontend

npm run build

Ghim vào Plank

Gói .deb cài desktop entry và icon hệ thống. Mở SpaceVibe Deck từ application menu, sau đó nhấp phải icon trên Plank và chọn Keep in Dock.

Nếu Plank chưa cập nhật launcher, chạy:

update-desktop-database ~/.local/share/applications /usr/share/applications

Sử dụng

Mở terminal không cần folder

Trong Open Board, chọn Open Terminal. Pane mới khởi động tại $HOME và không gắn với workspace dự án. Bạn vẫn có thể cd đến bất kỳ thư mục nào sau đó.

Mở workspace

  1. Chọn Open Workspace.
  2. Chọn thư mục dự án.
  3. Chọn layout.
  4. Chọn Claude, Codex, Gemini hoặc Shell only.

Deck khởi chạy agent đã chọn trong mọi pane của layout.

Codex welcome card và pet

Khi foreground process được nhận diện là codex, Deck hiển thị welcome card gồm:

  • nhãn OpenAI Codex;
  • pet Codex lấy từ cache chính thức tại $CODEX_HOME/cache/tui-pets;
  • runtime Codex CLI;
  • thư mục làm việc hiện tại.

Pet gốc của Codex được tắt riêng trong Deck để tránh xuất hiện hai lần. Cấu hình pet ở terminal khác không bị thay đổi.

Cấu hình Codex

Để Codex tải và chuẩn bị pet, thêm vào ~/.codex/config.toml:

[tui]
pet = "codex"

Deck đặt các biến sau cho PTY:

TERM=spacevibe-sixel
COLORTERM=truecolor
SPACEVIBE_DECK=1

Trên Linux, TERM_PROGRAM được xóa có chủ đích vì Codex ưu tiên biến này hơn TERM khi phát hiện giao thức hình ảnh. Terminfo spacevibe-sixel được đóng gói vào /usr/share/terminfo/s/spacevibe-sixel.

Tích hợp Codex với Cockpit

Repository có wrapper mẫu tại scripts/codex-cockpit-wrapper.sh. Wrapper:

  • kết nối Codex tới Unix socket của shared app-server;
  • yêu cầu systemd user service codex-shared-app-server.service khởi động khi cần;
  • tự resume conversation nếu Cockpit đổi account/auth;
  • tắt pet nổi chỉ khi SPACEVIBE_DECK=1.

Cài wrapper:

mkdir -p ~/.local/bin
install -m 755 scripts/codex-cockpit-wrapper.sh ~/.local/bin/codex-cockpit
ln -sfn ~/.local/bin/codex-cockpit ~/.local/bin/codex

Mặc định wrapper tìm Codex thật tại ~/.npm-global/bin/codex. Có thể đổi bằng:

export CODEX_REAL_BIN="$(command -v codex-real)"

Shared app-server phải tạo socket tại:

$XDG_RUNTIME_DIR/codex-shared.sock

Có thể đổi socket/service bằng CODEX_SHARED_SOCKET và CODEX_SHARED_SERVICE.

Phím tắt Linux

Phím Chức năng
Ctrl+T Tab mới / Open Board
Ctrl+D Chia pane dọc
Ctrl+Shift+D Chia pane ngang
Ctrl+] / Ctrl+[ Chuyển pane
Ctrl+Shift+Enter Zoom/khôi phục pane
Ctrl+W Đóng pane
Ctrl+Shift+W Đóng tab
Ctrl+Shift+T Mở lại tab vừa đóng
Ctrl+F Tìm trong terminal
Ctrl+K Xóa scrollback
Ctrl+, Mở Settings

Các phím được định nghĩa tập trung trong src/terminal/action-registry.ts.

Kiểm tra

Frontend

npm test -- --run
npm run build

Backend Rust

cd src-tauri
cargo fmt --check
cargo test

Kiểm tra gói Debian

npm run tauri -- build --bundles deb
dpkg-deb -I "src-tauri/target/release/bundle/deb/SpaceVibe Deck_0.9.0_amd64.deb"

Xử lý lỗi

Codex báo terminal không hỗ trợ pet

Kiểm tra trong pane Deck:

printf 'TERM=%s\nTERM_PROGRAM=%s\n' "$TERM" "${TERM_PROGRAM-}"
infocmp spacevibe-sixel

Kết quả mong đợi là TERM=spacevibe-sixel và TERM_PROGRAM rỗng. Không chạy Codex bên trong tmux/Zellij nếu lớp đó không chuyển tiếp SIXEL.

Pet trong card không xuất hiện

Chạy Codex một lần trong terminal có hỗ trợ pet để tạo cache, rồi mở lại Deck. Kiểm tra:

find ~/.codex/cache/tui-pets -name frame_000.png -print

Deck chỉ nhận diện wrapper là bash

Bản Linux này đọc argv của foreground process và nhận diện tên agent nằm sau shell/Node wrapper. Hãy rebuild/cài lại bản mới nhất nếu status bar vẫn hiện bash thay vì codex.

Chữ đi vào bong bóng IME thay vì ô chat

Nếu đang dùng IBus Bamboo, hãy đặt riêng SpaceVibe Deck sang chế độ nhập trực tiếp:

  1. Click vào terminal của Deck.
  2. Nhấn Shift+~ để mở menu chế độ Bamboo.
  3. Chọn 3 — ForwardKeyEvent I.

Bamboo lưu lựa chọn riêng cho từng ứng dụng. Có thể kiểm tra bằng:

rg -n 'spacevibe-deck' ~/.config/ibus-bamboo/ibus-bamboo.config.json

Kết quả mong đợi có dòng tương đương:

"spacevibe-deck:Spacevibe-deck": 3

Nếu chế độ 3 không hợp với phiên bản Bamboo đang dùng, thử lại Shift+~ và chọn 4 — ForwardKeyEvent II.

Kiến trúc ngắn gọn

Tauri 2 / Rust
  ├─ portable-pty: shell và process lifecycle
  ├─ Linux process inspection: cwd, agent, wrapper detection
  └─ Tauri commands: settings, file links, pet cache

Preact / TypeScript
  ├─ Open Board và workspace UI
  ├─ tab/pane layout manager
  └─ xterm.js + fit/search/unicode/image addons

Các file quan trọng:

  • src/terminal/pane.ts: khởi tạo xterm, SIXEL và Codex welcome card.
  • src/terminal/webkit-ime-fix.ts: xử lý IME WebKit.
  • src/styles.css: giao diện và composition helper trong suốt.
  • src-tauri/src/pty.rs: PTY, TERM/terminfo và biến môi trường Deck.
  • src-tauri/src/platform/linux.rs: tích hợp process Linux và wrapper detection.
  • src-tauri/src/images.rs: đọc pet frame từ cache Codex.
  • src-tauri/resources/: terminfo SIXEL đóng gói.

Quyền riêng tư

Deck không thêm telemetry hay tài khoản riêng. Dữ liệu terminal nằm trên máy; kết nối mạng đến từ agent CLI, MCP hoặc Cockpit mà người dùng tự cấu hình.

Nguồn và giấy phép

Tên và logo Claude, OpenAI Codex, Gemini thuộc chủ sở hữu tương ứng.

About

Gom cửa sổ terminal quản lý quy trình làm việc

Topics

developer-toolslinuxrusttauriterminaltypescriptxtermjs

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages