galaxy-code

v0.1.9

Published

11 days ago

Galaxy Code — AI-powered coding assistant CLI (Claude, Gemini, Ollama, Codex)

0High
0Medium
0Low

kevinbui210191

ai assistant cli code-generation galaxy claude gemini ollama productivity

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