Hướng dẫn Harp: Sắp xếp các tác nhân Claude Code và Codex trong thanh bên macOS gọn gàng

Harp là một nhánh macOS không chính thức của terminal Warp mã nguồn mở. Harp giữ lại các khả năng terminal, AI và đám mây của Warp, đồng thời thay thế thanh tab truyền thống bằng thanh bên được thiết kế cho các tác nhân lập trình chạy trong thời gian dài.

Với Harp, bạn có thể chạy nhiều phiên Claude Code và Codex cạnh nhau, đồng thời nhanh chóng biết phiên nào đang làm việc, chờ bạn, đã hoàn tất, đang chạy nền hoặc được tạm cất. Harp không vận hành máy chủ riêng; các tính năng Warp từ upstream vẫn tiếp tục giao tiếp với máy chủ của Warp như trong Warp.

Harp bổ sung những gì

Xem nhanh trạng thái tác nhân

Mỗi hàng trong thanh bên có thể hiển thị trạng thái của một phiên Claude Code hoặc Codex. Dấu chưa đọc sẽ vẫn hiển thị cho đến khi bạn kiểm tra phiên, dấu chấm cho biết tác vụ nền vẫn đang chạy, còn biểu tượng mặt trăng xác định tab bạn đã tạm cất. Dùng Cmd+R để đổi tên tab.

Nhóm cố định

Bạn có thể đưa các tab vào những nhóm được đặt tên để giữ cho dự án và tác nhân luôn ngăn nắp. Khi bật tích hợp tmux, Harp lưu nhóm và thứ tự trên các phiên tmux. Nhờ đó, bố cục vẫn được giữ sau khi khởi động lại và các ứng dụng tmux khác có thể thấy cùng cách sắp xếp.

Vòng giới hạn sử dụng

Chân thanh bên có thể hiển thị hai vòng cho mỗi nhà cung cấp: một vòng cho khung thời gian năm giờ và một vòng cho giới hạn hằng tuần. Harp đọc các giá trị này từ một tệp JSON cục bộ do công cụ bạn chọn duy trì. Harp không tự lấy dữ liệu sử dụng. Xem tài liệu định dạng vòng giới hạn để biết định dạng tệp cần có.

Phiên tmux thân thiện với điện thoại

Các phiên được gắn với tmux có thể mang theo tên, nhóm, trạng thái đã đọc và cờ không hoạt động. Một phiên tmux được khởi chạy ở nơi khác, chẳng hạn từ điện thoại qua SSH, có thể yêu cầu một tab Harp bằng cách đặt tùy chọn tmux @warp_adopt thành 1.

Cài đặt Harp

Cài đặt bản dựng macOS mới nhất

1. Mở bản phát hành Harp mới nhất từ trang GitHub Releases.
2. Tải xuống tệp Harp-<version>.dmg.
3. Mở ảnh đĩa và kéo Harp vào thư mục Applications.

Harp sử dụng mã định danh bundle riêng, com.dominikmartn.Harp, lược đồ URL, harp://, và thư mục cài đặt, ~/.harp. Nhờ đó, Harp có thể chạy cùng Warp mà không dùng chung các tài nguyên này.

Xây dựng từ mã nguồn

Để tự xây dựng Harp, hãy sử dụng macOS và bộ công cụ Rust được chỉ định trong rust-toolchain.toml. Từ thư mục gốc của kho mã, chạy tập lệnh bootstrap một lần:

./script/bootstrap

Sau đó biên dịch và khởi chạy ứng dụng gỡ lỗi:

./script/run

Bản dựng tạo ra target/debug/bundle/osx/Harp.app và khởi chạy ứng dụng. Tập lệnh chạy trên macOS ký ứng dụng bằng danh tính Apple Development đầu tiên trong keychain của bạn hoặc chuyển sang chữ ký ad-hoc. Để tạo DMG phát hành đã ký và có thể notarize, hãy dùng script/release_macos và xem phần trợ giúp của tập lệnh.

Cấu hình Harp

Các tích hợp bổ sung của Harp mặc định bị tắt. Tạo hoặc chỉnh sửa ~/.harp/settings.toml, sau đó bật những tính năng bạn cần. Harp sẽ tải lại tệp cài đặt khi tệp thay đổi.

[integrations.limit_rings]
enabled = true
file = "~/.cache/limit-rings.json"

[integrations.tmux]
enabled = true

Bật vòng giới hạn sử dụng

Đặt integrations.limit_rings.enabled thành true và trỏ integrations.limit_rings.file đến tệp JSON cục bộ chứa các giá trị sử dụng của nhà cung cấp. Ký tự ~ đại diện cho thư mục chính của bạn.

Bật đồng bộ hóa tmux

Đặt integrations.tmux.enabled thành true để bật đồng bộ hóa tmux, tiếp nhận phiên và phát hiện tác nhân bên trong tmux. Harp thăm dò tmux mỗi 10 giây.

Khi bật tmux, tên, nhóm, thứ tự, cờ đã đọc, cờ không hoạt động và các phiên được tiếp nhận có thể được đồng bộ hóa. Nếu cần hành vi tùy chỉnh, integrations.tmux.session_script có thể trỏ đến một tập lệnh xử lý việc đổi tên và gom nhóm. Tập lệnh nhận các lệnh theo các dạng sau:

<script> rename <shell_pid> <group> <title>
<script> group <session_id> <old_group> <new_group>

Điều chỉnh thanh bên và thanh công cụ tác nhân

• appearance.vertical_tabs.full_tab_menu mặc định là true. Đặt thành false để rút gọn các menu tab và nhóm, chỉ giữ lại những thao tác thiết yếu. Tùy chọn này cũng có trong Settings > Appearance > Tabs.
• agents.third_party.should_render_cli_agent_toolbar mặc định là false. Đặt thành true để khôi phục thanh công cụ upstream bên dưới các phiên tác nhân CLI.

Khi thanh công cụ tác nhân CLI bên thứ ba bị tắt, hãy cập nhật plugin Warp cho Claude Code thông qua chợ plugin của Claude Code, như dự án hướng dẫn.

Sử dụng Harp với các tác nhân lập trình

1. Mở Harp và tạo các phiên cho quy trình Claude Code hoặc Codex của bạn.
2. Đổi tên các tab bằng Cmd+R để dễ nhận biết mục đích của chúng.
3. Đưa các phiên liên quan vào những nhóm được đặt tên, chẳng hạn mỗi dự án một nhóm.
4. Theo dõi các chỉ báo trạng thái trên thanh bên để xác định những phiên cần bạn chú ý, vẫn đang làm việc hoặc đã hoàn tất.
5. Tạm cất những phiên bạn chưa cần ngay; Harp đánh dấu chúng bằng biểu tượng mặt trăng.
6. Mở các phiên chưa đọc khi bạn sẵn sàng xem lại kết quả.

Có thể tạo tab mới bằng Cmd+T, bằng cách nhấp đúp hoặc thông qua menu nhấp chuột phải trên vùng trống của thanh bên. Dự án chủ động loại bỏ một số điều khiển trên thanh tab, bao gồm trường tìm kiếm, tùy chọn chế độ xem và các nút cấu hình tab.

Tiếp nhận một phiên được bắt đầu ở nơi khác

Khi một phiên tmux được tạo từ thiết bị hoặc terminal khác, bạn có thể yêu cầu Harp tiếp nhận phiên đó dưới dạng một tab. Trong phiên tmux tương ứng, hãy chạy:

tmux set-option @warp_adopt 1

Sau khi bật tích hợp tmux, Harp có thể theo dõi phiên đó và phản ánh tên, nhóm cũng như trạng thái của phiên trong thanh bên. Tính năng này hữu ích để tiếp tục công việc được bắt đầu qua SSH, kể cả từ điện thoại.

Kết nối tính năng báo cáo tác vụ nền của Claude Code

Kho mã nguồn có một hook Claude Code để báo cáo các tác vụ nền cho Harp. Hướng dẫn tích hợp có tại integrations/claude-code. Hãy sử dụng các hướng dẫn đó khi bạn muốn hoạt động nền hiển thị trong thanh bên.

Tùy chọn phát triển nâng cao

Theo dõi thay đổi trạng thái

Để kiểm tra hồi quy dựa trên bản ghi tác nhân, hãy khởi chạy bản dựng gỡ lỗi với WARPOSS_STATUS_TRACE=1. Harp ghi các thay đổi trạng thái vào ~/Library/Logs/harp.log dưới dạng các dòng [status-check].

Chạy mà không cần đăng nhập thực tế

Đặt WARPOSS_SKIP_LOGIN=1 khi khởi chạy để bắt đầu với người dùng kiểm thử và khiến các yêu cầu xác thực thất bại. Tùy chọn này dành cho các lần chạy tự động không sử dụng đăng nhập.

Sử dụng hồ sơ dữ liệu gỡ lỗi biệt lập

Đối với các bản dựng gỡ lỗi, hãy đặt WARP_DATA_PROFILE=<name> để lưu cài đặt và dữ liệu trong ~/.harp-<name> thay vì vị trí hồ sơ mặc định.

Xác thực các đóng góp

Trước khi gửi thay đổi, hãy chạy các bước kiểm tra presubmit của kho mã nguồn:

./script/presubmit

Thao tác này sẽ chạy kiểm tra định dạng, Clippy và các bài kiểm thử.

Kết luận

Harp biến terminal Warp thành một không gian làm việc để quản lý nhiều phiên Claude Code và Codex chạy dài. Hãy cài đặt ứng dụng macOS hoặc tự dựng từ mã nguồn, bật các tích hợp tmux và limit-ring khi cần, sau đó sử dụng nhóm và chỉ báo trạng thái để duy trì tổ chức cho quá trình phát triển có tác nhân hỗ trợ. Harp là một nhánh không chính thức của Warp, vì vậy hãy báo cáo các vấn đề riêng của Harp cho kho mã nguồn của dự án thay vì cho Warp.