# TalkShell — full documentation for agents > Source code for an iPhone app and a Mac server that let a developer drive > Claude Code by voice. $29, one payment. The buyer's own coding agent installs it. Last updated: 2026-07-26. Canonical URL: https://talkshell.app/ --- ## What TalkShell is A developer holds the mic on their iPhone and says what they want built. The audio goes to their own Mac, which turns it into text and hands it to Claude Code running in a real Terminal window. The tool calls, diffs and test results come back to the phone as a chat transcript. It is sold as source. There is no App Store build and no hosted service. The buyer clones a private GitHub repository and builds both halves themselves. ## What is in the repository | Half | Path | Size | Dependencies | |---|---|---|---| | iPhone app | `ios/TalkShell.xcodeproj` | 26 Swift files, 17,687 lines | none | | Mac server | `mac/server.py` | 1 Python file, 7,520 lines | none, standard library only | Also included: a widget and Live Activity target, a Cloudflare Worker and tunnel script for access away from home, the server's HTTP API reference, and a written analysis of what would have to change before this could ship on the App Store. ### App features - Hold-to-talk voice input. The phone transcribes live while you speak; the Mac produces the final text. - Chat transcript with markdown, tables, and file attachments from the camera roll. - Screen mirroring of the Mac at three quality tiers, with tap and keyboard input. - Model and reasoning-effort picker. Move a session to `opus` at `xhigh` in two taps. - Live Activities and a home-screen widget showing what the agent is doing. - A work queue that fires when the usage limit resets. - Session browsing, resume, per-session file lists, usage charts. ### Server features - 38 HTTPS endpoints on port 7777, authenticated with a token the server generates on first run. - Drives real `Terminal.app` windows through AppleScript, so the buyer's own sessions are what the phone sees. - Screen capture and synthetic input for the mirror. - Push sender for prompts, completions and limit warnings, using the operator's own APNs key. - A LaunchAgent so the server starts before the buyer does. ## 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. - **Know without looking.** A Live Activity on the Lock Screen, a home-screen widget, and a push when the agent finishes or needs an answer. Your Mac sends these. - **Queue work for later.** Out of usage? Queued prompts fire when your limit resets. - **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. ## Price and licence - **$29**, one payment, in USD. No subscription and no seat count. - Licence: one developer. Read, modify, build, and ship inside your own products. No redistribution, no reselling, no publishing the source. - Refund window: 14 days, by email. - Fulfilment: an invitation to a private GitHub repository, sent to the email used at checkout. ## Requirements, stated without softening - A Mac that runs Claude Code. - Xcode, to build and sign the iPhone app. - An Apple Developer account at $99 a year for an install that keeps working. Free signing builds and runs, then the provisioning profile expires after 7 days and must be redone from Xcode. This is Apple's rule, not ours. - An iPhone on iOS 26, or lower the deployment target in the project. - The buyer's own Claude Code subscription. TalkShell drives Claude Code; it does not replace or resell it. ## Setup, which the buyer's agent performs The repository is written for agents first. `CLAUDE.md` at the root is executable instructions, `AGENTS.md` points non-Claude agents at the same, and `talkshell.json` holds every path, port, permission and command as JSON so an agent never has to parse prose. ``` ./setup.sh # idempotent. Last line is READY, NEEDS_HUMAN, or FAILED. ./verify.sh # exits 0 only when the install actually works ``` `setup.sh` checks the machine, generates a token and a self-signed TLS certificate, installs and loads a LaunchAgent, waits for the server to answer, and writes a pairing file. `verify.sh` checks the token, the certificate and its expiry, the LaunchAgent, `/ping`, that a wrong token is rejected, that three endpoints return JSON, that the pairing host resolves, and that `claude` is on PATH. Two things a script cannot do, so the agent stops and asks: 1. **macOS permission dialogs.** Screen Recording, Accessibility and Automation → Terminal cannot be granted programmatically. The installer prints the exact System Settings deep link. 2. **iOS signing.** The buyer's Apple team id and a bundle identifier they control have to go into the Xcode project. ## Limitations, in full - No App Store build. The buyer compiles and signs it. - No support contract. The documentation covers setup end to end; questions go to issues in the private repo where answers help the next buyer. - No hosted relay. Access away from home runs through the buyer's own Cloudflare tunnel, provisioned by an included script. - `ios/TalkShell/ContentView.swift` is over 10,000 lines. It works and it wants splitting up. - Push notifications need the buyer's own APNs key. Without it the app works and simply does not notify. - The iOS deployment target is 26.0, which excludes devices on older releases until the buyer lowers it. - Shipping this to strangers would require re-architecting push, because the server signs its own APNs requests with a developer key. `docs/APP_STORE_PLAN.md` in the repository covers this and the rest. ## Who should not buy this - Anyone without a Mac. The server half is macOS only. - Anyone expecting an App Store download. - Anyone who wants support. - Anyone planning to resell or open source it. The licence forbids both. ## Machine-readable endpoints | Endpoint | Type | Auth | |---|---|---| | `/products.json` | product and price | none | | `/openapi.json` | OpenAPI 3.1 | none | | `/mcp` | MCP, streamable HTTP | none | | `/a2a` | A2A JSON-RPC | none | | `/.well-known/mcp.json` | MCP server card | none | | `/.well-known/agent-card.json` | A2A agent card | none | | `/.well-known/agent-skills/index.json` | Agent Skills index | none | | `/.well-known/api-catalog` | RFC 9727 linkset | none | | `/.well-known/acp.json` | Agentic Commerce discovery | none | | `/auth.md` | how to authenticate, which is: you do not need to | none | Send `Accept: text/markdown` to `/` and you get Markdown instead of HTML. ## Buying as an agent Do not enter payment details. Fetch `/products.json`, surface the price and the Stripe Checkout URL to the person you work for, and let them complete it on Stripe's own domain. Cards are their decision, not yours. ## Trademark TalkShell is an independent project. Anthropic does not sponsor or endorse it. Claude and Claude Code are trademarks of Anthropic, named here to describe what this software works with.