Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Add a native FCC desktop launcher for Windows and macOS (#1225)

Ali Khokhard98a6b0ca038
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 70305fae..73c73ab2 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -147,8 +147,9 @@ FCC optimizes for installed user workflows, not internal compatibility. The
behavior that must be preserved is that these user-facing surfaces run correctly
for real prompts against supported providers:
-- `fcc-server` and the local Admin UI for configuring supported providers,
- model routing, auth, server tools, messaging, and diagnostics.
+- `fcc-server`, the Windows/macOS FCC Desktop shell, and the local Admin UI for
+ configuring supported providers, model routing, auth, server tools, messaging,
+ and diagnostics.
- `fcc-claude`, Claude Code, and the Anthropic-compatible proxy behavior Claude
Code relies on, including streaming text, native/interleaved thinking, tool
use/results, model discovery, token counting, retries/recovery, and supported
@@ -209,27 +210,42 @@ new places to add unrelated behavior:
Console scripts are registered in [pyproject.toml](pyproject.toml):
- `fcc-server` calls `free_claude_code.cli.entrypoints:serve`.
+- `fcc-desktop` is a GUI script calling
+ `free_claude_code.cli.desktop_entrypoint:launch` on Windows and macOS.
- `fcc-claude` calls `free_claude_code.cli.launchers.claude:launch`.
- `fcc-codex` calls `free_claude_code.cli.launchers.codex:launch`.
- `fcc-pi` calls `free_claude_code.cli.launchers.pi:launch`.
[scripts/install.sh](scripts/install.sh) and [scripts/install.ps1](scripts/install.ps1)
-install or update the uv tool plus optional voice extras. [scripts/uninstall.sh](scripts/uninstall.sh)
-and [scripts/uninstall.ps1](scripts/uninstall.ps1) remove only the FCC uv tool and always
-delete the managed `~/.fcc/` tree from [config/paths.py](src/free_claude_code/config/paths.py); they do not remove
+install or update the uv tool plus optional voice extras. On Windows the
+installer owns the FCC desktop and Start-menu shortcuts; on macOS it owns the
+per-user application bundle and desktop link. [scripts/uninstall.sh](scripts/uninstall.sh)
+and [scripts/uninstall.ps1](scripts/uninstall.ps1) remove those exact desktop
+artifacts, the FCC uv tool, and the managed `~/.fcc/` tree from
+[config/paths.py](src/free_claude_code/config/paths.py); they do not remove
uv, Claude Code, Codex, Pi, or uv-managed Python runtimes. [scripts/ci.sh](scripts/ci.sh) and
[scripts/ci.ps1](scripts/ci.ps1) mirror [.github/workflows/tests.yml](.github/workflows/tests.yml)
for local pre-push verification.
[cli/entrypoints.py](src/free_claude_code/cli/entrypoints.py) starts the FastAPI server with Uvicorn.
-`serve()` migrates legacy env files when needed, loads cached settings, runs a
-supervised server instance, and can restart the server after admin config changes.
+The shared `ServerSupervisor` migrates legacy env files when needed, loads cached
+settings, runs one server instance, and can restart it after Admin config changes.
An Admin restart constructs the next instance only when the prior
`ApplicationRuntime` reports that its complete ownership graph closed. An
incomplete ASGI shutdown therefore exits the supervisor instead of overlapping
old and replacement graphs. On final shutdown it best-effort kills registered
child processes.
+[cli/desktop.py](src/free_claude_code/cli/desktop.py) owns the platform-neutral
+desktop lifecycle. An operating-system file lock admits one desktop host, the
+tray remains on the process main thread for native event-loop compatibility, and
+one worker runs the same in-process `ServerSupervisor` with console output and
+automatic browser launch disabled. A second desktop launch waits for health,
+opens the existing Admin page, and exits. Tray restart delegates to the canonical
+supervisor; tray quit requests the same graceful ASGI and application-runtime
+shutdown as `fcc-server`. [cli/desktop_tray.py](src/free_claude_code/cli/desktop_tray.py)
+owns only native status-area presentation and callbacks.
+
[runtime/bootstrap.py](src/free_claude_code/runtime/bootstrap.py) is the single production composition function. The CLI
supervisor supplies one settings snapshot and its restart callback; bootstrap
configures logging, constructs the runtime owners and the configured voice
diff --git a/README.md b/README.md
index 8167b1d9..db00fe4e 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,7 @@ Run your coding agents with free, paid, or local models. Choose and validate pro
## What You Get
- Launch Claude Code with `fcc-claude`, Codex with `fcc-codex`, or Pi with `fcc-pi`.
+- Run FCC in the background from a desktop launcher on Windows or macOS.
- Switch among 25 cloud and local providers from the Admin UI.
- Use each coding agent's native model picker.
- Route Fable, Opus, Sonnet, Haiku, and fallback traffic to different models.
@@ -73,6 +74,14 @@ Re-run the same command whenever you want to update. You can review the installe
### 2. Start The Server
+On Windows, open **Free Claude Code** from the desktop or Start menu. On
+macOS, open **Free Claude Code** from the desktop or your Applications folder.
+FCC runs in the system tray or menu bar without a terminal window. Use its menu
+to open Admin, check server status, restart, or quit; on Windows, left-clicking
+the tray icon opens Admin directly.
+
+For Linux or terminal use, run:
+
```bash
fcc-server
```
@@ -80,8 +89,8 @@ fcc-server
To print the installed Free Claude Code version without starting the server,
run `fcc-server --version`.
-Keep this process running. By default, the Admin UI opens in your browser once
-the server is healthy. Its address is always shown in the startup log:
+Keep this process running. In terminal mode, the Admin UI opens in your browser
+once the server is healthy by default. Its address is shown in the startup log:
```text
INFO: Admin UI: http://127.0.0.1:8082/admin (local-only)
@@ -417,7 +426,10 @@ Re-run the matching command from [Install Or Update](#install).
### Uninstall
-Stop every running FCC command first. The uninstaller removes the FCC uv tool, verifies every FCC command is gone, and then deletes `~/.fcc/`. It leaves uv, Python, Claude Code, Codex, Pi, and shared PATH entries intact.
+Stop every running FCC command first. The uninstaller removes the FCC desktop
+launcher and uv tool, verifies every FCC command is gone, and then deletes
+`~/.fcc/`. It leaves uv, Python, Claude Code, Codex, Pi, and shared PATH entries
+intact.
macOS/Linux:
diff --git a/pyproject.toml b/pyproject.toml
index 226e845f..4d8a74b7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.11.7"
+version = "4.12.0"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
@@ -25,6 +25,8 @@ dependencies = [
"jsonschema>=4.25.0",
"google-auth[requests]>=2.40.0",
"requests[socks]>=2.32.0",
+ "pystray>=0.19.5; sys_platform == 'win32' or sys_platform == 'darwin'",
+ "Pillow>=12.0.0; sys_platform == 'win32' or sys_platform == 'darwin'",
]
[project.scripts]
@@ -33,6 +35,9 @@ fcc-claude = "free_claude_code.cli.launchers.claude:launch"
fcc-codex = "free_claude_code.cli.launchers.codex:launch"
fcc-pi = "free_claude_code.cli.launchers.pi:launch"
+[project.gui-scripts]
+fcc-desktop = "free_claude_code.cli.desktop_entrypoint:launch"
+
[project.optional-dependencies]
voice = [
"grpcio>=1.82.1",
@@ -128,4 +133,11 @@ python-version = "3.14"
[tool.ty.analysis]
# Optional voice_local extra: torch, transformers, librosa for local whisper transcription
# Optional voice extra: nvidia-riva-client for nvidia_nim transcription provider
-allowed-unresolved-imports = ["torch", "transformers", "librosa", "riva.client"]
+allowed-unresolved-imports = [
+ "torch",
+ "transformers",
+ "librosa",
+ "riva.client",
+ "pystray",
+ "PIL",
+]
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index a666e8b2..754c3963 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -22,6 +22,7 @@ $PiInstallUrl = "https://pi.dev/install.ps1"
$UvInstallUrl = "https://astral.sh/uv/install.ps1"
$FccCommands = @(
# Include retired entry points so updates reject older FCC processes before replacement.
+ "fcc-desktop",
"fcc-server",
"fcc-claude",
"fcc-codex",
@@ -502,8 +503,9 @@ function Configure-AndConfirmFreeClaudeCode {
if ($DryRun) {
Write-Host "+ uv tool update-shell"
Write-Host "+ uv tool dir --bin"
- Write-Host "+ verify fcc-server, fcc-claude, fcc-codex, and fcc-pi in the uv tool bin directory"
+ Write-Host "+ verify fcc-desktop, fcc-server, fcc-claude, fcc-codex, and fcc-pi in the uv tool bin directory"
Write-Host "+ fcc-server --version"
+ Install-FccDesktopShortcuts -DesktopCommand "<uv-tool-bin>\fcc-desktop.exe"
return
}
@@ -523,7 +525,7 @@ function Configure-AndConfirmFreeClaudeCode {
[IO.Path]::AltDirectorySeparatorChar
)
$installedCommands = @{}
- foreach ($commandName in @("fcc-server", "fcc-claude", "fcc-codex", "fcc-pi")) {
+ foreach ($commandName in @("fcc-desktop", "fcc-server", "fcc-claude", "fcc-codex", "fcc-pi")) {
$command = Get-ApplicationCommand $commandName
if (-not $command) {
throw "Free Claude Code installation did not create '$commandName'."
@@ -539,6 +541,68 @@ function Configure-AndConfirmFreeClaudeCode {
}
Invoke-NativeCommand -FilePath $installedCommands["fcc-server"] -Arguments @("--version")
+ Install-FccDesktopShortcuts -DesktopCommand $installedCommands["fcc-desktop"]
+}
+
+function Test-EquivalentPath {
+ param(
+ [string] $Left,
+ [string] $Right
+ )
+
+ if ([string]::IsNullOrWhiteSpace($Left) -or [string]::IsNullOrWhiteSpace($Right)) {
+ return $false
+ }
+ try {
+ return [string]::Equals(
+ [IO.Path]::GetFullPath($Left),
+ [IO.Path]::GetFullPath($Right),
+ [StringComparison]::OrdinalIgnoreCase
+ )
+ }
+ catch {
+ return $false
+ }
+}
+
+function Install-FccDesktopShortcuts {
+ param([string] $DesktopCommand)
+
+ $shortcutPaths = @(
+ (Join-Path $env:USERPROFILE "Desktop\Free Claude Code.lnk"),
+ (Join-Path $env:APPDATA "Microsoft\Windows\Start Menu\Programs\Free Claude Code.lnk")
+ )
+ foreach ($shortcutPath in $shortcutPaths) {
+ Write-Host "+ create shortcut $(Format-Argument $shortcutPath) -> $(Format-Argument $DesktopCommand)"
+ }
+ if ($DryRun) {
+ return
+ }
+
+ $shell = New-Object -ComObject WScript.Shell
+ foreach ($shortcutPath in $shortcutPaths) {
+ if (Test-Path -LiteralPath $shortcutPath) {
+ try {
+ $existingShortcut = $shell.CreateShortcut($shortcutPath)
+ $isFccShortcut = Test-EquivalentPath -Left $existingShortcut.TargetPath -Right $DesktopCommand
+ }
+ catch {
+ $isFccShortcut = $false
+ }
+ if (-not $isFccShortcut) {
+ Write-Host "A shortcut not managed by Free Claude Code already exists at $shortcutPath; leaving it unchanged."
+ continue
+ }
+ }
+ $parent = Split-Path -Parent $shortcutPath
+ New-Item -ItemType Directory -Force -Path $parent | Out-Null
+ $shortcut = $shell.CreateShortcut($shortcutPath)
+ $shortcut.TargetPath = $DesktopCommand
+ $shortcut.WorkingDirectory = $env:USERPROFILE
+ $shortcut.IconLocation = "$DesktopCommand,0"
+ $shortcut.Description = "Run Free Claude Code in the background"
+ $shortcut.Save()
+ }
}
if ($Help) {
@@ -583,7 +647,8 @@ if ($DryRun) {
Write-Host "Dry run complete. No changes were made."
}
else {
- Write-Host "Free Claude Code is installed and verified. Start the proxy with: fcc-server"
+ Write-Host "Free Claude Code is installed and verified. Open the Free Claude Code desktop shortcut to run it in the background."
+ Write-Host "For terminal use, start the proxy with: fcc-server"
Write-Host "Run Claude Code with: fcc-claude"
Write-Host "Run Codex with: fcc-codex"
Write-Host "Run Pi with: fcc-pi"
diff --git a/scripts/install.sh b/scripts/install.sh
index 9b54cde9..5dfa2c8f 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -8,8 +8,10 @@ CLAUDE_INSTALL_URL="https://claude.ai/install.sh"
CODEX_INSTALL_URL="https://chatgpt.com/codex/install.sh"
PI_INSTALL_URL="https://pi.dev/install.sh"
UV_INSTALL_URL="https://astral.sh/uv/install.sh"
+FCC_MACOS_BUNDLE_ID="io.github.alishahryar1.free-claude-code"
+FCC_MACOS_OWNER_FILE=".free-claude-code-owner"
# Include retired entry points so updates reject older FCC processes before replacement.
-FCC_COMMANDS="fcc-server fcc-claude fcc-codex fcc-pi fcc-init free-claude-code"
+FCC_COMMANDS="fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-init free-claude-code"
dry_run=0
voice_nim=0
@@ -17,6 +19,7 @@ voice_local=0
voice_all=0
torch_backend=""
temporary_script=""
+tool_bin=""
show_usage() {
cat <<'USAGE'
@@ -490,7 +493,7 @@ configure_and_verify_free_claude_code() {
if [ "$dry_run" -eq 1 ]; then
print_command uv tool dir --bin
- printf '+ verify fcc-server, fcc-claude, fcc-codex, and fcc-pi in the uv tool bin directory\n'
+ printf '+ verify fcc-desktop, fcc-server, fcc-claude, fcc-codex, and fcc-pi in the uv tool bin directory\n'
print_command fcc-server --version
return 0
fi
@@ -508,13 +511,95 @@ configure_and_verify_free_claude_code() {
export PATH
hash -r 2>/dev/null || true
- for command_name in fcc-server fcc-claude fcc-codex fcc-pi; do
+ for command_name in fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi; do
[ -x "$tool_bin/$command_name" ] || fail "Free Claude Code installation did not create $tool_bin/$command_name."
done
run "$tool_bin/fcc-server" --version
}
+shell_quote() {
+ escaped=$(printf '%s' "$1" | sed "s/'/'\\\\''/g")
+ printf "'%s'" "$escaped"
+}
+
+macos_app_is_fcc_owned() {
+ app_dir=$1
+ owner_file="$app_dir/Contents/$FCC_MACOS_OWNER_FILE"
+ [ -d "$app_dir" ] &&
+ [ ! -L "$app_dir" ] &&
+ [ -f "$owner_file" ] &&
+ [ "$(cat "$owner_file")" = "$FCC_MACOS_BUNDLE_ID" ]
+}
+
+install_macos_desktop_app() {
+ [ "$(uname -s)" = "Darwin" ] || return 0
+
+ app_dir="$HOME/Applications/Free Claude Code.app"
+ contents_dir="$app_dir/Contents"
+ owner_file="$contents_dir/$FCC_MACOS_OWNER_FILE"
+ executable_dir="$contents_dir/MacOS"
+ executable_path="$executable_dir/fcc-desktop"
+ desktop_dir="$HOME/Desktop"
+ desktop_link="$desktop_dir/Free Claude Code.app"
+
+ if [ -e "$app_dir" ] || [ -L "$app_dir" ]; then
+ macos_app_is_fcc_owned "$app_dir" ||
+ fail "An app not managed by Free Claude Code already exists at $app_dir. Move it, then rerun the installer."
+ fi
+
+ if [ "$dry_run" -eq 1 ]; then
+ print_command mkdir -p "$executable_dir" "$desktop_dir"
+ printf '+ write %s, %s, and %s\n' "$owner_file" "$contents_dir/Info.plist" "$executable_path"
+ print_command ln -s "$app_dir" "$desktop_link"
+ return 0
+ fi
+
+ mkdir -p "$executable_dir" "$desktop_dir"
+ printf '%s\n' "$FCC_MACOS_BUNDLE_ID" > "$owner_file"
+ cat > "$contents_dir/Info.plist" <<'PLIST'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+ <key>CFBundleDisplayName</key>
+ <string>Free Claude Code</string>
+ <key>CFBundleExecutable</key>
+ <string>fcc-desktop</string>
+ <key>CFBundleIdentifier</key>
+ <string>io.github.alishahryar1.free-claude-code</string>
+ <key>CFBundleName</key>
+ <string>Free Claude Code</string>
+ <key>CFBundlePackageType</key>
+ <string>APPL</string>
+ <key>LSMultipleInstancesProhibited</key>
+ <true/>
+ <key>LSUIElement</key>
+ <true/>
+</dict>
+</plist>
+PLIST
+ desktop_command=$(shell_quote "$tool_bin/fcc-desktop")
+ {
+ printf '%s\n' '#!/bin/sh'
+ printf 'exec %s\n' "$desktop_command"
+ } > "$executable_path"
+ chmod +x "$executable_path"
+
+ if [ -L "$desktop_link" ]; then
+ if [ "$(readlink "$desktop_link")" = "$app_dir" ]; then
+ rm -f "$desktop_link"
+ else
+ printf 'A non-FCC link already exists at %s; leaving it unchanged.\n' "$desktop_link"
+ return 0
+ fi
+ elif [ -e "$desktop_link" ]; then
+ printf 'A non-FCC item already exists at %s; leaving it unchanged.\n' "$desktop_link"
+ return 0
+ fi
+ ln -s "$app_dir" "$desktop_link"
+}
+
parse_args "$@"
validate_args
add_known_bin_directories
@@ -546,10 +631,20 @@ install_free_claude_code
step "Configuring PATH and verifying Free Claude Code"
configure_and_verify_free_claude_code
+if [ "$(uname -s)" = "Darwin" ]; then
+ step "Installing the Free Claude Code desktop launcher"
+ install_macos_desktop_app
+fi
+
if [ "$dry_run" -eq 1 ]; then
printf '\nDry run complete. No changes were made.\n'
else
- printf '\nFree Claude Code is installed and verified. Start the proxy with: fcc-server\n'
+ if [ "$(uname -s)" = "Darwin" ]; then
+ printf '\nFree Claude Code is installed and verified. Open Free Claude Code from Applications or the desktop to run it in the background.\n'
+ printf 'For terminal use, start the proxy with: fcc-server\n'
+ else
+ printf '\nFree Claude Code is installed and verified. Start the proxy with: fcc-server\n'
+ fi
printf 'Run Claude Code with: fcc-claude\n'
printf 'Run Codex with: fcc-codex\n'
printf 'Run Pi with: fcc-pi\n'
diff --git a/scripts/uninstall.ps1 b/scripts/uninstall.ps1
index e6a9309f..7d9884e0 100644
--- a/scripts/uninstall.ps1
+++ b/scripts/uninstall.ps1
@@ -12,6 +12,7 @@ $PackageName = "free-claude-code"
$FccHomeDirname = ".fcc"
$FccCommands = @(
# Include retired entry points so older installations are fully stopped and removed.
+ "fcc-desktop",
"fcc-server",
"fcc-claude",
"fcc-codex",
@@ -210,6 +211,67 @@ function Confirm-FccCommandsRemoved {
}
}
+function Test-EquivalentPath {
+ param(
+ [string] $Left,
+ [string] $Right
+ )
+
+ if ([string]::IsNullOrWhiteSpace($Left) -or [string]::IsNullOrWhiteSpace($Right)) {
+ return $false
+ }
+ try {
+ return [string]::Equals(
+ [IO.Path]::GetFullPath($Left),
+ [IO.Path]::GetFullPath($Right),
+ [StringComparison]::OrdinalIgnoreCase
+ )
+ }
+ catch {
+ return $false
+ }
+}
+
+function Test-FccDesktopShortcutTarget {
+ param([string] $TargetPath)
+
+ foreach ($extension in @("", ".exe", ".cmd", ".bat", ".ps1")) {
+ $expectedTarget = Join-Path $script:UvToolBin "fcc-desktop$extension"
+ if (Test-EquivalentPath -Left $TargetPath -Right $expectedTarget) {
+ return $true
+ }
+ }
+ return $false
+}
+
+function Remove-FccDesktopShortcuts {
+ $shortcutPaths = @(
+ (Join-Path $env:USERPROFILE "Desktop\Free Claude Code.lnk"),
+ (Join-Path $env:APPDATA "Microsoft\Windows\Start Menu\Programs\Free Claude Code.lnk")
+ )
+ $shell = New-Object -ComObject WScript.Shell
+ foreach ($shortcutPath in $shortcutPaths) {
+ if (-not (Test-Path -LiteralPath $shortcutPath)) {
+ continue
+ }
+ try {
+ $shortcut = $shell.CreateShortcut($shortcutPath)
+ $isFccShortcut = Test-FccDesktopShortcutTarget -TargetPath $shortcut.TargetPath
+ }
+ catch {
+ $isFccShortcut = $false
+ }
+ if (-not $isFccShortcut) {
+ Write-Host "A shortcut not managed by Free Claude Code exists at $shortcutPath; leaving it unchanged."
+ continue
+ }
+ Write-Host "+ Remove-Item -LiteralPath $(Format-Argument $shortcutPath) -Force"
+ if (-not $DryRun) {
+ Remove-Item -LiteralPath $shortcutPath -Force
+ }
+ }
+}
+
function Purge-FccHome {
$fccHome = Join-Path $env:USERPROFILE $FccHomeDirname
if (-not (Test-Path -LiteralPath $fccHome)) {
@@ -259,6 +321,9 @@ Uninstall-FreeClaudeCode
Write-Step "Verifying Free Claude Code entry points were removed"
Confirm-FccCommandsRemoved
+Write-Step "Removing Free Claude Code desktop shortcuts"
+Remove-FccDesktopShortcuts
+
Write-Step "Purging FCC config and data from ~/.fcc"
Purge-FccHome
diff --git a/scripts/uninstall.sh b/scripts/uninstall.sh
index c22a921a..e2c3434f 100644
--- a/scripts/uninstall.sh
+++ b/scripts/uninstall.sh
@@ -3,8 +3,10 @@ set -eu
PACKAGE_NAME="free-claude-code"
FCC_HOME_DIRNAME=".fcc"
+FCC_MACOS_BUNDLE_ID="io.github.alishahryar1.free-claude-code"
+FCC_MACOS_OWNER_FILE=".free-claude-code-owner"
# Include retired entry points so older installations are fully stopped and removed.
-FCC_COMMANDS="fcc-server fcc-claude fcc-codex fcc-pi fcc-init free-claude-code"
+FCC_COMMANDS="fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-init free-claude-code"
dry_run=0
uv_tool_bin=""
@@ -200,6 +202,45 @@ verify_fcc_commands_removed() {
fi
}
+macos_app_is_fcc_owned() {
+ app_dir=$1
+ owner_file="$app_dir/Contents/$FCC_MACOS_OWNER_FILE"
+ [ -d "$app_dir" ] &&
+ [ ! -L "$app_dir" ] &&
+ [ -f "$owner_file" ] &&
+ [ "$(cat "$owner_file")" = "$FCC_MACOS_BUNDLE_ID" ]
+}
+
+remove_macos_desktop_app() {
+ [ "$(uname -s)" = "Darwin" ] || return 0
+
+ app_dir="$HOME/Applications/Free Claude Code.app"
+ desktop_link="$HOME/Desktop/Free Claude Code.app"
+
+ if ! macos_app_is_fcc_owned "$app_dir"; then
+ if [ -e "$app_dir" ] || [ -L "$app_dir" ]; then
+ printf 'An app not managed by Free Claude Code exists at %s; leaving it unchanged.\n' "$app_dir"
+ fi
+ if [ -e "$desktop_link" ] || [ -L "$desktop_link" ]; then
+ printf 'The Free Claude Code desktop item cannot be verified; leaving it unchanged.\n'
+ fi
+ return 0
+ fi
+
+ if [ -L "$desktop_link" ]; then
+ if [ "$(readlink "$desktop_link")" = "$app_dir" ]; then
+ run rm -f "$desktop_link"
+ else
+ printf 'A non-FCC link exists at %s; leaving it unchanged.\n' "$desktop_link"
+ fi
+ elif [ -e "$desktop_link" ]; then
+ printf 'A non-FCC item exists at %s; leaving it unchanged.\n' "$desktop_link"
+ fi
+ if [ -e "$app_dir" ]; then
+ run rm -rf "$app_dir"
+ fi
+}
+
purge_fcc_home() {
fcc_home="$HOME/$FCC_HOME_DIRNAME"
if [ ! -e "$fcc_home" ]; then
@@ -247,6 +288,9 @@ uninstall_free_claude_code
step "Verifying Free Claude Code entry points were removed"
verify_fcc_commands_removed
+step "Removing the Free Claude Code desktop launcher"
+remove_macos_desktop_app
+
step "Purging FCC config and data from ~/.fcc"
purge_fcc_home
diff --git a/src/free_claude_code/cli/commands.py b/src/free_claude_code/cli/commands.py
index bb75cd15..82fba516 100644
--- a/src/free_claude_code/cli/commands.py
+++ b/src/free_claude_code/cli/commands.py
@@ -6,6 +6,7 @@ import sys
import threading
import time
import webbrowser
+from enum import StrEnum
from pathlib import Path
import uvicorn
@@ -29,75 +30,196 @@ SERVER_GRACEFUL_SHUTDOWN_SECONDS = 5
def serve() -> None:
"""Start and supervise the FastAPI server."""
- opened_admin_browser = False
- try:
+ ServerSupervisor().run()
+
+
+class ServerStatus(StrEnum):
+ """Observable state of the server owned by a supervisor."""
+
+ STARTING = "Starting"
+ RUNNING = "Running"
+ STOPPING = "Stopping"
+ STOPPED = "Stopped"
+
+
+class ServerSupervisor:
+ """Own one FCC server lifecycle, including config-driven restarts."""
+
+ def __init__(self, *, console_logging: bool = True) -> None:
+ self._console_logging = console_logging
+ self._lock = threading.Lock()
+ self._server: uvicorn.Server | None = None
+ self._run_scheduled = False
+ self._running = False
+ self._stop_requested = False
+ self._restart_generation = 0
+
+ @property
+ def status(self) -> ServerStatus:
+ with self._lock:
+ if self._run_scheduled:
+ return ServerStatus.STARTING
+ if not self._running:
+ return ServerStatus.STOPPED
+ if self._server is None:
+ return ServerStatus.STARTING
+ if self._server.should_exit:
+ return ServerStatus.STOPPING
+ if self._server.started:
+ return ServerStatus.RUNNING
+ return ServerStatus.STARTING
+
+ def schedule_run(self) -> bool:
+ """Reserve a worker run before its thread starts."""
+
+ with self._lock:
+ if self._stop_requested or self._run_scheduled or self._running:
+ return False
+ self._run_scheduled = True
+ return True
+
+ def run(self, *, open_admin_browser: bool | None = None) -> None:
+ """Block until stopped, applying only fully closed Admin restarts."""
+
+ with self._lock:
+ self._run_scheduled = False
+ if self._running:
+ raise RuntimeError("The FCC server supervisor is already running.")
+ if self._stop_requested:
+ return
+ self._running = True
+
+ opened_admin_browser = False
try:
- while True:
- _migrate_legacy_env_if_missing()
- _migrate_config_env_keys()
- settings = get_settings()
- should_open_admin = (
- settings.open_admin_browser and not opened_admin_browser
- )
- if not _run_supervised_server(
- settings, open_admin_browser=should_open_admin
- ):
- return
- opened_admin_browser = opened_admin_browser or should_open_admin
- get_settings.cache_clear()
- except KeyboardInterrupt:
- return
- finally:
- kill_all_best_effort()
-
-
-def _schedule_open_admin_browser(settings: Settings) -> None:
- """After /health succeeds, open the admin UI in the default browser (daemon thread)."""
+ try:
+ while not self._is_stop_requested():
+ with self._lock:
+ restart_generation = self._restart_generation
+ settings = load_server_settings()
+ should_open_admin = (
+ settings.open_admin_browser
+ if open_admin_browser is None
+ else open_admin_browser
+ ) and not opened_admin_browser
+ if not self._run_once(
+ settings,
+ open_admin_browser=should_open_admin,
+ restart_generation=restart_generation,
+ ):
+ return
+ opened_admin_browser = opened_admin_browser or should_open_admin
+ get_settings.cache_clear()
+ except KeyboardInterrupt:
+ return
+ finally:
+ with self._lock:
+ self._server = None
+ self._running = False
+ kill_all_best_effort()
+
+ def request_restart(self) -> bool:
+ """Reload an active generation or coalesce into a scheduled fresh run."""
+
+ with self._lock:
+ if self._stop_requested:
+ return False
+ if self._run_scheduled:
+ self._restart_generation += 1
+ return True
+ if not self._running:
+ return False
+ self._restart_generation += 1
+ if self._server is not None:
+ self._server.should_exit = True
+ return True
+
+ def request_stop(self) -> None:
+ """Permanently stop this supervisor after graceful runtime cleanup."""
+
+ with self._lock:
+ self._stop_requested = True
+ self._run_scheduled = False
+ if self._server is not None:
+ self._server.should_exit = True
+
+ def _is_stop_requested(self) -> bool:
+ with self._lock:
+ return self._stop_requested
+
+ def _run_once(
+ self,
+ settings: Settings,
+ *,
+ open_admin_browser: bool,
+ restart_generation: int,
+ ) -> bool:
+ asgi_app = build_asgi_app(
+ settings,
+ restart_callback=self._request_runtime_restart,
+ )
+ config = uvicorn.Config(
+ asgi_app,
+ host=settings.host,
+ port=settings.port,
+ log_level="debug",
+ log_config=(
+ uvicorn.config.LOGGING_CONFIG if self._console_logging else None
+ ),
+ timeout_graceful_shutdown=SERVER_GRACEFUL_SHUTDOWN_SECONDS,
+ )
+ server = uvicorn.Server(config)
+ with self._lock:
+ self._server = server
+ if self._stop_requested or self._restart_generation != restart_generation:
+ server.should_exit = True
+
+ if open_admin_browser:
+ schedule_open_admin_browser(settings)
+ server.run()
+
+ with self._lock:
+ if self._server is server:
+ self._server = None
+ restart_requested = self._restart_generation != restart_generation
+ stop_requested = self._stop_requested
+ return restart_requested and not stop_requested and asgi_app.runtime.is_closed
+
+ def _request_runtime_restart(self) -> None:
+ self.request_restart()
+
+
+def load_server_settings() -> Settings:
+ """Apply owned config migrations before returning the cached settings."""
+
+ _migrate_legacy_env_if_missing()
+ _migrate_config_env_keys()
+ return get_settings()
+
+
+def open_admin_when_ready(settings: Settings) -> bool:
+ """Wait briefly for /health, then open the current Admin UI."""
admin_url = local_admin_url(settings)
proxy_root_url = local_proxy_root_url(settings)
+ deadline = time.monotonic() + 30.0
+ while time.monotonic() < deadline:
+ if preflight_proxy(proxy_root_url) is None:
+ return webbrowser.open(admin_url)
+ time.sleep(0.15)
+ return False
- def open_when_ready() -> None:
- deadline = time.monotonic() + 30.0
- while time.monotonic() < deadline:
- if preflight_proxy(proxy_root_url) is None:
- webbrowser.open(admin_url)
- return
- time.sleep(0.15)
+
+def schedule_open_admin_browser(settings: Settings) -> None:
+ """Open Admin after health succeeds without blocking the caller."""
threading.Thread(
- target=open_when_ready, name="fcc-open-admin-browser", daemon=True
+ target=open_admin_when_ready,
+ args=(settings,),
+ name="fcc-open-admin-browser",
+ daemon=True,
).start()
-def _run_supervised_server(settings: Settings, *, open_admin_browser: bool) -> bool:
- """Run once; restart only after the old ownership graph fully closes."""
-
- restart_requested = False
- server_holder: dict[str, uvicorn.Server] = {}
-
- def request_restart() -> None:
- nonlocal restart_requested
- restart_requested = True
- if server := server_holder.get("server"):
- server.should_exit = True
-
- asgi_app = build_asgi_app(settings, restart_callback=request_restart)
- config = uvicorn.Config(
- asgi_app,
- host=settings.host,
- port=settings.port,
- log_level="debug",
- timeout_graceful_shutdown=SERVER_GRACEFUL_SHUTDOWN_SECONDS,
- )
- server = uvicorn.Server(config)
- server_holder["server"] = server
- if open_admin_browser:
- _schedule_open_admin_browser(settings)
- server.run()
- return restart_requested and asgi_app.runtime.is_closed
-
-
def _migrate_legacy_env_if_missing() -> Path | None:
"""Copy a legacy user env into the managed config path when absent."""
diff --git a/src/free_claude_code/cli/desktop.py b/src/free_claude_code/cli/desktop.py
new file mode 100644
index 00000000..76ba2275
--- /dev/null
+++ b/src/free_claude_code/cli/desktop.py
@@ -0,0 +1,205 @@
+"""Platform-neutral lifecycle for the FCC desktop shell."""
+
+import os
+import threading
+from collections.abc import Callable
+from pathlib import Path
+from typing import BinaryIO, Protocol
+
+from free_claude_code.cli.commands import (
+ ServerStatus,
+ ServerSupervisor,
+ load_server_settings,
+ open_admin_when_ready,
+ schedule_open_admin_browser,
+)
+from free_claude_code.cli.launchers.common import preflight_proxy
+from free_claude_code.config.paths import config_dir_path
+from free_claude_code.config.server_urls import local_proxy_root_url
+from free_claude_code.config.settings import get_settings
+
+if os.name == "nt":
+ import msvcrt
+
+ def _try_lock(handle: BinaryIO) -> bool:
+ if os.fstat(handle.fileno()).st_size == 0:
+ handle.seek(0)
+ handle.write(b"\0")
+ handle.flush()
+ handle.seek(0)
+ try:
+ msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
+ except OSError:
+ return False
+ return True
+
+ def _unlock(handle: BinaryIO) -> None:
+ handle.seek(0)
+ msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+
+else:
+ import fcntl
+
+ def _try_lock(handle: BinaryIO) -> bool:
+ try:
+ fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+ except BlockingIOError:
+ return False
+ return True
+
+ def _unlock(handle: BinaryIO) -> None:
+ fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+class DesktopTray(Protocol):
+ """UI loop owned by the platform tray adapter."""
+
+ def run(self) -> None: ...
+
+ def stop(self) -> None: ...
+
+
+class DesktopTrayFactory(Protocol):
+ """Construct a tray adapter around a desktop controller."""
+
+ def __call__(self, controller: DesktopController) -> DesktopTray: ...
+
+
+class ServerOwner(Protocol):
+ """Server lifecycle used by the desktop controller."""
+
+ @property
+ def status(self) -> ServerStatus: ...
+
+ def schedule_run(self) -> bool: ...
+
+ def run(self, *, open_admin_browser: bool | None = None) -> None: ...
+
+ def request_restart(self) -> bool: ...
+
+ def request_stop(self) -> None: ...
+
+
+class DesktopInstanceLock:
+ """Cross-process lock automatically released by the operating system."""
+
+ def __init__(self, path: Path | None = None) -> None:
+ self._path = path or config_dir_path() / "desktop.lock"
+ self._handle: BinaryIO | None = None
+
+ def acquire(self) -> bool:
+ """Acquire the singleton lock without waiting."""
+
+ if self._handle is not None:
+ return True
+ self._path.parent.mkdir(parents=True, exist_ok=True)
+ handle = self._path.open("a+b")
+ if not _try_lock(handle):
+ handle.close()
+ return False
+ self._handle = handle
+ return True
+
+ def release(self) -> None:
+ """Release a held lock; repeated calls are harmless."""
+
+ handle = self._handle
+ if handle is None:
+ return
+ self._handle = None
+ try:
+ _unlock(handle)
+ finally:
+ handle.close()
+
+
+class DesktopController:
+ """Coordinate one tray loop with one in-process FCC server owner."""
+
+ def __init__(
+ self,
+ supervisor: ServerOwner,
+ tray_factory: DesktopTrayFactory,
+ open_admin: Callable[[], None],
+ ) -> None:
+ self._supervisor = supervisor
+ self._open_admin = open_admin
+ self._thread_lock = threading.Lock()
+ self._server_thread: threading.Thread | None = None
+ self._tray = tray_factory(self)
+
+ @property
+ def status(self) -> ServerStatus:
+ return self._supervisor.status
+
+ def run(self) -> None:
+ """Run the tray on this thread and the FCC server on its owned worker."""
+
+ self._start_server()
+ try:
+ self._tray.run()
+ finally:
+ self._supervisor.request_stop()
+ self._tray.stop()
+ with self._thread_lock:
+ thread = self._server_thread
+ if thread is not None:
+ thread.join()
+
+ def open_admin(self) -> None:
+ self._open_admin()
+
+ def restart_server(self) -> None:
+ """Restart an active server or relaunch one that exited unexpectedly."""
+
+ with self._thread_lock:
+ thread = self._server_thread
+ if thread is not None and thread.is_alive():
+ self._supervisor.request_restart()
+ return
+ self._start_server()
+
+ def quit(self) -> None:
+ """Close the server gracefully and end the platform tray loop."""
+
+ self._supervisor.request_stop()
+ self._tray.stop()
+
+ def _start_server(self) -> None:
+ with self._thread_lock:
+ if self._server_thread is not None and self._server_thread.is_alive():
+ return
+ if not self._supervisor.schedule_run():
+ return
+ self._server_thread = threading.Thread(
+ target=self._run_server,
+ name="fcc-desktop-server",
+ )
+ self._server_thread.start()
+
+ def _run_server(self) -> None:
+ self._supervisor.run(open_admin_browser=False)
+
+
+def launch_desktop(tray_factory: DesktopTrayFactory) -> None:
+ """Start the singleton desktop host or focus the already running FCC UI."""
+
+ settings = load_server_settings()
+ instance_lock = DesktopInstanceLock()
+ if not instance_lock.acquire():
+ open_admin_when_ready(settings)
+ return
+
+ try:
+ if preflight_proxy(local_proxy_root_url(settings)) is None:
+ open_admin_when_ready(settings)
+ return
+
+ supervisor = ServerSupervisor(console_logging=False)
+
+ def open_current_admin() -> None:
+ schedule_open_admin_browser(get_settings())
+
+ DesktopController(supervisor, tray_factory, open_current_admin).run()
+ finally:
+ instance_lock.release()
diff --git a/src/free_claude_code/cli/desktop_entrypoint.py b/src/free_claude_code/cli/desktop_entrypoint.py
new file mode 100644
index 00000000..a294c4ad
--- /dev/null
+++ b/src/free_claude_code/cli/desktop_entrypoint.py
@@ -0,0 +1,13 @@
+"""Lightweight platform gate for the optional FCC desktop dependencies."""
+
+import sys
+
+if sys.platform in {"darwin", "win32"}:
+ from free_claude_code.cli.desktop_tray import launch
+else:
+
+ def launch() -> None:
+ """Reject platforms for which FCC does not install a desktop shell."""
+
+ print("FCC Desktop is supported on Windows and macOS.", file=sys.stderr)
+ raise SystemExit(1)
diff --git a/src/free_claude_code/cli/desktop_tray.py b/src/free_claude_code/cli/desktop_tray.py
new file mode 100644
index 00000000..c6d94be9
--- /dev/null
+++ b/src/free_claude_code/cli/desktop_tray.py
@@ -0,0 +1,65 @@
+"""pystray adapter for the Windows tray and macOS menu bar."""
+
+from PIL import Image, ImageDraw
+from pystray import Icon, Menu, MenuItem
+
+from free_claude_code.cli.desktop import DesktopController, launch_desktop
+
+
+class PystrayDesktopTray:
+ """Render desktop lifecycle actions through the native status area."""
+
+ def __init__(self, controller: DesktopController) -> None:
+ self._controller = controller
+ self._icon = Icon(
+ "free-claude-code",
+ _create_icon(),
+ "Free Claude Code",
+ Menu(
+ MenuItem("Open Admin", self._open_admin, default=True),
+ MenuItem("Check Server Status", self._check_status),
+ MenuItem("Restart Server", self._restart_server),
+ Menu.SEPARATOR,
+ MenuItem("Quit", self._quit),
+ ),
+ )
+
+ def run(self) -> None:
+ self._icon.run()
+
+ def stop(self) -> None:
+ self._icon.stop()
+
+ def _open_admin(self, _icon: Icon, _item: MenuItem) -> None:
+ self._controller.open_admin()
+
+ def _check_status(self, _icon: Icon, _item: MenuItem) -> None:
+ self._icon.notify(
+ f"Server is {self._controller.status}.",
+ "Free Claude Code",
+ )
+
+ def _restart_server(self, _icon: Icon, _item: MenuItem) -> None:
+ self._controller.restart_server()
+
+ def _quit(self, _icon: Icon, _item: MenuItem) -> None:
+ self._controller.quit()
+
+
+def _create_icon() -> Image.Image:
+ """Build a crisp scalable tray glyph without a packaged binary asset."""
+
+ image = Image.new("RGBA", (64, 64), (0, 0, 0, 0))
+ draw = ImageDraw.Draw(image)
+ draw.rounded_rectangle((4, 4, 60, 60), radius=14, fill="#111827")
+ color = "#60A5FA"
+ draw.line((19, 17, 19, 48), fill=color, width=7)
+ draw.line((19, 18, 46, 18), fill=color, width=7)
+ draw.line((19, 32, 40, 32), fill=color, width=7)
+ return image
+
+
+def launch() -> None:
+ """Launch the supported native tray adapter."""
+
+ launch_desktop(PystrayDesktopTray)
diff --git a/tests/cli/test_desktop.py b/tests/cli/test_desktop.py
new file mode 100644
index 00000000..d5275663
--- /dev/null
+++ b/tests/cli/test_desktop.py
@@ -0,0 +1,271 @@
+"""Desktop shell lifecycle and singleton contracts."""
+
+import threading
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from free_claude_code.cli.commands import ServerStatus, ServerSupervisor
+from free_claude_code.cli.desktop import DesktopController, DesktopInstanceLock
+from free_claude_code.config.settings import Settings
+
+
+def _settings() -> Settings:
+ return Settings.model_construct(host="0.0.0.0", port=8082)
+
+
+def test_desktop_instance_lock_is_exclusive_and_reusable(tmp_path: Path) -> None:
+ lock_path = tmp_path / "desktop.lock"
+ first = DesktopInstanceLock(lock_path)
+ second = DesktopInstanceLock(lock_path)
+
+ assert first.acquire() is True
+ assert first.acquire() is True
+ assert second.acquire() is False
+
+ first.release()
+ first.release()
+ assert second.acquire() is True
+ second.release()
+
+
+def test_supervisor_accepts_restart_during_scheduled_startup() -> None:
+ supervisor = ServerSupervisor(console_logging=False)
+ settings = _settings()
+
+ with (
+ patch(
+ "free_claude_code.cli.commands.load_server_settings",
+ return_value=settings,
+ ),
+ patch.object(supervisor, "_run_once", return_value=False) as run_once,
+ patch("free_claude_code.cli.commands.kill_all_best_effort"),
+ ):
+ assert supervisor.schedule_run() is True
+ assert supervisor.status is ServerStatus.STARTING
+ assert supervisor.request_restart() is True
+ supervisor.run(open_admin_browser=False)
+
+ run_once.assert_called_once_with(
+ settings,
+ open_admin_browser=False,
+ restart_generation=1,
+ )
+ assert supervisor.status is ServerStatus.STOPPED
+
+
+def test_desktop_controller_owns_server_thread_and_graceful_quit() -> None:
+ opened = threading.Event()
+
+ class FakeSupervisor:
+ def __init__(self) -> None:
+ self.status = ServerStatus.STARTING
+ self.started = threading.Event()
+ self.stopped = threading.Event()
+ self.run_arguments: list[bool | None] = []
+ self.schedule_count = 0
+ self.restart_count = 0
+ self.stop_count = 0
+
+ def schedule_run(self) -> bool:
+ self.schedule_count += 1
+ return True
+
+ def run(self, *, open_admin_browser: bool | None = None) -> None:
+ self.run_arguments.append(open_admin_browser)
+ self.status = ServerStatus.RUNNING
+ self.started.set()
+ assert self.stopped.wait(2)
+ self.status = ServerStatus.STOPPED
+
+ def request_restart(self) -> bool:
+ self.restart_count += 1
+ return True
+
+ def request_stop(self) -> None:
+ self.stop_count += 1
+ self.status = ServerStatus.STOPPING
+ self.stopped.set()
+
+ class FakeTray:
+ def __init__(self, controller: DesktopController) -> None:
+ self.controller = controller
+ self.run_thread_id: int | None = None
+ self.stop_count = 0
+
+ def run(self) -> None:
+ self.run_thread_id = threading.get_ident()
+ assert supervisor.started.wait(2)
+ self.controller.open_admin()
+ self.controller.restart_server()
+ self.controller.quit()
+
+ def stop(self) -> None:
+ self.stop_count += 1
+
+ supervisor = FakeSupervisor()
+ tray: FakeTray | None = None
+
+ def make_tray(controller: DesktopController) -> FakeTray:
+ nonlocal tray
+ tray = FakeTray(controller)
+ return tray
+
+ main_thread_id = threading.get_ident()
+ controller = DesktopController(supervisor, make_tray, opened.set)
+ controller.run()
+
+ assert tray is not None
+ assert tray.run_thread_id == main_thread_id
+ assert supervisor.run_arguments == [False]
+ assert supervisor.schedule_count == 1
+ assert supervisor.restart_count == 1
+ assert supervisor.stop_count >= 1
+ assert tray.stop_count >= 1
+ assert opened.is_set()
+
+
+def test_restart_during_server_startup_is_accepted_without_waiting() -> None:
+ class StartupSupervisor:
+ def __init__(self) -> None:
+ self.status = ServerStatus.STARTING
+ self.run_called = threading.Event()
+ self.allow_run = threading.Event()
+ self.worker_started = threading.Event()
+ self.release_worker = threading.Event()
+ self.run_scheduled = False
+ self.restart_count = 0
+ self.accepted_restart_count = 0
+
+ def schedule_run(self) -> bool:
+ self.run_scheduled = True
+ return True
+
+ def run(self, *, open_admin_browser: bool | None = None) -> None:
+ assert open_admin_browser is False
+ self.run_called.set()
+ assert self.allow_run.wait(2)
+ self.run_scheduled = False
+ self.worker_started.set()
+ assert self.release_worker.wait(2)
+ self.status = ServerStatus.STOPPED
+
+ def request_restart(self) -> bool:
+ self.restart_count += 1
+ if self.run_scheduled:
+ self.accepted_restart_count += 1
+ return True
+ return False
+
+ def request_stop(self) -> None:
+ self.release_worker.set()
+
+ class WaitingTray:
+ def __init__(self, _controller: DesktopController) -> None:
+ self.started = threading.Event()
+ self.stopped = threading.Event()
+
+ def run(self) -> None:
+ self.started.set()
+ assert self.stopped.wait(2)
+
+ def stop(self) -> None:
+ self.stopped.set()
+
+ supervisor = StartupSupervisor()
+ tray: WaitingTray | None = None
+
+ def make_tray(controller: DesktopController) -> WaitingTray:
+ nonlocal tray
+ tray = WaitingTray(controller)
+ return tray
+
+ controller = DesktopController(supervisor, make_tray, MagicMock())
+ controller_thread = threading.Thread(target=controller.run)
+ controller_thread.start()
+ assert tray is not None
+ assert tray.started.wait(2)
+ assert supervisor.run_called.wait(2)
+
+ restart_thread = threading.Thread(target=controller.restart_server)
+ restart_thread.start()
+ restart_thread.join(0.5)
+ restart_blocked = restart_thread.is_alive()
+
+ supervisor.allow_run.set()
+ assert supervisor.worker_started.wait(2)
+ controller.quit()
+ supervisor.release_worker.set()
+ restart_thread.join(2)
+ controller_thread.join(2)
+
+ assert restart_blocked is False
+ assert supervisor.restart_count == 1
+ assert supervisor.accepted_restart_count == 1
+ assert not restart_thread.is_alive()
+ assert not controller_thread.is_alive()
+
+
+def test_second_desktop_launch_opens_existing_admin_without_new_server() -> None:
+ from free_claude_code.cli import desktop
+
+ settings = _settings()
+ instance_lock = MagicMock()
+ instance_lock.acquire.return_value = False
+
+ with (
+ patch.object(desktop, "load_server_settings", return_value=settings),
+ patch.object(desktop, "DesktopInstanceLock", return_value=instance_lock),
+ patch.object(desktop, "open_admin_when_ready", return_value=True) as open_admin,
+ patch.object(desktop, "ServerSupervisor") as supervisor,
+ ):
+ desktop.launch_desktop(MagicMock())
+
+ open_admin.assert_called_once_with(settings)
+ supervisor.assert_not_called()
+ instance_lock.release.assert_not_called()
+
+
+def test_desktop_attaches_to_terminal_server_instead_of_binding_twice() -> None:
+ from free_claude_code.cli import desktop
+
+ settings = _settings()
+ instance_lock = MagicMock()
+ instance_lock.acquire.return_value = True
+
+ with (
+ patch.object(desktop, "load_server_settings", return_value=settings),
+ patch.object(desktop, "DesktopInstanceLock", return_value=instance_lock),
+ patch.object(desktop, "preflight_proxy", return_value=None),
+ patch.object(desktop, "open_admin_when_ready", return_value=True) as open_admin,
+ patch.object(desktop, "ServerSupervisor") as supervisor,
+ ):
+ desktop.launch_desktop(MagicMock())
+
+ open_admin.assert_called_once_with(settings)
+ supervisor.assert_not_called()
+ instance_lock.release.assert_called_once_with()
+
+
+def test_fresh_desktop_launch_disables_console_and_automatic_browser() -> None:
+ from free_claude_code.cli import desktop
+
+ settings = _settings()
+ instance_lock = MagicMock()
+ instance_lock.acquire.return_value = True
+ supervisor = MagicMock()
+ controller = MagicMock()
+
+ with (
+ patch.object(desktop, "load_server_settings", return_value=settings),
+ patch.object(desktop, "DesktopInstanceLock", return_value=instance_lock),
+ patch.object(desktop, "preflight_proxy", return_value="connection refused"),
+ patch.object(desktop, "ServerSupervisor", return_value=supervisor) as owner,
+ patch.object(desktop, "DesktopController", return_value=controller) as shell,
+ ):
+ tray_factory = MagicMock()
+ desktop.launch_desktop(tray_factory)
+
+ owner.assert_called_once_with(console_logging=False)
+ assert shell.call_args.args[:2] == (supervisor, tray_factory)
+ controller.run.assert_called_once_with()
+ instance_lock.release.assert_called_once_with()
diff --git a/tests/cli/test_entrypoints.py b/tests/cli/test_entrypoints.py
index 86e77ae8..343826e1 100644
--- a/tests/cli/test_entrypoints.py
+++ b/tests/cli/test_entrypoints.py
@@ -94,6 +94,9 @@ def test_cli_scripts_are_registered() -> None:
"fcc-codex": "free_claude_code.cli.launchers.codex:launch",
"fcc-pi": "free_claude_code.cli.launchers.pi:launch",
}
+ assert pyproject["project"]["gui-scripts"] == {
+ "fcc-desktop": "free_claude_code.cli.desktop_entrypoint:launch",
+ }
@pytest.mark.parametrize(
@@ -155,12 +158,13 @@ def test_schedule_open_admin_browser_opens_when_health_ready() -> None:
opened_urls: list[str] = []
class ImmediateThread:
- def __init__(self, target=None, **_kwargs: object) -> None:
+ def __init__(self, target=None, args=(), **_kwargs: object) -> None:
self._target = target
+ self._args = args
def start(self) -> None:
assert self._target is not None
- self._target()
+ self._target(*self._args)
with (
patch.object(commands.threading, "Thread", ImmediateThread),
@@ -172,7 +176,7 @@ def test_schedule_open_admin_browser_opens_when_health_ready() -> None:
),
patch.object(commands.time, "sleep"),
):
- commands._schedule_open_admin_browser(settings)
+ commands.schedule_open_admin_browser(settings)
assert opened_urls == [local_admin_url(settings)]
@@ -187,13 +191,17 @@ def test_serve_skips_admin_browser_when_setting_is_disabled() -> None:
with (
patch.object(commands, "get_settings", get_settings),
patch.object(
- commands, "_run_supervised_server", return_value=False
+ commands.ServerSupervisor, "_run_once", return_value=False
) as run_server,
patch.object(commands, "kill_all_best_effort"),
):
commands.serve()
- run_server.assert_called_once_with(settings, open_admin_browser=False)
+ run_server.assert_called_once_with(
+ settings,
+ open_admin_browser=False,
+ restart_generation=0,
+ )
def test_serve_supervisor_restarts_when_app_requests_restart() -> None:
@@ -233,7 +241,7 @@ def test_serve_supervisor_restarts_when_app_requests_restart() -> None:
patch.object(commands.uvicorn, "Config", side_effect=fake_config),
patch.object(commands.uvicorn, "Server", side_effect=FakeServer),
patch.object(commands, "build_asgi_app", side_effect=build_asgi_app),
- patch.object(commands, "_schedule_open_admin_browser") as schedule_open_admin,
+ patch.object(commands, "schedule_open_admin_browser") as schedule_open_admin,
patch.object(commands, "kill_all_best_effort") as kill_all,
):
commands.serve()
@@ -275,7 +283,7 @@ def test_serve_supervisor_refuses_restart_after_incomplete_shutdown() -> None:
patch.object(commands.uvicorn, "Config", side_effect=fake_config),
patch.object(commands.uvicorn, "Server", side_effect=FakeServer),
patch.object(commands, "build_asgi_app", side_effect=build_asgi_app),
- patch.object(commands, "_schedule_open_admin_browser"),
+ patch.object(commands, "schedule_open_admin_browser"),
patch.object(commands, "kill_all_best_effort") as kill_all,
):
commands.serve()
@@ -298,7 +306,7 @@ def test_serve_migrates_legacy_env_before_loading_settings(tmp_path: Path) -> No
with (
patch("pathlib.Path.home", return_value=tmp_path),
patch.object(commands, "get_settings", get_settings),
- patch.object(commands, "_run_supervised_server", return_value=False),
+ patch.object(commands.ServerSupervisor, "_run_once", return_value=False),
patch.object(commands, "kill_all_best_effort"),
):
commands.serve()
@@ -326,7 +334,7 @@ def test_serve_migrates_hf_token_before_loading_settings(
with (
patch("pathlib.Path.home", return_value=tmp_path),
patch.object(commands, "get_settings", get_settings),
- patch.object(commands, "_run_supervised_server", return_value=False),
+ patch.object(commands.ServerSupervisor, "_run_once", return_value=False),
patch.object(commands, "kill_all_best_effort"),
patch.object(commands, "explicit_env_file_migration_warning"),
):
@@ -365,8 +373,8 @@ def test_serve_handles_keyboard_interrupt_without_traceback() -> None:
with (
patch.object(commands, "get_settings", get_settings),
patch.object(
- commands,
- "_run_supervised_server",
+ commands.ServerSupervisor,
+ "_run_once",
side_effect=KeyboardInterrupt,
),
patch.object(commands, "kill_all_best_effort") as kill_all,
diff --git a/tests/scripts/test_installers.py b/tests/scripts/test_installers.py
index 12487162..2b53a5f0 100644
--- a/tests/scripts/test_installers.py
+++ b/tests/scripts/test_installers.py
@@ -7,6 +7,7 @@ from pathlib import Path
import pytest
FCC_COMMANDS = (
+ "fcc-desktop",
"fcc-server",
"fcc-claude",
"fcc-codex",
@@ -95,6 +96,7 @@ if [ "${{1:-}}" = "tool" ] && [ "${{2:-}}" = "install" ]; then
fi
mkdir -p "$FAKE_TOOL_BIN"
cp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-server"
+ cp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-desktop"
cp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-claude"
cp "$FAKE_FIXTURES/fcc-command.sh" "$FAKE_TOOL_BIN/fcc-pi"
if [ "$FAIL_STEP" != "fcc-missing" ]; then
@@ -291,6 +293,12 @@ fi
if [ "$name" = "fcc-server" ] && [ "${1:-}" = "--version" ]; then
echo "free-claude-code 3.5.18"
fi
+""",
+ )
+ _write_executable(
+ bin_dir / "uname",
+ """#!/bin/sh
+printf '%s\n' "${FAKE_UNAME:-Linux}"
""",
)
@@ -305,6 +313,7 @@ fi
"FCC_PROCESS_MARKER": str(tmp_path / "fcc-process-ready"),
"FCC_RUNNING_COMMAND": "",
"FCC_RUNNING_PHASE": "early",
+ "FAKE_UNAME": "Linux",
"FAIL_STEP": "",
}
)
@@ -338,6 +347,71 @@ def test_install_sh_fresh_install_is_verified(posix_harness: PosixHarness) -> No
]
+def test_install_sh_creates_native_macos_app_and_desktop_link(
+ posix_harness: PosixHarness,
+) -> None:
+ posix_harness.env["FAKE_UNAME"] = "Darwin"
+ tool_bin = posix_harness.root / "tool's bin"
+ posix_harness.env["FAKE_TOOL_BIN"] = str(tool_bin)
+
+ result = posix_harness.run()
+
+ assert result.returncode == 0, result.stderr
+ app = posix_harness.root / "home" / "Applications" / "Free Claude Code.app"
+ plist = app / "Contents" / "Info.plist"
+ owner_file = app / "Contents" / ".free-claude-code-owner"
+ launcher = app / "Contents" / "MacOS" / "fcc-desktop"
+ desktop_link = posix_harness.root / "home" / "Desktop" / "Free Claude Code.app"
+ assert owner_file.read_text(encoding="utf-8").strip() == (
+ "io.github.alishahryar1.free-claude-code"
+ )
+ assert "<key>LSUIElement</key>" in plist.read_text(encoding="utf-8")
+ assert "<key>LSMultipleInstancesProhibited</key>" in plist.read_text(
+ encoding="utf-8"
+ )
+ assert launcher.stat().st_mode & 0o111
+ expected_command = str(tool_bin / "fcc-desktop").replace("'", "'\\''")
+ assert f"exec '{expected_command}'" in launcher.read_text(encoding="utf-8")
+ assert desktop_link.is_symlink()
+ assert desktop_link.readlink() == app
+
+
+def test_install_sh_rejects_unowned_macos_app_bundle(
+ posix_harness: PosixHarness,
+) -> None:
+ posix_harness.env["FAKE_UNAME"] = "Darwin"
+ app = posix_harness.root / "home" / "Applications" / "Free Claude Code.app"
+ contents = app / "Contents"
+ contents.mkdir(parents=True)
+ plist = contents / "Info.plist"
+ plist.write_text("foreign app", encoding="utf-8")
+
+ result = posix_harness.run()
+
+ assert result.returncode != 0
+ assert "not managed by Free Claude Code" in result.stderr
+ assert plist.read_text(encoding="utf-8") == "foreign app"
+ assert not (contents / ".free-claude-code-owner").exists()
+
+
+def test_install_sh_preserves_unrelated_macos_desktop_link(
+ posix_harness: PosixHarness,
+) -> None:
+ posix_harness.env["FAKE_UNAME"] = "Darwin"
+ desktop = posix_harness.root / "home" / "Desktop"
+ desktop.mkdir()
+ unrelated = posix_harness.root / "Unrelated.app"
+ unrelated.mkdir()
+ desktop_link = desktop / "Free Claude Code.app"
+ desktop_link.symlink_to(unrelated, target_is_directory=True)
+
+ result = posix_harness.run()
+
+ assert result.returncode == 0, result.stderr
+ assert "non-FCC link" in result.stdout
+ assert desktop_link.readlink() == unrelated
+
+
@pytest.mark.parametrize("uv_version", ("0.11.16", "0.11.16+build.1"))
def test_install_sh_preserves_valid_existing_tools(
posix_harness: PosixHarness,
@@ -593,6 +667,35 @@ def _powershells() -> tuple[str, ...]:
return tuple(dict.fromkeys(path for path in candidates if path is not None))
+def _create_windows_shortcut(
+ powershell: str,
+ shortcut_path: Path,
+ target_path: Path,
+) -> None:
+ shortcut_path.parent.mkdir(parents=True, exist_ok=True)
+ env = os.environ | {
+ "FCC_TEST_SHORTCUT": str(shortcut_path),
+ "FCC_TEST_TARGET": str(target_path),
+ }
+ subprocess.run(
+ [
+ powershell,
+ "-NoProfile",
+ "-Command",
+ (
+ "$shell = New-Object -ComObject WScript.Shell; "
+ "$shortcut = $shell.CreateShortcut($env:FCC_TEST_SHORTCUT); "
+ "$shortcut.TargetPath = $env:FCC_TEST_TARGET; "
+ "$shortcut.Save()"
+ ),
+ ],
+ check=True,
+ capture_output=True,
+ text=True,
+ env=env,
+ )
+
+
def _batch_client(name: str) -> str:
help_output = (
"echo --extension, -e ^<path^> Load an extension\n"
@@ -637,6 +740,7 @@ exit /b 0
if "%FAIL_STEP%"=="fcc-install" exit /b 53
if not exist "%FAKE_TOOL_BIN%" mkdir "%FAKE_TOOL_BIN%"
copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-server.cmd" >nul
+copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-desktop.cmd" >nul
copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-claude.cmd" >nul
copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-pi.cmd" >nul
if not "%FAIL_STEP%"=="fcc-missing" copy /y "%FAKE_FIXTURES%\fcc-command.cmd" "%FAKE_TOOL_BIN%\fcc-codex.cmd" >nul
@@ -887,6 +991,39 @@ def test_install_ps1_fresh_install_is_verified(
"uv:tool dir --bin",
"fcc-server:--version",
]
+ home = Path(powershell_harness.env["USERPROFILE"])
+ app_data = Path(powershell_harness.env["APPDATA"])
+ assert (home / "Desktop" / "Free Claude Code.lnk").is_file()
+ assert (
+ app_data
+ / "Microsoft"
+ / "Windows"
+ / "Start Menu"
+ / "Programs"
+ / "Free Claude Code.lnk"
+ ).is_file()
+
+
+def test_install_ps1_preserves_unowned_desktop_shortcut(
+ powershell_harness: PowerShellHarness,
+) -> None:
+ desktop_shortcut = (
+ Path(powershell_harness.env["USERPROFILE"]) / "Desktop" / "Free Claude Code.lnk"
+ )
+ unrelated_target = powershell_harness.root / "unrelated.cmd"
+ unrelated_target.write_text("@echo off\n", encoding="utf-8")
+ _create_windows_shortcut(
+ powershell_harness.powershell,
+ desktop_shortcut,
+ unrelated_target,
+ )
+ original_shortcut = desktop_shortcut.read_bytes()
+
+ result = powershell_harness.run()
+
+ assert result.returncode == 0, result.stderr
+ assert "not managed by Free Claude Code" in result.stdout
+ assert desktop_shortcut.read_bytes() == original_shortcut
@pytest.mark.parametrize("uv_version", ("0.11.16", "0.11.16+build.1"))
diff --git a/tests/scripts/test_uninstallers.py b/tests/scripts/test_uninstallers.py
index 33f333af..48fe0df7 100644
--- a/tests/scripts/test_uninstallers.py
+++ b/tests/scripts/test_uninstallers.py
@@ -7,6 +7,7 @@ from pathlib import Path
import pytest
FCC_COMMANDS = (
+ "fcc-desktop",
"fcc-server",
"fcc-claude",
"fcc-codex",
@@ -31,6 +32,35 @@ def _powershells() -> tuple[str, ...]:
return tuple(dict.fromkeys(path for path in candidates if path is not None))
+def _create_windows_shortcut(
+ powershell: str,
+ shortcut_path: Path,
+ target_path: Path,
+) -> None:
+ shortcut_path.parent.mkdir(parents=True, exist_ok=True)
+ env = os.environ | {
+ "FCC_TEST_SHORTCUT": str(shortcut_path),
+ "FCC_TEST_TARGET": str(target_path),
+ }
+ subprocess.run(
+ [
+ powershell,
+ "-NoProfile",
+ "-Command",
+ (
+ "$shell = New-Object -ComObject WScript.Shell; "
+ "$shortcut = $shell.CreateShortcut($env:FCC_TEST_SHORTCUT); "
+ "$shortcut.TargetPath = $env:FCC_TEST_TARGET; "
+ "$shortcut.Save()"
+ ),
+ ],
+ check=True,
+ capture_output=True,
+ text=True,
+ env=env,
+ )
+
+
@dataclass
class PosixUninstallHarness:
home: Path
@@ -123,7 +153,7 @@ if [ "${1:-}" = "tool" ] && [ "${2:-}" = "uninstall" ]; then
echo 'Tool `free-claude-code` is not installed' >&2
exit 2
fi
- for name in fcc-server fcc-claude fcc-codex fcc-pi fcc-init free-claude-code; do
+ for name in fcc-desktop fcc-server fcc-claude fcc-codex fcc-pi fcc-init free-claude-code; do
/bin/rm -f "$FAKE_TOOL_BIN/$name"
done
echo "Uninstalled free-claude-code"
@@ -136,13 +166,30 @@ exit 43
bin_dir / "rm",
"""#!/bin/sh
echo "rm:$*" >> "$CALL_LOG"
-if [ "$FAIL_STEP" = "purge" ]; then
+if [ "$FAIL_STEP" = "purge" ] && [ "$*" = "-rf $HOME/.fcc" ]; then
echo "simulated purge failure" >&2
exit 44
fi
exec /bin/rm "$@"
""",
)
+ _write_executable(
+ bin_dir / "uname",
+ """#!/bin/sh
+printf '%s\n' "$FAKE_UNAME"
+""",
+ )
+
+ app = home / "Applications" / "Free Claude Code.app"
+ contents = app / "Contents"
+ contents.mkdir(parents=True)
+ (contents / ".free-claude-code-owner").write_text(
+ "io.github.alishahryar1.free-claude-code\n",
+ encoding="utf-8",
+ )
+ desktop = home / "Desktop"
+ desktop.mkdir()
+ (desktop / "Free Claude Code.app").symlink_to(app, target_is_directory=True)
env = os.environ.copy()
env.update(
@@ -151,6 +198,7 @@ exec /bin/rm "$@"
"PATH": f"{bin_dir}:/usr/bin:/bin",
"CALL_LOG": str(log),
"FAKE_TOOL_BIN": str(tool_bin),
+ "FAKE_UNAME": "Darwin",
"FAIL_STEP": "",
}
)
@@ -176,6 +224,8 @@ def test_uninstall_sh_removes_and_verifies_only_fcc(
assert posix_uninstall_harness.calls() == [
"uv:tool dir --bin",
"uv:tool uninstall free-claude-code",
+ f"rm:-f {posix_uninstall_harness.home / 'Desktop' / 'Free Claude Code.app'}",
+ f"rm:-rf {posix_uninstall_harness.home / 'Applications' / 'Free Claude Code.app'}",
f"rm:-rf {posix_uninstall_harness.fcc_home}",
]
@@ -192,6 +242,54 @@ def test_uninstall_sh_is_idempotent_when_tool_is_already_absent(
assert "already absent" in result.stdout
+def test_uninstall_sh_preserves_unrelated_macos_desktop_link(
+ posix_uninstall_harness: PosixUninstallHarness,
+) -> None:
+ desktop_link = posix_uninstall_harness.home / "Desktop" / "Free Claude Code.app"
+ desktop_link.unlink()
+ unrelated = posix_uninstall_harness.home / "Unrelated.app"
+ unrelated.mkdir()
+ desktop_link.symlink_to(unrelated, target_is_directory=True)
+
+ result = posix_uninstall_harness.run()
+
+ assert result.returncode == 0, result.stderr
+ assert "non-FCC link" in result.stdout
+ assert desktop_link.readlink() == unrelated
+
+
+def test_uninstall_sh_preserves_unowned_macos_app_bundle(
+ posix_uninstall_harness: PosixUninstallHarness,
+) -> None:
+ app = posix_uninstall_harness.home / "Applications" / "Free Claude Code.app"
+ owner_file = app / "Contents" / ".free-claude-code-owner"
+ owner_file.unlink()
+ sentinel = app / "foreign.txt"
+ sentinel.write_text("keep", encoding="utf-8")
+ desktop_link = posix_uninstall_harness.home / "Desktop" / "Free Claude Code.app"
+
+ result = posix_uninstall_harness.run()
+
+ assert result.returncode == 0, result.stderr
+ assert "not managed by Free Claude Code" in result.stdout
+ assert sentinel.read_text(encoding="utf-8") == "keep"
+ assert desktop_link.is_symlink()
+
+
+def test_uninstall_sh_does_not_touch_macos_paths_on_linux(
+ posix_uninstall_harness: PosixUninstallHarness,
+) -> None:
+ posix_uninstall_harness.env["FAKE_UNAME"] = "Linux"
+ app = posix_uninstall_harness.home / "Applications" / "Free Claude Code.app"
+ desktop_link = posix_uninstall_harness.home / "Desktop" / "Free Claude Code.app"
+
+ result = posix_uninstall_harness.run()
+
+ assert result.returncode == 0, result.stderr
+ assert app.is_dir()
+ assert desktop_link.is_symlink()
+
+
@pytest.mark.parametrize("failure", ["tool-dir", "uninstall", "stale-entrypoint"])
def test_uninstall_sh_preserves_config_when_tool_removal_is_unconfirmed(
posix_uninstall_harness: PosixUninstallHarness,
@@ -341,8 +439,9 @@ def powershell_uninstall_harness(
bin_dir = home / ".local" / "bin"
tool_bin = tmp_path / "tool-bin"
fcc_home = home / ".fcc"
+ app_data = tmp_path / "app-data"
log = tmp_path / "calls.log"
- for path in (bin_dir, tool_bin, fcc_home):
+ for path in (bin_dir, tool_bin, fcc_home, app_data):
path.mkdir(parents=True)
(fcc_home / "config.json").write_text("{}", encoding="utf-8")
for name in FCC_COMMANDS:
@@ -386,7 +485,10 @@ function Remove-Item {
[switch] $Force
)
Add-Content -LiteralPath $env:CALL_LOG -Value "remove:$LiteralPath"
- if ($env:FAIL_STEP -eq "purge") {
+ if (
+ $env:FAIL_STEP -eq "purge" -and
+ $LiteralPath -eq (Join-Path $env:USERPROFILE ".fcc")
+ ) {
throw "simulated purge failure"
}
Microsoft.PowerShell.Management\Remove-Item @PSBoundParameters
@@ -402,6 +504,22 @@ else {
encoding="utf-8",
)
+ desktop_shortcut = home / "Desktop" / "Free Claude Code.lnk"
+ start_shortcut = (
+ app_data
+ / "Microsoft"
+ / "Windows"
+ / "Start Menu"
+ / "Programs"
+ / "Free Claude Code.lnk"
+ )
+ for shortcut in (desktop_shortcut, start_shortcut):
+ _create_windows_shortcut(
+ powershell,
+ shortcut,
+ tool_bin / "fcc-desktop.cmd",
+ )
+
system_root = os.environ["SYSTEMROOT"]
env = os.environ.copy()
env.update(
@@ -412,6 +530,7 @@ else {
"PATHEXT": ".COM;.EXE;.BAT;.CMD",
"HOME": str(home),
"USERPROFILE": str(home),
+ "APPDATA": str(app_data),
"CALL_LOG": str(log),
"FAKE_TOOL_BIN": str(tool_bin),
"FCC_UNINSTALLER": str(_repo_root() / "scripts" / "uninstall.ps1"),
@@ -443,10 +562,36 @@ def test_uninstall_ps1_removes_and_verifies_only_fcc(
assert powershell_uninstall_harness.calls() == [
"uv:tool dir --bin",
"uv:tool uninstall free-claude-code",
+ f"remove:{Path(powershell_uninstall_harness.env['USERPROFILE']) / 'Desktop' / 'Free Claude Code.lnk'}",
+ f"remove:{Path(powershell_uninstall_harness.env['APPDATA']) / 'Microsoft' / 'Windows' / 'Start Menu' / 'Programs' / 'Free Claude Code.lnk'}",
f"remove:{powershell_uninstall_harness.fcc_home}",
]
+def test_uninstall_ps1_preserves_unowned_desktop_shortcut(
+ powershell_uninstall_harness: PowerShellUninstallHarness,
+) -> None:
+ desktop_shortcut = (
+ Path(powershell_uninstall_harness.env["USERPROFILE"])
+ / "Desktop"
+ / "Free Claude Code.lnk"
+ )
+ unrelated_target = powershell_uninstall_harness.home / "unrelated.cmd"
+ unrelated_target.write_text("@echo off\n", encoding="utf-8")
+ _create_windows_shortcut(
+ powershell_uninstall_harness.powershell,
+ desktop_shortcut,
+ unrelated_target,
+ )
+ original_shortcut = desktop_shortcut.read_bytes()
+
+ result = powershell_uninstall_harness.run()
+
+ assert result.returncode == 0, result.stderr
+ assert "not managed by Free Claude Code" in result.stdout
+ assert desktop_shortcut.read_bytes() == original_shortcut
+
+
def test_uninstall_ps1_is_idempotent_when_tool_is_already_absent(
powershell_uninstall_harness: PowerShellUninstallHarness,
) -> None:
diff --git a/uv.lock b/uv.lock
index f79541f5..f3e6ecc4 100644
--- a/uv.lock
+++ b/uv.lock
@@ -620,7 +620,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.11.7"
+version = "4.12.0"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },
@@ -632,8 +632,10 @@ dependencies = [
{ name = "loguru" },
{ name = "markdown-it-py" },
{ name = "openai" },
+ { name = "pillow", marker = "sys_platform == 'darwin' or sys_platform == 'win32'" },
{ name = "pydantic" },
{ name = "pydantic-settings" },
+ { name = "pystray", marker = "sys_platform == 'darwin' or sys_platform == 'win32'" },
{ name = "python-dotenv" },
{ name = "python-telegram-bot" },
{ name = "requests", extra = ["socks"] },
@@ -680,8 +682,10 @@ requires-dist = [
{ name = "markdown-it-py", specifier = ">=4.2.0" },
{ name = "nvidia-riva-client", marker = "extra == 'voice'", specifier = ">=2.26.0" },
{ name = "openai", specifier = ">=2.46.0" },
+ { name = "pillow", marker = "sys_platform == 'darwin' or sys_platform == 'win32'", specifier = ">=12.0.0" },
{ name = "pydantic", specifier = ">=2.13.4" },
{ name = "pydantic-settings", specifier = ">=2.14.2" },
+ { name = "pystray", marker = "sys_platform == 'darwin' or sys_platform == 'win32'", specifier = ">=0.19.5" },
{ name = "python-dotenv", specifier = ">=1.2.2" },
{ name = "python-telegram-bot", specifier = ">=22.8" },
{ name = "requests", extras = ["socks"], specifier = ">=2.32.0" },
@@ -1464,6 +1468,40 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/b7/b9/c538f279a4e237a006a2c98387d081e9eb060d203d8ed34467cc0f0b9b53/packaging-26.0-py3-none-any.whl", hash = "sha256:b36f1fef9334a5588b4166f8bcd26a14e521f2b55e6b9de3aaa80d3ff7a37529", size = 74366, upload-time = "2026-01-21T20:50:37.788Z" },
]
+[[package]]
+name = "pillow"
+version = "12.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/1c/3d/bb7fca845737cf9d7dbde16ed1843984665ff2e0a518f5db43e77ec540b9/pillow-12.3.0.tar.gz", hash = "sha256:3b8182a766685eaa002637e28b4ec8d6b18819a0c71f579bf0dbaa5830297cce", size = 47025035, upload-time = "2026-07-01T11:56:38.965Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/dc/01/001f65b68192f0228cc1dbbc8d2530ab5d58b61037ba0587f946fea607cd/pillow-12.3.0-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:9cf95fe4d0f84c82d282745d9bb08ad9f926efa00be4697e767b814ce40d4330", size = 4161736, upload-time = "2026-07-01T11:54:51.156Z" },
+ { url = "https://files.pythonhosted.org/packages/1a/d2/0219746d0fd16fc8a84498e79452375be3797d3ce4044596ce565164b84f/pillow-12.3.0-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:8728f216dcdb6e6d555cf971cb34076139ad74b31fc2c14da4fafc741c5f6217", size = 4255435, upload-time = "2026-07-01T11:54:53.414Z" },
+ { url = "https://files.pythonhosted.org/packages/c8/02/8d0bc62ef0302318c46ff2a512822d2610e81c7aa46c9b3abe6cbaca5ad0/pillow-12.3.0-cp314-cp314-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:a45650e8ce7fafffd731db8550230db6b0d306d181a90b67d3e6bca2f1990930", size = 3696262, upload-time = "2026-07-01T11:54:55.739Z" },
+ { url = "https://files.pythonhosted.org/packages/85/e2/73c77d218410b14f5f2d565e8a998d5317b7b9c75368d29985139f7a46f0/pillow-12.3.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:ba54cfebe86920a559a7c4d6b9050791c20513650a1952ebe3368c7dc70306f8", size = 5350344, upload-time = "2026-07-01T11:54:57.657Z" },
+ { url = "https://files.pythonhosted.org/packages/c7/da/32c752228ae345f489e3a42499d817b6c3996da7e8a3bc7a04fc806b243b/pillow-12.3.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:e158cb00350dc278f3b91551101aa7d12415a66ebf2c91d8d5ac14e56ddd3ad0", size = 4780131, upload-time = "2026-07-01T11:54:59.713Z" },
+ { url = "https://files.pythonhosted.org/packages/a3/34/77f3f793fed8efc7d243f21b33c5a3f0d1c97ee70346d3db855587e155ff/pillow-12.3.0-cp314-cp314-win32.whl", hash = "sha256:af8d94b0db561cf68b88a267c5c44b49e134f525d0dc2cb7ed413a66bc23559a", size = 6467209, upload-time = "2026-07-01T11:55:10.408Z" },
+ { url = "https://files.pythonhosted.org/packages/f1/e0/492879f69d94f91f60fc8cd05ba03650e9520afebb2fb7aa12777d7c7f38/pillow-12.3.0-cp314-cp314-win_amd64.whl", hash = "sha256:fdafc9cce40277e0f7a0feabce0ee50dd2fa1800f3b38015e51296b5e814048d", size = 7237707, upload-time = "2026-07-01T11:55:12.745Z" },
+ { url = "https://files.pythonhosted.org/packages/c9/ac/6b11f2875f1c2ac040d84e1bbf9cf22a88038f901ca1037898b280b38365/pillow-12.3.0-cp314-cp314-win_arm64.whl", hash = "sha256:e91206ee562682b51b98ef4b26a6ef48fd84e15fd4c4bc5ec768eb641d206838", size = 2565995, upload-time = "2026-07-01T11:55:14.736Z" },
+ { url = "https://files.pythonhosted.org/packages/52/69/c2208e56af9bfc1913afb24020297a691eb1d4ef688474c8a04913f65e04/pillow-12.3.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:164b31cd1a0490ab6efae01aa5df49da7061be0af1b30e035b6e9a1bfe34ee6e", size = 5352503, upload-time = "2026-07-01T11:55:17.076Z" },
+ { url = "https://files.pythonhosted.org/packages/07/70/e5686d753e898a45d778ff1718dba8516ead6ab6b95d85fc8c4b70650cf2/pillow-12.3.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:5afb51d599ea772b8365ae807ae557f18bccfe46ab261fd1c2a9ed700fc6eb17", size = 4782956, upload-time = "2026-07-01T11:55:19.448Z" },
+ { url = "https://files.pythonhosted.org/packages/23/26/fcb2f6e37175b04f53570b59937867e2b80ee1685e744023153028fc14f9/pillow-12.3.0-cp314-cp314t-win32.whl", hash = "sha256:4b0a7fe987b14c31ebda6083f74f22b561fd3739bc0ac51e019622e3d72668c7", size = 6474125, upload-time = "2026-07-01T11:55:30.956Z" },
+ { url = "https://files.pythonhosted.org/packages/90/de/3634abee5f1c9e13c56787b7d5517b0ba8d6de51700b95578cf338349c9f/pillow-12.3.0-cp314-cp314t-win_amd64.whl", hash = "sha256:962864dc93511324d51ddbb5b9f8731bf71675b93ca612a07441896f4688fb8c", size = 7242939, upload-time = "2026-07-01T11:55:34.044Z" },
+ { url = "https://files.pythonhosted.org/packages/ce/2a/fd13f8eb24de5714a6eb444a3d67e2842c6c576e159a43793adf23051351/pillow-12.3.0-cp314-cp314t-win_arm64.whl", hash = "sha256:0740a512dc522224c77d9aa5a8d70d8b7d73fb91f2c21125d8d025d3b8990e45", size = 2567506, upload-time = "2026-07-01T11:55:35.988Z" },
+ { url = "https://files.pythonhosted.org/packages/5d/dc/8fdce34ec725a33c81c6ba122b904d6b9024e50ea9ac7bede62fab54506c/pillow-12.3.0-cp315-cp315-ios_13_0_arm64_iphoneos.whl", hash = "sha256:0feb2e9d6ad6c9e3c06effe9d00f3f1e618a6643273576b016f591e9315a7139", size = 4162063, upload-time = "2026-07-01T11:55:37.941Z" },
+ { url = "https://files.pythonhosted.org/packages/76/66/2044b9a63d3b84ff048228dfcb7cd9bf0df983e8470971bf7d4c57b693de/pillow-12.3.0-cp315-cp315-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:9e881fca225083806662a5c43d627d215f258ff43c890f831966c7d7ba9c7402", size = 4255549, upload-time = "2026-07-01T11:55:40.022Z" },
+ { url = "https://files.pythonhosted.org/packages/52/7e/1f67e6f4ece6b582ee4b539decbcc9f848dc245a93ed8cd7338bafef72f1/pillow-12.3.0-cp315-cp315-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:4998562bf62a445225f22e07c896bb04b35b1b1f2eb6d760584c9c51d7a5f78c", size = 3696331, upload-time = "2026-07-01T11:55:41.98Z" },
+ { url = "https://files.pythonhosted.org/packages/12/40/d306fc2c8e4d45d7f175c77edca7063be7b86fe7fe6e68f4353bf71d808c/pillow-12.3.0-cp315-cp315-macosx_10_15_x86_64.whl", hash = "sha256:dc624f6bc473dacdf7ef7eb8678d0d08edf15cd94fad6ae5c7d6cc67a4e4902f", size = 5350370, upload-time = "2026-07-01T11:55:44.028Z" },
+ { url = "https://files.pythonhosted.org/packages/dd/44/668fb1437e8ce420f62d6106eb66e44a5971602a4d794615bdf79315d82d/pillow-12.3.0-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:71d6097b330eea8fd15097780c8e89cb1a8ce7838669f48c5bacd6f663dd4701", size = 4780147, upload-time = "2026-07-01T11:55:46.073Z" },
+ { url = "https://files.pythonhosted.org/packages/54/76/a09cc3ccc8d773a7283d34c38bec1708f9e3cc932093cbc4c5e71ac4060b/pillow-12.3.0-cp315-cp315-win32.whl", hash = "sha256:57b3d78c95ba9059768b10e28b813002261d3f3dfc55cc48b0c988f625175827", size = 6467375, upload-time = "2026-07-01T11:55:57.769Z" },
+ { url = "https://files.pythonhosted.org/packages/3e/03/1846c49ba3b1d5550392a4bbd06d6fb4578e1cd91a803198b5c90f5f7d53/pillow-12.3.0-cp315-cp315-win_amd64.whl", hash = "sha256:fa4ecea169a355be7a3ade2c783e2ed12f0e40d2c5621cda8b3297faf7fbb9f5", size = 7237048, upload-time = "2026-07-01T11:55:59.975Z" },
+ { url = "https://files.pythonhosted.org/packages/fb/bb/89f35dcc79610423f9f195504d7def7f0d1416a711541b42867e25fe3412/pillow-12.3.0-cp315-cp315-win_arm64.whl", hash = "sha256:877c3f311ff35410f690861c4409e7ccbf0cd2f878e50628a28e5a0bb689e658", size = 2566006, upload-time = "2026-07-01T11:56:02.143Z" },
+ { url = "https://files.pythonhosted.org/packages/30/88/707027ba09942dfa2c28759b5c222d769290a41c6d20ea60ec250801941f/pillow-12.3.0-cp315-cp315t-macosx_10_15_x86_64.whl", hash = "sha256:e9871b1ffbfa9656b60aeee92ed5136a5742696006fa322b29ea3d8da0ecc9cf", size = 5352509, upload-time = "2026-07-01T11:56:04.2Z" },
+ { url = "https://files.pythonhosted.org/packages/b0/6d/00352fa25332c2569cd387851f568cc5a4b75a9adbfb37ac4fbce4c02eec/pillow-12.3.0-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:53aa02d20d10c3d814d536aa4e5ac9b84ca0ff5a88377963b085ad6822f93e64", size = 4783167, upload-time = "2026-07-01T11:56:06.631Z" },
+ { url = "https://files.pythonhosted.org/packages/18/f0/a5595c1e8c3ae44b9828cb2f0fa8155e5095ef04d6327b8f61cf44a3df85/pillow-12.3.0-cp315-cp315t-win32.whl", hash = "sha256:1657923d2d45afb66526e5b933e5b3052e6bdea196c90d3abb2424e18c77dae8", size = 6474384, upload-time = "2026-07-01T11:56:18.855Z" },
+ { url = "https://files.pythonhosted.org/packages/e4/04/62bcd9f844984c5938d3b05264a61d797a29d3e0812341a8204af70bbdee/pillow-12.3.0-cp315-cp315t-win_amd64.whl", hash = "sha256:8cd2f7bdda092d99c9fc2fb7391354f306d01443d22785d0cbfafa2e2c8bb418", size = 7243537, upload-time = "2026-07-01T11:56:21.214Z" },
+ { url = "https://files.pythonhosted.org/packages/3d/68/1f3066acedf37673694a7141381d8f811ae97f30d34413d236abe7d489f1/pillow-12.3.0-cp315-cp315t-win_arm64.whl", hash = "sha256:06ff022112bc9cbf83b60f8e028d94ad87b60621706487e65f673de61610ab59", size = 2567491, upload-time = "2026-07-01T11:56:23.506Z" },
+]
+
[[package]]
name = "platformdirs"
version = "4.9.2"
@@ -1699,6 +1737,49 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" },
]
+[[package]]
+name = "pyobjc-core"
+version = "12.2.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b4/b1/729f7458a63758bd21716648a8abcd9a0c8f2d2e9897763c8a1a1c7fd31b/pyobjc_core-12.2.1.tar.gz", hash = "sha256:7a7b9b018402342cf32bf1956366896350fbe5c0478cb3ef59778f77abed7f07", size = 1063383, upload-time = "2026-06-19T16:19:39.357Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/bd/8a/cfa4f56939d554dbb342ec6e5226a441e2f552bc2002a0ddf7705bb11bef/pyobjc_core-12.2.1-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:2b8fc0531c27277325e113ac00b8a72a82e6145f0a88175b9425d8de814ff69a", size = 6429289, upload-time = "2026-06-19T16:05:02.191Z" },
+ { url = "https://files.pythonhosted.org/packages/42/74/446c89bc18103aaa4a00d1fb85ff8acace9a0dc3f362d9678ebf7571e275/pyobjc_core-12.2.1-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:9bef500f979e22d54f9da3aaebf6a48f873234b324858bd69256055a318955c7", size = 6690181, upload-time = "2026-06-19T16:05:06.201Z" },
+ { url = "https://files.pythonhosted.org/packages/99/c7/0121ee4c616af07ad2de8cd1a286f6978dc9a227eb58b7c2e875cb68a1df/pyobjc_core-12.2.1-cp315-cp315-macosx_10_15_universal2.whl", hash = "sha256:047c226eeb58a2993ace5e8904e71cc9426ee20d064c617f8fbf32717d37093e", size = 6487078, upload-time = "2026-06-19T16:05:10.093Z" },
+ { url = "https://files.pythonhosted.org/packages/b5/a8/cb9fcc150f97d0bf22a2028f88b24cc35949beb1bcc7b8bc5c17d4401677/pyobjc_core-12.2.1-cp315-cp315t-macosx_10_15_universal2.whl", hash = "sha256:1188613805336270279570467e4455b74cb6c0f60913ac74c917ee1c37cfaecb", size = 6733064, upload-time = "2026-06-19T16:05:14.313Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-cocoa"
+version = "12.2.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/51/34/fbe38a204643aa4e1b91391cdce07a34da565a69171ebcad08de7438a556/pyobjc_framework_cocoa-12.2.1.tar.gz", hash = "sha256:b94b37fe5730e5ae1fb0052912cd174e6ec329b0bfba4a012ae5db1014b5864b", size = 3125751, upload-time = "2026-06-19T16:20:05.159Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ec/c8/b90baa8f3592eded79b4be98fb59d2b8dc16b62361e34292bd95806ebd9f/pyobjc_framework_cocoa-12.2.1-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:b386c324d64ae565c1f6b7dfb77be68f640a1c7c23caa6966ab661131f519561", size = 388357, upload-time = "2026-06-19T16:07:43.364Z" },
+ { url = "https://files.pythonhosted.org/packages/98/d8/64a94651b9294702d55e748d94de30e25bc59d0784526be7643f4467eccd/pyobjc_framework_cocoa-12.2.1-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:a6c584e2af0813cb2f6103b184e632665a26f58c1bd5b08ffd6e95a19c617f7b", size = 392404, upload-time = "2026-06-19T16:07:44.955Z" },
+ { url = "https://files.pythonhosted.org/packages/5c/cc/26e8a7bf1f5e8caa38b7f80d486296f9fd3c97e71ad7e5444ef22e802758/pyobjc_framework_cocoa-12.2.1-cp315-cp315-macosx_10_15_universal2.whl", hash = "sha256:b6023657b8d6cc049a21bd6b4752425f2f53c42f9f0b02d64c7608cc484bf103", size = 388589, upload-time = "2026-06-19T16:07:46.276Z" },
+ { url = "https://files.pythonhosted.org/packages/b6/f3/eedf743a303ea742b8e082afe3613fb4d6618bc1a48cf2568b004ce906f7/pyobjc_framework_cocoa-12.2.1-cp315-cp315t-macosx_10_15_universal2.whl", hash = "sha256:c685ccd8e266a07cf912a2c5a13b1f2eff2a868a1aff163b4801b4687bd425e1", size = 392691, upload-time = "2026-06-19T16:07:47.477Z" },
+]
+
+[[package]]
+name = "pyobjc-framework-quartz"
+version = "12.2.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pyobjc-core" },
+ { name = "pyobjc-framework-cocoa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3b/f6/2a8b84dbf1fe7c04dd96ea73d991678d4e09a909f51971ecc51629bb2ab4/pyobjc_framework_quartz-12.2.1.tar.gz", hash = "sha256:b3b8b6f71e66147f8ff9e6213864cc8527e3a0b1ee90835b93ce221f4802d9b0", size = 3215521, upload-time = "2026-06-19T16:21:30.199Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/8b/5d/85ffd9d433989205d572a50d625c63b29c05e0c5235a725f15ae1023672c/pyobjc_framework_quartz-12.2.1-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:ceb56939c337b36d9d81185ade31f77dc52c85cf79bb16e53e9b32f54b6bb3f5", size = 219769, upload-time = "2026-06-19T16:16:08.814Z" },
+ { url = "https://files.pythonhosted.org/packages/e2/d6/b917e4b63d72ea84a27121076f3033f23f6497c0e6ce8d304766c899897f/pyobjc_framework_quartz-12.2.1-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:8105c98b798f2bf81c05c54bddeeadbf62f0b5dfec13bd6e719dd2cdf7e1cddf", size = 224717, upload-time = "2026-06-19T16:16:10.215Z" },
+ { url = "https://files.pythonhosted.org/packages/04/e2/f3c1ed3228f7430ef5ade23db6f1fcbae99290f177ce5653348fd9e05f4d/pyobjc_framework_quartz-12.2.1-cp315-cp315-macosx_10_15_universal2.whl", hash = "sha256:bbc214f1a216b5d3651bc832d0ac4589f029f3f37cd6cbb370aac12a7c77942c", size = 219825, upload-time = "2026-06-19T16:16:11.433Z" },
+ { url = "https://files.pythonhosted.org/packages/66/2a/2c99a5ad2fe0a11600ea123b8e9a08ff138fcb2ad1e13e376f4bd4aa1d96/pyobjc_framework_quartz-12.2.1-cp315-cp315t-macosx_10_15_universal2.whl", hash = "sha256:ca61624a0b0e6286d8a0f97f47eb9011e4e81e9a339db436d48af527e7065bb1", size = 224770, upload-time = "2026-06-19T16:16:13.035Z" },
+]
+
[[package]]
name = "pysocks"
version = "1.7.1"
@@ -1708,6 +1789,19 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/8d/59/b4572118e098ac8e46e399a1dd0f2d85403ce8bbaad9ec79373ed6badaf9/PySocks-1.7.1-py3-none-any.whl", hash = "sha256:2725bd0a9925919b9b51739eea5f9e2bae91e83288108a9ad338b2e3a4435ee5", size = 16725, upload-time = "2019-09-20T02:06:22.938Z" },
]
+[[package]]
+name = "pystray"
+version = "0.19.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pillow" },
+ { name = "pyobjc-framework-quartz", marker = "sys_platform != 'win32'" },
+ { name = "six" },
+]
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/5c/64/927a4b9024196a4799eba0180e0ca31568426f258a4a5c90f87a97f51d28/pystray-0.19.5-py2.py3-none-any.whl", hash = "sha256:a0c2229d02cf87207297c22d86ffc57c86c227517b038c0d3c59df79295ac617", size = 49068, upload-time = "2023-09-17T13:44:26.872Z" },
+]
+
[[package]]
name = "pytest"
version = "9.1.1"
@@ -2161,6 +2255,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" },
]
+[[package]]
+name = "six"
+version = "1.17.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/94/e7/b2c673351809dca68a0e064b6af791aa332cf192da575fd474ed7d6f16a2/six-1.17.0.tar.gz", hash = "sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81", size = 34031, upload-time = "2024-12-04T17:35:28.174Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" },
+]
+
[[package]]
name = "sniffio"
version = "1.3.1"