# JetBrains/thinkrail: IDE agentic làm việc an toàn hơn — hướng dẫn cài đặt và dùng

> ThinkRail là một IDE agentic chạy pi coding agent bên trong, giúp bạn giao việc cho AI trong workspace Git riêng, theo dõi thay đổi và quản lý pull request. Công cụ có bản desktop và CLI, cài khá đơn giản bằng bộ cài có sẵn; bạn cần Git và một model provider.

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

ThinkRail là một IDE agentic giúp bạn giao việc lập trình cho AI trong các workspace Git tách biệt. Công cụ kết hợp giao diện IDE, terminal, trình soạn thảo Monaco, chat với coding agent và hệ thống đặc tả dự án.

ThinkRail phù hợp với lập trình viên muốn AI làm việc theo kế hoạch rõ ràng, nhân viên kỹ thuật cần kiểm tra thay đổi trước khi nhập vào nhánh chính, hoặc nhóm muốn lưu lại kiến thức dự án qua nhiều phiên làm việc. Điểm đáng giá nhất là agent có thể làm việc trong git worktree riêng, nên bạn có thể chạy nhiều nhiệm vụ song song mà ít ảnh hưởng đến mã nguồn gốc.

Repo hiện có khoảng 8225 sao và 521 fork. Đây là dự án TypeScript, phát hành theo giấy phép Apache-2.0. README mô tả bản desktop native và CLI `thinkrail`; phần hướng dẫn dưới đây tập trung vào cách cài hai dạng này theo tài liệu đã cung cấp.

```repo
- repo | JetBrains/thinkrail
- kind | Ứng dụng
- desc | ThinkRail là IDE agentic dùng AI để lập trình, quản lý workspace Git, đặc tả dự án và mở rộng kỹ năng theo cách bạn làm việc.
- stars | 8.2k
- lang | TypeScript
- license | Apache-2.0
```

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

- **Tạo workspace cô lập bằng Git worktree.** Bạn có thể mở một repo Git rồi tạo workspace riêng, kèm branch và thư mục làm việc riêng. Agent được phép sửa trong workspace đó mà không chạm trực tiếp vào thư mục mã nguồn ban đầu. Cách này hữu ích khi bạn muốn thử một tính năng, sửa lỗi hoặc nâng cấp thư viện mà vẫn giữ nguyên trạng thái đang chạy.

- **Theo dõi thay đổi và pull request trong cùng giao diện.** ThinkRail hiển thị branch đang đứng như thế nào so với `origin`, trạng thái pull request và các kiểm tra CI. Khi hoàn tất, bạn có thể publish, push, tạo PR, đánh dấu ready, merge, reopen hoặc xóa branch từ giao diện.

- **Làm việc như một IDE đầy đủ.** Công cụ có tab Monaco, cây file tích hợp với Git, terminal và xem tài liệu Markdown. Khi agent sửa code, bạn có thể xem thay đổi ngay trong cùng ứng dụng thay vì chuyển qua nhiều cửa sổ.

- **Mở nhiều phiên chat cho một workspace.** Mỗi phiên có thể dùng model riêng. Bạn có thể gửi yêu cầu, xếp yêu cầu tiếp theo, giao việc cho subagent và cùng agent cập nhật một kế hoạch chung. Điều này phù hợp với công việc có nhiều phần như đọc code, viết test và sửa lỗi.

- **Tìm kiếm tập trung bằng một hộp lệnh.** Phím `⌘K`, hoặc nhấn đúp Shift, có thể tìm chat, tin nhắn, workspace, project, file, spec và plan. `⌘⇧F` tìm nội dung trong file của workspace, nhóm kết quả theo file và mở thẳng đến dòng tương ứng.

- **Chat không cần repo.** Bạn có thể hỏi, lập kế hoạch hoặc tạo file trong một thư mục tạm riêng dưới mục Chats. Khi cuộc trò chuyện trở thành công việc thật, lệnh Continue in workspace tạo bản tóm tắt bàn giao rồi bắt đầu chat mới trong workspace.

- **Lưu kiến thức dự án bằng spec graph.** ThinkRail dùng các file `SPEC.md` đặt cạnh code để lưu ý định và quy tắc của dự án. Agent có thể đọc, tìm kiếm và cập nhật chúng qua các công cụ `spec_*`, giúp những phiên làm việc sau không phải bắt đầu lại từ đầu.

- **Nạp skill từ nhiều coding agent.** ThinkRail đọc skill của `pi` và skill đã có trong project. Bạn cũng có thể bật skill từ Claude, Codex và các coding agent khác trong Settings → Extensions hoặc trong Skills dialog của từng project.

- **Dùng công cụ ngoài shell.** Agent có thể đặt câu hỏi trắc nghiệm có cấu trúc, vẽ sơ đồ Mermaid, hiển thị so sánh và xem trước file. Khi đề xuất thay đổi giao diện, agent có thể đưa ra mockup trước và sau để bạn nhận xét.

- **Kết nối MCP server.** Bạn có thể cấu hình MCP trong `pi` hoặc trong Settings. ThinkRail hỏi trước khi gọi server không đánh dấu công cụ là chỉ đọc; các server do repo định nghĩa cũng ở trạng thái tắt cho đến khi bạn phê duyệt.

- **Dùng provider và model server của bạn.** Bạn có thể đăng nhập JetBrains AI, dùng credential của provider trong `pi`, hoặc kết nối server tương thích OpenAI như LiteLLM, sglang, vLLM, Ollama, LM Studio và llama.cpp. Model được tìm thấy sẽ xuất hiện trong bộ chọn model của chat và trong CLI `pi`.

- **Chạy trên desktop hoặc trình duyệt.** Bản desktop là ứng dụng native. CLI `thinkrail` mở cùng ứng dụng trong trình duyệt. Cả hai dùng chung engine host và lưu trạng thái ứng dụng dưới `~/.thinkrail`.

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

- **Hệ điều hành:** macOS 14 trở lên trên Apple Silicon hoặc Intel; Windows x64; Linux x64 hoặc ARM64. CLI hỗ trợ các nền tảng tương ứng. Windows dùng executable ký số; Linux có binary chưa ký.

- **Git:** `git` phải có trong `PATH`. Đây là điều kiện cần để ThinkRail mở project, tạo worktree và làm việc với branch.

- **Model provider:** Bạn cần đăng nhập JetBrains AI hoặc cung cấp credential cho một provider mà `pi` hỗ trợ. ThinkRail không có tài khoản riêng.

- **Credential Git nếu dùng GitHub hoặc Git host khác:** Công cụ dùng credential và SSH key đã có trên máy của bạn để clone, push và làm việc với repo.

- **Linux desktop:** Máy cần glibc 2.38 trở lên, GTK 3, WebKitGTK 4.1, Ayatana AppIndicator 3, librsvg 2 và Ubuntu 24.04 trở lên. Desktop notification cần thêm `libnotify-bin`.

- **Cấu hình `pi` nếu bạn đã dùng trước đó:** ThinkRail đọc cấu hình hiện có ở `~/.pi/agent`. Bạn có thể chọn cấu hình khác trong Settings → Environment và thêm biến môi trường cho agent, terminal hoặc MCP server.

README không nêu yêu cầu GPU, RAM hoặc CPU cụ thể. Vì vậy, không nên tự suy ra rằng công cụ cần GPU riêng.

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

```steps
- Chọn dạng cài | Dùng desktop installer hoặc CLI thinkrail
- Cài dependency | Chuẩn bị Git và dependency Linux nếu dùng Linux desktop
- Chạy bộ cài | Tải binary, kiểm tra SHA-256 và đưa thinkrail vào PATH
- Khởi động lần đầu | Kết nối model provider và chọn hoặc tạo project
- Mở project | Mở repo có sẵn hoặc clone repository từ giao diện
```

### Chọn bản desktop hoặc CLI

ThinkRail được phát hành dưới hai dạng: desktop installer và CLI tự chứa. Bản desktop phù hợp nếu bạn muốn có cửa sổ native và thao tác bằng giao diện. CLI phù hợp nếu bạn quen terminal hoặc muốn mở cùng ứng dụng trong trình duyệt.

Bản desktop được tải từ landing page của dự án. README không ghi một lệnh tải desktop cụ thể, nên bạn cần chọn đúng asset theo hệ điều hành:

- macOS: mở DMG `thinkrail-desktop-darwin-arm64.dmg` hoặc `thinkrail-desktop-darwin-x64.dmg`.
- Windows x64: giải nén toàn bộ setup ZIP rồi chạy executable.
- Linux x64 hoặc ARM64: giải nén setup tarball rồi chạy `installer`.

Windows cần giữ nguyên toàn bộ nội dung trong setup ZIP trước khi chạy executable. Với Linux, hãy kiểm tra đúng kiến trúc máy trước khi chọn tarball.

### Cài dependency cho Linux desktop

Nếu dùng desktop trên Linux, cài các thư viện mà README yêu cầu bằng lệnh sau:

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

Lệnh này dùng trình quản lý gói APT để cài giao diện GTK, WebKit, biểu tượng ứng dụng, thư viện SVG và thông báo desktop. Bạn chạy trong terminal của máy Linux có quyền `sudo`. README yêu cầu Ubuntu 24.04 trở lên và glibc 2.38+, nên cài đủ gói chưa chắc khắc phục được nếu bản phân phối quá cũ.

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

Mở terminal, sau đó chạy lệnh chính xác trong README:

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

`curl` tải script cài đặt. Script chọn binary phù hợp, kiểm tra checksum SHA-256 và đặt `thinkrail` vào `PATH`. Vì lệnh truyền nội dung tải được trực tiếp cho `bash`, bạn nên chỉ chạy khi đã xác định đúng nguồn script và đang dùng máy mình kiểm soát.

Lệnh này cũng dùng được trên Windows trong Git Bash theo README. Nếu terminal chưa nhận lệnh ngay sau khi cài, hãy mở một cửa sổ terminal mới để nạp lại `PATH`.

### Cài CLI trên Windows

Mở PowerShell hoặc Command Prompt. README cho biết cùng một lệnh hoạt động từ cả hai môi trường:

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

Lệnh gọi PowerShell tải `install.ps1`, sau đó thực thi script cài đặt. Script đặt executable vào vị trí phù hợp và thêm đường dẫn cần thiết. Nếu Windows hỏi quyền hoặc terminal chưa nhận `thinkrail`, hãy mở lại terminal sau khi cài.

### Chọn kênh hoặc ghim phiên bản

Mặc định installer cài bản phù hợp theo kênh đang dùng. Bạn có thể chọn nightly trên macOS hoặc Linux:

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

Bạn cũng có thể ghim một phiên bản stable hoặc nightly:

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

Phiên bản ghim phải thuộc đúng channel đã chọn. Không nên dùng nightly cho môi trường cần ổn định nếu bạn chưa chấp nhận khả năng thay đổi.

Trên Windows, các tùy chọn được truyền bằng biến môi trường:

```powershell
$env:THINKRAIL_CHANNEL='nightly'; irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex
set "THINKRAIL_CHANNEL=stable" && set "THINKRAIL_VERSION=0.3.1" && powershell -c "irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex"
```

`THINKRAIL_CHANNEL` chọn kênh, còn `THINKRAIL_VERSION` ghim phiên bản. README cũng liệt kê `THINKRAIL_PREFIX` và `THINKRAIL_NO_MODIFY_PATH` cho Windows, nhưng không đưa ví dụ đầy đủ cho hai biến này.

### Khởi động và mở project

Sau khi cài, kiểm tra phiên bản hoặc xem trợ giúp:

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

Để mở một repo Git đã có:

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

Đường dẫn trong ví dụ là đường dẫn mẫu. Bạn thay bằng thư mục thật trên máy. Khi chạy lần đầu, ThinkRail hướng dẫn bạn kết nối provider và chọn project. Nếu chưa có repo, chọn Start a new project để tạo một Git repository trống, mặc định dưới `~/thinkrail`.

Bạn cũng có thể mở ThinkRail rồi chọn Add project → Clone repository… để clone một Git URL. Giao diện cho phép chọn thư mục cha, tên thư mục, giới hạn độ sâu lịch sử hoặc hủy clone đang chạy.

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

Cài thành công khi terminal nhận được hai lệnh sau và in ra thông tin tương ứng:

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

Sau đó chạy `thinkrail` hoặc `thinkrail ~/code/my-repo`. Kết quả mong đợi là ứng dụng ThinkRail mở trong desktop hoặc trình duyệt, hiển thị bước kết nối provider và chọn project.

Nếu mở một repo Git, bạn cần thấy project và workspace trong giao diện. Hãy thử tạo một workspace dạng worktree, mở một chat và yêu cầu agent đọc hoặc sửa một file nhỏ. Khi agent hoạt động, cây file và khu vực thay đổi phải phản ánh công việc trong workspace đang chọn.

Nếu bạn muốn kiểm tra luồng Git đầy đủ, hãy xem branch hiện tại, trạng thái so với `origin` và phần pull request. README cho biết ThinkRail hiển thị CI checks và quyết định review khi một PR đã mở.

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

### Chủ shop cần chỉnh tính năng cho website bán hàng

Chủ shop có thể mở repo website, tạo một workspace riêng rồi yêu cầu agent sửa một phần giao diện hoặc quy trình đặt hàng. Prompt nên nêu rõ phạm vi, ví dụ: “Trong workspace riêng, kiểm tra trang giỏ hàng, đề xuất kế hoạch sửa lỗi khi sản phẩm hết hàng, sau đó chờ tôi duyệt kế hoạch trước khi sửa code.”

Agent làm việc trong branch và thư mục riêng. Bạn xem kế hoạch, đọc diff trong cây file tích hợp Git, mở terminal chạy kiểm tra của dự án rồi mới chọn publish hoặc tạo pull request. Cách này giảm rủi ro agent sửa thẳng vào bản đang dùng.

### Nhân viên văn phòng muốn tự động hóa một báo cáo nội bộ

Nếu công việc cần tạo file hoặc thử một đoạn script nhưng chưa có repo, hãy bắt đầu bằng chat không cần project. Bạn có thể yêu cầu: “Tạo bản nháp quy trình tổng hợp dữ liệu bán hàng trong thư mục scratch, ghi rõ các bước và các giả định cần kiểm tra.”

Mỗi chat có thư mục scratch riêng dưới Chats. Khi bản nháp đã rõ và trở thành công việc lập trình thật, dùng Continue in workspace để agent tạo handoff summary rồi chuyển sang workspace mới. Bạn không phải tự chép lại toàn bộ bối cảnh giữa hai phiên.

### Dev mới tiếp quản một codebase khó hiểu

Dev có thể yêu cầu agent đọc dự án và ghi lại kiến thức bền vững vào spec graph: “Đọc cấu trúc module thanh toán, xác định luồng xử lý chính và đề xuất các mục SPEC.md cần bổ sung. Không sửa code.”

ThinkRail dùng các file `SPEC.md` để lưu ý định dự án cạnh code. Sau đó, bạn có thể dùng dấu `#` trong palette để tìm phần spec liên quan đến một câu hỏi. Kết quả được xếp hạng theo công cụ `spec_search`, giúp tìm thông tin ngay cả khi câu hỏi không dùng đúng từ trong tài liệu.

### Nhóm phát triển cần chạy nhiều việc song song

Một người có thể mở nhiều work session trong các workspace khác nhau. Ví dụ, một chat yêu cầu agent sửa lỗi, chat thứ hai viết test, chat thứ ba đọc tài liệu và lập kế hoạch nâng cấp. Mỗi workspace có branch riêng nên nhóm dễ xem, chọn và merge kết quả phù hợp.

Prompt mẫu: “Tạo workspace riêng cho việc nâng cấp dependency, kiểm tra các thay đổi có thể gây lỗi tương thích, lập kế hoạch trước và chỉ commit sau khi tôi xác nhận.” Khi PR mở, ThinkRail hiển thị trạng thái CI và review để bạn quyết định bước tiếp theo.

> Workspace riêng giúp AI có chỗ làm việc an toàn, còn bạn vẫn giữ quyền chọn thay đổi nào được nhập vào dự án.
>
> — Ông T

### Kết nối model server nội bộ

Nếu công ty có gateway LLM hoặc model chạy trên máy riêng, vào Settings → Providers → Custom servers. README cho biết ThinkRail hỗ trợ mọi server tương thích OpenAI, gồm LiteLLM, sglang, vLLM, Ollama, LM Studio và llama.cpp.

Sau khi kết nối, dùng Find models để xem model và capability mà server cung cấp. Model được lưu vào `pi`'s `models.json`, xuất hiện trong bộ chọn model của chat và trong CLI `pi`. Không nên dán credential vào prompt hoặc file mã nguồn; hãy cấu hình ở provider và environment theo cách mà hệ thống yêu cầu.

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

### Terminal báo không tìm thấy `thinkrail`

Thường là terminal đang dùng chưa nạp lại `PATH`. Đóng và mở lại terminal rồi chạy `thinkrail --version`. Trên Windows, kiểm tra installer có được phép thêm PATH hay không; README liệt kê tùy chọn `THINKRAIL_NO_MODIFY_PATH`, nên tránh đặt tùy chọn này nếu bạn muốn installer tự sửa PATH.

### ThinkRail mở nhưng không chạy được agent

Kiểm tra bạn đã kết nối model provider chưa. ThinkRail cần JetBrains AI hoặc credential của provider trong `pi`; ứng dụng không có tài khoản riêng. Nếu dùng cấu hình `pi` khác, vào Settings → Environment và chọn đúng cấu hình, sau đó khởi động lại vì thay đổi có hiệu lực ở lần start tiếp theo.

### Clone hoặc push repo thất bại

ThinkRail dùng Git credential và SSH key đã có trên máy. Kiểm tra Git có trong `PATH`, credential có quyền với repository và SSH key đúng tài khoản. Nếu đang clone từ giao diện, kiểm tra thư mục cha, tên thư mục và lịch sử depth trước khi thử lại.

### Desktop Linux không khởi động hoặc thiếu thông báo

Kiểm tra Ubuntu có đủ mới và hệ thống đáp ứng glibc 2.38+. Sau đó cài các thư viện trong lệnh APT ở phần cài đặt. `libnotify-bin` đặc biệt liên quan đến thông báo desktop; các thư viện còn lại phục vụ GTK, WebKit, app indicator và SVG.

### Bản cài thủ công không tự cập nhật

README yêu cầu binary thủ công được đặt tên là `thinkrail`, hoặc `thinkrail.exe` trên Windows, và đặt tại `/bin/thinkrail[.exe]` để self-update hoạt động. Binary giữ tên asset phát hành hoặc nằm ở vị trí khác phải được thay thủ công hoặc cài lại bằng script. Với bản thủ công, hãy tải kèm `SHA256SUMS` và tự kiểm tra checksum trước khi chạy.

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

ThinkRail đáng dùng nếu bạn muốn một giao diện thống nhất cho chat với coding agent, chỉnh code, terminal, Git worktree, đặc tả dự án, skill, MCP và pull request. Cách tổ chức workspace cô lập đặc biệt hữu ích khi bạn thường giao nhiều việc cho AI nhưng vẫn muốn xem diff và quyết định cuối cùng trước khi merge.

Công cụ cũng phù hợp với nhóm đã dùng `pi`, vì ThinkRail chạy `pi` trong process và đọc cấu hình, model, skill cùng session state của `pi`. Việc kết nối được nhiều provider và model server giúp bạn không bị buộc vào một nhà cung cấp duy nhất.

Giới hạn cần cân nhắc là README chưa nêu yêu cầu phần cứng cụ thể, chưa mô tả đầy đủ quy trình build từ source và phần “Under the hood” đã bị cắt trong tư liệu cung cấp. Vì vậy, nếu bạn muốn tự biên dịch monorepo TypeScript, cần đọc thêm `package.json`, tài liệu kiến trúc và các hướng dẫn còn lại trong repo; không nên tự đoán lệnh build.

Về riêng tư, ứng dụng thu thập một số sự kiện cơ bản như lần mở app, tạo chat, gửi tin nhắn và kết nối provider, gắn với installation ID ngẫu nhiên. README nói analytics không chứa prompt, code, file, credential hoặc danh tính tài khoản; báo lỗi cũng không chứa đường dẫn, tên, URL hay dữ liệu từ project. Bạn có thể tắt chia sẻ bổ sung bằng `thinkrail --no-analytics` hoặc biến môi trường `THINKRAIL_NO_ANALYTICS=1` cho lần chạy đó.

```note
Không đưa API key, credential, SSH private key hoặc dữ liệu khách hàng vào prompt, feedback survey hay file project. Kiểm tra quyền của MCP server và provider trước khi cho agent chạy công cụ có thể ghi file, gọi mạng hoặc thay đổi repository.
```

Nếu bạn chỉ cần một CLI tối giản để hỏi AI trong terminal, `pi` có thể phù hợp hơn. Nếu bạn cần IDE có nhiều workspace, spec graph, kiểm soát Git và giao diện xem thay đổi, ThinkRail là lựa chọn đáng thử. Hãy bắt đầu bằng stable channel, một repo thử nghiệm và workspace riêng trước khi đưa vào codebase quan trọng.

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

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

Tư liệu cung cấp không nêu chính sách giá hoặc gói miễn phí của ThinkRail. README chỉ nói bạn có thể đăng nhập JetBrains AI hoặc kết nối provider và credential của riêng mình.

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

README không nêu yêu cầu GPU hay phần cứng cụ thể. Công cụ có thể kết nối model server chạy trên máy riêng hoặc các server tương thích OpenAI, nhưng tư liệu không khẳng định yêu cầu phần cứng cho từng trường hợp.

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

Có. Bản desktop hỗ trợ Windows x64 và CLI có installer PowerShell. README cũng cho biết CLI Windows là executable ký số.

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

Không theo README. ThinkRail không có tài khoản riêng; bạn đăng nhập JetBrains AI hoặc dùng credential của provider trong cấu hình `pi`.

### Dữ liệu và prompt có được gửi đi không?

README nói analytics không chứa prompt, code, file, credential hoặc danh tính tài khoản. Tuy nhiên, agent vẫn làm việc với model provider mà bạn kết nối, nên dữ liệu xử lý bởi provider phụ thuộc cấu hình và chính sách của provider đó.

### ThinkRail khác gì một coding agent chạy trong terminal?

ThinkRail cung cấp IDE có Monaco, cây file, terminal, Git worktree, nhiều chat, spec graph, skill, MCP và theo dõi pull request quanh `pi`. README cũng nói các công cụ hỏi đáp, sơ đồ và preview có thể được dùng dưới dạng pi package trong terminal.

### Có thể dùng model chạy trên máy công ty không?

Có. Settings → Providers → Custom servers cho phép kết nối server tương thích OpenAI, gồm LiteLLM, sglang, vLLM, Ollama, LM Studio và llama.cpp. Nút Find models hiển thị model cùng capability mà server cung cấp.
