Oracle CLI: Gọi GPT-5 Pro với đúng context khi bạn đang mắc kẹt với code
Tóm tắt nhanh
- Oracle là CLI mã nguồn mở (MIT) do Peter Steinberger (steipete) tạo ra, giải quyết một vấn đề cụ thể: khi đang debug hoặc review code, làm thế nào để hỏi một AI mạnh hơn với đúng context cần thiết – không phải copy-paste thủ công từng file.
- Oracle đóng gói prompt và danh sách file bạn chỉ định thành một bundle Markdown có cấu trúc, rồi gửi thẳng đến model qua API hoặc qua browser (không cần API key).
- Hỗ trợ multi-model trong một lần chạy: có thể truy vấn GPT-5.1 Pro, Gemini 3 Pro và Claude Opus 4.1 cùng lúc để so sánh kết quả, với tổng hợp chi phí token từng model.
- GPT-5 Pro chạy ở chế độ background theo mặc định – Oracle lưu session lại để bạn reattach sau khi model hoàn tất, không cần ngồi chờ.
- Tích hợp được vào workflow qua MCP server (
oracle-mcp), Codex skill, AGENTS.md/CLAUDE.md, và Azure/OpenRouter endpoint.- Chạy ngay không cần cài đặt:
npx -y @steipete/oracle --help
Có một tình huống quen thuộc với bất kỳ developer nào đang làm việc với AI agent: bạn đang debug một lỗi khó, AI hiện tại trong IDE không đủ context để đưa ra câu trả lời hữu ích, và bạn biết rằng GPT-5 hay Claude Opus sẽ xử lý được nếu chỉ có đủ thông tin. Nhưng copy từng file lên ChatGPT thủ công vừa mất thời gian, vừa dễ thiếu sót.
Oracle là câu trả lời của steipete cho vấn đề đó: một CLI đơn giản, đóng gói prompt và file cần thiết thành một bundle hoàn chỉnh, rồi gửi đến đúng model bạn muốn – qua API hoặc qua browser – chỉ với một lệnh.
Oracle là gì và tại sao nó hữu ích?
Oracle không phải là một AI coding agent hoàn chỉnh như Cursor hay Claude Code. Nó là một context bundler và dispatcher: nhận prompt từ bạn, thu thập đúng các file liên quan theo glob pattern, lắp ráp thành một bundle Markdown có cấu trúc, rồi gửi đến model AI mạnh nhất bạn có quyền truy cập.
Lý do điều này hữu ích hơn copy-paste thủ công:
- Bạn chỉ định file bằng glob (
src/**/*.ts,!**/*.test.ts) thay vì mở từng file. - Bundle được tạo nhất quán, có header và metadata rõ ràng, giúp model đọc hiểu tốt hơn.
- Session được lưu lại – bạn có thể xem lại câu trả lời, replay hoặc gửi lại với prompt khác mà không cần bundle lại từ đầu.
- Dry run cho phép xem trước chính xác những gì sẽ được gửi trước khi tiêu token.
Model mặc định là GPT-5.1 Pro (alias đến GPT-5.2 Pro trên API). Oracle cũng hỗ trợ GPT-5.1, GPT-5.1 Codex, GPT-5.2, Gemini 3 Pro, Claude Sonnet 4.5, Claude Opus 4.1 và bất kỳ model nào trên OpenRouter.
Cài đặt Oracle
Oracle yêu cầu Node.js 22 trở lên.
Cài đặt toàn cục qua npm:
npm install -g @steipete/oracleHomebrew (macOS):
brew install steipete/tap/oracleChạy không cài đặt qua npx:
npx -y @steipete/oracle --helpCách npx phù hợp để dùng thử nhanh hoặc tích hợp trong script CI mà không muốn cài global.
Cấu hình API keys
Oracle tự động chọn engine dựa trên biến môi trường. Nếu có OPENAI_API_KEY, Oracle dùng API mode. Nếu không, nó chuyển sang browser mode.
export OPENAI_API_KEY="sk-..." # GPT-5.x
export GEMINI_API_KEY="..." # Gemini 3 Pro
export ANTHROPIC_API_KEY="sk-ant-..." # Claude Sonnet 4.5 / Opus 4.1Các key này cũng có thể đặt trong config file ~/.oracle/config.json (JSON5, cho phép trailing comma và comment):
{
model: "gpt-5.1-pro",
engine: "api",
filesReport: true,
browser: {
chatgptUrl: "https://chatgpt.com/g/g-p-.../project"
}
}Hướng dẫn sử dụng cơ bản
Review code với context đính kèm
Tình huống phổ biến nhất: bạn muốn review toàn bộ data layer TypeScript để tìm schema drift.
# Gửi qua API (cần OPENAI_API_KEY)
oracle -p "Review the TypeScript data layer for schema drift" \
--file "src/**/*.ts,!**/*.test.ts"
# Render bundle và copy vào clipboard để dán thủ công vào ChatGPT
oracle --render --copy \
-p "Review the TS data layer for schema drift" \
--file "src/**/*.ts,*/test.ts"Flag --render in ra bundle đã lắp ráp. Flag --copy copy bundle vào clipboard. Kết hợp cả hai là fallback hoàn hảo khi không có API key hoặc khi automation bị chặn.
Flag --files-report hiển thị chi tiết số token từng file:
oracle -p "Analyze storage adapters" \
--file src/storage/ \
--files-reportXem trước trước khi gửi (dry run)
Trước khi tiêu token, luôn nên kiểm tra Oracle sẽ gửi gì:
oracle --dry-run summary \
-p "Check release notes" \
--file docs/release-notes.mdChế độ --dry-run full in ra toàn bộ bundle. --dry-run json xuất dưới dạng JSON để xử lý tiếp theo.
Chạy nhiều model cùng lúc
Oracle hỗ trợ multi-model trong một lần chạy – kết quả và chi phí token của từng model được tổng hợp:
oracle -p "Cross-check the data layer assumptions" \
--models gpt-5.1-pro,gemini-3-pro,claude-4.5-sonnet \
--file "src/**/*.ts"Bạn cũng có thể kết hợp built-in model với OpenRouter ID:
oracle -p "Review API design" \
--models gpt-5.1-pro,minimax/minimax-m2 \
--file src/api/Kết quả từng model được lưu riêng khi dùng --write-output:
oracle -p "Architecture review" \
--models gpt-5.1-pro,claude-4.1-opus \
--file src/ \
--write-output review.md
# Tạo ra: review.md.gpt-5.1-pro và review.md.claude-4.1-opusChế độ browser: không cần API key
Khi không có API key, hoặc khi muốn dùng model Pro qua web mà không tốn thêm phí API, Oracle hỗ trợ browser mode:
# Mở ChatGPT trong trình duyệt và gửi bundle
oracle --engine browser \
-p "Walk through the UI smoke test" \
--file "src/**/*.ts"
# Gemini browser mode - dùng cookie từ gemini.google.com trong Chrome
oracle --engine browser --model gemini-3-pro \
-p "Analyze the API structure" \
--file src/api/GPT-5 Pro chạy lâu thường timeout trong browser. Oracle hỗ trợ auto-reattach để tự động polling lại tab ChatGPT sau khi model hoàn tất:
oracle --engine browser \
--browser-timeout 6m \
--browser-auto-reattach-delay 30s \
--browser-auto-reattach-interval 2m \
-p "Run the long UI audit" \
--file "src/**/*.ts"Quản lý session
GPT-5.1 Pro và các model nặng chạy background mode theo mặc định – Oracle detach ngay và trả lại terminal trong khi model vẫn đang xử lý. Để theo dõi và lấy kết quả:
# Xem tất cả session trong 72 giờ qua
oracle status --hours 72
# Xem nội dung của một session cụ thể
oracle session <id> --render
# Chạy lại một session với cùng bundle
oracle restart <id>Tất cả session được lưu tại ~/.oracle/sessions. Override bằng biến môi trường ORACLE_HOME_DIR. Để dọn dẹp session cũ:
oracle status --clear --hours 168Nếu muốn block terminal cho đến khi model trả về kết quả:
oracle --wait -p "Quick review" --file src/utils.tsTích hợp với MCP và Codex
MCP server:
Oracle cung cấp MCP server qua lệnh oracle-mcp, cho phép AI agent gọi Oracle như một tool:
npx -y @steipete/oracle oracle-mcpCấu hình trong Cursor qua .cursor/mcp.json:
{
"oracle": {
"command": "oracle-mcp",
"args": []
}
}Codex skill:
Oracle đi kèm một Codex skill sẵn dùng:
mkdir -p ~/.codex/skills
cp -R skills/oracle ~/.codex/skills/oracleSau đó tham chiếu trong AGENTS.md hoặc CLAUDE.md để agent tự động sử dụng Oracle khi gặp bug khó:
- Oracle bundles a prompt plus the right files so another AI (GPT-5 Pro + more) can answer.
Use when stuck/bugs/reviewing.
- Run `npx -y @steipete/oracle --help` once per session before first use.TUI tương tác:
Nếu thích giao diện dòng lệnh tương tác hơn:
oracle tuiKhi nào nên dùng Oracle?
Oracle phù hợp nhất với những tình huống sau:
- Bạn đang debug một lỗi khó mà AI hiện tại trong IDE không đủ context để giải quyết – Oracle bundle đúng các file liên quan và hỏi model mạnh hơn.
- Review kiến trúc hoặc schema trước khi merge – gửi toàn bộ data layer cho GPT-5 Pro để phát hiện vấn đề tiềm ẩn.
- So sánh góc nhìn từ nhiều model – chạy multi-model với cùng một prompt và context để có cái nhìn đa chiều.
- Cần “ý kiến thứ hai” từ model Pro mà không muốn rời khỏi terminal hay copy-paste thủ công.
- Tích hợp trong agentic pipeline – dùng MCP hoặc Codex skill để agent tự quyết định khi nào cần escalate lên Oracle.
Oracle không thay thế agent IDE như Cursor hay Claude Code. Nó là lớp escalation: khi agent hiện tại không đủ để xử lý, Oracle đưa vấn đề lên model mạnh nhất hiện có với toàn bộ context cần thiết.
Oracle giải quyết một vấn đề cụ thể và giải quyết tốt: bundle context đúng cách rồi gửi đến đúng model. Không phức tạp hơn mức cần thiết, không cố gắng thay thế toàn bộ workflow hiện có. Sự hỗ trợ multi-model, dry run, session management và tích hợp MCP/Codex biến nó thành một công cụ thực dụng trong bộ kit của developer đang làm việc với AI agent hàng ngày.
