# Agent Commander — Full Technical & Product Reference

> Agent Commander (https://agentcmd.app) is a free mobile and desktop companion system that lets developers control AI coding agents running on their own computer from an iPhone, iPad, or Android phone.

---

## 1. Product Summary & Core Architecture

- **Product Name**: Agent Commander
- **CLI Binary Name**: `agentcmd`
- **Canonical URLs**:
  - Vietnamese: https://agentcmd.app/
  - English: https://agentcmd.app/en/
  - Press & Fact Sheet (EN): https://agentcmd.app/en/press
  - Press & Fact Sheet (VI): https://agentcmd.app/press
- **Store & Download Links**:
  - Apple App Store (iOS 15.0+ / iPhone & iPad): https://apps.apple.com/us/app/agent-commander/id6804532033
  - Google Play Store (Android): https://play.google.com/store/apps/details?id=app.thopd.agentcommander
  - Server Binary Releases (GitHub): https://github.com/phidinhtho/agentcmd
- **Supported AI Coding Agents**:
  1. **Claude Code** (Anthropic — Claude Code CLI)
  2. **Codex** (OpenAI — Codex CLI)
  3. **Antigravity** (Google)
  *(Only one installed and signed-in agent on the host computer is required to start working.)*
- **Server Platforms**:
  - macOS (Apple Silicon `arm64` and Intel `amd64`) — `launchd` background service + macOS menu bar companion app
  - Linux (`amd64` and `arm64`) — `systemd` user service
  - Windows 11 (`x64`) — Windows Task Scheduler background task + system tray companion app
  - WSL (Windows Subsystem for Linux)
- **Architecture & Data Flow**:
  1. **Computer (`agentcmd` service)**: A single lightweight Go binary + migrated SQLite database running in the background on the user's development machine. No external Postgres, Redis, or Node service is required.
  2. **Transport Security (Certificate Pinning)**: During initial setup, `agentcmd` generates a unique self-signed TLS key and certificate. Scanning the pairing QR code pins the SHA-256 fingerprint of that certificate in the mobile app. Every subsequent HTTPS REST and WSS WebSocket connection verifies that exact certificate fingerprint.
  3. **Multi-Address Failover**: The pairing QR code embeds all network addresses of the host computer (LAN IP, Tailscale IP `100.x.y.z`, or public IP/domain). When the user moves between home Wi-Fi and mobile data/café Wi-Fi with Tailscale enabled, the app automatically switches to a reachable address without re-pairing.
  4. **Wake-Up Push Relay**: When the mobile app is closed while a long coding turn runs, `agentcmd` sends a wake-up signal through a stateless push relay. The relay carries NO conversation content and stores NO project data.

---

## 2. Key Capabilities

1. **Real-Time Agent Streaming & Tool Inspection**:
   - Stream assistant responses, tool calls, files read/edited, and unified diffs in real time over WebSocket.
   - Tap project file links directly in the transcript to open them; type `@` in the composer to reference project files, and `/` in Claude conversations to invoke skills.
2. **Remote Approvals & Interactive Decisions**:
   - Approve or deny tool execution requests, review and approve implementation plans (`exit_plan_mode`), and answer multiple-choice or free-text agent questions from the phone.
   - In Claude conversations, send follow-up steering messages mid-turn or queue the next task.
3. **Multi-Agent Coordination & Managed Delegation**:
   - Choose Claude Code, Codex, or Antigravity per conversation, along with model and effort level.
   - Configure project delegation rules or delegate a specific turn to a sub-agent running in an isolated Git worktree branch. Review sub-agent reports, accept and three-way merge worktree changes into the project, or send feedback for another round.
4. **Live Terminal CLI Session Tracking & Branching**:
   - Watch live Claude CLI sessions started in a desktop terminal and read Codex CLI session history from the phone.
   - Branch a closed CLI session into a new app conversation while preserving the original terminal session untouched.
5. **Per-Project Governance & Customization**:
   - Configure permission modes (`ask first`, `accept edits`, `plan first`, `full access`), system prompts, allow/deny tool rules, MCP servers, custom sub-agents, and skills per project.
6. **Artifact Preview & Safe Export**:
   - Preview generated images, SVG, HTML, Markdown, JSON, and text files inside the app; save, share, or export selected artifacts into the project tree with conflict detection.
7. **Built-In Project File Explorer, Code Editor & Git Client**:
   - Browse multi-root project directories, read and edit code with syntax highlighting and conditional `If-Match` saves, view Git status badges, inspect per-file commit history, view the branch commit lane graph, inspect commit/file diffs, and run Git Pull / Push / Publish Branch from the phone.
8. **Token, Cost, Prompt Cache & Plan Quota Tracking**:
   - Track daily token usage, per-turn and per-agent token/cost breakdowns, Claude prompt cache read/write tokens, cache warmth countdown, and provider plan quota limits with reset reminders.

---

## 3. Installation & Pairing (3 Steps)

### Step 1: Install `agentcmd` on the computer
Run the one-line installer in your terminal:

- **macOS, Linux, or WSL (Terminal / bash / zsh)**:
  ```bash
  curl -fsSL https://github.com/phidinhtho/agentcmd/releases/latest/download/install.sh | bash
  ```
- **Windows 11 (PowerShell)**:
  ```powershell
  irm https://github.com/phidinhtho/agentcmd/releases/latest/download/install.ps1 | iex
  ```

What the installer and setup do automatically:
1. Detects OS/architecture, downloads the latest release from `https://github.com/phidinhtho/agentcmd`, and verifies its SHA-256 checksum.
2. Creates the data directory and migrated SQLite database.
3. Generates the TLS private key and certificate that the mobile app will pin.
4. Writes a user-only environment configuration file.
5. Installs and starts the background service (`launchd`, `systemd`, or Windows Task Scheduler).
6. Prints a pairing QR code in the terminal (valid for 10 minutes).

### Step 2: Install the mobile app and scan the QR code
1. Download **Agent Commander** from the [App Store](https://apps.apple.com/us/app/agent-commander/id6804532033) or [Google Play](https://play.google.com/store/apps/details?id=app.thopd.agentcommander).
2. Open the app and scan the QR code shown in the computer terminal.
3. If the QR code has expired (after 10 minutes), generate a fresh one anytime by running:
   ```bash
   agentcmd auth show
   ```

### Step 3: Create or select a project and send a task
1. Ensure at least one coding agent CLI (`Claude Code CLI`, `Codex CLI`, or `Antigravity`) is installed and signed in on the computer.
2. Add your project folder in the app, pick your agent and model, and send your first coding task.

---

## 4. Remote & Local Connection Guide (Tailscale & LAN)

### Connecting from outside your home/office network (Recommended: Tailscale)
1. Install [Tailscale](https://tailscale.com/download) on both the computer running `agentcmd` and your phone.
2. Sign in to the same Tailscale account on both devices and turn Tailscale **On**.
3. If you installed Tailscale after pairing `agentcmd`, run `agentcmd auth show` on the computer and re-scan the QR code once so the app learns the computer's `100.x.y.z` Tailscale address.
4. Keep your computer awake (disable sleep while plugged in) so background coding tasks continue uninterrupted while you are away.

### Connecting on the same local Wi-Fi / LAN
1. Connect both phone and computer to the same Wi-Fi/LAN network (avoid guest networks with client isolation).
2. On Windows/macOS, mark the Wi-Fi network as **Private** so the local firewall permits incoming LAN connections to `agentcmd`.
3. On iOS, allow **Local Network** permission for Agent Commander in *Settings → Privacy & Security → Local Network*.

### Useful CLI Diagnostic Commands
- Check background service status:
  ```bash
  agentcmd status
  ```
- Run full installation, agent, and network diagnostics:
  ```bash
  agentcmd doctor
  ```
- Show pairing QR code and TLS certificate fingerprint:
  ```bash
  agentcmd auth show
  ```

---

## 5. Privacy, Security & Data Deletion

- **No Account Required**: No sign-up, no email registration, no cloud profile, and no third-party SSO. Pairing with your own `agentcmd` server is the only identity.
- **Local Data Ownership**: Conversations, project files, and task lists live in the SQLite database and filesystem on your computer. The publisher of Agent Commander does not receive or store copies of your code or conversations.
- **Certificate-Pinned Transport**: All traffic between the mobile app and your computer uses HTTPS and WSS pinned to the TLS certificate generated on your machine.
- **Zero-Content Push Relay**: Push notifications only wake the device; conversation text is fetched directly from your computer over the pinned connection.
- **No Ads or Tracking**: Free app with no ads, no behavioral analytics, and no in-app purchases (only anonymous crash reports via Firebase Crashlytics).
- **Deleting Data**:
  - **Remove a single paired computer in the app**: Deletes only the local cached data and downloaded files for that server on the phone; other paired servers and data on the computer remain intact.
  - **Uninstall the mobile app**: Removes all local data and pinned credentials stored on the phone.
  - **Uninstall `agentcmd` on the computer**: Stop the background service and delete the `agentcmd` binary and data directory on your computer to permanently erase all server conversation history.
  - Full instructions: https://agentcmd.app/en/data-deletion (English) and https://agentcmd.app/data-deletion (Vietnamese).

---

## 6. Frequently Asked Questions (Bilingual EN / VI)

### Q1: Can I pair more than one computer? / Ghép nối nhiều máy tính được không?
- **EN**: Yes. Pair several computers, switch between them, and give each a name. Removing one device deletes only the app's local data associated with that device, including downloaded files; other paired devices and data on the computer remain.
- **VI**: Được. Ghép nối nhiều thiết bị, chuyển thiết bị và đặt tên riêng. Gỡ một thiết bị chỉ xoá dữ liệu cục bộ trong app thuộc thiết bị đó, gồm tệp đã tải về; các thiết bị khác và dữ liệu trên máy tính vẫn còn.

### Q2: Do I need an account? / Có phải tạo tài khoản không?
- **EN**: No. There is no sign-up and no profile. The app pairs once with a server you run yourself, and that pairing is the only identity involved.
- **VI**: Không cần đăng ký hay hồ sơ. App ghép nối với thiết bị chạy Agent Commander của bạn.

### Q3: Which coding agents does it work with? / App chạy cùng những agent lập trình nào?
- **EN**: Agent Commander officially supports Claude Code, Codex, and Antigravity. To start a conversation, you only need to install and sign in to one of the three on your computer.
- **VI**: Agent Commander chính thức hỗ trợ Claude Code, Codex và Antigravity. Để bắt đầu hội thoại, bạn chỉ cần cài và đăng nhập một trong ba trên máy tính.

### Q4: Where does my code live? / Mã nguồn của tôi nằm ở đâu?
- **EN**: Your project folders and conversation database live on your computer, under your control. The publisher does not keep a conversation copy.
- **VI**: Thư mục dự án và cơ sở dữ liệu hội thoại nằm trên máy tính, do bạn kiểm soát. Nhà phát hành không giữ bản sao hội thoại.

### Q5: Can I reach my computer from another network? / Ở mạng khác có vào được máy tính của tôi không?
- **EN**: Yes, through Tailscale or a public address. The pairing code carries every address your server has, local network included, and when one stops answering the app moves to another on its own — no new scan.
- **VI**: Được, qua Tailscale hoặc địa chỉ công khai. Mã ghép nối mang mọi địa chỉ của thiết bị, kể cả địa chỉ mạng LAN, và khi một địa chỉ ngừng trả lời thì app tự chuyển sang địa chỉ khác — không phải quét lại.

### Q6: Can I pick up work I started in the terminal? / Việc đang làm dở ở terminal có tiếp tục được không?
- **EN**: Yes. Follow Claude CLI sessions live and read Codex CLI history. From a closed session, branch into a new app conversation and keep working from your phone, with the terminal history available to read and the original session preserved.
- **VI**: Được. Theo dõi trực tiếp phiên CLI của Claude và đọc lịch sử CLI của Codex. Từ phiên đã đóng, rẽ nhánh thành hội thoại mới trong app để làm tiếp trên điện thoại, với lịch sử terminal sẵn để đọc và phiên gốc được giữ nguyên.

### Q7: What does it cost? / Chi phí thế nào?
- **EN**: The app is free: no in-app purchases, no subscription, and no ads. Whatever your coding agent costs to run is billed by your existing plan with its provider, not by us.
- **VI**: App miễn phí: không mua trong ứng dụng, không thuê bao, không quảng cáo. Còn tiền chạy agent lập trình thì tính vào gói bạn đang có với nhà cung cấp của nó, không phải với chúng tôi.