# 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 dành cho AI agent do JetBrains phát hành (giấy phép Apache-2.0). Nó chạy agent lập trình `pi` trong giao diện có workspace tách biệt, đồ thị spec và kỹ năng (skills) để agent nhớ dự án qua nhiều phiên. Cài khá dễ: tải app desktop hoặc chạy một dòng lệnh để có CLI `thinkrail`, nhưng bạn cần có 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-11 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/thinkrail-ide-ai-agent-spec-huong-dan-cai-dat

ThinkRail là một IDE (môi trường lập trình) xây quanh AI agent, do JetBrains phát hành. Thay vì chỉ chat với AI rồi tự chép code, bạn làm việc trong một giao diện có sẵn trình soạn code, terminal, cây file theo dõi git, nhiều phiên chat song song và một bộ «trí nhớ» về dự án. Hiện repo có khoảng 8205 sao và 521 fork, giấy phép Apache-2.0, viết chủ yếu bằng TypeScript.

Repo này hợp với lập trình viên mới và người làm kinh doanh muốn nhờ AI sửa code mà không sợ làm hỏng bản gốc. Mỗi việc được giao cho agent chạy trong một workspace riêng (dùng `git worktree`), làm xong bạn xem thay đổi rồi mới quyết định giữ hay bỏ.

Điểm đáng giá nhất là «đồ thị spec»: các file `SPEC.md` nằm cạnh code, ghi lại ý định của dự án. Agent đọc và cập nhật chúng, nên lần sau mở lại, nó không phải đoán từ đầu. Đó là lý do tác giả nói công cụ «ngày càng tốt hơn mỗi lần bạn dùng».

```repo
- repo | JetBrains/thinkrail
- kind | Ứng dụng
- desc | ThinkRail của JetBrains là IDE bao quanh agent lập trình pi: workspace tách biệt, spec lưu ý định dự án, kỹ năng dùng lại. Có app desktop và CLI.
- stars | 8.2k
- lang | TypeScript
- license | Apache-2.0
```

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

Dưới đây là những tính năng chính, mình diễn giải 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 workspace từ nó. Mỗi workspace có nhánh và thư mục riêng. Nhiều agent làm song song mà không đụng vào code gốc. Xong việc, bạn gộp phần muốn giữ và xoá phần còn lại.
- **Theo dõi nhánh và pull request.** Thanh trên cùng cho biết nhánh hiện tại so với `origin` ra sao và PR đang ở trạng thái nào. Với PR trên GitHub, bạn xem được kết quả CI, quyết định review, và có thể đánh dấu sẵn sàng, merge, mở lại hoặc xoá nhánh từ xa.
- **IDE bao quanh agent.** Có tab soạn code Monaco, cây file hiện thay đổi git ngay khi agent sửa, terminal và xem trước Markdown có mục lục.
- **Nhiều phiên chat.** 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, xếp hàng prompt tiếp theo, giao việc cho subagent, và cùng chỉnh một kế hoạch chung.
- **Hộp tìm kiếm duy nhất.** 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 có thể hỏi, lên kế hoạch hay soạn nháp mà không có repo. Mỗi chat có thư mục nháp riêng. Khi chat thành việc thật, nút **Continue in workspace** nhờ agent viết bản bàn giao và mở chat mới trong workspace.
- **Spec luôn cập nhật.** Agent đọc, tìm và sửa đồ thị `SPEC.md` bằng các công cụ `spec_*`. Công cụ Specs (chỉ đọc) hiển thị đồ thị dạng cây. Trong hộp tìm kiếm, gõ `#` kèm câu hỏi để tìm đúng đoạn spec trả lời.
- **Skills.** ThinkRail nạp skill của `pi` và skill có sẵn trong dự án. Nó cũng nhập được skill từ Claude, Codex và các agent lập trình khác: bật trong Settings → Extensions hoặc trong hộp thoại Skills của từng project.
- **Công cụ vượt ra ngoài dòng lệnh.** Agent có thể hỏi bạn câu hỏi trắc nghiệm có cấu trúc thay vì đoán, vẽ sơ đồ Mermaid, đặt hai phương án cạnh nhau và xem trước file. Khi đề xuất đổi giao diện, nó cho bạn xem mockup trước/sau để bình luận như bình luận diff.
- **Máy chủ MCP.** Kết nối các MCP server trong `mcp.json` của `pi` hoặc cấu hình ngay trong Settings. ThinkRail hỏi bạn trong chat trước những lệnh gọi mà server không đánh dấu là chỉ đọc. Server do repo khai báo sẽ tắt cho đến khi bạn duyệt.
- **Nhà cung cấp mô hình của bạn.** Đăng nhập bằng JetBrains AI hoặc kết nối nhà cung cấp qua cơ chế 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 ở Settings → Providers → Custom servers.
- **App desktop hoặc trình duyệt.** Dùng app native, hoặc CLI `thinkrail` mở cùng giao diện đó trong trình duyệt. Trạng thái app nằm ở `~/.thinkrail`.
- **Đa ngôn ngữ, giao diện tuỳ biế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ữ như `de.json` vào `~/.thinkrail/locales`. Giao diện có các chủ đề tối, sáng, tối giản, tương phản cao, và bạn chọn được font.

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

Theo README, bạn cần:

- **Hệ điều hành** cho bản desktop: macOS 14 trở lên (Apple Silicon hoặc Intel), Windows x64, hoặc Linux x64 / ARM64. Bản Linux cần glibc 2.38+ với GTK 3, WebKitGTK 4.1, Ayatana AppIndicator 3, librsvg 2, và Ubuntu 24.04 trở lên.
- **Bản CLI** chạy trên macOS, Linux (cả Windows qua Git Bash) và Windows (cmd hoặc PowerShell).
- **`git`** phải có trong PATH.
- **Một nhà cung cấp mô hình AI.** Bạn đăng nhập bằng JetBrains AI trong app, hoặc dùng thông tin đăng nhập của nhà cung cấp riêng. Lần chạy đầu tiên sẽ dẫn bạn qua bước này.
- Không cần có sẵn repo. Chức năng **Start a new project** sẽ tạo một repo git trống (mặc định trong `~/thinkrail`).

Tư liệu không nói gì về yêu cầu phần cứng như GPU hay dung lượng RAM, nên mình không đoán.

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

Có hai đường: cài app desktop, hoặc cài CLI bằng một dòng lệnh. Mình tóm tắt đường CLI, vì nó có lệnh cụ thể.

```steps
- Chọn cách cài | App desktop hay CLI `thinkrail`
- Chạy lệnh cài | Dán một dòng lệnh vào terminal (CLI)
- Mở ThinkRail | Chạy `thinkrail`, có thể kèm đường dẫn repo
- Kết nối nhà cung cấp AI | Đăng nhập JetBrains AI hoặc dùng key của bạn
- Chọn hoặc tạo project | Mở repo có sẵn hoặc Start a new project
```

### Chọn app desktop hay CLI

Bản desktop là file tải về, bản CLI là một chương trình dòng lệnh mở giao diện trong trình duyệt. Hai bản dùng chung một engine. Nếu ngại terminal, hãy chọn desktop.

Với desktop, vào trang Releases của repo và tải file `thinkrail-desktop-*` hợp với máy bạn:

- macOS: mở file DMG, tên là `thinkrail-desktop-darwin-arm64.dmg` (Apple Silicon) hoặc `thinkrail-desktop-darwin-x64.dmg` (Intel).
- Windows x64: giải nén toàn bộ file ZIP cài đặt rồi chạy file thực thi. Lưu ý phải giải nén đủ, đừng chạy thẳng từ trong ZIP.
- Linux: giải nén tarball cài đặt và chạy `installer`. Trên Ubuntu, 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
```

App có hai kênh cập nhật là stable và nightly. Trong app, vào **Settings → Updates**, bấm **Download**, chờ **Preparing update**, rồi **Install & Restart**.

### Cài CLI trên macOS, Linux hoặc Git Bash

Mở terminal (ứng dụng Terminal trên macOS, hoặc Git Bash trên Windows) và chạy:

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

Theo README, trình cài tải đúng bản nhị phân cho máy bạn, kiểm tra checksum SHA-256 rồi đưa `thinkrail` vào PATH. Sau khi cài xong, hãy mở một cửa sổ terminal mới để PATH được nhận.

### Cài CLI trên Windows

Mở cmd hoặc PowerShell và chạy:

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

### Chọn kênh hoặc phiên bản cụ thể (không bắt buộc)

Trình cài nhận `--channel stable|nightly` và `--version`. Phiên bản bạn ghim phải thuộc đúng kênh đã chọn. Ví dụ trong README:

```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`):

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

### Chạy ThinkRail và kết nối nhà cung cấp AI

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

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

Lần chạy đầu tiên, ThinkRail dẫn bạn qua việc kết nối nhà cung cấp và chọn project. Chỗ này người mới hay vấp: nếu chưa có nhà cung cấp AI nào, agent sẽ không làm việc được. Chưa có repo thì chọn **Start a new project**.

```note
Bạn tự chịu chi phí của nhà cung cấp mô hình mình kết nối. ThinkRail không có tài khoản riêng. README nói mặc định chỉ làm nóng bộ nhớ đệm prompt khi có lượt chạy đang hoạt động, để chat nhàn rỗi không tốn tiền ngầm. Đừng dán key hay bí mật vào ô khảo sát phản hồi.
```

### Gỡ cài đặt và cập nhật CLI

Bản đang chạy tự kiểm tra cập nhật định kỳ và hiện nút «Update available». Muốn gỡ, chạy `thinkrail uninstall`. Lệnh này xoá chương trình, mục PATH mà trình cài đã thêm và thông tin cài đặt, rồi hỏi bạn có xoá dữ liệu `~/.thinkrail` hay không (mặc định giữ lại).

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

Với CLI, chạy hai lệnh sau. Nếu terminal in ra được thông tin thì `thinkrail` đã nằm trong PATH:

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

`--version` in ra bản build, còn `--help` liệt kê các cờ. Nếu terminal báo không tìm thấy lệnh, hãy đóng và mở lại terminal.

Sau đó chạy `thinkrail` và xem giao diện có mở ra, rồi đi qua bước kết nối nhà cung cấp và chọn project. Với bản desktop, chỉ cần app mở lên và hiện màn hình chào (Welcome). Bạn coi như xong khi gửi được một prompt trong chat và nhận được câu trả lời từ mô hình.

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

Các tình huống dưới đây bám theo những gì README mô tả. Câu lệnh mẫu mình đưa chỉ là ví dụ prompt để bạn tham khảo.

### Dev mới nhờ agent thử việc rủi ro mà không đụng code gốc

Bạn vừa nhận một dự án web và muốn nhờ AI đổi cách đặt tên hàng loạt. Mở dự án bằng `thinkrail ~/code/my-repo`, rồi tạo workspace mới. Agent làm việc trong nhánh và thư mục riêng, còn bản gốc của bạn không bị đụng tới. Bạn xem cây file để thấy file nào đổi, đọc diff, rồi merge phần ưng ý và xoá workspace nếu kết quả tệ.

Bạn cũng có thể gõ ngay trong chat: «Hãy làm việc này trong một workspace phụ». README nói agent sẽ tự mở workspace và chat đó rồi theo dõi chat cùng pull request của nó.

### Chủ shop có website nhỏ, cần ghi lại luật của dự án

Bạn thuê người làm website bán hàng và muốn các quy tắc như «giá hiển thị đã gồm VAT» không bị quên giữa các lần nhờ AI sửa. Hãy nhờ agent: «Ghi quy tắc tính giá vào SPEC.md của dự án, rồi dùng nó khi sửa trang thanh toán». Lần sau, bạn gõ `#` kèm câu hỏi vào hộp tìm kiếm (ví dụ về cách tính giá) để tìm đoạn spec trả lời. Bấm `↵` để mở spec, hoặc `⌥↵` để hỏi agent trong chat mới khi spec diễn đạt khác.

> Spec nằm cạnh code, nên agent không phải đoán lại ý bạn mỗi lần mở dự án.
>
> — Ông T

### Nhân viên văn phòng soạn kế hoạch hay nháp mà chưa có repo

Bạn chưa có dự án nào nhưng muốn hỏi AI về một quy trình, hay soạn nháp tài liệu. Bắt đầu từ màn hình Welcome và mở một chat không cần project. Mỗi chat có thư mục nháp riêng cho file, terminal và kế hoạch, không có nhánh hay pull request. Khi ý tưởng thành việc thật, bấm **Continue in workspace** để agent viết bản bàn giao và mở chat mới trong workspace. Xoá chat thì cả thư mục được chuyển vào Thùng rác.

### Dev dùng mô hình chạy trên máy mình

Công ty bạn có cổng LLM nội bộ, hoặc bạn tự chạy mô hình bằng Ollama hay LM Studio. Vào Settings → Providers → Custom servers, thêm máy chủ tương thích OpenAI, bấm **Find models** để liệt kê mô hình cùng khả năng của chúng. Máy chủ được lưu vào `models.json` của `pi`, rồi mô hình hiện trong bộ chọn của chat. Tuỳ chọn này hợp khi bạn muốn mã nguồn không rời khỏi hạ tầng của mình.

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

- **Gõ `thinkrail` báo không tìm thấy lệnh.** Trình cài vừa thêm PATH nên terminal cũ chưa nhận. Đóng terminal, mở cái mới rồi thử lại `thinkrail --version`. Nếu vẫn lỗi, chạy lại trình cài.
- **Agent không trả lời vì chưa có nhà cung cấp mô hình.** ThinkRail cần một nhà cung cấp. Đăng nhập JetBrains AI trong app, hoặc kết nối nhà cung cấp qua cơ chế xác thực của `pi`. Lần chạy đầu sẽ hướng dẫn bạn bước này.
- **Thiếu `git`.** README nói `thinkrail` cần `git` trong PATH. Cài git rồi mở lại terminal.
- **macOS chặn app (Gatekeeper) hoặc Windows cảnh báo.** README ghi rằng DMG cũ hoặc bản build tự dựng có thể chưa ký và bị Gatekeeper chặn, còn CLI macOS đã ký nhưng chưa được notarize. Hãy tải bản mới từ trang Releases chính thức, và đừng chạy file lấy từ nguồn lạ.
- **Bản desktop Linux không chạy.** Kiểm tra bạn có glibc 2.38+, Ubuntu 24.04 trở lên, và đã cài đủ gói bằng lệnh `sudo apt install ...` ở phần cài đặt. Các bản Linux chưa được ký.

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

**Điểm mạnh.** Workspace tách biệt giúp bạn thử nghiệm an toàn. Đồ thị spec giữ ý định dự án qua nhiều phiên. Bạn dùng được mô hình của chính mình (kể cả chạy cục bộ), không bị khoá vào một nhà cung cấp. Giao diện có cả desktop lẫn trình duyệt, giấy phép Apache-2.0, và repo vẫn được cập nhật trong 3 tháng gần đây.

**Giới hạn.** Bạn vẫn cần git, một nhà cung cấp AI (có thể tốn phí) và chút quen thuộc với repo. Giao diện chưa có tiếng Việt sẵn trong danh sách ngôn ngữ. Ứng dụng thu thập dữ liệu sử dụng cơ bản và báo lỗi gắn với một ID cài đặt ngẫu nhiên, README nói chúng không chứa prompt, code, file hay thông tin tài khoản. Bạn có thể tắt chia sẻ thêm trong Settings → Privacy hoặc chạy `thinkrail --no-analytics`. Bản Linux chưa được ký.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần hỏi đáp nhanh, một khung chat thông thường là đủ. Nếu bạn đã quen một agent chạy trong terminal và không cần giao diện, hãy dùng thẳng `pi` (hai gói công cụ hỏi đáp và sơ đồ của ThinkRail cũng cài được riêng cho `pi`). ThinkRail đáng thử khi bạn làm việc đều đặn với một dự án code và muốn agent hiểu dự án ngày một rõ hơn.

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

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

Repo dùng giấy phép Apache-2.0 và README không nói phải trả phí để dùng ứng dụng. Tuy vậy bạn cần một nhà cung cấp mô hình AI, và chi phí của nhà cung cấp đó do bạn tự chịu. README chưa nêu giá của JetBrains AI.

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

Tư liệu không nêu yêu cầu GPU. ThinkRail chạy agent qua nhà cung cấp mô hình mà bạn kết nối. Nếu muốn chạy mô hình ngay trên máy, bạn có thể nối Ollama, LM Studio hoặc máy chủ tương thích OpenAI khác, nhưng phần cứng cho việc đó phụ thuộc mô hình bạn chọn.

### Chạy được trên Windows không?

Có. Bản desktop hỗ trợ Windows x64 (giải nén ZIP cài đặt rồi chạy file thực thi). CLI cũng chạy trên Windows bằng cmd hoặc PowerShell, hoặc dùng Git Bash với lệnh của macOS và Linux.

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

README nói thống kê sử dụng không bao gồm prompt, code, file, thông tin đăng nhập hay danh tính tài khoản, và báo lỗi cũng không chứa đường dẫn file hay nội dung dự án. Dữ liệu gắn với một ID cài đặt ngẫu nhiên. Bạn tắt chia sẻ thêm trong Settings → Privacy hoặc chạy `thinkrail --no-analytics`. Code bạn gửi cho mô hình sẽ đến nhà cung cấp mà bạn chọn.

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

ThinkRail chạy agent `pi` trong một IDE có workspace git worktree tách biệt, nhiều phiên chat, đồ thị spec và giao diện cho PR, CI. README không so sánh trực tiếp với công cụ cụ thể nào khác. Các công cụ hỏi đáp và sơ đồ của nó cũng được phát hành thành gói `pi` riêng để dùng với `pi` thuần.

### Tôi có cần biết lập trình không?

README nhắm tới việc làm việc với repo git, nên biết cơ bản về git và cấu trúc dự án sẽ giúp ích. Tuy vậy bạn có thể bắt đầu bằng một dự án trống hoặc chat không cần project. Mức độ dễ dùng cho người hoàn toàn chưa biết code thì tư liệu chưa có thông tin.

### Gỡ ThinkRail như thế nào?

Với CLI, chạy `thinkrail uninstall`. Lệnh này xoá chương trình, mục PATH đã thêm và thông tin cài đặt, rồi hỏi bạn có xoá dữ liệu trong `~/.thinkrail` không (mặc định giữ lại). Cờ `--remove-data` xoá luôn dữ liệu, còn `-y` bỏ qua các câu hỏi.
