Sutram

One set of commands for your web app: people type them, AI agents call them. Try it live →

Sutram turns what your web app can do into commands. WebMCP is how a page hands tools to an agent; Sutram decides what those tools are. Every part of the app (a form, the navigation, a module) registers its commands in one registry, the same way. Register a command once, and it is there for everyone:

• Agents get it as a WebMCP tool, or call it from JavaScript with Sutram.call().
• People type it into a terminal-like console. Agents can type there too, so you watch every command they run.

› help
cart add <sku> [qty]  Add a product to the cart
cart status           Show what is in the cart  [read-only]
checkout              Place the order  [consequential]

› cart add V60-02 --qty=2
Added 2 × V60 dripper, size 02. The cart has 2 items, €48.00.

› checkout
Place an order for 2 items, €48.00? [Yes] [No]

Why use it

• No clicking around. An agent runs one short command instead of reading screenshots and hunting for buttons.
• The user's own session. Commands run in the browser, as the logged-in user. No new API, no new login, no new way into your server.
• Asks before it matters. Commands that are hard to undo ask the person first. (An agent typing into the console could answer for them: see the console.)
• Feels like a terminal. help, man, Tab completion, history and "did you mean". You write no help pages.
• Small. No dependencies, about 37 kB minified and gzipped, TypeScript types included.

Quick start

Save this as an HTML file, open it in a browser and press ` (the key left of 1):

<!doctype html>
<meta charset="utf-8">
<title>Hello, Sutram</title>
<p>Press <kbd>`</kbd> and type <code>help</code>.</p>

<script type="module">
  import Sutram from "https://cdn.jsdelivr.net/npm/@d34dman/[email protected]/dist/sutram.js";

  Sutram.register({
    name: "hello world",
    provider: "hello",
    description: "Say hello",
    input: {
      type: "object",
      properties: { who: { type: "string", default: "you", description: "Who to greet" } },
    },
    positional: ["who"],
    annotations: { readOnly: true },
    run: ({ who }) => ({ text: `Hello, ${who}.` }),
  });

  Sutram.mountConsole();
</script>

Then try:

› help
› hello world
› hello world Ada
› hello world --who="Grace Hopper"
› hello world -h
› man hello world

Install

npm install @d34dman/sutram

Other ways in:

• One file, no build: load dist/sutram.js as a module from a CDN, as in the quick start. It sets up the console and WebMCP for you.
• Drupal: install the drupal/sutram module.

See Install for the details.

Why commands

Without Sutram, an agent reads the page (screenshots, snapshots, HTML), works out what to click, then reads the page again to see whether it worked. With Sutram, it reads a short list of commands and runs them:

form fields node-article-form
form set node-article-form title "Pour-over, step by step"
form submit node-article-form

When something is wrong, the error names the field and the fix, so the agent corrects one value instead of starting over.

On the Drupal demo, Claude Code built a Canvas page with half the task tokens and 7 fewer calls (21 instead of 28) than the same agent without Sutram, and edited an article in 11 calls instead of 14. One run each, so a direction, not a benchmark. See Why commands and the measurements.

Why not just WebMCP?

WebMCP lets a page hand tools to an agent. It does not say which tools, how they are named, or how many parts of an app share one page. Sutram is that layer, and WebMCP is one of the ways out of it.

• Many providers, one page. On a Drupal page a dozen modules may each want to expose something. With plain WebMCP each registers its own tools, with its own names. With Sutram they share one registry and one command grammar.
• People see what agents see. WebMCP tools are invisible to people. Every Sutram command is also a line in the console, so you can type exactly what the agent would call, watch what it runs, and paste it into a bug report.
• Few tools, stable list. One command takes the thing on the page as an argument: form set <form> … is the tool form_set for every form, not one tool per form. Commands look up their target when they run and answer "not on this page" when it is gone, so the tool list stays put.
• What WebMCP leaves out. Discovery (help, man, status), errors that name the fix, changes to wait for (events wait) or poll (events recent), and app-defined formats. What WebMCP has no field for, like what a command returns or that it leaves the page, goes into the tool description.
• Works before WebMCP does. Browser agents, tests and Claude Code use the commands today through Sutram.call() or the console. Browsers with WebMCP get native tools, and your code does not change when support arrives.

Sutram registers its tools through WebMCP's own registerTool(), and it never reads or changes the page's HTML: your app's JavaScript says what the commands are. It does not replace Playwright or browser agents either. They drive the browser; Sutram gives them commands to call instead of buttons to click.

This is the beginning of the README. Read the rest at the original. Read the full README ↗