7f33621721
- System tray icon with connection status - Exec approval dialogs with queue and timeout - Settings persistence to JSON (%LOCALAPPDATA%\Clawdbot) - Auto-start on login via Windows Registry - Notification sounds for approvals and connection events - WebView2 Control UI embedding - 23 unit tests passing - Build scripts and Inno Setup installer template - Community build guide documentation Phase 0: Protocol models, WebSocket client, logging Phase 1: Tray icon, exec approval dialogs, Control UI Phase 2: Settings, auto-start, sounds, settings UI
227 lines
7.2 KiB
Markdown
227 lines
7.2 KiB
Markdown
# Clawdbot Windows Companion
|
|
|
|
Windows companion application for the Clawdbot Gateway, providing system tray integration and Control UI access.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
apps/windows/
|
|
├── ClawdbotWindows.sln # Solution file
|
|
├── src/
|
|
│ ├── Clawdbot.Windows/ # Main WPF application
|
|
│ │ ├── App.xaml(.cs) # Application entry point
|
|
│ │ ├── MainWindow.xaml(.cs) # WebView2 Control UI window
|
|
│ │ ├── ExecApprovalDialog.xaml(.cs) # Command approval dialog
|
|
│ │ ├── SettingsWindow.xaml(.cs) # Settings UI dialog
|
|
│ │ └── SystemTrayIcon.cs # System tray implementation
|
|
│ ├── Clawdbot.Windows.Core/ # Gateway client and services
|
|
│ │ ├── GatewayChannel.cs # WebSocket client
|
|
│ │ ├── AppLogger.cs # File-based logging
|
|
│ │ ├── AppSettings.cs # Settings persistence (JSON)
|
|
│ │ ├── AutoStartHelper.cs # Windows auto-start (Registry)
|
|
│ │ ├── NotificationSounds.cs # System notification sounds
|
|
│ │ ├── WebView2Helper.cs # WebView2 runtime detection
|
|
│ │ ├── ExecApprovalModels.cs # Exec approval request/response types
|
|
│ │ └── ExecApprovalService.cs # Exec approval event handling
|
|
│ └── Clawdbot.Windows.Protocol/ # Auto-generated protocol models
|
|
│ └── GatewayModels.cs # Protocol v3 types
|
|
└── tests/
|
|
└── Clawdbot.Windows.Tests/ # Unit and integration tests
|
|
├── Phase0ValidationTests.cs # Gateway connection tests
|
|
├── ExecApprovalTests.cs # Exec approval model tests
|
|
└── SettingsTests.cs # Settings persistence tests
|
|
```
|
|
|
|
## Prerequisites
|
|
|
|
- .NET 9.0 SDK
|
|
- Windows 10 version 1903 or later (for WebView2)
|
|
- Microsoft Edge WebView2 Runtime (auto-detected, downloads prompted if missing)
|
|
- Clawdbot Gateway running (in WSL2 or natively)
|
|
|
|
## Building
|
|
|
|
```powershell
|
|
cd apps/windows
|
|
dotnet build
|
|
```
|
|
|
|
## Running
|
|
|
|
```powershell
|
|
# From the apps/windows directory
|
|
dotnet run --project src\Clawdbot.Windows
|
|
```
|
|
|
|
Or run the built executable directly:
|
|
```powershell
|
|
.\src\Clawdbot.Windows\bin\Debug\net9.0-windows\Clawdbot.exe
|
|
```
|
|
|
|
The application will:
|
|
1. Start minimized to the system tray
|
|
2. Attempt to connect to the Gateway at `ws://127.0.0.1:18789/`
|
|
3. Display connection status via the tray icon color
|
|
4. Show the Control UI in a WebView2 window when double-clicking the tray icon
|
|
|
|
## Logging
|
|
|
|
Logs are written to:
|
|
```
|
|
%LOCALAPPDATA%\Clawdbot\logs\clawdbot-YYYY-MM-DD.log
|
|
```
|
|
|
|
View logs in PowerShell:
|
|
```powershell
|
|
Get-Content "$env:LOCALAPPDATA\Clawdbot\logs\clawdbot-$(Get-Date -Format 'yyyy-MM-dd').log" -Wait
|
|
```
|
|
|
|
## Settings
|
|
|
|
Settings are stored in:
|
|
```
|
|
%LOCALAPPDATA%\Clawdbot\settings.json
|
|
```
|
|
|
|
Access settings via the system tray icon → **Settings**.
|
|
|
|
### Available Settings
|
|
|
|
| Setting | Default | Description |
|
|
|---------|---------|-------------|
|
|
| Gateway URL | `ws://127.0.0.1:18789/` | WebSocket URL of the Gateway |
|
|
| Start on login | Off | Launch automatically at Windows startup |
|
|
| Minimize to tray | On | Minimize to tray instead of closing |
|
|
| Play sounds | On | Play notification sounds for events |
|
|
| Show connection notifications | On | Show balloon notifications |
|
|
|
|
### Auto-Start
|
|
|
|
When enabled, adds a registry entry to:
|
|
```
|
|
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Run
|
|
```
|
|
|
|
This starts Clawdbot automatically when you log in to Windows.
|
|
|
|
## Exec Approval Dialogs
|
|
|
|
When an AI agent requests to run a command, Clawdbot shows an approval dialog:
|
|
|
|
|
|
|
|
### Features
|
|
- **Command display**: Shows the full command in a monospaced font
|
|
- **Context details**: Working directory, executable path, host, agent ID, security level
|
|
- **Countdown timer**: Auto-denies after timeout (typically 60 seconds)
|
|
- **Three actions**:
|
|
- **Allow Once** (green): Run this command once
|
|
- **Always Allow** (blue): Add to allowlist and run
|
|
- **Don't Allow** (red): Deny the command
|
|
|
|
### Testing
|
|
In Debug builds, right-click the system tray icon and select **Debug > Test Approval Dialog** to see a sample dialog.
|
|
|
|
### Keyboard Shortcuts
|
|
- **Enter**: Allow Once (default button)
|
|
- **Escape**: Don't Allow
|
|
|
|
## Testing
|
|
|
|
### Unit Tests
|
|
```powershell
|
|
dotnet test
|
|
```
|
|
|
|
Current test results: **23 passing, 7 skipped** (integration tests require Gateway)
|
|
|
|
### Integration Tests (requires running Gateway)
|
|
Start the Gateway first:
|
|
```bash
|
|
# In WSL2 or Linux terminal
|
|
clawdbot gateway run --bind loopback --port 18789
|
|
```
|
|
|
|
Then the integration tests will run automatically (they detect if the Gateway is available).
|
|
|
|
## Architecture
|
|
|
|
### Clawdbot.Windows.Protocol
|
|
Auto-generated C# models matching the Gateway's TypeScript schema (Protocol version 3).
|
|
- Request/response frames
|
|
- Event payloads
|
|
- Configuration types
|
|
|
|
### Clawdbot.Windows.Core
|
|
Gateway client with:
|
|
- WebSocket connection management
|
|
- Automatic reconnection with exponential backoff
|
|
- Request/response correlation
|
|
- Event subscription and dispatch
|
|
- File-based logging (AppLogger)
|
|
- WebView2 runtime detection (WebView2Helper)
|
|
|
|
### Clawdbot.Windows (WPF App)
|
|
- System tray icon with context menu
|
|
- WebView2 embedding the Control UI (`http://127.0.0.1:18789/ui`)
|
|
- Connection status visualization
|
|
- Graceful exit handling
|
|
|
|
## Development Status
|
|
|
|
**Phase 0: Foundation Validation** ✅
|
|
- [x] Project structure
|
|
- [x] Protocol models (GatewayModels.cs)
|
|
- [x] Gateway WebSocket client (GatewayChannel.cs)
|
|
- [x] Unit tests passing (23/23)
|
|
- [x] Application icon from favicon.ico
|
|
- [x] File-based debug logging
|
|
- [x] WebView2 runtime detection
|
|
|
|
**Phase 1: Core Features** ✅
|
|
- [x] System tray icon with context menu
|
|
- [x] WebView2 Control UI embedding
|
|
- [x] Connection status in tray tooltip
|
|
- [x] Exec approval dialogs (ExecApprovalDialog.xaml)
|
|
- [x] Exec approval service with queue management
|
|
- [x] Timeout handling (auto-deny on expiry)
|
|
- [x] Debug menu for testing dialogs
|
|
|
|
**Phase 2: Production Ready** ✅
|
|
- [x] Settings persistence (`%LOCALAPPDATA%\Clawdbot\settings.json`)
|
|
- [x] Auto-start on login (Windows Registry)
|
|
- [x] Settings UI window
|
|
- [x] Notification sounds (Windows system sounds)
|
|
- [x] Settings tests (6 new tests)
|
|
|
|
**Phase 3: Distribution** 🔲
|
|
- [ ] Installer/packaging (MSIX or MSI)
|
|
- [ ] Auto-update mechanism
|
|
- [ ] Code signing
|
|
- [ ] Release automation
|
|
|
|
See [Windows-Companion-App-Plan.md](../../Windows-Companion-App-Plan.md) for the full roadmap.
|
|
|
|
## Known Issues
|
|
|
|
1. **No Gateway Available**: Without a running Gateway, the app shows "Disconnected" status. Need to install pnpm/bun to build and run the Gateway locally.
|
|
|
|
2. **Manual Testing Required**: Some features (tray icon visibility, window opening) require manual verification.
|
|
|
|
3. **WebView2 Control UI**: When Gateway is not connected, the WebView2 shows a "Waiting for Gateway connection..." overlay.
|
|
|
|
## Gateway Connection
|
|
|
|
The Windows companion connects to the Clawdbot Gateway via WebSocket:
|
|
|
|
| Component | URL |
|
|
|-----------|-----|
|
|
| Gateway WebSocket | `ws://127.0.0.1:18789/` |
|
|
| Control UI | `http://127.0.0.1:18789/ui` |
|
|
|
|
The Gateway must be running for the companion app to function.
|
|
|
|
## License
|
|
|
|
MIT - see [LICENSE](../../LICENSE) in the project root.
|