workerd / url
AGENTS.md9.2k starsChanged 8 months agoApache-2.0View on GitHub
URL and URLSearchParams in TypeScript, installed by main.ts under the TS_URL autogate in place of both C++ implementations (api/url-standard.h and api/url.h), which global-scope.h then leaves out. Parent directory conventions apply; see src/per_isolate/AGENTS.md. The graph is acyclic: url requires backend, one backend, runtime-class and serialization; the backends require only backend, urlencoded and internal-array. src/tests/url/AGENTS.md describes the behavior and keeps the ledger of every departure from the C++, toward WHATWG URL and WebIDL. Its suite runs against both implementations; change the code…
Trending
More talk lately.about the whole repository
Who's talking about cloudflare/workerd
- A Hacker News story“OS Workerd, Cloudflare's JavaScript/WASM Runtime”Hacker News · Sep 27, 2022 · 27 points
- withastro/astro“Cloudflare adapter returning [object Object]”GitHub · Oct 10, 2025 · 18 reactions
- supabase/supabase-js“The 'cache' field on 'RequestInitializerDict' is not implemented - Cloudflare Workers”GitHub · Mar 28, 2024 · 16 reactions
- NixOS/nixpkgs“Package request: workerd”GitHub · Nov 12, 2024 · 13 reactions
- nodejs/node“src: improve buffer.transcode performance”GitHub · Aug 1, 2024 · 13 reactions
The biggest 5 of 39 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 39
Talked about on GitHub, Bluesky, Hacker News and Stack Overflow (39 times).
On GitHub · 32
- Oct 10, 2025Cloudflare adapter returning [object Object] — withastro/astro18 reactions · 15 comments
- Mar 28, 2024The 'cache' field on 'RequestInitializerDict' is not implemented - Cloudflare Workers — supabase/supabase-js16 reactions · 24 comments
- Nov 12, 2024Package request: workerd — NixOS/nixpkgs13 reactions · 10 comments
- Aug 1, 2024src: improve buffer.transcode performance — nodejs/node13 reactions · 26 comments
- Feb 19, 2024Add Curve25519 — w3c/webcrypto9 reactions · 16 comments
27 more on GitHub
- Nov 3, 2025Optimize TextEncoder::encode — nodejs/performance7 reactions · 33 comments
- Oct 23, 2023🐛 BUG: pages dev output is unnecessarily verbose — cloudflare/workers-sdk7 reactions · 7 comments
- Nov 24, 2025util: improve textencoder encodeInto performance — nodejs/node6 reactions · 8 comments
- Aug 8, 2024Fix fetch adapter in cloudflare workers — axios/axios6 reactions · 1 comment
- May 25, 2024Partially fix #3160 by properly handling resultsFormat query — cloudflare/workers-sdk6 reactions · 12 comments
- Jan 23, 2026src: improve textEncoder encode performance with simdutf — nodejs/node5 reactions · 8 comments
- Jan 19, 2024Implement Vitest testing environment for Miniflare 3 — cloudflare/workers-sdksays it tested it5 reactions · 7 comments
- Nov 28, 2024src,lib: remove the cost of encoding parameter serialization — nodejs/node4 reactions · 3 comments
- Aug 8, 2026deps: bump the npm group in /kanarek-companion with 2 updates — trvny/trvny3 reactions · 4 comments
- Aug 8, 2026deps: bump the npm group in /weather-feed with 3 updates — trvny/trvny3 reactions · 4 comments
- Aug 8, 2026deps: bump the npm group in /mcp/status-mcp with 2 updates — trvny/trvny3 reactions · 4 comments
- Jan 24, 2026build(deps-dev): bump @cloudflare/workers-types from 4.20260123.0 to 4.20260124.0 — magicappdev/magicappdev3 reactions · 5 comments
- Nov 15, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20261112.1 — paglaai/PaglaROUTER2 reactions · 2 comments
- Nov 8, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20261104.1 — paglaai/PaglaROUTER2 reactions · 3 comments
- Nov 1, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20261029.1 — paglaai/PaglaROUTER2 reactions · 3 comments
- Oct 25, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20261022.1 — paglaai/PaglaROUTER2 reactions · 3 comments
- Oct 18, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20261015.1 — paglaai/PaglaROUTER2 reactions · 3 comments
- Oct 11, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20261008.1 — paglaai/PaglaROUTER2 reactions · 4 comments
- Oct 4, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20261001.1 — paglaai/PaglaROUTER2 reactions · 4 comments
- Sep 27, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20260924.1 — paglaai/PaglaROUTER2 reactions · 4 comments
- Sep 20, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20260917.1 — paglaai/PaglaROUTER2 reactions · 3 comments
- Sep 16, 2026[wrangler] Add Analytics SQL binding support — cloudflare/workers-sdk2 reactions · 4 comments
- Sep 13, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20260910.1 — paglaai/PaglaROUTER2 reactions · 4 comments
- Apr 21, 2026build(deps-dev): Bump @cloudflare/workers-types from 4.20260411.1 to 4.20260421.1 in /workers/auth-api — Trancendos/infinity-adminOS2 reactions · 4 comments
- Apr 14, 2026build(deps-dev): Bump @cloudflare/workers-types from 4.20260411.1 to 4.20260414.1 in /workers/ai-api — Trancendos/infinity-adminOS2 reactions · 4 comments
- Apr 14, 2026build(deps-dev): Bump @cloudflare/workers-types from 4.20260411.1 to 4.20260414.1 in /workers/files-api — Trancendos/infinity-adminOS2 reactions · 4 comments
- Jan 24, 2026build(deps-dev): bump @cloudflare/workers-types from 4.20260123.0 to 4.20260124.0 — magicappdev/templates2 reactions · 2 comments
On Bluesky · 4
- Mar 24, 2026workerd : le runtime JavaScript/Wasm open source de Cloudflare Workers — @news.humancoders.com4 likes and reposts
- Aug 22, 2026Current status: trying to build github.com/cloudflare/w... on various sandbox providers — @jeremymorrell.dev1 likes and repost
- Mar 24, 2026workerd : le runtime JavaScript/Wasm qui propulse Cloudflare Workers est maintenant open source. Basé sur les standards web, il permet… — @humancoders.com1 likes and repost
- Nov 5, 2024Technically workers are open source github.com/cloudflare/w... — @userops.bsky.social1 likes and repost
On Hacker News · 2
- Sep 27, 2022OS Workerd, Cloudflare's JavaScript/WASM Runtime27 points · 2 comments
- Oct 5, 2023Cloudflare workers is adopting Ada URL parser2 points
On Stack Overflow · 1
- Oct 1, 2024How to user KV in cloudflare workers?1 vote
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository84 other files it gives its agents.
- AGENTS.mdAGENTS.md
- build/AGENTS.mdAGENTS.md
- src/bench/streams/AGENTS.mdAGENTS.md
- src/bench/streams/body/AGENTS.mdAGENTS.md
- src/bench/streams/compression/AGENTS.mdAGENTS.md
- src/bench/streams/digest/AGENTS.mdAGENTS.md
- src/bench/streams/encoding/AGENTS.mdAGENTS.md
- src/bench/streams/identity/AGENTS.mdAGENTS.md
- src/bench/streams/piping/AGENTS.mdAGENTS.md
- src/bench/streams/readable/AGENTS.mdAGENTS.md
- src/bench/streams/readable-byte/AGENTS.mdAGENTS.md
- src/bench/streams/strategies/AGENTS.mdAGENTS.md
- src/bench/streams/transform/AGENTS.mdAGENTS.md
- src/bench/streams/writable/AGENTS.mdAGENTS.md
- src/cloudflare/AGENTS.mdAGENTS.md
- src/node/AGENTS.mdAGENTS.md
- src/per_isolate/AGENTS.mdAGENTS.md
- src/per_isolate/crypto/AGENTS.mdAGENTS.md
- src/per_isolate/events/AGENTS.mdAGENTS.md
- src/per_isolate/urlpattern/AGENTS.mdAGENTS.md
- src/per_isolate/webfs/AGENTS.mdAGENTS.md
- src/per_isolate/webstreams/AGENTS.mdAGENTS.md
- src/pyodide/AGENTS.mdAGENTS.md
- src/rust/AGENTS.mdAGENTS.md
- src/rust/cxx/AGENTS.mdAGENTS.md
- src/tests/dom-exception/AGENTS.mdAGENTS.md
- src/tests/events/AGENTS.mdAGENTS.md
- src/tests/events/eventsource/AGENTS.mdAGENTS.md
- src/tests/events/messagechannel/AGENTS.mdAGENTS.md
- src/tests/node/AGENTS.mdAGENTS.md
- src/tests/node/http-client/AGENTS.mdAGENTS.md
- src/tests/node/http-server/AGENTS.mdAGENTS.md
- src/tests/node/net/AGENTS.mdAGENTS.md
- src/tests/node/stream/AGENTS.mdAGENTS.md
- src/tests/streams/AGENTS.mdAGENTS.md
- src/tests/streams/cache/AGENTS.mdAGENTS.md
- src/tests/streams/compression/AGENTS.mdAGENTS.md
- src/tests/streams/digest/AGENTS.mdAGENTS.md
- src/tests/streams/encoding/AGENTS.mdAGENTS.md
- src/tests/streams/formdata/AGENTS.mdAGENTS.md
- src/tests/streams/htmlrewriter/AGENTS.mdAGENTS.md
- src/tests/streams/identity/AGENTS.mdAGENTS.md
- src/tests/streams/inspect/AGENTS.mdAGENTS.md
- src/tests/streams/iocontext/AGENTS.mdAGENTS.md
- src/tests/streams/piping/AGENTS.mdAGENTS.md
- src/tests/streams/r2-patterns/AGENTS.mdAGENTS.md
- src/tests/streams/readable/AGENTS.mdAGENTS.md
- src/tests/streams/readable-byte/AGENTS.mdAGENTS.md
- src/tests/streams/scaling/AGENTS.mdAGENTS.md
- src/tests/streams/sockets/AGENTS.mdAGENTS.md
- src/tests/streams/strategies/AGENTS.mdAGENTS.md
- src/tests/streams/transform/AGENTS.mdAGENTS.md
- src/tests/streams/writable/AGENTS.mdAGENTS.md
- src/tests/url/AGENTS.mdAGENTS.md
- src/tests/urlpattern/AGENTS.mdAGENTS.md
- src/workerd/api/AGENTS.mdAGENTS.md
- src/workerd/api/crypto/AGENTS.mdAGENTS.md
- src/workerd/api/node/AGENTS.mdAGENTS.md
- src/workerd/api/streams/AGENTS.mdAGENTS.md
- src/workerd/io/AGENTS.mdAGENTS.md
- The first 60 shown.
The file
We split this AGENTS.md into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 45
A URL's store is its query: Every ListStore mutation reserializes the URL's query, even one that changes nothing.
- Very specific: line 51
Every instance, iterators included, is markUncloneable().
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
src/per_isolate/url/
URL and URLSearchParams in TypeScript, installed by main.ts under the
TS_URL autogate in place of both C++ implementations (api/url-standard.h
and api/url.h), which global-scope.h then leaves out. Parent directory
conventions apply; see src/per_isolate/AGENTS.md.
MODULES
| Module | Role |
backend.ts | The facade-backend contract (UrlBackend, SearchParamsStore); exports the attribute numbers |
url.ts | The facade: both classes, the iterator, every WebIDL conversion, the shape; picks the backend |
ada-backend.ts | url_standard: href plus ada's offsets, sliced by the getters; ListStore |
kj-backend.ts | url_original: adapts the native LegacyUrlHandle (api/url.h) |
urlencoded.ts | application/x-www-form-urlencoded parsing and serializing, for ListStore |
internal-array.ts | Null-prototype arrays for internal lists |
cpp_exports.ts | The functions the C++ bridge calls |
The graph is acyclic: url requires backend, one backend, runtime-class
and serialization; the backends require only backend, urlencoded and
internal-array.
SEMANTICS
src/tests/url/AGENTS.md describes the behavior and keeps the ledger of
every departure from the C++, toward WHATWG URL and WebIDL. Its suite runs
against both implementations; change the code and the ledger together.
- The backend is chosen once per context from
url_standard. It decides the parser and every attribute's value; the facade decides everything else, the same way for both. - The facade converts every argument before reaching the backend, so a backend sees only USVStrings.
URL.parse()and thesearchParamsgetter hand their constructors an already-made state as the second argument, after the module-privatekAdopttoken. Not through module state: a constructor that throws on entry (a stack overflow) would leave it for the next construction.
INVARIANTS
- Origin cache (
ada-backend.ts): only thehref,protocol,host,hostnameandportsetters clear it.src/tests/url/origin-cache.jschecks it after every setter; a new setter path must keep that rule. - A URL's store is its query. Every
ListStoremutation reserializes the URL's query, even one that changes nothing; thehrefandsearchsetters reload the list. The kj backend's handle is both URL and store. - Internal lists are made with
internalArray(): a push onto an ordinary array runs any index setter user code put onArray.prototype. Return them to user code throughtoUserArray(). - Every instance, iterators included, is
markUncloneable().
THE C++ CONTRACT
api/url-bridge.h defines JsUrl and JsUrlSearchParams, which take the
TypeScript instances where C++ took the C++ classes: node:fs paths
(FileSystemModule::FilePath) and body initializers (Body::Initializer).
- They recognize an instance by the V8-private brand its constructor sets
(
workerd:URL,workerd:URLSearchParams), without running JavaScript. - They read it through
cpp_exports.ts(urlHref,searchParamsSerialize), which uses the implementation's own state, so user code replacingtoString()does not change what C++ sees. - The brand names and the export names are shared with
url-bridge.c++.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

