DEV Community: Tomas Grasl

"Developers Will Lose Their Jobs": How You Were All Wrong

Tomas Grasl — Sun, 02 Aug 2026 17:56:50 +0000

I don't write the code of our systems anymore. I write agents that write the code.

And that is exactly why the job panic looks so silly from where I sit.

I run a backend team at a Czech media house. Paywall, subscriptions, OAuth, CRM, mailing. Real systems with real money going through them. Most of my day now goes into rules, permissions, test gates and review steps for agents, not into functions. The work didn't disappear. It moved one layer up, and that layer is harder.

Every new name is a patch on the previous one

Watch the vocabulary of the last four years. Prompt engineering. Context engineering. Harness engineering. Loop engineering. Now graph engineering.

The community treats these like levels of enlightenment. They're not. They're workarounds. Each one exists because the previous one hit a wall.

2022, Prompt. You polish one sentence. "You are an experienced traffic lawyer, what do I do if they clocked me at 150 in a village, asking for a friend." It was a prestigious, well paid job title. Then agents started doing 50 steps in a row and one beautiful sentence stopped mattering.
Weakness: it doesn't scale past a single turn.

2025, Context. agents.md, .clinerules, repo conventions dumped into the window before the model touches anything. Stop guessing, here are the rules of this project.
Weakness: the model knows what to do, but has nothing stopping it from doing something else.

2026, Harness. Sandbox, tests, permissions, logs. The model is just an engine, the harness is the rig around it. There's a number going around that the same model jumps from 52% to 66% on coding tasks purely from a better harness, without anyone touching the weights. I can't verify that number, but the direction matches what I see: most of my quality gains in the last year came from the rig, not the model.
Weakness: you're still the one handing out every task.

Then, Loop. "I don't write prompts anymore, I have loops that assign work to the model." You start it and go get coffee. It watches PRs, fixes CI, picks up feedback.
Weakness: nondeterminism. Run it twice, get two different worlds. Fine for a side project, not fine for a paywall.

Now, Graph. Instead of a loop that improvises, you draw the thing. Code, then ALWAYS review, then merge. No guessing about order. Google reportedly rebuilt their agent dev kit from an agent runner into a graph engine for this reason.
Weakness: unknown so far. There will be one. Probably that the graph itself becomes a codebase nobody wants to maintain.

The skill is spotting the ceiling, not learning the name

Here's what I think people get wrong. They chase the vocabulary. New term drops, half the timeline rewrites their setup that weekend, usually because someone with a big following said so.

The actual skill is different. It's looking at a layer and knowing quickly where its ceiling is, and which lever to pull so the output gets good. Not "which layer is currently correct", but "this one will break on step 30, so I need a gate there".

You don't learn that from a thread. You learn it because you've watched it break a few dozen times. Which is a very old skill wearing a new hat.

What my day actually looks like

I set the rules, the permissions, the test gates, the review steps.
The agent works.
I read diffs and say yes or no.
When it gets stuck, I finish it by hand.

Less code written. More decisions made. And the decisions are the part that was always hard.

The pattern nobody says out loud

Look at the direction of that chain again. Prompt is a request. Graph is architecture.

Every single layer added since 2022 exists to take freedom away from the model and give control back to a human. Context takes away guessing. Harness takes away access. Loop takes away idle time, and then graph takes away the loop's improvisation.

The better the models get, the more control we take back. Not less.

That's the opposite of the story being sold. "AI writes everything, developers become obsolete" doesn't survive five minutes of contact with a production system. Somebody has to decide where the review step goes, where the rollback goes, which permissions the agent never gets, and whether a PR that looks fine is actually going to break checkout on Friday evening.

The people most sure that developers are finished are usually the people who have never run an agent against a real repo.

So what's next

I don't know.

Maybe the abstraction gets good enough that we end up back at prompting. You say what you want, and underneath it a graph of loops does something nobody fully follows anymore. The circle closes.

Even then, someone designs that graph. Someone maintains it. Someone gets paged when it merges garbage at 3am.

Guess who.

Not interested in which layer you're on. Where did you hit its ceiling? That's the more useful conversation.

Can we play a game on pixelden? Made my pixel art game portal playable inside Claude via MCP

Tomas Grasl — Thu, 30 Jul 2026 20:01:58 +0000

I hacked the new MCP UI extension 😎

By which I mean I read the spec and used it exactly as documented, for a dumb little game. 😅

MCP Apps is the official MCP UI extension. Short version: your server declares an HTML resource under ui://, links it to a tool via _meta.ui.resourceUri, and the host renders that HTML in a sandboxed iframe right in the conversation. The iframe talks back over JSON-RPC, so it can call tools. Not a rendered screenshot, a live UI.

Everyone is shipping dashboards and forms with it. I put a game loop in there.

The tool starts a run, the iframe is a real one button arcade game. When you crash, the widget sends the seed and the ticks you jumped at back to the server, the server replays them through the engine and computes the score. The model never touches the number.

👉 https://www.pixelden.io/play-in-claude

Claude Code plans, Cursor Composer executes, Claude reviews. I wired the three together.

Tomas Grasl — Thu, 30 Jul 2026 13:00:00 +0000

I was burning expensive Claude tokens on tasks a cheaper model could handle just fine. Renames, placeholder swaps, grinding through a well-scoped task list. That's not where Claude's magic is, and it's not where I want to spend the budget. So I stopped picking one tool and wired two together.

After a few weeks of juggling terminals, the setup settled into three moves:

Claude Code makes the plan.
Cursor Composer 2 executes it.
Claude reviews the diff.

Tokens saved, quality kept. I packaged it as a Claude Code plugin so I don't reinvent the hand-off every time.

Why not just stay in Cursor?

Because Claude Code has a real edge in planning, and it's not only the model. It's the whole rig: long-context sessions, subagents, the TUI, the way tools compose. The plans it produces are consistently good, and I didn't want to give that up to save money on execution.

Why not just stay in Claude?

Because Composer 2 is genuinely good at day-to-day coding and one-shot work. File edits, applying diffs, churning through a well-scoped task list in force mode. Cursor and Composer are heavily tuned for exactly this CLI use case. Fast, and safe enough for mechanical changes.

Picking one meant either overpaying for execution or under-planning. Wiring them together meant each tool does the part it's best at.

What I actually use it for

Bigger refactors: think out loud with Claude, then let Composer grind through the mechanical edits in the background. Multilingual site integration, where Composer swaps every hard-coded string for a placeholder, is a perfect fit.
"Rename X to Y across the codebase and update the tests": classic Composer territory. No reason to spend Claude cycles on it.
E2E testing via a browser MCP: one slash command spins it up. Composer 2 is more than enough here; I don't need a frontier model to click through a page and assert on it.

What didn't work

Letting Cursor do the planning. It's fine. But Claude's planning loop is better, and that's the one place I don't compromise. The lesson: don't split work by tool arbitrarily; split it by what each tool is actually best at. Planning to Claude, mechanical execution to Composer, review back to Claude.

What's in the plugin

Rather than re-do the hand-off by hand each time, I shipped it as a Claude Code plugin: eight /cursor:* commands (delegate, status, result, cancel, resume, browser-verify, sessions, setup) plus a cursor-runner subagent for automatic delegation. Zero runtime dependencies, MIT.

Heavily inspired by openai/codex-plugin-cc, which pulls the same trick with GPT/Codex, credit where it's due.

The takeaway

The interesting shift here isn't "use a cheaper model." It's treating your coding agents like a small team with different strengths instead of looking for one model to rule them all. A planner, an executor, a reviewer. They just happen to be three different CLIs, and the plugin is the glue that makes the hand-off free.

👉 github.com/freema/cursor-plugin-cc

Are you running a multi-tool coding setup, or still trying to make one model do everything? Curious how others split the work.

I've built a handful of MCP servers. Here's what separates a good one from a demo.

Tomas Grasl — Tue, 28 Jul 2026 13:00:00 +0000

This year I've built more MCP servers than I meant to, across three pretty different shapes:

vellum: a self-hosted server over a folder of markdown, so my agent has a memory that's just files I own. (Open source, MIT.)
Metrifyr: a marketing-data server that puts GA4, Search Console, AdSense and Tag Manager behind one connection.
A read-only gateway over a company's internal user-data stack, federating half a dozen internal services behind one audited MCP surface.

Personal, product, enterprise. Totally different data, totally different stakes. And yet the things that made each one good, versus a flashy demo that falls over the moment a real agent uses it in anger, were the same every time. Here are the seven that keep recurring.

1. Every tool you expose is a tax on the agent's context

This is the one nobody warns you about. Every tool definition (name, description, JSON schema) gets loaded into the model's context on every single request, whether or not it's ever called. Twenty tools of boilerplate and the agent is reading pages of plumbing before it touches your data.

So the design pressure runs the opposite way from a normal API: fewer, broader tools beat many narrow ones. vellum has 15 core tools and I fought to keep it there. If a tool doesn't earn its slot in the context window on most requests, it shouldn't be a tool.

2. Tools are for acting. Resources are for reading.

The corollary to #1. Most servers expose everything (including "read this thing") as a tool. But MCP has a better primitive for reading: resources. In vellum, every note is a resource at a stable URI (vellum://note/projects/x.md). The agent attaches a document by reference instead of spending a tool round-trip to fetch it, and it can subscribe to that URI and get told the moment the note changes.

Reading through a resource costs no tool definition. Reading through a tool costs one on every request. Use the right primitive.

3. Fail closed on auth, fail open on limits

A token with no grants should see zero tools: not an error when it tries to call one, but genuinely nothing in tools/list. Authorization fails closed. Rate limiters, on the other hand, should fail open: if the limiter itself breaks, you degrade to serving the request, not to locking everyone out. Getting these two backwards is how you either leak capability or take yourself down.

4. Annotate what's safe and what isn't

MCP lets you tag tools with hints: readOnlyHint, destructiveHint, idempotentHint. Use them. They're how a well-behaved client knows it can call your search tool freely but should think twice before your delete tool. On the marketing server this is the line between "the agent can answer any question about your analytics" and "the agent can reconfigure your analytics", and the annotations are what keep those two worlds visibly separate.

5. Writes must be conflict-safe

The moment more than one thing can write (an agent and a human, or two agents) last-write-wins silently eats data. vellum returns a content hash on every read, and a write fails on hash mismatch instead of clobbering. It's optimistic concurrency, the same trick databases have used forever, and it turns "the agent overwrote my edit" from a support ticket into a retry.

6. For anything touching real data: read-only, and audit everything

The enterprise gateway taught me this one hard. When an MCP server sits in front of a company's actual user data, the default posture is read-only, every tool call is logged with who called it and what came back, and any PII in a response comes back as a hash, not the raw value. An agent is a new kind of caller; treat it like one you'll have to explain to a security review later, because you will.

7. Tell the agent how to use you

MCP has a spot in the handshake for server instructions: a short document the agent reads before it does anything. This is where you say "notes are vault-relative paths," "prefer patch over rewrite," "empty query with tags is a pure tag filter." It's the difference between an agent that fumbles your API and one that uses it the way you intended on the first try. Most servers leave it blank. Don't.

One gotcha that cost me an afternoon

structuredContent roughly doubles your response size: the payload is serialized into the response twice. If you've got size-based metrics or limits, they'll suddenly read high for no obvious reason. Recalibrate them, or you'll spend an afternoon chasing a leak that isn't there.

None of this is about clever features. Across a note vault, a marketing stack and an enterprise gateway, the servers that behaved well were the ones that respected the agent's context, used the right primitive for each job, and were honest about what was safe to call. The demo is easy. The seven things above are what make it survive contact with a real agent.

If you're building on MCP: which of these bit you first? For me it was #1. I over-exposed tools on my first server and watched the agent drown in its own toolbox.

Mozilla adopted my Firefox DevTools MCP, but I didn't build it to browse the web

Tomas Grasl — Thu, 23 Jul 2026 13:00:00 +0000

A little while ago I wrote an MCP server that lets an AI agent inspect and control Firefox through the Remote Debugging Protocol. It got adopted into the Mozilla org. That's a nice flex, and I'll take it, but it buries the more useful story, which is why I built it. It wasn't to give my agent a browser. It was to make my agent write its own tests.

The real problem: e2e tests, not browsing

Multi-agent orchestration I've mostly got a handle on. My actual pain, the thing that eats my evenings, is end-to-end testing. Nobody wants to write it, it rots the moment the UI shifts, and it's exactly the kind of mechanical-but-fiddly work you'd love to hand off.

So the flow I actually care about looks like this:

Claude has a "test skill" that tells it to click through the app using the Firefox MCP: open the page, fill the form, follow the flow, read the DOM back.
Once it's walked the flow and knows what the app does, it writes a Cypress or Playwright test for it.
From then on it just runs the test. The MCP was scaffolding to author the test, not a permanent dependency.
If it gets stuck, it pings me and I finish that one by hand.

The result is a reasonably tight dev loop: the AI builds a thing, tests the thing, and knows when it broke the thing. The browser control is a means to that end.

Why Firefox, when Chrome DevTools MCP exists

Fair question. Chrome's DevTools MCP does most of the same moves. Three reasons I reached for Firefox anyway, and none of them is "Firefox is better at everything."

It's stricter about standards. Firefox holds the line on W3C (CSS Grid inspection, layout edge cases) where Chrome quietly papers over your mistakes. That sounds like a downside until you realize it's exactly what you want from a test browser. If a layout is going to break, I'd rather it break in the strict engine during testing than in front of a user.

Leaner to run on a server. I don't run this on my laptop. It runs on a server, next to a Claude CLI or Codex session and whatever else is going. When you're stacking agents on one box, a lighter headless browser is the difference between fitting and swapping. And for my setup, headless Firefox is the lighter one. (Measure it on your own box; it depends on what you load.)

It's open source. For something I want to run on my own infrastructure and tinker with, that speaks for itself.

What this says about MCP servers in general

The thing I keep taking away from this one: the best MCP servers are scaffolding for a workflow, not a permanent appendage. The Firefox MCP is at its most valuable in the minutes it takes the agent to learn a flow and codify it into a real test. After that, a plain playwright test command does the job: no agent, no MCP, no tokens.

Designing for that ("help the agent build something that outlives the session" instead of "keep the agent calling me forever") is a different mindset than most tool servers take. And it happens to produce the tool I actually reach for every day.

Try it

If your pain is the same as mine, writing and maintaining e2e tests, this flow is worth stealing even if you never touch Firefox: let the agent explore the app through a browser MCP, then have it emit a real Playwright/Cypress test you can run headless forever after.

The repo lives in the Mozilla org now: mozilla/firefox-devtools-mcp.

What's your current e2e testing loop: hand-written, recorded, or generated? I'm always looking to tighten mine.

I gave my AI a memory that's just a folder of markdown I own

Tomas Grasl — Tue, 21 Jul 2026 11:00:00 +0000

🚀 It's live on Product Hunt today. If this resonates, an upvote genuinely helps: Vellum on Product Hunt

Every time I gave my AI assistant "memory," I ended up in the same place: the memory lived in someone else's database, as embeddings I couldn't read, in a cloud I didn't control. Cancel the subscription and the memory goes with it. That felt backwards.

So I built the opposite. It's called Vellum, it's open source (MIT), and the whole idea fits in one sentence:

Point your agent at a folder of markdown. It reads and writes notes over MCP. The folder stays flat files you own.

What it actually is

Vellum is a small, self-hosted MCP server over a plain directory of .md files. Any MCP client (Claude, Cursor, ChatGPT desktop, the MCP Inspector) connects to it and can list, read, write, patch, search, tag, and backlink your notes. Every note is also exposed as a first-class MCP resource (vellum://note/{path}), so your agent can attach a note as context straight from its resource picker, no tool call, no copy-paste.

And because the "database" is just a folder, you keep editing the same vault in Obsidian, vim, or git. Nothing is trapped.

# try it in one command
docker run --rm -p 8080:8080 -v "$PWD/vault:/vault" ghcr.io/freema/vellum

# point Claude at it
claude mcp add --transport http vellum https://your-host/mcp

The deliberate choices

The whole project is an exercise in picking the smallest thing that just works.

No database. Ever (v1). Tags, backlinks, and task states live in an in-RAM index rebuilt in ~50 ms at startup. There's nothing to migrate, corrupt, or back up separately. Your data is the files.

No embeddings. Search is a ranked in-memory scan: the metadata index narrows by tag/dir, content is matched from a cache, results are ranked (title > tag > path > body). It's case-, diacritics-, and typo-insensitive ("preklapy" finds "překlepy") and runs in ~0.4 ms warm over a 2,000-note vault. No vector store, no warm-up, no index to rebuild. The Searcher interface exists so I can slot in bleve if it ever hurts. It hasn't.

It never calls an LLM itself. Vellum prepares context; your agent decides. The optional "curator" tools (folder suggestions by tag overlap, orphan/untagged/stale-inbox lists) are all deterministic, no API keys, no calls out.

It's its own OAuth 2.1 issuer. One client secret, PKCE, opaque in-memory tokens that die with the process. No external identity provider, nothing phones home. Writes are conflict-safe: every read returns a content hash, and write tools reject a stale hash instead of clobbering.

Small on purpose. One static Go binary with an embedded React UI, a 24 MB distroless image, ~5 MB idle RAM, a read-only container that only ever writes into the mounted vault. docker compose up -d and you're done, or one-click on Railway / Render / Fly.

Why not just…?

Obsidian + plugins: that's your editor, not a server. Vellum serves the same folder to your agent while you keep editing anywhere. No sync, no plugin sandbox, no Electron on a server.
Notion / Anytype: those own your data in a proprietary store. Vellum's store is ls and grep.
Heavier MCP note servers: a vector DB, API keys, and a big tool surface that eats agent context. Vellum is one 24 MB container and 15 focused tools.

The web workspace

It also ships an embedded three-pane workspace (tree / list / editor) in the same binary. It stays in sync with the vault on its own: MCP writes appear without a reload, a split view puts raw markdown beside the rendered note, and tasks (type: task + status) filter by state. It's the "human" window into the same folder your agent is working in.

Where it's going

v1 is intentionally boring and solid. I'd love feedback on two things especially: the MCP tool surface (15 tools today: what's missing, what's noise?) and the no-embeddings bet (where does a pure scan stop being enough for you?).

If "your agent's memory should be files you own" resonates, the repo is here:

👉 github.com/freema/vellum (MIT)
🚀 And it's live on Product Hunt today: producthunt.com/products/vellum-9 — an upvote is genuinely appreciated.

Where does a pure scan stop being enough for you: at what vault size would you reach for embeddings? That's the bet I'm least sure about.

I finally figured out what Claude Artifacts are actually for

Tomas Grasl — Fri, 17 Jul 2026 15:27:28 +0000

I've been using Claude for a long time and mostly ignored Artifacts. Fine for a quick React demo. Not something I reached for.

Then I needed to send an analysis to a few people at work, and it clicked. Or I'm just using it in a way nobody intended. Hard to say.

The actual case

I own the paywall backend at a Czech media house. The subscription offer on our news site is embedded as an iframe, and iframes are a bad neighbourhood: context isolation means the iframe has no access to the parent page's session, so user identity kept breaking and we kept patching it over postMessage. Every iframe is its own page view, so GA4 data was skewed and we had to build server-side tracking and session stitching to make the numbers mean anything. And ad blockers, CSP, and timeouts mean sometimes the thing just doesn't render, so we maintain a fallback UI in parallel.

I wanted to propose we drop the iframe and ship a JS embed library instead, distributed through our internal npm registry. That's an architecture change, so it needs a document: what we fixed, why the iframe is still structurally wrong, what the alternative costs, what the numbers say.

The numbers part came out of the same agent session, by the way. GA4 said roughly 0.14% of paywalled page views hit an error, about half of them iframe-blocked-by-browser. That's every 700th reader. Small number, real money.

The boring problem

You get a good answer out of the model. Now what?

You paste it into a doc. Reformat it, because chat markdown does not survive the trip. Fix the tables. Decide whether it goes in Confluence or an email. Send it. Then someone asks a follow-up, you go back to the model, get a better answer, and now there are two versions of the truth and one of them is in someone's inbox.

I've done the email version of exactly this document before. Outlook ate the markdown. I ended up hand-rolling plain text with unicode bullets and uppercase section headers like it was 1998.

Half of that work is transport, not thinking. And the transport step is where the document goes stale.

What I did instead

I had the same agent that produced the analysis publish it as an Artifact, and sent people the link. We have Claude on a team plan, so they just open it.

No docx export. No Confluence page. No slide deck. One URL.

The thing worth noticing: there is no handoff. The agent that has the analysis in context is the agent that renders it. No step where I copy something out of one tool into another, which means no step where I introduce a formatting mistake or quietly drop a caveat.

The part that actually surprised me

The Artifact is not a snapshot. As the thing moved (proposal → decision → plan with tickets), I had the agent rewrite it. Same URL the whole time.

So it stopped being "the thing I sent on Tuesday" and became the current state of the project. Nobody hunts for the newest version, because there is only one version. Nobody asks "is this still accurate?", because the answer is yes or the doc gets rewritten.

That's a surprising amount of what a wiki does, without the part where you have to remember the wiki exists.

Where this does not work

It is not documentation. No history, no diff, no "who changed this and why". If you need to know what the architecture decision was six months ago and what the reasoning was, you need a real doc in a real system.

This is a tool for one phase: the window between "I have a finding" and "we've decided what to do". A few days, sometimes a couple of weeks. During that window the document changes constantly and permanence is a liability. After the decision lands, the durable version goes in the wiki. The Artifact was scaffolding.

The other limit is obvious but worth saying: everyone who needs to read it has to be on the same team plan. Not a public publishing tool.

The one rule I'd give anyone trying this

Be deliberate about what data goes in.

The agent will happily render whatever it has in context. When the analysis touched production analytics, "whatever it has in context" included things that should not exist in a link pasted into a chat channel. In that same GA4 dig I found we were sending subscriber UUIDs to Google as an event category, which is its own separate problem, but it's a good illustration: the raw data had identifiers in it, and the shareable document must not.

Aggregates only. No personal data. Decide that before you ask for the artifact, not after you've shared it.

I ended up writing my conventions down as a skill file so the agent applies them the same way every time instead of me remembering to say it. A rule you have to remember is a rule you will forget. My skills live here if you want the format: https://github.com/freema/ai-skills

So is this what Artifacts are for?

Genuinely not sure. The feature is marketed as a place to preview code and content, and I'm using it as an internal document surface with a stable URL. Might just be a shape that happens to fit.

But "one link that stays current" is quietly the best part of it, and I haven't seen anyone talk about it that way.

Are you doing something similar on your team?

My note server has no search engine. Search still answers in 0.4 ms.

Tomas Grasl — Thu, 16 Jul 2026 13:00:00 +0000

vellum MCP is a self-hosted server over a folder of markdown, your agent's memory as plain .md files you own. Search is the feature everyone expects to be "solved" by a library: bolt on bleve or a vector index and move on.

I never did. Search is a ranked scan over the notes, held in RAM. No engine, no index to build. Bragging about not adding a dependency is a strange flex, so let me show you what that plain scan actually costs, and how one optimization pass later it runs about 5× faster than my first honest cut of it. This is the case for the boring option.

The heavy default

A bundled search engine sounds like the responsible choice, and for a large enough corpus it is. But look at what it actually drags in for a personal note vault:

an index to build and keep in sync with the files, a second source of truth that can drift, or corrupt
a warm-up cost, and memory for the index structures
a dependency with its own release cadence, CVEs and quirks
for vector search specifically: an embedding step, which means calling out to a model, which means API keys and network and cost, for search

For a vault of a few thousand notes, that's a lot of moving parts to answer "which notes mention OAuth."

What I did instead

The whole content is already in memory. Vellum holds the vault in an in-RAM index it rebuilds from disk in about 50 ms at startup. So search is just a ranked scan over that: walk the notes, score each against the query, sort, return the top slice. No separate index, nothing to warm up, nothing to corrupt.

Here's what that costs on a 2,000-note vault (Apple M4 Pro, warm):

Query type	Time
exact term	0.38 ms
accent-folded, multi-term	0.74 ms
worst-case typo match	0.39 ms

Sub-millisecond, every time. Nothing to invalidate except when a file actually changes. The cache keys off each file's mod-time and size, so an edit through the MCP layer, the web editor, or your text editor all invalidate the same way.

The matcher earns its keep

The reason I don't miss the library is that writing the matcher myself made it more forgiving, not less. Three things it does that matter for real notes:

Folds diacritics both ways. ukol finds úkol; poznamka finds poznámka; and the reverse. When half your notes are in a language with accents and you're typing on muscle memory, this is the difference between "found it" and "search is broken."

Tolerates typos, scaled to word length. For a 4 to 7 character word it allows one edit; for 8+ it allows two. So preklapy finds překlepy. Short words stay strict (you don't want cat matching car), long words get slack where a fat-fingered character is likely.

Ranks by where the match lands. A hit in the title beats a hit in a tag, beats one in the path, beats one buried in the body. And a match at the start of a word beats one mid-word. This is the part a generic engine gets generically right and a hand-written one gets right for your data. The ranking encodes how you actually think about your own notes.

The escape hatch

I'm not claiming a linear scan is the answer for everyone. It's the answer for this size of problem. So the search sits behind a Searcher interface. The day a vault gets big enough that a scan hurts, I can drop a real engine in behind the same seam without touching the callers.

That day hasn't come. Two thousand notes in, a full ranked scan is still sub-millisecond, and honestly it would take an order of magnitude more before the constant factors start to matter. When you do cross that line (tens or hundreds of thousands of documents, or you genuinely need semantic similarity rather than lexical matching), reach for the index. Below it, the index is the heavy option pretending to be the safe one.

The takeaway

"Use a library for search" is good advice that stops being good at small scale, and small scale is where a lot of self-hosted tools live. Before you add the dependency, the index, the warm-up and the embedding pipeline, check whether a scan over what's already in RAM answers in under a millisecond. For a personal knowledge base, it very likely does.

Sometimes the library is the heavy option.

👉 github.com/freema/vellum. MIT, one 24 MB container.

Where's your line for "just scan it" vs. "build an index"? I'd put it somewhere north of 50k documents for lexical search. Curious where others draw it.

Resources for reading, tools for acting: the MCP design choice most servers get wrong

Tomas Grasl — Wed, 15 Jul 2026 13:00:00 +0000

Every tool you expose over MCP ships its full definition (name, description, JSON schema) into the model's context on every single request, whether that tool ever gets called or not. Expose twenty tools and the agent wades through pages of boilerplate before it has read one of your notes.

That cost shaped the best decision I made building an MCP server in the open this week, and it isn't a feature. It's a split: tools are for acting, resources are for reading. Most MCP servers I've looked at ignore that line and expose everything as a tool. I think that's a mistake. Here's why.

The hidden cost of a tool

Sit with what that per-request tax actually buys you: nothing, most of the time. A note server that exposes "read this note," "list those notes," "get this document," "fetch that attachment" as four separate tools pays for all four on every turn, including the turns that only write. It's quietly burning your context window on plumbing.

MCP already gives you a better primitive for exactly this. It's called a resource.

What vellum MCP does instead

vellum MCP is a self-hosted server over a plain folder of markdown files. Your notes stay as .md on disk, no database, no embeddings. When I designed the surface, I split it clean down the middle.

Tools are for acting. Writing a note, moving it, patching a section, flipping a task from backlog to done. Fifteen of them, and I keep the number small on purpose. Every one costs context.

Resources are for reading. Every note is exposed as an MCP resource at a stable URI:

vellum://note/projects/launch.md

That changes two things:

The agent (or you, in a client's resource picker) can attach a document as context by reference. No tool call to fetch it. You point at the note by name and it's there.
A client can subscribe to that URI and get a notification the moment the note changes, whether the edit came through an MCP tool or from someone typing in the web editor. The list only re-announces when a note is created, deleted or renamed, not on every keystroke.

The result is an agent that references your documents by name instead of spending a tool round-trip to go get them. Less context on how, more room for what.

This is the whole philosophy, in miniature

I've been calling vellum MCP "deliberately light," and this is what I mean by it. The wins don't come from piling on features. They come from using the right primitive for each job and refusing to add weight that doesn't earn its place.

The same instinct runs through the rest of it. Search is a ranked scan in RAM, not a bundled search engine you have to warm up and can corrupt. Auth is the server being its own OAuth issuer, no external identity provider. The whole thing is one 24 MB container that idles at about 5 MB of RAM. docker compose up -d and it's running.

None of that is clever. It's mostly saying no.

Try it

vellum MCP is MIT-licensed and self-hostable in one command. If you're building with MCP, the tools-vs-resources split is the one idea I'd take even if you never touch my code.

👉 github.com/freema/vellum

What's your rule for when something becomes a tool vs. a resource on your own server? I'm curious how others draw that line.

Most code review catches bugs. I shipped one that argues with the design.

Tomas Grasl — Tue, 14 Jul 2026 18:00:00 +0000

The cheapest bug to catch is the one a reviewer circles on line 40. The expensive one never shows up as a bad line it ships as the wrong approach, clean and green. Your retry loop is correct and also retrying in the wrong layer. Your cache has no bug and invalidates on the wrong key. A normal review human or AI slides right past those, because it's anchored on "is this line right," not "is this the right thing to build."

This week I shipped v0.4.0 of cursor-plugin-cc, and the headline is a review command whose entire job is that second question.

Quick context if you haven't seen the plugin: it's a Claude Code plugin that keeps one loop running Claude plans, Cursor's Composer writes the code, Claude reviews the diff without leaving the Claude Code TUI. Two tools, each doing the half it's best at. v0.4.0 sharpens the review half.

`/cursor:adversarial-review`

A read-only review that questions the chosen implementation and design instead of only hunting implementation defects. You point it at a diff (working tree by default, --base <ref> for a branch, --scope, --model same target selection as the normal /cursor:review) and it pressure-tests:

the assumptions the change depends on,
the tradeoffs you made, spoken or not,
the failure modes under real load, concurrency, and edge cases,
and the one that matters most — whether a simpler or safer approach would have done the job.

It's steerable: any trailing text is a focus. "is the retry/backoff design sound under load?" aims the whole challenge at exactly the thing you're nervous about.

/cursor:adversarial-review
/cursor:adversarial-review --base main
/cursor:adversarial-review "question the retry/backoff design under load"
/cursor:adversarial-review --background --model opus look for race conditions and question the approach

Under the hood it's /cursor:review --adversarial, so it shows up as a normal job in /cursor:status, /cursor:result and /cursor:cancel. What used to be a --adversarial flag most people never found is now a first-class, discoverable command — and it's user-invoked only (disable-model-invocation: true), because a design challenge is something you reach for on purpose, not something an agent should fire off on its own.

Why split it out instead of just telling /cursor:review to "try harder"? Because a stricter bug pass and a design challenge are different jobs, and conflating them gets you neither. Naming the second one makes you actually run it — right before you ship a change you're not fully sure about, which is exactly when nobody bothers.

The part I'm quietly proud of: it can't touch your code

Both review commands are read-only by construction, not by good intentions. The run happens, then a post-flight check fails the job if the working tree changed. So a review can never quietly turn into an edit — even though the same plugin runs Composer elsewhere with auto-approve on. You can hand a fast model your diff and know the worst it can do is talk.

That guarantee is the whole reason I trust an adversarial pass. A reviewer that might also "helpfully" refactor while it argues is a reviewer you have to babysit.

Estimate first, then ask

Small ergonomics fix that removes a daily papercut. If you don't pass --wait or --background, the command now sizes the diff first — git status, git diff --shortstat, counting untracked files — and asks you once whether to wait or run it in the background, recommending background for anything beyond a tiny 1–2 file change. A multi-file review takes a while; you shouldn't have to guess up front whether it's going to block your terminal for the next two minutes.

The real lesson: I moved the know-how into a skill

The most interesting change isn't a command. For a while, the guidance for how to turn a task into a tight Cursor prompt ground it in the target repo's conventions, the five required sections (Goal / Repo context / Acceptance criteria / Files to touch / How to verify) plus a guardrails block, chunk anything over ~5 steps or ~10 files or 2 architectural layers, pick the smallest model that fits, resume vs. fresh — lived inline inside the cursor-runner subagent's prompt.

In v0.4.0 that moved into a composer-prompting skill. The subagent now references it with a single skills: line and shrank down to its operational spine: ground → invoke /cursor:delegate → return Cursor's output verbatim.

The lesson generalises past this plugin, and it's the same thread running through everything I've been writing about MCP and agents: an agent's prompt is context you pay for on every single run. Reusable know-how doesn't belong restated inside each agent that needs it — it belongs in one referenced skill that loads when it's actually relevant. The agent gets leaner, the knowledge gets a single home instead of three drifting copies, and the thing you maintain shrinks. Same instinct as splitting tools from resources on an MCP server: put weight where it earns its place, and nowhere else.

The boring guarantees

Still zero runtime dependencies — plain ESM, Node stdlib, no build step, no dist/. Still MIT. CI runs the tests and lint across Node 18.18 / 20 / 22 on Linux and macOS on every PR. And it's openly adapted from openai/codex-plugin-cc — the Codex/GPT original that pulls the same trick on OpenAI's side — ported to the Cursor CLI. Credit where it's due.

Try it

/plugin marketplace add freema/cursor-plugin-cc
/plugin install cursor@tomas-cursor
/reload-plugins
/cursor:setup

👉 github.com/freema/cursor-plugin-cc — v0.4.0, MIT.

When did a code review last change your **approach* instead of your lines? That's the review I actually want — and the one almost nobody runs. Curious whether you've found a way to make it a habit.*