peekme 0.2.1

package/.gitignore

@@ -0,0 +1,2 @@
+/node_modules
+

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+## 0.2.1 (2026-09-28)
+
+- You don't need Rust any more. peekme can be installed with npm (`npm i -g peekme`), with
+  Homebrew (`brew install gregorybolshakov/tap/peekme`) or with a shell script. Each release has
+  ready binaries for Linux and macOS, on x86_64 and ARM.
+- Ctrl+Z works when peekme was started through another program, like the npm launcher. Before,
+  the terminal could wait forever.
+
+## 0.2.0 (2026-09-28)
+
+- peekme works with Claude Code too. Type `claude` as always, select text, press Alt+P.
+  `peekme install` now hooks `claude` next to `codex`. If you installed 0.1, run
+  `peekme install` once more.
+- Claude Code explanations come from `claude -p` on Haiku with your Claude Code login. The
+  session is not saved. The context comes from the running session's transcript, and Alt+P
+  again sends the whole conversation (after asking, when it is big).
+- In Claude Code's full screen mode peekme reads the selection from the OSC 52 copy Claude sends
+  when you release the mouse. In the classic mode it reads the X11 PRIMARY selection.
+- Claude's input line stays live under the box, as with Codex. Ctrl+Z works with Claude too.
+- The box is never drawn in the middle of an escape sequence from the agent. Before, if the
+  agent's output stopped inside one (a window title, say), part of it could show as text.
+- While an explanation streams in, the box is redrawn at most about 30 times a second. This
+  sends much less to the terminal.
+- `peekme doctor` checks both agents. Plain `peekme` runs Codex, or Claude Code when only that
+  is installed.
+
+## 0.1.3 (2026-09-27)
+
+- peekme uses the shared Codex server that Codex 0.157 runs in the background, instead of
+  starting its own. A session now costs a few MB instead of about 250 MB. The connection is
+  made on the first Alt+P and made again if it drops. Without the shared server, peekme starts
+  its own server as before. `PEEKME_OWN_SERVER=1` forces that.
+- Alt+P again on a long chat shows the size first. Above about 40k tokens it asks for one more
+  Alt+P before it sends the whole conversation.
+
+## 0.1.2 (2026-09-27)
+
+- Works with Codex 0.157, which draws full screen and handles the mouse itself. peekme uses the
+  text Codex highlights when you drag. Moving the mouse no longer closes the box, the mouse
+  wheel scrolls it, and a click closes it and still reaches Codex.
+- The Codex input line stays live under the box in full screen too, and the box closes by
+  itself when Codex asks for approval.
+
+## 0.1.1 (2026-09-27)
+
+- Text in the box is cleaned before it is drawn. The explanation, the selected text and error
+  messages can no longer send terminal control sequences, for example one that writes your
+  clipboard, or characters that reverse the order of the text.
+
+## 0.1.0 (2026-09-26)
+
+- `peekme install` makes `codex` open with peekme. It adds a shell function `codex` and a
+  `codex` link at the front of PATH. Aliases and scripts that call `codex` keep working.
+  `peekme uninstall` removes it and leaves your files as they were. `peekme doctor` checks the
+  setup and says what is in the way.
+- The first plain `peekme` run asks once if it should set this up.
+- Only Codex's interactive screen gets peekme. `codex exec`, `login`, `mcp` and the other
+  subcommands, and output to a pipe or a file, run plain Codex directly.
+- peekme never wraps itself twice.
+- Ctrl+Z works. Codex stops, you get your shell back, and `fg` brings it back. Before, Ctrl+Z
+  did nothing inside peekme.
+- The Codex input line and status line stay live while the box is open. You can type, and
+  Enter sends the message and closes the box. If Codex needs more room, for example for an
+  approval question, the box closes by itself.
+- If peekme can't start its terminal, it starts Codex directly. If something inside peekme
+  fails later, it logs the error, puts the screen back and keeps passing Codex through.
+  The log is in `~/.local/state/peekme/peekme.log`.
+- The box gets smaller when the explanation is complete, so it takes only the rows it needs.
+- A comma or a bracket after styled text no longer starts a new line in the box.
+- The terminal cursor is hidden while the box is open. Before, it could show inside the box text.
+
+## 0.0.1 (2026-09-26)
+
+First working version.
+
+- Runs Codex (or any command) in a pseudo-terminal. Output goes to the terminal unchanged and is
+  also kept in a terminal emulator in memory.
+- Alt+P explains the text selected with the mouse (X11 PRIMARY selection). The box opens under
+  or above the text without clearing the screen. Works with the kitty keyboard protocol and with
+  any keyboard layout.
+- Esc restores the screen from a copy and then sends the Codex output that arrived meanwhile.
+- Explanations come from `codex app-server` with a temporary thread on the account's fast model,
+  so no API key is needed.
+- The model gets the text around the selection with the selection marked, the request it
+  answers, a short list of earlier requests and earlier uses of the same words.
+- Alt+P again on the same selection explains with the whole conversation.

package/LICENSE-APACHE

@@ -0,0 +1,176 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gregory Bolshakov
+
+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

@@ -0,0 +1,196 @@
+# peekme
+
+Peek me. Pick me. Select text in [Codex CLI](https://github.com/openai/codex) or
+[Claude Code](https://github.com/anthropics/claude-code) output, press **Alt+P**, and a short
+explanation opens right next to that text, inside the terminal. The other lines move to make
+room, like Peek in VS Code. Esc closes it and the screen is exactly as before.
+
+![peekme demo: type codex, ask a question, select "noisy commits" in the answer, press Alt+P, read the explanation, press Esc](https://raw.githubusercontent.com/GregoryBolshakov/peekme/main/docs/demo.gif)
+
+The explanation comes from a small, fast model and it knows the conversation. If you select
+"its split panes" in an answer that recommends Kitty, it tells you it is about Kitty.
+
+Status: 0.2.1. Tested on Linux with X11 and bash, with Codex 0.157 and Claude Code 2.1.283.
+
+## Install
+
+You need Codex CLI or Claude Code (logged in). Both is fine too. Then install peekme in one of
+these ways and run `peekme install`:
+
+```
+npm i -g peekme                               # you have npm already if you installed an agent with it
+brew install gregorybolshakov/tap/peekme      # Homebrew, on macOS or Linux
+cargo install peekme                          # builds it with Rust
+peekme install
+```
+
+Without npm, Homebrew or Rust, the script from the
+[latest release](https://github.com/GregoryBolshakov/peekme/releases/latest) puts peekme in
+`~/.local/bin`:
+
+```
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/GregoryBolshakov/peekme/releases/latest/download/peekme-installer.sh | sh
+```
+
+Ready binaries are there too, for Linux and macOS on x86_64 and ARM. macOS is not tested yet.
+
+After this, `codex` and `claude` open with peekme in every new terminal. You keep typing
+`codex` or `claude`, and your aliases and scripts that call them keep working. `peekme install`
+adds a short, marked block to your `~/.bashrc` or `~/.zshrc` (for fish, a file in
+`~/.config/fish/conf.d`). If you install one of the agents later, it gets peekme too.
+
+```
+peekme doctor      # check the setup, and see what is in the way if something is
+peekme uninstall   # remove the block, your files are as before
+command codex      # run plain Codex once
+command claude     # run plain Claude Code once
+```
+
+The first time you run `peekme` on its own, it asks if it should do `peekme install` for you.
+
+Upgrading from 0.1: run `peekme install` once more, so that `claude` gets peekme too.
+
+## Use
+
+Start Codex or Claude Code as always. Select text with the mouse as you normally do, then press
+Alt+P. When the agent draws full screen (Codex since 0.157, Claude Code with
+`"tui": "fullscreen"`), it makes the selection itself, and peekme uses that selection.
+
+| Key | When | What it does |
+|---|---|---|
+| Alt+P | any time | explain the selected text |
+| Alt+P again | box is open, same selection | explain again using the whole conversation |
+| PgUp / PgDn, mouse wheel | box is open | scroll a long explanation |
+| Esc | box is open | close the box |
+| typing | box is open | goes to the agent's input line, the box stays open |
+| Enter | box is open | sends your message and closes the box |
+
+In Claude Code, Alt+P opens the model picker. With peekme it explains the selection instead.
+`/model` still opens the model picker.
+
+No API key is needed. peekme asks the agent's own CLI, with your existing login:
+
+- Codex: its `app-server`, on a temporary thread that is not saved. Since Codex 0.157 a shared
+  Codex server runs in the background, and peekme uses it, so it adds only a few MB of memory.
+  Without that server it starts its own `codex app-server`, which takes about 250 MB.
+- Claude Code: `claude -p` on Haiku, without tools and without saving the session, so nothing
+  appears in `/resume`. After the first explanation one `claude -p` waits in the background for
+  the next one, so it starts in about half a second. It takes about 210 MB.
+
+It does use your plan, a little for each explanation. Nothing starts before the first Alt+P.
+
+Only the interactive screen gets peekme: `codex`, `codex "prompt"`, `codex resume`,
+`codex fork`, and `claude`, `claude "prompt"`, `claude --resume`, `claude -c`. Commands like
+`codex exec`, `codex mcp`, `claude -p` or `claude mcp`, and anything with output going to a pipe
+or a file, run the agent directly.
+
+## How it works
+
+The agent runs in a pseudo-terminal. Its output goes to your terminal unchanged, and the same
+bytes also go to a terminal emulator in memory (`alacritty_terminal`). So peekme always knows
+what is on your screen.
+
+On Alt+P it takes the selection and finds it on the screen:
+
+- Codex full screen: the text Codex highlighted.
+- Claude Code full screen: Claude copies the selection with an OSC 52 escape sequence when you
+  release the mouse. peekme reads the text from that sequence as it passes through, and knows
+  where the drag ended. This also works over SSH.
+- Otherwise: your terminal's mouse selection (the X11 PRIMARY selection).
+
+Then it redraws only the rows next to the selection, with the box between them. Nothing is
+cleared and there is no switch to another screen, so there is no flicker. The agent's input
+line and status line under the box keep updating, so you can type while you read. Other output
+that arrives while the box is open is kept aside.
+
+On Esc it draws those rows again from a copy taken when the box opened. After that it sends the
+kept output, so the terminal ends in the same state as if the box never existed. Tests check
+this cell by cell on real Codex and Claude Code output.
+
+### What the model gets
+
+A few words alone are not enough ("Desktop app", which one?). The whole chat is too much and too
+slow. So the model gets small parts, each with a size limit:
+
+1. One line saying which agent this is and in which directory. This is enough for text from the
+   agent itself, like the startup tips.
+2. The text around the selection, with the selection marked in place like `⟦this⟧`. peekme
+   finds it in the conversation by searching for the selection together with the words next to
+   it on screen. This way it finds the right place when the same words appear many times. If the
+   text is not in the conversation, it uses the screen.
+3. Your request that this text answers, and one line for each of your earlier requests.
+4. The first places in the conversation where the same words were used before.
+
+The conversation comes from Codex's app-server, or from Claude Code's session transcript in
+`~/.claude/projects` (peekme knows which one, because Claude registers its process id).
+
+Usually this is 1 to 7 KB of text. When it is not enough, press Alt+P again and the model gets
+the whole conversation. A long chat can be 5 to 30 times bigger than a normal explanation, so
+above about 40k tokens peekme shows the size first and sends it only when you press Alt+P once
+more.
+
+## Settings
+
+| Variable | Meaning |
+|---|---|
+| `PEEKME_MODEL` | model for Codex explanations. Default is the model your account lists as fast |
+| `PEEKME_CODEX_BIN` | codex binary to use for explanations. Default is `codex` |
+| `PEEKME_OWN_SERVER` | set to 1 to start peekme's own `codex app-server` instead of using the shared one |
+| `PEEKME_CLAUDE_MODEL` | model for Claude Code explanations. Default is `haiku` |
+| `PEEKME_CLAUDE_BIN` | claude binary to use for explanations. Default is `claude` |
+| `PEEKME_SELECTION` | use this text instead of the mouse selection, for testing |
+
+### How `codex` and `claude` get peekme
+
+`peekme install` does two things:
+
+1. It defines shell functions `codex` and `claude` in your shell setup. A function wins over
+   anything on PATH, so it keeps working when nvm, mise, Homebrew or an agent's installer
+   change PATH later. Aliases that call `codex` or `claude` go through it too.
+2. It puts `codex` and `claude` links to peekme in `~/.local/share/peekme/bin` at the front of
+   PATH, so scripts that run them also get peekme. If some tool puts its own directory in front
+   of it later, only scripts lose peekme, and `peekme doctor` tells you which directory it is.
+
+Both find the real agent on PATH themselves, so updating the agent changes nothing. If you
+remove peekme, the functions fall back to plain `codex` and `claude`.
+
+To use peekme with another program, run `peekme -- COMMAND`.
+
+## Limits
+
+- Only text that is on screen now. Text that scrolled up into the terminal history can't be
+  selected yet.
+- In full screen mode selection works anywhere, also over SSH, because peekme reads the
+  selection from the agent. Otherwise peekme needs the terminal's selection, which it reads on
+  Linux with X11 only. On Wayland it works through XWayland, and on macOS it reads the
+  clipboard, not tested.
+- Claude Code full screen: if `copyOnSelect` is off, Claude does not report the selection. Then
+  only a Shift+drag selection works (read from X11 PRIMARY).
+- An explanation takes about 1 to 2 seconds to start arriving.
+- `peekme install` is tested with bash. zsh uses the same block and should work the same way,
+  but it is not tested yet. The fish setup is not tested either.
+
+## Development
+
+```
+cargo test
+cargo clippy --all-targets
+cargo run --example vtdump -- capture.bin 120 40 [offset]
+cargo run --example peek_text -- "<screen text>" "<selection>" [--deep] [--claude [--pid PID]]
+python3 spikes/capture.py out.bin 120 40 "<script>" -- peekme claude
+python3 spikes/flicker_test.py
+python3 spikes/explain_probe.py
+```
+
+`vtdump` replays a captured byte stream and prints the screen. `peek_text` runs one explanation
+without a terminal and prints the exact prompt. `capture.py` runs a command in a pseudo-terminal,
+sends keys and mouse events from a script and saves everything it prints. `flicker_test.py`
+shows if your terminal flickers when a program switches screens. `explain_probe.py` makes one
+explanation request to `codex app-server` and prints timings.
+
+Each agent has its own folder in `src/` (`codex/`, `claude/`): how its selection is read, where
+its conversation comes from, and which model explains. The rest is shared.
+
+## License
+
+MIT or Apache-2.0, at your choice.

package/binary-install.js

@@ -0,0 +1,348 @@
+const {
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  mkdtemp,
+  rmSync,
+} = require("fs");
+const { join, sep } = require("path");
+const { spawnSync } = require("child_process");
+const { tmpdir } = require("os");
+
+const https = require("node:https");
+const http = require("node:http");
+
+const tmpDir = tmpdir();
+
+const error = (msg) => {
+  console.error(msg);
+  process.exit(1);
+};
+
+function getProxyForUrl(urlString) {
+  const url = new URL(urlString);
+  const isHttps = url.protocol === "https:";
+
+  const noProxy = process.env.NO_PROXY || process.env.no_proxy || "";
+  if (noProxy === "*") return null;
+  if (noProxy) {
+    const hostname = url.hostname.toLowerCase();
+    const noProxyList = noProxy.split(",").map((s) => s.trim().toLowerCase());
+    for (const entry of noProxyList) {
+      if (hostname === entry || hostname.endsWith("." + entry)) {
+        return null;
+      }
+    }
+  }
+
+  const proxyEnv = isHttps
+    ? process.env.HTTPS_PROXY || process.env.https_proxy
+    : process.env.HTTP_PROXY || process.env.http_proxy;
+
+  if (!proxyEnv) return null;
+
+  const proxyUrl = new URL(proxyEnv);
+
+  let auth = null;
+  if (proxyUrl.username || proxyUrl.password) {
+    auth = `${proxyUrl.username}:${proxyUrl.password}`;
+  }
+
+  return {
+    hostname: proxyUrl.hostname,
+    port: proxyUrl.port || (proxyUrl.protocol === "https:" ? 443 : 80),
+    auth: auth,
+  };
+}
+
+function connectThroughProxy(proxy, target) {
+  return new Promise((resolve, reject) => {
+    const headers = {};
+    if (proxy.auth) {
+      headers["Proxy-Authorization"] =
+        "Basic " + Buffer.from(proxy.auth).toString("base64");
+    }
+
+    const connectReq = http.request({
+      hostname: proxy.hostname,
+      port: proxy.port,
+      method: "CONNECT",
+      path: `${target.hostname}:${target.port || 443}`,
+      headers,
+    });
+    connectReq.on("connect", (res, socket) => {
+      if (res.statusCode === 200) {
+        resolve(socket);
+      } else {
+        reject(new Error(`Proxy CONNECT failed with status ${res.statusCode}`));
+      }
+    });
+    connectReq.on("error", reject);
+    connectReq.end();
+  });
+}
+
+function download(urlString, maxRedirects) {
+  if (maxRedirects === undefined) maxRedirects = 5;
+  return new Promise((resolve, reject) => {
+    if (maxRedirects < 0) {
+      return reject(new Error("Too many redirects"));
+    }
+
+    const parsed = new URL(urlString);
+    const isHttps = parsed.protocol === "https:";
+    const mod = isHttps ? https : http;
+    const proxy = getProxyForUrl(urlString);
+
+    const doRequest = (extraOptions) => {
+      const options = Object.assign(
+        {
+          hostname: parsed.hostname,
+          port: parsed.port || (isHttps ? 443 : 80),
+          path: parsed.pathname + parsed.search,
+          method: "GET",
+          headers: { "User-Agent": "cargo-dist-npm-installer" },
+        },
+        extraOptions || {},
+      );
+
+      if (proxy && !isHttps) {
+        // HTTP through HTTP proxy: request the full URL via the proxy
+        options.hostname = proxy.hostname;
+        options.port = proxy.port;
+        options.path = urlString;
+        if (proxy.auth) {
+          options.headers["Proxy-Authorization"] =
+            "Basic " + Buffer.from(proxy.auth).toString("base64");
+        }
+      }
+
+      const req = mod.request(options, (res) => {
+        if (
+          res.statusCode >= 300 &&
+          res.statusCode < 400 &&
+          res.headers.location
+        ) {
+          res.resume();
+          const nextUrl = new URL(res.headers.location, urlString).toString();
+          return download(nextUrl, maxRedirects - 1).then(resolve, reject);
+        }
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          res.resume();
+          return reject(new Error(`HTTP ${res.statusCode} from ${urlString}`));
+        }
+        resolve(res);
+      });
+      req.on("error", reject);
+      req.end();
+    };
+
+    if (proxy && isHttps) {
+      connectThroughProxy(proxy, parsed).then(
+        (socket) => doRequest({ socket, agent: false }),
+        reject,
+      );
+    } else {
+      doRequest();
+    }
+  });
+}
+
+class Package {
+  constructor(platform, name, url, filename, zipExt, binaries) {
+    let errors = [];
+    if (typeof url !== "string") {
+      errors.push("url must be a string");
+    } else {
+      try {
+        new URL(url);
+      } catch (e) {
+        errors.push(e);
+      }
+    }
+    if (name && typeof name !== "string") {
+      errors.push("package name must be a string");
+    }
+    if (!name) {
+      errors.push("You must specify the name of your package");
+    }
+    if (binaries && typeof binaries !== "object") {
+      errors.push("binaries must be a string => string map");
+    }
+    if (!binaries) {
+      errors.push("You must specify the binaries in the package");
+    }
+
+    if (errors.length > 0) {
+      let errorMsg =
+        "One or more of the parameters you passed to the Binary constructor are invalid:\n";
+      errors.forEach((error) => {
+        errorMsg += error;
+      });
+      errorMsg +=
+        '\n\nCorrect usage: new Package("my-binary", "https://example.com/binary/download.tar.gz", {"my-binary": "my-binary"})';
+      error(errorMsg);
+    }
+
+    this.platform = platform;
+    this.url = url;
+    this.name = name;
+    this.filename = filename;
+    this.zipExt = zipExt;
+    this.installDirectory = join(__dirname, "node_modules", ".bin_real");
+    this.binaries = binaries;
+
+    if (!existsSync(this.installDirectory)) {
+      mkdirSync(this.installDirectory, { recursive: true });
+    }
+  }
+
+  exists() {
+    for (const binaryName in this.binaries) {
+      const binRelPath = this.binaries[binaryName];
+      const binPath = join(this.installDirectory, binRelPath);
+      if (!existsSync(binPath)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  install(suppressLogs = false) {
+    if (this.exists()) {
+      if (!suppressLogs) {
+        console.error(
+          `${this.name} is already installed, skipping installation.`,
+        );
+      }
+      return Promise.resolve();
+    }
+
+    try {
+      rmSync(this.installDirectory, { recursive: true, force: true });
+    } catch {
+      // ignore - directory may not exist
+    }
+
+    mkdirSync(this.installDirectory, { recursive: true });
+
+    if (!suppressLogs) {
+      console.error(`Downloading release from ${this.url}`);
+    }
+
+    return download(this.url)
+      .then((res) => {
+        return new Promise((resolve, reject) => {
+          mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
+            if (err) return reject(err);
+            let tempFile = join(directory, this.filename);
+            const sink = res.pipe(createWriteStream(tempFile));
+            sink.on("error", (err) => reject(err));
+            sink.on("close", () => {
+              if (/\.tar\.*/.test(this.zipExt)) {
+                const result = spawnSync("tar", [
+                  "xf",
+                  tempFile,
+                  // The tarballs are stored with a leading directory
+                  // component; we strip one component in the
+                  // shell installers too.
+                  "--strip-components",
+                  "1",
+                  "-C",
+                  this.installDirectory,
+                ]);
+                if (result.status == 0) {
+                  resolve();
+                } else if (result.error) {
+                  reject(result.error);
+                } else {
+                  reject(
+                    new Error(
+                      `An error occurred untarring the artifact: stdout: ${result.stdout}; stderr: ${result.stderr}`,
+                    ),
+                  );
+                }
+              } else if (this.zipExt == ".zip") {
+                let result;
+                if (this.platform.artifactName.includes("windows")) {
+                  // Windows does not have "unzip" by default on many installations, instead
+                  // we use Expand-Archive from powershell
+                  result = spawnSync("powershell.exe", [
+                    "-NoProfile",
+                    "-NonInteractive",
+                    "-Command",
+                    `& {
+                        param([string]$LiteralPath, [string]$DestinationPath)
+                        Expand-Archive -LiteralPath $LiteralPath -DestinationPath $DestinationPath -Force
+                    }`,
+                    tempFile,
+                    this.installDirectory,
+                  ]);
+                } else {
+                  result = spawnSync("unzip", [
+                    "-q",
+                    tempFile,
+                    "-d",
+                    this.installDirectory,
+                  ]);
+                }
+
+                if (result.status == 0) {
+                  resolve();
+                } else if (result.error) {
+                  reject(result.error);
+                } else {
+                  reject(
+                    new Error(
+                      `An error occurred unzipping the artifact: stdout: ${result.stdout}; stderr: ${result.stderr}`,
+                    ),
+                  );
+                }
+              } else {
+                reject(
+                  new Error(`Unrecognized file extension: ${this.zipExt}`),
+                );
+              }
+            });
+          });
+        });
+      })
+      .then(() => {
+        if (!suppressLogs) {
+          console.error(`${this.name} has been installed!`);
+        }
+      })
+      .catch((e) => {
+        error(`Error fetching release: ${e.message}`);
+      });
+  }
+
+  run(binaryName) {
+    const promise = !this.exists() ? this.install(true) : Promise.resolve();
+
+    promise
+      .then(() => {
+        const [, , ...args] = process.argv;
+
+        const options = { cwd: process.cwd(), stdio: "inherit" };
+
+        const binRelPath = this.binaries[binaryName];
+        if (!binRelPath) {
+          error(`${binaryName} is not a known binary in ${this.name}`);
+        }
+        const binPath = join(this.installDirectory, binRelPath);
+        const result = spawnSync(binPath, args, options);
+
+        if (result.error) {
+          error(result.error);
+        }
+
+        process.exit(result.status);
+      })
+      .catch((e) => {
+        error(e.message);
+      });
+  }
+}
+
+module.exports.Package = Package;

package/binary.js

@@ -0,0 +1,124 @@
+const { Package } = require("./binary-install");
+const os = require("os");
+const libc = require("detect-libc");
+
+const error = (msg) => {
+  console.error(msg);
+  process.exit(1);
+};
+
+const {
+  name,
+  artifactDownloadUrls,
+  supportedPlatforms,
+  glibcMinimum,
+} = require("./package.json");
+
+// FIXME: implement NPM installer handling of fallback download URLs
+const artifactDownloadUrl = artifactDownloadUrls[0];
+const builderGlibcMajorVersion = glibcMinimum.major;
+const builderGlibcMinorVersion = glibcMinimum.series;
+
+const getPlatform = () => {
+  const rawOsType = os.type();
+  const rawArchitecture = os.arch();
+
+  // We want to use rust-style target triples as the canonical key
+  // for a platform, so translate the "os" library's concepts into rust ones
+  let osType = "";
+  switch (rawOsType) {
+    case "Windows_NT":
+      osType = "pc-windows-msvc";
+      break;
+    case "Darwin":
+      osType = "apple-darwin";
+      break;
+    case "Linux":
+      osType = "unknown-linux-gnu";
+      break;
+  }
+
+  let arch = "";
+  switch (rawArchitecture) {
+    case "x64":
+      arch = "x86_64";
+      break;
+    case "arm64":
+      arch = "aarch64";
+      break;
+  }
+
+  if (rawOsType === "Linux") {
+    if (libc.familySync() == "musl") {
+      osType = "unknown-linux-musl-dynamic";
+    } else if (libc.isNonGlibcLinuxSync()) {
+      console.warn(
+        "Your libc is neither glibc nor musl; trying static musl binary instead",
+      );
+      osType = "unknown-linux-musl-static";
+    } else {
+      let libcVersion = libc.versionSync();
+      let splitLibcVersion = libcVersion.split(".");
+      let libcMajorVersion = splitLibcVersion[0];
+      let libcMinorVersion = splitLibcVersion[1];
+      if (
+        libcMajorVersion != builderGlibcMajorVersion ||
+        libcMinorVersion < builderGlibcMinorVersion
+      ) {
+        // We can't run the glibc binaries, but we can run the static musl ones
+        // if they exist
+        console.warn(
+          "Your glibc isn't compatible; trying static musl binary instead",
+        );
+        osType = "unknown-linux-musl-static";
+      }
+    }
+  }
+
+  // Assume the above succeeded and build a target triple to look things up with.
+  // If any of it failed, this lookup will fail and we'll handle it like normal.
+  let targetTriple = `${arch}-${osType}`;
+  let platform = supportedPlatforms[targetTriple];
+
+  if (!platform) {
+    error(
+      `Platform with type "${rawOsType}" and architecture "${rawArchitecture}" is not supported by ${name}.\nYour system must be one of the following:\n\n${Object.keys(
+        supportedPlatforms,
+      ).join(",")}`,
+    );
+  }
+
+  return platform;
+};
+
+const getPackage = () => {
+  const platform = getPlatform();
+  const url = `${artifactDownloadUrl}/${platform.artifactName}`;
+  let filename = platform.artifactName;
+  let ext = platform.zipExt;
+  let binary = new Package(platform, name, url, filename, ext, platform.bins);
+
+  return binary;
+};
+
+const install = (suppressLogs) => {
+  if (!artifactDownloadUrl || artifactDownloadUrl.length === 0) {
+    console.warn("in demo mode, not installing binaries");
+    return;
+  }
+  const pkg = getPackage();
+
+  return pkg.install(suppressLogs);
+};
+
+const run = (binaryName) => {
+  const pkg = getPackage();
+
+  pkg.run(binaryName);
+};
+
+module.exports = {
+  install,
+  run,
+  getPackage,
+};

package/install.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const { install } = require("./binary");
+install(false);

package/npm-shrinkwrap.json

@@ -0,0 +1,52 @@
+{
+  "lockfileVersion": 3,
+  "name": "peekme",
+  "packages": {
+    "": {
+      "bin": {
+        "peekme": "run-peekme.js"
+      },
+      "dependencies": {
+        "detect-libc": "^2.1.2"
+      },
+      "devDependencies": {
+        "prettier": "^3.8.3"
+      },
+      "engines": {
+        "node": ">=14.14",
+        "npm": ">=6"
+      },
+      "hasInstallScript": true,
+      "license": "MIT OR Apache-2.0",
+      "name": "peekme",
+      "version": "0.2.1"
+    },
+    "node_modules/detect-libc": {
+      "engines": {
+        "node": ">=8"
+      },
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "license": "Apache-2.0",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "version": "2.1.2"
+    },
+    "node_modules/prettier": {
+      "bin": {
+        "prettier": "bin/prettier.cjs"
+      },
+      "dev": true,
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/prettier/prettier?sponsor=1"
+      },
+      "integrity": "sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw==",
+      "license": "MIT",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.3.tgz",
+      "version": "3.8.3"
+    }
+  },
+  "requires": true,
+  "version": "0.2.1"
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "artifactDownloadUrls": [
+    "https://github.com/GregoryBolshakov/peekme/releases/download/v0.2.1"
+  ],
+  "author": "Gregory Bolshakov",
+  "bin": {
+    "peekme": "run-peekme.js"
+  },
+  "dependencies": {
+    "detect-libc": "^2.1.2"
+  },
+  "description": "Select text in Codex CLI or Claude Code output and get a short explanation right under it, inside the terminal",
+  "devDependencies": {
+    "prettier": "^3.8.3"
+  },
+  "engines": {
+    "node": ">=14.14",
+    "npm": ">=6"
+  },
+  "glibcMinimum": {
+    "major": 2,
+    "series": 35
+  },
+  "homepage": "https://github.com/GregoryBolshakov/peekme",
+  "keywords": [
+    "command-line-utilities",
+    "codex",
+    "claude",
+    "terminal",
+    "cli",
+    "explain"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "name": "peekme",
+  "preferUnplugged": true,
+  "repository": "https://github.com/GregoryBolshakov/peekme",
+  "scripts": {
+    "fmt": "prettier --write **/*.js",
+    "fmt:check": "prettier --check **/*.js",
+    "postinstall": "node ./install.js"
+  },
+  "supportedPlatforms": {
+    "aarch64-apple-darwin": {
+      "artifactName": "peekme-aarch64-apple-darwin.tar.xz",
+      "bins": {
+        "peekme": "peekme"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "aarch64-unknown-linux-gnu": {
+      "artifactName": "peekme-aarch64-unknown-linux-gnu.tar.xz",
+      "bins": {
+        "peekme": "peekme"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-apple-darwin": {
+      "artifactName": "peekme-x86_64-apple-darwin.tar.xz",
+      "bins": {
+        "peekme": "peekme"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-unknown-linux-gnu": {
+      "artifactName": "peekme-x86_64-unknown-linux-gnu.tar.xz",
+      "bins": {
+        "peekme": "peekme"
+      },
+      "zipExt": ".tar.xz"
+    }
+  },
+  "version": "0.2.1",
+  "volta": {
+    "node": "18.14.1",
+    "npm": "9.5.0"
+  }
+}

package/run-peekme.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const { run } = require("./binary");
+run("peekme");