|
| 1 | +--- |
| 2 | +name: pyclawd-web |
| 3 | +description: The `pyclawd web` dashboard — a local, multi-project diff & code-review UI (the optional `pip install pyclawd[web]` extra). Browse the working diff across registered repos; view any file as syntax-highlighted **Source** or a rendered **preview** (Markdown renders GFM + GitHub alerts `> [!NOTE]` + emoji; HTML renders in a sandboxed, script-free iframe); leave **line-anchored review comments** on diff lines, on rendered-Markdown blocks, and on rendered-HTML elements; assemble them into one review and either send it to a running `claude` tmux pane or hand it to a headless agent to resolve. Also runs pyclawd verbs (check/test/golden/…) from the UI and edits/deletes files in the browser. Use when a human wants to review a diff or an agent's work in a browser, or when an agent needs to know what the dashboard renders and how comments flow. |
| 4 | +when_to_use: Reviewing a working diff or an agent's changes in a browser; collecting inline review comments and handing them to a tmux pane or a headless fix-agent; previewing how a Markdown doc (alerts / emoji / tables / task lists) or an HTML file will actually render; running `pyclawd check`/`test`/`golden` from a UI. Also relevant when an agent authors Markdown in the repo — it can use GitHub alerts and emoji knowing the dashboard renders them. |
| 5 | +--- |
| 6 | + |
| 7 | +# pyclawd-web |
| 8 | + |
| 9 | +`pyclawd web` is an **optional** local dashboard for reviewing diffs and driving |
| 10 | +review workflows in a browser. It is not part of the core install — a project (or |
| 11 | +you) must `pip install 'pyclawd[web]'` (FastAPI + uvicorn + watchfiles). The core |
| 12 | +`pyclawd` CLI never depends on it; when the extra is absent the `web` commands |
| 13 | +self-report. |
| 14 | + |
| 15 | +It is the **human side of the agent loop**: an agent makes changes on a branch / |
| 16 | +working tree, a human browses the diff, leaves inline comments, and then either |
| 17 | +sends those comments to the `claude` pane that is doing the work, or dispatches a |
| 18 | +fresh headless agent to resolve them. |
| 19 | + |
| 20 | +## Run it |
| 21 | + |
| 22 | +```bash |
| 23 | +pip install 'pyclawd[web]' # one-time, the optional extra |
| 24 | +pyclawd web serve # dashboard on http://127.0.0.1:8801 |
| 25 | +pyclawd web serve --host 0.0.0.0 --port 8830 --repo /path/to/repo |
| 26 | +pyclawd web add <path> [--name N] # register a repo |
| 27 | +pyclawd web list # list registered + auto-discovered repos |
| 28 | +pyclawd web remove <name> |
| 29 | +``` |
| 30 | + |
| 31 | +It auto-discovers git repos under configured roots (default `~/workspace`) and |
| 32 | +tracks a working diff live (a filesystem watcher pushes updates over SSE — no |
| 33 | +polling). It is **multi-project**: switch repos and comparison refs (any branch / |
| 34 | +tag / SHA / the working tree) from the top bar. |
| 35 | + |
| 36 | +## Viewing a file — Source ⟷ Rendered |
| 37 | + |
| 38 | +Every file opens in **Source**: the syntax-highlighted diff (inline or split) or |
| 39 | +full-file view, with a comment gutter. For **`.md` / `.html`** files a |
| 40 | +**Source | Rendered** toggle appears in the file header (the choice is **sticky** — |
| 41 | +it persists until you switch back): |
| 42 | + |
| 43 | +- **Markdown → Rendered** renders the doc richly: GitHub-Flavored Markdown (tables, |
| 44 | + task lists, strikethrough), **GitHub alerts** (`> [!NOTE]` / `[!TIP]` / |
| 45 | + `[!IMPORTANT]` / `[!WARNING]` / `[!CAUTION]` → colored callout boxes with icons), |
| 46 | + and **emoji shortcodes** (`:rocket:` → 🚀). Code fences render as plain preformatted |
| 47 | + text. |
| 48 | +- **HTML → Rendered** renders the page in an iframe sandboxed to `allow-same-origin` |
| 49 | + only — **repo scripts never run** (safe) and styles stay isolated. |
| 50 | + |
| 51 | +**Authoring implication for agents:** a Markdown doc you write in the repo will |
| 52 | +render with those features in the dashboard — so use `> [!NOTE]`/`[!WARNING]` |
| 53 | +callouts and emoji to make a hand-off / summary doc read well when a human previews |
| 54 | +it. |
| 55 | + |
| 56 | +## Commenting — one line-anchored model across every view |
| 57 | + |
| 58 | +Comments are always **anchored to a source line** and share **one store**, so the |
| 59 | +same comment shows up everywhere and feeds the review: |
| 60 | + |
| 61 | +- **Source / diff view** — click the 💬 gutter on a line (old or new side). |
| 62 | +- **Rendered Markdown** — hover a block, click 💬; the comment anchors to that |
| 63 | + block's source line and shows as a **persistent inline thread** right below it |
| 64 | + (commented blocks get an amber highlight). Edit/delete inline. |
| 65 | +- **Rendered HTML** — click any element; the comment anchors to that element's |
| 66 | + source line (the element gets a gold outline) and shows in a list below the page. |
| 67 | + |
| 68 | +Flip between Source and Rendered freely — it's the same comment either way. |
| 69 | + |
| 70 | +## Turning comments into action (the Review tray) |
| 71 | + |
| 72 | +The **Review (N)** tray lists every staged comment grouped by file. From there: |
| 73 | + |
| 74 | +- **Send → tmux** — assemble the comments into one structured message and paste it |
| 75 | + into the selected running `claude` tmux pane (pick the pane in the session picker). |
| 76 | +- **Copy** — copy the assembled review to the clipboard. |
| 77 | +- **🤖 Run (edits only / full access)** — dispatch a **headless `claude -p` agent** |
| 78 | + that resolves every comment (edits auto-accepted); progress streams live in the UI. |
| 79 | + |
| 80 | +So the loop is: agent works → human reviews the diff and leaves inline comments → |
| 81 | +one click sends them back to the same agent, or spins up a new one to fix them. |
| 82 | + |
| 83 | +## Also in the dashboard |
| 84 | + |
| 85 | +- **Verb runner** — run `pyclawd check` / `test` / `golden` / `lint` / `typecheck` / |
| 86 | + `format` / `doctor` from the UI; output streams with a pass/fail verdict. |
| 87 | +- **File edit / delete** — edit a file's working-tree content or delete it in the |
| 88 | + browser (the diff refreshes live). |
| 89 | +- **Sessions** — list running `claude` tmux panes to target with a review. |
| 90 | + |
| 91 | +## Boundaries |
| 92 | + |
| 93 | +- The `[web]` deps are an **optional extra** — never assume they're installed; the |
| 94 | + core CLI (`check`/`test`/`golden`/…) is the contract, the dashboard is a |
| 95 | + convenience over it. |
| 96 | +- Rendered views are for **preview + commenting**; the authoritative diff/lint/type |
| 97 | + signal is still `pyclawd check`. The dashboard runs those verbs, it doesn't replace |
| 98 | + them. |
0 commit comments