AIMonitor Setup

English | 简体中文

AIMonitor Setup is the desktop configuration and relay application for AIMonitor devices. It discovers AIMonitor devices on the local network, manages per-client display positions, state images, and Hooks, and forwards local events from Codex, Claude Code, Cursor, OpenCode, WorkBuddy, Hermes, OpenClaw, CodeBuddy, Qwen Code, Kimi Code, Qoder, Gemini CLI, and GitHub Copilot CLI to every configured online device.

The project is built with Tauri and React. Rust is the sole business backend; React is limited to presentation, interaction, and typed Tauri command calls.

Features

• Discover local AIMonitor devices through mDNS and UDP broadcast, then keep their online state refreshed in the background.
• Configure any of 25 display positions and four states—idle, running, asking, and error—separately for each device and AI client.
• Browse, filter, batch upload, and manage JPEG, PNG, GIF, BMP, and WebP images. The Rust backend validates, resizes, and converts images for device compatibility.
• Apply per-tool delivery semantics:
  • Stateful latest-wins: Codex, Claude Code, Cursor, OpenCode, Qwen Code, Kimi Code, Qoder, Gemini CLI, GitHub Copilot CLI.
  • Event-by-event FIFO: WorkBuddy, Hermes, OpenClaw, CodeBuddy.
• Write local relay configuration for supported AI clients. Command Hooks use AIMonitor's lightweight relay mode and do not depend on PowerShell on Windows. Missing configurations are added when AIMonitor starts or the AI selection changes, while existing AIMonitor-managed entries are left untouched.
• Inspect online devices and local relay metrics, including received, forwarded, failed, pending, deduplicated, and suppressed events.
• Use the interface in English or Simplified Chinese, run silently at startup, control the app from the system tray, switch between devices, and follow the first-run guide.

Screenshots

The following screenshots were captured from AIMonitor v2.2.4 on macOS; the depicted interface remains representative of v2.2.7.

Startup and device discovery

At startup, AIMonitor checks available devices through mDNS, UDP broadcast, and previously saved addresses.

Workbench

The workbench shows online devices and the local Hook relay's received, forwarded, failed, pending, and suppressed event counts.

Monitor management

Display positions and all four behavior states are stored independently for each device and AI client. A single image can be uploaded directly from the image picker and is selected automatically when the upload finishes.

Image management

Review image totals and formats, refresh or filter the list, and upload multiple images at once.

Settings

Choose AI clients, manage Hook configuration directories, set the shared display name and discovery interval, select a language, and configure launch at startup.

Getting started

The first-run guide starts with the sidebar and device switcher, then covers AI client selection and monitor display setup. A single image can be uploaded from Monitor management without visiting Image management.

Development

Requirements:

• Node.js 22.12+
• pnpm 10.30+
• Rust stable (currently verified with 1.97)
• The Tauri system dependencies for your target platform

Install dependencies and start the development application:

pnpm install
pnpm tauri dev

Common checks:

pnpm build
pnpm check
pnpm tauri build

Release builds (maintainer guide)

The release workflow uses the same commands, platform labels, and artifact naming conventions as AIMonitorDesktop. A macOS package is copied to publish/ only after Developer ID signing, notarization, ticket stapling, and Gatekeeper validation all succeed.

One-time build machine setup

Install project dependencies, Rust targets, and the Windows cross-compilation tools:

pnpm install
rustup target add aarch64-apple-darwin x86_64-apple-darwin
rustup target add x86_64-pc-windows-msvc
brew install llvm nsis
cargo install --locked cargo-xwin

The macOS keychain must contain a valid Developer ID Application certificate and its private key:

security find-identity -v -p codesigning

Create an App Store Connect API key with Developer access, save the downloaded .p8 key in a secure local directory, and store the notarization credentials in the keychain. Replace every placeholder before running these commands:

mkdir -p "$HOME/.appstoreconnect/private_keys"
chmod 700 "$HOME/.appstoreconnect/private_keys"
chmod 600 "$HOME/.appstoreconnect/private_keys/AuthKey_<KEY_ID>.p8"

xcrun notarytool store-credentials AIMonitorNotary \
  --key "$HOME/.appstoreconnect/private_keys/AuthKey_<KEY_ID>.p8" \
  --key-id "<KEY_ID>" \
  --issuer "<ISSUER_ID>"

Verify the stored credentials:

xcrun notarytool history --keychain-profile AIMonitorNotary

Never commit the certificate, its private key, the App Store Connect API key, the .p8 file, or the Issuer ID. Set AIMONITOR_NOTARY_PROFILE before building if you use a different keychain profile name.

Windows Authenticode signing is intentionally not required for this project. Windows releases use the explicit Tauri --no-sign flag; no Windows certificate, signing password, custom signCommand, or osslsigncode installation is needed.

Building a release

1. Update the version in package.json, src-tauri/Cargo.toml, and src-tauri/tauri.conf.json. All three values must match.

2. Run the pre-release checks:

   pnpm build
   pnpm check

3. Choose a target:

   # macOS universal binary (Apple Silicon + Intel)
   pnpm run build:mac
   
   # Intentionally unsigned Windows x64 through cargo-xwin on macOS/Linux
   pnpm run build:win
   
   # Canonical release: signed/notarized macOS + unsigned Windows x64
   pnpm release:desktop

   To build a single macOS architecture, override the default target:

   AIMONITOR_MAC_TARGET=aarch64-apple-darwin pnpm run build:mac
   AIMONITOR_MAC_TARGET=x86_64-apple-darwin pnpm run build:mac

4. After a successful build, inspect publish/:

   • AIMonitorSetup-macOS-universal-v<version>.dmg
   • AIMonitorSetup-Windows-x64-v<version>-setup.exe
   • AIMonitorSetup-SHA256SUMS.txt

   A standalone build:mac with AIMONITOR_MAC_TARGET uses arm64 or x64 instead of universal in its published DMG filename.

The release script clears and repopulates publish/ only after every requested platform succeeds, so it does not publish partial output. The automated macOS flow is: Tauri build and signing → DMG signature validation → Apple notarization and wait for Accepted → staple the ticket → Gatekeeper validation → copy the installer.

The Windows x64 installer is intentionally built through cargo-xwin and NSIS with --no-sign; it does not have an Authenticode signature. The release script still verifies that the packaged application binary is an x86_64 MSVC PE before copying the installer. Windows signing and macOS Developer ID signing/notarization are independent policies.

Post-release validation

Replace the version in each filename with the actual release version:

xcrun stapler validate "publish/AIMonitorSetup-macOS-universal-v<version>.dmg"
spctl --assess --verbose=2 --type open \
  --context context:primary-signature \
  "publish/AIMonitorSetup-macOS-universal-v<version>.dmg"
(cd publish && shasum -a 256 -c AIMonitorSetup-SHA256SUMS.txt)

stapler validate must succeed, and spctl must report accepted and source=Notarized Developer ID. Finally, test installation and first launch on another Mac and on a Windows machine.

Moving to a new machine or rotating keys

A new build machine needs the Developer ID certificate with its private key and the App Store Connect .p8 key. After importing the macOS signing certificate, run notarytool store-credentials again. Revoke the old API key only after the new setup can build and notarize macOS successfully. Windows requires no signing key.

Troubleshooting

• Signing identity not found: confirm that both the certificate and its private key are present in the keychain, then run security find-identity -v -p codesigning.
• AIMonitorNotary not found: run notarytool store-credentials again or set AIMONITOR_NOTARY_PROFILE to the correct profile.
• Notarization returns Invalid: obtain the Submission ID from the build output, then run xcrun notarytool log <SUBMISSION_ID> --keychain-profile AIMonitorNotary.
• Windows build prerequisites missing: confirm that cargo-xwin, makensis, and LLVM are installed; llvm-rc and llvm-readobj must be on PATH.
• Gatekeeper blocks the DMG: do not bypass the warning and publish it. Confirm that stapler validate succeeds and spctl reports Notarized Developer ID.

Project rules

• Technology stack and versions
• Architecture and code boundaries
• Hooks contract
• Agent collaboration rules

License

The source code is provided under the PolyForm Noncommercial License 1.0.0. It may be used, modified, and distributed for personal, research, educational, and other noncommercial purposes allowed by the license. Commercial use requires separate written permission from the copyright holder.

Because the license restricts commercial use, this project is source-available rather than open source under the OSI definition.