DEV Community: Nick K

Org-Level Email Campaigns are Somehow an Unsolved Problem

Nick K — Mon, 29 Dec 2025 01:06:31 +0000

Defining the Goal

We launched new community discord and slack bots recently at Mintlify and needed to do some customer marketing to let users who had large communities know about them.

Our goal was to send an email sequence to the ~3-10 people from each organization who we identified as being able to get value from the feature. Understand that the nature of this product is that once one person from an organization enables the bot, the task is complete, and we don't want to keep emailing everyone else from the org.

I thought this would be easy using any of the email marketing tools out there like Resend or Loops, but this was not the case. All of the available tools shockingly handle campaigns at a user instead of organization level.

None of them have the concept of "stop emailing this group when any member takes action." They're all built for individual drip campaigns, not org-level outreach.

Tool Selection

Claude Code has made me quite lazy insofar as I try to get everything I can done using it instead of doing things myself manually. Therefore my number one criteria when picking a tool to solve the above problem with was a large API surface that claude could work with.

Instantly was my final selection given its API was the most robust and well documented. It gave claude full access to campaigns, leads, and sequences while also being capable of sending webhooks on reply and unsubscribe events.

Kind of random aside but JAMstack architecture patterns are probably going to make a comeback with AI. I think tools like trpc are going to fall out of favor relative to openapi driven patterns that AI agents can better understand. Seperation of UI and business logic is the way forward if we want our apps to be accessible by AI.

Solution Architecture

The Instantly campaign holds the multi-email sequence and is configured to stop on reply. A lead upload script reads a CSV of contacts, groups them by company, and uploads them to Instantly with a companyName custom variable.

Then a webhook server listens for reply events, finds all leads from the same company, and marks them as "not interested" to stop their sequences.

CSV (company, email)
    → Upload Script
    → Instantly (leads with companyName)

Reply received
    → Instantly webhook
    → Webhook server
    → Find leads by companyName
    → Update lead status
    → Sequence stops for whole company

Creating the Campaign

The campaign itself is straightforward. Set stop_on_reply to true so Instantly stops the sequence for whoever replies, then define your email steps with delays between them.

curl -X POST https://api.instantly.ai/api/v2/campaigns \
  -H "Authorization: Bearer $INSTANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Feature Launch Outreach",
    "stop_on_reply": true,
    "stop_on_auto_reply": true,
    "sequences": [{
      "steps": [
        {"type": "email", "delay": 0, "variants": [{"subject": "...", "body": "..."}]},
        {"type": "email", "delay": 3, "variants": [{"subject": "...", "body": "..."}]}
      ]
    }]
  }'

Uploading Leads

The important bit is to include a companyName custom variable with every lead. Our webhook server uses that to find all leads from the same company and unsubscribe them on relevant events.

import csv
import requests

API_KEY = "your-api-key"
CAMPAIGN_ID = "your-campaign-id"

with open("contacts.csv") as f:
    reader = csv.DictReader(f)
    for row in reader:
        emails = row["emails"].split(";")
        company = row["company_name"]

        for email in emails:
            requests.post(
                "https://api.instantly.ai/api/v2/leads",
                headers={"Authorization": f"Bearer {API_KEY}"},
                json={
                    "email": email.strip(),
                    "company_name": company,
                    "custom_variables": {"companyName": company},
                    "campaign": CAMPAIGN_ID
                }
            )

Registering the Webhook

Tell Instantly to POST to your server whenever someone replies. You'll need the campaign ID from earlier.

curl -X POST https://api.instantly.ai/api/v2/webhooks \
  -H "Authorization: Bearer $INSTANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_hook_url": "https://your-server.com/webhook/reply",
    "event_type": "reply_received",
    "campaign_id": "your-campaign-id"
  }'

Webhook Server

This is the part that makes it all work. When anyone replies, the webhook server extracts the company name, queries Instantly for all leads with that company name, and updates each lead's status to stop their sequence.

const express = require('express');
const app = express();
app.use(express.json());

const API_KEY = process.env.INSTANTLY_API_KEY;
const CAMPAIGN_ID = process.env.CAMPAIGN_ID;

app.post('/webhook/reply', async (req, res) => {
  const event = req.body;

  if (event.event_type !== 'reply_received') {
    return res.json({ status: 'ignored' });
  }

  const leadEmail = event.lead_email;
  const companyName = event.lead?.company_name;

  if (!companyName) {
    return res.json({ status: 'ignored', reason: 'no company' });
  }

  // Find all leads from this company
  const leads = await findLeadsByCompany(companyName);

  // Stop all of them (except the one who replied, they're already stopped)
  for (const lead of leads) {
    if (lead.email !== leadEmail) {
      await stopLead(lead.email);
    }
  }

  res.json({ status: 'ok', stopped: leads.length - 1 });
});

// Instantly's API doesn't let you filter by company_name server-side.
// The search param only works on name/email. So we fetch all leads
// and filter client-side. For large campaigns, you'd want to cache
// this or build your own company->leads index.
async function findLeadsByCompany(companyName) {
  const leads = [];
  let cursor = null;

  do {
    const resp = await fetch('https://api.instantly.ai/api/v2/leads/list', {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ campaign: CAMPAIGN_ID, starting_after: cursor })
    });
    const data = await resp.json();
    leads.push(...data.items);
    cursor = data.next_starting_after;
  } while (cursor);

  return leads.filter(lead => lead.company_name === companyName);
}

async function stopLead(email) {
  await fetch('https://api.instantly.ai/api/v2/leads/update-interest-status', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ lead_email: email, interest_value: -1 })
  });
}

app.listen(3000);

You can host this anywhere that can receive HTTP requests. I used a cheap VPS with Docker behind Caddy for SSL. Other options include Cloudflare Workers, Railway, Render, AWS Lambda, or Vercel. The server is stateless, so any hosting that can run Node.js will work.

Someone Please Build This

This solution works, but it's more complex than it should be. The fact that I had to build a webhook server to get org-level behavior is absurd. This should be a checkbox in every B2B email tool.

What I actually want is to define groups of contacts by company, toggle "stop group on reply" as a campaign setting, and have the email tool handle it without webhooks.

If you're building email tools, please add this.

How I Use Claude Code on My Phone with Termux and Tailscale

Nick K — Mon, 20 Oct 2025 15:40:00 +0000

There's a mini gold rush to put Claude Code on your phone. Some startups are building custom apps, others are creating managed cloud environments. They're solving real problems, but you're trading raw Unix power for convenience. If you have a desktop and 20 minutes, you can get full kernel access with SSH, termux, and tailscale.

Yesterday I posted about shipping a feature to this blog from the passenger seat while driving to Apple Hill, CA from San Francisco. I SSH'd into my office desktop from my phone, prompted Claude to make the changes, tested them on my phone's browser, and pushed to production in 10 minutes. That post got 130k impressions and dozens of people asked for the setup.

This article walks through doing SSH-based mobile development with Claude Code. If you have a desktop that stays on (or a cheap VPS), you can get full terminal access from your phone with session persistence, port forwarding, and the ability to test your code on your actual mobile browser. The initial setup takes about 20 minutes and just works once configured.

The Architecture

The setup uses five standard Unix tools that work together without custom integration. A desktop runs Claude Code, tailscale creates a private network between your devices, termux gives you a real terminal on Android, SSH handles the connection, and tmux keeps your sessions alive when you disconnect.

Step 1: Setup Your Desktop

You need a computer that stays on. This could be a desktop at home, a desktop at your office, a cloud VM, or a home server. It doesn't need to be powerful. Claude Code just makes API calls, the actual compute happens at Anthropic.

I keep a desktop at my office that stays on 24/7. It's running Ubuntu with Claude Code installed. The computer does nothing else. It just sits there waiting for me to SSH in and start coding.

First, install Claude Code globally using npm. This gives you the claude command that you'll use to start coding sessions.

npm install -g @anthropics/claude-code

Next, install tmux for session persistence. When you disconnect from SSH (phone locks, network drops, whatever), tmux keeps your Claude Code session running in the background. When you reconnect, you pick up exactly where you left off.

sudo apt install tmux  # Ubuntu/Debian
brew install tmux      # macOS

With Claude Code and tmux installed, your desktop is ready to host your development sessions.

Step 2: Install Tailscale Everywhere

Tailscale creates a private network between all your devices. Your phone gets a stable IP address that can reach your desktop, even when you're on different networks. It just works.

On your desktop, run the Tailscale installer. The script will detect your OS and install the right package. Then bring up the Tailscale connection, which will prompt you to authenticate in your browser.

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Install Tailscale on your phone from the Play Store. Sign in with the same account. Your devices are now on the same network.

You'll need your desktop's Tailscale IP address to connect from your phone. Grab it with this command.

tailscale ip -4

You'll get something like 100.64.0.5. That's your desktop's address on the Tailscale network. It's stable, it's private, and it works from anywhere.

Step 3: Install Termux on Your Phone

Termux is a terminal emulator for Android that gives you a real Linux environment. Not a toy terminal. A real one with bash, ssh, and full package management.

Install Termux from F-Droid, not the Play Store. The Play Store version is outdated and broken. Get it from https://f-droid.org/en/packages/com.termux/.

Once installed, you'll need to update the package repositories and install the SSH client. Termux uses pkg as its package manager, which is basically a wrapper around apt.

pkg update
pkg install openssh

With OpenSSH installed, Termux can now connect to your desktop over SSH.

Step 4: SSH Into Your Desktop

Now for the moment of truth. Open Termux and SSH to your desktop using the Tailscale IP you grabbed earlier. Replace 100.64.0.5 with your actual IP and your-username with your desktop username.

ssh your-username@100.64.0.5

The first time you connect, SSH will ask you to verify the host fingerprint. Type yes. Then enter your password.

You're in. You're now running a shell on your desktop, from your phone, over a secure encrypted connection that works anywhere you have internet.

Step 5: Use tmux for Session Persistence

tmux is what makes this whole setup practical. When you disconnect from SSH, your tmux session keeps running on the desktop. When you reconnect, you attach to the same session and everything is exactly where you left it.

You're now connected to your desktop via SSH from your phone. Start a new tmux session with a name you'll remember. I usually name mine after the project I'm working on.

tmux new -s code

This creates a session named "code". You can name it anything. Inside the tmux session, launch Claude Code and start working.

claude

Now you're coding. On your phone. Using Claude Code. Running on your desktop.

When you need to disconnect, don't exit Claude Code. Don't exit tmux. Just close Termux or let your phone lock. The tmux session stays running on your desktop.

Later, when you want to code again, SSH back in and reattach to your session. Everything will be exactly where you left it.

ssh your-username@100.64.0.5
tmux attach -t code

Your conversation with Claude is still there. Your file context is still loaded. You can continue your previous task immediately.

In the Apple Hill example from the intro, this is exactly what I did. I SSH'd in, ran tmux attach -t personalsite to reconnect to my development session, and told Claude to add a section about the Public Suffix List and make headings into clickable anchor links. The session had been running for days. I just picked up exactly where I'd left off.

Why This Works Better Than Custom Apps

Every startup trying to solve "Claude Code on mobile" is building abstractions on top of these primitives. They're not giving you anything you can't already do with SSH and Termux. They're just wrapping it in a prettier UI and charging for hosting.

When you do it yourself, you get several advantages.

Port forwarding just works. With Tailscale, your desktop's ports are directly accessible from your phone. No configuration, no exposing services to the public internet, no proxies adding latency. Your phone and desktop are on the same private network, so anything listening on your desktop is one IP address away.

Full CLI access to configure your environment. Want to run your dev server with --host so you can test on your phone's browser? Just add the flag. Need to adjust firewall rules, modify server configs, or install system packages? You have root access. Native mobile coding apps can't offer this level of control because it's too niche for their target users, but for power users it's essential.

Session persistence that actually works. tmux was built for this. Your session survives network disconnections, phone reboots, and SSH reconnects. You never lose your place.

Your own hardware. Your desktop has your SSH keys, your git credentials, your environment exactly how you configured it. You're not coding in a disposable cloud container.

The Mobile Experience

I'm not going to pretend coding on a phone is as good as coding on a desktop. It's not. The screen is small. The keyboard is mediocre. You can't see multiple files at once.

But Claude Code is different from traditional coding. You're not typing out functions character by character. You're describing what you want, reviewing Claude's changes, and approving or rejecting them. That workflow actually works on mobile.

The Apple Hill example wasn't cherry-picked. I've shipped real features from my phone. I've fixed production bugs while getting coffee. I've reviewed pull requests from the back of an Uber. It's not my primary development environment, but it's shockingly capable when I need it.

The key is that Claude Code is conversational. You're having a back-and-forth with an AI that writes code for you. That interaction model translates to mobile better than traditional text editing. You're reading more than you're typing, and phones are great for reading.

Practical Tips

Once you have the basic setup running, there are a few tweaks that make the mobile coding experience dramatically better. These aren't strictly necessary, but they'll save you time and frustration.

Test Your Changes on Your Phone's Browser

This is the killer feature. You're not just editing code remotely, you can test it on your phone while the dev server runs on your desktop.

When I was working on the blog changes from Apple Hill, I wanted to see how the clickable anchor links looked on mobile. The trick is starting your dev server with the --host flag, which makes it accessible on your Tailscale network instead of just localhost.

yarn dev --host

For Vite (which Astro uses), this binds the dev server to 0.0.0.0 instead of 127.0.0.1. For other frameworks: npm start -- --host for React, next dev -H 0.0.0.0 for Next.js, python manage.py runserver 0.0.0.0:8000 for Django.

Grab your desktop's Tailscale IP again if you forgot it.

tailscale ip -4

Then on your phone's browser, navigate to http://100.64.0.5:4321 (replace with your Tailscale IP and port).

You're now viewing your local dev server, running on your desktop 2.5 hours away, in your phone's browser. I saw the anchor links were styled wrong, told Claude to fix them, refreshed, confirmed they looked good, and pushed. The whole workflow took maybe 10 minutes.

You're developing with the actual target device in your hand. You can test responsive layouts, check mobile interactions, and iterate immediately instead of deploying to staging or waiting until you're back at your desk.

Use SSH Keys

Don't type your password every time you SSH. Generate an SSH key on your phone and add it to your desktop's authorized keys.

Open Termux and generate an ed25519 key (the modern standard). Then use ssh-copy-id to automatically add it to your desktop's authorized keys file.

ssh-keygen -t ed25519
ssh-copy-id your-username@100.64.0.5

Now you can SSH without a password.

Create an SSH Config

Make connecting easier by adding your desktop to your SSH config. Instead of typing ssh your-username@100.64.0.5 every time, you can create an alias. Make a file at ~/.ssh/config in Termux with this content.

Host desktop
    HostName 100.64.0.5
    User your-username

Now you can just type ssh desktop instead of remembering the IP and username.

Use a Better Keyboard

Termux works with external keyboards. I keep a small Bluetooth keyboard in my bag. When I'm actually trying to get work done on my phone, I pull out the keyboard. It makes a massive difference.

The phone screen is fine for reading. The keyboard makes typing bearable.

Set Up tmux Keybindings

tmux's default keybindings are terrible on mobile. Remap them to something sensible. On your desktop, create or edit ~/.tmux.conf and add these bindings. They make tmux way easier to use on a phone keyboard.

# Use Ctrl-A instead of Ctrl-B (easier to type)
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# Split panes with | and -
bind | split-window -h
bind - split-window -v

Now you can manage tmux sessions without finger gymnastics.

Run Multiple Sessions

You can have multiple tmux sessions for different projects. I usually have one for each repo I'm actively working on. Start them with descriptive names so you remember what's what.

tmux new -s backend
tmux new -s frontend
tmux new -s experiments

When you SSH in and want to see what sessions are running, list them.

tmux ls

Then attach to whichever one you want to work on.

tmux attach -t frontend

This keeps your different projects isolated. You can switch contexts just by attaching to a different session.

Security Considerations

You're SSH'ing into your desktop over the internet. That's a potential security risk if you do it wrong. Do it right with a few precautions.

Use Tailscale. Never expose SSH to the public internet. Use Tailscale to create a private network between your devices. Your SSH traffic stays encrypted and never touches the public internet directly.

Use SSH keys. Disable password authentication entirely. Keys are longer, stronger, and can't be brute-forced. Edit /etc/ssh/sshd_config on your desktop and set these values, then restart sshd.

PasswordAuthentication no
PubkeyAuthentication yes

Keep your phone secure. Your phone now has SSH access to your development machine. If someone steals your phone, they can access your desktop. Use a strong PIN or biometric lock. Enable disk encryption. Consider using a password manager for your SSH key passphrase.

Monitor SSH access. Check who's connected to your machine with who or w. Check SSH logs with sudo tail -f /var/log/auth.log. If you see connections you don't recognize, revoke SSH keys and investigate.

The threat model here is pretty mild. Your SSH traffic is encrypted. Your Tailscale network is private. The main risk is losing your phone, which is why phone security matters.

When This Doesn't Work

This setup assumes you have a desktop that stays on. If you don't, you need a cloud VM or a home server. That's still not a reason to use a third-party service. Just rent a $5/month VPS from DigitalOcean or Hetzner, install Tailscale and Claude Code, and SSH into it the same way.

This also assumes you're on Android. If you're on iOS, Termux isn't available. You'll need to use a different SSH client like Blink or Prompt. The rest of the setup is the same.

If you're on unstable internet, SSH can be frustrating. Mosh (mobile shell) is designed for high-latency or unreliable connections. Install it on both your phone and desktop, then use mosh desktop instead of ssh desktop. It handles disconnections gracefully and keeps your terminal responsive even on bad networks.

The Bottom Line

Mobile development with Claude Code doesn't require new infrastructure or custom applications. The components you need are SSH, Tailscale, Termux, and a desktop that stays on. These are standard Unix tools that have been solving remote access problems for decades.

SSH has been the standard for secure remote access since 1995. Tmux has provided session management since 2007. Tailscale is newer, but it's built on WireGuard, which has undergone extensive security audits. These tools are mature, well-documented, and widely deployed in production environments.

The underlying problem, accessing a remote development environment from a mobile device, was solved long before mobile coding became a focus. This approach applies those established solutions to Claude Code without requiring custom middleware or managed services.

If you have a desktop or VPS and 20 minutes for setup, you can have this working today. Install termux, configure tailscale, and connect via SSH. The workflow is straightforward and the tools are reliable.

Glory be to the AI overlords, who grant us the grace to code at the bar without shame.

Respect Content Negotiation to serve Markdown instead of HTML to LLMs

Nick K — Sat, 04 Oct 2025 17:33:45 +0000

Agents don't need to see websites with markup and styling; anything other than plain Markdown is just wasted money spent on context tokens.

I decided to make my Astro sites more accessible to LLMs by having them return Markdown versions of pages when the Accept header has text/plain or text/markdown preceding text/html. This was very heavily inspired by this post on X from bunjavascript.

Hopefully this helps SEO too, since agents are a big chunk of my traffic. The Bun team reported a 10x token drop for Markdown and frontier labs pay per token, so cheaper pages should get scraped more, be more likely to end up in training data, and give me a little extra lift from assistants and search.

Note: You can check out the feature live by running curl -H "Accept: text/markdown" https://www.skeptrune.com or curl -H "Accept: text/plain" https://www.skeptrune.com in your terminal.

Static Site Generators are already halfway there

Static site generators like Astro and Gatsby already generate a big folder of HTML files, typically in a dist or public folder through an npm run build command. The only thing missing is a way to convert those HTML files to markdown.

It turns out there's a great CLI tool for this called html-to-markdown that can be installed with npm install -D @wcj/html-to-markdown-cli and run during a build step using npx.

Here's a quick Bash script an LLM wrote to convert all HTML files in dist/html to Markdown files in dist/markdown, preserving the directory structure:

# convert-to-markdown.sh
mkdir -p dist/markdown

find dist/html -type f -name "*.html" | while read -r file; do
    relative_path="${file#dist/html/}"
    dest_path="dist/markdown/${relative_path%.html}.md"
    mkdir -p "$(dirname "$dest_path")"
    npx @wcj/html-to-markdown-cli "$file" --stdout > "$dest_path"
done

Once you have the conversion script in place, the next step is to make it run as a post-build action. Here's an example of how to modify your package.json scripts section:

"scripts": {
    "build": "astro build && yarn mv-html && yarn convert-to-markdown",
    "mv-html": "mkdir -p dist/html && find dist -type f -name '*.html' -not -path 'dist/html/*' -exec sh -c 'for f; do dest=\"dist/html/${f#dist/}\"; mkdir -p \"$(dirname \"$dest\")\"; mv -f \"$f\" \"$dest\"; done' sh {} +",
  "convert-to-markdown": "bash convert-to-markdown.sh"
}

Moving all HTML files to dist/html first is only necessary if you're using Cloudflare Workers, which will serve existing static assets before falling back to your Worker. If you're using a traditional reverse proxy, you can skip that step and just convert directly from dist to dist/markdown.

Note: I learned after I finished the project that I could have added run_worker_first = ["*"] to my wrangler.json so I didn't have to move any files around. That field forces the worker to always run frst. Shoutout to the kind folks on reddit for telling me.

Cloudflare Workers-specific configuration

I pushed myself to go out of my comfort zone and learn Cloudflare Workers for this project since my company uses them extensively. If you're using a traditional reverse proxy like Nginx or Caddy, you can skip this section (and honestly, you'll have a much easier time).

If you're coming from traditional reverse proxy servers, Cloudflare Workers force you into a different paradigm. What would normally be a simple Nginx or Caddy rule becomes custom wrangler.jsonc configuration, moving your entire site to a shadow directory so Cloudflare doesn't serve static assets by default, writing JavaScript to manually check headers and using env.ASSETS.fetch to serve files. SO MANY STEPS TO MAKE A SIMPLE FILE SERVER!

This experience finally made Next.js 'middleware' click for me. It's not actually middleware in the traditional sense of a REST API; it's more like 'use this where you would normally have a real reverse proxy.' Both Cloudflare Workers and Next.js Middleware are essentially JavaScript-based reverse proxies that intercept requests before they hit your application.

While I'd personally prefer Terraform with a hyperscaler or a VPS for a more traditional setup, new startups love this pattern, so it's worth understanding.

Here's an example of a working wrangler.jsonc file to refer to a new worker script and also bind your build output directory as a static asset namespace:

{
  "main": "worker.js",
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS"
  }
}

Below is a minimal worker script that inspects the Accept header and serves markdown when requested, otherwise falls back to HTML:

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const acceptHeader = request.headers.get("accept") || "";
    const acceptTypes = acceptHeader.split(",");

    const plainIndex = acceptTypes.findIndex(
      (t) => t.includes("text/plain") || t.includes("text/markdown")
    );
    const htmlIndex = acceptTypes.findIndex((t) => t.includes("text/html"));
    const prefersMarkdown =
      plainIndex !== -1 && (htmlIndex === -1 || plainIndex < htmlIndex);

    const tryServeContent = async (format) => {
      let contentType;
      if (format === "markdown") {
        if (url.pathname == "" || url.pathname == "/") {
          const sitemapResponse = await env.ASSETS.fetch(
            new Request(new URL("/sitemap-0.xml", request.url))
          );
          if (sitemapResponse.ok) {
            const content = await sitemapResponse.text();
            return new Response(content, {
              headers: {
                "Content-Type": "application/xml; charset=utf-8",
                "Cache-Control": "public, max-age=3600",
              },
            });
          }
        }

        contentType = "text/plain; charset=utf-8";
        let distPath = `/markdown${url.pathname}`;

        if (!distPath.endsWith(".md") && !distPath.endsWith("/")) {
          distPath += "/index.md";
        } else if (distPath.endsWith("/")) {
          distPath += "index.md";
        }

        if (url.pathname === "/") {
          distPath = "/markdown/index.md";
        }

        try {
          const response = await env.ASSETS.fetch(
            new Request(new URL(distPath, request.url))
          );
          if (response.ok) {
            const content = await response.text();
            return new Response(content, {
              headers: {
                "Content-Type": contentType,
                "Cache-Control": "public, max-age=3600",
              },
            });
          }
        } catch (error) {
          console.error(`Error fetching HTML file from ${distPath}:`, error);
        }
      } else {
        contentType = "text/html; charset=utf-8";
        let distPath = `/html${url.pathname}`;

        if (!distPath.endsWith(".html") && !distPath.endsWith("/")) {
          distPath += "/index.html";
        } else if (distPath.endsWith("/")) {
          distPath += "index.html";
        }

        // Handle root path
        if (url.pathname === "/") {
          distPath = "/html/index.html";
        }

        try {
          const response = await env.ASSETS.fetch(
            new Request(new URL(distPath, request.url))
          );
          if (response.ok) {
            const content = await response.text();
            return new Response(content, {
              headers: {
                "Content-Type": contentType,
                "Cache-Control": "public, max-age=3600",
              },
            });
          }
        } catch (error) {
          console.error(`Error fetching HTML file from ${distPath}:`, error);
        }
      }

      return null;
    };

    if (prefersMarkdown) {
      const markdownResponse = await tryServeContent("markdown");
      if (markdownResponse) return markdownResponse;

      const htmlResponse = await tryServeContent("html");
      if (htmlResponse) return htmlResponse;
    } else {
      const htmlResponse = await tryServeContent("html");
      if (htmlResponse) return htmlResponse;

      const markdownResponse = await tryServeContent("markdown");
      if (markdownResponse) return markdownResponse;
    }

    return await env.ASSETS.fetch(
      new Request(new URL("/html/404.html", request.url))
    );
  },
};

Pro tip: make the root path / serve your sitemap.xml instead of markdown content for your homepage such that an agent visiting your root URL can see all the links on your site.

Caddy configuration

It's likely much easier to set this system up with a traditional reverse proxy file server like Caddy or Nginx. Here's a simple Caddyfile configuration that does the same thing:

{
    your-personal-domain.com {
        root * /path/to/your/dist
        file_server

        @markdown {
            header Accept *text/markdown*
            header Accept *text/plain*
            not header Accept *text/html*
        }
        handle @markdown {
            rewrite * /markdown{path}/index.md
            try_files {path} {path}.md /markdown/index.md
            file_server
        }

        handle {
            rewrite * /html{path}/index.html
            try_files {path} {path}.html /html/index.html
            file_server
        }

        handle_errors {
            respond "404 Not Found" 404
            try_files /html/404.html
        }
    }
}

I will leave Nginx configuration as an exercise for the reader or perhaps the reader's LLM of choice.

Conclusion: A More Accessible Web for Agents

By serving lean, semantic Markdown to LLM agents, you can achieve a 10x reduction in token usage while making your content more accessible and efficient for the AI systems that increasingly browse the web. This optimization isn't just about saving money; it's about GEO (Generative Engine Optimization) for a changed world where millions of users discover content through AI assistants.

Astro's flexibility made this implementation surprisingly straightforward. It only took me a couple of hours to get both the personal blog you're reading now and patron.com to support this feature.

If you're ready to make your site agent-friendly, I encourage you to try this out. For a fun exercise, copy this article's URL and ask your favorite LLM to "Use the blog post to write a Cloudflare Worker for my own site." See how it does! You can also check out the source code for this feature at github.com/skeptrunedev/personal-site to get started.

I'm excited to see the impact of this change on my site's analytics and hope it inspires others. If you implement this on your own site, I'd love to hear about your experience! Connect with me on X or LinkedIn.

Building SSR with Vite: A Custom getStaticProps Replacement

Nick K — Tue, 02 Sep 2025 13:34:07 +0000

For the complete source code of our implementation, check out the clients/react-server/ directory in our open-source repository.

When migrating from Next.js to a custom Vite setup, one of the biggest challenges is replacing Next.js's getStaticProps and getServerSideProps functions. These functions make server-side data fetching elegant and straightforward. But with a custom Vite SSR setup, you need to build this functionality yourself.

In this tutorial, I'll walk you through exactly how we implemented server-side data loading at Patron, creating a system that's both flexible and performant.

Why Build Custom SSR with Vite?

Before diving into the implementation, let's establish why you might want to build a custom SSR solution with Vite instead of using Next.js:

Full Control: Complete control over your server logic and data loading patterns
Performance: Vite's incredibly fast dev server and build times
Flexibility: No framework constraints on your architecture decisions
Streaming: Native support for React 18's streaming SSR features
Simplicity: Fewer abstractions between you and the underlying React SSR APIs

The Architecture Overview

Our SSR system consists of three main components:

Express Server (server.js) - Handles requests and orchestrates SSR
Server Entry Point (entry-server.tsx) - Renders React to streams
Client Entry Point (entry-client.tsx) - Hydrates the client-side app
Data Loading Function (loadDataForUrl) - Our getStaticProps replacement

Step 1: Setting Up the Express Server

Let's start with the core server setup. Create a server.js file in your project root:

import fs from "node:fs/promises";
import express from "express";

const isProduction = process.env.NODE_ENV === "production";
const port = process.env.PORT || 5173;
const base = process.env.BASE || "/";
const ABORT_DELAY = 10000;

const templateHtml = isProduction
  ? await fs.readFile("./dist/client/index.html", "utf-8")
  : "";

const app = express();

The key insight here is that we need different behavior for development vs production. In development, we'll use Vite's dev server. In production, we'll serve pre-built assets.

Step 2: Vite Integration

Next, integrate Vite's dev server for development mode:

/** @type {import('vite').ViteDevServer | undefined} */
let vite;
if (!isProduction) {
  const { createServer } = await import("vite");
  vite = await createServer({
    server: { middlewareMode: true },
    appType: "custom",
    base,
  });
  app.use(vite.middlewares);
} else {
  const compression = (await import("compression")).default;
  const sirv = (await import("sirv")).default;
  app.use(compression());
  app.use(base, sirv("./dist/client", { extensions: [] }));
}

This setup gives us Vite's dev server in development with hot module replacement, and efficient static serving in production.

Step 3: The getStaticProps Replacement

Here's where the magic happens. Instead of Next.js's getStaticProps, we create a custom loadDataForUrl function:

/**
 * Our replacement for getStaticProps/getServerSideProps
 * This runs on the server for every request
 */
async function loadDataForUrl(url, req) {
  // Route-based data loading
  if (url.startsWith("/api-demo")) {
    // Example: call internal APIs, databases, etc.
    // const response = await fetch(process.env.INTERNAL_API_URL + '/data');
    // return await response.json();

    return {
      route: url,
      userAgent: req.headers["user-agent"],
      message: "Hello from the server-only loader",
      now: new Date().toISOString(),
    };
  }

  if (url.startsWith("/profile")) {
    // Example: load user data
    // const user = await getUserFromDatabase(req.session.userId);
    // return { user };
  }

  // Return null for routes that don't need server data
  return null;
}

This function gives you complete control over data loading patterns. You can:

Call databases directly
Make internal API requests
Access request headers and session data
Implement route-based data loading logic
Return different data shapes for different routes

Step 4: Server-Side Rendering Pipeline

Now we connect everything together in the main request handler:

app.use(async (req, res) => {
  try {
    const url = req.originalUrl.replace(base, "");

    // Load template and render function
    let template;
    let render;
    if (!isProduction) {
      template = await fs.readFile("./index.html", "utf-8");
      template = await vite.transformIndexHtml(url, template);
      render = (await vite.ssrLoadModule("/src/entry-server.tsx")).render;
    } else {
      template = templateHtml;
      render = (await import("./dist/server/entry-server.js")).render;
    }

    // 1. Load server-side data (our getStaticProps replacement)
    const initialData = await loadDataForUrl(url, req);

    // 2. Safely serialize and inject data into HTML
    const serialized = JSON.stringify(initialData).replace(/</g, "\\u003c");
    template = template.replace(
      "<!--app-head-->",
      `<script>window.__INITIAL_DATA__ = ${serialized}</script>`,
    );

    // 3. Set up streaming SSR
    const [htmlStart, htmlEnd] = template.split("<!--app-html-->");

    let didError = false;
    const stream = render(url, initialData, {
      onShellReady() {
        res.status(didError ? 500 : 200);
        res.set({ "Content-Type": "text/html" });
        res.write(htmlStart);
        stream.pipe(res);
      },
      onAllReady() {
        res.end(htmlEnd);
      },
      onError(error) {
        didError = true;
        console.error(error);
      },
    });
  } catch (e) {
    vite?.ssrFixStacktrace(e);
    console.log(e.stack);
    res.status(500).end(e.stack);
  }
});

The critical steps here are:

Data Loading: Call our custom data loader
Data Serialization: Safely inject data into the HTML template
Streaming: Use React 18's streaming SSR for optimal performance

Step 5: React Server Entry Point

Create src/entry-server.tsx:

import { StrictMode } from "react";
import {
  type RenderToPipeableStreamOptions,
  type PipeableStream,
  renderToPipeableStream,
} from "react-dom/server";
import App from "./App";

export function render(
  _url: string,
  initialData: unknown,
  options?: RenderToPipeableStreamOptions,
): PipeableStream {
  return renderToPipeableStream(
    <StrictMode>
      <App initialData={initialData} />
    </StrictMode>,
    options,
  );
}

This is your server-side React rendering entry point. The initialData parameter contains whatever your loadDataForUrl function returned.

Step 6: Client-Side Hydration

Create src/entry-client.tsx:

import { StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";
import App from "./App";

hydrateRoot(
  document.getElementById("root") as HTMLElement,
  <StrictMode>
    <App initialData={(window as any).__INITIAL_DATA__} />
  </StrictMode>,
);

This hydrates your React app on the client side, using the same initialData that was serialized from the server.

Step 7: Using Server Data in Your App

Finally, use the server-loaded data in your React components:

type AppProps = {
  initialData?: unknown;
};

function App({ initialData }: AppProps) {
  // Use your server data however you need
  console.log("Data from server:", initialData);

  return (
    <div>
      <h1>My SSR App</h1>
      {initialData && <pre>{JSON.stringify(initialData, null, 2)}</pre>}
    </div>
  );
}

export default App;

Step 8: Vite Configuration

Don't forget your vite.config.ts:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
});

Step 9: Build Configuration

Update your package.json scripts:

{
  "scripts": {
    "dev": "node server",
    "build": "npm run build:client && npm run build:server",
    "build:client": "vite build --outDir dist/client",
    "build:server": "vite build --ssr src/entry-server.tsx --outDir dist/server",
    "preview": "cross-env NODE_ENV=production node server"
  }
}

Advanced Patterns

Route-Based Data Loading

You can implement sophisticated routing patterns:

async function loadDataForUrl(url, req) {
  const routes = {
    "/dashboard": () => loadDashboardData(req.session.userId),
    "/profile/(.+)": (match) => loadUserProfile(match[1]),
    "/api/posts": () => loadAllPosts(),
  };

  for (const [pattern, loader] of Object.entries(routes)) {
    const match = url.match(new RegExp(pattern));
    if (match) {
      return await loader(match);
    }
  }

  return null;
}

Error Boundaries and Loading States

Handle loading and error states gracefully:

function App({ initialData }: AppProps) {
  const [data, setData] = useState(initialData);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);

  // Client-side data fetching for navigation
  const loadData = async (url: string) => {
    setLoading(true);
    try {
      const response = await fetch(`/api/data?url=${url}`);
      const newData = await response.json();
      setData(newData);
    } catch (err) {
      setError(err as Error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <ErrorBoundary>
      {loading && <LoadingSpinner />}
      {error && <ErrorMessage error={error} />}
      <MainApp data={data} />
    </ErrorBoundary>
  );
}

Performance Considerations

Caching Strategy

Implement intelligent caching in your data loader:

const cache = new Map();

async function loadDataForUrl(url, req) {
  const cacheKey = `${url}-${req.session?.userId || "anonymous"}`;

  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }

  const data = await fetchDataForRoute(url, req);

  // Cache for 5 minutes
  cache.set(cacheKey, data);
  setTimeout(() => cache.delete(cacheKey), 5 * 60 * 1000);

  return data;
}

Streaming Benefits

React 18's streaming SSR provides significant performance benefits:

Faster TTFB: Users see content as soon as the shell is ready
Progressive Loading: Suspense boundaries load independently
SEO Benefits: Search engines get complete HTML
Better UX: No flash of unstyled content

Deployment Considerations

Environment Variables

Set up proper environment handling:

// In production, pre-load environment-specific data
const config = {
  apiUrl: process.env.API_URL,
  dbUrl: process.env.DATABASE_URL,
  cacheEnabled: process.env.CACHE_ENABLED === "true",
};

async function loadDataForUrl(url, req) {
  if (config.cacheEnabled) {
    // Use caching logic
  }

  // Use config.apiUrl for API calls
}

Docker Setup

Here's a sample Dockerfile:

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 5173

CMD ["node", "server.js"]

Comparison with Next.js

Feature	Next.js	Custom Vite SSR
Dev Speed	Good	Excellent
Build Speed	Good	Excellent
Data Loading	`getStaticProps`/`getServerSideProps`	Custom `loadDataForUrl`
Flexibility	Framework constraints	Complete control
Complexity	Low	Medium
Ecosystem	Large	Growing

Conclusion

Building a custom SSR system with Vite gives you the performance benefits of Vite with complete control over your data loading patterns. The loadDataForUrl pattern we've implemented provides a flexible replacement for Next.js's data fetching functions while maintaining the benefits of server-side rendering.

Key takeaways:

Server-side data loading can be implemented with a single function that routes based on URL patterns
Streaming SSR provides excellent performance characteristics
Development experience remains excellent with Vite's fast dev server
Production builds are optimized and efficient

The system we've built at Patron handles complex authentication flows, database queries, and API integrations while maintaining sub-100ms response times. It's a pattern that scales from simple blogs to complex applications.

For the complete source code of our implementation, check out the clients/react-server/ directory in our open-source repository.

How I Snagged `patron.com` and Why You Should Just Ship It 🚀

Nick K — Mon, 18 Aug 2025 07:32:56 +0000

The Plot Twist That Changed Everything

Picture this: It's 2022, I'm fresh out of college with a crystal-clear vision to build the next-gen Patreon for serialized creators called Patron. But then ChatGPT drops and suddenly everyone's losing their minds over AI.

So what did I do? I pivoted harder than a React component getting new props.

Instead of building creator tools, I went all-in on Trieve, a retrieval API riding the AI wave. Fast forward through 2.5 years of grinding: first customers ✅, Y Combinator ✅, $3.5M raised ✅, and boom - acquired!

But here's the kicker: that original Patron idea? It never left my brain. And now, post-exit, I finally had the bandwidth to chase it down.

Why "Patron" Just Hits Different

Ever notice how creators on Patreon accidentally say "Patron" instead of "Patreon"? It happens ALL. THE. TIME. It's like their brain is telling them what the platform should actually be called.

Plus, let's be real - Patreon treats every creator the same whether you're making $50/month or $50K/month. Where's the white-glove service for the heavy hitters? Where are the tools built specifically for episodic content instead of random posts?

I wanted to build what Patreon should have been: premium revenue splits, dedicated success managers, killer analytics, and tools that actually understand serialized content. Basically, treat creators like the media empires they actually are.

But first, I needed the perfect domain...

The Million Dollar Question: How Do You Get `patron.com`?

I punched in patron.com and got redirected to some basic landing page at world.com. Classic domain parking situation. The page screamed "we own premium domains as investments" and had one contact: Gary Millin.

Here's what most people don't get about premium domains: it's not just about throwing money at the problem. These domain owners are sitting on digital gold. They want to see their baby go to someone who'll actually build something epic with it.

Mission: convince Gary I was that person.

Cold Outreach Like a Boss

Time for some good old-fashioned hustle. I hit Gary with a standard outbound sequence:

Cold emails (professional but persistent)
LinkedIn Sales Navigator messages
No fancy tricks, just solid execution

The difference this time? Credibility was my secret weapon. Having YC, Trieve's growth story, and a successful exit meant people actually replied to my emails. It's wild how much easier doors open when you've got that track record.

Pro tip: If you're early in your journey and nobody's responding, just remember - it gets easier after your first win.

When in Doubt, Get on a Plane ✈️

Gary finally responded, and from there it was surprisingly straightforward:

Booked a flight to New Jersey (where his office was)
Met face-to-face and pitched the vision
Dropped a detailed 100-day plan covering product development, creator onboarding, and revenue projections
Negotiated terms like civilized humans

That 100-day plan was clutch. It proved I wasn't some domain flipper - I had a real roadmap with concrete milestones. Gary needed to see I was serious about building something valuable.

The deal? Founder-friendly terms where I get perpetual usage rights without cash upfront. I only pay a revenue percentage if the business actually works. Basically, Gary became an investor in the vision, not just a domain landlord.

A few weeks later, boom - domain transferred and I started building what you see today.

The Superpower of Just Doing Stuff

This whole experience crystallized something I've been thinking about: doers beat thinkers every single time.

While I was sending emails and booking flights, others were probably:

Researching "domain acquisition best practices"
Building 47-slide pitch decks
Running analysis paralysis marathons

Sometimes the "impossible" thing just needs an email, a phone call, a flight, and an honest conversation. The mechanics are simpler than the outcome suggests.

Your Turn to Ship Something Wild

Look, if you've got an idea rattling around in your head, stop overthinking it. There are probably way fewer blockers than your brain is telling you.

That side project you've been "planning"? That domain you think is "too expensive"? That person you think is "too important" to email?

Less planning. More doing. More shipping.

The worst thing that happens? Someone says no. The best thing? You end up with patron.com and a platform to build.

What are you going to ship this week? 👀

Currently building Patron - the creator platform I actually want to use. Follow the journey and maybe we'll change how serialized creators get paid.

Why VPS Rocks for Quick Deployments: My Story + Build an LLM-over-DNS agent in Under 30 Mins!

Nick K — Wed, 13 Aug 2025 16:40:04 +0000

My most valuable skill as a hacker/entrepreneur? Being confident enough to deploy random stuff that works on my laptop to the actual internet. Sounds simple, but this superpower literally got me into Y-Combinator and helped me raise a seed round!

The Struggle Bus Was Real 🚌

Picture this: teenage me, fresh off a Christmas Raspberry Pi gift, building my very first "real" project. A Twitter weather bot that would read from the API firehose and reply with weather conditions when you @'ed it. I followed a tutorial, got it working locally, and then... complete brain freeze on deployment.

Obviously I should just use my Pi as a server, right? WRONG. My code had more bugs than a summer camping trip, crashing whenever I wasn't around to babysit it. Then I couldn't even SSH back in because our house didn't have a static IP (and Tailscale wasn't a thing yet). It was like having a pet that only worked when you were home 😅

Welcome to PaaS Hell 🔥

Fast forward to building web apps in college. Somehow I completely skipped VPS and went straight to Platform as a Service hell. I'd Google "how do I deploy my create react app" and the top answer was always some third-party service with build steps, managed SSL, and enough complexity to make my head spin.

There was ALWAYS some weird limitation:

Memory constraints during build ✋
Puppeteer couldn't run because missing apt packages 📦
Stuck configuring Docker images (pre-AI era, so no ChatGPT to save me) 🐳

I spent more time fighting deployment than actually building my janky React apps. Not a good look!

My VPS Salvation 🙏

During college I got lucky and met this hacky startup entrepreneur who was hiring. The whole operation seemed barely legitimate, but I took the leap anyway.

Going in, I assumed the "proper" way to deploy was AWS or some other hyperscaler. But this guy? Total VPS maximalist with the most beautifully simple philosophy I'd ever encountered:

Rent a VPS, SSH in, do the same thing you did locally (yarn dev or whatever), throw up a reverse proxy, call it a day.

Watching him deploy like this over and over was like seeing magic. Everything was small, learnable, and confidence-building. That nagging voice in my head saying "I can't build this because I won't be able to deploy it" just... disappeared.

Paying It Forward ⚡

I've become a total evangelist for this approach, but never knew how to write about it entertainingly. Then I saw levelsio's tweet about deploying a DNS server that lets you talk to an LLM, and I knew I had my hook!

Want to see it in action? Try this magic:

dig @llm.skeptrune.com "what is the meaning of life?" TXT +short

Pretty wild, right? Let's build our own in less than 30 minutes with nothing but a rented server!

The Build: LLM-over-DNS in 30 Minutes ⏰

Step 1: Get Into Your VPS 🔑

After purchasing your VPS (I love Hetzner, but any provider works), you'll get an IP and login creds via email:

ssh root@<your-vps-ip>

Step 2: Clear the DNS Decks 🧹

Most VPS images come with DNS stuff pre-installed. Let's clean house:

# Check what's running
systemctl list-units --type=service | grep -E 'bind|dns|systemd-resolved'

# Stop the usual suspects
systemctl stop systemd-resolved
systemctl disable systemd-resolved

# Bye bye bind9
apt-get remove --purge bind9 -y

Step 3: Install Our Tools 🛠️

Just need a couple Python packages:

pip install dnslib requests

Step 4: The Magic Script ✨

Here's where the fun happens. Create a Python script that listens for DNS queries, treats them as prompts, hits the OpenRouter API, and returns the response as a TXT record:

from dnslib.server import DNSServer, BaseResolver
from dnslib import RR, QTYPE, TXT
import requests
import codecs

OPENROUTER_API_KEY = ""  # Add your OpenRouter API key here
LLM_API_URL = "https://openrouter.ai/api/v1/chat/completions"

class LLMResolver(BaseResolver):
    def resolve(self, request, handler):
        qname = request.q.qname
        qtype = QTYPE[request.q.qtype]
        prompt = str(qname).rstrip('.')

        # Forward prompt to LLM
        try:
            response = requests.post(
                LLM_API_URL,
                headers={
                    "Authorization": f"Bearer {OPENROUTER_API_KEY}",
                    "Content-Type": "application/json"
                },
                json={
                    "model": "openai/gpt-3.5-turbo",
                    "messages": [{"role": "user", "content": prompt}]
                },
                timeout=10
            )
            response.raise_for_status()
            raw_answer = response.json()["choices"][0]["message"]["content"]
        except Exception as e:
            raw_answer = f"Error: {str(e)}"

        try:
            answer = codecs.decode(raw_answer.encode('utf-8'), 'unicode_escape')
        except Exception:
            answer = raw_answer.replace('\\010', '\n').replace('\\n', '\n')

        reply = request.reply()
        if qtype == "TXT":
            # Split long responses into chunks (DNS has limits!)
            chunk_size = 200
            if len(answer) > chunk_size:
                chunks = [answer[i:i+chunk_size] for i in range(0, len(answer), chunk_size)]
                for i, chunk in enumerate(chunks):
                    reply.add_answer(RR(qname, QTYPE.TXT, rdata=TXT(f"[{i+1}/{len(chunks)}] {chunk}")))
            else:
                reply.add_answer(RR(qname, QTYPE.TXT, rdata=TXT(answer)))
        return reply

if __name__ == "__main__":
    resolver = LLMResolver()
    server = DNSServer(resolver, port=53, address="0.0.0.0")
    server.start_thread()
    import time
    while True:
        time.sleep(1)

Save this as llm_dns.py. Don't forget to grab an OpenRouter API key and paste it in!

Quick Note: This is totally a proof-of-concept. For real production stuff, you'd want proper process management, logging, rate limiting, and definitely not storing API keys in plaintext 😬

Step 5: Fire It Up! 🔥

Start your DNS-LLM hybrid (needs root for port 53):

sudo python3 llm_dns.py

Step 6: Test Your Creation 🧪

From another machine, send a DNS query and watch the magic:

dig @<your-vps-ip> "what is the meaning of life" TXT +short

You should see the LLM's response come back through DNS. How cool is that?!

When Things Go Wrong 🚨

Common hiccups:

Permission denied: Remember that sudo for port 53!
Connection timeout: Check your firewall settings
API errors: Double-check that OpenRouter key
No response: Make sure systemd-resolved is actually disabled

Lock It Down (Optional but Smart) 🔒

Want to add some basic security? UFW to the rescue:

ufw allow ssh
ufw allow 53
ufw enable

This keeps SSH open (don't lock yourself out!) and allows DNS queries while blocking everything else.

The VPS Philosophy 🎯

This whole exercise demonstrates why I'm such a VPS evangelist. No complex infrastructure, no weird platform limitations, no mysterious build failures. Just:

SSH into a server
Install what you need
Run your code
It works!

That's it. That's the tweet.

Sure, you might need more sophisticated setups for massive scale, but for 99% of side projects and early-stage startups? VPS all the way. The confidence boost alone is worth it.

Resources 📚

Now go forth and deploy weird stuff to the internet! Your future entrepreneurial self will thank you 🚀

What's the weirdest thing you've deployed to a VPS? Drop it in the comments!

Debugging a mysterious HTTP streaming issue

Nick K — Tue, 05 Aug 2025 17:52:40 +0000

We recently encountered a frustrating issue with HTTP response streaming at Mintlify. Our system uses the AI SDK with the Node stream API to forward streams, and suddenly things stopped working properly. The symptoms were confusing: streaming worked perfectly with cURL and Postman, but failed completely with node-fetch and browser fetch.

Initial Investigation

Our first hypothesis centered around stream compatibility issues. We suspected the problem might be related to how the AI SDK responds using web streams versus Node streams, particularly around HTTP/2 compliance. Web streams have known issues with HTTP/2, while Node streams are compliant.

The Cloudflare Worker Bandaid

While investigating, we discovered an odd workaround. We set up a Cloudflare worker as middleware between our server and clients:

// Cloudflare Worker that acts as a CORS-enabled streaming proxy
export default {
  async fetch(request, env, ctx) {
    // Handle preflight CORS requests
    // ....

    // Extract request body for non-GET requests
    const body = ["GET", "HEAD"].includes(request.method) ? null : request.body;

    // Create headers that mimic a real browser request
    // ....

    // Forward the request to the target URL
    const response = await fetch(request.url, {
      method: request.method,
      headers: proxyHeaders,
      body: body,
    });

    // Copy response headers and enable CORS
    const responseHeaders = new Headers(response.headers);
    responseHeaders.set("Access-Control-Allow-Origin", "*");

    // Create streaming response to handle large payloads
    const { readable, writable } = new TransformStream();
    response.body?.pipeTo(writable);

    return new Response(readable, {
      status: response.status,
      statusText: response.statusText,
      headers: responseHeaders,
    });
  },
};

This worker simply received the stream and responded with it. Somehow, this completely fixed the issue, which made no sense to us at the time.

Ruling Out HTTP Versions

We quickly invalidated our HTTP/1 vs HTTP/2 suspicion by using cURL with the --http1.1 flag. Even when making HTTP/1 requests, things streamed properly. Throughout the entire debugging process, cURL consistently worked as expected.

Header Stripping Suspicions

One thing that stuck out was that our egress systems (ALB and Cloudflare) were stripping these headers:

'Transfer-Encoding': 'chunked',
'Connection': 'keep-alive',
'Content-Encoding': 'none',

Since browsers frequently have issues with these headers, and given that Postman and cURL worked while node-fetch and browser fetch didn't, we thought this might be the culprit.

Learning About Dynamic Responses

During this investigation, I learned more about "dynamic" responses and HTTP streaming in general. We explored whether an egress proxy was buffering the entire response to assign a content-length header, but that wasn't happening. It was valuable to develop better intuition around what HTTP streaming actually means.

The Breakthrough

After about 3 hours of making no progress, only Lucas made any headway. His previous Cloudflare experience gave him the intuition that a worker might fix the issue, which led to our temporary solution.

We implemented the patch fix and went to lunch, but had to deal with another issue: changing the IP to the Cloudflare worker triggered our IP-based rate limiter. After fixing that, we called it a day around 8pm.

Later that night, Lucas had an epiphany. Thinking about why cURL worked but fetch didn't, he consulted Claude about the differences between these tools. Claude walked him through a crucial insight: when Lucas examined the request headers, he noticed that cURL wasn't sending an Accept-Encoding header by default, while browsers always do. This missing header was the red flag that led Claude to explain that "cURL doesn't allow compressed responses without the --compressed flag."

As Claude pointed out, this behavior difference is key:

Browser requests include Accept-Encoding: gzip, deflate, br by default
cURL requests omit Accept-Encoding unless you use the --compressed flag
Without the Accept-Encoding header, servers won't compress the response

Bingo. The problem was compression.

The Solution

Lucas went into the Cloudflare dashboard, disabled compression, and everything worked perfectly. A simple solution to what had been a very annoying problem causing 10+ second latency on requests.

The Embarrassing Realization: A Familiar Problem in Disguise

This was embarrassingly familiar. Denzell and I had actually dealt with this exact issue before at Trieve, fixing it in PR #2002: remove compression for chat routes. The reason we didn't immediately recognize it was what I call "magic obfuscation" - when you've fixed something before but the context makes it unrecognizable.

In fact, Mayank, another team member at Mintlify who worked with Trieve from the customer side, had discovered a similar streaming issue with this message:

hey folks! were there any changes to the message apis yesterday? streaming doesn't seem to be working as intended. maybe github.com/devflowinc/trieve/pull/1999/files?

The key difference was visibility. Since Trieve is source available, Mayank could look at recent commits and quickly identify the issue. In our current Mintlify case, we had no such visibility into what changed, which made the debugging process exponentially more difficult.

When Cloudflare's Magic Becomes a Nightmare

The strangest part is that streaming worked correctly one day and stopped working the next, without any changes on our end. ALB configuration stayed the same, Cloudflare wasn't touched, and none of our code changed. Somehow, Cloudflare had silently enabled compression, and we have no idea why.

This highlights a fundamental issue with Cloudflare's approach to infrastructure management. While their "intelligent" defaults and automatic optimizations can be helpful for simple use cases, they create serious problems for production systems that require predictable behavior. The fact that a critical setting like compression can change without explicit configuration updates makes debugging nearly impossible.

In a properly designed infrastructure-as-code environment, this issue would have been immediately obvious. A git diff would show exactly when compression was enabled, by whom, and why. Instead, we spent hours chasing ghosts because Cloudflare's dashboard-driven configuration model obscures the audit trail of changes.

This isn't just about compression—it's about the broader pattern of "helpful" automation that removes visibility and control from engineering teams. When debugging production issues, the last thing you want is uncertainty about whether your infrastructure configuration matches what you deployed.

Lessons Learned

Compression breaks HTTP streaming - This is now permanently etched in my brain
cURL vs fetch behavior differences - cURL doesn't allow compressed responses without --compressed flag
Cloudflare workers as debugging tools - Sometimes adding middleware can help isolate problems
Source availability matters - Having access to change logs makes debugging much easier
Team knowledge sharing - Lucas's Cloudflare experience was crucial to finding both the workaround and the real solution

If I'm ever on a team using Cloudflare again, we'll make sure compression is disabled for any HTTP streaming endpoints from day one.

The Bug That Drove Me So Crazy, I Got Hired Just to Fix It

Nick K — Thu, 31 Jul 2025 07:07:23 +0000

The Itch I Couldn't Scratch

Picture this: You're searching through documentation, typing away, and the search results keep flickering between what you typed three characters ago and what you're typing now. It's like having a conversation with someone who's perpetually three seconds behind.

That was my daily reality with Mintlify for over two years.

For context, Mintlify provides hosted documentation sites for developers (think GitBook, but cooler). They acquired my previous company, Trieve, which ironically provided the search infrastructure powering their 30,000+ documentation sites. So not only was I a frustrated user, I was the guy whose search technology was being... let's say "suboptimally implemented."

The problem? They weren't aborting debounced search queries. Every keystroke fired off a new search request, but old requests kept coming back, creating a chaotic race condition that made search feel sluggish and unreliable.

Look at this madness:

I'd mentioned this bug in our shared Slack channels when I was still just a vendor. "Hey, you know your search has this race condition issue?" I'd say, trying to be helpful without being that guy who points out problems in your customer's product.

But it wasn't a priority. Fair enough—there were bigger fish to fry, more critical features to ship, actual revenue-impacting work to do. A slightly janky search experience doesn't tank your business, even if it slowly chips away at your soul every time you use it.

The frustration was real though. I'd built search infrastructure for a living, and watching my own technology get hobbled by a simple frontend oversight was like watching someone use a Ferrari to deliver pizza... in first gear... with the parking brake on.

Sweet, Sweet Revenge (aka The Fix)

Fast forward to post-acquisition: I'm officially on the team, I have access to the codebase, and guess what the very first thing I fixed was?

You got it. That damn search race condition.

The solution? A simple AbortController. When a new search query starts, abort the previous one. Revolutionary stuff, I know. The search results now actually correspond to what you're currently typing instead of playing catch-up with your keystrokes.

This reminded me of when George Hotz joined Twitter for a hot minute after the Elon acquisition, fixed the annoying login popup, then promptly left. Sometimes you just need to scratch that itch yourself.

The Open Source Fantasy

Here's the thing that really gets me: If Mintlify had been open source during those two torturous years, I could have just submitted a PR. One AbortController, maybe 10 lines of code, and boom—problem solved for everyone.

Instead, this tiny annoyance festered across thousands of documentation sites, slowly grinding away at user experience like digital water torture. Not because it was technically challenging to fix, but because it wasn't accessible to the person who cared enough to fix it.

Don't get me wrong—I understand why companies choose proprietary models. There are valid business reasons. But there's something beautifully empowering about open source: when something bothers you, you can actually do something about it instead of just complaining into the void.

The Little Things That Matter

If Mintlify's search feels just a bit snappier now, just a little more responsive when you type—that's me. I fixed the bug that had been haunting my search experience for over two years, and it feels absolutely fantastic.

But here's the bigger picture: This is how legendary products are built.

Not through grand gestures or revolutionary features, but through obsessing over the tiny details that most people would ignore. The 10-millisecond improvements. The edge cases that only affect 0.1% of users. The barely noticeable refinements that somehow make everything feel just a little bit better.

There's something deeply satisfying about finally having the power to fix the things that annoy you. Even if they're microscopic.

Especially if they're microscopic.

Because at the end of the day, user experience isn't built in boardrooms or design sprints. It's built one tiny frustration at a time, one small fix at a time, one AbortController at a time.

And sometimes, the motivation to fix those tiny things is so strong, you'll literally get hired just to do it.

From side project idea to Hacker News front page: A 7,112 user retrospective

Nick K — Mon, 14 Jul 2025 08:16:46 +0000

I was burnt out from my startup and wanted to recover some of my creative energy, so I decided to build a fun side project called Jukebox.

I had the idea of building a collaborative playlist app where you could queue music together with friends and family.

I launched it on Hacker News, where it hit frontpage and got a lot of traction. In total, it had 7112 visitors who played 2877 songs.

Hacker News users are known for their eclectic tastes, so I was curious to see what kind of music they listened to. I did some data analysis on the usage patterns and music genres, and I wanted to share my findings.

People Actually Used It!

Part of the fun of side projects is that you can use them as an opportunity to build your skills. Personally, one of the core skills I want to improve is marketing.

Therefore, it was important to me that I actually drove traffic to the app and got people to use it. I'm happy to report that I was able to do that! Here's a full breakdown of the user engagement:

The data is reliable because each visitor to the site is assigned an anonymous user account. This allows for accurate tracking of how many unique users visited, how many created a "box" (playlist), and how many engaged with the main features.

Conversion rate into the primary "Create Box" CTA was awesome! However, I was sorely dissapointed to see that only 6.7% of people who created a box actually used the app to queue music together, which was the main reason why I built the app in the first place.

I'd call it a pyhrrhic victory. My product sense was a few rings off the bullseye, but still on the target. I'm not going to continue working on Jukebox, but it certainly fulfilled its core purpose of helping me recover my creative energy and learn some new skills.

What Music Did They Listen To?

I was originally planning to talk more about how Jukebox was built, but I think the more interesting part is the data analysis of what music Hacker News users listened to.

Genres

Spotify is generous with their API, so I was able to hydrate the songs data with genres by using their data.

Hacker News users actually disappointed me with their music tastes. I expected them to be more eclectic, but classic rock and rock were 2 times more popular than any other genre.

New wave, metal, and rap followed as the next most played genres, but there was a steep drop-off after the top three. The long tail of genres included everything from country and EDM to post-hardcore and progressive rock, but these were much less represented.

One thing that surprised me was how country music edged out electronic genres in popularity. I expected a tech-focused audience to gravitate more towards electronic or EDM, but country had a stronger showing among the top genres. It’s a reminder that musical preferences can defy stereotypes, even in communities you’d expect to lean a certain way.

Artists

When it comes to artists, the results were a mix of the expected and the surprising. Michael Jackson topped the list as the most played artist—proving that the King of Pop’s appeal truly spans generations and communities, even among techies. Queen and Key Glock followed closely, showing that both classic rock and modern hip-hop have their place in the hearts (and playlists) of Hacker News users.

I was surprised to see a strong showing from artists like Taylor Swift and Depeche Mode, as well as a healthy mix of rap, electronic, and indie acts. The diversity drops off after the top few, but there’s still a wide spread: from Daft Punk to Nirvana, Dua Lipa to ABBA, and even some more niche names like Wolf Parade and Day Wave.

Overall, while classic rock and pop dominate, there’s a clear undercurrent of variety—perhaps reflecting the broad interests of the Hacker News crowd, even if their musical tastes lean a bit more mainstream than I expected.

AI Makes Me More Willing to Build Things

Dens Sumesh, a former intern at my company, originally had the idea for Jukebox and told me about it at dinner one day. I thought it was a great and had potential, so I decided to build it. AI codegen has made me drastically more willing to build things on a whim.

Typically I would have probably quit after finishing the backend, because React slop is not my favorite thing to work on. However, since the AI is good enough at React to do most of that work for me, I was mentally able to push through and finish the project.

Another side benefit of building this was that I got a better handle on when AI is an efficient tool versus when it’s better to rely on my own skills. For example, highlighting a component and prompting "use framer-motion to make this fade in buttery smooth" is a great use of AI.

However, more complex asks like "add an api route to accept a song, put it in a queue with sqlite, and create a worker that downloads and uploads them to s3, with a final api route to check when they finish" are more efficiently handled by a human with intuition and experience.

Framing things out manually, or even prompting the frame, consistently seemed to be a more efficient strategy than trying to get the AI to one-shot entire features. Both approaches can work, but breaking things down helps you maintain control and clarity over the process.

If you rely too much on one-shot prompts, you can end up in a cycle where your eyes glaze over and you're pressing the "regenerate" button like it's a Vegas slot machine. This slot machining makes launching less likely because you spend more time hoping for a perfect result rather than iterating and moving forward. It's easy to get stuck chasing the ideal output instead of shipping something real and learning from feedback.

Conclusion

Build stuff, share it, get feedback, and learn. Shots on goal lead to more opportunities for improvement and innovation.

Even though Jukebox is now going into maintenance mode, it was everything I hoped it would be: a fun side project that people actually used.

If you want the raw data, you can find it on the GitHub repository.

If you want to see the source code for Jukebox, that's on Github at skeptrunedev/jukebox.

How to Build Agentic RAG for any PDF in 10 minutes

Nick K — Mon, 16 Jun 2025 07:06:37 +0000

Introduction

Retrieval Augmented Generation (RAG) has revolutionized how we build AI applications, allowing Large Language Models (LLMs) to answer questions based on custom data. But what if the LLM could decide when and how to search that data, like a smart assistant? That's where Agentic RAG comes in.

With Trieve, you can easily set up an agentic RAG pipeline that leverages advanced OCR for PDFs (via Chunkr) and gives your LLM the autonomy to intelligently query your knowledge base.

If you're not interested in the guide and just want to see the code in order to give it to your agent as a starting point, you can find a fully complete CLI demonstrating this functionality in a single file on github at github.com/devflowinc/trieve/blob/main/clients/cli/index.ts or install it via npm i -g trieve-cli.

Here's a short video where I break down how agentic RAG performs against Gemini with the entire file in the context window along with naive RAG (no agentic search) for the 2025 CrossFit Games Rulebook. Credit to canonical ai's original post.

Step 1: Sign Up for Trieve and Set Up Your Dataset

If you haven't already, sign up for a Trieve account at dashboard.trieve.ai. Once logged in, create a new dataset and upload your PDFs. Trieve will automatically process them using Chunkr, extracting text and metadata for efficient searching.

Prerequisites:

A Trieve account (sign up at dashboard.trieve.ai)
Copy your Trieve API_KEY, DATASET_ID, and ORGANIZATION_ID from the dashboard.
Node.js and npm/yarn installed.

Step 2: Initialize Your Node.js Project and Trieve Client

Create a new Node.js script (e.g., agentic-rag.js) and set up your Trieve client:

import fs from "fs";
import { TrieveSDK, UpdateDatasetReqPayload } from "trieve-ts-sdk";

// ---- Configuration ----
// Replace with your actual credentials
const TRIEVE_API_KEY = process.env.TRIEVE_API_KEY || "YOUR_TRIEVE_API_KEY";
const TRIEVE_DATASET_ID =
  process.env.TRIEVE_DATASET_ID || "YOUR_TRIEVE_DATASET_ID";
const TRIEVE_ORGANIZATION_ID =
  process.env.TRIEVE_ORGANIZATION_ID || "YOUR_TRIEVE_ORGANIZATION_ID";

if (
  TRIEVE_API_KEY === "YOUR_TRIEVE_API_KEY" ||
  TRIEVE_DATASET_ID === "YOUR_TRIEVE_DATASET_ID" ||
  TRIEVE_ORGANIZATION_ID === "YOUR_TRIEVE_ORGANIZATION_ID"
) {
  console.error(
    "Please set your TRIEVE_API_KEY, TRIEVE_DATASET_ID, and TRIEVE_ORGANIZATION_ID in the script or as environment variables.",
  );
  process.exit(1);
}

const trieveClient = new TrieveSDK({
  apiKey: TRIEVE_API_KEY,
  datasetId: TRIEVE_DATASET_ID,
  organizationId: TRIEVE_ORGANIZATION_ID, // Required for dataset updates
});

console.log("Trieve SDK initialized.");

Step 3: Configure Your Agent's Search Tool

For an LLM to act as an agent, it needs clear instructions on when and how to use its tools (in this case, searching your Trieve dataset). We configure this at the dataset level.

System Prompt (SYSTEM_PROMPT): This is the overarching instruction for the LLM. It should emphasize relying on the search tool.
Tool Description (tool_description): This tells the LLM when it should use the search tool. For robust RAG, you often want it to always use the tool.
Query Parameter Description (query_parameter_description): This guides the LLM on how to formulate its search queries effectively.

Tips and Tricks for Descriptions:

Be Explicit: Don't assume the LLM knows. Tell it directly, e.g., "ALWAYS call this search tool for EVERY user question."
Emphasize Data Freshness: Remind the LLM that its internal knowledge might be outdated and the search tool provides current information from your documents.
Encourage Specificity in Queries: Guide the LLM to extract keywords and form precise queries. Suggest trying multiple queries if the first attempt isn't fruitful.
Iterate: These descriptions are powerful. Experiment with different phrasings to see what works best for your use case.

Here's how to update your dataset configuration using the SDK:

async function configureSearchTool() {
  console.log("🔧 Configuring dataset for agentic search...");
  try {
    const updatePayload: UpdateDatasetReqPayload = {
      dataset_id: TRIEVE_DATASET_ID, // Ensure this is the correct dataset ID
      server_configuration: {
        SYSTEM_PROMPT: "You are an AI assistant that helps people find information in a set of documents. You have access to a search tool that can retrieve relevant information from the documents based on a query. YOU MUST ALWAYS CALL AND USE THE SEARCH TOOL FOR EVERY USER QUESTION WITHOUT EXCEPTION. Do not rely on your own knowledge - it may be outdated or incorrect. For each user question: 1) Use the search tool with a well-crafted query 2) If the first search doesn't yield satisfactory results, try additional searches with different terms 3) Only after searching should you formulate your response, citing the information found. Always inform the user that your answer is based on search results from their documents. If you don't find relevant information after multiple searches, be honest about this limitation.",
        TOOL_CONFIGURATION: {
          query_tool_options: {
            tool_description: "ALWAYS use the search tool for EVERY user question, even if you think you already know the answer. Your knowledge is limited and potentially outdated - you must rely on the provided search tool to get the most accurate and up-to-date information.",
            query_parameter_description: "Write a specific query with critical keywords from the user question. Use multiple search queries with different terms if needed to get comprehensive results.",
            // You can also define descriptions for other filters if you plan to use them agentically
            // price_filter_description: "The page range filter to use for the search",
            // max_price_option_description: "The maximum page to filter by",
            // min_price_option_description: "The minimum page to filter by",
          },
        },
      },
    };

    await trieveClient.updateDataset(updatePayload);
    console.log("✅ Dataset configuration updated successfully!");
  } catch (error) {
    console.error("❌ Failed to update dataset configuration:", error instanceof Error ? error.message : error);
  }
}

Step 4: Upload and Chunk Your PDF with Chunkr

Chunkr is Trieve's advanced file processing service. When you upload a file (like a PDF) with the chunkr_create_task_req_payload field, Chunkr uses sophisticated OCR technology that excels at understanding document layouts, tables, and images. This results in higher-quality chunks for your RAG pipeline.

Request Explanation:

base64_file: The file content, base64 encoded.
file_name: The original name of the file.
group_tracking_id (Optional but Recommended): A unique ID you can use to later check the status of the file processing and group related chunks. If not provided, Trieve might generate one.
chunkr_create_task_req_payload: {}: This empty object is the key! It signals Trieve to process this file using Chunkr for advanced chunking. You can pass specific Chunkr options here if needed, but an empty object uses sensible defaults.

async function uploadPdfWithChunkr(filePath: string, trackingId?: string) {
  console.log(`📤 Uploading PDF: ${filePath} with Chunkr...`);
  try {
    const fileBuffer = fs.readFileSync(filePath);
    const base64File = fileBuffer.toString('base64');
    const fileName = filePath.split('/').pop() || filePath;

    const generatedTrackingId = trackingId || `chunkr-doc-${fileName}-${Date.now()}`;

    const response = await trieveClient.uploadFile({
      base64_file: base64File,
      file_name: fileName,
      group_tracking_id: generatedTrackingId,
      chunkr_create_task_req_payload: {}, // This enables Chunkr processing!
    });

    console.log("📄 File upload initiated. Response:", response);
    console.log(`✨ File sent to Chunkr for processing. Tracking ID: ${generatedTrackingId}`);
    console.log("⏳ You can check processing status using this tracking ID with other Trieve endpoints.");
    return generatedTrackingId; // Return for potential status checking
  } catch (error) {
    console.error("❌ PDF upload failed:", error instanceof Error ? error.message : error);
  }
}

Note: File processing with Chunkr is asynchronous. The uploadFile endpoint returns quickly, but the actual chunking happens in the background. You'd typically use the group_tracking_id to poll for completion status if needed, though for this example, we'll assume it completes.

Step 4: Asking Agentic Questions

Now for the magic! To ask an agentic question:

Create a Topic: Topics are like conversation threads. Each agentic interaction typically happens within a topic.
Create a Message Reader: When creating a message within a topic, set:
- use_agentic_search: true: This tells Trieve to use the agentic flow defined by your dataset's tool configuration.
- model: Specify an LLM capable of agentic behavior. Trieve offers models like o3 (Claude 3 Opus), c3.5s (Claude 3.5 Sonnet), gpro (GPT-4o), gpt4t (GPT-4 Turbo) which are well-suited for this. Check Trieve documentation for the latest list of supported models. o3 is a powerful option.

The response will be streamed back, often including "thinking" steps from the agent before the final answer.

import { TrieveSDK, ChunkMetadata, Topic } from 'trieve-ts-sdk';
import chalk from 'chalk'; // Optional: for styled console output

// Assume trieveClient is already initialized and configured globally for this script
// const trieveClient = new TrieveSDK({ ... });

async function askAgenticQuestion(
  question: string,
  existingTopicId?: string,
  userId: string = 'default-blog-user-' + Date.now() // Example user ID
): Promise<{ actualAnswer: string; parsedChunks: ChunkMetadata[]; topicId: string } | undefined> {
  console.log(chalk.blue(`🤔 Asking agentic question: "${question}"`));
  try {
    let topicIdToUse = existingTopicId;

    if (!topicIdToUse) {
      const topicName = question.substring(0, 50) + "..."; // Simple topic name
      console.log(chalk.magenta(`📝 Creating new topic: "${topicName}" for user "${userId}"`));
      // Ensure Topic type is correctly imported if using createTopic's return type explicitly
      const topicData: Topic = await trieveClient.createTopic({
        name: topicName,
        owner_id: userId,
      });
      topicIdToUse = topicData.id;
      console.log(chalk.magenta(`🏷️ Topic created with ID: ${topicIdToUse}`));
    }

    // This check is good practice, though topicIdToUse should be set if creation was successful
    if (!topicIdToUse) {
        console.error(chalk.red("❌ Critical error: Topic ID could not be established."));
        return undefined;
    }

    const { reader } = await trieveClient.createMessageReaderWithQueryId({
      topic_id: topicIdToUse,
      new_message_content: question,
      use_agentic_search: true, // Crucial for agentic behavior
      model: "o3", // Or "c3.5s", "gpro", "gpt4t". Using a powerful model is recommended.
                    // "o3" refers to Claude 3 Opus in Trieve's context.
    });

    console.log(chalk.cyan("💬 Streaming response from agent:"));
    process.stdout.write(chalk.bold("🤖 Agent: ")); // Start the agent's response line

    const decoder = new TextDecoder();
    let actualAnswer: string = '';
    let parsedChunks: ChunkMetadata[] = [];
    let chunkDataAccumulator: string = ''; // Accumulates parts of the stream that might form chunk JSON
    let isParsingChunks: boolean = false;   // Flag: actively accumulating/expecting chunk JSON
    let isThinkingSection: boolean = false; // Flag: agent is sending "thinking" status messages

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      const streamChunkText = decoder.decode(value);

      // 1. Handle "thinking" or status messages from the agent stream
      if (streamChunkText.includes('🤔') || streamChunkText.includes('📝') || streamChunkText.includes('✅') || streamChunkText.includes('🔍')) {
        isThinkingSection = true; // We are in a special status update from the agent
        process.stdout.write(chalk.yellow(streamChunkText)); // Print thinking messages
        continue; // Process next part of the stream
      } else {
        // If we were in a thinking section and now receive a non-thinking chunk, reset the flag.
        // This ensures subsequent text is treated as part of the answer or chunk data.
        isThinkingSection = false;
      }

      // 2. Detect the start of the chunk JSON data section (inspired by CLI's logic)
      // Assumes chunk data starts with '[{'
      if (streamChunkText.includes('[{') && !isParsingChunks) {
        isParsingChunks = true;
        chunkDataAccumulator = ''; // Reset accumulator for this new potential JSON block
      }

      // 3. Accumulate and parse chunk JSON data
      if (isParsingChunks) {
        chunkDataAccumulator += streamChunkText;

        // Check for the delimiter "||" which, by CLI convention, separates chunk JSON from the main answer
        if (chunkDataAccumulator.includes('||')) {
          isParsingChunks = false; // We've likely received the full chunk JSON block
          const parts = chunkDataAccumulator.split('||');
          const jsonDataPart = parts[0].trim();

          if (jsonDataPart) {
            try {
              // The CLI expects the stream to format chunks as: [{ "chunk": ChunkMetadata }, ...]
              const rawChunkObjects: { chunk: ChunkMetadata }[] = JSON.parse(jsonDataPart);
              if (Array.isArray(rawChunkObjects)) {
                parsedChunks = rawChunkObjects.map(item => item.chunk);
                // Optional: Log that chunks were found during streaming
                process.stdout.write(chalk.dim(`\n[ℹ️ System: Extracted ${parsedChunks.length} reference chunks.]\n`));
                process.stdout.write(chalk.bold("🤖 Agent: ")); // Re-prompt for agent answer part
              }
            } catch (e) {
              process.stdout.write(chalk.yellow('\n⚠️ Warning: Could not parse chunk JSON. Content (partial): ' + jsonDataPart.substring(0, 100) + "...\n"));
              // If parsing fails, it might be an error or unexpected format.
              // The CLI logs an error. Consider if this data should be part of `actualAnswer`.
              // For now, mirroring CLI's behavior of just warning.
            }
          }

          // The part after "||" is considered the start of the textual answer from the LLM
          if (parts[1]) {
            const answerInitialPart = parts[1];
            actualAnswer += answerInitialPart;
            process.stdout.write(answerInitialPart);
          }
          chunkDataAccumulator = ''; // Clear the accumulator
        }
        // If "||" is not yet found, `chunkDataAccumulator` continues to build in next iteration.
      } else if (!isThinkingSection) {
        // 4. Accumulate the actual textual answer from the LLM
        // This runs if a) not parsing chunks, and b) not in a "thinking" message from the agent
        actualAnswer += streamChunkText;
        process.stdout.write(streamChunkText);
      }
    }

    reader.releaseLock();
    process.stdout.write('\n'); // Ensure a new line after the full streamed response

    console.log(chalk.green('\n✅ Agentic response complete.'));

    // Optional: Summarize found chunks after the stream
    if (parsedChunks.length > 0) {
        console.log(chalk.blueBright(`\n📚 Summary of ${parsedChunks.length} references found:`));
        parsedChunks.forEach((chunk, index) => {
            console.log(
                chalk.grey(`  Ref ${index + 1}: ID (${chunk.tracking_id || chunk.id.substring(0,8)}) `) +
                (chunk.link ? chalk.cyan(`Link: ${chunk.link} `) : '') +
                (chunk.metadata ? chalk.magenta(`File: ${chunk.metadata.file_name || 'N/A'}`) : '')
            );
        });
    } else {
        console.log(chalk.yellow('⚠️ No reference chunks were explicitly parsed from this stream via "||" delimiter.'));
    }

    return { actualAnswer, parsedChunks, topicId: topicIdToUse };

  } catch (error) {
    console.error(chalk.red('❌ Failed to process agentic question:'), error instanceof Error ? error.message : error);
    return undefined;
  }
}

Putting It All Together

Let's create a simple main function to run these steps. Make sure you have a PDF file (e.g., sample.pdf) in the same directory or provide a full path.

async function main() {
  // Step 1: Configure the dataset's search tool (run once or when you want to update)
  await configureSearchTool();

  // Step 2: Upload a PDF using Chunkr
  // Replace 'sample.pdf' with the path to your PDF file
  const pdfFilePath = "sample.pdf";
  if (!fs.existsSync(pdfFilePath)) {
    console.error(
      `Error: PDF file not found at ${pdfFilePath}. Please create a sample.pdf or update the path.`,
    );
    return;
  }
  const trackingId = await uploadPdfWithChunkr(pdfFilePath);

  if (!trackingId) {
    console.error("File upload failed, cannot proceed to ask question.");
    return;
  }

  // Give some time for Chunkr to process (in a real app, you'd poll status)
  console.log(
    "\n⏳ Waiting 30 seconds for Chunkr to process the PDF (adjust as needed for larger files)...",
  );
  await new Promise((resolve) => setTimeout(resolve, 30000));

  // Step 3: Ask an agentic question related to the content of your PDF
  const question = "What are the main topics discussed in this document?"; // Change this to fit your PDF
  const result = await askAgenticQuestion(question);

  if (result) {
    console.log(`\n🗣️ You asked: "${question}"`);
    // The fullResponse might contain structured data depending on the stream.
    // For this example, we primarily focused on printing text as it came.
    // console.log(`\n📝 Agent's Full Streamed Response (may include intermediate steps):\n${result.fullResponse}`);
  }
}

main().catch(console.error);

To run this:

Save the combined code as agentic-rag.js.
Place a sample.pdf in the same directory or update pdfFilePath.
Set your environment variables or update the placeholders in the script.
Run node agentic-rag.js (if you're not using TypeScript directly, you might need ts-node agentic-rag.ts or compile it first).

Conclusion

You've just built a powerful Agentic RAG pipeline! By configuring your Trieve dataset's tool descriptions, leveraging Chunkr for superior PDF processing, and enabling agentic search, you've empowered an LLM to intelligently query your custom documents.

This is just the beginning. You can expand on this by:

Implementing robust status checking for file uploads.
Building a more sophisticated UI to handle streamed responses and citations.
Experimenting with different agentic models and prompt engineering for your tool descriptions.

Trieve makes complex AI tasks like Agentic RAG surprisingly accessible. Happy building!

Beyond the Hype: A Look at 5+ AI Coding Agents for Your Terminal

Nick K — Tue, 03 Jun 2025 18:46:06 +0000

If you're looking to supercharge your development workflow on the terminal, you've got options – lots of 'em. But which one's right for you? I've been tinkering with a bunch, and here's my take on some of the key players.

If you enjoy this post, give my project Uzi a star on GitHub – it's a CLI tool that helps you run multiple AI coding agents in parallel, making it easier to manage your coding tasks.

OpenAI Codex CLI & Anthropic's Claude Code

Alright, let's kick things off with the heavyweights. OpenAI and Anthropic, the multi-billion dollar giants, are throwing serious manpower and cash at these coding assistants. If you're not a hardcore terminal nerd and just want something that works and boosts your productivity ASAP, these are your first stop. OpenAI's gone open-source with Codex CLI, while Anthropic's keeping Claude Code under wraps. The community's been vibing more with Claude Code lately, but don't count Codex CLI out – that open-source muscle could mean big things as the community jumps in.

OpenAI Codex CLI (Open Source)

OpenAI's offering, Codex CLI, aims to bring their powerful reasoning models straight to your terminal. Being open source is a big plus here, opening the door for community contributions and transparency.

Key Functionality:

Zero‑setup installation: A quick npm install -g @openai/codex and you're off.
Multimodal inputs: Feed it text, screenshots, or diagrams.
Rich approvals workflow: Choose your level of hand-holding with Suggest, Auto Edit, or Full Auto modes.
Runs entirely in your terminal: No context switching needed for quick iterations.

Getting Started:

Install:
```
npm install -g @openai/codex
```
Authenticate:
```
export OPENAI_API_KEY="<OAI_KEY>"
```
Run:
```
codex "Explain this repo to me."
```

While it has the potential to be more powerful and cheaper than some alternatives, the developer experience has been a bit rough around the edges, with some users (myself included) noting issues with model selection, API key management, and occasional crashes. Still, its open-source nature means it's one to watch.

Anthropic's Claude Code (Closed Source)

On the other side, we have Claude Code from Anthropic. This one's proprietary, but it has garnered a lot of praise for its design and usability.

Key Strengths (from community observations and my experience):

Well-designed and intuitive CLI: It just feels good to use.
Automatic codebase understanding: Gets up to speed with your project quickly.
Project settings can be saved: Speeds up future sessions.
Active internal development: Suggests a commitment to quality and future improvements.
Handles complex requests well: Especially in larger codebases, it seems to shine.

It's not without its downsides; being closed-source is a factor for many, and it can get pricey. However, if you're looking for a polished experience and deep codebase understanding out-of-the-box, Claude Code is a strong contender. Many, including myself, have found it particularly effective for more complex tasks.

Plandex & Aider

Now, if you're the type who loves to tinker and really get under the hood, Plandex and Aider are where things get interesting. These tools are definitely more opinionated. They demand a bit more from you upfront – expect a steeper learning curve as you dive into their docs and unique command sets. But master them, and you'll unlock some serious power. Keep in mind, these came onto the scene before the giants fully flexed their muscles with Codex and Claude, so it'll be fascinating to see how they adapt. My bet? They'll carve out niches by getting super precise and targeted. Both are open source, which is great for customizability.

Plandex v2 (Open Source)

Plandex is designed for large tasks and real-world projects, offering a terminal-based AI development tool that can plan and execute multi-step coding endeavors.

Standout Features:

Smart context management: Claims a 2M token effective context window and handles large projects/files well.
Cumulative diff review sandbox: Keeps AI changes separate until you're ready.
Model combination: Mix and match models from Anthropic, OpenAI, Google, etc.
Configurable autonomy: From full auto to fine-grained control.
Automated debugging: For terminal commands and even browser applications (with Chrome).
Project-aware chat mode: Flesh out ideas before implementation.
Git integration: With commit message generation.

Installation:

curl -sL https://plandex.ai/install.sh | bash

(Note: Windows support is via WSL.)

Plandex offers different hosting options, including a cloud service and self-hosting. It emphasizes resilience in large projects and a robust workflow. If you're tackling complex, sprawling tasks, Plandex aims to be your heavy lifter.

Aider (Open Source)

Aider lets you pair program with LLMs directly in your terminal, focusing on seamless integration with your existing codebase and Git workflow.

Core Features:

Broad LLM support: Works well with Claude 3.7 Sonnet, DeepSeek, OpenAI models, and can connect to local models.
Codebase mapping (repomap): Helps it understand context in larger projects.
Multi-language support: Python, JavaScript, Rust, Go, and many more.
Git integration: Automatically commits changes with sensible messages.
IDE integration: Use aider --watch to have it react to comments in your code.
Image and web page input: Provide visual context.
Voice-to-code: Speak your requests.
Linting & testing: Can automatically lint, test, and fix issues.

Getting Started:

python -m pip install aider-install
aider-install

# cd /to/your/project
# Example with DeepSeek:
# aider --model deepseek --api-key deepseek=<key>

Aider has a strong focus on transparency and developer control, making it easy to see what the LLM is thinking and doing. Its repomap feature is a clever way to give the LLM better context. For those who like a tight feedback loop and clear insight into the AI's process, Aider is a compelling choice.

Opencode (Open Source)

Opencode is playing a different game, and honestly, it's one to watch. These folks might not have the VC backing of the big players, but they've got something equally valuable: serious social capital. We're talking big names on X like @adamdotdev and @thdxr championing this project. They're building Opencode with a clear vision – a high-quality tool for devs who live and breathe the terminal, think Arch Linux users and the like. This focus, combined with the community buzz, gives me a hunch they've got a real shot at long-term success. I'd put them as the dark horse with the second-best odds. It's also open source.

Key Aspects:

TUI Focus: Built with Bubble Tea for a slick terminal user interface.
Multi-Provider Support: Works with OpenAI, Anthropic Claude, Google Gemini, AWS Bedrock, Groq, Azure OpenAI, and OpenRouter.
Session Management: Save and manage conversation sessions.
Tool Integration: AI can execute commands, search files, and modify code.
Integrated Editor: Vim-like text input.
LSP Integration: For code intelligence.
File Change Tracking: Visualize changes during sessions.

Installation (one of many options):

curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash

Or via Homebrew:

brew install opencode-ai/tap/opencode

And for Arch users:

yay -S opencode-ai-bin

Opencode feels like it's built by terminal lovers, for terminal lovers. If you appreciate a well-crafted TUI and want a versatile tool that integrates deeply into a command-line workflow, keep a close eye on Opencode.

Uzi (Open Source)

So, after looking at all these individual agents, you might be wondering where the real leverage is. My gut tells me that trying to out-build OpenAI or Anthropic on their core agent tech is a bit like bringing a knife to a gunfight. They're just too big, too fast. That's why I think the next frontier isn't about building another agent, but about orchestrating the ones we've got. And that's exactly where Uzi comes in. We're building Uzi because, frankly, managing multiple AI agents, even the good ones, can be a massive pain. If you've ever tried to run several agents in parallel, as I detailed in my post on Git worktrees and AI, you know it's powerful, but clunky. Uzi is our open-source answer to that.

The core idea is to make parallelization easy. Why run one agent when you can run five, each tackling the problem in an isolated Git worktree, managed by Tmux? Uzi is a lightweight CLI that wraps this whole process.

What Uzi Does:

🤖 Runs multiple AI coding agents in parallel.
🌳 Manages Git worktrees automatically for isolated development.
🖥️ Handles Tmux session management for each agent.
🚀 Sets up development servers with automatic port management.
📊 Provides real-time monitoring of agent status.
🔄 Automates handling of agent prompts and confirmations.
🎯 Makes checkpointing and merging agent changes straightforward.

Prerequisites:

Git: For version control and worktrees.
Tmux: For terminal session management.
Go: For installing Uzi.
Your AI tool of choice: Claude, Codex CLI, Aider, etc.

Installation:

go install github.com/devflowinc/uzi@latest

Make sure $HOME/go/bin is in your PATH:

export PATH="$PATH:$HOME/go/bin"

Configuration (uzi.yaml):
Create this in your project root:

devCommand: yarn dev --port $PORT # Example for a Node.js project
portRange: 3000-3010

The devCommand is crucial – it should include all setup steps like npm install as each agent runs in a clean worktree.

Basic Workflow Example:

Start agents:

uzi prompt --agents claude:3,codex:2 "Implement a REST API for user management"

Automate confirmations:
```
uzi auto
```
Monitor:
```
uzi ls -w
```

Broadcast a follow-up:

uzi broadcast "Ensure all endpoints are documented"

Merge work:

uzi checkpoint <agent-name> "feat: add user management API"

I genuinely believe that the future of AI-assisted development lies in parallel execution and smart orchestration. Instead of betting on a single agent to nail it every time, Uzi lets you hedge your bets, increasing your chances of getting a great solution faster. It's about making the existing powerful agents even more effective by streamlining the meta-work around them.

The landscape of AI coding tools is evolving at lightning speed. Hopefully, this rundown gives you a better idea of what's out there and helps you pick the tools that best fit your style!

Web Developer's Guide to Midjourney

Nick K — Mon, 02 Jun 2025 07:11:03 +0000

Midjourney's learning curve is steep, but climbing it unlocks a superpower for developers and entrepreneurs. Learn how to create stunning, cohesive image sets that actually work for your projects. Go from building style reference galleries to using the describe feature for professional marketing visuals that don't scream "AI-generated.

Background and Motivation

I tried to use Midjourney unsuccessfully a few times before, but decided to give it one more try after reading a good tutorial thread on X by @kubadesign. His thread got me most of the way there, but I picked up an additional trick with Midjourney's describe feature that I think is worth sharing.

Results From My Recent Attempt

I initially planned to use these images for uzi.sh, a tool for parallel LLM coding agents. While I ultimately chose a different final image for that project because I only needed one, the learning process was valuable. For this set, I aimed for a red color scheme to evoke action and speed, which you can see in the images below.

Find a Base Image

Following Kuba's advice, I went to pinterest and found a cool base image that I liked. I went with something that had a lot of red, but also darker colors on the border since I knew that I would need space for text and other elements if I wanted to use these on an actual website.

Build a Style With Neutral Prompts

You can't just start by describing the specific kind of image you want and expect to get good results. Style reference images are needed to give Midjourney the boundaries it needs to stick to your desired aesthetic and theme once you get more specific with your exact asks.

It's unlikely that you'll be able to find multiple images on the internet which match your desired style exactly, so I recommend using neutral prompts to generate additional images in order to create a cohesive gallery.

My neutral prompt here was Portrait photography of a woman, glow behind, futuristic vibe, flash photography, color film, analog style, imperfect --ar 3:4 --v 7. Essentially, any prompt describing a general subject and its characteristics—without getting too specific about style, camera angle, action, or other details—should work well.

Using Describe to Get More Specific

One of the images I wanted was an eagle diving. However, eagle diving with red glowing background wasn't getting me the results I wanted. I accidentally discovered the describe feature dragging images around, and instantly realized that it was a cheat code for getting the images I wanted.

You can take any one of these and pair them with the style reference images you generated earlier to get the eagle or any other image you described into the style you want. I could not believe how well this worked.

Post-Processing: Adding Film Grain for Web Design

Midjourney produces images which are too crisp to fit well as background images for the web. I recommend adding grain to them when you put them into your final site to create a more cohesive feel. If done correctly, you'll end up with a result that looks like the below. CSS is great for this! See a complete guide of how I applied the filter for the uzi.sh site below, full code on Github here.

You first need to add a svg filter definition to your HTML file such that the CSS can reference it later to put the grain on top of the background image. The filter uses feTurbulence to create a fractal noise pattern, and feColorMatrix to adjust the opacity. You can experiment with values like baseFrequency in feTurbulence or the alpha channel (the 0.8 in the feColorMatrix) to fine-tune the grain's intensity and texture.

<!-- SVG noise filter definition - this goes in your HTML -->
<svg style="display: none">
  <filter id="noiseFilter">
    <!-- Creates the fractal noise pattern -->
    <feTurbulence
      type="fractalNoise"
      baseFrequency="0.5"
      numOctaves="3"
      stitchTiles="stitch"
    />
    <!-- Converts noise to semi-transparent overlay -->
    <feColorMatrix
      type="matrix"
      values="0 0 0 0 0
              0 0 0 0 0
              0 0 0 0 0
              0 0 0 0.8 0"
    />
  </filter>
</svg>

Once you have the filter defined, you can apply it to a grain overlay element in your CSS. This element will cover the background image and apply the noise effect.

/* The grain overlay element that applies the filter */
.grain-overlay {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  z-index: 2; /* Above background image, below content */
  pointer-events: none; /* Allows clicks to pass through to elements below */
  filter: url(#noiseFilter); /* Applies the SVG filter defined above */
}

/* Background image styling for context */
.background-image {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  background-image: url("./media/16x9steppecommander.png");
  background-size: cover;
  background-position: center;
  z-index: 1; /* Below grain overlay */
}

Finally, you need to structure your HTML to ensure the layering works correctly. The grain overlay should be positioned above the background image but below any content you want to display.

<!-- HTML structure showing the layering -->
<div class="hero">
  <!-- Layer 1: Background image (z-index: 1) -->
  <div class="background-image"></div>

  <!-- Layer 2: Grain overlay (z-index: 2) -->
  <div class="grain-overlay" style="filter: url(#noiseFilter)"></div>

  <!-- Layer 3: Content (z-index: 3) -->
  <div class="content-center">
    <!-- Your content here -->
  </div>
</div>

Be Creative!

I have heard general discussion and worry about AI-generated art stealing from artists, but it is important to remember that AI is a tool. It can be used to create new things, and it can be used to create derivative works. I think the best way to use AI is to use it as a tool to enhance your own creativity, not as a replacement for it.

Use what you see from others to inspire your own work, but don't just copy and paste. Use AI to get the unique style in your head out onto the screen. Develop your own voice and vision, and let AI help you express it.

DEV Community: Nick K

Org-Level Email Campaigns are Somehow an Unsolved Problem

Defining the Goal

Tool Selection

Solution Architecture

Creating the Campaign

Uploading Leads

Registering the Webhook

Webhook Server

Someone Please Build This

How I Use Claude Code on My Phone with Termux and Tailscale

The Architecture

Step 1: Setup Your Desktop

Step 2: Install Tailscale Everywhere

Step 3: Install Termux on Your Phone

Step 4: SSH Into Your Desktop

Step 5: Use tmux for Session Persistence

Why This Works Better Than Custom Apps

The Mobile Experience

Practical Tips

Test Your Changes on Your Phone's Browser

Use SSH Keys

Create an SSH Config

Use a Better Keyboard

Set Up tmux Keybindings

Run Multiple Sessions

Security Considerations

When This Doesn't Work

The Bottom Line

Respect Content Negotiation to serve Markdown instead of HTML to LLMs

Static Site Generators are already halfway there

Cloudflare Workers-specific configuration

Caddy configuration

Conclusion: A More Accessible Web for Agents

Building SSR with Vite: A Custom getStaticProps Replacement

Why Build Custom SSR with Vite?

The Architecture Overview

Step 1: Setting Up the Express Server

Step 2: Vite Integration

Step 3: The getStaticProps Replacement

Step 4: Server-Side Rendering Pipeline

Step 5: React Server Entry Point

Step 6: Client-Side Hydration

Step 7: Using Server Data in Your App

Step 8: Vite Configuration

Step 9: Build Configuration

Advanced Patterns

Route-Based Data Loading

Error Boundaries and Loading States

Performance Considerations

Caching Strategy

Streaming Benefits

Deployment Considerations

Environment Variables

Docker Setup

Comparison with Next.js

Conclusion

How I Snagged `patron.com` and Why You Should Just Ship It 🚀

The Plot Twist That Changed Everything

Why "Patron" Just Hits Different

The Million Dollar Question: How Do You Get patron.com?

Cold Outreach Like a Boss

When in Doubt, Get on a Plane ✈️

The Superpower of Just Doing Stuff

Your Turn to Ship Something Wild

Why VPS Rocks for Quick Deployments: My Story + Build an LLM-over-DNS agent in Under 30 Mins!

The Struggle Bus Was Real 🚌

Welcome to PaaS Hell 🔥

My VPS Salvation 🙏

Paying It Forward ⚡

The Build: LLM-over-DNS in 30 Minutes ⏰

Step 1: Get Into Your VPS 🔑

Step 2: Clear the DNS Decks 🧹

Step 3: Install Our Tools 🛠️

Step 4: The Magic Script ✨

Step 5: Fire It Up! 🔥

Step 6: Test Your Creation 🧪

When Things Go Wrong 🚨

Lock It Down (Optional but Smart) 🔒

The VPS Philosophy 🎯

The Million Dollar Question: How Do You Get `patron.com`?