galaxy-code

Galaxy Code CLI

Galaxy Code là một AI Agent CLI đa nhà cung cấp, được xây dựng với giao diện TUI tương tác — tương tự Claude Code nhưng hỗ trợ nhiều AI provider và có các tính năng context engineering nâng cao.

  ██████╗  █████╗ ██╗      █████╗ ██╗  ██╗██╗   ██╗
 ██╔════╝ ██╔══██╗██║     ██╔══██╗╚██╗██╔╝╚██╗ ██╔╝
 ██║  ███╗███████║██║     ███████║ ╚███╔╝  ╚████╔╝
 ██║   ██║██╔══██║██║     ██╔══██║ ██╔██╗   ╚██╔╝
 ╚██████╔╝██║  ██║███████╗██║  ██║██╔╝ ██╗   ██║
  ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝
                         C O D E

Yêu cầu người dùng

#	Yêu cầu	Trạng thái
1	Giao diện TUI tương tác như Claude Code	✅ Hoàn thành
2	Lệnh galaxy-code để khởi động CLI	✅ Hoàn thành
3	Lệnh galaxy-code config mở folder ~/.galaxy	✅ Hoàn thành
4	Hỗ trợ 5 AI providers: Claude, Gemini, Ollama, Codex, Manual	✅ Hoàn thành
5	Đọc file: PDF, DOCX, XLSX/XLS, CSV, MD, TXT và các file code	✅ Hoàn thành
6	Sub AI Agent tóm tắt URD (User Requirements Document)	✅ Hoàn thành
7	Sub AI Agent review code sau khi AI viết xong (/review)	✅ Hoàn thành
8	Context Engineering: JIT Retrieval, Compaction, Structured Notes	✅ Hoàn thành
9	Config lưu tại ~/.galaxy/config.json (macOS)	✅ Hoàn thành
10	Ba màn hình: Chat (F1), Plan (F2), Settings (F3)	✅ Hoàn thành

Cài đặt

Yêu cầu hệ thống

• Node.js >= 18
• pnpm >= 8

Cài đặt toàn cục

# Clone hoặc tải về project
cd artifacts/galaxy-cli

# Cài đặt dependencies
pnpm install

# Link binary toàn cục
pnpm link --global

Sau khi link, bạn có thể gõ từ bất kỳ đâu:

galaxy-code          # Khởi động TUI
galaxy-code config   # Mở thư mục config
galaxy-code urd <file>  # Phân tích URD

Sử dụng

Khởi động TUI

galaxy-code

Giao diện TUI sẽ mở ra với ba màn hình điều hướng bằng phím tắt:

Phím	Chức năng
F1 hoặc Alt+1	Màn hình Chat
F2 hoặc Alt+2	Màn hình Plan (các bước nhiệm vụ)
F3 hoặc Alt+3	Màn hình Settings
Ctrl+K	Xóa lịch sử chat (reset cả session tracker)
? hoặc H	Bật/tắt Help
Q hoặc Ctrl+C	Thoát

Slash Commands

Gõ trực tiếp vào ô chat:

Lệnh	Chức năng
/review	Kích hoạt thủ công Code Reviewer Sub Agent — AI sẽ review toàn bộ file đã được viết/sửa trong session hiện tại
/diff	Xem toàn bộ thay đổi của tất cả file AI đã sửa trong session (unified diff)
/diff <file>	Xem chi tiết thay đổi của một file cụ thể, ví dụ: /diff src/auth.ts
/revert <file>	Hoàn tác file về trạng thái trước khi AI sửa. Nếu AI tạo file mới → xóa file. Nếu AI sửa file cũ → khôi phục nội dung cũ

Mở thư mục cấu hình

galaxy-code config

Lệnh này sẽ:

• In ra đường dẫn thư mục config
• Liệt kê các file trong thư mục
• Tự động mở File Manager (nếu có GUI)

Vị trí config theo hệ điều hành:

• macOS: ~/.galaxy/
• Linux: ~/.config/galaxy/
• Windows: %APPDATA%\galaxy\

Tóm tắt URD (User Requirements Document)

galaxy-code urd ./requirements.pdf
galaxy-code urd ./spec.docx
galaxy-code urd ./requirements.md

Sub AI Agent sẽ:

• Đọc và phân tích file tài liệu
• Dùng AI provider đang cấu hình để tóm tắt
• Xuất ra cấu trúc gồm: Overview, Functional Requirements, Non-Functional Requirements, Stakeholders, Acceptance Criteria, Risks, Priority Recommendations
• Lưu kết quả tại ~/.galaxy/urd-summaries/<tên-file>-summary-<timestamp>.md
• Thêm key points vào ~/.galaxy/NOTE.md để dùng trong session tiếp theo

Cấu trúc thư mục ~/.galaxy/

~/.galaxy/
├── config.json          # Cấu hình agents, API keys
├── NOTE.md              # Ghi chú ngữ cảnh persistent (Structured Notes)
└── urd-summaries/       # Các bản tóm tắt URD được lưu tự động
    └── spec-summary-2026-03-11T10-30-00.md

Cấu hình AI Providers

Chỉnh sửa ~/.galaxy/config.json:

{
  "agent": [
    {
      "type": "manual",
      "apiKey": ""
    },
    {
      "type": "claude",
      "model": "claude-sonnet-4-5-20250929",
      "apiKey": "sk-ant-..."
    },
    {
      "type": "gemini",
      "model": "gemini-2.5-flash",
      "apiKey": "AIza..."
    },
    {
      "type": "codex",
      "model": "gpt-4o",
      "apiKey": "sk-..."
    },
    {
      "type": "ollama",
      "model": "llama3.2",
      "baseUrl": "http://localhost:11434"
    }
  ]
}

Hoặc chỉnh sửa trực tiếp trong Settings (F3) của TUI.

Các AI Provider hỗ trợ

Provider	Mô tả	API Key
Manual	Tự động kết nối Ollama tại localhost:11434	Không cần
Claude	Anthropic Claude (claude-sonnet-4-5, claude-opus)	ANTHROPIC_API_KEY
Gemini	Google Gemini (gemini-2.5-flash, gemini-pro)	GOOGLE_API_KEY
Codex	OpenAI GPT-4o, GPT-4	OPENAI_API_KEY
Ollama	Local LLM (llama3.2, mistral, phi3, ...)	Không cần

Công nghệ sử dụng

Core Framework

Package	Phiên bản	Mục đích
@rezi-ui/core	0.1.0-alpha.59	TUI rendering engine core
@rezi-ui/node	0.1.0-alpha.59	Node.js backend cho Rezi
@rezi-ui/native	0.1.0-alpha.59	Native C++ addon cho terminal rendering

Rezi (https://rezitui.dev) là framework TUI TypeScript hiện đại, tương tự React nhưng cho terminal. Sử dụng:

• Worker thread architecture (rendering trong worker thread riêng biệt)
• Native C++ addon cho hiệu suất cao
• Reactive state management
• Route-based navigation

Document Parsing

Package	Phiên bản	Mục đích
mammoth	^1.11.0	Đọc file DOCX/DOC → plain text
pdf-parse	^1.1.1	Đọc file PDF → plain text
xlsx	^0.18.5	Đọc file Excel (XLSX/XLS/XLSM) → bảng markdown có cấu trúc

Runtime & Build

Package	Phiên bản	Mục đích
tsx	^4.21.0	TypeScript execution (ts-node alternative)
typescript	~5.9.2	Ngôn ngữ chính
Node.js	>=18	Runtime

Kiến trúc

artifacts/galaxy-cli/
├── src/
│   ├── cli.ts              # Entry point: xử lý argv (config, urd, TUI)
│   ├── main.ts             # TUI app khởi tạo (Rezi createNodeApp)
│   ├── types.ts            # TypeScript types chung
│   ├── theme.ts            # Themes: Nord, Dark, Light
│   │
│   ├── agents/
│   │   ├── runner.ts           # Điều phối AI call + tool execution + track file writes
│   │   ├── claude.ts           # Anthropic Claude driver (streaming)
│   │   ├── gemini.ts           # Google Gemini driver (streaming)
│   │   ├── ollama.ts           # Ollama local driver (streaming)
│   │   ├── codex.ts            # OpenAI Codex/GPT driver (streaming)
│   │   ├── manual.ts           # Manual/auto-Ollama driver
│   │   ├── urd-agent.ts        # Sub Agent: phân tích URD document
│   │   ├── code-reviewer.ts    # Sub Agent: review code sau khi AI viết xong
│   │   ├── session-tracker.ts  # Ghi lại file được viết/sửa trong session
│   │   └── types.ts            # AgentDriver interface + system prompt
│   │
│   ├── config/
│   │   ├── manager.ts      # Load/save config + platform path detection
│   │   └── types.ts        # GalaxyConfig, AgentConfig interfaces
│   │
│   ├── context/
│   │   ├── notes.ts        # Structured Notes: load/save ~/.galaxy/NOTE.md
│   │   └── compaction.ts   # Context Compaction: tóm tắt khi >40 messages
│   │
│   ├── helpers/
│   │   ├── keybindings.ts  # Ánh xạ phím → lệnh
│   │   └── state.ts        # State management + reducers
│   │
│   ├── screens/
│   │   ├── index.ts        # Route definitions cho Rezi
│   │   ├── chat.ts         # Màn hình Chat (F1)
│   │   ├── plan.ts         # Màn hình Plan (F2)
│   │   ├── settings.ts     # Màn hình Settings (F3)
│   │   └── shell.ts        # Shell command execution helper
│   │
│   └── tools/
│       ├── file-tools.ts       # File tools: read, write, edit, grep (cross-platform), head, tail
│       └── document-reader.ts  # Document parser: PDF, DOCX, XLSX/XLS, CSV, MD, TXT
│
├── package.json
├── tsconfig.json
└── README.md

Tính năng Context Engineering

1. Just-in-Time (JIT) Retrieval

Thay vì load toàn bộ file vào context, AI sử dụng các tool để chỉ lấy phần cần thiết:

read_file(path, maxLines=200, offset=0)   # Đọc từng phần (có offset + giới hạn dòng)
grep(pattern, path, contextLines=2)       # Tìm kiếm regex (native grep macOS/Linux, Node.js trên Windows)
head(path, lines=50)                      # Đọc N dòng đầu
tail(path, lines=50)                      # Đọc N dòng cuối
list_dir(path)                            # Khám phá cấu trúc thư mục
edit_file(path, old_string, new_string)   # Sửa phẫu thuật — chỉ thay đúng đoạn cần sửa
read_document(path)                       # Đọc PDF / DOCX / XLSX / CSV — trả về bảng markdown có cấu trúc

2. Context Compaction

Khi hội thoại vượt quá 40 tin nhắn, hệ thống tự động:

• Tóm tắt 30 tin nhắn đầu thành một summary message
• Giữ nguyên 10 tin nhắn gần nhất
• Giải phóng context window cho tiếp tục

3. Structured Notes (NOTE.md)

AI có thể ghi lại các thông tin quan trọng vào ~/.galaxy/NOTE.md:

• Ghi chú được load vào đầu mỗi session
• Persistent qua các lần khởi động
• URD summaries tự động append vào NOTE.md

Sub AI Agent: URD Analyzer

URD Agent là một sub-agent chuyên biệt, hoạt động độc lập với TUI:

galaxy-code urd ./requirements.pdf

Luồng hoạt động:

• Đọc file (PDF/DOCX/MD/TXT) bằng document-reader
• Truncate tối đa 60.000 ký tự cho context window
• Tự động chọn AI provider tốt nhất đang có (theo thứ tự: Claude > Gemini > Ollama > Codex > Manual)
• Gửi document với system prompt chuyên biệt của senior requirements analyst
• Stream kết quả ra terminal
• Lưu tóm tắt vào ~/.galaxy/urd-summaries/
• Append key points vào NOTE.md để dùng trong TUI session

Output bao gồm:

• Document Overview
• Key Functional Requirements
• Non-Functional Requirements
• Stakeholders
• Acceptance Criteria
• Risks & Assumptions
• Priority Recommendations (top 3)

Sub AI Agent: Code Reviewer

Code Reviewer là một sub-agent chuyên biệt, tự động kích hoạt sau khi AI viết hoặc chỉnh sửa code trong session.

Cách hoạt động

Trong suốt một session, hệ thống Session Tracker âm thầm ghi lại mọi file được AI tạo ra hoặc sửa đổi (qua write_file hoặc edit_file). Khi AI hoàn thành xong công việc, Code Reviewer tự động đọc lại toàn bộ danh sách file đó và gửi cho một AI instance riêng biệt — đóng vai senior code reviewer — để phân tích.

AI viết/sửa file  →  Session Tracker ghi nhận
                                  ↓
           AI hoàn thành nhiệm vụ / gõ /review
                                  ↓
           Code Reviewer đọc tất cả file trong session
                                  ↓
           Gửi cho AI (cùng provider) với prompt reviewer
                                  ↓
           Kết quả hiển thị trực tiếp trong Chat

Kích hoạt

Cách	Mô tả
Tự động	Sau mỗi lần AI viết file và hoàn thành nhiệm vụ
Thủ công	Gõ /review trong ô chat bất cứ lúc nào

Khi bạn gõ Ctrl+K để xóa chat, session tracker cũng được reset — file counter trở về 0.

Định dạng kết quả

Code Reviewer trả về phân tích theo chuẩn sau, hiển thị ngay trong cửa sổ Chat:

🔍 Code Review Result (N files)

- [CRITICAL] `src/auth.ts:42` — Token không được hash trước khi lưu DB. Dùng bcrypt.hash() thay vì lưu plain text.
- [WARNING]  `src/api.ts:88`  — Thiếu xử lý trường hợp response.data là null, có thể gây crash runtime.
- [INFO]     `src/utils.ts`   — Hàm formatDate() có thể dùng Intl.DateTimeFormat thay vì xử lý thủ công.

⚠️ Issues found — 1 critical, 1 warning (cần sửa trước khi ship)

Mức độ	Ý nghĩa
[CRITICAL]	Lỗi nghiêm trọng — bug, security hole, crash runtime. Phải sửa ngay
[WARNING]	Vấn đề cần chú ý — edge case, code quality, có thể gây lỗi sau
[INFO]	Gợi ý cải thiện — tùy chọn, không bắt buộc
✅ LGTM	Không có vấn đề gì, code sạch

Đặc điểm

• Dùng cùng AI provider với agent chính (không cần cấu hình thêm)
• Hỗ trợ mọi ngôn ngữ lập trình — AI đọc được tất cả
• Phân tích cross-file: phát hiện mâu thuẫn giữa các file với nhau
• Giới hạn 8.000 ký tự/file để tránh vượt context window

Màn hình TUI

Chat (F1)

• Nhập prompt và gửi đến AI agent đang active
• Hiển thị streaming response theo thời gian thực
• Hiển thị tool calls (read_file, grep, v.v.) và kết quả
• Cuộn lịch sử hội thoại

Plan (F2)

• Hiển thị các task step được AI tự động extract từ response
• Tracking trạng thái: pending → running → done/failed
• Hỗ trợ hiển thị kế hoạch nhiều bước

Settings (F3)

• Chuyển đổi giữa các AI provider
• Nhập/cập nhật API keys
• Chọn model cho từng provider
• Cài đặt auto-update

Phát triển

# Chạy trong dev mode
pnpm dev

# Type check
pnpm typecheck

# Chạy CLI entry point
pnpm start

License

MIT © Galaxy Code Project