better-grill 0.3.0 → 0.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "better-grill",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Run grill sessions in a local browser UI instead of the terminal: rounds of questions with options and a recommendation, a discussion thread per question, driven by your open Claude Code session.",
   "author": {
     "name": "Jakub Stastny",

package/README.md

@@ -1,74 +1,98 @@
-# better-grill
+<p align="center">
+  <img src="https://raw.githubusercontent.com/devbaj-stastny-jakub/better-grill/main/.github/assets/hero.png" alt="better grill, the UI for the grilling skill: grilling without the terminal mess. Rounds of questions, Claude's pick on each, a discussion thread per question.">
+</p>
 
-[![npm](https://img.shields.io/npm/v/better-grill)](https://www.npmjs.com/package/better-grill)
-[![license](https://img.shields.io/npm/l/better-grill)](LICENSE)
-[![node](https://img.shields.io/node/v/better-grill)](https://nodejs.org)
+<p align="center">
+  <a href="https://www.npmjs.com/package/better-grill"><img src="https://img.shields.io/npm/v/better-grill?color=f97316" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/better-grill?color=f97316" alt="license"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/better-grill?color=f97316" alt="node"></a>
+</p>
 
-Grill sessions for Claude Code, in your browser instead of the terminal.
+<p align="center"><b>Matt Pocock's <a href="https://github.com/mattpocock/skills"><code>grilling</code></a> skill, in a real UI.<br>Rounds, discussions, one clean send, and no mess in your terminal.</b></p>
 
-![A grill round in better-grill: one question locked in, the next with Claude's recommended option picked](https://raw.githubusercontent.com/devbaj-stastny-jakub/better-grill/main/.github/assets/round.png)
+---
 
-A grill session is Claude interviewing you about a plan until nothing is left unsaid. It maps the decisions as a tree, asks every question it can answer right now in one round with a recommended answer each, and keeps going until every branch is settled. The method comes from Matt Pocock's [`grilling`](https://github.com/mattpocock/skills) skill; better-grill gives it a proper UI.
+## Two ways to grill
 
-Why a browser:
+<table>
+<tr>
+<td width="50%" valign="top">
 
-- **Options side by side**, each with a description and Claude's pick marked, instead of a wall of terminal text.
-- **A discussion thread per question.** Push back on one question without derailing the rest; Claude can reword, resolve, drop or add questions from the talk.
-- **Answer at your own pace.** Lock in questions in any order, change your mind, then send the whole round at once.
-- **Runs on your Claude Code session.** Uses your existing subscription. No API key, no hosted service.
+**Grill a plan**
 
-## Requirements
+```
+/better-grill:better-grill <plan>
+```
 
-- [Claude Code](https://code.claude.com)
-- [Node.js](https://nodejs.org) 20 or newer on your `PATH`
-- The `grilling` skill from [mattpocock/skills](https://github.com/mattpocock/skills). better-grill brings the UI; `grilling` brings the method.
-- For the docs variant, also `domain-modeling` from the same repo.
+Claude grills your plan round by round until every decision is settled, then sums them up.
 
-## Install
+</td>
+<td width="50%" valign="top">
 
-In Claude Code:
+**Grill with docs**
 
 ```
-/plugin marketplace add devbaj-stastny-jakub/better-grill
-/plugin install better-grill@better-grill
+/better-grill:better-grill-docs <plan>
 ```
 
-## Usage
+The same grill, and Claude keeps a glossary (`CONTEXT.md`) and ADRs up to date as decisions settle, like `grill-with-docs`.
+
+</td>
+</tr>
+</table>
 
-In any Claude Code session:
+For example:
 
 ```
-/better-grill:better-grill <what you want grilled>
+/better-grill:better-grill a CLI that syncs my dotfiles across machines
 ```
 
-Or, to also keep a glossary (`CONTEXT.md`) and ADRs as decisions settle, like `grill-with-docs`:
+Your browser opens on the session, and Claude's first round of questions lands there.
+
+## Install
+
+In Claude Code:
 
 ```
-/better-grill:better-grill-docs <what you want grilled>
+/plugin marketplace add devbaj-stastny-jakub/better-grill
+/plugin install better-grill@better-grill
 ```
 
-1. Your browser opens on the session. The terminal stays quiet; everything happens in the UI.
-2. Claude posts a round of questions. For each one, pick an option, write your own answer, or both, then **Lock in**.
-3. Not sure about a question? Hit **Discuss** and talk it through. Claude answers in the thread and updates the question when you agree on something.
-4. When every question is locked in, **Send to Claude**. The next round builds on your answers.
-5. When nothing is left open, Claude posts a summary of every decision. Confirm it, or say what's wrong and the grilling continues.
+You also need [Node.js](https://nodejs.org) 20+ and the [`grilling`](https://github.com/mattpocock/skills) skill; the docs variant also uses `domain-modeling` from the same repo. better grill brings the UI, the skills bring the method.
+
+## What you get
 
-![A discussion thread next to the question it is about](https://raw.githubusercontent.com/devbaj-stastny-jakub/better-grill/main/.github/assets/discussion.png)
+![A round in better-grill: a question with a comparison table and Claude's pick selected, its discussion thread open alongside](https://raw.githubusercontent.com/devbaj-stastny-jakub/better-grill/main/.github/assets/discussion.png)
 
-Several Claude sessions can grill at the same time; each gets its own browser tab.
+<table>
+<tr>
+<td width="33%" valign="top"><b>One question at a time</b><br>Rounds step through their questions, with Claude's context, trade-offs and tables.</td>
+<td width="33%" valign="top"><b>Claude's pick on each</b><br>Take it, choose another option, write your own answer, add a note, or paste a screenshot.</td>
+<td width="33%" valign="top"><b>A thread per question</b><br>Push back on one question; Claude rewords, resolves, drops or adds questions.</td>
+</tr>
+<tr>
+<td width="33%" valign="top"><b>Lock in, then send</b><br>Answer in any order, change your mind, send the round when it's settled.</td>
+<td width="33%" valign="top"><b>A summary at the end</b><br>Every decision in one place. Confirm it, or keep grilling.</td>
+<td width="33%" valign="top"><b>Keyboard first</b><br><kbd>↑</kbd> <kbd>↓</kbd> walk the options, <kbd>Enter</kbd> locks in, <kbd>D</kbd> opens the discussion, <kbd>V</kbd> shows the visualization, <kbd>[</kbd> folds the sidebar.</td>
+</tr>
+<tr>
+<td colspan="3" valign="top"><b>Visualize any question</b><br>Press Visualize and Claude turns the question into an interactive page, right in the app, so it's easier to understand. Keep answering while it works.</td>
+</tr>
+</table>
 
-## How it works
+## Built into Claude Code
 
-- Claude Code has no port the browser could call, so better-grill starts a small local **bridge** server for each session.
-- Claude talks to the bridge with a CLI from its Bash tool: it posts rounds, then waits in the background until you send a round or write in a discussion.
-- The bridge never calls Claude or any API. It holds the session state and hands your answers back.
-- It listens on `127.0.0.1` only, rejects requests from other websites, and shuts down on its own after 30 idle minutes.
+- **Part of the session you're in.** One command from your current Claude Code session. No accounts, no API keys, nothing to set up.
+- **Live, both ways.** Your answers reach Claude the moment you send them, and its replies in a discussion show up as soon as it writes them.
+- **Claude knows your project.** The grill runs in the same conversation, so Claude asks with your code and everything you've discussed in mind.
+- **Your terminal stays quiet.** The whole grill happens in the browser; the terminal just shows Claude at work.
+- **Several grills at once.** Every Claude Code session gets its own grill in its own tab.
 
-Details, security model, CLI reference and known limits: [ARCHITECTURE.md](ARCHITECTURE.md).
+Curious about the internals? [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ## Contributing
 
-Issues and pull requests welcome. Dev setup: [CONTRIBUTING.md](CONTRIBUTING.md).
+Issues and pull requests welcome. Dev setup, demo and screenshots: [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-grill",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Grill sessions for Claude Code, in your browser instead of the terminal.",
   "keywords": [
     "ai",
@@ -33,6 +33,7 @@
     "skills/better-grill/SKILL.md",
     "skills/better-grill-docs/SKILL.md",
     "skills/better-grill-base/SKILL.md",
+    "skills/better-grill-base/visualize.md",
     "skills/better-grill-base/dist"
   ],
   "scripts": {

package/skills/better-grill-base/SKILL.md

@@ -2,7 +2,9 @@
 name: better-grill-base
 description: Internal. Shared instructions loaded by the better-grill and better-grill-docs skills. Do not invoke directly.
 user-invocable: false
-allowed-tools: Bash(node "${CLAUDE_SKILL_DIR}/dist/cli.js" *)
+allowed-tools:
+  - Bash(node "${CLAUDE_SKILL_DIR}/dist/cli.js" *)
+  - Read(~/.better-grill/images/**)
 ---
 
 # Better Grill
@@ -90,13 +92,15 @@ Output:
 {
   "events": [
     { "type": "answer", "questionId": "Q2", "title": "…", "choices": ["Label"], "text": "note or own answer", "revised": false, "by": "user" },
-    { "type": "chat", "questionId": "Q3", "title": "…", "text": "user message" }
+    { "type": "chat", "questionId": "Q3", "title": "…", "text": "on [Image 1] the header is too big", "images": ["/Users/…/.better-grill/images/62950-a1b2c3/img1.png"] }
   ],
   "open": [{ "id": "Q3", "title": "…" }]
 }
 ```
 
-`open` lists questions still unanswered after these events. A wait that returns only `chat` events means the round is still in progress: handle the chat, then wait again.
+`open` lists questions still unanswered after these events. A wait that returns only `chat` or `visualize` events means the round is still in progress: handle them, then wait again.
+
+`images` (on `answer` and `chat`, only when present) lists absolute paths of images the user pasted or dropped in: screenshots, sketches, diagrams. The user places each image inside their text, where it shows up as `[Image N]`: `[Image 1]` is `images[0]`, `[Image 2]` is `images[1]`, and so on. Read every image with the Read tool before you act on the event; they are part of what the user said, and the text around each marker tells you what it is about. When you reply about one, name it the same way ("in Image 2, …"). The files are deleted when the bridge stops.
 
 ## 5. Handle events
 
@@ -112,6 +116,11 @@ Output:
   ```
 
   Keep replies conversational and short. Then act on what the talk settled (next section). Never tell the user to go lock in an answer the two of you already agreed on.
+- **visualize** (`{ "type": "visualize", "questionId": "Q3", "title": "…", "note": "focus on the failure case" }`): the user pressed Visualize and wants the question visualized as an interactive page, shown in the UI. That takes a while, so hand it to a background sub-agent (Agent tool, `run_in_background: true`) and carry on with the grill. Give it this prompt, with the handle and id filled in:
+
+  > Run `node "${CLAUDE_SKILL_DIR}/dist/cli.js" visualize -s SESSION Q3 --brief`. It prints how to build the visualization, the question and the command that posts the page. Follow it exactly, post the page, and reply with one line.
+
+  Without sub-agents, run that brief yourself once the other events are handled. Don't reply in the thread about it: the UI shows the progress and the result. `note` is what the user wants to see; the brief includes it.
 - **summary_confirmed / summary_rejected / ended**: see step 6.
 
 ## 5b. Shape questions from the discussion