diff --git a/README.md b/README.md
index b2b677a..330caf6 100644
--- a/README.md
+++ b/README.md
@@ -88,6 +88,26 @@ Shorter compile-checked examples: [`example_test.go`](example_test.go) and
 - [MCP tools](docs/docs/reference/mcp-tools.md)
 - [Security model](docs/docs/explanation/security-model.md)
 
+## How this differs from Cloudflare's Code Mode
+
+Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) and CodeMode
+share a thesis: models are better at writing code than at emitting tool
+calls. They apply it on opposite sides of the protocol.
+
+Cloudflare's Code Mode is agent-side. Their Agents SDK converts the tool
+schemas of the MCP servers an agent already uses into a TypeScript API; the
+model writes TypeScript that runs in a V8 isolate on the Workers platform,
+and each call proxies back to the original servers.
+
+CodeMode is server-side. You author the server itself: capabilities are
+native typed Go functions, not wrapped remote tools, and the server runs the
+agent's program in a local worker process. Because code execution is part of
+the server's own contract, any MCP client gets one-round-trip composition
+without a special agent framework or hosting platform. The server also
+enforces its own policy: every capability call is authorized before it
+dispatches, and a deployment can disable capabilities it does not want to
+expose.
+
 ## Security boundary
 
 Each `execute` request runs Starlark in a fresh worker process that CodeMode