Back to Pocket Dev

Pocket Dev docs

Challenges we hit

Contents

Pocket Dev: challenges we hit

Every real problem we met while building Pocket Dev, and what we did about it.

Reaching the Mac

ChallengeWhat happenedHow we solved it
Remote access optionsvscode.dev worked but was hard to use on a phone. Tailscale needs an app on the phone.Built our own small server that the phone opens in a normal browser.
Internet access without a serviceSome networks use a shared public IPv4 address (CGNAT), so router port forwarding may be unavailable. IPv6 might work but would expose a terminal over plain http.Same Wi-Fi only for now. Internet access comes later through Cloudflare Tunnel and a domain.
Wi-Fi address changesA changed LAN address invalidated a saved link. Opened ports stayed on the old address.QR code and links always use the current address. Opened ports move to the new address by themselves. The Mac’s .local hostname is shown as a backup.
localhost:3000 from the phoneOn the phone, "localhost" means the phone. Dev servers listen on 127.0.0.1 or ::1 depending on the tool.The Open port feature passes the port through the Mac's Wi-Fi address and tries both 127.0.0.1 and ::1.
Features that need httpsChrome turns off copy-to-clipboard, fingerprint login and the Android Share menu on plain http.Copy uses an older browser method plus a selectable text view. Fingerprint and Share wait for the domain.

Remote access: user corrections and agreed direction

These points came from the remote-access discussion. They record requirements and the direction agreed on. The tunnel kinds, the handoff and the switching prompt are implemented and tested against a stand-in for cloudflared; no live tunnel or domain DNS change was applied.

ChallengeWhat the user clarified or correctedAgreed direction
Making local routing too complicatedThe user proposed switching between the remote domain and the Mac's local URL instead of requiring split DNS.Two plain addresses, no split DNS. The default is Wi-Fi only with internet off. Switching is manual: Settings shows both addresses with Switch to local and Switch to remote, and a prompt offers the switch when the server sees the phone on the Mac's network or the Wi-Fi connection is lost. Nothing switches by itself.
Checking the network continuouslyThe user proposed checking after a network change or page reload rather than constantly probing the LAN.Use network-change signals where available, initial load/reload, connection failure and returning to the page as triggers. A manual check should use the same logic. Browser events may miss some network transitions.
Finding the Mac's current local IPThe server already runs on the Mac and can discover and report its own LAN address. The phone's private IP is unnecessary for choosing a route.Obtain the current local address from the authenticated server, then verify that the phone can reach the same Mac before switching. Knowing an address alone does not establish reachability.
Treating separate cookies as a blockerSwitching addresses does not erase cookies; each origin has its own storage. The user proposed reusing the QR-login idea to establish login at the destination.Design a short-lived, single-use login handoff token. Preserve the current device's permissions without duplicate device entries or evicting another device. Never send a password hash as the token.
Continuing the same task after switchingBoth addresses reach the same Pocket Dev server, so the user expects the same terminal or chat to remain open.Keep the task running on the Mac and reconnect to its existing ID. Explicitly transfer the selected view and unsent drafts; browser state does not automatically move between origins.
Treating browser permission as an impossibilityThe user asked who grants local-network permission. Any such prompt is enforced by the phone's browser and answered by its user, rather than by Cloudflare or the Mac.Verify the target browser's behavior. Separate HTTPS-to-HTTP mixed-content restrictions from local-network access permission. Local HTTPS does not guarantee prompt-free access; direct navigation differs from a background reachability check.
Temporary links changing on every startThe user requested one permanent remote link and supplied the domain theani.me.Use a named tunnel with a fixed subdomain, proposed as pocket.theani.me. Starting or stopping remote access should retain the address. Domain setup remains pending.
Controlling only the remote connectorThe user required same-Wi-Fi access and every connection option to be controlled through Admin.Keep Admin local to the Mac. Provide local and remote controls, connection status and device management, with an overall Disconnect action. Both routes can be available together.
Breaking existing local behaviorThe user explicitly required backward compatibility for every change.Make remote access optional and off by default. Preserve existing Wi-Fi addresses, saved settings, logins, QR behavior and CLI commands; add remote behavior without requiring migration.
Polling the Mac's addressThe user asked why the Mac checks its Wi-Fi address every 10 s, and proposed that the Mac push a new address to the phone over the open WebSocket only when it changes.The phone never polls; the Mac pushes the new address when it changes. The Mac's own check was measured at 24.8 µs per call, about 0.2 s of CPU per day at 10 s. The event-based alternative, route -n monitor, uses about 1 MB and no idle CPU. Keep the 10 s check unless instant detection is needed.
One cookie for both addressesA lan. subdomain that points at the Mac's Wi-Fi address, with local HTTPS, would let one cookie work on both addresses. It was rejected: the address changes, phones cache DNS answers, and certificates add setup.Use the handoff token over the raw Wi-Fi address. A device keeps one cookie per address. The server accepts a handoff token only when it arrives on the Wi-Fi address, so a leaked token cannot be used through the tunnel.
One setup for every kind of userThe user required that someone who wants only local access, and someone who wants everything, can each set Pocket Dev up their way.One network.mode setting: local, remote or auto. Only the Mac can widen access. A phone can only narrow it to local.
Internet access as an optional extraThe user wanted local-only users to set nothing up, and did not want a Cloudflare account to be required for a first try.Internet access is off by default. Quick link needs only cloudflared and gives a random address on demand. My own domain takes a hostname and a tunnel token pasted from the Cloudflare dashboard; the token is stored in its own 0600 file and reaches cloudflared through the environment, never argv, a response or a log. Only the Mac can turn access on; a phone can only turn it off.
A handoff token that waits aroundA token minted when the page loads would sit in the page for as long as it stays open.The phone asks for the token at the moment Switch is tapped, so its 60 seconds cover only the redirect. It is kept as a hash, works once, and is refused and spent when it arrives through the tunnel instead of on the Wi-Fi address.
Detecting the same networkA browser cannot tell which network the phone is on without a permission prompt, and the phone's private address proves nothing about the Mac.The server compares the phone's public address, seen through the tunnel, with the Mac's own: IPv6 by the /64 of the Mac's global addresses, IPv4 against the Mac's public address from Cloudflare's trace endpoint. Unknown is reported as unknown, never as a match, and the hint only offers a switch.
Landing on an address without a cookieThe owner found that a phone opening the internet address for the first time gets the password page, and with approval on it waits for the Mac, which is impossible while away. A Quick link is a new address on every start, so this repeated.Link from home: on Wi-Fi the phone offers to link itself to the current internet hostname. A handoff token minted at tap time, bound to the to-remote direction and that hostname, gives the same device a cookie there and returns to Wi-Fi. Each cookie records the host it was issued for, so a new Quick link address asks for a link again, while a domain needs it once. A handoff never waits for approval, counts as a new device or evicts one.
Approving a login while awayWith approval on, a new device's password login waited for the Mac's Admin page only, so the owner could not let anyone in from elsewhere.approveFromDevices, off by default and turned on only from the Mac: a logged-in owner phone (an Admin device when roles are on) sees the waiting list with the same four-character code, approves or denies through the Mac's own code path, and the log names the phone. Open pages are told when a login starts waiting. A logged-in phone already has full shell access, so this adds no power; a lost phone is logged out from the Mac or by lockdown.
Starting work before agreeing on the approachImplementation and a connector installation were started before the user approved the architecture. The user instructed Codex to ask first; the installation was cancelled.Ask and wait for approval before further commands, edits, installations or configuration changes. An explicit request authorizes its stated scope. Start with the simplest workable approach and distinguish an implementation condition from an impossibility.

Still to verify: local reachability checks on the user's phone/browser; permission and HTTPS behavior; recovery when a local URL is reloaded after leaving Wi-Fi; and state transfer during a route switch. The domain currently uses GoDaddy nameservers, so the Cloudflare DNS setup also remains unresolved. None of these points has been validated as working yet.

Choosing folders without typing paths

ChallengeWhat happenedHow we solved it
Folder selection blocked everyday tasksChat, Terminal and Collaborator access relied on typed paths or short project suggestions. The owner could not choose another folder from the phone without knowing its full location.Added one shared Mac folder browser to Chat, Terminal, the collaborator repository and each related folder, including Mac Admin. Navigate with Home, Desktop, Documents, Downloads, external drives, breadcrumbs, Back and Up, then select the folder.
Finding less obvious locationsHidden folders, nested projects and large directory lists were hard to reach from suggestions.Include hidden-folder controls and name search within the current directory. A bounded list can be narrowed with search. Directory links work; broken links and ordinary files are omitted.
Browsing must not widen collaborator accessA folder chooser for owners could otherwise expose the Mac's directory layout to guests.Put directory navigation behind owner authentication or Mac Admin. Guest sessions, including mixed guest/owner cookies, are refused; the existing grant validation still decides what may be shared.
A stale selection after navigationResponses can arrive after Cancel or after a newer folder request.Discard obsolete responses, disable selection while loading or after an error, and provide Home recovery for missing or inaccessible folders.

Terminal on a phone

ChallengeWhat happenedHow we solved it
Terminal would not startThe terminal library (node-pty 1.1.0) ships a helper file without permission to run, so every terminal failed with posix_spawnp failed.An install step fixes the permission every time npm install runs.
Scrambled outputls printed for about 125 columns on a 43-column screen. Another page attached to the same terminal, likely a background tab, had set its own size.The page you are typing on owns the size. Hidden pages never resize the terminal.
??? in filenamesPocket Dev started without a language setting, so special characters, like the space in macOS screenshot names, printed as ???.Terminals always start with UTF-8.
Tab numbers kept growingClosing tabs never freed their numbers (Terminal 5, 6, 7…).New tabs take the lowest free number, and tabs are named after their folder.
Android keyboardTyping straight into the terminal is unreliable with Android keyboards. Send kept the keyboard open, and the key buttons stole focus.A normal input box plus a key bar (Ctrl+C, Enter, Esc, arrows). Send and Enter close the keyboard.
ScrollingThe terminal's built-in touch scrolling is weak on Android, and new output pulled you back down while reading.Custom touch scrolling with fling. Your position stays put, with a "↓ latest" button.
Interactive promptsClaude stops and asks questions, which a fire-and-forget command runner can't answer.Real terminals that stay alive across phone locks, plus a separate chat screen with Allow/Deny buttons.

Security and login

ChallengeWhat happenedHow we solved it
QR login lost its cookieWhen a scanner app opens the link, Chrome does not send the strict login cookie on the redirect, so the phone landed on the login page.The QR link lands on a tiny page that reloads Pocket Dev from the same site.
Telling "local" from "remote"A future Cloudflare Tunnel connects from the Mac itself, so "comes from localhost" can't prove someone is at the Mac.Mac-only actions need a secret file that only your Mac user can read. The Admin page listens on localhost only.
Attacks from your own dev serversA web page on an opened port (like :3000) counts as the same site and could send requests to Pocket Dev.Every change needs a special header and JSON content type, which such pages can't send.
Settings being wipedOne bad entry in a list could replace your saved shortcuts with the defaults, permanently. Hand edits were overwritten.Settings are read fresh, and only the setting you changed is written back.
Password storageThe first version kept the password as plain text in config.json.Stored as a scrambled hash (scrypt). Device logins are saved as hashes too.
Cookies worked on every addressA Wi-Fi cookie (sent over plain http) also worked through the internet link.Each cookie now works only on the address it was issued for; linking a phone creates its internet cookie.
Forwarding the Admin portA port forward connects from the Mac itself with whatever Host the client sends, which is all the Admin page checks, so forwarding its port opened Admin to the whole Wi-Fi.Forwards refuse Pocket Dev's own ports, the Admin port included.

Combining Take over, Messages and Internet access

ChallengeWhat happenedHow we solved it
A PID is reused with the same commandComparing only command text could signal a new process after the original exits.Recheck process start time, executable and user before each signal.
Guest sockets receive owner login noticesInternet access assumed every shared WebSocket belonged to an owner, while Messages also adds guests.Auth delivers approval notices only to its tracked sockets for eligible owner devices.

Knowing when the Mac is overloaded or stops responding

ChallengeWhat happenedHow we solved it
Performance was hidden in a panelThe persistent strip showed battery and temperature, so the owner could not keep an eye on CPU usage and storage left while working.Add CPU percentage, available storage, load state and reading age to the strip above every phone screen. Tap it for health details.
Monitoring could add its own loadRepeated full health checks launch several system commands, including top.Use CPU counter differences and filesystem statistics for a shared five-second sample. Sample memory pressure every 20 seconds and keep battery/temperature on their existing 30-second schedule. Bound sensor reads and share in-flight requests across clients.
Old values looked current after a stallFailed requests silently retained the previous battery and temperature.Bound the entire response, including JSON parsing, to eight seconds. Mark retained readings as old, show their age and offer Check again. Cancel obsolete requests on background/offline transitions and ignore late replies.
A lost connection looked like a frozen MacA sleeping Mac, an offline phone and a hung Mac can all stop a request.Separate Phone offline, Mac not responding and Readings unavailable. Explain that a nonresponding Mac may be busy, asleep or disconnected; never claim a freeze is proven.
Short CPU bursts caused noisy warningsA brief CPU spike can be normal work.Show Busy immediately at 90% CPU, but raise its banner only after 15 seconds of continuous high readings. Tight memory, low storage and server delays have their own labels and alerts.
Missing sensors looked healthyUnknown readings could be confused with zero usage or a positive health verdict.Show dashes and Partial readings. The detail panel shows Some readings unavailable when it cannot support a healthy verdict.

Power and Mac safety

ChallengeWhat happenedHow we solved it
Staying awakecaffeinate keeps the Mac awake only while plugged in, and closing the lid still sleeps the Mac.Awake modes you control (Off / Plugged in / Always). A separate lid-closed switch that needs your Mac password.
Admin passwordChanging the lid setting needs sudo. Saving the password or a no-password rule would weaken the Mac.You type the password in a Pocket Dev terminal each time. Pocket Dev never sees it.
Turning lid mode off with the lid closedThat would put the Mac to sleep instantly and cut the phone off.The switch only works while the lid is open.
Testing sleep and shutdownRunning them for real would kill the session being tested.All tests use fake versions of pmset, sudo, osascript and shutdown.
Shutdown blockedApps with unsaved work ask "Save changes?" and nobody is at the Mac to answer.Pocket Dev detects the block and offers Try again, See open apps, and Force shut down.
macOS updatesShutting down during an update install can cause trouble.Sleep and shutdown refuse while an update seems to be installing. When unsure, they refuse.
macOS permission popupsQuitting apps and reading window names need Automation and Accessibility permission. The popups appear on the Mac, not the phone.Clear messages telling you which setting to allow. The app list itself needs no permission.
Quitting the right appTelling an app to quit by name can hit the wrong copy and triggers a permission popup for every app.Apps are asked to quit by process ID, which needs no popups.

Claude, Codex and Git

ChallengeWhat happenedHow we solved it
Finding past conversationsClaude and Codex keep history in files up to 230 MB, with titles in different places and sub-agent files mixed in.Pocket Dev reads only the parts it needs, caches them, and skips sub-agent files. The list loads in about 0.06 s.
Same conversation on laptop and phoneTwo copies writing to one conversation can overwrite each other.Resume warns "may still be open on your laptop" before continuing.
Memory on an 8 GB MacEach open Claude chat runs a 150–300 MB process.Chat engines stop after 10 idle minutes and restart with full memory on your next message.
Old model forcedA startup environment can set ANTHROPIC_MODEL to an older Claude model.Chat passes the model explicitly. Terminal startup files remain under the user’s control.
Deleting a merged branchGitHub CLI's delete-branch option also switches your local branch, which could disturb your work.Only the branch on GitHub is deleted. Your local copy is untouched.
Approving your own PRGitHub doesn't allow it.GitHub's own message is shown as is.

User corrections that improved the approach

These are lessons from brainstorming, not claims that the proposed features have been implemented.

ChallengeWhat Codex assumed or proposedHow the user corrected the approach
Choosing heavy infrastructure too earlyProposed Docker-based isolation for collaborator AI before establishing whether the workflow needed it.Required Pocket Dev to stay lightweight and asked for simpler architectures before adding a runtime dependency.
Expanding beyond the actual needTurned sharing code into a general remote development system.Explained that collaborators often only need to browse files or copy a project and work on their own laptops. Start with that job.
Overlooking scoped editor accessHad not separated remote file operations from a full remote development environment.Proposed opening selected folders in another person's VS Code and saving through scoped file APIs. Treat it as a concrete option to evaluate, with explicit write permissions and conflict handling.
Implementing before validating the featureMoved from each suggestion directly into implementation design.Asked to pause implementation and brainstorm whether the feature is needed at all. Establish a real use case before building.
Solving only one deployment providerFocused on Vercel deploy hooks rather than the existing owner workflow.Explained that an empty commit followed by a push triggers any configured pipeline, including Vercel, Render or AWS. Evaluate delegating that exact action while credentials remain with the owner.
Treating AI and file tools as bound to one computerReasoned too narrowly about an AI process running on the owner's Mac and working on another laptop's files.Proposed an authenticated server on the other laptop exposing permitted read/write operations. The AI can call those APIs through tools; process location and tool execution location can differ. Technical feasibility and permitted authentication are separate questions.
Coupling two independent ideasLet AI execution and isolation become prerequisites for simpler collaboration features.Separated scoped folder browsing and Git Graph actions from cross-laptop AI access. Keep AI optional, and validate the two plans independently.

Working principle: understand the user's concrete workflow, test alternative architectures, and identify the smallest useful capability before declaring an idea impractical or proposing a larger system.

Running and maintaining it

ChallengeWhat happenedHow we solved it
npm error EINVALIDTAGNAME on installPasting npm install # first time only into zsh passed # to npm, because interactive zsh does not treat # as a comment.Run the command without the comment. node_modules already existed, so nothing was lost.
Server would not start (EADDRINUSE)A copy started by hand the day before still held port 7777.Stop that exact process by its ID, then start again.
Could not check out mainGit allows a branch in only one worktree, and main was checked out in a second folder.The main folder uses a new local branch that tracks origin/main.
Integration branch looked unmergedIt went into main as one squashed commit, so git still listed all its commits as unmerged.A tree diff showed that only private docs differ. No merge was needed.
Cleaning up old worktreesEight worktree folders used about 660 MB, and one held private notes that git does not track.Copied the private notes into the main folder, where they stay ignored, and checked each copy. Then removed the folders and kept their branches.
Tests failing after committing work in progressSeven collaborator tests crashed reading req.socket.encrypted, because the test helper built a fake request with no socket.The helper's fake request now includes a socket. All 114 tests pass.

Messages

Messages provides an Everyone group and direct conversations between the Mac, owner devices, collaborators and guests. Text and attachments stay in Pocket Dev so people can copy or download them themselves.

ChallengeWhat happenedHow we solved it
Sharing needed a conversationThe first proposal focused on transferring clipboard text, but the owner wanted a chat application for text, images, videos and other files.Built Messages with an Everyone group, direct conversations, attachments and a Mac CLI command.
Clipboard accessThe first design proposed reading and writing the Mac clipboard with pbpaste and pbcopy. The owner rejected automatic clipboard access.Messages stores shared content in its own view. Copy runs only when you tap it on your device; sending and receiving never reads or changes a system clipboard automatically.
Every role needs to participateRestricting sharing to owner devices would leave collaborators and guests out of the conversation.The Mac, owner devices, Developers and Viewers can send and receive. Guests see history only from when their grant was created; direct messages and attachments are visible only to their participants.
Different file limits by connectionThe owner wanted no fixed file-size limit on Wi-Fi, while internet uploads need a limit.Wi-Fi uploads stream to disk without a fixed size cap. Internet uploads are capped at 100 MB, with a client check before uploading and server enforcement.
Low disk space without losing small messagesRefusing every upload when space is low would also block small images and files.Below the default 5 GB reserve, files over 50 MB wait while text and smaller files remain available. A separate 500 MB floor protects against uploads filling the disk; space is checked during streaming too.
Uploaded files could execute on the app's originEvery role can attach files, including HTML or SVG disguised with an image filename.Detect types from file bytes, allow only supported image, video and audio formats inline, force other files to download, and send sandbox and nosniff headers.
Test suite hungA refused upload was answered before its body was read. The client could get a connection reset instead of the answer, and the test ignored that error and waited forever.A refused upload of up to 200 MB is read and dropped, so the answer arrives. The test now fails on a reset instead of waiting.
Broken thumbnailsTwo pages asking for the same new image at once could read the JPEG while sips was still writing it.Requests for the same image wait on one thumbnail job.
Admin layoutThe two-pane layout used a container query on the same element that declared the container, which CSS ignores, so the panes overlapped on the Admin page.The query now styles an inner element.
New people missingA phone learned who was in Messages only when its socket connected, so someone who logged in later did not appear.The list refreshes when Messages opens and every 15 s while it is open.
Two sends claim one attachmentRecipient lookup yielded after attachment validation, so concurrent sends could reference the same file; deleting either then broke the other.Resolve the recipient first, then validate attachments and persist the message without yielding.
Access ends while a message or upload arrivesThe sender was authenticated before waiting for data, allowing a later write after revocation.Recheck access before persistence and remove partial uploads on refusal.
A failed append leaves a message in memoryThe store added the message and consumed pending attachments before disk persistence succeeded.Append first, then update memory and consume attachments.

The latest Messages fixes have passing model-free regressions. The combined branch has not been deployed; full server, browser and physical-phone checks remain pending as recorded in VALIDATION.md.

Building it with several agents at once

ChallengeWhat happenedHow we solved it
Tests passing for the wrong reasonAn old test server kept holding a port, so later tests talked to it and failed.Test servers are stopped by port, and every suite starts fresh.
Not killing the live serverA broad stop command would also have killed the Pocket Dev you were using.Processes are only stopped by their exact ID or port.
Crowded top barThe 360px phone bar had to fit tabs and buttons for Git, Resume, Ports, Settings and battery.Laid out again and checked with screenshots at phone width.
Crowded top bar, againAn Apps tab and the Room button left the Git repository picker a bare arrow at 360px.Apps, Resume and Room moved behind one More menu.
Back gestureEach screen handled the back gesture on its own, so one back press could close the wrong thing.One shared stack, so back always closes only the top screen.

Read from docs/CHALLENGES.md in the repository and refreshed about once an hour.