nhadaututtheky/companion

Kết luận: partial · Công nghệ: knowledge-base · developer-tooling · documentation · workflow · personal-productivity

Repo companion có vẻ là một công cụ hỗ trợ tri thức/cộng tác cá nhân cho developer, phù hợp kiểu knowledge base nội bộ hơn là framework hay platform. Với bối cảnh các dự án hiện có, đây có khả năng hữu ích nhất cho việc gom tài liệu, ghi chú vận hành và chuẩn hóa ngữ cảnh làm việc giữa nhiều repo.

📖 Giới thiệu chi tiết

🧩 Nó là gì?

nhadaututtheky/companion là một “trung tâm điều khiển” tự host để chạy và quản lý nhiều coding agent như Claude Code, Codex, Gemini và OpenCode trong cùng một giao diện. Nói đơn giản: thay vì mở nhiều terminal rời rạc, bạn có một dashboard để theo dõi, điều khiển, ghi nhớ ngữ cảnh dự án và phối hợp nhiều agent cùng lúc.

🎯 Giải quyết vấn đề gì? Dành cho ai?

Khi làm việc với AI coding agent, người mới rất dễ gặp các vấn đề như:

• Mỗi agent chạy ở một nơi khác nhau, khó theo dõi.
• Nhiều phiên làm việc song song bị rối, không biết phiên nào đang làm gì.
• Agent thiếu ngữ cảnh về dự án, phải giải thích lại nhiều lần.
• Muốn kiểm tra code, xem file, duyệt project, nhưng phải chuyển qua lại giữa nhiều công cụ.
• Muốn điều khiển agent từ xa, ví dụ qua Telegram.
• Muốn cho nhiều agent cùng “tranh luận”, review hoặc brainstorm trước khi sửa code.

companion phù hợp với:

• Developer dùng Claude Code, Codex, Gemini CLI hoặc OpenCode hằng ngày.
• Người làm nhiều repo, nhiều task cùng lúc.
• Team nhỏ muốn có một nơi gom session, ghi chú, project memory và lịch sử làm việc với agent.
• Người thích tự host công cụ của mình thay vì phụ thuộc hoàn toàn vào dịch vụ bên ngoài.

Nó không phải là một framework để viết app, cũng không phải IDE mới. Hãy nghĩ nó giống một “bàn điều phối” cho các AI coding agent.

⚙️ Hoạt động ra sao?

Cơ chế chính của companion khá dễ hiểu:

• Bạn chạy companion trên máy hoặc server của mình bằng Docker Compose.
• Mở web dashboard tại http://localhost:3579.
• Từ dashboard, bạn có thể tạo session cho Claude Code, Codex, Gemini hoặc OpenCode.
• Server Rust của companion đứng giữa, quản lý vòng đời session: bắt đầu, theo dõi, resume, cleanup.
• Web UI giao tiếp với server qua REST API và WebSocket.
  • REST API: dùng cho thao tác kiểu tạo/sửa/xem dữ liệu.
  • WebSocket: dùng để cập nhật realtime, ví dụ log agent đang chạy.
• Dữ liệu như project, session, message, settings, template và agent memory được lưu trong SQLite.
• Nếu cấu hình Telegram bot, bạn có thể điều khiển session từ Telegram: start, monitor, resume, approve.
• Magic Ring đóng vai trò như nơi chia sẻ ngữ cảnh giữa các session liên quan.
• Debate mode cho phép nhiều agent cùng review, tranh luận hoặc đưa ra kết luận.
• Preview Intelligence giúp review website hoặc hình ảnh thiết kế, rồi gửi nhận xét trực quan đó cho agent.
• File viewer cho phép duyệt và xem file project ngay trong UI.
• Activity Terminal hiển thị log realtime của agent, mở nhanh bằng `Ctrl+``.
• Command Palette cho thao tác nhanh bằng Ctrl+K.

Kiến trúc tổng quát:

Browser (Next.js 16 + React 19)
  ↕ WebSocket + REST
Companion Server (native Rust — axum, server-rs)
  ↕ CLI/SDK adapters
Claude Code · Codex · Gemini · OpenCode
  ↕ Session events + permission gates
Telegram Bot (teloxide, in-process)

🆚 Khi nào nên dùng / không nên

Nên dùng companion khi:

• Bạn thường xuyên dùng nhiều coding agent.
• Bạn muốn chạy nhiều session song song và nhìn trạng thái của chúng trong một dashboard.
• Bạn muốn tự host để kiểm soát dữ liệu tốt hơn.
• Bạn cần quản lý project memory, file context, log và lịch sử làm việc với agent.
• Bạn muốn điều khiển agent từ Telegram.
• Bạn muốn thử workflow nhiều agent cùng review hoặc tranh luận.

Không nên dùng companion khi:

• Bạn chỉ thỉnh thoảng hỏi AI vài câu đơn giản.
• Bạn chỉ dùng một agent trong terminal và thấy như vậy đã đủ.
• Bạn không muốn cài Docker hoặc tự vận hành công cụ.
• Bạn cần một sản phẩm SaaS “đăng nhập là dùng ngay”, không cần cấu hình.
• Bạn đang tìm một framework backend/frontend để xây app mới.

So sánh ngắn:

• Dùng trực tiếp Claude Code, Codex, Gemini CLI hoặc OpenCode: đơn giản hơn, ít cài đặt hơn, nhưng khó quản lý nhiều session và nhiều agent cùng lúc.
• Dùng companion: cần setup ban đầu, nhưng đổi lại có dashboard, session history, project context, Telegram bot, file viewer và workflow đa agent.

🚀 Bắt đầu nhanh

Yêu cầu trước:

• Đã cài Docker Desktop và Docker đang chạy.
• Có credential cho ít nhất một CLI được hỗ trợ, ví dụ Claude Code.
• Nếu dùng Claude Code trong Docker image mặc định, companion sẽ mount ~/.claude để dùng lại thông tin đăng nhập Claude Code.

Cài nhanh trên macOS / Linux:

curl -fsSL https://companion.theio.vn/install | sh
cd companion
docker compose up -d
# Open http://localhost:3579

Cài nhanh trên Windows PowerShell:

irm https://companion.theio.vn/install.ps1 | iex
cd companion
docker compose up -d
# Open http://localhost:3579

Cài thủ công:

git clone https://github.com/nhadaututtheky/companion.git
cd companion
cp .env.example .env
# Edit .env — set API_KEY (protects the web UI)
docker compose up -d --build
# Open http://localhost:3579

Ví dụ tối thiểu sau khi chạy:

1. Mở http://localhost:3579
2. Nhập API_KEY nếu được hỏi
3. Tạo một session mới
4. Chọn agent, ví dụ Claude Code hoặc Codex
5. Chọn project/thư mục cần làm việc
6. Gửi yêu cầu đầu tiên, ví dụ:
   "Đọc project này và tóm tắt kiến trúc chính cho tôi."

Một số biến môi trường quan trọng:

API_KEY=«bí mật đã ẩn»
COMPANION_LICENSE_KEY=
TELEGRAM_BOT_TOKEN=
«bí mật đã ẩn»
TELEGRAM_ALLOWED_CHAT_IDS=
ALLOWED_BROWSE_ROOTS=

Trong đó:

• API_KEY: mật khẩu bảo vệ web UI. Nên đặt khi chạy thật.
• COMPANION_LICENSE_KEY: license key từ companion.theio.vn; nếu không đặt thì dùng free tier.
• TELEGRAM_BOT_TOKEN: token bot lấy từ @BotFather nếu muốn dùng Telegram.
• TELEGRAM_ALLOWED_USER_IDS: giới hạn user Telegram được phép dùng bot.
• ALLOWED_BROWSE_ROOTS: giới hạn thư mục mà file browser được phép truy cập.

Cập nhật phiên bản mới:

git pull
docker compose up -d --build

Dữ liệu được lưu trong SQLite qua Docker volume, nên rebuild thường không làm mất session hoặc settings.

✅ Điểm mạnh & ⚠️ Hạn chế

✅ Điểm mạnh:

• Gom Claude Code, Codex, Gemini và OpenCode vào một dashboard.
• Chạy được nhiều session song song, dễ theo dõi trạng thái.
• Có session resume, giúp khôi phục phiên sau khi server restart.
• Có project memory và context chung, giảm việc phải giải thích lại cho agent.
• Có Debate mode để nhiều agent cùng review, brainstorm hoặc đưa ra verdict.
• Có Telegram bot để điều khiển từ xa.
• Có file viewer, activity log realtime, command palette và voice input.
• Backend viết bằng Rust, dùng SQLite, phù hợp để tự host gọn nhẹ.
• Docker Compose giúp cài đặt nhanh.
• Free để self-host; thương mại cần license theo Business Source License 1.1.

⚠️ Hạn chế:

• Cần biết setup Docker cơ bản.
• Muốn dùng agent nào thì runtime phải có CLI hoặc credential tương ứng.
• Nếu quên đặt API_KEY, người khác trong cùng mạng có thể truy cập web UI.
• Một số tính năng nâng cao như Telegram, Preview Intelligence, multi-agent workflow cần cấu hình thêm.
• Free tier có giới hạn, ví dụ 2 sessions nếu không có COMPANION_LICENSE_KEY.
• Không phải lựa chọn tối giản nếu bạn chỉ cần chat nhanh với AI hoặc chạy một CLI đơn lẻ.