Codenotch là gì?
Codenotch là ứng dụng macOS ghim một phần khuyết đen nhỏ gọn vào bất kỳ cạnh màn hình nào. Các vòng hiển thị lượng giới hạn sử dụng đã tiêu thụ của từng trợ lý lập trình được hỗ trợ, cùng trạng thái phiên đang hoạt động, đã hoàn tất hoặc đang chờ nhập liệu.
Khi không hoạt động, phần khuyết vẫn là một viên thuốc nhỏ và mở rộng khi con trỏ chạm đến. Di chuột lên vòng của nhà cung cấp để xem các khoảng giới hạn và thời điểm đặt lại. Với Claude Code, vòng chính đại diện cho cùng khoảng phiên hiện tại được Claude Code hiển thị đầu tiên bằng lệnh /usage.
Codenotch cũng theo dõi hoạt động của phiên. Một cung mảnh xoay bên trong vòng của nhà cung cấp khi phiên đang bận. Nếu phiên cần bạn chú ý, vòng sẽ chuyển sang trạng thái màu hổ phách nhấp nháy. Di chuột lên để xem tên phiên theo thời gian thực, nơi phiên đang chạy và phiên cần gì.
Nhà cung cấp và nguồn dữ liệu được hỗ trợ
Codenotch không duy trì hệ thống tài khoản riêng và không yêu cầu bạn đăng nhập. Ứng dụng đọc thông tin xác thực hoặc phiên đã được các công cụ được hỗ trợ lưu trên máy Mac của bạn.
- Claude Code: Sử dụng mã thông báo OAuth được lưu trong chuỗi khóa đăng nhập và truy vấn cùng điểm cuối mà lệnh
/usagecủa Claude Code sử dụng. - Cursor: Đọc phiên đã đăng nhập của trình soạn thảo từ trạng thái SQLite cục bộ.
- Codex: Yêu cầu máy chủ ứng dụng Codex đang chạy cung cấp giới hạn tốc độ hiện tại. Nếu Codex không chạy, Codenotch chuyển sang nhật ký rollout.
- Antigravity: Thử máy chủ ngôn ngữ cục bộ trước, sau đó gọi điểm cuối hạn ngạch của Google. Khi cả hai đều không cung cấp dữ liệu hạn ngạch cho tài khoản, ứng dụng hiển thị số lượng yêu cầu thuần túy.
- GLM: Gọi điểm cuối giám sát Gói Coding của Z.ai bằng khóa đã được Claude Code lưu trong
settings.json, ZCode hoặc OpenCode.
Hãy cài đặt và đăng nhập vào công cụ được hỗ trợ như bình thường. Khi Codenotch phát hiện phiên hoặc thông tin xác thực cục bộ của công cụ, vòng tương ứng sẽ xuất hiện. Việc tắt một nhà cung cấp trong phần Cài đặt sẽ ngừng cho phép Codenotch đọc thông tin xác thực đó và xóa các số liệu đã lưu, nhưng không đăng xuất bạn khỏi công cụ gốc.
Tính năng chính
- Vòng sử dụng cho Claude Code, Cursor, Codex, Antigravity và GLM.
- Chi tiết khoảng đặt lại khi di chuột lên vòng.
- Trạng thái bận và chờ theo thời gian thực cho các phiên lập trình.
- Tự động phát hiện nhiều cấu hình Claude Code.
- Đặt ở cạnh trên, dưới, trái hoặc phải của màn hình.
- Bố cục thích ứng với vùng màn hình có thể sử dụng, vị trí Dock và phần khuyết phần cứng.
- Tùy chọn hiển thị biểu tượng Dock, biểu tượng thanh menu hoặc không hiển thị biểu tượng nào.
- Tự động kiểm tra bản cập nhật hằng ngày ở chế độ nền thông qua Sparkle.
- Hiển thị các trạng thái
stale,needsAuthvàerrorthay vì phần trăm ước tính.
Xây dựng và chạy Codenotch
Điều kiện tiên quyết
Đây là ứng dụng macOS được tạo bằng XcodeGen. Cài đặt XcodeGen một lần bằng Homebrew:
brew install xcodegenTừ bản sao cục bộ của kho mã, hãy tạo dự án, xây dựng và khởi chạy bản Debug:
make runBản Debug không yêu cầu danh tính ký.
Chạy kiểm thử
Sử dụng đích kiểm thử của dự án để xác minh các bộ điều hợp nhà cung cấp và hành vi khác:
make testCác cấu trúc phản hồi của nhà cung cấp được cố định bằng kiểm thử vì các điểm cuối nội bộ, cơ sở dữ liệu cục bộ và giao diện RPC bên dưới có thể thay đổi mà không báo trước.
Sử dụng dữ liệu demo
Nếu muốn xem giao diện mà không đọc dữ liệu trực tiếp từ nhà cung cấp, hãy khởi chạy ứng dụng với CODENOTCH_DEMO=1:
CODENOTCH_DEMO=1 make runChế độ demo cung cấp dữ liệu mẫu cố định, hữu ích cho việc phát triển giao diện, kiểm tra bố cục và chụp ảnh màn hình.
make releasekhông thuộc quy trình thiết lập cục bộ thông thường. Lệnh này yêu cầu chứng chỉ Developer ID và hồ sơ notarize của App Store Connect, đồng thời được người bảo trì sử dụng để lưu trữ, notarize và tạo nguồn cấp dữ liệu cập nhật tự động đã ký.
Cách sử dụng cơ bản
1. Đăng nhập bằng công cụ riêng của nhà cung cấp
Mở công cụ lập trình bạn muốn theo dõi và đăng nhập tại đó. Codenotch không bao giờ tự thực hiện việc đăng nhập. Ví dụ, hãy xác thực bằng Claude Code hoặc Cursor như bình thường, sau đó khởi chạy Codenotch.
2. Kiểm tra các vòng nhà cung cấp
Mỗi nhà cung cấp được phát hiện sẽ xuất hiện dưới dạng một vòng trong phần khuyết. Sử dụng vòng để biết lượng giới hạn khả dụng đã được tiêu thụ. Di chuột lên vòng để xem các khoảng giới hạn khả dụng và thời điểm đặt lại.
3. Theo dõi trạng thái phiên
Khi một phiên được hỗ trợ đang hoạt động, hãy tìm cung mảnh đang xoay bên trong vòng. Vòng màu hổ phách nhấp nháy có nghĩa là phiên bị chặn và đang chờ bạn. Di chuột lên để xem tên phiên, vị trí và hành động được yêu cầu.
4. Cấu hình phần khuyết
Mở Cài đặt thông qua quả cầu bên dưới phần khuyết. Khi ở trạng thái nghỉ, nó hiển thị dưới dạng một cung và chuyển thành bánh răng khi di chuột lên. Trong Cài đặt, bạn có thể chọn phần khuyết có mở ra khi di chuột, luôn hiển thị hay ẩn hoàn toàn.
Bạn cũng có thể chọn Codenotch hiển thị biểu tượng Dock, biểu tượng thanh menu hoặc không hiển thị biểu tượng nào.
5. Chọn cạnh màn hình
Đặt phần khuyết ở bất kỳ cạnh nào trong bốn cạnh:
- Trái hoặc phải: Các số liệu nhà cung cấp xuất hiện theo cột dọc.
- Trên hoặc dưới: Các số liệu nhà cung cấp xuất hiện cạnh nhau.
Codenotch bám theo cạnh có thể sử dụng của màn hình. Khi đặt ở dưới, phần khuyết nằm phía trên Dock và phản hồi khi Dock ẩn hoặc di chuyển. Trên máy Mac có khuyết phần cứng, vị trí trên sử dụng chính xác hình dạng của khuyết để phần khuyết vật lý và phần khuyết phần mềm xuất hiện như một thành phần duy nhất.
Theo dõi nhiều tài khoản Claude Code
Codenotch có thể hiển thị các vòng riêng biệt cho các thư mục cấu hình Claude Code khác nhau. Ví dụ, khởi chạy tài khoản công việc bằng:
CLAUDE_CONFIG_DIR=~/.claude-work claudeSau khi Claude Code đã sử dụng thư mục đó, Codenotch sẽ phát hiện và hiển thị vòng Claude (work) bên cạnh tài khoản cá nhân. Tài khoản công việc có giới hạn, phiên và hàng Cài đặt riêng.
Khi khởi chạy, Codenotch tìm các thư mục khớp với ~/.claude-<slug> mà Claude Code đã sử dụng. Tài khoản ~/.claude mặc định luôn được đặt đầu tiên, còn các cấu hình bổ sung được sắp xếp theo thứ tự bảng chữ cái để vị trí các vòng không thay đổi ngoài dự kiến.
Hành vi làm mới và giới hạn tần suất
Codenotch điều chỉnh tần suất thăm dò để giảm các yêu cầu không cần thiết. Khi không có phiên được giám sát nào đang chạy, việc thăm dò sẽ giảm xuống còn năm phút một lần. Để yêu cầu đọc dữ liệu mới theo cách thủ công, hãy nhấp chuột phải vào phần khuyết và chọn Làm mới ngay.
Điểm cuối của Claude có thể trả về HTTP 429 khi bị truy vấn quá thường xuyên. Codenotch áp dụng thời gian chờ tăng dần, bắt đầu ở 60 giây, tăng gấp đôi sau các phản hồi liên tiếp do giới hạn tần suất và tối đa là 15 phút. Thời hạn này được duy trì qua các lần khởi chạy, ngăn việc khởi động lại lập tức tiêu tốn thêm một lượt thử.
Cập nhật và bảo mật
Codenotch sử dụng Sparkle để kiểm tra bản cập nhật hằng ngày và cài đặt chúng trong nền. Có thể tắt cập nhật tự động trong phần Cài đặt. Các bản cập nhật chính thức được ký bằng EdDSA để ứng dụng không cài đặt bản dựng không do người duy trì tạo ra và ký.
Đối với các nhà cung cấp sử dụng keychain, ứng dụng chính thức dùng một danh tính Developer ID ổn định để một lần cấp quyền Luôn cho phép có thể được duy trì qua các lần dựng lại. Codenotch kiểm tra ngày sửa đổi của mục keychain trước khi đọc lại bí mật, giúp giảm các lời nhắc truy cập lặp lại trong quá trình thăm dò định kỳ.
Ghi chú phát triển nâng cao
Kiến trúc nhà cung cấp
Mỗi tích hợp triển khai UsageProvider trong Sources/Providers/. Một nhà cung cấp cũng khai báo giá trị Fidelity là .official, .derived hoặc .manual. Điều này ngăn giao diện trình bày một giá trị suy ra như thể đó là giá trị được nhà cung cấp công bố trực tiếp.
UsageStore, nằm trong Sources/Model/, thăm dò các nhà cung cấp theo bộ hẹn giờ và lưu lại lần đọc thành công gần nhất qua các lần khởi chạy. Khi một nhà cung cấp gặp lỗi, kho hiển thị trạng thái rõ ràng như stale, needsAuth hoặc error thay vì tự tạo ra một phần trăm.
Bố cục ở mép màn hình
Bố cục phần khuyết hoạt động trong không gian ngăn xếp một chiều bằng các tọa độ along và across. NotchPlacement ánh xạ các giá trị đó sang tọa độ màn hình thực tế theo cạnh đã chọn. NotchLayout tập trung các phép đo dùng để so sánh phần triển khai với khung thiết kế.
Kiểm tra nhật ký chẩn đoán
Vì Codenotch không có cửa sổ ứng dụng thông thường, thông tin chẩn đoán được ghi vào nhật ký hợp nhất của macOS. Phát trực tiếp các thông báo gỡ lỗi bằng:
/usr/bin/log stream --predicate 'subsystem == "com.vinz.codenotch"' --level debugĐây là công cụ xử lý sự cố chính khi một nhà cung cấp không thể xác thực, trả về dữ liệu cũ hoặc gặp định dạng phản hồi đã thay đổi.
Hiểu các giới hạn
Không có nhà cung cấp được hỗ trợ nào công bố một API đơn giản, ổn định có thể báo cáo phổ quát chính xác phần trăm đã sử dụng của một phiên lập trình. Vì vậy, Codenotch đọc các nguồn nội bộ hoặc cục bộ tương tự những nguồn mà ứng dụng sở hữu sử dụng, bao gồm các điểm cuối, cơ sở dữ liệu, máy chủ ngôn ngữ và nhật ký.
Các giao diện đó có thể thay đổi mà không báo trước. Codenotch xử lý rủi ro này bằng các bài kiểm thử bộ chuyển đổi và trạng thái lỗi rõ ràng, nhưng một tích hợp nhà cung cấp vẫn có thể tạm thời ngừng hoạt động sau khi ứng dụng nguồn thay đổi.
Kết luận
Codenotch đưa thông tin sử dụng trợ lý lập trình, thời điểm đặt lại và trạng thái phiên đang hoạt động vào một màn hình nhỏ ở mép màn hình macOS. Bắt đầu bằng make run, sử dụng chế độ demo để khám phá giao diện một cách an toàn, sau đó để ứng dụng phát hiện các tài khoản đã được cấu hình trong những công cụ được hỗ trợ. Để biết thông tin về phát triển và đóng góp, hãy xem CONTRIBUTING.md. Dự án được cung cấp theo Giấy phép MIT.