# Paradev: chạy song song nhiều agent code trên một repo — hướng dẫn cài đặt và dùng

> Paradev (trước đây tên Superset) là ứng dụng desktop mã nguồn mở, giấy phép MIT, giúp bạn chạy nhiều agent code trong terminal cùng lúc trên một repository. Mỗi việc có worktree, nhánh và terminal riêng. Cài app khá đơn giản: tải bản cho macOS (hoặc Linux thử nghiệm), máy chỉ cần có Git. Bản Windows hiện chưa có.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-14 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/paradev-chay-song-song-nhieu-agent-code

Paradev là một ứng dụng desktop mã nguồn mở để chạy nhiều agent code dạng CLI (Claude Code, Codex, OpenCode, Gemini CLI, Cursor Agent…) song song trên cùng một repository. Mỗi công việc được giao cho một Git worktree, một nhánh và một bộ terminal riêng, nên các agent không giẫm lên file của nhau. Repo này trước đây tên là Superset, nên lệnh CLI của nó vẫn là `superset`.

Paradev dành cho người đã quen dùng một agent code trong terminal và bắt đầu thấy chật chội: muốn giao hai, ba việc cùng lúc mà không phải tự mở hàng chục tab terminal, tự tạo nhánh, tự nhớ agent nào đang làm gì. Nếu bạn chưa dùng agent code bao giờ thì nên làm quen một agent trước, rồi quay lại đây.

Điều đáng giá nhất: Paradev không phải là một agent. Bạn mang theo gói đăng ký và API key của chính mình, Paradev không đứng giữa chuyển tiếp các lệnh gọi mô hình. README nói rõ app trên máy bạn miễn phí vĩnh viễn, toàn bộ mã nguồn dưới giấy phép MIT. Repo hiện có khoảng 16.268 sao và 1.457 fork, vẫn được cập nhật trong 3 tháng gần đây.

```repo
- repo | ParadevAI/Paradev
- kind | Ứng dụng
- desc | Ứng dụng desktop mã nguồn mở để chạy Claude Code, Codex và các agent CLI song song, mỗi việc một Git worktree riêng, có review diff và trình duyệt xem thử.
- stars | 16k
- lang | TypeScript
- license | MIT
```

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

Phần này tóm các tính năng chính theo kiểu "dùng để làm gì", không chép lại README.

### Mỗi việc một worktree riêng

Mỗi task có một bản sao làm việc của repository, trên một nhánh riêng. Nhờ vậy bạn có thể cho một agent sửa lỗi đăng nhập, agent khác viết test, agent thứ ba thử đổi giao diện, cùng lúc. Bạn cũng có thể giao cùng một bài toán cho hai agent theo hai hướng rồi giữ bản ưng ý hơn.

README nhắc thẳng một giới hạn: worktree chỉ tách file làm việc. Nó không cô lập tiến trình (sandbox) và không tự ngăn xung đột khi merge.

### Xem và xử lý thay đổi ngay trong app

Có khung **Changes** để xem diff, bình luận, sửa, commit, push và mở pull request. Có thêm khung pull request với trạng thái checks, các luồng review và nút merge. Bạn không phải nhảy qua lại giữa terminal, trình soạn thảo và trang GitHub.

### Trình duyệt tích hợp

App có khung trình duyệt để xem thử dev server của từng workspace. Cổng (port) được phát hiện riêng cho mỗi workspace, nên mỗi worktree có bản xem thử của riêng nó. Chế độ **Design** cho phép bạn chọn một phần tử trên trang và gửi yêu cầu sửa kèm ngữ cảnh phần tử đó cho agent.

### Theo dõi trạng thái agent

Thanh bên cho biết agent nào đang làm, đã xong hay đang chờ bạn. Có chuông báo khi xong và huy hiệu trên dock khi cần bạn chú ý. Khi chạy nhiều việc, đây là phần giúp bạn đỡ bỏ sót.

### Terminal và tuỳ biến

Terminal có tab, chia khung không giới hạn, preset và phiên làm việc giữ lại sau khi khởi động lại app. Bạn có thể đặt script cài đặt, dọn dẹp và chạy cho từng workspace trong `.paradev/config.json`. Ngoài ra app mở nhanh sang Cursor, VS Code hoặc trình soạn thảo khác, và có tích hợp Slack, Linear.

### Ngoài một máy tính

Có CLI `superset`, SDK TypeScript, MCP server để agent tự tạo và quản lý workspace. Các tính năng như máy chủ từ xa, app iPhone/iPad và automations (agent chạy theo lịch hoặc theo sự kiện) thuộc gói Pro theo README. App desktop chạy agent trên máy bạn là miễn phí.

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

Theo README, thứ bắt buộc phải có sẵn chỉ là **Git**. Cụ thể:

- **Hệ điều hành**: macOS (cả Apple Silicon và Intel). Linux có bản AppImage x64 ở dạng thử nghiệm, macOS là nền tảng chính. **Windows chưa có.**
- **Git**: bắt buộc.
- **gh (GitHub CLI)**: không bắt buộc, dùng cho các luồng làm việc với PR. README nói Paradev đề nghị cài giúp bạn.
- **Agent CLI của bạn**: Paradev không phải agent, nên bạn cần có ít nhất một agent (ví dụ Claude Code hoặc Codex) với gói đăng ký hoặc API key riêng.
- **App iPhone/iPad**: cần Paradev Pro và iOS 26 hoặc iPadOS 26 trở lên. Bạn không cần phần này để bắt đầu.

Nếu bạn định build từ mã nguồn để đóng góp, cần thêm Bun từ phiên bản 1.4.3 (ghim trong `.bun-version`), `docker`, `jq` và `gh`. Người chỉ muốn dùng app thì bỏ qua phần này.

```note
Paradev không đưa key của bạn lên máy chủ trung gian để gọi mô hình, nhưng agent bạn kết nối vẫn tính phí theo gói hoặc API key của chính bạn. Hãy kiểm tra mức dùng ở nhà cung cấp agent khi chạy nhiều agent song song, vì nhiều việc cùng lúc nghĩa là tiêu hao nhiều hơn.
```

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

```steps
- Kiểm tra Git | Chạy git --version để chắc máy đã có Git
- Tải app | Lấy bản .dmg cho macOS (hoặc AppImage cho Linux) ở trang releases
- Thêm repository | Mở app, thêm repo có sẵn trên máy hoặc clone một repo
- Tạo workspace đầu tiên | Chọn agent CLI, mô tả một thay đổi nhỏ
- Cài CLI (tuỳ chọn) | Dùng curl hoặc brew để có lệnh superset
```

### Kiểm tra Git

Mở Terminal (trên macOS: bấm Cmd + Space, gõ Terminal, Enter) và chạy:

```bash
git --version
```

Nếu in ra số phiên bản là bạn đã có Git. Nếu báo không tìm thấy lệnh, cài Git từ trang https://git-scm.com/ rồi mở lại terminal.

### Tải ứng dụng

Vào trang releases của repo trên GitHub và tải đúng bản cho máy bạn. README liệt kê:

- macOS chip Apple Silicon: file `Superset-arm64.dmg`
- macOS chip Intel: file `Superset-x64.dmg`
- Linux x64 (thử nghiệm): file `Superset-x86_64.AppImage`
- Windows: chưa có

Tên file vẫn còn chữ Superset vì dự án mới đổi tên. Điều này bình thường. Nếu không chắc máy Mac của bạn chip nào, vào menu Apple rồi chọn About This Mac để xem. Sau khi tải xong, mở file `.dmg` và cài như các ứng dụng Mac thông thường.

### Thêm một repository

Mở Paradev và thêm một repository từ máy bạn, hoặc clone một repository mới. Nên chọn một dự án nhỏ, an toàn để thử lần đầu. Nếu cần clone bằng terminal, lệnh phổ thông là:

```bash
git clone https://github.com/<chủ-repo>/<tên-repo>.git
```

Thay phần trong dấu `<>` bằng repo của bạn. README không ghi các bước bấm chi tiết trong giao diện. Hướng dẫn từng màn hình nằm ở tài liệu "Your First Parallel Session" mà README dẫn tới (docs.paradev.com/first-workspace).

### Tạo workspace và chọn agent

Tạo một workspace, chọn agent CLI bạn dùng, rồi mô tả một thay đổi nhỏ muốn làm. Lúc này Paradev tạo worktree và nhánh riêng cho việc đó. Khi agent làm xong, bạn xem bản vá trong **Changes**, chạy test liên quan, xem thử ứng dụng trong khung trình duyệt rồi mới commit.

### Cài CLI `superset` (tuỳ chọn)

README cho biết CLI đi kèm sẵn trong app desktop. Nếu muốn cài riêng, có hai cách:

```bash
curl -fsSL https://paradev.com/cli/install.sh | sh
# hoặc
brew install paradevai/tap/superset
```

Dòng đầu tải script cài đặt từ trang của dự án rồi chạy. Đây là kiểu cài phổ biến nhưng bạn nên tự cân nhắc trước khi chạy script từ mạng. Dòng thứ hai dành cho người dùng Homebrew. Tên lệnh sau khi cài là `superset`. Cách dùng chi tiết xem ở docs.paradev.com/cli/getting-started.

### Build từ mã nguồn (chỉ cho người muốn đóng góp)

Cách này không dành cho người chỉ muốn dùng app. README hướng dẫn: clone repo, thêm vào app Paradev đã cài, tạo workspace cho thay đổi của bạn:

```bash
git clone https://github.com/paradevai/paradev.git
```

Sau đó, trong terminal của workspace đó, chạy:

```bash
./.paradev/setup.local.sh
bun run dev
```

Chạy `setup.local.sh` một lần cho mỗi worktree mới. Script này tự dựng Postgres, neon-proxy và Redis bằng Docker rồi tạo sẵn tài khoản dev, nên bạn không cần tài khoản Neon hay khoá dịch vụ bên thứ ba. Đăng nhập bằng nút "Sign in as dev". Hướng dẫn đầy đủ nằm trong `DEVELOPMENT.md`.

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

Theo README, cách kiểm tra tự nhiên nhất là chạy thử đúng quy trình "một việc nhỏ":

1. Mở app, thấy repository của bạn trong danh sách.
2. Tạo workspace, chọn agent, gõ một yêu cầu nhỏ (ví dụ sửa một dòng chữ trong README).
3. Thanh bên hiện trạng thái agent đang làm, rồi báo xong.
4. Vào **Changes** thấy bản vá agent tạo ra.

Nếu cả bốn bước đó diễn ra, bạn đã cài thành công. Với CLI, README chưa nêu lệnh kiểm tra cụ thể. Bạn có thể xem trang CLI getting started trong tài liệu để biết lệnh đầu tiên nên chạy.

Với bản build từ mã nguồn, dấu hiệu thành công theo README là app dev mở lên và bạn đăng nhập được bằng nút "Sign in as dev".

## 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 chỉ là ví dụ để bạn hình dung, hãy sửa theo dự án của bạn.

### Dev một mình gánh ba việc trong một buổi chiều

Bạn đang làm một ứng dụng web và có ba việc nhỏ: sửa lỗi form đăng ký, viết thêm test cho phần thanh toán, đổi tên một thành phần giao diện. Thay vì làm lần lượt, bạn tạo ba workspace, mỗi cái một agent. Prompt mẫu cho workspace đầu:

```text
Form đăng ký báo lỗi khi bỏ trống số điện thoại. Hãy tìm nguyên nhân, sửa và chạy test liên quan.
```

Bạn xem thanh bên: cái nào xong thì mở **Changes** xem diff, cái nào đang chờ bạn thì trả lời. Kết quả là ba nhánh riêng, mỗi nhánh một bản vá cần duyệt, thay vì một nhánh lộn xộn.

> Chạy song song không làm agent giỏi hơn, nhưng làm bạn bớt phải ngồi chờ.
>
> — Ông T

### Thử hai hướng giải cho cùng một bài toán

Bạn chưa chắc nên viết tính năng lọc sản phẩm theo cách A hay B. Tạo hai workspace, giao cùng yêu cầu nhưng gợi ý hai hướng khác nhau. Khi cả hai xong, xem hai bản vá cạnh nhau, chạy thử từng bản trong khung trình duyệt rồi giữ bản ưng ý. README mô tả đúng cách dùng này: "thử hai cách tiếp cận cho cùng một vấn đề và giữ cái bạn thích hơn".

### Chủ shop nhờ agent chỉnh giao diện trang web

Giả sử bạn có một trang bán hàng đơn giản do lập trình viên làm, và bạn muốn đổi màu nút "Đặt hàng". Mở trang trong khung trình duyệt của workspace, bật chế độ **Design**, chọn đúng nút đó và gõ yêu cầu bằng lời, ví dụ:

```text
Đổi nút này sang màu xanh lá và tăng cỡ chữ lên một chút.
```

Paradev gửi yêu cầu kèm ngữ cảnh phần tử bạn vừa chọn cho agent. Agent sửa, bạn xem lại ngay trong trình duyệt. Nếu không rành code, bạn vẫn nên nhờ người có kinh nghiệm xem diff trước khi đưa lên trang thật.

### Nhờ agent sửa pull request theo góp ý

Đồng nghiệp để lại góp ý trong một PR. Vào **Pull requests → Code**, chọn các dòng diff cần sửa, rồi gửi góp ý cho một phiên agent đang chạy hoặc tạo phiên mới. README ghi rõ việc đăng bình luận lên GitHub là tuỳ chọn. Bạn có thể cho agent sửa trước, xem kết quả rồi mới quyết định có phản hồi trên GitHub hay không.

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

README không có mục xử lý sự cố riêng. Phần dưới là những lỗi rất dễ gặp với loại công cụ này, kèm hướng xử lý an toàn.

### Không tìm thấy bản cài cho Windows

Đây không phải lỗi: README nói rõ Windows chưa có. Bạn có thể dùng máy Mac, hoặc thử bản Linux (thử nghiệm). Nếu chỉ có Windows, tạm chọn công cụ khác và theo dõi trang releases của repo.

### Chọn nhầm bản cho chip Mac

Nếu mở app báo không tương thích hoặc chạy chậm bất thường, có thể bạn tải nhầm bản Intel cho Mac Apple Silicon hoặc ngược lại. Kiểm tra chip trong About This Mac rồi tải lại đúng file `arm64` hoặc `x64`.

### Agent không chạy hoặc đòi đăng nhập

Paradev không cung cấp agent, nên agent như Claude Code hay Codex phải được cài và đăng nhập riêng bằng tài khoản của bạn. Hãy thử chạy lệnh của agent đó trong terminal thường trước. Nếu ở đó cũng không chạy thì vấn đề nằm ở agent, không phải Paradev.

### Các nhánh vẫn xung đột khi merge

Worktree chỉ tách file làm việc, không ngăn xung đột. Nếu hai agent sửa cùng một file, bạn vẫn phải xử lý xung đột khi merge. Cách giảm rủi ro là giao việc sao cho mỗi agent đụng vào các phần khác nhau của mã, và merge từng nhánh một.

### Tính năng PR báo thiếu gh

Các luồng pull request cần GitHub CLI (`gh`). README nói Paradev đề nghị cài giúp. Nếu bạn muốn tự cài trên Mac, README có nhắc lệnh Homebrew trong phần build từ mã nguồn:

```bash
brew install jq gh
```

Lệnh này cài cả `jq` lẫn `gh`. Nếu chỉ cần `gh` thì bạn chỉ cần phần tên đó.

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

**Điểm mạnh**

- Giải đúng một nỗi đau cụ thể: chạy nhiều agent mà không phải tự quản lý nhánh và terminal.
- Miễn phí cho app trên máy bạn, mã nguồn MIT, bạn có thể tự fork và chỉnh.
- Không phải agent riêng, nên bạn giữ gói đăng ký hiện có và đổi agent thoải mái. Agent nào chưa có trong danh sách vẫn chạy được mà không cần cấu hình.
- Có đủ khâu từ giao việc, xem diff, xem thử trình duyệt đến mở PR trong một chỗ.

**Giới hạn**

- Chưa có Windows. Linux mới ở mức thử nghiệm.
- Người chưa từng dùng agent code trong terminal sẽ thấy khó, vì app giả định bạn đã có agent.
- Worktree không phải sandbox và không chống xung đột merge.
- Chạy nhiều agent cùng lúc dễ tốn hạn mức hoặc chi phí agent hơn dự tính.
- Máy chủ từ xa, app di động và automations thuộc gói Pro. Mình không có thông tin về giá trong tư liệu này.
- Tên cũ Superset vẫn còn ở tên file tải và lệnh CLI, dễ gây nhầm. Nó không liên quan đến Apache Superset, công cụ phân tích dữ liệu.

**Khi nào nên chọn cách khác**: nếu bạn dùng Windows, nếu chỉ làm một việc mỗi lần, hoặc nếu bạn muốn một công cụ gồm cả agent lẫn mô hình trọn gói, thì một agent CLI đơn lẻ hoặc một trình soạn thảo có AI sẽ gọn hơn. Còn nếu bạn đã quen một agent và muốn nhân lên thành nhiều luồng việc có kiểm soát, Paradev đáng để thử trên một dự án nhỏ trước.

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

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

README ghi app desktop miễn phí vĩnh viễn: chạy agent song song trên máy của bạn sẽ không bao giờ yêu cầu trả tiền. Một số tính năng như app iPhone/iPad và automations thuộc gói Pro. Chi phí agent hoặc API bạn kết nối là chuyện riêng, bạn tự trả cho nhà cung cấp đó.

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

Chưa. README ghi rõ Windows chưa có bản cài. Hiện hỗ trợ macOS (Apple Silicon và Intel) và một bản AppImage x64 cho Linux ở mức thử nghiệm.

### Có cần GPU hay cấu hình mạnh không?

Tư liệu không nêu yêu cầu phần cứng nào, kể cả GPU. Paradev không tự chạy mô hình mà điều phối các agent CLI của bạn. Yêu cầu bắt buộc duy nhất README nêu là máy phải có Git.

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

README nói bạn tự chọn agent, nhà cung cấp và tích hợp nào để kết nối, và Paradev không chuyển tiếp các lệnh gọi mô hình. Tư liệu chưa mô tả chi tiết các biện pháp bảo mật khác. Nếu mã nguồn của bạn nhạy cảm, hãy đọc tệp SECURITY.md và tài liệu của dự án trước khi dùng.

### Paradev khác gì Claude Code hay Codex?

Claude Code và Codex là các agent code. Paradev không phải agent mà là không gian làm việc bao quanh chúng: tạo worktree riêng cho từng việc, review diff, xem thử trình duyệt, theo dõi trạng thái. Bạn vẫn dùng chính các agent đó với gói đăng ký của mình.

### Paradev có liên quan đến Apache Superset không?

Không. Paradev trước đây tên Superset và lệnh CLI vẫn là superset, nhưng README nói rõ dự án không liên quan đến Apache Superset, công cụ phân tích dữ liệu.

### Những agent nào dùng được với Paradev?

README liệt kê nhiều agent được hỗ trợ đầy đủ như Claude Code, OpenAI Codex CLI, Cursor Agent, Gemini CLI, OpenCode, GitHub Copilot và nhiều agent khác. Agent CLI nào không có trong danh sách vẫn chạy được mà không cần cấu hình, và bạn cũng có thể thêm agent tuỳ chỉnh.
