AgentWrapper/agent-orchestrator

Kết luận: watch · Điểm bằng chứng: 92/100

AgentWrapper/agent-orchestrator là một lớp điều phối cho nhiều AI coding agents chạy song song, cho phép mỗi agent làm việc trong workspace cô lập bằng git worktree. Repo giải quyết vấn đề vận hành thực tế khi dùng nhiều agent cùng lúc: quản lý terminal/session, trạng thái công việc, pull request, lỗi CI, review comments và merge conflicts để đưa phản hồi về đúng agent.

✨ Tính năng nổi bật

• Chạy nhiều coding agents song song trong các workspace cô lập bằng git worktree
• Hỗ trợ nhiều agent CLI qua adapter chung: Claude Code, Codex CLI, Cursor, Aider, Goose, Copilot, Qwen Code và nhiều công cụ khác
• Quản lý terminal/session tập trung, có thể quan sát và gửi follow-up instruction vào đúng agent
• Theo dõi pull request, CI, review comments và merge conflicts để tự động route phản hồi
• Dùng runtime native như tmux trên Linux/macOS và conpty trên Windows
• Lưu trạng thái bền vững bằng SQLite với mô hình immutable facts và derived display status
• Phát sự kiện thay đổi qua CDC/SSE để UI/CLI cập nhật live
• Phù hợp cho mô hình agent fleet/agent swarm trong phát triển phần mềm

💡 Ý tưởng đáng học

💡 Tách mỗi agent session thành một git worktree riêng

Vì sao hay: Đây là cách đơn giản nhưng rất hiệu quả để nhiều agent cùng sửa một repo mà không đè file, không làm bẩn working tree chính và dễ tạo branch/PR riêng.

Áp dụng: Nếu dự án của bạn đang thử nhiều agent hoặc nhiều task song song, hãy tạo một worktree/branch cho mỗi task, đặt naming convention rõ ràng như agent/<task-id> và gom kết quả qua PR thay vì để agent cùng sửa một thư mục.

💡 Route feedback tự động từ CI/review/conflict về đúng session

Vì sao hay: Nút thắt lớn của agent coding không phải chỉ là sinh code, mà là vòng lặp sau đó: test fail, CI fail, reviewer comment, merge conflict. Tự động đưa feedback về đúng agent giúp giảm thao tác thủ công và tăng khả năng agent hoàn thành việc thật.

Áp dụng: Lưu mapping giữa branch/PR/session/agent. Khi webhook hoặc polling phát hiện CI failure hay review comment, tạo message ngữ cảnh và gửi vào terminal/session đang phụ trách branch đó.

🔥 Vì sao được chú ý

Repo nổi bật vì chạm đúng nhu cầu mới của lập trình viên: không chỉ dùng một AI coding agent, mà vận hành cả một đội agent chạy song song trên cùng codebase. Số sao cao, chủ đề như multi-agent, parallel-coding, git-worktrees, tmux, cùng việc hỗ trợ nhiều agent phổ biến khiến nó trở thành dự án đáng chú ý trong làn sóng agentic development.

⚙️ Kiến trúc

Kiến trúc tổng quan

• Local daemon / orchestrator: tiến trình trung tâm quản lý project, session, trạng thái agent, terminal runtime, PR/CI/review feedback và vòng lặp tự sửa.
• Session-per-agent: mỗi task hoặc agent session được tạo trong một git worktree riêng, tránh trộn thay đổi giữa các agent.
• Agent adapters: lớp adapter gọi các CLI agent khác nhau như Claude Code, Codex CLI, Cursor, Aider, Goose... thông qua một giao diện điều phối chung.
• Terminal runtime: dùng runtime native theo nền tảng, nổi bật là tmux trên Darwin/Linux và conpty trên Windows, để giữ terminal sống, quan sát được và có thể gửi lệnh tiếp.
• SCM/PR observer: theo dõi pull request, CI, review comments và merge conflicts, sau đó route feedback về session/agent sở hữu.
• Persistence layer: SQLite lưu facts/session/change log; trạng thái hiển thị được suy ra khi đọc thay vì ghi đè mọi thứ.
• CDC/SSE layer: DB trigger ghi thay đổi vào change_log, sau đó broadcast qua SSE để UI/CLI nhận cập nhật gần thời gian thực.

Luồng chính

1. Người dùng thêm project.
2. Tạo một hoặc nhiều session từ desktop app hoặc CLI.
3. Orchestrator tạo git worktree riêng cho mỗi session.
4. Agent adapter khởi chạy coding agent trong terminal runtime.
5. Daemon quan sát terminal, repo, PR, CI và review feedback.
6. Khi có lỗi CI, comment review hoặc conflict, hệ thống gửi ngữ cảnh về đúng agent để tiếp tục xử lý.

🧰 Tech stack

go · typescript · javascript · sqlite · tmux · git-worktrees · sse

✅ Kết luận

watch — Nên theo dõi và thử nghiệm trong workflow nội bộ, đặc biệt nếu bạn đã dùng nhiều coding agents. Tuy nhiên repo có phạm vi lớn, nhiều integration và nhiều issue mở, nên chưa nên adopt mù quáng cho quy trình sản xuất nếu chưa kiểm chứng độ ổn định trên repo thật của bạn.

🧭 Lộ trình đọc repo

1. Đọc README.md từ phần What is, Why và How it works — Để nắm đúng mental model: AO không phải coding agent mới, mà là lớp harness/orchestrator quản lý nhiều agent.
2. Tìm entrypoint CLI/daemon của phần Go — Ngôn ngữ chính là Go; entrypoint sẽ cho thấy cách project khởi động daemon, parse command, cấu hình project và điều phối session.
3. Đọc package quản lý project/session/worktree — Đây là lõi kiến trúc: cách tạo workspace cô lập, đặt branch, liên kết session với repo và lifecycle của agent.
4. Đọc phần agent adapters — Adapter layer cho biết repo trừu tượng hóa các CLI như Claude Code, Codex CLI, Aider, Goose như thế nào và đâu là interface chung đáng học.
5. Đọc phần terminal runtime, đặc biệt tmux/conpty — Terminal lifecycle là phần khó khi chạy agent tương tác dài; đây là nơi học cách attach, stream output và gửi instruction vào phiên đang sống.
6. Đọc phần persistence/SQLite/change_log/SSE — Để hiểu cách repo lưu facts, phát thay đổi realtime và giữ UI/CLI đồng bộ với daemon.
7. Đọc phần SCM/PR/CI/review observer — Đây là năng lực khác biệt: tự động route CI failures, review comments và merge conflicts về đúng agent session.