# TalkShell — Claude Code by voice Hold the mic on your iPhone. Your Mac runs Claude Code and sends back the diff. You get the source for both halves, app and server. **$29, one payment.** [Buy the source](https://talkshell.app/buy) · [Full documentation](https://talkshell.app/llms-full.txt) · [Product JSON](https://talkshell.app/products.json) - 25,207 lines - 26 Swift files - 1 Python file - 38 endpoints - 0 dependencies ## Your Claude Code sets it up The repo is written for an agent, not for a human with a checklist. Point Claude Code at it and say "set up TalkShell". It reads `CLAUDE.md`, runs the installer, and stops only where macOS demands a human click a permission dialog. ```bash git clone claude "set up TalkShell" ``` What the agent runs: - `./setup.sh` — checks the machine, generates the token and a self-signed TLS certificate, installs a LaunchAgent, waits for the server, writes a pairing file. Idempotent. Its last line is `READY`, `NEEDS_HUMAN`, or `FAILED`. - `./verify.sh` — exits 0 only when the server answers, TLS is valid, a wrong token is rejected, three endpoints return JSON, the pairing host resolves, and Claude Code is on PATH. `talkshell.json` in the repo root holds every path, port, permission and command as JSON, so an agent never parses prose. There is also an installable Claude skill at `.claude/skills/talkshell-setup/`. Two steps a script cannot do, and the agent will tell you so: the macOS permission dialogs, and putting your Apple team id into the Xcode project. ## What it does Every Claude Code session already open on your Mac shows up as a card. Tap in and you are in the same conversation, from the phone. - **Talk instead of typing.** Hold the mic and speak. The phone transcribes live so you see the words forming, then your Mac produces the final text and sends it. - **Watch the tool calls land.** Read, Edit, Bash, test output, diffs with line counts. The transcript renders markdown and tables. - **Every session, as a grid.** One card per Terminal window running Claude Code, each showing the latest reply and whether it is working, waiting, or done. - **Watch localhost render as it is built.** A real browser lives in the app, with tabs that keep their own history and scroll position. Type `3000` or `localhost:8787/admin` and it loads the dev server on your Mac. It goes through the same authenticated route as everything else, including the Cloudflare tunnel, so you can watch the agent's work appear from a train with no port forwarding and no ngrok. The app lists which ports are listening and can kill one that is stuck. - **Mac vitals while it works.** Watts, temperature, CPU with a sparkline, and memory used against total, read off the Mac. Useful when a long run starts cooking a laptop on a desk you are not at. - **Mirror and drive the Mac.** One tab over from the browser: the screen at three quality tiers, with tap and keyboard input, for the dialog Claude cannot click for you. - **Switch model and effort.** Move a session to `opus` at `xhigh` in two taps. The header chip shows which model answered and how much output was thinking. - **It tells you when a shell needs you.** Claude stops and asks something and your phone says "jarvis needs you" — the folder name, so you know which session, and a one-line summary of what it is actually asking rather than a generic "needs input". A finished run says "jarvis — tap to talk". - **Answer from the Lock Screen.** The notification carries Claude's real choices as buttons: Yes and No for a yes-or-no question, the first three options of a numbered menu, Continue for a finished run. Press and answer without unlocking or opening anything. - **Quiet about everything else.** You are only pinged for sessions you started from the phone, so work you do at the Mac never buzzes your pocket, and it stays silent about the session already open on your screen. A morning digest summarises what every project did overnight. - **Live on the Lock Screen.** A Live Activity ticks while the agent works, showing the session, elapsed time and token count in the Dynamic Island, plus a home-screen widget. - **Drop a file straight into the shell.** Paperclip a screenshot, photo, log or zip. It lands in that session's working directory and the agent reads it immediately. Big attachments get a progress bar and an hour to finish, so a video over slow Wi-Fi does not die at thirty seconds. - **Usage arcs wrapped around the Dynamic Island.** Two concentric rings hug the island: inner is the 5-hour limit with five hour-ticks etched in the track, outer is the 7-day with seven day-ticks, each with a glowing head at the tip. Pace evenly and the tip rides one tick per hour. A countdown to the next reset sits beside it. - **Queue work against the 5-hour reset.** Hit your limit mid-thought and the work does not evaporate. Queued prompts fire on their own when the window rolls over, into the session you picked. - **Pull results back out.** Browse everything the agent created or edited this session and open or share any of it from the phone. ## Away from your Wi-Fi The app works down a ladder on every poll and tells you which rung it landed on. 1. **Your Mac's `.local` name, over Bonjour.** The fast, free path. A 2.5 second probe of `/ping` decides whether it is alive, on its own throwaway session so a pending decision cannot poison the live one. 2. **The last LAN IP that worked.** mDNS quietly stops resolving on cellular and on Bonjour-blocking networks. The app cached the IP from the last successful connect. Toast: `trying cached LAN IP…` 3. **Your Cloudflare tunnel.** Both LAN routes dead means you are elsewhere. Tried *before* Wake-on-LAN on purpose: on cellular there is nothing local to wake, and waiting would cost six seconds for nothing. Toast: `away from Mac — switched to remote` 4. **Wake the Mac.** Still nothing and you *are* on its Wi-Fi, so it is asleep. A magic packet across the subnets it might be on, a six-second wait, one more try. Toast: `waking Mac…` 5. **And back again.** While on the tunnel the app re-probes your LAN once a minute and drops back to the fast path on its own. Toast: `back on home Wi-Fi — using LAN` What changes on the tunnel, because it is slower and metered: | On your Wi-Fi | On the tunnel | |---|---| | Polls every 3 seconds | Polls every 8 seconds | | Full payloads | `lite=1`, trimmed payloads | | Screen mirror at HD | Screen mirror drops to SD | | Wake-on-LAN available | Skipped, nothing local to wake | The tunnel is yours, not ours. `mac/setup-remote.sh` provisions it, and the included Cloudflare Worker checks a hash of your token at the edge, rate-limits per IP and token, then forwards to the private tunnel hostname with a shared secret; a direct hit without that secret gets a 401. Cold starts remember the route you were last on, so relaunching away from home reaches your Mac on the first poll instead of walking the ladder again. ## Why the source, not an App Store app There is no App Store build, and that is the point rather than a shortcoming. You are buying a Claude Code project that happens to be a Claude Code client, so "I wish it did X" stops being a feature request you send me and becomes a sentence you say to your agent. The repo ships with `CLAUDE.md`, `talkshell.json` and an installable skill, so your agent knows the codebase before you ask it anything. Each of these is one prompt: | Change | What it takes | |---|---| | Poll faster | One constant. Drop the 3-second poll to 1 second. | | A new model appears | Anthropic ships one, you add a card. Renaming Opus 4.8 to Opus 5 and making it the default was a two-line change. | | Render a tool call your way | Add a case for the tool you care about, give it its own layout. | | A second Mac | Host and token are settings. Point a second install at another machine. | | Your colours | One palette enum. | | A new endpoint | Add it to the server, call it from the app. Both halves are yours. | An App Store build would mean waiting on review for each of those, and waiting on me to want the same things you want. Nothing is behind a version bump, a feature flag, or a paid tier. ## What it costs to run Nothing, after the $29. - **No VPS.** The server is one Python file on the Mac you already own. No host to rent, no container to keep alive, no bill that grows with use. - **No account.** Nothing to sign up for. Your phone talks to your Mac over TLS with a token your own machine generated. We never see a request, so there is no service to go down or get acquired. - **No subscription.** One payment. No renewal, no seat count, no tier above this one, nothing to cancel. It keeps working whether or not the site still exists. Away from home does not change that: the included script provisions **your own** Cloudflare tunnel, free at this volume, and the Worker that fronts it runs on Cloudflare's free tier. The only recurring costs near TalkShell are ones you already pay — your Claude Code subscription, and Apple's $99/year if you want an install that does not expire. ## "I could build this in a weekend with Claude Code" That is what I thought too. It took months, and almost none of it was the SwiftUI. It was AppleScript, TCC prompts, Bonjour dying on cellular, and Live Activities. What you buy is the part that does not come out of a prompt. ## What's inside ### iPhone app — Swift, 26 files, 17,687 lines - Hold to talk. The phone transcribes live while you speak, then your Mac produces the final text. - Full chat transcript with markdown, tables, and file attachments. - Mirror the Mac screen at three quality tiers. Tap it and type into it. - Model and effort picker. Move a shell to `opus` at `xhigh` in two taps. - Live Activities and a widget for what the agent does while you are away. - A queue that fires when your usage limit resets. - Session browsing, resume, per-session file lists, usage charts. ### Mac server — Python, 7,520 lines, standard library - One file, no pip install. Nothing rots in six months. - 38 HTTPS endpoints, behind a token the server generates for you. - Drives your real Terminal windows with AppleScript. Your sessions, not a headless clone. - Screen capture and synthetic input for the mirror. - Push sender for prompts, completions, and limit warnings. - A LaunchAgent so the server is up before you are. - Cloudflare Tunnel and Worker, plus the script that provisions them. ## You need - A Mac that runs Claude Code - Xcode, to build and sign the app - An Apple Developer account at $99 a year for an install that lasts. Free signing works if you re-sign every 7 days. - An iPhone on iOS 26, or lower the deployment target yourself - Your own Claude Code subscription. TalkShell drives it and does not replace it. ## You don't get - An App Store build. You compile it yourself. - Support. The docs cover setup; questions go to issues where the answer helps whoever asks next. - A hosted service. Access from outside your Wi-Fi runs through your own Cloudflare tunnel. - Polish. One view file runs past 10,000 lines. You will want to split it up. - Resale rights. One developer, no redistribution. ## FAQ **Couldn't I build this myself with Claude Code?** You could. I thought the same thing and it took me months. The SwiftUI arrived fast. AppleScript, the TCC prompts, Bonjour on cellular, and Live Activities did not. **Does my agent really set it up?** Yes, and that is what the repo is built for. `CLAUDE.md` is executable instructions, `setup.sh` is idempotent, `verify.sh` exits 0 only when the install works. The agent stops at the macOS permission dialogs, because no script can click those. **Do I need a paid Apple Developer account?** For an install that outlives the week, yes, $99 a year. Free signing builds and runs, then the profile expires after 7 days and you re-sign from Xcode. **What am I reading when I clone it?** Swift and SwiftUI on the phone across 26 files, with the widget and Live Activity in their own target. One Python file on the Mac at 7,520 lines, standard library, driving Terminal through AppleScript. **Can I put it on the App Store?** Read `docs/APP_STORE_PLAN.md` in the repo first. The server signs its own APNs requests with a developer key, which works for one owner and breaks the moment you ship to strangers. **Will you help me set it up?** No. At $29 I answer in public or not at all, so questions belong in GitHub issues. **Can I resell it or open source it?** No. One developer, no redistribution. **What if I hate it?** Email me within 14 days and I refund you. ## For agents | Endpoint | What it gives you | |---|---| | [`/products.json`](https://talkshell.app/products.json) | price, contents, requirements, exclusions | | [`/llms.txt`](https://talkshell.app/llms.txt) | short summary | | [`/llms-full.txt`](https://talkshell.app/llms-full.txt) | everything, including who should not buy | | [`/mcp`](https://talkshell.app/mcp) | MCP server. `check_compatibility` tells you whether it will work for a given buyer | | [`/a2a`](https://talkshell.app/a2a) | A2A JSON-RPC | | [`/openapi.json`](https://talkshell.app/openapi.json) | OpenAPI 3.1 | | [`/auth.md`](https://talkshell.app/auth.md) | authentication, of which there is none | Buying: fetch `/products.json`, surface the checkout URL to the person you work for, and let them complete it on Stripe's domain. Do not enter their card details. --- TalkShell is an independent project. Anthropic does not sponsor or endorse it. Claude and Claude Code are trademarks of Anthropic, named here to say what this software works with.