pelican-cc 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,149 @@
 # Changelog
 
+## 0.3.0
+
+Every Claude Code session on your computer, on your phone. This release follows a ten-angle audit
+(first run, phone, computer and accessibility, the conversation, Claude Code parity, the server,
+security, the launch, competitors, code quality) and an adversarial review of the result.
+
+### Highlights
+
+- **Phone in one step.** `pelican phone` prints a QR code that opens Pelican on your phone, signed
+  in, once, for two minutes. It finds the address from `tailscale serve`, PELICAN_PUBLIC_URL or your
+  network; with Tailscale it is two commands. The start banner shows the code when it knows the
+  address.
+- **Keeps running.** `pelican service install` (also `status`, `restart`, `uninstall`) starts
+  Pelican at login with launchd or a systemd user service. While Claude works, the computer does not
+  idle to sleep (PELICAN_KEEP_AWAKE=0 turns this off).
+- **Sessions waiting in other apps.** A session waiting for an answer in the terminal, Claude
+  Desktop or VS Code shows "Needs you in the terminal", and your phone gets one notification if the
+  wait lasts about 20 seconds. You answer it in that app.
+- **Approvals as in Claude Code.** "Always allow" says what it saves and where ("Always allow
+  `npm test *` in this project", "Allow all edits this session"), and is not offered when Claude
+  Code says it would allow more than asked. Deny works like Claude Code's No. Cards use Claude
+  Code's wording, name the subagent or MCP server asking, and show hidden characters in commands.
+- **Folders you trust.** The first time Claude Code would start in a folder nobody trusted, and
+  the folder brings programs of its own (hooks, MCP servers, helpers, git filters), Pelican lists
+  them and asks: Trust and start, or Use my settings only.
+- **Much lighter on a phone.** Replies stream as appends (a long answer costs a few percent of
+  the data it did), everything is sent compressed, the conversation loads only when you open one,
+  pictures load when shown, and the session list stays fast with thousands of sessions.
+
+### Changes in behavior
+
+- New sessions start in Auto, unless you pick a mode in Settings (New sessions start with > Mode)
+  or Claude Code's `permissions.defaultMode` sets one; a model without Auto starts in Manual. Bypass
+  is never a default: a branch, an edited earlier prompt or `/clear` from a Bypass session starts in
+  that default mode. A mode picked in a session stays with it.
+- Permission modes carry Claude Code's names: Manual, Accept edits, Plan, Auto, Bypass
+  permissions. A session in Claude Code's Don't ask mode keeps it.
+- Deny with no note stops the turn and waits for you; with a note, Claude carries on with it.
+- Queued messages wait in a strip above the message box, where you can edit or remove them, and go
+  to Claude when the turn ends, each as its own message, so a queued `/compact` or `/model` runs as
+  a command.
+- Stop ends the turn but leaves background agents and commands running, as Esc does in the
+  terminal; each has its own Stop.
+- `/clear`, `/reset` and `/new` open a new session in the same folder.
+- Pages and visuals Claude makes show as still pictures until you tap Run, and only for tool calls
+  that ran.
+- A browser in use stays signed in; 30 days without use sign it out. `pelican token --reset` and
+  `pelican password` apply at once.
+- The Agent SDK, and the Claude Code it brings, is pinned, and the package ships
+  npm-shrinkwrap.json: installs get the tree that was tested. Updating Pelican updates its Claude
+  Code. A second command name, `pelican-cc`, is there for machines where `pelican` is taken.
+- Uploaded attachments are deleted after Claude Code's `cleanupPeriodDays` (30 unless set).
+
+### Sessions and the list
+
+- Sessions with the same folder and title (a scheduled task's runs, a named session's branches)
+  fold into one row, with the earlier ones a tap away.
+- A session whose background commands, subagents or scheduled checks keep running after its turn
+  stays under Active, with "2 tasks" and a steady dot.
+- A turn that ended on a Claude Code error shows "Stopped: not signed in" (or the error's kind)
+  instead of the error as Claude's reply.
+- Titles taken from a prompt fit on about one line; renamed sessions and Claude Code's own titles
+  keep theirs.
+- Archive from the list: swipe a row left on a phone, or use the button on hover, with Undo.
+- Rows are links (Cmd/Ctrl-click opens a new tab), the open session is marked, and long lists load
+  150 rows at a time while search still covers every session.
+- + opens a new chat in your latest project, ready to type; tap the folder to start elsewhere, or
+  make a new folder there (New folder in the folder browser).
+
+### The conversation
+
+- Opening a session lands on its newest message, also with pictures, a chart or an approval
+  waiting. While Claude works the view follows the newest output; a stray tap no longer stops that.
+- Diffs wrap long lines. Code blocks have a bar with the language and Copy. Tool output shows
+  without color codes or error tags. Long prompts fold, and files you sent show as chips.
+- What you decided stays visible: your answers to Claude's questions, plans approved or sent back,
+  steps you denied with your note.
+- The task list shows in full when it changes; in between, progress is one line.
+- Half-written messages are kept per session, with their files, across leaving and reloading.
+- Several approvals come one at a time ("1 of 3") and never push the message box off screen.
+- Drop files anywhere on the conversation to attach them.
+- A session another app has looks the same everywhere: the header says "Working in the terminal"
+  or "Needs you in Claude Desktop", each case is explained once, and the message box warns that
+  sending starts a second Claude.
+- API failures show once, in plain words (overloaded, too long: send /compact, not signed in,
+  usage limit and when it resets).
+- Hook feedback, warnings and local command output appear as notes, and stay after the turn and a
+  reload; terminal-only commands are left out of the / list.
+- MCP servers that ask for input get a card to answer instead of being declined.
+- Plans can be approved into Auto, Accept edits or Manual, or sent back with Keep planning.
+- Check-ins Claude schedules (/loop, reminders, session crons) are listed, and Claude keeps running
+  for them and for background work.
+- The cost shown is that turn's own, not the running total, and none on a subscription.
+- Notifications say what Claude wants (the command, the file, the question) or the reply's first
+  line.
+- On screens 1440px and wider, Changes and files sits beside the conversation (Cmd/Ctrl+Shift+D,
+  as in Claude Desktop). Comment on diff lines and add the comments to your message.
+
+### Keyboard and accessibility
+
+- Enter that confirms a Chinese, Japanese or Korean candidate never sends, Safari included.
+  Cmd/Ctrl+Enter always sends. Esc stops Claude. Cmd/Ctrl+K searches sessions. Cmd/Ctrl+/ lists
+  the keys.
+- Sheets are real dialogs: focus moves in and back, one Esc closes one, and on a phone you drag a
+  sheet down to close it.
+- Screen readers hear approvals, questions, plans, replies, failures and the connection state;
+  turns have headings and pictures have names.
+- Grey text and status words pass WCAG AA contrast in both themes; Reduce motion stops the pulsing.
+- On iPhone the message box stays above the keyboard and fields no longer make Safari zoom.
+
+### Reliability
+
+- Nothing a request or an unreadable transcript does crashes the server any more.
+- A chat no longer stays on "Working" after Claude finished while the phone slept or Pelican
+  restarted. Dead connections are noticed and replaced; coming back to the page catches up at once.
+- When the computer cannot be reached, one quiet line says so, with Retry.
+- A `!` command that leaves something running in the background returns at once.
+- A named pipe or device file in a project can no longer freeze Pelican.
+- On Linux with Node 24, a Claude Code that Node runs (Node names its main thread MainThread) is
+  recognized again as working in another app.
+- A signed-out or missing Claude Code is detected and said in Pelican's words; the banner and
+  Settings > About say which Claude Code runs, and when your own `claude` is newer.
+
+### Security
+
+- Folder trust, above. Typing `/` or `@` in an untrusted folder runs nothing of the repository's.
+- The app's own page has a script and connect policy; previews run their scripts only after Run.
+- Notifications stop on every device after a token or password change, and on sign-out.
+- `pelican service` never copies secrets such as API keys into the service.
+
+### Site, docs and project
+
+- The README and website were redesigned around the one line, the live demo, how it works, a
+  dated comparison with Remote Control, Happy and HAPI, Yep Anywhere, CloudCLI and SSH with tmux,
+  and answers to the questions launch threads ask (plan terms, Remote Control, tmux, sleep, cost
+  and telemetry, size).
+- The docs cover everything above and add a Claude Code coverage table, Keep it running, Update
+  and remove, and Folders you trust.
+- The live demo plays out the waiting approval and answers messages calmly.
+- CI runs the app and the site in a real browser on every change, on Node 22.12, 24 and 26 and on
+  macOS; the site publishes only after CI passes. Release candidates publish as `next`.
+- Each new Agent SDK arrives as its own pull request with a report of what changed upstream, and a
+  weekly issue lists Claude Code updates to consider.
+
 ## 0.2.3
 
 - A session keeps its own model, effort, speed, Ultracode and permission mode, Bypass included:

package/README.md

@@ -5,12 +5,12 @@
 <h1 align="center">Pelican</h1>
 
 <p align="center">
-  <b>Claude Code, in your pocket.</b><br>
-  A phone-first web app for the Claude Code on your computer. Follow every session live, answer Claude, approve its edits.
+  <b>Every Claude Code session on your computer, on your phone.</b><br>
+  No wrapper, no relay, no account.
 </p>
 
 <p align="center">
-  <a href="https://ki-seki.github.io/pelican/demo/"><b>Live demo</b></a> ·
+  <a href="https://ki-seki.github.io/pelican/demo/"><b>Try the live demo</b></a> ·
   <a href="https://ki-seki.github.io/pelican/">Website</a> ·
   <a href="https://ki-seki.github.io/pelican/docs.html">Docs</a>
 </p>
@@ -24,57 +24,140 @@
 <a href="https://ki-seki.github.io/pelican/demo/">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Ki-Seki/pelican/main/docs/shots/phone-dark.png">
-  <img alt="Pelican on a phone: the session list, a session waiting for approval of an edit, and a chart Claude drew" src="https://raw.githubusercontent.com/Ki-Seki/pelican/main/docs/shots/phone-light.png">
+  <img alt="Pelican on a phone: the session list, an edit waiting for approval with its diff, and a chart Claude drew" src="https://raw.githubusercontent.com/Ki-Seki/pelican/main/docs/shots/phone-light.png">
 </picture>
 </a>
 
-## Why Pelican
-
-- **Every session, wherever you started it.** The terminal, Claude Desktop, your editor: Pelican
-  reads Claude Code's own transcripts, so every session is there, live while it runs, with its
-  whole history back past each compaction. No wrapper command, no flag to remember.
-- **Nothing in between.** One small process on your computer: no account, no relay server, no copy
-  of your sessions. Reach it over Tailscale, an SSH tunnel or your own proxy.
-- **All of Claude Code.** Approvals with the diff, steer or queue while Claude works, `!` commands,
-  changes and files, rewind code, branches, subagents, MCP servers, usage limits, every model and
-  mode, `/` commands and `@` files. Charts Claude draws and pages it writes render right in the
-  conversation. It runs on the official Agent SDK, so your login, settings, `CLAUDE.md`, skills and
-  MCP servers apply.
-- **Made for a phone.** Calm and quick with one hand. A notification when Claude needs you,
-  dictation, and a Home Screen icon that opens it like an app.
+<p align="center"><sub>The live demo is the real app with made-up sessions, in your browser. Nothing to install.</sub></p>
+
+Pelican is one small server next to Claude Code. It reads Claude Code's own transcripts, so the
+sessions you started in the terminal, Claude Desktop or your editor are all there, live, with their
+whole history. It continues them through the official Agent SDK, so your login, settings,
+`CLAUDE.md`, skills and MCP servers apply. Your phone reaches it over Tailscale or an SSH tunnel:
+nothing sits in between.
+
+## Install
+
+```sh
+npm install -g pelican-cc
+pelican
+```
+
+On the computer where you use Claude Code, with Node 22.12 or newer and Claude Code signed in, on
+macOS or Linux. `pelican` prints the link that signs this browser in. The install is about 150 MB,
+most of it the copy of Claude Code that the Agent SDK brings. The command is also called
+`pelican-cc`, for computers where Python's Pelican has `pelican`.
+
+## On your phone
+
+```sh
+tailscale serve --bg 7860
+pelican phone
+```
+
+With [Tailscale](https://tailscale.com) on the computer and the phone, `tailscale serve` gives
+Pelican a private HTTPS address, and `pelican phone` shows a QR code for it. Scan it with the
+phone's camera: Pelican opens there, signed in. `pelican service install` keeps Pelican running.
+The docs cover [an SSH tunnel or your own proxy](https://ki-seki.github.io/pelican/docs.html#phone).
+
+## What it does
+
+- **Every session, wherever you started it.** Live while it runs, with its whole history back past
+  every compaction. When another app is working on one, or waits for you there, Pelican says which
+  app; once it is idle, continue it here.
+- **All of Claude Code.** Approvals with the diff, plans and questions, steer or queue while Claude
+  works, `!` commands, `/` commands and skills, `@` files, every model and permission mode, rewind
+  and branch, subagents and background tasks, MCP servers and usage limits.
+- **What Claude makes, in place.** Charts and diagrams Claude draws and pages it writes show in the
+  conversation, as still pictures until you tap Run.
+- **The changes beside the chat.** Every changed file with its diff. Tap a line to comment, and
+  your comments go into the next message.
+- **Made for a phone, good on a computer.** One hand, dictation, a notification when Claude needs
+  you or finishes, and a Home Screen icon. On a wide screen, the list, the conversation and the
+  changes sit side by side.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/Ki-Seki/pelican/main/docs/shots/tour.gif" width="320" alt="A tour of Pelican on a phone: a chart and a page Claude made, rendered in place; an edit waiting for approval with its diff; a session another app is running">
 </p>
 
-## Quick start
+## Compared with
 
-```bash
-npx pelican-cc --demo          # made-up sessions; nothing of yours involved
-npm install -g pelican-cc      # Node 22.12+, with Claude Code signed in
-pelican                        # prints the link that signs you in: http://localhost:7860/?token=…
-```
+As each project documents it, checked on 5 November 2026:
+
+| | Your sessions | Between phone and computer | Agents | License |
+| --- | --- | --- | --- | --- |
+| **Pelican** | All of them, from any app, with their whole history | Nothing: Tailscale, an SSH tunnel or your proxy | Claude Code | MIT |
+| [Remote Control](https://code.claude.com/docs/en/remote-control) | Those with Remote Control turned on; Claude plans only | Anthropic's servers, which keep the transcript while connected | Claude Code | Part of Claude Code |
+| [Yep Anywhere](https://github.com/kzahel/yepanywhere) | Resumes those from the CLI, VS Code and desktop apps | Nothing, or its end-to-end encrypted relay | Claude Code, Codex | MIT |
+| [Happy](https://github.com/slopus/happy), [HAPI](https://github.com/tiann/hapi) | Those started in Happy or HAPI | An end-to-end encrypted relay, or with HAPI your own tunnel | Claude Code, Codex and more | MIT, AGPL-3.0 |
+| [CloudCLI](https://github.com/siteboon/claudecodeui) | Every session in `~/.claude` | Nothing on your network, or CloudCLI Cloud | Claude Code, Cursor CLI, Codex | AGPL-3.0 |
+| SSH and tmux | The ones running in tmux | Nothing | Any | |
+
+Remote Control can answer a prompt waiting in your terminal; Pelican cannot. More in
+[the docs](https://ki-seki.github.io/pelican/docs.html#compare).
+
+## Claude Code coverage
+
+Pelican runs Claude Code itself, so your settings, `CLAUDE.md`, hooks, skills, subagents and MCP
+servers work as they do in the terminal, and so does any login: a Claude plan, an API key, Bedrock,
+Google Cloud or Microsoft Foundry. What Pelican does not do: Remote Control, cloud sessions, a
+worktree for each new session, side questions (`/btw`), a terminal of its own, or editing files by
+hand. [The full table](https://ki-seki.github.io/pelican/docs.html#coverage) goes through Claude
+Code's features one by one.
+
+## Security
+
+Whoever can use Pelican can run commands as you, so:
+
+- It listens on `127.0.0.1`, and every browser signs in, also on this computer: with the link it
+  prints, a QR code that works once, or a password.
+- Requests must come from Pelican's own page, under a host name it knows: no cross-site requests,
+  no DNS rebinding, no framing by other sites.
+- What Claude writes renders in a sandboxed frame that cannot reach Pelican, as a still picture
+  until you tap Run.
+- A folder runs nothing of its own, such as hooks or MCP servers, until you trust it.
+
+The whole model is in [SECURITY.md](SECURITY.md).
+
+## Questions
+
+**Does it work with my Claude plan?** Pelican runs Anthropic's own Claude Code, unmodified, on your
+computer, signed in the way you signed in to `claude`; it never sees, stores or forwards your
+credentials, and it is for your own use. Signed in with a plan, what you send from Pelican is Agent
+SDK usage and draws from your plan's limits, as
+[Anthropic's help center](https://support.claude.com/en/articles/15036540) says (checked on
+5 November 2026); the rules are under
+[authentication and credential use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use).
+
+**Why not Remote Control?** Use it if you are on a Claude plan and want to answer, from your phone,
+the prompt waiting in your terminal: Pelican cannot. Pelican shows every session without turning
+anything on, keeps nothing on anyone's servers, and works with any login, API keys and cloud
+providers included.
+
+**Why not SSH and tmux?** That works. Pelican is for what a terminal on a phone does badly: long
+transcripts, diffs, approvals in one tap, notifications, charts and pages, and history across
+compactions.
 
-Then [use it from your phone](https://ki-seki.github.io/pelican/docs.html#phone); with Tailscale it
-takes two commands.
+**What if my computer sleeps?** A computer that is asleep runs nothing. While Claude works, Pelican
+keeps it from going to sleep on its own; to reach Pelican at any time, keep the computer awake, as
+[the docs](https://ki-seki.github.io/pelican/docs.html#running) show.
 
-## Docs
+**Does it cost anything, or phone home?** No. Pelican is free and MIT licensed, with no account and
+no telemetry. It talks to your browser and, for notifications, to the browser's push service, with
+the content encrypted.
 
-[Using Pelican](https://ki-seki.github.io/pelican/docs.html#using) ·
-[configuration](https://ki-seki.github.io/pelican/docs.html#config) ·
-[security](https://ki-seki.github.io/pelican/docs.html#security) ·
-[how it works](https://ki-seki.github.io/pelican/docs.html#how) ·
-[compared with Remote Control, Happy and CloudCLI](https://ki-seki.github.io/pelican/docs.html#compare)
+[More questions](https://ki-seki.github.io/pelican/docs.html#faq)
 
 ## Contributing
 
-```bash
-npm ci && npm run dev    # the server and the web app, both reloading on change
-npm test && npm run typecheck
+```sh
+npm ci
+npm run dev
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports go through
-[SECURITY.md](SECURITY.md).
+`npm run dev` runs the server and the web app, both reloading on change; `npm test` and
+`npm run typecheck` check a change. See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports go
+through [SECURITY.md](SECURITY.md).
 
 ## License