Agent CLI

Nếu bạn đã dùng Claude Code hoặc Codex, bạn có thể chạy chúng bên trong Perch. Chọn một agent trong bộ chọn mô hình, giao cho nó một thư mục, và nó làm việc ở đó bằng công cụ của riêng nó, với tài khoản đăng nhập của chính bạn. Các cuộc trò chuyện Perch và các agent của bạn nằm chung một thanh bên, nên bạn có thể theo dõi tất cả từ một nơi.

Mỗi agent làm việc trong bản sao kho mã riêng của nó, trên một nhánh riêng, nên nhiều agent có thể làm việc cùng lúc mà không đụng đến bản checkout của bạn. Khi một agent làm xong, bạn xem nó đã thay đổi gì rồi hợp nhất vào thư mục của mình bằng một cú nhấp, hoặc mở một pull request.

Trước khi bắt đầu

• Perch Desktop 2.5.4 trở lên, đã đăng nhập tài khoản Pro hoặc Ultra. Agent CLI không có trong Perch trên web.
• Claude Code hoặc Codex đã được cài trên máy tính này và đã đăng nhập. Nếu claude hoặc codex chạy được trong terminal của bạn, Perch có thể khởi động nó. Perch dùng bản cài đặt và tài khoản đăng nhập của bạn, và không đóng gói sẵn công cụ nào trong hai công cụ này.
• Git. Trên Windows, hãy cài Git for Windows. Việc hợp nhất cần git 2.40 trở lên.
• Một thư mục bạn đã thêm vào Perch, nằm trong một kho mã git có ít nhất một commit, để agent có thể có bản sao riêng.

Bắt đầu một agent

Thanh của cuộc trò chuyện hiển thị agent đang làm gì, tên của nó, thư mục và nhánh của nó, chẳng hạn agent/add-a-dark-mode-toggle-t-7q2m.

Mỗi cuộc trò chuyện giữ nguyên agent mà nó dùng lúc bắt đầu. Để quay lại các mô hình của chính Perch, hãy bắt đầu cuộc trò chuyện mới.

Trong lúc agent làm việc

• Yêu cầu phê duyệt được gửi đến bạn. Khi agent xin phép làm một việc gì đó, một thẻ hiển thị Claude asks to go ahead cùng các lựa chọn mà agent đưa ra.
• Mode đặt các chế độ riêng của agent, giống những chế độ nó có trong CLI của mình, chẳng hạn Accept edits cho Claude.
• Gửi tin nhắn tiếp theo bất cứ lúc nào. Trong lúc agent làm việc, những gì bạn gửi sẽ chờ và được gửi đi khi lượt kết thúc. Bạn có thể đính kèm ảnh PNG, JPEG, GIF hoặc WebP, tối đa 5 MB mỗi ảnh.
• Diff mở bảng Changes với mọi tệp mà agent đã thay đổi trong bản sao của nó.
• Open terminal mở một terminal bên cạnh cuộc trò chuyện, trong bản sao kho mã của agent.
• Chạy nhiều agent cùng lúc. Tối đa bốn agent có thể chạy đồng thời, mỗi agent trong bản sao riêng. Thanh bên cho biết agent nào đang làm việc.

Bản sao riêng của kho mã

Theo mặc định, mỗi agent làm việc trong một git worktree: một bản checkout thứ hai của kho mã, trong thư mục riêng, trên nhánh riêng. Thư mục của bạn, nhánh của thư mục đó và mọi thứ bạn chưa commit vẫn giữ nguyên trong lúc agent làm việc, và hai agent không bao giờ sửa cùng các tệp.

Một worktree chỉ có các tệp mà git theo dõi. Perch cũng mang sang những gì hầu hết dự án cần để chạy:

• Tệp cấu hình cục bộ. Các tệp .env và .env.*, ở bất kỳ cấp thư mục nào, được sao chép vào khi git bỏ qua chúng. Để sao chép các tệp bị bỏ qua khác, chẳng hạn cài đặt cục bộ hoặc chứng chỉ, hãy liệt kê chúng trong một tệp .worktreeinclude ở thư mục gốc của kho mã, theo cú pháp .gitignore. Một tệp chỉ được sao chép nếu git cũng bỏ qua nó trong bản sao, nên nó không bao giờ lọt vào một commit. Tối đa 200 tệp, mỗi tệp 10 MB và tổng cộng 50 MB. Symlink sẽ bị bỏ qua.
• Copy node_modules, trong Options trên macOS, clone node_modules của bạn vào bản sao. Đây là bản clone kiểu copy-on-write: gần như tức thì và không tốn thêm dung lượng ổ đĩa.
• Setup command, trong Options, chạy một lệnh như npm install trong bản sao trước khi agent bắt đầu, bằng shell của bạn (PowerShell trên Windows). Perch ghi nhớ lệnh này cho kho mã đó. Nếu lệnh thất bại hoặc chạy quá 15 phút, agent vẫn bắt đầu và cuộc trò chuyện sẽ báo điều đó. Setup log trên thanh của cuộc trò chuyện hiển thị đầu ra của lệnh.

Options còn có Worktree folder, nơi các bản sao được tạo, và Account folder: nếu bạn có nhiều tài khoản đăng nhập Claude Code hoặc Codex, hãy chọn thư mục của tài khoản muốn dùng. Cả hai phải nằm trong thư mục home của bạn.

Tắt Worktree để agent làm việc ngay trong thư mục của bạn. Khi đó, các thay đổi của nó xuất hiện trong thư mục của bạn ngay khi nó thực hiện, và không có bước diff hay hợp nhất.

Đưa công việc về

Khi một lượt thay đổi tệp, một thẻ bên dưới cuộc hội thoại sẽ báo điều đó, ví dụ: "Claude changed 4 files in its own copy of perch-app. They're not in your folder yet." Thanh của cuộc trò chuyện giữ số đếm các tệp này cho đến khi bạn đưa chúng về. Review changes mở diff.

Hợp nhất vào nhánh của bạn

Merge into main, mang tên của nhánh mà thư mục của bạn đang ở, đưa toàn bộ thay đổi của agent lên nhánh của bạn thành một commit. Thông điệp commit ban đầu là tiêu đề của cuộc trò chuyện, và bạn có thể sửa nó. Sau đó, Remove the copy xóa worktree và nhánh của agent.

Perch không bao giờ stash, reset hay ghi đè bất cứ thứ gì trong thư mục của bạn để hợp nhất. Thay vào đó, nó dừng lại và báo cho bạn khi:

• Thư mục của bạn có thay đổi chưa được commit. Hãy commit chúng trước, rồi hợp nhất.
• Cùng những tệp đã thay đổi cả trên nhánh của bạn lẫn trong bản sao của agent. Ask Claude to fix gửi cho agent một tin nhắn để nó xử lý việc này trong bản sao của mình. Khi nó xong, hãy hợp nhất lại.
• Thư mục của bạn không ở trên nhánh nào, hoặc git cũ hơn 2.40.

Các cách hoàn tất khác

Menu bên cạnh nút hợp nhất có thêm hai lựa chọn:

• Commit only commit các thay đổi trên nhánh riêng của agent. Thư mục của bạn không thay đổi.
• Open pull request đẩy nhánh của agent lên origin và mở một pull request. Nếu đã cài GitHub CLI (gh), Perch mở pull request cho bạn. Nếu chưa cài, Perch mở trang tạo pull request mới của GitHub. Với các dịch vụ lưu trữ git khác, Perch đẩy nhánh lên, và bạn mở pull request ở đó.

Đóng cuộc trò chuyện

Nếu bạn đóng một cuộc trò chuyện mà bản sao của nó vẫn còn thay đổi chưa có trong thư mục của bạn, Perch sẽ hỏi trước: Merge first, Keep the copy (worktree và nhánh của nó được giữ nguyên) hoặc Discard (xóa bản sao và nhánh của nó, kể cả các thay đổi).

Gói của chính bạn

Agent CLI chạy bằng tài khoản đăng nhập Claude Code hoặc Codex của chính bạn, nên mức sử dụng của chúng được tính vào gói đó, không tính vào mức sử dụng Perch của bạn. Tin nhắn gửi đến chúng không dùng mức sử dụng đi kèm của Perch.

Perch hiển thị các giới hạn riêng của từng agent theo những gì agent đó báo về, gồm 5-hour limit và Weekly limit, kèm thời điểm mỗi giới hạn được đặt lại. Bạn sẽ thấy chúng trên thẻ của agent trong bộ chọn mô hình và trong Settings › Usage dưới mục On this computer, và một ghi chú phía trên ô soạn tin sẽ cảnh báo bạn khi một agent sắp chạm giới hạn. Chúng xuất hiện sau câu trả lời đầu tiên của agent trên máy tính này.

Quyền riêng tư

• Các cuộc trò chuyện ở lại trên máy tính này. Cuộc trò chuyện với agent CLI không được lưu vào tài khoản Perch của bạn, nên chúng không xuất hiện trong Perch trên web hay trên điện thoại của bạn.
• Agent giao tiếp với dịch vụ của chính nó. Tin nhắn của bạn đi từ Claude Code đến Anthropic, hoặc từ Codex đến OpenAI, giống như khi bạn tự dùng CLI. Chúng không đi qua máy chủ của Perch.
• Mỗi agent chỉ nhận những gì nó cần. Perch khởi động agent với một danh sách ngắn các biến môi trường của bạn: không có khóa của agent khác và không có gì của Perch.

Với sub-session

Perch có thể giao một phần công việc cho Claude Code hoặc Codex. Hãy yêu cầu, ví dụ "để Codex sửa bài test chập chờn trong phiên riêng của nó", và Perch sẽ đề xuất một sub-session chạy trên agent đó, trong một worktree mới của thư mục của cuộc trò chuyện. Như mọi sub-session, nó chỉ bắt đầu khi bạn chọn Start, và nó báo cáo lại cho cuộc trò chuyện đã tạo ra nó. Các yêu cầu phê duyệt của agent vẫn được gửi đến bạn.

Khắc phục sự cố

Tôi không thấy On this computer trong bộ chọn mô hình. Kiểm tra rằng bạn đã đăng nhập tài khoản Pro hoặc Ultra trong Perch Desktop 2.5.4 trở lên.

Một agent báo Not installed. Cài agent đó để claude hoặc codex có trong PATH của bạn, rồi thoát và mở lại Perch.

Agent báo Needs sign-in. Chọn Sign in in a terminal, thao tác này chạy claude hoặc codex login cho bạn. Hoàn tất đăng nhập, rồi chọn Try again.

Agent báo CLI của nó cũ hơn phiên bản Perch cần. Hãy cập nhật nó. Với Claude Code, chạy claude update. Cập nhật Codex theo cách bạn đã cài nó, bằng npm hoặc Homebrew.

Agent báo cần Node 22. Thông báo đó đến từ các bản build của ứng dụng máy tính trước 2.5.4. Hãy cập nhật Perch Desktop, bản này chạy agent mà không cần Node.

Thư mục không thể có worktree. Thư mục phải nằm trong một kho mã git có ít nhất một commit. Bạn cũng có thể tắt Worktree.

Trên Windows, không xóa được bản sao. Một tệp trong đó đang được mở trong chương trình khác. Hãy đóng nó lại, rồi thử lại.