From 2adc272f278b1d80d160ad4d6e1f35e3b61cb156 Mon Sep 17 00:00:00 2001
From: kaitranntt <kaitran.ntt@gmail.com>
Date: Thu, 18 Dec 2025 22:52:12 -0500
Subject: [PATCH 1/4] fix(cliproxy): prevent misleading update message when
 proxy is running

When CLIProxyAPI is already running as a background process, the update
cannot be applied because the old process is still in memory. Previously,
the CLI would download the new binary and show "Updating CLIProxyAPI..."
even though the running process remained on the old version.

Now checks if proxy is running before attempting update:
- If running: shows update available message with instruction to stop first
- If not running: proceeds with update as before

Fixes #143
---
 src/cliproxy/binary-manager.ts | 37 ++++++++++++++++++++++++----------
 1 file changed, 26 insertions(+), 11 deletions(-)

diff --git a/src/cliproxy/binary-manager.ts b/src/cliproxy/binary-manager.ts
index 8137c108..db9e38bf 100644
--- a/src/cliproxy/binary-manager.ts
+++ b/src/cliproxy/binary-manager.ts
@@ -19,7 +19,8 @@ import * as crypto from 'crypto';
 import * as zlib from 'zlib';
 import { ProgressIndicator } from '../utils/progress-indicator';
 import { ok, info } from '../utils/ui';
-import { getBinDir, getCliproxyDir } from './config-generator';
+import { getBinDir, getCliproxyDir, CLIPROXY_DEFAULT_PORT } from './config-generator';
+import { isCliproxyRunning } from './stats-fetcher';
 import {
   BinaryInfo,
   BinaryManagerConfig,
@@ -103,17 +104,31 @@ export class BinaryManager {
       try {
         const updateResult = await this.checkForUpdates();
         if (updateResult.hasUpdate) {
-          console.log(
-            info(
-              `CLIProxyAPI update available: v${updateResult.currentVersion} -> v${updateResult.latestVersion}`
-            )
-          );
-          console.log(info('Updating CLIProxyAPI...'));
+          // Check if CLIProxyAPI is currently running - can't update while running
+          const proxyRunning = await isCliproxyRunning(CLIPROXY_DEFAULT_PORT);
+          if (proxyRunning) {
+            // Proxy is running - can't update, just notify user
+            console.log(
+              info(
+                `CLIProxyAPI update available: v${updateResult.currentVersion} -> v${updateResult.latestVersion}`
+              )
+            );
+            console.log(info('Run "ccs cliproxy stop" then restart to apply update'));
+            this.log('Skipping update: CLIProxyAPI is currently running');
+          } else {
+            // Proxy not running - safe to update
+            console.log(
+              info(
+                `CLIProxyAPI update available: v${updateResult.currentVersion} -> v${updateResult.latestVersion}`
+              )
+            );
+            console.log(info('Updating CLIProxyAPI...'));
 
-          // Delete old binary and download new version
-          this.deleteBinary();
-          this.config.version = updateResult.latestVersion;
-          await this.downloadAndInstall();
+            // Delete old binary and download new version
+            this.deleteBinary();
+            this.config.version = updateResult.latestVersion;
+            await this.downloadAndInstall();
+          }
         }
       } catch (error) {
         // Silent fail - don't block startup if update check fails

From c9ad0b077934ae8418d4e97b9b02a09044ff898b Mon Sep 17 00:00:00 2001
From: kaitranntt <kaitran.ntt@gmail.com>
Date: Thu, 18 Dec 2025 23:03:45 -0500
Subject: [PATCH 2/4] feat(ui): add Stop and Restart buttons to
 ProxyStatusWidget

- Add POST /api/cliproxy/proxy-stop API endpoint
- Add proxyStop method in api-client and useStopProxy hook
- Update ProxyStatusWidget with Stop and Restart controls when running
- Restart = stop + delay + start (for applying CLIProxyAPI updates)

Complements the fix in binary-manager.ts which now tells users to stop
proxy before updates can be applied.
---
 src/web-server/routes.ts                  | 15 ++++-
 ui/src/components/proxy-status-widget.tsx | 81 ++++++++++++++++++-----
 ui/src/hooks/use-cliproxy.ts              | 21 ++++++
 ui/src/lib/api-client.ts                  |  9 +++
 4 files changed, 107 insertions(+), 19 deletions(-)

diff --git a/src/web-server/routes.ts b/src/web-server/routes.ts
index 9e1cd207..4f2797f7 100644
--- a/src/web-server/routes.ts
+++ b/src/web-server/routes.ts
@@ -44,7 +44,7 @@ import {
 } from '../cliproxy/account-manager';
 import type { CLIProxyProvider } from '../cliproxy/types';
 import { getClaudeEnvVars } from '../cliproxy/config-generator';
-import { getProxyStatus as getProxyProcessStatus } from '../cliproxy/session-tracker';
+import { getProxyStatus as getProxyProcessStatus, stopProxy } from '../cliproxy/session-tracker';
 import { ensureCliproxyService } from '../cliproxy/service-manager';
 // Unified config imports
 import {
@@ -1389,6 +1389,19 @@ apiRoutes.post('/cliproxy/proxy-start', async (_req: Request, res: Response): Pr
   }
 });
 
+/**
+ * POST /api/cliproxy/proxy-stop - Stop the CLIProxy service
+ * Returns: { stopped, pid?, sessionCount?, error? }
+ */
+apiRoutes.post('/cliproxy/proxy-stop', (_req: Request, res: Response): void => {
+  try {
+    const result = stopProxy();
+    res.json(result);
+  } catch (error) {
+    res.status(500).json({ error: (error as Error).message });
+  }
+});
+
 /**
  * GET /api/cliproxy/models - Get available models from CLIProxyAPI
  * Returns: { models: CliproxyModel[], byCategory: Record<string, CliproxyModel[]>, totalCount: number }
diff --git a/ui/src/components/proxy-status-widget.tsx b/ui/src/components/proxy-status-widget.tsx
index a85981c2..946d1cff 100644
--- a/ui/src/components/proxy-status-widget.tsx
+++ b/ui/src/components/proxy-status-widget.tsx
@@ -1,13 +1,13 @@
 /**
  * Proxy Status Widget
  *
- * Displays CLIProxy process status with start button for recovery.
+ * Displays CLIProxy process status with start/stop/restart controls.
  * Shows: running state, port, session count, uptime.
  */
 
-import { Activity, Power, RefreshCw, Clock, Users } from 'lucide-react';
+import { Activity, Power, RefreshCw, Clock, Users, Square, RotateCw } from 'lucide-react';
 import { Button } from '@/components/ui/button';
-import { useProxyStatus, useStartProxy } from '@/hooks/use-cliproxy';
+import { useProxyStatus, useStartProxy, useStopProxy } from '@/hooks/use-cliproxy';
 import { cn } from '@/lib/utils';
 
 function formatUptime(startedAt?: string): string {
@@ -28,8 +28,18 @@ function formatUptime(startedAt?: string): string {
 export function ProxyStatusWidget() {
   const { data: status, isLoading } = useProxyStatus();
   const startProxy = useStartProxy();
+  const stopProxy = useStopProxy();
 
   const isRunning = status?.running ?? false;
+  const isActioning = startProxy.isPending || stopProxy.isPending;
+
+  // Restart = stop then start
+  const handleRestart = async () => {
+    await stopProxy.mutateAsync();
+    // Small delay to ensure port is released
+    await new Promise((r) => setTimeout(r, 500));
+    startProxy.mutate();
+  };
 
   return (
     <div
@@ -61,21 +71,56 @@ export function ProxyStatusWidget() {
       </div>
 
       {isRunning && status ? (
-        <div className="mt-2 flex items-center gap-4 text-xs text-muted-foreground">
-          <span className="flex items-center gap-1">Port {status.port}</span>
-          {status.sessionCount !== undefined && status.sessionCount > 0 && (
-            <span className="flex items-center gap-1">
-              <Users className="w-3 h-3" />
-              {status.sessionCount} session{status.sessionCount !== 1 ? 's' : ''}
-            </span>
-          )}
-          {status.startedAt && (
-            <span className="flex items-center gap-1">
-              <Clock className="w-3 h-3" />
-              {formatUptime(status.startedAt)}
-            </span>
-          )}
-        </div>
+        <>
+          <div className="mt-2 flex items-center gap-4 text-xs text-muted-foreground">
+            <span className="flex items-center gap-1">Port {status.port}</span>
+            {status.sessionCount !== undefined && status.sessionCount > 0 && (
+              <span className="flex items-center gap-1">
+                <Users className="w-3 h-3" />
+                {status.sessionCount} session{status.sessionCount !== 1 ? 's' : ''}
+              </span>
+            )}
+            {status.startedAt && (
+              <span className="flex items-center gap-1">
+                <Clock className="w-3 h-3" />
+                {formatUptime(status.startedAt)}
+              </span>
+            )}
+          </div>
+          {/* Control buttons when running */}
+          <div className="mt-2 flex items-center gap-2">
+            <Button
+              variant="outline"
+              size="sm"
+              className="h-7 text-xs gap-1 flex-1"
+              onClick={handleRestart}
+              disabled={isActioning}
+              title="Restart to apply updates"
+            >
+              {isActioning ? (
+                <RefreshCw className="w-3 h-3 animate-spin" />
+              ) : (
+                <RotateCw className="w-3 h-3" />
+              )}
+              Restart
+            </Button>
+            <Button
+              variant="outline"
+              size="sm"
+              className="h-7 text-xs gap-1 hover:bg-destructive/10 hover:text-destructive hover:border-destructive/30"
+              onClick={() => stopProxy.mutate()}
+              disabled={isActioning}
+              title="Stop CLIProxy service"
+            >
+              {stopProxy.isPending ? (
+                <RefreshCw className="w-3 h-3 animate-spin" />
+              ) : (
+                <Square className="w-3 h-3" />
+              )}
+              Stop
+            </Button>
+          </div>
+        </>
       ) : (
         <div className="mt-2 flex items-center justify-between">
           <span className="text-xs text-muted-foreground">Not running</span>
diff --git a/ui/src/hooks/use-cliproxy.ts b/ui/src/hooks/use-cliproxy.ts
index 9f23842e..65a5be2f 100644
--- a/ui/src/hooks/use-cliproxy.ts
+++ b/ui/src/hooks/use-cliproxy.ts
@@ -240,3 +240,24 @@ export function useStartProxy() {
     },
   });
 }
+
+export function useStopProxy() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: () => api.cliproxy.proxyStop(),
+    onSuccess: (data) => {
+      queryClient.invalidateQueries({ queryKey: ['proxy-status'] });
+      if (data.stopped) {
+        toast.success(
+          `CLIProxy stopped${data.sessionCount ? ` (${data.sessionCount} session(s) disconnected)` : ''}`
+        );
+      } else {
+        toast.error(data.error || 'Failed to stop CLIProxy');
+      }
+    },
+    onError: (error: Error) => {
+      toast.error(error.message);
+    },
+  });
+}
diff --git a/ui/src/lib/api-client.ts b/ui/src/lib/api-client.ts
index 9732272b..5d5096a5 100644
--- a/ui/src/lib/api-client.ts
+++ b/ui/src/lib/api-client.ts
@@ -182,6 +182,14 @@ export interface ProxyStartResult {
   error?: string;
 }
 
+/** Result from stopping proxy service */
+export interface ProxyStopResult {
+  stopped: boolean;
+  pid?: number;
+  sessionCount?: number;
+  error?: string;
+}
+
 // API
 export const api = {
   profiles: {
@@ -216,6 +224,7 @@ export const api = {
     // Proxy process status and control
     proxyStatus: () => request<ProxyProcessStatus>('/cliproxy/proxy-status'),
     proxyStart: () => request<ProxyStartResult>('/cliproxy/proxy-start', { method: 'POST' }),
+    proxyStop: () => request<ProxyStopResult>('/cliproxy/proxy-stop', { method: 'POST' }),
 
     // Stats and models for Overview tab
     stats: () => request<{ usage: Record<string, unknown> }>('/cliproxy/usage'),

From 96762a9f6ee096570b2fe6136a4431e6ce1d1a47 Mon Sep 17 00:00:00 2001
From: kaitranntt <kaitran.ntt@gmail.com>
Date: Thu, 18 Dec 2025 23:17:05 -0500
Subject: [PATCH 3/4] feat(ui): show CLIProxyAPI update availability in
 dashboard

- Add GET /api/cliproxy/update-check endpoint
- Export checkCliproxyUpdate() function from binary-manager
- Add useCliproxyUpdateCheck hook with 1-hour cache
- Update ProxyStatusWidget with amber "Update" badge when available
- Highlight Restart button as "Update" with amber styling when update pending
---
 src/cliproxy/binary-manager.ts            | 17 ++++++++++
 src/web-server/routes.ts                  | 14 ++++++++
 ui/src/components/proxy-status-widget.tsx | 41 +++++++++++++++++++----
 ui/src/hooks/use-cliproxy.ts              | 12 +++++++
 ui/src/lib/api-client.ts                  |  9 +++++
 5 files changed, 86 insertions(+), 7 deletions(-)

diff --git a/src/cliproxy/binary-manager.ts b/src/cliproxy/binary-manager.ts
index db9e38bf..be2e533a 100644
--- a/src/cliproxy/binary-manager.ts
+++ b/src/cliproxy/binary-manager.ts
@@ -995,6 +995,23 @@ export async function fetchLatestCliproxyVersion(): Promise<string> {
   return result.latestVersion;
 }
 
+/** Update check result for API response */
+export interface CliproxyUpdateCheckResult {
+  hasUpdate: boolean;
+  currentVersion: string;
+  latestVersion: string;
+  fromCache: boolean;
+}
+
+/**
+ * Check for CLIProxyAPI binary updates
+ * @returns Update check result with version info
+ */
+export async function checkCliproxyUpdate(): Promise<CliproxyUpdateCheckResult> {
+  const manager = new BinaryManager();
+  return manager.checkForUpdates();
+}
+
 /**
  * Get path to version pin file
  * @returns Absolute path to .version-pin file
diff --git a/src/web-server/routes.ts b/src/web-server/routes.ts
index 4f2797f7..6f68fc27 100644
--- a/src/web-server/routes.ts
+++ b/src/web-server/routes.ts
@@ -46,6 +46,7 @@ import type { CLIProxyProvider } from '../cliproxy/types';
 import { getClaudeEnvVars } from '../cliproxy/config-generator';
 import { getProxyStatus as getProxyProcessStatus, stopProxy } from '../cliproxy/session-tracker';
 import { ensureCliproxyService } from '../cliproxy/service-manager';
+import { checkCliproxyUpdate } from '../cliproxy/binary-manager';
 // Unified config imports
 import {
   hasUnifiedConfig,
@@ -1402,6 +1403,19 @@ apiRoutes.post('/cliproxy/proxy-stop', (_req: Request, res: Response): void => {
   }
 });
 
+/**
+ * GET /api/cliproxy/update-check - Check for CLIProxyAPI binary updates
+ * Returns: { hasUpdate, currentVersion, latestVersion, fromCache }
+ */
+apiRoutes.get('/cliproxy/update-check', async (_req: Request, res: Response): Promise<void> => {
+  try {
+    const result = await checkCliproxyUpdate();
+    res.json(result);
+  } catch (error) {
+    res.status(500).json({ error: (error as Error).message });
+  }
+});
+
 /**
  * GET /api/cliproxy/models - Get available models from CLIProxyAPI
  * Returns: { models: CliproxyModel[], byCategory: Record<string, CliproxyModel[]>, totalCount: number }
diff --git a/ui/src/components/proxy-status-widget.tsx b/ui/src/components/proxy-status-widget.tsx
index 946d1cff..161be85a 100644
--- a/ui/src/components/proxy-status-widget.tsx
+++ b/ui/src/components/proxy-status-widget.tsx
@@ -2,12 +2,18 @@
  * Proxy Status Widget
  *
  * Displays CLIProxy process status with start/stop/restart controls.
- * Shows: running state, port, session count, uptime.
+ * Shows: running state, port, session count, uptime, update availability.
  */
 
-import { Activity, Power, RefreshCw, Clock, Users, Square, RotateCw } from 'lucide-react';
+import { Activity, Power, RefreshCw, Clock, Users, Square, RotateCw, ArrowUp } from 'lucide-react';
 import { Button } from '@/components/ui/button';
-import { useProxyStatus, useStartProxy, useStopProxy } from '@/hooks/use-cliproxy';
+import { Badge } from '@/components/ui/badge';
+import {
+  useProxyStatus,
+  useStartProxy,
+  useStopProxy,
+  useCliproxyUpdateCheck,
+} from '@/hooks/use-cliproxy';
 import { cn } from '@/lib/utils';
 
 function formatUptime(startedAt?: string): string {
@@ -27,11 +33,13 @@ function formatUptime(startedAt?: string): string {
 
 export function ProxyStatusWidget() {
   const { data: status, isLoading } = useProxyStatus();
+  const { data: updateCheck } = useCliproxyUpdateCheck();
   const startProxy = useStartProxy();
   const stopProxy = useStopProxy();
 
   const isRunning = status?.running ?? false;
   const isActioning = startProxy.isPending || stopProxy.isPending;
+  const hasUpdate = updateCheck?.hasUpdate ?? false;
 
   // Restart = stop then start
   const handleRestart = async () => {
@@ -57,6 +65,16 @@ export function ProxyStatusWidget() {
             )}
           />
           <span className="text-sm font-medium">CLIProxy Service</span>
+          {hasUpdate && (
+            <Badge
+              variant="secondary"
+              className="text-[10px] h-4 px-1.5 gap-0.5 bg-amber-100 text-amber-700 dark:bg-amber-900/30 dark:text-amber-400"
+              title={`Update: v${updateCheck?.currentVersion} -> v${updateCheck?.latestVersion}`}
+            >
+              <ArrowUp className="w-2.5 h-2.5" />
+              Update
+            </Badge>
+          )}
         </div>
 
         <div className="flex items-center gap-1">
@@ -90,19 +108,28 @@ export function ProxyStatusWidget() {
           {/* Control buttons when running */}
           <div className="mt-2 flex items-center gap-2">
             <Button
-              variant="outline"
+              variant={hasUpdate ? 'default' : 'outline'}
               size="sm"
-              className="h-7 text-xs gap-1 flex-1"
+              className={cn(
+                'h-7 text-xs gap-1 flex-1',
+                hasUpdate && 'bg-amber-600 hover:bg-amber-700 text-white'
+              )}
               onClick={handleRestart}
               disabled={isActioning}
-              title="Restart to apply updates"
+              title={
+                hasUpdate
+                  ? `Restart to update: v${updateCheck?.currentVersion} -> v${updateCheck?.latestVersion}`
+                  : 'Restart CLIProxy service'
+              }
             >
               {isActioning ? (
                 <RefreshCw className="w-3 h-3 animate-spin" />
+              ) : hasUpdate ? (
+                <ArrowUp className="w-3 h-3" />
               ) : (
                 <RotateCw className="w-3 h-3" />
               )}
-              Restart
+              {hasUpdate ? 'Update' : 'Restart'}
             </Button>
             <Button
               variant="outline"
diff --git a/ui/src/hooks/use-cliproxy.ts b/ui/src/hooks/use-cliproxy.ts
index 65a5be2f..fa93c06f 100644
--- a/ui/src/hooks/use-cliproxy.ts
+++ b/ui/src/hooks/use-cliproxy.ts
@@ -261,3 +261,15 @@ export function useStopProxy() {
     },
   });
 }
+
+// ==================== Update Check ====================
+
+export function useCliproxyUpdateCheck() {
+  return useQuery({
+    queryKey: ['cliproxy-update-check'],
+    queryFn: () => api.cliproxy.updateCheck(),
+    staleTime: 60 * 60 * 1000, // 1 hour (matches backend cache)
+    refetchInterval: 60 * 60 * 1000, // Refresh every hour
+    refetchOnWindowFocus: false, // Don't refresh on window focus (save API calls)
+  });
+}
diff --git a/ui/src/lib/api-client.ts b/ui/src/lib/api-client.ts
index 5d5096a5..f45837dd 100644
--- a/ui/src/lib/api-client.ts
+++ b/ui/src/lib/api-client.ts
@@ -190,6 +190,14 @@ export interface ProxyStopResult {
   error?: string;
 }
 
+/** Result from checking for CLIProxyAPI updates */
+export interface CliproxyUpdateCheckResult {
+  hasUpdate: boolean;
+  currentVersion: string;
+  latestVersion: string;
+  fromCache: boolean;
+}
+
 // API
 export const api = {
   profiles: {
@@ -225,6 +233,7 @@ export const api = {
     proxyStatus: () => request<ProxyProcessStatus>('/cliproxy/proxy-status'),
     proxyStart: () => request<ProxyStartResult>('/cliproxy/proxy-start', { method: 'POST' }),
     proxyStop: () => request<ProxyStopResult>('/cliproxy/proxy-stop', { method: 'POST' }),
+    updateCheck: () => request<CliproxyUpdateCheckResult>('/cliproxy/update-check'),
 
     // Stats and models for Overview tab
     stats: () => request<{ usage: Record<string, unknown> }>('/cliproxy/usage'),

From d43079b72414d7b841a35a934ea39a91527f4172 Mon Sep 17 00:00:00 2001
From: kaitranntt <kaitran.ntt@gmail.com>
Date: Thu, 18 Dec 2025 23:24:15 -0500
Subject: [PATCH 4/4] feat(ui): add version sync timestamp to ProxyStatusWidget

- Show current CLIProxyAPI version (e.g., v6.5.53)
- Display "Synced Xm ago" with full timestamp on hover
- Extend API response to include checkedAt timestamp
---
 src/cliproxy/binary-manager.ts            | 21 +++++++++++++--------
 ui/src/components/proxy-status-widget.tsx | 23 +++++++++++++++++++++++
 ui/src/lib/api-client.ts                  |  1 +
 3 files changed, 37 insertions(+), 8 deletions(-)

diff --git a/src/cliproxy/binary-manager.ts b/src/cliproxy/binary-manager.ts
index be2e533a..fa037060 100644
--- a/src/cliproxy/binary-manager.ts
+++ b/src/cliproxy/binary-manager.ts
@@ -59,6 +59,7 @@ interface UpdateCheckResult {
   currentVersion: string;
   latestVersion: string;
   fromCache: boolean;
+  checkedAt: number; // Unix timestamp of last check
 }
 
 /** Default configuration */
@@ -172,19 +173,21 @@ export class BinaryManager {
     const currentVersion = this.getInstalledVersion();
 
     // Try cache first
-    const cachedVersion = this.getCachedLatestVersion();
-    if (cachedVersion) {
-      this.log(`Using cached version: ${cachedVersion}`);
+    const cache = this.getVersionCache();
+    if (cache) {
+      this.log(`Using cached version: ${cache.latestVersion}`);
       return {
-        hasUpdate: this.isNewerVersion(cachedVersion, currentVersion),
+        hasUpdate: this.isNewerVersion(cache.latestVersion, currentVersion),
         currentVersion,
-        latestVersion: cachedVersion,
+        latestVersion: cache.latestVersion,
         fromCache: true,
+        checkedAt: cache.checkedAt,
       };
     }
 
     // Fetch from GitHub API
     const latestVersion = await this.fetchLatestVersion();
+    const now = Date.now();
     this.cacheLatestVersion(latestVersion);
 
     return {
@@ -192,6 +195,7 @@ export class BinaryManager {
       currentVersion,
       latestVersion,
       fromCache: false,
+      checkedAt: now,
     };
   }
 
@@ -287,9 +291,9 @@ export class BinaryManager {
   }
 
   /**
-   * Get cached latest version if still valid
+   * Get version cache data if still valid
    */
-  private getCachedLatestVersion(): string | null {
+  private getVersionCache(): VersionCache | null {
     const cachePath = this.getVersionCachePath();
     if (!fs.existsSync(cachePath)) {
       return null;
@@ -301,7 +305,7 @@ export class BinaryManager {
 
       // Check if cache is still valid
       if (Date.now() - cache.checkedAt < VERSION_CACHE_DURATION_MS) {
-        return cache.latestVersion;
+        return cache;
       }
 
       // Cache expired
@@ -1001,6 +1005,7 @@ export interface CliproxyUpdateCheckResult {
   currentVersion: string;
   latestVersion: string;
   fromCache: boolean;
+  checkedAt: number; // Unix timestamp of last check
 }
 
 /**
diff --git a/ui/src/components/proxy-status-widget.tsx b/ui/src/components/proxy-status-widget.tsx
index 161be85a..d3d4cd1d 100644
--- a/ui/src/components/proxy-status-widget.tsx
+++ b/ui/src/components/proxy-status-widget.tsx
@@ -31,6 +31,17 @@ function formatUptime(startedAt?: string): string {
   return `${minutes}m`;
 }
 
+function formatTimeAgo(timestamp?: number): string {
+  if (!timestamp) return '';
+  const diff = Date.now() - timestamp;
+  const minutes = Math.floor(diff / (1000 * 60));
+  const hours = Math.floor(diff / (1000 * 60 * 60));
+
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return `${minutes}m ago`;
+  return `${hours}h ago`;
+}
+
 export function ProxyStatusWidget() {
   const { data: status, isLoading } = useProxyStatus();
   const { data: updateCheck } = useCliproxyUpdateCheck();
@@ -167,6 +178,18 @@ export function ProxyStatusWidget() {
           </Button>
         </div>
       )}
+
+      {/* Version sync indicator */}
+      {updateCheck?.currentVersion && (
+        <div className="mt-2 pt-2 border-t border-muted flex items-center justify-between text-[10px] text-muted-foreground/70">
+          <span>v{updateCheck.currentVersion}</span>
+          {updateCheck.checkedAt && (
+            <span title={new Date(updateCheck.checkedAt).toLocaleString()}>
+              Synced {formatTimeAgo(updateCheck.checkedAt)}
+            </span>
+          )}
+        </div>
+      )}
     </div>
   );
 }
diff --git a/ui/src/lib/api-client.ts b/ui/src/lib/api-client.ts
index f45837dd..73815560 100644
--- a/ui/src/lib/api-client.ts
+++ b/ui/src/lib/api-client.ts
@@ -196,6 +196,7 @@ export interface CliproxyUpdateCheckResult {
   currentVersion: string;
   latestVersion: string;
   fromCache: boolean;
+  checkedAt: number; // Unix timestamp of last check
 }
 
 // API