@hyperlogue/r3 0.13.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +70 -177
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
<img src="web/favicon.svg" alt="r3 logo" width="120" height="120">
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
|
-
<h1 align="center">r3:
|
|
5
|
+
<h1 align="center">r3: Render. Review. Refine.</h1>
|
|
6
6
|
|
|
7
|
-
<p align="center"><b>
|
|
7
|
+
<p align="center"><b>View AI-generated artifacts. Give precise feedback.</b><br>HTML pages, Markdown documents, and code from any coding agent.</p>
|
|
8
8
|
|
|
9
9
|
<p align="center">
|
|
10
10
|
<a href="https://www.npmjs.com/package/@hyperlogue/r3"><img src="https://img.shields.io/npm/v/@hyperlogue/r3?color=cb3837&logo=npm&label=%40hyperlogue%2Fr3" alt="npm version"></a>
|
|
@@ -13,200 +13,93 @@
|
|
|
13
13
|
<a href="https://hyperlogue.github.io/r3/demo/"><img src="https://img.shields.io/badge/live-demo-6164ff?logo=googlechrome&logoColor=white" alt="live demo"></a>
|
|
14
14
|
</p>
|
|
15
15
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
quietly dropped two turns ago.
|
|
20
|
-
|
|
21
|
-
r3 is a local review tool for what your coding agent writes. Your agent opens a review
|
|
22
|
-
of its diff or its doc, you leave notes on the exact lines, and it works through them
|
|
23
|
-
one at a time. This is the loop you already know from code review, running entirely on your
|
|
24
|
-
own machine.
|
|
25
|
-
|
|
26
|
-
- **Your note sits on the line it's about.** Select a line of code, or a sentence
|
|
27
|
-
inside a rendered Markdown doc, and type. Nothing gets pasted into a chat window to
|
|
28
|
-
explain which part you meant.
|
|
29
|
-
- **The agent is waiting to revise.** It blocks on `r3 watch` while you read. Hit
|
|
30
|
-
Submit and it wakes with your notes; its replies show up in the browser without a
|
|
31
|
-
refresh.
|
|
32
|
-
- **Every note is tracked to resolution.** Each one carries its own thread and status,
|
|
33
|
-
so three rounds later you can still see which four are open.
|
|
34
|
-
|
|
35
|
-
<div align="center">
|
|
36
|
-
<video src="https://github.com/user-attachments/assets/0c1aefaf-0229-49e7-a4dc-e660dc0214f6" width="760" muted controls></video>
|
|
37
|
-
</div>
|
|
16
|
+
r3 is a tool for reading, using, and discussing agent output.
|
|
17
|
+
Open an interactive page, read a document, or inspect code changes. Select an
|
|
18
|
+
element or passage to leave feedback and continue the conversation with your agent.
|
|
38
19
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
```
|
|
20
|
+
Agents publish artifacts through a CLI or HTTP API. r3 works with any agent that
|
|
21
|
+
can run the CLI.
|
|
42
22
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
23
|
+
[Try the browser demo](https://hyperlogue.github.io/r3/demo/) to explore HTML,
|
|
24
|
+
Markdown, and diff feedback with a scripted agent. It uses bundled examples;
|
|
25
|
+
production preview protection is not simulated.
|
|
46
26
|
|
|
47
|
-
|
|
27
|
+
[](https://github.com/user-attachments/assets/26506cba-3d1a-493c-9c7a-e6ae2227718c)
|
|
48
28
|
|
|
49
|
-
|
|
29
|
+
## Screenshots
|
|
50
30
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
31
|
+
| Screenshot | What it shows |
|
|
32
|
+
| --- | --- |
|
|
33
|
+
| [](https://github.com/user-attachments/assets/2dec1368-6679-47cb-aa19-bfeb6228a7d6) | Review a UI improvement proposal and leave comments directly on HTML elements. |
|
|
34
|
+
| [](https://github.com/user-attachments/assets/396df7ca-661e-414d-952b-0a6325638c62) | Learn how a library works internally through an interactive demo. |
|
|
35
|
+
| [](https://github.com/user-attachments/assets/8e85f3d9-d03b-45ec-b478-fe7fe109ef19) | Codex receives a direct message from r3 when you ping the agent from the web page. |
|
|
55
36
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
loop until you Approve or Abandon
|
|
64
|
-
A->>S: [2] `r3 watch` (blocks for feedback)
|
|
65
|
-
U->>S: [3] leave feedback + Submit
|
|
66
|
-
S-->>A: `r3 watch` prints your feedback to stdout and exits
|
|
67
|
-
A->>S: [4] `r3 claim` feedback being worked
|
|
68
|
-
S-->>U: working indicator appears live
|
|
69
|
-
A->>S: [5] `r3 reply` by feedback id (releases claim)
|
|
70
|
-
S-->>U: [6] reply + claim release update live
|
|
71
|
-
end
|
|
37
|
+
## Get started
|
|
38
|
+
|
|
39
|
+
Install globally to make the `r3` command available on your PATH:
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
npm install -g @hyperlogue/r3
|
|
43
|
+
# Or: bun add -g @hyperlogue/r3
|
|
72
44
|
```
|
|
73
45
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
**Submit**. `watch` prints your feedback to stdout that's captured by the agent.
|
|
79
|
-
4. The agent claims the items it starts (`r3 claim <fid>...`), so the UI shows
|
|
80
|
-
which session is actively working. Claims are 60-minute leases and can be
|
|
81
|
-
renewed by repeating the command.
|
|
82
|
-
5. The agent works each item and **replies by feedback id**
|
|
83
|
-
(`r3 reply <fid> -m "what I changed"`), saying what it changed, or the
|
|
84
|
-
reasoning for why it didn't. A successful agent reply releases that claim.
|
|
85
|
-
6. Every reply lands on the web UI through live updates. The agent `watch`es again
|
|
86
|
-
until you **Approve** or **Abandon** the review.
|
|
87
|
-
|
|
88
|
-
## Quick start
|
|
89
|
-
|
|
90
|
-
r3 is driven by your coding agent, so the quickest start is to point your agent at
|
|
91
|
-
it. Drop this into your agent's instructions file (`AGENTS.md`, `CLAUDE.md`, or
|
|
92
|
-
your tool's equivalent), or just try it out by pasting it into a new session:
|
|
93
|
-
|
|
94
|
-
```md
|
|
95
|
-
This project uses r3 for review. Run it with whichever of these you have:
|
|
96
|
-
`r3` (if installed), `npx @hyperlogue/r3@latest`, `bunx @hyperlogue/r3@latest`, or
|
|
97
|
-
`nix run github:hyperlogue/r3 --`. `r3 guide` will show how to use it.
|
|
46
|
+
Or run it without installing `r3` on your PATH:
|
|
47
|
+
|
|
48
|
+
```sh
|
|
49
|
+
npx @hyperlogue/r3@latest
|
|
98
50
|
```
|
|
99
51
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
your agent uses lazily starts the web server on localhost and opens the review.
|
|
52
|
+
Ask your agent to run `r3 guide` and publish an artifact. The guide explains how
|
|
53
|
+
to publish, listen for feedback, and reply. Open the artifact URL from your agent, or visit
|
|
54
|
+
`http://127.0.0.1:8791/` for the full list.
|
|
104
55
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
http://127.0.0.1:8791/ to see every project's reviews in one tab.
|
|
56
|
+
Local Claude Code and Codex publications set up feedback delivery automatically,
|
|
57
|
+
so you can send feedback from the artifact page. Other agents can work from a
|
|
58
|
+
copied feedback prompt.
|
|
109
59
|
|
|
110
|
-
|
|
111
|
-
keyed by a **projects registry** (so worktrees of one clone are one project and
|
|
112
|
-
copies stay separate), and the web server announces itself in `$XDG_RUNTIME_DIR/r3/daemon.json`
|
|
113
|
-
so the CLI finds it with zero config. Run the CLI from any git repo, and it tells
|
|
114
|
-
the web server which project/worktree the call targets.
|
|
60
|
+
## Artifact types
|
|
115
61
|
|
|
116
|
-
|
|
117
|
-
`r3 create`:
|
|
62
|
+
r3 supports three kinds of artifacts:
|
|
118
63
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
64
|
+
| Artifact | What you can do | Examples |
|
|
65
|
+
| --- | --- | --- |
|
|
66
|
+
| HTML pages | Interact with a page and leave feedback on specific elements or text | Prototypes, dashboards, interactive tutorials |
|
|
67
|
+
| Documents and files | Read rendered Markdown, browse related files, and discuss specific passages or lines | Design proposals, research reports, generated project files |
|
|
68
|
+
| Code changes | See what changed and discuss it beside the affected lines | Bug fixes, refactors, feature reviews |
|
|
122
69
|
|
|
123
|
-
|
|
124
|
-
|
|
70
|
+
HTML artifacts open as pages; files artifacts have a file browser; diff artifacts
|
|
71
|
+
show captured code changes.
|
|
125
72
|
|
|
126
|
-
|
|
127
|
-
|
|
73
|
+
For ideas on using HTML for plans, reports, and interactive explanations, see
|
|
74
|
+
Anthropic's [The unreasonable effectiveness of HTML](https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html).
|
|
128
75
|
|
|
129
|
-
|
|
130
|
-
→ adhoc scratch review with no git source
|
|
131
|
-
```
|
|
76
|
+
## Local and remote access
|
|
132
77
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
Feedback anchors to a **quote**, not a line number: in a files review your notes
|
|
146
|
-
follow the code as it's edited; in a diff review the rounds are immutable, so
|
|
147
|
-
nothing drifts.
|
|
148
|
-
|
|
149
|
-
## How r3 compares to similar tools
|
|
150
|
-
|
|
151
|
-
| Tool | How r3 differs |
|
|
152
|
-
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
153
|
-
| [difit](https://github.com/yoshiko-pg/difit) / [diffx](https://github.com/wong2/diffx) | r3 makes the review loop live. The agent `watch`es, you Submit, replies land back in the UI, tracking every item to resolution. r3 also supports raw text files like design docs, not just diffs. |
|
|
154
|
-
| GitHub / GitLab PRs | r3 drives the local pre-PR loop with your agent: nothing needs a remote, a push, or even a commit. |
|
|
155
|
-
| AI review bots (CodeRabbit, Copilot code review, …) | In r3 _you_ review the AI's work: the agent is the author, addressing your feedback. |
|
|
156
|
-
|
|
157
|
-
If you want a one-shot look at a diff with no state left behind, difit and diffx
|
|
158
|
-
are good enough. r3 shines when the review outgrows a single pass — feedback
|
|
159
|
-
spans several rounds, and each item keeps its thread and status until it's
|
|
160
|
-
resolved.
|
|
161
|
-
|
|
162
|
-
## Remote access
|
|
163
|
-
|
|
164
|
-
If you work on a remote dev server, r3 listens on loopback there, and you reach
|
|
165
|
-
its web UI from your local device through a tunnel. Set one up however you like: an SSH
|
|
166
|
-
forward (`ssh -L 8791:localhost:8791 devbox`), `tailscale serve`, or a Cloudflare
|
|
167
|
-
tunnel. **Never** bind `0.0.0.0`.
|
|
168
|
-
|
|
169
|
-
**Exposing r3 beyond loopback turns on an optional login gate.** It's pure security
|
|
170
|
-
hardening — **on by default whenever r3 is exposed** (a non-loopback bind, a
|
|
171
|
-
non-loopback `R3_PUBLIC_URL`, or a non-loopback `R3_ALLOWED_HOSTS`), and **off on a plain
|
|
172
|
-
`localhost:8791`** so the default setup needs
|
|
173
|
-
no login at all. Over an SSH forward you browse `localhost`, so nothing changes. When
|
|
174
|
-
it's on, create a token on the host and paste it into the browser once: the browser
|
|
175
|
-
posts that **login token** to the daemon to mint an HttpOnly session cookie, and from
|
|
176
|
-
then on holds only the cookie. (The login token is a scoped, revocable credential; the
|
|
177
|
-
daemon's own per-user API token — the CLI's credential — is never handed to a browser
|
|
178
|
-
when exposed.) Force it either way with `R3_REQUIRE_LOGIN=1|0`.
|
|
179
|
-
|
|
180
|
-
> **Behind your own reverse proxy, set `R3_REQUIRE_LOGIN=1`.** r3 decides whether
|
|
181
|
-
> to require a login from its own bind + advertised host — it can't see that
|
|
182
|
-
> through a proxy that rewrites the `Host` header to `127.0.0.1` (nginx's default
|
|
183
|
-
> `proxy_pass`), which reads as loopback-only and hands the browser the per-user
|
|
184
|
-
> token. Setting `R3_PUBLIC_URL` to the public name fixes it too; `tailscale serve`
|
|
185
|
-
> forwards the real host, so it's already covered.
|
|
78
|
+
r3 runs locally by default. The CLI lazily starts a background daemon when a
|
|
79
|
+
command first needs the server. The daemon serves the browser UI and stores
|
|
80
|
+
artifacts and feedback. It listens only on loopback; local browser access works
|
|
81
|
+
without a login unless you enable one.
|
|
82
|
+
|
|
83
|
+
For remote access, use an HTTPS reverse proxy or tunnel, such as Tailscale Serve,
|
|
84
|
+
pointing to `http://127.0.0.1:8791/`. Forward the whole application, including
|
|
85
|
+
`/__r3_preview/`, and set `X-Forwarded-Proto: https` at the proxy. Previews use the
|
|
86
|
+
same address; no wildcard DNS or separate preview port is needed.
|
|
87
|
+
|
|
88
|
+
Set your public URL and explicitly require login before exposing r3. Replace the
|
|
89
|
+
example URL below with your proxy address:
|
|
186
90
|
|
|
187
91
|
```sh
|
|
188
|
-
|
|
189
|
-
r3 config set
|
|
190
|
-
r3 restart
|
|
191
|
-
|
|
192
|
-
r3 auth create-token --label laptop # prints the token once — paste it in the browser
|
|
92
|
+
r3 config set publicUrl https://reviews.example
|
|
93
|
+
r3 config set requireLogin 1
|
|
94
|
+
r3 restart
|
|
95
|
+
r3 auth create-token --label browser
|
|
193
96
|
```
|
|
194
97
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
`r3 auth list-tokens` / `r3 auth revoke-token <id> | --all` manage tokens (revoking
|
|
204
|
-
kills its sessions immediately).
|
|
205
|
-
|
|
206
|
-
Settings: `R3_PORT` (default 8791), `R3_BIND` (default `127.0.0.1`), `R3_ALLOWED_HOSTS`
|
|
207
|
-
(comma-separated exact Host names, never `*`; a non-loopback name here also marks r3
|
|
208
|
-
exposed), `R3_PUBLIC_URL` (a non-loopback host is auto-allowed **and** marks r3
|
|
209
|
-
exposed, so this alone covers the common single-name `tailscale serve` case), `R3_REQUIRE_LOGIN`
|
|
210
|
-
(`1`/`0` to force the login requirement on or off explicitly). Each resolves
|
|
211
|
-
**env → `config.json` (via `r3 config set`) → default**, so env overrides the
|
|
212
|
-
persisted file for a single run.
|
|
98
|
+
Use the generated login token to sign in. Browser sessions and login tokens are
|
|
99
|
+
revocable. r3 is a single-owner tool: a valid login grants access to all artifacts
|
|
100
|
+
on that instance, with no per-artifact sharing permissions.
|
|
101
|
+
|
|
102
|
+
Your agent can publish from a different machine: it uploads the artifact's files,
|
|
103
|
+
so the machine running r3 does not need a copy of your project.
|
|
104
|
+
See the [security model](.claude/skills/security-model/SKILL.md) for authentication
|
|
105
|
+
and preview isolation details.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hyperlogue/r3",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "1.0.1",
|
|
4
|
+
"description": "Render. Review. Refine. — view artifacts and give precise feedback to any coding agent. Runs the matching prebuilt native r3 binary (shipped as a per-platform optional dependency); works with `bunx @hyperlogue/r3` and `npx @hyperlogue/r3`.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"publishConfig": {
|
|
@@ -17,10 +17,10 @@
|
|
|
17
17
|
"launch.mjs"
|
|
18
18
|
],
|
|
19
19
|
"optionalDependencies": {
|
|
20
|
-
"@hyperlogue/r3-darwin-arm64": "0.
|
|
21
|
-
"@hyperlogue/r3-darwin-x64": "0.
|
|
22
|
-
"@hyperlogue/r3-linux-x64": "0.
|
|
23
|
-
"@hyperlogue/r3-linux-arm64": "0.
|
|
20
|
+
"@hyperlogue/r3-darwin-arm64": "1.0.1",
|
|
21
|
+
"@hyperlogue/r3-darwin-x64": "1.0.1",
|
|
22
|
+
"@hyperlogue/r3-linux-x64": "1.0.1",
|
|
23
|
+
"@hyperlogue/r3-linux-arm64": "1.0.1"
|
|
24
24
|
},
|
|
25
25
|
"engines": {
|
|
26
26
|
"node": ">=18"
|