airpocket 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+Every change people using Airpocket would notice, newest first. The form is
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.1.0 - 2026-09-17
+
+The first version. Airpocket runs on each Mac where you use Claude Code or
+Codex and makes those sessions reachable from a web app on your phone, over
+your own Tailscale network. There is no Airpocket server, account or relay.
+macOS only, Node 20 or newer.
+
+### Added
+
+- **One list** of every Claude Code and Codex session on every paired Mac,
+  with the ones waiting on you first: finished, waiting for input, needing
+  permission. Each row shows the model, effort, permission mode and whether a
+  turn is running. Agents running on the Mac that Airpocket hasn't heard from
+  yet are counted, with a line on how to bring them in.
+- **The conversation**, read from the agents' own session files rather than the
+  terminal: your messages, the replies, and one short label per step, updated
+  live. Codex turns are shown while they run.
+- **Reply and control** from the phone: send messages and photos, press keys,
+  pick options in on-screen menus, and change model, effort, permission mode
+  and fast mode from each agent's own model list. Commands such as compact,
+  resume and clear come from a fixed table on the Mac, and are refused while a
+  turn runs, a menu is open or unsent text sits in the box.
+- **New sessions** in a project, on a new branch or in an existing workspace,
+  for Claude Code or Codex, when Superset is installed.
+- **Files a session wrote, edited or linked**: text, Markdown, code, images,
+  PDFs and HTML pages, limited to the session's own folder and checked by
+  content. PDFs and pages open from a separate file-only origin through
+  two-minute links, and pages there run no scripts.
+- **`airpocket run claude|codex`**: starts the agent in a tmux session of
+  Airpocket's own, so the phone can answer a session started in any terminal.
+  `airpocket attach` brings back one whose window was closed. Sessions in
+  Superset or an existing tmux pane can be answered without it; anything else
+  is shown read-only.
+- **`airpocket setup`**: checks the Mac first and stops before changing
+  anything if something is missing, then installs the hooks for Claude Code
+  and Codex (merged into their settings, with a backup), a login item, the app
+  published inside the tailnet with `tailscale serve`, optional `claude` and
+  `codex` shell aliases, and a pairing code with its QR. `--dry-run` prints
+  the plan.
+- **`airpocket doctor`**: checks the install and says what to do about each
+  problem. **`airpocket uninstall`** removes what setup added, taking only its
+  own entries out of the agents' config files.
+- **Pairing** with a six-digit code or its QR, one token per phone and per
+  Mac, stored on the Mac only as a hash. `airpocket devices` lists paired
+  phones and `airpocket revoke` cuts one off at once.
+- **A home-screen web app** with no App Store. It still opens when the Mac
+  that served it is asleep, follows Reduce Motion and Reduce Transparency, and
+  ships its own fonts.
+- **Security documentation**: [SECURITY.md](SECURITY.md) for reporting a
+  problem, and a threat model and review checklist in the repository's `docs`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oncel Ozgul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,246 @@
-# Temporary Holding Version
+<h1 align="center"><img src="docs/images/banner.png" width="100%" alt="Airpocket: the dart and the wordmark on a dark chart, over the line &quot;Your agents fly the missions. This is the cockpit.&quot;"></h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="#install-macos">Install</a> ·
+  <a href="https://airpocket.sh/#how">How it works</a> ·
+  <a href="#security-in-one-paragraph">Security</a> ·
+  <a href="https://airpocket.sh/#faq">FAQ</a> ·
+  <a href="https://airpocket.sh">airpocket.sh</a> ·
+  <a href="https://github.com/airpocket-sh/airpocket/releases">Releases</a>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-D7C49E?style=flat-square&labelColor=1B2118" alt="License: MIT"></a>
+  <a href="https://github.com/airpocket-sh/airpocket/actions/workflows/test.yml"><img src="https://github.com/airpocket-sh/airpocket/actions/workflows/test.yml/badge.svg?branch=main" alt="Tests on main"></a>
+  <img src="https://img.shields.io/badge/platform-macOS-D7C49E?style=flat-square&labelColor=1B2118" alt="Platform: macOS">
+  <img src="https://img.shields.io/badge/node-20%2B-D7C49E?style=flat-square&labelColor=1B2118" alt="Node 20 or newer">
+  <img src="https://img.shields.io/badge/dependencies-none-8FD14F?style=flat-square&labelColor=1B2118" alt="Dependencies: none">
+</p>
+
+Your coding agents, on your phone. Every Claude Code and Codex session on every
+one of your Macs, in one list, with the ones waiting on you first. Read the
+conversation, reply, answer questions, switch models, start new sessions and
+open the files they made, from anywhere.
+
+Nothing sits in between: your phone talks to your Macs over your own
+[Tailscale](https://tailscale.com) network. There is no Airpocket server, no
+account and no relay. It works in the terminal you already use. What it needs:
+a Mac with Node 20 or newer and Claude Code or Codex, and Tailscale on the Mac
+and on the phone.
+
+<p align="center"><img src="docs/images/phones.png" width="100%" alt="Three phones running Airpocket. First, the session list: three sessions need you (one asking permission to use Bash, one asking which Stripe API version to target, one finished) above two open ones. Second, a session asking &quot;Do you want to proceed?&quot; with three numbered answers and a reply box. Third, a TypeScript file the agent wrote, open with line numbers."></p>
+
+> **Status: private, work in progress.** Not on npm yet: to try it, install
+> from a clone (below). See [docs/PLAN.md](docs/PLAN.md), and
+> [CONTRIBUTING.md](CONTRIBUTING.md) to send a change.
+
+## What it will do
+
+- **One list** of every session on every paired Mac: needs you, open, earlier.
+- **The conversation**, not the raw terminal: messages, answers, one line per
+  step, updated live, including Codex mid-turn.
+- **Reply and control**: send messages, press keys, pick options on screen,
+  change model, effort and permission mode, compact, resume and more.
+- **Start sessions** in a project, on a new branch or an existing workspace
+  (with Superset).
+- **Open files** a session wrote or linked: text, Markdown, code, images,
+  PDFs, pages, under strict rules.
+- **Send a photo**: a screenshot, a whiteboard, the thing on your desk, from
+  the phone's camera or its library, with or without a message.
+- **A web app**, added to your home screen. No App Store.
+
+<p align="center">
+  <img src="site/shots/mfd1-sessions-one-waiting.png" width="280" alt="The session list for one Mac: under Needs you, a Claude Code session needing permission to use Bash and a Codex session asking which Stripe API version to target; under Open, a Claude Code session working, on Opus 5 with high effort.">
+  &nbsp;
+  <img src="site/shots/mfd3-controls-model-effort.png" width="280" alt="The Controls sheet for a Claude Code session: Opus 5 active and Sonnet 5 picked to apply next, effort set to high, permission mode buttons, and session commands including Compact, Resume and Clear.">
+</p>
+
+## Any terminal
+
+It works in the terminal you already use: Terminal, iTerm2, Ghostty, Warp, a VS
+Code or Cursor pane. The one change is how you start the agent:
+
+```sh
+airpocket run claude          # instead of claude; anything after the name goes to it
+airpocket run codex resume --last
+airpocket attach              # back to one you closed the window on
+```
+
+Setup offers to alias `claude` and `codex` to that, and then you type exactly
+what you typed before. Sessions in Superset or tmux need no change: the phone
+answers them as they are.
+
+<p align="center">
+  <img src="site/shots/mfd2-question-answered.png" width="280" alt="A Claude Code session on the phone, asking before it runs a shell command: &quot;Do you want to proceed?&quot; with the numbered answers Yes; Yes, and don't ask again for npm test commands; and No, and tell Claude what to do differently. A reply box sits underneath.">
+</p>
+
+Why `run` is there: the phone can watch a session from its transcript and hooks
+alone, but to answer one Airpocket has to type into its terminal, and a tmux
+pane or a Superset terminal is what lets it. `run` starts the agent in a tmux
+session of Airpocket's own (its own socket in Airpocket's data folder, never
+your tmux server or `~/.tmux.conf`), tuned to stay out of sight: no status bar,
+no prefix key, Esc with no delay, Shift+Enter, the mouse wheel for scrollback,
+copying to the clipboard. Closing the window doesn't stop the agent: the phone
+can still answer it, and `airpocket attach` brings it back. Inside tmux or
+Superset already, `run` starts the agent there directly.
+
+A session started the plain way, outside all of that, still shows on the phone,
+read-only, with a line saying how to bring it in.
+
+## Install (macOS)
+
+**Airpocket runs on each Mac whose sessions you want to see.** Install it and
+run setup on every one of them, and pair your phone with each. There is no
+shared server and nothing passes between your Macs: the phone keeps one token
+per Mac and asks each one itself.
+
+You need, on each Mac: macOS, Node 20 or newer,
+[Tailscale](https://tailscale.com/download/mac) signed in with **MagicDNS and
+HTTPS certificates turned on for your tailnet**, and Claude Code or Codex. On
+the phone: Tailscale, signed in to the same tailnet. Setup also checks for tmux,
+which `airpocket run` uses (above); if it's missing, `brew install tmux`.
+
+### Which tailnet you land in
+
+Tailscale sorts people by the email domain they sign in with, so signing in
+with a **work address puts you in your company's tailnet**, not one of your
+own. There you are a member: an admin has to approve your device, the admin
+console won't open for you, and MagicDNS and HTTPS certificates — both
+tailnet-wide, both needed here — are someone else's switch to flip. Setup stops
+with that in plain words rather than half-installing.
+
+Signing in with a **personal account** gives you your own tailnet where you are
+the admin, and turning HTTPS certificates on is one switch on the
+[DNS page](https://console.tailscale.com/admin/dns). Either is fine — a shared
+tailnet only needs its admin to do it once, for everyone. Issuing a certificate
+publishes the machine's DNS name in public certificate-transparency logs; what
+it serves stays inside your tailnet.
+
+Sharing a tailnet doesn't share sessions: every Mac still asks the phone for a
+pairing code of its own, and hands out its own token.
+
+### Try it from a clone
+
+Airpocket isn't on npm yet. Until it is, install it from a clone:
+
+```sh
+git clone https://github.com/airpocket-sh/airpocket.git
+cd airpocket
+npm install -g .            # puts the airpocket command on your PATH; no dependencies
+airpocket setup --dry-run   # every change it would make; changes nothing
+airpocket setup
+```
+
+`npm install -g .` links the command to your clone. Setup copies Airpocket
+into its data folder and runs that copy (see
+[Keeping it up to date](#keeping-it-up-to-date)).
+
+Setup checks first and stops with a plain explanation if something is
+missing. Then it:
+
+- adds Airpocket's hooks to `~/.claude/settings.json` and `~/.codex/hooks.json`
+  (or under `$CLAUDE_CONFIG_DIR` and `$CODEX_HOME`). It merges: every other
+  setting and hook stays as it was, a timestamped backup is written next to the
+  file first, and a file that isn't valid JSON is left alone. Running it again
+  adds nothing twice.
+- adds a login item (`~/Library/LaunchAgents/sh.airpocket.service.plist`) that
+  starts Airpocket at login and brings it back after a crash. It runs the copy
+  of Airpocket kept in its data folder, not your clone, so moving or deleting
+  the clone doesn't stop it.
+- publishes the app and its file-only origin inside your tailnet with
+  `tailscale serve` (never `funnel`), on ports nothing else uses: 443 and
+  8443 when they are free.
+- asks whether to add two aliases to your shell profile (`~/.zshrc` or
+  `~/.bash_profile`), so `claude` and `codex` start where the phone can
+  answer them (above). `--alias` or `--no-alias` decides without asking.
+  Marked, backed up first, and removed by uninstall.
+- prints a pairing code and its QR.
+
+Codex asks you to review new hooks the next time it starts: choose to trust
+Airpocket's, or open `/hooks`. A Codex session shows up on the phone once
+you've sent it a first message. In Superset it's different: Superset's `codex`
+wrapper starts Codex with the trust check bypassed, so the hooks run there
+without the review (and the phone's "not trusted yet" line is about Codex
+started anywhere else).
+
+Claude Code picks up the hooks while it runs, so sessions started before setup
+need no restart: each appears the next time you prompt it. Codex reads its
+hooks only when it starts, so restart a Codex session that was running before
+setup. Until then the phone says how many Claude Code and how many Codex
+agents are running that haven't checked in, and whether Codex's hooks still
+need trusting; setup prints the same when it finishes.
+
+```sh
+airpocket doctor      # checks everything, says what to do; exits 1 if something is broken
+airpocket pair        # a new pairing code
+airpocket devices     # paired phones; airpocket revoke <id> cuts one off
+airpocket uninstall   # removes exactly what setup added; asks before deleting paired phones
+```
+
+**Tested so far:** setup, doctor and uninstall against a temporary home folder
+(with the real launchd in a trial), Claude Code end to end with real
+sessions, and Codex against recorded session files and a real Codex's hooks
+(installed, trusted, firing). Codex with real model replies driven from the
+phone has not been run end to end yet. `airpocket run` with a real Claude in a
+hidden terminal window (keys, paste, resize, scrollback, detach and attach).
+
+### Keeping it up to date
+
+```sh
+cd airpocket
+git pull
+airpocket setup
+```
+
+The `airpocket` command runs from your clone, but the service, the hooks and
+the login item run the copy setup made in the data folder. A `git pull` alone
+changes the command and nothing else; running setup again replaces the copy
+and restarts the service on it. Paired phones stay paired; the pairing code
+setup prints at the end can be ignored.
+
+`airpocket doctor` warns when the version the service runs differs from the
+command's. It compares the version numbers in `package.json`, so a pull that
+doesn't change the version passes unnoticed: run setup after every pull.
+
+## Photos
+
+The message box has a photo button. Pick from the library or take one, up to
+four to a message, and send it with or without words.
+
+The phone shrinks each photo to 2200px and re-encodes it before it goes, which
+also drops what the camera wrote into the file, the place it was taken
+included. The Mac keeps it in Airpocket's own data folder
+(`~/Library/Application Support/Airpocket/uploads`, 0600), never in the project
+the agent is working in, and types the path into the session as part of your
+message, so the agent reads it with the tools it already has. Photos are
+deleted after a week, and only the last forty are kept.
+
+Because they sit outside the project, the agent may ask before reading one —
+answer that from the phone like any other prompt. To stop it asking, allow that
+one folder in `~/.claude/settings.json`:
+
+```json
+{ "permissions": { "allow": ["Read(//Users/you/Library/Application Support/Airpocket/uploads/**)"] } }
+```
+
+## Security in one paragraph
+
+Airpocket listens on 127.0.0.1 and is published only inside your tailnet. Each
+phone gets its own token for a one-time pairing code; the Mac keeps only
+hashes. The phone never sends a file path or command text: it names a session
+and an action, and the Mac looks up the rest in its own records. Files are
+limited to what a session made or mentioned, inside its own folder, checked by
+content, and PDFs and pages open from a separate file-only origin through
+two-minute links.
+
+**Know this before you pair.** A paired phone can type anything into your
+agents, including shell commands (in Claude Code and Codex, a message that
+starts with `!` runs as one), and start new sessions. Its token doesn't expire:
+it works until you revoke it on that Mac. `airpocket devices` lists the paired
+phones, and `airpocket revoke <id>` cuts one off at once. Pair only phones you
+control, and revoke a lost one straight away.
+
+## License
+
+MIT. The fonts in `src/public/fonts` (B612, B612 Mono, IBM Plex Sans) are under the
+SIL Open Font License; their licences sit next to them.

package/SECURITY.md

@@ -0,0 +1,114 @@
+# Security policy
+
+Airpocket lets a phone read and type into coding agents on your Macs, so its
+security matters more than its size suggests. Thank you for looking.
+
+## Reporting a vulnerability
+
+**Please don't open a public issue, discussion or pull request for a security
+problem.**
+
+Report it privately through GitHub: on this repository, open the **Security**
+tab and choose **Report a vulnerability**. Only the maintainers can see the
+report and the conversation that follows.
+
+If that route isn't open to you — GitHub only offers it on a public
+repository, and not everyone wants a GitHub account to report a bug — email
+**info@airpocket.sh** instead. It reaches the same people.
+
+A good report says:
+
+- what the problem is, and what someone could do with it;
+- where it is (file, function, route or command);
+- the version or commit you tested;
+- how to see it happen on your own Mac, phone and tailnet.
+
+Leave out real device tokens, pairing codes, hook secrets, tailnet names,
+email addresses and anyone's conversations or files. Replace them with
+placeholders.
+
+## What to expect
+
+- **Within 7 days:** we confirm we received the report.
+- **Within 14 days:** a first assessment: in scope or not, how serious, and
+  what happens next.
+- **Until it's fixed:** an update at least every 14 days.
+- **A fix** as soon as its severity calls for it, released with a GitHub
+  security advisory that describes the problem and the fix.
+- **Disclosure:** please keep the details private until the advisory is out,
+  or 90 days after your report, whichever comes first. If a fix needs longer,
+  we'll ask you and agree on a date together.
+- **Credit** in the advisory, under the name you choose, if you want it.
+
+Airpocket is a free project. There is no bug bounty.
+
+## Supported versions
+
+Only the latest release gets security fixes. Fixes are not backported. Until
+the first release, that means the `main` branch.
+
+## Scope
+
+In scope:
+
+- The Airpocket service: the phone app server and its API, the file-only
+  server and the hook endpoint.
+- The hook (`src/hook.js`), the `airpocket` command, and the setup and
+  uninstall steps once they ship.
+- The phone web app (`src/public`).
+- Anything that breaks a promise in [docs/THREAT-MODEL.md](docs/THREAT-MODEL.md)
+  or in the posture below. For example: reaching the API without a valid
+  token; opening a file outside the file rules; typing into a terminal that
+  isn't the agent's; a token, secret or file's contents in a log; data leaving
+  the user's own machines.
+
+Out of scope:
+
+- A Mac account that is already compromised, including any process running as
+  that user.
+- Physical access to an unlocked phone.
+- What a user's own agent chooses to do.
+- Bugs in Tailscale, Claude Code, Codex, Superset, tmux, macOS or iOS. Please
+  report those to their makers. If Airpocket *uses* one of them unsafely, that
+  is in scope.
+- Setups Airpocket doesn't make: `tailscale funnel`, listening on addresses
+  other than 127.0.0.1, another proxy in front of it.
+- Denial of service by someone already on your tailnet or your Mac.
+- The residual risks already listed in the threat model, unless you show one
+  is worse than written there.
+
+When testing, use only Macs, phones and tailnets that are yours. Don't read,
+change or keep other people's data; if you come across any, stop and tell us.
+We won't pursue anyone who follows this policy in good faith.
+
+## Standing posture
+
+These hold for every release. A change that breaks one of them won't be
+accepted.
+
+- **Tailnet only.** Every server listens on 127.0.0.1. `airpocket setup`
+  publishes the app and the file-only origin with `tailscale serve`, which
+  reaches only devices on your tailnet. Airpocket never uses `tailscale
+  funnel` and never publishes anything to the public internet. The hook
+  endpoint is never published at all.
+- **No cloud.** There is no Airpocket server, relay or hosted service. Your
+  phone talks straight to your Macs over your own Tailscale network.
+- **No account.** Nothing to sign up for. Each phone pairs with each Mac using
+  a short-lived code shown on that Mac, and gets its own token; the Mac keeps
+  only a hash of it.
+- **Nothing leaves your machines.** Airpocket has no telemetry, analytics,
+  crash reporting or update checks, and makes no network requests except
+  between your phone and your Macs. Your conversations, files and tokens stay
+  on your devices. Your agents still talk to their own providers, as they do
+  without Airpocket, and Tailscale's coordination service knows which devices
+  you have, not what they send.
+- **The phone asks, the Mac decides.** The phone names a session and an
+  action. It never sends a file path, a terminal, or the text of a Controls
+  command; the Mac looks those up in its own records and fixed tables.
+- **One way in, one place to land.** The only thing a phone can put on the Mac
+  is a photo for a session, and it lands in Airpocket's own data folder, 0600,
+  never in a project. The bytes have to be an image the agents can read, the
+  phone gets a ref rather than a path, and old photos are swept.
+
+How Airpocket defends each of these, and what it knowingly doesn't, is in
+[docs/THREAT-MODEL.md](docs/THREAT-MODEL.md).

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "airpocket",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Your Claude Code and Codex sessions, from every Mac, on your phone.",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "tailscale",
+    "iphone",
+    "terminal",
+    "agents",
+    "macos"
+  ],
+  "homepage": "https://airpocket.sh",
+  "bugs": {
+    "url": "https://github.com/airpocket-sh/airpocket/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/airpocket-sh/airpocket.git"
+  },
+  "license": "MIT",
+  "author": "Oncel Ozgul",
+  "main": "src/server.js",
+  "bin": {
+    "airpocket": "src/cli.js"
+  },
+  "files": [
+    "src/",
+    "SECURITY.md",
+    "CHANGELOG.md"
+  ],
+  "os": [
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "node --test",
+    "smoke": "node .github/smoke.js"
+  }
+}