phonedesk

mcp
Guvenlik Denetimi
Basarisiz
Health Gecti
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 11 GitHub stars
Code Basarisiz
  • process.env — Environment variable access in scripts/check-overflow.ts
  • network request — Outbound network request in scripts/check-overflow.ts
  • spawnSync — Synchronous process spawning in scripts/gen-assets.ts
  • exec() — Shell command execution in scripts/gen-icons.ts
  • spawnSync — Synchronous process spawning in scripts/sign-macos.ts
  • rm -rf — Recursive force deletion command in setup.sh
  • exec() — Shell command execution in src/actions.ts
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

Turn an old phone into a Stream Deck-style control panel and dashboard for your Mac or Windows PC. No app, no account, no cloud.

README.md

PhoneDesk logo

PhoneDesk

Your old phone, a control panel for your computer.

Release MIT License macOS and Windows

English · Tiếng Việt

Turn an old phone or tablet into a Stream Deck-style control panel and dashboard for your Mac or Windows PC. PhoneDesk is a small
agent that runs on your computer and serves a touch overlay to any browser on the same Wi-Fi. There is no app to
install on the phone and no account or cloud service.

Status: early (0.x). macOS is the main target, Windows is experimental. Builds are not signed with a Developer ID or notarized: see Install.

PhoneDesk: your old phone, a control panel for your computer

What you can do

Use it for On the phone
Shortcuts Open apps (with their real icons) and URLs, key combinations, type text, shell commands, macros, media and volume keys
Monitoring CPU, memory, network, load and uptime with selectable chart styles; tap CPU for the process list
AI coding Claude, Codex and Antigravity quotas with reset times; pick which windows to show (5 hours, 7 days, per model); local Claude Code / Codex sessions
Claude Code from the couch Answer Allow / Deny permission prompts and Claude's multiple-choice questions on the phone (opt-in hooks)
Everyday Now Playing with artwork and Resume, 6 clock styles and world clocks, weather (hourly and daily, °C or °F), a soundboard, notifications
Home Assistant Lights with colour, colour temperature, scenes and effects; climate (mode, fan, swing), fans, covers, vacuums, locks and sensors (optional)
Automation Webhooks that push values and notifications, rules that react to activity on the computer
Make it yours Drag-and-drop grid (8×4, 8×3, 5×3…) with a preview for every screen size, 4 tile styles (Soft, Solid, Outline, iOS), any colour per tile, 5,000+ icons, English or Vietnamese

The layout is a fixed grid of square tiles built in a drag-and-drop management page at http://localhost:7420/manage/.
An MCP server lets an AI assistant arrange the layout for you. Runs on macOS, and on Windows 10/11 (experimental).

Screenshots

A 16-second tour with demo data: pages, AI quotas, keys, Home Assistant and a Claude Code question.
A 16-second tour with demo data: pages, AI quotas, keys, Home Assistant and a Claude Code question.

Answer Claude Code from your phone AI quotas and sessions
Answer Claude Code from your phone AI quotas and sessions
Stream Deck-style keys Home Assistant
Stream Deck-style keys Home Assistant

Install

You need a Mac (macOS 13 or later) or a Windows 10/11 PC, and a phone or tablet on the same Wi-Fi. Nothing
is installed on the phone. It takes about 2 minutes.

1. Install on the computer

On a Mac

  1. Open Terminal: press ⌘ Command + Space, type Terminal, press Return.
  2. Copy this line, paste it into Terminal, press Return:
curl -fsSL https://raw.githubusercontent.com/howznguyen/phonedesk/main/setup.sh | bash

On Windows (experimental)

  1. Open PowerShell: click Start, type PowerShell, press Enter (no administrator needed).
  2. Copy this line, paste it into PowerShell, press Enter:
irm https://raw.githubusercontent.com/howznguyen/phonedesk/main/setup.ps1 | iex

You will see a download bar, then a few OK lines. At the end PhoneDesk prints a QR code, a phone address
(for example http://your-mac.local:7420) and a 6-digit PIN. Keep that window open for the next step.

PhoneDesk now starts by itself every time you sign in, and the phonedesk command works in any new terminal window.

2. Open it on your phone

  • Easiest: open the phone's Camera and point it at the QR code on the computer. Tap the link that appears.
  • Or type the phone address into the phone's browser and enter the PIN.

The phone remembers it, so you only do this once. For a full-screen panel, add it to the home screen:

  • iPhone (Safari): tap Share → Add to Home Screen.
  • Android (Chrome): tap ⋮ → Add to Home screen.

3. Make it yours

On the computer, open http://localhost:7420/manage/ in your browser. Drag apps, shortcuts and widgets onto the
phone preview, then press Save. The phone updates right away.

  • Screen size: pick your phone (iPhone 5s/SE, iPhone, Pro Max, Android, iPad or a custom size) above the preview to
    see exactly what it will show. A warning appears when tiles get too small to tap.
  • Theme: mode, corner style, tile style, orientation and accent colour are picture cards, so you see the result
    before you choose.
  • Each tile: pick its colour, fill style and size (1×1 up to 4×3) from small previews.
The management page previewing the deck at iPhone 5s size, with the screen size picker
Theme options as picture cards Tile size and fill style pickers

The first time a key sends a shortcut, macOS asks for Accessibility permission: allow it (System Settings →
Privacy & Security → Accessibility). Windows asks once to allow PhoneDesk on the network: allow it.

Something not working?

Problem What to do
The phone cannot open the address Make sure the phone and the computer are on the same Wi-Fi. On Windows, allow PhoneDesk in the firewall prompt. Try the number address the installer printed (http://192.168…:7420).
could not reach GitHub or error: 503 GitHub had a hiccup. Wait a few seconds and run the same line again.
The download is slow It is about 20 MB (Windows 40 MB). Leave it running; the bar shows the progress.
phonedesk: command not found Open a new terminal window.
A key does nothing on the Mac Allow Accessibility for PhoneDesk, then run phonedesk doctor to see what else is missing.
Keys stopped working after an update macOS ties Accessibility to each build. In the management page, Permissions tab, press Reset and ask again (or run phonedesk doctor --request accessibility --reset) and turn phonedesk on.
.local address does not open on an old phone Use the IP address the installer printed, and give the computer a fixed IP in your router so it does not change.
port 7420 is in use Another program uses that port. Run the installer again with --port 7421 (Mac: … | bash -s -- --port 7421).

Update or remove

  • Update: run the same install line again. Your layout and paired phones are kept.
  • Remove (Mac): curl -fsSL https://raw.githubusercontent.com/howznguyen/phonedesk/main/uninstall.sh | bash. Your data is kept; add -s -- --purge after bash to delete it too.
  • Remove (Windows): irm https://raw.githubusercontent.com/howznguyen/phonedesk/main/uninstall.ps1 | iex.
More installer options and details
  • The installer downloads the right file from the latest release, checks
    its SHA-256 against SHA256SUMS and refuses on a mismatch, installs it for your user only (no sudo, no
    administrator), starts it at sign-in (a launchd agent on macOS, a Task Scheduler task on Windows) and adds it to your PATH.
  • Mac options go after bash -s --: --yes (no questions), --version 0.1.1, --port 7421, --no-autostart,
    --no-open, --no-path, --dry-run. On Windows set environment variables before the line, for example
    $env:PHONEDESK_PORT=7421; irm … | iex (see the top of setup.ps1).
  • Files: the program is ~/.phonedesk/bin/phonedesk on macOS and %LOCALAPPDATA%\PhoneDesk\bin\phonedesk.exe on
    Windows; your data is in ~/.phonedesk; logs are in ~/.phonedesk/logs.
  • Background service: phonedesk service install|uninstall|status|restart.
  • Signing: the binaries are signed ad hoc, not with an Apple Developer ID or a Windows certificate. The installers handle
    this; a file downloaded in a browser may need xattr -d com.apple.quarantine <file> on macOS or "More info → Run
    anyway" in Windows SmartScreen.
  • Known issue on Windows: keys that type text can produce wrong characters. Opening apps, shortcuts, media and volume work.

Install from source

Requirements: macOS 13+ (Apple silicon or Intel), or Windows 10/11 x64 (experimental). Linux is not tested yet.

From source (needs Bun 1.3+):

git clone https://github.com/howznguyen/phonedesk && cd phonedesk
bun install
bun run build          # builds the web apps and dist/phonedesk
./dist/phonedesk       # prints the phone URL and a pairing PIN

On Windows, bun run build:win produces dist/phonedesk-windows-x64.exe.

Open the printed URL on your phone (same Wi-Fi), enter the PIN, and add the page to the home screen for a
full-screen panel. The management page is at http://localhost:7420/manage/ on the Mac.

macOS asks for Accessibility permission the first time a tile sends key presses.

Claude Code integration (optional)

In Manage › AI, two separate switches install hooks into ~/.claude/settings.json (a backup is written first):

  • Permission prompts: a PermissionRequest hook shows Allow / Deny on the phone.
  • Questions: a PreToolUse hook for AskUserQuestion shows Claude's options on the phone and returns your
    choice. Optionally only while you are away from the keyboard.

If no phone answers in time, Claude Code asks in the terminal as usual. For Codex, the permission hook goes into
~/.codex/hooks.json.

Quotas are read-only: PhoneDesk reads the sign-in Claude Code already stored (never refreshes it), Codex's local
session files and Antigravity's local server. See PRIVACY.md for every outbound connection.

Permissions

macOS ties each permission to the program that asks. Under the background service that is the phonedesk binary; started from a terminal it is the terminal app. Run phonedesk doctor to see what is granted (it asks the running agent, never shows a prompt by itself):

Permission Needed for Where
Accessibility key press, typing and volume tiles Privacy & Security > Accessibility
Automation: System Events, Music, Spotify key tiles, Now Playing and media keys Privacy & Security > Automation
Keychain: Claude Code Claude usage quota (read-only) macOS asks once: choose Always Allow
Local Network Home Assistant on your LAN Privacy & Security > Local Network
Firewall phones connecting to the agent Network > Firewall > Options
phonedesk doctor                          # ✓ / ✗ for each item, with the fix
phonedesk doctor --open accessibility     # open the right Settings pane
phonedesk doctor --request accessibility  # make macOS list phonedesk (shows its prompt)

Updates are ad-hoc signed, so macOS may ask again after an update: remove the old phonedesk entry from the Privacy list and add it again. This goes away once releases are signed with a Developer ID.

On Windows phonedesk doctor checks different things (same commands, phonedesk doctor --open firewall opens Windows Security):

Check Why it matters
Firewall Windows blocks incoming connections unless a rule allows phonedesk.exe; the installer offers one rule, for your local subnet only (one UAC prompt, removed by uninstall.ps1). Manually, as administrator: netsh advfirewall firewall add rule name="PhoneDesk" dir=in action=allow program="<path>\phonedesk.exe" profile=any remoteip=localsubnet
Network profile Your Wi-Fi or Ethernet should be a Private network (Settings > Network & internet)
Desktop session Key presses, typing, Now Playing and volume only work when PhoneDesk runs in your signed-in desktop session (the scheduled task does; an SSH session or a Windows service does not)
PowerShell helper Now Playing, volume, app icons and the process list use a small Windows PowerShell 5.1 helper
SmartScreen A downloaded phonedesk.exe carrying the internet mark triggers warnings; the installer removes it

AI layout assistant (MCP)

PhoneDesk ships an MCP server, so Claude Code (or any MCP client) can arrange your deck in plain language: "add a page with my dev tools", "put Spotify next to the clock". It talks to the running agent, so start PhoneDesk first.

Register it once, with the path the installer used:

Installed with Command
setup.sh (macOS) claude mcp add phonedesk -- ~/.phonedesk/bin/phonedesk mcp
setup.ps1 (Windows) claude mcp add phonedesk -- "%LOCALAPPDATA%\PhoneDesk\bin\phonedesk.exe" mcp
Built from source claude mcp add phonedesk -- /full/path/to/dist/phonedesk mcp

Add --port N after mcp if the agent does not use port 7420, and --scope user before phonedesk to make it available in every project. Check it with claude mcp list.

Tools: get_layout, add_page, add_item, update_item, move_item, resize_item, remove_item, update_page, remove_page, set_theme, list_apps, list_widgets, search_icons, preview_changes, undo. Every change goes through the same validation as the management page and can be undone. The layout skill describes the schema to the assistant.

Security

  • The agent listens on your LAN. Phones must pair with a 6-digit PIN; the device token is kept in a cookie.
  • The management API only answers on localhost and rejects cross-site and DNS-rebinding requests.
  • Tiles can run shell commands you configure. Only pair devices you trust.

Development

bun run dev     # agent with watch mode
bun run test    # unit tests

Layout: src/ agent (Bun + TypeScript), web/deck phone overlay (Preact, Safari 12+), web/manage management page
(React), web/shared code used by both.

Credits

License

MIT

Yorumlar (0)

Sonuc bulunamadi