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 Free Claude Code app icon (#1252)

Ali Khokhar7a3d15826251
diff --git a/pyproject.toml b/pyproject.toml
index 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.ps1
index 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 $iconPath
return
}
@@ -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.sh
index 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() {
fi
if [ "$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 0
fi
- 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.icns
new file mode 100644
index 00000000..0f6f0332
Binary files /dev/null and b/src/free_claude_code/assets/app-icon.icns differ
diff --git a/src/free_claude_code/assets/app-icon.ico b/src/free_claude_code/assets/app-icon.ico
new file mode 100644
index 00000000..bcc6175c
Binary files /dev/null and b/src/free_claude_code/assets/app-icon.ico differ
diff --git a/src/free_claude_code/assets/app-icon.png b/src/free_claude_code/assets/app-icon.png
new file mode 100644
index 00000000..0cfc7576
Binary files /dev/null and b/src/free_claude_code/assets/app-icon.png differ
diff --git a/src/free_claude_code/assets/app-icon.svg b/src/free_claude_code/assets/app-icon.svg
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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.py
index 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 Image
from pystray import Icon, Menu, MenuItem
from free_claude_code.cli.desktop import DesktopController, launch_desktop
+from free_claude_code.cli.desktop_assets import app_icon_bytes
class 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.py
new file mode 100644
index 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().err
diff --git a/tests/scripts/test_installers.py b/tests/scripts/test_installers.py
index 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" ]; then
exit 36
fi
+if [ "$name" = "fcc-desktop" ] && [ "${1:-}" = "--export-icon" ]; then
+ [ "$FAIL_STEP" = "desktop-icon-export" ] && exit 37
+ mkdir -p "$(dirname "$2")"
+ printf 'fake icon\n' > "$2"
+fi
if [ "$name" = "fcc-server" ] && [ "${1:-}" = "--version" ]; then
echo "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 & 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
+ 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.18
exit /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.lock
index 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" },