srvr.in

Generative cover images for every post

Thu, 16 Apr 2026 00:00:00 +0000

Every blog post shared on social media needs an image. Without one, the platform picks something arbitrary — usually nothing good. The standard fix is og:image: a 1200×630 image in the post’s front matter that Twitter, LinkedIn, and iMessage use for the preview card.

I needed images for thirty-odd posts. The obvious route — Midjourney, Flux, DALL·E — felt wrong for this. AI image generators produce work that looks like AI image generators. Everything comes out with the same aesthetic fingerprint. Worse, the images bear no relationship to the post itself; they are decorative noise.

What I actually wanted was closer to what Sol LeWitt described as a wall drawing: a rule, applied consistently, that produces something distinct each time. Mathematical art fits this exactly. The image is not chosen or generated by taste — it follows from the input. Same post, same image, always.

There are several families of patterns that work well at this scale: flow fields (particles traced through a vector field), Truchet tiles (quarter-circle arcs on a grid), string art (straight lines connecting points around circles), Lissajous curves (parametric loops whose shape changes with two integer ratios). Each family is distinct. Each produces images that look designed rather than generated. And crucially, none of them require an API call, a GPU, or a model.

How it works on this blog

A Node.js script takes a post’s slug, hashes it to a seed, and uses that seed to deterministically pick a pattern family, a color palette, and all the parameters within. Same slug, same image, always. The rake np task that creates new posts now runs the script automatically — new post, new image, no manual step.

The images live in assets/images/posts/ as SVGs and are referenced in front matter. jekyll-seo-tag picks up the image: field and emits the right OG tags.

The cover you see at the top of this post is string art — points distributed around two circles, connected by straight lines skipping a fixed interval. The resulting curves look hand-drawn and mathematical at once. Every post on this blog has one, and no two are alike.

Omanathinkal Kidavo (ഓമനത്തിങ്കൾക്കിടാവോ) — Malayalam lullaby PDF

Wed, 15 Apr 2026 00:00:00 +0000

ഓമനത്തിങ്കൾക്കിടാവോ — PDF (RIT Ezhuthu) · PDF (Rachana) · English version below

മലയാളത്തിലെ ഏറ്റവും പ്രിയപ്പെട്ട താരാട്ടുപാട്ടാണ് ‘ഓമനത്തിങ്കൾക്കിടാവോ’. 1813-ൽ തിരുവിതാംകൂർ മഹാറാണി ഗൗരി ലക്ഷ്മി ഭായിയുടെ അഭ്യർത്ഥനപ്രകാരം ഇരയിമ്മൻ തമ്പിയാണ് ഈ വരികൾ രചിച്ചത്. തന്റെ അനന്തരവനായ (ഭാവി മഹാരാജാവ് സ്വാതി തിരുനാൾ രാമവർമ്മ) കുഞ്ഞിന്റെ ജനനം ആഘോഷിക്കാനായിരുന്നു ഇത്. അക്കാലത്ത് ഒരു ആൺവാരിസില്ലാത്തതിനാൽ ബ്രിട്ടീഷുകാർ രാജ്യം പിടിച്ചെടുക്കാൻ (Doctrine of Lapse) സാധ്യതയുണ്ടായിരുന്ന സമയത്ത് നടന്ന ഈ ജനനം രാജകുടുംബത്തിന് വലിയ ആശ്വാസമായിരുന്നു.

ആ സന്തോഷവും ആശ്വാസവും പാട്ടിന്റെ ഓരോ വരിയിലും പ്രകടമാണ്. കുഞ്ഞിനെ നിലാവിനോടും, പൂവിലെ തേനിനോടും, ആടുന്ന മയിലിനോടും, ദൈവത്തിന്റെ നിധിയോടും, ഭാഗ്യവൃക്ഷത്തിന്റെ ഫലത്തോടുമെല്ലാം കവി ഇതിൽ ഉപമിക്കുന്നു. എന്നാൽ കൗതുകകരമായ ഒരു കാര്യം, പാട്ടിലുടനീളം ഒരിക്കൽ പോലും കുഞ്ഞിനോട് “ഉറങ്ങാൻ” ആവശ്യപ്പെടുന്നില്ല എന്നതാണ്. പാട്ടിന്റെ രാഗത്തിലൂടെയും താളത്തിലൂടെയും കുട്ടി സ്വാഭാവികമായും ഉറങ്ങിക്കൊള്ളും എന്ന സങ്കല്പമാണ് ഇതിന് പിന്നിൽ.

ആദ്യകാലത്ത് ‘കുറിഞ്ഞി’ രാഗത്തിലും ആദി താളത്തിലുമാണ് ഇത് ചിട്ടപ്പെടുത്തിയത്. എങ്കിലും ഇന്ന് ‘നീലാംബരി’ അല്ലെങ്കിൽ ‘നവരോജ്’ രാഗങ്ങളിലാണ് ഇത് സാധാരണയായി പാടാറുള്ളത്. കെ.എസ്. ചിത്ര ആലപിച്ച രൂപമാണ് ഇന്ന് ഏറ്റവും ജനപ്രിയമായിട്ടുള്ളത്. 1987-ൽ പുറത്തിറങ്ങിയ ‘സ്വാതി തിരുനാൾ’ എന്ന സിനിമയിൽ എസ്. ജാനകിയും ഇതിന്റെ ഒരു ഭാഗം പാടിയിട്ടുണ്ട്.

2013-ൽ ഈ താരാട്ടുപാട്ട് അന്താരാഷ്ട്ര തലത്തിൽ വാർത്തകളിൽ ഇടം നേടിയിരുന്നു. ‘ലൈഫ് ഓഫ് പൈ’ (Life of Pi) എന്ന ചിത്രത്തിലെ ഓസ്കാർ നാമനിർദ്ദേശം ലഭിച്ച ‘പൈസ് ലല്ലബി’ (Pi’s Lullaby) എന്ന ഗാനം ഈ താരാട്ടുപാട്ടിന്റെ തമിഴ് വിവർത്തനമാണെന്ന് ആരോപിച്ച് ഇരയിമ്മൻ തമ്പി മെമ്മോറിയൽ ട്രസ്റ്റ് രംഗത്തെത്തിയിരുന്നു. എന്നാൽ ബോംബെ ജയശ്രീ ഈ ആരോപണം നിഷേധിച്ചു.

പിഡിഎഫ്

ഈ പാട്ടിലെ 25 ഈരടികളും പൂർണ്ണമായി ഉൾക്കൊള്ളുന്ന, ഭംഗിയുള്ളതും പ്രിന്റ് ചെയ്യാവുന്നതുമായ ഒരു എ4 ഷീറ്റ് തയ്യാറാക്കണമെന്ന് എനിക്കുണ്ടായിരുന്നു. ഇത് ഫ്രെയിം ചെയ്ത് വെക്കാനോ കുഞ്ഞുങ്ങളുടെ തൊട്ടിലരികിൽ സൂക്ഷിക്കാനോ അനുയോജ്യമാണ്.

ഡൗൺലോഡ്: ഓമനത്തിങ്കൾക്കിടാവോ — RIT Ezhuthu (PDF) · Rachana (PDF)

മലയാളം ലിപി പിഡിഎഫിൽ കൃത്യമാക്കിയ വിധം

മലയാളം ലിപി ഒരു പിഡിഎഫിൽ കൃത്യമായി തെളിയുക എന്നത് വിചാരിച്ചതിലും പ്രയാസകരമായ ഒന്നായിരുന്നു.

മലയാളം വളരെ സങ്കീർണ്ണമായ ഒരു ലിപിയാണ്. ചില്ലക്ഷരങ്ങൾ (ൻ, ൽ, ൾ, ർ, ൺ), കൂട്ടക്ഷരങ്ങൾ എന്നിവ അവയുടെ സ്ഥാനത്തിനനുസരിച്ച് രൂപം മാറുന്നവയാണ്. ഇതിന് ‘ഓപ്പൺ ടൈപ്പ് ടെക്സ്റ്റ് ഷേപ്പിംഗ്’ (OpenType text shaping) ആവശ്യമാണ്. അതായത്, ഫോണ്ടിലെ വിവരങ്ങൾ (GSUB, GPOS) വിശകലനം ചെയ്ത് അക്ഷരങ്ങളെ കൃത്യമായി യോജിപ്പിക്കേണ്ടതുണ്ട്. ‘ReportLab’ പോലുള്ള ലൈബ്രറികൾ ഉപയോഗിച്ച് വെറുതെ യൂണിക്കോഡ് കോഡുകൾ നൽകിയാൽ അക്ഷരങ്ങൾ തെറ്റായിട്ടായിരിക്കും വരിക.

ഇതിനായി ഞാൻ സ്വീകരിച്ച വഴി ഇതാണ്:

വരികൾ ആദ്യം ഒരു HTML പേജ് ആയി തയ്യാറാക്കി.
റചന (Rachana) ടൈപ്പോഗ്രഫി നിർമ്മിച്ച എഴുത്ത് (RIT Ezhuthu) ഫോണ്ട് ഉപയോഗിച്ചു. ഇതിൽ മലയാളം അക്ഷരങ്ങളുടെ എല്ലാ നിയമങ്ങളും കൃത്യമായി ഉൾക്കൊള്ളിച്ചിട്ടുണ്ട്.
ഇതിനെ Chrome headless ഉപയോഗിച്ച് പിഡിഎഫ് ആക്കി മാറ്റി. ഇതിലെ HarfBuzz എന്ന ഷേപ്പിംഗ് എഞ്ചിൻ (ഇത് തന്നെയാണ് ഫയർഫോക്സ്, ക്രോം, ആൻഡ്രോയിഡ് എന്നിവയിലും ഉപയോഗിക്കുന്നത്) മലയാളം അക്ഷരങ്ങളെ കൃത്യമായി രൂപപ്പെടുത്തുന്നു.

ഇതിന്റെ ഫലമായി 25 ഈരടികളും അടങ്ങുന്ന, വായിക്കാൻ സുഖമുള്ളതും പ്രിന്റ് ചെയ്യാവുന്നതുമായ ഒരു പേജ് എനിക്ക് ലഭിച്ചു.

English version below

Omanathinkal Kidavo is perhaps the most beloved lullaby in Malayalam. It was composed in 1813 by the court poet Irayimman Thampi, at the request of Maharani Gowri Lakshmi Bayi of Travancore, to celebrate the birth of her nephew — the future Maharajah Swathi Thirunal Rama Varma. The birth was a momentous event for the royal family, which had been facing the threat of annexation by the British under the Doctrine of Lapse for want of a male heir.

That relief and joy runs through every line. The baby is compared to moonlight, honey in a flower, a dancing peacock, a treasure from God, the fruit of the tree of fortune — but never once asked to sleep. The sleep is meant to come from the raga itself.

Originally set in Kurinji raga and Adi tala, it is most commonly performed today in the Nilambari or Navaroj ragas. K.S. Chithra’s rendition is the most widely known. S. Janaki sang a portion of it in the 1987 biographical film Swathi Thirunal. The poem made international headlines in 2013 when the Irayimman Thampi Memorial Trust alleged that the first eight lines of Bombay Jayashri’s Oscar-nominated “Pi’s Lullaby” from Life of Pi were a Tamil translation of this lullaby — a claim Jayashri denied.

The PDF

I wanted a clean, printable A4 sheet with all 25 couplets in Malayalam — something you could frame or keep by a crib.

Download: Omanathinkal Kidavo — RIT Ezhuthu (PDF) · Rachana (PDF)

Getting Malayalam right in a PDF

Getting Malayalam to render correctly in a PDF turned out to be more involved than expected.

Malayalam is a complex script. Characters like chillaksharams (ൻ, ൽ, ൾ, ർ, ൺ) and conjunct consonants change shape depending on context. They require OpenType text shaping: the rendering engine consults lookup tables in the font (GSUB and GPOS) to substitute and reposition glyphs. A naive approach — placing Unicode codepoints onto a PDF canvas as libraries like ReportLab do with drawString — skips this shaping step entirely, producing broken ligatures and garbled chillaksharams.

The solution was a proper shaping pipeline:

Write the lyrics as an HTML page with CSS for layout, borders, and typography.
Use the RIT Ezhuthu font from Rachana Typography — a well-crafted OpenType font with complete Malayalam shaping rules.
Convert to PDF using Chrome headless, which uses HarfBuzz — the same shaping engine used by Firefox, Chrome, and Android — to process the OpenType tables and produce properly formed Malayalam glyphs.

The result is a single A4 page with all 25 couplets, readable and print-ready.

A simple i18n strategy for single-page apps

Mon, 06 Apr 2026 00:00:00 +0000

I built nokkam — a Kerala election prediction game — and a week before the April 9 elections, I wanted to add Malayalam. I looked at react-i18next and FormatJS. Both are built for apps that need plural rules, date formatting, server-side loading, and right-to-left support. Nokkam has none of that. It is a two-language SPA with static strings and no backend.

I did not want to wire up a plugin system for a problem that did not need one. So I wrote the i18n layer myself. Here is what I needed:

Two languages only
Type safety: if ml.ts is missing a key that en.ts has, fail at compile time, not runtime
Language preference persists across page reload
No build step, no code generation

That is it. The result is 60 lines.

The type trick

The English file is a plain object. The last line is the important one:

// src/locales/en.ts
export const en = {
  splash: {
    title: "Kerala Assembly Election\nPrediction Game",
    tap: "Tap to begin",
  },
  leaderboard: {
    predictionSingular: "prediction",
    predictionPlural: "predictions",
  },
  constituencies: {
    1: "Manjeshwara",
    2: "Kasaragod",
    // ... 140 entries
  } as Record<number, string>,
  districts: {
    Kasaragodu: "Kasaragodu",
    // ... 14 entries
  } as Record<string, string>,
};

export type Translations = typeof en;

typeof en generates a type from the object’s shape. The Malayalam file imports that type and must satisfy it:

// src/locales/ml.ts
import type { Translations } from "./en";

export const ml: Translations = {
  splash: {
    title: "കേരള നിയമസഭാ തിരഞ്ഞെടുപ്പ്\nപ്രവചന മത്സരം",
    tap: "തുടങ്ങാൻ ടാപ്പ് ചെയ്യുക",
  },
  leaderboard: {
    predictionSingular: "പ്രവചനം",
    predictionPlural: "പ്രവചനങ്ങൾ",
  },
  // ...
};

If I add a key to en.ts and forget ml.ts, TypeScript throws a compile error. No runtime surprises, no JSON schema files, no code generation step.

One thing to avoid: as const on the en object. That makes every string a literal type, so ml.ts cannot satisfy Translations — every Malayalam string would need to match the English one character for character.

The context

The provider reads the saved preference from localStorage on mount, then exposes the current translations and a toggle function:

// src/lib/i18n.tsx
import { createContext, useContext, useState, type ReactNode } from "react";
import { en } from "../locales/en";
import { ml } from "../locales/ml";
import type { Translations } from "../locales/en";

export type Lang = "en" | "ml";

const LOCALES: Record<Lang, Translations> = { en, ml };
const STORAGE_KEY = "nokkam_lang";

interface I18nCtx {
  tr: Translations;
  lang: Lang;
  toggleLang: () => void;
  tC: (num: number) => string;
  tD: (name: string) => string;
}

const Ctx = createContext<I18nCtx | null>(null);

export function I18nProvider({ children }: { children: ReactNode }) {
  const [lang, setLang] = useState<Lang>(() => {
    const stored = localStorage.getItem(STORAGE_KEY);
    return stored === "ml" ? "ml" : "en";
  });

  const tr = LOCALES[lang];

  function toggleLang() {
    const next: Lang = lang === "en" ? "ml" : "en";
    localStorage.setItem(STORAGE_KEY, next);
    setLang(next);
  }

  function tC(num: number): string {
    return tr.constituencies[num] ?? en.constituencies[num] ?? String(num);
  }

  function tD(name: string): string {
    return tr.districts[name] ?? name;
  }

  return (
    <Ctx.Provider value={{ tr, lang, toggleLang, tC, tD }}>
      {children}
    </Ctx.Provider>
  );
}

export function useTranslation(): I18nCtx {
  const ctx = useContext(Ctx);
  if (!ctx) throw new Error("useTranslation used outside I18nProvider");
  return ctx;
}

A component calls useTranslation() and reads from tr:

// src/screens/SplashScreen.tsx
export function SplashScreen({ onNext }: Props) {
  const { tr } = useTranslation();
  const [line1, line2] = tr.splash.title.split("\n");
  return (
    <div className="splash-screen" onClick={onNext}>
      <h1>{line1}<br />{line2}</h1>
      <p>{tr.splash.tap}</p>
    </div>
  );
}

The toggle button shows “മ” in English mode and “EN” in Malayalam:

// src/components/LangToggle.tsx
export function LangToggle() {
  const { lang, toggleLang } = useTranslation();
  return (
    <button onClick={toggleLang} aria-label="Toggle language">
      {lang === "en" ? "മ" : "EN"}
    </button>
  );
}

The proper nouns problem

Kerala has 140 assembly constituencies and 14 districts. These are proper nouns — each has a canonical Malayalam spelling that differs from transliteration, and they are looked up by ID, not by a developer-chosen key.

i18n libraries handle this badly. They assume every string has a developer-chosen key.

The solution here is two separate maps inside the locale file, typed with Record<number, string> and Record<string, string>. The tC(num) and tD(name) helpers look up those maps and fall back to English if the key is missing — safe for incremental rollout.

The translation workflow

I wrote the first pass myself, with Claude helping inline. Then I embedded a review prompt as a block comment at the bottom of ml.ts and pasted the whole file into a separate chat.

The corrections that came back:

My version	Correct
`കാസർഗോഡ്`	`കാസർകോട്` (official district name)
`ആടൂർ`	`അടൂർ` (constituency #115)
`അറ്റിങ്ങൽ`	`ആറ്റിങ്ങൽ` (Attingal)
`അരൻമുള`	`ആറന്മുള` (Aranmula)
`നടപ്പുറം`	`നാദാപുരം` (Nadapuram)

The review also made several UI strings more colloquial.

The workflow is reproducible: write the review prompt once, embed it in the source, paste the file whenever you want a pass. It works for any language.

Where this breaks down

More than two or three languages, and the object approach stops scaling. Malayalam has complex plural forms — the current setup handles it with separate keys (predictionSingular, predictionPlural), which works but is not general. A proper i18n library handles pluralisation with a rules engine. Server-rendered apps need a different loading strategy. For ICU message format, date and number localisation, or RTL support: use a library.

For a small SPA with a fixed set of languages and no pluralisation complexity, this is enough.

Whisper dictation on Linux

Mon, 30 Mar 2026 00:00:00 +0000

macOS has built-in dictation. Windows has it too. Linux does not — not in any form that works system-wide, without the cloud, and without a painful setup ritual. So I built one.

whisper-dictation is a single Python file (~300 lines). Hold a keyboard shortcut, speak, release — your words appear in whatever app has focus. It runs entirely locally using OpenAI’s Whisper model via faster-whisper. No API keys. No cloud. No subscriptions.

The interesting part was not the speech recognition. That was easy. The interesting part was getting the transcribed text into the active window without breaking things.

The stack

faster-whisper — CTranslate2-optimized Whisper with int8 quantization. The “base” model is 140MB and transcribes a few seconds of audio in about a second on a laptop CPU.
sounddevice — PortAudio wrapper for mic capture.
evdev — reads keyboard events directly from /dev/input/*. On Wayland, there is no equivalent of X11’s XGrabKey, so reading from the input device directly is the only way to get global hotkeys.
uv — the script uses PEP 723 inline metadata, so uv run ./dictation.py installs everything automatically. No venv to manage.

The space-eating bug

The first version worked: evdev catches the hotkey, sounddevice records while it is held, faster-whisper transcribes on release, ydotool types the result. Had it running in an afternoon.

Then I tried using it with Claude Code.

Every space disappeared. The transcription in the logs was perfect — “Hello, I am testing this dictation tool” — but what appeared in the terminal was “Hello,Iamtestingthisdictationtool”.

The cause: Claude Code uses the space bar as a shortcut to activate voice chat mode. When ydotool type sends text character by character, each space is a separate key event. Claude Code intercepts those events before they reach the input field.

This is the kind of bug that only shows up when the tool meets a specific app’s keyboard handling. Unit tests would never catch it.

The fix is to not type characters at all. Instead:

Copy the transcribed text to the clipboard (wl-copy on Wayland)
Simulate Ctrl+Shift+V to paste it as a block

Simple in theory. In practice, this was a tour of everything broken about input simulation on Linux Wayland.

The Wayland input simulation gauntlet

Attempt 1: wl-copy + ydotool key

First try: wl-copy "text" to set clipboard, then ydotool key ctrl+shift+v to paste. The script hung. wl-copy does not fork on newer versions — it stays running as a clipboard server process, serving paste requests. subprocess.run() blocks forever waiting for it to exit.

Fix: use subprocess.Popen() and kill the previous instance before each new copy.

Attempt 2: ydotool syntax mismatch

The system had ydotool v0.1.8 (Ubuntu’s default), and I was using v1.0+ raw keycode syntax (29:1 42:1 47:1...). v0.1.8 uses named syntax (ctrl+shift+v). Different tool, different interface.

Also: the setup script had created a systemd service for ydotoold, the ydotool daemon. That binary does not exist in v0.1.8 — it was added in v1.0+. The service crash-looped with exit code 203 (EXEC: binary not found). Without the daemon, ydotool key was unreliable for single key combos.

Attempt 3: wtype

wtype is the Wayland-native text input tool. It uses the wlr-virtual-keyboard-v1 protocol.

Exit code 1. GNOME/Mutter does not implement wlr-virtual-keyboard-v1. That protocol is specific to wlroots-based compositors (Sway, Hyprland). wtype is useless on GNOME.

Attempt 4: xdotool

xdotool key ctrl+shift+v. Nothing happened. My terminal (Ptyxis, GNOME’s new GTK4 terminal) is a native Wayland app. xdotool only reaches XWayland windows.

What actually works: ydotool with a delay

Back to ydotool. The key insight: ydotool operates at the kernel level via uinput. It creates a virtual input device that the Wayland compositor treats as a real keyboard. This works with every window — Wayland-native, XWayland, GTK, Qt, terminal, browser.

The trick for reliability without the daemon: ydotool key --delay 200 ctrl+shift+v. The 200ms delay gives the compositor time to register the virtual keyboard device before the key events arrive.

Final working pipeline on GNOME Wayland:

wl-copy "text"  →  sleep 100ms  →  ydotool key --delay 200 ctrl+shift+v
(Popen, non-blocking)              (uinput → compositor → active window)

The compatibility breakdown across tools:

Tool	Mechanism	GNOME Wayland	Sway/Hyprland	X11
ydotool	Linux uinput (kernel)	Yes	Yes	Yes
wtype	wlr-virtual-keyboard-v1	No	Yes	No
xdotool	X11 protocol	No*	No	Yes

*Only reaches XWayland windows

A few other decisions

Hotkey combo, not single key. The initial hotkey was just Right Super (KEY_RIGHTMETA). On GNOME, releasing Super opens the Activities overview. Every dictation ended with the app launcher flashing open. Switched to Right Shift + Right Super as the default.

Tool detection at startup. All the shutil.which() checks for wl-copy, ydotool, xclip, xdotool run once when the script boots. During actual use, type_text() just branches on a cached string — no overhead per transcription.

Warnings, not crashes. If the ideal tools are not installed, the script tells you exactly what to install, but still tries to work with whatever is available. It falls back to ydotool type if nothing else is found — which works everywhere except in apps with custom space-bar handling.

What I learned

wl-copy is a long-lived process. It does not fire and forget. subprocess.run() will block your event loop forever.

ydotool 0.1.8 and ydotool 1.0+ are different tools. Different syntax, different architecture (daemon vs. direct), different reliability characteristics. Ubuntu ships the old one.

Clipboard paste is more robust than typing. Any app that does custom key handling — vim, tmux, Claude Code — may interpret individual key events differently than raw text. Pasting as a block sidesteps all of that.

Debug logging saves hours. Adding --debug early and logging every subprocess call with its exit code and stderr made each failure diagnosable in one iteration instead of three.

Try it

git clone https://github.com/srih4ri/whisper-dictation
cd whisper-dictation
./setup.sh
# log out, log back in
./dictation.py

Tested on Ubuntu 25.10 with GNOME 48/Mutter and Ptyxis terminal. The setup script detects your display server and installs the right tools. If something does not work on your setup, open an issue.

llm-relay: switching LLM backends with one env var

Fri, 20 Mar 2026 00:00:00 +0000

I have a homelab service that classifies incoming text using an LLM. I wanted different models in different environments: Apple Intelligence on my Mac (free, private), a quantised DeepSeek-R1 on Ollama on my home server, and AWS Bedrock on my cloud VPS. Each has a different SDK, a different async interface, and different configuration.

I did not want to write if backend == "anthropic" branches inside application code. So I extracted the problem into a small package: llm-relay.

The package is small by design. It is not a framework. It does not manage conversation history, streaming, or embeddings. It just routes a prompt to a model and returns a string — and that constraint is what keeps it useful across multiple unrelated services.

What it does

llm-relay exposes two functions:

from llm_relay import ask, ask_json

text = await ask("summarise this", system="You are a summariser")
data = await ask_json("classify: buy milk")
# → {"category": "shopping", "title": "Buy milk", ...}

The backend is controlled entirely by environment variables:

LLM_BACKEND=ollama       # or anthropic, bedrock, apple
LLM_MODEL=deepseek-r1:1.5b

Application code never changes. Only the deployment environment does.

How it works

It is mostly LiteLLM with Apple Intelligence support bolted on. For Ollama, Anthropic, and Bedrock it delegates to LiteLLM, which handles the protocol differences between providers. For Apple Intelligence it calls apple_fm_sdk directly, since the on-device Foundation Models framework has its own async interface that LiteLLM does not cover (see Apple Intelligence on the command line).

async def ask(prompt, *, system="", config=None):
    cfg = config or LLMConfig.from_env()
    if cfg.backend == "apple":
        return await _ask_apple(prompt, system=system, cfg=cfg)
    return await _ask_litellm(prompt, system=system, cfg=cfg)

ask_json is a thin wrapper that also strips markdown fences, since models habitually wrap JSON in ` ```json ` blocks even when asked not to.

How it is installed

A plain Python package published to GitHub, installed as a git dependency:

# pyproject.toml
dependencies = [
    "llm-relay @ git+https://github.com/srih4ri/llm-relay.git@v0.1.0",
]

Rise of the machines - watching the AI big bang unravel

Thu, 19 Mar 2026 23:47:00 +0000

I lived through COVID without writing a word about it. The spread, the panic, the lockdowns, the strange rituals — masks, hand sanitizer at every door, the six-foot distance that became reflex. Then the vaccines, and the slow return to something ordinary. And then one day, a year or two later, I realized: I had no record of having been there. Something historical had happened around me. I had nothing to show for having witnessed it.

I do not want to make that mistake again.

Something large is happening right now with AI. I can take notes while it happens. That is what this post is.

The timeline

~2022 — First words with ChatGPT

I do not remember the exact date. I was poking at it — asking questions to find where it breaks, watching it give stupid replies, laughing. This is dumb. That was my conclusion. I closed the tab.

~2022–2023 — A blurry image from a machine

I opened a Stable Diffusion web UI and typed a prompt. What came out was laughable. It did not draw what I asked. Faces melted together. Hands had seven fingers.

Fast forward two years: text-to-image works almost flawlessly. No ghost fingers. No obvious artifacts. You can still tell — there is a quality to AI images that gives them away. But there are no blatant mistakes. No unnatural features. The gap between what you ask for and what you get has nearly closed.

Early 2024 — Annoyance, and a policy

People started sending AI-generated pull requests. The code was not bad in obvious ways — it was formatted, described, plausible. But it made mistakes. Subtle ones. The kind a careful reviewer catches and a careless one ships. I was annoyed that people were not being careful, that they were throwing AI output at me to review as if I were a human compiler.

My own policy at the time: get AI to write a function — something small, with a clearly defined interface, where you can judge whether it works. But compose those functions yourself. Orchestrate yourself. Keep the reasoning yours.

I thought this was the paradigm for a while. Write the small pieces with AI. Own the structure. I did not think AI would ever reason about a large codebase and produce working code from a bare requirement. I was wrong, but I did not know that yet.

Early 2024 — Copy, paste, distrust

At work, I was not using any coding agent. The company had not completed the legal process to allow AI tools access to the codebase — privacy concerns, data exposure. I had no access.

Outside of that, I was using ChatGPT for coding the only way available: copy a snippet, paste a question, paste the answer back. It worked sometimes. But I never fully trusted the output. The code looked right. It often was not. I had no way to verify it quickly, and that uncertainty made me hesitant to lean on it. I did not know what coding agents existed or how to evaluate them. ChatGPT and the occasional Google search were the whole toolkit.

August 2024 — Agentic coding, first attempt

I was using GitHub Copilot from inside VS Code — agentic mode, letting it do more than autocomplete. Getting it to actually make a code change required nagging.

June 2025 — Laid off, and leaning in

I was laid off. I used AI more heavily than I ever had before. I exported my entire work history from Jira and fed it to AI to build my resume — not to write it for me, but to surface what mattered from years of tickets and notes. The result is here.

The original two-page resume was not working. I was applying and hearing nothing. We figured out that AI was probably doing the first-pass screening and auto-rejecting me. So I made the resume bigger. I also built workflows to generate cover letters from job descriptions and my own resume. It felt strange to do. Mechanical in a way I had not expected.

And then the eerie part: I was being rejected by AI when applying for jobs. I kept thinking — people are now going to encounter AI as their first point of contact with companies, and the AI may give them nothing useful.

It did not take long. Within months, AI chatbots were everywhere. Most of them are nearly useless. They send you in circles. They deflect. They cannot handle anything outside the script. Maybe they reduce call volume for companies, but as a customer — trying to cancel an airline ticket, trying to do something that requires actual judgment — the chatbot does not help. It gets in the way.

November 2025 — Claude

I switched to Claude. What struck me immediately was how it used tools — and how quickly. With Copilot, or Codex before it, I had to push the agent to make a change. Claude just did it. You asked, it reached for the file, made the change, moved on.

Around the same time, I tried to stop Claude from co-signing my commits. I fiddled with it for a bit, then stopped caring, and Claude has co-signed everything since. Someone told me they actually liked it — it shows they used Claude, not Copilot.

March 18, 2026 — Ten minutes

I ran Claude Code with --dangerously-skip-permissions. Along with the task, I told it: find the Telegram bot credentials somewhere in this repo, find my Telegram contact from any message history, and send me a message when you are done. I thought the task would take hours. I expected it might surprise me by finishing sooner. I did not expect it to finish the task, hunt down the credentials, find my contact, and actually send me a Telegram message — all in under ten minutes.

March 2026 — The first agent at work

I wrote my first agentic program at work: a system that reads incoming alerts and triages them autonomously. It reads context, makes a judgment, acts. It does something that used to require a human on-call at 3am.

I built it in a week.

April 2026 — Nokkam, quota, and talking to Claude

Last week I built nokkam.lol — a Kerala Assembly Elections 2026 prediction game where users pick winners across all 140 constituencies, get a shareable card, and land on a leaderboard. The frontend is React + TypeScript on Cloudflare Pages; the backend is Go + SQLite on a VPS. The app ships with full Malayalam i18n, anonymous user IDs, and scoring logic that sits dormant until results day on May 4.

This week I nearly hit my weekly AI usage quota. The ceiling is already there. AI cost is going to be a limiting factor — not eventually, but soon.

The biggest AI news this week: Anthropic released Claude Mythos Preview and then immediately said it cannot go public. The model scored 93.9% on SWE-bench and can find zero-day vulnerabilities across every major OS and browser fast enough that Anthropic judged it too dangerous to release. Instead, they launched Project Glasswing, giving 50+ tech companies access to use Mythos for defense rather than offense.

The release that excited me most was Claude channels and the Telegram plugin. I had been building toward this manually — a voice notes app to capture thoughts on Telegram, transcribe them with locally installed whisper-cpp, then copy the transcript into Claude. Three tools, fragile by design. Now that whole pipeline is native. I can talk to Claude.

At work, I started reaching for Codex for deep investigations. A GitHub issue that went wide documented Claude Code’s regression: someone had mined months of session logs, analyzed 17,871 thinking blocks and 234,760 tool calls, and traced a quality drop back to February when Anthropic changed how thinking tokens were handled. My confirmation bias ran with it. I switched to Codex for some investigations and found it useful; it caught gaps Claude had left. Whether Claude is actually lazier or I was primed to see it that way, I cannot say with confidence. But what struck me most about that report was not the regression — it was the telemetry. Someone had built months of instrumentation around an AI agent, monitoring it like infrastructure. That is a different relationship with a tool.

The permission model is a real blocker at work. I have eight terminal tabs open, each running a Claude Code or Codex session, all paused — waiting for my approval before they take the next step. The whole point of an agent is that it runs. I want to explore ways to let them operate uninterrupted without opening up everything.

Last week, alongside Nokkam, I reconnected with an old friend — Sudarsh MS — who is building with AI at the same pace and intensity. We traded workflows and shared what was working. It turned into a collaboration: we wrote a quick security auditor together, which will be published here soon.

This post updates as new moments happen. Last updated: April 2026.

Getting your feet wet with OpenTelemetry

Thu, 19 Mar 2026 20:00:00 +0000

A few months back I gave an introduction to OpenTelemetry for an engineering team. Most of it is general enough to be useful to anyone, so here it is — stripped of anything context-specific, for whoever searches for “what the hell is OTEL.”

OpenTelemetry (OTEL) is an open-source observability framework: a vendor-neutral standard for instrumenting applications to emit traces, metrics, and logs. It graduated from the CNCF in 2024 and is backed by every major cloud provider and observability vendor. It is the industry standard for distributed tracing.

The deck below covers the core concepts, the architecture, common pitfalls, and how to get started. Use the arrows to click through. Below the slides are links to go deeper, and a full written walkthrough for those who prefer reading.

1 / 14

Getting your feet wet with OpenTelemetry

A brief introduction to distributed tracing

2 / 14

When logs aren't enough

Traditional logging gets painful as your system grows:

Logs are scattered across services with no shared thread
No easy way to correlate what happened across a single request
Hard to tell timing, causality, or which service is actually slow
Grep-driven debugging across six services is not a strategy

Which service is slow? Why did this request fail? Which downstream call is the bottleneck?

3 / 14

What is OpenTelemetry?

An open-source observability framework for traces, metrics, and logs
Vendor-neutral — instrument once, send anywhere (Jaeger, Datadog, Grafana Tempo, AWS X-Ray)
CNCF graduated project, backed by AWS, Google, Microsoft, Datadog, Grafana
Born from the merger of OpenTracing and OpenCensus in 2019

4 / 14

Three core concepts

Trace

The complete journey of a single request through your system — from the moment it arrives to the moment it returns.

Span

A single operation within that journey: a database query, an HTTP call, a queue publish. Spans nest to form a tree.

Context Propagation

How trace information travels across service boundaries — via the W3C traceparent header. Every service adds its span and passes the context forward.

5 / 14

Anatomy of a span

Each span carries:

Span ID + Parent Span ID — where it sits in the tree
Operation name — what it represents (e.g., GET /users/:id)
Timestamps — start, end, duration
Attributes — key-value pairs: HTTP method, DB query, queue topic, custom data
Events — timestamped log entries within the span
Status — OK, Error (with message)

6 / 14

Reading the waterfall view

Every tracing backend shows traces as a waterfall (also called a flame graph). How to read it:

Each horizontal bar = one span
Nested bars = parent-child relationships
Bar width = duration
Colors = different services

At a glance you see: what happened, in what order, how long each step took, and where time was actually spent. A DB call taking 800ms of a 900ms request is immediately obvious.

7 / 14

The architecture

Data flows from your service, through a collector, to a backend:

Your Service → OTEL SDK/Agent → OTEL Collector → Backend (Jaeger / Datadog / Tempo / X-Ray)

The Collector is the key piece:

Centralises configuration — services just point at the collector
Redacts sensitive data before it hits any backend
Fan-out to multiple backends simultaneously
Handles buffering, retries, backpressure

8 / 14

Language support

OTEL has mature libraries for every major language. Most auto-instrument HTTP, databases, queues, and gRPC with zero code changes:

Java / Scala / JVM: opentelemetry-java-instrumentation — attach the agent, done
Python: opentelemetry-python-contrib — wraps Django, Flask, FastAPI, SQLAlchemy, Celery
Node.js: opentelemetry-js — Express, Fastify, NestJS, pg, Redis
Go: opentelemetry-go with contrib packages
.NET: opentelemetry-dotnet — ASP.NET Core, HttpClient, SQL Client

Check the OTEL Registry for your specific framework.

9 / 14

Getting started

Three steps:

Set up a backend to receive traces (Jaeger is free and easy; Grafana Tempo if you're on Grafana stack)
Set up an OTEL Collector to sit in front of it
Add the SDK or agent to your service, configure via environment variables:

OTEL_SERVICE_NAME=my-service
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

That last one is 10% sampling — important in production (see next slide).

10 / 14

Common pitfalls

Missing context propagation — if one service doesn't forward the traceparent header, the trace breaks there. Check every service boundary.
100% sampling in production — traces have real overhead. Start at 10%, go lower on high-traffic paths.
Meaningless span names — span-1 and handler tell you nothing. Name spans after what they do.
Sensitive data in baggage — baggage propagates to every downstream service and third-party API. Don't put PII there.
Losing async context — async code needs explicit context passing; the SDK doesn't always capture it automatically.
Not setting OTEL_SERVICE_NAME — all your spans show up under "unknown_service". Always set it.
Ignoring collector health — a backed-up collector silently drops spans. Monitor it.

11 / 14

What you can answer with traces

Why is this request slow — and which specific operation is responsible?
Which service is the bottleneck — mine or the one I call?
Why did this request fail — and which downstream call triggered the error?
What does our actual service communication graph look like?
Is that cache actually reducing database load?
What is our p99 latency broken down by operation type?

The payoff: debug production issues in minutes, not hours. The waterfall view usually points at the problem immediately.

12 / 14

FAQ

What's the performance overhead?: Less than 3% CPU at 10% sampling. Most teams find it negligible. At 100% sampling on high-traffic paths it matters more.
Do I need to change my code?: Usually no. Auto-instrumentation handles HTTP, DB, queues, and gRPC. Custom spans are optional, for operations the SDK can't see.
How long should I keep traces?: 3–14 days is typical. Storage is cheap, but unbounded retention gets expensive. Most debugging happens within 24–48 hours anyway.
Traces vs logs — when do I use which?: Logs are point-in-time events. Traces show timing and causality across a request. Use both — they complement each other.
Am I locked into a vendor?: No. Switching backends (Jaeger → Datadog → Tempo) is a config change, not a code change. That's the whole point.

13 / 14

Key takeaways

Traces tell stories. Logs tell facts. Both matter, but a trace gives you the full picture of a request.
OTEL is the standard. Not a vendor product, not a framework you'll need to replace in three years.
Auto-instrumentation gets you 80% of the value for free. Add the agent, point it at a collector, and you're already useful.
Always sample in production. 100% tracing is a footgun. Start at 10%.
Watch the context propagation gaps. They silently break traces across service boundaries. Test early.

14 / 14

Where to go next

Watch first: "What Is This OpenTelemetry Thing?" — Martin Thwaites, GOTO 2024. 46 minutes, 133k views, the clearest intro to OTEL I've seen. If you watch nothing else, watch this.
opentelemetry.io/docs — the official documentation. The concepts section is worth reading top to bottom.
OTEL Registry — find the right instrumentation library for your language and framework.
jaegertracing.io/docs — if you're self-hosting with Jaeger.
Grafana Tempo — a good free alternative backend if you're already on Grafana.

1 / 14

Resources

What Is This OpenTelemetry Thing? — Martin Thwaites, GOTO 2024 — Start here. 46 minutes, 133k views. The clearest, most practical intro to OTEL I’ve come across. Strongly recommended.
opentelemetry.io/docs — official docs; the concepts section is worth reading top to bottom
OTEL Registry — instrumentation libraries by language and framework
Jaeger — the easiest open-source backend to get started with
Grafana Tempo — good choice if you’re already on the Grafana stack
OpenTelemetry on GitHub — specification, SDKs, the collector

The full walkthrough

The problem with logs alone

Picture a common scenario: a user reports a slow request. You check the logs. Service A says “request received, request completed.” Service B says “processing started, done.” Service C says “query executed.”

But which service was slow? How long did each step actually take? You don’t know.

Traditional logging breaks down in distributed systems. Logs scatter across services with no correlation between them. They record events but not durations. When thousands of requests run concurrently, there is no way to tell which log line belongs to which request.

Distributed tracing solves this by following a single request through all your services.

What is OpenTelemetry?

OpenTelemetry, or OTEL, is an open-source observability framework. It works with any backend — Jaeger, Datadog, Grafana Tempo, AWS X-Ray. It is a CNCF graduated project, at the same level as Kubernetes, born from the merger of OpenTracing and OpenCensus in 2019.

AWS, Google, Microsoft, Datadog, and Grafana all support it. As Martin Thwaites puts it: nobody gets fired for suggesting they move their telemetry to OpenTelemetry.

The key benefit is portability. Switch backends with a config change, not a code change.

OpenTelemetry handles three signals: traces, metrics, and logs. Traces follow a request’s journey. Metrics are measurements over time. Logs are event records. The three complement each other, but traces are the most powerful for debugging distributed systems.

Traces and spans

Two concepts sit at the core of tracing.

A trace is the complete journey of a single request through your system. You don’t create traces directly — a trace is simply a group of spans that share the same Trace ID.

A span is one operation within that journey — a database query, an HTTP call, a queue publish. Each span has a unique Span ID, a Trace ID, a Parent Span ID (linking it to whoever called it), timestamps, and attributes.

One way to think about it: spans are fancy logs. Or flipped around: logs are boring traces.

Context propagation

How does the trace ID travel between services? Through context propagation.

When Service A calls Service B, it passes a traceparent header. This is defined by the W3C Trace Context spec. The header carries the Trace ID, the parent Span ID, and sampling flags. Service B reads it, creates its own span as a child, and passes the header forward to any service it calls.

Watch out for Baggage. Baggage attaches arbitrary key-value data to a trace context and propagates to every downstream service — including third-party APIs. Never put sensitive data in baggage.

What’s inside a span

Each span contains:

Span ID and Parent Span ID — where it sits in the call tree
Operation name — what it represents, e.g. GET /api/orders
Timestamps — start time and duration
Attributes — searchable key-value metadata
Events — timestamped log entries attached to the span
Status — OK, ERROR, or UNSET

Attributes deliver most of the searchable value. HTTP calls automatically carry method, status code, URL, and route. Database calls carry the system, statement, and database name. Messaging carries the queue system and destination. Add custom attributes for business context — user ID, order ID, tenant name — and you can search across your entire system: show me all spans where HTTP status code is 500.

Reading the waterfall

Every tracing backend visualises traces as a waterfall (sometimes called a flame graph). Each horizontal bar is one span. Nested bars show parent-child relationships. Bar width shows duration. Different colors represent different services.

You see immediately where time goes and what calls what. A database call taking 800ms of a 900ms request is the widest bar — obvious at a glance. An N+1 query shows up as a row of identical small bars repeating in a loop.

The architecture

Three components work together:

OTEL SDK or Agent — instruments your application, creating spans automatically for HTTP, database, messaging, and gRPC calls.

OTEL Collector — aggregates, processes, and routes telemetry data. Your services send to the Collector; the Collector sends to your backend.

Backend — stores and visualises traces. Jaeger, Datadog, Grafana Tempo, AWS X-Ray, Honeycomb — your choice.

The Collector is the piece worth understanding. It centralises configuration so API keys live in one place. It redacts sensitive data before it leaves your network. It fans out to multiple backends simultaneously. And if your backend is slow, it buffers rather than dropping spans.

Language support

OTEL has mature libraries for every major language. Most auto-instrument HTTP, databases, queues, and gRPC with zero code changes:

Java, Scala, JVM — auto-instrumentation via a Java agent. Attach the agent at startup, done. HTTP clients, JDBC, Kafka, RabbitMQ, gRPC, Akka, Play all covered.
Python — wrap your app with opentelemetry-instrument. Covers Django, Flask, FastAPI, requests, SQLAlchemy, Celery.
JavaScript / TypeScript — Express, Fastify, NestJS, pg, Redis auto-instrumented.
Go — contrib packages for net/http, gRPC, database/sql.
.NET — ASP.NET Core, HttpClient, SQL Client.

Check the OTEL Registry for the full list and your specific framework.

Getting started

Three steps:

Check if tracing infrastructure exists. Is there an OTEL Collector running? Is there a backend like Jaeger or Datadog to send to? If not, spin up Jaeger locally — it’s a single Docker container.
Add the SDK or agent. For JVM languages this means adding a -javaagent flag. For Python, pip install the distro and exporter then wrap with opentelemetry-instrument. For others, follow the library’s quickstart.
Configure via environment variables. These are standard across all languages:

OTEL_SERVICE_NAME=my-service
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

That last variable sets 10% sampling — more on why that matters below.

Common pitfalls

Missing context propagation. If any service in the chain doesn’t forward the traceparent header, the trace breaks there. Make sure you’re using OTEL-instrumented HTTP clients, not raw ones that strip unknown headers.

100% sampling in production. Tracing has real overhead. There are two sampling strategies: head sampling decides at request start (efficient but has limited info), and tail sampling decides after the trace is complete (can selectively keep errors and slow requests). Start at 10% and tune from there.

Meaningless span names. Don’t call your spans span-1 or doStuff. Use descriptive names like HTTP GET /api/orders or process-payment. Meaningless names make traces useless for debugging.

Sensitive data in attributes and baggage. Baggage propagates to every downstream service, including third-party APIs. Don’t put PII, SSNs, or secrets in baggage.

Losing async context. In threaded or async code, spans won’t automatically connect across thread boundaries. Use your language’s context propagation APIs explicitly.

Not setting OTEL_SERVICE_NAME. Without it, all your spans appear as unknown_service. Always set it.

Ignoring collector health. A backed-up or crashed collector silently drops spans. Monitor the otelcol_exporter_send_failed_spans metric.

What you can answer with traces

Once tracing is running, these questions have answers:

Why is this specific request slow — and which operation is responsible?
Is my service slow, or is the slowness coming from something it calls?
Why did this request fail — which downstream call threw the error?
What does our actual service communication graph look like at runtime?
Is that Redis cache actually reducing database queries?
What is our p99 latency, broken down by operation type?

The payoff: production issues debugged in minutes, not hours. Pull up the trace, and the waterfall points straight at the problem.

Apple Intelligence on the command line

Wed, 18 Mar 2026 00:00:00 +0000

Apple Intelligence isn’t just a suite of system-wide writing tools or a smarter Siri. For developers, it’s an on-device Foundation Models framework that we can hook into using Python.

The python-apple-fm-sdk ¹ provides a bridge to the ~3B parameter language model running on your Mac’s Neural Engine. It is entirely offline and requires no API keys.

What it can be used for

Because the model is local, it excels at high-volume, low-latency tasks where sending data to the cloud is either too slow, too expensive, or a privacy risk.

Email Classification: Sorting through thousands of subject lines to flag promotions for deletion (as seen in my previous post).
Utility Content Detection: Scanning your Photos library to filter out screenshots, documents, and blurry shots before cloud processing ².
Constrained Extraction: Pulling dates, amounts, or names from unstructured text without paying per-token fees.
On-Device Search: Building semantic search indices for personal notes or files that never leave your machine.

How to use it

The SDK is currently in beta and requires an Apple Silicon Mac running macOS 15.0+ with Xcode 16 installed ³.

Implementation is centered around the LanguageModelSession. It is strictly asynchronous:

import apple_fm_sdk as fm
import asyncio

async def classify_text(text):
    model = fm.SystemLanguageModel()
    if not model.is_available(): return "Unavailable"

    session = fm.LanguageModelSession()
    prompt = f"Is this SPAM or HAM? {text}"
    
    response = await session.respond(prompt)
    return str(response).strip()

Common gotchas

Working with on-device models is different from calling the OpenAI or Claude APIs. Here is what I’ve encountered:

Availability Check: You must always check model.is_available(). It can fail if the model hasn’t finished downloading or if Apple Intelligence is disabled in System Settings.
Serial Execution: While the Python code is async, the Apple Neural Engine (ANE) typically processes one inference request at a time. Parallelizing calls won’t make the hardware go faster.
Content Management: The model is stateless. You are responsible for managing the token limit in your LanguageModelSession.
Async Overhead: Integrating it into synchronous CLI scripts often requires a bit of asyncio boilerplate or a dedicated event loop runner.

Value

On-device AI changes the economics of software. When inference is free and private, you can apply “intelligent” logic to mundane tasks—like cleaning a mailbox or deduplicating photos—that were previously too small to justify a cloud API bill.

python-apple-fm-sdk - The official Python interface for Apple’s Foundation Models. ↩
On-Device Scene Analysis - Apple’s research into using local models for utility content detection. ↩
Apple Intelligence for Developers - Documentation on hardware requirements and framework adoption. ↩

A Logseq skill for your Agent

Wed, 18 Mar 2026 00:00:00 +0000

Logseq is my choice for personal knowledge management. It is an offline-first, local-only outliner ¹. When I’m working in the terminal with Gemini CLI or Claude Code, I often need to capture ideas, check my TODOs, or append a note to my daily journal.

I built a skill to bridge this gap.

What it does

The skill allows the agent to interact directly with the Logseq graph on my machine. It follows the Agent Skills open standard ², similar to the Strunk and White skill I wrote for prose review.

- Capture: “Add this to my journal” or “Remember this.”
Task Management: “Show my tasks” or “Add a TODO for tomorrow.”
Retrieval: Reading specific pages or searching recent journal entries.

The agent understands Logseq’s specific outline syntax—using tabs for nesting and bullets for blocks—and the :preferred-workflow :now workflow markers (NOW, LATER, DONE).

How it works

The skill is a markdown file with clear instructions on graph structure and file naming conventions. It uses standard unix tools like grep and find to navigate the journals directory efficiently.

Because the agent has direct access to the filesystem, it doesn’t need an API. It reads and writes the .md files in ~/Documents/Notes/Logseq/ directly.

Getting it

The skill is available as a GitHub Gist. To use it:

Create a directory in your project: .gemini/skills/logseq/ (or .claude/skills/logseq/).
Download the SKILL.md file into that directory.
Activate it by asking the agent to “Read my journal.”

The agent will then follow the instructions in the skill file to manage your notes and tasks without needing a plugin or third-party service.

Logseq - A privacy-first, open-source knowledge base. ↩
Agent Skills - An open standard for defining tools and capabilities for AI agents. ↩

A local AI mailroom

Wed, 18 Mar 2026 00:00:00 +0000

Promotional folders are digital landfills. We sign up once and receive daily “last chance” offers that bury important context. Traditional filters are too blunt; they can’t distinguish between a shipping notification and a coupon.

I built a suite of Python tools to act as a personal mailroom. It uses local AI to understand, organize, and prune Gmail.

How it works

The system acts as a bridge between your inbox and local inference engines. Metadata is synced to a local database before any analysis occurs to keep the API footprint small.

The Cleanup Workflow

graph TD
    A[Gmail Inbox] -->|Sync Metadata| B[(SQLite DB)]
    B -->|Pending Analysis| C{Local AI Engine}
    C -->|Apple FM SDK| D[Apple Intelligence]
    C -->|Ollama API| E[DeepSeek-R1]
    D -->|Decision: KEEP/DELETE| F[(SQLite DB)]
    E -->|Decision: KEEP/DELETE| F
    F -->|Trash Mode| G[Gmail API: Batch Modify]
    G -->|Move to Trash| H[Gmail Trash]

Local-first strategy

Privacy is the priority when dealing with personal email. The system uses a local-first fallback chain:

Apple Intelligence: Uses the apple_fm_sdk to hook into on-device Foundation Models ¹. It is fast, private, and requires no API keys.
DeepSeek-R1: A fallback running through Ollama ². It handles complex reasoning without sending data to a cloud provider.

The AI decision engine is simple. It reads the subject and snippet, then outputs a single word: KEEP or DELETE.

Smart organization

Manually creating Gmail filters is tedious. The system includes a discovery module that analyzes top senders and identifies patterns.

graph TD
    A[SQLite DB: Sender Stats] -->|Top 20 Senders| B{Apple Intelligence}
    B -->|Analyze Patterns| C[Proposed Rule Hierarchy]
    C -->|User Approval| D[Gmail API: Create Labels]
    D -->|Create Filters| E[Gmail API: Settings/Filters]
    E -->|Backfill| F[Label Existing Mail]

Instead of flat filters, it proposes a hierarchy (e.g., Cleanup/Retail/Clothing). Once approved, the script creates the labels and filters via the Gmail API ³ and backfills existing messages.

Accessing Gmail

To interact with Gmail, the tool uses the Google API Client Library for Python. It follows the OAuth 2.0 flow for installed applications, requesting a specific set of scopes: gmail.modify, gmail.settings.basic, and gmail.labels.

On the first run, it opens a local server for browser-based authentication. The resulting credentials are saved as token.json and automatically refreshed when they expire. To minimize API latency and respect rate limits, all operations—like trashing or labeling thousands of emails—are performed using batch requests, grouping up to 1,000 operations into a single call.

Unsubscribe auditing

The system scans for List-Unsubscribe headers and attempts to automate the process.

It also logs every unsubscription in a local SQLite database. A week later, a compliance audit checks if those senders have reappeared. If they have, it flags them as a violation. It turns the “unsubscribe” button from a suggestion into a tracked requirement.

Value

The cost of implementing software requirements has dropped. This project shows that unmaintained internal processes—like managing an inbox—can now be fixed by a single person with an AI agent.

We are moving away from monolithic cloud services that read our data to sell ads, toward local agents that read our data to save us time.

Apple’s on-device models are part of the Apple Intelligence suite announced in 2024, focusing on privacy-preserving personal context. ↩
DeepSeek-R1 is an open-weights reasoning model that achieved parity with proprietary models in early 2025. ↩
The Gmail API allows for fine-grained control over labels and filters through the users.settings.filters resource. ↩