DEV Community: Kushal Baral

Millions of Clicks, 200 Tickets: Building an Endpoint That Cannot Oversell

Kushal Baral — Sat, 22 Aug 2026 10:41:34 +0000

Friday morning, 10 AM sharp. Tickets go live.

200 seats. A band people have waited years to see. Within seconds, millions of fans are smashing the Buy button from phones on trains, laptops in offices, that one tablet at the back of a taxi.

Somewhere between request number 199 and request number 201, your database starts lying to you.

Not because it is broken. Because you wrote code that made perfect sense and quietly assumed the world is polite. It is not. This post is the story of every way that assumption breaks, and how to build an endpoint that stays honest no matter how many people click at once.

Every claim below is proven under real load against a working project: k6, autocannon, or plain loops of curl, whatever you prefer. The repo is linked at the end.

The uncomfortable truth about this bug

Here is the part nobody warns you about: the naive solution works fine. Genuinely fine. For a shop selling ten tickets a day, for a demo, for your portfolio site, for everything you have probably ever shipped.

These bugs do not exist at low traffic. They only exist when requests overlap in time, which means no code review catches them, no unit test fails, and your launch demo goes flawlessly. Then the crowd arrives and the lies begin.

You do not need millions of users either. A laptop, one endpoint, and any load tool (k6, autocannon, even a dumb for-loop of curl) reproduce everything below. Scale only changes how fast the lie spreads.

Three quick deaths of a naive counter

The version everyone writes first keeps count in memory and does if count < LIMIT: count += 1. It dies three ways:

The read-write gap: count += 1 is really read, add, write. Two simultaneous requests both read 199, both write 200, ticket 200 gets sold twice.
Multiple workers: run four processes for speed and there are four separate counters in four memory spaces, each selling its own private inventory.
Restarts: deploy at noon, memory resets, this morning's tickets go back on sale.

Shared mutable state under concurrency is dead on arrival, so the counter moves to Postgres. Where it dies again.

The database still lets you race

row = await conn.fetchrow("SELECT sold FROM tickets WHERE id = 1")
if row["sold"] < limit:
    await conn.execute("UPDATE tickets SET sold = sold + 1 WHERE id = 1")

Shared state, survives restarts, multiple workers all see the same number. Ship it?

Still oversells. Run it under load and watch.

The database serializes statements, not intentions. Your check and your write are two separate statements, and between them sits a network round trip where another connection happily runs its own check against the old value. Same movie as the in-memory counter, new costume.

The fix: make the check and the write ONE thing

This is the moment the whole problem collapses:

UPDATE tickets
SET sold = sold + 1
WHERE id = 1 AND sold < total_limit
RETURNING sold;

One statement. Postgres takes the row lock needed for the update and re-evaluates the WHERE condition against the current row version before applying it; if the condition fails you get zero rows back, which means sold out. There is no gap. There is no "between the check and the write" anymore, because they are the same operation.

k6 against this version: 500 concurrent purchases racing for 200 tickets. In repeated runs, exactly 200 succeeded and the remaining 300 were rejected as sold out. And that outcome is not luck or statistics: the check and the write are one atomic statement, so there is no application-level gap between them, regardless of how many workers hammer it.

Rule worth tattooing somewhere: never trust read-then-write across a network round trip. Push conditions INTO the statement.

Retries sell twice

Correctness achieved, so naturally the network ruins the party again.

Mobile networks retry. Users double-click. Payment gateways re-send notifications. Our endpoint charges one ticket per click, so a timeout followed by a retry now buys TWO tickets for one person.

The fix has a fancy name, idempotency, and a simple idea behind it: the client sends a key, and the same key always maps to the same outcome.

INSERT INTO purchases (idempotency_key, status)
VALUES ($1, 'pending')
ON CONFLICT (idempotency_key) DO NOTHING;

First request: the row inserts as pending and the flow moves toward confirmation. Retry with the same key: the insert does nothing, we look up what already happened and replay that stored outcome instead of selling again. One key always maps to its stored outcome, for as long as that record is retained (real systems define a retention window for keys). Stripe built entire SDK features around this concept, which tells you how often networks misbehave in production.

Proving it under fire

Correct when tried manually means nothing, as established. Time to be scientific. Load testing with k6:

export const options = {
  scenarios: {
    rush: {
      executor: 'shared-iterations',
      vus: 500,            // 500 virtual users
      iterations: 500,     // each buys once
    },
  },
  thresholds: {
    http_req_duration: ['p(95)<300'],
    checks: ['rate>0.99'],
  },
};

Two things being verified here. Correctness: never more than 200 confirmed sales. And speed: latency thresholds.

p95 means 95 percent of requests finished faster than that number. Percentiles exist because averages lie: 99 fast requests plus one five-second disaster average out to a polite-looking blur, while p99 points directly at the disaster.

One more production trick: when tickets run out, stop hammering the database. Cache a "sold out" flag in worker memory for a few seconds and reject instantly. The database remains the only source of truth: the flag can cause an early rejection, but it can never cause an oversell. And keep its lifetime short, because inventory can come BACK.

Final boss: payments take seconds

Everything so far assumed buying is instant. Real money is not.

If we mark the ticket SOLD immediately and wait for payment, every declined card permanently eats one ticket. Inventory leaks, slowly, forever. If instead we wait for payment while holding our precious atomic row, the entire system queues behind one human typing their CVV at the speed of a sleepy sloth. Connection pools fill. The site dies. This is Amdahl's law wearing a payment form.

Real systems escape with a state machine that separates GRABBING from OWNING:

                 reserve (fast, atomic)
   AVAILABLE -------------------------> HELD
                                          | verify ok -> CONFIRMED (sold)
                                          | verify fail / TTL expiry
                                          v
                                       RELEASED -> AVAILABLE again

Reserving a hold uses the same atomic trick as before, just counting holds instead of sales:

UPDATE tickets SET held = held + 1
WHERE id = 1 AND sold + held < total_limit
RETURNING id;

Milliseconds, no payment anywhere near the hot path. The customer gets a reservation id and a deadline. Payment gets verified outside the counter: a redirect back from the provider, a webhook, whatever the flow calls for. The state machine does not care who pulls the trigger.

But holds pile up from people who close the tab. Someone has to take the tickets back. Enter the sweeper:

WITH expired AS (
    UPDATE purchases SET status = 'released'
    WHERE status = 'reserved' AND expires_at < now()
    RETURNING id
)
UPDATE tickets
SET held = held - (SELECT count(*) FROM expired)
WHERE id = 1 AND held > 0;

One statement, one transaction, crash safe. Run it opportunistically inside reserve requests plus once per second in the background, and expired holds flow back into availability automatically. Even eight workers sweeping simultaneously cannot corrupt anything: the release only matches rows still sitting in reserved, so any hold transitions to released exactly once, no matter who fires first.

To be clear, that snippet is demonstration code for a single inventory bucket, one tickets row. Production schemas go further: each reservation references the exact inventory it holds, and many skip the separate held counter entirely, deriving availability from live reservations instead. That removes this entire class of bookkeeping from the equation.

Confirming payment is conditional too: WHERE status = 'reserved' AND expires_at > now(). Lose the race against the sweeper and the customer gets a polite "hold expired". One disappointed human. Never two tickets. That trade is the whole philosophy: correctness over comfort, always.

The expiry path proves itself quickly: set a short TTL, reserve a hold, watch /status show held go up, let the deadline pass, watch held drain back to zero while the ledger flips the row from reserved to released. Try paying anyway and you get HTTP 410, which is not an error case but the refund trigger, because money may already have moved. Inventory became self-cleaning.

Choosing the TTL is a business decision

How long should a hold live? Too short and customers lose their ticket mid checkout while typing card details. Rage, support tickets, lost sales. Too long and abandoned tabs lock inventory from real buyers: the event looks sold out when it is not.


TTL too short	customers lose tickets MID-CHECKOUT, rage ensues
TTL too long	dead tabs hold all 200 tickets, event looks sold out

There is no perfect number. Rule of thumb: measure how long your payment flow actually takes, set the TTL slightly above its p95, and for the love of users show a countdown timer. A silent expiry feels like theft. A visible countdown creates urgency. Production systems go further: renewing holds while the user is active on the payment page, grace windows for payments that provably succeeded seconds late, and automatic refunds whenever that "hold expired" response fires.

What the TTL must never be allowed to break is correctness. An expiring hold can cost a sale. It can never create two tickets.

Build it yourself

The whole thing lives as runnable code, one lesson per branch, each with its own README explaining what breaks and why:

Branch	Lesson
`step-1-theory`	the overselling problem, no code yet
`step-2-in-memory`	the naive counter, four workers four truths
`step-3-await-demo`	watching a race condition happen live
`step-4-naive-db`	moving to Postgres, still overselling
`step-5-atomic`	the atomic conditional UPDATE
`step-6-idempotency`	retries, keys, the purchases ledger
`step-7-load-tests`	k6 proof, percentiles, sold-out cache
`step-8-reservation`	holds, TTL sweeper, payments off the hot path

The concepts are the point, not the stack: any language, framework or database tells these same ideas just as well.

Repo: github.com/kushal1o1/XCounter

ZeroRelay: Direct Browser-to-Browser Sharing - No Server Ever Sees Your Data

Kushal Baral — Wed, 08 Jul 2026 10:35:51 +0000

A fully open-source P2P mesh app for sharing text, code, notes, and files directly between browsers. No signup, no accounts, no database.

The Pain Point

You're sitting next to a colleague. You need to send them a 200MB video file.

Email? 25MB limit + compression
Drive/Dropbox? Need an account + files sit on their servers forever
WhatsApp/Telegram? Compresses media + stores everything on their servers
AirDrop? Apple-only, doesn't work half the time
USB? Who carries one anymore?
SCP/iPerf? Overkill for a quick share

ZeroRelay: Open a tab,drag the file. Done. Direct browser-to-browser. Nothing touches a server.

Demo

What's ZeroRelay?

A peer-to-peer mesh app where every browser connects directly to every other browser over WebRTC. The signaling server (Cloudflare Durable Object) only exchanges join/leave messages and ICE candidates - it never stores or even sees your messages, files, or avatars.

Each peer is its own database - everything lives in IndexedDB (Dexie) on your browser. When you share something, it's broadcast over WebRTC data channels directly to connected peers. There is no central storage. There is no cloud. Your data never touches a server.

Architecture

                    ┌─────────────────┐
                    │  Cloudflare DO   │  ← signaling only
                    │  (per room)      │    (join/leave/ICE relay)
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
         ┌────────┐    ┌────────┐    ┌────────┐
         │ Peer A │◄──►│ Peer B │◄──►│ Peer C │  ← WebRTC mesh
         │(Dexie) │    │(Dexie) │    │(Dexie) │     (data channels)
         └────────┘    └────────┘    └────────┘

Each browser stores its own copy of everything in IndexedDB. When you share something, it's broadcast to all connected peers over WebRTC data channels. The signaling server never sees your messages, files, or avatars.

For full architecture deep-dive, see ARCHITECTURE.md on GitHub.

Features


Full P2P Mesh	Every peer connects directly to every other - no central relay
Zero Server Storage	No database, no logs, no message history on any server
No Signup or Accounts	Open the app, join a room - done
Share Anything	Text, code, notes, or files of any size
Password-Protected Rooms	Room-level passwords enforced by Cloudflare DO
Retention Per Item	Session, 5 min, 1 hour, 1 day, or forever
Open Source	MIT - fully auditable and self-hostable

Important Note


Peer Discovery	Works globally - anyone on the internet can see you in the room
Data Transfer	Works on same LAN - messages and files flow when peers are on the same network
Cross-Network	Not yet - needs a TURN server for symmetric NAT traversal

Peer discovery goes through the Cloudflare DO (WebSocket over TCP) so it works anywhere. Data transfer uses WebRTC which needs STUN/TURN to cross the public internet. Currently STUN-only. TURN support and contributions are welcome:)

Tech Stack

Layer	Choice
Frontend	Next.js 15 + React 19
State	Zustand (in-memory + localStorage persist)
Persistence	Dexie v4 (IndexedDB)
P2P Transport	WebRTC (full mesh topology)
Signaling	Cloudflare Workers + Durable Objects
Styling	Tailwind CSS v4
Tooling	Biome, TypeScript, Husky

Why Open Source?

Transparency - anyone can audit exactly what the server does (and doesn't) store
Self-host - deploy your own signaling worker if you want

I got tired of Googling "resize,compress ,optimize image online " so I built a CLI for it

Kushal Baral — Sun, 14 Jun 2026 07:30:03 +0000

Every time I need to resize a batch of images, strip metadata, or convert to WebP, I end up in the same loop:

Google "resize image online"
Pick a site, upload my photos (hope they don't keep them)
Wait for download
Repeat for the next thing

Or I open GIMP. Or I write yet another 10-line Pillow script that I'll lose by tomorrow.

So I built ImageX. It's the dumbest, simplest thing:

pip install imagex
cd ~/Pictures # works cross-platform with Python installed
imagex

A menu pops up. Pick what you want. Done. No uploads, no ads, no "premium" upsells.

What's in the box

Rotate, resize, convert, compress, watermark, strip metadata, rename batch, add noise. That covers 90% of what I ever need. Each one is an interactive prompt , no flags or command to memorize.

How it works

Every feature is its own .py file in a folder. Drop a new one in with a NAME, DESCRIPTION, and a run() function, and it shows up in the menu automatically. That's it.

NAME = "Rotate"
DESCRIPTION = "Rotate images 90° Left, 90° Right, or 180°"


def run(file, output_path, args):
    img = Image.open(file)
    rotated = img.transpose(args["method"])
    rotated.save(output_path)
    return True

Added in 20 lines. No config, no registration, no boilerplate.

Why you should contribute

If you've ever thought "I should make an open source PR someday" — this is a great place to start. The codebase is small, pure Python + Pillow, no framework, no build system. Adding a feature is literally writing one file. Want to add auto-color correction? Blur? Border? Side-by-side merge? Go for it.

devmcp-context: A Simple AI Memory Layer for Your Agent

Kushal Baral — Sun, 17 May 2026 13:37:55 +0000

AI assistants are useful, but they often forget important details between sessions. That makes it hard to keep track of decisions, project notes, bugs, and tasks.

devmcp-context solves that by giving your agent a simple memory layer that lives in your project folder. It is built as a Model Context Protocol (MCP) server, so once you connect it to an agent, the agent can use the MCP tools automatically when it needs to save, read, search, edit, or delete memory.

This post is a quick, easy overview of what it does, how it works, and how you can try it.

Why I Built It

When working with AI tools, I kept running into the same problem:

The agent would forget previous decisions.
Important context would get buried in chat history.
I needed a way to edit memory manually when something changed.
I wanted a solution that was visible, simple, and file-based.

So I built devmcp-context as a lightweight memory system for AI agents.

What It Does

devmcp-context stores memory in plain text files inside an ai-context/ folder.

That means:

You can see what the agent remembers.
You can edit memory directly.
You can change or delete entries directly from the project folder.
You can search across saved context.
You do not need a database.
The memory survives across sessions.

Memory Categories

The project organizes memory into five categories:

project for long-term project notes and conventions
decisions for architecture choices and reasoning
errors for bugs, failures, and fixes
tasks for work in progress
ephemeral for short-lived scratchpad notes

Each category helps keep the memory easy to understand instead of turning into one giant text dump.

How It Works

You do not normally tell the agent to remember every single thing by hand.

Instead, you connect devmcp-context as an MCP server in your agent setup, and then the agent can call the tools when needed:

context_save to create or update memory
context_load to read memory from a category
context_search to find matching entries
context_delete to remove an entry
context_status to see category summaries
context_purge_expired to clean up expired entries

That is the main idea: the agent uses the MCP tools, and the memory stays stored in your project folder where you can inspect it anytime.

How It Looks

The memory is stored as markdown files, so it is easy to inspect and edit.

How to Use It

First, install the package:

pip install devmcp-context

If you use uv:

uv add devmcp-context

After that, connect the server in your agent's MCP config. Once it is connected, the agent can use the tools automatically when it needs them.

Example Workflow

Here is the simple idea:

You connect devmcp-context to your agent.
The agent uses the MCP tools automatically when it needs to save, read, search, edit, or delete memory.
The memory is stored in plain markdown files inside your project folder.
If you want, you can still open those files and edit them manually yourself.

That gives you both automation and manual control.

Why This Is Useful

This setup is helpful when you want:

Better continuity across sessions
Less repetition in agent conversations
Clear project memory you can audit
A simple workflow that fits into Git-based projects

For me, the biggest win is that memory is no longer a black box.

Small Demo

In a real setup, the agent calls the MCP tools through the server, and you still keep full control of the files in the project folder.

context_save(category="decisions", key="auth-strategy", value="Use JWT with refresh tokens", tags=["security"])
context_load(category="decisions")
context_search(query="JWT")

Final Thoughts

devmcp-context is meant to be simple:

file-based
human-readable
searchable
editable
persistent

That is what makes it useful: the agent can use the MCP tools automatically, but the memory still lives in plain files you can open, edit, or delete whenever you want.

If you are building AI-assisted workflows and want memory you can trust, this is a good place to start.

If you want to try it, check out the project docs and give it a spin.

Creativity Is Theft. And Nature Stole First.

Kushal Baral — Thu, 07 May 2026 14:41:57 +0000

Let me ask you something weird.

Why does the human brain look like a neural network?

Not metaphorically. Actually. Literally. The thing we built and called "artificial intelligence" — the thing we're all losing sleep over — looks suspiciously like the thing already sitting inside your skull. Neurons firing. Weights adjusting. Patterns recognizing patterns. Learning from data. Getting better over time.

We didn't invent that. We copied it. And then we called it innovation.

It doesn't stop at the brain either.

The camera? That's an eye. Lens, aperture, light hitting a surface and creating an image. We looked at the human eye and said "yeah we want that" and spent centuries trying to build it out of glass and metal.

Sonar? Bats had it first. We just figured out how to put it in submarines.

Flight? Birds. Obviously. The Wright brothers didn't sit down and think from scratch. They watched things that already flew and asked "what if we did that but with wood and fabric?"

Velcro was invented by a guy who kept getting burrs stuck to his dog's fur.

The whole field of biomimicry exists because at some point engineers collectively admitted — nature figured this out already, let's just copy it.

So here's the uncomfortable question.

Is human creativity actually just... really sophisticated theft?

Okay stay with me here because this is where it gets interesting.

Now science will tell you — nature didn't design any of this intentionally. No plan. No intention. Just random mutations and survival. And maybe that's true.

But honestly? When I sit with that explanation something feels off to me.

Like — the eye. Think about the eye for a second. Something that detects a single photon of light. That adjusts in real time. That self repairs. That runs on almost zero energy. That connects directly to the most complex thinking machine we've ever encountered.

And we're supposed to believe that just... stumbled into existence?

I'm not saying it didn't. I'm not smart enough to say that. I'm just saying — when I look at how perfect these solutions are. How every answer was already there before we thought to ask the question. It doesn't feel like accident to me. It feels like something was already trying to be understood.

Over millions of years. Through billions of failures. Through creatures that couldn't see well enough dying before they reproduced and creatures that could see slightly better surviving just long enough to pass that slight improvement forward.

Evolution is just iteration with death as the feedback loop.

And what came out the other side? The most optimized, elegant, efficient solutions to problems that we are still — with all our intelligence and technology — struggling to fully replicate.

The brain runs on roughly 20 watts of power. Your laptop charger uses more energy than the most complex thinking machine ever created. A bird's bone structure is so optimized for weight and strength that aerospace engineers still study it.

Nature had billions of years and infinite iterations and the strictest possible quality control — if it didn't work, it died. Of course what survived is optimal. Of course we keep copying it. What else would we copy?

So back to AI.

When we built neural networks we weren't being clever. We were being honest. We looked at the only working example of general intelligence we had — the human brain — and we said "let's start there."

Convolutional Neural Networks that power image recognition? Directly inspired by how the visual cortex processes information. The way your brain doesn't look at an image all at once but breaks it into edges, shapes, patterns, then assembles them — CNNs do exactly that.

Reinforcement learning? That's just evolution again. Try things. Reward what works. Punish what doesn't. Repeat until something intelligent emerges.

Transformers, attention mechanisms, the whole architecture behind ChatGPT and everything like it — it's all trying to approximate something the brain does naturally, effortlessly, while also somehow remembering to breathe and regulate your heartbeat at the same time.

We are not building artificial intelligence. We are building a very early, very rough, very power hungry draft of what nature already perfected.

And here's where the philosophy hits.

If we copied nature. And nature copied nothing because nature invented the template. Then what is originality actually?

Picasso said "good artists borrow, great artists steal." But nature didn't even steal. Nature just ran the algorithm long enough that something extraordinary fell out the other side.

Maybe that's what creativity actually is. Not thinking of something from nothing. Nobody does that. Nothing comes from nothing.

Maybe creativity is just iteration with taste.

You take what exists. You combine it differently. You run it through your own specific set of experiences and failures and weird 2am thoughts. And something comes out the other side that didn't exist before. Not because you invented from zero. But because you are a specific, unrepeatable combination of everything you've ever absorbed.

Just like evolution. Just like nature. Just like the neural network sitting in your skull right now reading these words and deciding whether they mean something.

So is AI creative?

It was trained on everything humans ever made. Every book. Every image. Every pattern. Every idea. It iterates. It combines. It produces something that didn't exist before.

Sounds familiar right?

The difference — and maybe this is the only difference that matters — is that AI doesn't have a why.

Nature iterated because death was the alternative. Humans create because something inside us reaches toward meaning. Because we feel things. Because we're trying to say something to someone. Because we're afraid of being forgotten. Because we love someone and don't know how else to say it. Because we're confused about being alive and making something feels like an answer even when it isn't.

AI creates because you asked it to.

That gap — between creating because you must and creating because you were prompted — might be the last real distinction worth talking about.

And maybe this is just me thinking out loud. Maybe this is where the science ends and something else begins.

But when I look at how perfectly optimized nature is. How every solution was already there before we thought to look for it. How we keep arriving at the same answers from completely different directions.

It feels less like random accident to me. And more like something was already trying to be understood.

Maybe evolution isn't nature figuring things out. Maybe it's something figuring itself out. Through nature. Through us. Through whatever comes next.

Every tradition, every belief system, every culture that ever existed — they all pointed at something like this. Just with different words. Different stories. Different names. We rebranded it as science. And forgot to ask if they were describing the same thing all along.

But that's just what I think. I'm not asking you to agree. I'm just asking you to sit with it.

So here's my question for you.

If creativity is just sophisticated iteration — if nature iterated blindly, humans iterated with feeling, and AI iterates with data — at what point in that chain did something genuinely new actually enter the world?

Or did it never? Was it always just the same thing learning about itself through different shapes?

I genuinely don't know. Tell me what you think.

This was written with AI. But the question kept me up at night long before I typed the first prompt. So whose thought is it really? Maybe that's just another version of the same question.

Haul :) a tiny file organizer daemon for Linux

Kushal Baral — Sat, 25 Apr 2026 11:21:47 +0000

I hate messy Downloads folders. You know the feeling:

report.pdf
report(1).pdf
report(2).pdf
screenshot.png
screenshot(1).png
screenshot(2).png
video_final.mp4
video_final_FINAL.mp4
notes.docx
notes_copy.docx
notes_copy_FINAL(1).docx

At some point you just stop caring and let it rot.

Cron jobs felt overkill — why poll every minute just to watch an empty folder? So I built haul. Drop a file in a watched folder, it moves it to the right place. That's it.

The trick — zero CPU when idle

haul uses inotify, a filesystem event API built into the Linux kernel. Instead of running a loop, it just waits for the kernel to say "hey, a file arrived" — sorts it — then exits. systemd restarts it immediately for the next file.

No polling. No persistent process. Nothing running between events.

file lands
    ↓
kernel fires inotify
    ↓
haul wakes up
    ↓
file sorted → ~/Data/subfolder
    ↓
haul exits
    ↓
systemd restarts it
    ↓
(waiting for next file...)

Install

sudo apt install inotify-tools -y
curl -fsSL https://raw.githubusercontent.com/kushal1o1/haul/main/install.sh | bash

Usage

haul install      set up and start
haul sweep        sort files already sitting in watched folders
haul start/stop   manage the service
haul logs         tail the live log
haul uninstall    remove haul (your ~/Data/ is untouched)

What it sorts

Folder	Extensions
PDFs	`.pdf`
Images	`.jpg` `.jpeg` `.png` `.gif` `.webp` `.svg`
Videos	`.mp4` `.mkv` `.avi` `.mov` `.webm`
Audio	`.mp3` `.flac` `.wav` `.ogg` `.m4a`
Code	`.py` `.js` `.ts` `.sh` `.json` `.yaml` `.sql`
Zips	`.zip` `.tar.gz` `.rar` `.7z` `.deb`
WordFiles	`.doc` `.docx` `.odt`
Excel	`.xlsx` `.xls` `.csv`
Others	everything else

Screenshots are detected by source folder, not filename — set SCREENSHOTS to wherever your tool saves them.

Fully configurable

Everything — watched folders, destination, subfolder names, extension rules — is just bash variables at the top of ~/.local/bin/haul. Open it in any editor and change what you want.

DATA="$HOME/Files"          # change destination
DOWNLOADS="$HOME/Desktop"   # change watched folder

After editing: haul restart

Duplicate handling

Same file arrives again → deleted silently
Same name, different content → renamed with a timestamp before moving

Logs

[2024-01-15 14:30:22] MOVED report.pdf → ~/Data/PDFs/
[2024-01-15 14:31:45] DUPLICATE (identical) skipped: report.pdf
[2024-01-15 14:32:10] CONFLICT renamed: notes_20240115_143210.md

Requirements: Linux with systemd, bash 4+, inotify-tools. Tested on Ubuntu 22.04 / 24.04.

Source: github.com/kushal1o1/haul — MIT licensed.

If you've been living with a messy Downloads folder, give haul sweep a try first — it sorts whatever's already there without touching the daemon.

Real MCP has a lot going on - but the core idea is this simple

Kushal Baral — Tue, 21 Apr 2026 17:18:37 +0000

MCP (Model Context Protocol) is everywhere right now. Claude uses it, Cursor uses it, a ton of AI tooling is being built on top of it. There's an official SDK, servers, transports, capabilities negotiation... it can feel like a lot.

But when I actually dug into what MCP is doing at its core, I realized — it's just structured JSON going back and forth. That's the whole idea. So I built a minimal version from raw Python, no libraries, to make sure I actually understood it before touching the real thing.

What MCP actually is

Strip away the SDK and the spec details — here's the mental model:

a server exposes tools (functions an AI can call)
a client discovers those tools and calls them by name
everything is JSON, every message has a predictable shape

The real MCP spec adds things like capability negotiation, resource types, prompt templates, SSE transport, and more. But that core loop — client asks, server responds with a tool result — is the same.

Think of it like HTTP but designed specifically for AI agents calling tools. The protocol exists so any agent can talk to any server without needing custom glue code.

What I built to understand it

Two versions, zero external dependencies — just Python stdlib:

Basic version — the absolute minimum:

client sends a JSON request
server reads it from stdin
server runs a tool
server replies with JSON on stdout

Richer version — closer to real MCP, adds a JSON-RPC style flow:

initialize — handshake, server returns its name and version
tools/list — client asks what tools exist
tools/call — client calls a tool by name with arguments

That three-step flow is basically what happens every time an AI agent connects to a real MCP server.

How a protocol works (the bit no one explains)

Two processes agree on a message format, then just talk. That's it. In this case:

the server sits there reading stdin line by line
the client writes one JSON object per line, reads one JSON response back
no sockets, no framework — just text in an agreed shape

Real MCP uses stdio transport for local servers and SSE for remote ones. Same idea, just fancier plumbing.

Try it

python3 basic-mcp-server.py

Type a raw request:

{"tool": "say_hello", "arguments": {"name": "bro"}}

Get back:

{"result": "Hello bro"}

No library. No magic. Just Python reading and writing JSON — same as what the real SDK wraps.

Full code here → https://github.com/kushal1o1/Mcp-basics

Now I want to build an actual MCP module on top of this foundation — something useful, something real. A devtool? A workflow helper for AI agents?

Drop your idea in the comments — what MCP module should I build next? I'll pick the most interesting one and document the whole thing.

DEV Community: Kushal Baral

Millions of Clicks, 200 Tickets: Building an Endpoint That Cannot Oversell

The uncomfortable truth about this bug

Three quick deaths of a naive counter

The database still lets you race

The fix: make the check and the write ONE thing

Retries sell twice

Proving it under fire

Final boss: payments take seconds

Choosing the TTL is a business decision

Build it yourself

ZeroRelay: Direct Browser-to-Browser Sharing - No Server Ever Sees Your Data

The Pain Point

Demo

What's ZeroRelay?

Architecture

Features

Important Note

Tech Stack

Why Open Source?

Links

I got tired of Googling "resize,compress ,optimize image online " so I built a CLI for it

What's in the box

How it works

Why you should contribute

Links

devmcp-context: A Simple AI Memory Layer for Your Agent

Why I Built It

What It Does

Memory Categories

How It Works

How It Looks

How to Use It

Example Workflow

Why This Is Useful

Small Demo

Final Thoughts

Links

Creativity Is Theft. And Nature Stole First.

Haul :) a tiny file organizer daemon for Linux

The trick — zero CPU when idle

Install

Usage

What it sorts

Fully configurable

Duplicate handling

Logs

Real MCP has a lot going on - but the core idea is this simple

What MCP actually is

What I built to understand it

How a protocol works (the bit no one explains)

Try it