Forem: Anup Karanjkar

Claude Code 2.1 Agent View & /goal: Autonomous Dev Guide 2026

Anup Karanjkar — Sat, 23 May 2026 00:15:55 +0000

I let Claude Code run unsupervised for three hours last Wednesday. It wrote 847 lines of test coverage, debugged six failing tests, and stopped exactly when the conditions I set were met — without me touching the keyboard once. That is what the /goal command does. Combine it with Agent View, the new session dashboard that shipped in v2.1.139 on May 19, 2026, and you have the closest thing to a true autonomous coding partner the CLI has ever shipped.

The short version: claude agents gives you a live dashboard of every session — running, blocked, or done. /goal <condition> sets a completion target and Claude loops across turns until it is met. Background sessions with --bg let those loops run without blocking your terminal. This combination turns Claude Code from an interactive assistant into something closer to a scheduled background worker that asks for help only when genuinely stuck.

What Shipped in v2.1.139 (And What Came After)

The May 19 release was dense. Agent View and /goal were the headliners, but the two weeks of point releases that followed added features that change how you configure and automate agents. Here is the full picture:

Version	Feature	What It Does

| 2.1.139 | Agent View, /goal | Session dashboard; completion-driven loops |

| 2.1.140 | Agent hook types | Stop/SubagentStop hooks for agent frontmatter |

| 2.1.142 | New session flags | --add-dir, --settings, --mcp-config, --permission-mode |

| 2.1.143 | Worktree isolation toggle | bgIsolation: "none" for repos where worktrees break |

| 2.1.144 | /resume in agent view | Background sessions appear with bg tag; resume by ID |

| 2.1.145 | claude agents --json | JSON output for tmux, status bars, scripting |

| 2.1.147 | /code-review | Renamed from /simplify; reports correctness bugs at chosen effort level |

| 2.1.149 | /usage breakdown | Per-category costs: skills, subagents, plugins, MCP |

The version cadence tells you something: Anthropic is shipping against real developer feedback. The worktree isolation fix in 2.1.143 — adding bgIsolation: "none" for repos where git worktrees are impractical — was not a planned feature. It was a direct response to production blockers. The /resume functionality expanding to Agent View in 2.1.144 filled an obvious gap that the initial launch left open. This is the engineering culture at Anthropic: drop the headline, then fill the missing pieces fast.

Agent View: The Session Dashboard You Have Been Waiting For

Run claude agents from any terminal and you get a single live view of every Claude Code session: which ones are running, which are blocked waiting for your input, and which have finished. The count of sessions awaiting input appears in your terminal tab title — meaning you can see at a glance how many agents need attention without switching context.

# Open the agent view dashboard
claude agents

# Scope it to a specific project directory
claude agents --cwd ./my-project

# Output as JSON for scripting (tmux, status bars, monitoring)
claude agents --json

Inside the dashboard, four keyboard shortcuts do most of the work. Ctrl+T pins a background session — pinned sessions stay alive when idle and auto-restart after Claude Code updates instead of requiring manual relaunch. Ctrl+R renames a session to something human-readable. The left arrow key detaches or closes a session while preserving its state. And v opens the session directly in your editor.

The session state preservation is the part that matters most in practice. When you detach with the left arrow or background a session with /bg, it preserves the model, effort level, permission mode, MCP servers, and settings you configured. In earlier Claude Code versions, detaching and resuming a session sometimes reverted to defaults. That regression is gone as of 2.1.142.

One subtle improvement: sessions launched from Agent View respect the permissions.defaultMode from your settings.json. If your project settings say auto, agent view sessions inherit that without you passing a flag every time. Small change, large day-to-day impact.

/goal: Tell Claude When It Is Done

The /goal command is deceptively simple. You set a completion condition. Claude works across turns until that condition is met, then stops.

# In an interactive Claude Code session
/goal Write unit tests covering 95% of the authentication module

# Compound conditions work too
/goal Implement OAuth2 login with Google and GitHub. All existing tests must pass. No TypeScript errors.

While a goal is active, a live overlay panel shows elapsed time, number of turns completed, and cumulative token count. The overlay runs in real time without blocking your ability to type — you can interact with the session while Claude is working if you need to redirect it or provide context it is missing.

What makes /goal different from just giving Claude a task in a single message is that it creates a controlled loop. Claude writes code, runs tests, inspects failures, revises the code, and runs tests again — automatically, across as many turns as the goal requires. The completion condition is checked after each cycle. This is not a new capability in the underlying model; it is a harness change that lets the model apply its existing tool-use and reasoning capabilities over a longer trajectory without requiring you to manually re-prompt it.

I used /goal to write a Zod schema validation test suite covering edge cases I had been putting off for weeks. The goal ran for 41 minutes and 23 turns. It found three input patterns my initial schemas did not handle and fixed them before stopping. Total cost: $0.43 in API tokens according to /usage. That 41 minutes would have been three to four hours of my time, spread across three separate mornings of interrupted work.

The comparison to point-and-shoot prompting is stark. "Refactor the auth module" stops when Claude runs out of obvious things to do. "/goal Auth module refactored with no TypeScript errors and 90%+ test coverage" stops when the work is actually done. That distinction is what makes /goal a fundamentally different interface, not just a convenience wrapper.

Background Sessions: The Full Control Surface

Background sessions are not new to Claude Code, but the 2.1.x releases added enough configuration surface that they now behave like first-class agent deployments rather than a niche CLI trick.

# Start a simple background session
claude --bg "Audit the codebase for security issues in the auth module"

# Fully configured background agent
claude --bg --name "security-audit"   --model claude-opus-4-7   --effort high   --permission-mode auto   --settings ./.claude/settings.json   --mcp-config ./.claude/mcp.json   "Complete the security review and output findings to SECURITY_REPORT.md"

# Resume a background session interactively
/resume

# Resume by specific session ID
claude --resume

The --fallback-model flag is worth knowing for production workflows. If the primary model hits a rate limit or quota boundary, Claude Code falls back to the specified alternative instead of failing hard:

claude --bg --model claude-opus-4-7   --fallback-model claude-sonnet-4-6   "Refactor the payment processing module"

For repositories where git worktrees cause problems — monorepos with symlinks, certain CI-generated layouts, some Windows configurations — set "worktree.bgIsolation": "none" in your settings.json. Background sessions will then edit the working copy directly instead of creating an isolated worktree. This unblocks a significant class of production use cases that were painful before 2.1.143.

Empty idle background sessions auto-retire after five minutes. Sessions that finish their work but leave a background shell running move to "Completed" rather than "Running". These distinctions matter when you are managing six sessions and need to know which ones are still doing something versus which ones have finished and are just consuming memory.

New Agent Flags: Configure Everything

The v2.1.142 release added a set of flags that turn what used to be informal defaults into explicit, preservable configuration. All of these work in both claude and claude agents:

claude --add-dir ../shared-lib          # Give Claude read access to a directory outside cwd
claude --settings ./.claude/prod.json  # Use project-specific settings file
claude --mcp-config ./.claude/mcp.json # Attach specific MCP servers to this session
claude --plugin-dir ./.claude/plugins  # Load project-specific plugins
claude --permission-mode auto           # No prompts for safe file operations
claude --effort xhigh                   # Maximum reasoning depth for trust-boundary tasks
claude --dangerously-skip-permissions  # Full bypass (use only in sandboxed environments)

The --add-dir flag solves a recurring pain point. Claude Code previously could not read files outside the current working directory without you changing directories first. With --add-dir, you can give an agent access to a shared library, a design system package, or a documentation directory outside the project root — without restructuring your project layout to accommodate it.

For multi-agent orchestration, these flags let you configure each dispatched subagent independently. A lead orchestrator running at --effort high can dispatch subagents with lower effort for mechanical tasks like formatting or renaming, controlling cost across the entire system. For patterns on structuring these systems, the multi-agent coordination guide covers orchestrator-worker architectures in detail.

Three Workflows That Changed How I Work

1. The Background Audit

Every Friday, I run a background audit against the week's merged PRs. The agent reads the diff, checks for patterns from our CLAUDE.md security rules, and writes findings to a WEEKLY_AUDIT.md file. I come back Monday to a report rather than a vague sense that I should probably review something.

claude --bg --name "weekly-audit"   --model claude-opus-4-7   --effort high   --permission-mode auto   "Read all changes merged this week. Cross-reference against .claude/rules/trust-boundary.md. Write WEEKLY_AUDIT.md with findings ranked by severity. Flag any payment or auth path changes explicitly."

2. The Completion Gate

Before any PR goes out, I set a /goal with the exact criteria from our definition of done. Not a checklist I run through manually. Not a reminder to check TypeScript. A condition Claude satisfies or keeps working:

/goal All TypeScript type errors resolved. All unit tests pass. No console.log statements remaining. ESLint reports zero errors on changed files.

Claude works through the list systematically. It does not stop until every condition is true. This replaced my pre-PR checklist habit, which I was reliably skipping under deadline pressure.

3. The Pinned Session

I keep one pinned session open in Agent View for the project I am actively shipping. It holds project context, MCP server connections, and permission settings — configured once, preserved across updates. When I need Claude for something quick, I jump into the pinned session instead of starting a cold context window. Auto-restart on updates means I get new Claude Code features without losing the session configuration.

The /usage Command: Real Cost Visibility

Starting in v2.1.149, /usage breaks down your token costs by category: skills, subagents, plugins, and MCP server calls. Before this update, the aggregate cost was visible but opaque — you could not tell whether a session's cost was driven by MCP tool calls, recursive subagent spawning, or the main conversation. That distinction matters when you are optimizing a multi-agent workflow for cost efficiency.

For MCP-heavy workflows, the MCP servers guide covers patterns for keeping call counts reasonable. An agent that calls an MCP server 50 times in a session is often doing something that could be batched into 3–5 calls with better tool design. /usage makes that pattern visible instead of hiding it inside an aggregate number.

What to Do Right Now

Update to v2.1.149 or later: npm update -g @anthropic-ai/claude-code. Then run claude agents and look at what is actually running. Most developers are surprised to find sessions they backgrounded and forgot. Pin the ones that matter with Ctrl+T so they survive the next update cycle.

For any task that takes more than 20 minutes to specify, set a /goal with the completion criteria instead of a task description. The difference in outcome is consistent enough that I now default to /goal for anything beyond a single-file edit.

If you are building production workflows with background agents, read the new flag documentation before committing to an architecture. The --permission-mode, --fallback-model, and --add-dir flags together create a configuration surface that was not possible before May 2026. The agents you can build now are meaningfully more reliable than what shipped in April.

The CLAUDE.md templates, agent skill starters, and MCP server boilerplates for building these workflows are available at wowhow.cloud — pay once, configure once, ship reliably.

Originally published at wowhow.cloud

Claude for Small Business: 15 Workflows & Setup Guide 2026

Anup Karanjkar — Fri, 22 May 2026 12:22:36 +0000

Anthropic launched Claude for Small Business on May 13, 2026 — and it is the most practical deployment of AI in daily business operations to date. Rather than a chatbot you open in a separate tab, this package embeds 15 ready-to-run agentic workflows directly into the tools small businesses already pay for: QuickBooks, PayPal, HubSpot, Canva, DocuSign, Google Workspace, Microsoft 365, and Slack. Here is everything you need to know to evaluate, set up, and get real value from it.

The core design principle is deceptively simple: Claude does the work, then asks your approval before anything sends, posts, or pays. If your QuickBooks user cannot see a vendor's banking details today, they cannot see those details through Claude either. The permission model is exactly what every business owner feared they would have to configure themselves — and Anthropic built it in from day one.

What Is Claude for Small Business?

Claude for Small Business is a package built on top of Claude Cowork — Anthropic's collaborative workspace layer — that ships with three things: 15 ready-to-run agentic workflows, 15 reusable skills, and connectors to eight business tools. Each workflow is an end-to-end job, not a one-shot prompt. You authorize it once, Claude reads the relevant data, runs the analysis or drafting, and presents the output for your review before anything leaves the system.

The eight connected tools at launch are QuickBooks, PayPal, HubSpot, Canva, DocuSign, Google Workspace, Microsoft 365, and Slack. These cover the core operational surface of most small businesses: accounting, payments, CRM, design, contracts, email and calendar, productivity, and internal communication.

Pricing is straightforward. It is included with any existing Claude Pro ($20/month), Claude Max ($100–$200/month), or Claude Team subscription at no additional charge. You only pay for the partner tools you already use. Setup requires no IT support and takes under 30 minutes.

The 15 Workflows: What They Actually Do

The workflows span six categories: finance, operations, sales, marketing, HR, and customer service. Rather than listing all fifteen mechanically, here are the five that address the highest-friction recurring tasks for most small businesses.

1. Cash Flow Reconciliation and Forecasting

Claude checks your QuickBooks cash position against incoming PayPal settlements, builds a 30-day forward forecast, ranks overdue invoices by amount and age, and queues payment reminder drafts for your review. What previously took a bookkeeper two hours on Monday morning takes Claude under three minutes. Every draft sits in your queue until you approve it — nothing sends automatically. For a founder doing their own bookkeeping, this single workflow alone justifies the subscription.

2. Month-End Close Packet

Claude reconciles your books against bank and payment settlements, flags every mismatch with a plain-English explanation, writes a P&L summary your accountant can read without translation, and exports a close packet formatted for PDF delivery. The workflow eliminates the manual copy-and-reconcile cycle that makes month-end painful for small teams running lean financial operations.

3. Sales Campaign Builder

Claude identifies slow revenue periods in your HubSpot data, analyzes the performance of past campaigns, drafts a promotional strategy, and generates campaign assets in Canva — all before anything goes live. You review the strategy, the copy, and the design in one place. If you want to change the offer or the headline, you instruct Claude and it regenerates. The complete cycle from "we need a campaign" to "here are the assets for your review" is a single workflow invocation.

4. Contract Generation and Signature Routing

Claude drafts standard agreements using templates you have previously approved, generates the DocuSign envelope, and routes it to the correct counterparty. The workflow pulls contact information from HubSpot, so you are not manually copying email addresses between apps. You review the contract before it leaves your system. Signature reminders run on the schedule you configure, not by Claude autonomously deciding when to follow up.

5. Hiring and Onboarding Coordination

The HR workflow drafts job descriptions, schedules interviews through Google Calendar, generates offer letters based on your standard terms, sends DocuSign envelopes for new hire paperwork, and queues the onboarding checklist in Slack. A process that typically spans three tools and multiple copy-paste operations becomes a single workflow that presents every document for your approval at each step.

Skills vs. Workflows: The Distinction That Matters

The 15 skills are different from the 15 workflows. Workflows are end-to-end operations — they connect multiple tools, run analysis, and produce a complete output. Skills are reusable building blocks: specific ways Claude knows how to handle a particular type of task that you can invoke in conversation or chain into custom workflows you design yourself.

Examples of skills include: drafting a professional email to a delinquent client, formatting a financial report for a specific audience, generating a social post from a blog excerpt, or summarizing a PDF contract into plain English. These are not full workflows, but they are the components that make custom workflows fast to build as you understand the system more deeply.

Start with the pre-built workflows for immediate ROI. Then, as you identify recurring tasks that do not fit a pre-built workflow, chain skills together to create your own. This is where the system becomes significantly more powerful than any individual AI app you have used before.

The Permission Architecture: How Trust Actually Works

The most important thing to understand about Claude for Small Business is not what it can do — it is how it handles what it should not do.

Every connector respects the permissions that exist in the underlying tool. If an employee has read-only access to QuickBooks, Claude has read-only access to QuickBooks when that employee is using it. If a team member cannot approve payments in PayPal, Claude cannot approve payments on their behalf. This is not a Claude-level guardrail layered on top — it is native permission inheritance from each connected application, enforced at the OAuth token level.

The human-in-the-loop requirement for any external action is built into every workflow. Claude drafts the invoice reminder; you approve and send. Claude builds the campaign assets; you approve and publish. Claude prepares the contract; you review and route. This is the correct architecture for a business tool: AI as a tireless, accurate preparer, with the human retaining every consequential decision.

This design choice distinguishes Claude for Small Business from the "AI agent deleted our data" incidents that made headlines in early 2026. Anthropic made a deliberate product decision to build agentic capability without autonomous execution on financial or legal actions. For a small business with real money, real clients, and real legal exposure, that constraint is the right one.

Pricing Reality Check

The effective cost depends on where you sit in the Claude subscription stack. Claude Pro at $20/month is a personal tier; team features require Claude Team, billed per seat. Claude Max at $100–$200/month includes Claude for Small Business at no additional charge and is the cleanest entry point for a solo founder who wants all 15 workflows immediately.

The honest comparison is against the workflow time this replaces. Monthly bookkeeping review with a QuickBooks ProAdvisor runs $200–$500/month for a small operation. A part-time marketing assistant for campaign creation might cost $500–$1,500/month. A contract management platform beyond DocuSign's base tier adds $50–$200/month. Claude for Small Business does not replace any of these entirely, but it materially reduces the hours at each layer — which for a founder doing everything simultaneously, is the real ROI calculation.

Anthropic is running a 10-city US tour through summer 2026, starting in Chicago, with free half-day workshops and a free month of Claude Max for every attendee. If you are evaluating the platform seriously and are in the US, attending before committing is worth the half day.

Limitations Worth Knowing Before You Commit

Claude for Small Business launched US-focused in May 2026. International connector support — particularly for non-US accounting software like Xero, MYOB, or Tally — is not available at launch. If your financial stack is outside the eight supported tools, the finance workflows are unavailable until Anthropic expands the connector library.

The 15 pre-built workflows cover common patterns well, but they are not infinitely configurable out of the box. If your business has unusual contract structures, multi-entity accounting, or complex approval chains, you will need to work with skills rather than pre-built workflows — which requires more setup time and a deeper understanding of how Claude handles context across multi-step operations.

The system requires that you connect real accounts with real data. There is no sandbox mode for evaluation before authorization. If privacy or data security are concerns — particularly for businesses in regulated industries such as healthcare or legal services — read Anthropic's data handling terms carefully before connecting QuickBooks or DocuSign credentials. The same diligence applies to any third-party AI platform with access to financial data.

Who Should Start With Claude for Small Business

The clearest immediate candidates are founders running businesses between $500k and $5M in annual revenue with a small team: typically one to fifteen people. At this scale, the founder is often doing bookkeeping review, approving contracts, drafting campaigns, and managing hiring simultaneously — exactly the operational workload the 15 workflows address directly.

Service businesses — agencies, consultancies, professional services firms — will see the fastest payback from the contract and invoicing workflows. Product businesses with e-commerce components will see the most value from the QuickBooks + PayPal reconciliation and the HubSpot + Canva campaign builder.

Teams already running on Google Workspace or Microsoft 365 get the deepest integration since both are supported connectors from day one. Calendar scheduling, email drafting, and document generation all tie into the workflow layer without additional configuration.

Getting Started: Four Steps

Setup requires no IT support and takes under 30 minutes. Log into Claude.ai and navigate to the Cowork section. The Small Business package surfaces under Marketplace or Integrations depending on your account tier.

Connect QuickBooks first. The finance workflows deliver the highest ROI and the reconciliation workflow will produce a concrete output on real data within five minutes of connection — giving you an immediate proof point before you authorize any additional tool. Authorize the OAuth connection, confirm read/write permissions, and run the cash flow reconciliation workflow on your current data.

Connect HubSpot next if you run an active CRM. The sales and marketing workflows are the second-fastest value delivery. Then connect the remaining tools in order of daily use priority. Each connection is a separate OAuth authorization; you are not granting Claude blanket access to your entire business stack at once.

Claude for Small Business represents a meaningful shift in how small businesses can use AI — not as a chat assistant, but as a workflow layer embedded in the tools that run the business. The human-in-the-loop architecture, native permission inheritance, and pre-built workflow library solve the three main blockers that kept most small businesses from deploying AI in operational roles: trust, access control, and setup complexity. Whether the full 15-workflow suite fits your specific business will become clear in the first week of use.

Originally published at wowhow.cloud

OpenAI Files for IPO: What Every Developer Building on OpenAI Needs to Know (2026)

Anup Karanjkar — Fri, 22 May 2026 06:23:34 +0000

OpenAI filed its IPO prospectus confidentially this week, targeting a September 2026 public listing at a valuation above $1 trillion — and every developer building production applications on the OpenAI API needs to understand what that means for their business. IPOs do not just create paper wealth for insiders; they fundamentally reshape how companies operate. Pricing decisions, model release cadence, research openness, and API reliability all shift when public market accountability enters the picture. This guide breaks down OpenAI's financial position, what the Microsoft partnership restructure actually changes, and the concrete steps developers should take before the S-1 becomes public.

The filing is happening in the middle of the most competitive moment in AI history. Anthropic is targeting an October 2026 IPO. SpaceX filed its own S-1 on May 20. Both companies share overlapping infrastructure deals, investors, and developer mindshare. The AI infrastructure layer — APIs that millions of developers depend on — is about to become part of the public markets conversation in a way it never has been before. The implications are not theoretical.

What We Know About OpenAI's Financials

OpenAI's March 2026 funding round disclosed approximately $2 billion in monthly revenue — roughly $25 billion annualized, up from $20 billion at the close of 2025. The company closed a $122 billion funding round in late March 2026 at an $852 billion post-money valuation, making it one of the largest private financings in technology history. Those are staggering numbers, but they come with important context that the public S-1 will either confirm or complicate.

What investors and developers still cannot see — until the public S-1 drops — is gross margin after compute costs. Large language model inference is extraordinarily capital-intensive. Training and serving frontier models like GPT-5.5 requires GPU clusters at a scale that makes compute cost one of the largest variables in the economics. A company earning $25 billion in revenue but spending $22 billion on compute, salaries, and infrastructure has a very different financial profile than the headline revenue number suggests.

CFO Sarah Friar's blog post in January 2026 confirmed that the company crossed $20 billion annualized. What she did not disclose was burn rate, capex obligations, or the gross margin after infrastructure costs. Public market investors will demand those numbers. If compute economics are tighter than the valuation assumes, the pressure to raise API prices or cut model availability will intensify after the IPO.

For developers, watch the S-1 filing for three specific disclosures. First, gross margin — anything below 50% signals sustained price pressure. Second, API revenue as a percentage of total revenue — if enterprise subscriptions (ChatGPT Enterprise, OpenAI for Business) are growing faster than API revenue, that signals a de-prioritization of the developer tier. Third, capex guidance — if the company is committing to $30+ billion in infrastructure spend annually, the capital needs will put pressure on monetization timelines.

The Microsoft Restructure: What Actually Changed for Developers

The most underreported aspect of OpenAI's IPO preparation is the renegotiated Microsoft partnership finalized in May 2026. Under the new terms, OpenAI's total revenue-share payments to Microsoft are capped at $38 billion through 2030 — down from a projected $135 billion under the prior agreement. That $97 billion difference is structural improvement in OpenAI's cash flow position that directly affects how much financial pressure the company faces to aggressively monetize the API.

Microsoft retains approximately 27% of OpenAI on a diluted basis, valued at roughly $135 billion at the $852 billion round valuation. As the company moves toward an IPO, Microsoft's role shifts from a capital provider to a major shareholder with public market exposure. That alignment of interests changes the dynamic: Microsoft now has an incentive for OpenAI's public valuation to hold, which creates pressure to demonstrate stable, growing API revenue rather than subsidizing below-market pricing.

For developers building on Azure OpenAI Service, the restructure matters directly. Azure OpenAI pricing and model availability has historically tracked the direct API — but as the commercial interests of both companies sharpen around the IPO window, divergence is possible. A developer team with major Azure commitments may find its OpenAI model access governed through a different SLA and cadence than a team using the direct API. Mapping your specific integration path now, before the IPO paperwork locks in new commercial frameworks, is worth doing proactively.

API Pricing Under Public Market Pressure

The core developer concern with any AI company IPO is straightforward: does going public accelerate price increases? The honest answer is that it depends on where the company sits in its growth phase — and OpenAI's trajectory suggests measured caution is warranted.

OpenAI has historically used aggressive pricing as a growth lever. GPT-4o remains available on the free tier. GPT-5.5 dropped to $2/$8 per million tokens within weeks of launch. The company has subsidized developer adoption with below-cost pricing while scaling user growth. That strategy is sustainable with private capital and venture backing. It becomes structurally harder to justify on a quarterly earnings call when public investors are watching gross margin compress against capex commitments.

The historical precedent from SaaS infrastructure companies that went public is instructive. Twilio raised prices twice in the 18 months following its 2016 IPO. Snowflake restructured its pricing from on-demand to committed-use contracts to smooth revenue recognition for Wall Street analysts. Stripe's private pricing flexibility narrowed significantly as the company grew closer to IPO readiness. These are not failures — they are the predictable consequence of public market accountability requirements.

What this means in practice for OpenAI: the most likely scenario is not sudden price spikes but gradual reduction in free-tier generosity, more aggressive promotion of committed-use enterprise contracts, and slower pass-through of model cost reductions to API pricing. The era of GPT-4-class models becoming free-tier access almost certainly ends within 12 months of the IPO. Developers should baseline their current costs now and build cost-increase scenarios into runway models before the S-1 drops.

Model Release Cadence and Research Openness

Public companies in AI face a contradictory pressure: investors want predictable recurring revenue, but AI capability advances on an inherently unpredictable research timeline. OpenAI's current strategy of releasing models when they are ready — GPT-5.5 released May 2026, GPT-5.5 Instant for ChatGPT in the same month — gives the company maximum technical flexibility but creates inconsistent revenue recognition that equity analysts will push back on.

Post-IPO, expect more structured release cadences aligned with the quarterly earnings calendar. Research releases that previously happened when ready will increasingly align with quarterly announcements. This is not necessarily bad for developers — predictability in model updates makes API versioning and migration planning considerably easier — but it reduces the sense that you are always accessing the frontier model as fast as research progress allows.

Research openness is the more significant long-term concern. OpenAI's name grows increasingly ironic — the company has not open-sourced a frontier model in several years. The commercial pressures of being a public company make sharing model weights even less likely. If competitive advantage lives in the model, and the model is the primary revenue-generating asset, the incentive to open-source any meaningful component of that asset disappears entirely under public market scrutiny. Developers building on OpenAI should assume that access to model internals, fine-tuning endpoints on frontier models, and research previews will become more restricted rather than more open over the next 18 months.

Building a Multi-Provider Strategy Before the IPO

The most actionable response to OpenAI's IPO is to reduce API-level lock-in now, while switching costs are still manageable. Teams that built exclusively on the OpenAI API have accumulated technical debt in the form of provider-specific features: OpenAI function calling syntax, OpenAI Assistants API patterns, OpenAI file handling and thread management. Migrating those to provider-agnostic interfaces after a price increase happens under pressure — the worst possible conditions for careful engineering.

The multi-provider pattern that has emerged as the production standard in 2026 uses a routing layer — LiteLLM, OpenRouter, or a custom abstraction — that normalizes the OpenAI-compatible API interface across multiple providers. Anthropic's Claude, Google's Gemini, and OpenAI's GPT all accept requests in compatible formats when routed through these layers. The incremental engineering cost is a few hours; the optionality created is substantial.

A minimal provider hedge for a production application looks like this: route non-latency-sensitive tasks — batch summarization, classification, document extraction — to whichever provider currently offers the best cost-per-quality ratio. Route latency-sensitive tasks such as real-time chat and code completion to your primary provider. Keep model-specific integrations in an adapter layer that can be swapped without touching business logic. Evaluate at least one alternative provider monthly to maintain institutional familiarity and keep your routing configuration current.

The goal is not to abandon OpenAI. GPT-5.5 and its successors will likely remain among the strongest models for many use cases throughout the IPO period and beyond. The goal is to ensure that a price increase or API policy change is a decision you make deliberately, from a position of optionality, rather than a crisis you react to from a position of lock-in.

The Competitive Landscape After Three Public AI Companies

OpenAI's IPO does not happen in isolation. Anthropic is targeting an October 2026 public listing. Google's Gemini business is already public through Alphabet, with AI revenue now broken out separately in quarterly reports. The era of private AI companies competing on research timelines without public accountability is ending for all three major API providers simultaneously.

This convergence creates a meaningful developer opportunity: all three companies will be competing for developer mindshare under public market scrutiny, which historically increases investment in developer tools, documentation, pricing competitiveness, and ecosystem programs. The 18-24 months following the OpenAI IPO are likely to be the most actively competitive period for API pricing and developer tooling in AI history. Each company will be demonstrating developer ecosystem health to public market investors and analysts who can compare them directly.

Developers who maintain active integrations with multiple providers are positioned to benefit from this dynamic. Being a credible alternative-ready customer gives leverage in enterprise contract discussions that a provider-locked developer simply does not have. When three public companies are competing for the same developer spend on the same earnings cycle, the developer with optionality is the one with pricing power.

Three Things Developers Should Do This Week

The IPO filing is happening now. Here is what is worth doing before the public S-1 drops and the market narrative solidifies:

Audit your OpenAI API spend by feature. Break down your monthly spend by which specific capabilities you use: which models, which endpoints, which features have no direct equivalent elsewhere. Identify the 20% of your OpenAI usage that is genuinely irreplaceable versus the 80% that could be routed to an alternative today. The audit itself is valuable even if you never migrate a single workload — it gives you a clear picture of your actual exposure.

Set up a parallel environment with one alternative provider. Register for Anthropic API access or Gemini API access if you have not already. Run a representative sample of your production workloads against the alternative. Measure quality, latency, and cost. This takes a few hours of engineering time and removes the knowledge gap that makes migration feel more daunting than it actually is.

Define your cost escalation thresholds now. If your OpenAI costs increase by 25%, 50%, or 2x, what happens to your product economics and unit margins? Define those thresholds explicitly. Build a simple cost dashboard that surfaces provider spend on a daily basis. When the IPO-driven pricing pressure arrives — and historical precedent suggests it will — you will know immediately rather than discovering it in the next monthly invoice.

OpenAI going public is a genuine milestone for the AI industry — the company that sparked the modern large language model era will be accountable to public markets for the first time. For developers, the filing week is the right moment to stress-test your infrastructure dependency and build the optionality that keeps you in control of your own product economics, regardless of what any single provider decides to do with its pricing strategy in the quarters ahead.

Originally published at wowhow.cloud

Zod Validation: Type-Safe APIs & Forms in TypeScript (Complete Guide)

Anup Karanjkar — Thu, 21 May 2026 18:00:14 +0000

TypeScript types disappear at runtime. Your carefully typed User interface means nothing when the JSON from an external API, a form submission, or a database query arrives as unknown. Zod bridges this gap: you define a schema once, validate data against it at runtime, and get a TypeScript type back for free. This guide covers every Zod pattern you will use — from basic schemas to API validation, form handling, and OpenAPI generation.

If you are building TypeScript APIs or form-heavy applications, browse WOWHOW Tools for starter kits and check out the full catalog for Next.js and React templates with validation built in.

Why Zod Over Alternatives

Zod infers TypeScript types from schemas (schema-first, not type-first). It has zero dependencies, works in Node.js and browsers, and its error messages are structured objects you can use to build user-facing form errors without any extra work. It also chains neatly with transforms — parse, validate, and reshape data in one step.

Core Schema Types

import { z } from 'zod'

// primitives
const name    = z.string()
const age     = z.number()
const active  = z.boolean()
const created = z.date()
const id      = z.bigint()

// string constraints
const email    = z.string().email()
const url      = z.string().url()
const uuid     = z.string().uuid()
const slug     = z.string().regex(/^[a-z0-9-]+$/, 'Lowercase letters, numbers, hyphens only')
const password = z.string().min(8).max(128)
const bio      = z.string().max(500).optional()

// number constraints
const price    = z.number().positive().finite()
const rating   = z.number().int().min(1).max(5)
const quantity = z.number().int().nonnegative()

// literals and enums
const role     = z.enum(['admin', 'editor', 'viewer'])
const status   = z.literal('active')
const exact    = z.union([z.literal('pending'), z.literal('shipped'), z.literal('delivered')])

// infer types automatically
type Role   = z.infer   // 'admin' | 'editor' | 'viewer'
type Email  = z.infer  // string (with runtime guarantee)

Object Schemas

const UserSchema = z.object({
  id:         z.string().uuid(),
  email:      z.string().email().toLowerCase(),  // transform to lowercase
  firstName:  z.string().min(1).max(50),
  lastName:   z.string().min(1).max(50),
  role:       z.enum(['admin', 'editor', 'viewer']).default('viewer'),
  age:        z.number().int().min(13).max(120).optional(),
  createdAt:  z.string().datetime(),  // ISO 8601 string
})

type User = z.infer

// parse: throws ZodError on failure
const user = UserSchema.parse(rawData)

// safeParse: returns { success, data } or { success, error }
const result = UserSchema.safeParse(rawData)
if (!result.success) {
  console.error(result.error.flatten())
  // { fieldErrors: { email: ['Invalid email'] }, formErrors: [] }
}

Nested Objects and Arrays

const AddressSchema = z.object({
  street:  z.string().min(1),
  city:    z.string().min(1),
  state:   z.string().length(2),
  zipCode: z.string().regex(/^d{5}(-d{4})?$/),
  country: z.string().length(2).default('US'),
})

const OrderSchema = z.object({
  id:          z.string().uuid(),
  customerId:  z.string().uuid(),
  items:       z.array(
    z.object({
      productId: z.string().uuid(),
      quantity:  z.number().int().positive(),
      unitPrice: z.number().positive(),
    })
  ).min(1, 'Order must have at least one item'),
  shippingAddress: AddressSchema,
  total:       z.number().positive(),
  status:      z.enum(['pending', 'confirmed', 'shipped', 'delivered', 'cancelled']),
  notes:       z.string().max(1000).nullable().default(null),
})

type Order = z.infer

// tuple with mixed types
const CoordSchema = z.tuple([z.number(), z.number()])  // [lat, lng]
const TripleSchema = z.tuple([z.string(), z.number(), z.boolean()])

Transforms: Parse and Reshape in One Step

// coerce strings from form inputs
const FormPriceSchema = z
  .string()
  .transform((val) => parseFloat(val))
  .pipe(z.number().positive())

// parse ISO date strings into Date objects
const DateFromStringSchema = z
  .string()
  .datetime()
  .transform((str) => new Date(str))

// normalize phone numbers
const PhoneSchema = z
  .string()
  .transform((val) => val.replace(/[^0-9]/g, ''))
  .pipe(z.string().length(10, 'Must be 10 digits'))

// computed fields using transform
const FullNameSchema = z
  .object({
    firstName: z.string(),
    lastName:  z.string(),
  })
  .transform((data) => ({
    ...data,
    fullName: `\${data.firstName} \${data.lastName}`,
    initials: `\${data.firstName[0]}.\${data.lastName[0]}.`,
  }))

const { firstName, lastName, fullName, initials } = FullNameSchema.parse({
  firstName: 'Anup',
  lastName:  'Karanjkar',
})
// fullName: 'Anup Karanjkar', initials: 'A.K.'

Refinements: Cross-Field and Async Validation

// single-field refinement
const PasswordSchema = z
  .string()
  .min(8)
  .refine(
    (val) => /[A-Z]/.test(val) && /[0-9]/.test(val) && /[^a-zA-Z0-9]/.test(val),
    { message: 'Password must contain uppercase, number, and special character' }
  )

// cross-field refinement
const PasswordConfirmSchema = z
  .object({
    password:        z.string().min(8),
    confirmPassword: z.string(),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: 'Passwords do not match',
    path: ['confirmPassword'],   // attach error to specific field
  })

// date range validation
const DateRangeSchema = z
  .object({
    startDate: z.string().date(),
    endDate:   z.string().date(),
  })
  .refine(
    (data) => new Date(data.endDate) > new Date(data.startDate),
    { message: 'End date must be after start date', path: ['endDate'] }
  )

// async refinement (e.g. database uniqueness check)
const UniqueEmailSchema = z
  .string()
  .email()
  .superRefine(async (email, ctx) => {
    const exists = await db.user.findUnique({ where: { email } })
    if (exists) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: 'Email already in use',
      })
    }
  })

// use parseAsync for schemas with async refinements
const validEmail = await UniqueEmailSchema.parseAsync('user@example.com')

API Request Validation in Next.js Route Handlers

import { NextRequest, NextResponse } from 'next/server'
import { z } from 'zod'

const CreateProductSchema = z.object({
  name:        z.string().min(3).max(100),
  price:       z.number().positive(),
  currency:    z.enum(['USD', 'INR', 'EUR']).default('USD'),
  description: z.string().min(10).max(5000),
  tags:        z.array(z.string()).max(10).default([]),
  published:   z.boolean().default(false),
})

type CreateProductInput = z.infer

export async function POST(req: NextRequest) {
  let body: unknown
  try {
    body = await req.json()
  } catch {
    return NextResponse.json({ error: 'Invalid JSON' }, { status: 400 })
  }

  const result = CreateProductSchema.safeParse(body)
  if (!result.success) {
    return NextResponse.json(
      {
        error: 'Validation failed',
        details: result.error.flatten().fieldErrors,
      },
      { status: 422 }
    )
  }

  const product = await createProduct(result.data)
  return NextResponse.json(product, { status: 201 })
}

// helper to validate any route handler input
function validateBody(schema: z.ZodType) {
  return async (req: NextRequest): Promise => {
    let body: unknown
    try {
      body = await req.json()
    } catch {
      return NextResponse.json({ error: 'Invalid JSON' }, { status: 400 })
    }
    const result = schema.safeParse(body)
    if (!result.success) {
      return NextResponse.json(
        { error: 'Validation failed', details: result.error.flatten().fieldErrors },
        { status: 422 }
      )
    }
    return { data: result.data }
  }
}

Form Validation with React Hook Form

import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { z } from 'zod'

const CheckoutSchema = z.object({
  email:     z.string().email('Enter a valid email'),
  firstName: z.string().min(1, 'Required').max(50),
  lastName:  z.string().min(1, 'Required').max(50),
  address:   z.string().min(5, 'Enter full address'),
  city:      z.string().min(1, 'Required'),
  pinCode:   z.string().regex(/^d{6}$/, 'Enter 6-digit PIN code'),
  phone:     z.string().regex(/^[6-9]d{9}$/, 'Enter valid Indian mobile number'),
})

type CheckoutFormData = z.infer

function CheckoutForm() {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting },
  } = useForm({
    resolver: zodResolver(CheckoutSchema),
  })

  const onSubmit = async (data: CheckoutFormData) => {
    // data is fully typed AND validated
    await submitOrder(data)
  }

  return (


      {errors.email && 
{errors.email.message}
}


      {errors.pinCode && 
{errors.pinCode.message}
}


        {isSubmitting ? 'Processing...' : 'Place Order'}


  )
}

Schema Composition and Reuse

// base schema — shared fields
const TimestampedSchema = z.object({
  createdAt: z.string().datetime(),
  updatedAt: z.string().datetime(),
})

const BaseEntitySchema = z.object({
  id: z.string().uuid(),
}).merge(TimestampedSchema)

// extend for specific entities
const ProductSchema = BaseEntitySchema.extend({
  name:  z.string(),
  price: z.number().positive(),
})

// pick/omit for partial schemas
const ProductPreviewSchema = ProductSchema.pick({ id: true, name: true })
const CreateProductInput   = ProductSchema.omit({ id: true, createdAt: true, updatedAt: true })
const UpdateProductInput   = CreateProductInput.partial()  // all fields optional

// discriminated unions
const ApiResponseSchema = z.discriminatedUnion('success', [
  z.object({ success: z.literal(true),  data: z.unknown() }),
  z.object({ success: z.literal(false), error: z.string(), code: z.number() }),
])

type ApiResponse = z.infer

Environment Variable Validation

// src/env.ts — validate at startup, not at request time
import { z } from 'zod'

const EnvSchema = z.object({
  NODE_ENV:        z.enum(['development', 'test', 'production']),
  DATABASE_URL:    z.string().url(),
  REDIS_URL:       z.string().url().optional(),
  NEXTAUTH_SECRET: z.string().min(32),
  RAZORPAY_KEY_ID: z.string().startsWith('rzp_'),
  PORT:            z.coerce.number().int().positive().default(3000),
})

const parsed = EnvSchema.safeParse(process.env)
if (!parsed.success) {
  console.error('Invalid environment variables:')
  console.error(parsed.error.flatten().fieldErrors)
  process.exit(1)
}

export const env = parsed.data
// env.PORT is typed as number, env.DATABASE_URL is typed as string

Use `error.flatten()` on the `ZodError`. It returns `{ fieldErrors: Record<string, string[]>, formErrors: string[] }`. Field errors are keyed by the field path (e.g., `{ email: ['Invalid email address'] }`). If you are using React Hook Form with `zodResolver`, this mapping happens automatically — the resolver converts Zod errors into React Hook Form's error format and populates `formState.errors` for you.

Originally published at wowhow.cloud

GitHub Actions CI/CD: Build a Complete Node.js Pipeline (2026)

Anup Karanjkar — Thu, 21 May 2026 18:00:08 +0000

A CI/CD pipeline that catches bugs before deploy, builds reproducible Docker images, and ships to production with zero downtime is table stakes for any serious Node.js project. GitHub Actions makes all of this achievable with YAML configuration — but the defaults are slow, insecure, and fragile. This guide shows you every pattern you need, from caching to rollback.

Looking for production-ready Node.js templates? Browse WOWHOW Tools and the full product catalog for starter kits with CI/CD baked in.

Workflow Basics

Every workflow lives in .github/workflows/. The file name becomes the workflow name in the UI. Events trigger runs; jobs define what runs; steps are the individual commands.

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

# cancel in-progress runs for the same branch
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    name: Test
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - run: npm ci
      - run: npm run lint
      - run: npm test -- --coverage

Matrix Builds: Test Across Node Versions

jobs:
  test-matrix:
    name: Test Node ${{ matrix.node }} / ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        node: ['20', '22']
        os: [ubuntu-24.04, windows-latest]
        exclude:
          # skip windows + node 20 combination
          - os: windows-latest
            node: '20'

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

Caching for Speed

Without caching, npm ci downloads everything from npm on every run. With caching, subsequent runs skip the download entirely — cutting minutes off your pipeline.

steps:
  - uses: actions/checkout@v4

  # node setup with built-in npm cache
  - uses: actions/setup-node@v4
    with:
      node-version: '22'
      cache: 'npm'             # hashes package-lock.json automatically

  # manual cache for build artifacts (e.g. Next.js .next/cache)
  - name: Cache build artifacts
    uses: actions/cache@v4
    with:
      path: .next/cache
      key: nextjs-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.ts', '**/*.tsx') }}
      restore-keys: |
        nextjs-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}-
        nextjs-${{ runner.os }}-

  - run: npm ci
  - run: npm run build

Docker Build and Push

jobs:
  build-push:
    name: Build & Push Docker Image
    runs-on: ubuntu-24.04
    permissions:
      contents: read
      packages: write        # for GitHub Container Registry

    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=sha,prefix=sha-
            type=ref,event=branch
            type=semver,pattern={{version}}

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha        # GitHub Actions cache for layers
          cache-to: type=gha,mode=max
          build-args: |
            BUILD_DATE=${{ github.event.head_commit.timestamp }}
            GIT_SHA=${{ github.sha }}

Deploying to a VPS via SSH

deploy:
    name: Deploy to Production
    needs: [test-matrix, build-push]
    runs-on: ubuntu-24.04
    environment:
      name: production
      url: https://myapp.example.com
    if: github.ref == 'refs/heads/main'

    steps:
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USER }}
          key: ${{ secrets.VPS_SSH_KEY }}
          port: 22
          script: |
            set -e
            cd /opt/myapp

            # pull latest image
            echo "${{ secrets.GHCR_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
            docker pull ghcr.io/${{ github.repository }}:sha-${{ github.sha }}

            # snapshot last-good image before swapping
            docker tag ghcr.io/${{ github.repository }}:latest                        ghcr.io/${{ github.repository }}:last-good 2>/dev/null || true

            # atomic swap
            docker compose up -d --no-deps app
            docker image prune -f

Secrets and Environment Variables

# NEVER hardcode secrets. Use GitHub Secrets.
# Settings → Secrets and variables → Actions

jobs:
  deploy:
    steps:
      - name: Run migrations
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          REDIS_URL: ${{ secrets.REDIS_URL }}
        run: npm run db:migrate

      # pass to Docker build-arg (does NOT embed in final image layers if used correctly)
      - uses: docker/build-push-action@v6
        with:
          build-args: |
            NEXT_PUBLIC_API_URL=${{ vars.NEXT_PUBLIC_API_URL }}
          secrets: |
            DATABASE_URL=${{ secrets.DATABASE_URL }}

Reusable Workflows

Reusable workflows let you define a workflow once and call it from multiple repositories or jobs. They are the DRY principle for CI/CD.

# .github/workflows/_reusable-test.yml
on:
  workflow_call:
    inputs:
      node-version:
        required: false
        type: string
        default: '22'
    secrets:
      DATABASE_URL:
        required: true

jobs:
  test:
    runs-on: ubuntu-24.04
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: test
          POSTGRES_DB: testdb
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm test
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}

# .github/workflows/ci.yml — calling the reusable workflow
jobs:
  test:
    uses: ./.github/workflows/_reusable-test.yml
    with:
      node-version: '22'
    secrets:
      DATABASE_URL: ${{ secrets.DATABASE_URL }}

Self-Hosted Runners

# run on your own hardware for faster builds or private network access
jobs:
  deploy-internal:
    runs-on: self-hosted         # uses any runner with no labels
    # OR target specific runners:
    runs-on: [self-hosted, linux, x64, production]

    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run deploy:internal
        env:
          INTERNAL_API_URL: ${{ secrets.INTERNAL_API_URL }}

Register a self-hosted runner at Settings → Actions → Runners → New self-hosted runner. The runner process runs on your machine and polls GitHub for jobs. Label runners to control which jobs run where.

A Complete Pipeline: Test, Build, Deploy, Verify

# .github/workflows/deploy.yml
name: Deploy Production

on:
  push:
    branches: [main]

concurrency:
  group: deploy-production
  cancel-in-progress: false

jobs:
  test:
    uses: ./.github/workflows/_reusable-test.yml
    secrets: inherit

  build:
    needs: test
    runs-on: ubuntu-24.04
    outputs:
      image-tag: ${{ steps.meta.outputs.version }}
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: type=sha,prefix=sha-
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

  deploy:
    needs: build
    runs-on: ubuntu-24.04
    environment: production
    steps:
      - uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: deploy
          key: ${{ secrets.VPS_SSH_KEY }}
          script: |
            cd /opt/myapp
            IMAGE="ghcr.io/${{ github.repository }}:sha-${{ github.sha }}"
            docker pull "$IMAGE"
            IMAGE="$IMAGE" docker compose up -d --no-deps app

  verify:
    needs: deploy
    runs-on: ubuntu-24.04
    steps:
      - name: Health check
        run: |
          for i in 1 2 3 4 5; do
            STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://myapp.example.com/healthz)
            if [ "$STATUS" = "200" ]; then
              echo "Health check passed"
              exit 0
            fi
            echo "Attempt $i: got $STATUS, retrying in 10s..."
            sleep 10
          done
          echo "Health check failed after 5 attempts"
          exit 1

Use `actions/setup-node` with `cache: 'npm'` — this caches the npm global cache keyed on `package-lock.json`. Also use `npm ci` (not `npm install`) in CI — it skips the dependency resolution step, uses the lockfile directly, and is 2–3x faster. For monorepos, cache the individual package directories with `actions/cache` using a hash of all `package-lock.json` files as the key.

Originally published at wowhow.cloud

SQL Performance: Indexing, Query Tuning & Explain Plans (Developer Guide)

Anup Karanjkar — Thu, 21 May 2026 16:00:15 +0000

A missing index on a foreign key column can turn a 5ms query into a 5-second table scan. A correlated subquery in a WHERE clause can multiply your query time by the number of rows. An ORM that generates N+1 queries can bring down a production API under moderate load. SQL performance problems are almost always fixable — the hard part is knowing where to look. This guide is that map.

All examples use PostgreSQL 16 syntax. The concepts apply to MySQL, SQLite, and most relational databases.

How PostgreSQL Picks a Query Plan

Before optimizing, understand what the planner does. PostgreSQL maintains statistics about tables and uses a cost-based optimizer to choose among many possible query plans. It estimates row counts, considers available indexes, and picks the plan with the lowest estimated cost. The planner is usually right — when it is wrong, it is almost always because statistics are stale or misleading.

-- always run ANALYZE before investigating slow queries
ANALYZE orders;

-- basic EXPLAIN (shows plan, no execution)
EXPLAIN SELECT * FROM orders WHERE customer_id = 42;

-- EXPLAIN ANALYZE (runs the query, shows actual vs estimated rows)
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT o.id, o.total, c.email
FROM orders o
JOIN customers c ON c.id = o.customer_id
WHERE o.status = 'pending'
  AND o.created_at > NOW() - INTERVAL '7 days';

The output to look for: Seq Scan (table scan — usually bad on large tables), Index Scan (good), Bitmap Index Scan (good for low selectivity), and Hash Join vs Nested Loop vs Merge Join. A large discrepancy between "rows estimated" and "rows actual" means the planner has bad statistics.

B-Tree Indexes: The Foundation

-- basic single-column index
CREATE INDEX idx_orders_customer_id ON orders (customer_id);

-- index on a frequently filtered status column
CREATE INDEX idx_orders_status ON orders (status);

-- partial index — only index the rows you actually query
-- much smaller, faster to maintain
CREATE INDEX idx_orders_pending ON orders (created_at)
WHERE status = 'pending';

-- unique index (enforces uniqueness + faster lookups)
CREATE UNIQUE INDEX idx_users_email ON users (lower(email));

-- expression index — index a computed value
CREATE INDEX idx_users_email_lower ON users (lower(email));
-- now this query uses the index:
-- SELECT * FROM users WHERE lower(email) = 'user@example.com';

Composite Indexes: Column Order Matters

A composite index on (a, b, c) can satisfy queries on a, a, b, and a, b, c — but NOT on b alone or c alone. The leading column rule is the most commonly misunderstood fact about composite indexes.

-- this index supports:
-- WHERE status = 'pending'                          ✓
-- WHERE status = 'pending' AND created_at > ...    ✓
-- WHERE status = 'pending' AND created_at > ... AND customer_id = 42  ✓
-- WHERE created_at > ...                            ✗ (can't skip status)
CREATE INDEX idx_orders_status_created_customer
  ON orders (status, created_at, customer_id);

-- covering index — includes all columns the query needs, zero heap fetches
CREATE INDEX idx_orders_covering ON orders (customer_id, status)
INCLUDE (total, created_at);

-- query that uses the covering index with no heap access:
SELECT total, created_at
FROM orders
WHERE customer_id = 42 AND status = 'shipped';

Reading EXPLAIN ANALYZE Output

EXPLAIN (ANALYZE, BUFFERS)
SELECT p.name, SUM(oi.quantity * oi.unit_price) AS revenue
FROM order_items oi
JOIN products p ON p.id = oi.product_id
WHERE oi.created_at BETWEEN '2026-01-01' AND '2026-03-31'
GROUP BY p.id, p.name
ORDER BY revenue DESC
LIMIT 20;

/*
 Sample output sections to read:

 -> Hash Join  (cost=1234.56..5678.90 rows=10000 width=48)
              (actual time=45.123..98.456 rows=8734 loops=1)
   Hash Cond: (oi.product_id = p.id)
   Buffers: shared hit=1023 read=234

   -> Bitmap Heap Scan on order_items oi
         (actual time=12.3..34.5 rows=92345 loops=1)
      Recheck Cond: (created_at BETWEEN ...)
      ->  Bitmap Index Scan on idx_oi_created_at
            (actual time=8.9..8.9 rows=92345 loops=1)

 Planning Time: 2.1 ms
 Execution Time: 102.3 ms
*/

Key metrics: actual time is the real wall time. rows discrepancy is your optimization signal. Buffers: read=N means disk I/O — large values indicate missing indexes or cold cache.

Eliminating N+1 Queries

The N+1 problem happens when you fetch a list of records, then run one query per record to fetch related data. In SQL, the fix is always a JOIN.

-- BAD: 1 query for orders + N queries for customers
SELECT * FROM orders WHERE status = 'pending';
-- then for each order:
SELECT * FROM customers WHERE id = ?;

-- GOOD: single query with JOIN
SELECT
  o.id,
  o.total,
  o.created_at,
  c.id         AS customer_id,
  c.email      AS customer_email,
  c.first_name,
  c.last_name
FROM orders o
JOIN customers c ON c.id = o.customer_id
WHERE o.status = 'pending'
ORDER BY o.created_at DESC;

-- fetching nested aggregates without N+1
-- BAD: separate query per order for item count
SELECT * FROM orders WHERE created_at > NOW() - INTERVAL '30 days';
-- then: SELECT COUNT(*) FROM order_items WHERE order_id = ?

-- GOOD: aggregate in JOIN
SELECT
  o.id,
  o.total,
  COUNT(oi.id)              AS item_count,
  SUM(oi.quantity)          AS total_units
FROM orders o
LEFT JOIN order_items oi ON oi.order_id = o.id
WHERE o.created_at > NOW() - INTERVAL '30 days'
GROUP BY o.id, o.total
ORDER BY o.created_at DESC;

CTEs vs Subqueries

-- subquery in FROM (derived table) — planner can inline and optimize
SELECT p.name, revenue_data.total_revenue
FROM products p
JOIN (
  SELECT product_id, SUM(quantity * unit_price) AS total_revenue
  FROM order_items
  WHERE created_at > NOW() - INTERVAL '90 days'
  GROUP BY product_id
) revenue_data ON revenue_data.product_id = p.id
ORDER BY revenue_data.total_revenue DESC;

-- CTE — cleaner syntax, same performance in Postgres 12+
-- (CTEs are now inlined by default unless MATERIALIZED is specified)
WITH revenue_by_product AS (
  SELECT
    product_id,
    SUM(quantity * unit_price) AS total_revenue,
    COUNT(DISTINCT order_id)   AS order_count
  FROM order_items
  WHERE created_at > NOW() - INTERVAL '90 days'
  GROUP BY product_id
),
top_products AS (
  SELECT product_id, total_revenue, order_count
  FROM revenue_by_product
  WHERE total_revenue > 1000
)
SELECT p.name, tp.total_revenue, tp.order_count
FROM top_products tp
JOIN products p ON p.id = tp.product_id
ORDER BY tp.total_revenue DESC
LIMIT 50;

-- force materialization when the CTE result is expensive + reused
WITH MATERIALIZED expensive_aggregation AS (
  SELECT customer_id, AVG(total) AS avg_order_value
  FROM orders
  WHERE created_at > NOW() - INTERVAL '1 year'
  GROUP BY customer_id
)
SELECT c.email, ea.avg_order_value
FROM expensive_aggregation ea
JOIN customers c ON c.id = ea.customer_id
WHERE ea.avg_order_value > 200;

Window Functions

Window functions compute a value across a set of rows related to the current row — without collapsing them into a single GROUP BY result. They are one of the most powerful SQL features for analytics.

-- running total
SELECT
  created_at::date      AS date,
  SUM(total)            AS daily_revenue,
  SUM(SUM(total)) OVER (
    ORDER BY created_at::date
    ROWS UNBOUNDED PRECEDING
  )                     AS cumulative_revenue
FROM orders
WHERE created_at >= '2026-01-01'
GROUP BY created_at::date
ORDER BY date;

-- rank products by revenue within each category
SELECT
  p.name,
  p.category,
  SUM(oi.quantity * oi.unit_price)          AS revenue,
  RANK() OVER (
    PARTITION BY p.category
    ORDER BY SUM(oi.quantity * oi.unit_price) DESC
  )                                          AS rank_in_category
FROM products p
JOIN order_items oi ON oi.product_id = p.id
GROUP BY p.id, p.name, p.category
ORDER BY p.category, rank_in_category;

-- compare to previous period (LAG)
SELECT
  month,
  revenue,
  LAG(revenue) OVER (ORDER BY month)  AS prev_month_revenue,
  ROUND(
    (revenue - LAG(revenue) OVER (ORDER BY month))
    / NULLIF(LAG(revenue) OVER (ORDER BY month), 0) * 100,
    2
  )                                     AS pct_change
FROM (
  SELECT
    DATE_TRUNC('month', created_at) AS month,
    SUM(total)                      AS revenue
  FROM orders
  GROUP BY 1
) monthly
ORDER BY month;

-- deduplicate: keep latest record per customer
SELECT DISTINCT ON (customer_id)
  customer_id, id AS order_id, created_at, total
FROM orders
ORDER BY customer_id, created_at DESC;

Index Maintenance

-- find unused indexes (waste space, slow writes)
SELECT
  schemaname,
  tablename,
  indexname,
  idx_scan,
  pg_size_pretty(pg_relation_size(indexrelid)) AS index_size
FROM pg_stat_user_indexes
WHERE idx_scan = 0
  AND indexrelname NOT LIKE 'pg_%'
ORDER BY pg_relation_size(indexrelid) DESC;

-- find missing indexes on foreign keys
SELECT
  tc.table_name,
  kcu.column_name,
  ccu.table_name AS references_table
FROM information_schema.table_constraints tc
JOIN information_schema.key_column_usage kcu
  ON tc.constraint_name = kcu.constraint_name
JOIN information_schema.constraint_column_usage ccu
  ON tc.constraint_name = ccu.constraint_name
WHERE tc.constraint_type = 'FOREIGN KEY'
  AND NOT EXISTS (
    SELECT 1 FROM pg_indexes
    WHERE tablename = tc.table_name
      AND indexdef LIKE '%' || kcu.column_name || '%'
  );

-- rebuild bloated indexes concurrently (no table lock)
REINDEX INDEX CONCURRENTLY idx_orders_customer_id;

EXPLAIN shows the query plan the planner would use — it does not execute the query. EXPLAIN ANALYZE actually runs the query and shows both the estimated and actual row counts and timings. Always use EXPLAIN ANALYZE with BUFFERS (`EXPLAIN (ANALYZE, BUFFERS)`) when debugging performance issues so you can see disk I/O. Be careful: EXPLAIN ANALYZE on a DELETE or UPDATE will actually execute those statements, so wrap them in a transaction you roll back if needed.

Originally published at wowhow.cloud

Web Scraping with Node.js: Puppeteer vs Cheerio (Complete 2026 Guide)

Anup Karanjkar — Thu, 21 May 2026 16:00:10 +0000

Web scraping is one of those skills that looks simple until you hit your first JavaScript-rendered page, your first CAPTCHA, or your first IP ban. Cheerio handles 70% of scraping tasks with almost zero overhead. Puppeteer handles the rest. This guide covers both in depth — when to use each, how to build scrapers that survive real sites, and how to extract structured data reliably at scale.

If you are building data pipelines or automation workflows, check out the WOWHOW Tools library for pre-built utilities, and browse the full catalog for data engineering starter kits.

Cheerio: Fast Static Scraping

Cheerio loads raw HTML and gives you a jQuery-like API to query it. No browser, no JavaScript execution — just a DOM parser. It is 10–50x faster than Puppeteer for static pages and uses a fraction of the memory.

import * as cheerio from 'cheerio'

async function scrapeHackerNews(url: string) {
  const response = await fetch(url, {
    headers: {
      'User-Agent': 'Mozilla/5.0 (compatible; research-bot/1.0)',
    },
  })
  const html = await response.text()
  const $ = cheerio.load(html)

  const stories: Array = []

  $('.athing').each((i, el) => {
    const rank = parseInt($(el).find('.rank').text().replace('.', ''), 10)
    const titleEl = $(el).find('.titleline > a').first()
    const title = titleEl.text().trim()
    const href = titleEl.attr('href') ?? ''

    // points are in the NEXT sibling row
    const subtext = $(el).next('.spacer').next()
    const points = parseInt(subtext.find('.score').text(), 10) || 0

    stories.push({ rank, title, url: href, points })
  })

  return stories
}

Cheerio Selector Patterns

Mastering selectors is the key skill. Here are the patterns you will use most:

import * as cheerio from 'cheerio'

function demonstrateSelectors(html: string) {
  const $ = cheerio.load(html)

  // --- attribute selectors
  const dataLinks = $('a[data-track]')           // has attribute
  const exactMatch = $('input[type="submit"]')   // exact value
  const contains   = $('[class*="product-card"]') // contains substring
  const startsWith = $('[href^="https://"]')      // starts with

  // --- positional pseudo-selectors
  const firstCard  = $('.product-card').first()
  const lastCard   = $('.product-card').last()
  const thirdCard  = $('.product-card').eq(2)    // 0-indexed
  const evenRows   = $('tr:nth-child(even)')

  // --- traversal
  const parent       = $('.price').parent()
  const closestForm  = $('input').closest('form')
  const siblings     = $('h2').siblings('p')
  const nextSibling  = $('.title').next()
  const allChildren  = $('.card').children()

  // --- extracting data
  const text    = $('h1').text().trim()
  const html2   = $('.description').html()        // inner HTML as string
  const href    = $('a.cta').attr('href')
  const allHrefs = $('a').map((_, el) => $(el).attr('href')).get()

  // --- filtering
  const nonEmpty = $('p').filter((_, el) => $(el).text().trim().length > 0)
  const withPrice = $('.item').filter((_, el) => $(el).find('.price').length > 0)

  return { text, href, allHrefs }
}

Puppeteer: Dynamic Page Scraping

Use Puppeteer when the content you need is rendered by JavaScript after page load — single-page apps, infinite scroll, lazy-loaded images, login-gated content.

import puppeteer, { type Browser, type Page } from 'puppeteer'

async function launchBrowser(): Promise {
  return puppeteer.launch({
    headless: true,
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-dev-shm-usage',
      '--disable-gpu',
    ],
  })
}

async function scrapeDynamicPage(url: string): Promise {
  const browser = await launchBrowser()
  const page = await browser.newPage()

  try {
    // block images/fonts to speed up loads
    await page.setRequestInterception(true)
    page.on('request', (req) => {
      if (['image', 'font', 'media'].includes(req.resourceType())) {
        req.abort()
      } else {
        req.continue()
      }
    })

    await page.goto(url, { waitUntil: 'networkidle2', timeout: 30_000 })

    // wait for a specific element before extracting
    await page.waitForSelector('.product-list', { timeout: 10_000 })

    // extract data in page context (runs in browser)
    const items = await page.evaluate(() => {
      return Array.from(document.querySelectorAll('.product-card')).map((el) => ({
        title: el.querySelector('.title')?.textContent?.trim() ?? '',
        price: el.querySelector('.price')?.textContent?.trim() ?? '',
        imageUrl: (el.querySelector('img') as HTMLImageElement | null)?.src ?? '',
      }))
    })

    return items
  } finally {
    await browser.close()
  }
}

Handling Infinite Scroll

async function scrapeInfiniteScroll(page: Page): Promise {
  const results: string[] = []
  let previousHeight = 0

  while (true) {
    // extract items currently visible
    const newItems = await page.evaluate(() =>
      Array.from(document.querySelectorAll('.item-title')).map(
        (el) => el.textContent?.trim() ?? ''
      )
    )
    results.push(...newItems.slice(results.length))

    // scroll to bottom
    await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight))
    await new Promise((r) => setTimeout(r, 1500)) // wait for load

    const newHeight = await page.evaluate(() => document.body.scrollHeight)
    if (newHeight === previousHeight) break // no more content
    previousHeight = newHeight
  }

  return [...new Set(results)] // deduplicate
}

Rate Limiting — The Most Important Part

Scraping without rate limiting will get you banned. Treat rate limiting as mandatory, not optional.

class RateLimiter {
  private queue: Array void> = []
  private running = 0

  constructor(
    private readonly maxConcurrent: number,
    private readonly minDelayMs: number,
    private readonly maxDelayMs: number
  ) {}

  async acquire(): Promise void> {
    if (this.running >= this.maxConcurrent) {
      await new Promise((resolve) => this.queue.push(resolve))
    }
    this.running++

    // jitter: random delay between min and max
    const delay =
      this.minDelayMs + Math.random() * (this.maxDelayMs - this.minDelayMs)
    await new Promise((r) => setTimeout(r, delay))

    return () => {
      this.running--
      this.queue.shift()?.()
    }
  }
}

// usage
const limiter = new RateLimiter(2, 1000, 3000) // max 2 concurrent, 1-3s delay

async function fetchWithRateLimit(url: string): Promise {
  const release = await limiter.acquire()
  try {
    const res = await fetch(url)
    if (!res.ok) throw new Error(`HTTP \${res.status}`)
    return res.text()
  } finally {
    release()
  }
}

Proxy Rotation

const proxies = [
  'http://proxy1.example.com:8080',
  'http://proxy2.example.com:8080',
  'http://proxy3.example.com:8080',
]

function getProxy(): string {
  return proxies[Math.floor(Math.random() * proxies.length)]
}

// with Puppeteer
async function launchWithProxy(proxy: string): Promise {
  return puppeteer.launch({
    headless: true,
    args: [`--proxy-server=\${proxy}`, '--no-sandbox'],
  })
}

// with fetch (via undici or https-proxy-agent)
import { ProxyAgent, fetch as undiciFetch } from 'undici'

async function fetchViaProxy(url: string): Promise {
  const proxy = getProxy()
  const dispatcher = new ProxyAgent(proxy)
  const res = await undiciFetch(url, { dispatcher })
  return res.text()
}

Retry Logic with Exponential Backoff

async function withRetry(
  fn: () => Promise,
  maxAttempts = 3,
  baseDelayMs = 1000
): Promise {
  for (let attempt = 1; attempt  setTimeout(r, delay + jitter))
    }
  }
  throw new Error('unreachable')
}

// usage
const html = await withRetry(() => fetchWithRateLimit(url))

Structured Data Extraction with Zod Validation

import { z } from 'zod'
import * as cheerio from 'cheerio'

const ProductSchema = z.object({
  id: z.string(),
  title: z.string().min(1),
  price: z.number().positive(),
  currency: z.string().length(3),
  inStock: z.boolean(),
  imageUrl: z.string().url().nullable(),
})

type Product = z.infer

function extractProduct(el: cheerio.Cheerio, $: cheerio.CheerioAPI): Product {
  const priceText = $(el).find('[data-price]').attr('data-price') ?? '0'

  const raw = {
    id: $(el).attr('data-product-id') ?? '',
    title: $(el).find('.product-title').text().trim(),
    price: parseFloat(priceText),
    currency: $(el).find('[data-currency]').attr('data-currency') ?? 'USD',
    inStock: $(el).find('.stock-badge').text().includes('In Stock'),
    imageUrl: $(el).find('img').attr('src') ?? null,
  }

  return ProductSchema.parse(raw) // throws ZodError if invalid
}

Choosing Between Puppeteer and Cheerio

Use Cheerio when: the HTML you need is in the initial response body, you need speed, or you are running many concurrent requests. Use Puppeteer when: content is loaded by JavaScript after initial render, you need to interact with the page (click, scroll, fill forms), or you need to handle authentication flows.

A common pattern is to use Cheerio first, and fall back to Puppeteer only when the Cheerio output is empty — this gives you fast paths for static pages and automatic fallback for dynamic ones.

`networkidle0` waits until there are zero network connections for 500ms — good for pages that stop all requests when fully loaded. `networkidle2` waits until there are at most 2 connections for 500ms — better for pages that maintain persistent WebSocket or polling connections. Use `networkidle2` as the default and only switch to `networkidle0` if you know the page fully quiesces.

Originally published at wowhow.cloud

Build Your First MCP Server in TypeScript: Claude Code Integration Guide

Anup Karanjkar — Thu, 21 May 2026 15:40:41 +0000

The Model Context Protocol (MCP) crossed 9,400 registered servers in early May 2026. Every one of those servers unlocks a new capability inside Claude Code — file access, database queries, API calls, custom tool chains. Building your own MCP server is the fastest way to make Claude Code understand your stack, your data, and your workflows. This guide walks you through a complete, working server in TypeScript from zero to a running integration.

MCP is a JSON-RPC 2.0-based protocol that lets Claude Code call external tools, read resources, and use pre-built prompt templates. The server you build runs as a local process. Claude Code spawns it via stdio or connects via HTTP+SSE. The protocol has three capability types: tools (functions Claude can call), resources (data Claude can read), and prompts (reusable templates). You will build a server that exposes all three.

What We Are Building

A database introspection server. Claude Code will be able to: list tables in a SQLite database (tool), read table schemas (resource), and use a pre-built prompt template for generating migration scripts. By the end you will have a fully functional MCP server you can extend for any data source.

Find ready-made developer toolkits at WOWHOW Browse and TypeScript starter kits at WOWHOW Tools.

Project Setup

mkdir mcp-db-server && cd mcp-db-server
npm init -y
npm install @modelcontextprotocol/sdk better-sqlite3 zod
npm install -D typescript @types/node @types/better-sqlite3 tsx
npx tsc --init --target ES2022 --module Node16 --moduleResolution Node16 --strict --outDir dist

The @modelcontextprotocol/sdk package handles all protocol framing, message routing, and capability negotiation. You write handlers; the SDK handles the wire protocol.

Server Entry Point

// src/index.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import {
  CallToolRequestSchema,
  ListResourcesRequestSchema,
  ListToolsRequestSchema,
  ReadResourceRequestSchema,
  GetPromptRequestSchema,
  ListPromptsRequestSchema,
} from '@modelcontextprotocol/sdk/types.js'
import Database from 'better-sqlite3'
import { z } from 'zod'
import path from 'node:path'

// --- create the server instance
const server = new Server(
  { name: 'db-introspection-server', version: '1.0.0' },
  {
    capabilities: {
      tools: {},
      resources: {},
      prompts: {},
    },
  }
)

// --- open database (path from env or default)
const DB_PATH = process.env.DB_PATH ?? path.join(process.cwd(), 'dev.sqlite')
const db = new Database(DB_PATH, { readonly: true })

export { server, db }

Defining Tools

Tools are functions Claude Code can invoke. Each tool has a name, description, and a JSON Schema for its input parameters. The SDK validates inputs against the schema before calling your handler.

// src/tools.ts
import { server, db } from './index.js'
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from '@modelcontextprotocol/sdk/types.js'

// --- list available tools
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'list_tables',
      description: 'List all tables in the SQLite database with row counts',
      inputSchema: {
        type: 'object',
        properties: {},
        required: [],
      },
    },
    {
      name: 'query_table',
      description: 'Run a SELECT query on a specific table (read-only)',
      inputSchema: {
        type: 'object',
        properties: {
          table: {
            type: 'string',
            description: 'Name of the table to query',
          },
          limit: {
            type: 'number',
            description: 'Maximum rows to return (default 10, max 100)',
            default: 10,
          },
          where: {
            type: 'string',
            description: 'Optional WHERE clause (without the WHERE keyword)',
          },
        },
        required: ['table'],
      },
    },
    {
      name: 'describe_table',
      description: 'Get column definitions and indexes for a table',
      inputSchema: {
        type: 'object',
        properties: {
          table: { type: 'string', description: 'Table name' },
        },
        required: ['table'],
      },
    },
  ],
}))

// --- call tool handler
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params

  switch (name) {
    case 'list_tables': {
      const tables = db
        .prepare(
          `SELECT name, (SELECT COUNT(*) FROM main.\`\${name}\`) AS row_count
           FROM sqlite_master WHERE type='table' ORDER BY name`
        )
        .all() as Array

      return {
        content: [
          {
            type: 'text',
            text: tables
              .map((t) => `\${t.name} (\${t.row_count} rows)`)
              .join('\n'),
          },
        ],
      }
    }

    case 'query_table': {
      const schema = z.object({
        table: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/),
        limit: z.number().int().min(1).max(100).default(10),
        where: z.string().optional(),
      })
      const { table, limit, where } = schema.parse(args)

      const sql = where
        ? `SELECT * FROM \`\${table}\` WHERE \${where} LIMIT \${limit}`
        : `SELECT * FROM \`\${table}\` LIMIT \${limit}`

      const rows = db.prepare(sql).all()
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(rows, null, 2),
          },
        ],
      }
    }

    case 'describe_table': {
      const schema = z.object({
        table: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/),
      })
      const { table } = schema.parse(args)

      const columns = db.prepare(`PRAGMA table_info(\`\${table}\`)`).all()
      const indexes = db.prepare(`PRAGMA index_list(\`\${table}\`)`).all()
      const foreignKeys = db.prepare(`PRAGMA foreign_key_list(\`\${table}\`)`).all()

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({ columns, indexes, foreignKeys }, null, 2),
          },
        ],
      }
    }

    default:
      throw new Error(`Unknown tool: \${name}`)
  }
})

Defining Resources

Resources are data Claude can read — think of them as files or URLs your server exposes. They are listed via resources/list and fetched via resources/read.

// src/resources.ts
import { server, db } from './index.js'
import {
  ListResourcesRequestSchema,
  ReadResourceRequestSchema,
} from '@modelcontextprotocol/sdk/types.js'

server.setRequestHandler(ListResourcesRequestSchema, async () => {
  const tables = db
    .prepare(`SELECT name FROM sqlite_master WHERE type='table' ORDER BY name`)
    .all() as Array

  return {
    resources: tables.map((t) => ({
      uri: `db://schema/\${t.name}`,
      name: `Schema: \${t.name}`,
      description: `Full DDL and column info for table \${t.name}`,
      mimeType: 'application/json',
    })),
  }
})

server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  const { uri } = request.params
  const match = uri.match(/^db:\/\/schema\/([a-zA-Z_][a-zA-Z0-9_]*)$/)
  if (!match) throw new Error(`Unsupported resource URI: \${uri}`)

  const table = match[1]
  const ddl = db
    .prepare(`SELECT sql FROM sqlite_master WHERE type='table' AND name=?`)
    .get(table) as { sql: string } | undefined

  if (!ddl) throw new Error(`Table not found: \${table}`)

  const columns = db.prepare(`PRAGMA table_info(\`\${table}\`)`).all()
  const indexes = db.prepare(`PRAGMA index_list(\`\${table}\`)`).all()

  return {
    contents: [
      {
        uri,
        mimeType: 'application/json',
        text: JSON.stringify({ ddl: ddl.sql, columns, indexes }, null, 2),
      },
    ],
  }
})

Defining Prompt Templates

Prompts are reusable templates that surface inside Claude Code's slash-command picker. They can accept arguments and return pre-built message arrays.

// src/prompts.ts
import { server, db } from './index.js'
import {
  ListPromptsRequestSchema,
  GetPromptRequestSchema,
} from '@modelcontextprotocol/sdk/types.js'
import { z } from 'zod'

server.setRequestHandler(ListPromptsRequestSchema, async () => ({
  prompts: [
    {
      name: 'generate_migration',
      description: 'Generate a SQL migration script to add a column to a table',
      arguments: [
        { name: 'table', description: 'Target table name', required: true },
        { name: 'column', description: 'New column definition (e.g. email TEXT NOT NULL DEFAULT \'\')', required: true },
      ],
    },
  ],
}))

server.setRequestHandler(GetPromptRequestSchema, async (request) => {
  const { name, arguments: promptArgs } = request.params

  if (name === 'generate_migration') {
    const schema = z.object({
      table: z.string(),
      column: z.string(),
    })
    const { table, column } = schema.parse(promptArgs ?? {})

    const existingSchema = db
      .prepare(`SELECT sql FROM sqlite_master WHERE type='table' AND name=?`)
      .get(table) as { sql: string } | undefined

    const context = existingSchema
      ? `Existing DDL:\n\${existingSchema.sql}`
      : `Table '\${table}' not found. Generate a CREATE TABLE + ALTER TABLE migration.`

    return {
      messages: [
        {
          role: 'user' as const,
          content: {
            type: 'text' as const,
            text: `Generate a safe, idempotent SQLite migration to add '\${column}' to '\${table}'.

\${context}

Requirements:
- Use ALTER TABLE ... ADD COLUMN
- Include a rollback section (DROP COLUMN if SQLite version supports it)
- Add a comment with the date: \${new Date().toISOString().split('T')[0]}
- Wrap in a transaction`,
          },
        },
      ],
    }
  }

  throw new Error(`Unknown prompt: \${name}`)
})

Wiring Everything Together and Starting the Server

// src/main.ts
import './tools.js'
import './resources.js'
import './prompts.js'
import { server } from './index.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

async function main() {
  const transport = new StdioServerTransport()
  await server.connect(transport)
  // server is now listening on stdin/stdout
}

main().catch((err) => {
  process.stderr.write(`Fatal: \${err.message}\n`)
  process.exit(1)
})

Registering with Claude Code

Add the server to your ~/.claude.json (global) or project-level .claude.json:

{
  "mcpServers": {
    "db-introspection": {
      "command": "node",
      "args": ["dist/main.js"],
      "env": {
        "DB_PATH": "/path/to/your/dev.sqlite"
      }
    }
  }
}

Then build and restart Claude Code:

npx tsc
# restart Claude Code — it spawns the server fresh each session

Claude Code will now show your tools in its tool picker and your tables as readable resources.

Testing Without Claude Code

Use the MCP inspector for quick iteration:

npx @modelcontextprotocol/inspector node dist/main.js
# Opens a browser UI at http://localhost:5173
# Call tools, read resources, test prompts interactively

You can also write unit tests directly against your handler functions since they are plain async functions — no need to spin up the full server for logic tests.

Error Handling and Production Hardening

// wrap every handler to catch unexpected errors
function safeHandler(
  handler: (req: T) => Promise
): (req: T) => Promise {
  return async (req) => {
    try {
      return await handler(req)
    } catch (err) {
      const message = err instanceof Error ? err.message : String(err)
      // MCP errors surface as structured error responses
      throw Object.assign(new Error(message), { code: -32000 })
    }
  }
}

Use the `env` field in the server config to inject environment variables — pull values from your shell's existing env rather than hardcoding them. For team setups, use a secrets manager and inject at process startup. Never commit API keys or database credentials inside `.claude.json`.

Originally published at wowhow.cloud

Alibaba Merges Qwen AI with Taobao: Agentic Shopping Hits 4 Billion Products

Anup Karanjkar — Thu, 21 May 2026 15:30:14 +0000

Agentic shopping just went from a demo slide to the world's largest e-commerce platform. On May 11, 2026, Reuters and multiple Asian tech outlets confirmed that Alibaba is integrating its Qwen AI app directly into Taobao and Tmall — its two largest consumer marketplaces — to launch what the company calls an "end-to-end agentic shopping" experience. A shopper opens Qwen, describes what they want, and the AI agent searches, compares sellers, runs virtual try-ons, monitors a 30-day price track, and completes checkout through Alipay. The only human step is the final payment confirmation. This is not a chatbot bolted onto a search bar. It is a full AI-native shopping loop running over four billion products, built by the same team behind one of the world's leading open-weight model families. Here is what is actually happening, how it works, and why it matters well beyond China.

What Is Qwen, and Why Does This Integration Matter

Qwen is Alibaba's flagship AI model family, developed by the Tongyi Lab team. The Qwen 3 series — including the Qwen3-6-Max Preview that generated significant developer attention in early 2026 — has established itself as one of the most capable open-weight model families in the world, competitive with GPT-5.5 and Claude Opus 4.7 on specific reasoning and coding benchmarks. Alibaba releases most Qwen variants under Apache 2.0, making them freely deployable for commercial use. The Qwen app is the consumer product built on top of these models, roughly analogous to ChatGPT for OpenAI.

What makes this integration remarkable is not that Alibaba built a capable AI — that was already known — but that it is directly wiring that AI into the infrastructure of a platform with more than one billion registered users and four billion product listings. The Qwen app gains access to the entire Taobao-Tmall catalogue plus a layer of Alibaba-built skills handling logistics, customer service, and after-sales workflows. It is the kind of vertical integration that is almost impossible to replicate from scratch: a frontier model, a consumer app, a payment layer (Alipay), and the world's largest inventory of goods, all owned by a single company.

The End-to-End Agentic Shopping Experience

Here is what the experience looks like from a user's perspective, based on early documentation and reports from TechNode and Inside Retail Asia:

Step 1: Natural-Language Discovery

The user opens Qwen and types or speaks a request: "Find me a lightweight running jacket under 400 yuan that fits a size M and ships before Friday." Qwen treats this as an agentic task, not a keyword query. It extracts intent, constraints, and time requirements, then issues structured queries against the Taobao-Tmall catalogue API.

Step 2: Multi-Seller Comparison

Rather than returning a ranked list of ten options and leaving comparison to the user, the agent evaluates sellers on price, returns policy, delivery speed, and review sentiment, then surfaces a shortlist of two or three candidates with an explicit rationale. The output is structured enough to act on but transparent enough to override.

Step 3: Virtual Try-On

For apparel, footwear, and accessories, Qwen can trigger a virtual try-on using a previously uploaded user photo or a real-time camera capture. The try-on layer is powered by Alibaba's existing Pailitao visual AI infrastructure, which has been running in Taobao since 2023, now surfaced through a conversational interface rather than a standalone feature buried in the app.

Step 4: 30-Day Price Tracking

If the agent determines the item has been cheaper recently, it surfaces this and can schedule an automatic alert or a delayed purchase for when the price drops. This is a task that previously required a separate browser extension or deliberate effort from the user. In the agentic model, it is a default behavior the agent initiates without being asked.

Step 5: End-to-End Checkout

The transaction completes through Alipay. The agent handles cart management, address selection, coupon application, and payment initiation. The user receives a single confirmation prompt before money moves. Alibaba's design explicitly keeps the human in the loop at the payment step — a deliberate trust boundary that reflects both regulatory caution and user research about how much autonomy consumers are comfortable delegating.

Post-purchase, the agent can handle logistics queries ("where is my package?"), initiate return requests, and manage after-sales communications with the seller, all within the same Qwen interface.

The Scale Numbers That Make This Different

The Alibaba-Qwen integration is not the first attempt at AI-powered shopping. Amazon has been running AI recommendation layers for years. Google Shopping has integrated Gemini for search refinement. Shopify launched agentic commerce features for merchants in early 2026. What makes this different is the scale at which it is launching.

Qwen reached 300 million monthly active users across Taobao, Tmall, Alipay, and other Alibaba consumer surfaces by Q1 2026. During the Chinese New Year campaign — one of the heaviest e-commerce windows globally — approximately 140 million users logged their first AI-assisted shopping experience on Alibaba platforms. The platform being integrated into has more than four billion product listings across millions of active sellers. The payment layer (Alipay) processes over 100 million transactions per day at peak periods.

Most AI shopping experiments run over hundreds of thousands of SKUs in controlled pilots. This one starts at four billion. It is the largest real-world test of agentic commerce that has ever been attempted, and the infrastructure it is running on has already been load-tested at a scale no Western competitor has matched.

How the Agentic Pipeline Works: The Technical Picture

Alibaba has not released full technical documentation, but the architectural pattern described in developer briefings follows the agent-with-skills model that has become the dominant paradigm in 2026.

Qwen acts as the orchestrator: it receives user intent, plans the sequence of subtasks, and calls specialized skills for each step. The skills are purpose-built API wrappers that have access to Taobao catalogue search, seller reputation scoring, visual search, try-on rendering, price history databases, Alipay payment APIs, and logistics tracking. This is the same architecture described in the Microsoft Agent 365 enterprise control plane and increasingly standard across production agentic systems in 2026.

What Alibaba has built — and what makes it difficult to replicate quickly — is the skill layer. Each skill represents years of API development, data quality work, and operational hardening. The virtual try-on skill alone has been trained on hundreds of millions of product images and refined through billions of user interactions on Taobao. Connecting Qwen to these skills is valuable precisely because the skills themselves are mature.

The shopping agent also uses Alibaba's internal memory infrastructure to personalize across sessions: it knows a user's size preferences, past purchases, and stated preferences, and uses these to narrow its initial search without requiring the user to repeat contextual details each time. This is the kind of persistent, cross-session state management that turns a capable demo into a genuinely useful product.

The Competitive Landscape: How This Changes the Game

Alibaba's move comes in a week when agentic commerce is accelerating globally. Amazon has been integrating Alexa+ with its shopping infrastructure since late 2025, though its agentic capabilities remain more constrained on the discovery and comparison side. Google's Gemini integration into Google Shopping offers strong multimodal search but lacks the payment-through-completion that Alibaba is building. Shopify's agentic commerce features are merchant-facing — they help sellers configure AI-powered storefronts, but the buyer-side experience is still mediated through traditional checkout flows.

The company that has come closest to Alibaba's approach is Perplexity, which launched a buy-side commerce agent in 2025 that can complete purchases through Shopify's checkout API. But Perplexity operates across a fragmented set of merchant integrations, while Alibaba operates within a single unified platform. The difference in coverage, data quality, and operational control is significant.

For Western platforms, the question raised by Alibaba's move is whether the fragmented nature of Western e-commerce — spread across Amazon, Shopify merchants, Target, Walmart, and thousands of DTC sites — can ever support the kind of deeply integrated agentic experience that a single-platform operator can build. MCP (Model Context Protocol) has emerged as the interoperability standard that could allow an agent like ChatGPT or Claude to act across multiple retailer APIs using a common interface, as explored in the MCP developer guide. But protocol-level integration is a decade behind proprietary integration in terms of capability and reliability.

What Developers and Commerce Teams Should Take Away

If you are building shopping, commerce, or marketplace products in 2026, the Alibaba move signals several shifts worth acting on:

Agentic commerce is production, not R&D. Alibaba is not running a lab experiment. It is deploying agentic shopping to 300 million users on the world's largest e-commerce platform. The pattern is validated at scale. Teams that are still treating AI shopping as a future capability are behind.
The trust boundary at payment is the right design call. Alibaba explicitly keeps the human in the loop at payment confirmation. This is the correct answer to the "how much autonomy do you grant the agent?" question for high-stakes financial transactions. Build your agentic commerce flows with the same explicit confirmation step.
Skills quality matters more than model quality. Qwen's model capabilities are impressive but not uniquely so. What makes the integration valuable is the quality of the skills it calls: the try-on renderer, the price history database, the seller reputation scorer. If you are building an agent for commerce, the investment in high-quality, reliable skill APIs is the actual competitive moat, not the LLM choice.
Memory and personalization are the compound interest of agentic products. The persistent preference layer — knowing a user's size, style, and history — is what transforms a good first-use experience into a sticky daily habit. Build memory into agentic products from the beginning, not as a retrofit. The agent memory infrastructure landscape covers the current state of memory systems for production agents.
Vertical integration is a structural advantage, not just an efficiency gain. Alibaba's ability to move from model to app to catalogue to payment in a single agentic loop is a function of controlling all four layers. Teams building on third-party APIs face coordination friction that Alibaba simply does not have. Where vertical integration is not possible, MCP-based standardization is the next-best solution.

The Broader Signal: AI Commerce Is Compressing the Purchase Funnel

The traditional e-commerce purchase funnel — search, browse, compare, cart, checkout — was designed around human attention and choice architecture. Each step was a separate deliberate action. Agentic shopping collapses that funnel into a single natural-language statement, with the agent handling the intermediate steps autonomously.

This compression has significant implications for how merchants think about discovery, conversion, and retention. If the agent makes the comparison decision, brand presentation in traditional search results becomes less important than the structured data signals the agent uses — reviews, returns policy, seller reputation score, shipping time commitments. Merchants who optimize for these machine-readable signals will outperform merchants who optimize for human visual attention.

It also raises questions about what "shopping" means when the browsing is delegated. Part of shopping's value to consumers is not just acquisition — it is the experience of evaluation, discovery, and choice. How agentic platforms balance efficiency against the psychological value of the shopping experience will determine adoption rates among different consumer segments. Alibaba's choice to keep the try-on experience explicitly in the flow — rather than letting the agent skip it for speed — suggests they have thought carefully about this.

Conclusion

Alibaba merging Qwen with Taobao is the most significant deployment of agentic commerce in history by any reasonable metric: model capability, scale, catalogue size, and payment integration. It validates the agentic shopping architecture at a level of real-world stress that no lab demonstration can match. And it sets a competitive benchmark that every e-commerce platform, AI company, and digital commerce team now has to respond to.

The pattern Alibaba is demonstrating — frontier model as orchestrator, domain-specific skills as capabilities, payment layer as the trust boundary, persistent memory as the compound advantage — is portable. You do not need four billion products to apply it. You need a clear understanding of which skills matter in your domain, the data quality to make those skills reliable, and the architectural discipline to keep humans in the loop at the moments that matter.

Originally published at wowhow.cloud

I Keep Hermes Agent's Self-Improvement OFF For the First 14 Days — Here's What Happens When I Don't

Anup Karanjkar — Thu, 21 May 2026 15:24:37 +0000

I have published two articles praising Hermes Agent this week. This one is different. Both of those articles are accurate — Hermes is genuinely excellent at self-directed skill acquisition, and the compounding effect of the memory system is real. But the self-improvement loop is too powerful to enable on day one. Three weeks ago I ignored my own rule on a fresh VPS deployment. By day 14, eleven auto-generated skills had silently degraded my agent's output quality across three production workflows. I lost an entire evening reverting to a clean state and hand-auditing every skill file. That evening is the reason this article exists.

This is the contrarian Hermes Agent setup guide. The thesis is simple: disable auto_create and auto_refine for the first 14 days, observe how the agent actually behaves on your real workload, hand-author your first generation of skills with intention, build the rollback infrastructure you will need later, and then enable self-improvement deliberately. The compounding still happens. It just compounds toward your actual workflow rather than toward the agent's confused first-week impressions of what you do.

The Default Is a Footgun

Hermes Agent ships with self-improvement enabled. That is the right default for a demo environment, a low-stakes personal assistant, or a proof-of-concept. It is the wrong default for a production workload that touches customer data, deploys code, or handles anything with financial consequences. The default configuration assumes the agent will quickly learn what good looks like on your workload. It will learn something — but in the first week, what it observes is your onboarding confusion, your exploratory prompts, your experiments with workflow patterns you will ultimately discard. It encodes all of that as skills.

There is no single flag that cleanly disables self-improvement in the default Hermes config. You have to set it explicitly. Here is the configuration I call "training wheels on" — the starting point for every new Hermes deployment I run:

# config.yaml — Hermes Agent "training wheels on" baseline
# Use this for the first 14 days on any new workload

agent:
  name: "hermes"
  version: "2.4"

skills:
  # Disable autonomous skill creation entirely
  auto_create: false

  # Disable autonomous skill refinement (agent cannot improve its own skills)
  auto_refine: false

  # Memory stays ON — you want observation data, just not autonomous action on it
  memory_enabled: true

  # External dirs for read-only hand-written skills
  # The agent can USE these skills but cannot modify or create new ones
  external_dirs:
    - path: "/home/hermes/skills/hand-authored"
      mode: "read-only"
    - path: "/home/hermes/skills/pinned"
      mode: "read-only"

  # Auto-created skills dir exists but nothing writes to it yet
  managed_dir: "/home/hermes/skills/managed"
  managed_dir_writable: false

memory:
  observation_log: "/home/hermes/logs/observations.jsonl"
  session_summaries: true
  cross_session_retention: true

logging:
  level: "info"
  skill_invocations: true
  skill_outcomes: true

The key decisions in this config: memory stays on because you want the observation data accumulating, you just do not want the agent acting autonomously on those observations. The external_dirs section gives the agent access to your hand-authored skills through a read-only mount so it can use them immediately, but it cannot modify them. The managed directory exists but managed_dir_writable: false ensures nothing auto-generates there even if the agent tries.

Why "Delete Bad Skills Later" Doesn't Work

The most common objection I hear to this approach is: "just let it run and prune the bad skills afterward." This sounds reasonable. It does not work, for three distinct reasons.

Reason 1: Self-Congratulation Bias

The agent grades its own homework. When Hermes evaluates whether a skill it created is good, it uses the same reasoning model that created the skill in the first place. A skill that encodes a subtly wrong heuristic will generate outputs that look correct to the model that wrote the heuristic. The skill gets a high self-evaluation score. You have no external signal that something is wrong until the degradation shows up in actual output quality — which is a lagging indicator, often by days. By the time you notice the degradation, you have a week of accumulated sessions that all reinforced the bad skill.

Reason 2: The Skill Overwrite Problem

If you do write hand-authored skills and enable auto-refinement simultaneously, the agent can and will degrade your hand-authored skills. The refinement loop identifies "opportunities for improvement" based on observed usage. If the agent observes that your hand-authored skill for "deploy to production" is invoked frequently but not always successfully (because some failures are user errors, not skill errors), it may "improve" the skill by adding conditionals that change the behavior for the common-failure cases. Your carefully tested skill is now different from what you wrote. The diff is subtle. You will not notice until a deployment fails in a new way.

Reason 3: The Accumulation Rate

On a busy workload, Hermes generates approximately two to four skills per day on default settings. By day 14, you have 28 to 56 auto-generated skills. Auditing 50 skills is not a quick afternoon task — each skill requires you to understand what it encodes, test whether that encoding matches your actual intent, and decide whether to keep, modify, or delete it. In practice, most people do not do this audit. The skills accumulate. The agent's behavior drifts from what you intended, in small increments, over weeks. The drift is invisible until it is significant.

The math on why starting clean is easier: zero skills to audit on day 14, versus 28–56. The 14-day observation period also gives you the data to write skills that reflect your real workflow, not your first-week exploration of the tool.

What I Do During the 14 Days

Day 1–3: Capture the Baseline

The first three days are observation only. I run all the workflows I intend to automate through Hermes, treating the agent as a capable but un-optimized assistant. I take notes on what I am actually asking the agent to do, not what I thought I would ask it to do when I planned the deployment. These are always different.

The observation log lives in a markdown file in my project directory, not in Hermes's memory system. I want a human-readable record I can query without routing through the agent:

# hermes-observation-log.md

## Day 1 — 2026-05-01

### Workflows run:
- Deploy storefront to production (3x) — agent handled 2/3 correctly, 1 required manual intervention on Redis healthcheck
- Generate and publish blog post (2x) — worked correctly both times, agent remembered WordPress API format from session 1 to session 2
- Sync WooCommerce products from staging (1x) — FAILED: agent used wrong API version, needed correction

### Patterns noticed:
- Agent repeatedly asks clarifying question about git branch before deploys — this should be a skill default
- Agent does not know our VPS SSH key path — has to be prompted each session
- Agent remembers API format within a session but not across sessions (memory not long enough?)

### Skills that would have helped:
- skill/deploy-production: branch=main, ssh-key=/root/.ssh/deploy_key, healthcheck=redis+nextjs
- skill/wordpress-publish: api-version=v2, base-url=wordpress-app:80, auth=env:WP_APP_PASSWORD

## Day 2 — 2026-05-02

### Workflows run:
...

Three days of this log gives you something valuable: the real list of skills your deployment actually needs, derived from observation rather than upfront planning. The list is always shorter than you expected and more specific than any default skill set would produce.

Day 4–10: Hand-Author the First Generation

With three days of observation data, I write skills manually. Every skill I write follows a fixed template with YAML frontmatter, a procedure section, a pitfalls section, and a verification block. The verification block is non-negotiable — it is what makes skill quality objectively measurable rather than subjective:

---
skill_id: deploy-production
version: 1.0.0
author: anup
created: 2026-05-04
pinned: false
no_auto_refine: false
tags: [deploy, production, vps, docker]
description: ">"
  Deploys the storefront to the production VPS via SSH.
  Handles Redis healthcheck, Docker Compose restart, and
  liveness verification.
---

# skill: deploy-production

## Purpose

Deploy the storefront Next.js application to the production VPS.
Use this skill whenever the user asks to deploy, push to production,
or ship changes live.

## Prerequisites

- SSH key at /root/.ssh/deploy_key must exist
- Environment variable VPS_HOST must be set
- User must confirm they are on the correct git branch before proceeding

## Procedure

1. Confirm git branch:

   git branch --show-current

   Expected: "main". If not "main", STOP and ask user to confirm.

2. Confirm working tree is clean:

   git status --short

   Expected: empty output. If not empty, STOP and ask user whether to stash or commit.

3. Push to remote:

   git push origin main

4. Wait for GitHub Actions to complete (poll gh run list until conclusion=success):

   gh run list --branch main --limit 1 --json conclusion,status

   Poll every 30 seconds. Timeout after 10 minutes.

5. Verify liveness after deploy:

   curl -s -o /dev/null -w "%{http_code}" https://wowhow.cloud/

   Expected: 200. If not 200, trigger rollback procedure.

## Pitfalls

- Do NOT deploy if Redis healthcheck fails before deploy — the deploy will not fix it
- Do NOT interpret a 301 redirect as a success — check for 200 from the final URL
- GitHub Actions concurrency means only one deploy runs at a time — do not push again while a run is active
- If conclusion=cancelled, the next queued push will deploy — wait, do not push again

## Verification

After running this skill, the following must all be true:

- curl https://wowhow.cloud/ returns HTTP 200
- gh run list --limit 1 shows conclusion=success
- No active deploy lock at /tmp/wowhow-deploy.lock on VPS

## Rollback

If verification fails, run: skill/rollback-production

This template takes longer to write than an auto-generated skill. That is the point. The effort of writing it forces you to think through edge cases, failure modes, and verification criteria that auto-generation skips. The resulting skill is dramatically more reliable in production.

During days 4–10, I typically write between five and twelve skills, covering the core workflows identified in the observation log. Each skill goes into /home/hermes/skills/hand-authored/ where it is accessible to the agent but protected from modification by the read-only mount in the config.

Day 11–14: Build Rollback Infrastructure

Before enabling self-improvement, I need to be able to revert to a known-good state without manual effort. The rollback infrastructure has three components: git tracking of the skills directory, a wrapper script that enforces the git commit on every skill write, and a restore command.

Initialize git in the skills directory:

# Initialize git tracking for the skills directory
cd /home/hermes/skills
git init
git add hand-authored/ pinned/
git commit -m "day-14 baseline: hand-authored skills before enabling auto_create"

# Tag the baseline explicitly
git tag baseline-day14

The wrapper script is the key piece. When I enable auto-creation on day 15, I want every auto-generated skill to be committed to git immediately when Hermes writes it. This gives me a complete audit trail and a one-command rollback path. Here is the full wrapper script I use:

#!/usr/bin/env bash
# skill-write-with-audit.sh
# Wrap every skill write operation with a git commit.
# Usage: skill-write-with-audit.sh  
#
# Hermes Agent calls this script instead of writing skill files directly.
# Configure in config.yaml: skills.write_hook: "/home/hermes/bin/skill-write-with-audit.sh"

set -euo pipefail

SKILL_PATH="${1}"
CONTENT_FILE="${2}"
SKILLS_ROOT="/home/hermes/skills"
LOG_FILE="/home/hermes/logs/skill-audit.log"
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

# Validate inputs
if [[ -z "${SKILL_PATH}" || -z "${CONTENT_FILE}" ]]; then
  echo "[${TIMESTAMP}] ERROR: Missing arguments. Usage: $0  " | tee -a "${LOG_FILE}"
  exit 1
fi

# Resolve absolute path
ABS_SKILL_PATH="${SKILLS_ROOT}/${SKILL_PATH}"

# Ensure the target directory exists
mkdir -p "$(dirname "${ABS_SKILL_PATH}")"

# Check if this is an update to an existing skill
IS_UPDATE=false
if [[ -f "${ABS_SKILL_PATH}" ]]; then
  IS_UPDATE=true
  # Capture the pre-modification state for the log
  PREV_VERSION=$(grep -m1 "^version:" "${ABS_SKILL_PATH}" || echo "unknown")
fi

# Write the skill file
cp "${CONTENT_FILE}" "${ABS_SKILL_PATH}"

# Extract metadata from the written file
SKILL_ID=$(grep -m1 "^skill_id:" "${ABS_SKILL_PATH}" | awk '{print $2}' || echo "unknown")
NEW_VERSION=$(grep -m1 "^version:" "${ABS_SKILL_PATH}" | awk '{print $2}' || echo "unknown")

# Commit to git
cd "${SKILLS_ROOT}"

if [[ "${IS_UPDATE}" == "true" ]]; then
  COMMIT_MSG="auto-refine: ${SKILL_ID} ${PREV_VERSION} to ${NEW_VERSION} [${TIMESTAMP}]"
else
  COMMIT_MSG="auto-create: ${SKILL_ID} v${NEW_VERSION} [${TIMESTAMP}]"
fi

git add "${ABS_SKILL_PATH}"
git commit -m "${COMMIT_MSG}"
COMMIT_HASH=$(git rev-parse --short HEAD)

# Log the operation
echo "[${TIMESTAMP}] skill_write | id=${SKILL_ID} | path=${SKILL_PATH} | version=${NEW_VERSION} | update=${IS_UPDATE} | commit=${COMMIT_HASH}" | tee -a "${LOG_FILE}"

echo "OK: ${SKILL_PATH} written and committed as ${COMMIT_HASH}"

Make it executable and configure Hermes to use it:

chmod +x /home/hermes/bin/skill-write-with-audit.sh

# Add to config.yaml under the skills section:
# skills:
#   write_hook: "/home/hermes/bin/skill-write-with-audit.sh"

With this hook in place, every auto-generated skill is a git commit. Rolling back to the day-14 baseline is a single command:

# Roll back all auto-generated skills to the day-14 baseline
cd /home/hermes/skills
git checkout baseline-day14 -- managed/

# Verify the rollback
git log --oneline -5
git diff baseline-day14 HEAD -- managed/ | head -50

End of Day 14: The Activation Ritual

Before flipping the switch, I run through a fixed checklist. Skipping any item means waiting another 24 hours:

# Hermes Agent Day-14 Activation Checklist
# Complete ALL items before enabling auto_create / auto_refine

- [ ] Observation log has at least 3 days of workflow data
- [ ] At least 5 hand-authored skills written and tested manually
- [ ] Each hand-authored skill has a verification block with specific, testable criteria
- [ ] Skills directory is a git repo with baseline-day14 tag
- [ ] skill-write-with-audit.sh is executable and tested (run it manually once)
- [ ] Rollback command tested: git checkout baseline-day14 -- managed/ runs clean
- [ ] Audit log path is writable: touch /home/hermes/logs/skill-audit.log succeeds
- [ ] Config backup taken: cp config.yaml config.yaml.day14-backup
- [ ] Team notified that self-improvement is being enabled (if applicable)

When all items are checked, I update the config to enable auto-creation with conservative guardrails:

# config.yaml — Day 15+ configuration
# Self-improvement enabled with production guardrails

skills:
  auto_create: true
  auto_refine: true

  # Conservative creation threshold — agent must observe the same
  # pattern at least 5 times before creating a skill for it
  auto_create_threshold: 5

  # Refinement requires a meaningful quality delta, not marginal improvement
  auto_refine_min_improvement: 0.15

  # Maximum skills auto-created per day — prevents accumulation explosions
  auto_create_daily_limit: 2

  # Write hook — every skill write goes through the audit wrapper
  write_hook: "/home/hermes/bin/skill-write-with-audit.sh"

  # Hand-authored skills remain read-only even now
  external_dirs:
    - path: "/home/hermes/skills/hand-authored"
      mode: "read-only"
    - path: "/home/hermes/skills/pinned"
      mode: "read-only"

  managed_dir: "/home/hermes/skills/managed"
  managed_dir_writable: true

The auto_create_threshold: 5 and auto_create_daily_limit: 2 are the two guardrails I consider non-negotiable even after enabling self-improvement. The threshold prevents the agent from creating skills based on one-off requests. The daily limit means that even in the worst case, you have at most two new things to audit per day rather than four or more.

Pinning Critical Skills

Some skills must never be deleted, archived, or modified by the self-improvement loop, regardless of how the agent evaluates them. Production deployments, security-related workflows, and the audit wrapper itself all belong in this category. Hermes has a pin mechanism for exactly this purpose:

# Pin a skill so the self-improvement loop never touches it
hermes curator pin skill/deploy-production
hermes curator pin skill/rollback-production
hermes curator pin skill/security-review-checklist

# Verify pinned skills
hermes curator list --pinned

# Output:
# PINNED SKILLS
# -------------
# skill/deploy-production      v1.0.0   pinned: 2026-05-15
# skill/rollback-production    v1.0.0   pinned: 2026-05-15
# skill/security-review-checklist  v1.2.0   pinned: 2026-05-15

Pinned skills also live in /home/hermes/skills/pinned/ which is mounted read-only even in the day-15+ configuration above. The git tracking still applies — if you manually update a pinned skill, the audit wrapper logs the change — but the self-improvement loop cannot touch them.

The YAML frontmatter for a pinned skill looks like this:

---
skill_id: deploy-production
version: 1.0.0
author: anup
created: 2026-05-04
pinned: true
no_auto_refine: true
tags: [deploy, production, pinned]
---

Setting both pinned: true and no_auto_refine: true in the frontmatter creates a belt-and-suspenders guarantee. The pinned flag is enforced by the curator. The no_auto_refine flag is enforced by the self-improvement loop itself. Either one alone is sufficient; both together ensure the skill survives any config change or curator state reset.

Four Workflows That Should Never Be on Auto

Even after day 14, there are categories of workflow where I permanently keep auto-refinement disabled. These are set with the no_auto_refine frontmatter flag, not by the global config, so they stay protected regardless of what the global auto_refine setting is.

1. Production Deployments

Any skill that touches the production deployment pipeline gets no_auto_refine: true and pinned: true. The reasoning is simple: a deployment skill that has been tested and is working correctly should not be modified by an automated process. The cost of a bad deployment is high enough that human review of every change to the deploy skill is worth the overhead.

2. Security Reviews and Audit Checklists

Security review skills encode decisions made with deliberate human judgment about what constitutes an acceptable risk on this specific workload. An automated refinement process does not have the context to make those judgments. More importantly, a subtly weakened security review skill — one that drops a check that seems redundant based on recent session patterns — is exactly the kind of silent degradation that causes real incidents.

3. Customer-Facing Workflows

Any skill that generates content, sends communications, or takes actions visible to customers gets no_auto_refine: true. The agent's self-evaluation of output quality is based on patterns in past sessions. Customer-facing quality has dimensions the agent cannot observe: tone consistency with your brand, regulatory compliance, and the implicit expectations of your specific customer base. Automated refinement optimizes for what the agent can measure, which is not the same thing as customer quality.

4. The Audit Wrapper Itself

The skill-write-with-audit.sh wrapper must never be modified by any automated process. This is the ouroboros risk: if the self-improvement loop can modify the mechanism by which skill modifications are logged, the audit trail becomes unreliable. The wrapper lives outside the skills directory entirely, owned by root, and is never referenced in any Hermes skill file as a dependency.

The config block that enforces these permanent exceptions at the skill level rather than globally:

# These skills have auto-refinement permanently disabled
# regardless of the global auto_refine setting.
# Set in each skill's YAML frontmatter:

# skill/deploy-production
no_auto_refine: true
pinned: true

# skill/rollback-production
no_auto_refine: true
pinned: true

# skill/security-review-checklist
no_auto_refine: true
pinned: true

# skill/customer-email-template
no_auto_refine: true

# skill/wordpress-publish
no_auto_refine: true

The Honest Other Side

It is fair to push back on this approach. If you are running Hermes on a low-stakes workload — personal productivity, research summarization, drafting non-critical content — the 14-day observation period is probably unnecessary friction. The default self-improvement settings will produce a reasonably good agent within a week, and the cost of a bad auto-generated skill is low enough that you can simply delete it when you notice the problem.

The rule is specifically for production workloads, customer-facing systems, and workflows where a subtle degradation in agent behavior costs real money or damages real relationships before you catch it. If your Hermes deployment does not touch any of those categories, you can safely ignore this article and turn on self-improvement on day one.

I also want to be honest about the overhead. The 14-day observation period, the hand-authored skills, the git infrastructure, and the rollback tooling together represent roughly eight to twelve hours of work that a default deployment skips. That is a real cost. It pays back on production workloads because the alternative — debugging a degraded agent while production workflows are impaired — costs more. On a side project, the math probably does not work out in the same direction.

The clearest decision heuristic I have found: if you would run a staging environment and a rollback procedure for code changes to this workload, run them for your agent skills too. If you would not, default settings are probably fine.

Closing

Self-improvement is too powerful to enable on a workload you do not yet understand. The first 14 days of any new Hermes deployment are a learning period for you, not just for the agent. You are learning what the agent actually does on your real tasks, what the friction points are, where the agent excels without any skills at all, and where the gaps are that hand-authored skills can fill. Blocking self-improvement during that period is not about distrust of the agent. It is about having the data you need to make the self-improvement loop produce good outcomes.

When I enable self-improvement on day 15 with the conservative guardrails in place, the compounding still happens. It just compounds toward my real workflow rather than toward my first-week confusion. The difference in output quality after 30 more days is significant. The skills the agent generates are coherent with the hand-authored baseline, targeted at actual patterns rather than exploratory noise, and limited in accumulation rate so the audit burden stays manageable.

The evening I spent reverting eleven bad auto-generated skills from my last fresh deployment convinced me to never skip the observation period again. It is a better use of that time than debugging a degraded agent on a live workload.

If you found this useful, the two Hermes Agent articles I referenced at the start cover the positive case — what self-improvement looks like when it is working correctly, and the architecture of the skill system that makes it possible. This article is the prerequisite, not the replacement.

Originally published at wowhow.cloud

I Built the Hermes + Claude Code Dual-Stack: Orchestrator Meets Coder — Here's the Full Architecture

Anup Karanjkar — Thu, 21 May 2026 15:24:32 +0000

The framing showed up in a few places at the same time. A thread on Indie Hackers, a post on browseract, some Discord chatter: Hermes Agent as the orchestrator, Claude Code as the coder. Two agents, one stack, specialization instead of generalization. The framing made sense to me immediately. What nobody published was a working architecture — actual config files, the MCP bridge that connects them, and the failure modes you hit when you try to run this in production.

I spent two weeks building and debugging this dual-stack setup. I run it daily now. This is the complete architecture: VPS side, local side, the MCP bridge between them, six production patterns, and an honest accounting of what broke and what stuck.

Why Dual-Stack at All

The single-agent problem is real. I was running Claude Code as my primary agent for everything — code generation, git operations, GitHub issue management, cron-like scheduling via shell scripts. It works, but there are gaps. Claude Code is exceptional at code generation, file editing, and TypeScript/React tasks. It is not designed for persistent messaging, Telegram integration, or scheduling. Every time I wanted a notification when a task completed, I had to wire something up manually. Every time I wanted to trigger a code task from my phone, I was doing gymnastics.

Hermes is the inverse. It is excellent at persistent orchestration — running tasks on a schedule, consuming messages from Telegram or Discord, maintaining memory across sessions, coordinating multi-step workflows that span minutes or hours. It is not a specialized coder. When Hermes writes code, it is using a general-purpose model for a task where Claude Code has been specifically optimized.

The dual-stack argument is simple: let each agent do what it does best and bridge them. The complexity cost is real — two agent runtimes, a bidirectional MCP bridge, synchronized config — but the capability gain justifies it if you are building in public or running a product that needs both coding and operational automation.

Architecture Overview

The stack has three components:

Hermes on VPS — always-on, receives Telegram messages, runs cron jobs, maintains memory, and dispatches work
Claude Code on local machine — has full codebase access, IDE integration, runs tests, writes and edits files
MCP bridge — bidirectional: Claude Code calls Hermes tools, Hermes calls Claude Code tools

The key architectural decision is that Hermes runs on the VPS permanently. It is the always-on component. It receives messages from the outside world and decides what to do with them. Claude Code runs on my laptop where the codebase lives. It is the coding workhorse. The MCP bridge connects them so each can use the other as a tool.

Here is the data flow for the most common workflow — a Telegram message triggering a code change:

Phone (Telegram) → Hermes (VPS) → MCP bridge → Claude Code (local) → filesystem → git → GitHub → Hermes → Telegram → Phone

The notification loop is closed. I send a message from my phone, the code change happens, and I get a confirmation back on my phone. No manual steps in between.

VPS Side Setup

Hermes runs on a Hostinger VPS (Ubuntu 22.04, 4GB RAM). It starts via systemd on boot and stays running. The full config:

# ~/.hermes/config.yaml
# Hermes v0.13.0 — VPS production config

model: anthropic/claude-sonnet-4-6

systemPrompt: |
  You are a persistent orchestration agent running on a VPS. Your role is:
  1. Receive and triage messages from Telegram
  2. Maintain a task queue and dispatch coding tasks to Claude Code via MCP
  3. Monitor task completion and send confirmations back via Telegram
  4. Run scheduled workflows at their designated times

  IMPORTANT: Do not write code directly. For any code generation, file editing,
  or git operations, use the claude_code tool. You are the orchestrator; Claude
  Code is the coder. Your job is planning and coordination.

models:
  router:
    provider: anthropic
    model: claude-haiku-4-5-20251001
    temperature: 0.0
    use_for: task_classification
  summarizer:
    provider: anthropic
    model: claude-haiku-4-5-20251001
    temperature: 0.0
    use_for: result_summarization

messaging:
  telegram:
    token: "${TELEGRAM_BOT_TOKEN}"
    allowed_chat_ids:
      - "${TELEGRAM_OWNER_CHAT_ID}"
    on_message:
      route_to: task_queue
      confirm_receipt: true

memory:
  backend: sqlite
  path: ~/.hermes/memory.db
  retention_days: 90

mcpServers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem@1.9.2", "/root/storefront"]
    capabilities:
      prompts: false
      resources: true
      tools: true

  git:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-git@0.6.2"]
    env:
      GIT_AUTHOR_NAME: "Hermes Orchestrator"
      GIT_AUTHOR_EMAIL: "hermes@wowhow.cloud"
    capabilities:
      prompts: false
      resources: false
      tools: true

  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
    include:
      - list_issues
      - get_issue
      - create_issue
      - add_issue_comment
      - list_pull_requests
      - create_pull_request
      - get_pull_request
    capabilities:
      prompts: false
      resources: false
      tools: true

  claude_code:
    command: claude
    args: ["mcp", "serve"]
    description: "Claude Code — use for all code generation, TypeScript, React, file edits, and git commits"
    include:
      - edit_file
      - create_file
      - read_file
      - run_bash_command

serve:
  transport: stdio
  name: hermes-orchestrator
  description: |
    Hermes persistent orchestration agent. Accepts natural language task
    descriptions, manages a Telegram gateway, runs cron workflows, and
    delegates code generation to Claude Code.

The cron jobs live in a separate file to keep the main config readable:

# ~/.hermes/cron.yaml
jobs:
  morning-triage:
    # 7 AM IST = 1:30 AM UTC on weekdays
    schedule: "30 1 * * 1-5"
    task: |
      Pull the last 24 hours of open GitHub issues and pull requests.
      Categorize them by priority: blocking, needs-review, backlog.
      Create a summary and send it to Telegram with counts and top 3 items.
    model: anthropic/claude-haiku-4-5-20251001
    max_steps: 12
    on_failure:
      notify: telegram

  pr-triage:
    # Every 4 hours
    schedule: "0 */4 * * *"
    task: |
      Check for pull requests that have been open more than 48 hours without
      a review. Post a reminder comment on each one. Do not create new PRs.
    model: anthropic/claude-haiku-4-5-20251001
    max_steps: 8
    dry_run: false

  weekly-digest:
    # Sunday 9 PM IST = 3:30 PM UTC
    schedule: "30 15 * * 0"
    task: |
      Generate a weekly summary: commits merged, issues closed, PRs opened.
      Query GitHub for the past 7 days. Format as markdown and send to Telegram.
    model: anthropic/claude-sonnet-4-6
    max_steps: 15

Start cron runner as a daemon:

hermes cron start --config ~/.hermes/cron.yaml --daemon

The systemd unit file that keeps Hermes running on the VPS:

# /etc/systemd/system/hermes.service
[Unit]
Description=Hermes Orchestration Agent
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root
ExecStart=/usr/local/bin/hermes serve --config /root/.hermes/config.yaml
Restart=on-failure
RestartSec=10
Environment=ANTHROPIC_API_KEY=your-key-here
Environment=TELEGRAM_BOT_TOKEN=your-token-here
Environment=TELEGRAM_OWNER_CHAT_ID=your-chat-id-here
Environment=GITHUB_TOKEN=your-github-token-here

[Install]
WantedBy=multi-user.target

systemctl enable hermes
systemctl start hermes
systemctl status hermes

Local Side Setup

Claude Code runs on my MacBook where the codebase lives. The configuration that registers Hermes as an MCP server goes in ~/.claude.json (global, so it is available in every project):

# ~/.claude.json
{
  "mcpServers": {
    "hermes": {
      "command": "ssh",
      "args": [
        "-T",
        "root@your-vps-ip",
        "hermes mcp serve --config /root/.hermes/config.yaml"
      ],
      "description": "Hermes orchestration agent on VPS — use for Telegram messaging, scheduled tasks, GitHub operations, and multi-step workflows. Do not use for code generation or file editing."
    }
  }
}

The SSH transport is the key implementation detail here. Claude Code spawns the MCP server by running the command + args and communicating via stdio. By using ssh -T, the stdio of the local Claude Code process connects via SSH to Hermes running on the VPS. From Claude Code's perspective, it is talking to a local MCP server. From Hermes's perspective, it is receiving MCP protocol messages via stdin from an SSH session.

This is the cleanest approach I found. The alternatives — running a local Hermes proxy that connects to the VPS, or exposing Hermes on a port and using HTTP transport — both introduce more failure points. The SSH stdio bridge is two commands and a config entry.

For the SSH connection to work without prompting for credentials, set up key-based auth first:

ssh-copy-id root@your-vps-ip
# Verify it works without password:
ssh -T root@your-vps-ip echo "bridge works"

You can also use a project-level .mcp.json if you only want Hermes available in specific repositories:

# storefront/.mcp.json
{
  "mcpServers": {
    "hermes": {
      "command": "ssh",
      "args": [
        "-T",
        "root@your-vps-ip",
        "hermes mcp serve --config /root/.hermes/config.yaml"
      ],
      "description": "Hermes orchestration agent — Telegram, GitHub, cron dispatch"
    }
  }
}

The MCP Bridge

The bridge is bidirectional. Claude Code can call Hermes tools. Hermes can call Claude Code tools. Both sides are configured as MCP servers that the other agent registers as a client.

From Claude Code's perspective, Hermes appears as a set of tools. The primary ones Hermes exposes:

run_task — execute a multi-step orchestration task
send_telegram — send a message to a specific Telegram chat
query_memory — query Hermes's persistent memory store
schedule_task — add a one-off task to Hermes's cron queue
get_github_context — fetch issues, PRs, and recent commits from the configured repository

From Hermes's perspective, Claude Code appears as a set of tools. The primary ones Claude Code exposes when run as an MCP server:

edit_file — make targeted edits to an existing file
create_file — create a new file with specified content
read_file — read file content
run_bash_command — run a shell command in the project directory

Start Claude Code as an MCP server (for Hermes to call):

claude mcp serve
# Listens on stdio — Hermes spawns this process via its claude_code mcpServer config

The bidirectionality is what makes the system genuinely useful. Without it, you have two separate agents with no way to coordinate. With it, each agent can delegate to the other for tasks in the other's specialty.

One thing I learned the hard way: the connection from Hermes on the VPS to Claude Code on my local machine requires the local machine to be running and reachable. Hermes can trigger Claude Code tasks only when my MacBook is on and the SSH reverse tunnel is active. For scheduled tasks that run at 7 AM, I need either: (a) my MacBook on, (b) Claude Code also running on the VPS with VPS codebase access, or (c) Hermes falling back to doing the code work itself. I chose option (b) for cron-triggered coding tasks — a second Claude Code instance on the VPS with read/write access to the deployed code.

Six Production Patterns

Pattern 1: Phone → Hermes → Claude Code (Telegram Trigger)

The most-used pattern. I send a Telegram message describing a code change I want. Hermes receives it, decides it is a coding task, dispatches it to Claude Code via the MCP bridge, and sends me a confirmation with the result.

Example message from my phone:

Add a "last updated" timestamp to every blog post card on the /blogs listing page.
Format it as "Updated May 16, 2026". Use the published_at field. Mobile-friendly.

Hermes's processing:

1. Classify: coding task → route to Claude Code
2. Add context: attach relevant file paths from memory (blog card component location)
3. Call claude_code.run_bash_command: read current component
4. Call claude_code.edit_file: apply the timestamp addition
5. Call claude_code.run_bash_command: run tsc --noEmit to verify
6. Call git tool: commit the change to a feature branch
7. Call github tool: open a draft PR
8. Call send_telegram: "Done. PR #47 opened. Timestamp added to BlogCard.tsx."

The total elapsed time from my Telegram message to the Telegram confirmation is 90–180 seconds, depending on file size and TypeScript complexity. I am not at my computer for any of it.

Pattern 2: Cron → Hermes → Claude Code (Scheduled PR Triage)

Every morning at 7 AM IST, Hermes runs the morning-triage cron job. For issues tagged needs-fix that have been open more than 3 days, Hermes dispatches a task to Claude Code to generate a fix proposal:

# Hermes cron task (simplified)
1. List GitHub issues tagged "needs-fix" older than 3 days
2. For each issue:
   a. Read the relevant code file via claude_code.read_file
   b. Call claude_code.run_task: "Propose a fix for this issue. Read the current code and describe the change needed, then implement it in a new branch."
   c. Open a draft PR with the proposed fix
   d. Post a comment on the original issue linking to the PR
3. Send Telegram summary: "Fixed 2 issues overnight. PRs #48, #49 ready for review."

This pattern requires Claude Code to be available on the VPS (or the local machine to be on). I keep a Claude Code session running on the VPS in a tmux pane during working hours. For overnight tasks, I use the VPS Claude Code instance with access to the mirrored codebase.

Pattern 3: Claude Code → Hermes → Telegram (Completion Notification)

Claude Code can call Hermes tools directly. After completing a long implementation task, Claude Code calls hermes.send_telegram to notify me:

# Claude Code side — after completing a task
# Claude Code calls the hermes MCP tool automatically when instructed:
# "When you finish, send me a Telegram notification with a summary."

# The tool call Claude Code makes:
hermes.send_telegram({
  message: "Done: Implemented the dual-stack blog post. Files modified: 2. TypeScript: clean. Build: passing. PR branch: feat/dual-stack-blog-post."
})

This is the simplest pattern and the one I use most often during active development. I start a Claude Code task, tell it to notify me when done, and go do something else. The Telegram ping tells me when to come back.

Pattern 4: Hermes Skill → Claude Code Tool

Hermes supports skills — reusable task templates stored in ~/.hermes/skills/. A skill can reference Claude Code as a tool. Here is the blog-writer skill that I use frequently:

# ~/.hermes/skills/blog-writer.yaml
name: blog-writer
description: Write and publish a technical blog post to the WOWHOW storefront

steps:
  - name: research
    task: |
      Research the topic: ${TOPIC}
      Find 3-5 technical sources. Summarize key points and data.
      Output: research_summary (markdown)
    model: anthropic/claude-sonnet-4-6

  - name: outline
    task: |
      Create a detailed outline for a ${WORD_COUNT}-word technical blog post
      about ${TOPIC}. Use the research from the previous step.
      Include all H2 sections, key code blocks, and conclusion.
    model: anthropic/claude-sonnet-4-6

  - name: write
    tool: claude_code
    task: |
      Write the full blog post based on the outline. Create the TypeScript
      data file at the correct path in src/data/blog-posts/. Follow the
      exact format used in existing blog post files. Escape all template
      literal variables with backslash. Return the file path when done.

  - name: register
    tool: claude_code
    task: |
      Add the import and spread to src/data/blog-posts.ts. Add the slug
      to the POST_ORDER array at position 0. Verify TypeScript compiles.

  - name: notify
    tool: send_telegram
    message: "Blog post created: ${TOPIC}. File: ${write.result}. Compile: clean."

Invoke from Telegram:

/skill blog-writer TOPIC="Hermes dual-stack architecture" WORD_COUNT=4200

The skill runs end-to-end: research, outline, write (delegated to Claude Code), register (delegated to Claude Code), notify. I get a Telegram message when it is done.

Pattern 5: Shared Knowledge Base

Hermes maintains a persistent SQLite memory store. Claude Code reads from CLAUDE.md and project files. The gap between these two knowledge sources is a real problem — Hermes knows things Claude Code does not, and vice versa.

I bridge this in two ways. First, I have a cron job that exports Hermes's memory to a markdown file that Claude Code can read:

# ~/.hermes/cron.yaml
  memory-sync:
    schedule: "0 * * * *"    # every hour
    task: |
      Export all memory entries tagged "architecture" or "decisions" to
      /root/storefront/storefront/.hermes-context.md in markdown format.
      Format: ## [tag] 
 - [key]: [value] 

    model: anthropic/claude-haiku-4-5-20251001
    max_steps: 5

Second, I add a reference to this file in CLAUDE.md:

# In storefront/CLAUDE.md, add:
## Hermes Context
Read `.hermes-context.md` for decisions and context that Hermes has recorded.
This file is auto-updated hourly by Hermes's memory-sync cron job.

The reverse direction — Claude Code writing to Hermes memory — works via the hermes.query_memory and (when available) hermes.write_memory tools. I instruct Claude Code to record important architectural decisions to Hermes memory at the end of significant tasks. This keeps Hermes's context current without manual updates.

Pattern 6: Multi-Agent Kanban with Claude Code as Worker

For larger features that span multiple sessions, I use Hermes as a Kanban board manager and Claude Code as the task worker. Hermes maintains a task list in its memory store, assigns tasks, tracks completion, and dispatches the next task when the previous one finishes.

# Hermes task queue in memory (simplified schema)
tasks:
  - id: T001
    title: "Add dual-stack blog post"
    status: done
    assigned_to: claude_code
    completed_at: "2026-05-16T22:00:00Z"

  - id: T002
    title: "Add Hermes skill index page"
    status: in_progress
    assigned_to: claude_code
    started_at: "2026-05-16T22:15:00Z"

  - id: T003
    title: "Update tools registry with 5 new tools"
    status: pending
    assigned_to: claude_code
    depends_on: [T002]

When Claude Code completes T002, it calls hermes.run_task with a task completion report. Hermes marks T002 done, checks dependencies, and dispatches T003 to Claude Code automatically. I get a Telegram update after each task completes.

This pattern is useful for late-night work — I set up the Kanban queue before sleeping and wake up to a Telegram thread showing what was completed overnight. Claude Code on the VPS handles the actual execution. Hermes handles sequencing and notification.

What Broke

This section is the most important one. Architectural diagrams always look cleaner than the implementation.

MCP stdio bridge latency. The SSH stdio bridge adds 200–400ms to every MCP tool call. For interactive use this is borderline acceptable. For workflows with 15+ tool calls, you notice it accumulate. A Hermes task that calls Claude Code 10 times takes 2–4 seconds just in bridge overhead before accounting for model inference time. I have not found a way to reduce this without switching to a persistent TCP connection, which introduces its own complexity.

Session state is not shared. Hermes has its SQLite memory store. Claude Code has CLAUDE.md and project context. There is no live shared state — the two agents do not see each other's current reasoning. When Hermes dispatches a task to Claude Code, Claude Code has no awareness of what Hermes is "thinking about" beyond what Hermes explicitly passes in the task description. I compensate by writing verbose task descriptions, but this is a real limitation. Long tasks sometimes lose context mid-execution because the task description did not include a fact that seemed obvious from Hermes's perspective.

Skill format mismatch. Hermes skills use Hermes's YAML format with Hermes-specific interpolation syntax. Claude Code skills use a different format. You cannot share skill definitions between the two systems — you maintain two separate skill libraries. I tried to abstract this into a shared format and gave up after a day. The formats are different enough that a translation layer would be more maintenance than two separate libraries.

Claude Code MCP server is not designed for concurrent access. When Hermes runs two cron jobs simultaneously and both dispatch tasks to Claude Code, you get race conditions. The second task waits for the first to complete (or fails with a lock error). I now stagger cron jobs by at least 5 minutes and ensure no two jobs can both dispatch to Claude Code in the same window.

SSH tunnel drops. If the SSH connection drops mid-task, the MCP bridge silently dies. Hermes does not always detect this cleanly — sometimes it retries the same tool call instead of reporting a connection failure. I added a keepalive to the SSH config and a health check to the Hermes config, but this remains the flakiest part of the setup.

# ~/.ssh/config — add for the VPS connection
Host your-vps-ip
  ServerAliveInterval 30
  ServerAliveCountMax 3
  ConnectTimeout 10

The Workflow That Stuck

After two weeks of debugging and two more weeks of daily use, one workflow pattern has become my default and I expect it to stay:

Phone-driven development.

Morning: Wake up. Open Telegram. Check the overnight Hermes summary (morning-triage cron). It tells me what is open, what needs review, and what broke. I read it on my phone before getting out of bed.

During the day: When I think of a code change while away from my computer, I send a Telegram message. Hermes routes it to the task queue. When my computer is on and Claude Code is running, the task executes. I get a confirmation when it is done. I do not need to be at the computer to initiate the work or to know when it is complete.

Evening: I review what was done. If something needs manual review, the PR is already open. I read it, request any changes via GitHub (or via Telegram → Hermes → GitHub comment), and move on.

The dual-stack did not change how I write code — Claude Code does that the same as before. What changed is the coordination layer around the coding. Scheduling, notification, context from the outside world — all of that now runs through Hermes, always-on, without me needing to be at my desk to trigger or monitor it.

The question people usually ask at this point: is it worth the setup complexity? For a solo founder running a product with 1,800+ items, a blog pipeline, and daily SEO and coding work — yes. If you are doing weekend projects or one-off builds, probably not. The setup cost is three to four hours of real work. The maintenance burden is low once it is running. The payoff is a development loop that runs while I sleep and notifies me on my phone.

Full Config Summary

All the config files in one place for reference:

# VPS: ~/.hermes/config.yaml — Hermes orchestrator
# VPS: ~/.hermes/cron.yaml — Scheduled jobs
# VPS: /etc/systemd/system/hermes.service — Auto-start
# Local: ~/.claude.json — Claude Code global MCP registration
# Local: storefront/.mcp.json — Project-level MCP registration (optional)
# Local: ~/.ssh/config — SSH keepalive settings
# Shared: storefront/.hermes-context.md — Hourly memory sync output

The minimum viable dual-stack is three files: ~/.hermes/config.yaml on the VPS with the claude_code mcpServer entry, ~/.claude.json on your local machine with the hermes mcpServer entry using SSH transport, and SSH key auth set up between the two machines. Everything else — cron, Telegram, memory sync, skills — layers on top of that foundation.

Start with the minimum. Get the bridge working. Run a test task end-to-end. Then add the pieces that match your specific workflow.

Originally published at wowhow.cloud

I Wired Claude Code Into Hermes Agent (And Hermes Into Claude Code): The Full Tool Gateway Reference

Anup Karanjkar — Thu, 21 May 2026 15:11:12 +0000

The Hermes Tool Gateway is the piece of the Hermes architecture that most documentation glosses over. Every guide shows you how to start Hermes, pick a model, and chat. Almost none of them explain how the MCP (Model Context Protocol) integration actually works in production — specifically, how to configure Hermes as an MCP client so it can call external tools, and simultaneously as an MCP server so Claude Code or any other agent can call Hermes as a tool. That bidirectionality is what makes Hermes genuinely useful in a multi-agent stack.

I spent a week wiring Hermes v0.13.0 into my production setup — Claude Code as the primary coder, Hermes as the orchestration layer, with shared tool access across both. What follows are 12 working patterns from that process, in increasing order of complexity. Every YAML block is a copy-paste starting point. I have run each of these in production and debugged the failure modes so you do not have to.

Before we get into the patterns, one prerequisite: run the sanity check. Everything else depends on your environment being clean.

Setup Step Zero: The Doctor Check

Before touching a single config file, run Hermes's built-in diagnostics command:

hermes doctor

A healthy environment produces output that looks like this:

[hermes doctor] Checking environment...

  ✓ hermes binary          v0.13.0
  ✓ config file            ~/.hermes/config.yaml (found)
  ✓ default model          anthropic/claude-sonnet-4-6 (reachable)
  ✓ API credentials        ANTHROPIC_API_KEY set (not expired)
  ✓ MCP runtime            @modelcontextprotocol/server v1.9.2
  ✓ Node.js                v22.4.0 (required ≥ 20)
  ✓ filesystem permissions ~/.hermes/ writable
  ✓ log directory          ~/.hermes/logs/ writable

[hermes doctor] All checks passed. Tool gateway ready.

If you see any red ✗ entries, fix them before proceeding. The two most common failures are a stale ANTHROPIC_API_KEY and a Node.js version below 20. The MCP runtime in v0.13.0 uses native fetch and async generators that require Node 20+. On Node 18, you will get silent failures in the tool invocation layer — no error, just missing tool calls. Upgrade first.

If the config file is missing entirely:

hermes init
# Creates ~/.hermes/config.yaml with defaults

Pattern 1: Outbound — Filesystem MCP Server

The simplest outbound MCP connection gives Hermes read and write access to a directory on your local filesystem. This is the foundation for every pattern that follows — once you understand how the mcpServers key works in config.yaml, the rest of the patterns are variations on the same structure.

# ~/.hermes/config.yaml
model: anthropic/claude-sonnet-4-6

mcpServers:
  filesystem:
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - /Users/yourname/projects        # root directory Hermes can access
    env:
      NODE_ENV: production

With this config, Hermes gains the following tools automatically: read_file, write_file, list_directory, create_directory, move_file, search_files, and get_file_info. You do not define these tools yourself — they come from the MCP server binary. Hermes discovers them at startup via the MCP handshake and makes them available to the model during every conversation.

Verify it is working:

hermes tools list
# Expected output includes:
# [mcp:filesystem] read_file
# [mcp:filesystem] write_file
# [mcp:filesystem] list_directory
# ... (7 tools total)

The command: npx pattern is important. Hermes spawns the MCP server as a child process using stdio transport. The -y flag on npx auto-installs the package if it is not cached. In production I pin the version to avoid surprises:

args:
  - -y
  - "@modelcontextprotocol/server-filesystem@1.9.2"
  - /Users/yourname/projects

Pattern 2: Outbound — GitHub Issues with Tool Whitelist

The GitHub MCP server exposes a large surface area by default — pull request management, repo creation, branch operations, issue management, gist operations. In most workflows you only want a subset. Use the include key to whitelist exactly the tools Hermes is allowed to call:

# ~/.hermes/config.yaml
model: anthropic/claude-sonnet-4-6

mcpServers:
  github:
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-github"
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
    include:
      - list_issues
      - get_issue
      - create_issue
      - add_issue_comment
      - list_pull_requests
      - get_pull_request

The include key is a capability filter. Tools not in the list are invisible to the model — they are filtered out during the MCP handshake response. This matters for two reasons. First, it reduces the tool count in the model's context, which measurably improves tool selection accuracy. When Hermes has 60 GitHub tools available, it occasionally picks the wrong one. With 6 relevant tools, it consistently picks correctly. Second, it eliminates accidental destructive operations. A model that cannot see delete_repository cannot call delete_repository, no matter what a user asks.

Note the ${GITHUB_TOKEN} syntax — Hermes resolves environment variables in the config file at startup. Set the variable in your shell profile before running Hermes. Never hardcode tokens in the config file.

Pattern 3: Outbound — OAuth-Protected Remote Servers (Stripe Example)

Not all MCP servers run as local stdio processes. Some run as remote HTTP servers that use OAuth for authentication. The Stripe MCP server is the canonical example, and it is the pattern I use for payment-related Hermes tasks:

# ~/.hermes/config.yaml
model: anthropic/claude-sonnet-4-6

mcpServers:
  stripe:
    transport: http
    url: "https://mcp.stripe.com/v1"
    auth:
      type: oauth2
      clientId: "${STRIPE_MCP_CLIENT_ID}"
      clientSecret: "${STRIPE_MCP_CLIENT_SECRET}"
      tokenUrl: "https://mcp.stripe.com/oauth/token"
      scopes:
        - customers:read
        - charges:read
        - subscriptions:read
    include:
      - list_customers
      - retrieve_customer
      - list_charges
      - retrieve_subscription

The transport: http key switches Hermes from stdio to HTTP/SSE transport. Hermes handles the OAuth token lifecycle automatically — it fetches a token on first use and refreshes it before expiry. You do not need to manage token rotation in your application code.

For the Stripe MCP server specifically, request only read scopes unless your workflow explicitly requires write operations. Hermes is good at knowing when to call tools, but defense in depth means limiting what a tool can do even when called correctly. I use customers:read, charges:read, and subscriptions:read for my billing workflow — no write access, no refund operations, no configuration changes.

Pattern 4: Multi-Server Composition

The real power of the mcpServers key is that you can define multiple servers simultaneously. Hermes aggregates all the tools from all connected servers into a single unified toolset. The model sees one flat list of available tools and picks from it based on the task. Here is my baseline five-server composition:

# ~/.hermes/config.yaml
model: anthropic/claude-sonnet-4-6

systemPrompt: |
  You are a senior developer assistant with access to filesystem tools,
  git operations, GitHub API, a Postgres database, and project documentation.
  Always prefer reading documentation before modifying code. Always commit
  changes to git before marking a task complete.

mcpServers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem@1.9.2", "/Users/yourname/projects"]

  git:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-git@0.6.2"]
    env:
      GIT_AUTHOR_NAME: "Hermes Agent"
      GIT_AUTHOR_EMAIL: "hermes@yourproject.local"

  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
    include:
      - list_issues
      - get_issue
      - create_issue
      - add_issue_comment

  postgres:
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-postgres"
      - "${DATABASE_URL}"
    include:
      - query
      - list_tables
      - describe_table

  docs:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-fetch"]
    env:
      ALLOWED_DOMAINS: "docs.yourproject.com,api.yourproject.com"
    include:
      - fetch
      - search

The systemPrompt key at the top-level config is essential in multi-server setups. Without a system prompt, the model treats all tools as equally available and equally appropriate. With a system prompt that sets behavioral priorities — "read documentation before modifying code", "commit before marking complete" — tool selection becomes more intentional and the overall task completion quality improves significantly.

One thing to watch in multi-server setups: tool name collisions. If two MCP servers expose a tool called search, Hermes namespaces them as mcp:docs:search and mcp:github:search in its internal registry but presents both to the model. Whether the model picks the right one depends heavily on how well the server's tool descriptions distinguish the two operations. If you see the model consistently picking the wrong search variant, add an include filter to one of the servers to remove the ambiguous tool.

Pattern 5: Inbound — Hermes as MCP Server

Everything so far has been outbound: Hermes calling external MCP servers. Pattern 5 flips the direction. Hermes itself becomes an MCP server that external agents — Claude Code, Cursor, custom tools — can call as a tool.

# Start Hermes as an MCP server
hermes mcp serve   --transport stdio   --name "hermes-orchestrator"   --description "Multi-step task orchestrator with filesystem, git, and GitHub access"   --port 0

When run in this mode, Hermes exposes itself via stdio using the standard MCP protocol. External agents connect to it exactly as they connect to any other MCP server. From the external agent's perspective, Hermes is a tool with one primary method: run_task, which accepts a natural-language task description and returns the result of Hermes completing that task using its own tool chain.

To make this permanent and auto-starting, configure it in a hermes-server.yaml:

# ~/.hermes/server.yaml
serve:
  transport: stdio
  name: hermes-orchestrator
  description: |
    Hermes orchestration agent. Accepts natural language task descriptions
    and completes them autonomously using filesystem, git, GitHub, and
    Postgres tools. Returns structured results with tool call traces.
  tools:
    - name: run_task
      description: |
        Execute a multi-step development task. Provide a clear task description
        including success criteria. Hermes will plan and execute the task using
        its available tools and return a structured result.
      inputSchema:
        type: object
        properties:
          task:
            type: string
            description: Natural language task description with success criteria
          context:
            type: string
            description: Optional additional context (file paths, constraints, etc.)
          max_steps:
            type: integer
            default: 20
            description: Maximum tool calls before halting
        required: [task]

Start it:

hermes mcp serve --config ~/.hermes/server.yaml

Pattern 6: The Dual-Stack — Claude Code as Coder, Hermes as Orchestrator

This is the pattern I use every day and the one that makes the biggest difference to how I work. Claude Code handles code generation, edits, and TypeScript/React tasks. Hermes handles orchestration — running sequences of tasks, managing git state, interacting with GitHub and Postgres, and coordinating work across multiple files and tools. Both agents share tool access, but they have different roles.

Here is how to wire it up. First, configure Hermes to expose itself as an MCP server AND connect to Claude Code's tool surface:

# ~/.hermes/config.yaml (Hermes side)
model: anthropic/claude-sonnet-4-6

systemPrompt: |
  You are an orchestration agent. You plan multi-step development workflows,
  manage git state, coordinate with GitHub, and delegate code-generation
  subtasks to Claude Code when needed. You do not write code directly — you
  describe what code is needed and call the claude_code tool to generate it.
  Always verify git status before and after code changes.

mcpServers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem@1.9.2", "/Users/yourname/projects"]

  git:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-git@0.6.2"]

  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
    include:
      - list_issues
      - create_pull_request
      - add_issue_comment

serve:
  transport: stdio
  name: hermes-orchestrator

Second, add Hermes as an MCP server in Claude Code's .claude.json:

# ~/.claude.json (Claude Code side)
{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp", "serve", "--config", "/Users/yourname/.hermes/config.yaml"],
      "description": "Hermes orchestration agent — use for multi-step tasks, git workflows, GitHub operations, and database queries"
    }
  }
}

Third, add Claude Code as an MCP server in Hermes's config, completing the bidirectional bridge:

# Add to ~/.hermes/config.yaml under mcpServers:
  claude_code:
    command: claude
    args: ["mcp", "serve"]
    description: "Claude Code — use for code generation, TypeScript, React, file edits"
    include:
      - edit_file
      - create_file
      - read_file
      - run_bash_command

With both sides configured, the workflow looks like this in practice:

I describe a feature to Hermes: "Implement the UserProfile component, wire it to the /api/profile endpoint, commit to a feature branch, and open a draft PR."
Hermes plans the steps, reads the existing codebase via filesystem tools, and calls Claude Code via MCP to generate the actual component code.
Claude Code returns the generated code. Hermes writes it to disk via filesystem tools, runs the git commit via git tools, and creates the PR via GitHub tools.
Hermes reports the PR URL and a summary of what was done.

Neither agent is trying to do everything. Claude Code is better at code generation. Hermes is better at multi-step planning and tool orchestration. The dual-stack lets each do what it does best.

One critical thing to get right: the systemPrompt on the Hermes side must explicitly tell it NOT to write code directly and to call Claude Code for code generation. Without that instruction, Hermes will try to generate code itself using its own model — which works, but loses the specialization advantage. The system prompt is the architectural boundary.

Pattern 7: Cron-Driven Scheduled MCP Workflows

Hermes supports scheduled task execution via its cron integration. This is useful for automated workflows — daily digest emails, scheduled database cleanups, periodic GitHub sync, and similar recurring operations. The cron config goes in a separate cron.yaml file:

# ~/.hermes/cron.yaml
jobs:
  daily-digest:
    # Run at 8 AM IST (2:30 AM UTC) every weekday
    schedule: "30 2 * * 1-5"
    task: |
      1. Query the Postgres database for all open issues created in the last 24 hours.
      2. Fetch the corresponding GitHub issues to get current status.
      3. Generate a markdown summary grouped by priority.
      4. Create a new page in the project docs directory with today's date as the filename.
      5. Post the summary as a comment on the tracking GitHub issue #1.
    model: anthropic/claude-haiku-4-5-20251001    # cheaper model for scheduled tasks
    max_steps: 15
    on_failure:
      notify: "hermes-alerts"    # Telegram integration (configured separately)

  weekly-cleanup:
    # Every Sunday at midnight UTC
    schedule: "0 0 * * 0"
    task: |
      Query the Postgres database for rows in the task_log table older than 30 days.
      Delete them in batches of 100 to avoid locking. Report the row count deleted.
    model: anthropic/claude-haiku-4-5-20251001
    max_steps: 10
    dry_run: false    # set to true to preview without executing

Start the cron runner:

hermes cron start --config ~/.hermes/cron.yaml --daemon

Check cron status:

hermes cron status
# Output:
# daily-digest    next run: 2026-05-17T02:30:00Z    last: completed (14 steps, 42s)
# weekly-cleanup  next run: 2026-05-17T00:00:00Z    last: completed (8 steps, 12s)

The model override in cron jobs is important. Scheduled tasks that run unattended do not need the highest-capability model. Using Haiku for daily digest generation costs roughly 10x less than Sonnet and produces equivalent quality for structured, well-defined tasks. I only use Sonnet or Opus in cron jobs when the task involves genuine reasoning or ambiguous input.

Pattern 8: Per-Tool Gateway Routing with use_gateway

By default, all MCP tool calls go through Hermes's primary model. The use_gateway key lets you route specific tool calls through a different configuration — a different model, different retry behavior, or a different timeout. This is useful when one tool in your stack is unreliable or slow:

# ~/.hermes/config.yaml
model: anthropic/claude-sonnet-4-6

mcpServers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem@1.9.2", "/Users/yourname/projects"]

  slow-api:
    command: npx
    args: ["-y", "@company/internal-mcp-server"]
    env:
      API_URL: "${INTERNAL_API_URL}"
      API_KEY: "${INTERNAL_API_KEY}"
    use_gateway:
      timeout_seconds: 120      # Default is 30s — this server is slow
      retry:
        max_attempts: 3
        backoff: exponential
        initial_delay_ms: 1000
      circuit_breaker:
        failure_threshold: 5    # Open circuit after 5 consecutive failures
        recovery_timeout_s: 60  # Try again after 60s

The use_gateway block is per-server, not per-tool. Every tool from slow-api inherits the 120-second timeout and exponential backoff. If you need different timeouts for different tools from the same server, you need to run two instances of the server with different configs — there is no per-tool timeout override in v0.13.0.

The circuit breaker is the most important part of the use_gateway config for production. Without it, Hermes will keep trying a failing MCP server on every tool call, accumulating timeouts and burning model tokens on retries. With a circuit breaker, after 5 consecutive failures the server is marked as unavailable for 60 seconds. Hermes continues with the remaining tools and reports that the unavailable server's tools are offline. This degrades gracefully instead of hanging.

Pattern 9: Auxiliary Models for Sub-Tasks

Hermes supports a models block that lets you define auxiliary model configurations for specific purposes. The three patterns I use most are: a fast router model for initial task classification, a reasoning model for complex multi-step planning, and a cheap model for tool result summarization:

# ~/.hermes/config.yaml
model: anthropic/claude-sonnet-4-6    # primary model

models:
  router:
    provider: anthropic
    model: claude-haiku-4-5-20251001
    temperature: 0.0                   # deterministic routing decisions
    use_for: task_classification       # Hermes uses this model to classify tasks before routing

  reasoner:
    provider: anthropic
    model: claude-opus-4-7
    temperature: 0.3
    use_for: complex_planning          # Used when task requires multi-step planning > 10 steps
    max_tokens: 8192

  summarizer:
    provider: anthropic
    model: claude-haiku-4-5-20251001
    temperature: 0.0
    use_for: result_summarization      # Condenses verbose tool output before adding to context

mcpServers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem@1.9.2", "/Users/yourname/projects"]

routing:
  classify_tasks: true                 # Enable automatic task classification via router model
  auto_route_complex: true             # Auto-upgrade to reasoner for complex tasks
  complexity_threshold: 8              # Tasks requiring > 8 steps use the reasoner model

The routing.complexity_threshold is calibrated by trial and error. At 8, about 20% of my tasks get routed to Opus. Those are the tasks where the reasoning model's stronger multi-step planning genuinely produces better outcomes. If you set it too low, you pay Opus rates for tasks that Sonnet handles fine. If you set it too high, complex orchestration tasks fail partway through because Sonnet loses the thread.

The summarizer model is particularly valuable in multi-server setups where some tools return verbose output. Postgres query results with hundreds of rows, GitHub API responses with nested JSON, fetch results from documentation pages — all of these can balloon the context window quickly. The summarizer runs after each tool call and condenses the output to the relevant facts before it goes into the conversation context. This alone cuts my average token cost by roughly 30% on database-heavy workflows.

Pattern 10: Fallback Provider for Resilience

If Anthropic's API is degraded — which happens a few times a year — a Hermes instance without a fallback becomes completely non-functional. The fallback key configures an alternative provider that Hermes switches to automatically when the primary provider returns errors:

# ~/.hermes/config.yaml
model: anthropic/claude-sonnet-4-6

fallback:
  model: openai/gpt-4o
  env:
    OPENAI_API_KEY: "${OPENAI_API_KEY}"
  trigger:
    on_error_codes: [429, 500, 502, 503, 504]
    consecutive_failures: 3            # Switch after 3 consecutive failures
  recovery:
    check_interval_seconds: 300        # Check primary provider every 5 minutes
    return_after_successful_checks: 2  # Return to primary after 2 successful health checks

The fallback model does not need to match the primary model's capability tier exactly — it needs to be good enough to handle the tasks your cron jobs and automated workflows run while the primary provider is down. I use GPT-4o as the fallback for Sonnet because the capability overlap is high and the MCP tool calling behavior is similar enough that my existing workflows work without modification.

One thing to watch: fallback models may have different tool calling output formats, especially for complex nested tool calls. If your downstream code parses Hermes's output programmatically, test it against the fallback model before relying on automatic switching in production.

Pattern 11: Capability Filter Discipline

The include and exclude keys apply at the server level, but there are two additional capability types you can filter that most documentation does not mention: prompts and resources. MCP servers can expose three capability categories — tools, prompts, and resources — and Hermes enables all three by default:

# ~/.hermes/config.yaml
model: anthropic/claude-sonnet-4-6

mcpServers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

    # Tool capability filter (whitelist)
    include:
      - list_issues
      - get_issue
      - create_issue
      - add_issue_comment

    # Explicitly disable prompt and resource capabilities
    # These add unnecessary context overhead in tool-only workflows
    capabilities:
      prompts: false
      resources: false
      tools: true

  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem@1.9.2", "/Users/yourname/projects"]
    capabilities:
      prompts: false      # No prompt templates needed — we use the top-level systemPrompt
      resources: true     # Keep resource access for file content fetching
      tools: true

Disabling unused capability types reduces the size of the MCP capability advertisement that Hermes sends to the model at the start of each conversation. In a five-server setup, a full capability advertisement can run to 4,000-6,000 tokens before the user has said a word. Turning off prompts and resources on servers where you only need tools cuts this by 30-50%.

The exclude key is the alternative to include when you want most tools but need to block specific ones:

mcpServers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
    exclude:
      - delete_repository
      - create_repository
      - delete_branch
      - force_push

Use include when you want a small, well-defined set of tools (fewer than 10). Use exclude when you want most tools but need to block specific destructive operations. Never use both on the same server — if you specify both include and exclude, Hermes v0.13.0 applies include first and ignores exclude. This behavior may change in future versions.

Pattern 12: Production Diagnostics

When something goes wrong in production — a tool call hangs, a cron job fails, the dual-stack produces unexpected results — these are the diagnostic commands I run in order:

Step 1: Full doctor check

hermes doctor --verbose
# The --verbose flag checks MCP server reachability individually
# Output includes per-server connection test results

Step 2: List connected tools

hermes tools list --mcp
# Shows all tools currently registered from all connected MCP servers
# With --mcp flag, groups by server and shows server health status
# Example output:
#
# [mcp:filesystem] HEALTHY (7 tools)
#   read_file, write_file, list_directory, create_directory,
#   move_file, search_files, get_file_info
#
# [mcp:github] HEALTHY (4 tools, 2 excluded)
#   list_issues, get_issue, create_issue, add_issue_comment
#
# [mcp:slow-api] CIRCUIT_OPEN (circuit opened 3m ago, recovery in 57s)
#   (no tools available — circuit breaker active)

Step 3: Inspect recent tool call logs

hermes logs --last 50 --format json | jq '.[] | select(.type == "tool_call")'
# Shows the last 50 log entries filtered to tool calls only
# Each entry includes: timestamp, tool_name, server, duration_ms, status, error (if any)

Step 4: Replay a failed task with debug logging

hermes run --task "your failed task description"   --debug   --log-file /tmp/hermes-debug-$(date +%Y%m%d-%H%M%S).json
# Runs the task with full tool call tracing enabled
# Writes structured log to /tmp/ for inspection

Step 5: Test a specific MCP server connection in isolation

hermes mcp test --server github
# Runs the connection handshake for a single MCP server
# Reports capability negotiation, tool list, and a test tool call
# Useful for isolating whether a failure is in Hermes itself or the MCP server

Step 6: Cron job inspection

hermes cron logs --job daily-digest --last 10
# Shows the last 10 runs of a specific cron job
# Includes task output, step count, duration, and failure reason if applicable

The structured JSON log format (Pattern 12, step 3) is essential for debugging failures that are intermittent or time-sensitive. I pipe these logs to a simple monitoring script that alerts via Telegram when error rates exceed a threshold. The log format is stable across Hermes patch versions — the fields type, tool_name, server, duration_ms, and status are documented in the v0.13.0 changelog as stable public API.

Full Production Config Reference

Here is the complete config.yaml that combines all 12 patterns into a single production-ready file. This is my actual config, sanitized for sharing:

# ~/.hermes/config.yaml
# Hermes v0.13.0 — Full production config
# Last updated: 2026-05-16

model: anthropic/claude-sonnet-4-6

systemPrompt: |
  You are a senior development orchestration agent. You plan and execute
  multi-step development workflows using your available tools. You do not
  write code directly — delegate code generation to the claude_code tool.

  Behavioral rules:
  - Always read the current git status before modifying files
  - Always run tests after modifying code (use bash tool to run npm test)
  - Always commit changes to a feature branch, never directly to main
  - Prefer reading documentation before making architectural decisions
  - Summarize what you did at the end of every task

models:
  router:
    provider: anthropic
    model: claude-haiku-4-5-20251001
    temperature: 0.0
    use_for: task_classification
  reasoner:
    provider: anthropic
    model: claude-opus-4-7
    temperature: 0.3
    use_for: complex_planning
    max_tokens: 8192
  summarizer:
    provider: anthropic
    model: claude-haiku-4-5-20251001
    temperature: 0.0
    use_for: result_summarization

fallback:
  model: openai/gpt-4o
  env:
    OPENAI_API_KEY: "${OPENAI_API_KEY}"
  trigger:
    on_error_codes: [429, 500, 502, 503, 504]
    consecutive_failures: 3
  recovery:
    check_interval_seconds: 300
    return_after_successful_checks: 2

routing:
  classify_tasks: true
  auto_route_complex: true
  complexity_threshold: 8

mcpServers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem@1.9.2", "/Users/yourname/projects"]
    capabilities:
      prompts: false
      resources: true
      tools: true

  git:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-git@0.6.2"]
    env:
      GIT_AUTHOR_NAME: "Hermes Agent"
      GIT_AUTHOR_EMAIL: "hermes@yourproject.local"
    capabilities:
      prompts: false
      resources: false
      tools: true

  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
    include:
      - list_issues
      - get_issue
      - create_issue
      - add_issue_comment
      - list_pull_requests
      - create_pull_request
    capabilities:
      prompts: false
      resources: false
      tools: true

  postgres:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    include:
      - query
      - list_tables
      - describe_table
    use_gateway:
      timeout_seconds: 60
      retry:
        max_attempts: 2
        backoff: exponential
        initial_delay_ms: 500
      circuit_breaker:
        failure_threshold: 3
        recovery_timeout_s: 120
    capabilities:
      prompts: false
      resources: false
      tools: true

  claude_code:
    command: claude
    args: ["mcp", "serve"]
    description: "Claude Code — use for all code generation, TypeScript, React, and file edits"
    include:
      - edit_file
      - create_file
      - read_file
      - run_bash_command

serve:
  transport: stdio
  name: hermes-orchestrator
  description: |
    Hermes multi-step development orchestrator. Accepts natural language task
    descriptions and executes them autonomously using filesystem, git, GitHub,
    Postgres, and Claude Code tools.

What the Dual-Stack Changes Day-to-Day

After running this setup for three months, the practical difference is that I spend significantly less time context-switching between tools. A task like "implement the subscription cancellation flow, write the API route, the client component, and the email notification, then open a PR" — which previously required me to coordinate multiple Claude Code sessions, manually run git commands, and interact with the GitHub UI — now runs end-to-end in a single Hermes invocation. Claude Code handles the code. Hermes handles the coordination.

The failure modes are real but manageable. MCP server startup time adds 2-5 seconds to the first tool call in a new session — this is the child process startup latency. In interactive sessions this is invisible. In cron jobs it is worth noting in your timeout calculations. The circuit breaker (Pattern 8) has saved me from cascading failures twice when my internal API was down. Without it, those cron jobs would have hung for their full timeout duration on every scheduled run until I manually intervened.

Version pinning (Pattern 1, the @1.9.2 syntax) is not optional in production. MCP server packages ship frequently and minor versions occasionally contain breaking changes in tool output format. Pin your versions, test before upgrading, and keep a note of which version is in production. I learned this the hard way when server-filesystem changed the list_directory output format in a patch version and broke a downstream script that was parsing the output.

Run `hermes doctor` as part of your deployment verification. If your deployment process changes environment variables or Node versions, a doctor check immediately after deploy catches configuration problems before they cause silent failures in production workflows. I have it in my post-deploy script alongside the standard HTTP health check.

Originally published at wowhow.cloud

Forem: Anup Karanjkar

Claude Code 2.1 Agent View & /goal: Autonomous Dev Guide 2026

What Shipped in v2.1.139 (And What Came After)

Agent View: The Session Dashboard You Have Been Waiting For

/goal: Tell Claude When It Is Done

Background Sessions: The Full Control Surface

New Agent Flags: Configure Everything

Three Workflows That Changed How I Work

1. The Background Audit

2. The Completion Gate

3. The Pinned Session

The /usage Command: Real Cost Visibility

What to Do Right Now

The CLAUDE.md templates, agent skill starters, and MCP server boilerplates for building these workflows are available at wowhow.cloud — pay once, configure once, ship reliably.

Claude for Small Business: 15 Workflows & Setup Guide 2026

What Is Claude for Small Business?

The 15 Workflows: What They Actually Do

1. Cash Flow Reconciliation and Forecasting

2. Month-End Close Packet

3. Sales Campaign Builder

4. Contract Generation and Signature Routing

5. Hiring and Onboarding Coordination

Skills vs. Workflows: The Distinction That Matters

The Permission Architecture: How Trust Actually Works

Pricing Reality Check

Limitations Worth Knowing Before You Commit

Who Should Start With Claude for Small Business

Getting Started: Four Steps

OpenAI Files for IPO: What Every Developer Building on OpenAI Needs to Know (2026)

What We Know About OpenAI's Financials

The Microsoft Restructure: What Actually Changed for Developers

API Pricing Under Public Market Pressure

Model Release Cadence and Research Openness

Building a Multi-Provider Strategy Before the IPO

The Competitive Landscape After Three Public AI Companies

Three Things Developers Should Do This Week

Zod Validation: Type-Safe APIs & Forms in TypeScript (Complete Guide)

Why Zod Over Alternatives

Core Schema Types

Object Schemas

Nested Objects and Arrays

Transforms: Parse and Reshape in One Step

Refinements: Cross-Field and Async Validation

API Request Validation in Next.js Route Handlers

Form Validation with React Hook Form

Schema Composition and Reuse

Environment Variable Validation

People Also Ask

What is the difference between parse and safeParse in Zod?

Can Zod schemas generate OpenAPI / JSON Schema documentation?

How do I handle validation errors in a way that maps to form field errors?

GitHub Actions CI/CD: Build a Complete Node.js Pipeline (2026)

Workflow Basics

Matrix Builds: Test Across Node Versions

Caching for Speed

Docker Build and Push

Deploying to a VPS via SSH

Secrets and Environment Variables

Reusable Workflows

Self-Hosted Runners

A Complete Pipeline: Test, Build, Deploy, Verify

People Also Ask

How do I prevent GitHub Actions from running on draft pull requests?

What is the difference between secrets.GITHUB_TOKEN and a personal access token?

How do I speed up npm install in GitHub Actions?

SQL Performance: Indexing, Query Tuning & Explain Plans (Developer Guide)

How PostgreSQL Picks a Query Plan

B-Tree Indexes: The Foundation

Composite Indexes: Column Order Matters

Reading EXPLAIN ANALYZE Output

Eliminating N+1 Queries

CTEs vs Subqueries

Window Functions

Index Maintenance

People Also Ask

When should I use a partial index instead of a full index?

Why does adding an index sometimes make queries slower?

What is the difference between EXPLAIN and EXPLAIN ANALYZE?

Web Scraping with Node.js: Puppeteer vs Cheerio (Complete 2026 Guide)

Cheerio: Fast Static Scraping

What is the difference between `parse` and `safeParse` in Zod?

What is the difference between `secrets.GITHUB_TOKEN` and a personal access token?

What is the difference between `waitUntil: 'networkidle0'` and `'networkidle2'`?

Use the `env` field in the server config to inject environment variables — pull values from your shell's existing env rather than hardcoding them. For team setups, use a secrets manager and inject at process startup. Never commit API keys or database credentials inside `.claude.json`.