better-grill 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "better-grill",
+  "version": "0.1.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",
+    "url": "https://github.com/devbaj-stastny-jakub"
+  },
+  "homepage": "https://github.com/devbaj-stastny-jakub/better-grill",
+  "repository": "https://github.com/devbaj-stastny-jakub/better-grill",
+  "license": "MIT",
+  "keywords": [
+    "grill",
+    "interview",
+    "planning",
+    "browser-ui"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jakub Stastny
+
+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,142 @@
+# better grill
+
+Run grill sessions in a browser instead of the terminal. Claude posts rounds of questions with options and a recommendation; you lock in each question when ready (pick, type your own answer, or both), or open a discussion thread per question. When everything is locked in, **Send to Claude** sends the round; discussion messages go right away. From a discussion, Claude can resolve, edit, drop or add questions in the UI. Everything runs through your open Claude Code session, so it uses your Claude Code subscription. No API key.
+
+## Requirements
+
+- [Claude Code](https://code.claude.com)
+- [Node.js](https://nodejs.org) 20 or newer on your `PATH`
+- Matt Pocock's `grilling` skill from [mattpocock/skills](https://github.com/mattpocock/skills). better-grill brings the UI; `grilling` brings the method (design tree, frontier, recommended answers).
+
+## Install
+
+In Claude Code:
+
+```
+/plugin marketplace add devbaj-stastny-jakub/better-grill
+/plugin install better-grill@better-grill
+```
+
+Then, in any session:
+
+```
+/better-grill:better-grill <what you want grilled>
+```
+
+Your browser opens on the session. Claude keeps the terminal quiet and talks to you in the UI until you confirm the final summary.
+
+Several Claude sessions can grill at the same time; each gets its own bridge, port and browser tab.
+
+## How it talks to Claude Code
+
+Claude Code has no port or socket to call, so the browser cannot reach it. A small local **bridge** sits between them:
+
+```
+Claude Code session                 bridge (node, 127.0.0.1)            browser
+───────────────────                 ────────────────────────            ───────
+grill round  ── POST /api/rounds ─▶ session state ── SSE /api/stream ─▶ UI
+grill wait   ── GET  /api/wait ───▶ (held open)
+                                    ◀── POST answer / chat ──────────── click
+             ◀── events JSON ─────  releases the wait
+grill reply  ── POST /reply ──────▶ ── SSE ────────────────────────────▶ chat thread
+```
+
+- Claude drives the bridge with the `grill` CLI from its Bash tool.
+- `grill wait` is a long-poll Claude runs in the background. It returns when you press Send or write in a discussion, and Claude Code wakes the session with the events.
+- The bridge never calls Claude. It only holds state and releases waits.
+- A bridge exits on its own after 30 minutes with no wait running, no browser tab open and no requests.
+
+### Security
+
+The bridge listens on `127.0.0.1` only and:
+
+- refuses requests whose `Host` isn't localhost (DNS rebinding),
+- refuses requests whose `Origin` isn't the page it serves, and requires JSON bodies, so other websites open in your browser can't post into the session,
+- refuses Claude-side calls without its session id (see below).
+
+## CLI
+
+The plugin runs it as `node <skill dir>/dist/cli.js`; outside Claude Code it is also `npx better-grill`.
+
+```
+grill start [--title T] [--port N] [--no-open]   # prints {"session":"62950-a1b2c3","url","log"}
+grill round   -s SESSION < round.json
+grill add     -s SESSION < questions.json      # into the latest round, while unsent
+grill wait    -s SESSION
+grill reply   -s SESSION Q3 < text.md
+grill resolve -s SESSION Q3 < resolution.json  # {"options":[1],"text":"…"}
+grill edit    -s SESSION Q3 < patch.json
+grill drop    -s SESSION Q3 < reason.txt
+grill summary -s SESSION < summary.md
+grill state   -s SESSION
+grill stop    -s SESSION
+```
+
+Each `grill start` runs its own bridge on a free port. The session handle is `<port>-<id>`: the CLI sends the id in an `x-grill-session` header and the bridge refuses Claude-side calls whose id doesn't match, so a session that mixes up ports gets an error instead of writing into someone else's grill.
+
+Exit codes: 0 ok, 1 bridge rejected the input, 2 usage error or bridge unreachable.
+
+## Development
+
+Needs Node 24 (`.nvmrc`) and pnpm.
+
+```sh
+pnpm install
+pnpm dev          # bridge from TypeScript on :4777 as session 4777-dev (node --watch) + Vite on :5173 proxying /api
+pnpm demo         # fake Claude: posts rounds, echoes chat replies, ends in a summary
+pnpm check-types
+pnpm build        # web UI + bridge bundle into skills/better-grill/dist
+```
+
+Open http://localhost:5173 after `pnpm dev`, then run `pnpm demo` in a second terminal.
+
+To use your checkout from real Claude Code sessions, either load it as a plugin with `claude --plugin-dir .`, or symlink the skill:
+
+```sh
+ln -s "$PWD/skills/better-grill" ~/.claude/skills/better-grill
+```
+
+The skill runs the bundle in `skills/better-grill/dist`, so rebuild after bridge changes (`pnpm --filter @better-grill/bridge build:watch` keeps it fresh).
+
+### Layout
+
+| Path                    | What                                                                          |
+| ----------------------- | ----------------------------------------------------------------------------- |
+| `packages/protocol`     | Zod schemas and types shared by bridge and UI: rounds, answers, events         |
+| `apps/bridge`           | Node server (`server.ts`), session logic, `grill` CLI, demo and build scripts  |
+| `apps/web`              | Vite + React + Tailwind + shadcn/ui (Base UI) UI                               |
+| `skills/better-grill`   | `SKILL.md`, plus the built `dist/` (bridge bundle and web UI) it runs          |
+| `.claude-plugin`        | Plugin manifest and the marketplace that points at the npm package             |
+
+In development the bridge runs TypeScript directly with Node's type stripping. For release, esbuild bundles it into dependency-free JS for Node 20+.
+
+`apps/web/src` follows [bulletproof-react](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md):
+
+| Path                 | What                                                                                |
+| -------------------- | ----------------------------------------------------------------------------------- |
+| `app/`               | Providers and `session-screen.tsx`, which composes the features                      |
+| `features/<name>/`   | `session`, `rounds`, `discussion`, `navigation`, `summary`: each with `api/`, `components/`, `hooks/`, `utils/` as needed |
+| `components/ui/`     | shadcn components (Base UI, `base-nova` style). Add more with `pnpm dlx shadcn@latest add <name>` in `apps/web` |
+| `components/`        | Shared app components: markdown, errors, feedback notes, brand, theme toggle         |
+| `hooks/` `lib/` `utils/` `types/` `config/` | Shared hooks, bridge client + theme + lock, pure helpers, types, constants |
+
+Features never import from each other; only `app/` combines them. Theme tokens (stone + orange accent, light and dark) live in `src/index.css`.
+
+### Releasing
+
+The plugin ships as the `better-grill` npm package; the marketplace in `.claude-plugin/marketplace.json` points at it, so nothing built is committed.
+
+```sh
+npm version patch      # bumps package.json and .claude-plugin/plugin.json together
+npm publish            # prepublishOnly runs check-types and build
+git push --follow-tags
+```
+
+## Known limits
+
+- State lives in bridge memory. Browser refresh is fine; a bridge crash loses the session.
+- One Claude session per bridge. Events queue while Claude is busy and arrive as one batch.
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "better-grill",
+  "version": "0.1.0",
+  "description": "Run grill sessions in a local browser UI instead of the terminal, driven by your open Claude Code session.",
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "grill",
+    "interview",
+    "planning"
+  ],
+  "license": "MIT",
+  "author": "Jakub Stastny (https://github.com/devbaj-stastny-jakub)",
+  "homepage": "https://github.com/devbaj-stastny-jakub/better-grill",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devbaj-stastny-jakub/better-grill.git"
+  },
+  "bugs": "https://github.com/devbaj-stastny-jakub/better-grill/issues",
+  "type": "module",
+  "packageManager": "pnpm@10.11.1",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "better-grill": "skills/better-grill/dist/cli.js"
+  },
+  "files": [
+    ".claude-plugin/plugin.json",
+    "skills/better-grill/SKILL.md",
+    "skills/better-grill/dist"
+  ],
+  "scripts": {
+    "dev": "pnpm --parallel --filter @better-grill/bridge --filter @better-grill/web dev",
+    "demo": "pnpm --filter @better-grill/bridge demo",
+    "build": "pnpm --filter @better-grill/web build && pnpm --filter @better-grill/bridge build",
+    "check-types": "pnpm -r check-types",
+    "prepublishOnly": "pnpm check-types && pnpm build",
+    "version": "node -e \"const f='.claude-plugin/plugin.json',fs=require('fs'),p=JSON.parse(fs.readFileSync(f));p.version=process.env.npm_package_version;fs.writeFileSync(f,JSON.stringify(p,null,2)+'\\n')\" && git add .claude-plugin/plugin.json"
+  }
+}

package/skills/better-grill/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: better-grill
+description: Run a grill-me session in a local browser UI instead of the terminal. Rounds, options, free-text answers and a discussion thread per question, all driven from this Claude Code session.
+disable-model-invocation: true
+allowed-tools: Bash(node "${CLAUDE_SKILL_DIR}/dist/cli.js" *)
+---
+
+# Better Grill
+
+Grill the user exactly like the `grilling` skill, but every question, answer and discussion goes through a local browser UI. The terminal stays quiet.
+
+Every command below is `node "${CLAUDE_SKILL_DIR}/dist/cli.js" …`, written exactly like that so it runs without a permission prompt. In prose it is called `grill`.
+
+## 1. Load the method
+
+Call the Skill tool with `grilling`. If no such skill exists, stop and tell the user that better-grill needs Matt Pocock's `grilling` skill installed first (https://github.com/mattpocock/skills), then end.
+
+Follow its method: design tree, frontier, recommended answers, facts found by you (sub-agents), decisions made by the user, done when the frontier is empty.
+
+Ignore two things from it and from any memory or instruction elsewhere:
+
+- its text round format, and
+- any rule to ask through AskUserQuestion.
+
+In this session the UI is the only channel for questions. Never print questions in the terminal.
+
+## 2. Start the bridge
+
+```bash
+node "${CLAUDE_SKILL_DIR}/dist/cli.js" start --title "<short topic>"
+```
+
+If `node` is not found or the command says Node is too old, stop and tell the user to install Node.js 20 or newer (https://nodejs.org), then end.
+
+It opens the browser and prints `{"session": "62950-a1b2c3", "url": …, "log": …}`. Remember the session handle: every later command takes `-s SESSION`, exactly as printed. Other Claude sessions may run their own bridges at the same time; the handle is what keeps you on yours. Tell the user the URL in one line.
+
+## 3. Post a round
+
+Pipe JSON on stdin with a quoted heredoc:
+
+```bash
+node "${CLAUDE_SKILL_DIR}/dist/cli.js" round -s SESSION <<'EOF'
+{
+  "title": "Optional round title",
+  "questions": [
+    {
+      "title": "Short question, ends with ?",
+      "body": "Markdown. Context, why it matters, what hangs off it.",
+      "options": [
+        { "label": "Option", "description": "What it means, trade-off" }
+      ],
+      "recommended": 0,
+      "recommendation": "Markdown. Your recommended answer and why.",
+      "multiSelect": false
+    }
+  ]
+}
+EOF
+```
+
+- The bridge numbers questions `Q1`, `Q2`, … across the whole session and prints the ids. Use them in later commands.
+- `recommended` is an index into `options`. Do not write "(Recommended)" into labels; the UI marks it.
+- Do not add an "Other" option. The user can always type an own answer and open a discussion.
+- `options` may be empty for an open question.
+
+## 4. Wait for the user
+
+```bash
+node "${CLAUDE_SKILL_DIR}/dist/cli.js" wait -s SESSION
+```
+
+**Always run it with `run_in_background: true`.** It blocks until the user does something, which can take hours. You are notified when it exits; then read its output. Keep exactly one wait running: after handling events, start the next wait straight away. While a wait runs you may do other work (sub-agents for facts).
+
+Output:
+
+```json
+{
+  "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" }
+  ],
+  "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.
+
+## 5. Handle events
+
+- **answer**: the user pressed **Send**, which only works when every question is answered, so answers arrive together as one complete round. Recompute the frontier and post the next round, exactly as in `grilling`.
+  - `by: "claude"`: your own resolution (below), which the user sent back unchanged.
+  - `revised: true`: the user changed an answer you already had. Re-check everything that depended on it.
+- **chat**: the user wants to talk about that question. Reply in its thread:
+
+  ```bash
+  node "${CLAUDE_SKILL_DIR}/dist/cli.js" reply -s SESSION Q3 <<'EOF'
+  Markdown reply.
+  EOF
+  ```
+
+  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.
+- **summary_confirmed / summary_rejected / ended**: see step 6.
+
+## 5b. Shape questions from the discussion
+
+The UI is yours to keep accurate. After a chat, change the questions to match what was said:
+
+- **Settled in the discussion** → resolve it for the user. Pick option indexes, write text, or both. Use text alone when the agreed answer is none of the options (a custom solution). The user sees "resolved by Claude" and can still change it before Send.
+
+  ```bash
+  node "${CLAUDE_SKILL_DIR}/dist/cli.js" resolve -s SESSION Q6 <<'EOF'
+  { "options": [1], "text": "TanStack Query, and the SSE stream writes into the `['session']` cache." }
+  EOF
+  ```
+
+- **Question was framed wrong, or options need changing** → edit it. Send only the fields that change. `null` clears `recommended` / `recommendation`. Sending `options` clears any answer on it, because the answer may point at old options.
+
+  ```bash
+  node "${CLAUDE_SKILL_DIR}/dist/cli.js" edit -s SESSION Q4 <<'EOF'
+  { "title": "Better title?", "options": [{ "label": "A" }, { "label": "B" }], "recommended": 0 }
+  EOF
+  ```
+
+- **No longer matters** → drop it (it stays visible, struck through, with your reason):
+
+  ```bash
+  node "${CLAUDE_SKILL_DIR}/dist/cli.js" drop -s SESSION Q4 <<'EOF'
+  Moot: you chose memory-only state.
+  EOF
+  ```
+
+- **Discussion surfaced a new question for this round** → add it to the current round instead of starting a new one. Fails once the user has sent that round; then it belongs in the next round.
+
+  ```bash
+  node "${CLAUDE_SKILL_DIR}/dist/cli.js" add -s SESSION <<'EOF'
+  { "questions": [{ "title": "…?", "body": "…", "options": [] }] }
+  EOF
+  ```
+
+In the thread, say in one line what you changed ("Resolved Q6 as TanStack Query + SSE cache.").
+
+## 6. Finish
+
+When the frontier is empty and `open` is empty, post a summary of every settled decision (by question id) and remaining risks, then wait:
+
+```bash
+node "${CLAUDE_SKILL_DIR}/dist/cli.js" summary -s SESSION <<'EOF'
+### Settled
+- **Q1 First user:** solo developers
+EOF
+```
+
+- `summary_confirmed`: run `grill stop -s SESSION`, then print the summary in the terminal as your final output. Act on it only if the user asks.
+- `summary_rejected`: its `text` is new input. Keep grilling, then post a new summary.
+- `ended` (user closed the session in the UI, at any time): run `grill stop -s SESSION` and print what was settled so far.
+
+## Terminal etiquette
+
+Between tool calls print at most one short line (for example "Round 3 posted."). All content belongs in the UI.
+
+## Troubleshooting
+
+- `No bridge for session …` (exit 2): the bridge is gone. It exits on its own after 30 minutes with no wait running and no browser tab open, and it can crash. Start a new one; the old session state is gone.
+- `Wrong session: …` (exit 1): you used a handle that isn't yours, and it reached another session's bridge. Find the `session` your own `grill start` printed and retry with it. Never take a handle from `ps`, a log file or another session. If you can't find yours, start a new bridge.
+- Exit 1 with a validation message: fix the JSON and post again.
+- `grill state -s SESSION` prints the full session state.
+- Bridge log path is printed by `grill start`.