A sleek, transparent desktop overlay that automatically triggers a beautiful Warp Speed particle animation when using OpenCode — any provider (xAI/Grok, and more).

• Auto show/hide animation when OpenCode is generating (any provider: xAI/Grok, …)
• Canvas particle field: 11 styles (default Hyperspace + Signal waves, Datastream, Orbit, …)
• Reactive motion: start kick · idle shimmer · token heartbeat · multi-session tint · completion bloom
• Multi-process: several OpenCode windows at once — overlay stays up until all gens end
• Fully transparent overlay · does not steal IDE focus on generation start
• Works with your existing OpenCode setup (no extra API key)
• Tauri 2 (Rust) + Svelte 5 + Python bridge (logs + SQLite token poll)
• Token flow chips · per-style alpha · Windows & macOS
• Shim/oc keep your project cwd (OpenCode opens the folder you ran from)

• Tauri 2 + Svelte 5 + TypeScript + Vite · Canvas 2D particles
• Rust (tiny_http localhost event server)
• Python 3 bridge (opencode_bridge: detect, emit, log claims, DB poll)

⚠️ Actively developed. Contributions and feedback are welcome!

Status: stable for daily use — OpenCode TUI works normally, particles auto show/hide, no [EVENT] spam on chat (logs go to file / settings diagnostics).

Settings panel	Generating (warp particles)

• demo.gif — End-to-end animation demo
• demo-1 — Settings (styles, Style alpha, Token flow, intensity, speed, Test warp)
• demo-2 — Transparent overlay, full-bleed particles while generating

Media: public/. Full setup guide (Windows + macOS) below.

📖 Docs site (GitHub Pages): sonht113.github.io/overlayagent-opencode

1. Tổng quan
2. Yêu cầu
3. Setup Windows
4. Setup macOS
5. Dùng hàng ngày
6. Settings overlay
7. Lệnh & API
8. Kiến trúc
9. Cấu trúc thư mục
10. Troubleshooting
11. Gỡ cài đặt

Agent Overlay là cửa sổ desktop trong suốt (Tauri) hiển thị animation particles khi OpenCode đang generate. Có 11 style (mặc định Hyperspace; Signal = sóng đồng tâm) và chỉnh alpha theo style.

Luồng tự động (Windows / macOS giống nhau):

Login
  → start-overlay (autostart) → tray, window ẩn, HTTP :9876

Terminal (cwd = project của bạn)
  → gõ: opencode   (hoặc oc)
  → shim/oc set PYTHONPATH + AGENT_TOOL_ROOT (không cd tool root)
  → opencode_bridge → OpenCode TUI (thật, đúng project)
  → generate → POST event (+ bridge_pid, session_id) → Overlay particles
  → generation_end (per session) → khi không còn session → fade → ẩn

Env chung: AGENT_TOOL_ROOT, OPENCODE_CMD, OPENCODE_REAL, TAURI_EVENT_URL, OPENCODE_DB / OPENCODE_DATA_DIR / OPENCODE_LOG_DIR.

Tool root: clone repo bất kỳ đâu. oc.ps1 / shim / start-overlay resolve root theo vị trí script (hoặc AGENT_TOOL_ROOT). Không bắt buộc C:\Work\Tool — các ví dụ bên dưới dùng path đó chỉ mang tính minh họa.

Làm tuần tự. Sau bước 2–4 nên đóng hết terminal rồi mở lại.

# Clone repo rồi cd vào thư mục đó (ví dụ $env:AGENT_TOOL_ROOT)
cd $env:AGENT_TOOL_ROOT\agent-overlay   # hoặc: cd path\to\overlayagent-opencode\agent-overlay
npm install

# Production binary (khuyến nghị cho dùng thật)
npm run tauri build

# Hoặc dev (hot reload, chậm lần đầu)
# npm run tauri dev

Thành công: icon Agent Overlay trên system tray, window ẩn.

Kiểm tra HTTP bridge:

Invoke-RestMethod http://127.0.0.1:9876/health
# Kỳ vọng: ok=true, service=agent-overlay, port=9876

Nếu chưa có exe release, start-overlay.ps1 vẫn dùng target\debug\agent-overlay.exe nếu đã tauri dev / cargo build trước đó.

cd C:\Work\Tool
powershell -ExecutionPolicy Bypass -File .\install-shim.ps1

Script sẽ:

• Tìm OpenCode thật (ưu tiên …\opencode-ai\bin\opencode.exe)
• Ghi config: C:\Work\Tool\.agent-bridge\config.json
• Bật monitoring: .agent-bridge\monitoring.enabled
• Prepend C:\Work\Tool\shim (+ Tool root) vào User PATH

powershell -ExecutionPolicy Bypass -File .\install-autostart.ps1

Optional — thêm daemon giữ overlay sống:

powershell -ExecutionPolicy Bypass -File .\install-autostart.ps1 -WithDaemon

Tạo shortcut trong thư mục Startup của Windows.

notepad $PROFILE

Thêm:

. C:\Work\Tool\profile-snippet.ps1

Lưu → restart Warp / PowerShell.

Profile cung cấp:

• oc, Start-AgentOverlay
• Enable-AgentMonitor / Disable-AgentMonitor / Get-AgentStatus
• PATH shim + Tool root trong session

Trong terminal mới:

where.exe opencode
# Dòng đầu: C:\Work\Tool\shim\opencode.cmd

Get-Content C:\Work\Tool\.agent-bridge\config.json
# opencode_cmd trỏ tới ...\opencode.exe (không phải shim)

Invoke-RestMethod http://127.0.0.1:9876/health

# Mở TUI (phải vào giao diện OpenCode, chat sạch)
opencode

Làm trên MacBook (bash/zsh). Repo path ví dụ: ~/Tool hoặc clone git.

# Xcode command line tools (nếu chưa)
xcode-select --install

# Node, Python (Homebrew)
brew install node python rustup
rustup default stable

# OpenCode
npm install -g opencode-ai
# hoặc theo hướng dẫn opencode.ai

export AGENT_TOOL_ROOT=/path/to/Tool   # thư mục chứa opencode_bridge + agent-overlay
cd "$AGENT_TOOL_ROOT/agent-overlay"
npm install
npm run tauri build
# → …/src-tauri/target/release/bundle/macos/Agent Overlay.app

Dev (hot reload):

npm run tauri dev

cd "$AGENT_TOOL_ROOT"
chmod +x start-overlay.sh oc.sh install-shim.sh install-autostart.sh shim/opencode
./install-shim.sh

Script sẽ:

• Tìm OpenCode thật (PATH, npm global, Homebrew)
• Ghi .agent-bridge/config.json
• Thêm shim + AGENT_TOOL_ROOT vào ~/.zshrc (hoặc .bashrc)

source ~/.zshrc
which opencode
# …/Tool/shim/opencode

./install-autostart.sh
# LaunchAgent: ~/Library/LaunchAgents/com.agent.overlay.plist

# ~/.zshrc
export AGENT_TOOL_ROOT=/path/to/Tool
source $AGENT_TOOL_ROOT/profile-snippet.zsh

Helpers: oc, start-agent-overlay, enable-agent-monitor, get-agent-status.

./start-overlay.sh
curl -s http://127.0.0.1:9876/health
# {"ok":true,"service":"agent-overlay",…}

opencode
# hoặc: ./oc.sh

export AGENT_TOOL_ROOT=/path/to/Tool
export OPENCODE_CMD="$(command -v opencode)"  # binary thật, trước khi prepend shim
cd "$AGENT_TOOL_ROOT"
./start-overlay.sh
python3 -m opencode_bridge run

1. Login → overlay chạy nền (tray) nếu đã autostart.
2. Mở terminal.
3. Chạy:

opencode

hoặc:

oc

4. Làm việc / generate với OpenCode như bình thường (mọi provider).
5. Overlay tự hiện khi generate, tự ẩn khi xong.
6. Không còn dòng [EVENT] … đè lên ô chat (đã tắt print console).

Mặc định im lặng trên console để không phá TUI. Muốn xem log event trên terminal:

# Windows
$env:AGENT_BRIDGE_VERBOSE = "1"
opencode

# macOS
export AGENT_BRIDGE_VERBOSE=1
opencode

Event vẫn luôn được ghi vào:

• $AGENT_TOOL_ROOT/.agent-bridge/last_events.jsonl (Win: C:\Work\Tool\…)
• Settings → Recent events
• GET http://127.0.0.1:9876/events

# Windows
Invoke-RestMethod -Method POST http://127.0.0.1:9876/event `
  -ContentType "application/json" `
  -Body '{"event":"generation_start","data":{"model":"test","provider":"xai"}}'

# macOS
curl -s -X POST http://127.0.0.1:9876/event \
  -H "Content-Type: application/json" \
  -d '{"event":"generation_start","data":{"model":"test","provider":"xai"}}'

Hoặc tray → Show settings → Test warp.

Mở panel: Right-click lên overlay (khi đang generate) · tray → Show settings · double-click tray.

Settings được persist trong localStorage (agent-overlay.settings) — style, alpha từng style, opacity, intensity, speed, hướng. (Debounce khi kéo slider.)

Phân biệt Opacity vs Style alpha

• Style alpha · {tên}: chỉnh riêng style đang chọn; nút Reset → 1.0×.
• Datastream / Signal dùng draw “soft” — chỉnh Style alpha nếu muốn sáng/tối hơn.
• Default vẫn Hyperspace; chọn Signal trong Settings để xem waves.

Chỉ áp dụng style không ẩn motion (Classic, Aurora, Rain, Embers, Comet, Datastream).
Radial (không hiện direction): Hyperspace, Signal, Spark, Orbit, Vortex.

• Spread thấp (6–15°): tia/làn gọn.
• Spread cao (30–45°): tỏa rộng.

Preset nút: ↑ Up / → Right / ↓ Down / ← Left.

Từ repo root (set PYTHONPATH hoặc cd vào root):

# Windows
cd C:\Work\Tool
py -3 -m opencode_bridge status
py -3 -m opencode_bridge enable
py -3 -m opencode_bridge disable
py -3 -m opencode_bridge run
py -3 -m opencode_bridge daemon

# macOS
cd "$AGENT_TOOL_ROOT"
python3 -m opencode_bridge status
python3 -m opencode_bridge enable|disable|run|daemon

Profile helpers:

Base: http://127.0.0.1:9876 (chỉ localhost)

Payload event:

{
  "event": "generation_start",
  "timestamp": "2026-07-16T00:00:00",
  "data": {
    "provider": "xai",
    "model": "grok-4.5",
    "session_id": "ses_xxx",
    "bridge_pid": 12345
  }
}

Token realtime: log INFO không còn emit tokens.* giữa stream. Bridge poll OpenCode SQLite (message + stream estimate + session delta) ~0.4s khi có session_id. Path: OPENCODE_DB hoặc $OPENCODE_DATA_DIR/opencode.db (mặc định ~/.local/share/opencode/…).

┌─────────────────────────────────────────────────────────┐
│  Agent Overlay (Tauri 2 + Svelte 5)                     │
│  • Tray + autostart + single-instance                   │
│  • HTTP 127.0.0.1:9876  (/health /event /events)        │
│  • Canvas: 11 styles + reactive phases + multi-session  │
└──────────────────────────▲──────────────────────────────┘
                           │ POST JSON (+ bridge_pid)
┌──────────────────────────┴──────────────────────────────┐
│  opencode_bridge (Python)                               │
│  • detect: stream start/end (legacy + OpenCode ≥1.15)   │
│  • emit: HTTP (config cache, coalesce tokens) + jsonl   │
│  • runner: TUI inherit + stderr + claimed log tail      │
│  • log_claims / status.bridges[pid] (multi-process)     │
│  • db_tokens: SQLite RO poll                            │
└──────────────────────────▲──────────────────────────────┘
                           │
              shim (opencode.cmd | opencode)  hoặc  oc
              (giữ cwd caller + PYTHONPATH)
                           │
                    OpenCode binary (TUI)

Detect generation:

1. Start: legacy message=stream providerID=… modelID=… hoặc OpenCode ≥1.15 service=llm … stream
2. End: exiting loop / session.idle / abort / dispose (session-scoped khi có session.id)
3. Sources: stderr (--print-logs) + tail log file (claim theo process, dedup)
4. Tokens: poll opencode.db (không dựa log tokens.* trên INFO)
5. Bỏ qua small=true; mọi providerID (xai, aibox, …)

Multi-process:

• log_claims.json — mỗi bridge claim 1 log; PID liveness (Windows: không dùng os.kill làm probe)
• status.json → bridges[pid]
• Overlay activeSessions keyed pid:session

python3 -m opencode_bridge disable   # hoặc py -3 trên Windows
python3 -m opencode_bridge enable

File: $AGENT_TOOL_ROOT/.agent-bridge/monitoring.enabled (1 / 0).

Tool/   (AGENT_TOOL_ROOT — script-relative hoặc env)
├── README.md / README-oc.md
├── public/                     # demo media (README)
│   ├── demo.gif                # Animation demo
│   ├── demo-1.png              # Settings panel
│   └── demo-2.png              # Generating particles
├── docs/                       # GitHub Pages site
│   ├── index.html
│   ├── guide.html
│   ├── content.md
│   └── assets/
├── tests/                      # test_detect, test_log_claim, test_session_keys
├── oc.cmd / oc.ps1 / oc.sh
├── start-overlay.ps1 / .bat / start-overlay.sh
├── install-shim.ps1 / install-shim.sh
├── install-autostart.ps1 / install-autostart.sh
├── profile-snippet.ps1 / profile-snippet.zsh
├── opencode_monitor.py
├── opencode_bridge/            # Python (cross-platform)
│   ├── config.py               # paths, status, log claims, PID liveness
│   ├── runner.py               # TUI + dual feed + claim log
│   ├── detect.py / emit.py / daemon.py / db_tokens.py
├── shim/
│   ├── opencode.cmd / opencode.ps1   # Windows
│   └── opencode                      # macOS / Linux
├── .agent-bridge/              # config, status, log_claims, last_events
└── agent-overlay/              # Tauri app
    ├── src/                    # Svelte + particles
    └── src-tauri/

Invoke-RestMethod http://127.0.0.1:9876/health
Invoke-RestMethod http://127.0.0.1:9876/events
Get-Content $env:AGENT_TOOL_ROOT\.agent-bridge\last_events.jsonl -Tail 10
py -3 -m opencode_bridge status

curl -s http://127.0.0.1:9876/health
tail -10 "$AGENT_TOOL_ROOT/.agent-bridge/last_events.jsonl"
python3 -m opencode_bridge status

# Windows (từ repo root)
powershell -File .\install-shim.ps1 -Uninstall
powershell -File .\install-autostart.ps1 -Uninstall
# Tray → Quit
# Remove-Item -Recurse .\.agent-bridge

# macOS
./install-shim.sh --uninstall
./install-autostart.sh --uninstall
# Tray → Quit
# rm -rf "$AGENT_TOOL_ROOT/.agent-bridge"

Gỡ dòng source …/profile-snippet trong shell profile nếu đã thêm.

cd agent-overlay
npm install
npm run tauri dev    # hot reload UI
npm run check
# Sau khi đổi particles/UI cho bản cài đặt:
npm run tauri build  # rồi Quit tray + mở lại Agent Overlay.app / exe
# start-overlay ưu tiên release bundle — không hot-reload bản release

Chi tiết app: agent-overlay/README.md.