DEV Community: Chirag Aggarwal

Keeping track of your agent's work

Chirag Aggarwal — Mon, 26 Oct 2026 12:47:20 +0000

Agents are long-running LLMs, and long-running LLMs lose context. Not sometimes. Eventually, almost always.

The agent doesn't tell you when it happens. It compacts, summarises, or starts a new session, and whatever didn't make the cut is gone. The worse part is that you lose context too, and you usually don't notice either.

How the context goes missing

Three things keep happening to me.

The agent finds something important and mentions it once. Halfway through a task it notices a second bug, a migration that will break existing data, or a flag that does something nobody expected. It writes one line about it, carries on with what you asked for, and never brings it up again. After the next compaction it doesn't know either.

You can't see what it forgot. When I lose track of my own work, I at least know I've lost it. With an agent the context is invisible. I don't know what's in its window, what got summarised away, or which decision from two hours ago is still being honoured.

It writes more than you can read. An agent can produce pages of output, plans, and reasoning in the time it takes me to read one paragraph. Most of it is fine. Some of it matters. Finding the part that matters takes longer than the agent took to write all of it, so I skim, and skimming is how the one important line gets missed.

Put those together and the important stuff ends up nowhere: not in the agent's context, not in your head, and buried somewhere in a transcript nobody will read again.

Give every piece of work a ticket

The fix I've settled on is boring: an issue tracker. One place for each feature or fix I'm working on, where the state of that work lives outside both the agent and me.

A few rules make it work.

Scope it however you like. A ticket can be as broad as "ship passkeys" or as narrow as "fix the logo on the consent screen". When something gets big, split it into sub-issues instead of growing one giant description. The parent says what we're doing and why. The children say what's left.

It has to make sense to you. This is the whole point. If the ticket reads like the agent's scratchpad, you've just moved the gibberish somewhere else. Decisions, open questions, things that were found along the way, what's done, what isn't. Short enough that I can read it in a minute and know where things stand.

The agent keeps it up to date, always. Not at the end. Every time it finds something, decides something, or finishes a step, it goes in the ticket. That one-line mention of a second bug becomes a sub-issue instead of a sentence that disappears after the next compaction.

The side benefit: anyone can pick it back up

Once the state lives in the ticket, the session stops mattering.

If I hit a usage limit mid-task, or a session dies, or I just close the laptop and come back a day later, a fresh agent can read the ticket and carry on. It doesn't need the old transcript or me re-explaining everything. The same goes for a different agent, or a teammate, or me in a week when I've forgotten all of it.

Examples

All of these are from the last month of my own sessions.

Mentioned once, then gone. While fixing text responses in the SDK generator (#1944), the agent noticed Dart models type nullable fields as non-null and offered to leave it out of the PR. I never replied. It never came up again, and the template still only checks whether a field is required.

Still on main a month later (model.dart.twig)

A ticket that reads like a status page. #13828 tracked moving our libraries into the monorepo in waves. The agent rewrote the top of it after each wave, so "where we are" was always one glance away.

#13828, kept current by the agent

A finding becomes its own issue. While researching something else, an agent found endpoints returning a 500 for values too long for their column. It filed #14293 instead of mentioning it in passing, so I could hand it to the database team. It's closed now.

#14293, filed by the agent

Parked work anyone can resume. When we deferred the last wave, it got its own issue, #14255, with the branch, the commit and exactly what to do next. Any session, or person, can start from here.

#14255, the handoff for wave 6

What I'd tell someone starting

Assume your agent will lose context. Plan for it instead of hoping it won't.
Give every feature or fix a ticket. Split big ones into sub-issues.
Write tickets for a human. If you can't read it in a minute, it's not doing its job.
Make the agent update the ticket as it goes, not at the end.
Treat the ticket as the handoff. Any session should be able to start from it.

The agent will forget. The ticket won't.

Originally published on chiragaggarwal.tech.

A Master's in Ireland While Building Appwrite

Chirag Aggarwal — Mon, 26 Oct 2026 12:37:04 +0000

TL;DR

I moved to Ireland on August 30, 2026 to start an MSc in Software Engineering at the University of Limerick, and I'm still working full-time as a Platform Engineer at Appwrite. It's been just over a month, my first midterm is literally tomorrow, and enough has happened that I wanted to write it down: how I got here, why I came, and what comes next.

Why a Master's, and why now

Not many people know this, but I started working at Appwrite while I was still doing my bachelor's at Bennett University in India. I joined as an intern for six months and then moved to full-time. By the time I graduated in May 2026, I'd already been at Appwrite for a year and a half.

Doing both at once never felt like a compromise. I loved the work and I loved studying, and the two fed into each other in a way I wasn't ready to give up. So instead of picking one, I signed up for another degree.

There's a second reason, and it has more to do with where the industry is right now. With AI, you can prompt almost any feature into existence. It's very easy (and I'm guilty of this too) to take a request from a product person, paste it into a Claude Code session and ship whatever comes out, without putting any real thought into it.

That's exactly why I think the fundamentals matter more now, not less. Knowing how to design a system, and why some designs hold up while others fall apart, is the part an agent can't do for you. One month in, I'm reading Martin Fowler, Grady Booch and the Gang of Four on design patterns. Yes, I'm only now properly meeting these people, and yes, I'm enjoying it a lot.

Work teaches you a lot, but mostly it teaches you whatever this week's problem needs. A degree gives me room to step back and learn the reasoning behind patterns I already use every day, and to put names to things I'd only ever picked up by osmosis. Once you can name a pattern, you can spot it, question it and explain it to someone else, which matters a lot more when an agent is writing half the code.

Why Ireland

Ireland is tiny compared to India, but it punches well above its size. I kept hearing about new startups coming out of it, the tech scene keeps growing, and most importantly the education looked hands-on and practical. That was especially true of the University of Limerick, which is where I ended up.

Dublin was a close second. It's where most international students go, it has more universities, and it's a much denser city. Limerick felt calmer, and that was exactly what I wanted.

The visa took a long time. A very long time. It was my first visa application, so I had no idea what to expect. Collecting documents alone took weeks, mostly because my university was slow to issue my provisional degree. Once I applied, the decision took about five weeks and arrived uncomfortably close to the start of my course. If you're applying, start earlier than you think you need to.

A picture with Wolfie, the mascot of UL Student Life

Keeping Appwrite in the picture

I've always been open with the team about my plans, and they've backed every decision I've made. Working at Appwrite has never felt like something I had to force. I get to build technology I care about with what is honestly the best team I could ask for, and it has always felt like home. (Literally, since I work remotely. But still, I've never once wanted to quit.) Thankfully the team felt the same way about me, so the work continues!

What has changed is how I work. Lectures often clash with my sync meetings, so a lot more of my work is async now. That has forced better habits on me: planning everything ahead, keeping blockers to a minimum, and communicating more clearly.

The communication part is the one I feel most. I have fewer hours to unblock someone, so if a misunderstanding is my fault, it costs more than it used to. An async message has to stand on its own: what I did, where I'm stuck and what I need from whom. If I leave a gap, someone waits half a day for me to come out of a lecture and fill it.

Being fully remote has plenty of perks, and being able to do all of this from a different country is one of them :D

The move

Ireland's housing crisis is as bad as everyone says. Just a few days ago, students in Dublin were protesting over exactly this. I was lucky to get on-campus accommodation, so I can walk to my classes and make it to the university gym or a tennis session at a few minutes' notice.

The thing nobody really prepares you for is the weather. Everyone warns you about the rain, but it doesn't land until you live in it. "Constant rain" sounds like a proper downpour, and usually it isn't. It's more of a background process: a light drizzle that never quite stops and keeps the roads permanently wet. Then, at the most inconvenient moments, like when I need to walk to class, it turns into a small storm.

I'm also still getting used to cooking for myself, doing my own groceries and learning a whole new set of food brands. A lot of things taste better here. I will say, though, that restaurant food and street food were better back in India :P

Visiting the Cliffs of Moher on a guided trip by UL Student Life

What I'm looking forward to

There's so much here I want to try. I've already started playing tennis again, which I played a lot in high school but hadn't touched in about four years. With the courts a two-minute walk from my room, it's very hard to find excuses.

I'm also going to far more events than I used to. At a small computer society event, I built a heartbeat monitor, my first ever hardware project. I spend my days on servers and APIs, so wiring up a sensor on a breadboard and watching my own pulse appear on a tiny screen was a completely different kind of fun.

My first ever hardware project: a heartbeat monitor. Verdict: normal human

Events aren't limited to Limerick either. I went up to Dublin for the MongoDB student hackathon during Dublin AI Week, which was a great excuse to see a bit more of the country and meet students from other universities, including one from Trinity College Dublin who had a much shorter trip than I did.

The MongoDB student hackathon, part of Dublin AI Week

There's also a real overlap between what I'm studying and what I build at Appwrite. Modules like Advanced Software Design are all about writing enterprise-grade software that is reusable, extensible and maintainable. That's not abstract for me. Appwrite is a large, open source codebase that a lot of people depend on, and every shortcut we take there gets copied, extended and maintained for years.

A lot of what I'm reading about already exists in that codebase in some form. Utopia's database library, which Appwrite is built on, gives you one interface with a separate adapter for each database engine underneath, which is pretty much a textbook example from the patterns books. Learning the theory behind code I already work in every day makes both of them click a lot faster, and I'm excited to bring more of it back into my work.

One month in

It's busy. Lectures, assignments and Appwrite all want my time, and there's a midterm tomorrow that I should probably be revising for instead of writing this :P But it's the good kind of busy. What I learn in class connects straight back to my work, and outside of both I'm doing things I hadn't done in years. Ask me again after exams, but so far I'm really glad I made the jump.

Thank You

To the Appwrite team, for backing this from the very first conversation and making it possible to keep doing work I love from a new country. To UL Student Life, for Wolfie, the Cliffs of Moher and making a new place feel welcoming so quickly. And to my family and friends back home. India is four and a half hours ahead, so my evenings are your late nights, and our calls have moved to my mornings. Thank you for working around that so I can be here.

You can check out my profile to learn more about me: https://www.chiragaggarwal.tech/

If you're thinking about studying in Ireland or juggling work and a degree, hit me up on any of my socials. I'm always up for a chat :D

Originally published on chiragaggarwal.tech.

My agent has two Playwrights

Chirag Aggarwal — Mon, 26 Oct 2026 12:36:32 +0000

My agent made 1,929 browser calls through Playwright MCP last month, and almost none of them were tests.

That surprised me, because I do have tests. The Appwrite console has a playwright.config.ts, CI runs four Console E2E jobs on every pull request, and I spent part of the month fixing flakes in them. None of the 1,929 calls, spread over 62 sessions in my Claude Code transcripts between 17 September and 17 October, ran that suite. They used the browser for something else.

So my agent has two Playwrights, and I've stopped treating them as one tool.

Two jobs

The test suite answers one question: did something that used to work stop working? It runs headless in CI, it's mostly deterministic, and it doesn't care what anything looks like.

Playwright MCP answers a different one: does the thing I just built look right? Nobody has written an assertion for that, because an hour ago the thing didn't exist. The agent opens a real browser, goes to the page, clicks through it, reads it back and takes a picture.

Interactive version on the original post.

Screenshots are the second most common call overall. In the sessions where the agent was checking its own work, they're the most common: 281 screenshots against 226 navigations, and 209 of those navigations went to localhost or a local file. It isn't browsing the web. It's looking at what it just made.

browser_evaluate is mostly reading, not poking. Of its 304 calls plus 188 run_code_unsafe calls, 175 use querySelectorAll and 151 read innerText. A handful flip the dark class on <html> so the next screenshot shows the other theme.

This is what one of those pictures looks like. When Appwrite added function intervals as an alternative to cron, the agent built the console picker, then opened it in the browser and screenshotted every state before the PR went up.

The interval picker, checked by the agent in a local console before review (#14319)

Where the calls went

What the session was for	Sessions	Calls
Checking a UI, docs or release change	34	1,209
Chores in logged-in web apps	23	553
Research	5	167

Nearly two thirds is verification. The rest is a different story, which I'll come back to.

Three sessions

"The logo looks off"

I pasted a screenshot of the Appwrite CLI's device sign-in screen and typed four words: "the logo looks off, debug why". The logo was a black mark sitting on a near-black card.

The asset was fine. Every official app logo in that storage bucket is black on transparent, on purpose. The marketplace already knew this: its logo component puts the image on a muted tile and inverts it in dark mode. The OAuth consent screens just didn't use that component.

The fix was to move it into a shared AppLogo and use it in both places. The part I care about came after. I asked the agent to check the other OAuth clients too, and it used the console's debug preview route to render the consent and result screens for Claude Code, Cursor, Codex, Claude Desktop and Gemini CLI in dark mode, then did one pass in light mode. That took 19 Playwright calls, with no errors, and produced eight screenshots.

No test in the suite would have caught this, because no test checks that a logo is visible against its background. If I wrote one now, it would only protect against the last bug.

The OG image X wouldn't show

The passkeys announcement showed a grey placeholder when shared on X. The agent found the cause quickly: the cover image was AVIF, and X only renders JPG, PNG, WEBP and GIF for cards. Every blog and changelog cover in the repo is AVIF, all 538 of them.

The fix was a route that converts the cover to JPEG for og:image and twitter:image only. Then I asked for "pure reproduction and fix verification screenshots in pr desc". The agent built two small pages showing the share card before and after, resized the browser to the card's size and took a screenshot of each. Its first attempt failed because Playwright MCP blocks file:// URLs, so it served the pages over local HTTP instead.

The two screenshots that went into the PR description

Then the suite took over. The review bot flagged two problems, a type-baseline check broke because of the new route, and the four Console E2E jobs ran. Once all 20 checks were green, #14622 was ready. Both Playwrights were in that PR: one showed the reviewer what changed, the other showed that nothing else did.

Release QA for 2.3.0

The biggest session of the month used 183 Playwright calls. I'd asked the agent to "do end to end testing of release notes, especially frontend side" before shipping Appwrite 2.3.0.

It built the 2.3.0 image locally, installed 2.2.0 in a separate Docker Compose project so my dev data stayed safe, seeded it, and upgraded. migrate failed: projects that already existed never got the new pushLedger collection. After fixing that it found a second gap: existing topics were missing the new qos, expiry and sequence fields. Both fixes shipped with regression tests and went into the release branch before anyone upgraded.

To be fair, the browser didn't find the migration bug. migrate exiting with code 1 did. What Playwright did was walk the console against the upgraded install and check each claim in the release notes, one screen at a time. Still, nothing in the test suite runs an upgrade. Release QA used to be manual QA. Now it's manual QA I hand to an agent.

Where the browser does earn its keep is reproducing what users report. After 2.4.0, someone in the community said the upgrade wizard ignored their custom ports. I pasted the feedback and asked the agent to confirm each issue before fixing anything. It installed a stack on ports 8080 and 8443 with HTTPS on, opened the upgrade wizard, and screenshotted it offering 80, 443 and HTTPS off. Then it fixed the bug and took the same screenshot again. Nobody writes a test for this kind of bug until it bites someone.

Same install, two upgrade wizards (#14345)

Every PR gets a picture

This is the habit I care most about. A reviewer can't run your branch, but they can look at it.

The loop has four steps:

The agent checks the change with Playwright MCP.
It saves each screenshot under a name that says what it shows: passkeys-off.png, passkeys-on.png, cli-device-light.png. 317 of the month's 332 screenshots had a name like that.
It writes the PR description with relative image links like ![Before](./before.png) and runs gh pr create --attach or gh pr edit --attach. Recent versions of gh upload each file to GitHub and rewrite the link to point at the upload.
It deletes .playwright-mcp/ and any loose PNGs so none of it gets committed.

A good pair needs no explanation. When self-hosted consoles stopped offering OAuth and passkey sign-in, the PR showed the page before and after, and the reviewer could see the change in a second:

Self-hosted console sign-in, before and after (#14434)

Dark mode gets its own screenshot, because that's where things like the invisible logo hide:

Passkey sign-in in dark mode, with the last-used badge (#14400)

I didn't start with --attach. Over the month, screenshots reached my PRs three ways: committed to an orphan branch on my fork and linked through raw.githubusercontent.com, committed to a repo as docs assets, and attached. A reviewer caught the problem with the first one: "Screenshot evidence disappears after merge. Screenshots reference an assets branch that the instructions then delete." If the screenshots live on a branch you delete, the evidence goes with it. Attachments stay. 32 of the 53 PRs with screenshots now use them.

And 53 out of 904 is the honest number. The rate depends on the repo. In the two public Appwrite repos where most of my UI work lands:

Repo	PRs	With screenshots
`appwrite/vibes`	39	11 (28%)
`appwrite/appwrite`	224	25 (11%)

Backend-heavy repos sit far lower, which is partly fair, since there's often nothing to look at. But there's a less flattering reason too: I asked for screenshots by hand about 30 times this month ("add screenshots in pr desc", "before and after screenshot in pr desc", "show screenshots of ur testing in pr desc"). The habit only happened when I remembered to type it.

So I made it a rule. This is now in my global CLAUDE.md:

If a PR changes anything a reviewer can see (UI, rendered docs, emails, OG cards, dashboards), verify it with Playwright MCP and put screenshots in the PR description without being asked: before and after for fixes, light and dark for UI. Name each file for what it shows, reference it as ![alt](./name.png) in the body, and upload with gh pr create --attach / gh pr edit --attach. Never host screenshots on a branch that gets deleted, and never commit .playwright-mcp/ or stray PNGs.

The other 553 calls

These had nothing to do with UI work. Help Scout, the university's Brightspace, the Google Cloud and AWS consoles, an SMS provider's dashboard. These are tools I use daily that either have no API or none I have access to.

The pattern is always the same: "use playwright to login to helpscout, i want you to check some tickets". I log in myself in the browser window, and the agent reads. The browser becomes an API for software that doesn't offer one. That's a different post, but it's why the server stays installed even in weeks when I'm not building UI.

Where it falls short

About 10% of calls fail. 195 of 1,929 returned an error. The biggest causes were boring: the browser or tab had already closed (36), scripts trying to read files outside the sandbox (25), and timeouts waiting for a page or element (around 30). Four were "Browser is already in use", which usually means two parallel worktree sessions wanted the same browser profile.
Phones barely exist. There were 45 resizes this month and exactly one was a phone viewport, 390 by 844. Everything else was desktop. That's a blind spot, not a policy.
file:// is blocked. Any quick HTML mockup has to be served over HTTP first.
Screenshots land in the repo. By default they go into .playwright-mcp/ at the repository root. Several sessions ended with the agent cleaning up after itself, and in at least one session the screenshots ended up in the main checkout instead of the worktree.

What I'd tell someone starting

Keep the test suite for anything that must never break. A screenshot is evidence, not a regression test.
Use the MCP browser for the question the suite can't ask: does this look right?
Name every screenshot and check both themes.
Put before and after in the PR as attachments, not links to a branch.
Write the rule down, so it doesn't depend on you remembering to type it.

The suite catches what broke. The screenshots show the reviewer what's new.

Originally published on chiragaggarwal.tech.

Seven months of coding agents: what $28,335 actually bought

Chirag Aggarwal — Mon, 26 Oct 2026 12:36:00 +0000

Seven months, $28,335, across five agent harnesses. For a lot of people running agents right now that's a heavy week.

I publish that number on /trends and it updates itself, so I've had a while to look at it. What I expected to find was a story about cost. What's actually in the data is a story about scheduling, and the number that tells it is this one: 0.7% of my agent's tool calls happened between midnight and six in the morning.

Claude Code and Codex arrive at 0.7% independently. Different vendors, different session formats, 1,432 sessions between them, and I only noticed the match because I ran the same script twice and thought I'd double-counted.

The shape of the bill

Interactive version on the original post.

That's 201,473 tool calls bucketed by the hour I was awake for them. It looks like a workday because it is one. The peak is 16:00. The trough is 03:00, and the trough is empty.

An agent that runs unattended doesn't produce this shape. If you leave loops running, your histogram flattens — the overnight band fills in, because that's the entire point of leaving them running. Mine has a hole in it, and the hole is where I was asleep.

The weekly view says the same thing. Weekdays average $176 a day; weekends average $67. The spend tracks my calendar, not a scheduler's.

What the spend actually bought

Interactive version on the original post.

The curve is boring until April, where it goes up 7.4× in one month and then stays there. That's not a pricing change and it isn't a new model. April is when I stopped running one conversation at a time and started running agents in parallel git worktrees, which is the single largest change in how much I spend and the single largest change in how much lands.

Underneath it: 9,350 commits across 145 repositories since January, concentrated in sdk-generator, cloud and appwrite.

I want to be careful with that number, because it's the one most likely to be wrong in my favour. sdk-generator emits bulk generated output, so its 1,933 commits are not 1,933 units of thought. And only 205 commits carry a Co-authored-by trailer for an agent, which is not a measure of anything except how inconsistently I remember to keep the trailer. Take 9,350 as a statement of scale and nothing finer.

The leash is fifteen actions long

The interesting ratio isn't dollars per commit. It's how much rope the agent gets before I say something.

	Claude Code	Codex	Combined
Sessions	200	1,232	1,432
Human turns	3,016	10,336	13,352
Tool calls	29,438	171,040	200,478
Tool calls per human turn	9.8	16.5	15.0
Interrupts	218	1,829	2,047
Median human turns per session	7	4	—
Median session length	34 min	16 min	—

Sessions with at least one human turn, 12 January to 14 August 2026. Interrupts are escape presses in Claude Code and aborted turns in Codex.

Fifteen actions, then I say something. That is the whole working relationship in one number, and it has stayed roughly constant while the spend went up 300×. What April changed was how many leashes I hold at once, not how long any one of them is.

The interrupt count is the part I didn't expect. 2,047 times I stopped a run in progress — a little over ten times per active day. I'd have guessed a tenth of that. Interrupting is so cheap that it stopped registering as an event, which is a strange thing to learn about your own habits from a log file.

296 of 1,432 sessions were single-turn: ask, receive, done. That's 21%. The other 79% are conversations. The median session is four to seven human turns over sixteen to thirty-four minutes, which is not automation. It's pairing, with a partner who types faster than me and needs checking.

The part that argues against me

I have around 130 skills installed. Across all my Claude Code transcripts, they've been invoked 52 times.

Twenty-six of those are one skill, release-sdk, which is a genuine repetitive chore. After that: artifact-design six times, dataviz four, sentry-cli three, and then a tail of skills fired exactly once.

The infrastructure behind those 130 is not casual. There's a harness-neutral root at ~/.agents/skills with a lock file that pins each skill to a GitHub commit, symlinked outward into Claude Code, Codex and Pi, with a config listing fifteen harnesses it knows how to install into. ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md and ~/.config/opencode/AGENTS.md are byte-identical, all three md5 295f62fc. I built a distribution system for my own instructions.

And then I mostly don't invoke the things it distributes. I type instead.

There are two readings. The generous one is that skills are a library, and a library you consult four times a year is still worth having. The honest one is that I enjoy building the workshop more than I use the tools in it, and that 130-installed-52-fired is a tooling habit rather than a workflow.

Both are probably true. What neither reading supports is the idea that any of this productivity came from automation running without me.

The choice, and what it costs

Here's the objection I can't fully answer: is 0.7% restraint, or just circumstance?

Right now the marginal cost of running agents overnight is about as low as it will ever be. Everything is subsidised. I have the budget, five harnesses configured, worktree isolation already working, and a skills system that can install into fifteen agent runtimes. Every ingredient for a 24/7 loop is sitting on this machine, and the histogram still has a hole in it.

So it's a choice, and it's worth being clear about what I'm buying with it. Fifteen tool calls is roughly how much work I can hold in my head and still meaningfully review. Past that I'm not reviewing, I'm accepting. The 2,047 interrupts are the mechanism: they only happen because I'm watching, and I'm only watching because the run is short enough to watch.

The cost is real. There's work I could have shipped overnight and didn't. The trade is that I can still explain every one of those 9,350 commits, which matters more to me in a codebase I'll be on call for.

$28,335 over seven months is a modest bill by current standards. I don't think that's because I was careful with money. I think it's because a leash fifteen actions long is inherently cheap, and the thing it's actually buying is that I never stopped being the one holding it.

Originally published on chiragaggarwal.tech.

MCP 2.0: the release that deleted the handshake

Chirag Aggarwal — Mon, 26 Oct 2026 12:35:27 +0000

MCP versions are dates. 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25, and now 2026-07-28. From the outside they all look like the same kind of event.

The last one isn't. The working group called the release candidate "the largest revision of the protocol since launch," which usually means a long changelog. Here it means the connection model is gone. No initialize. No session id. No held-open stream. If you'd asked me a year ago to describe MCP in one sentence, that sentence would be wrong now.

Nothing you have deployed today stops working, which is exactly why it's easy to skim past.

The handshake era

Every MCP revision up to and including 2025-11-25 opened the same way. The client sends initialize with its protocol version, its capabilities and its clientInfo. The server answers with the version it picked, its own capabilities and its serverInfo. The client sends notifications/initialized. Only then is the connection allowed to carry anything useful.

That exchange establishes a session, and everything after it is defined relative to that session. Over Streamable HTTP the server could mint an Mcp-Session-Id, which the client then echoed on every request; DELETE ended it, Last-Event-ID resumed a dropped SSE stream.

The design makes complete sense if you remember where MCP started. In November 2024 it was a thing you ran as a subprocess of your editor over stdio. One client, one server, one pipe, and the pipe's lifetime is the session. Negotiating capabilities once at the start costs nothing when there is exactly one of everything.

Streamable HTTP arrived in 2025-03-26 and carried that model onto the network, where "the connection has a memory" stops being free.

Interactive version on the original post.

So you pick one: sticky routing, or a shared session store. Same problem, different bill. Every deploy drops live sessions. A crashed replica takes conversations with it. And since the session id tells a gateway nothing about what the request wants, the gateway has to open the JSON body to find out whether it's metering a tools/list or a database drop.

Four revisions of adding things to a connection, then one that removed the connection.

What 2026-07-28 actually does

The handshake is gone. No initialize, no initialized, no Mcp-Session-Id. Everything that used to be negotiated once now travels on every request, in _meta. The same tool call, before and after:

Before: 2 round trips

POST /mcp HTTP/1.1
Content-Type: application/json
{"jsonrpc":"2.0","id":1,"method":"initialize",
 "params":{"protocolVersion":"2025-11-25","capabilities":{},
           "clientInfo":{"name":"my-app","version":"1.0"}}}

POST /mcp HTTP/1.1
Mcp-Session-Id: 1868a90c-3a3f-4f5b
Content-Type: application/json
{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"search","arguments":{"q":"otters"}}}

After: 1 request

POST /mcp HTTP/1.1
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: search
Content-Type: application/json
{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"search","arguments":{"q":"otters"},
           "_meta":{"io.modelcontextprotocol/clientInfo":{"name":"my-app","version":"1.0"}}}}

The second one is cold. That client has never spoken to this server, nothing was set up first, and nothing is kept afterward. The three new headers are there so a gateway can route and meter it without opening the body.

Version negotiation stopped being a phase and became a field. The server accepts or rejects each request on its own, and if it can't speak the version it answers UnsupportedProtocolVersionError listing the versions it can, so the client retries. There's a server/discover method that returns supported versions and capabilities in one call, which servers MUST implement and clients don't have to call. Discovery is a convenience now, not a precondition.

Server-to-client calls stopped needing an open pipe. That was the load-bearing dependency on sessions. A tool that needs to ask the user something used to do it over a stream held open for the length of the call, which pins the call to one process.

Interactive version on the original post.

Under SEP-2322 the server returns an InputRequiredResult and hangs up. The client answers later with inputResponses and the requestState it was handed, and any instance can take it from there. SEP-2260 tightens things further: a server may only start a request while it's actively processing one from the client. Between them they replace elicitation/create and sampling/createMessage.

State moved into the open. The spec is blunt about where it went:

Servers that need to carry state across calls can do what HTTP APIs have always done: mint an explicit handle (a basket_id, a browser_id) from a tool and have the model pass it back as an ordinary argument on later calls.

The spec's own phrasing is that this "makes the state visible to the model rather than hidden away." A session was state the model never saw and could not recover once it was gone.

Infrastructure can read the traffic without parsing it.

SEP	What it adds	What it buys
2243	`Mcp-Method` and `Mcp-Name` request headers	Routing, metering and WAF rules with no body inspection
2549	`ttlMs` and `cacheScope` on list and read	Clients know how long a tool list is good for, and who may share it
414	`traceparent` / `tracestate` / `baggage` in `_meta`	One trace across client, gateway and server, into any OTel backend

A server rejects any request where the headers and the body disagree, which is what makes the headers safe to trust for anything that never looks inside.

Why this is 2.0 and not 1.4

The protocol changes are the part you notice. The governance changes are the part that decides whether any of it survives the next revision, and there are three.

Extensions became first class. They get reverse-DNS identifiers, negotiate through an extensions map, version independently of the spec, and live in their own ext-* repositories with their own maintainers. Tasks graduated out of the core and into io.modelcontextprotocol/tasks. MCP Apps, which is server-rendered HTML in a sandboxed iframe talking back over the same JSON-RPC, ships as one too. The core stays small and the interesting parts move at their own speed.

Features now have a lifecycle: Active, Deprecated, Removed, with a documented migration path and twelve months minimum before anything deprecated is eligible for removal. Three features entered it immediately.

Deprecated	Use instead
Roots	Tool parameters, resource URIs, or server configuration
Sampling	Your LLM provider's API, directly
Logging	`stderr` on stdio, OpenTelemetry for anything structured

All three still work. That's the point of writing the policy down.

Conformance became a gate. A Standards Track SEP can't reach Final until matching scenarios land in the conformance suite, and official SDKs are scored against that suite under a tier system. All four Tier 1 SDKs (TypeScript, Python, Go, C#) shipped 2026-07-28 support the day the spec did, with Rust in beta.

The remaining breaking changes are small but worth knowing. Tool schemas moved to full JSON Schema 2020-12, so oneOf, $ref and conditionals are legal now, and the spec says out loud that you must not auto-dereference external $ref URIs. structuredContent takes any JSON value instead of only objects. The missing-resource error went from MCP's custom -32002 to the standard -32602, which breaks anyone matching on that literal. Every 2025-11-25 Tasks implementation needs migrating.

We had already bet on this

I spent sixteen months building Appwrite's MCP server, and most of that time went to authorization. When I got to the transport, the hosted server went out with one flag set:

StreamableHTTPSessionManager(app=server, json_response=False, stateless=True)

No sessions. Every request carries a bearer token; verify it, build a client from it, serve the call, forget everything. I'd love to claim foresight here. The real reason is duller: OAuth had already made session state pointless, because the token identifies the user on every request, and I didn't want to run a Redis to hold something I had no use for.

The spec shipped on July 28. We merged 2026-07-28 support on July 29, in PR #89, by moving from MCP Python SDK v1.28 to v2.0.0. The HTTP and OAuth surface didn't move at all. What made it a day rather than a quarter is that v2's session manager routes on the protocol version header, so one deployment serves both eras:

def _is_modern_request(scope: Scope) -> bool:
    """Match the SDK's era-routing predicate: a present ``MCP-Protocol-Version``
    that is not a handshake-era revision goes to the modern path."""
    version = _header(scope, b"mcp-protocol-version")
    return version is not None and version not in HANDSHAKE_PROTOCOL_VERSIONS

Handshake versions, 2024-11-05 through 2025-11-25, take the legacy path. Anything else takes the per-request one. Nobody's client broke.

Three things did cost real work:

Tool errors. v1 wrapped a raised exception into CallToolResult(isError=true). v2 turns an uncaught exception into a sanitized -32603, so the model never learns why the call failed. Our confirm_write refusals are only worth anything if the model can read them, so every handler now returns is_error=True explicitly.
CORS. Mcp-Method and Mcp-Name ride on every modern request. If your allow-list doesn't name them, browser-based clients fail before they ever reach your auth code.
Metrics. Modern clients never send initialize, so our handshake counter would have quietly flatlined exactly as clients migrated, which is the worst possible time to lose a graph. It's keyed off activity windows now, so the timeseries stays comparable through the transition.

None of that is protocol work. It's the ordinary cost of a dependency changing shape under you, and it only took a day because a decision made eighteen months earlier, for completely unrelated reasons, happened to line up.

The good kind of boring

A 2026-07-28 MCP server takes an HTTP request, reads some headers, and returns a response. That's the whole shape of it. You can put it behind a CDN, cache its list endpoints, and restart it in the middle of someone's conversation without telling anyone.

It's a less interesting protocol than the one that launched in 2024. I think that's the point. The bidirectional stateful version was more fun to read about and considerably worse to operate, and operating it is what most of us actually do.

Reference

Term	What it means here
handshake era	Every MCP revision through `2025-11-25`, where a connection began with `initialize` and carried a session from then on.
`Mcp-Session-Id`	The header that identified that session. Removed in `2026-07-28`.
`_meta`	A metadata object on every request. Now carries protocol version, client info and capabilities, one copy per request.
`server/discover`	A single call returning supported versions, capabilities and identity. Mandatory for servers, optional for clients.
sticky routing	Making a load balancer send every request from one client to the same backend. The price of server-side session state.
`requestState`	The opaque blob a server hands back with an `InputRequiredResult` so the follow-up can be processed by any instance.
SEP	Specification Enhancement Proposal, MCP's change process. Standards Track SEPs now need conformance scenarios before reaching Final.
Streamable HTTP	The HTTP transport introduced in `2025-03-26`, replacing the original HTTP+SSE one.
CIMD	Client ID Metadata Documents, the replacement for Dynamic Client Registration in OAuth flows.

The spec

The release candidate announcement and the release itself
2026-07-28, versioning and negotiation, and server/discover
The feature lifecycle policy and the deprecated features registry
The 2025-11-25 changelog, for what the last handshake-era revision was still adding

The code

appwrite/mcp, and PR #89 — the dual-era migration
The hosted server is at https://mcp.appwrite.io/, or claude mcp add --transport http appwrite https://mcp.appwrite.io/

Originally published on chiragaggarwal.tech.

Will MCP replace the CLI?

Chirag Aggarwal — Mon, 26 Oct 2026 12:35:11 +0000

Every developer tool now seems to need an MCP server. The growth is real: monthly downloads of the MCP TypeScript SDK went from 1.9 million in March 2025 to 191.9 million in July 2026.

But the command line is not collapsing underneath it. Downloads of Commander, a widely used Node.js CLI framework, grew from 787 million to 1.93 billion over the same period.

Interactive version on the original post.

The numbers are imperfect because npm downloads include CI and transitive installs. Still, they look less like a replacement and more like a new layer being added.

MCP is not the GUI for agents

A GUI and CLI are interfaces for humans. MCP is a contract between a model host and software. The host discovers tools, gives their schemas to the model, validates arguments, and sends the call.

An agent can already use a CLI. It can run --help, execute a command, inspect stdout, and retry. MCP makes that operation typed, discoverable, and easier for the host to police.

That difference is enough to split the market:

MCP wins when…	CLI wins when…
The product is remote	The work is local
OAuth should happen in the client	Credentials already exist
Actions need a rendered confirmation	Commands need to run unattended
The agent must discover capabilities	The workflow must be reproducible
Structured output matters more than UX	Pipes, files, and exit codes matter

For a SaaS product, MCP is a much better front door. One URL and an OAuth flow can replace installing a package, setting environment variables, and teaching the model a command tree.

MCP turns installation, authentication, discovery, and approval into one client workflow.

For repository work, the calculation reverses. git diff, bun test, and docker compose logs are already available, inspectable, and easy for a human to rerun. Wrapping each in a tool server often adds schema without adding a useful boundary.

The MCP trend nobody advertises

Early MCP servers tried to expose everything. Clients and models pushed back. Cursor once sent only the first 40 tools to the agent; Windsurf refused servers that crossed its limit.

The current direction is smaller surfaces with search behind them. Appwrite went from 981 methods to four visible tools. Stripe and Sentry also put larger catalogs behind search; GitHub groups its tools into sets.

Interactive version on the original post.

That is a real drawback, not an implementation detail. MCP tools consume context merely by existing. A CLI can have hundreds of subcommands without pasting every help page into the conversation.

Uploads expose another mismatch. A hosted MCP server cannot read a path on the user's machine. Appwrite prefers a public URL, but also accepts a small image or deployment ZIP as Base64 inside the JSON tool call. Decoded inline content is capped at 10 MB, and Base64 makes the payload roughly one-third larger.

Interactive version on the original post.

The Base64 path works, but it is a hack around the transport. The CLI can open ./site.zip and upload its bytes directly without making the artifact public or passing it through the model's context.

MCP also gives you another service to operate: authorization, deployment, observability, client compatibility, schema versioning, and a security policy for every mutation. OAuth proves who the user is. It does not prove the model understood what the user wanted before calling delete_project.

The CLI's problems are older and easier to see: prose output, shell quoting, broad environment access, platform differences, and weak capability discovery. It is a worse interface for a model, surrounded by a better ecosystem for debugging and automation.

My prediction

MCP does not need to replace the CLI to win. It only needs to become the agent-facing adapter.

MCP will become the default way an agent first meets a remote product. The CLI will remain the deterministic path for local work, scripts, CI, and the moment an abstraction leaks.

So I do not expect a replay of “GUI beats terminal.” That verdict never happened. Most people chose GUIs; developers kept terminals for the work where precision and composition mattered.

MCP can win distribution without winning everything. The durable stack is likely an API underneath, a CLI for operators, and a narrow MCP surface for agents.

Originally published on chiragaggarwal.tech.

Appwrite MCP vs Vercel MCP: I benchmarked both

Chirag Aggarwal — Wed, 19 Aug 2026 17:12:09 +0000

An MCP server should be judged by what an agent can finish, not by how many tools sit in its catalog. So I pointed an agent at the hosted Appwrite and Vercel MCP servers and asked both to do the same job: deploy identical applications, inspect the builds, diagnose a deliberate failure, ship a second version, and recover from it.

The two servers are built for different jobs, and the result splits along those lines:

Appwrite reached much further into the backend and was the only one of the two exposing rollback, deletion, and explicit write confirmation through MCP.
Appwrite shipped a real bug into this run. Its runtime log tool fetched the data successfully and then told the agent it had failed.
Vercel deployed faster and reported runtime failures better. It reached READY in about 2.1 seconds on the static app and its dedicated log tools filter properly.

How I tested

Both hosted MCP servers ran over OAuth from the same Darwin 25.5 arm64 client. I threw away the first call to each tool so nobody paid for a cold start, then alternated between the two servers so neither got the benefit of going second. Anything that wrote data went into a throwaway project I could delete afterwards.

Two test apps:

A static site with identical index.html and marker.json files, deployed from the same source archive on both platforms.
A Next.js 15.2.8 SSR app with deterministic build markers and controlled 200, 400, and 500 responses.

Each agent had to discover its workspace, deploy both apps, inspect logs and analytics, recover from an intentional build failure, publish v2, attempt a rollback, and handle 50 requests at concurrency 10.

Six stages, same order, both platforms:

#	Stage	Fixture	What separated them
01	Orient	workspace + IDs	Vercel ahead: 4.6 against 3.4 on discovery
02	Deploy	same source bytes	Vercel ahead: READY in ~2.1s against ~27s
03	Break	exit code 42	Even, both diagnosed their own failure
04	Observe	3×200 · 1×400 · 1×500	Vercel ahead: filtered 12.3 KB against 115 KB
05	Recover	v2 + rollback	Appwrite ahead: rollback in 1.32s, not exposed at all on Vercel
06	Burst	50 requests · c=10	Even, both cleared it without errors

How I scored it

Six things counted, correctness most of all: correctness and completeness at 30%, then result compactness, discoverability and call economy, median and p95 latency, and safety and lifecycle control at 15% each, and error recovery quality at 10%.

The two combined totals landed close enough that the gap between them tells you nothing, and the per-category numbers behind them were never written up. The per-task scores from the read and observability phases are the ones worth putting on screen:

Task, out of 5	Appwrite	Vercel
Workspace and project discovery	3.4	4.6
Resource detail	4.6	4.4
List deployments	3.8	3.5
Deployment detail	4.6	4.3
Build logs	4.0	4.6
Runtime logs	2.4	4.2
Usage and analytics	4.7	3.7
Documentation search	4.3	3.5

Appwrite wins five of the eight tasks, and the three it loses are the ones it loses badly.

Router versus toolbox

Vercel exposes 33 direct tools covering projects, deployments, logs, analytics, agent runs, collaboration, domains, purchases, and deployment protection. Once the agent has a team or project ID, it calls a tool named for the task.

Appwrite exposes 992 operations across 81 services behind a handful of meta-tools. Instead of loading every schema into the model's context, the agent works through four calls:

appwrite_get_context to find the account, organization, and project
appwrite_search_tools to find an operation
appwrite_call_tool to execute it
appwrite_search_docs to search current documentation

The router usually costs one extra call before an unfamiliar operation, and buys access to Auth, Databases, Storage, Messaging, Functions, Sites, usage, domains, and infrastructure from one interface. Vercel's toolbox is easier to navigate as long as the work stays inside deployment.

What each server actually covers

Use case	Appwrite MCP	Vercel MCP
Static and SSR deployment	Sites, deployments, activation	One-call project creation
Build and runtime logs	Available, with defects	Dedicated, filter-rich tools
Auth and user management	Full backend management	Not exposed
Databases and storage	Full backend management	Not exposed
Functions	CRUD, deployments, executions, variables	Runtime and deployment inspection
Usage and analytics	Resource and compute metrics	Visitors, pageviews, routes, events
Deployment protection	Site and project controls	Direct protection and bypass tools
Domains	Domain catalog and DNS	Availability, purchase, management
Agent collaboration	No direct equivalent	Agent traces and toolbar threads
Rollback and cleanup	Activation, rollback, delete	Not exposed through the tested tools

Six strong rows each. "Not exposed" refers only to the MCP tool set I tested, not to what the platform can do.

Lifecycle control: Appwrite exposed more

Getting the first URL live is the easy half. An operator also has to publish updates, switch versions, disable things, and clean up.

Appwrite deployed v2 to the existing Site with an explicit build cache hit, switched the active deployment, and then rolled back to v1 in 1.32 seconds. The public health endpoint returned version: "v1" immediately. Disabling the Site returned a 404 router_deployment_not_found, and re-enabling restored v1 straight away.

Vercel's inline deployment tool created a new project for v2, which also meant it reported no previous build cache. Its tested MCP surface exposed no rollback, no redeploy to an existing project, no project deletion, and no general environment-variable management. Those capabilities exist elsewhere on the Vercel platform; the benchmark required MCP-only operation. The practical consequence is that both Vercel projects from this run are still live, because nothing in the 33 tools can delete them.

Write safety differed too. Appwrite required confirm_write=true before every mutation and refused the first unconfirmed create. Vercel's deploy tool had no equivalent parameter, though its commercial operations do separate quotes from purchases.

Deployment speed: Vercel was a bit faster

Vercel accepted an inline file tree and had the static app ready in about 2.1 seconds, on one write. Appwrite needed two, create the Site then upload and activate a gzipped deployment, and took about 27 seconds end to end. On SSR the gap narrowed to 39.1 seconds against a 91-second build, roughly 2.3 times faster on reported build time alone.

Both platforms rejected an earlier version of the SSR app, for different and legitimate reasons: Appwrite's adapter expected a next.config.* file, and Vercel blocked Next.js 15.2.4 over a known vulnerability. Each agent diagnosed its own failure from the logs it was handed.

Observed latency

Once the agent had picked a project, Appwrite was faster on every repeated read I measured, in the case of build logs by a factor of eight.

Repeated read	Appwrite	Vercel	Runs
Resource detail	416 ms	891 ms	3 + 3
Deployment list	448 ms	897 ms	3 + 3
Deployment detail	491 ms	914 ms	3 + 3
Build logs	319 ms	2,590 ms	1 + 1
Analytics	416 ms	915 ms	1 + 1
Docs search	525 ms	1,464 ms	3 + 3

Medians where three rounds landed, single calls where only one succeeded. Lower is better.

Both servers cleared the bounded concurrency check without errors. Appwrite returned 50 of 50 in 5.146 seconds wall time, Vercel 50 of 50 in 4.714 seconds. Vercel was modestly faster, and the sample is far too small to support a broader performance claim.

Compactness is where the read gap is real rather than marginal. Asking for 100 log entries returned roughly 115 KB from Appwrite for 96 events, which got context-truncated, against 12.3 KB of filtered events from Vercel.

Choosing between them

Appwrite MCP fits when the agent has to operate the backend as well as the deployment: users, data, files, messaging, functions, and Sites. It is also the stronger fit when you need explicit write confirmation, rollback, repeated deployment to one resource, and cleanup the agent can actually perform.

Vercel MCP fits when the job is deploying, inspecting, diagnosing, and analyzing Vercel-hosted applications. Its direct tools remove selection ambiguity, its builds were faster here, and its log filters make for a cleaner diagnostic loop.

Worth saying plainly: both of these deploy sites well. Every app I handed to either server went live, and both agents read their own build failure and fixed it without help. Vercel got there faster, 2.1 seconds against 27 on the static app and roughly 2.3 times quicker on the SSR build, and its log responses came back small enough to actually read. Appwrite was slower to the first URL and reached much further once it arrived: rollback, deletion, write confirmation, and the rest of the 992 operations behind the router, none of which the 33 Vercel tools touch. If your work stops at deploying, that speed is the whole story. If it doesn't, one extra search call buys you a lot.

Test conditions

Access. Hosted MCP endpoints, authenticated over OAuth.
Client. A single macOS arm64 machine, one continuous session.
Write phase. Static deployment, SSR deployment, an induced build failure, a second version, and a rollback.
Excluded. No paid protection tier was enabled, and no purchase operation was executed.
Scope. Results describe the MCP surfaces as tested, not controlled infrastructure benchmarks.

Originally published on chiragaggarwal.tech.

How utopia-php/client keeps fixing our memory leaks

Chirag Aggarwal — Wed, 05 Aug 2026 06:36:19 +0000

Originally published on my site, where the three diagrams are interactive.

One of our billing workers kept dying.

It would sit flat for hours, then climb into its memory limit in about four minutes and get killed. Kubernetes restarted it, and later the same day it happened again. Six times a day, every day.

The obvious first move is to look at what PHP is holding on to, and that's where it got strange. When PHP runs out of memory it tells you: a fatal error, a stack trace, the allocation that tipped it over. We had none of that. memory_get_usage() reported a flat 6 MB the entire time, right up to the moment the process vanished.

Those two facts together are the whole puzzle. Something was eating memory, and it wasn't the PHP heap. It was cURL, two sockets at a time, and the cause turned out to be a missing keyword.

We've chased this same shape in more than one Appwrite service now, and the fix has been the same every time: stop building a new HTTP client for every call, and move the library onto utopia-php/client.

What was actually leaking

The worker idles at ~330 MB against a 512Mi limit, which is the flat stretch below. Once a day the newly-due invoice batch runs, about a thousand invoices with several Stripe calls each, and it goes from comfortable to dead in roughly four minutes.

Memory as a percentage of the container limit; the axis starts at 45% because nothing happens below it. Six hours flat around 60%, then the batch starts and the line goes vertical: 332 MB, 374, 450, 533, against a 536 MB ceiling.

Luke traced it, and the code turned out to be completely unremarkable. Pay\Adapter::call() built a new Utopia\Fetch\Client for every request. In a one-shot FPM request that's fine; the process exits and the OS reclaims everything. In a long-lived worker it's a slow bleed, and the reason is a reference cycle that has nothing to do with the PHP heap.

curl_setopt stores your write callback on the CurlHandle. A closure declared inside an instance method captures $this. So the handle holds the closure, the closure holds the adapter, and the adapter holds the handle. Nothing can be freed by refcounting, and __destruct, with its curl_close, only runs when PHP's cycle collector fires. By default that means after 10,000 cycle roots have piled up. Until then every request strands an open keep-alive connection.

Reduced down, that's this:

final class Curl
{
    private ?CurlHandle $handle = null;   // the adapter holds the handle

    public function send(Request $request): Response
    {
        $body = '';

        // Nothing in here mentions $this. Declaring a closure inside an
        // instance method binds it anyway, and curl_setopt parks the
        // closure on the handle: adapter -> handle -> closure -> adapter.
        curl_setopt(
            $this->handle,
            CURLOPT_WRITEFUNCTION,
            function ($ch, string $chunk) use (&$body): int {
                $body .= $chunk;

                return strlen($chunk);
            },
        );

        // ...
    }
}

The fix is one keyword:

static function ($ch, string $chunk) use (&$body): int {

A static closure gets no $this, so the last edge never forms and refcounting frees the handle as soon as the adapter goes out of scope. Neither callback used $this in the first place, which is what makes the change safe and also what makes it so easy to miss.

Two file descriptors and roughly a megabyte of native TLS buffers per request, none of it visible to memory_get_usage(). Descriptors are capped per process too, so whichever ceiling you reach first decides how the thing dies: the kernel OOMKills you, or you start refusing connections with Too many open files. I've written that exact closure before, probably more than once, and it would never have occurred to me that static was load-bearing. Adding it to both callbacks in utopia-php/fetch took 150 sequential requests from 309 fds and 183 MB RSS to 9 fds and 31 MB, flat.

We shipped that and moved on, which was the wrong instinct. It fixed the symptom in one library and left three others still hand-rolling their own transport, each free to reinvent the same bug.

What the library is

utopia-php/client is a PSR-18 HTTP client for PHP 8.5. It's about 2,400 lines including both transports, and it doesn't try to be clever:

Every layer implements the same Adapter interface, so they stack in any order and a caller can replace any of them with a stub.

Utopia\Client itself does almost nothing at request time. It resolves the URI against a base, fills in default headers, optionally stamps a traceparent, and hands the request to an adapter. Connection lifetime, TLS, timeouts and error classification all live in the adapter. Anything policy-shaped lives in a decorator.

$client = new Client(new CurlAdapter())
    ->withBaseUri('https://api.stripe.com/v1')
    ->withBearerAuth($secret)
    ->withConnectionReuse()
    ->withTimeout(30);

$response = $client->sendRequest(
    new Request\Factory()->form(Method::POST, 'customers', ['email' => $email]),
);

Which specs it holds itself to

Writing your own HTTP transport in five places means reading the specs badly in five places. Here's what the shared one is on the hook for.

Spec	What it decides
PSR-18	`4xx`/`5xx` are responses; the two-branch exception contract
PSR-7 / PSR-17	Immutable messages and the factories that build them
RFC 9110	Idempotency, `Retry-After`, `Authorization`, content negotiation
RFC 9112	HTTP/1.1 framing, chunked bodies, status-line parsing
RFC 9113	HTTP/2, which APNs requires and HTTP/1.1 can't satisfy
RFC 3986	Base-URI resolution and dot-segment removal
RFC 6750 / 7617	`Bearer` and `Basic` credential formats
RFC 7578 / 2046 / 2183	`multipart/form-data`, boundaries, `Content-Disposition`
RFC 1951 / 1952 / 7932 / 8878	deflate, gzip, br, zstd content codings
RFC 8446	TLS 1.3, and the floor you can pin below it
W3C Trace Context	`traceparent` propagation

PSR-18 decides what counts as an error

The sentence that does the most work:

A Client MUST NOT treat a well-formed HTTP request or HTTP response as an error condition. For example, response status codes in the 400 and 500 range MUST NOT cause an exception and MUST be returned to the Calling Library as normal.

A 429 is not a failure, it's an answer. So sendRequest() returns it, and only genuine "there is no response" conditions throw. PSR-18 splits those into two branches: RequestExceptionInterface for a malformed request or response, NetworkExceptionInterface for a transport that failed. The type answers one question, which is the only one you have at the catch site. Would trying again help?

The library's own hierarchy keeps that property all the way down.

ClientExceptionInterface
├── NetworkExceptionInterface — retrying may help
│   └── NetworkException
│       ├── DnsException, TimeoutException, ProtocolException, ProxyException
│       └── ConnectionException
│           └── TlsException
└── RequestExceptionInterface — retrying is pointless
    └── RequestException
        ├── InvalidUriException, InvalidResponseException
        └── AdapterPreconditionException, AdapterInitializationException

Each adapter maps its native error codes into that tree. The cURL adapter matches on CURLE_* constants, guarded by defined() so a libcurl build without HTTP/3 doesn't fatal at load.

Another line from the spec you can find in the code almost verbatim:

If a Client chooses to decompress the message body then it MUST also remove the Content-Encoding header and adjust the Content-Length header.

Both adapters negotiate compression for you: the request advertises whatever codecs the transport can decode, and the response arrives as plaintext. Which means the Content-Encoding: gzip and Content-Length the server sent are now lies about the body you're holding, so the adapter drops both. Set your own Accept-Encoding and it gets out of the way entirely.

Retrying, and why only some requests get to

Retry is a decorator, and its default Backoff strategy reads almost directly off RFC 9110. Only idempotent methods (§9.2.2) are retried, so a lost response can't turn into a double charge. Only transient outcomes are retried: a NetworkExceptionInterface, or a 429 / 502 / 503 / 504. A numeric Retry-After (§10.2.3) beats the computed delay, because the server knows things the client doesn't.

With no Retry-After, the wait is exponential with full jitter: a value drawn uniformly from [0, ceiling) rather than the ceiling itself.

Our workers run as a fleet. A fleet that backs off deterministically comes back at a struggling upstream in lockstep and keeps it struggling.

Every one of those decisions lives behind a single method, so a library with different rules writes its own:

interface Strategy
{
    public function delay(
        RequestInterface $request,
        int $attempt,
        ?ResponseInterface $response,
        ?ClientExceptionInterface $error,
    ): ?float;
}

utopia-php/storage does exactly that. S3 signals throttling in an XML body as often as in a status code, so S3\RetryStrategy parses the body first and retries SlowDown, ServiceUnavailable, Throttling and RequestThrottled. It also refuses to retry a 503 whose body parses cleanly into some other error code, which is the case a status-code-only rule gets wrong.

`withBaseUri()` is not string concatenation

It looks like a convenience until you send ../v2/users and find out which one your client implements. This one does dot-segment removal, and only applies the base when the request URI is actually relative. An absolute URI passes through untouched.

Everything else is a header you'd otherwise hand-roll

withBasicAuth() is RFC 7617's base64(user:pass). withBearerAuth() is RFC 6750's Bearer <token>. Part::file() builds an RFC 7578 part with its RFC 2183 Content-Disposition. withMinTlsVersion(Tls::V1_2) is an enum each adapter maps to CURLOPT_SSLVERSION or Swoole's ssl_protocols. withTracePropagation() forwards the active utopia-php/span trace as a traceparent, and refuses to overwrite one that's already on the request.

None of these are hard. They're just wrong in slightly different ways in every library that rolls its own.

The four rules underneath

Reuse over recreate

withConnectionReuse() keeps one connection alive per client and reuses it for every request to the same origin. curl_reset() clears per-request options while preserving the handle's connection cache; the Swoole adapter keeps a kept-alive coroutine client keyed by origin. It's opt-in, on the theory that a client built for one call shouldn't sit on a socket. Any long-lived service wants it on.

For Pay, that one change was the entire fix. Four hundred requests against a local echo server, before and after:

	fds	RSS
client per call	+800	+21 MB
reused connection	+0	+48 kB

When you need concurrency rather than sequence, Client\Pool borrows a client from a utopia-php/pools pool per request and reclaims it afterwards, so N coroutines share a bounded set of connections instead of opening N of their own.

Every `with*()` returns a clone

In Swoole that's not a style preference. A shared client you can mutate is a cross-request bleed waiting to happen, and cloning means there's no way to reconfigure someone else's client from inside a request handler.

A default is also only ever a default. withHeaders() fills in a header the request doesn't already carry and nothing more, so a per-request Content-Type beats the client-wide one.

Policy lives in decorators

Retry implements the same Adapter interface it wraps, forwards every configuration helper inward, and overrides only sendRequest() and stream(). So retries, pooling and whatever you add stack in any order, and none of them turn into constructor flags on the transport.

The stream() override is my favorite detail in the library. It counts bytes handed to the sink, and once a single byte has been delivered it stops retrying, because replaying would duplicate data the caller already processed.

Bounded memory by default

stream() hands each chunk to a sink as it arrives, so SSE and LLM token streams cost the same memory as a ping. Uploads go the same way: cURL pulls the body through a read callback, Part::file() reads lazily, and Swoole sends files with zero-copy sendfile(). A seekable body gets rewound before each attempt, which is what makes a streamed upload safe to retry at all.

Where it ended up

Package	Before	Now
`utopia-php/pay`	`new Fetch\Client` per call	one injected client, `Adapter::call()` deleted
`utopia-php/messaging`	raw `curl_*` and `curl_multi`	PSR-18, plus a Swoole pool for batched FCM/APNs
`utopia-php/storage`	ad-hoc HTTP in the S3 devices	default client with a stall watchdog and `S3\RetryStrategy`
`utopia-php/fastly`	—	built on it from day one
`appwrite/appwrite`	per-service HTTP wiring	`jobs` and `screenshots` clients in the DI container

The Pay migration was net -55 lines. Adapter::call(), handleError(), and nine METHOD_* constants went with it — seven of the nine had no caller. A PSR-18 client and a PSR-17 factory already mean "build a request, send it"; the indirection was only ever a second vocabulary for HTTP.

Messaging is the one worth reading if you're doing this yourself. It kept every adapter's public API identical while swapping curl_multi for Swoole coroutines over a bounded pool, and added a Closure(): ClientInterface factory so a caller can inject retries, a proxy, or a stub. The one constraint it documents loudly: your factory must produce a client that can negotiate HTTP/2, because APNs rejects HTTP/1.1 outright.

What we grep for now

Climbing RSS with a flat PHP heap. Count fds, not memory_get_usage(). ls /proc/<pid>/fd | wc -l in a loop finds this in five minutes.
new Client() or curl_init inside a request path. In a long-lived process a client is a resource with a lifetime, not a local variable.
Non-static closures handed to curl_setopt. If it doesn't touch $this, make it static. Costs nothing, and it's the whole bug.
Any utopia library still carrying its own private HTTP stack. That's the rest of the work list.

Repo: utopia-php/client, though development happens in the monorepo. @lukebsilver wrote it and did the Pay migration. I did messaging, which is how I ended up with opinions about APNs.

fetch(...) per Stripe API call, with a paste showing rss=63212kB fds=7 at start and rss=64696kB fds=47 at i=40, exactly +1 fd per fetch, RSS monotonic, PHP heap flat at 6.0MB throughout. Solution is to migrate to utopia-php/client. Reply: the astronaut meme, wait, solution is migrate to utopia-php/client? always has been." width="799" height="541">

Internal consensus, after the third identical incident. The paste is the diagnostic: fds climb one per call, RSS follows, the PHP heap never moves.

Reference

Term	What it means here
file descriptor (fd)	The integer the kernel gives a process to refer to something it has open. Every live socket holds at least one, and each process has a cap (`ulimit -n`).
RSS	Resident set size: the physical memory a process actually occupies, native allocations included. This is what the kernel measures when it decides to kill you.
OOMKilled	The kernel terminating a process for exceeding its memory limit. It happens outside PHP, so there's no fatal error and nothing in the logs.
PHP heap	The pool the Zend allocator manages, which is what `memory_get_usage()` reports and `memory_limit` caps. cURL and OpenSSL allocate outside it.
reference cycle	Objects holding each other so no refcount ever reaches zero. Only PHP's cycle collector can free them, and it runs on its own schedule.
idempotent method	A request that can be sent more than once without changing the outcome. `GET`, `HEAD`, `PUT`, `DELETE`, `OPTIONS`, `TRACE` qualify; `POST` doesn't.
full jitter	Backoff where the wait is drawn uniformly from `[0, ceiling)` instead of being the ceiling, so a fleet retrying together spreads out.
coroutine	Swoole's userland concurrency. One worker process interleaves many in-flight requests, which is why connection lifetime matters so much.
sink	The callback `stream()` hands each response chunk to as it arrives, instead of buffering the whole body.
APNs / FCM	Apple and Google's push notification services. APNs is the one that rejects HTTP/1.1.

The specs

HTTP semantics in RFC 9110, message framing in RFC 9112, HTTP/2 in RFC 9113, and 429 in RFC 6585
PHP-FIG: PSR-18 for clients, PSR-7 for messages, PSR-17 for factories
URIs in RFC 3986; credentials in RFC 6750 and RFC 7617
Multipart in RFC 7578, building on RFC 2046 and RFC 2183
Content codings: deflate, gzip, br, zstd
TLS 1.3 and W3C Trace Context

The code

utopia-php/client, developed in the monorepo package, on top of utopia-php/psr7 and utopia-php/pools
fetch#22 — the reference cycle, with the fd and RSS measurements
pay#32 — the migration that fixed the OOMKills, and the before/after numbers
messaging#137 — curl_multi swapped for Swoole coroutines over a pool

Background

AWS, Exponential Backoff and Jitter, which is where the full-jitter formula comes from
PHP manual, Collecting Cycles, on when the collector actually runs

Cross-posted from chirag.appwrite.network.

How I built the Appwrite MCP server (and decided to hide most of its capabilities)

Chirag Aggarwal — Tue, 04 Aug 2026 03:37:36 +0000

When Anthropic introduced the Model Context Protocol on November 25, 2024, it got everyone's eyes on it, including Christy, who was Appwrite's Engineering Lead back then. I had just started my role as an "Engineering Intern" and had no idea what a whole new protocol meant, or why it was such a big deal.

Looking at the surface, I wasn't entirely wrong. MCP is JSON-RPC with a schema and a handshake stapled on. What took us sixteen months was everything stapled around it.

Streamable HTTP did not exist when MCP launched. It replaced HTTP+SSE in the 2025-03-26 revision.

The stdio years

Christy had a working stdio server in the repo by February 26, 2025. We already had API keys, so the wiring was simple:

claude mcp add appwrite \
  --env APPWRITE_PROJECT_ID=<YOUR_PROJECT_ID> \
  --env APPWRITE_API_KEY=<YOUR_API_KEY> \
  --env APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1 \
  -- uvx mcp-server-appwrite

An API key is scoped to exactly one project by design, so the ceiling was baked into the credential. Switching projects meant editing your editor config. Creating a project was impossible. So was anything at the organization level.

The credential is the whole difference between the two transports, and everything hard about the hosted version follows from swapping it for a token that belongs to the user instead of the project.

Authorization ate the schedule

By the spec, authorization is genuinely optional:

Authorization is OPTIONAL for MCP implementations. [...] Implementations using an HTTP-based transport SHOULD conform to this specification.

For a service where one tool call can drop a database, we weren't comfortable treating it as optional. If you use Auth0 or WorkOS, this is a config screen. Appwrite keeps everything in-house, so Matej built the authorization server itself, and I built the resource server plus whatever Cloud was still missing before real clients would work.

Steps 2 through 6 are the part that makes "just paste this URL" work. Nothing is pre-provisioned.

Three RFCs carry that flow. Protected Resource Metadata (RFC 9728) is the only real MUST in the whole authorization spec:

{
  "resource": "https://mcp.appwrite.io/",
  "authorization_servers": ["https://cloud.appwrite.io/v1/oauth2/console"],
  "scopes_supported": ["..."],
  "bearer_methods_supported": ["header"]
}

Resource Indicators (RFC 8707) put our canonical URI into the token's aud, so a token minted for another service can't be replayed against us. Dynamic Client Registration (RFC 7591) is what lets a client self-register. Add PKCE with S256, RFC 8414 discovery, and you have the shape of it.

The RFCs are documented. What isn't documented is that every client reads them differently, and you find out in production:

Raycast was on the 2025-03-26 authorization spec, which looks for /.well-known/oauth-authorization-server instead of the protected-resource route. I only found it by putting a logging proxy in front of the server and watching what it actually asked for.
Claude Code re-authenticated every single run. It listens on an ephemeral loopback port, so the redirect URI never matched. OAuth's native-app BCP (RFC 8252 §7.3) says you must allow any port on 127.0.0.1. We weren't.
Our own scope catalog broke the flow. All ~118 granular scopes produced a scope parameter of ~2,680 characters against a validator capped at 2,048. Nobody ever reached a consent screen.

One warning if you're about to build this: RFC 7591 went from SHOULD to MAY in 2025-11-25 and is deprecated as of 2026-07-28, replaced by Client ID Metadata Documents. We shipped that too. This part of the spec is still moving.

Sessions, and then no sessions

The 2025-06-18 spec let a server hand out an Mcp-Session-Id alongside the InitializeResult, with DELETE to terminate and Last-Event-ID for resumability. We skipped all of it:

StreamableHTTPSessionManager(app=server, json_response=False, stateless=True)

Every request carries a bearer token. Verify it, build a client from it, serve the call. Nothing to store, nothing to lose on restart, nothing to make sticky across replicas.

That turned out to be the right bet for a reason I can take no credit for. The 2026-07-28 revision removed sessions from the protocol entirely. Mcp-Session-Id, the initialize handshake, the GET SSE stream: all gone. What we do carry is version negotiation, because you don't get to pick your clients' protocol version.

Off-topic, but why not REST?

Many intellectuals like myself must have wondered why MCP exists at all. Can't this be 100x simpler with, I don't know, REST?

The model only knows its training data plus whatever you hand it at runtime. If it has never seen Appwrite, it will never guess this:

POST https://<REGION>.cloud.appwrite.io/v1/tablesdb
X-Appwrite-Project: <PROJECT_ID>
X-Appwrite-Key: <API_KEY>
Content-Type: application/json

{ "databaseId": "unique()", "name": "Production" }

The endpoint, the header names, the fact that unique() is a magic value. With MCP the same operation shows up self-describing:

{
  "name": "tables_db_create",
  "description": "Create a database in an Appwrite project",
  "inputSchema": {
    "type": "object",
    "properties": {
      "databaseId": { "type": "string" },
      "name": { "type": "string" }
    },
    "required": ["databaseId", "name"]
  }
}

You can be happy knowing AI needs a lot more handholding than you do (for now).

Tool choice

Every MCP server I looked at ships a small, curated set. Appwrite generates one tool per SDK method, which lands at 981 methods across 38 services.

Counts as of August 2026. GitHub's 90 are grouped into 22 toolsets with 5 on by default.

There's no version of "expose them all" that works, for two unrelated reasons.

The clients won't take them. In early 2025 Cursor documented that it "will only send the first 40 tools to the Agent" and truncated silently. Windsurf refused outright above 50.

Discord, liviu74, Mar 14 2025. Windsurf refused it; Cursor accepted it and silently dropped tools 41 onward.

That was with per-service flags already in place, which is the part that stings. A community user opened issue #17, "Please reduce the number of tools":

Cursor has 40 MCP tools limit to use, but Appwrite solely has 195 tools, so it cannot be used with other tools nor even all of Appwrite tools.

I pointed out you could narrow it with --databases. The reply:

That's quite non-sense. Then do I have to edit MCP parameter settings for each time whenever I do another jobs...? And anyway, --databases solely has 42 tools, which already exceeds Cursor's recommended limit (40).

Quality falls off well below the caps. The numbers converge from unrelated directions. Anthropic puts degradation at "once you exceed 30-50 available tools". OpenAI says "fewer than 20 functions at the start of a turn". Block's Goose recommends 50 or fewer. And the fix measures well: Anthropic's advanced tool use work takes Opus 4 from 49% to 74% on MCP tool-use evals with a search tool enabled, and Opus 4.5 from 79.5% to 88.1%, with 85% fewer tokens on definitions. RAG-MCP more than triples selection accuracy (43.13% against 13.62%).

The caveat, because it cuts against me: MCPVerse found some agentic models handle big action spaces fine. Claude-4-Sonnet scored 62.3 with an oracle tool set and 62.4 with ~220 tools. Big catalogs aren't fatal. They're a tax you're paying for nothing when the agent needs three tools out of 981.

Four tools over 981

appwrite_get_context answers where you are and which projects you can see
appwrite_search_tools searches the hidden catalog in natural language
appwrite_call_tool calls one of them by name
appwrite_search_docs searches the Appwrite docs semantically

Search narrows at request time, which is why the per-service flags could be deleted entirely. Mutations require confirm_write: true, and results too large for the conversation become MCP resources instead.

The scoring behind appwrite_search_tools is deliberately dumb: token and substring matching against the tool name, description, service and resource, a bonus when the query's inferred verb matches the tool's, a penalty when it doesn't. No embeddings, no index to rebuild, no inference call in the hot path.

Here's what a client sees:

981 methods behind 4 tools and 1 resource. The "Logout" link is the OAuth session.

What made me stop second-guessing the design is that we weren't alone. Stripe put its whole API behind stripe_api_search. Sentry exposes 9 of 46 through search_sentry_tools. GitHub removed its dynamic toolset tools and looks to be building a search replacement. Three companies with no reason to coordinate landed on search-then-execute in the same window.

Where it landed

claude mcp add --transport http appwrite https://mcp.appwrite.io/

No API key, no project ID, no config editing to switch projects. Projects and organizations are parameters on the call now instead of properties of the credential.

stdio didn't go away. I removed it in the hosted refactor and put it back two days later, because self-hosted users need it. It runs on a project API key and gets 647 of the 981 methods, since a project key can't reach console-level operations anyway.

Behind that URL there's also OpenTelemetry, Sentry, Grafana dashboards, and region routing so a project in another Cloud region doesn't return general_access_forbidden. You end up operating a service, not publishing a package. That's the part I underestimated most.

What I'd tell anyone building one

The transport is not where the time goes. The authorization spec and everything it pulls in is where the months disappear.

Test against real clients early and expect them to disagree. A logging proxy in front of your server was worth more to me than another pass through the docs.

Assume the spec moves under you. Between starting and shipping, sessions were removed, RFC 7591 was deprecated, and a stateless revision landed. Anthropic donated MCP to the Agentic AI Foundation in December 2025, so it isn't even one vendor's project anymore.

And don't hand your API surface over as your tool surface. The architecture this server has today came out of a bug report from a user who was annoyed with us, which I think is the correct way for this to have gone.

The server is open source at github.com/appwrite/mcp, and the hosted one is at https://mcp.appwrite.io/.

Managing multiple docker hub accounts using docker-use

Chirag Aggarwal — Mon, 25 May 2026 05:08:01 +0000

Most of the time I'm signed into my work Docker Hub account, and that's fine. Almost everything I build ends up there. Then one weekend I was playing around with openruntimes/orchestrator, an orchestration service for running containerized workloads with callbacks. I had a PR open with some small tweaks, and I wanted to publish release-candidate images so I could pull them down and actually test end-to-end.

I didn't want those RC images sitting in my work namespace. So for the first time, I actually needed to switch Docker Hub accounts on my machine, and there isn't a good way to do it. The official answer is docker logout, then docker login again. Docker does respect a DOCKER_CONFIG environment variable that points at a config directory, but you still have to set it yourself every time.

A few years ago I'd have spent the afternoon hunting for someone else's tool. In the age of AI, you can just build the one you wished existed. So I did.

The result is docker-use.

The idea

The fix is small. Docker already respects the DOCKER_CONFIG environment variable, and whatever directory it points at is treated as the active config. So the whole mechanism is:

Give every account its own config directory.
Let the shell flip DOCKER_CONFIG between them by name.

No patches to Docker, no daemon involvement, no new credential store. A directory per account, plus a shell function to switch between them.

What it looks like

# one-time per account
docker-use add appwrite -u my-appwrite-username
docker-use add personal -u chiragagg5k

# day-to-day
docker-use appwrite

docker-use personal
docker push chiragagg5k/job-sidecar:temp-appwrite-pr-4f081ed-20260521-r2

docker-use whoami   # which one am I on right now?
docker-use list     # all accounts

add shells out to a normal docker login, so 2FA and access tokens behave the way you already expect.

How it works

There are three pieces.

Each account lives in its own config directory, at ~/.docker-accounts/<name>/config.json. Names are validated against ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$ so they can't escape the directory or surprise the shell.

The trickier piece is a shell wrapper that mutates the parent shell. A child process can't change its parent's environment variables, so the binary on its own can't make DOCKER_CONFIG stick in your shell. The workaround is a shell function, generated by docker-use init zsh, that you source in your rc file:

eval "$(docker-use init zsh)"

The wrapper calls the binary, reads the printed config path, and assigns it to DOCKER_CONFIG in the current shell. It's a plain assignment, not an eval on the path itself, so a weird config name can't smuggle anything into your shell. zsh, bash, and fish all work.

The last piece is keeping Docker's credential helpers in place. When docker login finishes, the resulting config.json often contains "credsStore": "osxkeychain" (or secretservice on Linux). If you wipe that field, Docker Desktop's keychain integration breaks and the next push prompts you for a password. So during add, docker-use reads the config Docker just wrote and preserves the credential helper settings.

Things I'd flag if you read the source

A few decisions that weren't obvious going in.

The shell wrapper assigns the config path directly instead of eval-ing whatever the binary prints. Eval-ing user-controllable output tends to age badly.

Account names get validated before any filesystem operation runs. docker-use add ../etc -u … is not a debugging session I want to have.

remove asks for confirmation before deleting. It's a destructive action on credentials, so the extra keystroke is worth it.

Install

brew tap chiragagg5k/tools
brew install docker-use

Then drop this into your ~/.zshrc (or ~/.bashrc, or ~/.config/fish/config.fish):

eval "$(docker-use init zsh)"

Binaries for other platforms are on the releases page.

If you end up using it, I'd love to hear what works and what doesn't. Open an issue or reach out directly.

How we solved logging at Appwrite

Chirag Aggarwal — Sun, 19 Apr 2026 11:56:39 +0000

A few weeks back I came across a post by @boristane sharing a website he made, loggingsucks.com. It caught my eye because it had been shared by my favorite tech YouTuber, @theo. Like most people, I was really inspired by the article and shared it with my team. @lukebsilver, Appwrite's Engineering Lead, was also inspired by it and decided to work on a new PHP library, utopia-php/span, to fix logging throughout the Appwrite codebase.

What we had

Before this, Appwrite used a combination of two different libraries targeting logging in two different areas:

utopia-php/console — a very simple wrapper library around stdout logging using functions like Console::success(), Console::error(), etc.
utopia-php/logger — an adapter-based library to push error logs to monitoring systems like Sentry, AppSignal, Raygun, etc.

Combined, these libraries served their purpose for a long time, but we often ran into problems when debugging production issues, the same ones the original article discusses in detail. I'd highly recommend going through that article first so I don't repeat it all here.

Our solution

Funnily enough, the first tricky problem was deciding on a name. "Logger" was already taken, so we had to be creative. The word "Span" captured exactly what we were trying to solve: a fundamental unit of work with a named, timed operation alongside various attributes, errors, trace IDs, etc.

The first step was to move away from simple log lines to structured logging. Span enforces this by only exposing a single primary method, add(), which accepts a key-value pair.

Before:

Console::info("Deleting project {$project->getId()} (type={$type}, region={$project->getAttribute('region')})");

After:

Span::add('project.id', $project->getId());
Span::add('project.type', $type);
Span::add('project.region', $project->getAttribute('region'));

This massively improved the queryability of our logs — one of the things we struggled with most when going through logs in production.

We also wanted the library to be extremely simple to use. Earlier, with "logger", we had to hop through various dependency injection loops just to use it:

public function action(
    Message $message,
    Document $project,
    Log $log, // ← has to be injected just to add a tag
): void {
    $log->addTag('projectId', $project->getId());
    $log->addTag('type', $payload['type']);
    // ...actual work...
}

With Span, it's much simpler:

public function action(
    Message $message,
    Document $project,
): void {
    Span::add('projectId', $project->getId());
    Span::add('type', $payload['type']);
    // ...actual work...
}

Why not just make the logger methods static?

Because Appwrite's codebase leverages coroutines (via Swoole) for concurrency between requests, similar to goroutines in Go. A naive static implementation would leak state across concurrent requests. Span solves this by allowing you to choose the storage type:

Span::setStorage(new Storage\Coroutine());

Exporters

To combine both logger and console capabilities, Span exposes built-in Exporters, which, as the name suggests, export the logs to not just stdout but any supported adapter. The library currently supports three:

Stdout: basic usage. Dumps the output as plain JSON:

{
  "action": "worker.deletes",
  "span.trace_id": "7a3f9c2b4e1d8f06",
  "span.duration": 1.92,
  "project.id": "67f3a9",
  "project.type": "projects",
  "project.region": "fra"
}

Pretty: JSON dumps are very useful in production where you have OpenTelemetry or other monitoring set up, but locally you just want things to be readable:

worker.deletes · 1.92s · 7a3f9c2b

  project.id      67f3a9
  project.type    projects
  project.region  fra

  ────────────────────────────────

Sentry: since Sentry is primarily an error tracking system, Span also exposes a callable "sampler" that lets you filter which logs get exported to a particular exporter:

Span::addExporter(
    new Sentry(dsn: '...'),
    // Sampler: drop noisy expected errors, keep everything else.
    sampler: function (Span $span): bool {
        $error = $span->getError();
        return !($error instanceof ExecutorException) || $error->isPublishable();
    },
);

Before and after

One massive improvement we saw was with error logs. Before, we had very verbose and noisy errors that were often hard to make sense of:

[Error] Timestamp: 2026-04-17T10:32:16+00:00
[Error] Type: Utopia\Database\Exception\Timeout
[Error] Message: Query took too long
[Error] File: /usr/src/code/src/Appwrite/Cloud/Platform/Workers/Deletes.php
[Error] Line: 214
Trace: #0 /usr/src/code/app/worker.php(828): ...

Now:

{
  "action": "worker.deletes",
  "span.trace_id": "7a3f9c2b4e1d8f06",
  "span.duration": 2.14,
  "project.id": "67f3a9",
  "error.type": "Utopia\\Database\\Exception\\Timeout",
  "error.message": "Query took too long",
  "error.file": "/usr/src/code/src/Appwrite/Cloud/Platform/Workers/Deletes.php",
  "error.line": 214,
  "error.trace": [
    { "file": "/usr/src/code/app/worker.php", "line": 828, "function": "action" }
  ]
}

If you're writing PHP in 2026, give utopia-php/span a shot. And a massive shoutout to @lukebsilver, who actually built the library. I just learned from him and wanted to share what I picked up.

JStack + Appwrite: A Match Made in Heaven for Modern Web Development

Chirag Aggarwal — Sun, 06 Jul 2025 15:27:22 +0000

If I had a penny for each time a youtuber has launched his own tech stack, I would have 2 pennies, which isn't much but its weird that it happened twice.

I am talking about T3 Stack launched a while back by everyone's favourite Theo, but recently a new player has entered the market called JStack, by Josh who is the lead Devrel at Upstash. To be fair, its not even that recent, but as always ~~I am late to the party~~ I try to give a framework time to mature and gather feedback from community before giving it a shot.

So, did I prefer JStack over T3 stack? Did it have more compatibility with Appwrite, my favourite backend provider? Can it be hosted on Appwrite Sites? Let's find out.

Getting Started

Let's start with initialising the project:

bunx create-jstack-app@latest

Options selected:

┌   jStack CLI 
│
◇  What will your project be called?
│  testing-jstack-appwrite
│
◇  Which database ORM would you like to use?
│  None
│
◇  Should we run 'bun install' for you?
│  Yes

Using: bun

✔ testing-jstack-appwrite scaffolded successfully!

Let's just quickly run a dev server to see what we get out of the box:

cd cd testing-jstack-appwrite
bun dev

Initialising Project

On skipping the ORM option, the stack still sets up a /src/server folder with an example posts router. But it only mocks the DB using an array which does not persist:

// Mocked DB
interface Post {
  id: number
  name: string
}

const posts: Post[] = [
  {
    id: 1,
    name: "Hello World",
  },
]

We skipped the ORM option because Appwrite provides built-in schema management through its SDK, eliminating the need for a separate ORM layer. To get started, let's head over to https://cloud.appwrite.io to set up our project.

If you are using Appwrite for the first time, I highly recommend you check out our Start with Web docs.

Here is a quick setup guide:

Create a new project -

Add a new web platform and select Next.js -

Go to project overview and grab your project's ID and region-specific endpoint:

Create a new .env file in your project directory and paste in those values:

NEXT_PUBLIC_APPWRITE_PROJECT_ID=686a271700323696d223
NEXT_PUBLIC_APPWRITE_ENDPOINT=https://fra.cloud.appwrite.io/v1
NEXT_PUBLIC_APP_DOMAIN=localhost # we will change it later

Now, let's initialise the Appwrite SDK in the project using:

bun add appwrite

This covers up on how to initialize Appwrite in normal Next.js project. Now we need to configure our Appwrite databases according to the project. For this demo, let's create a Posts collection to shift the mock database JStack uses as an example to Appwrite.

Defining Schema

Go to the Appwrite Console > Databases > Create Database. We will call it main , and keep it' ID as main as well:

Similarly, create a collection posts and keep its ID as posts.
Each document in Appwrite already has an unique ID attached to it, so the only attribute we need is name for now:

Lastly, you will need to define who can access your collection. To learn more about it, check out the docs for Appwrite Permissions. For now, we will set it to any:

Syncing Types

That's it, we are all set with configuration on the Appwrite Console. Now let's set it up in our project. I will also take the help of the Appwrite CLI to help me set up things faster. You can learn more about how to install it by following the installation docs.

Once done, run:

appwrite init project

? How would you like to start? Link directory to an existing project
? Choose your organization 67610b8ee51f147ca943
? Choose your Appwrite project. [object Object]
✓ Success: Project successfully linked. Details are now stored in appwrite.json file.
Would you like to pull all resources from project you just linked? Yes

Once done, let's utilize the last Types Generation feature to sync our defined types:

appwrite types src/types       

ℹ Info: Detected language: ts
ℹ Info: Directory: src/types does not exist, creating...
ℹ Info: Found 1 collections: posts
ℹ Info: Found 1 attributes across all collections
ℹ Info: Added types to src/types/appwrite.d.ts
✓ Success: Generated types for all the listed collections

Result will look something like this:

import { type Models } from 'appwrite';

/**
 * This file is auto-generated by the Appwrite CLI. 
 * You can regenerate it by running `appwrite types -l ts src/types`.
 */

export type Posts = Models.Document & {
  name: string;
}

Obviously pretty small for now, but a really helpful feature once the project expands and more collections are defined.

Configuring Code

Final steps are to connect the Appwrite backend with our tech stack. For that let's create a simple appwrite.ts file in src/lib folder:

import { Client, Databases, ID } from "appwrite";

const client = new Client()
    .setEndpoint(process.env.NEXT_PUBLIC_APPWRITE_ENDPOINT!)
    .setProject(process.env.NEXT_PUBLIC_APPWRITE_PROJECT_ID!);

const databases = new Databases(client);

export { client, databases };

Now, we can modify the original post-router.ts file to use the defined database:

import { z } from "zod";
import { j, publicProcedure } from "../jstack";
import { databases } from "@/lib/appwrite";
import { type Posts } from "@/types/appwrite";
import { ID } from "appwrite";

const DATABASE_ID = "main";
const POSTS_COLLECTION_ID = "posts";

export const postRouter = j.router({
  recent: publicProcedure.query(async ({ c }) => {
    const posts = await databases.listDocuments<Posts>(
      DATABASE_ID,
      POSTS_COLLECTION_ID,
    );
    return c.superjson(posts.documents.at(-1) ?? null);
  }),

  create: publicProcedure
    .input(z.object({ name: z.string().min(1) }))
    .mutation(async ({ c, input }) => {
      const post = await databases.createDocument<Posts>(
        DATABASE_ID,
        POSTS_COLLECTION_ID,
        ID.unique(),
        {
          name: input.name,
        },
      );

      return c.superjson(post);
    }),
});

And done! Now your JStack application is using Appwrite as its backend provider.

Testing

Start the dev server if not already by running:

bun run dev

Your application should have started on: http://localhost:3000/
Create a new post.
You should be able to see it in recent posts:

Also, the data should be visible in your Appwrite Console:

Deploying your application

Until recently, to deploy your Next.js application, you had pretty low choices. But no more Appwrite Sites. Now, you can have your backend and frontend hosted on Appwrite.

Check out these docs on how to get started with Sites - https://appwrite.io/docs/advanced/self-hosting/sites

Let's deploy your application using Sites:

Go to Appwrite Console > Sites > Create Site.
You can upload a tar file directly, or connect to a GitHub repository (I prefer the GitHub option for automatic deployments).
Select the repository:

You can keep all the settings as the default ones, just make sure to upload the environment variables we defined earlier:

Depending on the domain you are assigned / plan to use, you also need to update the APP_DOMAIN variable we defined earlier. For me I will keep it:

NEXT_PUBLIC_APP_DOMAIN=jstack-appwrite-template.appwrite.network

Click on deploy.

And done! Your application should be live 🎉

You can checkout the demo application here - https://jstack-appwrite-template.appwrite.network/

Conclusion

Let's start by answering the question the blog began with: Do I prefer JStack over T3 Stack? I'm sorry, Theo, but I do.

JStack solves the fundamental problems I have always had with Next.js:

Using Hono instead of Next.js's inbuilt convention for defining API routes.
Using TanStack query out of the box. Trust me, you should start now if you are not using it.
Type safe and uses Zod.

The most noticeable difference between T3 Stack and JStack is how light they are, mainly due to the inclusion of the tRPC protocol in T3 Stack. Although JStack also uses tRPC, it seems like a much simpler implementation of it. Most projects do not require the complexity tRPC adds, and in my opinion it makes the code 10x more complicated to maintain.

So, give JStack a shot if you are starting with a new project (or want to spend a weekend migrating your existing stack to it). Huge shoutout to Josh for creating this wonderful stack. And lastly, give Appwrite a chance to be your next all in one cloud platform, both for your backend and frontend needs.

Sources:

JStack - https://jstack.app/
Appwrite Docs - https://appwrite.io/docs
Github repository - https://github.com/ChiragAgg5k/jstack-appwrite-template

DEV Community: Chirag Aggarwal

Keeping track of your agent's work

How the context goes missing

Give every piece of work a ticket

The side benefit: anyone can pick it back up

Examples

What I'd tell someone starting

A Master's in Ireland While Building Appwrite

TL;DR

Why a Master's, and why now

Why Ireland

Keeping Appwrite in the picture

The move

What I'm looking forward to

One month in

Thank You

My agent has two Playwrights

Two jobs

Where the calls went

Three sessions

"The logo looks off"

The OG image X wouldn't show

Release QA for 2.3.0

Every PR gets a picture

The other 553 calls

Where it falls short

What I'd tell someone starting

Seven months of coding agents: what $28,335 actually bought

The shape of the bill

What the spend actually bought

The leash is fifteen actions long

The part that argues against me

The choice, and what it costs

MCP 2.0: the release that deleted the handshake

The handshake era

What 2026-07-28 actually does

Why this is 2.0 and not 1.4

We had already bet on this

The good kind of boring

Reference

The spec

The code

Will MCP replace the CLI?

MCP is not the GUI for agents

The MCP trend nobody advertises

My prediction

Appwrite MCP vs Vercel MCP: I benchmarked both

How I tested

How I scored it

Router versus toolbox

What each server actually covers

Lifecycle control: Appwrite exposed more

Deployment speed: Vercel was a bit faster

Observed latency

Choosing between them

How utopia-php/client keeps fixing our memory leaks

What was actually leaking

What the library is

Which specs it holds itself to

PSR-18 decides what counts as an error

Retrying, and why only some requests get to

withBaseUri() is not string concatenation

Everything else is a header you'd otherwise hand-roll

The four rules underneath

Reuse over recreate

Every with*() returns a clone

Policy lives in decorators

Bounded memory by default

Where it ended up

What we grep for now

Reference

The specs

The code

Background

How I built the Appwrite MCP server (and decided to hide most of its capabilities)

The stdio years

Authorization ate the schedule

Sessions, and then no sessions

Off-topic, but why not REST?

Tool choice

`withBaseUri()` is not string concatenation

Every `with*()` returns a clone