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 Free Claude Code app icon (#1252)
Ali Khokhar7a3d15826251
diff --git a/pyproject.toml b/pyproject.tomlindex 369a15b9..f2cfcf08 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "4.12.4"+version = "4.12.5"description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"readme = "README.md"requires-python = ">=3.14.0"diff --git a/scripts/install.ps1 b/scripts/install.ps1index 78a20624..3bec19f0 100644--- a/scripts/install.ps1+++ b/scripts/install.ps1@@ -518,12 +518,19 @@ function Install-FreeClaudeCode {}function Configure-AndConfirmFreeClaudeCode {+ $iconPath = Join-Path $env:USERPROFILE ".fcc\app-icon.ico"if ($DryRun) {Write-Host "+ uv tool update-shell"Write-Host "+ uv tool dir --bin"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"+ Invoke-NativeCommand -FilePath "<uv-tool-bin>\fcc-desktop.exe" -Arguments @(+ "--export-icon",+ $iconPath+ )+ Install-FccDesktopShortcuts `+ -DesktopCommand "<uv-tool-bin>\fcc-desktop.exe" `+ -IconPath $iconPathreturn}@@ -559,7 +566,16 @@ function Configure-AndConfirmFreeClaudeCode {}Invoke-NativeCommand -FilePath $installedCommands["fcc-server"] -Arguments @("--version")- Install-FccDesktopShortcuts -DesktopCommand $installedCommands["fcc-desktop"]+ Invoke-NativeCommand -FilePath $installedCommands["fcc-desktop"] -Arguments @(+ "--export-icon",+ $iconPath+ )+ if (-not (Test-Path -LiteralPath $iconPath -PathType Leaf)) {+ throw "Free Claude Code did not export its Windows app icon to '$iconPath'."+ }+ Install-FccDesktopShortcuts `+ -DesktopCommand $installedCommands["fcc-desktop"] `+ -IconPath $iconPath}function Test-EquivalentPath {@@ -584,7 +600,10 @@ function Test-EquivalentPath {}function Install-FccDesktopShortcuts {- param([string] $DesktopCommand)+ param(+ [string] $DesktopCommand,+ [string] $IconPath+ )$shortcutPaths = @((Join-Path $env:USERPROFILE "Desktop\Free Claude Code.lnk"),@@ -617,7 +636,7 @@ function Install-FccDesktopShortcuts {$shortcut = $shell.CreateShortcut($shortcutPath)$shortcut.TargetPath = $DesktopCommand$shortcut.WorkingDirectory = $env:USERPROFILE- $shortcut.IconLocation = "$DesktopCommand,0"+ $shortcut.IconLocation = "$IconPath,0"$shortcut.Description = "Run Free Claude Code in the background"$shortcut.Save()}diff --git a/scripts/install.sh b/scripts/install.shindex ce2495a7..0596ef7d 100644--- a/scripts/install.sh+++ b/scripts/install.sh@@ -557,6 +557,8 @@ install_macos_desktop_app() {owner_file="$contents_dir/$FCC_MACOS_OWNER_FILE"executable_dir="$contents_dir/MacOS"executable_path="$executable_dir/fcc-desktop"+ resources_dir="$contents_dir/Resources"+ icon_path="$resources_dir/AppIcon.icns"desktop_dir="$HOME/Desktop"desktop_link="$desktop_dir/Free Claude Code.app"@@ -566,13 +568,16 @@ install_macos_desktop_app() {fiif [ "$dry_run" -eq 1 ]; then- print_command mkdir -p "$executable_dir" "$desktop_dir"+ print_command mkdir -p "$executable_dir" "$resources_dir" "$desktop_dir"+ print_command fcc-desktop --export-icon "$icon_path"printf '+ write %s, %s, and %s\n' "$owner_file" "$contents_dir/Info.plist" "$executable_path"print_command ln -s "$app_dir" "$desktop_link"return 0fi- mkdir -p "$executable_dir" "$desktop_dir"+ mkdir -p "$executable_dir" "$resources_dir" "$desktop_dir"+ run "$tool_bin/fcc-desktop" --export-icon "$icon_path"+ [ -f "$icon_path" ] || fail "Free Claude Code did not export its macOS app icon to $icon_path."printf '%s\n' "$FCC_MACOS_BUNDLE_ID" > "$owner_file"cat > "$contents_dir/Info.plist" <<'PLIST'<?xml version="1.0" encoding="UTF-8"?>@@ -585,6 +590,8 @@ install_macos_desktop_app() {<string>fcc-desktop</string><key>CFBundleIdentifier</key><string>io.github.alishahryar1.free-claude-code</string>+ <key>CFBundleIconFile</key>+ <string>AppIcon</string><key>CFBundleName</key><string>Free Claude Code</string><key>CFBundlePackageType</key>diff --git a/src/free_claude_code/assets/app-icon.icns b/src/free_claude_code/assets/app-icon.icnsnew file mode 100644index 00000000..0f6f0332Binary files /dev/null and b/src/free_claude_code/assets/app-icon.icns differdiff --git a/src/free_claude_code/assets/app-icon.ico b/src/free_claude_code/assets/app-icon.iconew file mode 100644index 00000000..bcc6175cBinary files /dev/null and b/src/free_claude_code/assets/app-icon.ico differdiff --git a/src/free_claude_code/assets/app-icon.png b/src/free_claude_code/assets/app-icon.pngnew file mode 100644index 00000000..0cfc7576Binary files /dev/null and b/src/free_claude_code/assets/app-icon.png differdiff --git a/src/free_claude_code/assets/app-icon.svg b/src/free_claude_code/assets/app-icon.svgnew file mode 100644index 00000000..27168a87--- /dev/null+++ b/src/free_claude_code/assets/app-icon.svg@@ -0,0 +1,15 @@+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024">+ <rect x="32" y="32" width="960" height="960" rx="216" fill="#080b12"/>+ <g fill="none" stroke="#f97316" stroke-linecap="round" stroke-linejoin="round" stroke-width="56">+ <path d="M220 300h170c24 0 38 9 52 28l130 162c12 15 22 22 46 22h48"/>+ <path d="M220 512h446"/>+ <path d="M220 724h170c24 0 38-9 52-28l130-162c12-15 22-22 46-22h48"/>+ </g>+ <g fill="#f97316">+ <circle cx="220" cy="300" r="62"/>+ <circle cx="220" cy="512" r="62"/>+ <circle cx="220" cy="724" r="62"/>+ </g>+ <rect x="648" y="372" width="244" height="280" rx="62" fill="#080b12" stroke="#f97316" stroke-width="56"/>+ <path d="m742 454 58 58-58 58" fill="none" stroke="#f8fafc" stroke-linecap="round" stroke-linejoin="round" stroke-width="48"/>+</svg>diff --git a/src/free_claude_code/cli/desktop_assets.py b/src/free_claude_code/cli/desktop_assets.pynew file mode 100644index 00000000..192be7d2--- /dev/null+++ b/src/free_claude_code/cli/desktop_assets.py@@ -0,0 +1,31 @@+"""Packaged visual assets owned by the FCC desktop shell."""++from importlib.resources import files+from pathlib import Path++_ICON_FILES = {+ ".icns": "app-icon.icns",+ ".ico": "app-icon.ico",+ ".png": "app-icon.png",+}+++def app_icon_bytes(suffix: str) -> bytes:+ """Read the packaged app icon matching a native file suffix."""++ normalized_suffix = suffix.lower()+ try:+ filename = _ICON_FILES[normalized_suffix]+ except KeyError as exc:+ supported = ", ".join(sorted(_ICON_FILES))+ raise ValueError(+ f"Unsupported app icon format {suffix!r}; expected one of: {supported}"+ ) from exc+ return files("free_claude_code").joinpath("assets", filename).read_bytes()+++def export_app_icon(destination: Path) -> None:+ """Copy the packaged native icon to an installer-owned destination."""++ destination.parent.mkdir(parents=True, exist_ok=True)+ destination.write_bytes(app_icon_bytes(destination.suffix))diff --git a/src/free_claude_code/cli/desktop_entrypoint.py b/src/free_claude_code/cli/desktop_entrypoint.pyindex a294c4ad..16b9a1a7 100644--- a/src/free_claude_code/cli/desktop_entrypoint.py+++ b/src/free_claude_code/cli/desktop_entrypoint.py@@ -1,13 +1,26 @@-"""Lightweight platform gate for the optional FCC desktop dependencies."""+"""Lightweight entrypoint for the optional FCC desktop shell."""import sys+from collections.abc import Sequence+from pathlib import Path-if sys.platform in {"darwin", "win32"}:- from free_claude_code.cli.desktop_tray import launch-else:+from free_claude_code.cli.desktop_assets import export_app_icon- def launch() -> None:- """Reject platforms for which FCC does not install a desktop shell."""+def launch(argv: Sequence[str] | None = None) -> None:+ """Export installer assets or launch the supported native tray adapter."""++ args = tuple(sys.argv[1:] if argv is None else argv)+ if len(args) == 2 and args[0] == "--export-icon":+ export_app_icon(Path(args[1]))+ return+ if args:+ print("Usage: fcc-desktop [--export-icon PATH]", file=sys.stderr)+ raise SystemExit(2)+ if sys.platform not in {"darwin", "win32"}:print("FCC Desktop is supported on Windows and macOS.", file=sys.stderr)raise SystemExit(1)++ from free_claude_code.cli.desktop_tray import launch as launch_tray++ launch_tray()diff --git a/src/free_claude_code/cli/desktop_tray.py b/src/free_claude_code/cli/desktop_tray.pyindex c6d94be9..d76246f3 100644--- a/src/free_claude_code/cli/desktop_tray.py+++ b/src/free_claude_code/cli/desktop_tray.py@@ -1,9 +1,12 @@"""pystray adapter for the Windows tray and macOS menu bar."""-from PIL import Image, ImageDraw+from io import BytesIO++from PIL import Imagefrom pystray import Icon, Menu, MenuItemfrom free_claude_code.cli.desktop import DesktopController, launch_desktop+from free_claude_code.cli.desktop_assets import app_icon_bytesclass PystrayDesktopTray:@@ -47,16 +50,10 @@ class PystrayDesktopTray: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+ """Load the same branded artwork used by native desktop launchers."""++ with Image.open(BytesIO(app_icon_bytes(".png"))) as image:+ return image.convert("RGBA")def launch() -> None:diff --git a/tests/cli/test_desktop_assets.py b/tests/cli/test_desktop_assets.pynew file mode 100644index 00000000..8ef37e42--- /dev/null+++ b/tests/cli/test_desktop_assets.py@@ -0,0 +1,57 @@+"""Packaged desktop icon and export contracts."""++import struct+from pathlib import Path++import pytest++from free_claude_code.cli import desktop_entrypoint+from free_claude_code.cli.desktop_assets import app_icon_bytes, export_app_icon+++def test_packaged_icons_have_native_container_headers() -> None:+ png = app_icon_bytes(".png")+ ico = app_icon_bytes(".ico")+ icns = app_icon_bytes(".icns")++ assert png.startswith(b"\x89PNG\r\n\x1a\n")+ assert struct.unpack(">II", png[16:24]) == (1024, 1024)+ assert ico[:4] == b"\x00\x00\x01\x00"+ assert struct.unpack("<H", ico[4:6])[0] >= 8+ assert icns.startswith(b"icns")+ assert struct.unpack(">I", icns[4:8])[0] == len(icns)+++def test_export_app_icon_creates_parent_and_preserves_bytes(tmp_path: Path) -> None:+ destination = tmp_path / "managed" / "AppIcon.ICNS"++ export_app_icon(destination)++ assert destination.read_bytes() == app_icon_bytes(".icns")+++def test_export_app_icon_rejects_unknown_format(tmp_path: Path) -> None:+ with pytest.raises(ValueError, match="Unsupported app icon format"):+ export_app_icon(tmp_path / "app-icon.jpg")+++def test_desktop_entrypoint_exports_icon_without_launching_tray(+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ destination = tmp_path / "app-icon.ico"+ monkeypatch.setattr(desktop_entrypoint.sys, "platform", "linux")++ desktop_entrypoint.launch(["--export-icon", str(destination)])++ assert destination.read_bytes() == app_icon_bytes(".ico")+++def test_desktop_entrypoint_rejects_unknown_arguments(+ capsys: pytest.CaptureFixture[str],+) -> None:+ with pytest.raises(SystemExit) as exc_info:+ desktop_entrypoint.launch(["--unknown"])++ assert exc_info.value.code == 2+ assert "Usage: fcc-desktop" in capsys.readouterr().errdiff --git a/tests/scripts/test_installers.py b/tests/scripts/test_installers.pyindex 1bf8a134..6ceb9bac 100644--- a/tests/scripts/test_installers.py+++ b/tests/scripts/test_installers.py@@ -291,6 +291,11 @@ echo "$name:$*" >> "$CALL_LOG"if [ "$FAIL_STEP" = "fcc-verify" ]; thenexit 36fi+if [ "$name" = "fcc-desktop" ] && [ "${1:-}" = "--export-icon" ]; then+ [ "$FAIL_STEP" = "desktop-icon-export" ] && exit 37+ mkdir -p "$(dirname "$2")"+ printf 'fake icon\n' > "$2"+fiif [ "$name" = "fcc-server" ] && [ "${1:-}" = "--version" ]; thenecho "free-claude-code 3.5.18"fi@@ -362,19 +367,39 @@ def test_install_sh_creates_native_macos_app_and_desktop_link(plist = app / "Contents" / "Info.plist"owner_file = app / "Contents" / ".free-claude-code-owner"launcher = app / "Contents" / "MacOS" / "fcc-desktop"+ icon = app / "Contents" / "Resources" / "AppIcon.icns"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"- )+ plist_text = plist.read_text(encoding="utf-8")+ assert "<key>CFBundleIconFile</key>" in plist_text+ assert "<string>AppIcon</string>" in plist_text+ assert "<key>LSUIElement</key>" in plist_text+ assert "<key>LSMultipleInstancesProhibited</key>" in plist_text+ assert icon.read_bytes() == b"fake icon\n"assert launcher.stat().st_mode & 0o111expected_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+ assert any(+ call == f"fcc-desktop:--export-icon {icon}" for call in posix_harness.calls()+ )+++def test_install_sh_stops_if_macos_icon_export_fails(+ posix_harness: PosixHarness,+) -> None:+ posix_harness.env["FAKE_UNAME"] = "Darwin"++ result = posix_harness.run(fail_step="desktop-icon-export")++ assert result.returncode != 0+ assert "Command failed with exit code 37" in result.stderr+ assert not (+ posix_harness.root / "home" / "Desktop" / "Free Claude Code.app"+ ).exists()def test_install_sh_rejects_unowned_macos_app_bundle(@@ -750,6 +775,27 @@ def _create_windows_shortcut()+def _windows_shortcut_icon(powershell: str, shortcut_path: Path) -> str:+ env = os.environ | {"FCC_TEST_SHORTCUT": str(shortcut_path)}+ completed = subprocess.run(+ [+ powershell,+ "-NoProfile",+ "-Command",+ (+ "$shell = New-Object -ComObject WScript.Shell; "+ "$shortcut = $shell.CreateShortcut($env:FCC_TEST_SHORTCUT); "+ "[Console]::Out.Write($shortcut.IconLocation)"+ ),+ ],+ check=True,+ capture_output=True,+ text=True,+ env=env,+ )+ return completed.stdout++def _batch_client(name: str) -> str:help_output = ("echo --extension, -e ^<path^> Load an extension\n"@@ -892,6 +938,11 @@ def powershell_harness(for %%I in ("%~f0") do set "FCC_NAME=%%~nI"echo %FCC_NAME%:%*>>"%CALL_LOG%"if "%FAIL_STEP%"=="fcc-verify" exit /b 55+if "%FCC_NAME%"=="fcc-desktop" if "%1"=="--export-icon" if "%FAIL_STEP%"=="desktop-icon-export" exit /b 56+if "%FCC_NAME%"=="fcc-desktop" if "%1"=="--export-icon" (+ if not exist "%~dp2" mkdir "%~dp2"+ echo fake icon>"%~2"+)if "%FCC_NAME%"=="fcc-server" if "%1"=="--version" echo free-claude-code 3.5.18exit /b 0""",@@ -1044,14 +1095,25 @@ def test_install_ps1_fresh_install_is_verified(for call in calls)assert not any(call.startswith("git:") for call in calls)- assert calls[-3:] == [+ assert calls[-4:-1] == ["uv:tool update-shell","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()+ icon = home / ".fcc" / "app-icon.ico"+ assert icon.read_text(encoding="utf-8").strip() == "fake icon"+ assert calls[-1] == f"fcc-desktop:--export-icon {icon}"+ desktop_shortcut = home / "Desktop" / "Free Claude Code.lnk"+ assert desktop_shortcut.is_file()+ assert (+ _windows_shortcut_icon(+ powershell_harness.powershell,+ desktop_shortcut,+ )+ == f"{icon},0"+ )assert (app_data/ "Microsoft"@@ -1062,6 +1124,17 @@ def test_install_ps1_fresh_install_is_verified().is_file()+def test_install_ps1_stops_if_windows_icon_export_fails(+ powershell_harness: PowerShellHarness,+) -> None:+ result = powershell_harness.run(fail_step="desktop-icon-export")++ assert result.returncode != 0+ assert "Command failed with exit code 56" in result.stderr+ home = Path(powershell_harness.env["USERPROFILE"])+ assert not (home / "Desktop" / "Free Claude Code.lnk").exists()++def test_install_ps1_preserves_unowned_desktop_shortcut(powershell_harness: PowerShellHarness,) -> None:diff --git a/uv.lock b/uv.lockindex 2252ea6e..9295f6ac 100644--- a/uv.lock+++ b/uv.lock@@ -620,7 +620,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "4.12.4"+version = "4.12.5"source = { editable = "." }dependencies = [{ name = "aiohttp" },