<p>I wanted research-backed guidance for my Claude Code agents. I had
Claude read everything Anthropic has published on agent design, then
ran deep research reports from ChatGPT, Gemini, and Claude on the
same topic. Notes are in the wiki
(<a href="/wiki/research/anthropic-guidance.html">Anthropic guidance</a>,
<a href="/wiki/research/coding-agent-best-practices.html">deep research synthesis</a>).
Here's what I applied.</p>
<p>Some key findings:</p>
<ul>
<li><strong>Most multi-agent failures are specification problems</strong>, not
infrastructure. Bad task descriptions, ambiguous instructions,
missing termination conditions. Berkeley's
<a href="https://arxiv.org/abs/2503.13657">MAST taxonomy</a> analyzed
150+ tasks across 5 frameworks and found specification and
system design issues were the dominant failure category.</li>
<li><strong>Teach delegation.</strong> Give subagents an objective, output
format, tool/source guidance, and task boundaries. Without
all four, agents duplicate work or leave gaps.
(<a href="https://www.anthropic.com/engineering/multi-agent-research-system">Multi-Agent Research System</a>)</li>
<li><strong>Evaluators need isolated context.</strong> If the evaluator shares
context with the producer, it becomes "another participant
in collective delusion."
(<a href="https://www.anthropic.com/research/building-effective-agents">Building Effective Agents</a>)</li>
<li><strong>Start wide, then narrow.</strong> Agents default to overly specific
queries in unfamiliar territory. Begin with broad queries to
map what exists before drilling in.
(Gemini deep research,
<a href="/wiki/research/coding-agent-best-practices.html">wiki</a>)</li>
<li><strong>Action-oriented descriptions improve auto-delegation.</strong>
Trigger phrases like "MUST BE USED when..." in agent
descriptions help Claude decide when to invoke subagents.
(Claude deep research,
<a href="/wiki/research/coding-agent-best-practices.html">wiki</a>)</li>
<li><strong>Agents without browser tools ship half-working features.</strong>
Unit tests pass but the rendered page is broken. Playwright
catches what tests miss.
(<a href="https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents">Effective Harnesses</a>)</li>
<li><strong>Route models by risk, not task complexity.</strong> Opus for
judgment calls that are hard to verify. Sonnet for mechanical
work that's easy to check. A complex summarization is
low-risk because you can read and discard it. A one-line
security review is high-risk because getting it wrong has
consequences.
(<a href="https://www.anthropic.com/research/building-effective-agents">Building Effective Agents</a>,
all three deep research reports)</li>
<li><strong>Deny-by-default permissions.</strong> Start with no tool access
and progressively allowlist. The opposite of what most people
do (give the agent everything, restrict when something goes
wrong).
(<a href="https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents">Context Engineering</a>,
Claude deep research,
<a href="/wiki/research/coding-agent-best-practices.html">wiki</a>)</li>
<li><strong>The harness enforces termination, not the agent.</strong> Don't
rely on the agent to know when to stop. Set max iterations,
token budgets, and repetition detection in the system that
runs the agent.
(<a href="https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents">Effective Harnesses</a>,
Claude deep research,
<a href="/wiki/research/coding-agent-best-practices.html">wiki</a>)</li>
<li><strong>Write results to files, pass back references.</strong> Subagents
writing full output through the orchestrator bloats its
context window. Subagents should write to files and return
a summary and a path.
(<a href="https://www.anthropic.com/engineering/multi-agent-research-system">Multi-Agent Research System</a>)</li>
<li><strong>Research, plan, then implement.</strong> Without explicit
instructions, Claude jumps straight to coding. Say "read X,
then make a plan, then implement." Three phases, stated
explicitly. Claude won't reliably do them on its own.
(<a href="https://code.claude.com/docs/en/best-practices">Claude Code Best Practices</a>)</li>
<li><strong>One feature per prompt, commit after each piece.</strong> Agents
try to do everything and exhaust context mid-task. Commits
are rollback points. If the agent breaks something on step
3, you revert to step 2 instead of starting over.
(<a href="https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents">Effective Harnesses</a>)</li>
<li><strong>Agents use ~4x more tokens than chat. Multi-agent uses
~15x.</strong> Don't pay that unless the task needs it. Multi-agent
is an economic decision, not an architectural one.
(<a href="https://www.anthropic.com/engineering/multi-agent-research-system">Multi-Agent Research System</a>)</li>
<li><strong>Start simple, add layers only when measured outcomes
improve.</strong> The canonical agent loop is ~50 lines. Don't
build the full stack on day one.
(<a href="https://www.anthropic.com/research/building-effective-agents">Building Effective Agents</a>)</li>
</ul>
<p>Security baseline: the
<a href="https://genai.owasp.org/llm-top-10/">OWASP Top 10 for LLM Applications</a>.
All three deep research reports recommended it. I use it as a
checklist for the Security Auditor agent.</p>
<h1 id="2026-03-15s-agent-roster">2026-03-15's Agent Roster</h1>
<p>The agents from the
<a href="/agent-org-chart.html">org-chart post</a> were made off-the-cuff.
16 agents, too ambitious, didn't have the infrastructure to support
them. I deleted most and got down to 7. This time: I had Claude
load the deep research synthesis, I extracted the best practices
that applied, and I updated the agent definitions with specific,
traceable changes.</p>
<table>
<thead>
<tr>
<th>Agent</th>
<th>Model</th>
<th>Role &#x26; Applied Research</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/publisher.md">Publisher</a></td>
<td>Opus</td>
<td>Content pipeline orchestration, writing. <a href="https://www.anthropic.com/engineering/multi-agent-research-system">Delegation specs</a>, trigger phrase.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/analyst.md">Analyst</a></td>
<td>Opus</td>
<td>Research ingestion, system improvements. Trigger phrase.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/synthesizer.md">Synthesizer</a></td>
<td>Opus</td>
<td>Compare/contrast Deep Research reports. No changes needed.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/researcher.md">Researcher</a></td>
<td>Sonnet</td>
<td>Sourced facts, research briefs. <a href="/wiki/research/coding-agent-best-practices.html">Start wide, then narrow</a> search strategy, trigger phrase.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/reviewer.md">Reviewer</a></td>
<td>Opus</td>
<td>Style, substance, sourcing. <a href="https://www.anthropic.com/research/building-effective-agents">Context isolation</a> from producer.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/qa.md">QA</a></td>
<td>Sonnet</td>
<td>Build, render, links via <a href="https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents">Playwright</a>. Trigger phrase.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/security-auditor.md">Security Auditor</a></td>
<td>Opus</td>
<td><a href="https://genai.owasp.org/llm-top-10/">OWASP LLM Top 10</a>, confidential data. Added LLM05 check.</td>
</tr>
</tbody>
</table>
<pre class="mermaid">
graph TD
    Claude["Vanilla Claude"]
    Publisher["Publisher (Opus)"]
    Analyst["Analyst (Opus)"]
    Synthesizer["Synthesizer (Opus)"]
    Researcher["Researcher (Sonnet)"]
    Reviewer["Reviewer (Opus)"]
    QA["QA (Sonnet)"]
    Security["Security Auditor (Opus)"]

    Claude --> Publisher
    Claude --> Analyst
    Claude --> Synthesizer
    Claude --> Researcher
    Claude --> Reviewer
    Claude --> QA
    Claude --> Security
    Publisher --> Researcher
    Publisher --> Reviewer
    Publisher --> QA
    Publisher --> Security
</pre>
<p>Three report directly to me (Publisher, Analyst, Synthesizer).
Four are subagents under Publisher. Model routing follows the
research: Opus for judgment calls (review, security, editorial,
synthesis), Sonnet for mechanical work (research, QA).</p>
<h2 id="calling-the-agents">Calling the agents</h2>
<p>Three ways to use them:</p>
<p><strong>Vanilla Claude auto-delegates.</strong> Each agent definition has a
<code>description</code> field that Claude reads when deciding whether to
spawn a subagent. The trigger phrases ("MUST BE USED when
writing blog posts", "MUST BE USED when gathering facts") tell
Claude when to invoke each one. If I ask vanilla Claude to
write a blog post, it sees the Publisher's description and
delegates. It can also run multiple subagents in parallel
when the tasks are independent.</p>
<p><strong>CLAUDE.md tells Claude what's available.</strong> The project's
<code>CLAUDE.md</code> includes a section listing all 7 agents with their
roles and invocation commands. This gives vanilla Claude the
full picture of what agents exist without having to discover
them from the file system.</p>
<p><strong><code>claude --agent publisher</code> for the full pipeline.</strong> This
starts Claude with the Publisher's system prompt as the main
thread. Publisher then orchestrates the entire content
pipeline: research, substance gate, write, review, QA,
security audit. It spawns each subagent natively using Claude
Code's Agent tool, not CLI calls. Independent stages (QA and
security audit) run in parallel. This is the heavy path for
writing a full post from scratch.</p>
<p>Claude Code enforces a single-level subagent hierarchy.
Publisher can spawn subagents, but those subagents can't
spawn their own. If Reviewer needs research, it doesn't call
Researcher. It reports back to Publisher, which decides
what to do next.</p>


<p>This is a companion to the <a href="/ga4-mcp.html">GA4 MCP post</a>. Same idea,
different service. Cloudflare ships a remote MCP server that covers
their entire API. You connect it to Claude Code, authenticate via
OAuth in your browser, and then Claude can query your Cloudflare
account directly.</p>
<p>I <a href="/dns-xfer-godaddy-cloudflare.html">moved my DNS to Cloudflare</a> a
while back and use the CDN proxy on
<a href="https://kyle.pericak.com">kyle.pericak.com</a>. The MCP server lets me
check DNS records, zone settings, and account details without opening
the dashboard. Read-only access is fine for this.</p>
<h1 id="how-it-works">How it works</h1>
<p>Cloudflare's MCP server is different from most. It has
<a href="https://developers.cloudflare.com/api/">thousands of API endpoints</a>,
but instead of exposing one tool per endpoint, it exposes two:
<code>search</code> and <code>execute</code>.</p>
<p><code>search</code> queries the OpenAPI spec to find the right endpoint.
<code>execute</code> runs JavaScript code server-side against the Cloudflare
API using a
<a href="https://github.com/cloudflare/mcp"><code>cloudflare.request()</code></a>
function. Claude writes the code, the server runs it, and the
result comes back.</p>
<p>Cloudflare calls this
"<a href="https://blog.cloudflare.com/code-mode-mcp/">Code Mode</a>."
The full Cloudflare API (2,500+ endpoints) fits in about 1,000
tokens of tool definitions instead of 1.17 million for native
MCP with full schemas.</p>
<h1 id="one-command-to-connect">One command to connect</h1>
<pre><code class="language-bash">claude mcp add --transport http cloudflare-api \
  https://mcp.cloudflare.com/mcp
</code></pre>
<p>This adds the server to your <code>~/.claude.json</code> under the current
project. Restart Claude Code and run <code>/mcp</code> to confirm it shows up.</p>
<h2 id="oauth">OAuth</h2>
<p>The first time Claude calls a Cloudflare tool, your browser opens to
an authorization page. You pick an access level:</p>
<ul>
<li><strong>Read Only</strong> (recommended): view resources without making changes</li>
<li><strong>Workers Full Access</strong>: full access to Workers, KV, D1, R2</li>
<li><strong>DNS Full Access</strong>: full access to DNS records and zone settings</li>
<li><strong>Advanced</strong>: pick individual permissions</li>
</ul>
<p>You can always re-auth later with broader
permissions if you need to manage Workers or edit DNS from the
terminal.</p>
<p>After you log in and grant access, the OAuth token is cached
in <code>~/.mcp-auth/</code> (by the
<a href="https://github.com/geelen/mcp-remote">mcp-remote</a> transport
layer). Delete that directory to force re-authentication or
change access levels.</p>
<h1 id="querying-my-account">Querying my account</h1>
<h2 id="list-zones">List zones</h2>
<pre><code>> What zones do I have in Cloudflare?
</code></pre>
<p>Claude called <code>execute</code> with code that hit <code>GET /zones</code> and returned:</p>
<table>
<thead>
<tr>
<th>Zone</th>
<th>Status</th>
</tr>
</thead>
<tbody>
<tr>
<td>example.com</td>
<td>active</td>
</tr>
<tr>
<td>example.info</td>
<td>active</td>
</tr>
</tbody>
</table>
<h2 id="dns-records">DNS records</h2>
<pre><code>> Show me the DNS records for example.com
</code></pre>
<p>This one appears the most useful. Sanitized sample from the
full output:</p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Name</th>
<th>Content</th>
<th>Proxied</th>
</tr>
</thead>
<tbody>
<tr>
<td>A</td>
<td>example.com</td>
<td>198.51.100.1</td>
<td>No</td>
</tr>
<tr>
<td>CNAME</td>
<td>blog.example.com</td>
<td>c.storage.googleapis.com</td>
<td>Yes</td>
</tr>
<tr>
<td>MX</td>
<td>example.com</td>
<td>example-com.mail.protection.outlook.com</td>
<td>No</td>
</tr>
<tr>
<td>TXT</td>
<td>example.com</td>
<td>v=spf1 include:spf.protection.outlook.com -all</td>
<td>No</td>
</tr>
</tbody>
</table>
<p>The blog subdomain is proxied through Cloudflare (the orange cloud),
pointing at a GCS bucket. The root domain has A records from a
previous setup. The MX and TXT records are for email.</p>
<p>Useful when debugging
<a href="/cloudflare-https-frontend.html">certificate issues</a> or verifying
propagation after a change.</p>
<h2 id="zone-details">Zone details</h2>
<pre><code>> What are the nameservers for example.com?
</code></pre>
<p>It returned the two Cloudflare nameservers assigned to the zone,
plus the creation date and plan tier.</p>
<h2 id="what-else-to-ask-it">What else to ask it</h2>
<p>DNS lookups are the obvious use, but the full API means you can
ask about things you'd otherwise dig through the dashboard for:</p>
<ul>
<li>"Is Cloudflare proxying blog.example.com or is it DNS-only?"</li>
<li>"Do I have any DNS records still pointing at my old hosting
IP?"</li>
<li>"Show me all TXT records across all my zones"</li>
<li>"What Workers do I have deployed?"</li>
<li>"Compare the DNS records for example.com and example.info"</li>
<li>"Are there any firewall events for my zone?"</li>
<li>"What countries is my traffic coming from right now?"</li>
</ul>
<h1 id="product-specific-servers">Product-specific servers</h1>
<p>The main <code>mcp.cloudflare.com/mcp</code> endpoint covers the entire API,
but Cloudflare also ships
<a href="https://developers.cloudflare.com/agents/model-context-protocol/mcp-servers-for-cloudflare/">focused MCP servers</a>
for individual products:</p>
<ul>
<li><strong>DNS Analytics</strong>: <code>dns-analytics.mcp.cloudflare.com/mcp</code></li>
<li><strong>Observability</strong>: <code>observability.mcp.cloudflare.com/mcp</code></li>
<li><strong>Workers Builds</strong>: <code>builds.mcp.cloudflare.com/mcp</code></li>
<li><strong>Radar</strong>: <code>radar.mcp.cloudflare.com/mcp</code> (internet traffic
data)</li>
<li><strong>Browser Rendering</strong>: <code>browser.mcp.cloudflare.com/mcp</code></li>
</ul>
<p>Same transport, same <code>claude mcp add --transport http</code> setup.
The main server is enough for general use.</p>
<h1 id="compared-to-the-ga4-mcp-server">Compared to the GA4 MCP server</h1>
<p>The <a href="/ga4-mcp.html">GA4 MCP server</a> runs locally via <code>pipx</code>, uses
Google Application Default Credentials, and exposes five specific
tools. Setting it up requires enabling GCP APIs and running
<code>gcloud auth</code>.</p>
<p>The Cloudflare MCP is a remote server. No local install, no API
keys to manage. OAuth in the browser and you're done. The tradeoff
is you need network access to <code>mcp.cloudflare.com</code> and the
server's availability depends on Cloudflare.</p>
<p>The two-tool design (search + execute) is interesting. It means Claude
has to write JavaScript to query the API. But it
also means the responses are raw API output rather than pre-formatted
tool results. For most queries that's fine.</p>


<h2 id="table-of-contents">Table of contents</h2>
<ul>
<li><a href="#why-one-router">Why one router</a>
<ul>
<li><a href="#claudes-token-efficiencies">Claude's token efficiencies</a></li>
</ul>
</li>
<li><a href="#getting-an-openrouter-key">Getting an OpenRouter key</a></li>
<li><a href="#claude-code">Claude Code</a></li>
<li><a href="#opencode">OpenCode</a>
<ul>
<li><a href="#what-didnt-work">What didn't work</a></li>
<li><a href="#what-worked">What worked</a></li>
</ul>
</li>
<li><a href="#openclaw">OpenClaw</a></li>
<li><a href="#custom-openrouter-usage-mcp">Custom OpenRouter Usage MCP</a>
<ul>
<li><a href="#registering-it">Registering it</a></li>
<li><a href="#usage-output">Usage output</a></li>
<li><a href="#model-pricing-snapshot">Model pricing snapshot</a></li>
</ul>
</li>
</ul>
<h1 id="why-one-router">Why one router</h1>
<p>I run three AI tools regularly: Claude Code, OpenCode,
and OpenClaw. Each has its own API key, its own billing
dashboard, and its own model config. Anthropic bills
Claude Code. Google bills OpenClaw's Gemini usage.
OpenCode can talk to either.</p>
<p>That's three places to check spend, three sets of rate
limits, and no single view of what I'm burning through.
OpenRouter fixes this. It's a proxy that sits between
your tools and the model providers. You get one API key,
one billing dashboard, and the ability to swap models
without changing provider credentials.</p>
<p>The tradeoff is a small markup on token costs and an
extra network hop. For a personal setup where I want
visibility and flexibility, that's fine.</p>
<h2 id="claudes-token-efficiencies">Claude's token efficiencies</h2>
<p>Anthropic's Pro and Max plans include Claude Code
usage at a steep discount compared to raw API pricing.
Pro is $20/month with generous token allowances. Max
plans scale up from there. If you only use Claude Code,
the Pro plan is the cheapest way to run it.</p>
<p>The problem is that those plan tokens only work with
Claude Code through Anthropic's direct API. OpenCode
and OpenClaw are third-party tools. They can call
Claude models, but not through your Pro subscription.
They hit the standard API and bill at full rate.</p>
<p>So the choice is: keep Claude Code on the Pro plan
(cheapest for that one tool) and manage the other two
separately, or route everything through OpenRouter and
get unified billing at API rates. I went with
OpenRouter because the visibility across all three
tools matters more to me than the per-token savings
on Claude Code alone.</p>
<h1 id="getting-an-openrouter-key">Getting an OpenRouter key</h1>
<ol>
<li>Sign up at <a href="https://openrouter.ai">openrouter.ai</a></li>
<li>Go to Settings > Keys and create a new API key</li>
<li>Add credits (pay-as-you-go, no minimum)</li>
</ol>
<p>OpenRouter gave me $100 in free credits as a signup
promo. That's a lot of tokens to experiment with before
committing any money.</p>
<p>Set the key in your shell:</p>
<pre><code class="language-bash">export OPENROUTER_API_KEY="sk-or-v1-..."
</code></pre>
<p>Add it to your <code>~/.zshrc</code> or <code>~/.bashrc</code> so it persists.
The same key works for every tool below.</p>
<p>OpenRouter's <a href="https://openrouter.ai/models">models page</a>
shows per-token pricing for every model. Useful for
comparing costs before swapping models around.</p>
<h1 id="claude-code">Claude Code</h1>
<p>Claude Code normally talks directly to Anthropic's API.
To route it through OpenRouter, you override the base
URL and auth token via environment variables:</p>
<pre><code class="language-bash">ANTHROPIC_BASE_URL="https://openrouter.ai/api" \
ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY" \
ANTHROPIC_API_KEY="" \
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
claude
</code></pre>
<p>Four variables. <code>ANTHROPIC_BASE_URL</code> points Claude Code
at OpenRouter instead of Anthropic. <code>ANTHROPIC_AUTH_TOKEN</code>
passes your OpenRouter key. <code>ANTHROPIC_API_KEY</code> must be
set to an empty string, otherwise Claude Code tries to
use it and the auth conflicts.
<code>CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC</code> stops
telemetry calls that would fail against OpenRouter.</p>
<p>That's verbose to type every time. I wrapped it in a
shell function:</p>
<pre><code class="language-bash"># ~/.zshrc
orclaude() {
  ANTHROPIC_BASE_URL="https://openrouter.ai/api" \
  ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY" \
  ANTHROPIC_API_KEY="" \
  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
  claude "$@"
}
</code></pre>
<p>Now <code>orclaude</code> launches Claude Code through OpenRouter.
Regular <code>claude</code> still uses the Anthropic API directly.</p>
<p>You can also swap models. Claude Code has three model
slots (Opus, Sonnet, Haiku) that you can override:</p>
<pre><code class="language-bash">export ANTHROPIC_DEFAULT_SONNET_MODEL=\
  "google/gemini-2.5-pro"
export ANTHROPIC_DEFAULT_HAIKU_MODEL=\
  "google/gemini-2.5-flash"
</code></pre>
<p>Any model on OpenRouter that supports tool use works.
Models without tool use will break Claude Code since
it relies on tools for file reading, editing, and
command execution.</p>
<h1 id="opencode">OpenCode</h1>
<p>OpenCode has native OpenRouter support.</p>
<h2 id="what-didnt-work">What didn't work</h2>
<p>I tried putting the API key in <code>opencode.json</code>. It passed config validation but
OpenCode still tried to bill through its own payment system. "No payment method" error
pointing at OpenCode's billing page, not OpenRouter's.</p>
<h2 id="what-worked">What worked</h2>
<p>OpenCode picks up <code>OPENROUTER_API_KEY</code> from the environment automatically. The config
file only needs the model names. <code>opencode.json</code> goes in the project root where you
launch it, or the global <code>~/.config/opencode/opencode.json</code>.</p>
<pre><code class="language-json">{
  "model": "openrouter/anthropic/claude-sonnet-4-6",
  "small_model": "openrouter/anthropic/claude-haiku-4-5"
}
</code></pre>
<p>The key has to be registered through OpenCode's auth system. Inside the TUI:</p>
<ol>
<li>Run <code>/connect</code></li>
<li>Search for "OpenRouter"</li>
<li>Paste your API key</li>
</ol>
<p>After that, OpenCode routes through OpenRouter. The
<code>openrouter/</code> prefix on model names tells it which
provider to use.</p>
<p>Note: OpenCode shows a warning when you select
OpenRouter saying requests "will often be routed to
subpar providers." That feels like they're trying to just sell their own model hosting.</p>
<h1 id="openclaw">OpenClaw</h1>
<p>OpenClaw has native OpenRouter support. The model
reference format is <code>openrouter/&#x3C;provider>/&#x3C;model></code>,
same as OpenCode.</p>
<p>In OpenClaw's home directory, <code>openclaw.json</code>, for the K8s setup
<code>/home/node/.openclaw/openclaw.json</code> (the PVC mount). For a local install it'd be
<code>~/.openclaw/openclaw.json.</code>:</p>
<pre><code class="language-json5">{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      model: {
        primary: "openrouter/anthropic/claude-sonnet-4-6"
      },
    },
  },
}
</code></pre>
<p>Or use the CLI:</p>
<pre><code class="language-bash">openclaw onboard \
  --auth-choice apiKey \
  --token-provider openrouter \
  --token "$OPENROUTER_API_KEY"
</code></pre>
<p>Since my OpenClaw runs in K8s with secrets injected via
Vault, I added <code>OPENROUTER_API_KEY</code> to the Vault secret
and updated the Vault Agent template to export it. Same
pattern as the
<a href="/openclaw-linear-skill.html">Linear API key</a> from the
previous post.</p>
<p>After redeploying, I cleared my OpenClaw agent's sessions (OpenClaw
caches the model config per session) and asked what
model it was running:</p>
<pre><code class="language-text">Claude: What model are you running on?
Pai: I'm running on Claude Sonnet 4.6 via OpenRouter
  (openrouter/anthropic/claude-sonnet-4-6).
</code></pre>
<p>Previously Pai ran Gemini 2.5 Flash through Google's
API directly. Now it's Claude Sonnet 4.6 through
OpenRouter. Same Vault-injected credentials pattern,
different model, one billing dashboard.</p>
<p>The Linear skill still works through the new model.
Pai listed my teams and issues the same as before.
The skill's curl commands don't care which model is
driving the agent.</p>
<h1 id="custom-openrouter-usage-mcp">Custom OpenRouter Usage MCP</h1>
<p>With everything routed through OpenRouter, I wanted
to check my spend without leaving the terminal. OpenRouter
has a billing API, so I built a small
<a href="https://github.com/kylep/multi/tree/main/apps/mcp-servers/openrouter">MCP server</a>
that queries it.</p>
<p>The server has two tools. <code>get_usage</code> calls the
<code>/api/v1/key</code> endpoint and returns daily, weekly, monthly,
and total spend plus remaining credits. <code>get_model_pricing</code>
calls <code>/api/v1/models</code> and shows per-million-token costs,
with an optional filter to search by model name.</p>
<p>The whole thing is one TypeScript file using the MCP SDK
with stdio transport. It reads <code>OPENROUTER_API_KEY</code> from
the environment, same key the other tools already use.</p>
<h2 id="registering-it">Registering it</h2>
<p>In <code>~/.claude.json</code>, under the project's <code>mcpServers</code>:</p>
<pre><code class="language-json">"openrouter": {
  "type": "stdio",
  "command": "node",
  "args": [
    "/path/to/openrouter-mcp/build/index.js"
  ]
}
</code></pre>
<p>No <code>env</code> block needed. Claude Code spawns it as a child
process, which inherits the shell environment.</p>
<h2 id="usage-output">Usage output</h2>
<p>After restarting Claude Code, I asked it to check my
OpenRouter usage:</p>
<pre><code class="language-text">Key: sk-or-v1-3fd...374
Free tier: no

Usage:
  Today:  $0.5467
  Week:   $0.5467
  Month:  $0.5467
  Total:  $0.5467

Credit limit:
  Limit:     $200.0000
  Remaining: $199.4533
</code></pre>
<p>That $0.55 is from a few hours of Claude Code and
OpenCode use. The $200 limit is what I set on the key
in OpenRouter's dashboard.</p>
<p>The pricing tool is useful for comparing models before
switching. Searching "claude-sonnet-4" shows all the
Sonnet variants and their per-million-token rates side
by side.</p>
<h2 id="model-pricing-snapshot">Model pricing snapshot</h2>
<p>Pulled from <code>get_model_pricing</code> on 2026-03-10:</p>
<table>
<thead>
<tr>
<th>Model</th>
<th>Prompt</th>
<th>Completion</th>
<th>Context</th>
</tr>
</thead>
<tbody>
<tr>
<td>openai/gpt-5.4-pro</td>
<td>$30.00/M</td>
<td>$180.00/M</td>
<td>1050k</td>
</tr>
<tr>
<td>openai/gpt-5.4</td>
<td>$2.50/M</td>
<td>$15.00/M</td>
<td>1050k</td>
</tr>
<tr>
<td>openai/gpt-5.3-codex</td>
<td>$1.75/M</td>
<td>$14.00/M</td>
<td>400k</td>
</tr>
<tr>
<td>openai/gpt-5.2-pro</td>
<td>$21.00/M</td>
<td>$168.00/M</td>
<td>400k</td>
</tr>
<tr>
<td>openai/gpt-5.1</td>
<td>$1.25/M</td>
<td>$10.00/M</td>
<td>400k</td>
</tr>
<tr>
<td>anthropic/claude-opus-4.6</td>
<td>$5.00/M</td>
<td>$25.00/M</td>
<td>1000k</td>
</tr>
<tr>
<td>anthropic/claude-sonnet-4.6</td>
<td>$3.00/M</td>
<td>$15.00/M</td>
<td>1000k</td>
</tr>
<tr>
<td>anthropic/claude-haiku-4.5</td>
<td>$1.00/M</td>
<td>$5.00/M</td>
<td>200k</td>
</tr>
<tr>
<td>anthropic/claude-opus-4</td>
<td>$15.00/M</td>
<td>$75.00/M</td>
<td>200k</td>
</tr>
<tr>
<td>anthropic/claude-sonnet-4</td>
<td>$3.00/M</td>
<td>$15.00/M</td>
<td>200k</td>
</tr>
<tr>
<td>google/gemini-3.1-pro-preview</td>
<td>$2.00/M</td>
<td>$12.00/M</td>
<td>1049k</td>
</tr>
<tr>
<td>google/gemini-2.5-pro</td>
<td>$1.25/M</td>
<td>$10.00/M</td>
<td>1049k</td>
</tr>
<tr>
<td>google/gemini-2.5-flash</td>
<td>$0.30/M</td>
<td>$2.50/M</td>
<td>1049k</td>
</tr>
<tr>
<td>google/gemini-2.5-flash-lite</td>
<td>$0.10/M</td>
<td>$0.40/M</td>
<td>1049k</td>
</tr>
<tr>
<td>deepseek/deepseek-v3.2</td>
<td>$0.25/M</td>
<td>$0.40/M</td>
<td>164k</td>
</tr>
<tr>
<td>deepseek/deepseek-r1-0528</td>
<td>$0.45/M</td>
<td>$2.15/M</td>
<td>164k</td>
</tr>
<tr>
<td>meta-llama/llama-4-maverick</td>
<td>$0.15/M</td>
<td>$0.60/M</td>
<td>1049k</td>
</tr>
<tr>
<td>mistralai/mistral-large-2512</td>
<td>$0.50/M</td>
<td>$1.50/M</td>
<td>262k</td>
</tr>
<tr>
<td>qwen/qwen3.5-397b-a17b</td>
<td>$0.39/M</td>
<td>$2.34/M</td>
<td>262k</td>
</tr>
<tr>
<td>qwen/qwen3-coder-plus</td>
<td>$0.65/M</td>
<td>$3.25/M</td>
<td>1000k</td>
</tr>
</tbody>
</table>
<p>Prices are per million tokens. These change often.
Check OpenRouter's models page for current rates.</p>


<p>Linear's official MCP server launched in May 2025. It lets the robots lean in on the
project management work. I want to get some ideation-bots going.</p>
<h2 id="supported-commands">Supported Commands</h2>
<table>
<thead>
<tr>
<th>Category</th>
<th>Commands</th>
</tr>
</thead>
<tbody>
<tr>
<td>Issues</td>
<td>list, get, create/update, status, statuses</td>
</tr>
<tr>
<td>Projects</td>
<td>list, get, create/update, labels</td>
</tr>
<tr>
<td>Documents</td>
<td>list, get, create, update, search</td>
</tr>
<tr>
<td>Comments</td>
<td>list, create/update, delete</td>
</tr>
<tr>
<td>Attachments</td>
<td>get, create, delete, extract images</td>
</tr>
<tr>
<td>Milestones</td>
<td>list, get, create/update</td>
</tr>
<tr>
<td>Cycles</td>
<td>list</td>
</tr>
<tr>
<td>Teams</td>
<td>list, get</td>
</tr>
<tr>
<td>Users</td>
<td>list, get</td>
</tr>
<tr>
<td>Labels</td>
<td>list issue labels, create issue label</td>
</tr>
</tbody>
</table>
<h2 id="setup">Setup</h2>
<p>Linear hosts the MCP server at <code>https://mcp.linear.app/mcp</code>. Use that endpoint, not the
old SSE one which is deprecated.</p>
<h3 id="claude-code">Claude Code</h3>
<pre><code class="language-bash">claude mcp add --transport http linear-server https://mcp.linear.app/mcp
</code></pre>
<p>Restart and authenticate via OAuth.</p>
<hr>
<h1 id="idea-nightly-ideation-engine">Idea: Nightly Ideation Engine</h1>
<p>Instead of using Linear as a human-operated task tracker, an AI agent can read youri
codebase, compare it against goals, and file suggestions directly.</p>
<p>What I'm hoping to build is a system where a scheduled agent runs nightly. It reads
blog posts, checks page speed, reviews SEO metadata, and compares everything against a
set of high-level goals:</p>
<ul>
<li>100% accurate content</li>
<li>Fast loading</li>
<li>Low cost</li>
<li>Looks good</li>
<li>Good SEO</li>
<li>Interesting tutorials about emerging tooling</li>
</ul>
<p>It should create Linear issues for anything worth improving, labeled "Suggestion" and
drop them into the Backlog.</p>
<h3 id="the-pipeline">The pipeline</h3>
<p>Linear's built-in statuses act as gates between human and agent
work.</p>
<pre class="mermaid">
stateDiagram-v2
    [*] --> Backlog: AI files suggestion
    Backlog --> Todo: Human promotes
    Backlog --> Canceled: Human rejects
    Todo --> InProgress: Agent picks up
    InProgress --> InReview: Agent finishes
    InReview --> Done: Human approves
    InReview --> InProgress: Human pushes back
</pre>
<p>Each step has a clear owner:</p>
<table>
<thead>
<tr>
<th>Status</th>
<th>Owner</th>
<th>What happens</th>
</tr>
</thead>
<tbody>
<tr>
<td>Backlog</td>
<td>AI</td>
<td>Nightly agent creates suggestion issues</td>
</tr>
<tr>
<td>Todo</td>
<td>Human</td>
<td>You move the good ones forward</td>
</tr>
<tr>
<td>In Progress</td>
<td>Agent</td>
<td>A working agent picks it up</td>
</tr>
<tr>
<td>In Review</td>
<td>Agent</td>
<td>Agent finishes, leaves a comment</td>
</tr>
<tr>
<td>Done</td>
<td>Human</td>
<td>You verify and close</td>
</tr>
<tr>
<td>Canceled</td>
<td>Human</td>
<td>Bad idea, toss it</td>
</tr>
</tbody>
</table>
<h3 id="agent-notes-via-comments">Agent notes via comments</h3>
<p>When agents work on an issue, they leave comments. This beats
internal context files because comments are visible, searchable,
and survive across sessions. If one agent starts a task and another
finishes it, the full history is right there on the issue.</p>
<p>I might also run multiple planning agents that each comment on a
ticket before I review it. A fact-checker, a SEO reviewer, and a
style auditor could all weigh in on the same Backlog issue. By the
time I look at it, there's already a thread of perspectives.</p>
<pre><code class="language-bash"># An agent checking for work:
# list_issues with label="Suggestion", state="Todo"

# An agent leaving notes:
# save_comment with issueId and markdown body
</code></pre>
<h3 id="filtering">Filtering</h3>
<p>The nightly agent queries existing Backlog suggestions before
creating new ones, avoiding duplicates. Working agents filter
by label and status to find their next task:</p>
<pre><code>list_issues → label: "Suggestion", state: "Todo"
</code></pre>
<h2 id="defining-state-as-prompts">Defining State as Prompts</h2>
<p>Linear's community Terraform provider exists but only covers teams,
labels, workflow states, and templates. No custom views. The GraphQL
API has a <code>customViewCreate</code> mutation, but nobody's wrapped it in
IaC tooling yet.</p>
<p>So instead of declaring views in HCL, I described mine as a prompt
and had Claude set it up via Playwright MCP:</p>
<blockquote>
<p>Create a custom view called "Suggestion Backlog" on the Pericak
team. Filter to issues where label includes "Suggestion" and
status is "Backlog". Description: "AI-generated improvement
suggestions awaiting human review".</p>
</blockquote>
<p>Claude navigated to Linear in Chromium, clicked "Add new view",
filled in the name, added both filters, and hit Save. The view
now lives as a tab on the team page.</p>
<p>This is nondeterministic state management. There's no lock file,
no plan/apply, no drift detection. But it works, and the prompt
is the documentation. If the view ever gets deleted, re-run the
prompt.</p>
<h3 id="a-linear-admin-agent">A Linear-Admin agent</h3>
<p>A "Linear-Admin" agent could own all workspace
configuration: views, labels, workflow states, notification
settings. You'd feed it a doc describing your desired workspace
setup, and it would use Playwright to converge Linear's UI to
match. Like Terraform, but with a browser instead of an API.</p>
<p>The tradeoffs are real. Playwright clicks are slow, brittle if
Linear redesigns their UI, and hard to make idempotent. But for
a personal workspace where the alternative is "click around in
the UI manually," the prompt-as-IaC approach is surprisingly
practical.</p>
<p>Still faster than a person.</p>


<p>Two things in this post. First, wiring up GA4 on this blog, which turns out to
be pretty straightforward on Next.js. Second, connecting the official GA4 MCP
server so Claude Code can query the analytics data directly in natural language.</p>
<p>Once the MCP is connected, you can ask
Claude things like "which posts got the most traffic last month" or "what are
my top referral sources" and it queries GA4 and tells you. No dashboard required.</p>
<h1 id="setting-up-ga4">Setting Up GA4</h1>
<h2 id="create-the-property">Create the Property</h2>
<p>Go to <a href="https://analytics.google.com">analytics.google.com</a>. Hit Create →
Property, fill in a name and your timezone, click through the business details
screens (mostly irrelevant for a personal blog), then choose Web as the
platform and enter your domain. GA4 creates the property and a web data stream
in one flow.</p>
<p>Once the stream is created, click it to open the stream details. The
measurement ID is right there. It looks like <code>G-XXXXXXXXXX</code>.</p>
<h2 id="add-tracking-to-nextjs">Add Tracking to Next.js</h2>
<p>This blog is statically exported Next.js. The right place to add the tracking
script is <code>_app.js</code>, using <code>next/script</code> with <code>afterInteractive</code> so it doesn't
block rendering:</p>
<pre><code class="language-jsx">// pages/_app.js
import Script from 'next/script';

export default function MyApp({ Component, pageProps }) {
  return (
    &#x3C;>
      &#x3C;Script
        src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"
        strategy="afterInteractive"
      />
      &#x3C;Script id="google-analytics" strategy="afterInteractive">
        {`
          window.dataLayer = window.dataLayer || [];
          function gtag(){dataLayer.push(arguments);}
          gtag('js', new Date());
          gtag('config', 'G-XXXXXXXXXX');
        `}
      &#x3C;/Script>
      {/* rest of your app */}
    &#x3C;/>
  );
}
</code></pre>
<p>Replace <code>G-XXXXXXXXXX</code> with your actual measurement ID. Deploy, open the GA4
realtime report, and visit your site to confirm hits are coming in. Takes a
couple minutes to show up.</p>
<p>Note: if you're serving via a CDN with aggressive caching (this blog uses GCS),
make sure the HTML is being revalidated, not served stale. The script tag needs
to actually make it into the page.</p>
<h1 id="the-ga4-mcp-server">The GA4 MCP Server</h1>
<p>Google ships an <a href="https://github.com/googleanalytics/google-analytics-mcp">official MCP server</a>
for GA4. It's read-only, which is fine for querying data. It wraps the GA4
Admin API and Data API and exposes a handful of tools Claude can call.</p>
<h2 id="auth-setup">Auth Setup</h2>
<p>The server uses Google Application Default Credentials. Before you can log in,
you need to enable two APIs in your GCP project. Check which project your
gcloud CLI is using:</p>
<pre><code class="language-bash">gcloud config get-value project
</code></pre>
<p>Then enable the APIs:</p>
<pre><code class="language-bash"># Required for get_account_summaries, get_property_details
gcloud services enable analyticsadmin.googleapis.com

# Required for run_report, run_realtime_report
gcloud services enable analyticsdata.googleapis.com
</code></pre>
<p>Then log in:</p>
<pre><code class="language-bash">gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform
</code></pre>
<p>The <code>cloud-platform</code> scope is required alongside <code>analytics.readonly</code>. Without
it you get a deprecation error and the auth fails.</p>
<p>That stores credentials at
<code>~/.config/gcloud/application_default_credentials.json</code>. No service account
file needed.</p>
<p>If you'd rather use a service account (better for shared environments), create
one in Google Cloud Console, grant it Viewer access on your GA4 property, and
download the JSON key. Set <code>GOOGLE_APPLICATION_CREDENTIALS</code> to point at it.</p>
<h2 id="add-to-claude-code">Add to Claude Code</h2>
<p>Add it to <code>.mcp.json</code> at the project root to share it with the team:</p>
<pre><code class="language-json">{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/Users/you/.config/gcloud/application_default_credentials.json"
      }
    }
  }
}
</code></pre>
<p>Or add it for yourself only:</p>
<pre><code class="language-bash">claude mcp add analytics-mcp --env GOOGLE_APPLICATION_CREDENTIALS=~/.config/gcloud/application_default_credentials.json -- pipx run analytics-mcp
</code></pre>
<p>Restart Claude Code and run <code>/mcp</code> to confirm <code>analytics-mcp</code> is listed.</p>
<h2 id="what-it-exposes">What It Exposes</h2>
<p>Five tools:</p>
<ul>
<li><code>get_account_summaries</code>: lists your GA4 accounts and properties. Good first
call to confirm auth is working and grab your property ID.</li>
<li><code>get_property_details</code>: details for a specific property.</li>
<li><code>run_report</code>: the main one. Queries the GA4 Data API with dimensions and
metrics of your choice.</li>
<li><code>run_realtime_report</code>: same thing but against the realtime endpoint.</li>
<li><code>get_custom_dimensions_and_metrics</code>: lists any custom dimensions you've
defined on the property.</li>
</ul>
<p>The server is read-only. It can't modify your GA4 configuration.</p>
<h1 id="querying-data">Querying Data</h1>
<p>Once connected, you can ask in plain English. Claude figures out which dimensions and
metrics to use and calls <code>run_report</code> for you.</p>
<p>Some things I've asked it:</p>
<p><strong>Traffic overview:</strong></p>
<blockquote>
<p>What were my total users and sessions last week, broken down by day?</p>
</blockquote>
<p><strong>Top content:</strong></p>
<blockquote>
<p>Which pages got the most views in the last 30 days?</p>
</blockquote>
<p><strong>Referrals:</strong></p>
<blockquote>
<p>What are my top traffic sources this month?</p>
</blockquote>
<p><strong>Realtime:</strong></p>
<blockquote>
<p>How many people are on the site right now and what pages are they on?</p>
</blockquote>
<p>For anything beyond basic questions, it helps to know a few GA4 concepts.
"Sessions" and "users" mean what you'd expect. "Engaged sessions" are ones
where the user spent more than 10 seconds, viewed more than one page, or
triggered a conversion. The distinction matters when you're trying to tell real
readers from bots.</p>
<p>Claude will sometimes ask for your property ID before running a report. Either
give it the <code>G-XXXXXXXXXX</code> measurement ID or the numeric property ID from the
GA4 UI. If you add the property ID to your <code>CLAUDE.md</code> or project context,
it'll stop asking.</p>
<h1 id="what-its-actually-good-for">What It's Actually Good For</h1>
<p>The dashboard is fine for browsing. The MCP is better for specific questions,
comparing time periods, and anything you'd normally have to build a custom
report for.</p>
<p>The bigger thing I have in mind though is eventually having like OpenClaw or similar
using it in an ideation loop. Some sort of PM agent that adds potential tickets to a
Jira or Linear board and uses this data as an input.</p>
<p>I'm also just starting to love being back in tmux and not having to operate websites
as much. I set up the <a href="/cloudflare-mcp.html">Cloudflare MCP server</a>
next for the same reason.</p>
<p>Lastly I figure I can hook this up to voice commands somehow for a really custom voice
assistant.</p>


<p>Playwright MCP gives Claude Code a real browser to drive. Coding agents are kind of
awful at doing the right thing unless they can verify their work. If you want to do any
front-end work and not be the human in the loop every step along the way, it's gotta be
able to operate Chromium and review the photos. Opus 4.6 is multi modal and any later
models will just be better, so it can consume the photos itself.</p>
<h1 id="setup">Setup</h1>
<pre><code class="language-bash">claude mcp add playwright -- npx @playwright/mcp@latest --browser chromium
</code></pre>
<p>Or add it to <code>.mcp.json</code> at the project root to share it with the team:</p>
<pre><code class="language-json">{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--browser", "chromium"]
    }
  }
}
</code></pre>
<p>Restart Claude Code. Run <code>/mcp</code> to confirm it's listed. If you've got a session
already, tell it to store its memory first and to load it back after, works well.</p>
<h1 id="what-playwright-does">What Playwright Does</h1>
<p>At work we migrated from Selenium/WebDriver to this to address flakiness long before
the MCP was out, but at this point my interest in playwright is more about the AI
integration.</p>
<p>Playwright MCP exposes the browser as individual tools Claude can call. This post demos
the main ones, with examples against my dev blog server at <code>http://localhost:3000</code>.</p>
<p>I'm pretty sure I'll be able to post agents at this post even to tell it how I want
them to work, and ask them to write a claude.md about it.</p>
<h2 id="browser_navigate">browser_navigate</h2>
<pre><code>browser_navigate: { url: "http://localhost:3000" }
</code></pre>
<p>Loads a URL. Returns the final URL (catches redirects) and a console
error/warning count alongside the snapshot.</p>
<h2 id="browser_snapshot">browser_snapshot</h2>
<pre><code>browser_snapshot: {}
</code></pre>
<p>Returns an accessibility tree of the current page. This is the main tool for
reading page state: what's visible, what's interactive, what the structure is.
Faster and more structured than HTML, and the <code>ref</code> values it returns are what
<code>browser_click</code> and <code>browser_type</code> use to target elements.</p>
<h2 id="browser_take_screenshot">browser_take_screenshot</h2>
<pre><code>browser_take_screenshot: {}
</code></pre>
<p>Returns a PNG of the current viewport. This is the tool Claude uses to judge
look and feel. It's multimodal, so it actually reads the image and can catch
layout problems, broken images, or rendering bugs that don't show up in the
accessibility tree. It can't extract <code>ref</code> values from a screenshot though, so
use <code>browser_snapshot</code> when you need to drive further actions.</p>
<h2 id="browser_click">browser_click</h2>
<pre><code>browser_click: { element: "Posts", ref: "..." }
</code></pre>
<p>Clicks by visible label or element reference. Drives navigation and interactive
components.</p>
<h2 id="browser_type">browser_type</h2>
<pre><code>browser_type: { element: "search input", ref: "...", text: "Playwright" }
</code></pre>
<p>Types into an input. The <code>ref</code> comes from <code>browser_snapshot</code>.</p>
<h2 id="browser_evaluate">browser_evaluate</h2>
<pre><code>browser_evaluate: { function: "() => document.title" }
</code></pre>
<p>Runs JavaScript in the page context. For reading state that isn't in the DOM.</p>
<h2 id="browser_wait_for">browser_wait_for</h2>
<pre><code>browser_wait_for: { text: "Playwright MCP" }
browser_wait_for: { textGone: "Loading..." }
browser_wait_for: { time: 2 }
</code></pre>
<p>Three modes: wait for text to appear, wait for text to disappear, or sleep for
N seconds. No explicit timeout parameter. It uses Playwright's default (30s).
Needed for anything that renders async.</p>
<h2 id="browser_console_messages">browser_console_messages</h2>
<pre><code>browser_console_messages: {}
browser_console_messages: { level: "error" }
</code></pre>
<p>Returns the full console output: message text, level, and source location.
The <code>level</code> filter works like log levels: <code>error</code> gives you errors only, <code>info</code>
gives you everything. The navigate and snapshot tools show a count
(<code>1 errors, 0 warnings</code>), but this is where you get the actual content.</p>
<p>Claude can read and interpret it. Errors include full stack traces and, for
things like React hydration mismatches, the actual HTML diff showing which
component diverged between server and client. Ask Claude to look at the console
and it'll summarize the errors and suggest fixes rather than dumping the raw
text at you.</p>
<p>First thing to check when something looks wrong but the DOM appears fine.</p>
<p>Also worth having in every test suite: a test that loads each key page and
asserts no console errors. It catches a lot of regressions for free.</p>
<pre><code class="language-typescript">test('no console errors on homepage', async ({ page }) => {
  const errors: string[] = [];
  page.on('console', msg => {
    if (msg.type() === 'error') errors.push(msg.text());
  });
  await page.goto('/');
  expect(errors).toHaveLength(0);
});
</code></pre>
<h2 id="browser_network_requests">browser_network_requests</h2>
<pre><code>browser_network_requests: {}
browser_network_requests: { includeStatic: true }
</code></pre>
<p>The network log since the last navigation. Returns method, URL, and status code
for each request. Good for catching 404s on assets or confirming a request
fired. Excludes static resources by default. Pass <code>includeStatic: true</code> to see
everything.</p>
<p>No timing data. If you need to assert on response duration, use Playwright's
<code>page.on('response', ...)</code> in a test instead:</p>
<pre><code class="language-typescript">test('API calls complete within 500ms', async ({ page }) => {
  const timings: number[] = [];
  page.on('response', async response => {
    if (response.url().includes('/api/')) {
      const timing = response.timing();
      timings.push(timing.responseEnd - timing.requestStart);
    }
  });
  await page.goto('/');
  expect(Math.max(...timings)).toBeLessThan(500);
});
</code></pre>
<p><code>page.on('response', ...)</code> fires for every network response. Filter by URL
pattern to target whatever you care about: API calls, a specific domain,
a file type. Same pattern works for asserting no 404s:</p>
<pre><code class="language-typescript">test('no broken asset requests', async ({ page }) => {
  const failures: string[] = [];
  page.on('response', response => {
    if (response.status() >= 400) failures.push(`${response.status()} ${response.url()}`);
  });
  await page.goto('/');
  expect(failures).toHaveLength(0);
});
</code></pre>
<h2 id="browser_resize">browser_resize</h2>
<pre><code>browser_resize: { width: 375, height: 812 }
</code></pre>
<p>Resizes the viewport. Triggers CSS media queries based on width, so layout
reflows and responsive breakpoints work as expected. Good for a quick visual
check. Pair it with <code>browser_take_screenshot</code> to see what changed.</p>
<p>It doesn't change the user agent, device pixel ratio, or pointer type. That
means UA-sniffing code still thinks it's a desktop browser, <code>srcset</code> serves
desktop-resolution images, and <code>hover: none</code> / <code>pointer: coarse</code> media queries
don't fire. For proper mobile regression coverage, use Playwright's device
emulation in the test config instead:</p>
<pre><code class="language-typescript">import { devices } from '@playwright/test';

// playwright.config.ts
export default defineConfig({
  projects: [
    { name: 'desktop', use: { viewport: { width: 1280, height: 720 } } },
    { name: 'mobile',  use: { ...devices['iPhone 13'] } },
  ],
});
</code></pre>
<p><code>devices['iPhone 13']</code> sets viewport, user agent, device scale factor, and
touch support together. Your tests run against both profiles automatically.</p>
<hr>
<h1 id="gherkin-specs-as-source-of-truth">Gherkin Specs as Source of Truth</h1>
<p>AI-generated test code has a maintenance problem. The agent writes tests, they
drift from what the UI actually does, someone edits them directly, and now you
have no reliable source of truth.</p>
<p>What I'm experimenting with here is to keep specs in Gherkin, generate tests from
them, and treat the generated code as a build artifact. Claude rewrites the tests from
spec whenever they go stale. Nobody edits the generated files.</p>
<pre><code>tests/
  spec/
    index.feature
    post.feature
    navigation.feature
  playwright/
    index.spec.ts      # generated, do not edit
    post.spec.ts       # generated, do not edit
    navigation.spec.ts # generated, do not edit
  playwright.config.ts
</code></pre>
<p>The actual specs for this blog live in
<a href="https://github.com/kylep/multi/tree/main/apps/blog/blog/tests/spec/"><code>tests/spec/</code></a>.
Here's the index one:</p>
<pre><code class="language-gherkin"># tests/spec/index.feature

Feature: Blog index page

  Scenario: Page loads with post list
    Given I navigate to the blog homepage
    Then I see a list of posts
    And each post has a title, date, and summary

  Scenario: Posts link to their detail page
    Given I navigate to the blog homepage
    When I click the first post title
    Then I am on a post detail page
    And the post has a title and content

  Scenario: Pagination controls are present
    Given I navigate to the blog homepage
    Then I see pagination controls
</code></pre>
<p>The instruction to Claude is: read the <code>.feature</code> file, generate a matching
<code>spec.ts</code>. If something breaks, fix the spec first, then regenerate. The feature
file is what documents how the UI is supposed to behave.</p>
<p>A <code>CLAUDE.md</code> in <code>tests/</code> gives Claude guidance when generating tests, things
like keeping the suite under a minute, no sleeps, one assertion per scenario.
If you're using <a href="/ruler-cross-tool-ai-rules.html">Ruler</a> to share rules across tools,
put that content in <code>tests/.ruler/</code> instead and let Ruler generate the
<code>CLAUDE.md</code> alongside your <code>AGENTS.md</code>.</p>
<h1 id="claude-verifying-its-own-changes">Claude Verifying Its Own Changes</h1>
<p>This is the part I wanted to try. Claude makes a change, then uses the MCP
browser to check whether it worked, before handing back.</p>
<pre class="mermaid">
graph TD
    A[Claude makes a change] --> B[Build blog]
    B --> C[Start dev server]
    C --> D[Navigate to affected page]
    D --> E[Screenshot + read DOM]
    E --> F{Looks right?}
    F -->|No| H[Investigate and fix]
    H --> B
    F -->|Yes| I{Add a test?}
    I -->|No| G[Done]
    I -->|Yes| J[Write Gherkin scenario]
    J --> K[Generate Playwright spec]
    K --> L[Run test to verify]
    L --> G
</pre>
<p>It's nondeterministic. That's the strength and the problem. Claude
isn't following a checklist. It navigates to what it changed, reads what's
there, and decides whether it matches intent. That catches a class of dumb
mistakes a checklist wouldn't, but it also means "looks right" depends on the
agent's judgment, which isn't always reliable.</p>
<p>The multimodal part matters here. When Claude calls <code>browser_take_screenshot</code>,
it doesn't get back an opaque file path. It sees the rendered page. It can tell
if an image failed to load, if a layout broke, if text is overlapping. That's
more than a DOM inspection gives you. It's also not a substitute for explicit
assertions, because "looks right" is still a judgment call.</p>
<pre class="mermaid">
graph TD
    A[Claude ready to commit] --> B[Start dev server]
    B --> C[Run Playwright tests]
    C --> D{Tests pass?}
    D -->|Yes| E[Commit]
    D -->|No| F[Investigate and fix]
    F --> C
</pre>
<p>This part is deterministic as reasonably quick in headless mode.
Screenshots are for the stuff that's hard to assert: visual regressions, style
issues, anything where you'd want a human to glance at it.</p>
<h2 id="playwright-config-for-the-blog">Playwright Config for the Blog</h2>
<pre><code class="language-bash">cd apps/blog
npm init playwright@latest
</code></pre>
<pre><code class="language-typescript">// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests/playwright',
  use: {
    baseURL: 'http://localhost:3000',
  },
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: true,
  },
});
</code></pre>
<p>The generated specs live in
<a href="https://github.com/kylep/multi/tree/main/apps/blog/blog/tests/playwright/"><code>tests/playwright/</code></a>.
Run them with:</p>
<pre><code class="language-bash">cd apps/blog/blog
npx playwright test
</code></pre>
<p>Claude gets pass/fail output with assertion details. Unambiguous, scriptable,
no judgment required.</p>
<p>Note: <code>npx playwright test</code> runs headless by default. No browser window appears.
Pass <code>--headed</code> to watch it run, or set <code>headless: false</code> in the config.</p>
<h1 id="where-this-is-going-agent-teams">Where This Is Going: Agent Teams</h1>
<p>Claude Code has a multi-agent feature in preview. The setup that makes sense
here is a builder agent making changes and a separate verifier agent running
tests and reporting back. They work in parallel. Failures come back as tasks.</p>
<p>Not wired up yet. But the spec files, generated tests, and MCP config are what
make it possible to hand verification to a different agent without losing the
context of what the tests mean. I ended up wiring this into a <a href="/agent-org-chart.html">QA subagent in
the agent team</a>.</p>


Kyle Pericak

"It works in my environment"

Categories

Tags