peekme 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.4.2 (2026-10-09)
+
+- Ask a question about the selection: Alt+Shift+P (Option+Shift+P on a Mac) opens the box empty,
+  you type the question and press Enter. The answer comes from the model your chat runs on, with
+  the whole conversation. Set `PEEKME_CLAUDE_ASK_MODEL`, `PEEKME_CODEX_ASK_MODEL`,
+  `PEEKME_COPILOT_ASK_MODEL` or `PEEKME_KIRO_ASK_MODEL` for another model. With a box open,
+  Alt+Shift+P asks about the text that box explains.
+- Kiro CLI support. `peekme install` now also sets up `kiro-cli`, and a setup from an older
+  peekme gets it the next time peekme starts. Everything works as in the other agents: select
+  text, press Alt+P (Option+P on a Mac), peek inside a peek, click underlined text for the saved
+  answer, also inside tmux and over SSH.
+- Kiro starts inline and leaves the mouse to the terminal. After `/fullscreen` Kiro makes the
+  selection itself and peekme reads it, also over SSH. Underlined text can be clicked only there.
+- Explanations go through `kiro-cli acp` with your Kiro login, on `claude-haiku-4.5` without
+  tools. About 0.01 Kiro credits each. The sessions are deleted afterwards, so they don't show up
+  in Kiro's session list. Set `PEEKME_KIRO_MODEL` for another model.
+- The model knows the Kiro conversation, read from `~/.kiro/sessions/cli`.
+
+## 0.4.1 (2026-10-07)
+
+- Mac: after `peekme install`, `claude` could stop with `error: unknown option
+  '--internal-jobctl-helper'` and Claude Code never opened. `codex` and `copilot` had the same
+  problem. On macOS peekme's helper process started under the name of the agent link, and
+  peekme passed its own flag on to the agent. Now the helper is found first. The same happened
+  on any system where `claude` was a copy of peekme instead of a link.
+- Tests no longer depend on running inside tmux or over SSH.
+
 ## 0.4.0 (2026-10-06)
 
 Everything from the 0.4.0 betas below, now in the normal install (`npm i -g peekme`, Homebrew,

package/README.md

@@ -1,17 +1,17 @@
 # peekme
 
 Pick me. Select text in [Claude Code](https://github.com/anthropics/claude-code),
-[Codex CLI](https://github.com/openai/codex) or
-[GitHub Copilot CLI](https://github.com/github/copilot-cli) output, press **Alt+P** (**Option+P** on a Mac), and a short
+[Codex CLI](https://github.com/openai/codex),
+[GitHub Copilot CLI](https://github.com/github/copilot-cli) or [Kiro CLI](https://kiro.dev/cli/) output, press **Alt+P** (**Option+P** on a Mac), 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 in Claude Code: ask about detached HEAD, select "git switch -" in the answer, press Alt+P, read the explanation, press Esc](https://raw.githubusercontent.com/GregoryBolshakov/peekme/main/docs/demo-claude.gif)
+![peekme in Claude Code: select "planner statistics" in an answer and press Alt+P. In the explanation select "hash join" and press Alt+P again for a box inside the box. Esc closes them, and a click on the underlined words opens the saved answer](https://raw.githubusercontent.com/GregoryBolshakov/peekme/main/docs/demo-claude.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.4.0. Tested with Claude Code 2.1.292, Codex 0.159 and Copilot CLI 1.0.89 on Linux, also
+Status: 0.4.2. Tested with Claude Code 2.1.292, Codex 0.161, Copilot CLI 1.0.93 and Kiro CLI 2.28 on Linux, also
 inside tmux and over SSH. On macOS it is tested in Terminal and iTerm2 with a stand-in agent, and
 in Terminal with the real Codex, also inside tmux and over SSH.
 
@@ -19,8 +19,8 @@ in Terminal with the real Codex, also inside tmux and over SSH.
 
 Many developers have more than one agent CLI and switch between them during the day. peekme
 works the same way in each of them. You install it once, and the key and the box are the same
-everywhere. Claude Code, Codex CLI
-and GitHub Copilot CLI work today, and more agents are planned. If one agent gets its own way to
+everywhere. Claude Code, Codex CLI,
+GitHub Copilot CLI and Kiro CLI work today, and more agents are planned. If one agent gets its own way to
 explain a selection some day, it will work in that agent only. peekme keeps working in all of
 them.
 
@@ -39,8 +39,8 @@ npm i -g peekme
 peekme install
 ```
 
-Open a new terminal. Now `claude`, `codex` and `copilot` open with peekme, and you type them as
-always. That's all.
+Open a new terminal. Now `claude`, `codex`, `copilot` and `kiro-cli` open with peekme, and you
+type them as always. That's all.
 
 peekme has no account of its own. The explanation uses the login of the agent you are in.
 
@@ -52,9 +52,10 @@ Don't have npm? Use one of these instead of the first line:
 
 ## Use
 
-Start Claude Code, Codex or Copilot CLI as always. Select text with the mouse as you normally
-do, then press Alt+P. When the agent draws full screen (Claude Code with `"tui": "fullscreen"`,
-Codex since 0.157, Copilot CLI), it makes the selection itself, and peekme uses that selection.
+Start Claude Code, Codex, Copilot CLI or Kiro CLI as always. Select text with the mouse as you
+normally do, then press Alt+P. When the agent draws full screen (Claude Code with
+`"tui": "fullscreen"`, Codex since 0.157, Copilot CLI, Kiro CLI after `/fullscreen`), it makes
+the selection itself, and peekme uses that selection.
 
 | Key | When | What it does |
 |---|---|---|
@@ -65,6 +66,7 @@ Codex since 0.157, Copilot CLI), it makes the selection itself, and peekme uses
 | 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 |
 | Alt+P on text in the box | box is open | opens a new box inside it, under that line |
+| Alt+Shift+P (Mac: Option+Shift+P) | any time | type a question about the selected text first, Enter sends it |
 | click on underlined text | any time | shows the answer from before, with no new request |
 
 Text you already asked about gets a dotted underline, so you can see what you peeked before.
@@ -72,18 +74,31 @@ A click on it opens the saved answer again, a second click closes it. Inside a b
 words and press Alt+P again, and go several levels deep while the window is wide enough. The
 wheel scrolls the box under the pointer, Esc closes the innermost box.
 
+### Ask a question
+
+Sometimes a short explanation is not what you need. Select the text and press Alt+Shift+P
+(Option+Shift+P on a Mac) instead. The box opens empty and you type your question, for example
+"why not use a mutex here?". Enter sends it, Esc cancels. While you type, the keys stay in the
+box and don't go to the agent.
+
+The question goes to the model your chat runs on, not the small one, together with the whole
+conversation (Codex gets a copy of the thread). So it takes longer and costs more than a normal
+peek. With a box open, Alt+Shift+P asks about the text that box explains. The answer is saved
+with the question, and a click on the underline shows both.
+
 ### On a Mac
 
 Option+P works as it is, with no terminal setting, also over SSH and inside tmux. A Mac
 terminal sends Option+P as the character `π`. When something is selected, peekme takes `π` as
-the shortcut. When nothing is selected, `π` is typed as usual, so you never lose the letter. If
+the shortcut. When nothing is selected, `π` is typed as usual, so you never lose the letter.
+Option+Shift+P types `∏` and works the same way for questions. If
 you type Greek, `π` stays a letter. If your terminal sends Option as Meta, Option+P works too.
 
 When the agent draws full screen, peekme gets the selection from the agent. Otherwise (Claude
-Code's classic screen) it reads the clipboard: iTerm2 copies a selection there by itself, in
-Terminal press Cmd+C after you select. Over SSH only the agent's own selection can be read, so
-use the full screen mode there (Claude Code with `"tui": "fullscreen"`, Codex and Copilot CLI
-by default).
+Code's classic screen, Kiro CLI before `/fullscreen`) it reads the clipboard: iTerm2 copies a
+selection there by itself, in Terminal press Cmd+C after you select. Over SSH only the agent's
+own selection can be read, so use the full screen mode there (Claude Code with
+`"tui": "fullscreen"`, `/fullscreen` in Kiro CLI, Codex and Copilot CLI by default).
 
 Inside tmux, Codex leaves the mouse to the terminal when tmux has the mouse off, which is tmux's
 default. A selection is then your terminal's own, and over SSH peekme cannot read it. Add
@@ -110,13 +125,20 @@ No API key is needed. peekme asks the agent's own CLI, with your existing login:
   on the first explanation. Each explanation is a short session without tools, and peekme
   deletes it afterwards, so nothing appears in your session list. The model is Copilot's Auto
   unless you set one. It uses a little of your AI credits for each explanation.
+- Kiro CLI: its ACP server (`kiro-cli acp`, the one Kiro's own screen and editors use), started
+  on the first explanation. It runs with a peekme agent that has no tools. Each explanation is
+  a short session, and peekme deletes it afterwards, so nothing appears in your session list.
+  The model is `claude-haiku-4.5` unless you set one (Auto if your plan doesn't have it). One
+  explanation costs about 0.01 Kiro credits.
 
 It does use your plan, a little for each explanation. Nothing starts before the first Alt+P.
 
 Only the interactive screen gets peekme: `claude`, `claude "prompt"`, `claude --resume`,
-`claude -c`, `codex`, `codex "prompt"`, `codex resume`, `codex fork`, and `copilot`,
-`copilot -i "prompt"`, `copilot --resume`. Commands like `claude -p`, `codex exec`, `copilot -p`
-or `copilot login`, and anything with output going to a pipe or a file, run the agent directly.
+`claude -c`, `codex`, `codex "prompt"`, `codex resume`, `codex fork`, `copilot`,
+`copilot -i "prompt"`, `copilot --resume`, and `kiro-cli`, `kiro-cli chat`, `kiro-cli --resume`.
+Commands like `claude -p`, `codex exec`, `copilot -p`, `copilot login`,
+`kiro-cli chat --no-interactive` or `kiro-cli acp`, and anything with output going to a pipe or
+a file, run the agent directly.
 
 ## How it works
 
@@ -130,7 +152,7 @@ On Alt+P it takes the selection and finds it on the screen:
   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.
 - Codex full screen: the text Codex highlighted.
-- Copilot CLI: the same OSC 52 sequence as Claude Code.
+- Copilot CLI, and Kiro CLI after `/fullscreen`: the same OSC 52 sequence as Claude Code.
 - 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
@@ -140,7 +162,7 @@ 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 Claude Code, Codex and Copilot CLI output.
+this cell by cell on real Claude Code, Codex, Copilot CLI and Kiro CLI output.
 
 ### What the model gets
 
@@ -157,8 +179,9 @@ slow. So the model gets small parts, each with a size limit:
 4. The first places in the conversation where the same words were used before.
 
 The conversation comes from Claude Code's session transcript in `~/.claude/projects`, from
-Codex's app-server, or from Copilot CLI's session log in `~/.copilot/session-state`. peekme
-knows which session, because the agent registers its process id there.
+Codex's app-server, from Copilot CLI's session log in `~/.copilot/session-state`, or from Kiro
+CLI's session log in `~/.kiro/sessions/cli`. peekme knows which session, because the agent
+registers its process id there.
 
 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
@@ -176,22 +199,28 @@ more.
 | `PEEKME_OWN_SERVER` | set to 1 to start peekme's own `codex app-server` instead of using the shared one |
 | `PEEKME_COPILOT_MODEL` | model for Copilot CLI explanations. Default is Copilot's Auto |
 | `PEEKME_COPILOT_BIN` | copilot binary to use for explanations. Default is `copilot` |
+| `PEEKME_KIRO_MODEL` | model for Kiro CLI explanations. Default is `claude-haiku-4.5` |
+| `PEEKME_KIRO_BIN` | kiro-cli binary to use for explanations. Default is `kiro-cli` |
+| `PEEKME_CLAUDE_ASK_MODEL` | model for typed questions in Claude Code. Default is the chat's model |
+| `PEEKME_CODEX_ASK_MODEL` | model for typed questions in Codex. Default is the thread's model |
+| `PEEKME_COPILOT_ASK_MODEL` | model for typed questions in Copilot CLI. Default is the chat's model |
+| `PEEKME_KIRO_ASK_MODEL` | model for typed questions in Kiro CLI. Default is the chat's model |
 | `PEEKME_SELECTION` | use this text instead of the mouse selection, for testing |
 
-### How `claude`, `codex` and `copilot` get peekme
+### How `claude`, `codex`, `copilot` and `kiro-cli` get peekme
 
 ```
 peekme doctor      # check the setup, and see what is in the way if something is
 peekme uninstall   # remove it, your files are as before
-command claude     # run plain Claude Code once (same for codex, copilot)
+command claude     # run plain Claude Code once (same for codex, copilot, kiro-cli)
 ```
 
 `peekme install` does two things:
 
-1. It defines shell functions `claude`, `codex` and `copilot` in your shell setup. A function wins over
+1. It defines shell functions `claude`, `codex`, `copilot` and `kiro-cli` 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 them go through it too.
-2. It puts `claude`, `codex` and `copilot` links to peekme in `~/.local/share/peekme/bin` at the front of
+2. It puts `claude`, `codex`, `copilot` and `kiro-cli` 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.
 
@@ -199,7 +228,7 @@ Both find the real agent on PATH themselves, so updating the agent changes nothi
 remove peekme, the functions fall back to the plain agents.
 
 The block in `~/.bashrc` or `~/.zshrc` (for fish, a file in `~/.config/fish/conf.d`) is short
-and marked. It covers all three agents, so an agent you install later gets peekme too. When a new
+and marked. It covers all four agents, so an agent you install later gets peekme too. When a new
 peekme version knows more agents, it adds them to your setup the next time it starts and says
 so once.
 
@@ -217,11 +246,12 @@ To use peekme with another program, run `peekme -- COMMAND`.
   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 (see [On a Mac](#on-a-mac)).
+- A click on underlined text works only when the agent takes the mouse (full screen mode). On
+  Claude Code's classic screen and Kiro CLI before `/fullscreen` the click goes to your
+  terminal.
 - 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
 
@@ -229,11 +259,12 @@ To use peekme with another program, run `peekme -- COMMAND`.
 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|--copilot] [--pid PID]
+cargo run --example peek_text -- "<screen text>" "<selection>" [--deep] [--ask QUESTION] [--claude|--copilot|--kiro] [--pid PID]
 python3 spikes/capture.py out.bin 120 40 "<script>" -- peekme claude
 python3 spikes/flicker_test.py
 python3 spikes/explain_probe.py
 python3 spikes/copilot_probe.py info
+python3 spikes/kiro_probe.py [MODEL] [PROMPT]
 ```
 
 `vtdump` replays a captured byte stream and prints the screen. `peek_text` runs one explanation
@@ -241,9 +272,9 @@ without a terminal and prints the exact prompt. `capture.py` runs a command in a
 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. `copilot_probe.py` does the same
-with Copilot CLI's headless server.
+with Copilot CLI's headless server, `kiro_probe.py` with Kiro CLI's ACP server.
 
-Each agent has its own folder in `src/` (`claude/`, `codex/`, `copilot/`): how its selection is read, where
+Each agent has its own folder in `src/` (`claude/`, `codex/`, `copilot/`, `kiro/`): how its selection is read, where
 its conversation comes from, and which model explains. The rest is shared.
 
 ## License

package/npm-shrinkwrap.json

@@ -19,7 +19,7 @@
       "hasInstallScript": true,
       "license": "MIT OR Apache-2.0",
       "name": "peekme",
-      "version": "0.4.0"
+      "version": "0.4.2"
     },
     "node_modules/detect-libc": {
       "engines": {
@@ -48,5 +48,5 @@
     }
   },
   "requires": true,
-  "version": "0.4.0"
+  "version": "0.4.2"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/GregoryBolshakov/peekme/releases/download/v0.4.0"
+    "https://github.com/GregoryBolshakov/peekme/releases/download/v0.4.2"
   ],
   "author": "Gregory Bolshakov",
   "bin": {
@@ -9,7 +9,7 @@
   "dependencies": {
     "detect-libc": "^2.1.2"
   },
-  "description": "Select text in Claude Code, Codex CLI or GitHub Copilot CLI output and get a short explanation right under it, inside the terminal",
+  "description": "Select text in Claude Code, Codex CLI, GitHub Copilot CLI or Kiro CLI output and get a short explanation right under it, inside the terminal",
   "devDependencies": {
     "prettier": "^3.8.3"
   },
@@ -28,8 +28,8 @@
     "claude-code",
     "codex",
     "copilot",
-    "terminal",
-    "tui"
+    "kiro",
+    "terminal"
   ],
   "license": "MIT OR Apache-2.0",
   "name": "peekme",
@@ -70,7 +70,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.4.0",
+  "version": "0.4.2",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"