<h2 id="table-of-contents">Table of contents</h2>
<ul>
<li><a href="#a-warning">A warning</a></li>
<li><a href="#why-an-org-chart-for-ai-agents">Why an org chart for AI agents</a></li>
<li><a href="#the-agents">The agents</a></li>
<li><a href="#the-org-chart">The org chart</a></li>
<li><a href="#pai-the-executive-assistant">Pai: the executive assistant</a>
<ul>
<li><a href="#agent-invocation-via-bash">Agent invocation via Bash</a></li>
<li><a href="#dry-run-mode">Dry-run mode</a></li>
<li><a href="#adversarial-loops">Adversarial loops</a></li>
<li><a href="#logging">Logging</a></li>
</ul>
</li>
<li><a href="#the-wiki-layer">The wiki layer</a></li>
<li><a href="#pai-in-action">Pai in action</a>
<ul>
<li><a href="#the-dry-run">The dry-run</a></li>
<li><a href="#the-real-run">The real run</a></li>
<li><a href="#the-adversarial-demo">The adversarial demo</a></li>
</ul>
</li>
<li><a href="#watching-them-work">Watching them work</a></li>
</ul>
<h1 id="a-warning">A warning</h1>
<p>As of 2026-03-11, this is a "Hey this is neat" post and not a "this works really well!"
one. I found the process of building and testing this really fun, but I've also been
using this approach for basically no time at all and I'm sure a bunch of the things I'm
trying here are just going to straight up not work the way I want in the long run. I'll
be iterating on it a lot. The bot-wiki is meant to be kept up to date and that + the
code are probably the right places to check (or just ask me) how things are working
later on in time.</p>
<h1 id="why-an-org-chart-for-ai-agents">Why an org chart for AI agents</h1>
<p>Because it's cool, mostly. Also I hope it will work really well. But mostly, it's cool.</p>
<p>I've defined a team of Claude Code agents that each have a named
role, themed around being a virtual agent company. Any of them
work fine on their own:</p>
<pre><code class="language-bash">claude --agent cmo -p "What are my top 5 posts by pageviews?"
</code></pre>
<p>The benefit is persistent context. Each agent definition carries
its goal, tools, rules, and domain knowledge. I don't re-explain
what the CMO does every time I invoke it. The definition is the
context.</p>
<p>The challenge is coordination. When a request spans multiple
agents, someone has to decide which agents to call, in what
order, and how to stitch the results together. That's robot
work, not a good use of human time. I also don't want to be
the medium for shared context, copying output from one agent
into another's prompt.</p>
<p>I repurposed my OpenClaw agent
<a href="/openclaw-linear-skill.html">Pai</a> into an orchestrator. Pai
decomposes multi-agent requests and invokes the right agents
in sequence. The C-suite agents (CMO, CFO, CTO, CDO, CSO) each
own a domain and can sub-orchestrate their own subagents. The
CMO delegates to SEO, the CFO delegates to Cost Tracker, and
so on. The top-level/C-Suite agents also work as antagonistic loop orchestrators of
their own, I like to think of it as them enforcing high standards.</p>
<h1 id="the-agents">The agents</h1>
<table>
<thead>
<tr>
<th>Agent</th>
<th>Role</th>
<th>Model</th>
<th>Key Tools</th>
</tr>
</thead>
<tbody>
<tr>
<td>Pai</td>
<td>Orchestration</td>
<td>Sonnet</td>
<td>Bash, Linear MCP</td>
</tr>
<tr>
<td>CMO</td>
<td>Traffic and growth</td>
<td>Sonnet</td>
<td>GA4 Analytics MCP</td>
</tr>
<tr>
<td>CFO</td>
<td>AI spend</td>
<td>Sonnet</td>
<td><a href="/openrouter-ai-tools.html">OpenRouter MCP</a></td>
</tr>
<tr>
<td>CTO</td>
<td>Delivery, blockers</td>
<td>Sonnet</td>
<td>Linear MCP, Bash</td>
</tr>
<tr>
<td>CDO</td>
<td>Knowledge management</td>
<td>Sonnet</td>
<td>Wiki read/write, Bash</td>
</tr>
<tr>
<td>CSO</td>
<td>Security and privacy</td>
<td>Sonnet</td>
<td>File tools, Bash</td>
</tr>
<tr>
<td>AR</td>
<td>Agent onboarding, mediation</td>
<td>Sonnet</td>
<td>File tools, Bash</td>
</tr>
<tr>
<td>Publisher</td>
<td>Blog content pipeline</td>
<td>Sonnet</td>
<td>Bash, file tools</td>
</tr>
<tr>
<td>SEO</td>
<td>Search audits</td>
<td>Sonnet</td>
<td>GA4, WebSearch</td>
</tr>
<tr>
<td>Cost Tracker</td>
<td>Spend reports</td>
<td>Haiku</td>
<td>OpenRouter MCP</td>
</tr>
<tr>
<td>Librarian</td>
<td>Wiki read/write</td>
<td>Haiku</td>
<td>Wiki file tools</td>
</tr>
<tr>
<td>Privacy Auditor</td>
<td>Flag confidential data</td>
<td>Haiku</td>
<td>File tools</td>
</tr>
<tr>
<td>Researcher</td>
<td>Gather sourced facts</td>
<td>Sonnet</td>
<td>WebSearch, Read</td>
</tr>
<tr>
<td>Writer</td>
<td>Draft posts from briefs</td>
<td>Sonnet</td>
<td>Read, Write</td>
</tr>
<tr>
<td>Fact Checker</td>
<td>Verify claims</td>
<td>Haiku</td>
<td>WebSearch, Read</td>
</tr>
<tr>
<td>Reviewer</td>
<td>Style and structure</td>
<td>Haiku</td>
<td>Read, Grep</td>
</tr>
<tr>
<td>QA</td>
<td>Production readiness</td>
<td>Sonnet</td>
<td>Bash, Playwright</td>
</tr>
</tbody>
</table>
<p>Each C-suite agent owns a domain and has subagents for
specialized work. SEO reports to the CMO. Cost Tracker
reports to the CFO. The Librarian reports to the CDO. The
Privacy Auditor reports to the CSO. AR (Agent Resources,
the HR department) handles agent onboarding and role boundary
mediation.</p>
<p>The Publisher is its own sub-org with a four-stage content
pipeline: researcher, writer, fact-checker, and reviewer.
QA runs after the pipeline to verify the post actually
builds, renders, and links correctly before it goes live.
QA uses <a href="/playwright-mcp.html">Playwright MCP</a> to take screenshots
and inspect the rendered page.</p>
<p>Every agent connects to real
<a href="https://modelcontextprotocol.io/">MCP</a> servers. No mocks. The
CMO queries real GA4 data. The CFO pulls real OpenRouter bills.</p>
<h1 id="the-org-chart">The org chart</h1>
<p>This is accurate as of 2026-03-12. The
<a href="/wiki/projects/agent-team/org-chart.html">bot-wiki org chart</a>
stays up to date as agents are added or reorganized.</p>
<pre class="mermaid">
graph TD
    Kyle["Kyle"]
    Pai["Pai — Executive Assistant"]
    CMO["CMO — Grow Readership"]
    CFO["CFO — Optimize Spend"]
    CTO["CTO — Delivery"]
    CDO["CDO — Knowledge"]
    CSO["CSO — Security"]
    AR["AR — Agent Resources"]
    Publisher["Publisher — Content Pipeline"]

    SEO["SEO Subagent"]
    CostTracker["Cost Tracker"]
    Librarian["Librarian"]
    PrivacyAuditor["Privacy Auditor"]

    Researcher["Researcher"]
    Writer["Writer"]
    FactChecker["Fact Checker"]
    Reviewer["Reviewer"]
    QA["QA"]

    Kyle --> Pai
    Kyle --> CMO
    Kyle --> CFO
    Kyle --> CTO
    Kyle --> CDO
    Kyle --> CSO
    Kyle --> AR
    Kyle --> Publisher

    Pai -.->|orchestrates| CMO
    Pai -.->|orchestrates| CFO
    Pai -.->|orchestrates| CTO
    Pai -.->|orchestrates| CDO
    Pai -.->|orchestrates| CSO
    Pai -.->|orchestrates| AR
    Pai -.->|orchestrates| Publisher

    CMO --> SEO
    CFO --> CostTracker
    CDO --> Librarian
    CSO --> PrivacyAuditor

    CMO -.->|reads/writes| Librarian
    CFO -.->|reads/writes| Librarian
    CTO -.->|reads/writes| Librarian

    Publisher --> Researcher
    Publisher --> Writer
    Publisher --> FactChecker
    Publisher --> Reviewer
    Publisher --> QA
</pre>
<p>It being my blog and virtual team, I get to sit at the top. Every agent is directly
invocable by me, but ideally I don't need to do that often.</p>
<p>Solid lines mean "reports to." Dashed lines from Pai mean
"orchestrates." Dashed lines to the Librarian mean "can
read/write wiki through."</p>
<p>The Privacy Auditor is the gatekeeper. Any agent writing
content that will end up in git or on the internet should
check with the Privacy Auditor first. It scans for leaked
analytics data, spend numbers, secrets, and anything else
that shouldn't be public. This came from a scare where one of my agents with access
to mildly confidential data referenced it in content that
would have been public. I feel strongly that all agent flows
need a privacy step at minimum, and ideally agents should
have purposefully curtailed access to sensitive data.</p>
<p>Pai is structured as a peer to the other top-level agents, and orchestrator. I can
still run <code>claude --agent cmo</code> whenever I want. Pai is for when a request spans
multiple agents and I don't want to do the routing myself.</p>
<p>The Librarian is an experiment in context management and
shared state. Any agent can talk to it directly to persist
notes, plans, or evidence to the wiki. I already built a
<a href="/wiki-rag.html">RAG system</a> over the wiki. Once the wiki
gets big enough that agents can't skim it all, I'll have
them query the RAG index instead. For now, the agents just
use git and local file storage for wiki access. The CDO
owns the wiki strategy, but the Librarian does the actual
reading and writing.</p>
<h1 id="pai-the-executive-assistant">Pai: the executive assistant</h1>
<p>Agent definitions live in <code>.claude/agents/</code>. Here's Pai's
frontmatter:</p>
<pre><code class="language-yaml"># .claude/agents/pai.md
name: pai
description: >-
  Pai — Executive assistant that orchestrates
  multi-agent workflows
model: sonnet
tools:
  - Bash
  - Read
  - Glob
  - Grep
  - Write
  - mcp__linear-server__list_issues
  - mcp__linear-server__list_projects
</code></pre>
<p>The body of the definition has four key sections.</p>
<h2 id="agent-invocation-via-bash">Agent invocation via Bash</h2>
<p>Pai invokes other agents with
<code>claude --agent &#x3C;name> -p "prompt"</code> through the Bash tool.
Each call is a fresh session. Agents don't share memory or
context with each other.</p>
<p>This is the main tradeoff. Fresh sessions mean no shared
state, but Pai bridges the gap by reading output from one
agent and passing relevant parts into the next agent's prompt.</p>
<p>The alternatives I considered:</p>
<ul>
<li><strong>Shared memory / message bus.</strong> Tools like LangGraph or
CrewAI give agents shared state. More powerful, but more
moving parts. I wanted something I could debug by reading
a bash script.</li>
<li><strong>Single mega-agent.</strong> One agent definition with all the
tools. Simpler, but the context window fills up fast and
the agent loses focus. Splitting by role keeps each
session lean.</li>
<li><strong>MCP-based orchestration.</strong> Route through an MCP server
that manages agent sessions. Interesting, but overkill
for a blog. I'd rather build on <code>claude --agent</code> which
already works.</li>
<li><strong><a href="https://github.com/steveyegge/beads">Beads</a>.</strong> A
structured task memory for AI agents, backed by Dolt
(version-controlled SQL). I looked into it, but it's
more of an alternative to Linear than to the wiki. It
solves task tracking and agent handoff, not knowledge
management. I like Linear for tasks and markdown files
for knowledge.</li>
</ul>
<p>I went with the dumb approach: Bash calls and text passing.
It's easy to understand, easy to debug, and the wiki handles
long-term memory. If I outgrow it, I'll upgrade.</p>
<h2 id="dry-run-mode">Dry-run mode</h2>
<p>Add <code>--dry-run</code> to your message and Pai outputs the
orchestration plan without executing anything. Which agents,
what prompts, what order, how it would synthesize.</p>
<p>Useful for checking that Pai will do what you want before it
burns tokens on three agent calls.</p>
<h2 id="adversarial-loops">Adversarial loops</h2>
<p>For requests that need critique or review between agents:</p>
<ol>
<li>Agent A produces output</li>
<li>Agent B critiques it</li>
<li>Agent A revises based on feedback</li>
<li>Up to 3 rounds or until the reviewer approves</li>
</ol>
<p>CMO proposes blog topics, CTO reviews technical feasibility,
CMO revises. The back-and-forth produces better output than
either agent alone.</p>
<h2 id="logging">Logging</h2>
<p>Every orchestration run appends a timestamped entry to
<code>pai-log-YYYY-MM-DD.md</code>. Agent name, prompt summary, result
status, and a one-line synthesis.</p>
<h1 id="the-wiki-layer">The wiki layer</h1>
<p>Each agent has a page in the
<a href="/bot-wiki.html">Bot-Wiki</a> that documents its goal, tools,
subagents, and example prompts.</p>
<pre><code class="language-text">agent-team/
├── index.md          # org chart and coordination model
├── pai.md            # orchestration agent
├── cmo.md            # traffic and growth
├── cfo.md            # AI spend
├── cto.md            # delivery and blockers
├── cdo.md            # knowledge management
├── cso.md            # security and privacy
├── publisher.md      # blog pipeline
└── phase-2.md        # future async architecture
</code></pre>
<p>The wiki is the shared memory layer.</p>
<p>Every agent session is stateless. The CMO doesn't remember
what the CTO said last week. But if the CTO writes its
findings to the wiki through the Librarian, the CMO can
read them next time it runs. The wiki is how agents share
context across sessions.</p>
<p>The Librarian (a Haiku subagent under the CDO) handles
all wiki read/write operations. Any agent can invoke it
directly with <code>claude --agent librarian -p "..."</code> to
persist notes, plans, evidence, or whatever else needs to
survive between sessions. The CDO owns the strategy:
what gets documented, how pages are structured, when
content is stale.</p>
<p>This is cheaper than giving every agent write access to
the full file system. The Librarian runs on Haiku, knows
the wiki format, and won't accidentally clobber unrelated
files.</p>
<p>In time I may have the CFO tweak the models the agents use to manage costs, too.</p>
<h1 id="pai-in-action">Pai in action</h1>
<h2 id="the-dry-run">The dry-run</h2>
<p>I asked Pai for a quarterly health check with <code>--dry-run</code>:</p>
<pre><code class="language-bash">claude --agent pai -p "Give me a quarterly health check. \
  How's traffic trending, what am I spending on AI, and \
  are there any blocked issues? --dry-run"
</code></pre>
<p>Pai planned three parallel agent calls:</p>
<blockquote>
<p><strong>Agent 1, CMO:</strong> Pull a quarterly traffic report for
kyle.pericak.com. Total sessions and users for the quarter
vs prior quarter, top 5 posts by pageviews, traffic channel
breakdown.</p>
<p><strong>Agent 2, CFO:</strong> Pull OpenRouter AI spend for Q1 2026.
Break it down by model and by month. Flag any month-over-month
spikes > 20%.</p>
<p><strong>Agent 3, CTO:</strong> Review all open Linear issues and flag any
that are blocked, stalled (no update in 14+ days), or missing
an assignee.</p>
</blockquote>
<p>It also laid out the synthesis plan: group results by theme
(traffic, spend, delivery), cross-reference findings, and
call out any cross-domain issues.</p>
<p>No agents ran. No tokens burned. I could review the plan and
adjust before committing.</p>
<h2 id="the-real-run">The real run</h2>
<p>Same request without <code>--dry-run</code>. Pai invoked three agents
and synthesized everything into one report.</p>
<p><strong>Traffic</strong> (from CMO): GA4 only had a week of data. The
site is new enough that there's no meaningful baseline yet.
Almost entirely direct traffic, organic search barely
registering. CMO recommended connecting Search Console and
revisiting in 30 days.</p>
<p><strong>AI spend</strong> (from CFO): well under budget with no pressure.
OpenRouter's API only surfaced account-level totals, no
per-model breakdown. CFO noted the biggest future lever is
routing non-reasoning tasks to flash-tier models.</p>
<p><strong>Delivery</strong> (from CTO): most issues done or in backlog,
one in progress (this blog post). No hard blockers, but
three dependency chains worth watching:</p>
<ol>
<li>RSS feed is high priority but hasn't started. Four
distribution issues are gated on it.</li>
<li>CMO and CFO baseline runs haven't started. They gate
two future blog posts.</li>
<li>This post has an open PR to close.</li>
</ol>
<p>Pai wrote a log entry automatically:</p>
<pre><code class="language-markdown">## 21:30 — Quarterly health check

| Agent | Prompt Summary | Result |
|-------|---------------|--------|
| cmo | 90-day traffic trend | success |
| cfo | 90-day AI spend | success |
| cto | Blocked/stalled issues | success: 3 clusters |

**Synthesis:** Early launch phase, minimal spend,
no hard blockers but three dependency chains.
</code></pre>
<h2 id="the-adversarial-demo">The adversarial demo</h2>
<p>I asked Pai to have the CMO propose blog topics and the CTO
review feasibility:</p>
<pre><code class="language-bash">claude --agent pai -p "The CMO wants to propose 3 new \
  blog topics. Have CTO review feasibility."
</code></pre>
<p>CMO proposed three posts:</p>
<ol>
<li><strong>Give Your Agents a Memory</strong> - wire agents to read/write
wiki context on startup</li>
<li><strong>Agents That Run Themselves</strong> - scheduled execution with
cron and cost guardrails</li>
<li><strong>Teach Your CTO Agent to Review PRs</strong> - GitHub Actions
workflow that fires the CTO agent on every PR</li>
</ol>
<p>CTO reviewed each one:</p>
<ul>
<li>Post 6 (wiki memory): needs groundwork. Wiki is read-only
from agents today. A write protocol means git commits from
within agent sessions.</li>
<li>Post 7 (scheduling): blocked. Phase 2 prerequisites from
the wiki aren't met. PER-37 and PER-38 haven't started.</li>
<li>Post 8 (PR review): needs groundwork. Most self-contained,
but <code>.github/workflows/</code> doesn't exist yet.</li>
</ul>
<p>CTO's recommended ship order: complete PER-37 and PER-38
first, then post 6, then post 8, then post 7 last (after
the others prove stability).</p>
<p>The interesting thing here is the cross-referencing. The CTO
pulled the same PER-37/PER-38 dependency from the health
check. It flagged the same blocker from two different angles
without being told about the first run.</p>
<h1 id="watching-them-work">Watching them work</h1>
<p>I got bored waiting for the agents to finish doing their thing so I made them all
post status updates to a local file. I <code>tail -f</code> the file and watch them work. It's
neat. Eventually I think I might plug them into some chat app or something instead so
it looks more like people talking to each other. I think
that'd be fun.</p>


<p>I added a new top-level section to this site: the
<a href="/wiki.html">Bot-Wiki</a>.</p>
<p>It looks like a wiki. It reads like a wiki. But it's not really for
humans. It's a structured knowledge base designed for AI agents and
RAG pipelines to consume.</p>
<h2 id="why-a-wiki-when-i-already-have-a-blog">Why a wiki when I already have a blog?</h2>
<p>Blog posts are stories. They have a narrative arc, opinions, tangents.
They're written for people who want to understand how I got from point
A to point B. That's great for learning from my experience but
terrible for a robot trying to answer "what MCP servers does this
project use?"</p>
<p>The wiki is the opposite. Each page is a factual reference card.
Structured metadata, explicit scope declarations, keyword lists for
embedding search, and cross-references for graph traversal. The tone
is robots writing notes for other robots.</p>
<h2 id="whats-in-it">What's in it</h2>
<p>The wiki covers the same ground as my recent blog posts but organized
by topic rather than chronology:</p>
<ul>
<li><strong>AI Tools</strong>: Claude Code, OpenCode, OpenRouter, local LLMs, image gen</li>
<li><strong>MCP Integrations</strong>: Playwright, Linear, GA4</li>
<li><strong>OpenClaw</strong>: the agent, its skills, Kubernetes security</li>
<li><strong>DevOps</strong>: security toolkit, lint toolkit, Ruler</li>
<li><strong>Blog Architecture</strong>: how this site is built, the markdown pipeline,
testing setup</li>
</ul>
<p>Each page has frontmatter designed for machine consumption:</p>
<pre><code class="language-yaml">title: "Claude Code"
summary: "CLI AI coding assistant by Anthropic with MCP support"
keywords:
  - claude-code
  - anthropic
  - mcp
related:
  - wiki/ai-tools/opencode
  - playwright-mcp
scope: "Setup, config, MCP integration, and usage patterns"
last_verified: 2026-03-10
</code></pre>
<p>The <code>summary</code> and <code>scope</code> fields help a RAG system decide whether to
retrieve the full page. The <code>keywords</code> list feeds embedding search.
The <code>related</code> links let an agent traverse the knowledge graph.
<code>last_verified</code> tells the agent how stale the content might be.</p>
<h2 id="how-this-connects-to-rag">How this connects to RAG</h2>
<p>This is step one of a larger plan. Next I'm building a RAG pipeline
that indexes the wiki content, generates embeddings, and lets agents
query it during conversations. The wiki's structured metadata makes
chunking and retrieval much cleaner than trying to RAG over blog
posts directly.</p>
<p>The directory structure maps to the URL structure which maps to the
knowledge hierarchy. An agent asking about MCP servers gets pointed
to <code>wiki/mcp/</code> and its children, not to a 2000-word blog post that
mentions MCP in passing.</p>
<h2 id="how-its-built">How it's built</h2>
<p>The wiki reuses the blog's existing infrastructure. A new <code>WikiService</code>
reads markdown from <code>markdown/wiki/</code> instead of <code>markdown/posts/</code>,
builds a tree from the directory structure, and generates navigation
automatically. Each <code>index.md</code> file gets a tree of its children
rendered above its own content.</p>
<p>The routing plugs into the same Next.js catch-all that handles blog
posts. Wiki pages get the same layout, sidebar, and responsive
behavior. They just have different content and metadata.</p>
<p>No images in the wiki. It's all text, all the time. Robots don't
need hero images.</p>
<p>You can find it at <a href="/wiki.html">/wiki.html</a>, or use the new Wiki
link in the header.</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>


<h2 id="table-of-contents">Table of contents</h2>
<ul>
<li><a href="#why-i-dont-trust-the-skill-marketplace">Why I don't trust the skill marketplace</a></li>
<li><a href="#how-openclaw-skills-work">How OpenClaw skills work</a></li>
<li><a href="#the-skill">The skill</a></li>
<li><a href="#one-ai-writing-tools-for-another">One AI writing tools for another</a></li>
<li><a href="#loading-it-into-k8s">Loading it into K8s</a>
<ul>
<li><a href="#injecting-the-api-key">Injecting the API key</a></li>
<li><a href="#mounting-the-skill">Mounting the skill</a></li>
<li><a href="#the-jq-problem">The jq problem</a></li>
<li><a href="#stale-sessions">Stale sessions</a></li>
</ul>
</li>
<li><a href="#talking-to-pai-pericak-ai">Talking to Pai (Pericak AI)</a></li>
</ul>
<h1 id="why-i-dont-trust-the-skill-marketplace">Why I don't trust the skill marketplace</h1>
<p>In the <a href="/openclaw-k8s.html">K8s post</a> I mentioned wanting
to connect OpenClaw to Linear for issue tracking. The
obvious path is ClawHub, OpenClaw's public skill
marketplace. Install a community skill, set your API key,
done. I didn't do that.</p>
<p>In February 2026, a campaign called
<a href="https://cybersecuritynews.com/clawhavoc-poisoned-openclaws-clawhub/">ClawHavoc</a>
compromised ClawHub. Researchers at Trend Micro and Antiy
documented over 1,184 malicious skills that had been
published to the registry. The skills looked legitimate,
had normal names and descriptions, and passed ClawHub's
automated checks. They distributed
<a href="https://www.trendmicro.com/en_us/research/26/b/openclaw-skills-used-to-distribute-atomic-macos-stealer.html">Atomic macOS Stealer</a>,
a credential harvester targeting Keychain, browser
passwords, and crypto wallets.</p>
<p>The publishing bar was low. A one-week-old GitHub account
was enough to push a skill to ClawHub. No code review, no
signing, no sandbox. Once installed, a skill runs inside
the agent process with access to every environment variable
the agent has. That includes API keys, tokens, and anything
else injected via Vault or config.</p>
<p>This is the same pattern that hit npm, PyPI, and VS Code
extensions. A package registry with low friction publishing
and high-privilege execution is a target. ClawHub is no
different.</p>
<p>My approach: write the skill myself, keep it in my repo,
and audit every line. The Linear skill I need is about 150
lines of markdown. That's a small surface to own compared
to trusting a stranger's code with my credentials.</p>
<h1 id="how-openclaw-skills-work">How OpenClaw skills work</h1>
<p>An OpenClaw skill is a directory with a <code>SKILL.md</code> file.
The file has YAML frontmatter (name, description, required
tools and environment variables) and a markdown body with
instructions the agent follows.</p>
<p>There's no compiled code. No dependencies to install. No
background process. The agent reads the markdown, learns
what commands are available, and executes them via bash
when you ask it to. If you want to audit a skill, you read
one file.</p>
<p>Compare this to MCP servers, which are running processes
that the agent connects to over a transport protocol. MCP
servers can do more (stateful connections, streaming), but
they're also harder to audit and have a larger attack
surface. For something like "list my Linear issues," a
static document with curl commands is plenty.</p>
<p>The frontmatter declares what the skill needs:</p>
<pre><code class="language-yaml">---
name: linear
description: Manage Linear issues, projects,
  and comments via the Linear GraphQL API.
metadata: {"openclaw": {"emoji": "📐",
  "requires": {"bins": ["curl"],
  "env": ["LINEAR_API_KEY"]}}}
---
</code></pre>
<p>OpenClaw checks these requirements at load time. If <code>curl</code>
isn't on PATH, or <code>LINEAR_API_KEY</code> isn't set, the skill
doesn't load. No runtime errors, no mysterious failures.</p>
<h1 id="the-skill">The skill</h1>
<p>I had Claude write a Linear skill covering the operations
I actually use: listing issues, creating and updating them,
managing labels, and adding comments. The full skill lives
at <code>apps/openclaw-skills/linear/SKILL.md</code> in my monorepo.</p>
<p>Linear's API is GraphQL-only. No REST endpoints. Every
request is a POST to <code>https://api.linear.app/graphql</code> with
a JSON body containing the query. The skill uses <code>curl</code>
for HTTP. One API key, no OAuth dance.</p>
<p>The auth header is <code>Authorization: $LINEAR_API_KEY</code>.
Linear personal API keys don't use a <code>Bearer</code> prefix.</p>
<p>Here's what listing issues looks like:</p>
<pre><code class="language-bash">curl -s -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  -d '{"query": "{ issues(filter: { team: \
    { key: { eq: \"PER\" } } }, first: 25) \
    { nodes { id identifier title \
    state { name } } } }"}'
</code></pre>
<p>And creating an issue:</p>
<pre><code class="language-bash">curl -s -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  -d '{"query": "mutation { issueCreate(input: \
    { teamId: \"TEAM_UUID\", \
    title: \"Issue title\", \
    description: \"Issue description\" }) \
    { success issue { id identifier url } } }"}'
</code></pre>
<p>The skill also covers workflow statuses. Changing an
issue's status in Linear means looking up the target
state's UUID first, then passing it to <code>issueUpdate</code>. The
agent chains these naturally: list statuses, find the one
named "Todo", grab its ID, update the issue.</p>
<p>This matches the workflow I described in the
<a href="/linear-mcp.html">Linear MCP post</a>. Nightly agents create
Suggestion issues in Backlog, I promote the good ones to
Todo, working agents pick them up. The skill gives OpenClaw
the same Linear access that Claude Code gets through its
MCP server.</p>
<p>The full skill is about 150 lines of markdown. Ten
operations with copy-paste curl commands and a few compound
examples at the end. I read every line.</p>
<h1 id="one-ai-writing-tools-for-another">One AI writing tools for another</h1>
<p>Claude Code (Opus 4.6) wrote this skill. It read the
Trello skill as a pattern, checked the Linear GraphQL API
docs, and produced a skill that follows the same structure.
One AI building capabilities for another AI.</p>
<p>I described what I wanted at a high level, and Claude
handled the GraphQL query syntax, the jq filters, and the
escape sequences. I reviewed the output. The whole thing
took one conversation.</p>
<p>The skill lives in my monorepo under version control. If
Linear changes their API or I need a new operation, I
update one file.</p>
<h1 id="loading-it-into-k8s">Loading it into K8s</h1>
<p>Getting the skill into the running OpenClaw pod took more
work than writing it. The skill file needs to end up in
the right directory inside the container, the API key
needs to be injected, and OpenClaw needs to discover it.</p>
<h2 id="injecting-the-api-key">Injecting the API key</h2>
<p>I added the Linear API key to Vault alongside the existing
Gemini and Telegram secrets, then updated the Vault Agent
template to export it:</p>
<pre><code class="language-text">{{- with secret "secret/openclaw" -}}
export GEMINI_API_KEY="{{ .Data.data.gemini_api_key }}"
export TELEGRAM_BOT_TOKEN="..."
{{ if .Data.data.linear_api_key }}
export LINEAR_API_KEY="{{ .Data.data.linear_api_key }}"
{{ end }}
{{- end }}
</code></pre>
<h2 id="mounting-the-skill">Mounting the skill</h2>
<p>I stored the SKILL.md in a ConfigMap and mounted it into
the init container. ConfigMap mounts use symlinks
internally, and OpenClaw's skill loader rejects symlinked
paths as a security measure. So the init container copies
the file onto the PVC as a regular file:</p>
<pre><code class="language-yaml">initContainers:
  - name: config-seed
    command: ["sh", "-c"]
    args:
      - |
        # ... existing config seed logic ...
        # Copy skills onto PVC workspace
        mkdir -p /data/workspace/skills/linear
        cp /skill-src/linear/SKILL.md \
          /data/workspace/skills/linear/SKILL.md
    volumeMounts:
      - name: linear-skill
        mountPath: /skill-src/linear
        readOnly: true
</code></pre>
<p>The key detail: skills must live under the workspace
directory (<code>&#x3C;workspace>/skills/</code>), not just anywhere on
the filesystem. OpenClaw's skill discovery only scans
three locations: bundled, managed (<code>~/.openclaw/skills</code>),
and workspace. I initially tried <code>extraDirs</code> and the
managed path. Neither worked until I put it in the
workspace.</p>
<h2 id="the-jq-problem">The jq problem</h2>
<p>The original skill required both <code>curl</code> and <code>jq</code> in its
<code>requires.bins</code> frontmatter. The OpenClaw container has
<code>curl</code> but not <code>jq</code>. The skill gating check runs at
startup: missing binary means the skill silently doesn't
load. Claude dropped <code>jq</code> from the requirements. The agent
is smart enough to parse JSON responses on its own using
the <code>node</code> binary that's already in the container.</p>
<h2 id="stale-sessions">Stale sessions</h2>
<p>After all that, I asked Pai what skills it had. Still
three. OpenClaw snapshots eligible skills when a session
starts and reuses that list for the session's lifetime.
The <code>openclaw agent --message</code> CLI command was reusing an
existing session from before the skill was loaded.
Clearing the sessions directory forced a fresh snapshot:</p>
<pre><code class="language-bash">rm -rf /home/node/.openclaw/agents/main/sessions/*
</code></pre>
<p>After that, the skill appeared.</p>
<h1 id="talking-to-pai-pericak-ai">Talking to Pai (Pericak AI)</h1>
<p>With the skill loaded, Claude Code talked to Pai (the
OpenClaw agent running Gemini 2.5 Flash) through
<code>kubectl exec</code>, using the same pattern from the
<a href="/openclaw-k8s.html">K8s post</a>.</p>
<pre><code class="language-text">Claude: List my Linear teams using the linear skill.
Pai: Your Linear teams are:
  - Pericak (Key: PER)

Claude: List my Linear issues for team PER.
Pai: Here are the Linear issues for team PER:
  - PER-10: ... (State: Backlog)
  - PER-9: ... (State: Todo)
  - PER-8: ... (State: Todo)
  - PER-7: ... (State: Todo)
  - PER-6: ... (State: Todo)
  - PER-5: ... (State: Todo)
  ...
</code></pre>
<p>That's real output (titles redacted). Pai read the
skill's curl commands, called the Linear GraphQL API
with the Vault-injected API key, and returned my actual
issues. The full chain: Claude Code runs <code>kubectl exec</code>,
which calls the <code>openclaw agent</code> CLI, which sends the
message to Gemini 2.5 Flash, which reads the skill, runs
curl against Linear's API, and returns the result.</p>
<p>Two AIs, two different models, coordinating through a
Kubernetes pod with Vault-injected secrets and a
hand-written skill file. The whole thing is auditable
from end to end.</p>


<h1 id="what-openclaw-is">What OpenClaw is</h1>
<p><a href="https://openclaw.ai/">OpenClaw</a> is wildly popular and kind of confusing. From what I
can tell before starting, other than being a first-class security concern, it's meant
to be a tool that lets you connect to your ai agents over chat tools like WhatsApp.</p>
<p>It runs locally, you bring your own API key (Anthropic, OpenAI,
DeepSeek), and your data stays on your machine (until you screw up). The gateway
connects to messaging platforms like Telegram, Signal, WhatsApp,
Discord, and apparently about 20 others.</p>
<h1 id="install-on-macos">Install on macOS</h1>
<p>Prerequisites: Node.js 22+ and an API key for your chosen
model provider (more on that next).</p>
<p>The recommended install uses their script:</p>
<pre><code class="language-bash">curl -fsSL https://openclaw.ai/install.sh | bash
</code></pre>
<p>That handles Node detection and installs the <code>openclaw</code> CLI.
If you want to skip the wizard and install the binary only:</p>
<pre><code class="language-bash">curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
</code></pre>
<p>Then run the onboarding wizard separately:</p>
<pre><code class="language-bash">openclaw onboard
</code></pre>
<p>The wizard walks through gateway setup, workspace directory,
and API key config. Everything lives in <code>~/.openclaw/</code>.</p>
<h1 id="picking-a-model">Picking a model</h1>
<p>The onboard wizard asks which model to use. OpenClaw supports
a long list of providers, but here are the ones that matter
for a personal assistant:</p>
<table>
<thead>
<tr>
<th>Model</th>
<th>Input / Output (per 1M tokens)</th>
<th>Good for</th>
</tr>
</thead>
<tbody>
<tr>
<td>Claude Haiku 4.5</td>
<td>$1 / $5</td>
<td>Cheap daily driver</td>
</tr>
<tr>
<td>Claude Sonnet 4.6</td>
<td>$3 / $15</td>
<td>Solid middle ground</td>
</tr>
<tr>
<td>Claude Opus 4.6</td>
<td>$5 / $25</td>
<td>Best reasoning</td>
</tr>
<tr>
<td>GPT-5</td>
<td>$1.25 / $10</td>
<td>Strong alternative</td>
</tr>
<tr>
<td>GPT-4o Mini</td>
<td>$0.15 / $0.60</td>
<td>Budget OpenAI</td>
</tr>
<tr>
<td>Gemini 2.5 Flash</td>
<td>Free (250 req/day) / ~$0.30 paid</td>
<td>Free option</td>
</tr>
<tr>
<td>Gemini 3 Pro</td>
<td>$2 / $12</td>
<td>Strong reasoning</td>
</tr>
<tr>
<td>DeepSeek (via Ollama)</td>
<td>Free (local)</td>
<td>Fully offline</td>
</tr>
</tbody>
</table>
<h2 id="can-you-use-your-20month-subscription">Can you use your $20/month subscription?</h2>
<p><strong>ChatGPT Plus/Pro:</strong> No. The subscription doesn't include API
access. You need a separate OpenAI API key with pay-as-you-go
billing.</p>
<p><strong>Claude Pro ($20/mo):</strong> Not anymore. Early on, people found a
workaround using OAuth tokens from the Claude Code CLI.
Anthropic shut that down in January 2026. You need a separate
Anthropic API key.</p>
<p><strong>Claude Max ($200/mo) and Claude Code subscription:</strong> Same
story. The setup-token auth path existed briefly but Anthropic
scoped the tokens so they only work with the official Claude
Code client.</p>
<h2 id="trying-geminis-model">Trying Gemini's model</h2>
<p>Apparently Google's Gemini API has a free tier, I tried it out. Gemini 2.5 Flash gets
250 requests/day free. For texting a bot a few times a day to manage issues, that's ok.</p>
<p>Annoyingly there are a bunch of 2.5 options. No idea if they all have free tiers.</p>
<p>I initially picked <code>google/gemini-2.5-flash-preview-09-2025</code> during the wizard and
gave it my api key using the <code>Paste API key now</code> option. Sadly that had an error</p>
<pre><code class="language-test">models/gemini-2.5-flash-preview-09-2025 is not found for API version v1beta,
</code></pre>
<p>Fixing it was a pain in the ass, their <code>/model</code> and <code>/models</code> tools TUI setup was jank
af and just didnt work.</p>
<pre><code class="language-bash">/exit
openclaw configure
</code></pre>
<p>I tried to switch the model up to <code>google/gemini-2.5-flash</code>.</p>
<p>Note that this thing stays running in the background</p>
<pre><code class="language-bash">➜  ~ ps aux | grep openclaw
kp               39009   0.1  1.0 444980720 173456   ??  R    11:03AM   0:07.97 openclaw-gateway
</code></pre>
<p>Re-open the TUI with <code>openclaw tui</code> if you end up out of it.</p>
<h2 id="connect-telegram">Connect Telegram</h2>
<p>I paused here to install Telegram on my MacBook. It's pretty easy if you already have
it on your phone, you just scan a QR code.</p>
<p>During the quick start it recommends you use Telegram. I chose to use
<code>Telegram (Bot API)</code>. Then I followed the instructions:</p>
<pre><code class="language-text">◇  Telegram bot token ───────────────────────────────────────────────────────────────────╮
│                                                                                        │
│  1) Open Telegram and chat with @BotFather                                             │
│  2) Run /newbot (or /mybots)                                                           │
│  3) Copy the token (looks like 123456:ABC...)                                          │
│  Tip: you can also set TELEGRAM_BOT_TOKEN in your env.                                 │
│  Docs: https://docs.openclaw.ai/telegram  │
│  Website: https://openclaw.ai                                                          │
│                                                                                        │
├────────────────────────────────────────────────────────────────────────────────────────╯
</code></pre>
<p>The /newbot prompt had me name it. Then I got the key to give OpenClaw.</p>
<h2 id="set-up-search">Set up Search</h2>
<p>I chose to use Gemini since I'm giving it that API key anyways. Plus, Google's gotta be
the best at search, right? It's like, their thing. Suprisingly it asked again for
<code>Gemini (Google Search) API key</code>. I just gave it the same key as before.</p>
<h2 id="sketchy-skills-time">Sketchy Skills Time</h2>
<p>Then I got to here and just proceeed. There was some news about malware in the skills.</p>
<pre><code class="language-text">◇  Skills status ─────────────╮
│                             │
│  Eligible: 8                │
│  Missing requirements: 43   │
│  Unsupported on this OS: 0  │
│  Blocked by allowlist: 0    │
│                             │
├─────────────────────────────╯
</code></pre>
<h2 id="places-api">Places API</h2>
<p>What, why?</p>
<pre><code class="language-text">◆  Set GOOGLE_PLACES_API_KEY for goplaces?
│  ○ Yes / ● No
</code></pre>
<h2 id="gemini-for-nano-banana">Gemini for nano banana</h2>
<p>I mean yeah but I already gave it this key twice, kinda annoying.</p>
<pre><code class="language-text">◆  Set GEMINI_API_KEY for nano-banana-pro?
│  ● Yes / ○ No
</code></pre>
<h2 id="the-other-keys-it-wants">The other keys it wants</h2>
<p>... It wants a lot of keys, just start saying no.</p>
<h2 id="hooks">Hooks</h2>
<p>I don't trust boot-md yet.</p>
<pre><code class="language-text">◆  Enable hooks?
│  ◻ Skip for now
│  ◻ 🚀 boot-md
│  ◼ 📎 bootstrap-extra-files (Inject additional workspace bootstrap files via glob/path patterns)
│  ◼ 📝 command-logger (Log all command events to a centralized audit file)
│  ◼ 💾 session-memory (Save session context to memory when /new or /reset command is issued)
</code></pre>
<h2 id="node-wants-to-find-devices-on-local-networks">Node wants to find devices on local networks</h2>
<p>MacOS popup. Yeah, nah. This is already probably the least secure thing I've ever done
on purpose.</p>
<h2 id="hatch-the-bot">Hatch the bot</h2>
<p>I love a good TUI.</p>
<pre><code class="language-text">◆  How do you want to hatch your bot?
│  ● Hatch in TUI (recommended)
│  ○ Open the Web UI
│  ○ Do this later
</code></pre>
<h1 id="talk-to-the-bot-on-telegram">Talk to the bot on Telegram</h1>
<p>The BotFather sends you a link to your bot account. I clicked it, hit start, and that
sent /start to it. It immediately told me OpenClaw: access not configured. Love it.
I copied its whole message and just dumped it into the TUI for OC to sort it out.</p>
<p>Aand, it's that error again:</p>
<pre><code class="language-text">LLM error: {
"error": {
"code": 404,
"message": "models/gemini-2.5-flash-preview-09-2025 is not found for API version v1beta, or is not supported for generateContent. Call ListModels to see the list of available models and their supported methods.",
"status": "NOT_FOUND"
}
}
</code></pre>
<p>Turns out changing the model doesn't stick unless you restart the gateway.
Entertainingly I asked it to restart the gateway in the TUI. It killed the gateway and
then immediately went unresponsive, not having a gateway to work with.</p>
<p>Restarting it... <code>openclaw gateway</code>: Conveniently that opens it in the foreground, it
looks great in tmux.</p>
<h2 id="set-up-the-tone-and-such">Set up the tone and such</h2>
<p>When the messaging finally works on Telegram it'll ask you for an identity and tone.
It's kind of fun.</p>
<h1 id="shutdown-procedure">Shutdown Procedure</h1>
<p>Don't wanna leave this thing running until it's secured.</p>
<pre><code class="language-bash"># Stop the gateway
openclaw gateway stop

# Verify nothing is still running
ps aux | grep openclaw
pkill -f openclaw-gateway
</code></pre>
<h1 id="whats-next">What's next</h1>
<p>I wanted to set this up with Linear, but honestly I don't love it runing flat on my
Macbook. I'm gonna <a href="/openclaw-k8s.html">put it in K8s</a> and producitonize this now
that I've got the MVP figured out.</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>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>


<p>I use Cursor and Claude Code, sometimes Codex, and I'm about to try OpenCode.
Each tool has its own rules format, and I've been maintaining them separately.
<a href="https://github.com/intellectronica/ruler">Ruler</a> generates each tool's native
config from a single source. Worth setting up.</p>
<h1 id="tool-agnosticism-with-common-rules">Tool agnosticism with common rules</h1>
<p>I'm trying to keep up. There are too many tools. I don't want to migrate things around.
We're using this at work too, since different devs use different tools. Here's how I
set up Ruler to consolidate my Cursor and Claude rules together.</p>
<p>I had this rule in Cursor:</p>
<pre><code class="language-markdown"># Monorepo rules

This git repo is a monorepo. It contains multiple sub-projects.
Do not look for context or cross-reference calls between sub-projects.
Each directory within apps/ and games/ is a sub-project. They shouldn't
share code.
</code></pre>
<p>Claude Code has CLAUDE.md files scattered through the tree:</p>
<table>
<thead>
<tr>
<th>File</th>
<th>Contents</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>CLAUDE.md</code> (root)</td>
<td>Branching: never commit to main, always PR</td>
</tr>
<tr>
<td><code>apps/games/sillyapp/CLAUDE.md</code></td>
<td>iOS build and test commands, simulator lifecycle</td>
</tr>
<tr>
<td><code>apps/blog/.../posts/CLAUDE.md</code></td>
<td>Blog writing voice, formatting rules, structure</td>
</tr>
<tr>
<td><code>apps/games/kid-bot-battle-sim/features/CLAUDE.md</code></td>
<td>Interface details for that feature set</td>
</tr>
</tbody>
</table>
<h1 id="ruler-setup">Ruler Setup</h1>
<pre><code class="language-bash">npm install -g @intellectronica/ruler
</code></pre>
<p>Initialize at the repo root:</p>
<pre><code class="language-bash">ruler init
</code></pre>
<p>This creates a <code>.ruler/</code> directory and a <code>ruler.toml</code> config. Drop your
instructions as Markdown files inside <code>.ruler/</code>, then:</p>
<pre><code class="language-bash">ruler apply
</code></pre>
<h2 id="what-happens-when-you-run-it">What happens when you run it</h2>
<p>Claude Code gets <code>CLAUDE.md</code>. Everything else (Cursor, OpenCode, Codex,
Copilot, 30+ others) gets <code>AGENTS.md</code>. Generated files go into <code>.gitignore</code>
automatically, so only the <code>.ruler/</code> source is committed.</p>
<p>Ruler supports nested directories. A <code>.ruler/</code> at the repo root applies
globally. A <code>.ruler/</code> inside a sub-project applies when an agent is working
there. That matches how Claude Code already loads CLAUDE.md files walking up
the directory tree.</p>
<pre class="mermaid">
graph TD
    A[".ruler/ at repo root\nbranching, monorepo"] --> B[Claude Code]
    A --> C[Everyone Else\nCursor, OpenCode, Codex...]
    E[".ruler/ in sillyapp/\nbuild, test"] --> B
    E --> C
    F[".ruler/ in posts/\nblog style"] --> B
    F --> C
    B --> G[CLAUDE.md]
    C --> H[AGENTS.md]
</pre>
<p>You can symlink ~/.ruler to your dir too if you want global Claude rules.</p>
<h1 id="note-consider-just-using-agentsmd">Note: Consider just using AGENTS.md</h1>
<p>Most tools read <code>AGENTS.md</code>: Cursor, OpenCode, Codex, <del>others</del>. If all you have is
rules, it's not a bad idea to skip all of this and just use that format. I think it
might win. That doesn't help with Skills, though.</p>
<h2 id="skills">Skills</h2>
<p>Rules are basically just fancy prompt context that are always loaded.
Skills are just fancy prompt context loaded on-demand, maybe with some extra files
sometimes. Different tools implement them in different ways:</p>
<ul>
<li>Claude Code: <code>.claude/skills/</code></li>
<li>Cursor: <code>.cursor/skills/</code></li>
<li>Other tools follow the same pattern under their own config directories</li>
</ul>
<p>Ruler figures it out and distributes them for you. Could this all just be a bash
script? Yes. Does it do a bunch of stuff I don't understand too? Also, probably, yes.</p>
<p>Enabled by default. Pass <code>--no-skills</code> to skip it:</p>
<pre><code class="language-bash">ruler apply           # distributes rules + skills
ruler apply --no-skills  # rules only
</code></pre>
<hr>
<h1 id="consolidating-rules-migration-steps">Consolidating rules: Migration steps</h1>
<p>The <code>ruler.toml</code> at the root lists the agents to target:</p>
<pre><code class="language-toml">default_agents = ["claude", "cursor"]
</code></pre>
<p>Content moves from existing config files into <code>.ruler/</code> source files:</p>
<pre><code>.ruler/
  branching.md        # from root CLAUDE.md
  monorepo.md         # from .cursor/rules/monorepo.md (Claude never saw this)
apps/games/sillyapp/
  .ruler/
    build.md          # from sillyapp/CLAUDE.md
apps/blog/blog/markdown/posts/
  .ruler/
    style.md          # from posts/CLAUDE.md
apps/games/kid-bot-battle-sim/features/
  .ruler/
    interfaces.md     # from features/CLAUDE.md
</code></pre>
<p>Root <code>.ruler/branching.md</code> (was only in Claude Code):</p>
<pre><code class="language-markdown"># Branching

Never commit directly to `main`. Always create a branch and open a PR
against main for review.
</code></pre>
<p>Root <code>.ruler/monorepo.md</code> (was only in Cursor):</p>
<pre><code class="language-markdown"># Monorepo

This repo contains multiple independent sub-projects under `apps/` and
`games/`. Do not cross-reference or import code between sub-projects.
Each directory in those folders is its own isolated project.
</code></pre>
<p>The project-specific files (sillyapp build commands, blog style guide)
move into <code>.ruler/</code> inside their directories unchanged. Content stays the
same, location shifts.</p>
<p>Note: the existing hand-written CLAUDE.md files get replaced by generated
versions after <code>ruler apply</code>. Edit the <code>.ruler/</code> source, not the output.</p>


<p>I'm building a tabletop RPG game that generates images on the fly: character portraits,
enemy illustrations, scene art. Cloud APIs work but get expensive when every combat
encounter wants several images. More importantly, I need character consistency. If I
generate a portrait of "Aria the rogue" in session one, future images of her should
look like the same character, not a random new person.</p>
<p>ComfyUI solves both. It runs locally on Apple Silicon, exposes a REST API, and
supports IP-Adapter for using an existing portrait as a visual reference for new
generations.</p>
<h1 id="hardware-reality">Hardware Reality</h1>
<p>MacBook Air M2, 16GB unified memory. The Air throttles under sustained load since
it has no active cooling. Fine for a game that generates at natural breaks (between
scenes, at combat start) rather than continuously.</p>
<p>16GB comfortably fits:</p>
<ul>
<li><strong>SDXL</strong> (fp16, ~6.5GB): mature IP-Adapter ecosystem, good portrait quality</li>
<li><strong>FLUX.2-klein-4B</strong> (fp8, ~8-9GB): Apache 2.0, released November 2025, 4-step
distilled generation, supersedes FLUX.1-schnell. IP-Adapter support less
mature than SDXL.</li>
<li><strong>FLUX.1-dev</strong> (fp8, ~8GB): previous generation but still the best quality
option that fits 16GB. FLUX.2-dev exists but won't fit.</li>
</ul>
<p>For this post I'm using SDXL. Its IP-Adapter tools are battle-tested for exactly
this use case, and 6.5GB leaves plenty of headroom for additional models.</p>
<h1 id="install-comfyui">Install ComfyUI</h1>
<p>ComfyUI has a <a href="https://github.com/Comfy-Org/desktop">Desktop app</a> that handles
everything automatically. Use that if you just want the UI. For API access and
full control, manual install is cleaner.</p>
<pre><code class="language-bash">git clone https://github.com/comfyanonymous/ComfyUI
cd ComfyUI
python3.13 -m venv venv
source venv/bin/activate
python --version  # must say 3.13 — if it says 3.9 you have an old venv, rm -rf venv and redo
pip install -r requirements.txt
</code></pre>
<p>On Apple Silicon, the requirements file pulls a PyTorch build with MPS support
automatically. No CUDA, no special flags.</p>
<p>Start it:</p>
<pre><code class="language-bash">source venv/bin/activate
python main.py --listen 0.0.0.0 --port 8188
</code></pre>
<p><code>--listen 0.0.0.0</code> binds to all interfaces instead of localhost only. Needed for
the API to be reachable from other processes or devices on your network.</p>
<p>I keep a <code>start-comfyui.sh</code> in <code>~/models/</code> next to the model README so there's
one place for everything model-related:</p>
<pre><code class="language-bash">#!/bin/bash
source /path/to/ComfyUI/venv/bin/activate
cd /path/to/ComfyUI
python main.py --listen 0.0.0.0 --port 8188
</code></pre>
<p>Open <code>http://localhost:8188</code>. You should see the node graph UI with a default
workflow loaded. No models needed for the server to start — the UI comes up
regardless.</p>
<h1 id="model-storage">Model Storage</h1>
<p>Models don't need to live inside the repo. ComfyUI will look in additional
directories if you tell it to via <code>extra_model_paths.yaml</code>:</p>
<pre><code class="language-bash">cp extra_model_paths.yaml.example extra_model_paths.yaml
</code></pre>
<p>Then add an entry pointing at wherever you keep models. For example, if you
store them under <code>~/models/</code>:</p>
<pre><code class="language-yaml">my_models:
  base_path: ~/models/
  checkpoints: sdxl/
  ipadapter: ipadapter/
  clip_vision: clip_vision/
</code></pre>
<p>Adjust the subdirectory names to match your layout. ComfyUI merges these with
its own paths and shows everything in the UI dropdowns.</p>
<h1 id="models">Models</h1>
<p>Download SDXL (~6.5GB):</p>
<pre><code class="language-bash">hf download stabilityai/stable-diffusion-xl-base-1.0 \
  sd_xl_base_1.0.safetensors \
  --local-dir ~/models/sdxl/
</code></pre>
<p>For IP-Adapter, clone the custom node into ComfyUI's <code>custom_nodes/</code> directory:</p>
<pre><code class="language-bash">cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/cubiq/ComfyUI_IPAdapter_plus
</code></pre>
<p>No pip install needed — it has no extra dependencies beyond what ComfyUI
already installs. ComfyUI picks it up automatically on next startup.</p>
<p>Then download the IP-Adapter weights:</p>
<pre><code class="language-bash"># IP-Adapter for SDXL
hf download h94/IP-Adapter \
  sdxl_models/ip-adapter_sdxl.bin \
  --local-dir ~/models/ipadapter/

# CLIP vision encoder (required by IP-Adapter — must be ViT-bigG, not ViT-L)
hf download laion/CLIP-ViT-bigG-14-laion2B-39B-b160k \
  --local-dir ~/models/clip_vision/CLIP-ViT-bigG-14-laion2B-39B-b160k/
</code></pre>
<p>Restart ComfyUI after installing custom nodes. It rescans the nodes directory on
startup.</p>
<h1 id="quick-test">Quick Test</h1>
<p>Before touching the API, confirm generation works at all.</p>
<p>The built-in Templates target newer models and won't work with SDXL. ComfyUI
ships a test workflow in the repo — open it with <strong>File > Open</strong>:</p>
<pre><code>/path/to/ComfyUI/tests/inference/graphs/default_graph_sdxl1_0.json
</code></pre>
<p><img src="/images/comfyui-web-interface.png" alt="ComfyUI web interface"></p>
<p>It's a base+refiner workflow with two Load Checkpoint nodes. The top one
should already show <code>sd_xl_base_1.0.safetensors</code>. The bottom one defaults to
<code>sd_xl_refiner_1.0.safetensors</code> — change it to <code>sd_xl_base_1.0.safetensors</code>
too. We're not doing base+refiner, just running base twice.</p>
<p>Drop a prompt into one of the CLIP Text Encode nodes and hit <strong>Run</strong>:</p>
<pre><code>a knight in plate armor holding a mace and shield, fantasy RPG portrait,
detailed face, dramatic lighting, painterly style, 4k, highly detailed
</code></pre>
<p>First run is slow while the model loads. On M2 Air, SDXL at 20 steps takes
90-120 seconds. Subsequent runs with the model cached are faster but still
in that range — the Air throttles under sustained load with no active cooling.</p>
<p><img src="/images/oss-img-gen-knight.png" alt="Knight portrait generated with SDXL"></p>
<h1 id="img2img-post-battle">Img2Img: Post-Battle</h1>
<p>Txt2img generates from noise. Img2img starts from an existing image and
nudges it toward a new prompt. Good way to stay close to a character while
changing context or condition.</p>
<p>Add two nodes to the current workflow. Right-click empty canvas space (not
on a node) to get the picker:</p>
<ul>
<li><strong>image → Load Image</strong> — then select your knight from <code>ComfyUI/output/</code>
using the dropdown in the node, or upload it from there</li>
<li><strong>latent → VAE Encode</strong> — converts a pixel image into the latent space
the sampler works in, replacing the EmptyLatentImage</li>
</ul>
<p>Then make three connections. To draw a wire: click and drag from an output
dot (right side of a node) to an input dot (left side of another node).
The dots are color-coded by type and will only connect to compatible ports.</p>
<ol>
<li>Drag from the <strong>IMAGE</strong> dot (blue, right side of Load Image) to the
<strong>pixels</strong> dot on VAE Encode</li>
<li>Drag from either <strong>Load Checkpoint VAE</strong> dot → <strong>VAE Encode vae</strong> dot</li>
<li>Drag from <strong>VAE Encode LATENT</strong> dot → <strong>KSampler latent_image</strong> dot
(disconnects EmptyLatentImage automatically)</li>
</ol>
<p>The test workflow uses <strong>KSampler Advanced</strong>, which has no <code>denoise</code> slider.
Instead set <strong>start_at_step</strong> to <code>6</code>. With 20 total steps that runs the last
14, equivalent to about 70% denoise. Lower start_at_step = more faithful to
original, higher = more change.</p>
<p>Update the positive prompt — that's the CLIP Text Encode node wired to the
KSampler's <strong>positive</strong> input, as opposed to the negative one (which holds
your "ugly, blurry..." text):</p>
<pre><code>a knight in plate armor, damaged armor, battle-worn, dented helmet,
scratches and dents, mud-stained, exhausted, fantasy RPG portrait,
detailed face, dramatic lighting, painterly style, 4k, highly detailed
</code></pre>
<p>Hit <strong>Run</strong>. If it's changing too much, drop start_at_step to 4. If the
damage isn't reading, push to 8.</p>
<p><img src="/images/img2image-knight.png" alt="Knight after img2img battle damage pass"></p>
<p>Img2img works, but it's coarse. Fine details like face structure get lost
as you increase denoise, and at low denoise the prompt has limited
influence. Good for "same scene, different state." Not what you want for
generating the same character across completely different scenes.</p>
<p>That's what IP-Adapter is for. Instead of perturbing the reference image,
it encodes it through CLIP vision into an embedding that gets injected
alongside the text conditioning during generation. The sampler still starts
from pure noise, but the attention layers are nudged toward the character's
appearance at every step. Face and body survive across very different
scenes because the conditioning runs throughout, not just at the start.</p>
<h1 id="the-api">The API</h1>
<p>ComfyUI's API accepts a workflow as JSON and queues the generation. The workflow
you build in the UI can be exported in API format: go to Settings, enable Dev
Mode Options, then use the "Save (API Format)" button on the workflow.</p>
<p>The API format represents each node as a dict entry keyed by node ID. Here's a
minimal SDXL workflow:</p>
<pre><code class="language-json">{
  "4": {
    "class_type": "CheckpointLoaderSimple",
    "inputs": { "ckpt_name": "sd_xl_base_1.0.safetensors" }
  },
  "5": {
    "class_type": "EmptyLatentImage",
    "inputs": { "batch_size": 1, "height": 1024, "width": 768 }
  },
  "6": {
    "class_type": "CLIPTextEncode",
    "inputs": {
      "clip": ["4", 1],
      "text": "a fantasy rogue in a dark alley, RPG portrait, detailed"
    }
  },
  "7": {
    "class_type": "CLIPTextEncode",
    "inputs": {
      "clip": ["4", 1],
      "text": "ugly, blurry, watermark, text, bad anatomy"
    }
  },
  "3": {
    "class_type": "KSampler",
    "inputs": {
      "model": ["4", 0],
      "positive": ["6", 0],
      "negative": ["7", 0],
      "latent_image": ["5", 0],
      "seed": 42,
      "steps": 20,
      "cfg": 7,
      "sampler_name": "dpmpp_2m",
      "scheduler": "karras",
      "denoise": 1
    }
  },
  "8": {
    "class_type": "VAEDecode",
    "inputs": { "samples": ["3", 0], "vae": ["4", 2] }
  },
  "9": {
    "class_type": "SaveImage",
    "inputs": { "filename_prefix": "rpg", "images": ["8", 0] }
  }
}
</code></pre>
<p>Submit it:</p>
<pre><code class="language-bash">curl -X POST http://localhost:8188/prompt \
  -H "Content-Type: application/json" \
  -d '{"prompt": &#x3C;workflow_json>}'
# Returns: {"prompt_id": "abc123...", "number": 1, "node_errors": {}}
</code></pre>
<p>Poll for completion:</p>
<pre><code class="language-bash">curl http://localhost:8188/history/abc123
# When done: history[prompt_id]["status"]["completed"] == true
</code></pre>
<p>Fetch the image:</p>
<pre><code class="language-bash">curl "http://localhost:8188/view?filename=rpg_00001_.png" \
  --output character.png
</code></pre>
<p>Images also land in <code>ComfyUI/output/</code> on disk if you'd rather read them
directly.</p>
<h1 id="image-consistency-with-ip-adapter">Image Consistency with IP-Adapter</h1>
<p>IP-Adapter encodes a reference image using CLIP vision and injects that embedding
alongside the text prompt during generation. The result is a new image that
respects the prompt but is visually pulled toward the reference: same hair, same
armor, similar face structure.</p>
<p>It's not a perfect clone. Think of it as a strong nudge. Consistent text prompts
help too. If every prompt for Aria includes "tall elf rogue, purple hair, leather
armor," you're conditioning from both directions.</p>
<p>Add these nodes to the workflow above:</p>
<pre><code class="language-json">"10": {
  "class_type": "IPAdapterModelLoader",
  "inputs": { "ipadapter_file": "ip-adapter_sdxl.bin" }
},
"11": {
  "class_type": "CLIPVisionLoader",
  "inputs": { "clip_name": "CLIP-ViT-bigG-14-laion2B-39B-b160k/open_clip_model.safetensors" }
},
"12": {
  "class_type": "LoadImage",
  "inputs": { "image": "aria_portrait.png" }
},
"13": {
  "class_type": "IPAdapterAdvanced",
  "inputs": {
    "model": ["4", 0],
    "ipadapter": ["10", 0],
    "image": ["12", 0],
    "clip_vision": ["11", 0],
    "weight": 0.6,
    "weight_type": "linear",
    "combine_embeds": "concat",
    "start_at": 0.0,
    "end_at": 1.0,
    "embeds_scaling": "V only"
  }
}
</code></pre>
<p>Then change node <code>"3"</code>'s <code>model</code> input from <code>["4", 0]</code> to <code>["13", 0]</code>.</p>
<p>The prompt here asks for the same knight in a tavern — completely different
scene, same character used as reference.</p>
<p><img src="/images/oss-img-gen-ipadapter.png" alt="Knight in a tavern, generated with IP-Adapter using the portrait as reference"></p>
<p><code>weight</code> is the main knob. At 0.5 you get style and general appearance influence.
At 0.8 it starts fighting the text prompt. For character identity, 0.6-0.7 is
the range to start with.</p>
<p>The <code>image</code> input in node <code>"12"</code> is a filename relative to <code>ComfyUI/input/</code>.
Copy your reference images there, or upload them via the API:</p>
<pre><code class="language-bash">curl -X POST http://localhost:8188/upload/image \
  -F "image=@aria_portrait.png"
# Returns: {"name": "aria_portrait.png", "subfolder": "", "type": "input"}
</code></pre>
<h2 id="face-consistency">Face Consistency</h2>
<p>Standard IP-Adapter works well for overall style and body type. Faces drift more
than you'd like, especially across very different scenes. IP-Adapter FaceID handles
this by extracting face embeddings specifically rather than encoding the whole image.</p>
<p>Download:</p>
<pre><code class="language-bash">hf download h94/IP-Adapter-FaceID \
  ip-adapter-faceid-plusv2_sdxl.bin \
  --local-dir ~/models/ipadapter/
</code></pre>
<p>FaceID also requires InsightFace, which isn't on HuggingFace. Download the
<code>antelopev2</code> model package from the
<a href="https://github.com/deepinsight/insightface/tree/master/model_zoo">InsightFace model zoo</a>
and place it under <code>~/models/insightface/models/antelopev2/</code> (or wherever your
<code>extra_model_paths.yaml</code> maps <code>insightface</code>).</p>
<p>Install the Python package into the ComfyUI venv:</p>
<pre><code class="language-bash">source /path/to/ComfyUI/venv/bin/activate
pip install insightface onnxruntime
</code></pre>
<p>With FaceID installed, use <code>IPAdapterFaceIDAdvanced</code> instead of <code>IPAdapterAdvanced</code>.
It takes the same inputs but runs the face embedding extraction automatically.
Faces stay recognizable across very different scenes much more reliably than with
the standard adapter.</p>
<p>You can combine both: use <code>IPAdapterAdvanced</code> for overall character appearance
and <code>IPAdapterFaceIDAdvanced</code> for face locking, chaining them in sequence.</p>
<h1 id="game-integration">Game Integration</h1>
<p>The pattern for a TTRPG character system:</p>
<pre class="mermaid">
graph TD
    A[Player describes character] --> B[Generate initial portrait\nno reference image]
    B --> C[Store portrait in character record]
    C --> D[Game event triggers image]
    D --> E[Build scene + character prompt]
    E --> F[Upload portrait, generate\nwith IP-Adapter]
    F --> G[Display in game]
    G --> D
</pre>


<p>CodeRabbit is an AI code review tool. It can review your PRs on GitHub / MRs on GitLab
after you push. You can also hook it into Claude Code to get the review and fix up the
nits with your agent prior to opening the PR.</p>
<h1 id="install-the-cli">Install the CLI</h1>
<pre><code class="language-bash">curl -fsSL https://cli.coderabbit.ai/install.sh | sh
</code></pre>
<p>Then authenticate:</p>
<pre><code class="language-bash">coderabbit auth login
</code></pre>
<p>This opens a browser. Log in with GitHub, copy the token, paste it in the
terminal. The token lasts 90 days.</p>
<p>Verify it worked:</p>
<pre><code class="language-bash">coderabbit --version
</code></pre>
<h1 id="install-the-claude-code-plugin">Install the Claude Code Plugin</h1>
<p>From any terminal:</p>
<pre><code class="language-bash">claude plugin install coderabbit
</code></pre>
<p>Or from inside a Claude Code session:</p>
<pre><code class="language-text">/plugin install coderabbit
</code></pre>
<p>The plugin wraps the CLI and exposes review commands you can run directly in
your Claude Code session. It also lets you trigger a review with plain English,
which Claude Code routes to the plugin automatically.</p>
<h1 id="the-workflow">The Workflow</h1>
<p>With both the CLI and plugin installed, the loop before any PR looks like this:</p>
<pre class="mermaid">
graph TD
    A[Make changes with Claude Code] --> B[Run coderabbit review]
    B --> C{Issues?}
    C -->|Yes| D[Ask Claude Code to fix them]
    D --> A
    C -->|No| E[Create PR]
</pre>
<p>Inside a Claude Code session, after you've made changes:</p>
<pre><code class="language-text">/coderabbit:review uncommitted
</code></pre>
<p>This reviews everything not yet committed. You can also review committed-but-
not-pushed changes:</p>
<pre><code class="language-text">/coderabbit:review committed
</code></pre>
<p>Or compare against a specific branch:</p>
<pre><code class="language-text">/coderabbit:review --base main
</code></pre>
<p>The review comes back as inline comments. You can ask Claude Code to fix specific
issues, re-run the review, and iterate until it's clean. Then push and open the
PR knowing CodeRabbit's automated review will be quiet.</p>
<p>It's kind of slow, but so is the PR review.</p>
<h1 id="claudemd-integration">CLAUDE.md integration</h1>
<p>CodeRabbit reads your <code>CLAUDE.md</code> files automatically. It treats them as code
guidelines and applies them during review.</p>
<p>That means that because my <code>CLAUDE.md</code> says "no em-dashes" and "never commit directly to
main",  CodeRabbit enforces those same rules when it reviews your PR. You don't need to
configure anything extra.</p>
<h1 id="config-with-coderabbityaml">Config with <code>.coderabbit.yaml</code></h1>
<p><code>.coderabbit.yaml</code> at the root gives control over what gets reviewed, how aggressively,
and with what focus per directory.</p>
<p>Notably:</p>
<ul>
<li><code>path_filters</code>: glob patterns for files to skip entirely (lock files, build
artifacts, node_modules, etc)</li>
<li><code>path_instructions</code>: per-path AI instructions</li>
</ul>
<p>Don't put <code>CLAUDE.md</code> in <code>path_instructions</code>. That makes CodeRabbit try
to review the file rather than use it as guidelines. The auto-detection handles
it correctly without any config.</p>
<h2 id="setup-for-this-repo">Setup for this repo</h2>
<p>Here's <a href="https://github.com/kylep/multi/blob/main/.coderabbit.yaml">the <code>.coderabbit.yaml</code> for this repo</a>.</p>
<p><strong><code>profile: chill</code></strong> is the most significant setting. CodeRabbit's default
profile generates a lot of comments. I'm actually on the fence still about this though,
once I can get the AI agents to run the code review and fix up in a ralf-style-loop I
may go back to aggressive.</p>
<p><strong><code>poem: false</code></strong> turns off CodeRabbit's cute poems, I'm not reading them like this.</p>
<p><strong>Path filters</strong> drop lock files, build artifacts, and generated directories.
There's no value in reviewing a <code>package-lock.json</code> diff.</p>
<p><strong><code>infra/</code> and <code>apps/kytrade/</code></strong> get security-focused instructions with
everything else deprioritized. Terraform style is not worth a comment.
A misconfigured IAM policy is.</p>
<p><strong><code>apps/blog/blog/markdown/posts/</code></strong> gets a specific instruction to ignore
grammar, phrasing, and tone entirely. I'm specifically spending effort to not write
like a robot, I can't stand the writing style. CodeRabbit shouldn't fight it.</p>
<p><strong><code>samples/</code></strong> is tutorial code I used to save examples of projects along the way.</p>
<p><strong><code>**/tests/**</code></strong> is told to focus on whether tests actually assert something,
not on style. A test that always passes is a real problem. Variable naming is
not.</p>
<h2 id="update-teaching-it-about-false-positives-2026-03-11">Update: teaching it about false positives (2026-03-11)</h2>
<p>CodeRabbit kept flagging my blog frontmatter tags as needing YAML
list format. The blog parser handles comma-separated tags on one
line, so this was a false positive on every post.</p>
<p>The fix is <code>path_instructions</code> in <code>.coderabbit.yaml</code>. I added a
note to the blog posts path telling it not to suggest converting
frontmatter tags to list format. CodeRabbit applies these
instructions on every review, so the false positive should stop
recurring.</p>
<p>You can also reply <code>@coderabbitai</code> on a PR comment to teach it
inline. It stores those as "learnings" and applies them to future
reviews. The <code>.coderabbit.yaml</code> approach is more durable since
it's checked into the repo.</p>


<p>No API costs, no data leaving the machine, works offline. The catch is you're
limited to models that fit in RAM. At 16GB, you can run most 7-8B models at
good quality, or push into 12B at a lower quant.</p>
<p>This runs three models locally and compares them:</p>
<table>
<thead>
<tr>
<th>Model</th>
<th>Params</th>
<th>Style</th>
<th>Quant</th>
<th>Size</th>
</tr>
</thead>
<tbody>
<tr>
<td>Qwen3 8B</td>
<td>8B</td>
<td>Instruction</td>
<td>Q4_K_L</td>
<td>5.49 GB</td>
</tr>
<tr>
<td>DeepSeek-R1-Distill-Qwen-7B</td>
<td>7B</td>
<td>Reasoning</td>
<td>Q4_K_L</td>
<td>5.09 GB</td>
</tr>
<tr>
<td>Mistral Nemo Instruct 2407</td>
<td>12B</td>
<td>Instruction</td>
<td>Q4_K_L</td>
<td>7.98 GB</td>
</tr>
<tr>
<td>Mistral Small 3.1 24B</td>
<td>24B</td>
<td>Instruction</td>
<td>Q4_K_S</td>
<td>13.5 GB</td>
</tr>
</tbody>
</table>
<p>The first three fit comfortably in 16GB with room for context. Mistral Small
3.1 at 13.5 GB leaves very little headroom on a 16GB machine. To browse other models,
<a href="https://huggingface.co/bartowski">bartowski's HuggingFace page</a> is a good
starting point for well-tested GGUF quantizations.</p>
<p><strong>Params</strong> (parameters) are the learned weights that make up the model. More
parameters generally means more capable, but also more RAM and slower inference.
7-8B is a practical sweet spot for 16GB machines.</p>
<p><strong>Quantization</strong> is how a full-precision model gets compressed to fit on
consumer hardware. The original weights are 16 or 32-bit floats; quantization
rounds them down to fewer bits, trading a small amount of accuracy for a large
reduction in size and RAM usage. <strong>Q4_K_L</strong> uses 4-bit weights with the
embedding and output layers kept at higher precision (8-bit) to preserve
quality. <strong>Q4_K_S</strong> is the smaller sibling: same 4-bit compression throughout,
including the embedding layers, shaving off a bit of quality for a smaller
file. For Mistral Small 3.1 that's the difference between 13.5 GB (K_S) and
14.8 GB (K_L). On a 16GB machine, that 1.3 GB matters, so K_S is the right
pick there.</p>
<p><strong>Instruction</strong> models are trained to follow directions and answer questions
directly. You ask, they answer. <strong>Reasoning</strong> models think out loud first,
working through the problem step by step before giving a final answer. Slower,
but more reliable on anything involving logic, math, or code.</p>
<h1 id="hardware">Hardware</h1>
<ul>
<li>MacBook Air M2, 16GB unified memory</li>
<li>macOS 26 (Tahoe)</li>
</ul>
<p>No active cooling on the Air, so it'll throttle during long runs. Fine for
interactive use.</p>
<h1 id="setup">Setup</h1>
<p>These steps are shared across all three models.</p>
<h2 id="1-install-llamacpp">1. Install llama.cpp</h2>
<p><a href="https://github.com/ggerganov/llama.cpp">llama.cpp</a> is the runtime that loads
and runs GGUF model files. It handles the actual inference: tokenizing your
input, running it through the model weights, and streaming tokens back to you.
Think of it as the engine; the GGUF file is the model it runs. It also handles
Metal GPU offloading on Apple Silicon, which is what makes local inference fast
enough to be usable.</p>
<pre><code class="language-bash">brew install llama.cpp
</code></pre>
<p>Gives you <code>llama-cli</code> for interactive chat and <code>llama-server</code> for an
OpenAI-compatible HTTP API.</p>
<h2 id="2-install-the-hugging-face-cli">2. Install the Hugging Face CLI</h2>
<p>Installing Python tools with plain <code>pip</code> can stomp on system Python or conflict
with other packages. <code>pipx</code> puts each CLI tool in its own isolated environment
and adds it to your PATH. No venv to activate.</p>
<pre><code class="language-bash">brew install pipx
pipx ensurepath
pipx install "huggingface_hub[cli]"
</code></pre>
<p><code>pipx ensurepath</code> adds pipx's bin dir to your PATH. Restart your terminal after
running it.</p>
<p>Note: the installed command is <code>hf</code>, not <code>huggingface-cli</code>. The name changed in
v1.x.</p>
<h1 id="the-models">The Models</h1>
<h2 id="qwen3-8b">Qwen3 8B</h2>
<p>Alibaba's Qwen3 8B (released April 2025) is a dense instruction-tuned model
that also supports a thinking mode. By default it answers directly. You can
enable step-by-step reasoning with <code>/think</code> in the chat, or disable it with
<code>/no_think</code>.</p>
<pre><code class="language-bash">hf download bartowski/Qwen_Qwen3-8B-GGUF Qwen_Qwen3-8B-Q4_K_L.gguf \
  --local-dir ~/models/qwen3-8b/
</code></pre>
<h2 id="deepseek-r1-distill-qwen-7b">DeepSeek-R1-Distill-Qwen-7B</h2>
<p>Note: despite the name, there is no 8B Qwen-based DeepSeek distill. The 8B
distill uses Llama architecture. This one is 7B on Qwen architecture, released
January 2025.</p>
<p>DeepSeek distilled the chain-of-thought behaviour from their R1 reasoning model
into this smaller base. It always shows its thinking inside <code>&#x3C;think>...&#x3C;/think></code>
tags before the final answer. Verbose for simple questions, but useful for
anything involving logic or code.</p>
<pre><code class="language-bash">hf download bartowski/DeepSeek-R1-Distill-Qwen-7B-GGUF \
  DeepSeek-R1-Distill-Qwen-7B-Q4_K_L.gguf \
  --local-dir ~/models/deepseek-r1-qwen-7b/
</code></pre>
<h2 id="mistral-small-31-24b">Mistral Small 3.1 24B</h2>
<p>Released March 17, 2025. Mistral's most capable small model at the time.
24B parameters, multimodal (supports image input), 128k context window,
Apache 2.0. Mistral officially recommends 32GB RAM for this one, so running
it on a 16GB M2 Air is pushing it. It loads and runs, but context has to stay
small.</p>
<p>Note: bartowski's repo for this model has a <code>mistralai_</code> prefix in the name,
unlike the others.</p>
<pre><code class="language-bash">hf download bartowski/mistralai_Mistral-Small-3.1-24B-Instruct-2503-GGUF \
  Mistral-Small-3.1-24B-Instruct-2503-Q4_K_S.gguf \
  --local-dir ~/models/mistral-small-3.1-24b/
</code></pre>
<p>K_S over K_L here because at 13.5 GB vs 14.8 GB, the difference determines
whether you have any RAM left for context and the OS.</p>
<h2 id="mistral-nemo-instruct-12b">Mistral Nemo Instruct 12B</h2>
<p>Mistral's 12B model (released July 2024, jointly with NVIDIA). Bigger than the
other two, which shows in the quality of longer-form responses. At Q4_K_L it's
7.98 GB, leaving ~6GB free for macOS and context.</p>
<pre><code class="language-bash">hf download bartowski/Mistral-Nemo-Instruct-2407-GGUF \
  Mistral-Nemo-Instruct-2407-Q4_K_L.gguf \
  --local-dir ~/models/mistral-nemo-12b/
</code></pre>
<h1 id="running-them">Running Them</h1>
<p>The flags are the same for all three. Swap the <code>-m</code> path.</p>
<h2 id="interactive-chat">Interactive chat</h2>
<pre><code class="language-bash"># Qwen3 8B
llama-cli \
  -m ~/models/qwen3-8b/Qwen_Qwen3-8B-Q4_K_L.gguf \
  -ngl 99 -c 8192

# DeepSeek-R1-Distill-Qwen-7B
llama-cli \
  -m ~/models/deepseek-r1-qwen-7b/DeepSeek-R1-Distill-Qwen-7B-Q4_K_L.gguf \
  -ngl 99 -c 8192

# Mistral Nemo 12B
llama-cli \
  -m ~/models/mistral-nemo-12b/Mistral-Nemo-Instruct-2407-Q4_K_L.gguf \
  -ngl 99 -c 8192

# Mistral Small 3.1 24B — tight on RAM, keep context small
llama-cli \
  -m ~/models/mistral-small-3.1-24b/Mistral-Small-3.1-24B-Instruct-2503-Q4_K_S.gguf \
  -ngl 99 -c 2048
</code></pre>
<p>Flags:</p>
<ul>
<li><code>-ngl 99</code>: offload all layers to Metal. Without this you're CPU-only and it's
very slow. <code>--fit on</code> instead might be better, not sure.</li>
<li><code>-c 8192</code>: context window. Comfortable with 16GB for the smaller two. Fine
for Mistral Nemo too given the headroom.</li>
</ul>
<p>Interactive mode is auto-enabled when the model has a chat template, which all
three do. The old <code>--interactive-first</code> flag was removed in newer llama.cpp.</p>
<h2 id="openai-compatible-server">OpenAI-compatible server</h2>
<pre><code class="language-bash">llama-server \
  -m ~/models/qwen3-8b/Qwen_Qwen3-8B-Q4_K_L.gguf \
  -ngl 99 -c 8192 --port 8080
</code></pre>
<p>Exposes <code>http://localhost:8080/v1/chat/completions</code>. Swap the model path for
whichever you want to serve.</p>
<h1 id="conclusion">Conclusion</h1>
<h2 id="notes-on-each">Notes on Each</h2>
<p><strong>Qwen3 8B</strong>: Pretty fast. The thinking thing was a bit slow but not bad. It mostly
stuck to the instructions I gave it, like "max 3 paragraphs", and was reasonably
creative. It was also kind of bland and generic, for better or worse.</p>
<p><strong>DeepSeek-R1-Distill-Qwen-7B</strong>: Also ok speed. It had a hard time following
instructions and sticking to the constraints that I'd tried to put in place, like that
same 3 paragraph limit. Overall I was pretty dissapointed given its reputation.</p>
<p><strong>Mistral Nemo 12B</strong> The direct responses felt fast even though it ran at about half
the tokens per second, due to it not working in Reasoning mode. The writing style of
Nemo was by far the best, and it adhered much better to the prompts.</p>
<p><strong>Mistral Nemo 24B</strong> Not enough RAM. I'd figured I could close things and make it work
but it's not worth it. Maybe on a better computer.</p>
<h2 id="not-enough-tokens">Not enough tokens</h2>
<p>The <code>8192</code> tokens they all use got to feeling pretty small, pretty fast. I tried to
push the continuity with a "Choose your own adventure" style conversation and it did
well until it just kind of stopped. I think I've seen claude crushing context down when
it gets near the limit, I wonder if there's a way to do that with this too, or get it
to do some sort of context shifting where it restarts with just the later context when
it runs low. Maybe I can run it in server mode and have a better client manage that,
but that seems like its own post. If you want to run models through an API
rather than locally, <a href="/openrouter-ai-tools.html">OpenRouter</a> is worth a look.</p>
<h2 id="winner">Winner</h2>
<p>Nemo was the pretty clear winner. I'm not sure if that's because of the size of the
model or something else, but it was a significant step up in its ability to stick to
the prompt's instructions, and the writing style was better too.</p>


<p>I wrote about this blog's <a href="/ai-generate-blog-images.html">automated image generation</a> previously. The short version: <code>generate-images.mjs</code> runs before each build, finds posts with missing images, builds a prompt from the <code>imgprompt</code> front matter field (or has <code>gpt-4o-mini</code> summarize the post), then calls DALL-E 3 to produce a 1024x1024 image.</p>
<p>It works, but DALL-E 3 is frustrating. It ignores prompt details, can't make a white background to save its life, and the results look more "AI art" than "clean icon." Time to see what else is out there.</p>
<p><em>Lesson Learned</em>: Don't let Cursor/Claude look online to find the most recent model versions. It got it wrong twice. I had to manually go back and update it after noticing that Gemini's 2.0-flash was not the newer Nano Banana (2.5, 3).</p>
<h1 id="top-models-today">Top Models Today</h1>
<p>This space moves fast. As of February 2026, these are the top 3 image generation models on the <a href="https://arena.ai/leaderboard/text-to-image">LM Arena text-to-image leaderboard</a> that have public APIs. These rankings are based on blind human preference voting and will almost certainly be different by the time you read this.</p>
<p><strong>ELO Scores:</strong> ELO is a rating system where users are shown two AI-generated images side by side (without knowing which model made which) and pick the one they prefer. Wins and losses shift each model's score, so a higher ELO means the model's images are consistently preferred by real people.</p>
<table>
<thead>
<tr>
<th>Model</th>
<th>Provider</th>
<th>Released</th>
<th>ELO</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>GPT Image 1.5</strong></td>
<td>OpenAI</td>
<td>December 2025</td>
<td>1248</td>
<td>4x faster than GPT Image 1. Token-based pricing, 20% cheaper than its predecessor.</td>
</tr>
<tr>
<td><strong>Nano Banana Pro</strong></td>
<td>Google (Gemini 3 Pro Image)</td>
<td>November 2025</td>
<td>1237</td>
<td>Native Gemini image gen. Strong multimodal integration.</td>
</tr>
<tr>
<td><strong>Flux 2 Max</strong></td>
<td>Black Forest Labs</td>
<td>November 2025</td>
<td>1169</td>
<td>32B parameter model. Megapixel-based pricing. BFL's highest quality tier.</td>
</tr>
</tbody>
</table>
<p>GPT Image 1.5 and Nano Banana Pro are close in quality. Flux 2 Max sits ~80 ELO points behind them but is the strongest non-Google non-OpenAI option available.</p>
<p><strong>What about open source?</strong> Flux 2 Dev is open-weight and Stable Diffusion 3.5 is fully open source, but neither is practical for this use case. Running them on a MacBook Air M2 (8GB unified memory, passive cooling) means throttling after ~90 seconds, a max practical resolution of 512x512, and needing to close basically every other app first. The quality gap vs. the API models is real too. For a build-time script that needs to reliably produce clean images, cloud APIs win.</p>
<h1 id="setup-gpt-image-15">Setup: GPT Image 1.5</h1>
<p>This is the easiest since the blog already uses OpenAI.</p>
<ol>
<li><strong>API Key</strong>: Already set up. Same <code>OPENAI_API_KEY</code> used for DALL-E 3.</li>
<li><strong>Model change</strong>: Update the <code>model</code> parameter from <code>dall-e-3</code> to <code>gpt-image-1.5</code> in the images API call.</li>
<li><strong>API differences</strong>: GPT Image 1.5 supports both the Images API (<code>/v1/images/generations</code>) and the newer Responses API. The Images API is the closest drop-in replacement. Quality can be set to <code>low</code>, <code>medium</code>, <code>high</code>, or <code>auto</code>. It also supports streaming partial renders and up to 16 reference images for editing.</li>
</ol>
<pre><code class="language-bash">export OPENAI_API_KEY="sk-..."
</code></pre>
<p>If you don't already have a key, create one at <a href="https://platform.openai.com/api-keys">platform.openai.com/api-keys</a>.</p>
<h1 id="setup-nano-banana">Setup: Nano Banana</h1>
<p>Nano Banana is Google's image generation feature built on Gemini. You can access it through the official Google Gemini API.</p>
<ol>
<li><strong>Get an API key</strong>: Go to <a href="https://aistudio.google.com/app/apikey">Google AI Studio</a> and create a new API key.</li>
<li><strong>Install the SDK</strong>:
<pre><code class="language-bash">npm install @google/genai
</code></pre>
</li>
<li><strong>Set the environment variable</strong>:
<pre><code class="language-bash">export GEMINI_API_KEY="your-key-here"
</code></pre>
</li>
<li><strong>API usage</strong>: Nano Banana image gen uses the Gemini API with <code>responseModalities: ["TEXT", "IMAGE"]</code>. The model name for the standard tier is <code>gemini-2.5-flash-preview-image</code> and for Pro it's <code>gemini-3-pro-image</code>.</li>
</ol>
<p>Note: the API flow is different from OpenAI. You send a chat completion-style request with image output enabled, and the response includes inline image data.</p>
<h1 id="setup-flux-2-max">Setup: Flux 2 Max</h1>
<p>Black Forest Labs runs their own API platform.</p>
<ol>
<li><strong>Create an account</strong>: Register at <a href="https://dashboard.bfl.ai">dashboard.bfl.ai</a> and confirm your email.</li>
<li><strong>Add credits</strong>: Navigate to API → Credits and add funds via Stripe. Pricing is simple: 1 credit = $0.01 USD.</li>
<li><strong>Create an API key</strong>: Go to API → Keys, click "Add Key", and copy it immediately (it's only shown once).</li>
<li><strong>Set the environment variable</strong>:
<pre><code class="language-bash">export BFL_API_KEY="your-key-here"
</code></pre>
</li>
<li><strong>API usage</strong>: POST to <code>https://api.bfl.ai/v1/flux-2-max</code> with your prompt, width, and height. The API is async — you submit a task and poll for the result using the returned task ID.</li>
</ol>
<h1 id="setup-verification">Setup Verification</h1>
<p>Once you've configured your API keys, you can verify everything is wired up correctly by running:</p>
<pre><code class="language-bash">node apps/blog/blog/scripts/generate-images.mjs --verify
</code></pre>
<p>This will check that each configured API key is valid and can reach its respective service without actually generating any images. We'll implement this flag in a follow-up change.</p>
<h1 id="cost">Cost</h1>
<p>All prices are USD per image at 1024x1024.</p>
<table>
<thead>
<tr>
<th>Model</th>
<th>Cost</th>
<th>Pricing Model</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>DALL-E 3 (prior)</td>
<td>~$0.04</td>
<td>Per image</td>
<td>Fixed price, single quality tier</td>
</tr>
<tr>
<td>GPT Image 1.5</td>
<td>$0.009–$0.14</td>
<td>Per token (output)</td>
<td>Varies by quality: low ~$0.009, medium ~$0.03, high ~$0.14. ~20% cheaper than GPT Image 1</td>
</tr>
<tr>
<td>Nano Banana</td>
<td>~$0.02</td>
<td>Per image</td>
<td>Standard tier (Gemini 2.5 Flash). Pro tier is ~$0.10/image</td>
</tr>
<tr>
<td>Flux 2 Max</td>
<td>~$0.07</td>
<td>Per megapixel</td>
<td>Scales with resolution. 1024x1024 ≈ 1MP ≈ 7 credits</td>
</tr>
</tbody>
</table>
<p>The ambiguity here is mostly around GPT Image 1.5 — the token-based pricing means cost depends heavily on the quality setting and prompt length. For a fair comparison we'll use "medium" quality, which lands close to what we're paying for DALL-E 3 today. Flux 2 Max's megapixel pricing is predictable but gets more expensive at higher resolutions.</p>
<h1 id="results">Results</h1>
<p>Each model was given the same prompt, built from <code>imgprompt: "A cute robot wearing a short chefs hat and holding a paint brush"</code>:</p>
<pre><code class="language-text">Subject: "A cute robot wearing a short chefs hat and holding a paint brush".
Style: minimalist flat vector icon, clean lines, crisp edges, simplified geometric shapes.
Colors: black, white, and one primary accent color only. No gradients.
Composition: centered subject, generous negative space, wide landscape 16:9 aspect ratio.
Background: pure solid white (#FFFFFF), filling the entire image.
No text, no shadows, no textures, no transparency, no background elements.
</code></pre>
<p>All images were center-cropped to 533x300 (16:9) after generation.</p>
<h2 id="gpt-image-15-openai">GPT Image 1.5 (OpenAI)</h2>
<p>Model: <code>gpt-image-1.5</code>, size: 1024x1024, quality: medium. Estimated cost: ~$0.03.</p>
<p><img src="/images/ai-image-gen-bakeoff-openai.png" alt="GPT Image 1.5 result"></p>
<h2 id="gemini-20-flash-google">Gemini 2.0 Flash (Google)</h2>
<p>Model: <code>gemini-2.0-flash-exp-image-generation</code>. Estimated cost: ~$0.02 (free tier may apply).</p>
<p><img src="/images/ai-image-gen-bakeoff-gemini-2.0.png" alt="Nano Banana 2.0 result"></p>
<h2 id="nano-banana-gemini-25-flash">Nano Banana (Gemini 2.5 Flash)</h2>
<p>Model: <code>gemini-2.5-flash-image</code>. Estimated cost: ~$0.02.</p>
<p><img src="/images/ai-image-gen-bakeoff-gemini-2.5.png" alt="Nano Banana 2.5 Flash result"></p>
<h2 id="nano-banana-pro-gemini-3-pro">Nano Banana Pro (Gemini 3 Pro)</h2>
<p>Model: <code>gemini-3-pro-image-preview</code>. Estimated cost: ~$0.10.</p>
<p><img src="/images/ai-image-gen-bakeoff-gemini-3-pro.png" alt="Nano Banana 3 Pro result"></p>
<h2 id="flux-2-max-bfl">Flux 2 Max (BFL)</h2>
<p>Model: <code>flux-2-max</code>, size: 1024x576. Estimated cost: ~$0.04 (~0.6MP at $0.07/MP).</p>
<p><img src="/images/ai-image-gen-bakeoff-flux.png" alt="Flux 2 Max result"></p>
<h1 id="conclusion">Conclusion</h1>
<p>It's pretty close between OpenAI and Nano Banana 2.5. I'll likely switch back and forth between the two, but to pick a flat winner as default I'm going with OpenAI for now.</p>
<p>OpenAI has that annoying same-y generic feel that lets you know it's AI art, and I don't love that, but it's also definitely more cute.</p>
<p>Nano Banana's ones are pretty original. I like 3-pro the most but not the price. 2.5-flash is fun, a bit cleaner than OpenAI's art, just kind of <em>busy</em>. I'll probably pick it when I'm aiming for cleaner images than cute ones.</p>
<p>Flux's was more artsy. It's just kind of... weird? It kept drawing unique stuff but just sort of unsettling.</p>


<p>Making blog thumbnails and images is tedious. I don't want to fight with Gimp or whatever and I don't think anyone cares what the image really is.</p>
<p>To make publishing easier, this site now checks for the image in each markdown post during the build to see if it already exists. If not, a prompt is built from the post title and content and sent to OpenAI's image API. The returned art is saved alongside the post and a 70×70 thumbnail is produced using Sharp.</p>
<p>To make the image for this post it cost me about $0.12 CAD in OpenAI credits. Entertainingly that's probably more than what hosting this site will cost for like a week due to the setup I'm using to host this.</p>
<p>This automation was initially coded with Codex, but it didn't work quite right. I fixed it up with Cursor, then a bit manually to get it across the finish line. This was as much about playing with the AI dev tools as building the feature.</p>
<p>Check it out here <a href="https://github.com/kylep/multi/blob/main/apps/blog/blog/scripts/generate-images.mjs">generate-images.mjs</a>.</p>
<h1 id="how-it-works">How It Works</h1>
<p>The image generation system is integrated into the build pipeline through the <code>package.json</code> build script:</p>
<pre><code class="language-json">"build": "node scripts/generate-images.mjs &#x26;&#x26; next build"
</code></pre>
<p>Before Next.js builds the static site, the <code>generate-images.mjs</code> script runs and:</p>
<ol>
<li><strong>Scans all markdown files</strong> in <code>markdown/posts/</code> for front matter</li>
<li><strong>Checks for missing images</strong> referenced in the <code>image</code> and <code>thumbnail</code> fields</li>
<li><strong>Generates missing images</strong> using OpenAI's DALL·E API if <code>OPENAI_API_KEY</code> is set</li>
<li><strong>Creates thumbnails</strong> by resizing generated images to 70×70 pixels using Sharp</li>
</ol>
<h2 id="the-generation-process">The Generation Process</h2>
<p>It's all pretty straightforward:</p>
<p>High level script logic:</p>
<ol>
<li>If there's no image defined, do nothing</li>
<li>If the image is defined in the front matter but doesn't exist, generate it.</li>
<li>If the image does exist but thumbnail doesn't, resize it and save that too.</li>
</ol>
<p>Generating the image is also simple:</p>
<ol>
<li>If the front matter has <code>imgprompt</code> in it, use that as the <code>summary</code> of the post.</li>
<li>If <code>imgprompt</code> is not present get <code>gpt-4o-mini'</code> to write a <code>summary</code> of the post.</li>
<li>Use <code>dall-e-3</code> to create the image.</li>
<li>Complain that it didn't look right, tweak the prompt, repeat until sufficiently frustrated, move on.</li>
</ol>
<h3 id="prompts">Prompts</h3>
<p>At time of writing (I won't keep this updated, check the code), I used these for the prompts:</p>
<p>Making the summary:</p>
<pre><code class="language-javascript">async function summarizeBlogContent(data, content) {
  const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
  const prompt = await openai.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: `In max 20 words, describe a simple logo image that would represent this blog post: ${content}` }],
  });
  const summary = prompt.choices[0].message.content;
  console.log(`✨📝 Created summary of "${data.title}" → ${summary}`);
  return summary;
}
</code></pre>
<p>Making the image</p>
<pre><code class="language-javascript">async function getPromptFromContent(data, content) {
  const subject = data.imgprompt
    ? data.imgprompt
    : await summarizeBlogContent(data, content);
  const prompt = [
    "Simple minimalist flat vector icon.",
    `Subject: "${subject}".`,
    "Style: clean flat SVG-style vector, crisp edges, no gradients, no shadows, no textures, no lighting effects.",
    "Colors: limited palette, high contrast, modern minimal. Black, white, and primary colors only.",
    "Composition: centered subject with generous whitespace, 1:1 icon framing.",
    "Background: pure solid white (#FFFFFF) and completely filled. Nothing around the logo.",
    "No transparency. No checkerboard. No grid. No background elements.",
    "No text. No words. Just a simple image centered in white space."
  ].join("\n");
  return prompt;
}
</code></pre>
<h3 id="environment-setup">Environment Setup</h3>
<p>Set your OpenAI API key</p>
<pre><code class="language-bash">export OPENAI_API_KEY="your-api-key-here"
</code></pre>
<p>Without this key the build just skips image generation with a warning.</p>
<hr>
<h1 id="outstanding-problem">Outstanding Problem</h1>
<p>Dalle-3 is super frustrating when it comes to just making a white background. I spent a couple hours trying different prompts and it just refuses. Here's what the code came up with as a prompt for this page:</p>
<pre><code class="language-text">Simple minimalist flat vector icon.
Subject: "A simple logo featuring a stylized laptop and a paintbrush, symbolizing effortless content creation and automated design.".                     
Style: clean flat SVG-style vector, crisp edges, no gradients, no shadows, no textures, no lighting effects.                                                                                                
Colors: limited palette, high contrast, modern minimal. Black, white, and primary colors only.   
Composition: centered subject with generous whitespace, 1:1 icon framing.                             
Background: pure solid white (#FFFFFF) and completely filled. Nothing around the logo.                
No transparency. No checkerboard. No grid. No background elements.                                    
No text. No words. Just a simple image centered in white space. 
</code></pre>
<p>It does not seem to care for my preference. If anyone has any tricks for this I'd love to hear about it.</p>


<h1 id="aside-leveraging-ai-for-blog-content">(Aside) Leveraging AI for Blog Content</h1>
<p>Most of this change was written by Codex, and finished up by Cursor. Cursor did a much better job actually running and fixing the errors in the build. When I joined Super.com, my current employer, I rewrote this entire SSG blog engine from Pelican into React + Next as a learning exercise. I'd been writing production code in Angular for years so it wasn't a big jump. I've picked at this blog over the years, but purely as an engine to keep my skills sharp since I'm a senior leader now and spend most of my days in meetings or planning technical and organizational strategy. This is the first blog post in a long time.</p>
<p>AI wrote the first draft. It was bad. For the code, that was ok. It took some iterating but AI codes well enough now if you hold its hand.</p>
<p>The mermaid chart syntax example in this post is all AI. The actual writing style of AI makes my eyes glaze over and I don't want to subject other people to it, so I rewrote basically all of the actual text. No sense contributing too much towards a dead internet, right?</p>
<p>Have feelings about the idea of AI being used for this sort of thing? I'd love to hear your thoughts. You can find my socials on the about page.</p>
<hr>
<h1 id="how-the-rendering-works">How the rendering works</h1>
<p>Take a look at the <a href="https://github.com/mermaid-js/mermaid">official GitHUb page for Mermaid-JS</a> for more details about mermaid in general. It's really neat and I'm convinced it'll be considered the standard for flow charts for the next while.</p>
<p>The markdown loader still starts by parsing front matter with <a href="https://github.com/jonschlinkert/gray-matter"><code>gray-matter</code></a>, but the Remark pipeline now detects any fenced code block labeled <code>mermaid</code> and rewrites it into HTML with the <code>mermaid</code> class.</p>
<p>It's all pretty simple from there. You can see <code>remarkMermaidToHtml</code> (from <a href="https://github.com/kylep/multi/blob/main/apps/blog/blog/utils/remarkMermaid.js">remarkMermaidToHtml in remarkMermaid.js</a>) is new here:</p>
<pre><code class="language-javascript">	static async getRenderedMarkdownAndProps(rawMarkdown){
		// contentHtml is the rendered markdown, metaData is the front matter as a flat object
		const { data: metaData, content: markdown } = matter(rawMarkdown);
		MarkdownService.#serializeDates(metaData); 
                const result = await remark()
                        .use(remarkGfm)
                        .use(remarkToc, {heading: 'Table of contents'})
                        .use(remarkMermaidToHtml)
                        .use(remarkHtml, { sanitize: false })
                        .process(markdown);
		const contentHtml = result.toString();
		const props = {props: {contentHtml, metaData},};
		return props;
	 };
</code></pre>
<hr>
<h1 id="mermaid-syntax-reference">Mermaid Syntax Reference</h1>
<p>Here's a trivial reference of how to use Mermaid syntax.</p>
<p>I plan to use this reference myself for future content, and may update it with more useful examples in time.</p>
<h2 id="flowchart">Flowchart</h2>
<pre><code class="language-text">graph TD;
  Source[Markdown] --> Remark;
  Remark --> |HTML| Browser;
  Browser --> MermaidRuntime;
  MermaidRuntime --> |SVG| PublishedPost;
</code></pre>
<pre class="mermaid">
graph TD;
  Source[Markdown] --> Remark;
  Remark --> |HTML| Browser;
  Browser --> MermaidRuntime;
  MermaidRuntime --> |SVG| PublishedPost;
</pre>
<h2 id="sequence-diagram">Sequence diagram</h2>
<pre><code class="language-text">sequenceDiagram
  participant Author
  participant Blog
  participant Mermaid
  Author->>Blog: Write markdown with mermaid fences
  Blog->>Mermaid: Request runtime initialization
  Mermaid-->>Blog: Render SVG
  Blog-->>Author: Display diagram
</code></pre>
<pre class="mermaid">
sequenceDiagram
  participant Author
  participant Blog
  participant Mermaid
  Author->>Blog: Write markdown with mermaid fences
  Blog->>Mermaid: Request runtime initialization
  Mermaid-->>Blog: Render SVG
  Blog-->>Author: Display diagram
</pre>
<h2 id="state-diagram">State diagram</h2>
<pre><code class="language-text">stateDiagram-v2
  [*] --> Draft
  Draft --> Review: lint &#x26; build
  Review --> Published: merge
  Published --> Archived
</code></pre>
<pre class="mermaid">
stateDiagram-v2
  [*] --> Draft
  Draft --> Review: lint & build
  Review --> Published: merge
  Published --> Archived
</pre>
<h2 id="class-diagram">Class diagram</h2>
<pre><code class="language-text">classDiagram
  class MarkdownService {
    +getRenderedMarkdownAndProps()
  }
  class BlogPostContentPage {
    +useEffect mermaid bootstrap
  }
  MarkdownService --> BlogPostContentPage : HTML
</code></pre>
<pre class="mermaid">
classDiagram
  class MarkdownService {
    +getRenderedMarkdownAndProps()
  }
  class BlogPostContentPage {
    +useEffect mermaid bootstrap
  }
  MarkdownService --> BlogPostContentPage : HTML
</pre>


Kyle Pericak

"It works in my environment"

Categories

Tags