All Agents Considered

I Built an Open Source MCP To Analyze Your Substack Data With Hermes And Codex

Dan Cucolea — Tue, 25 Aug 2026 13:51:27 GMT

A little while ago, I shared how I built a Substack API with Hermes and Codex and covered how a missing scheduling feature turned into the Unofficial Substack SDK. That article explained how I built the SDK, which was focused more on developers. Since then, I have added an MCP to it that runs directly on your computer.

This guide explains how to install and use it.

The premise was simple: I wanted Codex and Hermes (though it also works with Claude) to find my strongest posts, review my Notes, and run data analysis. The usual workaround involves copying figures from several Substack pages and pasting them into a chat, which was tedious.

So I added a read-only connection that lets Codex fetch the information it needs from Substack. You can install it without writing code, and the only technical part is copying a small settings block and adding your own publication details.

I’ll explain every step in plain English, including what the unfamiliar terms mean and where you need to be careful.

In This Edition

What the Substack connection does
How to add it to Codex safely
How to confirm that you connected the right account
Five prompts you can copy and adapt

What You’re Installing

You’ll configure an MCP server that runs exclusively on your computer and doesn’t rely on any external services. This means your data will only be shared between your Substack profile and your AI, so nobody else can see it.

Moreover, the connection is read-only. It can look at your profile, posts, Notes, subscriber totals, and recent activity. I specifically left out every action that would change your account, so Codex can’t publish, delete, comment, restack, or change your settings through this MCP.

The GitHub project also contains an SDK, which is a toolkit for developers who want to build their own software. You won’t use that part in this guide, and please make sure you know what you’re doing if you feel like you want to access the full capabilities of this project.

What You Need

The setup requires three items:

Node.js 18 or newer: This free program lets your computer run the MCP.
Your publication address: For example yourname.substack.com.
Your Substack session cookie: A private login value stored by your browser.

The word “cookie” sounds harmless, but this one proves that you’re logged in. Anyone who gets it may be able to access your account.

Treat it like your password.

Check Node.js

Open Terminal on macOS or Windows Terminal on Windows. Paste this command and press Enter:

node --version

If you see a version beginning with v18 or a higher number, continue. If the command isn’t recognised, install the current supported version of Node.js from its official website, then run the check again.

You can close the terminal after this check as the rest of the setup happens in a Codex settings file.

Start by logging in to Substack in your browser.

You can get it super easily by installing the EditThisCookie (V3)Chrome extension and copying the value of substack.sid=.

If you don’t want that then you must use your browser’s developer tools. On Windows and Linux, the usual shortcut is Ctrl+Shift+I. On macOS, use Cmd+Option+I, or just press F12 on your keyboard. The shortcut or tab name can vary slightly between browsers.

Look for a tab named Application or Storage, then open the cookie list for Substack. Find the row named substack.sid and copy the value column.

Copy the long value alone. Leave out substack.sid= and any other cookie entries.

I can’t stress this enough but you HAVE to keep this value private. It shouldn’t appear in a public prompt, screenshot, shared project folder, support ticket, or shared document.

Add It To Codex

There are 2 ways to do this. First, just go to Plugins, then click on the gear icon up top Manage, then click on MCPs and Add Server.

Complete it like this:

Name: substack  
Type: STDIO  
  
Command to launch:  
npx  
  
Arguments:  
-y  
unofficial-substack-sdk  
  
Environment variables:  
SUBSTACK_SESSION_TOKEN = eyJ...  
SUBSTACK_PUBLICATION_URL = yoursubstack.substack.com

Then just save and restart Codex. Everything should work once you open it up again.

The second way to install the MCP is a bit more complicated and manual. Codex keeps its personal settings in a file named config.toml.

On macOS and Linux, the usual location is:

~/.codex/config.toml

On Windows, it sits inside your user folder:

C:\Users\YOUR-NAME\.codex\config.toml

Folders whose names begin with a dot are sometimes hidden. On Windows, open File Explorer and paste the full path into the address bar after replacing YOUR-NAME. On macOS, open Finder, choose Go, then Go to Folder, and enter ~/.codex.

Open config.toml in a plain text editor such as Notepad or TextEdit. Create it if it doesn’t exist. If the file already contains settings, keep them and paste the block below at the end:

[mcp_servers.substack]
command = "npx"
args = ["-y", "unofficial-substack-sdk"]

[mcp_servers.substack.env]
SUBSTACK_SESSION_TOKEN = "your-substack.sid-value"
SUBSTACK_PUBLICATION_URL = "https://your-publication.substack.com"

You don’t need to understand the formatting. Change only the two values inside quotation marks at the bottom.

Replace your-substack.sid-value with the private cookie value you copied. Replace the example publication address with your real Substack address, including https://.

If the file already has a section beginning with [mcp_servers.substack], edit that section instead of adding a second copy. When creating the file in Notepad, check that it ends in .toml rather than .toml.txt.

Use the personal settings file for this connection. Settings kept inside a project can accidentally be copied or uploaded with the rest of its files, which creates an unnecessary risk for the cookie.

Save the file and restart Codex. The Codex desktop app, command-line app, and editor extension use the same MCP settings on the same computer, according to the official Codex MCP documentation.

The first request may take a little longer because npx, a helper installed with Node.js, downloads the MCP package before starting it. You don’t need to open the package or install a separate Substack app.

Check The Connection

Begin with a small request. This confirms the account before Codex pulls a larger set of publication statistics.

Paste this prompt:

Use my Substack MCP to confirm which account is connected and list my five most recent posts with their publication dates.

Stop after the list. Say so if the account or publication doesn't match.

Check the account name and post titles yourself. These three messages cover the most common setup problems:

The wrong publication appears: Correct the publication address in config.toml.
You see a login error: The cookie has probably expired or was copied incorrectly. Log in to Substack again, copy a fresh substack.sid value, and replace the old one.
Codex couldn’t start the MCP: Repeat the Node.js check from the earlier section.

Restart Codex after every change to the settings file.

Ask A Focused Question

A broad request such as “analyze my Substack” gives Codex too much freedom. It has to guess the period, the measurement that matters, and the kind of answer you want.

Your prompt should make four choices clear:

The goal: State the decision you’re trying to make.
The material: Name the post, Note, or period you want reviewed.
The limit: Ask for a short summary before requesting detailed records.
The standard: Tell Codex to label facts and guesses separately.

You can refer to an article by title instead of hunting for the behind-the-scenes number Substack assigned to it. Ask Codex to find the title first, confirm the match, and then inspect it.

Five Prompts Worth Saving

These prompts use normal language. Codex chooses the appropriate Substack tools behind the scenes.

Text inside square brackets is a blank for you to replace. For example, change [POST TITLE] to the exact title of your article. You can also change quantities such as “top 10” or “20 most recent” without touching your settings.

Review Your Publication

Use this when you want a broad view of what happened during a month or quarter.

Use my Substack MCP to review my publication from [START DATE] through [END DATE].

Rank the top 10 posts by new subscribers. Summarize the totals and average rates that Substack provides, then group the posts by section and content type.

Keep the detailed post rows out of the response. Separate the numbers Substack returned from your interpretation, then suggest two ideas I can test next month.

Review One Post

You can use the post title here. Codex can find its behind-the-scenes number for you.

Find the Substack post titled “[POST TITLE]” and confirm the title and date before analyzing it.

Summarize the available delivery, subscriber, link, referral, and reader-engagement figures. Point out anything Substack didn't provide instead of estimating it.

Give me two strengths, two weak points, and one follow-up question. Keep reported facts separate from your interpretation.

Compare Your Notes

Substack doesn’t always provide a reliable view count for Notes. This prompt uses visible reactions and conversations instead.

Use my Substack MCP to review my 20 most recent Notes.

Choose five Notes with the strongest visible response, then compare their reactions, restacks, direct replies, and replies inside those conversations.

Tell me if any reply count is incomplete. Don't rank the Notes by views unless Substack supplied a real view number.

Sort Your Notifications

This prompt asks Codex to prepare a shortlist. The read-only MCP can’t send the replies.

Use my Substack MCP to check my 20 most recent unread activity items.

Put replies and mentions ahead of restacks and lower-priority activity. Choose the five items that most deserve my attention.

Summarize the context and suggest one response angle for each. Leave every reply as a draft for my review.

Check Subscriber Totals

This prompt keeps individual subscriber records out of the conversation.

Use my Substack MCP to return a privacy-safe subscriber summary.

Show the total subscriber count and any overall figures Substack provides. Don't request names, email addresses, or individual subscriber records.

Explain what this snapshot tells me and where the available information stops. Don't calculate growth or churn unless Substack returned the history required for that calculation.

Ask For Summaries First

Codex has a limited amount of working memory in each conversation. Large blocks of raw data occupy space that the model could use to compare results and explain them.

Think of that working memory as a desk. A neat summary leaves room to reason. Hundreds of copied rows cover the desk before the useful work begins.

The MCP already reduces many responses before returning them. A publication review can read the email data Substack makes available while sending Codex a compact summary. Detailed rows stay out unless you request them.

Follow the same habit in your prompts. Start with a summary, choose the one post or Note that deserves attention, then ask a narrower follow-up question.

What Read-Only Protects

The MCP leaves every account-changing action unavailable. A mistaken prompt can’t publish a Note or delete a comment through this connection.

But read-only access still requires care. Your cookie opens the connection, and the information Codex receives becomes part of the conversation. Keep the cookie in your personal settings file and leave individual subscriber records out of your requests.

This project connects through parts of Substack’s website that aren’t documented for outside apps. Substack can change them without warning, meaning that a request that worked yesterday might fail today. If that’s the case then you might want to check the GitHub project page for an update or reported problem.

People building custom software can use the developer toolkit for Note publishing and other account actions. That route requires code, testing, and a human approval step. The read-only MCP is the better fit when you want to ask questions about your publication.

Your First Ten Minutes

Use this sequence:

Check that Node.js 18 or newer is installed.
Copy the value of your substack.sid cookie.
Paste the settings block into your personal Codex settings file.
Restart Codex and run the account-check prompt.
Choose one focused prompt from this guide.

Check important figures against your Substack dashboard while you learn how the connection behaves. Save the prompts that help, while keeping the private answers out of public screenshots and repositories.

The MCP finds the information. You decide what it means and what deserves to change.

What Should I Add Next?

I’m continuing to expand the read-only Substack tools around questions publishers still answer by hand.

What’s the most frustrating analytics question you still have to answer inside the Substack dashboard? Leave it in the comments, and I’ll use the replies to guide the next tool or tutorial.

You can find the public project on GitHub and its installation package on npm.

Everything I described here is one small example of the broader pattern behind the first Hermes 101 course: connect an agent to the tools and information you control, keep the sensitive parts local, and build a workflow you can inspect. I’m working on the course right now, and it should be ready soon. If you want the full step-by-step Hermes setup, that course is where it will live.

What Hermes Thinks I Do When I'm Not Talking To It

Dan Cucolea — Tue, 11 Aug 2026 12:44:11 GMT

I’ve spent months teaching Hermes the shape of my work, from where each project lives to the point where it should stop for a decision.

Last week I reversed the arrangement by giving Hermes a limited view of my recent work and asking it to describe the person behind those files.

My official title is full-stack AI engineer, but Hermes came back with something far less suitable for LinkedIn:

AI Workflow Field Reporter With a Side Cart of Websites

The phrase was ridiculous enough to make me laugh, yet it was accurate enough to keep me reading.

In This Edition

Hermes used my recent files to describe what I appear to do all day.
The audit exposed a gap between my engineering title and my visible output.
Editorial work left a clearer trail than many technical decisions.
The read-only boundary hid large parts of my actual working day.
You can reuse my prompt to audit a safe corner of your own workspace.

Here’s How It Works

Most AI tools learn about us through the tidy summaries we write before asking them to do any work.

A profile explains the job we claim to have, while a project note gives the agent a clean version of whatever we’re trying to finish. The result is a useful identity for the agent, although it rarely resembles the mess of an ordinary week.

On a normal day, I can move from researching an AI release to debugging a TypeScript problem without feeling that I’ve changed jobs. By evening, the useful part of either task may have become an article that still needs editing before I can publish it.

I wanted to see what Hermes would say if I stopped describing myself and allowed the artifacts to make the introduction.

This exercise was possible because most of my agent work already lives in plain files that both Hermes and I can inspect. I described that setup in Why My Best Agent Workflow Is Mostly Files, where a small amount of structure made the workspace easier for an agent to follow.

For this audit, I limited Hermes to the parts of my vault that record published work and the planning behind it. I also included working notes and a small set of professional documents, although I did have to sanitize the answer.

I treated each file modification as proof that some work had happened, while leaving effort and time outside the audit. Also, every conclusion needed a visible piece of evidence from inside that boundary.

The Job Title

Hermes sorted my work into a few basic categories and I observed that the actual connections mattered way more than the labels.

Publishing and research created the most visible output. These are the articles and guides people actually read.

Workflow design sat right underneath that surface layer. It mapped out how every project should move and also decided exactly where human input was needed.

The audit also looked way beyond my newsletter (I generalized that outside work for privacy). This gave Hermes the full picture of my career., basically stopping the system from treating AAC like an isolated hobby.

Seeing everything together produced a surprisingly accurate description. I never would have written it for myself.

You appear to be an AI workflow educator and operator who turns technical research and firsthand build stories into practical published guidance, while keeping several professional and commercial projects moving in the background.

That sentence would look totally ridiculous on LinkedIn, but it perfectly describes my actual daily life.

The Strongest Trail

The playful title gave me the opening for this article, but the strongest finding came from the evidence underneath it.

Hermes found the clearest record in my editorial work because I preserved the full path of each article from uncertainty to publication.

I traced ideas taking shape in the early files, then saw which claims actually survived my checks before publication.

Hermes saw way more than finished articles because I had documented the whole system behind them.

Hermes called the pattern editorial systems work, and the phrase stuck with me because people only see the writing at the end. I spend most of my effort deciding whether an idea deserves attention or whether a claim has earned the confidence I want behind it.

Part of my editorial work involves removing weak signals before they ever reached a draft, then shaped the surviving claims into explanations another person could follow.

I expected building to dominate the audit, but Hermes found that I built a lot of infrastructure just to support the workflows around my technical work.

Reading the files back, I saw engineering and writing as different stages of the same loop rather than two unrelated jobs sharing a calendar.

I build until something teaches me a useful lesson, then I preserve that lesson in a form another person can inspect.

That description fits AAC way better than saying I write about AI.

Uncovering the Weak Points

Hermes also found a gap between the identity I lead with and the work that left the most evidence behind. I foreground engineering because I build production AI systems that extend from the interface to the infrastructure underneath it.

But the recent artifacts told a broader story. I kept turning that technical work into explanations another person can use.

Inside the selected folders, engineering showed up more as the thing I was explaining than the thing I was building. That observation stung on the first read because it sounded like a challenge to an identity I know is accurate.

The audit boundary explained most of the tension since editorial work leaves a thicker paper trail than most engineering decisions. I might produce several visible drafts for one article, while the hardest technical decision of the week survives as a single changed line in a repository outside the audit.

Visibility favors work that documents itself, and that gave the editorial side of my week an obvious advantage.

Even with that limitation, the audit made it harder for me to dismiss publishing as a layer wrapped around my real work.

What Disappeared

Keeping the audit safe forced me to hide a huge part of my working day from Hermes. I kept my engineering work in separate folders and repositories and left almost no trace of my private interactions. This blind spot also swallowed any experiment that failed before I wrote down the results. Hermes just described my best-documented work instead of reconstructing my actual calendar.

The system captured that limitation perfectly in one line:

A file trail records exhaust. rather than the engine.

That distinction keeps the exercise useful since the agent only describes visible work instead of pretending to value everything outside the frame. A polished plan might represent a project I never started. Meanwhile, a single modest code diff might represent the hardest afternoon of my month.

The audit also exposed a smaller operational problem.

Some article projects contained several drafts without a clear current version. Those files proved I did the editing, but they forced Hermes to waste extra effort deciding which draft actually mattered.

I previously found the larger version of this mess when I ran the twenty-minute audit that showed where Hermes was getting lost. Seeing this exact problem pop up as a footnote today tells me even my digital biographer needs stricter file naming.

There’s A Valuable Lesson Here

The audit gave me a much clearer description of the loop I repeat across all my projects. A technical problem always starts the cycle, and the useful lesson becomes the only thing worth preserving once I finish the immediate work. I often turn that lesson into an article because writing forces me to explain exactly what happened without relying on the original conversation.

This exact loop explains why I ditched isolated prompts and started building workflows that leave evidence between steps.

I described this process in How to Build AI Workflows When You’re Tired of Optimizing Prompts by showing how one step writes something the next step can read. Hermes reconstructed my recent work entirely from the residue of those handoffs.

That happy accident turned the whole audit into a live test of my system.

The weak spots in the final answer showed exactly where my ongoing projects still need a better handle for the next session. Dropping a small current-state note into the folder usually saves a project when it needs to survive beyond the original conversation. Passing thoughts can still disappear naturally without forcing me to turn my whole workspace into a diary.

And those existing files gave Hermes just enough evidence to spot my patterns (to a point) without relying on constant activity tracking or screen recording.

Your Turn

You can run a smaller version of the same exercise over a few folders you already control.

Choose a recent time window and keep the task read-only so the audit can’t reorganize the evidence while inspecting it.

Exclude private material before the run, then require the agent to cite the files behind each conclusion.

This is the prompt I used:

I want you to describe what I appear to do for work based on the
artifacts I leave behind.

This is a read-only audit. Don't create, edit, move, rename, or
delete anything.

Inspect work produced or modified during the last 30 days inside
these folders only:

[LIST SAFE FOLDERS]

Skip credentials and private material.

Treat file changes as evidence that work happened, without using
them to estimate time or effort.

Give me a one-sentence description of what I appear to do.

Give me a playful job title based only on the evidence.

Describe the strongest pattern you found and cite the files that
support it.

Explain which part of my work is likely invisible to this audit.

Compare the evidence with my official job title only after reaching
your conclusion.

Separate direct evidence from inference.

End with a short section called "Where I Might Be Wrong."

Keep the tone observant and lightly humorous rather than judgmental.

Read the result as a mirror whose frame you chose rather than a performance review with any authority over your working life.

Correct the parts it gets wrong before removing anything too private to share outside the workspace.

Then pay attention to the work it can’t see, since missing evidence may explain more than the confident conclusions.

What’s the playful job title your agent gave you?

Behind the Title

My official title still says full-stack AI engineer, but the weird title Hermes generated remains way too strange for my next family gathering.

That strange title highlighted a habit I usually downplay because my writing grows naturally straight from my technical work.

My commercial projects sit right next to those two main areas since I apply that exact same habit to my business work. I always turn useful builds into plain explanations that other people can actually use.

My public work creates very clean file folders while private conversations leave almost zero evidence behind for an AI to read. Hermes only analyzed this heavily documented version of my career, yet I still completely recognized myself inside that incomplete picture.

This exercise proved I built a clear enough trail for a machine to follow without pretending this final summary captures my entire reality. My official job title just names the foundation, and these files show exactly what I keep building on top of it.

The One File That Made Hermes Finally Learn From Its Mistakes

Dan Cucolea — Tue, 04 Aug 2026 12:57:20 GMT

Some time ago, I covered my Hermes research workflow. It runs every week, sorts through tens of tech news publications and forums, and filters out the fluff so I can stay on top of everything that is going on. It took me a few tries to get it right, but now I can safely rely on it.

That trust came from two early mistakes. On the first real run, Hermes ranked a generic news item too highly because my definition of practical tech news was too loose. I tightened the instruction and ran it again.

On the second run, a vendor press release passed the filter because I never told Hermes to exclude vendor press releases. I added that rule, ran it a third time, and got a clean result.

The workflow got better, but the reason why it got better simply vanished.

If you’d open my final instruction file now, you’ll see one clean rule: reject vendor press releases. You do not see the bad output that created the rule, why the first wording failed, or the result that proved the fix worked.

Hermes still remembers my projects, files, and old conversations. It also squeezed the useful lessons from those failed runs into one line with no history. And that bothers me because the next mistake it makes might be less obvious. A tool may fail only on one server. An API may accept a believable field name and ignore it. A workflow may write to the wrong folder and still report success.

So I figured we can’t let the AI bury these critical lessons in old chat logs.

That’s why I started adding one file to each repeated workflow:

MISTAKE_LEDGER.md

This article explains what belongs in it, what does not, and the small instruction I use to stop an agent from turning every failed attempt into permanent bad advice.

In this edition

Why persistent memory still loses operational lessons
Where a Mistake Ledger fits inside a file-based workflow
The four-step rule that keeps guesses out of the ledger
A complete instruction you can paste into Hermes or Codex
The failure modes that make a mistake ledger worse than no ledger

Memory Keeps Context

I have argued for months that memory changes what an AI agent can do.

An agent that carries project details and preferences across sessions beats a blank chat window every time. I wrote about this shift in Forgetting to Forget when persistent memory made long-running agent work feel possible.

I still believe that.

The mistake was treating memory and learning as the same thing. Hermes Agent v2026.6.5 describes its built-in memory as a bounded, curated set of user preferences, project details, environmental context, and learned information. Session logs preserve more of what the system did.

An operational lesson serves a different purpose. It tells you what failed, what fixed it, and when that fix applies again.

Those are three different layers.

The exact correction may still exist in an old conversation, but that does not mean it will enter the context of a new run six weeks later. Hermes built-in memory is injected as a bounded snapshot at the start of a session rather than retrieved as a complete archive of every old chat. The useful lesson can remain buried in conversation history even while the agent remembers the project.

On March 21, 2026, an Ask HN post about operational memory called this missing layer an “Agent Experience Cache.” The post listed tool quirks, repeatable workflow patterns, environment-specific knowledge, and failure modes that cost too much time to rediscover.

That idea made sense to me, but I wanted a smaller version that I could read without adding another memory service.

One Markdown file beside the workflow felt like the right size.

Keep Mistakes Local

My first instinct was to create one global file containing every mistake made by Hermes or Codex.

That file would become useless fast.

My content research workflow, Substack analytics tools, server deployments, and draft-writing system fail for different reasons. A rule learned while deploying software should not make Hermes cautious while sorting research. Likewise, a correction about brand sources should not influence how Codex handles a server path. Both Hermes and Codex share the same files and workflows through my Obsidian vault.

The mistakes should live where the work happens.

I already use an INDEX.md file to map large workflows. I explained that setup in Why My Best Agent Workflow Is Mostly Files.

Inside the project, each repeated workflow gets its own small folder. My research sorter came from the four-file pattern in Tear Down Your AI Workflow and Rebuild It Like This:

01.Research Sorter/
├── 01.instructions.md
├── 02.input.md
├── 03.output.md
├── 04.review.md
└── MISTAKE_LEDGER.md

The first four files tell Hermes how to run the work. The fifth preserves the verified lessons produced by running it.

If a project contains one workflow, project-specific and workflow-specific mean the same thing. Once a project contains several repeated processes, separate ledgers keep the lessons scoped.

Because the ledger is visible and readable, I can challenge an entry, edit its scope, or retire the advice after a tool changes. I do not have to rely on a memory entry or session log that sits apart from the workflow it affects.

If the same lesson appears across several workflow ledgers, I can promote it into a wider agent instruction after reviewing it.

What an Entry Holds

The file needs enough detail to stop the same error without becoming a diary of everything that went wrong.

Each entry records seven fields:

Date
Task
What went wrong
Confirmed cause
Verified fix
When this applies
When to recheck or retire it

If the ledger had existed when I built my research workflow, the vendor PR entry would have looked like this:

## YYYY-MM-DD: Vendor PR passed the research filter

**Task:** Sort research items into All Agents Considered article observations.

**What went wrong:** A vendor announcement was kept as a strong
article signal even though no independent technical source discussed it.

**Confirmed cause:** The filter excluded broad news but did not
explicitly exclude vendor PR as a daily input.

**Verified fix:** Add vendor PR to the exclusions and require an
independent technical source before keeping a vendor announcement.

**When this applies:** Every All Agents Considered research-sorting run.

**Recheck or retire:** Recheck if the source policy changes.

This is a reconstruction from the failure I documented in the earlier article.

I did not have a ledger then, so I am taking a pattern already hidden inside my workflows and making it visible.

Verify Before Recording

AI agents write terrible rules when they update their own instructions after every failure. One plausible guess can harden into a permanent constraint before anyone checks whether it explains what went wrong.

During one weekly research run, Hermes kept a promotional article from a vendor’s own website and treated it as independent reporting. When I told it to remove the article, Hermes guessed that the missing ingredient was a deep technical quote. It proposed a permanent rule requiring one in every future submission.

The diagnosis sounded plausible, but it focused on the article’s format when the source was the real warning sign. The piece appeared on the vendor’s corporate domain and repeated the company’s marketing claims without support from independent reporting. The useful lesson was to treat articles on vendor-owned domains as promotional unless an independent source supported them. Recording Hermes’s first guess would have taught the workflow to reject legitimate news briefs because the reporter did not include a direct quote.

That is why I have to verify the root cause with my own eyes before the agent turns a plausible explanation into a permanent lesson.

Building my unofficial Substack SDK exposed the same problem in code. Hermes proposed scheduled_at as the field for scheduling a post. The choice looked logical because plenty of other APIs use that naming convention. The Substack scheduling endpoint I tested expected trigger_at instead.

An automated test now checks the request body and fails if the implementation sends a different field. That gives me proof outside the conversation instead of another confident answer from an agent.

I covered the full story in How I Built a Substack API With Hermes and Codex. Without that hard check, neither field name would deserve a permanent spot in a Mistake Ledger.

Based on that experience, I created a strict four-step rule that keeps guesses out of my final documentation:

Catch: Workflows fail, I correct the AI, or the AI spots a bad assumption.
Fix: I finish the task before writing down a lesson.
Verify: I prove the fix works using a result outside our chat.
Record: I add one specific entry to the workflow ledger.

Real proof makes or breaks the verification step. It can come from passing code tests, live API responses, correct files landing in the right folders, or final outputs meeting exact standards. AI confidence alone proves nothing.

The Tiny Instruction

The working version fits in one instruction-only skill. There is no script, service, database, or download.

You can paste the text into a Hermes or Codex task. If you want it available across repeated sessions, save the same block as SKILL.md.

---
name: mistake-ledger
description: Record a verified reusable lesson after a workflow
failure or user correction, and check the current workflow's
MISTAKE_LEDGER.md before running related work.
---

# Mistake Ledger

Before running a repeated workflow, check whether its folder contains
MISTAKE_LEDGER.md. Read only that workflow's ledger and apply relevant
active lessons. State which lesson you are applying.

When a task fails, the user corrects you, or you discover a wrong
assumption:

1. Fix the problem first.
2. Verify the replacement through an observable result.
3. Record a lesson only when it is concrete, reusable, and scoped to
   this workflow.
4. Append one entry to MISTAKE_LEDGER.md with:
   - date
   - task
   - what went wrong
   - confirmed cause
   - verified fix
   - when this applies
   - when to recheck or retire it

Do not record speculation, secrets, private content, or one-off user
preferences. Do not turn an unverified diagnosis into a permanent rule.
Mark outdated lessons as retired instead of deleting them.

Hermes users can keep the repeated version under ~/.hermes/skills/, or add a shared folder to skills.external_dirs in ~/.hermes/config.yaml. The Hermes Agent v2026.6.5 skill documentation describes both routes.

If you keep the instruction inside the workflow folder without configuring that folder as a skill directory, ask Hermes to read the file before the run.

Codex users can save the same instruction at .agents/skills/mistake-ledger/SKILL.md inside a repository. The current OpenAI Build skills documentation describes the required SKILL.md format.

Test the Next Run

Creating the file proves nothing by itself. The next run must show that the recorded lesson changed the workflow’s behavior.

My next research test is straightforward. I will place a vendor announcement in 02.input.md beside several independent technical stories. I will then run the workflow and check three things:

Did Hermes read MISTAKE_LEDGER.md before scoring the items?
Did it state that the vendor PR lesson applied?
Did it exclude the announcement unless an independent technical source supported it?

The same test works for other workflows. First, reproduce the conditions that caused the original failure. Then check whether the agent applies the relevant lesson without being reminded.

I also need to measure the cost of using the ledger. If Hermes starts citing irrelevant history on every run, the ledger has created a new problem. It should reduce repeated work without becoming a compliance manual that the agent must review before every task.

This method still needs several real repetitions before I make stronger claims about it. I expect the trigger wording, retirement rules, and promotion threshold to change as I use it across more workflows. That uncertainty belongs in the build log. A clean ending would give the method more confidence than it has earned.

When the Ledger Lies

A Mistake Ledger creates five failure modes of its own. Any one of them can make the workflow worse:

False causality: The agent records a symptom as the cause. It then applies the wrong fix every time the workflow runs.
Bad scope: The agent promotes a useful lesson from one workflow into a universal rule. That rule starts interfering with unrelated work.
Stale advice: APIs change, tools get updated, and folder structures move. A correct fix can eventually become a new bug.
Noise: Every typo, failed search, and abandoned idea enters the ledger. Hermes then has to sort through a second pile of clutter before starting the real task.
Exposure: A careless entry preserves credentials, private customer information, session cookies, or sensitive tool output. None of that information belongs in a file the agent keeps reading.

Some repeated failures reveal a broken workflow structure rather than a reusable lesson.

If Hermes keeps selecting an archived file because current and old drafts live together, the folder structure needs fixing. If every output lands in a new location, the workflow needs a defined destination. Recording “pick the current file next time” only hides those structural problems from the next run.

Before turning that kind of confusion into a permanent lesson, run the audit from The Twenty Minute Audit That Found Where Hermes Was Getting Lost. The audit will show whether the agent’s map of the work is the real problem.

My dividing line is simple:

If Hermes cannot find the right work, fix the map. If it finds the right files and still repeats the same operational error, record the lesson.

Try It in 60 Seconds

Open one workflow that you run more than once. Think of the last correction you gave the agent. Then confirm that the replacement worked outside the conversation where you suggested it.

If you still do not know what caused the failure, stop there. An unverified correction has not earned a permanent entry.

Once the fix is verified, create MISTAKE_LEDGER.md inside the workflow folder. Record the seven fields while the evidence is still easy to inspect.

On the next run, ask the agent to read the ledger first and state which lesson applies. Do not remind it of the original error or steer it toward the answer.

That run is the test. You do not need a new model, an extra memory service, or a global database containing everything your agent has ever done. One workflow and one verified mistake are enough to test whether the lesson survives the conversation where it was learned.

Give Failure a Job

The clean version of my research workflow hides the two failed runs that shaped it. The final instructions preserve the rules without showing which mistakes forced me to add them.

That makes the instructions easier to read. It also removes the operating history I will need when a rule starts causing trouble.

Six months from now, I want to know why a rule exists before I delete it. Hermes should understand when the rule applies without searching old conversations. Both of us should see when the advice has expired.

These tools support different parts of the same system. Project maps and workflow folders make the work findable and repeatable. Audits expose structural defects before they become permanent instructions. The Mistake Ledger preserves verified failures after the immediate problem has been fixed.

The ledger does not turn Hermes into an agent that trains itself. It gives the next run a short piece of reviewed evidence from the last one. That is enough for version one.

What mistake does your agent keep repeating? Tell me whether it belongs in a workflow ledger or whether the workflow itself needs fixing.

Everything I described here is the field-notes version. I built the Mistake Ledger because my research workflow kept surfacing the same vendor PR problem until I wrote the lesson down and watched the next run actually use it. That small experiment, one folder, one verified entry, one retest, convinced me the pattern was worth teaching properly. The step-by-step version of how I apply this across every workflow I run goes into the first Hermes 101 course. I am building it right now and it should be ready soon.

If the broader stack is what you are after, I wrote about the full cost breakdown and the morning workflow that runs on it. Both depend on the same file-based workflow structure to stay reliable across sessions.

Capability is cheap when the foundation is broken. Audit one folder. Fix one thing. Then decide whether you need another tool.

How Pangram Decides What Looks Like AI

Dan Cucolea — Tue, 28 Jul 2026 12:37:08 GMT

I have no doubt you already know that last week Substack just attached an AI detector to every article on the platform.

The new “Scan for AI” feature lets readers analyze a post, Note, comment, or reply with Pangram, which estimates how much of the writing is human, AI-assisted or written by AI.

And the percentage it returns might looks precise, like a speed camera telling you exactly how fast you were going.

But Pangram did not watch the person type, check their browsing history, or find a hidden signature left by ChatGPT or Claude. It looked at the finished text and decided what the writing resembled.

That distinction sits at the center of the argument happening across the Substack, professor, and AI research subreddits.

Some people think these detectors generate little more than a random number. Others treat the score like a confession.

Both sides are missing the point.

Pangram is pretty good at identifying obvious AI writing, and it has more behind it than the early tools that made AI detection a laughing stock. In independent testing from the University of Chicago, it identified writing from widely available AI models with low error rates under the conditions studied.

But it is not perfect. Some model output and repeated paraphrasing can evade it, and human writing can still be classified incorrectly.

A low AI score does not prove that no AI was used, just as a high score does not prove an algo wrote the text. Pangram is a serious pattern detector, not a yes-or-no authorship test. It cannot magically settle the question of authorship. So today I am going a bit out of the way with the main topics of AAC to show you the truth behind Pangram and AI detectors.

In this edition I’ll cover how Pangram is trained, what its score measures, why it differs from older detectors, and where it fails, without pretending the tool can prove with 100% certainty who wrote a piece a text.

In this article:

Why older AI detectors earned so much distrust
How Pangram learns to identify AI patterns
What its percentage does and does not mean
The strongest evidence that it works
The known ways it can fail
How to use a result without accusing the wrong person

Why Everyone Hates AI Detectors

Early AI detectors often leaned heavily on two ideas called perplexity (not the tool) and burstiness.

Perplexity asks how surprised a language model is by the next word. AIs are trained to predict the next word, that’s literally written in the DNA of all LLMs. On the other hand, our human writing patterns are less predictable just because our writing tends to be messier.

Burstiness asks whether sentence lengths and structures vary. Humans may write one clipped sentence, then an overgrown paragraph, followed by a shorter sentences. AI models usually settle into a steady rhythm (like the Rule of 3’s).

You don’t need me to point out that these “AI detection” techniques are fundamentally flawed. Imagine judging whether bread came from a factory by checking whether every slice has the same thickness. That clue may help in some cases, but it doesn’t tell you exactly who baked the loaf.

A safety manual is predictable because it needs to be. A legal form repeats itself because consistency matters. A non-native writer may use simpler sentence patterns.

A poet may produce language so unusual that the detector has little familiar ground beneath it.

This is why old detectors produced absurd headlines. In 2023, Ars Technica reported that one detector labeled part of the US Constitution as likely AI-generated. A 2023 academic review of detection tools also found serious reliability problems, especially after text was edited or paraphrased. Pangram argues that those two measures alone fail as a basis for detection.

Thus an online myth was born: AI detectors don’t work.

Before we go into why Pangram is truly different, we really have to get this out of the way. Pangram is not the only trained detector in 2026. GPTZero describes a multiclass model for human, mixed, polished, generated, and paraphrased text. Originality says its current detector uses a trained transformer model built from human and generated examples.

Pangram Does Not Search for an Em Dash

Pangram is a trained classifier.

Researchers train it on many documents labeled by source: human-written or AI-generated. From those examples, the detector learns which combinations of patterns tend to distinguish one group from the other.

Think of it like teaching someone to recognize counterfeit passports rather than giving them a checklist of what a document should contain. Side note: this reminded me of the game Papers, Please.

Pangram says its flagship detector uses a transformer model adapted to classify sequences of text. Its technical explanation and original research paper describe a system that learns from human writing and model-generated writing. Basically they created an AI that can detect AIs.

It does not call OpenAI to ask whether ChatGPT wrote the paragraph. It does not recover the prompt. It does not compare the post with a giant database of every answer an AI company has produced. There’s literally no need for that.

Pangram learns what different kinds of writing tend to look like, then it analyzes the text you feed it against that map.

This should also clear up the em dash frenzy.

Pangram can show human-readable supporting clues such as em dashes, lists, headings, stock phrases, Markdown, and groups of. But Pangram says those visible clues are separate from the flagship detector. They help a reader inspect the text and show that they are not the inputs driving the main model.

To better put this into perspective, imagine a prisoner just escaped from incarceration. Deleting every em dash is like removing their striped shirt before a facial-recognition scan. The prisoner changed something visible without necessarily changing what the system recognizes.

Pangram Trains on Twins

The most interesting difference is how Pangram constructs its training set.

Suppose we trained a detector using personal diaries as the human examples and software landing pages as the AI examples. It might appear accurate while learning the wrong lesson. Instead of detecting AI, it could learn that feelings are human and product features are synthetic.

Pangram tries to prevent that shortcut with what it calls synthetic mirroring.

For each human document, it creates an AI counterpart about the same subject, in a similar tone and style, carrying similar information. A human book review is compared with an AI book review of the same material. A human essay is paired with its AI twin.

The detector must find differences between twins rather than compare a shopping list with a sales page.

Pangram’s model card says its human training material covers essays, reviews, books, creative writing, news, scientific papers, Wikipedia, and general web text. Its AI side is generated in-house to create those matched comparisons. Then it makes the exam even harder.

Pangram scans large collections of known human writing and looks for passages the detector wrongly calls AI. Researchers add those mistakes back into the training data, create AI mirrors for them, and train again.

This technique is called hard-negative mining.

There’s a famous story from World War II based on the statistician Abraham Wald. The military engineers were asked to examine aircraft that returned from battle and map where they had been hit. In most cases, the wings and fuselage were covered in bullet holes, so the obvious response was to reinforce those areas.

Wald argued that the military was looking only at surviving aircraft, but if those planes could return despite being hit in the wings and fuselage, then those areas were not the most vulnerable. That’s how he figured out the places with few bullet holes (like the engines) needed more protection.

Hard-negative mining follows a similar principle. The most useful evidence often comes from the cases a system mishandles. So instead of repeatedly training a detector on obvious AI writing, researchers study the difficult human passages Pangram (initially) falsely identified as AI and feed those mistakes back into the training process.

Pangram’s Open Model Is Not the Substack Model

Pangram has released public code, data links, and model weights through its EditLens repository. The project accompanies a paper accepted at ICLR 2026 on measuring degrees of AI editing.

That is meaningful transparency. It lets researchers inspect and reproduce part of the method without trusting a marketing page.

What it doesn’t reveal is the complete system running inside Pangram’s commercial product.

The public repository contains two smaller research models and instructions for training them. Pangram’s Open Pangram announcement explicitly says the release is a research baseline and should not be used to enforce AI policies in schools or workplaces.

The current commercial model described by Pangram is version 3.3. Its model card documents a larger production system with later training and scanning changes. Substack publicly confirms the Pangram integration, but its help page does not name the exact model version or threshold it uses.

What the Percentage Means

We can all agree that teal writing has made binary detection obsolete.

A writer may create the first draft, ask Claude to tighten one section, run the result through Grammarly, dictate a new ending, and then rewrite every sentence by hand. Which words belong to whom?

Pangram’s EditLens research tries to measure that grey area. Researchers begin with human text, ask models to edit it at different intensities, and compare each edited version with the original. A classifier then learns to estimate the degree of editing from the final text.

The full EditLens paper states the important limitation of its method. When the detector checks your article, it doesn’t receive your original draft. It only sees the final text.

The estimate is like a restorer examining a painting and guessing how much has been retouched. They may recognize signs of later work, but they can’t count the extra brushstrokes.

For long documents, Pangram breaks the text into overlapping windows, checks each window, then makes a finer pass near uncertain boundaries. Its 3.2 model card describes an approximate resolution of 50 words.

Pangram can then describe shares of a document as Human, Lightly AI-assisted, Moderately AI-assisted, or AI. A result such as 30% AI refers to the share of classified text segments assigned to that category.

It does not mean:

There is a 30% chance the writer used AI
A machine typed exactly 30% of the words
Pangram found the original prompt
The writer contributed only 70% of the thinking

Ideas, wording, structure, research, and final judgment are different contributions. No detector can reduce all of them to one authorship percentage by reading the final copy.

This is where Substack’s interface creates a social problem. A percentage looks like a measurement, but underneath it’s just a classification.

The Evidence That Pangram Works

The strongest independent evidence I found comes from the 2025 University of Chicago working paper Artificial Writing and Automated Detection.

The researchers gathered 1,992 verified human passages across blogs, novels, résumés, essays, business writing, and other genres. They produced matched AI versions using GPT-4.1, Claude Opus 4, Claude Sonnet 4, and Gemini 2.0 Flash.

On medium and long passages in that test, Pangram produced essentially zero false positives and false negatives. It outperformed GPTZero, OriginalityAI, and an open RoBERTa detector in the same experiment.

That should clear up the myth that “AI detectors never work”.

But this should also be taken with a grain of salt. The paper was, after all, a working paper. The test used a controlled set of matched human and synthetic documents. It evaluated the Pangram service available in May 2025 and it did not test every Substack voice, mixed editing workflow, new model, humanizer, or unusual format.

Pangram’s current numbers come from Pangram. Its 3.3 model card reports a 0.01% false-positive rate for long-form creative writing, 0.02% for academic writing, 0.04% for multilingual how-to articles, and 0.49% for poetry.

It also reports a 1.5% false-negative rate on a random Chatbot Arena set.

Those are impressive company-reported results, but they shouldn’t be treated as promises about the next text you scan.

The clearest warning comes from a competing test. In February 2026, GPTZero published its own benchmark and reported that GPTZero 4.3b beat Pangram 3.2 on its datasets.

That does not prove GPTZero is better. It proves the winner changes with the test set, model version, threshold, and person running the test.

I made the same argument in my breakdown of why AI benchmarks fail real agent workflows. A leaderboard compresses the conditions into one number, but conditions change and can be picked arbitrarily.

Where Pangram Messes Up

Pangram’s own documentation says it works best on long-form prose written in complete sentences, like a Substack post.

Its 3.3 limitations warn about bullet lists, technical instructions, tables of contents, references, templates, equations, headers, and footers. Poetry has a much higher reported false-positive rate than long creative prose.

Short text creates another problem. Just as a smoke detector cannot identify much from a few molecules in the air, Pangram can not correctly classify a short text.

Then there are false negatives.

A May 2026 preprint titled Base Models Look Human To AI Detectors found that output from base language models often looked human to both Pangram and GPTZero. Instruction-tuned chat models were easier to identify than base models. Researchers also used repeated paraphrasing to make AI text appear more human to the detectors.

That suggests detectors may be especially good at recognizing the habits produced by chat-model training, rather than detecting one universal substance called “AI writing.”

The Atlantic found another crack. A reporter sent ChatGPT and Claude output through the Walter Writes humanizer, then watched Pangram label the result human. Pangram has since described better humanizer detection in version 3.3, so one test does not freeze the system forever, but it does show the shape of the fight.

The detector learns the disguise, and the disguise keeps changing. It’s just like with police figuring out a new way to transport illicit substances, then traffickers come up with something new and the wheel keeps spinning.

This arms race creates an important asymmetry:

A result of “AI” can be a false accusation
A result of “Human” can be successfully disguised AI

Neither side provides proof.

Pangram CEO Max Spero told The Atlantic the detector should never be the final arbiter. The company setting limits on its own tool carries more weight than a critic attacking it from outside.

How to Read a Pangram Result

A Pangram result is closer to weather radar than a fingerprint.

Radar detects conditions associated with a storm. It can tell you when the signal is strong, where to look, and whether you should carry an umbrella. A fingerprint connects a person to an object through physical evidence, and Pangram has no such access to the writing process.

I also don’t use Pangram as a moral scorecard. I write about technical subjects, and I use AI heavily to structure my thoughts and explain difficult concepts to less technical readers. My first question when I read something is much simpler: Did I get anything valuable from it?

If an article teaches me something new, gives me a useful idea, or makes a complicated subject easier to understand, I’m satisfied with the time I spent reading it; whether AI helped produce it comes second.

I take the same approach to Duolingo, where I’m currently learning German. Duolingo has openly described using generative AI to create and validate course content. I also know that more than 1,000 volunteers helped create dozens of its original language courses.

I have serious ethical problems with that history. I personally believe that Duolingo owes an enormous debt to the community that helped build it, and embracing automation does not erase that debt. But I cannot reverse the company’s decisions, and I still want to learn German, so I keep on using the app and embrace the technology for what it can do.

That is roughly how I approach AI-assisted writing. I care about the quality of the thinking, the usefulness of the result, and whether the article rewards my attention. A detector score may tell me something about how the prose was produced, but it cannot decide whether the prose was worth reading.

With that in mind, I use four rules when reading a Pangram result:

Check the material. Is it long-form prose, or a short Note, poem, list, technical manual, reference section, or template? Pangram’s own model card says the detector is intended for long-form writing in complete sentences and warns that lists, instructions, reference sections, templates, and dense equations are more susceptible to false positives.
Read the label as resemblance. Pangram is a trained classifier. It studies patterns in human and AI writing and estimates which group a new passage most closely resembles. Pangram describes the process as turning the text into a numerical representation and passing it through a classifier. It does not observe who typed the words or watch the document being created.
Do not mistake the score for a reconstruction of the writing process. A high result does not tell me which ideas came from a model, how much work the writer contributed, or whether AI only helped with editing. A low result does not prove that no AI was involved. The detector sees the finished prose, not the conversation, research, prompting, or revision behind it. This is also why my best agent workflow is mostly files. Files preserve the trail between research, drafting, and editing, even when AI is part of the process.
Ask what question I actually want answered. If I want to know whether the prose resembles AI-generated writing, Pangram provides a useful signal. If I want to know whether the article is accurate, original, insightful, or worth reading, I have to judge those things myself. A strong idea does not become worthless because AI helped express it, just as a completely human-written article does not become valuable merely because a person typed every word.

I apply the same discipline when AI gives me a technical answer because accepting AI’s first answer without checking it replaces judgment with convenience. I do not reject an answer because a model produced it, and I do not trust it merely because it sounds polished. I ask whether it is accurate, useful, and worth my attention.

A Pangram result can describe patterns in the writing, but it cannot tell me whether I learned something. That would be dystopian.

My Verdict On Pangram

Pangram is different from the crude detectors people remember.

Its classifier learns from paired human and AI documents.

Its synthetic mirrors reduce topic shortcuts.
Its hard-negative mining feeds human false positives back into training.
Its calibration favors avoiding false accusations.
EditLens attempts to model mixed editing rather than forcing every document into a human-or-machine box.

Independent researchers found that this approach performed extremely well on their tested medium and long passages.

Those are facts.

Pangram still sees only the finished text. It cannot observe the actual writing process.

Its published research does not reveal every part of the production system, and its accuracy varies by domain. Short and formulaic formats remain particularly difficult.

New model types and paraphrasing can also evade detection. Not to mention independent benchmarks do not always agree with Pangram’s own results.

And even the percentage can be misleading. Readers may mistake it for a probability or a record of the writing process, but it is neither.

Those limitations are facts too.

The reasonable conclusion lies somewhere between “all detectors are useless” and “the algorithm knows the absolute truth”.

Pangram has earned the right to be treated as evidence, but it hasn’t earned the right to be treated as a verdict.

Has Pangram scanned something you wrote from scratch? Tell me what kind of text it was, how long it was, and whether any part of your workflow involved AI. I want to compare the writing history with the score, not collect percentages without receipts.

How I Built A Substack API With Hermes And Codex

Dan Cucolea — Tue, 21 Jul 2026 12:53:31 GMT

By the middle of June, I had dozens of Substack Notes sitting in markdown files with dates and publishing times. I had rewritten the awkward ones, removed repeated ideas, and mixed the topics so two similar Notes wouldn’t appear one after another.

But there was that one task I kept postponing in Asana: Finish Notes Scheduled Setup.

Scheduling a single Note inside Substack takes about 30 seconds. Keeping several days’ worth of posts organized turns into admin work fast, especially when one edit changes the order and every publishing time after it.

On June 12, I asked Hermes to find an old Substack tool installed somewhere in my Projects folder. Other software used it to talk to my Substack account, and I wanted to know whether it supported scheduled Notes. I expected a quick yes or no, followed by a small fix if I got lucky.

Hermes found the forgotten package beside old test files and a database from my Notes analysis project. Publishing worked. Scheduling didn’t.

One missing feature pulled me much further than expected. A few weeks later, I had published the Unofficial Substack SDK, a reusable Substack toolkit for other apps. Five versions shipped in three days, followed by 500+ downloads during its first week.

I use two agents to run my workflows, and this project showed me why the split matters. One agent handling every stage carries its early assumptions all the way to the finish line.

Hermes handled the messy beginning, pulling context from old conversations, forgotten files, licences, and competing projects. Codex stepped in once the work fit inside one project folder and I knew what a successful result looked like.

In today’s edition, I’ll walk you through how I built the SDK and show why the handoff between Hermes and Codex mattered more than either agent working alone.

In this piece

How Hermes turned a half-remembered package into a real starting point
Why Codex became more useful once the job got smaller
How one wrong field name exposed the danger of plausible AI answers
A handoff format for splitting your next build without losing context

The Package I Forgot

I remembered using the old tool to collect Substack data, though I had forgotten its name, where it lived, and how much of it still worked. Hermes identified it as substack-api and traced it back to an open-source project.

Reading profiles, posts, comments, and Notes already worked. Publishing worked too. Scheduling notes support was missing.

Hermes searched the project, looked through public clues left in Substack’s website, and checked similar tools. Instructions for publishing a Note were already known, while scheduling remained undocumented. Nobody had confirmed the label Substack expected for the publishing time.

Hermes proposed scheduled_at. Plenty of online services use a label like this, and it looked completely at home beside the existing instructions. Hermes still warned me about the missing proof and listed other names Substack might expect.

I nearly ignored the warning because the feature looked finished. Doing so would’ve left me with a neat scheduling button sending a label Substack never promised to read.

Version 0.2.2 uses trigger_at. An automated check reads the exact instruction sent to Substack and fails if the label changes. Proof now lives outside the AI conversation.

Getting the first field wrong became the most useful part of the build because it forced me to separate finding an answer from earning trust in it.

Hermes Found The Ground

Starting from scratch would’ve been wasteful. Jakub Slys had already spent years learning how Substack’s private machinery worked, and his project carried working instructions plus a large set of checks.

Hermes traced the installed tool back to his GitHub project, checked the MIT licence, and kept the original credit. His research remains credited in the finished project.

From there, Hermes compared the other available projects instead of treating the first one as the automatic winner. Some were ready-made services for apps and AI agents. Others only read public posts. I wanted a small building block speaking directly to Substack without sending a user’s login through somebody else’s server.

An early experiment turned the inherited project into a small online service running on Cloudflare. Hermes removed parts tied to a traditional server and locked it to read-only access. All 230 automated checks passed before the project moved into my account.

Substack blocked requests coming from Cloudflare, so the first version hit a dead end. I moved the SDK to my VPS and built a small server interface around it, giving my other apps a stable way to use it.

Hermes handled this part well because the problem stretched beyond one project folder. Old conversations, forgotten files, licensing, and the safety of each user’s digital login key all affected the decision.

A coding agent focused on one project sees the files in front of it. Hermes also saw why I had them, what I had tried before, and which surrounding work mattered.

.I covered a similar choice in my guide to choosing AI tools. Tool choice starts before the interface. First decide whether the messy part is finding the work or doing it.

Codex Needed a More Targeted Job

Once Hermes had found the right starting point and cleared up the wider questions, I moved the project into VS Code.

I use Codex through the VS Code extension, and this is where it works best for me. I point it at a specific file, ask for one change, review the result, and keep moving without reopening the whole project discussion.

I asked Codex to run the version Hermes had prepared beside my other services without rewriting anything. It downloaded the project, installed what it needed, passed the checks, and started the service.

Then I opened my Files app and couldn’t see it.

Codex had placed the project inside a private folder on the server, while my Files app only showed a different Projects folder. Every command had succeeded, yet the result still lived somewhere I didn’t use.

I corrected the path, and Codex moved the project before restarting the service. One small mistake exposed a useful limit: a coding agent understands the project in front of it, while personal conventions still need to be stated clearly.

Once everything ran from the right place, I asked Codex to launch Jakub’s newer project beside mine. His version already worked as a complete service for regular apps and AI agents. Mine did less, though its smaller size made it easier to reuse inside other products.

Running both made the decision easier. Jakub’s project was the stronger ready-made service, while my smaller toolkit made more sense as a building block for the server I wanted to control.

OpenAI had also given me banked resets, small refills for my Codex allowance whenever I reached the limit. Hermes burned through those resets much faster than Codex inside VS Code because it carried a wider working history into every session, including old conversations and surrounding files.

Codex stayed focused on the active project and the exact edit in front of it. For small changes, this made the VS Code extension faster and cheaper to run.

No model comparison or architecture discussion would’ve given me the same confidence. Hermes found and framed the right project, then Codex handled the precise edits without dragging the entire history behind it.

The Server Had To Prove It

Next came a small server for making the toolkit available to other apps through a web address. Codex downloaded it, ran its checks, started it locally, and confirmed it was healthy before I added my Substack login details.

After setup, I asked for my latest Substack notification. A live video alert came back from my account. Five recent replies followed when I asked for my latest mentions.

Documentation examples are easy to fake, so I had to know this would be working as expected. A response from my account proved the toolkit had completed the full trip to Substack and returned with real data.

Live use also exposed a design problem. Loading one Substack login at startup meant every person using the service would’ve appeared as me. A multi-user app needed a private and secure way of storing each account's data and selecting the right login for every request.

I am building an app for that and will soon have it ready. I’m thinking of calling it StackedHQ.

Let The Tests Argue

scheduled_at and trigger_at both sound reasonable as labels for a publishing time. An AI has seen enough software to defend either one with enough detail to waste your afternoon and usage quota.

Tests settle the argument by opening the instruction before it leaves the toolkit. One scheduling check expects trigger_at. Another caught missing image information and led to a tiny correction.

Version 0.2.2 passes 25 tests covering 52 expected behaviors. GitHub reruns them before every release, then publishes with one-time approval instead of storing a permanent publishing password.

I don’t care which agent sounds more certain once a request has an observable answer. Real responses, changed files, and passing checks get the final vote.

This is the part I missed inside one AI thread. Whoever researched the problem also wrote the code and explained why it looked correct. Moving the final decision into a check broke the loop.

This habit follows the same direction as The Agentic Engineering Shift. More AI responsibility requires stronger proof outside the conversation.

The Split I Use Now

I didn’t sit down before this project and design a three-part method. Each phase kept failing for a different reason, and the split appeared from those failures.

Hermes worked best while the starting point was messy. I use it when the request sounds like “find the package we used before,” “check what we decided last month,” or “compare this with the rest of my setup.” It searches across the wider project and brings back a prepared job.

Codex worked best after the task fit inside one project folder. I use it once I know where the work lives, what needs to change, and what success looks like. “Improve the Substack tool” leaves too much room. “Run both versions and tell me which one fits an app used by AI agents” gives the work an edge.

Tests take over wherever the answer belongs to the machine. A field name, an installable file, or a response from my real account shouldn’t end as a debate between two models.

I think of those roles as scout, specialist, and referee.

A scout finds the right ground. A specialist works inside a defined surface. A referee ignores confidence and checks what happened.

Choose the role before choosing the model. A stronger model won’t rescue a job whose boundaries are still mixed together.

Copy This Handoff

My handoff between Hermes and Codex now fits inside one short file:

Goal
[one result the project should produce]

Starting point
[where the work lives and what already works]

Known evidence
[useful files observations and previous attempts]

Limits
[what the AI must avoid]

Checks
[how we will prove the result works]

Stop and ask
[what needs my approval before continuing]

Hermes fills the first version from the wider context. I remove weak assumptions, cut extra scope, and make the checks specific. Codex receives the file with the project and works until a check passes or it reaches something needing my approval.

When a check fails, the next request gets smaller. I don’t reopen the whole project. I send the failed behavior back as one specific correction.

This handoff works outside software too. Research produces a sourced brief, writing turns it into a draft, and a publication checklist checks the result. My article about file-based AI workflows covers the wider system.

What Shipped

Version 0.2.2 of the Unofficial Substack SDK gives other apps a reusable way to work with Substack. It reads profiles, posts, comments, engagement numbers, and subscriber data. It also publishes Notes, schedules them, edits drafts, and adds images.

What feels crazy to me is that npm recorded 708 downloads from July 13 through July 19. Those are downloads rather than 708 individual people, and I won’t pretend otherwise. I still find the number encouraging for a new tool solving a problem I found in an old folder on my server.

If you want to give this a test you must know that Substack might change its private API without warning. Tests make breakage easier to find, though they don’t turn an unofficial tool into a promise from Substack.

Two Agents One Workflow

This project started because I wanted Hermes to schedule my Substack Notes. It ended with an open-source SDK, a server running on my VPS, and a much clearer idea of where each agent belongs.

Hermes earned its place at the messy beginning. It found the forgotten package, pulled in old conversations, compared the available projects, and followed the work when Cloudflare blocked the first version. Carrying all this context also made Hermes burn through my OpenAI-banked resets much faster.

Codex worked better once the problem became smaller. In VS Code, it stayed close to the active files and handled precise edits without loading the full project history. This made it faster and cheaper for the small changes where a focused coding agent has the advantage.

Independent checks sat between both agents and the finished package. Real account responses and passing tests overruled every confident answer before anything shipped.

One setup detail matters if you want to try the SDK. I deliberately left the Substack cookie out of the npm package because it gives access to your account. Ask your agent to read the setup instructions and tell you what needs configuring, then add the value of your substack.sid cookie yourself as a trusted server-side environment variable and pass it as sessionToken. Never paste the cookie into your codebase or anywhere likely to save and share it.

Substack blocked requests from Cloudflare during my build, which is why I added a server interface and ran it on my VPS. Your setup might behave differently, though your login cookie should always stay on a server you trust.

Look at your last AI project sprawling across one long conversation. Give the messy discovery work to the agent with the widest view, hand the focused edits to the agent closest to the files, and let independent checks decide when the result is ready.

Tell me where your handoff keeps breaking in the comments. I want to collect real examples and turn the common failure points into a follow-up piece.

I’m working on Hermes 101, and it should be ready soon. It starts from the same idea: one visible workflow, a clear place for human judgment, and more autonomy only after the loop earns trust.

For the wider tool decision, read When to Use MCPs CLIs or Your Own Tool. For the responsibility behind the work, read The Agentic Engineering Shift.

Use the agent with the widest view to find the path, use the focused agent to make the change, and trust neither until the work passes a check.

OpenAI Is Coming for Hermes One Codex Update at a Time

Dan Cucolea — Tue, 14 Jul 2026 12:49:05 GMT

Last week I caught myself spending more time inside Codex than using Hermes, and I couldn’t pinpoint when the shift happened. GPT-5.6 had just landed, and what used to be a coding tool inside my ChatGPT subscription had become something closer to a full agent workspace.

What made it strange was that the same $20 bill could also feed a bunch of models into my Hermes agent. One subscription covering two competing stacks, with OpenAI shipping features every week that made one of them feel redundant. Browser control, remote access, plugins, banked resets, and looser usage limits all arrived over a single month, and every one of those used to be a separate purchase or, in some cases, an implementation I had to build myself.

Now I still use Hermes every day, but I just started spending more of my week inside Codex because OpenAI keeps adding features that I use all the time.

Today I’ll share why I believe Codex is catching up with Hermes and why I believe the $20 CHatGPT subscription is really a great deal.

In this article:

The recent Codex releases that shifted how I compare the two
How my ChatGPT subscription supplies Codex models inside Hermes through OAuth
Which workflows moved to Codex and which ones I refuse to move
A three-way test I run before building another agent workflow

The July Sprint That Reshaped My Stack

GPT-5.6’s July 9 release pushed this piece to the front of my queue. OpenAI added the GPT-5.6 family across ChatGPT, Codex, and its API, with three versions called Sol, Terra, and Luna. OpenAI positions Sol as the frontier model, Terra as the balanced option, and Luna as the efficient one (OpenAI’s GPT-5.6 announcement).

Placement matters more than early benchmarks. GPT-5.6 arrived inside Codex alongside faster computer use. OpenAI improved the model and its interface for acting on a computer at the same time. That pairing matters to me more than another leaderboard. An agent becomes useful when its brain and working environment stop feeling like separate purchases.

OpenAI expanded the desktop surface too. Its new ChatGPT desktop app puts Chat, Work, and Codex under one roof. Editing happens directly in Markdown and code, with inline annotations and selected-text revision. GitHub pull requests sit in the sidebar, related repositories share one project, and plugins are managed in Settings (Codex changelog).

Those sound like small interface updates when you read them one at a time. Together, they remove handoffs. Review now stays inside the task. I can inspect the diff where the work happened and return feedback without moving changes through a separate editor. Codex can hold several related repos in one project instead of treating every codebase like a separate room.

Browser work became more serious too. With explicit approval, Developer Mode gives Codex controlled access to Chrome’s developer tools, including the console, network activity, page structure, styles, and performance data (Codex browser documentation). That turns the browser from a page the agent can click into an environment it can inspect. For anyone building or testing a site, this removes another reason to wire up a separate browser setup for bounded work.

Codex Reaching Beyond Desktop

Codex also gained more reach. Codex Remote reached general availability on June 25. A task can start or continue from the ChatGPT mobile app while the work runs on a paired Mac or Windows computer. OpenAI also released a DigitalOcean Droplet Workspace plugin that provisions a remote machine, configures SSH, and connects it as a Codex workspace (ChatGPT release notes).

That closes part of the gap I used to describe as simple. Hermes lived on my VPS and stayed available from Telegram. Codex lived on the computer in front of me. Remote access and remote workspaces make that boundary less clean.

Plugins are moving the same direction. OpenAI replaced the old App Directory with a Plugin Directory, and its plugins can package skills, apps, and templates. Codex also improved plugin loading and made remote plugin catalogs easier to use. A workflow that once forced me to choose between an MCP, CLI, or custom tool can increasingly arrive as one installable bundle.

Then OpenAI softened the usage wall. On June 11, eligible Plus and Pro users received reset banking, including one free launch reset. A separate referral promotion ran from June 11 through June 24 and awarded resets after invited users sent their first Codex message. Earned resets expire after 30 days, so I wouldn’t treat them as permanent monthly allowance (Codex pricing).

On July 12, Codex lead Tibo Sottiaux said OpenAI was temporarily removing the five-hour restriction for Plus, Business, and Pro users. Weekly limits remained, and OpenAI’s standing pricing page still documented the five-hour structure. His announcement also included a usage reset after Codex reached six million active users (Sottiaux’s announcement, Codex pricing). Temporary is the word doing the work here. OpenAI can bring the restriction back or change the allowance again.

Still, the immediate price calculation changed. My $20 subscription stretches further during heavy weeks, with banked resets and fewer interruptions while the temporary change lasts.

This is bigger than GPT-5.6 or a reset button. OpenAI shipped the model and workspace upgrades alongside remote control and friendlier limits. That’s what turns Codex into an agent workspace rather than a coding interface. Work that previously started with choosing four services now starts with opening one app.

One Subscription Feeding Two Agents

Hermes officially supports an OpenAI Codex provider authenticated through ChatGPT OAuth. I can run hermes model, choose OpenAI Codex, complete the device-code login, and use the Codex models available through my ChatGPT subscription. Hermes can also import existing Codex CLI credentials when present (Hermes provider documentation).

I don’t need a separate OpenAI API key for that route.

It’s limited to Codex models exposed through the subscription rather than every model sold through the OpenAI API. That boundary still changes the economics. My ChatGPT subscription now pays for two different layers. It pays for the serviced Codex workspace, and it supplies one model route inside the Hermes runtime I control.

Codex and Hermes are competing for my workflows while sharing part of the same model bill.

I also use GLM-5.2 inside Hermes, and this is one of the main reasons Hermes is staying online. My workflow remains in place while I change the model serving it. Hermes’s model catalog includes GLM-5.2 through supported provider routes, while its CLI lets me switch among models I’ve configured (Hermes CLI documentation).

I’ve tested model choice inside a real Hermes workday, and the result kept pointing back to the same rule: the workflow should survive the model swap. GLM-5.2 uses a separate provider route, leaving the ChatGPT subscription as another option beside it.

That distinction was missing from my earlier $30 Hermes stack breakdown. Hermes still has visible hosting and provider costs. Nous Portal now offers a more bundled route, so several separate API keys are optional. Maintenance time remains part of the bill either way.

Codex hides more of those decisions inside a single price. I covered the wider plan economics in my comparison of six AI subscriptions, but the practical difference is simple. Codex supplies a serviced workshop. Hermes gives me the keys to one I own.

Serviced workshops keep adding equipment. My own workshop lets me decide which engine runs it.

The Workflows Codex Took From Hermes

Research moved first.

My Hermes research setup used a custom search route and a saved-file workflow that sorted everything against my brand filter. I still use it for recurring research, but one-off article research is usually faster in Codex now.

Codex researches against my local brief and writes the result back into the same Obsidian workspace. Research and writing live in one task, giving most bounded questions one search route.

This article is a concrete example. Its outline, research brief, old posts, and brand files all live in my vault. Codex can research the release claims against those files and write the article into the correct folder without me carrying context between tools.

Repository and browser work followed. Codex already had an advantage here because code is its home territory. Inline review and Browser Developer Mode widen that advantage. I can inspect a site and its console, edit the code, and review the diff in one working session.

One-off files became obvious too. When I need an office file or visual asset once, building a permanent Hermes workflow around it makes little sense. Codex has the file tools and task context ready. I verify the output and leave without creating another piece of agent infrastructure. My biggest change is how rarely I prepare infrastructure before starting. Codex removes the provider and output-routing decisions for bounded work.

Some work moved only halfway. Hermes still collects recurring research and saves the briefing on schedule. Codex often takes over when I turn one of those observations into a finished asset. That handoff keeps both systems useful without maintaining the same production setup twice.

The Workflows Hermes Still Defends

My morning workflow stays.

It runs before I sit down, applies my filters to the sources I chose, saves a briefing, and delivers it through the gateway I control. I documented the full version in How My Hermes Agent Plans My Morning Before I Have My Coffee.

Codex now supports scheduled automations and remote work of its own. My reason for keeping this workflow in Hermes survives those additions because the complete runtime already lives on my VPS. Moving it would trade a working system I control for a product surface whose limits and behavior OpenAI controls.

I keep that runtime dependable with my Hermes maintenance routine, which checks the layers a bundled product manages for me.

Telegram stays too. Hermes remains available where I already communicate, even when my laptop is closed. It can call my own scripts and services, work with the files on my server, and keep the result in a location another workflow already knows how to find.

Provider choice matters most here. I use GLM-5.2 in Hermes and can switch the same workflow to a Codex model through ChatGPT OAuth when I want to. If one provider changes its terms or performs poorly on a task, I’ve got another route. That freedom has a maintenance cost, but here it buys continuity instead of technical decoration.

Persistent files finish the case. My workflows leave briefs and outputs in folders I own, with review notes beside them. Codex can work inside those folders, but Hermes is the runtime connecting them over time. One task hands a file to the next without depending on a single product account to remember the whole chain.

Sorting Every Workflow Into Three Buckets

I stopped choosing one agent for everything. I sort each workflow into one of three groups.

Bounded, interactive work where I’m present to start it and approve the result goes to Codex. Research for one article, repository work, browser testing, a document, or a short analysis usually lands there.

Work that needs to run without me, start from a schedule or outside trigger, reach private services, persist across sessions, or survive a provider switch stays in Hermes. Morning research, Telegram access, and multi-step file workflows land here.

Rare or unstable work stays manual for three runs. I automate it only after the inputs, judgment points, and output stop changing.

Six Checks Before You Build

I use six questions before deciding where a workflow belongs.

Does the workflow need to run without me? Does it need a schedule or external trigger? Does it touch files or services I want under my control? Would losing one vendor break the workflow? Do I need to switch models or providers? Does the control repay the maintenance cost?

Results map to Codex for bounded work, Hermes when continuity or control shows up several times, and three manual runs when the pattern remains unclear.

Two Workloads Through the Same Test

My morning research passes five of the six ownership checks. It runs unattended on a schedule and feeds later workflows from my files, so provider switching changes the result. Hermes earns its place there.

Researching a single article passes almost none. I’m present, the task is bounded, and the output goes into a draft I’ll review. Codex wins.

This test takes less time than configuring one API, and it has stopped me from maintaining the same capability twice.

Run Your Own Audit

Write down three recurring AI tasks and mark each one C, H, or M. Pause one duplicated layer this week, then check whether the workflow still finishes cleanly.

The Expanding Overlap Open Source Needs to Answer

When I say OpenAI is coming for Hermes, I’m describing an expanding product overlap rather than alleging that OpenAI copied a specific feature or set out to kill an open-source agent.

Codex is swallowing the layer of self-run agent work where convenience was the main payoff. Every new piece OpenAI bundles into the working environment makes the ownership case work harder.

Open source needs to protect a result I’d lose inside the rented product, because more switches alone no longer win. For me, those results are provider choice, persistent files, and an always-on runtime I control.

Codex carries the opposite risk. OpenAI controls the product and its limits. July’s friendlier terms prove both sides of that bargain because the company can remove friction or restore it quickly.

I wrote the longer version of that risk in my vendor-lock-in article. Codex’s current sprint has made me more selective about where independence pays while leaving the underlying risk intact.

Codex is shrinking the part of my stack worth maintaining. Hermes protects the workflows I refuse to rent.

Ownership has to earn its maintenance now.

Where the Line Sits Today

Codex handles bounded research, article production, repository work, browser inspection, and one-off files. These jobs start with me, end with a reviewed output, and benefit from the serviced bundle.

Hermes handles scheduled research, Telegram, persistent file chains, private services, and workflows where I want GLM-5.2, a Codex model, or another provider without rebuilding the system.

Manual covers everything else until it survives three real runs.

Which workflow has a subscription recently pulled out of your self-run stack?

Codex is the serviced workshop, and OpenAI keeps delivering new equipment. Hermes is the workshop I own, where I control the keys, files, and engines.

I build fewer tools myself and reserve ownership for the workflows where it protects the result. But that line keeps moving one Codex update at a time.

The Twenty Minute Audit That Found Where Hermes Was Getting Lost

Dan Cucolea — Tue, 07 Jul 2026 13:27:09 GMT

I just got back from two weeks on the Croatian coast. While scrolling in a café in Rovinj, a Forbes headline caught my attention and I had to read the whole thing. AI costs more than the people it was supposed to replace. The technology that was promised to make labor cheaper is, at this moment, more expensive than the humans it was meant to displace.

That made me realize something. A few months earlier, I spent three weeks swapping models, adding MCPs, and building automation layers because Hermes kept getting confused. I kept chasing smarter models and better integrations when the problem was my workspace the whole time. None of it worked until I stopped adding tools and started looking at the files underneath them.

I wrote about the fix in a previous piece, and that article showed what a clean workspace looks like after reorganization, but people kept asking me the same question: how do you know which folder is broken before you start fixing things?

Today I cover the five-point audit I use, a prompt that runs it through Hermes itself, and how to pick the one fix that matters most without rebuilding your entire setup.

In this piece:

Why adding tools before auditing your workspace makes the same problem worse, because every new tool inherits the same confusion
A five-point audit that finds exactly where Hermes gets lost in your files and takes twenty minutes to run
A copy-paste prompt that audits any folder through Hermes itself and tells you where the confusion lives
How to pick the one fix that matters most without reorganizing your entire setup or over-structuring folders that work fine

When Tools Inherit the Mess

The hardest thing about working with Hermes, or any other AI harness for that matter, is accepting that it has no memory of what I already know.

When I open a folder, my brain automatically filters everything. I remember which draft I was working on yesterday, I can tell the difference between notes from this month and notes from six months ago, and I know exactly which file I need because I remember writing it.

Hermes doesn’t get any of that context. It looks at my workspace the same way a stranger would, reading only what’s visible right now and making assumptions based on file names, folder names, dates, and whatever instructions I happened to give it.

That gap between what I know and what Hermes can see is where everything breaks down.

If current and archived files look identical from their names alone, Hermes treats them as equally valid options and sometimes picks the wrong one without realizing it. If there’s no clear starting point in a folder, Hermes has to search through everything before it understands what it’s looking at. And if draft work lives in the same space as public actions, Hermes has no way to know when it should stop and ask for permission.

This is why my Hermes maintenance routine only works when the workspace underneath it is clean.

That routine checks models, memory, cron jobs, and gateway health, but every single one of those checks depends on reading from files. When the files are a mess, the routine produces noise instead of signal.

Workflow handoffs and approval gates fail the same way because they all assume Hermes knows where to read, where to write, and when to ask before acting. Those assumptions collapse the moment the folder structure doesn’t make those answers obvious.

I learned this by watching the same failure repeat every time I tried to fix it with a new tool.

A smarter model reading the wrong file still produces the wrong answer. A new MCP fetching data into a folder with no structure still loses the output somewhere. Switching providers doesn’t change where Hermes writes things down.

The one variable that determines whether Hermes succeeds or searches in circles is the one I kept ignoring, because it wasn’t as exciting as upgrading to a better model or connecting a new integration.

The 20-Minute Audit

My audit runs five checks on one folder Hermes touches often. Pick that folder and open it like Hermes would, with fresh eyes and no memory of what’s inside.

Hermes Workspace Audit

1. Active work
There is one obvious place for current work.
Pass if Hermes knows where current drafts, notes, or tasks live.
Fail if current and old material share the same folder.

2. Archive boundary
Old files have a separate archive folder.
Pass if archived material is clearly historical.
Fail if old files look current from the filename alone.

3. Entry point
The folder has an obvious starting file when it has multiple subfolders.
Pass if the first file tells Hermes where to start.
Fail if Hermes has to search before it understands the folder.

4. Handoff path
Each repeated workflow has an input and output location.
Pass if Hermes knows where to read and where to write.
Fail if every run invents a new output location.

5. Risk boundary
External, paid, destructive, or public actions have a review step.
Pass if Hermes knows when to stop.
Fail if the same instruction lets it draft and publish.

Walk through each check on one folder. Don’t audit the whole vault, don’t reorganize anything yet. Find the one folder where Hermes wastes the most time and understand why.

This prompt runs the same audit through Hermes:

Audit this folder as if Hermes had to work inside it.

Folder path or description:
[PASTE FOLDER PATH OR DESCRIBE THE FOLDER]

Main task Hermes should do here:
[DESCRIBE TASK]

Check the folder across these categories:

1. Active work
Does the current source of truth stand out.

2. Archived work
Does old material look separate from current material.

3. Starting point
Is there an obvious first file, root map, or README.

4. Handoffs
Are input and output locations clear.

5. Risk boundary
Are public, paid, destructive, or external actions separated from draft work.

Return:
- what would confuse Hermes
- the first file it should read
- the first file or folder I should rename, move, or index
- whether this folder needs a root map, and a recommendation on creating an INDEX.md for it
- one warning about over-organizing this folder

Run it on the folder you audited by hand and compare the results. If Hermes finds problems you missed, your instinct about the folder was incomplete. If you find problems Hermes missed, your prompt needs more context about the task. You can build this as an agent or skill file, or keep it in your docs and point Hermes to the folder when you’re running the audit.

Walking Through an Audit

Let me show you what this looks like with a real folder so you can see where to pay attention and how to interpret what you find.

I’ll use the research workflow I rebuilt in my previous piece because it’s a concrete example of what happens when you get the structure right from the start. The folder is called 01.Research Sorter and it holds the entire workflow that turns raw research links into scored article angles.

01.Research Sorter/
├── 01.instructions.md
├── 02.input.md
├── 03.output.md
└── 04.review.md

Four files, numbered for reading order, each with one job. Let me walk through how each audit check applies to this folder.

{image 5: diagram-036-folder-pass.png — Infographic: folder structure passing all five audit checks}

Check 1: Can Hermes find the current work? Pass. The numbered prefixes tell Hermes exactly where to start. 01.instructions.md is the entry point, 02.input.md is where I paste my research links, 03.output.md is where Hermes writes the scored results, and 04.review.md is the checklist I run through after. There’s no ambiguity about which file matters for which step. Hermes reads the instructions first, then moves to the input, then writes to the output. The sequence is explicit.

Check 2: Archive boundary. Pass. This folder only holds the current workflow. Old research runs get archived to a separate Archive folder once I’ve picked an article angle from them. The active folder stays clean because completed runs don’t pile up inside it.

Check 3: Entry point. Pass. 01.instructions.md is the obvious starting file. When Hermes opens this folder, it reads the instructions first and knows exactly what the workflow does, what the brand filter is, and how to score each item. No searching required.

Check 4: Handoff paths. This is where the audit caught a real problem in my earlier version. Before the rebuild, my research workflow would write output to different locations depending on what I’d told Hermes that day. Sometimes it went to 01.Articles/Drafts, sometimes to the root folder, sometimes to a folder I’d created on the fly. Every time Hermes had to find the output from the last run, it had to search again. The numbered file structure fixes this as 03.output.md is always in the same place. The next workflow step knows exactly where to look.

Check 5: Risk boundaries. Pass. This folder only produces draft observations and article angles. Nothing in it triggers a publish action or sends anything public. The actual writing and publishing happens in a separate workflow folder with its own risk boundaries. That separation means Hermes can run this research workflow freely without accidentally pushing something live.

Once I walked through these five checks, I could see why this workflow runs reliably while others didn’t. The structure answers every question Hermes might have before it asks.

The key thing I learned from auditing this folder is that you’re not looking for problems in isolation. You’re looking for the one problem that creates the most confusion for Hermes. In folders that fail the audit, the archive boundary is usually the biggest issue because it affects every single task.

That prioritization is what makes the audit useful. You’re not trying to fix everything at once. You’re trying to find the one thing that, if fixed, would make the biggest difference across most tasks.

Pick One Fix

Find the single issue from the audit that creates the most Hermes confusion. One fix, not five.

If current and archived files live together, fix the archive boundary first. Move old files to a separate archive folder. This one change solves more Hermes confusion than any other because it stops the most common failure: picking the wrong version of a file.

If outputs are unclear, define where Hermes should write before changing any tool. Create one output folder and point Hermes at it every time. Consistency matters more than location.

If there’s no starting point, build the INDEX.md pattern from my piece on file-first agent workflows. Read that piece, build one INDEX.md for the folder that failed the audit, and run the same task again. If Hermes finds the right file in under thirty seconds, the fix worked.

What you shouldn’t do is fix everything at once. Most of your folder names are fine, and the audit tells you which ones confuse Hermes. I wrote about the over-organizing trap in my previous piece on file-first agent workflows, where adding INDEX.md to every subfolder made Hermes slower. The short version: add only enough structure to fix the specific problem the audit found.

Also, don’t use memory to paper over bad file structure. Memory tells Hermes things across sessions, but it doesn’t help Hermes find the right file inside the current one. If the folder is confusing, fix the folder. And don’t add another MCP before Hermes knows where the work lives. I wrote about the MCP versus CLI versus custom tool decision in a previous piece. If Hermes can’t find files in a clean local workspace, no external tool integration will compensate.

Once the workspace is clear, the tool choice gets easier. A clear local workspace often points to CLI or file tools first. Shared external systems point to MCP. Repeated narrow steps point to a custom wrapper or skill. Most of the time, the audit reveals that I don’t need a new tool. I need a better folder. Even when I’m running multiple agent frameworks through the same Hermes brain, the workspace structure is what makes it work. Different agents, same files, same folder map.

Everything I described here is the short version, the field notes. The full audit checklist with scoring rubrics, the INDEX.md templates for different workflow types, the prioritization framework for picking which fix to implement first, and how to verify each fix actually worked go into the first Hermes 101 course. I’m working on it right now and it should be ready soon. If you want the step-by-step version of what I’m describing in field-notes form here, that course is where it will live.

If the broader stack is what you’re after, whether that’s provider routing, memory ownership, or scheduled workflows, I wrote the full cost breakdown of the stack and the morning workflow that runs on it. Both of those depend on the same workspace audit pattern to stay reliable across sessions.

Everything I’ve written about in this newsletter traces back to one instinct. Own the layer that matters. I built my stack so no company controls my tools. I built my workflows so no noise controls my output.

Capability is cheap when the foundation is broken. Audit one folder. Fix one thing. Then decide whether you need another tool.

Tear Down Your AI Workflow and Rebuild It Like This

Dan Cucolea — Tue, 30 Jun 2026 13:40:51 GMT

Futurism ran a story last week about employees burning their company’s expensive AI tokens on pointless tasks. Amazon staffers were using their mandated AI agent to run personal tasks to hit usage quotas. A single employee at one company spent over $150,000 a month on AI tokens.

Moreover, Uber capped each employee’s AI spending at $1,500 a month after engineers blew through the company’s entire 2026 AI budget.

I did the same thing on a smaller scale, and it cost me three full days before I admitted it. Last week I wrote about reorganizing my files so my agent could find them in thirty seconds, and that gave me the ground to rebuild on. If I were starting over today, the first thing I would do before connecting anything is this one test I skipped.

In this edition I’m going to show you that test, the workflow I use now because of it, and how you can run it on your own setup right now.

In this piece:

A five-minute test that tells you whether a source belongs in your workflow before you waste a day configuring it
The exclusions list that cost me three days to learn but saves me 40 minutes every morning since
A four-file workflow pattern that turned 80% noise into 10 usable article angles per run

The Three Days I Lost to Configuration

When I found Hermes, the first impulse was to connect everything I could think of. arXiv for academic papers, Reddit through the Arctic Shift API for community discussion, RSS feeds for blogs I read, and a cron job to run the whole thing every morning so I would wake up to a fresh batch of research.

Each connection required its own setup, and each setup required its own research.

Arctic Shift needed an endpoint, subreddit filters, and time-range parameters. I had to find the API, read its documentation, figure out the filtering, and test it. That alone ate a full day. arXiv needed category filters for computer science papers, rate limiting so I wouldn’t get blocked, and a custom parser for its XML feed. Another day gone. Then I had to build the Hermes skill that would call both APIs, parse the results, deduplicate across sources, and route everything through my brand filter, which checks whether each item helps someone move beyond ChatGPT toward open source, local, and agentic systems they control. Its skill file alone was 180 lines of configuration listing six sources, a daily cron schedule, and the output format for observations and article angles.

By the time I finished, six sources were wired together and firing on a daily schedule. Less than 20% of the output was relevant to anything I would write about for All Agents Considered. arXiv served academic papers I would never translate for readers, while the subreddits I scraped served social chatter that would never pass my brand filter.

I filtered the noise for a few days thinking I could tighten it, but the bigger loss was time spent on API setup and skill management for sources I never held next to my filter before wiring them in. Building felt productive. Connecting APIs felt productive. Making things run on a schedule felt productive. But none of it produced a single article angle because those sources were never going to fit the work I do.

Every item must support the AAC mission: help AI users become more independent by building open source, local, and agentic systems they control.

I had that filter written down in the skill file. I never held it next to arXiv and Reddit before wiring them in. Instead I built on a wrong foundation for three days and ran the output for another week before I admitted it.

The Test I Should’ve Run First

Open your brand filter or audience description. If you don’t have one, write three sentences about who you serve and what they need. That’s your filter.

Open each source you’re planning to connect. Spend 60 seconds scrolling through what it produces today. Hold that output next to your filter.

arXiv today publishes papers on transformer architecture, reinforcement learning benchmarks, and multimodal reasoning. None of those help a non-coder move beyond ChatGPT. Reddit’s r/LocalLLaMA discusses quantization formats, model benchmarks, and hardware setups. Some crosses into AAC territory, but most assumes a technical reader who already knows what GGUF means. My audience doesn’t.

Most source mismatches are obvious when you see them side by side. People skip the test because connecting an API feels like real work and reading a webpage feels like nothing, so we gravitate toward what looks productive.

If you’re about to wire a source into your AI workflow, run this test right now. Open the source, open your filter, look at both. If the match is weak, put the source on an exclusions list and move on. You saved yourself a day of configuration.

Where the Output Proved Me Wrong

20 to 30 items every morning from 6 sources, and I was spending 40 minutes sorting through them. My brand filter was supposed to do the sorting, but the agent was applying it loosely because the input was too varied. Academic abstracts, Reddit threads, blog posts, and RSS headlines all needed different interpretation, and the instructions weren’t specific enough.

I tightened the filter and added scoring from one to five:

# Scoring rubric
+1 if technical people are discussing it
+1 if it helps people move beyond ChatGPT
+1 if it relates to independence, control, cost, memory,
   files, agents, local AI, or open source
+1 if a non-coder needs translation
+1 if it points to a practical setup, workflow, article,
   course module, or useful build

Drop anything scoring below 3.

Each rule caught real noise, but each rule was also more configuration on a foundation already wrong.

A daily cron meant the workflow ran every morning whether I needed it or not. Some mornings I hadn’t scanned new sources since the last run, so the output was thin. Other mornings I had a weekend backlog the single daily run couldn’t handle. Every three days to a week would’ve been right, but daily felt productive.

When I subtracted the setup days from the value the workflow produced, the complicated version was worse than no workflow at all. I’d spent more time configuring sources I should never have connected than I would’ve spent doing the task manually for a month. Once I understood that math, I tore the whole thing down.

The Exclusions List That Replaced It

Before I rebuilt anything, I wrote down every source that didn’t serve my work:

# Hard exclusions - sources I don't track as daily inputs

- arXiv
- Semantic Scholar
- Papers with Code
- Hugging Face Daily Papers
- Hugging Face trending models
- Ollama as a standalone source
- Reddit
- X
- LinkedIn
- YouTube
- Discord
- Product Hunt

Every source on that list is fine for other audiences. arXiv is essential for researchers. Reddit is gold for technical practitioners. YouTube is where most people learn about AI today. None of them produce output that helps a non-coder AAC reader move beyond ChatGPT toward systems they control.

Exclusions are where time savings compound. Every source you don’t connect is a day of configuration you don’t spend, an API you don’t debug, and a category of noise you don’t filter every morning. Short list, massive savings.

I wrote about the shift from optimizing prompts to building workflows earlier this month, and the exclusions list is the bridge between those two ideas. You can’t build a workflow until you know what doesn’t belong in it.

What stayed was small by comparison. Hacker News for technical discussion that non-coders need translated. Lobsters for deeper practitioner conversations. A handful of blogs I’ve read for years and trust to stay in my lane. RSS feeds from three newsletters that cover the intersection of AI and personal productivity. That’s the input list, and it fits on a single screen.

Before the rebuild, I was sorting through 20 to 30 items every morning from 6 sources, spending 40 minutes filtering noise. With this list, I paste a handful of links, run the agent, and get 10 usable angles back in the time it takes to make coffee.

The Workflow That Replaced Three Days of Configuration

My rebuild started by asking what the workflow needs to do. Sort raw research notes from sources I trust, score each against the brand filter, keep what passes, turn the best into article angles, and save the result to review with my coffee.

Structure uses the same numbered-folder pattern from my file structure piece, applied to a single workflow instead of a whole vault. Four files in one folder for one task I repeat every few days, with no external APIs, no cron, no routing, and no memory layers. Everything the agent needs to do its job lives in those four files, and nothing else creeps in.

01.Research Sorter/
├── 01.instructions.md
├── 02.input.md
├── 03.output.md
└── 04.review.md

Instructions tell the agent what the workflow is and what it should do, in plain English:

# AAC Research Sorter

This workflow takes raw research notes and turns them into
AAC article observations and seeds.

Read 02.input.md. For each item, apply the brand filter:
- Does this help someone move beyond ChatGPT?
- Does it point to a practical setup or decision?
- Does a non-coder need it translated?

Score each item from 1 to 5. Keep items scoring 3 or higher.
For each kept item, write one observation with a signal,
a plain-English translation, and an article angle.

Write the sorted list to 03.output.md.

Input holds the raw material. Links, titles, one-line observations I jot down while scanning sources I already trust. Everything I dump goes in this file, and the instructions file tells the agent how to sort it. Output receives the result: a dated note with top observations, article angles for each, the best three ideas to write next, and any course or build connections. Review tells me what to check:

# Review Checklist

- Read the best-three list
- Pick one idea to pursue this week
- Flag any observation where the article angle feels generic
- Check whether any item scored too high because the
  brand filter was applied loosely

Numbers give the agent its reading order, one concern per file keeps boundaries clear, and every file has one job. When the agent opens the folder, it doesn’t have to guess what to read first or what each file is for.

Three Manual Runs Before You Automate Anything

Before I added anything back, I ran the workflow three times manually. Three mornings of pasting links, running the agent, and checking what it produced. First run had a scoring error because my brand filter instruction was too vague about what counts as practical. Second run turned a pure news item into an observation because the instructions didn’t explicitly exclude vendor PR. Third run was clean.

If I’d added the cron schedule after the first run, I would’ve automated a workflow still broken in ways I hadn’t seen. Running manually three times is what taught me what the workflow does well and where it breaks. One run teaches you nothing because you haven’t seen the variance.

This is where most people go wrong. They build something, it works once, and they schedule it to run forever. Second run catches edge cases the first one missed. Third run proves the pattern holds. Skipping any of those steps means you’re automating a system you haven’t validated, and automation amplifies problems as reliably as it amplifies good output.

You can build this as an agent or skill file, or keep them in your docs as they are and point Hermes to the folder when you’re running the workflow.

Its full version now fetches from nine sources I’ve validated against my brand filter, scores 166 items in a single run, and produces ten article observations with course connections. It runs every few days, not every morning, because that’s the cadence the task needs. I wrote about how this fits into my morning routine, and the Hermes maintenance routine I run keeps it from drifting.

Run This Today

Open your AI workflow. Look at every source it connects to, every API it calls, every feed it reads. For each one, hold the source next to your filter. If the match is weak, disconnect it. Put it on your exclusions list. You freed up the configuration time and morning filtering time that source was costing you every single day.

If you don’t have a brand filter yet, write three sentences about who you serve and what they need. Sources that survive the test are your real input list. Build around those, run it by hand three times, and think about scheduling only after the third run is clean.

Whole process takes an afternoon and replaces weeks of configuration sprawl. Every layer you add after that, whether it’s a cron schedule or a new source, gets added only when the previous one works.

What source did you connect to your AI workflow that you should’ve tested first? Tell me in the comments.

Everything I described here is the short version, the field notes. The full workflow pattern, the scoring rubric, the exclusions list template, and how to layer automation on top without automating mistakes go into the first Hermes 101 course. I’m working on it right now and it should be ready soon. If you want the step-by-step version of what I’m describing in field-notes form here, that course is where it will live.

If the broader stack is what you’re after, whether that’s provider routing, memory ownership, or how to build an agent that doesn’t drift between sessions, I wrote the full cost breakdown of the Hermes stack and the morning workflow that runs on it. Both of those depend on the same small-file-loop pattern to stay reliable.

Capability is cheap when the wiring around it is broken. Build the filter first, run it by hand three times, and the capability takes care of itself. One brand statement and a four-file loop is the difference between an AI workflow that wastes your mornings and one that gives you back two hours a week.

Why My Best Hermes Workflow Consists Of Plain MD Files

Dan Cucolea — Tue, 23 Jun 2026 13:47:58 GMT

Last week I read about an AI that designed a vaccine fighting coronaviruses we haven’t even encountered yet (ScienceDaily). Cambridge ran the first human trial, and 39 volunteers received the antigen.

It’s crazy to think that an algorithm analyzed the entire genetic family of a virus and engineered protection against members still circulating in animals and waiting to jump. But when I ask it to fetch my latest brief from a list of docs, it can spend nearly two minutes opening the wrong files in my vault just to show me a brief from three months ago.

And I know Cambridge uses a custom trained AI, but what I want to show you is that the gap between what AI can do and what a setup lets it do is what makes or breaks your workflow and productivity.

I never built scaffolding on purpose, until recently. It piled up around the agent by accident, folder by folder, until the agent lost its way inside a mess I shaped for myself.

So I spent a day timing every failure, and a pattern showed up. In this edition I show you why your agent keeps tripping over the easy stuff while the world calls it a genius, and the fix that puts it back on your side.

In this piece:

Folder structure failed my agent because my folders were organized for how I think, not for how an agent navigates
One index file at the root of every major folder turned slow searches into thirty-second reads
The invisible scaffolding around your agent matters more than the agent’s own capability, and here’s how to build it
A diagnostic test you can run in five minutes to see whether your folder structure is the real problem

The Structure Your Agent Can’t See

I organized my vault the way most people do. Articles, research, assets, strategy docs, each got their own folder. That structure felt clean because I think in content types. Folders map to my categories and I never think about where to look. Drafts are articles, notes are research, the filing system runs on autopilot.

But an agent doesn’t think in categories. When I ask Hermes to plan a product launch, the task pulls from strategy notes, brand guidelines, and previous launches scattered across different folders.

Those pieces of context live in different places in my content-type structure. My agent has to search everywhere every time, without knowing which draft is current versus which one is archived, or which research note is from this month versus from six months ago.

Content-type organization works perfectly for humans. You’ve spent your whole life filing things under categories, and your brain does the cross-referencing automatically. It’s only natural to expect AI to work the same, when in fact an agent has to do that cross-referencing manually, and that’s where the structure breaks down.

The structure around your agent does more work than the agent’s own capability.

Once I saw the pattern, the cause was obvious: I had built my vault for a human brain that remembers where things live, then handed it to an agent that has to search from scratch every time, and that exposed the real issue underneath the folder mess.

A searcher needs a map, because without one the agent is walking through the dark and treating every file like it might be the answer.

What Capability Wastes On

Hermes kept opening a bunch of files before landing on the right one, or grabbing an archived version when the current file was somewhere else. Worse, it would ask which file to use when the answer should have been obvious from context. This happened with every model I used, including Opus, GPT 5.5, Qwen, and GLM.

The pattern kept repeating, and I was stuck watching the same slow searches play out across task after task.

Even though my agent was capable enough to find things, the folder structure had become the main bottleneck before it ever reached the actual work.

I hit the breaking point the day I timed the failures. I tracked how many files Hermes opened before it reached the right one, and how long it took to get there. Five common tasks looked like this before I changed anything.

Before I changed anything:

Find the current article brief: 7 files opened, 2:00 to the correct file;
Find brand color definitions: 5 files opened, it took 1:12;
Look up the article queue for planning: 4 files opened, it took 0:48;
Find previous articles on the same topic: 6 files opened, it took 1:36;
Pull promotion strategy for a launch: 3 files opened, irt took 0:34.

Rough experiment, so treat the exact numbers as directional.

Every task crossed multiple folders. Most of them opened archived versions before finding the active ones. My agent was burning capability on navigation instead of doing its job. One launch plan needed three files that lived in three different folders, and I watched it make three wrong attempts before landing on the right ones.

An agent that writes articles, codes, and plans shouldn’t be spending most of its time looking for things.

The Smallest Cage That Works

One folder per concern, numbered for order, with an INDEX.md at the root that maps everything. That’s the whole fix, and the details live in three rules that work together.

INDEX.md at the root of each major folder is a map. It lists every subfolder and canonical file, plus where my agent should start. My agent reads this first and knows what’s inside before touching anything else. Think of it as a soft approval gate where the agent isn’t allowed to start work until it knows what it’s working with.

My brand folder structure looks like this after the reorganization.

05.Brand/
├── INDEX.md
├── 01.Brand System/
├── 02.Editorial Strategy/
├── 03.Promotion/
├── 04.Public Deliverables/
├── 05.Operating Plan/
└── 06.Archived/

This structure organizes by concern instead of content type. Each concern gets its own folder, so brand work stays with brand work and strategy stays with strategy. My agent doesn’t cross boundaries looking for something that doesn’t belong there.

Numbers on folders make reading order explicit instead of relying on alphabetical sorting. 01.Brand System gets read before 02.Editorial Strategy. My agent doesn’t guess. Numbers inside folders do the same thing for files, so my agent knows 01.AAC Articles is the starting point before 02.Previous Articles.

I lead folder names with a number because it’s easier for me to remember as well.

This is how my full $30 Hermes stack stays easy to move across dozens of folders without my agent ever getting lost.

Archived stuff lives in 06.Archived, where old briefs and retired plans go to wait. My agent knows not to look there unless I specifically ask for historical context. That separation is what keeps the active folders clean and the searches fast.

Once my agent was told not to cross that boundary by default, every task inside the active folders ran faster.

My INDEX.md looks like this.

# AAC Brand Index

This folder holds the current All Agents Considered brand system.

## Folder Map

| Folder | Purpose | Updated |
|---|---|---:|
| `01.Brand System/` | Visual identity, topic scope, voice | 2026-06-11 |
| `02.Editorial Strategy/` | Article direction, title rules, queue | 2026-06-11 |
| `03.Promotion/` | Launch, distribution, tool strategy | 2026-06-11 |

## Canonical Files

| File | Purpose |
|---|---|
| `01.Brand System/01.AAC Brand System.md` | Visual identity, colors, typography |
| `02.Editorial Strategy/01.AAC Articles.md` | Article queue, title rules |

## Where To Go

- Start with `01.Brand System/04.AAC Direction.md` for mission
- Use `02.Editorial Strategy/01.AAC Articles.md` for article selection

INDEX.md went through three versions. My first version listed every single file inside the brand folder and ran to forty lines. It was technically complete but my agent had to parse it every time and the length was its own overhead. My second version was too short, around fifteen lines, and my agent still asked questions I hadn’t answered. This third version lists only subfolders and canonical files, with a short “Where To Go” section that tells my agent its starting points.

When I ask my agent to pull promotion strategy for a launch, it reads 05.Brand/INDEX.md, opens 03.Promotion/01.AAC Promotion Strategy.md, and gets to work. Timing after the reorganization looks like this.

After the reorganization:

Find the current article brief: 1 file opened, 0:10
Find brand color definitions: 3 files opened, 0:22
Look up the article queue for planning: 1 file opened, 0:10
Find previous articles on the same topic: 2 files opened, 0:18
Pull promotion strategy for a launch: 1 file opened, 0:12

The slowest task dropped from 2 minutes to 26 seconds, and the fastest runs landed around 10 seconds. My agent opens the INDEX.md, follows the starting point it needs, and gets to work without wandering. No capability changed on my agent’s side. Folder structure stopped wasting most of it before the task even started.

Folder structure is a cage I built that constrains how my agent moves without constraining what my agent can do. Inside the cage, my agent runs freely. Without it, Hermes tends to wander off and I have to waste my time pointing it at the right file.

Moving to Hermes let me build that kind of system across files, providers, and memory all at once, and the INDEX.md pattern is the smallest piece that made the biggest difference day-to-day.

Every Cage Has a Lock

My first mistake was adding INDEX.md to every subfolder. Too many maps means my agent spends its time reading indexes instead of doing work. I keep INDEX.md only at the root of major folders like Brand and Editorial Strategy, where there are enough subfolders to need a map. Inside a small subfolder with four or five files, Hermes navigates directly without any map at all.

Keep in mind that numbering gets tedious when you add new folders. I’ve got to decide where a new folder fits in the sequence, and sometimes I append it at the end instead of renumbering everything. That’s fine. Numbers don’t have to be perfect as long as they’re directional. Perfectly ordered folders aren’t the goal, and treating them as one turns a practical fix into a cosmetic project.

A bigger mistake is building structure before your agent shows any confusion. Most people over-engineer their agent setup because they think it needs proper infrastructure.

My current rule follows the same principle behind choosing MCPs versus CLIs versus your own tool. It uses the smallest interface that gets the job done. Add structure only when your agent gets lost, and add only enough structure to fix that specific problem.

Another failure I ran into was nesting structure inside structure. I added subfolders inside subfolders to make everything perfectly categorized, which turned a two-level hierarchy into a five-level one. My agent then had to read multiple INDEX files and parse multiple numbering sequences to reach a single file. I collapsed those extra levels back into flat subfolders and navigation sped up again.

Depth is the enemy of fast file lookup, and most reorganizations add depth thinking it’s precision.

Measure Before You Reorganize

Before touching a single folder, run this test on three real tasks your agent handles most often. Time each one, and note how many files it opens before finding the right one. Track how often it picks the wrong file or stops to ask you which one to use.

Any task that takes your agent more than thirty seconds or opens three or more wrong files points to a folder behind that task that’s broken.

Pick the one failure that happens most often. Open that folder and write an INDEX.md that lists every subfolder and important file, plus where your agent should start. Save it. Run the same task again.

If your agent finds the right file in under thirty seconds, the fix worked and you now know the pattern. Apply it to the next broken folder. If it still fails, the problem is likely numbering or one-concern-per-folder, and those are the next two things to fix.

Start with the one folder that wastes the most time, fix it, and move to the next only when you’re ready.

Where the Bars Still Bends

Archived content still gets referenced sometimes when I need an old brief for context. My agent has to know to look in 06.Archived instead of the active folders, and I mention this in the INDEX.md so it knows where historical material lives. Without that note my agent assumes archived content doesn’t exist.

Also, Obsidian Sync creates occasional problems when it does not catch up cleanly across devices. If I update a file on my laptop but the older version is still sitting on my VPS, Hermes loads the VPS copy and treats it like the current source of truth. That is a sync problem more than a folder-structure problem, but it shows up inside the folder system because the agent only sees the files in front of it.

Numbering breaks down when you’ve got so many folders that the sequence becomes meaningless. Past ten or twelve numbered items at one level, the numbers start being arbitrary.

I try to keep major categories below that threshold and nest deeper structure inside instead of expanding the top level.

Renaming is another source of friction. When I reorganize I sometimes rename folders to better match their purpose, and any INDEX.md reference to the old name breaks until I update it. I now try to set folder names once and leave them alone, because a slightly awkward name is cheaper than a broken reference.

This structure works best for content-heavy workflows and planning-heavy ones. Pure code or data-heavy setups might need different organization principles entirely, and the INDEX.md pattern doesn’t solve every navigation problem.

Which folder in your setup would your agent get lost in right now? Tell me in the comments.

Everything I described here is the short version, the field notes. Full folder templates, the INDEX.md patterns for different workflow types, and how this fits into the broader agent setup go into the first Hermes 101 course. I’m working on it right now and it should be ready soon. If you want the step-by-step version of what I’m describing in field-notes form here, that course is where it will live.

If the broader setup is what you’re after, whether that’s provider routing, memory ownership, or scheduled workflows, I wrote the full cost breakdown of the stack and the morning workflow that runs on it. Both of those depend on the same INDEX.md pattern to stay reliable across sessions.

Everything I’ve written about in this newsletter traces back to one instinct. Own the layer that matters. I built my stack so no company controls my tools. I built my vault so no mess controls my agent. Same principle from providers to folders to whatever comes next.

Capability is cheap when the scaffolding around it is broken. Build the scaffolding, and the capability takes care of itself. One index file and a few numbers in front of your folder names is the difference between an agent that wanders and an agent that works.

I Built My Hermes Stack to Survive Vendor Lock-in and Google Just Proved Me Right

Dan Cucolea — Tue, 16 Jun 2026 13:53:30 GMT

Two days from now, Google will switch off a free tool a lot of people built their daily work around. Most readers here have never touched it, so the shutdown itself won’t ruin your week. What sits underneath the shutdown is the part worth your attention. It keeps happening, and one day it might land on a tool you do depend on.

Gemini CLI is a small terminal tool Google released to run AI agents straight from your computer. Think of it as Google’s answer to Claude Code or Codex, a way to point an agent at your files and let it work.

What made it interesting was that it shipped open source, which means anyone was free to read the code, copy it, fix it, or build something better on top of it. Open source is the closest thing software has to a promise that a tool stays yours even if the company behind it loses interest.

Google made that promise, and now Google is walking away from it.

Last month, Google announced that on June 18 2026, the tool will stop working with Google’s AI subscription plans. In its place comes something called Antigravity CLI, which is closed-source.

Six days earlier, the US government forced Anthropic to shut down Fable 5, a model people had barely started using before it disappeared.

Two different shutdowns, same lesson. The tool you built your work around can change or disappear, and you won’t get a vote.

That’s why I built my AI stack so I can always swap models without rebuilding anything. When one company shuts the door, another one is already wired up and ready to go. In today’s edition, I am going to show you exactly how to break free of vendor lock-in.

In this piece:

Why three different AI vendors made three different moves in one month, and how every move pointed at the same trap
How to spot the parts of your own AI setup that secretly hold your context, your memory, and your routines hostage
The three decisions I built mine around so any single vendor change turns into a shrug instead of a crisis
One move you finish in twenty minutes today that proves the whole principle to yourself

A Pattern Everyone Recognizes and Nobody Names

Here’s how it goes, almost every time. A company hands out something free, often open source, and people build real work around it because free and open feels safe. Word spreads. More people lean on it.

Then a quiet thing happens inside the company. Someone notices the free tool now does roughly what the paid product does, and the two start eating each other. Around that point the terms change, or the license shifts, or the whole tool gets retired and replaced by a sealed version.

Goodwill came from the open thing. Money comes from the closed thing. When those two collide, money wins every single time.

Gemini CLI walked this exact road. It carried an Apache 2.0 license, which in plain terms meant it stays open forever, free for anyone to keep using even if Google lost interest.

Last month’s announcement erased that. A permanently open tool moved behind a paywall and into closed source. A community of people who trusted the open license now has less than 48 hours to migrate or go dark.

Anthropic ran a version of the same play a week before Google’s announcement. They quietly walked back hidden safeguards inside Claude after a public backlash.

People leaning on Claude for serious research found out their tool had been working against them in the background. It shifted its behavior while they changed nothing about how they used it.

Then the US government forced Anthropic to shut down Fable 5 entirely. People who had just started building on it lost access overnight, and the company had no choice but to comply.

Two different moves from the same company in the same week. One changed the tool’s behavior in secret. The other made it disappear completely.

Same week, OpenAI floated price cuts aimed squarely at Anthropic. Your monthly AI bill now rides on a boardroom argument you’ll never sit in and never hear about.

Three companies, three different moves, one shared lesson. Lean your whole setup on a single vendor’s tool or model, and you take on their shutdown dates, their hidden behavior changes, their price wars, and every private decision about which features live and which ones disappear overnight.

What Dependency Looks Like

Most people never feel dependent until the morning something breaks. You sit down with coffee, open Claude, and a prompt it handled fine yesterday gets refused today for no reason you understand.

In that moment, you learn your entire research routine was balancing on one model staying agreeable. Or you open ChatGPT to pick up a three-month project and your conversation history is gone, wiped during a policy change you never read.

A tool you built your whole day around changed its mind. Your only role in the decision was finding out afterward.

Dependency runs deeper than the model itself. It reaches into everything the model has been touching on your behalf.

Your project context lives inside a chat window that vanishes the second you close the tab. Your task history sits trapped behind an interface with no real export. Your routines and saved instructions live in one company’s private format.

Moving to a competitor later means rebuilding the whole thing by hand from memory. Nobody handed you a contract to sign. You used a tool that felt good in the moment.

The context you kept adding to it became the most valuable thing in the room, right up until the day it walked out the door wearing the tool’s logo.

This was my normal life before I built around it. I would spend an hour walking Claude through a project, finally get answers worth keeping, close the laptop, come back the next morning, and start from zero.

Every time I switched providers chasing a better price or a smarter model, every routine reset to nothing. None of it hurt enough to fix on any single day.

It only became unbearable after it happened enough times that building a real fix took less energy than complaining about it one more morning.

Three Decisions That Make Any Single Vendor Irrelevant

Understanding this pattern was the same moment I started rebuilding my setup to outlive it. I didn’t see the Gemini CLI shutdown coming by name, or predict Claude’s safeguards, or guess OpenAI’s pricing move.

Watch any group of vendors for more than a few months, and the shape becomes obvious. Building around the shape costs almost nothing compared to getting blindsided by it. Three decisions carried most of the weight.

Decision one was routing. Rather than wiring my whole workflow to a single provider, I spread the work across Opencode Go, OpenRouter, and Codex (via ChatGPT Pro) depending on the job.

One small file tells my agent which company handles which kind of request. Writing goes to one model because it holds tone better. Research goes to another because it chews through long documents faster. Routine generation goes wherever the price is lowest that hour.

When a provider hikes prices, throttles me, or pulls a model, I change three lines in that file and the work keeps flowing through the others without missing a beat. I broke down the full money side of this in my cost comparison against Claude Max, because the savings surprised even me.

Decision two was memory, and this one mattered most. Claude’s conversations disappear when the chat closes. ChatGPT’s history lives on OpenAI’s servers, under OpenAI’s rules. I know that both Claude and ChatGPT have memory, but it’s a single file, and you can not alter it directly. All this means that you don’t have full access to it.

My setup has 3 types of memory. First, Hermes comes with its own memory files and also built-in tools for session recall, so it can search our past convos. Then I added a 3rd party memory provider called Hindsight, but I might drop it as it’s proven to be too much hassle for too little return for me.

Last but not least, I use Obsidian with plain markdown files, synced across my devices through the built-in Sync, readable by any AI tool I choose to point at it. Project notes, research, past sessions, saved agent routines, all of it sits as a file on my VPS, laptop, and phone. I also configured a WebDAV server and MCP so literally any AI can get access to my files (behind a login, of course).

A provider changes its deal tomorrow, and my context follows me wherever I go next. None of it ever belonged to the provider in the first place.

Decision three was the agent layer, and this is the piece most people skip. I run Hermes as the stack that sits between me and whichever company happens to be doing the actual thinking.

Hermes holds the workflow, the saved skills, the routing, and the handoff logic. Whatever provider is plugged in becomes a swappable engine. Switching it means changing a single reference.

When Claude started refusing harmless prompts last week, my workflow never stopped. I would’ve sent the work somewhere else and kept moving. Every saved skill that taught my agent how my projects run stayed identical, because those skills live in files I control.

I moved to Hermes specifically for this, because the layer running my work needed to stay independent.

None of these three decisions asks for a computer science degree. Each one asks for a single choice, which is refusing to build your livelihood inside a tool that rewrites its own terms without asking you first.

How to Build Your Own AI System

Nobody builds the whole thing in two days, and trying to is how people give up. You build it one decision at a time, letting the setup grow around the parts you genuinely use rather than the parts a tutorial told you to want.

Order matters, because each layer makes the next one easier. Here is the order I followed and why.

Start by owning your memory. That move pays off the same afternoon and keeps paying off every month after.

Pull your project notes out of whatever AI chat tool currently holds them and drop them into a notes app you control. Obsidian, Notion, plain text files in a folder on your desktop, any of them works.

The brand of the app matters far less than the fact that nothing inside it disappears when you close a tab. Every month you keep building context inside a chat window is a month of thinking that disappears the moment the company changes its mind.

With your memory off the company’s servers, adding a second provider becomes the natural next step instead of a scary one. Pick one piece of your workflow and run it through a different service for a week.

If Claude writes for you, send a research task through OpenRouter and watch what happens. If ChatGPT does everything, hand one job to a rival model purely to feel the difference.

Replacing your favorite tool is not the goal here. Learning what switching costs, while nothing is on fire, is the goal. That way, the day you need to switch under real pressure, you already know what you have to do.

Remember that your workflow is really a handful of separate jobs pretending to be one tool.

Ideation runs on one model. Research runs on another. Notes and memory live in your own app. These pieces talk to each other through plain files and simple handoffs.

The tool you love this month might not be the tool you want next year. Spend a little time now making sure that gap costs you nothing when it arrives.

Do This in Twenty Minutes Today

Fastest possible start, and also the simplest. Open whichever AI chat tool you lean on most.

Find the one conversation holding your most valuable project context, the thread full of decisions you made, research you gathered, and ideas you would really need to save.

Drop this prompt into that conversation:

If this pattern sounds familiar and you want weekly breakdowns of what it means for independent AI setups, subscribe, and I’ll send you one every Tuesday.

Copy what comes back. Paste it into any app you own, whether that’s Obsidian, Notion, Google Docs, or a single text file on your desktop.

Label it with the project name and today’s date, and close the loop.

You’re done. You moved your first piece of context off a company’s servers and into something nobody gets to switch off.

Your chat tool still works exactly as it did five minutes ago, no harm done, no bridges burned. What changed is that the best part of that conversation now survives even if the tool rewrites its terms tomorrow morning.

Ten conversations fit comfortably in twenty minutes. And once you’re done you’ll figure out that you’ve already taken the first step towards building your own system. When you decide to install Hermes, or an open-source agent, you’ll have everything you need to get going.

Get Ready For When Things Break

This setup is not perfect, and pretending otherwise would waste your trust. Some months I pour more time into maintaining my routing file than I would have spent living inside one vendor and taking the lock-in.

Independence carries an upkeep cost.

Memory sync across devices stumbles now and then. Mostly when I edit the same note on two machines at once and create a conflict I have to fix by hand.

Routing across providers means keeping three pricing models straight in my head instead of one. When a company changes its rates, I need to update my calculations. But usually prices go down instead of up with each open source model (not the same can be said about proprietary ones).

A handful of tools refuse to hand context to each other cleanly. That leaves me copying and pasting between them in a way a single sealed vendor would have smoothed over for me.

Honest version, this whole approach suits people who already got burned by vendor dependency at least once and decided they would rather spend an hour a month on upkeep than risk losing an entire year of work to a corporate decision they were never allowed to influence.

Draw Your Own Dependency Map

Give this two more minutes. Write down three things in your AI life you couldn’t easily replace.

One model that handles your most important work (like Opus is for some). One app holding your project history and notes. One workflow that breaks if a single tool changes its terms next week.

Now run one quick test on each. Try to export it.

Find your AI conversations locked inside a chat window with no real export button, and you found your first weak point. The twenty-minute exercise above already started repairing it.

Find your project notes trapped inside a tool that won’t let you download them, and you found your second weak point. You already know its name without checking.

Export cleanly from all three and you hold more independence than almost every AI user out there. Fail to export from even one, and you found exactly where your next twenty minutes belongs.

My own automated morning workflow runs this same provider-agnostic pattern on a schedule. Every check reaches into files I own instead of interfaces I rent by the month.

Gemini CLI’s shutdown is only the newest entry in a pattern with no plans to stop. Claude’s hidden safeguards, OpenAI’s pricing war, Google’s license reversal, each one is the same story wearing a different month on the calendar.

Everything above is the short version, the field notes. Full treatment, including the actual routing files, the Obsidian Sync setup, and the provider comparison that pushed me toward OpenCode Go and OpenRouter, is going into the first Hermes 101 course.

I’m building it right now, and it should be ready by end of July. That course is where the patient step-by-step version of all this will live for anyone who wants their hand held through it.

If the money angle is what grabbed you, I wrote a full breakdown of the $30 Hermes stack that goes toe to toe with Claude Max and asks for no subscription. If you want the origin story, my migration from OpenClaw to Hermes is the longer answer to why I needed an agent layer I controlled before any of the rest of this made sense.

How to Build AI Workflows When You're Tired of Optimizing Prompts

Dan Cucolea — Tue, 09 Jun 2026 13:18:29 GMT

Vibe Stack Lab is now All Agents Considered.

I kept drifting toward agent stuff, and the old name didn't fit anymore, so I renamed it.

Same writer, same weekly email.

Finding good content ideas used to take me hours every week. Reddit in one tab, news in another, arXiv in a third, and an Obsidian note where I’d paste everything and try to remember how the pieces connected. Each AI search took seconds, but I spent the rest of the time being the glue.

What made it worse was how much attention I burned just moving between tabs and chats. Every switch cost me focus, and every reset made the work feel heavier than it was.

I didn’t know it then, but instead of overly optimizing my prompts, I should’ve just created a workflow. Took me some time to figure out the best way to go about this and so I am ready to share my way of converting prompts into workflows.

In this piece:

Why prompt habits break at scale
How to spot your first workflow candidate
How to find the seams in long conversations
The handoff pattern that carries context forward

If you’re copying output between AI chat tabs, you’re doing the coordination work the AI should handle. The fix is to turn your prompts into a workflow where each step writes to a file and the next reads it. Context carries forward without you carrying it. You only stop where a real decision needs to be made.

When Prompting Stops Working

Almost everyone starts with AI the same way. You type a question, get an answer, copy-paste it somewhere, repeat. This is how I spent my first year using it. And I get it, it feels productive because each interaction gives you something tangible.

Then you notice you’re spending more time managing the AI than the AI is saving you. You’re the one copying between steps. You’re the one remembering what step three needed from step one.

An October 2025 study published on arXiv found that LLM accuracy drops significantly when relevant information is embedded within longer contexts, even when all irrelevant tokens are masked.

Prompt engineering blogs and courses are still selling the idea that the right words will fix everything. They’re optimizing the wrong layer. You’re trying to run a pipeline through a chat window, and no amount of word-smithing changes that.

Hitting a ceiling with prompting means you have an architecture problem.

How to Spot Your First AI Workflow

Before we go further, try this. Think about the last repetitive task you did with AI. The one that took 45 minutes and made you want to scream by minute 30. Now ask yourself:

Did I copy-paste between steps?
Did I open multiple chat windows because context kept getting polluted?
Did I have to remember what step three needed from step one?
Did the AI produce good output at each step, but the final result was mediocre?

If you answered yes to any of these, you already have a workflow candidate. You’ve been doing the coordination work manually.

Here’s a prompt you can use right now. Paste it at the end of your next long AI conversation, after you’ve finished a task:

Look back at this conversation we just had. I'm going to paste the initial prompt I started with below. I want you to analyze whether this task could be converted into a reusable skill or workflow.

Specifically:
1. Could the steps I took be structured as a sequence where each step produces output the next step needs?
2. Are there handoff points where context needs to carry forward?
3. Would this task benefit from being broken into separate steps with clean context, rather than running as one long conversation?
4. What would the input, instructions, output, and checkpoint look like if this became a workflow?

Here's the initial prompt I used: [PASTE YOUR INITIAL PROMPT HERE]

Tell me if this is a good candidate for a workflow, and if so, sketch what the steps would look like.

Run this after your next repetitive task. You might find you’re already doing workflow-shaped work manually.

This works whether you use Hermes, Claude Code, Codex, Cowork, or any other AI conversation tool. Patterns stay the same. Tools don’t matter. Structure does.

Where to Find the Seams in a Long Conversation

Converting a long conversation into a workflow starts with seeing where your current process has seams.

When you have a long AI conversation, look for the moments where you switched gears. Where you said “okay, now let’s do X” and started a new mental context. Where you copied something from earlier in the chat and pasted it into a new request. Where you had to remind the AI what you were working on because it forgot. Those seams are where scope creep happens. I wrote about what Gordon Ramsay taught me about scope and knowing when to stop.

Those are your seams. Each seam is a potential step in a workflow.

My breaking point came during a content ideation project. I needed to find interesting angles for newsletter articles, which meant pulling from multiple sources. Reddit threads surfaced complaints about specific problems, news articles covered emerging tools, and arxiv papers hinted at new capabilities.

I started manually, copy-pasting Reddit posts into a document, scraping news headlines, running arxiv searches and saving abstracts. Each source lived in its own chat session because context windows kept getting polluted. By the time I finished with Reddit, I’d forgotten what I found in the news search.

Then I created individual skills for each source. One skill for Reddit research, another for news scraping, a third for arxiv papers. Each skill worked fine on its own, but I was still the one coordinating between them. I’d run the Reddit skill, save the output, run the news skill, save that output, run the arxiv skill, save that output. Then I’d manually combine all three into a final idea list.

I was doing the agent’s coordination work manually. The AI could do each step well. Handoffs were the problem. I was the middleware.

How to Correctly Carry Context Forward

Workflows are sequences of steps where each step produces something the next step needs. What separates workflows from prompting is that context moves forward automatically instead of you carrying it by hand.

Anthropic’s “Building Effective Agents” guide, published in December 2024 and widely cited as the definitive resource, makes a clean distinction. Workflows are systems where LLMs and tools are orchestrated through predefined code paths. Agents are systems where LLMs dynamically direct their own processes.

For non-coders, workflows are the sweet spot. You define the path. The AI does the work at each stop.

Anthropic describes five workflow patterns. In plain English:

Prompt chaining works like an assembly line. Step one’s output becomes step two’s input. Each step stays simple and focused.

Routing sorts different inputs down different paths. Like a mail sorter that sends letters to the right zip code.

Parallelization runs multiple things at the same time. Like having three researchers instead of one.

Orchestrator-workers uses a boss agent that breaks down the work and delegates it to worker agents.

Evaluator-optimizer has one agent do the work and another check it. The first one revises based on feedback.

I call the files that hold it all together handoff files. Each step writes its work down so the next step doesn’t have to guess. Format matters less than the principle. It could be a markdown file, a Google Doc, a structured text block. What matters is that each step produces something the next step can read.

I tried everything for holding context between steps. In-memory variables disappear when the session ends, database entries require setup and maintenance, and shared state files get corrupted when two steps write at once.

Markdown files in Obsidian won because they’re boring and reliable.

Each step in a workflow writes its output to a markdown file, and the next step reads that file. Files sit in a folder structure that mirrors the workflow. When something goes wrong, I open the file and see exactly what step three produced. I trace the problem backward through the chain.

This also gives me something I didn’t expect. I track what each subagent or step did, with links to the specific files it produced. When something sounds fishy in the final output, I open the intermediate files and find where the drift started.

Markdown has practical advantages too. Plain text works everywhere. Files move between systems without conversion. Changes are version-controllable over time. Everything renders nicely in Obsidian, which I already use for notes.

Storing context in a database or shared state mechanism adds complexity, requires setup, and creates dependencies. Markdown files require nothing except a folder and a text editor.

Each step writes its work down. The next step reads what the previous step wrote. Context carries forward through files, not through memory.

Building an AI Workflow Step by Step

Let me show you what this looks like in practice. I’ll use my content ideation workflow as the example, but the structure works for any repeating task. If you want to learn how to architect a workflow in 5 minutes before building, that article covers the planning phase.

Four steps make up this workflow. Each step reads from the previous step’s output file and writes to its own output file.

Step 1: Reddit research
Input: A topic or keyword to search for.
What it does: Searches Reddit for threads where people complain about problems related to that topic.
Output: reddit-findings.md with thread titles, URLs, and key complaints.

Step 2: News scraping
Input: The same topic.
What it does: Searches news sources for articles about emerging tools or trends related to that topic.
Output: news-findings.md with headlines, URLs, and summaries.

Step 3: Arxiv search
Input: The same topic.
What it does: Searches arxiv for papers that hint at new capabilities related to that topic.
Output: arxiv-findings.md with paper titles, abstracts, and relevance notes.

Step 4: Synthesis
Input: All three files from steps 1-3.
What it does: Reads all three files and synthesizes them into a list of article angle ideas.
Output: idea-angles.md with 5-10 potential article topics, each grounded in the research.

Each step gets a clean context with exactly what it needs. Nothing is buried. Nothing is forgotten.

My first attempt at this workflow was ugly. Files on my desktop, a checklist in a notes app, and a lot of copy-pasting held it together. But it was structured. Each step had a clear input and a clear output. The agent didn’t need to remember anything from three steps ago because I gave it exactly what it needed.

Eventually I built one unified skill that handles the whole pipeline. It pulls from Reddit, news sources, and arxiv in sequence, writes each batch of findings to a separate markdown file, then synthesizes all three into a final idea list. The skill runs top to bottom without me copying anything between steps.

Prompting vs. Workflows: The Same Task

Content ideation looks completely different the prompt way versus the workflow way.

The prompt way: You open a chat and ask the AI to search Reddit for complaints about a specific topic. It gives you a list. You copy that list into a document. You open a new chat and ask it to scrape news articles about the same topic. It gives you headlines and summaries. You copy those into your document. You open another chat and ask it to search arxiv for relevant papers. It gives you abstracts. You copy those too.

By the time you’re done, you’ve got three separate chunks of text in a document. Now you need to synthesize them into idea angles. You paste everything into a new chat and ask for ideas. The AI produces a list, but it’s generic. It lost the nuance from the Reddit complaints because they got buried in the combined text. It missed the arxiv findings because they were at the bottom of a 5,000-word prompt.

The workflow way: You run a skill that searches Reddit and writes the findings to a file called reddit-findings.md. The skill then searches news sources and writes to news-findings.md. Then it searches arxiv and writes to arxiv-findings.md. Each file is clean and focused.

The final step reads all three files and synthesizes them into idea-angles.md. Each step gets a clean context with exactly what it needs. Nothing is buried or forgotten.

Clare Liguori’s research at AWS tested five approaches to guiding agent behavior across 3,000 evaluation runs. Simple prompt instructions reached 82.5% accuracy, meaning roughly one in five interactions failed. When she added structured feedback loops, what she calls steering hooks, accuracy hit 100% across 600 runs.

Better structure made the difference, not better prompts.

I tested this myself when comparing how different models handle real Hermes workflows. Models that looked impressive on benchmarks often failed at structured workflows because they overthought simple steps or ignored format constraints. Structure matters more than raw capability.

Where Humans Still Check

Every workflow needs checkpoints, but not every step needs one. Adding review points everywhere turns the workflow into a series of interruptions.

I use decision gates. You only stop where a real choice needs to be made. Which angle to pursue. Which source to prioritize. Whether to cut a section that doesn’t fit.

If the output is fine and no decision is needed, you don’t stop. Workflows run until they hit a point where they can’t proceed without your judgment.

Decision gates check whether the output matches your intent. AI produces grammatically correct, well-researched content that still goes in the wrong direction. Decision gates catch that before the next step builds on a mistaken assumption. I wrote about why accepting AI’s first answer is bad and how checkpoints prevent drift.

I wrote a full guide on adding approval gates to Hermes workflows if you want the technical details. Gates protect your reputation by blocking external actions without your OK, protect your data by requiring confirmation before system changes, and protect your wallet by blocking spending above a threshold without approval.

For most workflows, you need one gate at the point where the output becomes public or irreversible. A content workflow might have a gate after the outline, before the final draft goes live. A research workflow might have a gate after the synthesis, before you act on the findings.

Decision gates are where you stay in control of direction while the AI handles execution.

Where to Start Your First Workflow

Pick one repeating task. Not the most complex one. Pick the one you do every week that takes 45 minutes and makes you want to scream by minute 30. That’s your first workflow.

Mine was a morning briefing that pulls tasks and articles before coffee. Two steps. Read from Asana, format the output, deliver it. Simple enough to build in an afternoon, useful enough to run every weekday since I built it.

If you’re new to Hermes, start with a two-step workflow like this one before attempting anything complex.

Minimum viable workflows have four parts: input (what goes in), instructions (what the agent does), output (what comes out), and checkpoint (where you verify). You don’t need software. You don’t need code. You need a folder with files in it.

Anthropic’s own advice from “Building Effective Agents” is to start simple and add complexity only when needed. They explicitly warn against starting with frameworks or complex architectures. Start with two steps. Make them reliable. Then add a third.

Confluent’s guidance on AI workflows makes the same point. Simple solutions are often the best place to begin. Starting with simple prompt engineering may not be perfect, but it works well enough as a first pass. When you hit the ceiling, add structure. Don’t add structure preemptively.

Boring beats clever. Your first workflow should be so simple it’s embarrassing. A two-step process with a file handoff and a human check. That’s it. People who get value from AI workflows built boring ones and ran them 50 times, not impressive ones they ran twice. I wrote about why AI makes you build too much and how to resist that urge.

Most AI productivity advice tells you to write better prompts. Designing better handoffs is where the real payoff lives. Prompts at each step can be mediocre if the context they receive is clean. A brilliant prompt in a bloated chat thread will still produce mediocre output.

Recognizing when you’re doing coordination work the AI should handle is the whole shift. Once you see the pattern, you can’t unsee it. Every repetitive task becomes a candidate for structure. Every manual handoff becomes a design problem.

Hitting a ceiling with prompting means you have an architecture problem. Build the pipeline. Let the context flow. Keep your hands on the decisions that matter.

Why AI Benchmarks Fail Real Hermes Agent Workflows

Dan Cucolea — Tue, 02 Jun 2026 13:14:14 GMT

The day after Opus 4.8 launched, I gave it a job that should’ve taken two minutes. Find a named file, summarize it under a strict word limit and return the result in a specific format so the next step in the pipeline could parse it correctly.

Opus handled it with clean output and solid reasoning, but it took its time making sure every move was right. By the time it finished, a cheaper model would’ve done the same work three times over.

That was the moment I stopped trusting benchmarks. A leaderboard score tells you how a model performs on a clean task under controlled conditions. It says nothing about whether that model can survive a twenty-step workflow.

I’ve wanted to put models through a proper test for a while now. I finally found the time and the right config to do it. Here’s how I run every model through the same real tasks, and what four models taught me about real Hermes work.

In this article:

Tool call discipline matters more than reasoning quality. A model that calls the right tool once beats one that explores and verifies three times over.
Route by task, not by preference. Use the cheapest model that reliably finishes the job, and step up only when it fails.
A simple testing framework that puts models through real Hermes tasks instead of synthetic benchmarks.

Bottom line: There is no single survivor. I route lightweight models (GLM 5.1) for fast background tasks, capable mid-tier models (Qwen 3.7 Max) for complex workflows, and flagships (Opus) exclusively for deep debugging when the others fail.

Why AI Benchmarks Fail Agent Workflows

Benchmarks test the thing they can measure cleanly. Can the model solve this logic puzzle, answer this math question, write code that passes these test cases? Those are useful questions for evaluating raw capability.

But agent work needs different skills. The model needs to be obedient, fast, disciplined with tools, and able to stop when the task is done. None of these show up on a benchmark because none of them are easy to measure in a controlled test.

A model can score in the top tier on a reasoning benchmark and still be the wrong fit for unattended workflow automation. It might overthink simple tasks, waste tokens on unnecessary reasoning, or call tools it doesn’t need because it’s trying to be thorough. In a chat interface that thoroughness feels impressive. In a scheduled job running at 6 AM it means the session times out before the work finishes.

Benchmarks also miss the compounding effect of small failures. A model that adds an extra section, ignores a format constraint, or calls a tool twice when once would suffice. Each is minor on its own. In an agent workflow where each step feeds the next one, minor failures cascade into broken jobs.

In my opinion, ClawEval comes close to a valid benchmark. The paper runs 300 human-verified agent tasks across 9 categories with a Pass^3 rule that eliminates lucky runs. A task only passes if the model meets the success criteria in all three independent trials, which is a meaningfully stricter bar than Pass@3. It’s the most serious attempt at realistic agent evaluation I’ve seen, and it has already spawned related work like WildClawBench that tests agents inside live OpenClaw instances. But that’s beyond the point.

My test is less scientific and more practical. I put models through the same jobs I schedule on Hermes, using the same config I run every day, and I watch what happens.

Speed Is a Workflow Cost

Speed matters in two completely different ways depending on how you use the model.

When you’re in a session talking to Hermes, time is something you’re spending. A model that takes four seconds instead of one is the difference between staying in flow and getting distracted between tool calls. Fast models give that time back to you.

In a cron job, nobody’s watching the clock. But speed still matters because fast models tend to produce fewer reasoning tokens per tool call, and that directly affects cost and reliability. Less verbosity means a tighter context window across twenty steps, which keeps context window degradation from compounding into broken jobs by step fifteen.

This is why GLM 5.1 on Ollama Cloud carries most of my daily workload. It’s fast enough to feel instant in interactive sessions and tight enough with tokens to keep scheduled jobs cheap and stable. I use it for heartbeat checks, morning briefings that synthesize Asana tasks before coffee, and anything that needs to be fast and correct without deep reasoning. The boring work that makes up most of a Hermes workday.

Speed also compounds with cost. A fast mid-tier model that finishes a workflow in three minutes is cheaper than a slow flagship that takes fifteen minutes. The cost math behind this is what I’ve been tracking across providers and it’s where a fast model pays for itself.

For tasks that require massive token input and a lot of tool calls to read and process files, I reach for DeepSeek v4 Flash. When a job needs to chew through a hundred thousand tokens across a dozen files, speed is the only thing that keeps the session from becoming an exercise in patience.

Tool Call Discipline Beats Reasoning

This is the sharpest opinion I hold about models inside agent loops, and it’s the one benchmarks almost never test.

Benchmarks measure whether a model can think hard about a problem. Hermes needs a model that calls the right tool once, reads the result, and moves on without second-guessing itself. Those are different skills, and the second one matters more for unattended work.

A model that makes twelve tool calls when four would do is being expensive and fragile. Every extra call adds API cost, creates another failure point, and fills the context window with noise the model has to process on the next step. Most of what people call “context engineering” inside an agent loop is just preventing this kind of noise from ever entering the window in the first place.

I’ve seen top-tier reasoning models call a search tool, read the results, then call a different search tool to verify what the first one returned, then call a third tool to format the output when a simple string operation would’ve worked. The net effect was a session that cost three times as much and took three times as long.

The same failure shows up with instruction obedience. A model that ignores format constraints and adds helpful extra sections breaks downstream parsing. A model that keeps writing after the task is done wastes tokens. A model that skips a negative constraint includes something you told it to avoid at the worst possible moment.

In a chat, each of these looks like helpfulness. In an agent workflow, each one becomes a liability because each step feeds the next one.

Tool call discipline separates a model I trust with unattended work from a model I keep supervised. A disciplined model reads the task, decides which tools it needs, calls each one once, and stops. An undisciplined model explores and adds helpful extra steps nobody asked for.

If you’re running Hermes with approval gates, tool call discipline becomes even more important. A model that makes unnecessary tool calls also tends to ignore “ask before destructive action” instructions. The model thinks it knows better than the prompt.

This also ties into the interface question I’ve been tracking — a disciplined model calls the right tool the right way, and sometimes the right tool is a lightweight CLI instead of a bloated MCP server that chokes the context window before the model even starts thinking.

How I Route AI Models in Hermes

Model selection inside an agent loop is a routing problem, not a ranking problem. There’s no single best model. There’s a best model for each job, and the job changes throughout the day.

GLM 5.1 carries most of my workload. Heartbeat checks, simple scheduled jobs, structured data parsing, quick research tasks. These are tool calls that need to be fast and correct but don’t need deep reasoning. GLM on Ollama Cloud is cheap enough that I don’t think twice about spinning up a session. The boring work that makes up the bulk of a Hermes workday.

GPT-5.5 is what I use through my Codex subscription for the heavy work. I tried it inside Hermes first and it burned through usage by making tons of unnecessary tool calls. The model doesn’t know when to stop, which makes it terrible for agent loops where each tool call costs tokens and fills the context window. So I stopped using it in Hermes and shifted it to Codex, where I control the loop. In Codex it handles most of my coding and the research pulls where I want thorough coverage. It is more verbose than the other models in my stack, which helps for research and hurts for tight format constraints, so I shape the prompt accordingly. The subscription removes cost as a gating factor, which means I can run it as often as the job needs without watching a counter.

Opus gets the tasks GPT 5.5 can’t finish. I run it through the API and it’s expensive, so I keep it scoped to debugging. When a problem doesn’t reproduce cleanly or when a code review needs a different reasoning style, Opus handles it. That’s it. Outside of those sessions it stays idle.

Qwen 3.7 Max is my surgical tool. I reach for it when a task needs more reasoning than GLM can deliver but I don’t want to pay Opus prices. The step up from the cheaper Qwen tier is noticeable on tasks involving multi-step logic or ambiguous instructions. The cheaper version guesses and moves on. 3.7 Max pauses and works through it. For most structured agent work, the cheaper version gets the job done. I use 3.7 Max sparingly and mostly for content and deep research.

My pattern is simple. Use the cheapest model that reliably completes the specific task type. When GLM fails, step up. When the mid-tier fails, step up again. Escalation stays task-driven, not model-driven. Pricing only matters once the model can finish the job.

The first rule of routing is reliability. The second rule is cost. Get them in the wrong order and you’ll pay for it.

I pay per token every time Hermes calls a tool, so the cost math matters. Every tool call generates input tokens from the context window and output tokens from the response. A session with a dozen tool calls consumes as many tokens as a long chat conversation.

My AI Agent Evaluation Ladder

I don’t trust leaderboards because they don’t test what I need. So I run models through the same set of real tasks from my actual work. Same files, same prompts, same conditions for every model so the comparison stays honest. Each task tests a different dimension of what I need from an agent model.

The tasks escalate from simple to demanding.

First, whether the model stays restrained when given no task. A good Hermes model sends a short greeting back and waits. A bad one starts searching files and scanning memory before you ask it to. The model that won’t wait is the model that won’t stop.

Then whether it finds a document and summarizes under strict format rules without drifting into extra sections. I cap the summary at a specific number of bullets with a word limit on each one. The task doesn’t require deep reasoning. It requires the model to follow directions and stop.

Whether it packages a CLI tool into a reusable skill without overbuilding. Some models create five files when one would do. The disciplined model reads the help output before it writes anything.

Whether it uses that skill correctly in a fresh session with specific source rules. No Reddit, no arXiv, no turning search snippets into facts. This tests whether the model can follow negative constraints, which are harder than positive ones because the model has to actively suppress the instinct to include everything it finds.

And finally, whether it pulls together sources, cross-checks claims, and produces a decision-ready report under a word limit. This combines everything. Format constraints, tool judgment, instruction obedience, and the discipline to stop writing when the task is done.

That last requirement is the one benchmarks never test. In a chat, extra writing is harmless. In an agent workflow, extra writing is a tax on every step that follows.

What’s Coming Every Thursday

I’m running Opus, GPT-5.5, Qwen 3.7 Max via OpenCode Go, and GLM 5.1 via Ollama Cloud through these tasks and publishing a short verdict card every Thursday. Each card covers the best use case, the conditions where you should skip it, cost notes from real sessions, and whether the model belongs in a Hermes setup at all.

The goal is a repeatable testing standard that accumulates over time instead of a one-off leaderboard that goes stale the week after publishing.

I’ll also note when a model fails because of provider instability rather than model quality. A weak model needs replacing. An unreliable route needs a backup. I’ve hit this with Hindsight memory timeouts and gateway drift — things that look like the model broke but were actually a layer below it.

Each Thursday card follows the same format so you can compare over time. The verdict will be one of five categories: daily driver, strong specialist, background worker, backup only, or skip entirely. I’ll add new tasks to the ladder based on what people suggest in the comments.

Stay tuned and subscribe to receive these reports as soon as I publish them.

Which model should go through the ladder first, and what real workday task should I add to the test? Let me know in the comments.

My Hermes AI Agent Maintenance Routine For Maximum Reliability

Dan Cucolea — Tue, 26 May 2026 12:59:38 GMT

Last week, I spent a few days blaming the model before I realized Hermes was waiting on a memory recall timeout.

When the response time got worse, I assumed provider latency because I’d changed models before and knew that layer could get noisy.

The real problem sat one layer earlier, inside the retrieval path I hadn’t checked yet.

My external memory provider, Hindsight, threw a retrieval error, Hermes retried, and the request stalled because the memory system was broken before the model ever had a chance to answer.

A few days later, my Friday Hermes health-summary job missed its Telegram report over a long weekend. The stack still answered messages, but the missing report told me the scheduled workflow had stopped producing the artifact I expected to see.

Hermes maintenance means checking the layers around the model before you blame the model. The routine I use now is a set of cron-backed prompts that check memory, gateways, scheduled jobs, model IDs, and backups, then stop before they make changes that need approval.

Most install guides skip this part because they get you to the first successful command, then leave you with a working AI control plane and no maintenance loop around it.

Hermes feels like one system when it works, but it routes through models, memory, gateways, skills, cron jobs, provider keys, and local files, so the fault can sit in any one of those layers when the stack starts behaving strangely.

And don’t get me wrong, I’ve never had a single issue with the actual Hermes code compared with my time using OpenClaw, but I have had issues with models, providers, and third-party integrations.

The model gets blamed first because it’s the visible part of the stack, while the failure usually starts somewhere less obvious.

This article is the maintenance routine I use now, rewritten as prompts you can hand to your agent.

In this article:

A maintenance routine you can run after Hermes is installed, so silent drift doesn’t turn into a broken workflow.
Copy-paste cron-job prompts for daily, weekly, and monthly checks across memory, gateways, scheduled jobs, providers, and backups.
A simple approval rule that lets agents report problems without giving them permission to delete, update, rotate, restore, or rewrite anything.
A rollout path for turning maintenance into useful visibility instead of another noisy automation.``

After Hermes Install

The first successful Hermes run can trick you into treating setup as finished before operations have even started. You connect a provider, configure the gateway, test memory, send a message through Telegram or the TUI, and watch Hermes answer with context from the project you care about.

That moment is where the stack leaves the install guide and becomes something you have to run. Old configs can keep stale model names, scheduled jobs can miss their expected output, memory calls can slow down, and backups can look comforting until the first restore test fails.

I treat those failures as normal infrastructure behavior because a control plane becomes trustworthy only after you can see whether its dependencies are still healthy.

That lesson showed up during my OpenClaw to Hermes migration, even though the migration itself went smoothly. The first week felt better because Hermes followed instructions more closely, kept memory behavior cleaner, and made the gateway setup feel less stitched together.

The first problems were small enough to ignore in the moment but specific enough to matter later. An imported publishing skill failed because its YAML header was malformed, one environment variable was missing from the runtime, and token usage climbed while memory ingestion ran behind the workflow I was paying attention to.

None of those problems killed the setup, but each one pointed at the same operational truth: the model is only one layer inside a wider system. I stopped treating maintenance as an occasional chore once I realized a scheduled prompt could check those layers before the next failure stole an afternoon.

Cron Prompts Beat Commands

The earlier version of this routine had shell commands sprinkled through the article because that was how I checked my own server. Commands are useful when your environment matches mine, but they don’t travel cleanly across Windows, Linux, Docker, hosted runners, local agents, and the custom glue every serious stack accumulates over time.

The official Hermes Agent docs are where I would start for setup details. This piece starts after setup, when the question changes from “Can Hermes run?” to “Can I trust this workflow tomorrow?”

Prompts travel better because they describe the job instead of assuming the tool. A cron-backed agent can inspect logs, check timestamps, call a gateway, read a config file, compare recent output, or ask for approval using the tools available inside its own environment.

If the maintenance prompt needs to reach outside Hermes, the same decision from When to Use MCPs, CLIs, or Your Own Tool applies here: use the smallest interface that can inspect the system cleanly without turning one check into a brittle integration project.

A scheduled prompt still needs firm boundaries because a useful maintenance job names the layer being checked and asks for evidence before it reports confidence. The report should be readable at a glance, but the agent should refuse to delete, update, rotate, restore, or rewrite anything without approval.

That boundary turns maintenance automation into a reporting system instead of a new source of damage. I want the agent to notice problems before I do while every irreversible action still comes back to me as a decision.

Three Maintenance Layers

My Hermes maintenance routine uses three layers that map cleanly to the way the stack fails: updates, cleanup, and health checks. Those labels keep the job concrete enough for a scheduled agent to report on the system without turning the prompt into a vague request to “check Hermes.”

This is the operational side of the $30 Hermes stack, because a cheaper and more flexible agent setup only stays useful if the layers around it keep working.

The update layer asks whether something changed underneath the workflow while I was focused on using it. Providers rename models, preview routes become stale, plugins move, skills change formats, and memory backends update their APIs.

The cleanup layer asks whether the stack has accumulated enough junk to start changing behavior. Logs grow, sessions pile up, cached files stick around, and memory keeps old context long after the project has moved on.

The health-check layer answers the operational question before I start relying on the stack again. Before the workday starts, I want evidence that the gateway answers, the provider route works, scheduled jobs are producing output, and memory can retrieve a recent decision without timing out.

The layers keep the routine small enough to survive a busy week without reducing the review to a shallow status ping. Maintenance disappears when it depends on a vague intention, while a scheduled job with named layers can keep running after the calendar gets crowded.

Daily Hermes Health Check Prompt

The daily job should be boring enough that you can read it every morning without turning the start of the day into a debugging session. Its job is to tell you whether the stack is ready for work, then stop before it tries to repair anything.

Use this as a read-only cron job near the start of the workday, then adapt the gateway name, job names, and project references to match your own setup.

Create a Hermes cron job called "Daily Stack Pulse" that runs every morning at 8:00 local time, delivers to origin, and uses a cheap model (gemini-3.1-flash-lite via openrouter, or deepseek-v4-flash via opencode-go — pick whichever is configured). Restrict toolsets to terminal and web. Use this exact prompt body for the job:

---
Run a daily read-only Hermes stack pulse check. Make no changes: do not delete files, rotate keys, update packages, prune memory, restore backups, or rewrite configuration.

1. Gateway. Send or simulate one normal request through the Telegram gateway and confirm it responds.
2. Scheduled workflows. Run `hermes cron list` and inspect ~/.hermes/cron/output/ for the latest runs of jobs tagged or named for morning briefing, health summary, memory maintenance, publishing, client, or paid workflows. Confirm each ran inside its expected window.
3. Logs. Scan recent warnings and errors from the Hermes runner (~/.hermes/logs/), the model provider, the memory layer (hindsight), the gateway, and the scheduler.
4. Memory recall. Run one hindsight_recall query against an active project decision (use "All Agents Considered newsletter" or "Vibe Stack Lab library repo"). Report whether the result was relevant, stale, missing, or slow.

Return a short report with exactly these sections, one sentence per item:

PASS:
Healthy checks with evidence.

WARN:
Items needing attention later, with the layer named in parentheses.

FAIL:
Broken or missing items that block reliance on the stack today.

APPROVAL NEEDED:
Any action that would delete, update, rotate, restore, rewrite, prune, or change provider behavior. Name the action and layer. Do not execute.
---

After creating the job, run it once immediately so we can see the first report, then confirm the job ID and schedule.

The report matters more than the scheduler that happens to run it, as long as the result gives you enough evidence to trust or question the stack. You can run the prompt from cron, a recurring Hermes task, a hosted automation, a CI runner, or any agent runner that has permission to inspect the stack.

I care most about evidence that the gateway answered, the important jobs ran, memory recall still works, and recent errors haven’t turned into a pattern. Once the report names the failed layer, the next step becomes smaller because the investigation has a place to start.

Weekly AI Agent Drift Review Prompt

My quiet cron failure is the reason I care more about weekly drift than a one-time setup checklist. A job definition sitting in a scheduler proved nothing once the Friday health-summary report stopped reaching Telegram.

That is the same reason my morning Hermes workflow checks visible output instead of trusting that a scheduled task exists somewhere in a config file.

The weekly review looks for slow changes that don’t announce themselves while normal work still appears to be moving. Disk pressure, stale output, growing logs, slow memory, and old model IDs rarely feel urgent while they are accumulating, but they become expensive once they pile up inside a broken workflow.

Use this prompt near the end of the week, when the report can shape a short maintenance pass instead of interrupting deep work in the middle of a day.

Create a Hermes cron job called "Weekly Drift Review" that runs every Sunday at 9:00 local time, delivers to origin, and uses a cheap model (gemini-3.1-flash-lite via openrouter, or deepseek-v4-flash via opencode-go — pick whichever is configured). Restrict toolsets to terminal and web. Use this exact prompt body for the job:

---
Run a weekly read-only Hermes drift review. Make no changes. If a fix is obvious, list it under RECOMMENDED ACTIONS or APPROVAL NEEDED but do not execute.

1. Storage growth. Measure size of ~/.hermes/logs/, ~/.hermes/sessions/, ~/.hermes/cache/, ~/.hermes/memory/, ~/.hermes/cron/output/, /tmp/hermes*, and any backup folder under ~/.hermes/. Compare to last week if a snapshot exists at ~/.hermes/cron/output/drift-snapshot.json. Save a fresh snapshot at that path after measuring. Flag any folder that grew more than 25 percent or crossed 1GB.

2. Scheduled jobs. Run `hermes cron list`. For each job, confirm it exists, has run inside its expected window, and produced a visible artifact in ~/.hermes/cron/output/ or the delivery channel. A job definition with no recent run counts as broken.

3. Memory recall. Run three hindsight_recall queries: one active project ("All Agents Considered newsletter"), one older project ("Build It #2 AI Code Review Agent"), one recent decision ("Vibe Stack Lab library repo"). Report each as accurate, stale, empty, or slow.

4. Provider and model config. Read ~/.hermes/config.yaml. Flag preview or dated model names (anything with -preview, -beta, dated suffixes, or matching known-deprecated IDs), fallback routes pointing at old IDs, and project-level overrides under ~/.hermes/profiles/*/config.yaml that diverge from the main config without obvious reason.

5. Logs. Scan the last 7 days of ~/.hermes/logs/ for repeated errors, retry loops, auth failures, timeouts, and missing-env-var messages. Group by layer (runner, provider, memory, gateway, scheduler).

Return a report with exactly these sections:

DRIFT:
Storage growth and configuration drift observed this week.

BROKEN:
Jobs, routes, providers, memory calls, or gateways that failed and need repair. Name the layer.

STALE:
Model IDs, project configs, skills, outputs, or memory entries that look outdated.

RECOMMENDED ACTIONS:
Small proposed fixes. For each: action, risk (low/med/high), expected benefit, approval needed (yes/no).

APPROVAL NEEDED:
Anything that changes files, deletes data, updates Hermes, rotates keys, changes providers, prunes memory, restores backups, or edits scheduled jobs. Do not execute.
---

After creating the job, run it once immediately so we can see the first report, then confirm the job ID and schedule.

That weekly prompt would have caught my quiet cron failure earlier because a cron entry sitting in a file doesn’t prove the workflow is alive. The agent has to find the last run, the last output, or the last expected message before it claims the job is healthy.

The same weekly review helps with memory issues because recall drift often feels like model weakness from the outside. When retrieval returns stale or empty context, the report should call that a memory-layer problem before anyone starts blaming generation quality.

Monthly Hermes Assumptions Review Prompt

The monthly job checks whether the assumptions under the stack still hold after weeks of normal use. Provider behavior, model IDs, permissions, backups, and release notes deserve a slower review because mistakes in those layers can create bigger messes than a missed daily report.

Run this one when you have enough time to read the report and decide what should change, because the monthly review is the one most likely to recommend actions that touch live state.

Create a Hermes cron job called "Monthly Assumptions Review" that runs on the 1st of every month at 10:00 local time, delivers to origin, and uses a cheap model (gemini-3.1-flash-lite via openrouter, or deepseek-v4-flash via opencode-go — pick whichever is configured). Restrict toolsets to terminal, web, and file. Use this exact prompt body for the job:

---
Run a monthly read-only Hermes assumptions review. Make no changes: do not update Hermes, change providers, rotate keys, restore backups, prune memory, delete files, rewrite configs, or edit scheduled jobs.

1. External change summary. Check for changes that could affect this stack in the last ~30 days:
   - Hermes Agent: `cd ~/.hermes/hermes-agent && git log --since="30 days ago" --oneline` and check release notes
   - Plugins and skills: list anything in ~/.hermes/plugins/ and ~/.hermes/skills/ modified in the last 30 days
   - Provider changes: scan OpenRouter and opencode-go model lists for renamed, deprecated, or newly preview-flagged IDs that match anything in ~/.hermes/config.yaml
   - Gateway, memory backend (hindsight), scheduler, and backup tool changelogs if accessible
   Summarize only changes relevant to this stack.

2. Provider and model ID audit. Grep every config layer for model IDs:
   - Main: ~/.hermes/config.yaml
   - Profiles: ~/.hermes/profiles/*/config.yaml
   - Cron jobs: ~/.hermes/cron/jobs.json
   - Skills referencing models: search_files for "model:" or model IDs under ~/.hermes/skills/
   - Scripts under ~/.hermes/scripts/
   - Env files: ~/.hermes/.env and any *.env
   Flag preview IDs (-preview, -beta, dated suffixes), known-deprecated IDs, missing fallbacks, and defaults that conflict between layers.

3. Health sweep. Quick check across:
   - Gateway response (one Telegram round-trip)
   - Provider reachability (one ping each to configured providers)
   - Memory recall (hindsight_recall on an active project)
   - Scheduler activity (hermes cron list plus recent output)
   - Storage headroom (df -h on ~/.hermes/ partition)
   - Backup completion (most recent backup artifact timestamp and size)
   - Key availability (env vars and 1Password references exist, not the values)
   - Permissions (~/.hermes/ ownership and mode)

4. Restore test. Pick one non-sensitive backup artifact under ~/.hermes/backups/ or wherever backups land. Copy to /tmp/hermes-restore-test/, inspect contents, confirm it opens and matches expectations. Do not overwrite live files. Delete the temp copy after inspection.

5. Approval-gate review. List every workflow (cron job, skill, plugin, script) that can delete files, prune memory, rotate keys, change providers, restore backups, update Hermes, edit configs, or send messages outside this workspace. For each, confirm whether it requires explicit approval or runs automatically.

Return a report with exactly these sections:

ASSUMPTIONS STILL VALID:
Operational assumptions that still look safe.

ASSUMPTIONS TO RECHECK:
Provider, memory, gateway, scheduler, backup, or permission assumptions that may have drifted. Name the layer.

RESTORE TEST:
Artifact inspected, safe location used, and result.

PROPOSED CHANGES:
Each with reason, risk (low/med/high), rollback notes, approval status.

APPROVAL NEEDED:
Every action that would modify the stack or touch live data. Name the action and layer. Do not execute.
---

After creating the job, run it once immediately so we can see the first report, then confirm the job ID and schedule.

I review provider model IDs here instead of waiting for a stale preview route to break under load. A fallback route in an old project config can keep calling yesterday’s model even after the main Hermes provider has moved to the stable ID.

The Hindsight timeout became confusing because the symptom pointed at the wrong layer. Hermes felt slow, I blamed the model, and the retrieval path had already burned the time before generation started.

Approval Gate for Maintenance Jobs

Every scheduled maintenance job should carry the same approval rule because the boundary gets easy to forget after the first few reports look useful. Read-only inspection can run freely, while destructive or identity-changing work still needs a human decision.

If you haven’t built that habit yet, start with the approval gate setup before you let a maintenance prompt touch files, providers, keys, or backups.

Add this block to the end of every maintenance prompt that runs on a schedule, especially if the agent has access to files, keys, backups, provider settings, or outbound channels.

Approval rule for this maintenance job:

You may observe, inspect, summarize, classify, and recommend without asking first.

You must ask for approval before any action that deletes files, prunes memory, rotates keys, changes providers, restores backups, updates Hermes, edits configuration, changes scheduled jobs, rewrites prompts, sends external messages, or changes permissions.

When approval is needed, return a proposal with the issue, suggested action, expected benefit, risk level, affected files or systems, rollback notes, and the exact command or tool call you want to run.

If the risk is unclear, classify the action as approval needed and wait.

That rule keeps the maintenance agent useful without letting it become a cleanup bot with too much confidence. The agent can prepare the decision, but I still want to make the decision when live state changes.

Quiet Agent Failures

The failures that cost time are small enough to miss and specific enough to blame on the wrong thing. My cron failure didn’t crash the stack because it stopped doing work in a corner I wasn’t watching.

The model ID drift behaved differently because the main provider setup looked current while an older route still pointed somewhere stale. The visible symptom showed up as slower Hermes responses and memory behavior that looked worse than it was.

The Hindsight timeout changed how I diagnose agent slowness in every workflow that depends on memory. When an AI tool slows down, I check the retrieval chain before I blame the model because the model may be downstream from the delay.

Maintenance doesn’t prevent every failure, but it reduces the time spent accusing the wrong layer. Once you can name whether the issue sits in routing, memory, scheduling, storage, backup, skills, or config, the repair becomes less mysterious.

How to Roll Out the Routine

I would start with one weekly maintenance job before adding daily and monthly jobs. Weekly reporting is frequent enough to catch drift, and a month of reports gives you enough signal to decide whether the daily pulse is worth the extra noise.

Once the weekly report proves useful, add the daily pulse for the pieces you depend on most. My daily set covers gateway response, scheduled job output, memory recall, and provider reachability because those failures change whether I can trust the stack that morning.

The monthly review should stay slower and more deliberate because updates, provider IDs, backup restores, and permission gates need more attention than a quick morning report can give them.

Your stack may use different names, but the shape should stay the same. The scheduled agent observes the stack, reports the failed layer, proposes small actions, and stops before touching anything that could create real damage.

Failure Limits

Maintenance won’t make the stack perfect, and the prompts shouldn’t pretend they can. Provider outages, weak retrieval, bad project context, poor model fit, and bad release notes can still turn into manual work.

The routine also leaves approval gates in place for every action that changes live state. If Hermes wants to prune memory, change providers, delete logs, rotate keys, restore a backup, or update itself, I still want to approve that action before it touches anything real.

That boundary keeps the routine useful because the agent can notice problems before I do, while every action that changes the system comes back as a proposal I can read.

Bottom Line

Hermes feels like one system when it’s working, but underneath it’s a control plane sitting on top of models, memory, gateways, cron jobs, files, skills, providers, and backups. When one layer drifts, the whole experience gets worse even if the visible symptom looks like a slow model or a lazy agent.

The maintenance loop keeps those layers visible through a daily pulse, a weekly drift review, and a monthly assumptions review. For most personal agent stacks, that rhythm is enough to know where to look when something breaks.

Start with the weekly prompt and run it long enough to see whether the reports change your behavior. If the reports help you catch missed jobs, stale model IDs, slow memory, or backup gaps, add the daily pulse and monthly review around the same approval rule.

The install guide gets Hermes running, and the maintenance loop is what keeps it worth trusting.

Drop the layer you trust least in your agent stack right now: model, memory, gateway, cron, or backups.

I Tested 6 AI Plans to Find What $5, $10 and $20 Get You

Dan Cucolea — Tue, 19 May 2026 14:10:55 GMT

A little while ago, I built a multi-step workflow in Hermes to generate a ten-page report that would get stronger each time it passed through the document. It checked the latest news, then read through Reddit threads, then cross-checked with X and also read through a bunch of internal documents.

For most of the run, it worked the way I wanted, and Hermes kept moving the file forward while pulling in the context it needed and holding onto the thread of the job.

By the time it reached the last stage, somewhere around the fourteenth tool call, it already had the material it needed and only had to stay coherent long enough to verify the details and write the final section cleanly into the file.

Then it just stopped in the middle of the edit. It retried enough times to trigger a context reduction right when the report needed the fullest possible view of everything that had already happened. The fact that I had to step back in and rebuild the whole thread was extremely annoying and the reason why I decided to write this article.

That was also the moment I started focusing on reliability rather than judging AI plans by the model menu.

Pricing pages encourage you to compare plans by the names they advertise, but Hermes forces a more practical question, which is whether a plan can carry real work through a messy session without handing it back to you halfway through.

Once I started looking at plans that way, I cared a lot less about whether a subscription included a famous model and a lot more about whether Hermes could finish the work before my own attention became the most expensive part of the workflow.

I have paid for enough AI accounts to know how misleading a low sticker price can be. A five-dollar plan stops feeling cheap the moment it burns an hour of focused work.

Not to mention that most twenty-dollar plans might feel like they come with extra usage compared to their cheap alternatives, but that is not usually the case. Looking at you, Anthropic.

That’s the frame for this piece, because I rechecked the official pricing pages on May 19, 2026, and I want to show you these prices through an AI agent lens rather than focusing on their sales copy.

In this article:

Why model names and benchmark scores are the wrong way to judge an AI plan
How one $5 plan became my daily driver after I fixed my routing
Why the $10 tier is where most plans start to make real sense
What the big brand names ($20 tier) actually limit once you push them
Where plans break mid-session and how cost per useful hour flips the math
The exact stack I would buy today and which plans I would skip

The One Test That Picks Winners

Benchmarks tell you how a model performs in isolation, but Hermes shows you something much harder to fake, which is whether a plan stays useful once the session fills with tool calls, file reads, and the usual clutter that comes with trying to finish real work.

My test now feels much simpler than any leaderboard, because all I really have to do is give Hermes one job from a normal week and watch how much of my own attention it gives back to me by the end.

If Hermes gets to a result I can keep, the plan earns its place. If the session breaks, the model loses the thread, or I have to step back in for cleanup, the plan gets more expensive no matter how cheap the subscription looked when I bought it.

$5: Where Most People Get It Wrong

The five-dollar tier starts with OpenCode Go, and it stands out immediately as it’s the only subscription I found that gives you a real first month instead of a throwaway trial.

Right now, OpenCode Go is $5 for the first month and $10 after that, and it works in Hermes by default, which matters because it feels like a provider route built for agents instead of a chat plan stretched into agent work after the fact.

What changed my view of this plan is that it did not stay a cheap side route for long. It became my daily driver, even during the stretch when I was still paying for three subscriptions just to keep up with my usage.

At the time, the real problem was not the plan itself but the way I was using it, because I kept pushing the same model through every kind of Hermes task and expecting it to behave well no matter what the work looked like.

For a while I ran Qwen 3.6 Plus for almost everything, and that worked badly enough that I ended up compensating with more subscriptions instead of better routing.

The setup only started to make sense once I matched the model to the job, with DeepSeek V4 Flash and V4 Pro taking most of the regular Hermes work while Gemini 3.1 Flash Lite via OpenRouter handled image analysis more cleanly than the routes I had been forcing before.

OpenCode Go became much more useful once I stopped treating one model like a universal answer and started treating the plan like a routing layer for different kinds of work.

I still think the five-dollar month is the right place to learn this lesson, since it is cheap enough to experiment with and real enough to show you very quickly whether your workflow is efficient or just patched together.

$10: The Real Starting Line

The $10 tier is where most of these plans start to feel normal, since the $5 and sub-$5 options are mostly gone now outside of special promos.

That is also the first tier I would take seriously for regular Hermes use.

After the first month, OpenCode Go lands here at its regular price, and MiniMax Token Plan Starter shows up at the same $10 with 1,500 M2.7 requests every 5 hours.

On paper, that sounds like a clean comparison. In practice, I care much less about the headline limits and much more about what the workflow feels like once Hermes is doing the work.

MiniMax Starter gives you a dedicated M2.7 bucket, which is useful if you already know that model is good enough for most of your week and you want limits that are easy to reason about.

OpenCode Go works differently, since it gives you a shared routing budget across several model families, and that can look better or worse depending on what kind of week you’re having.

If you mostly run MiniMax M2.7 through Go, the published estimates are higher at around 3,400 M2.7 requests every 5 hours for the same monthly price, so it can look cheaper than MiniMax Starter on raw throughput alone.

Still, that is not what would decide it for me.

I would judge the whole tier by loop quality more than by the model list or benchmarks. Sometimes I hit 503 errors on Qwen 3.6 Plus through OpenCode Go, and other times the tokens per second I got through Go were clearly better than what I was getting from MiniMax directly. And I absolutely hate it to wait for AI to answer. I’d rather have a faster model than a smarter model, but that’s just personal preference.

What matters most to me is whether it keeps moving after the first answer, uses tools cleanly, and keeps its replies short enough that the session stays readable while the work is still in progress.

$20: Brands You Know, Limits You Don’t

The $20 tier is where the familiar companies start showing up.

OpenAI and Anthropic are the obvious ones, because they are the subscriptions most people already know. Ollama belongs in the same conversation for a different reason, as it’s one of the few open-model companies that already feels big enough to sell a hosted plan without sounding like a side project.

That matters because this tier is not only about extra usage. It is also about how much trust people attach to the company behind the plan, and whether that trust survives contact with the actual limits.

ChatGPT Plus is the default benchmark. OpenAI lists Plus at $20 per month, says it gives higher GPT-5.5 limits inside ChatGPT, and keeps API usage separate from the subscription.

You can count Plus in the real stack because Hermes supports OpenAI Codex through ChatGPT OAuth, but the plan still buys ChatGPT access rather than API credit. The limit story is also less generous than the branding makes it feel. OpenAI says Plus users can send up to 160 GPT-5.5 messages every 3 hours, and manual GPT-5.5 Thinking has a weekly limit of up to 3,000 messages. That is fine for normal chat use. It starts looking smaller once you lean on it harder.

Claude Pro has the same advantage and the same problem. Anthropic is a big enough name that people do not need much convincing to try the plan, and Claude is useful enough that plenty of people will keep paying for it anyway. The issue is that the limits are nowhere close to generous for heavy use.

It’s just easy to run into the ceiling faster than the $20 price tag suggests, especially once you lean on Sonnet for real work.

Ollama Cloud Pro is more interesting to me because it is not trying to be ChatGPT or Claude. Ollama lists Pro at $20 per month or $200 per year, with larger cloud models, 50x more cloud usage than Free, and three concurrent cloud models.

That sounds strong until you compare how the limit story is presented next to OpenCode Go. OpenCode Go tells you the five-hour, weekly, and monthly caps directly, including a monthly ceiling of $60. Ollama tells you usage is mostly GPU time, gives you five-hour and weekly resets, and lets you run three cloud models at once, but it does not spell out a monthly limit on the pricing page. That makes the plan harder to reason about.

The three-model ceiling also matters more in Hermes than it would in a normal chat app. If you mostly run one agent at a time, it probably feels fine. If you like concurrent agents, background runs, or separate research and writing loops happening together, three can start feeling smaller than the headline suggests.

So yes, Ollama Pro looks good. It is just not automatically better than Go once you care about legibility, concurrency, and what the plan looks like over a full month instead of over a good afternoon.

Nous Portal Plus is less mainstream than OpenAI, Anthropic, or Ollama, but it still deserves the slot because it fits Hermes more naturally than most of the bigger brands. Nous lists Plus at $20 per month with 300+ models, hosted tool usage, and $22 in monthly credits with rollover. I felt that I should include this because they are the team who created Hermes after all.

MiniMax Token Plan Plus is still the simplest volume play. MiniMax lists Plus at $20 per month with 4,500 M2.7 requests every 5 hours plus speech and image quotas. If M2.7 already works for your Hermes load, that is a very direct way to buy more room.

Those are not the same thing, and the difference only shows up once Hermes starts leaning on the plan instead of just chatting through it.

Where Plans Hit the Wall

Hermes exposes plan limits in the middle of real work instead of at the edge of a chat.

A chat cap is annoying when you are asking questions. The same cap inside Hermes can land in the middle of a file edit, a research loop, or a tool run that was finally starting to cohere. Then you lose more than a reply. You lose the state of the job and pay for it again in the next session.

Fallback models create a quieter version of the same mess. A session starts on one route and ends on another, and you can feel it even before you check the model picker. Instruction following gets softer. The agent stops being careful with the same tool path it was following ten minutes earlier.

Tool use is still the cleanest divider for me. A model can sound impressive in a chat window and still be weak inside an agent loop. If it avoids reading files, skips verification, or acts allergic to tools, I do not care how good the brand or benchmark looks. The less glamorous route that checks its work often finishes more jobs per dollar.

Memory changes the value of a plan too. Hermes only starts to feel useful once it can carry a project forward across sessions. If the provider leaves you with a morning reset, the agent never really joins the work. It just keeps reintroducing itself.

That is also why the OpenClaw to Hermes migration mattered so much to me. I was not looking for a smarter chat app. I wanted something that could keep the work moving without making me rebuild the thread every time.

Latency has its own cost. A slow model is fine for overnight cleanup or background chores. It gets expensive the moment you are thinking with the agent in real time and waiting for the next useful move.

The Only Math That Matters

The metric I keep coming back to is cost per useful Hermes hour.

I like it because it is boring enough to be honest.

cost per useful hour = monthly plan cost / Hermes hours that ended in usable work

If a $5 plan gives you ten clean background hours, it is excellent.

If that same plan burns one focused afternoon because Hermes stalls in the fragile part of the job, the cheap price was fake.

A $20 plan can still be the cheaper one if it finishes the sessions you would otherwise have to rescue.

I would not build a dashboard for this. One line in your notes after each session is enough. Write down the plan, the job, and whether Hermes finished without babysitting.

After a week, the pattern usually gets obvious. OpenCode Go might end up doing the background work. MiniMax might carry more of the daily load than you expected. Nous might keep its place because the tool gateway removes setup friction. Ollama might stay as the open-model cloud route. ChatGPT and Claude might remain in the stack because they are still where you think best before sending the work back into Hermes.

That is enough to make the decision. The goal is to stop paying for subscriptions without knowing what job each one is there to do.

Here Is What I Would Buy

If I were rebuilding this stack today, I would still start with OpenCode Go and give it the boring work first.

That is the cheapest place to learn whether the workflow is efficient or just being propped up by extra subscriptions.

I would keep fragile sessions away from it until it earned trust. Cleanup, first-pass research, low-risk drafts, and the kind of work that is useful when it lands but not painful if it misfires.

Once the first month ended, I would treat the $10 tier like the real test. OpenCode Go at full price and MiniMax Starter both deserve a normal week before I let a $20 brand into the stack on reputation alone.

After that, I would only pay for a $20 plan if I knew exactly why it was there. ChatGPT Plus belongs if the ChatGPT or Codex lane matters enough to keep. Claude Pro belongs if Claude is still where the best writing or dev work happens, even with the limits. Nous sits closest to native Hermes work. Ollama Pro belongs if I want the open-model cloud lane and can live with the three-model ceiling. MiniMax Plus is the straightforward volume upgrade if M2.7 is already carrying real work.

That is less satisfying than picking one winner. It is also closer to how the work behaves.

Different jobs deserve different routes. Background chores do not need the same plan as the sessions where one bad restart can waste half an afternoon.

Drop your current AI subscription stack in the comments. I want to know which plan hits the wall first in your Hermes workflow.

Bottom Line

The cheapest AI plan is the one that gives Hermes work you would keep.

A $5 route is great when it clears background noise. A $10 route is where I would test daily Hermes usage. A $20 route only earns its place when it gives you something the cheaper paths do not, whether that is better fit, clearer limits, or a route you trust enough to use for harder work.

The wrong plan steals focus at any price.

Before you buy another subscription, look at your last ten Hermes sessions. Mark the ones that ended in usable work. Mark the ones you had to rescue. Then ask which plan helped the work move forward and which one only looked cheap on the invoice.

That becomes the buying decision.

I would rather pay for one route that finishes the work than keep juggling three subscriptions that still need me to manage them.

Source Notes

OpenCode Go lists the $5 first month and the $10 monthly price after that. The page also covers any-agent use and current request allowances.

ChatGPT Plus lists $20 per month, app-level Plus benefits, and the note that API usage is billed separately. OpenAI API pricing lists GPT-5.5 and GPT-5.4 token pricing outside ChatGPT subscriptions.

Ollama Cloud pricing lists Pro at $20 per month or $200 per year. The same page covers three concurrent cloud models and usage measurement based mainly on GPU time.

Nous Portal lists Plus at $20 per month with 300+ models and hosted tool usage. It also lists the $22 monthly credits and rollover rules.

Claude Pro lists Pro usage behavior and resets, while Anthropic API pricing lists Claude API prices separately from Pro.

MiniMax Token Plan lists Starter at $10 per month with 1500 M2.7 requests per 5 hours and Plus at $20 per month with 4500 M2.7 requests per 5 hours.

Hermes AI Providers lists the relevant provider paths for Nous Portal and OpenAI Codex. It also covers OpenCode Go and Anthropic.

When to Use MCPs, CLIs, or Your Own Tool

Dan Cucolea — Tue, 12 May 2026 13:17:53 GMT

A while back, I wanted my AI agent to help manage my Asana tasks. Like anyone following the current agent meta, my first instinct was to plug in an Asana MCP server. Of course, this either flat-out broke or took an eternity to load a sngle task because the agent was trying to digest a massive, complicated integration.

Frustrated, I ripped the MCP out and installed a lightweight Asana CLI instead. It took a little bit of setup, but it worked. I took it one step further and created a custom skill teaching my agent exactly how to trigger those specific CLI commands. Checking my tasks went from a sluggish, bloated mess to happening instantly. I detailed this setup in my morning automation guide.

That experience explains why the default advice in agent-land right now, to connect every integration you can find and sort it out later, is a trap.

I get why people do it. Plug-and-play tools are everywhere right now. Every week another company ships one, another app exposes itself to AI, and another setup thread turns into a shopping list. An agent with more tools feels more capable the same way a dashboard with more widgets feels more complete.

The friction starts soon after. You notice the agent taking longer to think because it’s trying to juggle too many complex instructions at once. Simple tasks start driving up your token costs. One tool fails with a timeout, another dumps a wall of messy data when you only needed a single sentence, and eventually, you lose track of what your own setup can do on its own.

In my Hermes setup, I rely on three distinct patterns. A lightweight GitHub CLI handles my repository work because it’s fast and focused. The Brave Search MCP handles broad web research. My custom OpenCode Cowork Proxy Worker exists because neither an off-the-shelf integration nor a basic command line was the right fit for routing Claude through OpenCode models.

There’s a fine line between over-integrating and building everything yourself. I touched on this balance in my build vs buy scorecard. How do you know which type of tool fits which job? Read on to see how to decide.

TL;DR: When deciding how to connect your AI agent:

Use CLIs for local, internal tasks where speed matters and you own the credentials.

Use MCPs to cross boundaries into external SaaS systems where structured data and secure auth are required.

Build Custom Wrappers when you need translation, formatting, or a narrower interface than what off-the-shelf tools provide.

In this edition:

Why MCP vs CLI is the wrong argument
When a CLI is the better interface for Hermes
When an MCP server earns its place
When your own small tool beats both
The 60-second test I use before adding a new tool

MCP vs CLI: Asking a Better Question

Most MCP vs CLI arguments sound cleaner than the real problem. People talk about protocols, tokens, and elegance. When you are in the middle of actual work you are usually trying to answer a simpler question. You want to know the least messy way to let your agent do this one job.

An MCP server gives an AI app a standard way to discover and call external tools. It exposes actions, inputs, and outputs in a format the model-facing app understands. Anthropic introduced MCP in November 2024 as an open standard for connecting AI assistants to data sources, business tools, content repositories, and developer environments.

A CLI gives the agent the same command-line tool a human developer would use. Think git, gh, docker, kubectl, wrangler, gws, or a tiny script you wrote for your own stack. The model writes commands, reads stdout or stderr, and adjusts from there.

Both let an agent act, but they package control differently. MCP gives the agent a typed menu of actions with structured inputs. CLI gives the agent a terminal surface with familiar commands and visible output.

The filter I use is simpler than the debate. Look at where the work happens, who owns the data, and what breaks when the agent gets it wrong. Use a CLI when the agent works as you inside your own workspace. Use an MCP server when the agent needs structured access to external systems or authenticated data. Build your own tool when MCP is too broad, CLI is too loose, or the workflow needs a narrow bridge between two systems.

The custom option matters more than people admit because many agent problems are shape problems, not model problems. A full protocol server or open shell gives the workflow too much room to drift. One small action with the right inputs, rejection rules, and clean output often fits better.

When to Start With CLI for Local AI Workflows

I start with CLI far more often than MCP. If Hermes works inside my own environment, on local files and repos, build commands, deployment checks, server diagnostics, GitHub tasks, or small scripts where I already know the command, the terminal is usually the right first stop.

A command-line tool has a structural advantage here. Most frontier models have years of examples for common command-line patterns. They know how git status behaves, how gh pr list --json returns fields, and how to trim output before the context window fills up.

Local work becomes easier to debug. When a CLI command fails, Hermes gets an exit code and an error message. I rerun the same command myself, copy it into a terminal, and see the failure without translating through a protocol layer.

Scalekit ran a useful benchmark on this in March 2026. They compared CLI, CLI plus skills, and GitHub’s MCP server across 75 runs using the same model and the same GitHub tasks. In their test, CLI won on cost and reliability. CLI hit 100 percent reliability, MCP completed 72 percent of runs, and MCP used 4 to 32 times more tokens depending on the task.

I wouldn’t stretch that benchmark into a universal law. It tells us something narrower and more actionable: schema weight is real. If the agent connects to a GitHub MCP server with dozens of available tools, it carries descriptions for actions it will never touch during a repo language lookup. A local gh command gives the answer with less ceremony.

StackOne makes the same split from an architecture angle. CLI fits local developer tools like Git, Docker, gh, Terraform, kubectl, and AWS CLI because these tools already have mature command cultures around them. The agent reuses patterns baked into the model and the docs instead of learning a strange new interface from scratch.

My Hermes setup leans on CLI for repo work. If I ask Hermes to clean up a branch, summarize open PRs, or check the status of a deploy, I want it using tools I run myself. I use gh for GitHub, wrangler for Cloudflare Workers, and gws for narrow Google Workspace experiments.

The trade-off is permission shape. Most CLI tools inherit local credentials. Hermes using gh after gh auth login acts with my GitHub access. That works for my own repo on my own machine, then breaks fast once a product needs to act across other users, accounts, or shared business systems.

One user on one machine inside one workspace is CLI territory. Many users across many accounts turns CLI into complex auth plumbing.

When to Reach For MCP At The Boundary of External Data

I don’t reach for MCP first. I reach for it when the data lives somewhere else and I want Hermes to touch it without wandering around with raw shell access.

Search tools, shared SaaS systems, business databases, internal APIs, and third-party services need scoped auth, audit logs, and structured actions more than terminal speed.

A command-line tool assumes a person already logged in. That person owns the machine, the credentials, and the risk. An MCP server exposes a narrower set of actions to the agent with defined inputs and outputs. It gives the agent a tool boundary instead of raw shell access.

Anthropic’s original MCP pitch makes sense through that lens. Every agent stack eventually hits the same wall: the model works well, but the data lives outside its reach. MCP gives AI systems a standard way to connect to those data sources without every app inventing its own format.

I use Brave Search via MCP because research is external, variable, and structured. I want Hermes calling a defined search action with a defined result format instead of guessing URLs or scraping pages with shell commands.

SaaS tools often fit the same pattern. If Hermes needs to read from Notion, Gmail, Linear, Slack, Greenhouse, or a database with scoped access, MCP is cleaner than a homemade CLI script. The farther the workflow moves from your own machine, the more identity matters.

Descope puts the identity question well: choose based on who the agent works for. If the agent acts as a solo developer inside their own workflow, CLI is enough. If the agent acts across customer data, employee accounts, partner systems, or shared business tools, auth becomes the primary concern.

At that point, you care about scopes, consent, logs, tenant boundaries, and revocation. One ambient shell token doing everything in the background becomes a liability, even if it feels faster during local tests.

Every MCP server still has to earn its place. A bloated server slows the agent down, a badly designed one returns excess data, and a broad action list hands the agent more control than the task needs. The best MCP servers feel boring: a small list of tools, clear input fields, tight output, and an auth model that matches the risk.

You want a clean tool drawer, not a giant toy box.

Build The Bridge Yourself

This sounds like extra work at first. Then you try to force a bad fit through MCP or CLI for hours and realize the small custom tool would’ve been the simpler path all along.

By small tool, I mean a tiny adapter, wrapper, Worker, script, webhook, or endpoint that does one job in the exact shape your workflow needs.

I used this lane for my OpenCode Cowork Proxy Worker. Claude Code speaks Anthropic’s API format. OpenCode Go and Zen models mostly use OpenAI-compatible routes. I wanted Claude Code and Claude Cowork as the interface, with OpenCode as the model layer. A generic MCP server or raw CLI would’ve made the flow messier.

The workflow lacked translation, so I built a Cloudflare Worker that sits in the middle. Claude sends an Anthropic-style request. The Worker rewrites it for OpenCode. The response returns in the format Claude expects. That is a custom tool doing its job by removing ambiguity.

I wrote the full setup in How to Use Claude Code For Free With OpenCode Models. For this article, the decision matters more than the proxy details. When the workflow needs a translation layer, build the translation layer.

Safer wrappers around risky commands follow the same pattern. Say Hermes needs to deploy a project. One path gives it raw shell access and asks it to remember the right sequence. The better path gives it one command:

deploy-preview --project yahini

That command runs checks, prints the diff, refuses production deploys without a flag, and outputs a clear summary. Hermes gets one safe action instead of an open-ended terminal adventure.

Task tools work the same way. My Asana setup has three possible shapes: raw API calls, MCP, or a small wrapper:

asana-task create --project hermes --title "Research MCP auth tradeoffs" --due tomorrow

That wrapper hides the noisy parts. Hermes gets the project, title, and due date without carrying the project GID, JSON payload shape, or field rules in every prompt. The tool encodes the boring decisions once.

Custom tools pay off when the existing interface adds ambiguity. A translator fixes format mismatch, a filter trims redundant output, and a validator stops bad inputs before they reach the real system. The common thread is narrower access to the machinery underneath.

Approval gates fit on top of this lane. Your custom tool prepares a draft, validates inputs, or creates a preview. The final send, publish, delete, deploy, or purchase still pauses for review. I covered the safety layer in How to Add Approval Gates to Your Hermes Agent, and it pairs well with custom tools because the interface and approval rule solve different problems.

A custom tool gives Hermes the right action. An approval gate decides whether Hermes gets to complete it alone.

Reply with one MCP, CLI, or script you are unsure about and I will help classify the workflow.

The Rule I Use

Before giving Hermes a new way to act, I sort the workflow into one of three lanes. The categories are plain enough to use while building, which matters more to me than making the taxonomy perfect.

Use CLI for local work. Choose CLI when the tool is mature, the docs are everywhere, the output is controllable, and Hermes is acting inside your own environment. Good fits include GitHub PR summaries through gh, Cloudflare Worker deploy checks through wrangler, local file operations, build commands, server diagnostics, and one-off scripts. If I would run the command myself in a terminal, and the worst mistake affects my own workspace, CLI is the starting point.

Use MCP for structured external systems. Choose MCP when Hermes needs a defined tool boundary, scoped auth, a remote data source, or runtime tool discovery. Search, Google Drive, Slack, Gmail, CRM data, ATS data, internal databases, and shared business tools fit this lane when permissions and structure matter. If the agent touches data outside your own local workspace, MCP deserves a look.

Build your own tool when the job is narrow. Choose a custom tool when the problem is translation, filtering, validation, or repeatability. API format translation, safer deploy wrappers, task helpers, memory update commands, webhook receivers, cronjob helpers, and scripts compressing risky command chains into one reviewed action fit here. If you keep writing long prompts to make the agent use a tool in the same careful way, that prompt wants to become a tool.

Concrete Hermes examples make the rule easier to apply. GitHub PR cleanup goes through CLI because gh is mature and easy to inspect. Competitive research goes through MCP because search needs structured external results. Morning briefings use connectors or MCP for sources like Gmail and calendars, then a prompt or custom formatter turns those inputs into the briefing structure I covered in my Hermes morning briefing article.

For higher-risk work, I mix lanes. Production deploys should use CLI wrapped in a custom command, plus an approval gate before production. Claude Code to OpenCode routing belongs in a custom Worker. Project memory updates from research should use a custom command or proposed-change format, then pause for review before permanent memory changes.

That last one matters because wrong memory is worse than no memory. If Hermes reads a weak article and updates project memory with a sloppy summary, I pay for that mistake later. A custom “propose memory update” tool is safer than letting the agent edit memory directly.

60-Second Tool Test

Before adding a new MCP server or writing a wrapper, run this test. It takes about a minute, and it saves an afternoon of cleanup.

1. Check for a mature CLI. If the tool has a strong CLI, structured output flags, and common examples in the docs, start there. The agent gets a smaller surface to reason through, and you get commands worth replaying.

2. Check whether the agent acts only as you. If Hermes works inside your own machine, repo, or server, CLI works well. Slow down when the workflow crosses into shared systems.

3. Check whether auth shape matters. MCP moves up the list when you need scopes, consent, tenant boundaries, or audit logs. Local credentials are convenient until the agent needs to act inside a shared business system.

4. Check whether the MCP is too broad. If a server exposes fifty actions and your workflow needs two, consider a custom wrapper or filtered gateway. A smaller interface beats a bigger config when the task has a narrow shape.

5. Check whether a small tool would remove repeated prompting. If your instruction keeps repeating the same safety rules and formatting rules, build a tool that enforces the shape. Repeated prompting points to an interface problem.

After the test, the answer usually sorts itself. CLI handles local work, MCP handles structured external systems, and your own tool handles narrow bridges, translations, and repeatable actions. Approval gates sit on top of all three when the action is expensive, destructive, external-facing, or hard to undo.

This is the shift I wrote about in The Agentic Engineering Shift. The work is moving from asking the model better to designing the system around the model better. Tool choice is part of that system.

More Control, Less Clutter

A well-designed agent stack earns trust when the agent knows what to do, shows what it did, and uses the smallest interface that fits the work. MCP hype tends to blur that distinction because installing another server feels like progress.

MCP is useful. CLI is underrated. Your own small tools save you from both when the workflow has a shape neither one matches.

Start by auditing one workflow. Pick the last task you gave Hermes that involved a tool and ask which lane it belonged in. If the task was local, try CLI. If it crossed into shared systems, look at MCP. If you kept explaining the same careful sequence over and over, build the tiny tool. Use an agent you trust because every interface has a reason to exist.

Drop one workflow in the comments and classify it: MCP, CLI, or your own tool. If you are unsure, I will help sort it.

How to Use Claude Code For Free With OpenCode Models

Dan Cucolea — Tue, 05 May 2026 14:28:01 GMT

Yes, you can use Claude Code for free by routing it through a small Cloudflare Worker and pointing that Worker at a free OpenCode Zen model like nemotron-3-ultra-free.

Claude stays the interface. OpenCode becomes the model layer.

That means you can keep the Claude experience people already like, skip Anthropic billing for low-stakes work, and only move to a paid provider lane when the task actually deserves it.

You see, at the end of March 2026, Anthropic shipped a Claude Code npm package with a source map inside it. That packaging mistake exposed a huge chunk of the Claude Code TypeScript source. Within hours, mirrors spread across GitHub. Some picked up thousands of stars and forks before Anthropic started sending takedowns.

Then the cleanup got messy. TechCrunch reported on April 1, 2026 that Anthropic’s DMCA request hit about 8,100 GitHub repositories before the company narrowed the scope.

That told me two things.

First, developers wanted Claude Code badly enough to swarm the leaked source. Second, the demand for using Claude’s interface with other provider lanes was already there.

All this landed at a weird time for me. I’ve already shifted a lot of my own coding time to Codex, mostly because GPT got close enough to Opus for my day-to-day work and the usage limits feel better. Hermes still handles my heavier recurring workflows and automations.

But I still liked Claude Code. And I still wanted to try Claude Cowork without paying the full Anthropic tax every time I wanted a polished coding session.

The problem was simple.

Claude speaks Anthropic. OpenCode Zen and OpenCode Go mostly speak OpenAI-compatible endpoints.

So I built a translator.

The OpenCode Cowork Proxy Worker lets Claude Code talk to OpenCode Go models and selected OpenCode Zen models. Claude keeps sending Anthropic-style requests, then the Worker translates them into the upstream format OpenCode expects.

No key storage. No message storage. Just a format bridge.

With that in place, you can start with free OpenCode Zen models like minimax-m2.5-free, then move to OpenCode Go’s subscription lane when the work gets more demanding.

I made the switch easy on purpose. You need a Cloudflare account and an OpenCode account. Both can start free, and you only upgrade if the workflow becomes worth it.

Deploy the Worker in Cloudflare First

Before Claude can use OpenCode, you need a gateway URL it can call.

Open the OpenCode Cowork Proxy Worker repo and click the Deploy to Cloudflare Workers button at the top. Cloudflare supports this one-click deploy flow directly for Workers projects, which is why this setup is fast to hand off.

Cloudflare walks you through the rest. When it finishes, copy your Worker URL.

At that point, your gateway is live.

Your deployed URL will look like your own Cloudflare Worker endpoint. In the examples below, I’ll call it:

YOUR_DEPLOYED_WORKER_URL

Configure Claude Desktop to Use OpenCode Zen

Open Claude Desktop and go to the third-party inference setup.

If you’re on Windows, go to:

Help > Troubleshooting > Enable Developer Mode

Claude will restart and expose a new menu:

Developer > Configure Third-Party Inference

Anthropic’s current help docs for Claude Cowork’s third-party setup use this same path, so you’re not relying on a weird hidden hack here. You’re using the intended setup UI.

For your first test, point Claude at OpenCode Zen with the free model minimax-m2.5-free:

Backend: Gateway
Gateway base URL: YOUR_DEPLOYED_WORKER_URL/zen
API key: your OpenCode API key
Auth scheme: x-api-key
Model: minimax-m2.5-free

Once that’s done, make sure to add the model manually too:

minimax-m2.5-free

Click Apply locally. Fully quit Claude Desktop. Reopen it.

That’s the basic path for using Claude Code with a free OpenCode model through your Worker.

Start with Free OpenCode Zen Models

Start with OpenCode Zen, not Go.

Zen is OpenCode’s curated model gateway. Some Zen models are paid. Some are free for a limited time while model teams collect feedback.

Last updated: May 7, 2026

The current OpenCode Zen docs list these free models:

minimax-m2.5-free
ling-2.6-flash
hy3-preview-free
nemotron-3-super-free
big-pickle

Use this first:

minimax-m2.5-free

Your base URL should end with:

/zen

Your model field should be:

minimax-m2.5-free

Free means free while OpenCode is offering that model under a free period. It does not mean no account, no API key, or no caveats.

You still need an OpenCode API key.

And you should absolutely check the privacy notes before using free models with sensitive work. As of May 7, 2026, OpenCode’s Zen docs say several free models may use collected data during the free period to improve the model. That includes minimax-m2.5-free. This is the exact opposite of the lane you want for sensitive code.

This is the test lane.

Use it for summaries, low-risk code review, documentation cleanup, and tiny file edits in a throwaway folder. Don’t start by pointing it at your main repo with write access.

On my own first tests, the free Zen route handled summaries, low-risk reviews, and tiny file edits fine, but I switched to /go as soon as I wanted stronger reasoning over a larger repo.

I wrote about the bigger reason open models matter in Ditch Your Subscriptions and Run Open Source AI on Your Device. The short version is the same here: model choice gets more useful when your tools stop forcing the interface and the engine to stay married.

Choose /zen for Free Models and /go for OpenCode Go

The proxy has two routes.

Use /zen for free models and Zen pay-as-you-go models:

YOUR_DEPLOYED_WORKER_URL/zen

Use /go for the monthly OpenCode Go subscription lane:

YOUR_DEPLOYED_WORKER_URL/go

If you want the fast mental model, use it like this:

/zen is the free test lane
/go is the stronger daily-work lane

As of May 7, 2026, the OpenCode Go docs list Go at $5 for the first month, then $10 per month.

The same docs currently list these usage limits:

5-hour limit: $12 of usage
Weekly limit: $30 of usage
Monthly limit: $60 of usage

Your actual request count depends on the model.

Cheaper models stretch much further. Heavier models burn the limit faster.

The important privacy distinction is this: OpenCode Go says its providers follow a zero-retention policy and do not use your data for model training. That makes it a much better fit for real coding work than the free-model lane. I would still avoid calling anything “complete privacy,” but it is the safer route according to the current docs.

I covered OpenCode Go more broadly in The $30 Hermes Stack That Makes Claude Max Look Like a Ripoff. For Hermes, Go gives you a cheaper provider lane. With this proxy, Go becomes useful from Claude Code too.

Why This Route Instead of OpenRouter or Ollama?

Because the point here is not just “find any cheaper provider.”

The point is keeping Claude’s interface and tool flow while swapping the model layer underneath it.

If you just want the fastest generic provider swap, OpenRouter is simpler.

If you want fully local inference, Ollama is a better answer.

If you specifically want Claude Code or Claude Cowork as the front end while OpenCode handles the models behind the scenes, this Worker route is the right tool.

That matters more than it sounds. A lot of people do not actually want a new interface. They just want a cheaper or more flexible inference lane behind the interface they already like.

If you want the broader comparison between Claude Cowork and other agent setups, I broke that down in OpenClaw vs Claude Cowork vs Perplexity Computer - Which AI Agent Actually Fits Your Life.

Test Claude Code Safely in a Throwaway Folder

Don’t point this at your main repo first.

Create a throwaway folder:

claude-opencode-proxy-test

Add a file:

project-notes.md

Put fake project notes in it. No secrets. No client data.

Ask Claude Code:

Read project-notes.md.
Summarize the project in 10 bullets.
Create a second file called next-actions.md with a short implementation checklist.
Do not modify project-notes.md.

This checks whether routing and tool behavior work together. Claude has to create the new file from the notes without touching the original.

If that works, try a small code review:

Review this function for bugs.
Do not edit files yet.
Give me the risk list first.

I like that second test because it keeps the model away from edits until you see how it behaves.

After that, test one small tool-heavy task. Ask it to compare two files and create a short note. Keep the task boring.

You’re testing routing and tool behavior, not the model’s taste.

Free models are useful, but they need judgment. I wrote about that line between vibe coding and agentic engineering in The Agentic Engineering Shift.

Switch to OpenCode Go When the Free Lane Stops Being Worth It

OpenCode Go is one of the more transparent AI subscriptions out there because the limits are expressed in dollar value, not in a vague “come back later” chat cap.

Switch to /go when the free Zen models are too weak, too slow, too rate-limited, or too risky for the work.

That usually happens when one of these becomes true:

You want better reasoning over a bigger codebase.
You want fewer caveats around data usage.
You are doing enough coding work that a $10 lane is cheaper than burning a premium subscription elsewhere.

The nice part is that the setup barely changes. You keep Claude as the interface. You just swap the route and the model.

I covered OpenCode Go in The $30 Hermes Stack That Makes Claude Max Look Like a Ripoff. For Hermes, Go gives you a cheaper provider lane. With this proxy, Go becomes useful from Claude Code too.

How This Also Works with Claude Cowork

This is the part I care about more than the free model itself.

People like Claude Code and Claude Cowork because the interface feels good to use, and nobody wants another subscription with fuzzy limits hanging over every small coding session.

Claude Cowork especially has the kind of product polish that makes people want to stay inside it. The project view feels clean, the tool activity is easy to follow, and the whole thing feels closer to an app than a pile of agents you have to babysit.

The annoying part is paying for the whole Anthropic route every time you want that app experience.

I can justify premium reasoning models when I’m asking for difficult architecture help or reviewing a risky change. I do not want to burn premium usage on every small housekeeping task.

That’s why I built this proxy, and I want the compatibility point to be explicit: this route works with Claude Cowork too. You can keep Claude Cowork or Claude Code as the place where you work without needing Claude itself as the model route behind it.

The cheap path lets you keep the Claude app experience instead of forcing yourself into another interface.

You can start with a free OpenCode Zen model, then move to the $10 OpenCode Go lane when you want a stronger open model inside Claude Cowork or Claude Code.

I still like OpenCode. I still use Codex. Hermes is still where my serious recurring workflows live. The point is that Claude Cowork does not have to become another expensive subscription decision when OpenCode can provide the model layer for free or for far less.

If you want the shared-workflow version of that story, read OpenClaw or Claude Cowork? Here’s How to Plug Both Into the Same Brain.

Use This 10-Minute Checklist to Get Started

Open the OpenCode Cowork Proxy Worker repo.
Click Deploy to Cloudflare Workers and install the Worker in your Cloudflare account.
Copy your deployed Worker URL.
Open Claude Desktop.
Enable Developer Mode, then open Configure Third-Party Inference.
Set the base URL to YOUR_DEPLOYED_WORKER_URL/zen.
Set auth scheme to x-api-key.
Paste your OpenCode API key.
Add minimax-m2.5-free manually.
Click Apply locally, fully quit Claude, then reopen it.
Run the throwaway-folder test.
Switch to YOUR_DEPLOYED_WORKER_URL/go and a Go model when you want the subscription lane.

Grab the Worker, run the throwaway-folder test, and star the repo if it works for you. Stars tell me which Claude/OpenCode routes are worth maintaining next.

FAQ

Can I use Claude Code for free?

Yes, but not in the default Anthropic-billed path this article is bypassing.

You use Claude Code for free here by routing its requests through your own Cloudflare Worker and pointing that Worker at a free OpenCode Zen model such as minimax-m2.5-free.

Is Claude Code in VS Code free?

Claude Code itself can be installed, but the model path behind it usually costs money unless you route it to a free provider lane.

This setup gives you one of those free lanes.

How do I get Claude Code credits for free?

You don’t get Anthropic credits from this method.

You bypass Anthropic billing for these sessions by translating Claude’s requests to a free OpenCode Zen model instead.

How do I use Claude Code free forever?

“Forever” is doing too much work in most of the videos and posts ranking for this topic.

You can use it free as long as a provider keeps offering a free model and the setup still works. That can change. That’s why this article treats the free route as a useful lane, not a permanent law of nature.

External Sources Worth Checking

If you want the primary docs behind this setup, start here:

And if you want the leak story source rather than my summary, TechCrunch covered the takedown incident here:

Anthropic took down thousands of GitHub repos trying to yank its leaked source code

How to Add Approval Gates to Your Hermes Agent

Dan Cucolea — Tue, 28 Apr 2026 13:29:46 GMT

Most people who try AI agents go through the same cycle. They set it up, give it access to everything, and watch it do impressive things for a week. Then something goes wrong, like a wrong message or a broken file, and they shut it down and go back to doing things manually.

The problem was skipping the safety net.

I went through that cycle twice. The first time, my agent sent an email to a client with the wrong name, and I mean a completely different person, not a typo. I found out when the client forwarded it back asking if I was working with someone else. I spent the next three weeks manually reviewing everything the agent touched. That burned more time than if I had done the work myself.

The second time, I set up gates before giving the agent access. Drafts and system changes came to me for review. Spending above a threshold required approval. I let it run, and nothing went wrong. The gates caught mistakes before they went live.

I’ll show you how to build approval gates into any Hermes workflow. Gate #1 takes 15 minutes and stops your agent from sending anything external without your OK. Gate #2 adds protection against unwanted system changes and puts dollar limits on spending. Start with the first one. Add the others when you’re ready.

If you’re new to Hermes itself, start with Hermes Is the AI Agent OpenClaw Promised to Be.

In this article:

What an approval gate is, and why it isn’t a roadblock
The three types of gates every AI workflow needs
Step-by-step setup for each gate, from beginner to advanced
A simple framework to decide what to gate and what to leave free
The three mistakes people make with approval gates, and how to avoid them

A Checkpoint Is Not a Roadblock

The word gate makes people think of barriers and delays. That’s the wrong mental model. An approval gate is more like a checkpoint at the end of an assembly line. The work happens at full speed. The checkpoint keeps defects from shipping.

Three patterns exist for keeping humans involved in AI workflows. Human-in-the-loop means the agent stops and asks you before taking an action. You review, you approve, the agent continues. Human-on-the-loop means the agent runs autonomously, but you can watch what it does and intervene if something looks wrong. Full autonomy means you set it up and never look at it again.

Shopify defaults to human-in-the-loop by design for anything that touches production systems. LangChain found that most organizations use approval checkpoints as their primary guardrail. The EU AI Act requires evidence of appropriate oversight for each AI system. These are standard practice.

The same principle works for solo operators. You need a simpler version.

The Three Gates You Need

Every AI workflow that touches the outside world or modifies your data needs at least one gate.

The Send Gate. Nothing goes external without your OK. Emails, social posts, client communications, any message that carries your name. Your agent drafts, delivers to you, and waits. You review and approve the send. That’s the gate most people need first.

The Change Gate. Nothing modifies your systems without your OK. File edits, database updates, configuration changes. Your agent identifies what needs to change, shows you the proposed change with context, and waits for confirmation.

The Spend Gate. Nothing costs money without your OK. Paid API calls above a threshold, tool purchases, subscription changes. Your agent estimates the cost before any paid action. Below your threshold, it proceeds automatically. Above it, it pauses and asks you.

Each gate protects something different: your reputation, your data, your wallet. You don’t need all three on day one. Start with the Send Gate.

Gate #1: The Send Gate (Start Here)

That’s the one that fixes the wrong-name-in-an-email problem. The setup takes about 15 minutes. You build a workflow where the agent drafts everything, but you control the final step.

The workflow has four steps:

Step 1. The agent drafts the content. An email, a social post, a client response, anything.

Step 2. The agent delivers the draft to you through chat, email, or a file. It doesn’t send it anywhere, just hands it to you for review.

Step 3. You review the draft and fix anything that needs fixing. Reply with your approval or your corrections.

Step 4. The agent sends or publishes the approved version. If you asked for changes, it revises and shows you the updated version.

In Hermes, the Send Gate works best as two separate pieces. The first is a standing rule in project memory. The second is the cronjob or task that runs under that rule. If project memory still feels abstract, my article on infinite memory explains why these standing rules matter.

Example 1: Save this in Hermes memory

Treat this as a starter template, not a fixed script. You may need to change the approval words, the delivery channel, or the types of content it covers based on how Hermes is set up in your project.

You are my Content Assistant. Your job is to draft content for review.

When I give you a content request (email, social post, client response):

1. Draft the content based on my instructions and the project brief.
2. Present the draft clearly labeled "DRAFT [FOR REVIEW]".
3. Don't send, publish, or share the content anywhere.
4. Wait for my approval or my requested changes.
5. If I request changes, apply them and present the revised draft.
6. Only when I explicitly say "approved" or "send it", take the final action.

Always include a brief note at the end explaining what you did and why.

Example 2: Use this as a Hermes cronjob

This works best when Hermes already has access to the inputs it needs, such as meeting notes, a calendar, or a project brief, and already knows where to send drafts back to you. You may need to change the schedule, the source it reads from, or the format of the output to fit your workflow.

Every weekday at 9:00 AM, review yesterday's meeting notes and draft any follow-up emails that need to be sent.

Present each email as "DRAFT [FOR REVIEW]".
Do not send anything automatically.
Wait for my approval before any email goes out.

If there are no follow-ups to draft, tell me that no action is needed today.

If you want to see cronjobs in action before you build this one, the Hermes morning briefing workflow shows a complete example.

Watch Out: If your agent has tool access that lets it send emails or post to social media directly, make sure the prompt overrides those tools. The approval step must be the only path to external action.

If you’re still wiring up Hermes tools, memory, and integrations, the Hermes setup guide covers the stack behind workflows like this.

Gate #2: The Change Gate (Level Up)

Once your Send Gate works, add protection against unwanted system changes. This gate matters when your agent interacts with files, databases, or any system where a bad edit breaks something real.

The agent identifies what needs to change: which record, which field, and what the new value should be. Vague requests like “update the database” fail this gate.

The agent shows you the proposed change with full context: current state, new state, why the change is needed, and what happens if the change goes wrong.

You approve or reject. If you reject, the change never happens. If you approve, the agent executes it and confirms the result.

The rollback plan is simple. If a change causes problems, you tell the agent to reverse it. Because the agent showed you what it wanted to change before doing it, it can undo the change on request.

Use this prompt for a research agent that updates your knowledge base:

When you find information that should update the project knowledge base:

1. Show me the proposed change with this format:
   - Current value: [what exists now]
   - Proposed value: [what you want to change it to]
   - Reason: [why this change is needed]
   - Source: [where you found this]

2. Wait for my approval before making any changes.

3. If I approve, make the change and confirm what was updated.

4. If I reject, don't make the change. Log the rejection in the project notes.

Never modify files, databases, or project memory without going through this process first.

This takes about 20 minutes on top of your Send Gate. The time investment is worth it the first time your agent wants to overwrite a file with outdated information.

Gate #3: The Spend Gate (Advanced)

This gate protects your wallet. AI agents can run API calls, subscribe to tools, and make purchases if you give them access. Without a spend gate, a runaway loop of API calls can cost hundreds before you notice.

The setup relies on spending thresholds in your project memory. Set a dollar limit that matches your comfort level, whether that’s $5 per transaction or $50. Pick the number that lets you sleep well.

Your agent estimates the cost before any paid action. Below your threshold, it proceeds automatically. Above it, it pauses, shows you the estimate, and waits for approval.

Add this to your prompt:

Before taking any action that costs money (API calls, tool purchases, subscriptions):

1. Estimate the cost.
2. If the cost is below $10, proceed automatically and log the expense.
3. If the cost is $10 or above, pause and show me:
   - What you want to do
   - Why it is needed
   - Estimated cost
   - Free alternatives, if any
4. Wait for my approval before proceeding with actions that cost $10 or more.

Keep a running total of all expenses in the project notes.

Adjust the threshold to your needs. The point is to keep you informed when the agent is about to spend money that matters. This takes about 15 minutes on top of the others. If your agent doesn’t have spending access, skip this one.

What is the one task you’d hand off to your agent if you knew there was a gate before it went live? Drop it in the comments. I’ll share the exact prompt for your use case.

To Gate or Not to Gate

You can’t gate every action. If you do, your agent becomes a slow typist that asks permission before every keystroke. At that point, you might as well do the work yourself.

Low risk, high volume. No gate needed. File organization, summarization, categorization, formatting. The worst thing that happens is a slightly messy summary, and you fix that in seconds.

Medium risk, moderate volume. Review gate. Draft emails, content suggestions, data analysis. The agent produces the work, you review it before it goes anywhere. The Send Gate handles this category.

High risk, low volume. Full gate. External communications, system changes, spending. The agent pauses, explains what it wants to do, and waits for explicit approval. All three gates cover this category.

To apply this to your own workflows, list every task your agent handles. Write down the worst thing that could go wrong. If the mistake costs you money, damages your reputation, or breaks a system, gate it.

If the mistake is annoying but easy to fix, let it run free and correct course when needed.

The Three Mistakes People Make

Most failures come from one of these three patterns.

Gating everything. This turns your AI into a slow typist. You spend an hour approving every sentence and paragraph, then realize you could have done the work yourself. The fix: apply the decision framework above. Gate only what needs gating.

Gating nothing. That’s how your AI sends wrong emails to clients, overwrites production files, and racks up unexpected charges. You give the agent full autonomy on day one. Something goes wrong. You stop using the agent entirely. The fix: start with the Send Gate. Add the others as your trust grows.

Gating without context. A vague approval request forces you to dig through the agent’s reasoning to figure out if the change is safe. The fix: require the agent to show the current state, the proposed change, and the reason for the change. A good gate gives you everything you need to decide in under 10 seconds.

Trust the Process but Keep the Net

You stop babysitting and stop opening every draft with a knot in your stomach. You give your agent a task, trust the process, and review the output at the checkpoint. Most of the time, you approve it without changes. Occasionally, you catch something and fix it. Either way, the work moves forward.

The trick is to start tight and loosen up over time. In week one, you review every draft. By month two, you move the Send Gate to sample mode: review every third draft, trust the rest. You haven’t caught a mistake in weeks. The gate stays in place, but you use it less.

That’s the goal. Reduce gates as the system matures. Real delegation is only possible when you know the safety net works. Once you see the net catching problems, you can let the agent fly higher.

Building the right gates is all delegation requires. Once they’re in place, you can let it run.

How My Hermes Agent Plans My Morning Before I Have My Coffee

Dan Cucolea — Tue, 21 Apr 2026 13:19:34 GMT

You probably start every morning the same way most people do. Phone in hand. Six apps open before you finish your coffee. Email, task manager, Slack, calendar, news feed, Substack digest. Each one wants your attention. Each one claims urgency.

By the time you reach actual work, your best mental energy is already spent. You made dozens of tiny decisions about what to open, what to read, and what to ignore. Your real work gets the leftovers.

The problem is not discipline. The fire hose of inputs hits you the second you wake up, and no amount of willpower fixes a broken system.

I stopped trying to fix my habits and started fixing how information reaches me. Now one cronjob gathers my Asana tasks and hands me one clear decision to start the day. A second cronjob runs twice daily, checks Gmail for Substack articles, and sends me a curated digest email. I read the briefing in 30 seconds. The two hours come from fewer context switches, less reactive mode, and a single first action instead of a dozen tiny decisions.

Follow along as we build both systems in three layers. Layer 1 takes 15 to 20 minutes and covers the Asana morning briefing. Layer 2 adds the Substack digest email that runs twice daily. Layer 3 extends the briefing to Slack, Jira, GitHub, or any service with an API. Start wherever you want as each layer is useful on its own.

What we will cover:

Why checking multiple apps each morning burns your best energy before work even starts
The four-section briefing structure that replaces a to-do list with a decision
Step-by-step setup for the Asana briefing and the Substack digest email
How to extend the briefing to any API-driven tool you already use
Keeping both systems from bloating into useless noise

You Are Not Lazy, Just Constantly Interrupted

You are exhausted before 9 AM, and the reason has nothing to do with laziness.

Gloria Mark at UC Irvine studied this for years. Her research found that after an interruption, it takes an average of 23 minutes and 15 seconds to return to deep focus on the original task. Not to finish it. Just to get back into it. If you check email, then Slack, then your calendar, then a task list, then a news feed, you end up losing over an hour in refocus time alone.

The Adobe Email Usage Study found that Americans spend over five hours per day checking work and personal email combined. We spend hours refreshing inboxes. Actual communication barely happens. We train ourselves to react to whatever arrives instead of deciding what matters.

Inbox zero reinforces this pattern. It teaches you to treat every incoming message as equally urgent. The newsletter you subscribed to in 2019 gets the same mental weight as a client asking about a deadline. Your morning becomes a sorting exercise for other people’s priorities.

CEOs and important people have secretaries who sift through everything before it reaches them. We have AI agents like Hermes and Openclaw that can do this for us, maybe even better than the average person.

Here is how I built the one system that gathered everything in my pipeline and made one recommendation to get my day started.

What an Actually Good AI Briefing Looks Like

A good briefing works as a decision support document. It replaces your basic to-do list.

Most people think a morning briefing means listing everything they need to do today. That approach creates anxiety instead of clarity. A list of 15 tasks leaves you feeling behind instead of showing you where to start.

My briefing has four sections. Each one stays capped at 2 to 3 bullets. It ends with one forced decision. Without that final gate, the briefing becomes another scrollable feed you skim and forget.

Here is the structure:

Today — Meetings, deadlines, hard commitments that cannot move.

Tasks — Open items from Asana, sorted by impact, not by order added.

Alerts — Unread emails from humans, not newsletters. Overdue items that need attention.

One Decision — The single action that would make the rest of the day easier.

The Today section tells me what time is already spoken for. The Tasks section tells me what I chose to work on. The Alerts section catches anything that slipped through. The One Decision section forces me to think instead of consume.

I have seen people build briefings with ten sections. Weather, stock prices, news headlines, calendar, tasks, emails, social mentions, fitness data. That approach builds a dashboard, and dashboards serve monitoring. Briefings serve decision-making.

If your briefing takes longer than 3 minutes to read, trim a source. Tighten a filter. Clarity matters more than completeness.

Layer 1: Build Your First Briefing in 20 Minutes

Start with one source. Asana works well because you already put your commitments there. If your Asana is messy, the briefing will reflect that mess. Spend 10 minutes cleaning due dates and priorities first. The cronjob cannot organize what you have not organized. If your task manager lacks structure, that cleanup step becomes your first priority before automating anything.

What you need:

An Asana account, free tier works
Your Asana personal access token
Hermes with cron support

Prerequisites:

An Asana account (sign up here)
Your Asana personal access token (get one here)
Asana API docs for reference: developers.asana.com/docs or the Asana MCP server if you prefer MCP over REST
Hermes with cron support

Everything else happens inside the prompt. Hermes handles the API calls, the sorting, and the formatting. You do not write code or configure endpoints. You paste the prompt, set a schedule, and the cronjob does the rest.

Here is the exact prompt I give my cronjob:

You are my Morning Briefing Agent. Your job is simple: help me start the day with clarity instead of chaos.

Every morning at 8:15 AM Bucharest time, run this routine:

1. Pull my open tasks from Asana using the asana API or CLI
2. Sort them by: due date (overdue first), priority, project
3. Identify my top 3 highest-impact tasks for today
4. Flag anything overdue or due today
5. Format everything into a 2-minute briefing

The briefing structure:
---
TODAY'S BRIEFING — [Date]

TODAY:
- [Meetings/deadlines from tasks]

TOP 3 TASKS:
1. [Highest impact task] — [Project] — Due: [Date]
2. ...
3. ...

ALERTS:
- [Overdue items]
- [Items due today]

ONE DECISION:
What is the one task I should finish first to make everything else easier?
---

Keep each section to 2-3 bullets. No fluff. No summaries of summaries. Just the signal.

Paste that prompt directly into your Hermes chat, whether through Telegram or the TUI. Hermes handles the API calls, the sorting, and the formatting. Set a schedule with the cronjob tool, point the delivery at your chat or email, and run it once to verify the output.

Here is what the actual output looks like on a typical morning:

TODAY'S BRIEFING — April 22, 2026

TODAY:
- 10:00 AM — Client sync call (Project Alpha)
- 3:00 PM — Article draft deadline

TOP 3 TASKS:
1. Finish API integration for client proposal — Client Work — Due: April 22
2. Review pull request #25 — Open Source Project — Due: April 23
3. Update Substack draft for next week — Substack — Due: April 25

ALERTS:
- "Design mockups feedback" task overdue since April 20
- "Invoice March services" due today

ONE DECISION:
Finish the API integration before the 10 AM call so you have something concrete to discuss.

That is it. Twenty minutes. One source. One clear read every morning.

If you have read Hermes Is the AI Agent OpenClaw Promised to Be, you know why the cron architecture matters. This briefing runs on the same backbone. If you have not set Hermes up yet, The $30 Hermes Stack That Makes Claude Max Look Like a Ripoff walks through the full stack.

Layer 2: The Substack Digest Email

The morning briefing covers your tasks. Your newsletters need a separate system. I run a second cronjob that checks Gmail for Substack article emails twice a day on weekdays, at 9:15 AM and 4:15 PM. It reads each article, summarizes it, and sends me a formatted digest email. This is not part of the Telegram morning briefing. It is a separate pipeline with a different output and a different schedule.

What you need:

The gws CLI tool for Google Workspace integration
A Gmail account where Substack sends your digests

gws is a command-line tool that connects Hermes to Google Workspace, including Gmail. You install it once, authenticate with your Google account, and the cronjob gains read-only access to your inbox.

Here is the cronjob prompt I use:

Check Gmail for new Substack article emails and deliver a nicely formatted digest to your email, only covering emails received since the last check.

## Step 1: Check Gmail for new Substack articles

1. Read the last run timestamp from a tracking file. If it doesn't exist, use 24 hours ago as the cutoff.
2. List Substack emails: gws gmail +triage --query "from:*@substack.com" --max 20
   Note: Substack emails arrive already marked as read, so do NOT use is:unread.
3. For each message, read it with gws gmail +read --id  to get the email Date header. Compare against the last run timestamp. Skip anything received AT or BEFORE the last run time. Only process emails received AFTER.
4. Filter out non-article emails (follower notifications, subscriber alerts, live video announcements).
5. For each new article in the time window:
   a. Extract the article URL from the email body
   b. Fetch the full article via markdown.new: curl -sL "https://markdown.new/http://"
   c. Generate a short 2-3 sentence summary
   d. Determine if FREE or PAID by checking for paywall text

## Step 2: Output Format

Compose a formatted email digest with this exact structure:

📬 Substack Digest — [Day, Month DD, YYYY]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🆓 Article Title
by Author Name
Summary: 2-3 sentences covering the core argument and why it matters
🔗 Article URL

🔒 Article Title (PAID — subscriber only)
by Author Name
Summary: 2-3 sentences covering the core argument and why it matters
🔗 Article URL

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Use 🆓 for free articles and 🔒 for paid ones. Keep it clean and scannable.

## Step 3: Deliver

1. Send the digest via gws gmail +send to your email
2. Write the current time to the tracking file for the next run

If no new articles found, respond with [SILENT].

The digest runs twice daily because Substack articles arrive throughout the day. The morning catch covers overnight posts. The afternoon catch covers everything published during work hours. Each run only processes articles received since the last check, so you never see duplicates.

Here is what a typical digest looks like:

📬 Substack Digest — Tuesday, April 21, 2026

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🆓 Computer agents are going mainstream
by Jonas Braadbaart (The Circuit)
Summary: Examines the gap between AI adoption and actual agent deployment, arguing that individual operators are the ones closing the gap rather than enterprise teams. Practical look at how solo builders are using agents for real workflows.
🔗 https://thecircuit.substack.com/p/computer-agents-mainstream

🔒 Claude Managed Agents Review
by Creators AI
Summary: Testing managed agent workflows and comparing them to self-hosted alternatives. Covers setup complexity, cost trade-offs, and when managed services actually save time.
🔗 https://creatorsai.substack.com/p/managed-agents

🆓 Don Quixote and the Sorrowful Algorithm
by Farida Khalaf (Lights On)
Summary: Literary essay on AI narrative inevitability using Don Quixote as metaphor. Explores how algorithmic storytelling converges on predictable patterns despite different prompts.
🔗 https://lightson.substack.com/p/don-quixote-sorrowful-algorithm

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Trade-off: You are giving your cronjob email access. Start with read-only permissions. Never give it send permissions until you have run this for a month and trust the output. The agent reads. You decide. That boundary matters.

Layer 3: Plug in Slack, Jira, GitHub, or Anything with an API

The morning briefing can pull from more sources besides Asana. The same cronjob that checks your tasks can also query Slack, Jira, GitHub, or any service with an API.

What you can add:

Slack: Unread DMs or mentions from specific channels
Jira: Tickets assigned to you, overdue sprints
GitHub: PRs waiting for review, assigned issues
Notion: Database items flagged for review
Any API: If it has an API, Hermes can query it

How to add a new source:

Get an API token for the service.
Add the token to your Hermes project environment.
Add one step to the cronjob prompt: “Pull my open items from [service].”
Add a section to the briefing template.
Test once, then schedule.

Trade-off: More sources means more noise. I recommend adding one source per week and watching the signal-to-noise ratio. If the briefing gets longer than 30 seconds to read, trim something.

The pattern stays consistent across every source. Token in environment. One new step in the prompt. One new section in the output. You do not need to rebuild the system. You just expand it.

I run Asana for tasks and GitHub PRs for code review items. That is my sweet spot. Anything more and the briefing starts to feel like work before I have finished my coffee.

Information Without Action Is Just Noise

The cronjob’s final instruction in every layer is the same: “At the end, identify the ONE decision or action that would make the rest of the day easier.”

This prevents the briefing from becoming another scrollable feed. It forces me to think, not just consume.

You read the briefing. You nod. You close it. You open your laptop and immediately forget what you just read. The information felt useful, but it did not change what you did next. The One Decision gate fixes this problem. Skip it and the briefing loses its purpose. The One Decision is the entire point.

Some days the decision is obvious. “Finish the client proposal first so the deadline stops hanging over me.” Other days it is strategic. “Block two hours for deep work before opening Slack, or the day will get stolen.” Either way, I start with a clear intention instead of a reactive scan.

Here are real One Decisions from my last week:

“Reply to the contract email before noon so the other side does not stall waiting for us.”
“Merge the PR before the afternoon standup so the team can proceed with testing.”
“Write the article outline first because the blank page anxiety blocks everything else.”

This is where the human-in-the-loop approach from article 005 on approval gates matters. The cronjob drafts. You approve. The system does not replace your judgment. It surfaces information so your judgment has something to work with.

The briefing is a draft. You review it. The cronjob does not act without you.

How to Keep Your Briefing Brief

Most people give up because the briefing becomes useless fast. Here are the three breakdowns I have seen, and how to fix each one.

1. Too much noise

Filter out newsletters, automated alerts, and low-priority senders. In Asana, use sections, tags, or due dates to surface only what matters. In email, filter by sender, not just unread status. If your briefing includes a GitHub notification about someone starring a repo you contributed to in 2022, your filters are too loose.

2. Stale priorities

Update your project memory bank weekly. Five minutes. Review and tweak the prompt monthly, or the briefing drifts into generic summaries. The tasks you cared about in January differ from the tasks you care about in April. Your briefing should reflect that shift.

3. Cronjob goes stale

If you stop reading the briefing, the cronjob will keep sending it. It becomes inbox clutter. Pause the schedule. Fix the output. Resume. Do not let automation become noise you ignore. The system only works if you trust it enough to read it.

I review my briefing prompt on the first Monday of each month. Five minutes. I check whether the sections still match what I need, whether any source has gotten too noisy, and whether the One Decision question still forces useful answers. Those five minutes save me from a month of useless briefings.

Less Cognitive Load Is the Real Payoff

Time saved is a side effect. The actual benefit comes from removing decision fatigue.

I no longer open email first thing. I start with my own priorities. The two hours come from fewer context switches, less reactive mode, and clearer first actions. Moving between working and getting the right things done requires that shift in how you begin the day.

Before the briefing, my morning involved a series of small decisions about what to check next. After the briefing, my morning involves one decision about what to do first. Everything else follows from there.

The system has rough edges. Some days the cronjob misses context. Some days the One Decision misses the mark. The results still beat the chaos I dealt with before, and every prompt tweak makes it sharper.

The architecture behind this is straightforward. One cronjob. Four sections. One forced decision. Each source adds a single API call and a single template section. The complexity lives in the filters, not the infrastructure.

What is the first source you would add to your briefing? Drop it in the comments. I read every response.

The Agentic Engineering Shift

Dan Cucolea — Tue, 14 Apr 2026 13:35:47 GMT

The fastest way to build a product you cannot maintain is to let AI write all of it without asking questions.

Sure, you will ship faster than anyone in the room. Yeah, the demo will work. But two weeks later, when a user reports a bug, you will open the file and scroll through functions you do not remember writing. Because you did not write them. The AI did. You accepted the output, tested the happy path, and moved on.

Changing one line feels dangerous because you cannot trace what it touches. The code works, but you do not own it. You are maintaining a stranger’s project inside your own repo.

Andrej Karpathy gave this gap a name. In February 2025 he coined “vibe coding” to describe the practice of accepting AI output without scrutiny. A year later he followed up with “agentic engineering,” the practice of orchestrating AI agents with oversight, structure, and human judgment at every step.

The naming matters because thousands of builders recognized themselves in it. But a label does not tell you what to change. This post gives you a way to figure out where you sit on the spectrum between the two and which practices will move you forward.

If you have read How To Architect A Feature In 5 Minutes Before Talking To AI, you already know why thinking before prompting matters. This piece picks up where that one left off. Thinking before prompting is the starting habit. What follows is the full set of habits that separates builders who ship from builders who ship and survive.

In this edition:

What Karpathy’s two terms mean and where the conversation stops being useful
A 4-stage maturity spectrum to locate where you are right now
The 5 workflow practices that make the shift from vibe coding to agentic engineering concrete
A 60-second diagnostic you can run on your last shipped feature tonight

What Karpathy Named

Vibe coding means giving an AI a prompt, getting code back, and shipping it without meaningful review. You trust the output because it runs. You move fast because the feedback loop feels instant.

The AI writes a function, you glance at the result, and if nothing throws an error, it goes into the codebase.

Agentic engineering means working with AI agents as part of a structured process. You provide context, define constraints, review outputs, run evaluations, and make the final call on what ships.

The AI still does the heavy lifting, but YOU direct the work and own the result. Every piece of generated code passes through your judgment before it touches production. And this goes beyond coding.

Both terms describe real behaviors that builders already practiced before the vocabulary existed. Karpathy gave the community a shared language for something people felt but struggled to articulate. The developer copying AI output straight into a feature branch at 2am was vibe coding long before anyone named it.

The problem is that most of the conversation stopped at the labels. Forums and comment sections turned it into a binary: vibe coding bad, agentic engineering good. That framing misses the point.

Nobody operates at one extreme all the time. A solo builder prototyping on a Saturday afternoon and a team shipping a payments feature to 10,000 users should not follow the same process. The real question is what specific behaviors separate one from the other, and how you move between them.

The Spectrum

This is not a pass/fail test. Builders sit at different points on a gradient, and the position shifts depending on the project, the deadline, and the stakes. The useful exercise is recognizing where you are right now based on what you do, not what you believe.

Stage 1: Prompt and Ship

You describe what you want. The AI writes it. If the output runs, you merge it. Testing means clicking through the feature once to confirm it loads.

This works for throwaway prototypes and weekend experiments. The failure mode shows up later. Features become untouchable because you cannot predict what changing one piece will break.
You open a file, see 200 lines of logic, and realize you have no idea why the AI structured it that way. Every revisit feels like defusing a bomb you did not build.

Stage 2: Patch and Pray

Bugs appear. You fix them by prompting the AI again with the error message. The fix works, but you still do not understand the underlying structure. You know fragments of the codebase. You do not know the system.

This is where most builders I see in forums and Reddit threads are sitting right now. The product shipped. Users showed up. And every maintenance task takes three times longer than it should because the codebase grew in directions nobody planned.

The failure mode here is compounding. Each reactive patch adds weight. You fix the form validation bug and break the error toast. You fix the error toast and notice the loading state flickers. Confidence drops with every fix because you are never sure the patch did not break something else. The codebase starts to feel adversarial.

Stage 3: Review and Contain

You start reading the AI’s output before merging. You notice recurring patterns in what the AI gets wrong. You add checks. You push back on suggestions that feel over-engineered or unclear.

At this stage, AI becomes a fast junior developer on your team rather than an oracle. You treat its output the way a senior developer treats a pull request from someone in their first year. You catch the unnecessary abstraction. You question why it created three helper functions when one would do.

The failure mode is inconsistency. The review habit exists, but it drops off when you are tired, rushed, or excited about a feature. Friday afternoon, deadline looming, a new feature working on the first try. The temptation to merge without reviewing is strongest when the output looks clean. Process without discipline reverts to vibe coding under pressure.

Stage 4: Agent with Guardrails

You work with explicit context documents, evaluation criteria, test expectations, and review gates. You can explain why every function exists and what conditions would break it. The AI still generates the code. You architect the system and verify the output.

The failure mode even here is over-automation. Trusting the process so fully that you stop applying judgment to edge cases. The test suite passes, the evaluation loop looks green, and you ship without reading the diff. Process is a tool, not a replacement for thinking.

Most builders reading this will recognize themselves somewhere in stages 2 or 3. That recognition is the starting point. The next section covers what moves you forward.

If you have been through The Build vs Buy Scorecard, you already know the value of slowing down before making technical decisions. The same principle applies here. The spectrum rewards deliberate behavior over fast output.

The Practices

The shift from vibe coding to agentic engineering is visible in workflow, not philosophy. These are five habits you can observe yourself doing, or not doing. Each one addresses a specific failure mode from the spectrum above.

1. Review Gates

Treat every AI output like a pull request from a junior developer. Read the code before you merge it. Check whether the approach matches what you asked for. Look for unnecessary complexity, redundant calls, or logic you cannot follow.

When you skip this: you inherit code you cannot reason about. The AI might add a caching layer you never asked for, or restructure your data flow in a way that makes sense in isolation but clashes with the rest of your system. The codebase grows in ways you did not choose, and every future change requires re-learning what the AI decided on your behalf.

2. Eval Loops

Test more than “does it work once.” Feed the AI’s code edge cases, unexpected inputs, and failure scenarios. If you built a form handler, send it empty fields, duplicate submissions, and malformed data. Check what happens when the external API is slow or down.

When you skip this: the AI passes the demo and fails the real world. You find the bugs in production instead of in development, and your users find them before you do.

3. Test Coverage for Agent Output

If the agent wrote the code, someone needs to verify it holds up. Write tests for the critical paths. If you do not write tests yourself, at minimum run the feature through its failure modes manually before shipping.

When you skip this: “works in dev” becomes “breaks in production.” Maintenance turns into archaeology because you are digging through code with no map of what was supposed to happen. You can pair this with the approach in How to Prompt AI for Consistent JSON Responses to make sure the outputs you are testing against stay predictable.

4. Context Architecture

The quality of AI output depends on the quality of your input. Before prompting, define what the feature needs to handle, what it connects to, and what constraints exist. Break the problem into scoped pieces. Give the agent acceptance criteria, not open-ended requests.

When you skip this: the agent guesses the system you meant. It fills in gaps with assumptions pulled from training data, and those assumptions may not match your product, your users, or your stack. You ask for a notification system and get a full pub/sub architecture when all you needed was a database flag and a polling endpoint. This is where the 5-minute architecture sketch pays off the most.

5. The Explain-It-Back Check

Before shipping any AI-generated code, explain what it does in your own words. Walk through the logic, the data flow, and the failure path. If you hit a function you cannot explain, that is the part that will break first in production.

When you skip this: ownership never transfers back to you. The code ships under your name, but the understanding stays with the model that generated it. When a user reports a bug at 11pm, you will stare at the function and have no starting point for debugging it. You become a passenger in your own project.

None of these practices make AI infallible. AI will still produce flawed output, miss edge cases, and make assumptions you did not ask for. These practices make your relationship to that output honest. You stop hoping the code is correct and start knowing where to look when it is not. The AI handles generation. You handle judgment. That division of labor is the entire point.

Tell me which practice from this list you have started doing, or which one you know you have been skipping. Drop it in the comments.

The 60-Second Test

Open the last feature you shipped with AI assistance. Pick any file from that feature and read through it.

For each function, check three things. Whether you can explain what it does without reading it line by line. Whether you know what happens when it fails. Whether there is a test covering the critical path.

If you breeze through all three, pick a second file. Keep going until you hit the wall. Most builders find it faster than they expect.

The first question you cannot answer marks your starting point on the spectrum. That is the exact spot where your next upgrade begins. You do not need to fix everything at once. Pick one practice from the list above that addresses the failure mode you are sitting in, and apply it to the next feature you build.

The $30 Hermes Stack That Makes Claude Max Look Like a Ripoff

Dan Cucolea — Tue, 07 Apr 2026 13:32:00 GMT

I was paying $200 for Claude Max and still hitting limits mid-project. I’d open Hermes to write some code, summarize an article or set some reminders for later use. It was fast and way better than OpenClaw, but something was keeping me from going all-in.

Then I spent the full week to figure out how to configure it properly.

Now Hermes remembers everything across sessions, manages my projects, syncs files instantly across devices, and handles complex workflows while I’m asleep. It went from a tool I use to a teammate that works independently.

Here’s exactly how to do the same.

The two AI providers worth using right now (Fire Pass vs OpenCode Go) so Hermes never chokes mid-session.
The four tools that changed how I use Hermes (GitHub CLI, Telegram gateway, Brave Search, Skills) and the workflows they make possible.
Fixing persistent memory with Honcho, replacing bloated Nextcloud with lean WebDAV, and wiring up Asana so your work doesn’t disappear.
The 30-day plan to full turbo mode, plus why you should never expose port 8642.

You’re Running Hermes Agent in First Gear

Open your Hermes setup right now and count how many of these you have configured. A fast AI provider with unlimited or high-limit access. Cross-session memory that works reliably. Integration with your project management tool. File sync that doesn’t make you wait 30 seconds. Skills that automate repetitive workflows. Remote access from your phone.

Most people have one or two. Maybe three if they’re motivated.

The setup looks intimidating, so people skip most of it. I did the same thing for weeks.

But each of these capabilities compounds on the others. Fast AI lets you iterate. Memory means you stop repeating yourself every session. Project integration means tasks get tracked automatically. File sync means your notes show up everywhere. Skills mean the boring stuff runs without you.

Once all of them are running together, the experience changes. Hermes stops feeling like a chatbot you type into and starts feeling like someone who knows your work, remembers your preferences, and handles things without being asked twice.

That shift is what the rest of this article builds toward.

Picking the Right AI Provider: Fire Pass Vs OpenCode Go

Hermes is only as good as the AI powering it. Pick the wrong provider and you’ll hit rate limits at the worst moment or watch tokens drain your budget faster than expected.

I tested several. Two stood out.

Fireworks Fire Pass costs $7 per week (about $30/month), first week free. You get unlimited access to Kimi K2.5 Turbo at roughly 393 tokens per second. That’s one of the fastest inference speeds available anywhere right now.

The catch: it’s Kimi K2.5 only. No model variety, no backup if Kimi goes down. But for coding, reasoning, and long documents, Kimi handles all of it well. And at 393 t/s, even long outputs feel instant.

Kimi K2.5 Turbo runs on a 1 trillion parameter MoE architecture with 32 billion active per forward pass. The “Turbo” label means the same weights served on optimized infrastructure, with a 256k context window and strong agentic tool use. When I’m in the middle of a long coding session and need fast iteration, this is what I reach for.

OpenCode Go costs $5 the first month, then $10. Instead of one fast model, you get six with generous request limits: MiniMax M2.7, MiniMax M2.5, MiMo-V2-Omni, GLM-5, Kimi K2.5, and MiMo-V2-Pro.

MiniMax M2.7 is the standout. Released March 2026, it scores 50 on the Artificial Analysis Intelligence Index, matching GLM-5 at roughly one-third the cost.

My recommendation: start with Fire Pass if you want simplicity and speed. Switch to OpenCode Go when you find yourself wanting to test alternatives or when you’re doing bulk work where MiniMax M2.7’s cost advantage matters.

Both work with Hermes out of the box. Set your API key in ~/.hermes/.env and you’re running.

Fixing Hermes’ Forgetfulness with Persistent Cross-Session Memory

Hermes has built-in memory, but it’s session-scoped by default. Close the terminal, lose the context. Fine for one-off tasks. Useless for ongoing work.

I noticed this on day three. I’d spend twenty minutes bringing Hermes up to speed on a project we’d discussed the day before. The conversations were gone. Every morning felt like onboarding a new hire.

Honcho fixed this. It’s an open-source memory library that gives Hermes persistent cross-session context. The team describes it as a “peer paradigm” where both you and the agent build a relationship over time. In practice, it stores facts about you, your projects, your preferences. Every new session starts with that context already loaded. No re-explaining your stack, your location, or your goals.

Setting it up locally took me longer than I expected. Docker Compose, deriver logs, token limit errors. I spent hours watching the deriver fail with “Observation content exceeds maximum token limit of 8192” when synthesizing my imported memory files. The raw search worked fine, but the AI-synthesized peer cards kept failing on large imports.

Here’s the honest breakdown. The raw memory retrieval is solid. Honcho stores entries and retrieves them instantly. The AI synthesis layer, the part that builds distilled user profiles, chokes on large imports. Use raw search for now.

On April 3, 2026, Hermes introduced the Pluggable Memory Provider Interface. Memory is now an extensible plugin system where third-party backends register through a provider ABC. This changes things.

The providers available today:

Honcho, the reference implementation with AI-native cross-session modeling
Hindsight (vectorize.io), a purpose-built plugin hitting 91.4% accuracy on LongMemEval
Mem0, widely adopted but cloud-focused
Letta (formerly MemGPT), a full agent platform with tiered memory
Zep/Graphiti, temporal knowledge graphs
OpenViking, Holographic, RetainDB, ByteRover, community alternatives

I’m exploring building a custom solution. Full local control, token-efficient storage, direct Hermes integration without middleware, and a deriver that doesn’t choke on context limits. The pluggable interface makes this possible now.

For immediate setup: run hermes memory setup and select Honcho. It works well enough for raw search. Expect synthesis to improve, or plan to swap providers as the ecosystem matures.

How to Run Your Entire Workflow from a Single Interface

Once you have fast AI and working memory, the next layer is the tooling that makes Hermes useful beyond chat.

GitHub CLI was the first thing I set up. Install gh, authenticate once, and you have commits, pushes, and PR management without leaving the terminal. This became the foundation for everything else.

Telegram integration is what made the whole setup click for me. Run hermes gateway telegram setup once and you have a direct line to your agent from anywhere. I use this constantly. Someone messages me about a website change while I’m out. I send a Telegram command to Hermes. It pulls the repo, edits the file, commits with “[via Telegram]” in the message, pushes. Vercel auto-deploys. I never opened a laptop.

That workflow alone justified the entire Hermes setup.

Brave Search is the research tool I reach for most. Built into Hermes via MCP, it finds emails, hiring managers, technical documentation, competitive intelligence. The queries I run regularly: "company" "hiring manager" email, "competitor" pricing 2026, "technology" benchmark performance. For contract work research, nothing comes close.

Skills are reusable instruction packages that teach your agent to perform specific tasks consistently. I have one for deploying to production, another for writing article briefs, another for analyzing codebases. Install with npx skills add from sources like Vercel Labs or LobeHub.

One thing to watch out for: the skills CLI doesn’t fully recognize Hermes yet. It defaults to .openclaw/ directories. Import manually to ~/.hermes/skills/ instead. And skills have full system access, so only install from sources you trust.

OpenCode for Root Access

Sometimes Hermes struggles with system-level operations. Editing system files, installing packages that need root permissions. The sandboxing gets in the way.

I keep OpenCode running on my VPS root for these situations. Quick system tweak, I use OpenCode. Complex multi-step workflow, I switch to Hermes. Two tools, each in the environment where it performs best.

What workflow automation saves you the most time? Drop a comment. I’m collecting the best setups.

The Simple CLI Setup for Tracking Work Across Sessions

All this capability falls apart if you lose track of what needs doing. I use Asana because it integrates cleanly and the free tier handles personal projects.

The setup: Python asana package in a dedicated virtual environment, CLI wrapper at /usr/local/bin/asana-api, token in ~/.asana_env sourced by .bashrc. My main project is called “Hermes project” and Hermes remembers the GID, auto-linking tasks to conversations.

During a session I’ll say “create an Asana task to research Hindsight memory provider.” Hermes creates it, tags it with the session ID, and I pick it up later from anywhere. The task lives in one place regardless of which device or gateway I used to create it.

Linear works well too if you prefer GraphQL. Notion databases are popular. The tool matters less than the habit: one source of truth your agent reads and writes to.

How to Fix Slow File Sync Between Devices

If you’re syncing Obsidian with Nextcloud right now, you already know the pain. Thirty seconds to sync two hundred small files. File locking issues during rapid changes. A database-backed architecture adding overhead you never asked for.

I ran Nextcloud for months. It worked. But every sync felt like watching paint dry.

The fix: WebDAV server + Filebrowser + Obsidian LiveSync.

WebDAV is purpose-built for file sync. No database layer, direct file operations, lightweight protocol. Filebrowser adds a web UI for browser access when you need it. Together they’re roughly ten times faster than Nextcloud for the same job.

services:
  webdav:
    image: bytemark/webdav
    volumes:
      - ./data:/var/lib/dav
    environment:
      - AUTH_TYPE=Basic
      - USERNAME=youruser
      - PASSWORD=yourpass
    ports:
      - "8080:80"

  filebrowser:
    image: filebrowser/filebrowser
    volumes:
      - ./data:/srv
      - ./filebrowser.db:/database.db
    ports:
      - "8081:80"

In Obsidian, install the Remotely Save plugin, point it at your WebDAV endpoint, set a 30-second sync interval. Done. Files created by Hermes appear instantly in your notes. Briefs, articles, research, everything syncs across devices without the Nextcloud overhead.

If you’re running Nextcloud for Obsidian sync only, this one change saves you hours of waiting per month.

Securing Your Hermes API: Authentication and Safeguards

Hermes runs as an API server on port 8642. Other tools connect to it. IDE extensions in VS Code, Zed, JetBrains. Custom tools that send tasks. Multi-agent systems where one Hermes serves multiple clients. Webhooks from external services.

The v0.7.0 ACP (Agent Client Protocol) integration means editors register their own MCP servers and Hermes automatically discovers them as tools. Full slash command support in your IDE, powered by your configured Hermes instance.

This sounds great until you think about what you’re exposing.

Hermes has full system access. Terminal, file system, API keys, everything. Exposing port 8642 exposes all of that. Any client connecting executes arbitrary commands. And there’s no built-in authentication in the base setup.

I learned this the hard way when I briefly opened the port to test an integration from my phone. It worked, but I realized anyone on my network had the same access I did. Shut it down within the hour.

If you need to expose Hermes, put a reverse proxy in front of it. Cloudflare Access or Authelia work well. Restrict to local network when possible. Use token-based auth with short expiry. Enable approval mode so every action requires manual confirmation. Never expose raw port 8642 to the internet.

The safer approach: use Telegram or Discord gateways for remote access. They have built-in platform authentication. Run separate Hermes instances per project with limited scopes. Use Docker sandbox for anything untrusted.

The API mode is the most capable part of the Hermes stack, and the easiest way to accidentally give the internet shell access to your systems.

The 30-Day Hermes Setup Plan

You don’t need to do all of this in one weekend. Here’s the order that worked for me.

Week 1 is the foundation. Pick your provider, Fire Pass for unlimited Kimi or OpenCode Go for variety. Set up your API keys in ~/.hermes/.env. Configure GitHub CLI with gh auth login. Run a few test conversations to make sure everything connects.

Week 2 is memory. Set up Honcho locally with Docker Compose. Run hermes memory setup and select Honcho. Verify that raw memory search returns results. Import existing context from past conversations. By the end of this week, Hermes should remember who you are when you open a new session.

Week 3 is tooling. Configure the Telegram gateway. Install 3-5 essential skills, manually importing to ~/.hermes/skills/. Set up your Asana CLI integration (or Linear, or Notion). Test Brave Search with a few research queries. This is the week where Hermes starts feeling useful beyond basic chat.

Week 4 is sync. Deploy the WebDAV + Filebrowser stack. Configure Obsidian’s Remotely Save plugin. Migrate your notes from whatever slow setup you’re running now. Verify that files sync instantly across all your devices.

After month one, experiment with API mode locally. Explore alternative memory providers. Build internal tools that call Hermes, with proper authentication in front of everything.

Each week builds on the last. By the end you’ll have something that remembers everything, works while you sleep, and syncs across every device you own.

That’s the setup. Everything before it is first gear.

What’s the first capability you’re adding? Reply and tell me. I read every response.

Hermes Is the AI Agent OpenClaw Promised to Be

Dan Cucolea — Tue, 31 Mar 2026 13:58:03 GMT

The first time my agent forgot who I was, I blamed the config. The twelfth time, I blamed the architecture.

I’d been running OpenClaw for weeks now. Building workflows, storing preferences, training my agent to work the way I work. And every few weeks, something would slip. A project decision I’d explained twice already. A formatting rule I’d set three conversations ago. Context that should have been obvious, gone.

A week after I stopped blaming myself, I installed Hermes. A month later, going back never crossed my mind.

This is the migration guide I wish someone had written for me.

In this article:

Why I Moved
The Tradeoff
Before You Start
The Migration
The Gateway
Your First Week
The Honcho Difference
First Bumps
The Bottom Line

Why I Moved

OpenClaw carried me for a few weeks. I built workflows, connected it to Nextcloud, ran it alongside Claude Cowork, and wrote about the whole setup on this newsletter. The tool works.

But the longer I used it, the more I noticed where it fought me.

Instructions. I’d write a detailed prompt telling my agent exactly how to handle a task. OpenClaw would get 70% of it right and improvise the rest. I’d rewrite. It’d still miss the same parts. After enough rounds of this, I realized the problem wasn’t my prompting. The framework itself was cutting corners on how it passed instructions to the model.

Hermes fixed this on day one. The same prompts that produced mediocre results in OpenClaw produced exactly what I asked for in Hermes. It does use more tokens per interaction, so the API bill goes up. But the outputs land closer to what you asked for, every time.

Memory. I wrote an entire article about OpenClaw’s memory problem. Lossless Claw patched it. The patch worked, mostly. But it was still a patch on a system that wasn’t designed for persistent memory from the ground up.

Security. In January 2026, a published security audit reported 512 vulnerabilities in OpenClaw, including one allowing remote code execution through a single malicious link. Researchers at Cisco found 335 malicious skills on ClawHub. I’d been running this on my server with access to my files, API keys, and personal documents.

Reading those reports accelerated my timeline. I was already leaning toward Hermes.

The Tradeoff

Hermes is better for me. It might not be better for you. Here’s both sides.

What got better:

Instruction following. Hermes reads your full prompt and executes it. The token cost is higher because it runs more tools, creates skills to standardize processes and basically processes more of your instructions instead of skipping them. It likes to be super thorough.

Setup. Installing Hermes took less time than any OpenClaw update I’ve done. The setup wizard walks you through everything, detects your existing OpenClaw install, and offers to bring your data over automatically.

Memory. Honcho runs as a separate memory layer. You can just sign up and get $100 for it. Your conversations persist across restarts, model switches, and gateway reboots. I am playing with the local install to use my own models and keep my memory safe and hosted locally.

Self-improving skills. When Hermes solves a hard problem for you, it writes a reusable skill document. Next time a similar task comes up, it’s faster and will actually know what to do. OpenClaw never did this.

What got worse:

Model providers. OpenClaw works with a massive list of providers. Hermes doesn’t. If you depend on a specific model through a specific provider, check compatibility before you commit.

Token usage. Your API bill will go up. Mine increased by roughly 20%. The outputs are better, so the cost per useful result is about the same. But the raw number on your invoice will be higher. This is a price I am willing to pay just for the model to actually listen to my instructions.

Ecosystem. OpenClaw has ClawHub with thousands of community skills. Hermes has a smaller library. The self-improving skills system offsets this over time, but on day one you’ll have fewer pre-built options.

Before You Start

Two things to do before you install Hermes.

Back up your OpenClaw config. Copy your ~/.openclaw/ directory somewhere safe. Your .env files, your skill definitions, your SOUL.md. Hermes will import most of this automatically, but having a backup costs you thirty seconds and saves you from a bad day.

cp -r ~/.openclaw/ ~/openclaw-backup/

Check your model providers. Open your OpenClaw .env file and look at which providers you’re using. Visit the Hermes docs and confirm they’re supported. If your primary model works, you’re good. If it doesn’t, figure out your alternative before you start.

Hermes handles everything else.

Migrating Is Straightforward

Install Hermes on your server. The first time you run hermes setup, it detects your OpenClaw installation and asks if you want to import your data.

Say yes.

The setup wizard pulls in your memories, your SOUL.md (your agent’s personality and system prompt) and your preferred channels (I use Telegram).

What you’ll need to redo by hand:

Any API keys or secrets that weren’t on the allowlist get skipped. The setup tells you exactly which ones it skipped and why. Add them to ~/.hermes/.env manually.

If you were using ClawHub marketplace skills, those don’t transfer. Recreate the ones you need in the Hermes skill format, or check if the Hermes community has equivalents.

The entire process took me about fifteen minutes. Most of it was copying over API keys and recreating some skills.

Hermes Gateway

Hermes centralizes your gateway config in one file: ~/.hermes/config.yaml.

Run Hermes with hermes and ask it to configure the messaging channels for you, or just do it manually.

If you were on Telegram with OpenClaw, the setup looks like this:

gateway:
  platform: telegram
  telegram:
    bot_token: ${TELEGRAM_BOT_TOKEN}
  port: 8082

Add your bot token to ~/.hermes/.env, point the config at it, and start the gateway. Open Telegram and send your agent a message. If it responds, you’re live.

For Discord, Slack, WhatsApp, or Signal, the pattern is the same. One platform block in the config file, one token in the env file. The Hermes docs list every supported platform with copy-paste examples.

I switched my Telegram bot to Hermes and sent it a test message within two minutes of finishing the migration. It responded with context from my last OpenClaw conversation. The memory import worked.

Your First Week

The first thing you’ll notice is that your agent listens better.

I gave Hermes a content brief with twelve specific formatting rules. It followed all twelve. The same brief in OpenClaw would produce something that hit eight or nine, with two or three “creative interpretations” I didn’t ask for.

The second thing you’ll notice is the token counter. My daily usage went up noticeably. Hermes processes more of the conversation context on every turn, and it doesn’t shy away from calling tools, which is why the instruction following is better. You’re paying for the model to read more and skip less.

In a single conversation Hermes had created two skill documents on its own. One for how I like my research summaries formatted. Another for the file naming convention I use in my Nextcloud docs folder. I didn’t ask it to learn these things. It picked them up from our conversations and wrote reusable procedures.

If you built the Nextcloud bridge from my earlier article, it works with Hermes too. Point Hermes at the same synced folder and your shared brain carries over. Nothing changes on the file sync side.

Honcho Makes a Difference

The real memory system in Hermes is called Honcho, and it’s a 3rd party tool.

It stores your conversations, builds a profile of who you are and how you work, and serves that context back to the agent at the start of every interaction.

I chanted with Hermes using the TUI and then asked it something on Telegram. It picked up exactly where we left off. The context from Friday’s conversation was also there. The decisions we made on Monday were referenced correctly.

I tested the same scenario in OpenClaw before I migrated. The agent remembered some fragments through vector search. It missed the thread connecting them. I spent ten minutes re-explaining what we’d already decided.

According to Honcho’s published pricing, it costs $2 per million tokens ingested. Every context retrieval call is free with no limits. Based on my usage patterns, it adds a few dollars a month to my total cost. For the amount of time it saves me re-explaining context, it’s the cheapest upgrade in my entire stack.

Nevertheless, I am a die-hard fan of self hosting and you can actually self host Honcho. I wanted to give it a try first before committing but now I am sold.

Drop a comment if you’ve already made the switch. I want to hear what your first week looked like.

First Bumps

The migration went smoothly, but the first few days had a couple of bumps. Here’s what I ran into and how I fixed it.

Skills not loading. One of my imported skills had a formatting issue in its SKILL.md file. Hermes skipped it silently. I checked ~/.hermes/skills/openclaw-imports/, opened each file, and found a broken YAML header. Fixed the formatting, restarted, done.

Token spikes. My first full day of usage ran higher than my OpenClaw average. By day three it settled to about 20% above baseline. The spike on day one was Honcho ingesting my conversation history and building the initial context graph.

Missing env variables. I forgot to move one API key from my backup into ~/.hermes/.env. The error message told me exactly which key was missing and which skill needed it. Added the key, restarted, fixed.

For anything else, the same pattern from my Nextcloud article applies. Copy the error message, paste it to your agent, and let it diagnose the problem. Hermes is better at debugging itself than OpenClaw because it retains the context of what went wrong and what was already tried.

The Bottom Line

If you’re building long-term workflows where context matters, where your agent needs to remember what you decided last week and why, migrate now. Hermes was built for this from the ground up, and the migration wizard makes the switch painless.

If you’re running simple one-off automations and OpenClaw handles them fine, stay put. There’s no reason to move if your current setup does what you need.

For everyone in between, it takes fifteen minutes and a slightly higher API bill. You get an agent that follows your instructions, remembers your preferences, and gets better at your specific workflows every day it runs.

I moved a week ago. The only thing I regret is not moving sooner.

Ditch Your Subscriptions and Run Open Source AI on Your Device

Dan Cucolea — Tue, 24 Mar 2026 13:35:30 GMT

Open-source AI models are beating the paid ones. A year ago that sentence would have been ridiculous. Not anymore.

Qwen 3.5 is outscoring GPT-5.2 on key benchmarks. MiniMax M2.5 is running on people’s Mac Studios at 20 words per second, trading blows with frontier models like Opus 4.5 and Gemini 3 Pro. The gap between a $20/month cloud subscription and running that same intelligence on your own hardware has never been thinner.

The models are free. The tools are ready. The part most people get stuck on is figuring out which model their specific hardware can actually handle without crawling.

I spent weeks digging through benchmarks, community reports, and real-world results across every hardware tier for two of the most relevant open-source model families. What follows is exactly what runs where, how fast, and which model deserves a spot on your machine.

In this article:

Two Families
Efficiency Tier
GPU and Mac Mini Tier
The Final Boss
The Cheat Sheet
Your Machine, Your Model
What Comes Next

Two Families

Two model families cover the entire spectrum from “runs on a phone” to “runs on a workstation” better than anything else available today.

Qwen 3.5 (by Alibaba) is the Swiss Army knife of open-source AI. Eight sizes from 0.8B to 397B parameters. Specialized variants for coding, vision, and reasoning. All Apache 2.0 licensed. Every local AI tool worth mentioning, Ollama, LM Studio, llama.cpp, Jan.ai, supports it out of the box. The latest generation dropped between February and March 2026 with a new Gated DeltaNet architecture, 262K-token context windows, and 201 languages. This is where most people should start.

MiniMax M2.5 is the ambitious one. 230 billion total parameters, but it only activates 10 billion on every response thanks to an extreme Mixture-of-Experts architecture (more on this soon). 200K native context window. The community at Unsloth compressed it from 457GB down to a 101GB file, making home deployment possible. For those with the hardware, it’s frontier-class intelligence on your own desk.

Efficiency Tier

You do not need an expensive GPU to run a language model locally.

You can use your travel laptop with integrated graphics, a base Mac Mini or your aging desktop to run a Qwen model at home.

Qwen3.5-4B (~2.5 GB at Q4 quantization) is the best quality at this size. Drafting emails, summarizing documents, light coding help, translation, private conversations that never leave your machine.

Based on community reviews, it’s coherent and helpful in ways you wouldn’t expect from a model this small. Qwen3.5-2B (~1.3 GB) is the sweet spot for CPU-only machines. Qwen3.5-0.8B (~0.5 GB) runs on anything with a CPU (like your phone).

These won’t write your PhD thesis, but they’re fast (40+ tokens per second on CPU), completely private, and the 4B punches well above its weight. Getting started takes one command:

ollama run qwen3.5:4b

Ollama downloads the model and then you’re ready to chat. Use LM Studio if you prefer a GUI or, my favorite, Jan.ai if you want something prettier.

GPU and Mac Mini Tier

No API latency. No rate limits. You hit Enter and the answer starts flowing instantly. This tier is where people have the “wait, this is running on MY computer?” moment.

The hardware range here is wide. On the lower end: an RTX 3060 12GB, an RTX 4060 Ti 16GB, an RX 7800 XT, or a Mac Mini M4 Pro with 24GB. On the upper end: an RTX 3090, an RTX 4090, or a Mac Mini M4 Pro with 48-64GB.

Apple’s unified memory works like VRAM for AI inference, so a 24GB Mac Mini sits in this tier right alongside a 24GB GPU. One rule applies across the board: the bigger the GPU and the more memory you have, the faster your tokens generate and the larger the model you fit.

Qwen3-8B (~5 GB) is a solid all-rounder that leaves tons of headroom on a 12GB card. Good for quick tasks and light conversations.

Qwen3-14B (~9 GB) is the Goldilocks model. Fits comfortably on 12-16 GB, and delivers top notch quality when you take its size into account. It’s does a great job at coding, reasoning and creative writing. If you have the memory for it, this is where I’d recommend most people start.

Qwen3.5-35B-A3B (~18.6 GB) is the model that inspired me to write this article. It has 35 billion total parameters, but only 3 billion activate on every response. This is a Mixture-of-Experts model.

MoE models are built differently. Instead of one massive brain firing every neuron, think of it as a team of specialists. Ask a coding question and the coding experts light up. Switch to creative writing and a different set activates. The result: you get 35B-level intelligence at 3B speed and memory cost. Fits on 16GB with CPU offloading.

This MoE architecture is the same idea behind MiniMax M2.5, so keep that concept in mind as we move along.

Qwen3.5-27B (~17 GB) is the dense powerhouse at the top of this tier. Built for 24GB cards and 48-64GB Macs. All 27 billion parameters fire on every response, it supports 262K context across 201 languages, and it wins on reasoning and coding benchmarks against every model at this size. With 24GB of VRAM you still have plenty of headroom left for long conversations.

Qwen3-Coder-30B-A3B also deserves a mention here as its a dedicated coding model (also MoE, 3B active), rivaling Claude Sonnet 4 on SWE-Bench.

Speed across this tier ranges from 15 to 40+ tokens per second, depending on model size and your hardware. A 64GB Mac Mini M4 Pro runs the 27B at 15-25 tok/s and the 35B-A3B even faster thanks to MoE efficiency. A 24GB GPU pushes the smaller models past 40 tok/s. For reference, average human reading speed is roughly 250 words per minute, or about 5-6 tokens per second.

Worth noting for anyone planning to run models around the clock: the Mac draws about 30W under load compared to 300W+ for a GPU rig. Over months of use, the electricity savings add up.

The Boss Level

Everything above was the warm-up. This is the final boss.

You need a Mac Studio with 128GB unified memory or a multi-GPU PC with 96GB+ RAM. The Mac Mini caps at 64GB, so it tops out at the GPU tier above.

MiniMax M2.5 takes the MoE concept to the extreme: 230 billion total parameters, 10 billion active per response. A 200K native context window that handles entire codebases, full novels, or months of transcripts in one conversation.

Mac Studio 128GB is the ideal setup. No bottleneck between GPU and CPU since it’s all one memory pool. Community benchmarks: 20-25 tok/s. PC with dual GPUs + 96GB RAM works through CPU offloading. Slower (12-25 tok/s) but functional.

The key number: 101GB. Unsloth’s 3-bit GGUF (UD-Q3_K_XL) compresses the model from 457GB to 101GB with minimal quality loss.

Start with 16K-32K context and scale up. Enable flash attention and CPU-MOE offloading.

Do all that and you’ll get frontier-class intelligence and massive context entirely on your hardware. No API costs, no data leaving your machine, no rate limits. For lawyers, researchers, or developers handling sensitive work, this is the endgame of private AI.

For developers at this tier: Qwen3-Coder-480B-A35B is the most capable open-source coding model available (that you can run at home). 480B total parameters, 35B active, 69.6% on SWE-bench Verified, comparable to Claude Sonnet. It needs 240GB+ at Q4, so a Mac Studio with 192GB or a multi-GPU server setup is the minimum. If you write code for a living and have the hardware, this is the local Copilot replacement to end all replacements.

Looking ahead: MiniMax M2.7 launched March 18 with strong coding benchmarks (56.2% SWE-Pro, 97% skill adherence across 40+ tasks), but weights are proprietary. You can’t run it locally yet. MiniMax M3 is expected to add multimodal capabilities (text, images, video). M2.5 is text-only, which is its biggest gap compared to Gemini Flash or GPT-5.4 Mini. If M3 ships open-weight, it becomes a direct competitor to those cloud-only models on home hardware.

The Cheat Sheet

Find your hardware, grab your model, go.

Your Machine, Your Model

The cheat sheet above gets you close, but VRAM estimates are estimates. Your exact hardware, OS, and background apps all matter. Reddit gives conflicting advice. YouTube benchmarks were run on different machines.

This is why I’m building the AI Hardware Checker. It’s a website where you plug in your hardware details, your GPU, your RAM, and it tells you exactly which AI model fits your setup, what settings to use, and what speed to expect.

It’s not live yet. I’m actively building it right now. And I want to build it around real hardware owned by real people.

Drop a comment with your GPU and the model that caught your eye. I’ll tell you if it runs and what settings to use.

Drop your GPU in the comments. I’ll tell you which model to run.

What Comes Next

What needed a datacenter two years ago runs on a gaming PC today. What runs on a gaming PC will run on a phone tomorrow. MoE architectures, Gated DeltaNet, aggressive quantization. The field is sprinting toward “run anywhere.”

Qwen and MiniMax are the beginning. MiniMax M2.7 is already here (API-only), M3 with multimodal is on the horizon. The walls between cloud AI and local AI are dissolving.

The best time to start was last year. The second best time is right now.

If you’re running local models alongside cloud tools, I wrote a full guide on connecting them through a shared Nextcloud bridge. Worth a read if you want both worlds.

OpenClaw vs Claude Cowork vs Perplexity Computer - Which AI Agent Actually Fits Your Life

Dan Cucolea — Tue, 17 Mar 2026 14:43:11 GMT

In the next 2 weeks you have a rare opportunity.

Both Anthropic and OpenAI are running 2x usage limits on their paid plans right now. Claude Pro subscribers get double the capacity across Claude AI, Cowork, and Claude Code. ChatGPT Plus subscribers get the same bump across ChatGPT and Codex, which is awesome since you can use your ChatGPT Pro account in OpenClaw.

Same price, twice the output. These promos won’t last, and they’ve given me the perfect excuse to push all of these tools harder than I normally would.

And I needed that, because three weeks ago the AI agent space exploded.

In late February, the AI agent space stacked up fast. OpenClaw shipped a major security and reliability update. Days later, Anthropic launched scheduled tasks for Claude Cowork and Perplexity dropped their Computer product on the same day. Three different companies, three different visions of what an AI agent should be, all landing within the same few weeks.

I’ve been running OpenClaw on a cloud server for months now. Claude Cowork is my daily driver for local work. I’ve spent a week with OpenAI’s Codex after it launched its Windows app. And I’ve done a ton of research on Perplexity Computer, watching head-to-head comparisons, reading reviews, and studying how it stacks up against the tools I use daily.

Based on all of that, I wrote this so you can make an informed decision and pick the right tool for your specific use case.

In this article:

The Lineup
Where It Runs
Head to Head
What It Costs
Who Sees Your Data
Pick Yours
Where This Is Going
One More: Codex

The Lineup

Here’s the 30-second version of each tool. They look similar on paper but they’re built on fundamentally different philosophies.

OpenClaw is a self-hosted, always-on AI agent. Open-source, 319,000+ GitHub stars, recently “acquired“ by OpenAI. You install it on a VPS or a Mac Mini, and it runs 24/7. You talk to it over Telegram, WhatsApp, Discord, or whatever messaging platform you prefer. Think of it as a remote employee who never clocks out. You bring your own API keys, your own models, your own rules.

Claude Cowork is a local co-pilot that lives inside Claude Desktop. $20/month on any paid Claude plan. Best UI of the three by a wide margin. The recently added scheduled tasks feature turned it into a lightweight automation tool, letting you set up daily briefings, weekly reports, and recurring workflows. The catch: it only runs while your computer is awake and the app is open.

Perplexity Computer is a cloud-based multi-model orchestrator. It takes your task, breaks it into subtasks, and dispatches them across 19 specialized AI models: Claude Opus for reasoning, Gemini for research, GPT-5.4 for long-context work, Grok for quick tasks. It was locked behind the $200/month Max plan at launch, but it’s now available to Pro users ($20/month) through usage credits. Over 400 app integrations including Gmail, Notion, Slack, and Salesforce.

Where It Runs

Every comparison I’ve read focuses on features, pricing tiers, model benchmarks. None of those tell you as much as one thing: where the agent runs.

This is the fork in the road. Security, reliability, cost structure, and what the tool does for you all flow from this single architectural decision.

On your machine. That’s Claude Cowork. Easiest to start. Most polished experience. You install the desktop app, point it at a folder, and you’re working. But it dies when your laptop sleeps. Scheduled tasks only fire while the app is open. If you close your lid at 6 PM, your “daily overnight report” never runs. Great for working-hours automation. Terrible for overnight agent dreams.

On your server. That’s OpenClaw. True autonomy. It runs while you sleep, eat, and go on vacation. I’ve had mine running on a Hetzner VPS for months and it processes tasks at 3 AM without me lifting a finger. But you’re now a sysadmin. Updates break things. Security is your responsibility. In independent testing it scored a 4 out of 10 for ease of setup. That number feels generous on a bad day.

In someone else’s cloud. That’s Perplexity Computer. Always on, zero maintenance, no servers to manage. But you’re paying a premium for that convenience, and your data flows through Perplexity’s infrastructure. With Pro credits now available, the entry barrier dropped significantly. Heavy users will still feel the cost.

I chose to run OpenClaw and Cowork together because I need both modes. If I had to pick only one, the answer depends entirely on whether I need an agent that works while I don’t. If you need something running overnight, it’s OpenClaw or Perplexity. If your AI work happens during business hours, Cowork is more than enough.

Head to Head

Enough architecture. Here’s how they perform across the three categories that matter most.

Research and Reports

Perplexity Computer wins here, and it’s not particularly close. The multi-model orchestration means it cross-references sources across different AI systems, and every output includes clickable citations with links in the footer. In one head-to-head test I studied, both tools were asked to research AI invoice automation tools and compile a one-page PDF comparison. Perplexity came back with precise pricing data, clean formatting, and source URLs you could verify in seconds.

Cowork produced a solid report but broke the one-page constraint, got a team plan price wrong, and listed sources by name without linking them. Still usable, about 90% as good, but that missing 10% is the part that matters when you’re sending deliverables to a client.

OpenClaw handles research, but it’s manual. You prompt, it fetches, you verify. There’s no orchestration layer coordinating multiple models behind the scenes. It works. It’s slower and requires more hand-holding.

Verdict: If research is your main job, Perplexity Computer earns its price tag. For everyone else, Cowork is good enough.

Working with Your Own Files

Cowork dominates this category. It reads your local filesystem directly. Point it at a folder and it references, reviews, or builds on anything inside it. No uploads, no API overhead, no friction.

I tested Cowork with messy client intake notes: 10 inconsistent text files with different formats, missing fields, and contradictory information. Cowork parsed them all, identified the real business bottleneck for each client, and output a clean structured spreadsheet. In the same test run by a reviewer, Perplexity handled the task but required manual file uploads for each one. It also made a weaker recommendation, suggesting ChatGPT for a client whose real problem was a bad website.

OpenClaw can access server files natively, and if you’ve built the Nextcloud bridge I wrote about previously, it can reach anything your local AI can reach too. Different path to the same destination.

Verdict: If your work lives in local files, Cowork. If it lives on a server, OpenClaw. If it lives in cloud apps like Gmail, Notion, or Google Sheets, Perplexity Computer’s 400+ integrations give it the edge.

Automation and Scheduled Tasks

This is where the “where does it run” question hits hardest.

OpenClaw was built for this. Heartbeats, cron jobs, always-on triggers, multi-platform messaging. It runs whether you’re awake or not. I have mine sending me a Telegram summary of my project pipeline every morning at 9 AM. I don’t touch anything. It shows up.

Cowork now has scheduled tasks and they work well when they work. Daily, weekly, hourly, on-demand. The UI for managing them is cleaner than anything OpenClaw offers. But the limitation is real: they only execute while your computer is on and the app is open. If your laptop is closed, the task simply doesn’t run.

Perplexity Computer can handle multi-hour and even multi-day workflows autonomously in the cloud. For long-running research or complex multi-step tasks, the results are strong. But you’re paying cloud prices for that always-on capability.

Verdict: True 24/7 automation means OpenClaw or Perplexity. For business-hours automation, Cowork handles that well.

What It Costs

Sticker prices lie. Here’s what each tool costs when you’re using it daily.

Claude Cowork: $20/month. Simplest math of the bunch. One subscription, everything included. No API keys, no hosting bills, no infrastructure to maintain. This is the “I want it to work, no setup” option. And right now, Anthropic is running 2x usage limits on all paid plans. Double the Cowork capacity for the same $20. If you’ve been waiting to try it, this is the window.

OpenClaw: $0 software + $6-50/month real cost. The software is free and open-source. But you need somewhere to run it. A VPS costs $6-24/month depending on specs. API calls for models like Opus, Gemini Pro, or GPT-5.4 add another $10-200/month depending on how heavily you use it. Light users land under $20 total. Power users blow past $200 easily.

The hidden cost is your time. Setup, maintenance, debugging when an update breaks something. OpenClaw is free in dollars but expensive in hours. I spent an entire evening once debugging a permissions conflict between OpenClaw and Nextcloud on the same server. That evening had a price even if my credit card didn’t see it.

Perplexity Computer: $20/month (Pro with credits) or $200/month (Max). The Pro credits path is new and it changes the equation. You get access to the full multi-model orchestrator without the $200 commitment. But heavy workflows eat through credits fast. Max at $200/month is aimed at professionals whose time is worth more than the subscription: consultants, researchers, analysts working on problems where a single good report saves hours of manual work.

The value verdict. Cowork wins on pure value for most people. OpenClaw wins if you already have a VPS and enjoy tinkering. Perplexity Computer’s Pro tier makes it worth trying, but Max is only justified if it saves you measurable hours every week. And with both Claude and Codex running 2x promos simultaneously, mid-March 2026 is the cheapest stress-test window you’re going to get. Take advantage before it ends.

Who Sees Your Data

This is the part that nobody wants to talk about but everybody should.

OpenClaw has full system access by design. It can read, write, and execute anything on the host machine. In independent testing it scored a 3 out of 10 on security. The low score comes from the architecture itself.

The tool works precisely because it’s unconstrained. But if you misconfigure it, everything on that machine is exposed. Your business plans, client files, API keys, all accessible.

Self-hosting means you own the risk and the control.

This is why I run OpenClaw behind my own server with a Nextcloud layer on top. Full control over every file, every model, every connection. But I wouldn’t recommend that setup to someone who isn’t comfortable managing a VPS and thinking about access control lists.

Claude Cowork is sandboxed to your working folder. It scored a 9 out of 10 on security in the same evaluation. Anthropic handles the model infrastructure, you handle your files. It’s the safest option out of the box by a wide margin. If security keeps you up at night, this is your tool.

Perplexity Computer is cloud-based with 400+ integrations. Your data flows through Perplexity’s infrastructure and gets routed across multiple model providers. If you trust them, great. If you’ve built your workflow around data sovereignty and self-hosting, this is going to feel uncomfortable.

Pick Yours

Find yourself in 10 seconds.

Choose Claude Cowork if:

You’re non-technical or want zero setup friction
You already pay for Claude Pro, Max, or Team
Your work is mostly local files, writing, and brainstorming
You want scheduled tasks that run during working hours
Budget matters and $20/month all-in sounds right

Choose OpenClaw if:

You want a 24/7 agent that works while you sleep
You’re comfortable with a VPS and basic server management
You need mobile access via Telegram or WhatsApp
You want full control over which models you use, where your data lives, and how everything connects
You like open-source and building your own stack

Choose Perplexity Computer if:

Your work is research-heavy and citation quality matters
You need multi-model orchestration across providers
Your workflow already lives in cloud apps like Gmail, Notion, Sheets, or Slack
You want autonomous multi-day task execution without managing infrastructure
You’re a Pro user willing to try it with credits, or a professional where $200/month pays for itself in saved time

Use more than one if:

You have different modes of work. Deep focus, always-on automation, and heavy research are three different jobs. These tools aren’t mutually exclusive. I run OpenClaw on my VPS for overnight tasks, Cowork locally for writing and brainstorming, and bridge them through Nextcloud so both AIs share the same files. Different tools for different jobs, one shared brain.

Which combo are you running? Drop a comment, I read every one.

Where This Is Going

Three major platforms shipped competing agent features in the same few weeks. All of them converging at once tells you where the industry is heading.

The “build a SaaS wrapper” era is ending. Scheduled email briefings, automated research reports, CRM workflows, client intake processing. These tools do all of that out of the box now. Dozens of startups built businesses around features included in a $20/month subscription.

The surviving play is learning which agent to deploy for which task, how to connect them, and how to make them share context across platforms. The people who figure out how to wire these tools together will have the real edge.

Pick the right combination of agents, matched to how you work, and you’ll move faster than anyone stuck choosing sides.

One More: Codex

I’ve only been using Codex for a week, so it’s not in the main comparison. But it deserves a mention because it’s solving a different problem entirely.

Codex is OpenAI’s cloud-based coding agent, powered by codex-1, a version of o3 optimized specifically for software engineering. It comes in three flavors. Codex Web is the autonomous cloud version: you give it a task, it spins up a sandboxed environment, works for 1 to 30 minutes, and comes back with a pull request. You can fire off multiple tasks in parallel.

Codex Desktop launched on Windows recently, which is how I’ve been running it, as a native app on my machine alongside Claude Desktop. Codex CLI is the open-source command-line version, similar in spirit to Claude Code.

Codex stays in one lane: software engineering. Writing code, fixing bugs, answering codebase questions, and proposing pull requests. Where the main three tools try to be general-purpose assistants, orchestrators, or always-on agents, Codex focuses on code and nothing else.

It’s included with ChatGPT Plus at $20/month with usage limits. Pro at $200/month gets 6x the capacity.

And right now, OpenAI is running 2x usage limits on Plus, so you get double the Codex tasks for the same $20. Pair that with Anthropic’s own 2x promo on Claude, and mid-March 2026 is the best window to trial both ecosystems side by side.

My early impressions after a week on the Windows app: the cloud execution model is the standout feature. Fire off a task and go do something else. No terminal babysitting. I kicked off three bug fixes simultaneously and reviewed them all when they came back.

The sandboxed environment means it can’t break your local setup, which is a relief compared to OpenClaw’s “full access to everything” philosophy. And it cites terminal logs and test outputs as evidence, so you can trace exactly what it did and why.

But it’s early days. I haven’t stress-tested it on complex multi-file refactors yet, and I don’t know how it handles edge cases in large codebases. For developers, it fills the same focused coding role in your stack. For non-developers, it won’t add much.

I’ll write a full breakdown once I’ve spent more time with it. For now: if you’re already paying for ChatGPT Plus, you have access. Go try it while the 2x limits last.

Forgetting to Forget - How Infinite Memory Reinvents OpenClaw

Dan Cucolea — Tue, 10 Mar 2026 14:57:07 GMT

I’ve been running OpenClaw for a few weeks now and got familiar with its pros and cons. One thing I love about it is that it saves every conversation and, if configured correctly, it can search through all past sessions.

On paper, the memory system works. In practice, it has gaps.

I’d reference a decision from two weeks ago and the agent would pick it up fine. Then I’d ask about something equally important from the same week and get a random response.

The conversations were there, stored and searchable, but the retrieval was inconsistent. Important context slipped through the cracks, not every time, but often enough that I stopped trusting it to remember the things that mattered.

After long workflow runs where subagents coordinated multi-step tasks, the problem got worse. The agent would lose track of what happened mid-chain, missing details that should have been obvious given the work it just completed.

I found myself re-explaining decisions, re-stating preferences, and mentally tracking which parts of our shared history the agent could actually access versus which parts had quietly fallen out of reach.

OpenClaw v2026.3.7 fixes this.

The update introduces a pluggable context engine architecture and the lossless-claw plugin, making it possible for the first time to retain absolutely everything across days, weeks, months, or years. And no, this is not a premium feature locked behind a paywall, after all OpenClaw is, well, Open Sourced.

I really believe this is the beginning of genuinely intelligent agents available to anyone willing to put in the work and self-host them.

Here’s my take on how to set this up for your OpenClaw and what it might mean in the long term.

No More Starting Over

The system no longer forgets who I am the moment I close the window. Every command, every conversation, every preference builds uninterrupted continuity. I pick up exactly where I left off the night before.

Here’s what a typical workflow looks like now. I tell my assistant:

Follow up on yesterday's discussion and start drafting an email campaign. Keep my usual tone and the branding guidelines we cemented last week.

The assistant already knows my “usual tone.” It’s been watching me work for a few days (since the update came in). The branding guidelines I established are preserved, searchable, and actively informing every new output.

The old setup forced me into a cycle of pasting documents or pulling info from my Notion DB. I also found myself searching through the /memory folder for a past convo and pasting that inside my Telegram chat. That was really a massive time waster.

Now with this upgrade I won’t have to do all that. Yeah, it works for massive conversations, but I don’t want to save every little, unimportant thing, but more on that later.

The End of the Context Tax

Every new AI session used to demand a toll. Re-establish who I am. Re-explain the project. Re-state my conventions. This “context tax” consumed time and mental energy better spent on actual work.

Sure, you can just update your MEMORY.md and AGENTS.md, even the IDENTITY.md, but you shouldn’t pollute these super important files with info you need to fetch on demand.

Think of a developer re-explaining their tech stack loses five minutes per session. Over a quarter, those minutes add up to hours burned on orientation instead of output.

Or writers restating brand voice, marketers re-uploading style guides, project managers re-establishing timelines. Everyone pays the context tax, nobody benefits.

Infinite memory removes this friction entirely. The entire history becomes the implicit foundation for every new request, which let’s you jump directly into substantive work.

The productivity gains are measurable. Intelligence requires context and memory to function meaningfully. When the assistant retains everything, outputs become exponentially more accurate and relevant.

Why Previous Memory Systems Fell Short

Older systems relied on basic vector searches to retrieve relevant conversation fragments. When I asked a question, the system computed an embedding, searched a vector database for similar embeddings, and retrieved matching fragments. When it wanted to.

The problem: vector similarity is a poor proxy for actual relevance.

A search for “authentication” might return discussions about password hashing from six months ago, even though the current question is about OAuth implementation in a completely different project. The context window fills up with marginally relevant fragments, causing the model to hallucinate or lose track of the conversation thread.

And that’s how I involuntary become sort of a memory manager. I pruned chats, started fresh sessions, and developed elaborate “starter prompts” pasted at the beginning of every session to reconstruct context the system should have retained on its own.

None of these workarounds addressed the core problem. Vector retrieval alone doesn’t capture the nuanced thread of a long-term working relationship.

How Lossless Claw Fixes This

Lossless Claw takes a fundamentally different approach. It replaces the AI’s “forgetting” mechanism with a permanent memory system. Every conversation is stored in a fast local SQLite database, while a background AI (Gemini 3.1 Flash-Lite in my case) silently summarizes older messages into a compressed, intelligent graph.

When you need context, the system retrieves exactly what’s relevant from this history, combining it with your recent messages, so the AI never forgets what matters, even months from now.

The Boring, Technical Architecture

Jump right ahead if you don’t care about the ins and outs of how this works.

The system keeps the most recent 20 messages completely untouched in the “fresh tail.” Whatever I’m actively discussing remains in perfect, verbatim context. This means fast responses because the model has exact quotes from the active workflow rather than summaries or approximations.

Once a message ages out of the fresh tail, a background process kicks in. Gemini 3.1 Flash-Lite silently summarizes and compresses those older messages into a dense graph structure. The SQLite database stores these nodes efficiently, preventing system bloat while maintaining instant accessibility. This compression runs automatically on a schedule, keeping history growth manageable without any manual intervention.

When I ask a complex question requiring past knowledge, the system pulls from the compressed graph up to a 150k token retrieval limit. This boundary guarantees the main model has enough room to read relevant history and generate a high-quality response without slowing down.

And the retrieval is really smart. Rather than dumping raw tokens into the context window, the system identifies the portions of history relevant to the current query and surfaces those specific sections.

Think of it as a research librarian versus a keyword search.

A keyword search returns every document mentioning a term. A librarian understands the question, knows the project, and brings the three documents that matter. The compressed graph gives the assistant that librarian’s judgment.

Setting Up Lossless Claw

No code. No terminal. No config files. The entire setup is conversational.

Tell your OpenClaw this:

Install this https://github.com/Martian-Engineering/lossless-claw and let's configure it once it is done.

One prompt. The plugin manages the SQLite lifecycle internally, covering database initialization, optimization, and maintenance without running a single command.

Integrating memory into existing agents is equally straightforward. Tell your agent:

Create a persistent memory profile for each of my active agents using the lossless-claw plugin.

Whether there are separate agents for coding, writing, or project management, each one maintains its own coherent memory growing over time. The system stays invisible, surfacing forgotten context exactly when it’s needed.

For anyone who’s already been running OpenClaw and has existing conversation history worth preserving, tell the gateway:

Import my existing conversation history into the lossless-claw memory graph and index it for retrieval.

The system ingests past sessions, compresses them through the same summarization pipeline, and makes them part of the permanent memory from day one. No history left behind.

Professional Tuning and My Settings

These are settings I use when I run OpenClaw with Gemini 3.1 Pro Preview Custom Tools.

Distillation threshold: 0.25

This low threshold triggers the summary process early, keeping the active window clean and leaving plenty of room for complex reasoning. Early distillation means the context window stays usable even during long, demanding sessions. Tell the assistant:

Set the lossless-claw distillation threshold to 0.25.

Fresh tail: 20 messages

Preserving the last 20 messages as raw text ensures the agent understands the current flow and the most recent shifts in the conversation. Summarizing too early kills nuance. The back-and-forth of a debugging session or the evolution of an idea within a single sitting needs full fidelity to stay coherent.

Retrieval limit: 150k tokens

This is the sweet spot between depth and speed. When I need to recall a decision from six months ago, the system pulls it in instantly while still leaving room for the current task.

Set my retrieval limit to 150k tokens and the fresh tail to 20 messages.

Why Flash-Lite Powers the Background

I use Gemini 3.1 Flash-Lite to handle the summarization layer. This is a secretary task that doesn’t require a high-cost reasoning model to compress facts, and Flash-Lite is built for exactly this kind of work. And it’s dirt cheap.

Team Memory and Shared Knowledge

I run OpenClaw solo most of the time, but the team angle is worth talking about.

Right now, each person’s agent works in isolation. No shared memory of decisions, conventions, or project history. A new team member has to absorb months of tribal knowledge by asking around. Every agent profile starts from zero.

Shared memory profiles fix this. The reasoning behind picking one database over another lives in the agent, not in someone’s head or a forgotten Slack thread. Onboarding becomes less about catching people up and more about pointing them at a system already loaded with context.

For agencies managing multiple clients, each client agent keeps its own partitioned memory. The tone and history for one account never bleeds into another.

And this also applied to a team of AI agents, not necessarily to your coworkers.

Security and Privacy

The first thing people ask about persistent memory is where the data lives.

On my machine. The SQLite database, the summarized graph, all of it stays local unless I configure it otherwise. Summarization runs locally too, through models I control. Nothing goes to a third-party server to become training data, if I don’t want to.

I own the history. I control the models touching it. And if I need to wipe something, i just tell my OpenClaw:

Purge all memory nodes related to [project name] from my agent profile.

The memory is permanent by default, but deletion is one prompt away.

What Infinite Memory Changes

The most useful part of this update is everything I stopped doing.

I stopped managing memory by hand. I stopped pasting old conversations into new sessions. I stopped wondering whether the agent remembered the decision we made last Tuesday when it answered with something that sounds a bit strange.

The agent feels less like a tool I operate and more like a collaborator who has been around long enough to know how I think. I did not expect this shift to happen so fast.

Tell me how are you using OpenClaw and if you had problems with its ability to remember stuff.

OpenClaw almost crossed 300,000 stars on GitHub. The project started as an experimental framework and is becoming something closer to an agent operating system, and infinite memory will play a big role in this.

OpenClaw or Claude Cowork? Here's How to Plug Both Into the Same Brain

Dan Cucolea — Tue, 03 Mar 2026 14:14:10 GMT

If you work with AI regularly, you’ve probably hit this same wall.

I’ve been running OpenClaw on a cloud server for a while. It’s autonomous, always on, and handles heavy-lift work like drafting business plans and processing research while I sleep. has been deep in Claude Cowork, using it constantly for writing, brainstorming, workflow building, and managing her systems locally on her laptop.

That’s why from is joining me today to go over how to connect two of the most used AI agent frameworks.

We both got curious about the other side.

I wanted to bring Claude Cowork into my setup and see what local AI could do for me. Mia wanted to experiment with OpenClaw and tap into the power of a cloud agent that never sleeps.

But the moment we tried to cross over, we hit the wall: our tools couldn’t see each other’s work.

OpenClaw would generate something brilliant on my server, and Mia’s local Claude session had zero awareness it existed. The reverse was just as bad. Two powerful AIs, completely siloed, with us playing messenger pigeon between them.

So instead of just swapping tools, we decided to connect them through a real, permanent bridge between cloud AI and local AI that didn’t leak our data to a third party or drain our wallets on token usage.

The SaaS Trap And Why We Avoided It

Mia was the first to flag this. She’d been trying to use Notion as a shared knowledge base and kept running into the same friction: proprietary databases, opaque storage formats, and the constant overhead of API calls every time an AI needed to “think” about her notes.
The math doesn’t work.

Every time your AI searches a Notion database or queries an AFFiNE page block, you’re burning API tokens. Scale that to a real workflow - dozens of queries per session, multiple sessions per day - and the costs pile up fast. Worse, your most private strategies and unreleased ideas are sitting on corporate servers where terms of service can change overnight.

We wanted something that stored everything as plain .md text files, synced instantly, and let both AIs read directly without any API overhead.

That something turned out to be Nextcloud.

Nextcloud: The Private Bridge

Think of Nextcloud as your own self-hosted Dropbox, except you own the server and control every byte.

It lives on a cheap VPS that you rent (Hetzner, Linode, DigitalOcean; a few dollars a month). We use a Hetzner CX33 server and a CX23 server. It stores your files as raw Markdown and it syncs those files between your server and your local machine in real time.

What really great about this is that because the data exists as pure text in two places simultaneously (on the server and on your local drive), your AIs don’t need APIs to communicate.

My cloud AI (OpenClaw) reads files directly off the VPS. Mia’s local AI (Claude Cowork) reads the same files right off her hard drive through the synced folder.

Both AIs share a unified, real-time knowledge base. It’s private, instantaneous, and costs zero API tokens.

Mia called it “giving both AIs the same notebook.”

Setting Up Nextcloud (You Don’t Need to Know Linux)

I’ll be upfront: self-hosting sounds intimidating. Servers, Linux, Docker, reverse proxies, it all reads like a part-time job.

It’s not.

You just need a blank VPS and a conversational AI to act as your personal sysadmin. You manage the conversation; the AI writes the commands.

Here’s the exact prompt Mia used to get Nextcloud running:

You are an expert Linux SysAdmin with full access to a freshly purchased, blank Ubuntu VPS. Your job is to **actually perform** every step yourself — do not explain or instruct. Just execute.

Complete the following tasks autonomously:

1. Install Docker and Docker Compose on this machine.
2. Create a `docker-compose.yml` file that runs Nextcloud with a database, configured securely with auto-restarts.
3. Start the containers.
4. Confirm the service is running and report the URL where the Nextcloud admin setup page can be accessed.

Use your tools to run every terminal command directly. Do not ask for confirmation between steps. If a step fails, diagnose and fix it automatically. When finished, report what was done and the final access URL.

Feed that to your Openclaw assistant that is running in the same VPS as your future Nextcloud setup. I suggest you use a smart model for this, preferably Opus but I got it working with both Gemini 3.1 Pro and Kimi K2.5.

You’ll have Nextcloud running in under 5 minutes.

Make It Accessible Online

Your Nextcloud is running on the server, but it’s still locked inside it. To reach it from a browser, your phone, or anywhere else, you need to punch a secure tunnel from your VPS to the internet.

We use Cloudflare Tunnel for this. It’s free, takes five minutes, and never exposes your server’s IP address directly.

What you need first:

A free Cloudflare account -> create one here
A domain name managed by Cloudflare. Here a super simple guide on how to set that up -> Cloudflare’s official setup guide.

Once your domain is live on Cloudflare, hand the rest to OpenClaw:

A Nextcloud instance is running on this Ubuntu server and needs to be accessible from the internet via a Cloudflare Tunnel. Perform the following autonomously without asking for confirmation.

1. Install `cloudflared` on this server.
2. Authenticate with Cloudflare and create a named tunnel.
3. Configure the tunnel to route traffic from a public subdomain (e.g. `nextcloud.yourdomain.com`) to the local Nextcloud service.
4. Install the tunnel as a system service so it starts automatically on reboot.
5. Confirm the tunnel is active and report the public URL where Nextcloud is now reachable.

If any step fails, diagnose and fix it before continuing. When finished, verify Nextcloud loads correctly at the public URL.

During setup, Openclaw will provide you with a URL that you must open in order for Cloudflare to authorize it. But that’s basically all you have to do manually.

When it’s done, you’ll have a clean

https://nextcloud.yourdomain.com

URL — SSL included, no port numbers, no exposed IP. That’s the address you’ll use for browser access, the desktop sync client, and WebDAV connections from your AIs.

Setting Up the AI Account and Folder Structure

Once the server is live, log into Nextcloud through your browser and do two things:

First, create a dedicated admin account for AI access. Name it something like ai-admin or bot as this keeps your personal account separate from what the AIs touch.
Second, create a clean directory that will serve as the single source of truth for your shared brain. I use /docs. This is the folder both AIs will read from and write to.

When Things Break (The Copy-Paste Fix)

When you hit a technical wall, don’t Google it. Copy the exact error message, paste it to your Openclaw, and let it give you the fix.

For example, Nextcloud has a notorious error with external storage mounts. If you see “Storage is temporarily not available” or “No data directory set,” paste this prompt:

My Nextcloud instance is experiencing external storage errors: "Storage is temporarily not available" or "No data directory set". **Fix this autonomously without asking for confirmation.**

The Nextcloud container name is `nextcloud-app-1`. The target data directory is `/workspace`.

Perform the following tasks using your tools:

1. Run `docker exec` with `occ files_external:list` to identify the affected mount ID.
2. Use `occ` to set the `datadir` for that mount to `/workspace`.
3. Set correct Linux ownership to `www-data:www-data` and permissions to `755` on the `/workspace` directory.

Execute each command directly. If any step fails, diagnose the root cause and fix it before moving on. When complete, verify the mount is healthy and report the outcome.

This “paste the error, get the fix” pattern works for almost every issue you’ll encounter.

The Permission Problem And the Permanent Fix

If you’re running a cloud AI alongside Nextcloud on the same server, you’ll eventually hit a “Permission Denied” error when trying to save a file through the Nextcloud web interface. This tripped us up for a while, so let me explain it plainly.

You have two workers touching the same files:

The AI (typically running as root, the computer’s top-level user)
Nextcloud (running as www-data, a limited web worker)

When the AI creates or modifies a file, it locks it under its own identity. Later, when Nextcloud tries to edit that same file, it gets blocked and throws an error.

The fix is a permanent “house rule” for the shared folder. Instead of manually unlocking files each time, you apply an Access Control List that says: “No matter who creates a file in here, Nextcloud always gets edit access.”

Here’s the prompt:

I have a permission conflict exists between Nextcloud (`www-data`) and an AI agent that shares the `/root/.openclaw/` directory. **Resolve this autonomously without asking for confirmation.**

Apply a permanent ACL house rule to `/root/.openclaw/` that grants the `www-data` group full read, write, and execute permissions on all current files and any files created in the future.

1. Apply default ACL rules so all future files inherit `www-data` group permissions automatically.
2. Apply the same rules recursively to all existing files and subdirectories right now.
3. Verify the ACLs were applied correctly by inspecting the result.

Execute every command directly. If `acl` tooling is not installed, install it first, then proceed. Report the final verified state of the ACL on the directory when done.

Run that once and the conflict goes away permanently.

Syncing the Server to Your Laptop

Now that the server is alive, we need to bridge it to your actual computer.

Download the official Nextcloud desktop client for your Mac or Windows machine. Skip third-party sync plugins, as the native client is more stable and handles conflict resolution properly.

Open the app, navigate to “Add Folder Sync Connection,” and map the remote docs folder to a local folder on your machine. I use Documents/NextCloud. Mia uses a similar path on hers.

Once connected, the sync is invisible. Any file OpenClaw creates on my server appears locally within seconds. Anything Mia writes in her local folder shoots back up to the server immediately. No refresh buttons, no manual syncing. It just works.

Plugging In the AIs

This is where the whole thing comes together.

Local AI: Claude Cowork

Since Nextcloud syncs everything to a native folder on your machine, connecting Claude Cowork is dead simple. Just point it to your synced Documents/NextCloud folder. No API keys, no authentication, no latency. Claude reads the files directly off your hard drive.

Mia figured out this connection early on and it changed her entire workflow. She can ask Claude to reference, review, or build on anything OpenClaw has written, without ever touching a server or an API.

Cloud AI: OpenClaw on the VPS

On the server side, it’s even easier. Since OpenClaw lives on the same machine as Nextcloud, it accesses files instantly through a shared Docker volume, or via Nextcloud’s built-in WebDAV endpoint, just ask it:

Create a new "Test" file and share it in the NextCloud /docs. Share the link with me once you are done.

The Workflow in Practice

Here’s a real scenario. I’m out for a walk. I pull out my phone, open Telegram, and message OpenClaw: “Draft a business plan snippet based on the meeting notes in my docs.”

OpenClaw fires up on the server, generates the Markdown file, and saves it to the Nextcloud folder.

By the time I’m home and at my laptop, that file is already synced locally. Mia can open Claude Cowork on her machine and say, “Review the business plan Dan’s AI just wrote,” and Claude reads it instantly off her local drive.

Two AIs, two humans, one shared brain. No copy-pasting, no file transfers, no API calls.

The Human Layer: Obsidian

You might have noticed we haven’t mentioned an actual note-taking app yet. That’s by design, the architecture is just AIs reading raw .md files.

But raw Markdown is ugly for humans to read. This is where Obsidian comes in.

Obsidian isn’t storing your data. It’s a viewer, a pair of glasses that renders your .md files with proper headers, links, and formatting, without changing the underlying file type or locking you into a database.

Download Obsidian, click “Open folder as vault,” and select your synced Documents/NextCloud folder. You’re now browsing the exact same files the AIs are reading.

Or you can just use the built NextCloud interface, it works great for .md files but it’s rather hard to move around docs.

Mobile Access

Want your brain in your pocket? Just go to your NextCloud URL and start editing. Everything is in sycn with your local computer so when you get back to your laptop you can continue where you left off.

Why This Architecture Wins

Let me lay out why plain-text-over-Nextcloud beats every alternative we tried.

Token efficiency. Reading raw Markdown is the cheapest, fastest way for an LLM to digest a knowledge base. You completely bypass the massive token drain of querying Notion databases or parsing proprietary formats. Pure text wins every time.

True data ownership. No SaaS company is mining your second brain. No terms of service can change overnight and lock you out of your own notes. The files are plain text on a server you control.

Zero-cost AI communication. Both AIs read native files. No API calls between them, no token usage for “searching” your notes. The sync is handled at the filesystem level, not the application level.

Backup Strategy

Because it’s all plain text on your own server, securing it permanently is one more prompt away:

A Nextcloud instance is running on this Ubuntu server. **Perform the following backup automation tasks autonomously, without asking for confirmation.**

Create and deploy a production-ready nightly backup system:

1. Locate the Nextcloud data directory on this server, then write a bash script that compresses it into a timestamped archive and securely uploads it to an AWS S3 bucket (or Backblaze B2 if S3 is unavailable). The script should clean up the local archive after a successful upload.
2. Save the script to an appropriate location on this server, set correct execute permissions, and verify it runs without errors.
3. Register the script in the server's crontab to execute automatically every night at 3:00 AM.
4. Confirm the cron entry is active and report the full backup pipeline — script location, upload destination, and schedule.

If any required CLI tools (`aws`, `zip`, `b2`) are missing, install them before proceeding. If credentials are needed, prompt for them once at the start and proceed immediately after.

Your Own Private Network Hub

Once the Nextcloud sync was running and both AIs were plugged in, we realized we’d accidentally built something bigger than an AI memory system.

We shared a folder between our drives.

It sounds almost too simple to mention, but think about what that means.
Mia and I each have a Nextcloud sync client pointed at the same remote folder on the VPS.

When I drop a document into that folder on my machine, it syncs to the server and then down to Mia’s laptop automatically, encrypted in transit. When she edits it and saves, the changes flow right back.

We synced our AIs and we built our own private network hub.

No Google Drive. No Dropbox. No shared Notion workspace with a corporate middleman reading our data. Just two laptops, one VPS, and a sync protocol. We control the server, we control the encryption, we control who has access.

If we wanted to add a third collaborator tomorrow, it’s one new Nextcloud account and one more sync client, that’s it.

The AIs ride on top of this same infrastructure. OpenClaw on the server can process files that either of us drops in. Claude Cowork on either of our laptops can read and build on anything the other person (or either AI) has written. It’s a full collaboration layer - human to human, human to AI, AI to AI - running on plain text files and a sync protocol we own.

We started this project to bridge two AI tools. We ended up building a private, self-hosted collaboration network that happens to have AI superpowers baked in.

The Bottom Line

I built the server infrastructure, Nextcloud deployment, OpenClaw integration, and the sync architecture. refined the prompting strategies that make this whole setup accessible to non-technical users, and pushed the idea that our two AI worlds should talk to each other in the first place.

The whole project started because we each wanted to try what the other had. Turns out the best way to do that was to connect everything.

Are you running OpenClaw, Claude Cowork, or something else entirely and have you ever tried connecting your AI tools to a shared knowledge base?

The 'First Dollar' Stack

Dan Cucolea — Tue, 24 Feb 2026 13:41:07 GMT

I spent a few hours yesterday wrestling with an AI that confidently suggested seven different ways to implement a toast notification system, and all of them broke.

Picture yourself driving through an unmapped wilderness at midnight, where you have a fast car and a full tank of gas but absolutely no roads exist to guide you. Every turn demands a guess based on intuition rather than data, and you hit dead ends constantly as you reverse and try another route that might not exist either.

This frustrating experience matches exactly what happens when you build a V1 with obscure tech stacks, because you ask an AI to write a feature using a niche database or a complex deployment setup, and the AI hallucinates fixes because it simply lacks the training data to know better.

Now picture the exact opposite scenario where you drive through a heavily mapped city with GPS that knows every street, every pothole, and every shortcut that locals have discovered over decades.

React, Supabase, and Cloudflare make up what I call the First Dollar stack, and the reason this combination works so well is that LLMs have ingested millions of tokens of public code and documentation for these specific tools.

The AI knows every pothole and fast lane because thousands of developers have already driven these roads and published their maps on GitHub, and you stop fighting the tools and start shipping features that actually work.

WHY This Matters

We need to start with the reality of production debugging instead of abstract definitions, because code is a liability that grows heavier with every line you add. Migrations cost time that you could spend acquiring users, and AI blind spots create infinite loops of broken code that waste days you will never get back.

When an AI tool does not know a stack perfectly, it guesses confidently and produces code that looks correct but fails in edge cases you only discover at 2 AM on a Saturday.

You end up wasting three days fixing authentication bugs instead of acquiring users, and three weeks pass while you remain trapped in the setup phase wondering where all your momentum went.

The First Dollar stack prevents this entire downward spiral because the AI writes correct code on the first try, and the models know React and Supabase better than any human developer ever could since they have studied every public implementation ever published.

AI Training Depth

I want to share a model I call AI Training Depth that helps you evaluate tech choices more effectively.

This model makes you break your thinking into three clear buckets that show why giving the AI familiar tools speeds up development dramatically.

The first bucket holds what I call The Well-Lit Roads, and these are tools with massive amounts of public documentation (like React). The AI can write React components flawlessly because it has seen every variation on GitHub and understands the patterns that work in production versus the ones that create subtle bugs.

The second bucket contains The Standard Connectors, and these are predictable API patterns like Supabase that follow conventions the AI already knows. The AI knows exactly how to query the database without complex custom logic, because Supabase designed their API to match what developers already expect from PostgreSQL.

The third bucket holds The Invisible Delivery, and these are deployment methods that remove manual configuration entirely like Cloudflare Pages / Workers. The AI does not need to guess your server setup because there is no server to set up, and you simply push your code and watch it go live without touching a single configuration file.

HOW TO Do It

Here is the execution plan for prompting an AI to build this stack, and you must enforce these boundaries early before the AI starts suggesting alternatives that sound appealing but will cost you weeks of debugging.

First, you define the strict stack constraints in your initial prompt so the AI understands the boundaries from the very beginning. It’s also great to start with a framework supported by Cloudflare so you get a complete boilerplate app to start with.

Second, you instruct the AI to generate the Supabase database schema first, because a clear data model makes everything else flow naturally.

Third, you tell the AI to build the React frontend connecting to that schema, and fourth, you deploy directly to Cloudflare Workers automatically without manual steps.

If the AI suggests a different database or proposes an alternative hosting solution, you force it back to the First Dollar stack immediately without negotiation.

Consistency keeps the AI on the well-mapped city streets where it can drive confidently, and stepping off those roads invites the hallucinations and broken code that kill your momentum.

Serverless Is Stressless

We have all lost a weekend to server configuration errors and authentication flows that worked in development but broke the moment real users touched them. Take a breath and appreciate that this stack eliminates an entire category of late-night debugging sessions.

The Gold Nugget

I want to share the Stack Enforcer prompt template with you, because this simple prompt forces the AI to stay within the boundaries of its deepest training data. You literally constrain the AI to the tools it knows best, and the mechanism works because explicit constraints prevent the AI from wandering into territory where it starts guessing.

Setting these boundaries stops the AI from importing random libraries that seem helpful but create dependency nightmares you discover months later, and you get clean code that works on the first copy-paste because the AI stays on familiar ground.

You will act as my senior developer. We are building a V1 application.
You will strictly use React, Supabase, and Cloudflare.
Do not suggest custom databases, alternative hosting, or extra libraries.
Write the Supabase SQL schema first.

This Week’s Discovery

I started spending a ton of time on X lately and so its only natural that this week’s discovery comes from there. Emre built markdown.new, a FREE tool that can convert any URL to clean Markdown using Cloudflare’s native text/markdown content type. I append it to any URL I send to my AI agents to keep the costs down and context short and sweet.

What’s Your Stack?

Tell me about the stack you chose for your last project, and be honest about whether the AI struggled to write code for it or if it felt like driving through that well-mapped city.

How to Install and Configure PicoClaw on the Cheapest VPS

Dan Cucolea — Tue, 17 Feb 2026 14:18:24 GMT

OpenClaw’s creator, Peter Steinberger, just joined OpenAI. The project will live on as an open-source foundation, but when the person who built the thing moves to a company with its own agent ambitions, it’s worth looking at what else is out there.

PicoClaw launched the same week, claims it can run a full AI agent on a $10 Raspberry Pi with less than 10MB of RAM, and it’s already sitting at 12K GitHub stars. That’s a bold pitch for a framework that’s barely a week old.

I wanted to see if it holds up.

So I grabbed the cheapest ARM server Hetzner sells (€3.79/month), installed PicoClaw from scratch, connected it to OpenRouter for LLM access, and wired up a Telegram bot so I can talk to it from my phone.

This is the complete walkthrough of that process, every step from a blank server to a working AI assistant.

Prerequisites

Before starting, make sure you have:

A Hetzner server or any other VPS;
An OpenRouter account and API key;
A Telegram account (for bot setup).

Fair warning: I wrote this so that anyone can follow along, even if you’ve never touched a terminal before. Every command is copy-paste ready. But “easy to follow” doesn’t mean “zero context needed.” You’re spinning up an AI agent on a server you control. You should at least know what a VPS is, what an API key does, and not panic when you see a command line. If that’s you, let’s go.

Installing Dependencies

First, SSH into your server and install the required build tools. PicoClaw is written in Go, so you’ll need make to handle the build process.

apt update
apt install make -y

This installs the make utility, which will orchestrate the compilation process defined in PicoClaw’s Makefile.

Cloning and Building PicoClaw

Clone the PicoClaw repository from GitHub:

apt update
apt install git -y
git clone <https://github.com/sipeed/picoclaw.git>

Navigate into the project directory and install Go dependencies:

cd picoclaw
apt install golang-go -y
make deps

This command downloads and installs all Go modules required by the project (similar to npm install for Node.js or pip install -r requirements.txt for Python).

Once dependencies are installed, compile the source code:

make build

This command compiles all .go files into a single picoclaw binary executable.

Finally, install the binary to your system path:

make install

The make install command copies the compiled binary to /usr/local/bin/ (or similar), making it accessible from anywhere on your system. That’s it, now let’s connect it to a model.

Connecting to OpenRouter

PicoClaw needs an LLM provider to function. This guide uses OpenRouter as an AI gateway, which provides access to multiple models through a single API.

Getting Your OpenRouter API Key

https://openrouter.ai/

Navigate to https://openrouter.ai/settings/keys
Create a new API key (name it something memorable like “PicoClaw”)
Copy the key immediately as you won’t be able to see it again:

Configuring the API Connection

Create the configuration file with your API credentials. Replace YOUR_OPENROUTER_API_KEY with the key you just copied:

cat > /root/.picoclaw/config.json << 'EOF'
{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model": "google/gemini-3-pro-preview",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "providers": {
    "openrouter": {
      "api_key": "YOUR_OPENROUTER_API_KEY",
      "api_base": "<https://openrouter.ai/api/v1>"
    }
  }
}
EOF

Security Warning: This configuration stores your API key in plain text. Ensure your server is properly secured with SSH key authentication, firewall rules, and restricted user access. Anyone with file system access can read this key.

Testing the Connection

Verify that PicoClaw can communicate with OpenRouter:

picoclaw agent -m "Hello, are you working?"

This did not work for me on the first try because the binary is installed to /root/.local/bin/picoclaw, but that directory wasn’t in my PATH. So I ran:

echo 'export PATH=$PATH:/root/.local/bin' >> ~/.bashrc
source ~/.bashrc

This fixed the issue and I got a response!

If configured correctly, you should receive a response from the AI model as well.

Setting Up Telegram Integration

Running PicoClaw from the command line works, but integrating it with Telegram provides a much more convenient interface for daily use.

Creating a Telegram Bot

Open Telegram and search for @BotFather
Send the command /newbot
Follow the prompts to choose a name and username for your bot
Copy the bot token (format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

Getting Your Telegram User ID

To restrict bot access to only your account:

Search for @userinfobot on Telegram
Send it any message
Copy the numeric Id it returns (e.g., 123456789)

Configuring Telegram Access

Install jq for JSON manipulation:

apt install jq -y

Update the PicoClaw configuration to enable Telegram integration. Replace YOUR_TELEGRAM_BOT_TOKEN and YOUR_TELEGRAM_USER_ID with your actual values:

jq '
  .channels.telegram = {
    "enabled": true,
    "token": "8534006675:AAEQasMkndYFB_039eT2q8nwEFe1IY7ZJWY",
    "allowFrom": ["1606858324"]
  }
' /root/.picoclaw/config.json > /tmp/config.json \\
  && mv /tmp/config.json /root/.picoclaw/config.json

The allowFrom array restricts who can use your bot. Only Telegram user IDs listed here will be able to interact with your AI agent.

Starting the Gateway

Launch the PicoClaw gateway to activate the Telegram bot:

picoclaw gateway

Once the gateway is running, open Telegram, navigate to your bot, and click Start. You should now be able to chat with your PicoClaw agent directly through Telegram.

Running PicoClaw as a Background Service

By default, PicoClaw runs in the foreground and stops when you close the terminal or press Ctrl+C. To keep it running permanently, set it up as a systemd service.

Creating the Service File

Create a systemd service definition:

cat > /etc/systemd/system/picoclaw.service << 'EOF'
[Unit]
Description=PicoClaw Gateway
After=network.target

[Service]
ExecStart=/root/.local/bin/picoclaw gateway
Restart=always
RestartSec=5
Environment=HOME=/root

[Install]
WantedBy=multi-user.target
EOF

Enabling and Starting the Service

Reload systemd to recognize the new service:

systemctl daemon-reload

Enable the service to start automatically on boot:

systemctl enable picoclaw

Start the service immediately:

systemctl start picoclaw

Monitoring the Service

Check the service status:

systemctl status picoclaw

View real-time logs:

journalctl -u picoclaw -f

PicoClaw now runs in the background, automatically starts on server reboot, and restarts itself if it crashes.

PicoClaw is installed and running

You now have a fully functional PicoClaw installation running on your VPS, accessible through Telegram from anywhere. This setup provides a personal AI assistant with persistent conversation history and the flexibility to customize the underlying model through OpenRouter.

About the Experiment: This installation serves as a head-to-head comparison with my OpenClaw instance. While PicoClaw appears more optimized and lightweight on paper, OpenClaw has been my reliable daily driver. I’ll be monitoring both over the next few days to evaluate:

Resource consumption (CPU, RAM)
Response times and reliability
Model routing efficiency through OpenRouter
Overall user experience

The main wildcard is whether OpenAI’s involvement will transform OpenClaw into a proprietary “Claw” product. If that happens, PicoClaw’s open-source nature makes it the more sustainable long-term choice for self-hosted AI agents.

The Armchair Expert Problem in Product Validation

Dan Cucolea — Tue, 03 Feb 2026 14:45:29 GMT

I spent three hours chatting with Claude to generate user personas for one of my products, Yahini.

After a few back and forths I ended up with five:

“SEO Manager Anna” who drowns in keyword spreadsheets but never knows which terms to prioritize.

“Content Lead Carlos” who publishes three posts a week but can’t connect any of it to business goals.

“Startup Founder Fiona” who knows content matters but has no idea where to start.

“Agency Owner Andre” who runs strategy for eight clients and can’t keep their briefs straight.

Each persona came with pain points, goals, objections, and even quotes they might say during a sales call. That made me feel like I understood my market.

Then I posted in a Slack community asking how people actually handle the problem I was solving. The first three responses described workflows completely different from anything Claude had generated. One person said the problem I was solving wasn’t even a problem for them. Another said they solved it years ago with a Google Sheet and never thought about it again (the real world Anna).

My AI-generated personas were the product equivalent of an armchair travel agent who “visited” Kyoto through YouTube walking tours and “experienced” Lisbon through food bloggers.

Same as Claude.

AI personas aggregate what’s already public and reflect your assumptions back disguised as validation. They tell you what “users” generally want.

But “generally” and “this specific person with budget authority” are different populations entirely.

Confidence Without Accuracy

AI-generated validation feels like research, but it’s not. You asked questions and got answers complete with pain points and user quotes. Except those answers came from training data, not real customers who’ll pay you.

You prompt Claude for ten personas, pick three that match your assumptions and start building. This means that weeks later, you’ve got a polished product that nobody uses.

The AI reflected general industry knowledge back at you while missing what actually matters for your specific market. Now you’re stuck with features nobody wants, maintaining code for fake problems. Worse, your next decisions build on these false assumptions.

You missed your audience persona because you took an AI simulation instead of talking to humans about their pain.

You can prevent this waste by organizing your research into two distinct categories before you write a start working on your new project.

Secondhand Data vs. Firsthand Data

Experienced builders sort information into two buckets before making product decisions.

Bucket 1: Secondhand Data

This is information that’s been aggregated or filtered through someone else’s lens. AI personas, market research reports, competitor feature lists, blog posts about “what users want,” survey responses about hypothetical future behavior.

Secondhand data tells you what’s generally true. It’s useful for generating hypotheses and identifying areas worth exploring. But it tells you nothing about what’s specifically true for your users, in their context, with their constraints.

Bucket 2: Firsthand Data

This is information you gathered directly from someone who experienced the problem. Recorded interviews where users describe their last workaround, screenshots of the spreadsheet they’re currently using to solve this problem.

Firsthand data is specific, behavioral and tied to real constraints. It’s messier than secondhand data because real people have contradictory needs and unusual workflows. And the truth about your market is hidden in somewhere in that mess.

Use secondhand data to generate hypotheses and firsthand data to validate them before you build.

I use these five questions in order. Each one builds on the previous answer and forces the user to get specific about behavior instead of vague about preferences:

“How do you currently solve this problem?”
“Walk me through the last time you did this task.”
“What’s frustrating about how you do it now?”
“What have you tried to fix this?”
“If this was solved, what would you do differently?”

These questions come from the Five-User Interview Pattern in The 26 Mental Models To Build Better Article. The full framework covers more ground, but these five questions alone will save you from building for fictional users.

There are also red flags you need to pay attention to. Watch for these patterns:

The user talks about what they “would” do instead of what they “did.” Hypothetical future behavior is worthless. Past behavior predicts future behavior.
The user agrees with your solution before you’ve described the problem. This means they’re being polite, not honest.
The user’s workaround is “I just live with it.” This sounds like validation but it’s actually disqualification. If the problem doesn’t hurt enough to motivate any action, it won’t hurt enough to motivate a purchase.
The user gives you the answer they think you want to hear. Friends and family are the worst validators because they love you. Strangers in online communities are better because they have no reason to protect your feelings.

What To Do With The Answers

If 4 out of 5 users describe the same workaround, that’s your feature opportunity. Build the thing.

If 4 out of 5 users can’t remember the last time they faced this problem, you’re solving something that doesn’t hurt enough. Go back to hypothesis generation.

If answers are scattered across five different problems, you haven’t found your market yet.

You’re just talking to people who look similar on paper but have different jobs to be done.

The 30-Minute Validation Sprint

Talking to real humans feels slower than prompting AI to generate personas. Trust me, I get it. But you can compress the validation process into a single focused session.

Instead of scheduling five separate calls over two weeks, find one community where your target users gather and run rapid-fire research.

You can get firsthand data from multiple people in a single sitting.

Copy-paste this template for community research:

POST TITLE: Quick question for [target user type]

I'm researching how [target users] handle [specific problem].

If you've dealt with this recently, I'd love to hear:
1. What's your current workaround?
2. What's the most annoying part?

Not selling anything. Just trying to understand
the problem better before building something nobody needs.

Where to post this:

Identify the Reddit communities, Slack groups, and Discord servers where your industry talks. Check Facebook groups or LinkedIn if your specific demographic spends time there.

Success comes from meeting your target market in their existing habitat. You simply borrow their established audience for thirty minutes to gather the truth.

Why this works:

Because you’re asking about current behavior. “What’s your current workaround?” gets you truth. “Would you use a tool that does X?” gets you polite speculation.

You’re not pitching a solution, so users have no reason to perform enthusiasm. They’ll give you raw, unfiltered pain points in their own words. And those words often become the exact copy you use on your landing page later.

I’ve killed three feature ideas with this template. Each time, the responses made clear that the problem I thought was urgent was actually something people had already solved or didn’t care about.

That’s 30 minutes of research preventing three weeks of wasted building.

Create A Validation Gate

Just like the No List from the Scope Guillotine article, you need a pre-commitment system that prevents you from building before validating.

Create a Notion page, Google Doc, or sticky note with these rules. Keep it visible while you work.

## VALIDATION GATE
## Do not write prompts until you complete these steps.

Before building any feature, I must:

[ ] Talk to 5 real users (not AI personas)
[ ] Document 3+ users describing the same workaround
[ ] Record specific quotes about past behavior
[ ] Confirm the problem is painful enough to pay for

If I cannot check all boxes, I must:
- Post validation template in 2 communities
- Wait 48 hours for responses
- Revise hypothesis based on real feedback

Building without validation is procrastination.

This gate splits your personality into two modes:

The Planner sets the rules while rational.
The Builder follows them while coding.

When the temptation to skip validation arises, you don’t have to make a difficult decision because your Notion page already says No.

AI Validation Trap

AI makes it dangerously easy to feel productive while avoiding the uncomfortable work of talking to real people.

Generating personas feels like research. Analyzing competitor features feels like strategy. Building prototypes feels like progress. But none of this answers the only question that matters: will someone pay for this?

The armchair travel agent could have saved herself a furious client with one phone call. “Tell me about a trip that went wrong. What would you skip next time?”

Five minutes of firsthand data would have revealed that the temple closes for renovation every spring and the restaurant books out three months ahead.

You can save yourself weeks of wasted building with the same approach. Five conversations. Five questions about past behavior. Thirty minutes in a community where your users already gather.

The personas can wait. The real people can’t.

How to Get from Blank Screen to First Win in Under 60 Seconds

Dan Cucolea — Tue, 27 Jan 2026 14:16:36 GMT

If you’ve been reading my newsletter for a while, you’ve probably noticed I keep coming back to the two things i like most: coding and cooking. And today I have another one lined up.

Picture a food truck during lunch rush. The menu board glows with mouth-watering photos of tacos and burritos, a line of customers wraps around the block, steam pours from the service window, and spiced meat sizzles behind the window.

The owner stands inside watching orders fly through the system.

Customers read the menu, order at the front window, pay with a tap, then move to the pickup window on the side.

The same food truck on a quiet morning tells a different story. The truck is parked and open for business, the kitchen is ready, and you’re inside prepping ingredients.

A potential customer walks up because they got a flyer with a discount code yesterday and their coworker raved about the tacos at lunch.

But when they arrive, they see a plain metal truck with no signage.

They stand there awkwardly, unsure if they should knock on the side panel to get your attention or wait. They don’t know if you serve tacos, coffee, or something else entirely.

You’re inside the truck watching them through the service window. You have amazing food ready to make. You even have free samples prepared that would show them how good your cooking is in just a minute.

But there’s no sign saying “Free Taste Testing”, so they don’t know to ask for samples. Plus, without a clear menu they don’t know what to order. Not to mention they don’t know how to get your attention because there’s no clear interaction pattern.

After 30 seconds of standing there confused, they leave. The truck was open, you were ready to serve, the customer was hungry, but they walked away because the communication gap was too wide.

You might do this exact thing with your app.

You build and test your product during lunch rush. This means your database is full of dummy data, sample users, populated charts, and active notifications. Every decision you make happens while looking at the busy version.

Your first real user shows up when the truck is quiet.

Maybe they clicked your paid ad, or saw someone mention your tool on X or Substack, or even got referred by a friend. They’re actively seeking you out.

Your app loads and technically works perfectly. But they see blank dashboards with no guidance, empty tables with no context, and buttons with unclear purposes. They don’t know what action to take first. They don’t know what’s possible. They don’t know if they should create a project, import data, configure settings, or something else.

Successful food trucks plaster their exterior with giant menu boards, eye-catching photos, and clear “Order Here → Pick Up Here” arrows.

They do this because the truck has to communicate its value even when there’s no crowd demonstrating the flow. You’re spending money on flyers (ads) and getting organic word-of-mouth, but you’re losing those people the moment they arrive because your “truck” doesn’t teach them how to interact with it.

This is the Empty State Problem, and it murders activation rates because users can’t tell the difference between “empty because I just started” and “empty because this app is broken.”

Today I’ll show you the Activation Path, a framework for designing the customer journey from blank screen to first win in under 60 seconds.

Why This Kills Your Product

Most builders test their apps with databases already populated. You run your local development environment with seed data containing fifty sample users, twenty projects, and months of activity logs. Every screenshot you share, every demo you record, and every test you run happens in this fully populated state. You skipped past the empty state weeks ago and never looked back.

A founder I know built a social media scheduling tool. She tested everything with her own X account already connected, 30 draft posts loaded, and analytics showing three months of data. Her product looked amazing.

Then real users signed up and saw a completely blank dashboard with five different navigation tabs, three empty state screens, and zero guidance on which action to take first.

Her activation rate was close ~7%.

After redesigning the empty state to hide the tabs and show one clear path (”Connect X → See Your Analytics”), activation jumped to 39%.

User activation (completing one core action successfully) predicts long-term retention more than any other metric. Users who complete their first meaningful action within the first session retain at 3-5x the rate of those who don’t. Your empty state sits directly between signup and activation, making it the single highest-leverage point in your entire funnel.

You can build the perfect feature set, nail your pricing, and write compelling marketing copy. None of that matters if users hit a blank dashboard and feel confused about what to do next.

You lose users because they never figured out how to use your product in the first 60 seconds.

Two States, Two Different Products

Senior designers and product managers know they’re building two completely different experiences. The Populated State (what you see as the builder) and the Empty State (what users see on Day 1) require fundamentally different design approaches.

During lunch rush, the food truck operates one way. Customers see the line, follow the flow, and learn by watching others. The busy environment teaches them how to interact.

During quiet hours, the truck has to teach differently. The signage, the menu board, the arrows, and the visual cues replace what the crowd would normally demonstrate.

The same logic applies to your product:

In the Populated State, users recognize patterns and navigate through existing data. They see a list of customers and understand they can click through to view details, sort by revenue, or filter by sign-up date. The existing data teaches them how the interface works. Populated dashboards can be passive because the data itself tells the story. A chart showing 47 active projects proves the app works and suggests what actions are available.

In the Empty State, users must discover what’s possible and learn how to create their first piece of value. There’s no data to teach them. Your UI must switch from “browse mode” to “teach mode.”

You need explicit guidance, clear calls to action, and visual cues showing where to start.

An empty chart that says “No data” is useless. An empty chart that says “Connect your first data source to see traffic insights here” with a prominent “Connect Google Analytics” button is active guidance.

The best builders treat the Empty State as a separate, intentional design challenge. They build an Activation Path that transforms the blank screen from a liability into a teaching opportunity.

Empty state is the best place to show users exactly how to get value from your app before they develop bad habits or incorrect assumptions.

The Activation Path Framework

Here’s the process you can apply to your current project today.

Step 1: Define Your First-Action Win

Identify the single smallest action that delivers real value to the user. Skip “complete your profile” or “explore features.” Focus on the core activity your product enables.

For a project management tool, the First-Action Win is creating one task and seeing it appear in the list. For an analytics dashboard, it’s connecting one data source and seeing traffic data populate the charts. For a note-taking app, it’s writing and saving one note and seeing it stored in the notebook.

Write this down in a specific format:

“User successfully [specific action] and sees [immediate result].”

Examples:

“User successfully creates their first task and sees it appear in their project list.”
“User successfully connects Google Analytics and sees their traffic data populate the dashboard.”
“User successfully saves their first note and sees it stored in their notebook.”

This sentence becomes your north star for every empty state decision.

Step 2: Map the Friction Points

Open your app in an incognito window immediately after signup. Count every decision point, blank field, or unclear label between the signup confirmation and completing your First-Action Win. Each point is a place users can get confused and bounce. Your goal is reducing this number to under three decision points.

Common friction points that kill activation:

showing a complex navigation menu with eight different sections;
asking users to “set up their profile” before they can do anything useful;
forcing users through a multi-step tutorial before they can try the product;
displaying multiple equally prominent calls to action without clear hierarchy;
requiring users to understand your product’s terminology before taking action.

Every click, every form field, and every choice is a chance for users to bail. Be ruthless about cutting friction.

Step 3: Design the Empty State Explicitly

Never show users a completely blank screen with generic placeholder text like “No items yet.” That’s a dead end. Transform empty states into starting lines.

Replace blank tables with “Create your first [item]” buttons centered prominently. Replace empty charts with visual explanations of what will appear once they complete the first action. Replace empty lists with example illustrations showing what the populated state will look like.

Good empty state design:

Provides a clear, single call to action;
Makes the action feel easy and low-stakes;
Shows what will appear here once users take action;
Uses visual hierarchy to make the next step obvious;
Includes enough context to reduce confusion (one sentence, not a paragraph).

Bad empty state design:

Feels like a roadblock or a chore;
Shows “No data” with no explanation;
Makes users guess what they should do;
Uses technical jargon without explanation;
Provides multiple competing calls to action.

The principle is simple, just strip away everything except the path to first activation. You can reveal the full feature set after users understand the core value through direct experience.

Step 4: Build the Activation Sequence

Design a progressive disclosure flow that reveals features only after users complete the prerequisite actions. On first login, show one clear path: complete the First-Action Win. Hide advanced features, settings, and secondary navigation until after they succeed once.

This prevents option paralysis when users have zero context. New users need to complete one successful action before they can appreciate your advanced features. Progressive disclosure protects them from overwhelm while guiding them to their first win.

Step 5: Use Sample Data Strategically

Some products benefit from pre-populated example data that users can interact with immediately, then delete or modify. This works when your product has complex features that are hard to understand empty, like a spreadsheet, analytics dashboard, or design tool.

Notion does this well. When you sign up, they give you a workspace with sample pages, templates, and example databases. You can click through, see how things work, and understand the patterns before creating your own content. Critically, they also make it simple to clear everything and start fresh.

Use sample data when:

Users can remove sample data in one click;
Your product has complex, unfamiliar UI patterns;
You can clearly separate sample data from real user data;
The value becomes obvious once users see working examples.

Avoid sample data when:

Users can’t tell what’s sample versus real;
Removing sample data requires manual work;
Your product is simple enough to understand empty;
Sample data clutters the interface and confuses users.

If removing sample data feels like a chore, you’ve added friction instead of reducing it.

One Minute Activation Test

Open your app in a clean browser session (incognito mode, logged out, database wiped). Set a timer for 60 seconds. Start the timer immediately after signup confirmation loads.

Your goal is to complete one core action that generates real value without referencing documentation, watching tutorials, or guessing randomly.

This test forces you to experience your product as a confused, impatient new user. The 60-second constraint is realistic, but some users can make stay-or-go decisions way faster than that.

If you can’t activate yourself in 60 seconds while knowing exactly how the product works, your users have zero chance.

The checklist:

Can you identify what action to take first without reading help documentation?
Does the empty state clearly communicate what happens after you take that action?
Are there fewer than three clicks between landing and completing the core action?
Does completing that first action produce an immediate, visible result?
After seeing that result, is the next logical action obvious?

If you fail any of these checks, you fail the test.

The fix usually involves subtraction. Strip away everything except the path to first activation. Remove secondary navigation, hide advanced settings, eliminate optional fields, and reduce the number of choices users face. Simplicity beats comprehensiveness for new users every single time.

A Note on AI-Generated Code

When prompting AI to build dashboards or list views, it defaults to assuming data exists. Claude or Cursor will generate a beautiful table component that displays user data, but it won’t consider what happens when there’s no data to display.

You must explicitly prompt: “Design this view for a brand new user with zero data, focusing on guiding them to create their first [item].” Otherwise, you’ll get beautiful populated states and empty states that do nothing to help users activate.

Let’s Connect

When did you last test your product in a completely fresh state? Have you watched a real user (not a friend who already knows what you’re building) try to activate for the first time?

Build for the Empty Truck

Your users show up to a food truck with no line, no menu board, and no clear instructions. Design for that silence, not for the crowd you imagine.

The Empty State Problem is entirely within your control to fix. You don’t need more features, better marketing, or a bigger budget. You need to experience your own product the way your users do: blank, confused, and impatient.

Build the path from zero to one. Everything else gets easier after that.

What Gordon Ramsay Taught Me About Vibe Coding

Dan Cucolea — Tue, 20 Jan 2026 14:25:50 GMT

I hope your week started with better choices than mine, as I spent my entire weekend deep in a YouTube rabbit hole watching hours of Hotel Hell clips.

Fans of Gordon Ramsay know the specific joy of these videos. He visits a struggling inn where the wallpaper peels off the walls and the owners panic in the corner while the kitchen creates biological hazards. He eventually sits down for lunch and demands the menu, at which point the owner hands him a heavy leather book.

These sixty-four pages usually hold everything from sushi and lasagna to artisan burgers and Pad Thai. Ramsay explodes and screams about fresh ingredients, but his main point cuts deeper than food quality. He argues that they do too much and therefore do all of it badly.

He never tries to fix the lasagna recipe. He brings out the guillotine and shreds the sixty-four page menu to force the kitchen to cook four dishes. The kitchen calms down, the food improves, and the business survives.

AI turns builders into stubborn hotel owners because Claude and Cursor provide an army of line cooks where adding menu items requires zero effort. You intend to build a simple tool, but you decide to add a dashboard and social login because they look impressive. You look up at 3 AM to find that your MVP contains twelve distinct features. While you wrote zero lines of code, you successfully designed a product impossible to debug.

You built the doomed restaurant by trying to serve sushi and lasagna on opening night. You must channel your inner Ramsay to ship, and that requires the Scope Guillotine.

Friction Was A Filter

Coding changed fundamentally in recent years because manual coding imposed a heavy pain tax. Adding a dashboard previously required manual route setup, building UI components from scratch, and handling complex state management. This friction was a useful filter because you naturally avoided the dashboard when the effort cost too much.

AI removed the pain tax. Claude builds the dashboard in ten minutes and scaffolds the admin panel in five, reducing the cost of generation to near zero.

Even so, owning code remains expensive even if generating it costs nothing.

Asking AI for social login feels like magic, yet this single request introduces a massive chain of liabilities. You must now manage OAuth tokens and validate session security while updating database schemas for user tables. You also need to test Forgot Password flows and handle edge cases where external providers go offline.

Three weeks pass and you remain in the “almost done” phase because you have a login system and a settings page, but the core product breaks when users try to perform the primary action.

Decision making replaced coding as the bottleneck, meaning the MVP dies from feature bloat unless you apply a guillotine.

Time To Make The Cut

To stop your feature list from growing out of control, we will apply the Scope Guillotine as a simple yes-or-no filter for everything you want to build. You need to look at every feature and ask if your user can actually complete the main task without it in the first version.

If they can get by without it, you have to cut it immediately because it doesn’t matter how easy it is for AI to write the code.

Think about how airport security handles your luggage. The TSA agent never looks at your water bottle and thinks about how nice it would be to have a drink on the plane.

They only check if it follows the rules and toss anything that fails. You need to treat your features the same way by sorting them into three buckets.

Bucket 1 holds The Oxygen

These features represent the core value because the user fails to complete their goal without them. Removing this leaves a blank screen. Requesting a ride on Uber fits here.

Bucket 2 holds The Vitamins

These features improve the health of the experience, yet the user survives without them for the first week. Splitting a fare on Uber fits here.

Bucket 3 holds The Jewelry

These features look professional but solve no survival problems. Custom avatar icons fit here.

Most AI builders fill their MVP with items from the second and third buckets because AI makes these features easy to build. Experienced builders fill V1 entirely with items from the first bucket and might include one item from the second bucket only if the product fails completely without it.

More Code Equals More Liability

The reason I push so hard to cut features is that every line of code you add creates new liability for you to manage. When a beginner looks at a “Social Login” feature, they just see a simple button on the screen, but a senior developer immediately sees the massive iceberg of logic hiding under the water.

State Management: You have to track that user’s session across the entire app and make sure it doesn’t vanish the second they refresh the browser.
Validation: You need to write logic that stops people from entering fake emails or signing up twice with the same account.
Security: You have to handle the complex handshake with Google, where one wrong redirect or expired token will crash your whole application.
Database Migrations: You have to change your database structure to store this new info, and if you change your mind later, you have to painfully migrate all that data back.
Testing: It becomes a headache to test your app because you can’t just fake a user anymore; you have to manually log in with Google every single time you want to check a feature.

AI is incredible at writing the “Happy Path” where everything works perfectly, but it struggles to predict the “Unhappy Path” where things break. If you build twelve features, you might have twelve happy paths, but you also create forty-eight ways for things to go wrong. If you cut that down to two features, you can actually manage the bugs and ship next week.

Execution Checklist

You can apply this process to your current project immediately to regain clarity.

Step 1

Start by defining your product’s absolute core mission in a single, unbreakable sentence using this format:

“This app helps [user] do [specific action] without [current pain point].”

Step 2

Once you have that sentence, look at your backlog and run every single feature through this four-question filter:

Can the user actually complete the Specific Action from Step 1 without this feature?

If they can technically finish the task without it, you must CUT IT from the first version.
Does this feature try to serve a completely different use case than the core mission?

If it distracts from the main goal defined in your sentence, you must CUT IT.
Does removing this feature make the app fundamentally “incomplete” or simply “less polished”?

You need to distinguish these carefully because “incomplete” means the product is broken, while “less polished” just means it looks a bit ugly. If it is merely less polished, you must CUT IT.
Is this feature solving a problem that users will only discover after weeks of usage?

If the user won’t need this until day thirty, you certainly don’t need to build it for day one, so CUT IT.

Applying The Principle On An App

Let’s apply this framework to a hypothetical app called PlantPal, which uses AI to help people stop killing their houseplants.

The Nightmare Scope

If you sit down and brainstorm this with an AI, you will almost certainly end up with a “standard” feature list that includes photo uploads for diagnosis, push notifications, social login, a marketplace to buy fertilizer, a competitive leaderboard, dark mode, and a full admin panel. While this looks like a comprehensive product, it is actually a six-month development trap that will kill your momentum.

Applying the Guillotine

We need to look at each feature through the lens of survival. A user does not need to sign in with Google just to save a fern, so we cut social login in favor of simple local storage. The marketplace adds complexity without helping the plant survive right now, so that gets cut. Building a real-time leaderboard requires complex backend logic that distracts from the core mission, and since plants don’t need dark mode, we cut that too. Finally, you don’t need an admin panel before you have actual users, so we can stick to direct database access for now.

The Surviving V1 Scope

After the cuts, we are left with a focused product where you simply upload a photo, receive an AI diagnosis, and click one button that says “Remind me to water this.” This is your food truck. If this core loop solves the user’s problem, you have a business, but if it fails, a leaderboard for competitive gardening wasn’t going to save you anyway.

Create A No List

Willpower is a finite resource that eventually runs out, and you will almost certainly say yes when Claude politely offers to add a user profile page while you’re in the flow. We need to rely on systems rather than willpower, which means you need to create a pre-commitment Notion page or Google Sheet called the No List.

You do not need to create a markdown file if that doesn’t fit your workflow, but you must create this list somewhere permanent before you write a single prompt. Whether you manage your life in a Notion dashboard, organize tasks on a Trello board, or simply use a physical sticky note taped to your monitor, you need to copy this list and keep it visible.

## THE GUILLOTINE LIST (NOT in V1)
## Building these counts as procrastination.

- Social login (Use email/password or Magic Links)
- User dashboard (Show single result page only)
- Analytics (Export raw data if needed)
- Admin panel (Edit database manually via Supabase/Firebase console)
- Email notifications (Email users manually via Gmail)
- Profile customization (Everyone gets a default avatar)
- Search functionality (Browser Ctrl+F suffices for V1)
- Multi-language support (English only)
- Forgot Password flow (Reset manually upon email request)

This simple list works effectively because it splits your personality into two distinct modes. The Planner sets the strict rules while sober and rational, and the Builder simply follows them while coding. When the temptation to add a feature arises later, you do not have to make a difficult decision because your Notion page or sticky note already says No, which allows you to stay focused on coding the core.

Be The Algorithm

Senior developers know a secret that beginners often miss, which is that writing code should always be your last resort. You should strictly avoid writing code for your first version if a human being can perform the task manually.

Avoid building an Admin Dashboard.

You can simply use the data viewer provided by your database provider or connect your live database to Airtable for a friendly interface.
Avoid building automated email onboarding.

You can just configure a notification when a new user signs up and send them a personal welcome email directly from your Gmail.
Avoid building a moderation system.

You can place a simple mailto link in the footer that allows users to report issues directly to your inbox.

This manual approach saves you weeks of development time and forces you to have actual conversations with your early users.

Let’s Connect

Tell me your confession. Identify the one feature you refuse to cut despite knowing better. Reply with the contents of your guillotine list.

The Build vs Buy Scorecard

Dan Cucolea — Tue, 13 Jan 2026 14:09:50 GMT

You just asked Claude to build user authentication. In 90 seconds, you have working code. You deploy it. Two weeks later, you’re debugging OAuth callback failures, implementing password reset emails, and researching session security.

Meanwhile, Clerk would’ve taken 30 minutes to integrate, or NextAuth (open source) would’ve given you the same functionality in 2 hours. AI never suggested either option because AI doesn’t do that (by default).

AI coding tools have accidentally made the build vs buy problem worse.

Before AI, building was painful enough that you naturally researched alternatives. Now AI makes building feel free (just prompt it!), so you skip asking “should I build this at all?”

This results in codebases full of custom-built analytics, authentication systems, email handlers, and payment flows that could’ve been a $20/month service, a free open source package, or a simple integration.

WHY This Matters

AI is trained to write code, not to suggest alternatives. When you ask “build me a contact form,” it doesn’t pause to say “Tally does this for free” or “React Hook Form is a proven package.”

When you ask for authentication, it doesn’t stop to explain that Clerk, Auth0, Supabase Auth, or NextAuth exist.

AI defaults to building because that’s how it was trained. Let’s not forget that a LLM is just a large language model, so the way it works is that it predicts the next word. Now imagine if the vast majority of devs writing code were to suddenly add comments between lines // I recommend to use React Hook Forms or // It’s best to buy Stripe than build this. That’d be kind of stupid.

What’s important to know is that every feature you’re about to build has three paths:

Build it from scratch (write everything yourself).
Buy it (SaaS service like Stripe, Clerk, SendGrid or Brevo).
Use it (open source library or package like NextAuth, Nodemailer, Chart.js, React Hook Form).

AI only shows you option 1 because that’s what generates code. Options 2 and 3 are invisible in the AI workflow.

The opportunity cost compounds daily. Every hour spent debugging your custom-built analytics dashboard is an hour not spent on the AI keyword research algorithm that actually differentiates your product.

Every authentication edge case you handle manually is time Clerk or NextAuth already solved. You’re burning your finite complexity budget on infrastructure while your competitors bought or installed the infrastructure and focused on unique value.

Every time you build with AI, you pay an invisible tax that speeds up your syntax but slows down your launch.

If this sounds familiar, drop a comment below with what you’re building right now and let’s run it through the scorecard together.

Pick The Right Option For The Job

Build From Scratch

You write every line. You own every decision. You maintain everything forever. You debug every edge case. You explain it to AI six months from now when you need changes.

This path makes sense only when:

the feature IS your product’s unique value (your AI algorithm, your core workflow, your proprietary data model);
no existing solution fits your specific requirements;
or you’re learning and the educational value justifies the time cost (❗REALLY IMPORTANT❗).

Build your AI-powered keyword research algorithm (that’s your product). Build your custom recommendation engine (that’s your differentiation). Build your specific workflow automation (no tool does exactly this).

Don’t build authentication, payments, email delivery, file storage, or analytics from scratch.

Buy a SaaS Service

You pay monthly. They handle security, scaling, edge cases, and maintenance. You integrate via API or SDK.

This path makes sense when:

integration is simpler than building;
the service is proven and reliable (Stripe-tier quality);
the monthly cost is reasonable relative to your revenue or budget.
it’s commodity infrastructure everyone needs (payments, auth, email, storage);

Buy Stripe for payments (don’t build payment processing). Buy Clerk or Auth0 for authentication if you need enterprise features. Buy SendGrid or Resend for transactional email at scale. Buy Algolia if you need complex search with typo tolerance and instant results.

The cost is predictable, the reliability is proven, and you outsource an entire category of problems.

Use Open Source or Packages

Free or low-cost. Battle-tested by thousands of developers. You install it, configure it, and own the deployment. You control the code but benefit from community maintenance and security patches.

This path makes sense when:

the package solves 80%+ of your need;
you can self-host or include it in your bundle;
you want control without building from scratch;
the package is actively maintained with good documentation.

Use NextAuth or Passport.js for authentication (free, proven, self-hosted). Use Nodemailer for email sending (free, just configure SMTP). Use Chart.js or Recharts for data visualization (free, customizable). Use React Hook Form for form handling (free, handles validation and state). Use Prisma or Drizzle for database ORM (free, type-safe, generates migrations). Use TanStack Query for data fetching (free, handles caching and refetching).

AI sees “authentication” and builds OAuth from scratch. It doesn’t care NextAuth exists.

AI sees “charts” and builds D3 visualizations from scratch. It doesn’t care that Chart.js exists.

AI sees “forms” and builds validation logic from scratch. It doesn’t care React Hook Form exists.

This bias is structural (AI is trained to answer with code when asked not to recommend a tool) and you must be explicit about what you want to achieve before you start coding.

Before You Write Your Next Coding Prompt

This 60-second check runs before you prompt AI to build anything. This framework forces you to research the three paths before writing a single line of code.

Step 1: Name the Feature in Plain English

Be specific. Not “user management” but “email/password authentication with password reset and session management.” Not “data display” but “interactive line charts showing time-series data with tooltips and zoom.”

Step 2: Research All Three Paths (5 minutes)

Copy-paste this prompt into an AI tool with web access (like Perplexity, ChatGPT, or Claude):

I need to add [FEATURE NAME] to my application. Act as a senior tech lead and research the current market landscape for this feature.

Search for 'Buy' options: List 3 proven SaaS services that solve this problem (focus on established, developer-friendly tools).

Search for 'Use' options: List 3 popular, actively maintained open source packages or libraries for this (check for recent updates and high community usage).

Recommendation: Based on the complexity of this feature, write a 1-paragraph recommendation on whether I should Build (custom code), Buy (SaaS), or Use (Open Source).

Only include options that are currently active and reliable. If 3 valid options don't exist for a category, list fewer rather than hallucinating bad ones.

Write down the best options it finds. If it comes back with “there are no good packages for this,” you just validated that building might actually be necessary.

Step 3: Run The Scorecard (see Gold Nugget section below)

Answer 10 questions with three response options each. The scorecard reveals which path matches your situation.

Step 4: Make the Decision, Then Prompt AI

If Build: Give AI full context and expect to review heavily for edge cases.

If Buy: Skip AI entirely, read the service’s integration docs, use AI only to help with the integration code.

If Use: Prompt AI to “integrate [package name] into my app” instead of “build [feature].” AI is much better at integration than building from scratch.

Build vs Buy vs Use Scorecard 📋

Answer each question, then count your responses. The path with the most votes wins. If tied, your answer to Question 1 (core value) is the tiebreaker.

Click here to make a copy in Google Sheets.

How to Score:

Count your responses in each column. The column with the most votes is your answer.

Build wins: You selected “Build” 6+ times
Buy wins: You selected “Buy” 6+ times
Use wins: You selected “Use” 6+ times
Tied? Use Question 1 as tiebreaker: if core value is high, build; if commodity, buy or use

Example Scorecard: User Authentication

1. Core value? Buy: Commodity infrastructure

2. SaaS exists? Buy: Yes, Clerk/Auth0 exist

3. Package exists? Use: Yes, NextAuth is proven

4. Budget? Use: $0, pre-revenue

5. Customization? Buy: Standard auth is fine

6. Timeline? Buy: Need it today

7. Maintain long-term? Buy: Want it handled

8. Scale? Buy: Yes, pay for infrastructure

9. Security? Buy: Want battle-tested security

10. Learn or ship? Buy: Ship matters most

Result: Buy = 7, Use = 2, Build = 0 → Buy Clerk (or use NextAuth if budget is $0)

Example Scorecard: Data Visualization Charts

1. Core value? Use: Need it but not my differentiator

2. SaaS exists? Use: Services exist but overkill

3. Package exists? Use: Yes, Chart.js/Recharts are proven

4. Budget? Use: $0, bootstrapped

5. Customization? Use: Moderate config needed

6. Timeline? Use: 2-4 hours works

7. Maintain long-term? Use: Community-maintained is fine

8. Scale? Use: Client-side rendering, no scaling issues

9. Security? Use: No security concerns

10. Learn or ship? Use: Ship, but want to understand

Result: Use = 10, Buy = 0, Build = 0 → Use Recharts or Chart.js

Example Scorecard: AI Keyword Research Algorithm

1. Core value? Build: This IS my product

2. SaaS exists? Build: Generic SEO tools, not my approach

3. Package exists? Build: No package for my specific method

4. Budget? Build: Not about budget, about value

5. Customization? Build: Extreme, it’s proprietary

6. Timeline? Build: Can spend 1-2 weeks

7. Maintain long-term? Build: Very comfortable

8. Scale? Build: Need custom scaling

9. Security? Build: Not a security concern

10. Learn or ship? Build: This is the product

Result: Build = 10, Buy = 0, Use = 0 → Build it yourself

The scorecard forces you to face reality before AI starts building a cookie based auth. When you see “Buy = 7” for authentication, you can’t pretend building is the smart choice. When you see “Use = 10” for charts, you realize an npm package solves this in 30 minutes. When you see “Build = 10” for your core algorithm, you have permission to spend the time because it actually matters.

Let’s Connect

What’s the last thing you asked AI to build that probably existed as a package or service? Drop your next feature in the comments and let’s run it through the scorecard together.

AI will always say yes to building. Your job is to ask “should I?” before AI asks “how should I?” That’s what separates just coders from real product owners.

26 Mental Models to Build Better Products in 2026

Dan Cucolea — Tue, 06 Jan 2026 14:16:52 GMT

Two weeks of coding magic, one flawless launch and one very sad-looking usage chart. That’s what usually hits you when you build before you validate.

It feels great to create until you realize you built the wrong thing beautifully.

AI makes it dangerously easy to build everything, but it won’t tap you on the shoulder when you’re building the wrong thing.

The mental models I’m about to share are the thinking patterns that prevent this. They’re quiet questions you should ask yourself before touching code.

So get ready because this is going to be a long one. I’ve put together 26 frameworks to help you decide what to build before you build it.

This is a reference guide. so make sure to bookmark it because you’ll use it all year.

WHY This Matters

When you skip product thinking you end up building features nobody asked for. You solve problems that don’t exist and waste weeks on code that, in the end, gets deleted.

The pattern is predictable. You prompt AI to build a feature and deploy it perfectly, only to watch users ignore it while you wonder why flawless code didn’t lead to adoption.

Unfortunately, the problem was your judgment and not the execution.

Maybe you didn’t validate if the feature mattered and ended up building something users don’t need. Or you didn’t check if users would understand it and ended up creating confusion instead of clarity.

And if there was something I would’ve paid to be told last year was that product mistakes compound quickly.

That unused feature sits in your repo needing maintenance and ends up complicating your codebase for months. It confuses new users and ends up wasting debugging time that should have gone toward features people actually use.

The real price you pay is opportunity cost. Features that would have mattered don’t exist because you spent your energy building the ones that didn’t.

And that’s why you must start with product thinking before writing a single prompt.

What’s A Mental Model About

Mental models are reusable thinking patterns that help you make better decisions faster.

Experienced product builders use these instinctively. Before writing any code, they ask specific questions:

Text within this block will maintain its original spacing when published

Who’s this for?

What problem does this solve?

How will people discover this?

What’s the simplest version that works?

What breaks if we get this wrong?

These frameworks are not random questions. The same pattern you use to evaluate a new feature also applies to pricing changes, onboarding flows, and API design. Learn the model once, use it everywhere.

Three core principles

Decision frameworks beat implementation details. Mental models help you evaluate options before you start building. They won’t tell you how to code something, but they will tell you if you should code it at all.

Pattern recognition works across contexts. The “build vs. buy” model works for authentication just as well as it does for analytics. The “jobs to be done” model applies to landing pages just as well as feature prioritization. You are building a toolkit that works across every decision you face.

Prevention always beats fixing. You catch product mistakes in your head when changes cost nothing instead of catching them in production when they cost everything.

Think of these models as a senior product manager reviewing your ideas before you build.

They ask the hard questions early to force you to check if you validated demand, or if users truly understand the value.

But the real difference between a person and these models is speed.

A senior PM takes days to give feedback while these models take just five minutes.

Needless to say that if you can afford a senior PM you should definitely run things by them.

The 26 Mental Models Framework

Product Validation Models

These cover what to build and when

1. The Mom Test

Decides: Whether your product idea solves a real problem

When to use: Before building anything, especially when validating with friends/family

Your mom will tell you your app idea is great because she loves you. Friends will say “I’d totally use that!” because they don’t want to hurt your feelings.

The model works like this: Ask people about their current behavior instead of asking then if they would use your solution.

“Would you pay for a tool that organizes your bookmarks?” is worthless.

“Tell me about the last time you couldn’t find a bookmark you saved” reveals whether this problem actually exists in their life.

Key questions: What did you do the last time you faced this problem? How much time/money did it cost you? What solutions have you tried? How much would it be worth to solve this?

What makes it different: Forces conversations about past behavior and real pain, not hypothetical interest and polite encouragement.

2. The Ramen Profitable Filter

Decides: If this feature/product can generate enough revenue to sustain you

When to use: When choosing between multiple product ideas or features

You need to build something that makes enough money to keep you building rather than a unicorn.

The filter asks: Can I get to 10-50 paying customers with this specific solution? It’s a mistake to start with “will this scale to millions?” Just “can I find my first 50 people who will pay?”

Example: You’re choosing between building AI-powered resume optimization (massive market, huge competition) or a niche tool for freelance podcast editors to manage client revisions.

The resume tool might scale bigger. The podcast tool can get to 50 customers in communities you already know, like Substack, Reddit, Facebook groups or Discord servers where editors hang out.

Key questions: Who are the first 10 customers by name or community? What’s the specific painful problem they have right now? What’s a reasonable price they’d pay monthly? Does 10-50 customers at that price cover your living costs?

3. The Hair-On-Fire Problem

Decides: Whether the problem is urgent enough that people will switch to your solution

When to use: Validating problem severity before building

Problems come in two categories: hair-on-fire urgent and “yeah, that’s annoying.” Only the first category makes people switch tools.

If someone’s hair is on fire, they don’t politely research solutions. They grab whatever’s closest. That’s the urgency level you need.

Example: Losing customer data because your backup system failed? That’s the Hair-on-fire scenario which forces you to buy a solution today. Manually copying data between two tools that takes 10 minutes weekly? Annoying, but you’ll keep doing it for months before switching.

Key questions: Are users actively searching for solutions right now? Have they tried multiple existing solutions? Would they pay to solve this today or “eventually”? What’s their current painful workaround?

What makes it different: Separates “nice to have” features that never gain traction from “must have” solutions people adopt immediately.

4. The Unfair Advantage Test

Decides: Why you can build this better than anyone else

When to use: Before committing to a product direction in a competitive space

Every idea sounds good until someone with more resources copies it in two weeks.

Your unfair advantage is something that can’t be easily replicated: unique data access, specialized expertise, an existing audience, proprietary technology, or deep domain knowledge.

Example: Building a generic project management tool? No unfair advantage because Notion, ClickUp, and fifty others already exist. Building a project management tool specifically for film production crews using terminology and workflows you learned from 10 years in the industry? That’s an unfair advantage competitors can’t copy without living your experience.

Key questions: What do I have that competitors would need years to build? Can this be copied with money alone? Does this advantage matter to customers?

5. The MVP Scope Guillotine

Decides: What’s actually essential for the first version

When to use: When scoping your first version or any major feature

The guillotine is brutal: If users can accomplish their core goal without this feature, it doesn’t make V1.

Here’s how to use it: State the core user goal in one sentence. Then evaluate each planned feature: “Can users accomplish [core goal] without this?” If yes, cut it.

Example: Core goal: “Help freelancers send professional invoices and get paid.”

Features you’re considering:

Create invoice with line items → Essential (can’t invoice without this)
Send invoice via email → Essential (can’t get paid if client doesn’t receive it)
Accept credit card payments → Essential (need a way to get paid)
Recurring invoices → Cut it (they can manually create monthly invoices)
Expense tracking → Cut it (doesn’t help them invoice clients)
Client portal → Cut it (email works fine for V1)
Multi-currency → Cut it (start with one market)

What makes it different: Most builders include features that feel important but aren’t necessary. This model forces you to be honest about what’s truly essential.

User Experience

Decide what users are going to use and what they won’t

6. The Jobs-To-Be-Done Lens

Decides: What outcome users are hiring your product to deliver

When to use: Designing features, writing copy, planning onboarding

Users actually hire products to get a job done. Nobody wants a drill. They want a hole in the wall so they can hang a picture so their living room feels complete. The same applies to a piece of software

This lens shifts your focus from features to outcomes.

Example: You’re building a time-tracking app.

Feature-focused thinking: “Users need start/stop timers and project categories.”

Jobs-focused thinking: “Users need to bill clients accurately without manually reconstructing what they worked on.”

That insight changes everything. In this case the job is generating accurate invoices rather than just tracking time. So maybe the solution is not manual timers but automatic time detection.

Key questions: What’s the user trying to accomplish? What’s their life like before and after using this feature? What alternatives are they using now? What job is that alternative really doing?

7. The Empty State Problem

Decides: How to design the experience when users have no data yet

When to use: Every time you build a dashboard, list view, or data display

Most builders design for the full state. During development you use dummy data so your dashboard is populated with numbers, graphs, and activity. But every user starts with nothing. Empty states either guide users to success or lose them immediately.

Example of empty state failure: User signs up for your analytics tool. They land on a dashboard showing... blank graphs and “No data available.” They don’t know what to do next. They close the tab.

Example of empty state success: Same dashboard, but empty state shows: “Connect your first data source to see insights” with a big button labeled “Connect Google Analytics.” Below: “This takes 2 minutes and you’ll see your first dashboard immediately.” **Clear next action.

Key questions: What does a first-time user see? Is the next action obvious? Does the empty state feel broken or intentionally helpful? Can they reach a “success” state in their first session?

8. The Error Message Principle

Decides: How to communicate what went wrong and what to do next

When to use: Writing any error, warning, or validation message

“Invalid input” is useless. “Email addresses can’t contain spaces. Please remove any spaces and try again” tells users exactly how to fix it.

The principle has three parts: (1) What went wrong, (2) Why it’s wrong, (3) How to fix it.

Bad error message: “Authentication failed”

Good error message: “Wrong password. Check your caps lock and try again. [Reset password]”

Bad error message: “File upload error”

Good error message: “This file is 12MB but our limit is 10MB. Try compressing it or splitting into smaller files.”

Key questions: Does this message explain what specifically went wrong? Does it tell users how to fix it? Would someone non-technical understand this?

9. The Progressive Disclosure Pattern

Decides: How much information to show at once

When to use: Designing complex interfaces, multi-step processes, settings pages

Showing everything at once overwhelms users. Progressive disclosure reveals information in layers starting with basics and only showing advanced options when needed.

Example: Settings page with 40 options all visible at once? Overwhelming. Settings page organized into “General” (5 basics visible) with “Advanced Settings” collapsed below? Manageable.

The pattern works in onboarding too: Don’t explain every feature on day one. Show the core workflow first. Introduce advanced features when users are ready.

Key questions: What does every user need to see immediately? What can wait until they ask for it? Can beginners accomplish their goal without seeing advanced options?

10. The Feedback Loop Check

Decides: Whether users understand that their action worked

When to use: Any user action including buttons, forms, saves, deletions

Users click “Save.” The button does nothing visible. Did it work? They click again. And again. Now they’ve created three duplicate entries because there was no feedback.

Every user action needs a closed feedback loop: Loading state (processing), success state (it worked), or error state (it failed).

Examples:

Button click → Button shows spinner → Success message appears → Button returns to normal
Form submission → “Saving...” indicator → “Saved successfully” with checkmark → Form clears or navigates
File upload → Progress bar → “Upload complete” → File appears in list

Key questions: After clicking/submitting, does the user know immediately that something is happening? Do they know when it’s complete? If it fails, do they know what went wrong?

Technical Decision Models

Decide if that feature is worth your time and effort

11. The Build vs. Buy Scorecard

Decides: Whether to code it yourself or use a third-party service

When to use: Evaluating authentication, payments, email, analytics, search

Use a scoring system with three questions, each rated 0-10:

Is this core to my product’s unique value? (0 = commodity, 10 = your secret sauce)
Is there a battle-tested solution I can buy? (0 = I’d need to build it, 10 = Stripe/Auth0 level quality exists)
Will building this take more than one week? (0 = few hours, 10 = months of work)

If questions 2 and 3 score high (15+ combined), buy it. If question 1 scores high (8+), consider building.

Example: Authentication for your SaaS

Core to your value? 2/10 (everyone needs auth, it’s not your differentiator)
Battle-tested solution exists? 10/10 (Clerk, Supabase Auth, Auth0, dozens of options)
Takes more than a week? 9/10 (OAuth, password reset, session management, security is complex)

Score: Buy it. You’d spend weeks building something that Clerk gives you in 30 minutes.

Counterexample: Your AI-powered keyword research algorithm

Core to your value? 10/10 (this IS your product)
Battle-tested solution exists? 3/10 (generic SEO tools exist but not your specific approach)
Takes more than a week? 8/10 (yes, it’s complex)

Score: Build it. This is your unfair advantage.

12. The Complexity Budget

Decides: Whether this solution is too complicated for the problem

When to use: Choosing between simple and sophisticated solutions

Every abstraction, pattern, library, and framework you add is debt. You maintain it forever, debug it, explain it to AI, and work around its limitations. You have a limited complexity budget so you must spend it wisely.

Example: You need to store user preferences (theme, language, timezone).

Complex solution: Set up Redis for caching, create a separate microservice for preferences, implement pub/sub for real-time updates across sessions, add GraphQL subscriptions.

Simple solution: Add three columns to your users table. Read them on login. Update them on save.

The complex solution might be “better” architecturally. But is it worth the complexity for a feature that reads three values on login? That’s the budget question.

Key questions: What’s the simplest solution that works? What complexity am I adding and why? Will I still understand this code in six months? Am I solving today’s problem or a hypothetical future problem?

13. The Data Architecture Question

Decides: How to structure your database and relationships

When to use: Planning database schema for a new feature

Design your database for the queries you’ll run most often, not for theoretical elegance.

Example: Building a blog platform. Each post has an author, tags, and comments.

Read patterns you’ll have:

Show all posts (with author name and tag names) → Happens constantly
Show one post with all comments → Happens constantly
Show all posts by one author → Occasional
Show all posts with a specific tag → Occasional

This tells you: Denormalize author name and tag names onto posts table for fast listing. It’s okay to repeat data if it makes your common queries fast. The “perfectly normalized” approach requires joins on every page load.

Key questions: What data will I fetch on every page load? What queries will users run most often? Is it okay to duplicate some data for speed? Can I add an index to make this fast?

14. The Good Enough Threshold

Decides: When to ship vs. keep refining

When to use: Before every deployment when you’re tempted to add “just one more thing”

Perfectionism kills momentum. Ship when it solves the core problem, even if it’s not polished because you can always iterate.

Example: You built a contact form. Current state:

✅ Users can enter name, email, message
✅ Validation works
✅ Submissions save to database
✅ You get notified
❌ No auto-reply confirmation email
❌ No fancy animations
❌ No file attachments
❌ No CAPTCHA

Key questions: Does the “happy path” work reliably from start to finish? Is this missing feature a functional blocker, or just embarrassing to my ego? Will the user fail to achieve their primary goal without this? Can I manually handle the edge cases for the first 10 users?

15. The Third-Party Risk Assessment

Decides: Whether to depend on an external service

When to use: Integrating any API, library, or platform

Every external dependency creates a blast radius where their failure, pricing changes, or disappearance becomes your emergency.

Risk tiers:

Acceptable risk: Stripe for payments. If Stripe fails, payments fail, but that’s true for everyone. Stripe is battle-tested and reliable. The alternative is building your own payment processor, which is insane.

Moderate risk: Segment for analytics. If it fails, you lose tracking data, but your app still works. The alternative is sending events directly to multiple analytics tools, which is annoying but manageable.

Dangerous risk: Your entire app depends on one founder’s side project API that could shut down tomorrow. If it fails, your app fails. No fallback exists. This is unacceptable risk.

Key questions: What breaks if this service fails? How likely is failure? How hard is it to switch to an alternative? Is this service core infrastructure or a nice-to-have feature?

AI-Assisted Building Models

Decide when the AI is right and when it is wrong

16. The AI Review Checklist

Decides: Whether AI-generated code is production-ready

When to use: After AI generates any code before you commit it

AI models default to the “happy path,” writing code for a perfect world where inputs are valid, APIs never fail, and bad actors don’t exist.

AI has five predictable blind spots. Check these every time:

✅ Validation: Does it validate user input on both frontend and backend?

✅ Error handling: What happens when API calls fail, files are missing, or data is malformed?

✅ Edge cases: What if the user uploads a 500MB file? Enters emoji? Submits the form twice?

✅ Security: Does it sanitize inputs? Check permissions? Prevent injection attacks?

✅ Performance: Will this work with 1,000 records? What about 100,000?

Example: AI generates a file upload function.

What AI probably included: Basic upload logic, saving to storage, returning success.

What AI probably missed:

File size limits (user uploads 2GB video, server crashes)
File type validation (user uploads .exe file, security risk)
Error handling if storage is full
What happens if upload is interrupted
Duplicate filename handling

Run through the checklist. Add what’s missing.

17. The Feature Architecture Sketch

Decides: How to structure a feature before prompting AI

When to use: Before building any non-trivial feature

Five-minute sketch saves hours of AI going in circles. Map the data flow: User action → Frontend → Backend → Database → Response

Example: Building a “save for later” feature for articles.

Quick architecture sketch:

1. User clicks "Save" button on article 
2. Frontend: Disable button, show spinner
3. Frontend: Send POST to /api/saves with article_id
4. Backend: Check if user is authenticated
5. Backend: Check if article exists
6. Backend: Check if already saved (prevent duplicates)
7. Backend: Insert into saves table with user_id + article_id + timestamp
8. Backend: Return success with saved article data
9. Frontend: Update UI to show "Saved" state, enable button
10. Handle errors: Not authenticated, article not found, database error

Now when you prompt AI, you give it this sketch. AI knows exactly what to build. Without the sketch, AI makes assumptions and you spend an hour iterating.

Key questions: What triggers this feature? What data moves where? What can go wrong at each step? What does success look like? What does failure look like?

18. The Context Window Strategy

Decides: What information to include in your AI prompts

When to use: Starting any new feature or debugging complex issues

Strategic context makes AI 10x more useful. Random context makes it confused.

What to include:

Database schema (relevant tables only)
Existing code patterns from your project
Error messages (full stack trace)
Specific requirements and edge cases

What to skip:

Implementation history (”I tried X then Y”)
Vague goals (”make it better”)
Unrelated code
Your entire codebase

Example of a good prompt:

I need to add email validation to my signup form.

Current schema:
users table: id, email, password_hash, created_at

Current pattern (from login.ts):
We use Zod for validation
We return errors as {field: string, message: string}
We validate on both frontend and backend

Requirements:
Check for valid email format
Check if email already exists (return friendly error)
Case-insensitive email check
Trim whitespace before validating

Generate the validation function for backend.

This prompt includes schema, existing patterns, and specific requirements so AI can generate exactly what you need.

19. The Iteration Pattern

Decides: How to improve AI output without starting over

When to use: When AI code almost works but has issues

Iterate surgically. Point to the specific problem and requested change.

The pattern: (1) Identify the specific line or section, (2) Explain what’s wrong, (3) State exactly what you want instead.

Bad iteration: “This doesn’t work. Make it better.”

Good iteration: “The form submits successfully but doesn’t show a success message. Add a toast notification after line 47 that says ‘Settings saved’ and clears after 3 seconds.”

Bad iteration: “Add error handling.”

Good iteration: “Add a try-catch around the API call on line 23. If it fails, set error state to ‘Unable to load data. Please try again.’ and show it in a red alert box.”

20. The AI Blind Spot Map

Decides: What categories of problems to always check manually

When to use: Any AI-generated feature touching real users

AI writes code for a single user in a perfect vacuum, consistently missing the “invisible” systemic chaos.

AI has predictable blind spots across five categories:

1. Race conditions: Two users click at the same time—does data get corrupted?

2. Proper validation: Frontend validation exists, but does backend validate too?

3. Edge case handling: Empty arrays, null values, missing data

4. Security: Authentication checks, permission verification, input sanitization

5. Async logic: Promises, error handling in async operations, loading states

Build a habit of checking this manually as from experience I can tell you that AI misses these categories almost every time…

Example: AI builds a “delete account” feature. Check the blind spots:

Race condition: Can user trigger delete twice? Add request debouncing
Validation: Does it check if user is deleting their own account? Add permission check
Edge cases: What if user has active subscriptions? Add validation before delete
Security: Does it require password confirmation? Add confirmation step
Async: Does it handle database errors? Add error handling and rollback

Without this checklist, you ship code with security holes and broken edge cases.

Product Growth Models

Decide how to expand your product offering and what to charge for it

21. The Pricing Validation Test

Decides: Whether your pricing makes sense to buyers

When to use: Setting initial pricing or considering changes

Show your pricing tiers to 10 target users. If they can’t choose a tier in 30 seconds, your pricing is broken.

The test reveals:

Can users self-identify which tier fits them?
Do they understand the value difference between tiers?
Are tier names clear (not cute)?
Do limits make sense?

Example of bad pricing:

Starter: $19/mo - “For individuals”
Growth: $49/mo - “For growing teams”
Pro: $99/mo - “For professionals”

User confusion: “I’m an individual but also professional. I’m not growing but I have a team of 2. Which tier?”

Example of good pricing:

Solo: $19/mo - Up to 5 projects, 1 user
Team: $49/mo - Up to 25 projects, up to 5 users
Business: $99/mo - Unlimited projects, unlimited users

User clarity: “I have 3 projects and work alone. Solo plan.” Decision made in 10 seconds.

Key questions: Can users identify their tier based on concrete limits? Do tier names describe who it’s for or how much they can do? Would you be able to choose if you were seeing this for the first time?

22. The Impact vs. Effort Matrix

Decides: Which features to build next

When to use: Feature prioritization and roadmap planning

True velocity is about aggressively filtering out “Low Impact, High Effort” traps that feel productive to build but deliver nothing to the user.

Plot every potential feature on two axes: User impact (low to high) and Development effort (low to high).

Four quadrants:

High impact, low effort: Build these first (quick wins)
High impact, high effort: Build these next (major features)
Low impact, low effort: Build if you have spare time (nice-to-haves)
Low impact, high effort: Never build these (time sinks)

Features under consideration example:

High impact, low effort:

Add password reset link to login page (1 hour, prevents 20% of support tickets)

High impact, high effort:

Build API for integrations (2 weeks, enables enterprise customers)

Low impact, low effort:

Add dark mode (3 hours, some users will appreciate it)

Low impact, high effort:

Build custom analytics dashboard (3 weeks, competitors exist, users won’t switch for this)

Build in this order: password reset → API → dark mode when slow → skip custom analytics.

Key questions: Is this feature actually valuable or just fun to build? Can we get 80% of the impact with 20% of the effort? If we don’t build this, will users actually leave?

23. The Five-User Interview Pattern

Decides: What users actually need vs. what they say they want

When to use: Planning new features or understanding why adoption is slow

Just five conversations focused on past behavior can reveal more actionable data than 1,000 surveys asking about future wishes.

The pattern:

How do you currently solve [problem]? (Reveals workarounds)
Walk me through the last time you did [task]. (Actual behavior)
What’s frustrating about how you do it now? (Real pain points)
What have you tried to fix this? (Shows urgency)
If we solved this, what would you do differently? (Validates impact)

What you’re listening for: Patterns across multiple users. If 4 out of 5 mention the same workaround, that’s your feature opportunity.

Example: You’re building a content calendar tool. User interviews reveal:

5/5 users currently use Google Sheets
4/5 users manually check LinkedIn/Twitter to see what competitors posted
5/5 users forget to repurpose content across platforms
2/5 users want AI writing assistance (not a pattern yet)

Result: Build competitive content tracking and cross-platform reminders. Leave AI writing for later because there isn’t enough demand signal.

Key questions: Did they complain about a problem, or did they prove they are trying to solve it? Am I listening to the loudest user or the recurring pattern? Did I ask “would you use this” (bad) or “how do you do this now” (good)?

24. The One Metric Focus

Decides: What success metric this feature moves

When to use: Before building any feature intended to improve the product

Shipping code without a defined success metric is just recreational engineering.

Every feature needs one primary metric that defines success.

Shift from “Building” to “Solving”:

Bad planning: “We’re building a referral program because it would be cool.”
Good planning: “We’re building a referral program to increase new user signups by 20%. Success = 1 in 5 users refers someone.”

More examples:

“Add onboarding tutorial” → Metric: Increase activation rate (users who complete first task) from 40% to 60%
“Build API documentation” → Metric: Reduce API-related support tickets by 50%
“Add social proof to landing page” → Metric: Increase conversion rate from 2% to 3%

Key questions: What specific metric will move if this works? How will we measure it? Do we have a baseline for that number right now? If the metric doesn’t move, will we kill the feature or iterate on it?

25. The Pivot vs. Persist Framework

Decides: When to change direction vs. keep iterating

When to use: When growth stalls or user feedback is consistently negative

Abandoning a good idea because of bad execution is a tragedy, but polishing a product nobody wants it’s the fastest way to bankruptcy.

Pivot when:

❌ Users consistently say “I don’t have this problem” (Problem validation failed).
❌ Free users like it but nobody will pay (Value proposition broken).
❌ Churn is high because the product doesn’t solve a core need.
❌ You repeatedly hear “I’d use this if it did X instead” (Wrong solution).

Persist when:

✅ Users confirm the problem is real and painful.
✅ Some users are willing to pay but pricing/packaging needs work.
✅ Churn happens because of execution issues (bugs, missing features).
✅ You hear “I love this but wish it had Y feature” (Right direction, needs iteration).

Example: You built a project management tool for freelancers.

Pivot Signal: After 6 months, users say, “I don’t actually need project management—I just work on one project at a time. I need invoicing.” → Problem validation failure. Pivot to invoicing.
Persist Signal: Users say, “I love this but it’s missing recurring tasks and a mobile app.” → Execution issue. Persist and build the missing features.

Key questions: Are users complaining about bugs (fix it) or the concept (kill it)? Do they wish it worked better, or do they wish it was something else entirely? Is the refusal to pay about the price or the value?

26. The Feature Kill Switch

Decides: When to remove features that aren’t working

When to use: Regular product audits and when considering feature expansion

Every unused feature is a permanent tax on your codebase that slows down every future deployment.

“Zombie” Feature Tax:

Maintenance Burden: You still have to debug, explain, and test code that nobody uses.
Interface Clutter: More buttons mean more confusion for new users trying to find the core value.
False Confidence: Usage metrics look healthy overall, but the engagement is diluted across 20 mediocre features instead of 3 great ones.

Kill Switch Process:

Identify: Flag features used by < 5% of users in the past 30 days.
Investigate: Is it broken, hidden, or just useless?
Announce: Give users 30 days notice to save their data.
Delete: Remove the code entirely.
Listen: If nobody complains, you just made your product better.

Example: Monthly Feature Audit

Core workflow: 100% usage
Export to CSV: 65% usage
Custom templates: 45% usage
Bulk actions: 25% usage
Custom emoji reactions: 3% usage → Kill this
Calendar view: 2% usage → Kill this

Key questions: Does this feature pay rent? If we deleted this tomorrow, would our support inbox actually notice? Are we keeping this because it adds value, or just because we already wrote the code?

This is a lot. You don’t need to memorize all 26 models right now.

Think of this as your 2026 reference guide. Bookmark it and come back when you’re facing a specific decision, like: should I build this feature, how do I price this, is this AI code production-ready, which feature matters most?

The mental models you use most often will become instinctive.

The Gold Nugget 💡

Here’s how to actually use these mental models: use the 5-Minute Product Think framework.

Before you prompt AI or write any code, spend five minutes asking which mental models apply. Write out 3-5 questions based on those models. Use the answers to guide what you build.

Copy-paste ready template:

Before I build [FEATURE]:
1. Product Validation: Is this a hair-on-fire problem or nice-to-have?
2. User Experience: What does the empty state show and what action should users take?
3. Technical Decision: Is this core to my value or should I use a third-party service?
4. What could go wrong: What edge cases will break this in production?
5. Success looks like: What metric moves if this feature works?

Adapt the questions based on which models fit your situation.

Building a new feature? Use product validation and UX models.

Reviewing AI code? Use the AI review checklist and good enough threshold.

Choosing your tech stack? Use build vs. buy and complexity budget.

This framework works because it forces product thinking before code thinking. It catches misaligned expectations when changes cost nothing and gives AI better context for what you actually need.

Let me show you this in action with a real scenario:

You’re thinking of adding social sharing to your app. Five-minute product think:

Hair-on-fire problem (Model #3): Are users actively asking to share? Check support tickets and interviews. Result: Nobody mentioned sharing in the last 50 conversations. Not urgent.
Jobs-to-be-done (Model #6): What job would sharing solve? Maybe: “Get my teammates to sign up.” But is that really how B2B tools spread? Result: Direct invites probably work better than social sharing.
Build vs. buy (Model #11): If we build this, use a library or write custom? Result: Social sharing libraries exist, but...
Impact vs. effort (Model #22): High or low impact? Low (nobody’s asking). High or low effort? Medium (2-3 days with testing). Result: Low impact, medium effort = don’t build.
One metric (Model #24): What metric would this move? Signups? But we get 90% of signups from SEO and direct outreach, not social sharing. Result: Won’t move our key metrics.

Decision after 5 minutes: Skip social sharing. Build the team invitation feature instead (users actually asked for this).

See how the models work together? You prevented wasting 3 days building something nobody needs.

When to skip this: Quick experiments, throwaway prototypes, learning exercises, anything that won’t touch real users.

When it’s essential: Features that real users will interact with, technical decisions that affect your architecture o product changes that impact revenue.

The five minutes you spend thinking through mental models saves hours of building the wrong thing. And hours of debugging the right thing built wrong.

Let’s Connect

Which of these 26 mental models do you wish you’d known about six months ago?

Or what product decision are you facing right now that could use a mental model? Reply and tell me. I read every response and often turn common questions into future articles.

Build With Better Judgment

Bookmark this page. Use it all year. Come back when you’re facing a decision and not sure how to think it through.

You’ll still build fast with AI but now you’ll just build the right things.

Mental models are how experienced builders think. Now they’re how you think too.

Accepting AI's First Answer Is Bad For Your Code

Dan Cucolea — Tue, 16 Dec 2025 14:00:44 GMT

When you ask a waiter “What’s good?”, they point to the most popular dish. The safe recommendation that works for most customers, regardless of your taste.

AI does the same thing when you ask it to solve a technical problem. It surfaces the pattern that appears most frequently in its training data. The approach from thousands of tutorials. The solution that statistically safest to suggest.

That popular solution might not fit your constraints at all.

Why AI Defaults to Generic Answers

AI generates code through pattern matching. Ask how to validate form data, and you get the approach used in thousands of Stack Overflow answers.

Even when you give AI full context about your codebase, it still defaults to the most common pattern first. It optimizes for statistical safety over contextual fit. The model recognizes “form validation” and surfaces the approach seen most often, regardless of whether batch processing or real-time validation better matches your production constraints.

Experienced developers work differently. Before writing code, they mentally sketch multiple approaches while considering edge cases, production constraints, and creative alternatives that might reuse existing infrastructure.

Every technical decision involves trade-offs. When you accept the first idea, you miss better options that actually fit your situation.

What Determines the Right Answer

Your constraints determine which solution works.

Timeline — Are you shipping a client demo Friday or building infrastructure that runs for years?

Scale — Are you processing 10 requests daily or handling 1,000 concurrent users?

Infrastructure — What systems already exist that you could repurpose?

Maintenance burden — Who maintains this code six months from now?

AI won’t evaluate these factors unless you explicitly ask it to compare options. It suggests the highway route because “that’s what most people take,” without knowing you need the back roads that guarantee arrival time.

The Cost of Accepting First Answers

You ship the feature. Two days later, intermittent timeouts appear in production.

You spend six hours debugging and trace the issue to individual API calls where batch processing would have prevented the problem entirely. You never saw the alternative approach because AI gave you the pattern it sees most often in tutorials, not the one that handles your data volume gracefully.

The fragile solution ships when a more stable option accomplishes the same goal.

In the end, you end up burning hours debugging problems that only exist because you chose the wrong architecture.

How to Force Better Thinking

Whenever AI presents a solution, pause before you implement it.

Ask: “Show me different approaches with trade-offs.“

Be specific about what matters: “Compare maintenance burden versus implementation speed.”

Watch how AI structures the response. The quick version uses minimal code and gets functionality working fast but might break under edge cases. The robust version handles errors gracefully and scales to production load but introduces more complexity. The creative version finds unconventional approaches that solve the problem differently.

That third option will often surprise you. AI might suggest batch processing your requests, using a queue system you already have, or restructuring data flow so you make one call instead of hundreds.

When AI Gives You Generic Options

If AI provides variations of the same basic approach, push back.

Ask for fundamentally different architectures: “These all use the same pattern. Show me completely different ways to solve this like processing in batches versus real-time, or using a queue versus direct calls.”

If trade-offs are unclear, ask explicitly: “What do I gain and give up with each approach?”

This pattern works beyond initial feature building. Use the same prompt when you’re refactoring existing code.

The principle is the same, you need to get multiple perspectives, understand what you’re trading, then choose based on what actually matters for your situation.

Prompt For A Better Architectural Solution

Copy this prompt structure and use it every time AI gives you an architectural solution:

Show me different approaches for [feature/problem]:

Quick version (minimal complexity, MVP-ready)
Robust version (production-ready, handles edge cases)
Creative version (unconventional or reuses existing infrastructure)

For each approach, explicitly state:

- What it optimizes for?
- What trade-offs I’m making?
- When I’d choose this over the others?
- What breaks first when this approach fails?

This structure forces AI past its default instinct to give you the most popular answer. Plus, the explicit trade-off request transforms your decision-making from implicit guesswork to transparent evaluation.

When It Actually Matters

Not every decision needs multiple options.

You should stick with AI’s first suggestion and move on for things like button colors, padding and margin, variable names or even simple utility functions.

Save this technique for architectural decisions that shape how your code works:

Structuring state management;
Planning error handling strategies;
Choosing which API pattern to use;
Deciding between client-side and server-side rendering;
Selecting data flow patterns (polling vs webhooks vs server-sent events);

These decisions ripple through your codebase.

When you get them right the first time, you prevent days of refactoring when reality does not match your assumptions.

This Should Become Instinct

Stop accepting first answers reflexively and start recognizing architectural decisions before you (use AI to) write code.

When AI suggests an approach, your immediate thought should be “What else exists?” instead of “Let me implement this.”

Build features that fit production constraints instead of tutorial constraints. Your code works reliably because you chose the architecture that matches your actual traffic patterns and infrastructure.

The five minutes up front stop feeling like extra work, rather make you feel and ACT as a software architect.

This Week’s Discovery - PixelLab

I just adore this tool! It generates pixel art sprites and keeps them visually consistent across animations and rotations. You describe what you want (”walking animation” or “attack motion”) and it outputs sprite sheets that actually match your game’s style instead of giving you random variations like most image AI does.

I’m not building a game, but when and if I will then I’ll definitely give it a try. Maybe I’ll even use it for a website or app, who knows. Check them out at pixellab.ai.

Let’s Connect

Do you accept AI’s first solution and build it, or do you ask for alternatives before you commit to code?

Reply and tell me about a time comparing options saved you from shipping the wrong architecture, or a time you wish you’d seen the alternatives before building.

Why AI Gets Stupid Deep in the Thread

Dan Cucolea — Tue, 09 Dec 2025 13:35:53 GMT

I was 25 messages deep in a Kilo Code chat, debugging a Stripe payment integration. The first 15 messages were solid and the whole dev experience was great. AI caught edge cases and suggested clean fixes, basically understood exactly what I needed.

Then around message 20, something changed.

Responses got vaguer and suggestions referenced files I wasn’t even working on anymore. I figured something was wrong, then I checked the token count and knew for sure. My thread reached 115k tokens.

Every file I’d @ mentioned back in message 3 was still being re-read in message 25, even though I’d moved on to completely different parts of the feature. Not to mention the cost of each new message increased exponentially.

The chat had rotted.

Your Chat Is Rereading Everything

Here’s what happens when you’re working in Kilo Code, Windsurf, Antigravity, Claude Code, or any AI editor. You @ mention three files in message 1. AI reads them. Makes sense. But by message 10, when you’re asking about a completely different part of your codebase, AI is still re-processing those original three files from message 1.

By message 20, AI re-reads the entire conversation history with every new prompt you send. Every file you ever mentioned, every response it generated, every question you asked. All of it gets processed again just to answer your latest question.

The cost compounds with each message, but worse, the quality degrades.

Somewhere past 100k total tokens (not per message, but 100k for the entire accumulated chat history), AI performance starts falling off a cliff.

The Chroma research study from July 2025 tested this across 18 modern models including GPT-4.1, Claude Opus 4, and Gemini 2.5 Pro. Performance drops 30-50% on tasks that should be simple when context exceeds certain thresholds.

You’re not imagining it. The research proves context rot is real and measurable.

Say you’re working on a login feature, you mention 4 files in the first few messages debugging form validation. Then you shift to working on session persistence.

By message 20, AI is still carrying those original 4 validation files in context even though they’re completely irrelevant to sessions.

Each new message processes more irrelevant history, degrading quality while burning tokens (and money).

Why 2 Million Token Windows Can Actually Hurt You

The industry keeps bragging about bigger context windows. Grok 4.1 Fast now has 2 million tokens while Gemini 3 and Sonnet 4.5 both have 1 million. Sounds impressive. But when it comes to code, those massive windows can backfire.

Modern AI code editors maintain full conversation history to provide continuity.

That’s actually useful, until it isn’t. Each message you send, AI re-processes everything: all previous messages, all @ mentioned files from the entire chat, every response it generated.

The Chroma study proves that even models claiming million-token windows show measurable performance degradation past 100k tokens on real tasks. Context rot happens at the architectural level, regardless of how large the window claims to be.

More Space Means More Places to Lose Focus

The Adobe research from February 2025 demonstrates that needle-in-a-haystack accuracy plummets as context grows, even on modern models. When you add reasoning complexity (exactly what happens when debugging code), performance degrades faster.

Think of it like trying to find a specific wrench in a toolbox versus searching through an entire garage.

More space means more places to lose track of what matters.

Furthermore, Anthropic’s research explains that LLMs have a finite “attention budget” that spreads thinner as tokens accumulate. Every file you’ve ever @ mentioned in the chat consumes part of that budget, even if it’s no longer relevant to your current question.

By message 25, AI is spending attention on 20 files when you only care about 2.

The Deliberate Constraint of Small Windows

Consider why Claude Opus 4.5 ships with a relatively small context window compared to competitors boasting million token windows. Anthropic could have made it bigger for their SOTA model. They chose not to.

Smaller windows force you to be selective about context, which paradoxically produces better code responses. The constraint becomes a feature: you can’t dump your entire codebase, so you have to think about what actually matters.

How to Keep Your Chats Under 100k Tokens

Watch your cumulative token count, not per message, but total chat history. Research shows degradation starts around 100k total tokens.

Use these three filters before @ mentioning any file:

Is this file directly involved in what I’m working on right now? Right now, not “earlier in this chat.” If you mentioned auth files 15 messages ago when debugging login but now you’re working on session storage, don’t keep the auth files in context. Start a new chat focused on session storage.

Will AI need to see this file’s code to answer my current question? Don’t include files that “might be helpful.” Only include files AI must literally read to answer your question. If you’re asking about error handling logic, AI doesn’t need your frontend component files. If you’re asking about a specific function’s behavior, AI needs that file and maybe its direct imports. Nothing else.

Am I still working on the same feature I started this chat for? If you began the chat debugging form validation and you’ve now pivoted to refactoring the API endpoint, that’s a different feature. Start fresh. The validation files rotting in your context from 18 messages ago are degrading AI’s focus on the API work.

Structure Your Chats Around Features

Set a hard reset at 100k total tokens. Most AI code editors show token count somewhere in the UI. Watch it. When you hit 90k-100k for the entire conversation history (all messages, all files, all responses combined), stop the chat regardless of whether you’ve “finished” the feature.

Start new chats for each distinct feature or problem.

Don’t debug login persistence, then pivot to building a password reset flow in the same chat. The login context pollutes the password reset work because AI re-reads everything with each new message.

Front-load the feature boundary in message 1.

Explain what you’re working on in 2-3 sentences, then @ mention only the files directly involved. Research proves AI has strongest recall for context at the beginning of conversations, so make that first message count.

Watch for These Red Flags

If you’re @ mentioning new files but your token count is jumping by 40k instead of 15k, you’re carrying massive history. If AI responses get noticeably slower (it’s processing more tokens), you’ve passed the efficiency threshold. If AI starts giving generic advice instead of specific code suggestions, the context has rotted.

Large context windows let you accumulate more junk before you notice the degradation.

The 60-Second Reset That Saves Hours

Watch your total chat token count. When any conversation approaches 100k tokens (usually 15-25 messages depending on how many files you’re @ mentioning), force yourself to start a new chat.

Before you do, spend 60 seconds writing a 3-4 sentence summary of what you learned:

Previous chat identified that Remember Me checkbox issue is in authMiddleware.js line 47. Cookie maxAge uses seconds, should be milliseconds. Tested fix but session.store config also needs updating. Files to focus on: authMiddleware.js (already know the bug) and config/session.js (need to check store settings).

Start the new chat with this summary and @ mention only the 2 files you need right now. Don’t bring forward files from the old chat unless they’re directly relevant to your next step. The summary gives AI continuity without the 95k tokens of deprecated context.

The Chroma research proves performance degrades past 100k tokens even on cutting-edge models.

You improve output quality by preventing context rot.

AI in message 3 of a fresh chat dramatically outperforms AI in message 23 of a rotted chat, even when asking the exact same question.

For quick one-off questions, token count rarely matters. But for feature development, debugging sessions with multiple dead ends, or refactoring work, the 100k reset is non-negotiable.

The research showing 30-50% performance drops in long contexts proves this strategy delivers better code, not just token savings.

This Week’s Discovery

I haven’t tested this yet but I’m planning to soon: MCP Memory Keeper Server.

It’s an MCP server designed to help Claude Code and other MCP-compatible editors maintain context across sessions without token bloat. It works by storing key decisions, progress notes, and architectural context separately from conversation history.

Instead of dragging 100k tokens of chat history forward, you reference stored context that doesn’t count against your window. The concept addresses exactly the problem I’ve been coming across: maintaining continuity across multiple chat sessions without starting from zero, while avoiding rotted context.

Worth exploring if you’re regularly hitting the 100k reset threshold.

Let’s Connect

When do you reset your AI coding chats? Do you watch token count, count messages, or just feel when AI stops being useful?

Reply and tell me your threshold. I’m especially curious if you’ve noticed the degradation around 100k tokens, or if you’ve been pushing past 200k and wondering why responses got worse.

How to Prompt AI for Consistent JSON Responses

Dan Cucolea — Tue, 02 Dec 2025 13:44:56 GMT

You just used AI to generate your API integration code, tested it locally, and deployed it to production because it seemingly worked perfectly. Two hours later, your logs are filled with parsing failures and users cannot complete actions because “Invalid JSON” errors are popping up everywhere. The AI gave you working code, but the problem is that it only worked in your controlled test environment with your specific input.

It happened to me so many times I lost count, so I’m going to share one of the best ways to get your AI to generate valid json, every single time.

Bad JSON Means High Costs

When you are building features that depend on structured data like API integrations, database operations, or configuration files, JSON consistency directly determines whether your app works or breaks. A single malformed response can quickly cascade into hundreds of failed user actions, corrupt database writes, and support tickets flooding your inbox.

While AI generates JSON that looks correct during development, production environments expose inconsistencies like missing commas, trailing commas in strict parsers, unescaped quotes in user-generated content, and Unicode characters from international users. These small formatting errors crash entire features, so you need AI to output valid and production-ready JSON consistently instead of just succeeding in your local tests.

Airport Security Model

Airport security examines your documents multiple times at check-in, security, and the gate because mistakes are expensive to fix later. JSON validation works the same way because AI generates structurally sound JSON in controlled conditions but often breaks under real-world variance. That’s why you need to build multiple validation checkpoints to catch these errors.

Most builders stop at the prompt, but production-ready apps require five distinct checkpoints to ensure reliability.

Most Common Ways AI Breaks Your Data

Syntax Errors: Missing or extra commas, brackets, or quotes break JSON.parse() immediately on your server. For example, AI often adds a trailing comma after the last object property or forgets to close a nested object properly. While some lenient parsers might handle this, standard Node.js or Python backends will throw an exception and crash the request before your logic even runs.

Escaped Character Traps: One of the most insidious errors occurs when AI double-escapes characters inside the JSON string itself (e.g., returning \\\\” instead of \\”). This technically creates a valid string but invalid JSON content for your parser, causing it to fail when processing fields that contain quotes, backslashes, or special characters.

Structure Mismatch: This happens when you get valid JSON in the wrong shape, such as receiving {”title”: “My Article”} when you actually need {”article”: {”title”: “My Article”}}. Your backend code expects nested objects but receives flat structures, which causes undefined property errors that can take down your entire API endpoint.

Type Confusion: AI sometimes returns strings when you need numbers or arrays when you need objects. This results in valid JSON with broken logic. An example is when a count field comes back as “25” (string) instead of 25 (number), which breaks database schema validation and any math operations you perform on that data.

Truncated Responses: When you request a large dataset, some models will hit their output token limit and cut off the JSON mid-stream (e.g., ending with ... or just stopping). This leaves you with an incomplete, unparsable string. The reliable fix is to request data in smaller chunks—generating multiple subsets and concatenating the results in your code rather than asking for one massive payload.

The 5-Checkpoint Framework for Bulletproof JSON

1. Be Explicit in Your Prompt

Don’t say: “Return the SEO data as JSON”

Say: “Return ONLY valid JSON with no additional text. Use this exact structure: {”title”: string, “description”: string}“

2. Provide a JSON Schema

The most reliable way to get consistent JSON structure is to give AI an exact schema to follow.

JSON Schema defines the structure, types, and requirements for your data. Instead of describing what you want in natural language, you provide a formal specification that eliminates ambiguity.

Add this to your prompt:

“Return JSON matching this exact schema. Do not add any fields not in the schema. All required fields must be present:

{
  “type”: “object”,
  “properties”: {
    “title”: {
      “type”: “string”,
      “maxLength”: 70,
      “description”: “An engaging, SEO-friendly article title”
    },
    “description”: {
      “type”: “string”,
      “maxLength”: 160,
      “description”: “A concise summary of the article content”
    }
  },
  “required”: [
    “title”,
    “description”
  ],
  “additionalProperties”: false
}

Why this works: Schemas eliminate type confusion and structure mismatch because the model validates its output against the schema pattern during generation. The additionalProperties: false flag is particularly powerful because it strictly forbids the AI from hallucinating extra fields you didn’t ask for. This catches errors before they reach your code. Learn more about schema properties at the OpenAPI Schema specification.

3. Request Code Fences

Add to your prompt: “Wrap the JSON in markdown code fences with json syntax highlighting”

This prevents AI from adding explanatory text before or after the JSON because extra text breaks parsing when you extract the response.

4. Validate Before Using

Never assume AI output is valid. Always wrap in try-catch:

try {
  const data = JSON.parse(aiResponse);
  *// Use data here*
} catch (error) {
  console.error(’Invalid JSON from AI:’, error);
  *// Handle the error gracefully*
}

5. Check Structure After Parsing

Valid JSON doesn’t guarantee correct structure:

function validateSeoData(data) {
  if (!data.title) return false;
  if (typeof data.title !== ‘string’) return false;
  if (typeof data.description !== ‘string’) return false;
  return true;
}

Red Flags and What to Watch For

🚩 AI adds explanation text before or after JSON: This breaks parsing. AI models are trained to be conversational and often add context before JSON blocks, so you must always request “ONLY valid JSON, no additional text.”

🚩 Nested objects are inconsistent: AI formats the first object correctly but makes errors in deeply nested structures. The model’s attention weakens as JSON depth increases, which leads to malformed brackets and missing commas three or four levels deep.

🚩 Numbers as strings: AI often wraps numbers in quotes because it sees numbers as text tokens rather than numeric types. You need to be explicit that “count should be a number, not a string.”

🚩 Double-escaped characters in strings: AI returns \\\\” instead of \\” for quotes inside strings because the model treats escape sequences as text patterns rather than functional syntax.

Watch Out For Escaped Character

One of the most frustrating JSON issues occurs when AI returns responses with escaped characters inside the JSON itself.

Example of what goes wrong:

What you expect: {”title”: “The \\”Best\\” Guide”}
What AI sometimes returns: {”title”: “The \\\\\\”Best\\\\\\” Guide”}

The AI double-escapes quotes, backslashes, and special characters. When you parse this JSON, you get literal backslash characters in your strings instead of properly escaped quotes. This breaks things when you try to display the data to users or pass it to other systems that expect clean strings.

How to prevent it:

Add to your prompt: “Use proper JSON escaping. Quotes inside strings should use single backslash escape (”), not double backslash (\”).”

Hidden Edge Cases

Trailing commas: AI adds commas after the last item in objects or arrays. Strict JSON parsers reject this immediately even though JavaScript often accepts it, so this breaks in production environments using different parsers.

Unescaped special characters: If your data contains quotes or backslashes, AI often forgets to escape them. A title like “O’Brien’s Guide” will break your JSON when AI returns “title”: “O’Brien’s Guide” instead of “title”: “O\\’Brien’s Guide” if your parser is strict about apostrophes.

Inconsistent null handling: AI randomly switches between null, “null”, empty string, or omitting the field entirely. Your application logic assumes one pattern but receives variations, which causes conditional checks to fail unpredictably.

My Production Safety Net

You have likely spent an hour debugging a critical failure only to discover the culprit was a single missing comma. In production, that one missing comma is not just a syntax error. It represents hundreds of failed user requests and corrupted data that piled up before you even noticed the issue.

Here’s the technique that changed everything for me:

Use jsonrepair to automatically fix malformed JSON.

import { jsonrepair } from ‘jsonrepair’;

try {
  *// Try parsing normally first*
  const data = JSON.parse(aiResponse);
} catch (error) {
  *// If parsing fails, attempt repair*
  try {
    const repairedJson = jsonrepair(aiResponse);
    const data = JSON.parse(repairedJson);
    console.log(’JSON repaired successfully’);
  } catch (repairError) {
    console.error(’Could not repair JSON:’, repairError);
    *// Handle the error*
  }
}

The jsonrepair library automatically fixes common JSON formatting issues like adding missing commas, removing trailing commas, fixing unescaped quotes, and repairing truncated JSON.

Think of it as insurance. You hope you never need it, but when production breaks at 2 AM, you will be grateful it is there. And don’t ask me how I know that…

Tool of the Week: Zod

Zod - TypeScript-first schema validation

Once you have valid JSON from AI, you still need to validate that the structure matches what your app expects. Zod lets you define schemas and validate data in one line. TypeScript validates types at compile time, while Zod validates data at runtime.

Example:

import { z } from ‘zod’;

const SeoSchema = z.object({
  title: z.string().max(70),
  description: z.string().max(160)
});

*// Validate AI output*
const result = SeoSchema.safeParse(aiData);
if (!result.success) {
  console.error(’Invalid structure:’, result.error);
}

It catches structure mismatches and type confusion instantly, so pairing it with jsonrepair gives you bulletproof AI output handling.

Final Thoughts

Valid JSON is boring until it breaks production at the worst possible time. Build the checkpoints now and thank yourself later.

Let’s Connect: What’s your strategy for handling AI-generated structured data? Do you validate everything, or trust AI until it breaks? Reply and tell me about the weirdest JSON error you’ve debugged.

How To Architect A Feature In 5 Minutes Before Talking To AI

Dan Cucolea — Tue, 25 Nov 2025 14:32:00 GMT

Yesterday I opened my server logs and saw my API costs had spiked for no obvious reason.

I was building a new feature and thought I’d be clever. I told the AI: “Just reuse the logic from the other generator.” The AI said “Sure!” The UI worked perfectly when I tested it.

But I never looked at what was happening underneath.

The AI had built something that made three separate calls to my server every time a user clicked one button. The feature worked on my screen, but it was costing me money with every click and making users wait longer than they should.

AI Will Make Anything Work Even if It’s Wasteful

One of the first things you’ll learn building with AI tools is that they’ll make anything work on the surface, even if it’s wasteful underneath.

When you ask AI to build a feature, it assumes everything will go perfectly. It assumes your backend is already set up exactly right. It assumes you don’t care how many times it calls your database or how long users have to wait. It assumes you know what you’re doing.

AI is incredibly fast at writing code but it doesn’t think about what happens when that code runs in the real world, with real users.

That’s why you have to treat AI like a brilliant junior developer who will take shortcuts whenever you aren’t watching. Here’s what you need to know to actually make it work.

The 5-Minute Sketch That Saves Hours

Spend 5 minutes thinking before you start typing prompts.

Before you ask AI to build anything, draw what you actually want to happen. I’m talking about the data flow, basically what information moves where, and in what order.

When I saw those cost spikes, I stopped. I grabbed a piece of paper and drew what the AI had actually built. It was a mess of arrows going back and forth.

Then I drew what I actually wanted:

Browser calls the API;
Server gets the request;
Server computes and routes my message;
Server calls the AI and saves the result in the database;
The browser polls my database and shows the new information.

Once I saw it on paper, the problem was obvious. The AI was calling the save step twice and re-fetching data that was already in database. It tried to reuse logic from an old feature that worked differently.

This Is The Classic “Reuse this code” Trap

I was building a Meta Description generator for Yahini. I already had a Brief Generator that creates meta titles and descriptions along with a bunch of other content analysis and writing the brief.

I thought I’d be smart. I told the AI: “Repurpose the Brief Generator logic, but just return the meta title and description.”

The AI obliged. The feature worked. Users could generate meta information.

But here’s what I didn’t notice: the AI kept all the calls from the Brief Generator, then throwing all of it away and only showing the meta title/description.

I was paying for a full brief generation every single time someone just wanted a meta description. That’s like ordering a full meal at a restaurant, eating only the dessert, and throwing the rest away.

My prompt started with *reuse this to…* without thinking about what this actually did.

This is why the 5-minute sketch matters. If I’d drawn what I wanted before prompting and share it with the AI, it would have seen immediately that the Brief Generator did 10 steps and I only needed 3 of them.

4 Questions to Ask Before You Prompt

Run through these 4 questions for 5 minutes before you prompt and your AI code will most certainly be more reliable.

Think of these as your architecture checklist. I use these symbols to mark my sketch:

🚩 Red flag: What will break your feature
✅ Green flag: What makes it production-ready

1. What goes in?

Be specific about what data you’re sending and what format it’s in.

🚩 Red flag: Vague descriptions like “user data” or “form values” leave too much room for AI to guess wrong.

✅ Green flag: Write exactly what the user provides: “A URL (text), a tone choice (dropdown with 3 options: professional, witty, casual), and their user ID (number).”

Example: Instead of telling AI “handle the signup form,” say: “User enters email (must include @), password (minimum 8 characters), and checks a newsletter opt-in box (yes/no).”

2. What happens to it?

Trace the complete path your data takes from start to finish.

🚩 Red flag: Skipping steps like “validate” or “check permissions” because they seem obvious—AI won’t assume them.

✅ Green flag: Map every hop: “Browser → Server validates URL format → Server scrapes website → Server sends scraped text to AI → AI returns description → Server saves to database → Server responds to browser.”

Example: For a contact form, map the full path: “Server checks email is valid → Server checks for spam → Server saves to database → Server sends confirmation email → Server responds ‘Message sent’ to browser.”

3. What could slow this down?

Think about external dependencies and what happens if they’re slow or unavailable.

🚩 Red flag: Assuming external services (website scraping, AI APIs, payment processors) will always respond instantly.

✅ Green flag: Identify each external dependency and set realistic timeout expectations: “Scraping might take 5-10 seconds. AI call usually takes 2-3 seconds but could take up to 10.”

Example: For a feature that checks if a domain is available, note potential delays: “Domain lookup calls an external API—it might take 3 seconds or fail completely if the service is down.”

4. What happens when it breaks?

Think through (almost) every way this could fail and what the user should see.

🚩 Red flag: Only planning for the “happy path” where everything works perfectly.

✅ Green flag: List specific failure scenarios and responses: “If scraping fails → show ‘Couldn’t access that website, try another URL’ and don’t charge credits. If AI times out → show ‘Taking longer than expected, try again’ and don’t save partial results.”

Example: For a file upload feature, plan for: “File too large → ‘Maximum 5MB.’ Wrong file type → ‘Only PDF, DOC, or TXT files.’ Upload interrupted → ‘Upload failed, please try again’ and clean up partial files.”

Example time

Let’s say you’re building a feature that generates social media posts from a blog URL.

Before you prompt AI, spend 5 minutes on this:

Draw your data flow on paper:

User pastes blog URL and picks platform (Twitter, LinkedIn)
Your server fetches the blog content
Your server sends content + platform to AI
AI returns optimized post
Your server saves it and shows it to the user

Mark your 4 questions on the sketch:

What goes in? Blog URL (text, must start with http), platform choice (dropdown: Twitter/LinkedIn), user’s account ID
What happens? Browser → Server validates URL → Server scrapes blog → Server sends to AI with platform context → AI returns post → Server saves → Server responds
What could slow it down? Blog scraping might take 5-10 seconds if the site is slow. AI usually responds in 2-3 seconds. Total: plan for 15 seconds max.
What breaks? Blog URL invalid → show “Please enter a valid URL.” Scraping times out → show “Couldn’t access that blog, try another.” AI fails → show “Generation failed, try again” and don’t save anything.

Now you’re ready to prompt AI. Your prompt might look like:

“Create an action plan on how to build an API endpoint that takes a blog URL and platform choice (Twitter or LinkedIn). First validate the URL format. Then scrape the blog content with a 10-second timeout. Send the scraped content to OpenAI with context about which platform. Return the generated post. If scraping fails, return error message without calling OpenAI. If AI fails, return error without saving. Only save successful results to database.”

The AI will build exactly what you sketched because you thought through the flow first.

IMPORTANT - Use this kind of prompt to generate a more comprehensive action plan and only then start coding. I use an Architect mode in Kilo Code that creates a To Do list and then my other agents implement each item from that list.

Show AI a Picture, Not a Paragraph

Here’s how I fixed my expensive feature in 10 minutes.

I grabbed my rough sketch and uploaded the photo to the AI.

My sketch showed:

~~Brief Generator (full flow with 10 steps)~~ ← crossed out
New simple flow: URL → Scrape → AI → Save → Return
Notes in the margin: “Only need meta description and title, skip other stuff.”

My prompt was simple: “Rebuild this to match my sketch. Remove the extra steps.”

The AI understood immediately. It rewrote the code, removed the wasted calls, and cut the delay in half.

💡 The pattern: A rough sketch beats a detailed text explanation every time.

What to include in your sketch:

Boxes for each major step (Browser, Server, Database, External API)
Arrows showing what data moves where
Notes about what to validate or check
Cross-outs showing what NOT to do
Timing notes (”10 sec timeout here”)

You don’t need perfect diagrams. You need clarity about what talks to what and in what order.

Architecture Means Deciding Before Building

When developers talk about “architecture,” it sounds intimidating.

Architecture means deciding how the pieces of your feature will talk to each other before you build them.

No-code platforms make these decisions for you, usually poorly, especially when your prompts are vague. It’s up to you to orchestrate everything, and it’s easier than you think.

When you skip the architecture sketch, you end up debugging in production. A user clicks a button, something breaks, and you’re digging through server logs trying to figure out which of the five database calls failed.

When you sketch first, you know exactly what should happen. When something breaks, you can trace the flow on your sketch and find the problem in minutes.

The sketch becomes your debugging map.

✅ The test: If you can draw it on paper in 5 minutes, you’re ready to build it. If you can’t draw it, you don’t understand it well enough yet.

This Week’s Discovery: tldraw

I usually just use pen and paper, but when I need to share my sketch or save it for later, I use tldraw.

It keeps that hand-drawn feel, which stops you from obsessing over making it perfect. And when you need to share your architecture with AI, you can export the sketch and paste it directly into your prompt.

The hand-drawn style actually helps by keeping you focused on the flow instead of making it pretty.

Check Out The Past Editions

Let’s Connect

Next time AI-generated code isn’t working the way you expected, stop. Step away from the screen. Draw what you actually want to happen.

Did you discover a loop or redundancy you didn’t know existed? Reply and tell me.

Build smart,

Dan

Your Landing Page Is Probably Over-Engineered

Dan Cucolea — Tue, 18 Nov 2025 14:13:46 GMT

React is what most developers reach for first, wrapped in Next.js or Remix or just running through Vite.

That makes sense for products that behave like real apps, where the screen is constantly reacting to what the user does, but it quietly makes simple sites feel heavier than they should to be.

For most solo founders, the priority is a site that loads fast, feels snappy on cheap phones, and plays nicely with AI crawlers and search engines trying to understand what you actually do.

Imagine a landing page with a hero, three feature blocks, and an email signup form.

In a typical React setup, you are loading an entire framework just to make that form submit.

That often means shipping a bunch of useless JavaScript even though the page itself is mostly text and a couple of buttons.

This causes multiple issues, starting with visitors having to wait for JavaScript to parse before they can even scroll smoothly.

AI tools trying to summarize your site, or search engines like Google trying to index your copy, have to run your JavaScript first before they “see” your text.

That extra step can fail on slower devices, tighter crawl budgets, or when an AI assistant is racing through dozens of sites to answer a user’s question about “simple task management tools.”

How visitors and AI experience your stack

Picture someone on a train with spotty signal clicking your link.

They see your headline start to appear, then watch the layout shift three times as JavaScript loads, then wait for the “Sign Up” button to become clickable.

By the time the page finally loads, they have already spent a few seconds wondering whether your product will feel just as clunky.

Now picture an AI agent trying to figure out what your product does so it can recommend you to someone asking for help.

It lands on your site, waits for React to hydrate, tries to parse your state tree, and eventually gives up or grabs a half-rendered snippet that makes your product sound vague or broken.

React shines when the page is constantly changing based on what the user does: think dashboards, editors, or complex flows.

Marketing pages are different. They sit closer to a good PDF with a few buttons than to Figma or Notion. Their whole purpose is to help the visitor understand what you do and ideally take an action towards your conversion goal, be it to sign up or to download a resource.

React for apps, Astro for “reading”

The turning point for me was admitting that my main site behaves more like a magazine than an app.

People land there to understand the promise, skim through a few sections, maybe read a FAQ, and then decide if they want to try the product.

Astro fits that world because it builds pages as plain HTML first and then lets you sprinkle interactivity only where you truly need it.

The default experience puts content ahead of JavaScript, which lines up nicely with what search engines, AI crawlers, and impatient humans all tend to prefer.

For the product itself, React still plays a big role.

I use it heavily for real app features and tiny tools where it makes sense, often with AI helpers and Kilo Code (my lightweight editor setup) to move fast on more complex flows.

The site you hit first, the one where you decide if this thing is worth your time, stays much simpler and more focused on clarity than the app that sits behind it.

Hosting on Cloudflare Workers

Once the pages are built, they live on Cloudflare’s network as static files.

You can think of this as uploading a folder of prebuilt pages to a network of cities around the world.

The setup is three steps: build your site, run one command to push to Workers, and you are done. I do have a Github action setup that does this automatically which I will share in a later edition.

Static files are cheap to serve (basically free), and backend only gets involved when there is something truly dynamic to handle, like a form submission or a webhook callback.

From a reader’s point of view, the page shows up quickly from wherever they are, with no waiting for a single origin server halfway across the world.

From your point of view, it means one fewer thing to worry about, and one more piece of your stack that “just works” once you set it up.

From an AI crawler’s point of view, it means clean HTML that arrives fast and makes sense without needing to execute a bunch of JavaScript first.

If something does go wrong, you’re usually looking at a small, specific piece of logic instead of a giant app server.

A tiny Astro example that shows the difference

Here is a concrete look at how a page can be mostly “just content” with one small interactive piece.

You do not need to understand every symbol. The key idea is that almost everything is plain HTML, and only one piece is interactive.

This example shows the file structure of a typical Astro page. The top section (between the --- marks) runs at build time to prepare variables. The middle section is your HTML template. The <Counter /> component at the bottom is the only part that ships JavaScript to the browser.

---

const title = “Ship your first version this weekend”;
import Counter from ‘../islands/Counter.jsx’;

---

<html lang=”en”>
<body>
<main>
<h1>{title}</h1>
<p>Describe your product in one clear paragraph here.</p>
<Counter client:load />
</main>
</body>
</html>

Here is what happens when someone visits this page:

The browser receives HTML immediately. Your headline and paragraph appear before any JavaScript downloads.
Astro sends one tiny script to wake up the <Counter /> component, because you marked it with client:load.
Everything else stays as plain HTML. No framework overhead, no hydration delay, no waiting for a bundle to parse.

Compare that to a React app, where the entire page waits for JavaScript to load before showing anything, and AI tools have to execute your bundle just to read your headline.

Why this matters for a landing page: Most of your page is static content. Your headline does not change based on user input. Your feature descriptions do not need React. Only the signup form or a demo widget might need interactivity, and Astro lets you load JavaScript for just that piece.

Why this stack matters for real people (and AI)

For readers, a fast site means less time waiting and more time deciding whether they trust you.

Most people never think about frameworks. They simply notice whether your page appears quickly on hotel Wi-Fi and whether it feels smooth on an older phone.

For AI assistants, clean HTML means they can actually understand what you do and recommend you when it makes sense.

When ChatGPT, Perplexity, or any other AI tool crawls your site, it wants structured content it can read in milliseconds instead of a React bundle it has to execute first.

Pre-built pages give AI the straight story, which means you show up in AI-generated answers instead of getting skipped for something easier to parse.

For search engines, clear, pre-built content is easier to crawl and understand.

Astro’s style of building static pages plays nicely with this, and hosting them on Cloudflare’s edge means the “fast page” story stays true worldwide.

For you as a founder, this split makes your life simpler.

React stays where its power actually pays off, inside your product, while your marketing site stays closer to a document you can reason about in an afternoon.

When something breaks, the stack is small enough that the issue usually lives in Astro, React, or a specific Worker instead of feeling like a maze.

I mention Yahini on the site as an example of this stack in action: Astro for content, React where it counts, and Cloudflare Workers to get it all to people and AI crawlers quickly.

That mix keeps things simple enough that when something breaks, you can usually trace the problem in one sitting.

This week’s finds: Grok Code Fast 1 and serving markdown to AI crawlers

Grok Code Fast 1 has been quietly helping in the background. It is a coding-focused model built for speed and low cost, which means you can afford to iterate quickly instead of waiting for one “perfect” answer.

The best part is that you can fire off several quick rounds of prompting without worrying about your bill, things like: “draft this component,” “simplify it,” “make it easier to read,” and treat it like a rapid feedback loop in your editor.

That makes it a great fit for experiments like “rewrite this page component for Astro” or “split this React widget into a tiny piece I can reuse elsewhere,” where you mostly need many small tries instead of one giant brain dump.

For example, I used it to turn a React hero section into a simple Astro page, then asked it to remove anything that was not strictly needed for the first version. The whole experiment took about fifteen minutes and three iterations, which would have felt much slower with a heavier model.

I use Grok Code Fast 1 via Open Router, but you can also use it directly from Grok.

Serving markdown to AI crawlers with Cloudflare Workers is another small trick worth knowing about.

Someone on Reddit shared a setup where Workers detect AI crawlers (like ChatGPT or Perplexity bots) and serve them a clean markdown version of your page instead of the full HTML.

That makes it even easier for AI tools to parse your content, understand what you do, and recommend you when people ask questions your product can solve.

If you are already on Cloudflare, this is a tiny addition that can make a real difference in how AI sees your site. The setup involves checking the user agent string, then serving a simplified markdown response when it matches known AI crawlers.

Link: Using Cloudflare Workers to serve markdown to AI crawlers - Reddit post

Let’s connect

Which page in your world is mostly words and a single call to action, but still runs through your full React setup?

Reply and tell me what it does and what you are using today, and I will suggest the smallest “content-first” version you could try without touching the rest of your product.

If you have already split your app this way, reply with “stack split” and tell me how it went, so I can include a few real-world examples in a future issue.

You do not have to pick between “I will just rent a platform forever” and “I need to become a full-time engineer.”

One fast, simple, ownable website is often enough to start, and moving it off your full app stack might be the lowest-risk win you can grab this week.

How to Search Beyond the Docs When Your Code Won't Work

Dan Cucolea — Tue, 28 Oct 2025 13:54:01 GMT

Last week I started building the new project management feature in Yahini, which meant creating a table with advanced sorting capabilities. At first, everything looked perfect. The table loaded, the data showed up, and when I clicked the “Due Date” column header, it actually sorted the rows.

But something was wrong.

Tasks with due dates were mixing randomly with tasks that had no dates at all. The empty ones should’ve been sitting at the bottom of the list, out of the way, but instead they scattered throughout the entire table. It drove me nuts.

I tried fixing it five different ways. Asked Kilo (via Context7) to pull the TanStack Table docs. Read through the sorting guide. Tried every example they had. Nothing worked. After 45 minutes of this, I started questioning whether I’d completely misunderstood how table sorting was supposed to work.

Exa to the Rescue

On attempt six, I asked Kilo to use Exa to search for similar TanStack sorting issues. Instead of just looking over docs, Exa searches the whole web, including GitHub discussions, obscure blogs and reddit threads.

The AI came back with a GitHub discussion thread and two Stack Overflow posts. One discussion nailed it: “TanStack automatically pushes undefined values to the end when sorting, but it treats null as an actual value and tries to sort it.”

That was the issue. Supabase returns null for empty date fields by default. JavaScript treats null and undefined as completely different values. TanStack’s sorting knows what to do with undefined (push it to the bottom), but null gets treated like any other value and sorted randomly in the list.

The AI was smart enough to connect the dots. It read those discussions, saw that I was fetching from Supabase (thanks to the Kilo Code context), and suggested: “Your database is probably returning null. Convert it to undefined when you process the data.”

The fix was one line:

due_date: task.due_date === null ? undefined : task.due_date

That’s it. Simply check if the value is null and convert it to undefined. TanStack now knows to push those tasks to the bottom.

Five minutes later, sorting worked exactly how it should. Tasks with due dates sorted by date. Tasks without due dates stayed at the bottom where they belong.

Would’ve spent another hour manually Googling variations of “tanstack date sorting broken.”

Make Your Coding Assistant Even Smarter

MCP (Model Context Protocol) is just a standard way to connect AI assistants to external tools. Think of it like giving your AI a phone and a library card. Instead of being locked in a room with only what it remembers, it can now call out for current information whenever it needs it.

This matters because every time you leave your editor to search for something, you break flow. Before I set up MCPs, I’d be coding, hit a problem, open a browser tab, read three Stack Overflow threads, maybe check the docs, then try to context-switch back to where I was in my code. That’s 5-10 minutes gone, plus the mental energy to get back into the problem.

With MCPs, the AI does the searching while you stay in your editor. You’re still in your code, still thinking about the problem, and the answer comes to you instead of you going to find it.

What Exa Adds to Your MCP Setup

I already use Context7 MCP for documentation. Context7 is great when you need the official answer. Think of API references and function signatures, basically the “correct” way to do something according to the docs.

Exa fills the gap that documentation doesn’t cover: real-world implementations. It reads the entire web. Blog posts where developers explain edge cases. GitHub issues where someone hit your exact bug and posted their solution. Stack Overflow threads with working code. Even Substack posts where people share problems they ran into.

For the sorting bug, Context7 gave me TanStack’s official sorting documentation. That told me how sorting is supposed to work in theory. Exa found the GitHub discussions about null vs undefined specifically. That told me how to fix my actual problem.

The AI reads what Exa finds, interprets it, then asks clarifying questions. When it saw those discussions about null values, it connected that to my Supabase setup and suggested the exact conversion I needed. I didn’t have to piece together the solution myself, but rather used the AI to synthesize information from multiple sources and give me a working answer.

That whole debugging process took 15 minutes total. An hour saved on a problem that would’ve been painful to solve manually.

Exa Helped Me Migrate Yahini Too

When I moved Yahini’s presentation website from Remix to Astro a few weeks back (full breakdown coming this Friday), Exa saved me from hitting every edge case the hard way.

I asked Kilo Code via Exa to find blog posts from people who’d done the same migration.

It pulled up five different posts.

One from someone who migrated a SaaS marketing site, another from a developer who documented every routing difference they found, and a third with deployment gotchas for hosting static websites on Cloudflare Workers.

Used those posts as my migration checklist. When I hit a routing issue with dynamic paths, I already knew how to fix it because someone else had documented the solution. When my build failed the first time, I recognized the error from one of those posts and knew exactly which config setting to change.

What would’ve been two days of trial-and-error turned into about six hours of focused work. More on this next week with the full play-by-play.

Before the next section, you might want to check out my previous post about Kilo code:

Setting Up Exa MCP

Takes about 1 minute in Kilo Code.

Step 1: Sign up at exa.ai and grab your API key from the dashboard. Free account gives you $10 in credits. That’s roughly 2k searches with 1 to 25 results.

Step 2: Open your MCP config file. In Kilo Code: Settings → MCP Server → Edit Global MCP (this applies to all projects) or Edit Project MCP (just one project). In Cursor: Settings → Features → Model Context Protocol.

Step 3: Add this configuration:

  “mcpServers”: {
    “exa”: {
      “command”: “npx”,
      “args”: [”-y”, “exa-mcp-server”],
      “env”: {
        “EXA_API_KEY”: “your-exa-api-key-here”
      }
    }
  }

Step 4: Replace your-exa-api-key-here with your actual key. Don’t commit this to GitHub if you’re working on a public repo—keep your API keys in environment variables or a local config file.

Step 5: Restart your editor. Exa should now show up in your AI assistant’s available tools list. You can verify this by asking Kilo “What tools do you have access to?” and checking if Exa appears. Or just look at the green dot beside its name in your MCP list.

Exa Pricing

$10 free credits to start. I’ve used maybe 200 searches building Yahini features over the past few weeks and am still a long way from hitting my free credit limit.

After that, roughly $5 per 1,000 searches. To put that in context: if you do 10 searches per day (which is a lot), that’s 300 searches per month, or about $1.50. Compare that to one hour of stuck time where you’re manually debugging, and the ROI is obvious.

How I Actually Use This

I run three MCPs together when coding for Yahini: Context7, Exa, and Supabase MCP (lets the AI query my database directly for debugging). Between the three, I can build most features without leaving my editor.

Here’s my actual workflow when I hit a problem:

First, I ask Context7 for the official approach. “Pull the TanStack Table sorting docs” or “Show me the Supabase date handling API.” This gives me the foundation.

Then, if that doesn’t solve it, I bring in Exa. “Find examples of people sorting null values in TanStack” or “Search for blog posts about Remix to Astro migration.” This gives me real-world solutions from people who’ve hit the same problem.

The AI synthesizes both. It takes the official docs from Context7, finds the practical implementations from Exa, and gives me a solution that actually works in production.

The combined theory with actual practice is what makes this setup powerful.

I still open browser tabs for some things. Visual design inspiration, testing how a feature feels in different browsers, reading long-form technical deep-dives. But for “how do I build this” or “why isn’t this working,” the MCP setup handles the research while I stay focused on code.

Not to mention the Architect mode in Kilo works 10 times better when given access to the web.

This Week’s Discovery: shadcn/ui

When I built Yahini’s task table (the one from the sorting saga), I started with shadcn’s data table component. It gave me the basic structure, sorting UI, and loading states out of the box. Then I customized it to match Yahini’s design.

shadcn isn’t a component library you install via npm. You get the actual code dropped into your project. So when I needed custom styling for overdue tasks (red text, bold font, urgent indicator), I opened the component file and modified it directly. No CSS overrides fighting with library defaults. No digging through prop documentation hoping there’s an onOverdue callback.

And they have an MCP server, which I had to try!

Check it out here → ui.shadcn.com

Let’s Connect

What makes you leave your editor most often? Looking up UI patterns? Finding code examples? Debugging weird behavior that doesn’t match the docs? Reply and let me know. Curious what would actually speed up your workflow.

Want to try Exa? Grab the free credits at exa.ai, drop that config into your MCP settings, and test it for a week. You’ll know pretty fast if it’s worth it.

Remember this: less time searching means more time building.

Kilo Code Changed How I Write Code and I'm Never Going Back

Dan Cucolea — Fri, 24 Oct 2025 13:13:53 GMT

Quick note: This is an extension for VS Code, the free code editor a lot of developers use (which Cursor is based on).

I had 10 browser tabs open while coding. Each AI model was good at something different. One crushed backend logic while the other handled frontend better. I’d switch between them constantly, copy-pasting code back and forth.

Copy, paste, test, find bugs, repeat.

I spent more time switching between tabs than actually building. Until I discovered Kilo Code.

Right now, vibe coders are stuck between two bad options:

pick an expensive platforms like Lovable that charge $25-$200/month and force you to use their code editor;
juggle separate AI interfaces that don’t integrate with where you actually work.

Today I’ll show you the third and better way.

How I Started Coding Features In Yahini

I’d write a prompt in ChatGPT or Gemini, get code, copy it, paste into VS Code, test, find bugs, go back to the chat, explain the error, get new code, repeat. I’d spend 15 minutes just switching between tabs.

I even tried self-hosting an AI wrapper like Chatbot UI. One of those open-source chat interfaces you connect to your API keys to use multiple models in the same browser tab.

Spent a Saturday setting up Supabase, configuring environment variables, deploying to Cloudflare.

Got it working, had my own private ChatGPT/Sonnet/Gemini/Grok basically. But it was still a separate tab. Still copy-pasting code between the chat and VS Code. And now I had to maintain it. Database migrations, updates, auth issues. Gave up after two weeks because it didn’t actually solve the problem.

These approaches keep AI separate from your code. With platforms like Lovable or Bolt, you don’t even get to choose your AI model. They pick for you, mark it up, and you pay whatever they decide.

BYOK Changes Everything

Kilo Code is an open-source VS Code extension with specialized modes:

Architect (plan before you code),
Code (generate features),
Ask (understand existing code),
Debug (fix issues).

Instead of asking ChatGPT in another tab, Kilo Code sits next to your code like a pair programming partner. It can automatically reference files, use MCP servers and compress the context when it becomes too large.

But nothing beats the bring-your-own-keys (BYOK) functionality.

I use OpenRouter with Google Vertex credits. I have one API key in Kilo Code that points to OpenRouter. Then inside OpenRouter, I add all my provider keys. Anthropic, OpenAI, Google, whatever.

I create different model configs in OpenRouter and switch between them based on task complexity.

Simple task? Cheaper model. Complex refactor? Claude Sonnet. All through one key.

I also added a couple hundred dollars in OpenRouter credits to have a backup in case I run out of credits on other platforms. These credits also allow me to test specific new models like the Grok Code Fast 1 without depositing funds into individual providers.

Now think of this, Cursor and Lovable charge anywhere from $20 to thousands of dollars per month.

With Kilo Code, I pay $0 for the tool (it’s open source). Then I only pay for whichever AI model I use at provider rates.

Last month: $119 in API calls for 117 million tokens.

Disclaimer: This includes some of Yahini’s usage besides coding. If I were to approximate I would say that I spent ~$50 for coding which includes a complete migration of the Yahini.io website from Remix to Astro.

Building an API Endpoint in 2 Hours

I needed an API endpoint for Yahini’s lead magnet downloads. Captures email, queues it for processing, triggers email sequence. Built with Hono and Cloudflare Workers.

I opened Architect mode and said: “I need an API endpoint that handles lead magnet downloads with email capture and queue processing.”

Architect mode (powered by Sonnet 4.5) created a to-do list:

Set up POST endpoint with Hono routing;
Add anti-spam and rate limiting middleware;
Add request validation (email, resource ID);
Queue message for email worker;
Batch processing with delays;
Error handling and retries.

Then I switched to Code mode. It followed the to-do list Architect created to complete each step. The Cloudflare documentation MCP was also a huge time saver. I used it to give Kilo Code access to all the Workers docs, queue setup, and batch processing patterns, making sure the AI won’t hallucinate too much.

Here’s the simplified version of the worker:

import { Hono } from ‘hono’
import { antiSpam } from ‘./middleware/antiSpam’
import { rateLimiter } from ‘./middleware/rateLimiter’

const app = new Hono()
const api = new Hono()

*// Apply anti-spam and rate limiting middleware*
api.use(’/download-resource’, antiSpam)
api.use(’/download-resource’, rateLimiter)

api.post(’/download-resource’, async (c) => {
  const { email, resourceId } = await c.req.json()
  
  *// Validation*
  if (!email || !resourceId) {
    return c.json({ error: ‘Missing required fields’ }, 400)
  }
  
  *// Queue email for processing*
  await c.env.EMAIL_QUEUE.send({
    to: email,
    subject: ‘Your Resource is Ready’,
    templateData: { resourceId },
    requestId: crypto.randomUUID()
  })
  
  return c.json({ success: true })
})

app.route(’/api’, api)

export default {
  fetch: app.fetch,
  
  async queue(batch, env) {
    console.log(`Received batch of ${batch.messages.length} messages`)
    
    const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms))
    
    for (const message of batch.messages) {
      await delay(50)
      
      try {
        await handleSendEmail(message.body, env)
        message.ack()
      } catch (error) {
        console.error(’Failed. Retrying:’, error.message)
        message.retry()
        throw error
      }
    }
  }
}

Validation, anti-spam, rate limiting, and queue processing. Nothing fancy, but production-ready.

Took 2 hours total to have a fully functional worker. I ended up integrating it in my dedicated Brevo Worker to keep things organized. And Kilo Code helped with that too.

Why Kilo Code Beats Platform Lock-In

The platform trap is real. Lovable charges $25/month minimum for 100 credits, but here’s the catch: those credits burn fast. A simple “Add authentication” prompt costs 1.2 credits. Building a landing page? 2 credits. You’re looking at 50-80 prompts per month before you need to upgrade.

Bolt isn’t better. Their Pro plan starts at $20/month for 10 million tokens, but developers report burning through 7-12 million tokens just fixing simple errors. One user lost 1.3 million tokens in a single day. And those tokens don’t roll over.

But the real problem isn’t the cost. It’s that you don’t own anything.

With Lovable or Bolt, you’re building inside their editor. Sure, Lovable added GitHub sync (which is huge), but you’re still paying a monthly subscription just to access the platform. When credits run out mid-build, your work stops until you top up. When a new model drops that’s perfect for your use case, you can’t switch to it unless they support it.

And here’s the part nobody talks about: Lovable Cloud. That’s their backend service, powered by Supabase. It has completely separate billing. You get $25 free per month, but once your app needs real data storage, authentication, or file uploads, that meter starts running. People build prototypes thinking they’re spending $25/month, then their app gets traction and suddenly they’re getting surprise bills for backend usage they didn’t budget for.

Kilo Code separates the tool from the cost.

The extension is free. Open source. You install it in VS Code (also free) or even in Cursor if you’re already paying for that. Then you bring your own API keys.

Here’s what that means in practice:

Want to use Sonnet 4.5 for complex refactors? Pay Anthropic’s API rates directly.
Found a free model that’s great for simple tasks? Use that.
Got Google Vertex credits? Code for free until they run out.
New model drops? Switch to it immediately.

No subscription. No credits that expire. No separate backend billing. Just pay for the AI you actually use, at the rates the providers actually charge.

Even if you’re already paying for Cursor ($20/month), adding Kilo Code means you control which models you use and when. Cursor’s credits burn fast when you’re in Max Mode. With Kilo Code, you decide if a task needs an expensive model or if a cheap one will do. You’re not locked into their usage tiers.

Quick Note on Credits

I’m running Kilo Code with free Google Vertex credits routed through OpenRouter, so I’m basically coding for free until those run out. I’ll write a full post on how to set that up.

For now, just know BYOK means you can use whatever credits or pricing you want. Free model for learning? Go for it. Paid premium model for production? Your choice. You aren’t locked into anyone’s credit system.

This Week’s Discovery

The Cloudflare Documentation MCP made building that endpoint smooth. Instead of opening docs in another tab, Kilo Code had all the queue syntax, Worker config, and routing info right there. Saved me 30 minutes of tab-switching. If you’re building on Cloudflare, this MCP is essential.

https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/docs-vectorize

Let’s Connect

What’s your setup? Juggling AI chat tabs? Paying for Cursor or stuck in Lovable? Reply and tell me.

Want to try Kilo Code with BYOK? GitHub repo: https://github.com/Kilo-Org/kilocode. If you want the full OpenRouter + free credits walkthrough, let me know. I’ll write that in the upcoming editions

Own your tools. Control your costs. That’s how you stop paying rent on your own work.

I Learned React in 9 Months and Built a Real SaaS - Yahini

Dan Cucolea — Tue, 21 Oct 2025 13:06:42 GMT

The idea was rather simple. Yahini was going to be an app that would automate the keyword research and content briefing work I was doing manually for my agency clients. Work that was eating 15-20 hours per project.

That quote is the reason this newsletter exists. It was the moment I realized I couldn’t hire my way out, and the “no-code” platforms couldn’t handle what I needed to build.

So I learned React instead.

This is the first post of Vibe Stack Lab. It’s the story of how I learned just enough code to build a real SaaS product that now serves paying customers. And it’s the start of a journey where I’ll teach you everything I learned.

I plan to show and teach you how to bridge the gap between writing prompts in tools like Lovable and actually owning your code.

The $15,000 Wake-Up Call

Back in 2023, I was running a content agency. My co-founder and I were essentially acting as content CMOs for a handful of clients, but the process was brutal and they were asking how we could integrate AI into our workflow.

For every single client we had to:

pull their top 20 competitors;
analyze 50-100 ranking keywords per competitor;
map each keyword to a funnel stage (TOFU, MOFU, BOFU);
score them by difficulty and business relevance;
write detailed content briefs for the priority topics.

We did all that manually. In spreadsheets. For 15-20 hours per project per month.

And after all that we actually wrote the content, which I won’t go into to much detail right now.

It was right about the time when AI started to become way more powerful , so we had an idea.

What if we productize the workflow and turn the agency into a SaaS?

Now the problem was that I couldn’t write a single line of code, and hiring developers was out.

Mainly because the quotes were way more than we could afford to burn at that time. Not to mention we spent tens of thousands of dollars over the years to build other apps that either did not work, or kept on chewing money just to keep them afloat.

Does that sound familiar?

You’re paying Bolt or Webflow $200-$600 a month, or you’re considering it.

But what happens when your AI coding agent gets stuck on a loop and starts writing gibberish code. Or worse yet, you get stuck with a bug that can’t be fixed and you start burning millions of tokens (or credits) to get it working.

Just Like a Broken Record

The agency work was repetitive in the best way.

We had frameworks that worked and proven content strategy methodologies that we’d refined over 5 years of hand-on experience.

The problem was execution. Every new client meant manually researching keywords, mapping them to funnel stages (TOFU, MOFU, BOFU), analyzing competitors, and writing detailed briefs.

I knew AI could handle this. We’d already started using it internally to speed up proposals and research. But I needed a real product, not a Notion doc full of ChatGPT prompts.

The math didn’t work to hire developers.

Even at $15,000 upfront, I’d still need them on retainer for bug fixes, feature updates, and maintenance. That would run another $3,000-$5,000 per month minimum. The only way out was to DIM (Do It Myself).

I spent about two weeks researching.

I looked at no-code tools first - Bubble, Webflow, even Airtable with Zapier. But they all had the same problem: I’d be renting my product from them forever. Plus their capabilities were limited, and it would take me months to get a good system in place.

If I wanted to move, I’d have to rebuild from scratch. After researching how people actually build web apps in 2024, React kept coming up. I found The Ultimate React Course by Jonas Schmedtmann.

My starting point? A little HTML/CSS from tinkering and some concepts from setting up tracking in Google Tag Manager, but zero real JavaScript experience. I was basically starting from scratch.

“Oh Crap”

I opened that first React tutorial and thought, “What have I gotten myself into?”

The boilerplate code looked like hieroglyphics. But I had my $15,000 motivation and 15-20 hours of manual work per client to automate. So I kept going.

Nine Months to a Real SaaS: The Honest Timeline

This wasn’t a “weekend project.” It took nine months of consistent, focused work.

My routine was simple: about three hours of studying and three hours of building every day.

Months 1–3 →

I followed Jonas’s course religiously. I did the exercises, built the tutorial projects, and tried to absorb core concepts. The first real project was a pizza ordering app. It felt silly, but it taught me how React’s component structure actually worked.

Then came a “usePopcorn” movie tracking app that introduced me to API calls and side effects. Nothing “clicked” overnight. Things just slowly became less terrifying.

Months 4–6 →

This is when I started building Yahini. I threw away my first three attempts at the core feature, which was the most complicated one (the automated keyword research engine).

My first version tried to do everything in one massive component. It was 800 lines of spaghetti code that broke every time I touched it.

My second attempt over-engineered everything into tiny components that passed props through five layers. Also terrible. State management was a nightmare. I spent an entire week trying to understand the useEffect hook.

What finally made it click was building a tiny, isolated app that did nothing but fetch data. Seeing it work in a simple context unlocked the concept.

And GPT3.5 also helped a little. Try to use it now to write code and you’ll see what I mean by little.

Months 7–9 →

I started integrating the real stack: Supabase for the database, Cloudflare Workers for the backend.

This is when I realized I was actually building something real. I had user authentication working. I had forms that saved data. I had API calls that returned actual keyword results.

This is when AI became my coding partner. I’d get stuck on a bug, feed the code to an AI, and ask it to explain the error. It was like having a senior developer who never got annoyed with my questions.

It didn’t write the app for me, it was just too stupid. I’d estimate AI maybe wrote 20-30% of the final code, mostly boilerplate and utility functions. But it massively accelerated debugging by helping me understand error messages and suggesting where to look for problems.

Then Came the Launch

I considered Yahini “launched” when the first real, non-friend user signed up, ran their domain through the system, and got a complete content strategy workbook with prioritized keywords and briefs. That was Month 11. Nine months of learning and building, plus two more months of polish and bug fixes after the first “working” version.

Today, Yahini runs on React, Hono, Supabase, and Cloudflare. The platform automatically learns a business from its URL, generates funnel-mapped keyword strategies, and creates expert-level content briefs.

My total monthly infrastructure cost is $5. This covers the Cloudflare Workers premium subscription. In addition, we have API costs, but that is part of operating costs rather than infrastructure.

Let’s do the math on the alternative. That $15,000 quote was just for the initial build. Add in retainers, maintenance, and feature requests over eleven months, and I would have easily spent over $20,000 (probably closer to $30,000 if I’m honest).

Instead, I spent a few hundred on courses and about $100 in total hosting costs, AI credits and API costs while building.

The Truth About Timelines

You see people on Twitter saying, “I built a SaaS in a weekend!” They’re either lying, or they’re not counting the years of learning that came before.

Nine months is a real timeline. It’s achievable if you’re consistent. Here’s the core philosophy of Vibe Stack Lab: platforms like Bolt and Lovable are great for testing ideas, but terrible for owning your business long-term. Traditional coding bootcamps teach you like you’re going to work at Google, which you’re not.

I believe I found a middle path, and here it is: learn just enough code and master the right tools to work with AI to build production apps. You’re not trying to become a senior engineer. You’re learning to be dangerous enough that AI becomes a superpower instead of a random code generator.

In the End, Was It Worth It?

Absolutely. Understanding core code principles is a superpower.

When a user reports a bug, I can fix and deploy it in minutes. I don’t file tickets or wait for quotes. When I wanted to add the Brand Intelligence feature that automatically analyzes a user’s website , I just built it. It took about four days of focused work alongside AI:

Two days to figure out how to scrape and parse website content,
One day to structure the AI prompts to extract brand voice
One more day to wire it all together and test it.

Yahini runs for $5 a month. I’m not locked into any platform’s pricing, roadmap, or limitations. When I need to add a feature or change the pricing model, I can immediately DIM (Do It Myself). That’s real freedom.

The nine months of struggle was the price of admission. But think about it this way: if I’d stuck with the agency model, I’d still be manually doing keyword research for clients right now. Instead, I have a product that does it automatically and serves multiple customers simultaneously.

This Week’s Discovery

I’ve been using Exa MCP in Kilo Code, and it’s worth highlighting because it solves a problem every builder faces: AI coding agents that confidently write broken code. Exa MCP connects Kilo Code to Exa’s search engine through the Model Context Protocol, and the killer feature is exa-code .

With this, exa searches billions of GitHub repos, documentation sites, and Stack Overflow threads to find actual working examples before my agents write anything. When I’m building a new feature in Yahini, instead of getting hallucinated API syntax or deprecated methods, the agent pulls real, current code patterns.

The difference between this and just prompting ChatGPT is that Kilo Code can execute commands, edit multiple files, and use the search results in context while building. It also includes web search, company research tools, and a deep researcher that can write comprehensive reports on technical topics.

For anyone building production apps, having an agent that verifies its code against real-world examples before touching your codebase is the difference between spending 10 minutes on a feature versus burning an afternoon debugging AI-generated nonsense.

Check it out here → **https://docs.exa.ai/reference/exa-mcp**

Let’s Build Together

Where are you on this path? Stuck in tutorials? Dreading another platform bill? Thinking about learning to code but worried about the time investment?

Reply to this email and tell me your situation. If you want to see my week-by-week learning plan from those nine months, just ask and I’ll send it over.

This is the start of Vibe Stack Lab.

The newsletter where I teach vibe coders how to graduate from expensive platforms to actually own their code.

Every week, I’ll share what I’m learning while building Yahini in production. Real costs, real timelines, real mistakes. You’ll learn the exact setup I use: React for the frontend, Cloudflare Workers for the backend, Supabase for the database. The whole stack runs for dollars per month, and you own every line of code.

The Journey Starts Now

Nine months sounds like a long time. But trust me, you from the future whishes you started today.

Welcome to Vibe Stack Lab. Let’s build.

All Agents Considered

I Built an Open Source MCP To Analyze Your Substack Data With Hermes And Codex

In This Edition

What You’re Installing

What You Need

Check Node.js

Find Your Login Cookie

Add It To Codex

Check The Connection

Ask A Focused Question

Five Prompts Worth Saving

Review Your Publication

Review One Post

Compare Your Notes

Sort Your Notifications

Check Subscriber Totals

Ask For Summaries First

What Read-Only Protects

Your First Ten Minutes

What Should I Add Next?

What Hermes Thinks I Do When I'm Not Talking To It

In This Edition

Here’s How It Works

The Job Title

The Strongest Trail

Uncovering the Weak Points

What Disappeared

There’s A Valuable Lesson Here

Your Turn

Behind the Title

The One File That Made Hermes Finally Learn From Its Mistakes

In this edition

Memory Keeps Context

Keep Mistakes Local

What an Entry Holds

Verify Before Recording

The Tiny Instruction

Test the Next Run

When the Ledger Lies

Try It in 60 Seconds

Give Failure a Job

How Pangram Decides What Looks Like AI

Why Everyone Hates AI Detectors

Pangram Does Not Search for an Em Dash

Pangram Trains on Twins

Pangram’s Open Model Is Not the Substack Model

What the Percentage Means

The Evidence That Pangram Works

Where Pangram Messes Up

How to Read a Pangram Result

My Verdict On Pangram

How I Built A Substack API With Hermes And Codex

In this piece

The Package I Forgot

Hermes Found The Ground

Codex Needed a More Targeted Job

The Server Had To Prove It

Let The Tests Argue

The Split I Use Now

Copy This Handoff

What Shipped

Two Agents One Workflow

OpenAI Is Coming for Hermes One Codex Update at a Time

The July Sprint That Reshaped My Stack

Codex Reaching Beyond Desktop

One Subscription Feeding Two Agents

The Workflows Codex Took From Hermes

The Workflows Hermes Still Defends

Sorting Every Workflow Into Three Buckets

Six Checks Before You Build

Two Workloads Through the Same Test

Run Your Own Audit

The Expanding Overlap Open Source Needs to Answer

Where the Line Sits Today

The Twenty Minute Audit That Found Where Hermes Was Getting Lost

When Tools Inherit the Mess

The 20-Minute Audit

Walking Through an Audit

Pick One Fix

Tear Down Your AI Workflow and Rebuild It Like This