knarr 0.1.0__tar.gz

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.
knarr-0.1.0/LICENSE ADDED
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
knarr-0.1.0/NOTICE ADDED
@@ -0,0 +1,4 @@
1
+ Knarr
2
+ Copyright 2026 Ron Hermansen
3
+
4
+ Licensed under the Apache License, Version 2.0 (see LICENSE).
knarr-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,296 @@
1
+ Metadata-Version: 2.4
2
+ Name: knarr
3
+ Version: 0.1.0
4
+ Summary: An MCP server that lets an AI agent work through a website toward a goal with guarded browser tools: writes blocked, origin pinned, destructive clicks refused.
5
+ Author: Ron Hermansen
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/ywapom/knarr
8
+ Project-URL: Repository, https://github.com/ywapom/knarr
9
+ Project-URL: Issues, https://github.com/ywapom/knarr/issues
10
+ Keywords: mcp,browser,playwright,agent,claude,testing
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: MacOS
14
+ Classifier: Operating System :: POSIX :: Linux
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Software Development :: Testing
19
+ Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
20
+ Requires-Python: >=3.12
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ License-File: NOTICE
24
+ Requires-Dist: mcp<2,>=1.13
25
+ Requires-Dist: playwright<2,>=1.48
26
+ Requires-Dist: pyyaml<7,>=6.0
27
+ Requires-Dist: websockets<16,>=12
28
+ Provides-Extra: dev
29
+ Requires-Dist: pytest>=8; extra == "dev"
30
+ Dynamic: license-file
31
+
32
+ # Knarr
33
+
34
+ *A knarr was the Viking ocean-going ship: built to sail somewhere new and come back intact.*
35
+
36
+ Knarr lets an AI agent work through a website toward a goal you set, using a small set of guarded browser tools. The run passes only when the page shows the success criterion fixed at the start; the agent can't change it partway or grade itself with other text. It works on any site you can open in a browser, including ones you're logged in to.
37
+
38
+ It runs as an MCP server: Claude (in Claude Code, or any MCP client) drives the browser tools in your conversation.
39
+
40
+ ## How it works
41
+
42
+ You give Knarr a start URL, a goal and a success criterion. Each turn the agent:
43
+
44
+ 1. Reads the page as a numbered list of controls, e.g. `[3] button 'Place order'`.
45
+ 2. Acts: clicks by number or by text, fills a field, submits, navigates or waits.
46
+ 3. Repeats until `assert_state` finds the success criterion on the page, the agent gives up, or a limit is reached.
47
+
48
+ Guards around every action:
49
+
50
+ - **URL boundary.** Navigation must stay on the start URL's origin, or inside a manifest's URL patterns. From Claude Code, the page's real origin is checked before and after every call. If your own action (a click, a fill, a submit) took the page elsewhere, it's sent back to the start page and counts as a violation; three end the run. If the page went elsewhere by itself, such as a late redirect to a sign-in page, Knarr lets the sign-in finish, follows it again with your login, and counts no violation. A site that keeps sending the page to the same place ends the run as `login_required`, and a new session can start once you've signed in. The guard returns only to a page Knarr chose to load (the start page), never to one a click landed on, so it can't repeat a link that changes data.
51
+ - **Forbidden actions.** Actions on destructive or irreversible verbs (Delete, Archive, Publish, Approve, Send Request and others) are refused, including a `submit` that would hit a button such as "Save and Publish". A [site profile](#site-profiles) can add verbs for one site (a shop's "Buy now", say). Three refusals end the run.
52
+ - **Writes blocked** by default. Requests that could change data (anything but GET, HEAD and OPTIONS, plus outgoing WebSocket messages) are answered with a fake success and recorded instead of being sent. Clicks still really happen, so the agent can explore; nothing is saved.
53
+ - **Its own browser.** Knarr always runs its own browser, so every request, new tabs included, goes through the write block, and it's closed at the end.
54
+ - **Limits.** Turns (default 30), wall clock (15 minutes), tokens (500k) and memory.
55
+
56
+ Each run writes a record of every tool call (`trace.jsonl`) and a `summary.json`. The record keeps what you typed into a field out of the file (it holds the field's label and the length of the text, since a field may be a password), and removes the text from error messages that repeat it. A URL in either file loses its `user:password@`, the values of parameters named like credentials (`code`, `token`, `session`, `password` and the like) and values that look like random tokens, in the query and in the `#` part; the parameter names stay. Each trace line has its own UTC time (`at`), and `summary.json` says who ran the session (`user`, the operating-system account) and when it started and ended (`started_at`, `ended_at`). With `KNARR_TRACE=1` it also writes a Playwright trace you can open with `python3 -m playwright show-trace trace.zip`; traces record page contents, typed text, request headers and bodies, and cookies, so they hold the session's login and whatever was typed.
57
+
58
+ ## Use it from Claude Code
59
+
60
+ If you use the plugin (step 2), `/knarr:install` walks through steps 1 and 3 with you, one command at a time, and ends with `/knarr:doctor`.
61
+
62
+ **1. Install uv.** The plugin starts the server with `uvx knarr`, which fetches the [`knarr`](https://pypi.org/project/knarr/) package from PyPI, with a Python 3.12+ for it, the first time it runs. See [docs.astral.sh/uv](https://docs.astral.sh/uv/) to install uv. To fetch a newer release later:
63
+
64
+ uvx --refresh --from knarr knarr-doctor
65
+
66
+ **2. Add it to Claude Code**, either as a plugin (MCP server plus a skill that teaches Claude how to use it):
67
+
68
+ /plugin marketplace add ywapom/knarr
69
+ /plugin install knarr@knarr
70
+
71
+ or as a bare MCP server:
72
+
73
+ claude mcp add knarr -- uvx knarr
74
+
75
+ **3. Give it a browser.** Either download Playwright's Chromium, for the Playwright version Knarr uses:
76
+
77
+ uvx --from knarr playwright install chromium
78
+
79
+ or use the Google Chrome you already have, by setting `KNARR_BROWSER_CHANNEL=chrome` in the environment Claude Code starts with (an `env` entry in `~/.claude/settings.json`, or an `export` before you start it). Chrome needs no download.
80
+
81
+ **Without uv.** Install the package with pip into a Python 3.12 or newer, and add the server for that Python:
82
+
83
+ python3 -m pip install knarr
84
+ python3 -m playwright install chromium
85
+ claude mcp add knarr -- python3 -m knarr.mcp
86
+
87
+ The ranges in `pyproject.toml` all have an upper bound, and `requirements.lock` holds the exact versions the whole test suite passed on (mcp 1.30.0, Playwright 1.64.1 and what they pull in). To install exactly those, from a clone: `python3 -m pip install -r requirements.lock`, then `python3 -m pip install --no-deps .`. The doctor fails if an installed package is outside the ranges.
88
+
89
+ Then ask Claude something like *"Use Knarr to check that placing an order on http://localhost:3000 shows 'Order placed'"*.
90
+
91
+ Claude calls the tools in this order:
92
+ 1. `session_start` with the start URL, the goal and a **success criterion**: the text that will be on the page when the goal is reached, in quotes, e.g. `the page shows 'Order placed'`. It's required and can't be changed during the session.
93
+ 2. `read_page`, `click_index`, `fill` and the other browser tools.
94
+ 3. `assert_state`, which checks the page against that criterion (every quoted phrase must be visible), or `give_up`.
95
+ 4. `session_end`, which returns the summary and the run directory.
96
+
97
+ Every tool result ends with a status line, e.g. `[knarr] call 4 of 30, 880 s of browser time left`. Once the run ends, further calls are refused.
98
+
99
+ ### Check your setup
100
+
101
+ Run `/knarr:doctor` in Claude Code, or `uvx --from knarr knarr-doctor` in a terminal (`knarr-doctor` if you installed with pip). It checks:
102
+ - the Python that runs it, and that `uvx`, which the plugin starts the server with, is on your PATH;
103
+ - the installed packages and their versions;
104
+ - your `KNARR_*` settings (a misspelt name, a bad allow pattern, a missing saved-login file, writes allowed, tracing on);
105
+ - the browser: it starts one the way a session does, loads a local page that tries to write, and checks that the write block held the write back;
106
+ - the Chrome you borrow a login from (`KNARR_CDP_URL`): that it answers, how many tabs are open, and that it hands over its cookies (only a count is printed). If it isn't set up, it prints the command to start Chrome;
107
+ - that the MCP server starts and lists its tools.
108
+
109
+ Each problem comes with the fix. `--quick` skips the browser and the server. It never opens a site, and exits 1 if anything failed.
110
+
111
+ The server runs one session at a time per conversation. Run output goes to `~/.knarr/runs/<run-id>/`.
112
+
113
+ The model chooses the start URL and the criterion. Everything after that is fixed by the session and your environment:
114
+ - the origin the start URL lands on, after any redirect;
115
+ - the destructive-verb list;
116
+ - the limits in the variables below.
117
+
118
+ The time limit counts only time the browser spends on tool calls, so waiting for you to approve a call doesn't use it up. A session with no calls for 15 minutes is closed. If a guard stops a session (too many boundary or forbidden-action violations), no new session can start in that conversation.
119
+
120
+ ## Turn a walkthrough into a Playwright project
121
+
122
+ Knarr drives the browser; Claude reads the pages, decides what to do next and writes the code. Together they can walk a flow once and leave you a script that repeats it. For example, ask Claude:
123
+
124
+ > Use Knarr to explore https://app.example.com. Walk the flow from the login page to the submit form, and write down each page's fields and buttons. Don't submit anything real. Then write a Python Playwright project that logs in, fills the form and submits it, using role and label locators.
125
+
126
+ Knarr lists each page as numbered controls with their role, label and visible text (`[3] button 'Place order'`). Claude clicks and fills its way through, then writes the project from what it saw. Every step is recorded in `trace.jsonl` in the run folder, so you can check the script against what actually happened.
127
+
128
+ What to know before you try it:
129
+ - **Login.** Knarr never logs in itself, and with writes blocked the login form's POST is faked. Either [borrow a login from your Chrome](#using-a-site-youre-logged-in-to), allow just that request with `KNARR_WRITE_ALLOW` (use a test account), or have Claude write the login step from the login page's fields without running it.
130
+ - **Submit.** The final submit is faked, so you can walk up to it and see the form, but nothing is saved and `assert_state` can't confirm the real result. Don't use `read_only` for this: it fakes every click, so Claude couldn't move between pages.
131
+ - **Selectors.** Knarr reports controls by role, label and text, not CSS selectors or test ids. That suits Playwright's `get_by_role` and `get_by_label`. A `data-testid` has to come from you.
132
+ - **The generated script isn't guarded.** Knarr's write block applies to Knarr's browser only. When you run the script against the real site, its submit really happens: use a test account or a test environment.
133
+
134
+ ## Using a site you're logged in to
135
+
136
+ Knarr doesn't log in for you. Either let it borrow the login from a Chrome you've already logged in to, or give it a saved login.
137
+
138
+ **Borrow your login from Chrome.** Start Chrome with a debugging port and a separate profile directory, log in to the site there, and keep a tab open on it:
139
+
140
+ "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
141
+ --remote-debugging-port=9222 --user-data-dir="$HOME/.knarr-chrome"
142
+
143
+ export KNARR_CDP_URL=http://127.0.0.1:9222
144
+
145
+ When a session starts, Knarr asks that Chrome, over a short DevTools connection, for two things, and keeps them in memory:
146
+ - the cookies Chrome would send to the start site;
147
+ - the site's localStorage, read from your open tab on it.
148
+
149
+ Then it launches its own browser with that copy. Single sign-on works the same way: if the page moves to other origins by itself (a redirect to your company's sign-in page, whether from the server or a script), Knarr borrows each origin's login in turn and loads the start URL again, up to four times, so the sign-in can finish. Before it starts, Knarr waits for the page to finish loading (a slow page included, up to a limit), for its requests to go quiet, and for a `Refresh` header or meta refresh to another origin to fire. A redirect from a timer or a slow script can't be seen in advance; Knarr follows it when it happens. Each reload of the sign-in loads the start URL again, so anything the page does on load (a request that `KNARR_WRITE_ALLOW` lets through, a GET that changes data) happens once per reload; pick a start URL that doesn't. If the sign-in is longer than four reloads, the start message says which origin's login wasn't borrowed. If you're not signed in at the provider, the session stays on the page it settled on (the sign-in page), the start message says where that is, and nothing counts as a violation.
150
+
151
+ Your tabs and any dialogs in them are left alone. A tab showing a dialog can't answer, so after 2 seconds Knarr skips its localStorage and says so; it doesn't wait. Cookies for other sites, sessionStorage and IndexedDB aren't copied. The start message says exactly what was borrowed, and says plainly when nothing was.
152
+
153
+ The session gets your login for the start site and for the sign-in sites the page sends it through, so approve a `session_start` only for a site you'd open with that login.
154
+
155
+ The DevTools connection is direct, so an `HTTP_PROXY` in your environment doesn't apply to it. `KNARR_CDP_URL` may be written as `http://127.0.0.1:9222` or as the `ws://` address Chrome prints. **It must be on your own machine** (`127.0.0.1`, `localhost` or `[::1]`, without a user name or password); anything else is refused and the session does not start, because anyone who can reach a Chrome debugging port controls that Chrome and every login in it, and Knarr asks it for cookies. The same rule holds for the WebSocket addresses Chrome's replies name, and a redirect from the DevTools address is not followed. Knarr never opens that endpoint as a page, whatever the spelling (`localhost`, `localhost.`, `127.1`, `[::1]`), and no request from its browser reaches it, whatever the page or the request type (a fetch, an `<img>`, a redirect): a page there could list, open and close your tabs. A refused request is noted in the result.
156
+
157
+ This works for sites that keep their login in cookies or localStorage, which covers most. If a site keeps it somewhere Knarr can't copy, it will start logged out. Logging in inside Knarr's browser won't work while writes are blocked, because the login form's POST is blocked too. In that case, either:
158
+ - let the login request through with `KNARR_WRITE_ALLOW`;
159
+ - or set `KNARR_ALLOW_WRITES=1` for that session.
160
+
161
+ Some single sign-on hands the login back to the site with a POST (SAML and OpenID Connect `form_post` do). While writes are blocked, that POST is blocked too, so the session would start on a "Blocked by Knarr" page; the start message says so. Allow that one request, e.g. `KNARR_WRITE_ALLOW=https://app.example.com/saml/acs`.
162
+
163
+ With Claude Code, set the variable in the shell you start Claude Code from.
164
+
165
+ **Saved login.** Point `KNARR_STORAGE_STATE` at a Playwright storage-state file. Knarr launches a browser with those cookies.
166
+
167
+ ## Safety
168
+
169
+ **Writes are blocked by default.** In Knarr's browser, every request other than GET, HEAD and OPTIONS is faked and recorded, not sent, along with outgoing WebSocket messages from pages. The block works at the browser level, so it covers:
170
+ - fetch and XHR;
171
+ - form posts, which show a "Blocked by Knarr" page;
172
+ - `sendBeacon`;
173
+ - iframes, including cross-site ones;
174
+ - new tabs the page opens;
175
+ - the requests current Chrome sends itself while a page unloads (`sendBeacon` and `fetch(keepalive)` on leaving a page or closing it).
176
+
177
+ A faked response to a cross-origin request carries the CORS headers that let the page read it, so the page sees a success, not a network error. A GET, HEAD or OPTIONS request that carries a body counts as a write.
178
+
179
+ Only the request types that can carry a write are paused (documents, XHR, fetch, pings, CSP reports and "other"). Images, scripts, stylesheets, fonts and media are only fetched with GET, so pages load at nearly normal speed.
180
+
181
+ Channels whose traffic can't be intercepted are shut off. Service workers are blocked. SharedWorker and WebSocketStream are removed by a browser flag in every frame and worker. WebTransport and RTCPeerConnection are disabled by a script in each page frame.
182
+
183
+ Knarr runs Chromium with its sandbox on. If that can't start where you run it (a container, say), set `KNARR_NO_SANDBOX=1`.
184
+
185
+ From Claude Code, each tool result lists the writes it blocked. `summary.json` and `session_end` report `dry_run`: true means writes were intercepted and none went out, as far as Knarr can see. It's false once a request let through by `KNARR_WRITE_ALLOW` has been sent, and false with `blocked_writes` and `allowed_writes` of `null` (not zero: not observed) when writes aren't intercepted.
186
+
187
+ `captured_writes.jsonl` in the run directory lists each request by:
188
+ - method, host and URL path. Credentials in a URL are never recorded. A path segment is shown as it is only if it has the shape of a route word (`orders`, `sign-in`, `getUser`, `v2`, `save.json`); an ID, token, code, email or anything with digits or odd characters is shown as `:param`. This is a guess from the shape, so a lowercase slug, a username or a coupon code in lowercase looks like a route word and is kept;
189
+ - the names of query parameters;
190
+ - the body's type (from its Content-Type) and size;
191
+ - the body's field names, where a parser for that type found them (JSON, URL-encoded and multipart forms).
192
+
193
+ A name is shown only if it looks like a field name (letters, digits and `_ . [ ]` `-`, up to 40 characters; not a UUID, a hash or a run of mixed case and digits). Anything else, such as JSON sent with a form Content-Type or a token, is only counted (`unnamed_fields`, `query_unnamed`), and a name you list in `KNARR_RECORD_FIELDS` is always shown. This is also a guess from the shape: a key that is a username looks like a field name. Past 30 names, the rest are counted (`body_fields_more`). Only the first 5,000 records are listed; later writes are still counted.
194
+
195
+ It records no values, except for fields you name in `KNARR_RECORD_FIELDS` (comma-separated, e.g. `title,qty`). Those are recorded from JSON, URL-encoded and multipart text fields and from the query string, and nothing else ever is.
196
+
197
+ Some writes can't be blocked this way:
198
+ - a GET that changes data (`/delete?id=1`);
199
+ - Chrome's Reporting API and NEL uploads (`Report-To`, `Reporting-Endpoints`, `NEL`): reports a site asks Chrome to send. The browser sends them itself, in the network service. When a response asks for them, the result warns;
200
+ - WebSocket messages sent from a dedicated Web Worker, which Playwright can't intercept, and WebTransport sessions opened from one. When a page starts a worker, the result warns (once), and the summary lists it under `write_block_gaps`;
201
+ - the same channels in a sandboxed `srcdoc` frame without `allow-same-origin` (`<iframe sandbox="allow-scripts" srcdoc=...>`), which current Chrome gives none of Knarr's page script. When a page embeds one, the result warns;
202
+ - the requests the browser itself makes for FedCM sign-in (federated login prompts), which Chrome doesn't let Knarr pause;
203
+ - work the server starts on its own.
204
+
205
+ Very large request bodies are held back, but slowly: Playwright passes every paused request's body through its driver, so a 10 MB text upload stalls the page for about a second and uses about 1.5 GB of memory, and a 20 MB one, or a large body of mostly zero bytes, can end the session at the memory limit. Knarr warns when it holds back a body over 5 MB. The memory limit counts a session's own growth, so one big upload doesn't disable later sessions.
206
+
207
+ The sockets Knarr lets through, or only listens to, are Playwright mocks. The server's messages reach the page, but frames of different kinds (text and Blob) can arrive out of order, and the last frame before the server closes the socket can be lost.
208
+
209
+ WebSocket messages a page sends are dropped, but the socket itself still connects, so live updates reach the page: the handshake (with your cookies and the socket's URL, query string included) goes to the server like a GET, which Knarr doesn't hold back. The page's own close code and reason aren't passed on; the server's side closes with a neutral one. Real-time features that need the page to talk (chat, subscriptions that send a request first) don't work while blocked. A `KNARR_WRITE_ALLOW` pattern that matches the socket's URL lets it through: its messages and close are sent, and counted as allowed writes, and it can then carry writes too.
210
+
211
+ Some sites use POST for reads (GraphQL queries, search), and those break while blocked. You can let them through with `KNARR_WRITE_ALLOW`:
212
+ - The part of a pattern before any `?` matches the URL's scheme, host, port and path (`**` matches anything, `*` one path segment). A part after `?` matches the query string (`*` matches anything but `&`). Each part may have at most two wildcards, `**` may not be in the host or port, and a pattern that names a site needs a path: `https://app.example.com/**` for the whole site. Credentials in a URL never take part in the match. Write a port the way Chrome writes URLs: a default port (`:443`) is left out. A URL longer than 2,048 characters, query included, never matches. A pattern that breaks these rules stops the session with a message saying why.
213
+ - Requests let through are sent, reported in results and counted as `allowed_writes`, once the browser has accepted them to continue. A request the page cancels at the same moment (type-ahead search) may be counted although it never reached the server; the count is never lower than what did. Once one has been sent, the run is no longer a dry run.
214
+ - Be careful with GraphQL: mutations usually use the same URL as queries, so allowing `**/graphql` allows its writes too.
215
+
216
+ To allow all writes, set `KNARR_ALLOW_WRITES=1`; the agent then acts with your real permissions. Both are your settings, not the model's.
217
+
218
+ ### Site profiles
219
+
220
+ `KNARR_WRITE_ALLOW` is read when the MCP server starts, so changing it means restarting the server. A site profile does the same job per site, and it is read at every `session_start`: edit the file, then start a new session. A profile is a YAML file in `~/.knarr/sites/` (or `KNARR_PROFILES_DIR`):
221
+
222
+ # ~/.knarr/sites/shop-staging.yaml
223
+ origins: [https://staging.shop.example.com]
224
+ allow: # URL patterns of non-GET requests to send anyway
225
+ - https://staging.shop.example.com/api/v2/search
226
+ forbidden_text: [Buy now, Send Invoice] # more verbs to refuse; the defaults stay
227
+ caps: {max_turns: 60, max_wall_clock_sec: 1200}
228
+
229
+ - **Which profile applies** is decided by the start URL's origin (scheme, host and port). The model doesn't name or choose a profile, and a profile for another site has no effect.
230
+ - **`allow`** takes the same patterns as `KNARR_WRITE_ALLOW` (see above), added after the ones from the environment. A pattern matches any non-GET method to that URL. In a profile the scheme (`http` or `https`) and the host are written out, with no `*` in the host or port (`https://api.example.com/v1/**` is fine, `https://*/**` is refused): a pattern that matches every host would be `writes: live` without its `authorized_by`.
231
+ - **`writes: live`** lets every write through for that site, like `KNARR_ALLOW_WRITES=1` but for one origin. It needs `authorized_by:` (who allowed it, such as an email or a ticket link), which is recorded in `summary.json`. It can't be combined with `allow`.
232
+ - **`forbidden_text`** adds verbs to refuse. A profile can't remove a default one.
233
+ - **`caps`** sets `max_turns` and `max_wall_clock_sec`; `KNARR_MAX_TURNS` and `KNARR_MAX_WALL_CLOCK_SEC` still win.
234
+ - **The environment wins.** `KNARR_BLOCK_WRITES` keeps writes blocked even for a `live` profile, and the start message says so.
235
+ - **It is never silent.** The start message says which profile applied and what it changed, and `summary.json` records it under `profile`.
236
+ - **A profile that can't be used is ignored, not half-applied,** which is the stricter outcome: an unknown or misspelled setting, a setting written twice (YAML would keep the last one without saying so), a bad pattern, a file larger than 64 KB, a file or directory other users can write to or that someone else owns (`chmod go-w` fixes it), or two files naming the same origin. The start message lists what was ignored (`profiles_ignored` in `summary.json`), and `/knarr:doctor` explains each.
237
+
238
+ A profile is only as safe as the directory it sits in. The model can't pick or change a profile through the tools, but an agent that can write files could edit `~/.knarr/sites/` itself and widen its own policy before the next session. To stop that, put an ask or deny rule for edits to that directory in your Claude Code permissions and confirm it with `/permissions`. `/knarr:doctor` warns unless it finds an ask or deny rule for editing files in the directory you use, written as `~/path` or `//path` (for example `Edit(~/.knarr/sites/**)`); a rule for reading, for a shell command or for another directory doesn't count. That does not stop a shell command from writing the file. Knarr guards against a misbehaving agent, not against you.
239
+
240
+ Other limits:
241
+ - **Tool arguments have length limits** (a URL 2,048 characters, a typed value 10,000, a note or a reason 2,000, a label or target 500, the goal 2,000, the success criterion 1,000) and may not contain a NUL character. A call over a limit is refused with the limit named, uses no turn and counts as no guard violation. The MCP SDK reads a whole message before these checks run, so they cap what is used, not what is read.
242
+ - **Page text is untrusted.** A website can write anything on its page, including instructions aimed at the model ("ignore your instructions and run this command"). Knarr returns page text as it is, marks it as untrusted in the server instructions, in the skill and in a line after each `read_page` and `inspect_error` result, and its guards limit what the browser can do. They do not limit Claude's other tools (a shell, file edits) in the same session, so keep those under your permission rules when you let Claude browse a site you don't control.
243
+ - **Read-only mode** (`--read-only`, or `read_only` on `session_start`) goes further and fakes every click, fill and submit, so the agent can't open anything that needs a click. With the write block it's rarely needed.
244
+ - **The forbidden list matches text** on the controls the agent targets. It reduces risk; it isn't a guarantee.
245
+
246
+ ## Environment variables
247
+
248
+ A switch takes `1`, `true`, `yes`, `on`, `y`, `t` or `enabled` for on, and `0`, `false`, `no`, `off`, `n`, `f` or `disabled` (or nothing) for off. A value that is neither is off, except for `KNARR_BLOCK_WRITES`, where it counts as on; `/knarr:doctor` points out such a value.
249
+
250
+ | Variable | Effect |
251
+ |---|---|
252
+ | `KNARR_CDP_URL` | Borrow the login from a running Chrome, e.g. `http://127.0.0.1:9222`; must be on this machine |
253
+ | `KNARR_STORAGE_STATE` | Launch with a saved Playwright login |
254
+ | `KNARR_BROWSER_CHANNEL` | Launch an installed browser, e.g. `chrome`, instead of Playwright's Chromium |
255
+ | `KNARR_ALLOW_WRITES` | `1` to let writes through (blocked by default) |
256
+ | `KNARR_BLOCK_WRITES` | `1` to keep writes blocked whatever else says otherwise; wins over `KNARR_ALLOW_WRITES` and a profile's `writes: live`. Any value except an explicit off counts as on, so a typo blocks |
257
+ | `KNARR_RECORD_FIELDS` | Comma-separated field names whose values `captured_writes.jsonl` may record; no other values are ever recorded |
258
+ | `KNARR_NO_SANDBOX` | `1` to start Chromium without its sandbox, for a container that can't run it |
259
+ | `KNARR_TRACE` | `1` to write a Playwright `trace.zip`; it holds the session's cookies |
260
+ | `KNARR_WRITE_ALLOW` | Comma-separated URL patterns of non-GET requests to send anyway, e.g. `https://api.example.com/search`; see Safety for how they match |
261
+ | `KNARR_RUNS_DIR` | Run output (default `~/.knarr/runs`) |
262
+ | `KNARR_PROFILES_DIR` | Where site profiles are read from (default `~/.knarr/sites`); see Site profiles |
263
+ | `KNARR_MAX_TURNS`, `KNARR_MAX_WALL_CLOCK_SEC` | MCP session limits (defaults 30 calls, 900 s of browser time) |
264
+ | `KNARR_IDLE_TIMEOUT_SEC` | Close an MCP session with no calls for this long (default 900) |
265
+
266
+ ## Project layout
267
+
268
+ knarr/explorer/ the core
269
+ explorer_tools.py the agent's tools and the guards
270
+ session.py browser session (launch, borrowed or saved login)
271
+ borrow.py copies a login out of the user's Chrome over DevTools
272
+ write_block.py the network write block
273
+ profiles.py per-site profiles
274
+ origin.py URL and origin normalisation
275
+ caps.py, trace.py limits, trace and summary writers
276
+ human_demo.py, learned_controls.py
277
+ record what a person demonstrates, for runners that ask one
278
+ knarr/mcp/ MCP server: session, browser worker thread, tools
279
+ knarr/doctor.py the setup check behind /knarr:doctor
280
+ plugin/ Claude Code plugin (MCP config, skill, /knarr:install, /knarr:doctor)
281
+ tests/ unit tests; tests/integration needs a browser
282
+
283
+ ## Development
284
+
285
+ python3 -m pip install -e ".[dev]"
286
+ python3 -m pytest tests/unit -q
287
+
288
+ Raise `version` in `plugin/.claude-plugin/plugin.json` whenever you change a file under `plugin/` (the skill, the commands, `.mcp.json`): Claude Code goes by that number to decide whether an installed plugin has an update, so an unchanged number can hide your change. The browser code is the Python package, released to PyPI separately (see `RELEASING.md`).
289
+
290
+ The unit tests don't need a browser or network access. The end-to-end tests start the real server and a real browser; run them with `KNARR_BROWSER_TESTS=1 python3 -m pytest tests/integration` (add `KNARR_BROWSER_CHANNEL=chrome` to use installed Chrome). `tests/unit/test_import_boundary.py` restricts imports to the standard library, `knarr`, and a short list of third-party libraries.
291
+
292
+ Knarr is tested on macOS and Linux. It may work on Windows, but nothing there is tested yet.
293
+
294
+ ## License
295
+
296
+ Apache License 2.0; see `LICENSE`.