CodeWhale - Terminal coding agent mã nguồn mở cho mọi LLM

Tóm tắt nhanh (Key Takeaways)

CodeWhale là “coding agent trong terminal” – một TUI và CLI giúp AI đọc code, chỉnh sửa file, chạy lệnh, kiểm tra kết quả, tự lập kế hoạch và tự sửa lỗi khi có failure.

Công cụ open-source (MIT, Rust), chạy trực tiếp trên máy bạn, ưu tiên model mở (DeepSeek, open-weight) nhưng cũng hỗ trợ Claude, GPT, Kimi, GLM, OpenRouter, Hugging Face, DeepInfra, vLLM, SGLang, Ollama… qua cùng một runtime và bộ tool.

Cài đặt cực ngắn gọn: npm install -g codewhale (Node 18+), wrapper sẽ tự tải binary đã được verify SHA-256 từ GitHub Releases; người dùng nâng cao có thể dùng Cargo, Docker, Nix, Scoop hoặc tải binary trực tiếp.

CodeWhale có safety model nghiêm túc: 3 mode (Plan/Agent/YOLO), tool qua cổng phê duyệt, sandbox cấp hệ điều hành (Seatbelt, Landlock+seccomp, bubblewrap) và rollback bằng snapshot Git riêng, không chạm vào .git của repo.

Ngoài TUI tương tác, CodeWhale có chế độ headless codewhale exec để tự động hoá fix bug, refactor, chạy test trong CI/CD, cron job hoặc tích hợp vào n8n/automation pipeline.

CodeWhale tự gọi mình là “the terminal coding agent for any model — open models first”: bạn trỏ nó vào một model và một project, phần còn lại agent lo. Nó đọc code, đề xuất thay đổi, áp dụng patch, chạy lệnh, xem log, lập kế hoạch nhiều bước và tự backtrack khi có lệnh fail.

Dự án bắt đầu dưới tên deepseek-tui, tập trung quanh workflow DeepSeek, sau đó cộng đồng đóng góp mạnh, multi-provider ra đời và cái tên CodeWhale xuất hiện để phản ánh đúng tầm của một agent harness đa model. Mã nguồn viết bằng Rust, MIT license, repo public tại: https://github.com/Hmbown/CodeWhale

Vì sao CodeWhale đáng để bạn dùng trong terminal?

Khách với “chat trong browser”, CodeWhale đặt agent vào đúng ngữ cảnh công việc: terminal + repo thật. Bạn không cần copy/paste file, không phải dán log vào web; agent đọc trực tiếp từ filesystem, chạy test bằng lệnh thực, hiểu cấu trúc mono-repo và có thể rollback từng bước.

Với developer thích self-host hoặc đa provider, CodeWhale là một layer ổn định phía trên LLM: bạn đổi provider/model (DeepSeek, Ollama, vLLM, OpenRouter…) mà không phải viết lại tool hoặc script xung quanh, vì tất cả đi qua cùng một runtime và set tools.

Kiến trúc TUI, CLI và fleet

CodeWhale bao gồm hai binary chính: codewhale (dispatcher CLI) và codewhale-tui (runtime TUI tương tác). Lệnh codewhale là entry point: nó xử lý auth, config, profile, rồi forward prompt hoặc subcommand sang TUI runtime để thực thi.

Ngoài session tương tác, CodeWhale còn có Fleet – control plane cho multi-worker, multi-task, cho phép bạn chạy nhiều worker headless song song, lưu ledger .codewhale/fleet.jsonl để resume sau khi máy ngủ, terminal crash hoặc restart. Điều này rất phù hợp cho batch refactor, mass migration, hoặc nhiều job CI dài.

Hỗ trợ provider LLM: Từ cloud đến self‑hosted

Danh sách provider của CodeWhale khá ấn tượng:

Open models hosted: deepseek (default), openrouter, huggingface (Inference Providers), deepinfra, together, fireworks, novita, siliconflow, moonshot (Kimi), zai (GLM), minimax, volcengine (Ark), atlascloud, qianfan, wanjie-ark, openmodel…
Self-hosted: vllm, sglang, ollama chạy trên localhost – không cần API key, rất hợp cho cluster nội bộ hoặc lab R&D.
Closed providers native: anthropic (Claude) với adapter messages riêng, openai-compatible cho mọi gateway hỗ trợ schema Chat Completions.

Bạn chỉ cần chọn provider + model, phần RouteResolver của CodeWhale sẽ resolve thành một route “thật” gồm endpoint, wire protocol, context limit và giá, để mọi thứ về context budget và cost đều dựa trên dữ liệu không bịa đặt.

Chuẩn bị môi trường trước khi cài đặt

Trước khi cài, bạn nên rà lại vài điểm:

Hệ điều hành: Linux (x64, arm64, riscv64), macOS (Intel + Apple Silicon) và Windows x64 đều có binary prebuilt.
Node.js: nếu dùng npm wrapper, cần Node 18+ để npm install -g codewhale hoạt động.
Rust: nếu định build từ source hoặc cài qua Cargo, cần Rust 1.88+ và toolchain C cơ bản (build-essential, pkg-config, libdbus-1-dev trên Debian/Ubuntu).

Với Linux ARM64 (Raspberry Pi, AWS Graviton…), từ v0.8.8 trở lên đã có binary chính thức, không còn lỗi “Unsupported architecture: arm64” khi cài qua npm.

Cài đặt CodeWhale bằng npm (cách nhanh nhất)

Cách ngắn gọn và được khuyến nghị là dùng npm global:

npm install -g codewhale
codewhale --version

Gói npm đóng vai trò wrapper: sau khi cài, nó tự tải cặp binary codewhale và codewhale-tui tương ứng với platform của bạn từ GitHub Releases, verify SHA-256 rồi đặt lên PATH. Bạn không phải tự chọn file .tar.gz hay .zip thủ công.

Nếu bạn ở mainland China hoặc đường đến npm/GitHub chậm, có thể set registry mirror và environment để tăng tốc, như sử dụng registry.npmmirror.com hoặc mirror cho Rust/Cargo theo hướng dẫn trong INSTALL.md.

Các cách cài đặt khác: Cargo, Docker, Nix, Scoop

Ngoài npm, CodeWhale hỗ trợ nhiều đường cài để phù hợp từng style dev:

Cargo (Linux/macOS, mọi kiến trúc Tier‑1 Rust)

cargo install codewhale-cli --locked
cargo install codewhale-tui --locked
codewhale --version

Lưu ý cần cài cả hai crate, nếu không sẽ bị lỗi MISSING_COMPANION_BINARY.

Docker / GHCR

docker run --rm -it \
  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
  -v ~/.deepseek:/home/codewhale/.deepseek \
  ghcr.io/hmbown/codewhale:latest

Image chứa cả dispatcher và TUI, phù hợp khi muốn tách biệt hoàn toàn khỏi môi trường host.

Nix

nix run github:Hmbown/CodeWhale

Nix sẽ build codewhale-tui rồi start dispatcher; bạn có thể thêm vào flake.nix để đóng gói thành system package.

Windows Scoop hoặc tải binary thủ công: Scoop đã có package codewhale, hoặc bạn có thể tải codewhale-windows-x64.zip and install.bat từ trang Releases để cài vào %USERPROFILE%\bin.

Cấu hình provider và API key lần đầu

Sau khi cài xong, bước tiếp theo là khai báo provider và key (nếu dùng dịch vụ hosted).

Một quy trình tối thiểu:

codewhale auth set --provider deepseek
codewhale auth status
codewhale doctor

codewhale auth set lưu API key vào ~/.codewhale/config.toml (hoặc path kế thừa ~/.deepseek/config.toml tuỳ version).
auth status cho bạn xem provider đang active, key lấy từ đâu (config, keyring, env), không lộ key.
doctor kiểm tra auth, provider, runtime, PATH và gợi ý fix nếu có vấn đề.

Config có thể override qua file TOML riêng hoặc env: codewhale --config và biến CODEWHALE_PROVIDER, CODEWHALE_MODEL, CODEWHALE_BASE_URL giúp bạn chuyển profile một cách linh hoạt.

Lần chạy đầu tiên: TUI, mode và lệnh cơ bản

Khi mọi thứ ổn, chỉ cần chạy:

codewhale

Bạn sẽ vào TUI của CodeWhale, nơi có transcript, sidebar Work/Tasks/Agents, footer hiển thị model, usage, cost và mode hiện tại. Một số lệnh slash hữu ích:

/provider mở dashboard provider, cho thấy trạng thái auth, route default, cost meter; có thể truyền arg như /provider nvidia-nim để đổi ngay giữa chừng.
/model chọn model và “reasoning effort” (low/medium/high/max).
/restore rollback một turn dựa trên snapshot Git bên ngoài repo chính.
/fleet, /skills, /config, /statusline để quản lý fleet, workflow, runtime và HUD.

Có ba mode an toàn: Plan (chỉ đọc, không thay đổi file), Agent (thực thi nhưng hỏi trước khi dùng tool nguy hiểm) và YOLO (auto-approve), chuyển bằng Tab hoặc /mode.

Headless mode cho CI, cron job và automation

Bạn không phải lúc nào cũng ngồi nhìn TUI; CodeWhale có headless mode cho script:

codewhale exec \
  --allowed-tools read_file,exec_shell \
  --max-turns 10 \
  "fix the failing test"

Ở đây, bạn mô tả goal ở dạng natural language, giới hạn tool được dùng (VD: chỉ đọc file và chạy shell), giới hạn số turn; phần còn lại agent lo. Đây là mảnh ghép hoàn hảo để nhúng vào:

CI pipeline (GitHub Actions, GitLab CI, Jenkins) để tự sửa test, format hoặc refactor nhỏ.
n8n, cron job hoặc server tự host cho các tác vụ bảo trì định kỳ.

Nhờ cùng runtime với TUI, bạn có thể debug một flow bằng TUI trước, sau đó chuyển qua exec để chạy tự động.

Safety: Sandbox, phê duyệt và rollback

Vì CodeWhale chỉnh sửa file và chạy lệnh, dự án đầu tư khá kỹ vào safety:

Three modes: Plan (read-only), Agent (thực thi có hỏi), YOLO (auto-approve), giúp bạn tuỳ mức trust với agent theo repo.
Approval-gated tools: file .codewhale/hooks.toml định nghĩa tool nào được phép, tool nào phải xin phép hoặc bị chặn.
OS sandboxing: dùng Seatbelt trên macOS, Landlock + seccomp + bubblewrap trên Linux nơi có thể; Windows đang đi theo hướng containment tree, không marketing quá đà.
Rollback: mọi chỉnh sửa được snapshot vào “side-git” ngoài .git của repo, cho phép /restore rollback từng turn mà không phá history thật của project.

Với developer làm việc trên codebase quan trọng (prod, core infra), bạn có thể ép sandbox mode read-only hoặc workspace-write, set approval_policy phù hợp để hạn chế rủi ro.

Tối ưu workflow với CodeWhale cho developer Việt Nam

Nếu bạn đã quen với Docker, n8n, self-host LLM:

Chạy DeepSeek hoặc model open-weight trên vLLM / SGLang / Ollama nội bộ và cho CodeWhale trỏ tới http://localhost – không key, không phụ thuộc cloud.
Dùng profile để tách environment: profiles.work (provider công ty), profiles.home (lab cá nhân), profiles.ollama (LLM local), rồi chuyển nhanh bằng codewhale --profile name.
Tích hợp VS Code extension và bridge như Telegram/Feishu để nhận log, status hoặc trigger run từ xa.

Để bắt đầu với CodeWhale, bạn có thể truy cập:

GitHub repo chính thức: https://github.com/Hmbown/CodeWhale
Website/documentation: https://codewhale.net

Chỉ với một lệnh npm install -g codewhale, bạn đã có một coding agent mạnh, an toàn, đa provider, có thể nhúng sâu vào terminal, CI, Docker và cả stack self-hosted LLM hiện có. Từ đó, tuỳ bạn decide: dùng CodeWhale như “pair programmer” trong TUI, hay như một “worker đội AI” âm thầm xử lý backlog trong background.