AXAG — Agent Annotations for Web UIs

Make your web UI agent-ready. Add semantic annotations to HTML/JSX/TSX elements, then generate MCP tools that any AI agent can consume — no backend changes required.

The Problem

AI agents (Claude, GPT, Gemini) can browse web UIs but have no idea what buttons actually do. They see DOM nodes, not intent. Every agent interaction is a fragile guess.

The Solution

AXAG (Agent Experience Annotation Grammar) lets you declare what each UI element does — its intent, entity, action type, risk level, and safety constraints — directly in your markup:

<!-- Before: opaque DOM node -->
<button onclick="deleteAccount()">Delete</button>

<!-- After: machine-readable semantic contract -->
<button
  onclick="deleteAccount()"
  axag-intent="account.delete"
  axag-entity="account"
  axag-action-type="delete"
  axag-description="Permanently delete the user account and all associated data"
  axag-risk-level="critical"
  axag-confirmation-required="true"
  axag-scope="user"
  axag-side-effects='["data_loss", "session_termination"]'
>
  Delete
</button>

Now any AI agent knows this button permanently deletes data, requires confirmation, and has irreversible side effects — before it clicks.

The Pipeline

 Your Code            Semantic Manifest       MCP Tools
 (axag-* attrs)   →   (JSON contract)     →   (Agent-ready)

 <button                {                       {
   axag-intent=           "intent":               "name":
   "account.delete"       "account.delete",       "account_delete",
   axag-risk-level=       "risk_level":           "inputSchema": {
   "critical"             "critical"                "type": "object",
   ...                  }                           ...
 >                                              }

1. Annotate — Add axag-* attributes to your elements (this extension helps)
2. Scan — axag-cli scan ./src --manifest → axag-manifest.json
3. Generate — axag-cli generate-tools → tool-registry.json
4. Serve — Any MCP-compatible agent consumes the tools automatically

✨ Features

🔤 Intelligent Autocomplete

Type axag- inside any HTML, JSX, or TSX element and get suggestions for all 15 AXAG attributes with descriptions, types, and enum values.

📖 Hover Documentation

Hover over any axag-* attribute to see rich inline docs — description, expected type, allowed values, and whether it's required.

⚠️ Real-Time Diagnostics

Instant validation as you type:

• Missing required attributes — flags axag-intent without the mandatory trio: axag-entity, axag-action-type, axag-description
• Invalid enum values — catches typos in axag-action-type, axag-risk-level, axag-scope
• Malformed JSON — validates axag-required-params, axag-optional-params, axag-side-effects, axag-preconditions

✂️ Snippets

Scaffold complete annotated elements instantly:

📊 Status Bar Counter

See the number of AXAG annotations in the current file at a glance — right in the VS Code status bar.

🎓 Guided Walkthrough

First time? Use Help → Get Started to walk through annotating, using snippets, and generating MCP tools.

🚀 Quick Start

1. Install from the VS Code Marketplace
2. Open any .html, .jsx, or .tsx file
3. Type axag- inside an element — autocomplete kicks in
4. Snippet — type axag-full + Tab for a fully annotated element
5. Generate — run npx axag-cli scan ./src --manifest && npx axag-cli generate-tools

🗂 Supported Languages

🆚 How AXAG Compares

AXAG is the only standard that combines human-readable semantics with machine-readable contracts and auto-generates MCP-compatible tool definitions.

📋 Attribute Reference

Required (Core 4)

Safety & Risk

Parameters & Constraints

Metadata

🧰 The AXAG Ecosystem

🤝 Contributing

Contributions are welcome! Please see the AXAG Contributing Guide.

📄 License

MIT © AXAG