# ThinkRail: IDE cho AI agent, nhớ dự án qua spec — hướng dẫn cài đặt và dùng

> ThinkRail là một IDE lấy AI agent làm trung tâm, do JetBrains phát hành mã nguồn mở. Nó chạy agent `pi` trong các workspace git tách biệt và lưu kiến thức dự án vào các file SPEC.md để agent nhớ lâu. Cài bằng một dòng lệnh hoặc tải bản desktop, không khó, nhưng bạn cần có sẵn git và một nhà cung cấp mô hình AI.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-08-10 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/thinkrail-ide-ai-agent-spec-huong-dan-cai-dat-va-dung

ThinkRail là một IDE (môi trường lập trình) dựng quanh AI agent, do JetBrains phát hành mã nguồn mở theo giấy phép Apache-2.0. Thay vì chỉ có khung chat bên cạnh trình soạn code, ThinkRail cho agent làm việc trong các workspace riêng, có biên tập code, terminal, kế hoạch chung và một đồ thị tài liệu mô tả dự án của bạn.

Vấn đề nó giải quyết khá quen thuộc: mỗi lần mở một phiên chat mới, AI lại quên dự án của bạn. ThinkRail giữ ý định của dự án trong các file `SPEC.md` nằm cạnh code. Agent đọc, tìm và cập nhật chúng, nên phiên sau nó vẫn hiểu bối cảnh. Đó là lý do tác giả nói đây là IDE «càng dùng càng tốt hơn».

Repo hiện có khoảng 8205 sao và 521 fork, vẫn được cập nhật trong 3 tháng gần đây. Bài này hợp với lập trình viên mới, người làm sản phẩm hoặc văn phòng hay giao việc cho AI, và bất kỳ ai muốn thử nhiều hướng làm việc song song mà không sợ hỏng code gốc.

```repo
- repo | JetBrains/thinkrail
- kind | Ứng dụng
- desc | ThinkRail là IDE dựng quanh AI agent pi: mỗi việc một workspace git riêng, có đồ thị spec giúp agent nhớ dự án qua các phiên làm việc.
- stars | 8.2k
- lang | TypeScript
- license | Apache-2.0
```

## ThinkRail làm được gì

Mình tóm lại những tính năng đáng giá nhất, theo lợi ích thực tế.

- **Workspace tách biệt.** Bạn mở một repo git làm project, rồi tạo các workspace bằng `git worktree`. Mỗi workspace có nhánh và thư mục riêng, nên nhiều agent làm song song mà không đụng vào code gốc. Làm xong, bạn gộp phần muốn giữ và xoá phần còn lại. Thanh trên cùng cho thấy nhánh đang đứng đâu so với `origin` và tình trạng pull request. Với GitHub, bạn xem được kết quả CI, quyết định review, rồi merge ngay trong app.
- **IDE bao quanh agent.** Có tab soạn code Monaco, cây file hiện thay đổi git theo thời gian thực, terminal và xem trước Markdown có mục lục.
- **Chat mạnh.** Mỗi workspace mở được nhiều phiên làm việc, mỗi phiên một mô hình riêng. Bạn gửi prompt hoặc xếp hàng như câu nối tiếp, giao việc cho subagent, và cùng chỉnh một kế hoạch chung với agent.
- **Spec luôn cập nhật.** Đồ thị các file `SPEC.md` được agent đọc, tìm và duy trì qua các công cụ `spec_*`. Công cụ Specs hiển thị nó dạng cây, chỉ đọc.
- **Một ô tìm mọi thứ.** Bấm `⌘K` (hoặc chạm đôi phím Shift) để tìm chat, tin nhắn, workspace, file, spec và kế hoạch. Bấm `⌘⇧F` để tìm chữ trong file của workspace.
- **Chat không cần project.** Bạn hỏi, lên kế hoạch hay soạn nháp mà không cần repo. Mỗi chat có một thư mục tạm riêng. Khi việc thành thật, nút **Continue in workspace** nhờ agent viết bản bàn giao và mở chat mới trong workspace.
- **Skills.** ThinkRail nạp skill của `pi`, skill có sẵn trong project, và nhập được skill từ Claude, Codex cùng các agent code khác (bật trong Settings → Extensions).
- **Công cụ vượt ra ngoài shell.** Agent hỏi bạn câu trắc nghiệm có cấu trúc thay vì đoán, vẽ sơ đồ Mermaid, so sánh, xem trước file, và đưa mockup trước/sau khi đề xuất đổi giao diện.
- **MCP server.** Kết nối MCP server trong `mcp.json` của `pi` hoặc cấu hình trong Settings. Với lệnh gọi mà server không đánh dấu chỉ đọc, ThinkRail hỏi bạn trong chat trước. Server do repo tự khai báo sẽ tắt cho đến khi bạn duyệt.
- **Nhà cung cấp và mô hình của bạn.** Đăng nhập JetBrains AI hoặc dùng thông tin xác thực của `pi`. ThinkRail không có tài khoản riêng. Bạn cũng nối được máy chủ tương thích OpenAI như LiteLLM, sglang, vLLM, Ollama, LM Studio hay llama.cpp.
- **Cá nhân hoá.** Giao diện có tiếng Anh, Nhật, Nga, Trung giản thể, Tây Ban Nha và Trung phồn thể (Đài Loan). README chưa liệt kê tiếng Việt, nhưng bạn có thể thêm file ngôn ngữ vào `~/.thinkrail/locales`. Ngoài ra còn có chủ đề màu và phông chữ tuỳ chỉnh.
- **Bản desktop hoặc trình duyệt.** Dùng app native, hoặc lệnh `thinkrail` mở cùng app đó trong trình duyệt.

## Cần chuẩn bị gì

Theo README, bạn cần:

- **Hệ điều hành:** macOS 14 trở lên (Apple Silicon hoặc Intel), Windows x64, hoặc Linux x64 / ARM64.
- **Với Linux (bản desktop):** glibc 2.38 trở lên, GTK 3, WebKitGTK 4.1, Ayatana AppIndicator 3, librsvg 2, Ubuntu 24.04 hoặc mới hơn, thêm `libnotify-bin` nếu muốn có thông báo.
- **`git`** có trong PATH (bắt buộc cho bản CLI).
- **Một nhà cung cấp mô hình AI:** đăng nhập JetBrains AI trong app, hoặc dùng thông tin xác thực của nhà cung cấp riêng. Lần chạy đầu sẽ dẫn bạn qua bước kết nối.
- **Không cần repo có sẵn:** nút **Start a new project** tạo một repo git rỗng (mặc định dưới `~/thinkrail`).

README không nói gì về yêu cầu GPU hay dung lượng ổ đĩa, nên mình không đoán.

```note
ThinkRail không có tài khoản riêng, nhưng nhà cung cấp mô hình bạn nối vào có thể tính phí theo lượng dùng. Hãy xem chính sách giá của nhà cung cấp đó trước khi cho agent chạy nhiều phiên song song.
```

## Cài đặt từng bước

ThinkRail có hai dạng: bản desktop (trình cài đặt) và bản dòng lệnh `thinkrail`. Bạn chọn một trong hai.

```steps
- Chọn dạng cài | Bản desktop hoặc CLI `thinkrail`
- Chạy lệnh cài | Dùng install.sh (macOS/Linux) hoặc install.ps1 (Windows)
- Mở terminal mới | Để PATH nhận lệnh `thinkrail`
- Chạy thử | Gõ `thinkrail --version` rồi `thinkrail`
- Kết nối nhà cung cấp | Đăng nhập JetBrains AI hoặc dùng key riêng, rồi chọn project
```

### Cách A: cài bản desktop

Vào trang chủ [thinkrail.ai](https://thinkrail.ai/#install) hoặc trang Releases của repo, tải file có tên bắt đầu bằng `thinkrail-desktop-` đúng với máy bạn:

- **macOS:** mở file DMG đúng kiến trúc, `thinkrail-desktop-darwin-arm64.dmg` (Apple Silicon) hoặc `thinkrail-desktop-darwin-x64.dmg` (Intel).
- **Windows x64:** giải nén trọn bộ file ZIP setup, rồi chạy file thực thi bên trong. Lưu ý giải nén đủ, đừng chạy thẳng từ trong ZIP.
- **Linux:** giải nén tarball setup rồi chạy `installer`.

Trên Linux, cài các thư viện cần thiết trước:

```bash
sudo apt install libgtk-3-0 libwebkit2gtk-4.1-0 libayatana-appindicator3-1 librsvg2-2 libnotify-bin
```

Lệnh này cài các gói giao diện mà app desktop cần. Nó cần quyền `sudo` nên máy sẽ hỏi mật khẩu.

### Cách B: cài CLI trên macOS hoặc Linux

Mở Terminal và chạy:

```bash
curl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash
```

Script tải đúng bản nhị phân, kiểm tra checksum SHA-256 và đặt `thinkrail` vào PATH. Lệnh này cũng chạy được trên Windows nếu bạn dùng Git Bash.

### Cách C: cài CLI trên Windows

Mở cmd hoặc PowerShell (không cần chuyển qua Git Bash) và chạy:

```powershell
powershell -c "irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex"
```

Sau khi cài xong, hãy đóng terminal cũ và mở terminal mới. Đây là chỗ người mới hay vấp: terminal đang mở có thể chưa nhận PATH mới nên báo không tìm thấy lệnh.

### Chạy lần đầu

Gõ `thinkrail`, có thể kèm đường dẫn một repo git để mở thành project:

```bash
thinkrail ~/code/my-repo
```

Lần đầu, app dẫn bạn qua bước kết nối nhà cung cấp và chọn project. Bạn cũng có thể chọn **Start a new project** nếu chưa có repo. Muốn clone từ GitHub, dùng **Add project → Clone repository…**: chọn thư mục cha, tên thư mục, có thể giới hạn độ sâu lịch sử. Git dùng thông tin đăng nhập và khoá SSH đã có sẵn trên máy bạn.

### Tuỳ chọn: kênh nightly và bản cố định

Installer nhận `--channel stable|nightly` và `--version`. Phiên bản cố định phải thuộc đúng kênh đã chọn:

```bash
curl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash -s -- --channel nightly
curl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash -s -- --channel stable --version 0.3.1
```

Trên Windows, các tuỳ chọn là biến môi trường (`THINKRAIL_CHANNEL`, `THINKRAIL_VERSION`, `THINKRAIL_PREFIX`, `THINKRAIL_NO_MODIFY_PATH`). Ví dụ PowerShell:

```powershell
$env:THINKRAIL_CHANNEL='nightly'; irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex
```

Bản nightly có thể kém ổn định hơn bản stable, nên nếu mới dùng, bạn cứ để mặc định.

### Gỡ cài đặt

```bash
thinkrail uninstall
```

Lệnh này xoá file chạy, mục PATH do installer thêm và thông tin cài đặt. Sau đó nó hỏi có xoá dữ liệu app trong `~/.thinkrail` không (mặc định là giữ lại). README ghi thêm `--remove-data` để xoá luôn dữ liệu và `-y` để bỏ qua các câu hỏi.

## Kiểm tra đã chạy được chưa

Với bản CLI, mở terminal mới và chạy:

```bash
thinkrail --version
thinkrail --help
```

Lệnh đầu in ra phiên bản bạn đã cài. Lệnh sau liệt kê các cờ. Nếu cả hai chạy, lệnh `thinkrail` đã nằm trong PATH.

Sau đó gõ `thinkrail`. Theo README, app mở trong trình duyệt và dẫn bạn qua bước kết nối nhà cung cấp, chọn project. Bạn thành công khi thấy màn hình Welcome, tạo được một workspace và gửi được một prompt cho agent. Với bản desktop, bạn chỉ cần mở app và thấy màn hình đó.

Nếu muốn biết có bản mới không, vào **Settings → Updates** trong app desktop: **Download**, rồi **Preparing update**, rồi **Install & Restart**.

## Dùng vào việc thật

Dưới đây là vài tình huống mình thấy khớp với khả năng README mô tả. Các câu lệnh mẫu là prompt gợi ý để bạn gõ vào chat, không phải lệnh có sẵn của repo.

### Dev mới thử sửa lỗi mà không sợ hỏng code

Bạn vừa nhận một repo và được giao sửa một lỗi nhỏ. Bạn chạy `thinkrail ~/code/my-repo`, tạo một workspace mới (nhánh riêng, thư mục riêng), rồi nhờ agent:

```
Tìm nguyên nhân lỗi đăng nhập báo sai mật khẩu dù nhập đúng, đề xuất cách sửa và chờ mình duyệt.
```

Cây file hiện ngay file nào agent sửa. Nếu không ưng, bạn xoá workspace, nhánh gốc vẫn nguyên. Ưng thì bạn mở PR từ thanh trên cùng, mô tả có thể dựa trên kế hoạch và commit.

> Cho AI một chỗ làm riêng, bạn mới dám giao việc thật.
>
> — Ông T

### Thử hai hướng làm song song

Bạn không chắc nên viết tính năng theo cách A hay B. Hãy mở hai chat ở hai workspace, hoặc nói với agent làm trong «một workspace phụ». README ghi agent sẽ tự dựng workspace và chat đó rồi theo dõi chat cùng pull request. Cuối cùng bạn so hai kết quả và gộp bản tốt hơn.

### Giữ bối cảnh dự án qua nhiều ngày

Bạn làm một dự án dài hơi và mệt vì phải giải thích lại từ đầu mỗi phiên. Hãy để agent ghi quyết định vào `SPEC.md` thông qua công cụ `spec_*`. Hôm sau, trong ô tìm kiếm, gõ `#` kèm câu hỏi, ví dụ `#vì sao chọn cách tính phí này`, để tìm đúng đoạn spec trả lời. Bấm `↵` để mở đoạn đó, hoặc `⌥↵` để hỏi agent trong chat mới nếu spec diễn đạt khác.

### Người không code: soạn nháp và lên kế hoạch

Bạn là nhân viên văn phòng cần lên dàn ý một quy trình hay soạn tài liệu. Bạn dùng chat không cần project từ màn hình Welcome. Agent có thể hỏi bạn câu trắc nghiệm cho rõ yêu cầu và vẽ sơ đồ Mermaid. Khi việc cần đưa vào một dự án thật, bạn bấm **Continue in workspace** để agent viết bản bàn giao rồi mở chat mới ở workspace.

## Lỗi hay gặp và cách xử lý

**Gõ `thinkrail` báo không tìm thấy lệnh.** Thường do terminal mở trước khi cài nên chưa nhận PATH mới. Hãy đóng và mở terminal mới. Nếu bạn đặt `THINKRAIL_NO_MODIFY_PATH` khi cài, installer sẽ không sửa PATH, bạn phải tự thêm.

**Cài trên Windows không chạy.** Hãy chắc bạn chạy đúng lệnh PowerShell ở trên. Với bản desktop, nhớ giải nén trọn ZIP rồi mới chạy file thực thi.

**macOS chặn app (Gatekeeper).** README cho biết các DMG cũ hoặc bản tự build có thể chưa ký và bị chặn. Hãy tải bản mới nhất từ trang Releases hoặc trang chủ thay vì dùng file cũ.

**Linux không mở được app desktop.** Kiểm tra bạn đã cài đủ các gói ở phần chuẩn bị, và hệ thống đạt glibc 2.38 trở lên (Ubuntu 24.04+). Các file Linux không được ký.

**Agent không trả lời hoặc báo chưa có mô hình.** Có thể bạn chưa kết nối nhà cung cấp. Vào Settings, đăng nhập JetBrains AI hoặc thêm thông tin xác thực qua `pi`. Nếu dùng máy chủ riêng (Ollama, LM Studio…), vào Settings → Providers → Custom servers và bấm **Find models**.

**Đổi cấu hình `pi` nhưng chưa thấy có tác dụng.** README ghi cấu hình mới có hiệu lực ở lần khởi động tiếp theo. Hãy khởi động lại ThinkRail.

## Có nên dùng không

**Điểm mạnh.** Workspace tách biệt giúp thử nghiệm an toàn. Đồ thị spec giúp agent nhớ dự án. Bạn tự chọn nhà cung cấp và mô hình, kể cả mô hình chạy trên máy riêng. Mã nguồn mở Apache-2.0, bản Windows và CLI được JetBrains ký, và có cả bản desktop lẫn chạy trong trình duyệt.

**Giới hạn.** Nó xây trên agent `pi`, nên bạn nên làm quen với `pi` nếu muốn dùng sâu. Bản Linux chưa ký, và bản CLI trên macOS đã ký nhưng chưa notarize. Giao diện chưa có tiếng Việt sẵn (README liệt kê sáu ngôn ngữ, không có tiếng Việt). Phần phân tích: app thu thập sự kiện sử dụng cơ bản và báo cáo lỗi gắn với một ID cài đặt ngẫu nhiên, README nói không gồm prompt, code, file hay thông tin tài khoản. Bạn có thể tắt chia sẻ dữ liệu bổ sung trong Settings → Privacy hoặc chạy với `thinkrail --no-analytics`.

**Khi nào nên chọn cách khác.** Nếu bạn chỉ cần AI sửa vài dòng trong một file, một công cụ gọn hơn có thể đủ. ThinkRail đáng giá nhất khi bạn làm dự án có nhiều việc song song, cần giữ bối cảnh lâu dài, hoặc muốn nhiều agent cùng làm mà không giẫm chân nhau.

## Câu hỏi thường gặp

### ThinkRail có miễn phí không?

Repo là mã nguồn mở theo giấy phép Apache-2.0. Tuy nhiên chi phí gọi mô hình AI phụ thuộc nhà cung cấp bạn kết nối (JetBrains AI hoặc nhà cung cấp riêng). README không nêu bảng giá.

### ThinkRail có chạy được trên Windows không?

Có. README hỗ trợ Windows x64 cả bản desktop (file ZIP setup) lẫn CLI (lệnh PowerShell dùng install.ps1). JetBrains ký bản CLI Windows và trình cài đặt desktop.

### Có cần GPU không?

README không yêu cầu GPU. Nếu bạn dùng mô hình chạy trên máy riêng qua Ollama, LM Studio hay llama.cpp thì phần cứng tuỳ mô hình, nhưng tư liệu không nêu cụ thể.

### Dữ liệu và code của mình có an toàn không?

README nói thống kê sử dụng không chứa prompt, code, file, thông tin xác thực hay danh tính tài khoản. Báo cáo lỗi chỉ gồm loại lỗi và vị trí trong code của ThinkRail. Bạn có thể tắt chia sẻ dữ liệu bổ sung trong Settings → Privacy hoặc dùng thinkrail --no-analytics.

### ThinkRail khác gì dùng agent thẳng trong terminal?

ThinkRail bọc agent pi trong giao diện có workspace git riêng, soạn code, terminal, theo dõi PR và đồ thị spec. Phần công cụ hỏi đáp và sơ đồ cũng được xuất bản dạng gói pi, nên pi thuần trong terminal vẫn dùng được. Tư liệu không so sánh trực tiếp với công cụ khác.

### Có cần tài khoản ThinkRail không?

Không. README ghi ThinkRail không có tài khoản riêng. Bạn đăng nhập bằng JetBrains AI hoặc kết nối nhà cung cấp thông qua cấu hình xác thực của pi.

### Có dùng được mô hình chạy trên máy của mình không?

Có. Trong Settings → Providers → Custom servers, bạn nối máy chủ tương thích OpenAI như LiteLLM, sglang, vLLM, Ollama, LM Studio hay llama.cpp. Nút Find models liệt kê các mô hình có trên máy chủ đó.
