DEV Community: Stephen McCullough

Indexatron Update: Context-Aware Analysis with Local Vision Models

Stephen McCullough — Mon, 06 Apr 2026 01:36:02 +0000

An update to the original Indexatron experiment

From Proof of Concept to Production

The original Indexatron answered a simple question: can local LLMs extract meaningful metadata from family photos? The answer was yes, but with caveats.

Feeding a vision model an image with zero context is like asking someone to describe a photo with no knowledge of the subjects, the era, or the occasion. The AI sees pixels. It doesn't see your grandmother's wedding or your family's Christmas traditions.

This update explores what happens when you bridge that gap by injecting domain knowledge into the analysis pipeline and transforming a generic image classifier into something that understands your specific archive.

The Problem with Context-Free Analysis

My first runs were disappointing. The AI would look at a 1974 photo titled "Auntie Wilma, Mum, Dad and Uncle Sam" and completely ignore that context. It knew there were people in the photo. It had no idea who.

Worse, I tried Llama 3.2 Vision (the newer, supposedly better model) and got output like this:

{
  "categories": ["family", "children", "family", "children", "family", "children"...]
}

The model had entered a repetition loop, producing thousands of repeated tags. It also generated oddly-phrased descriptions that weren't suitable for a family website. Not ideal.

The Solution: Context-Aware Prompting

Instead of asking "what's in this photo?", I started telling the AI what it should already know:

IMPORTANT: This photo includes Edmund McCullough, Isobel McCullough.
Use these REAL names in the 'people' array.

IMPORTANT: This photo is from 1974-08-14 (1970s).
Use this as the era decade with 'high' confidence.

This photo is from the album: "Old 35mm Slides"
Caption says: "Auntie Wilma, Mum, Dad and Uncle Sam"

The results improved dramatically. The AI now had guardrails.

Prompt Injection: Teaching the AI Your Domain

The real breakthrough was realising I could inject domain knowledge into the prompt itself. The AI doesn't know my family, but I can tell it.

Alias Resolution

Every family has nicknames. Rather than expecting the AI to understand "Mamie" means my Mum, I built an alias resolver that runs before the prompt is constructed:

FAMILY_ALIASES = {
    "nickname": "Real Name",
    # ... your family's nicknames
}

The system scans titles, captions, and gallery names for known aliases and injects the real names into the prompt. The AI then uses these names in its output.

Metadata as Directives

The prompt isn't just "analyse this photo". It's structured with explicit directives:

IMPORTANT: This photo includes [extracted names]. Use these names in the 'people' array.
IMPORTANT: This photo is from [date] ([decade]). Use this era with 'high' confidence.
This photo is from the album: "[gallery name]" - [gallery description]
Title: "[photo title]"
Caption: "[photo caption]"

This transforms the AI from a generic image analyser into something that understands your photos. It knows who might be in the frame before it even looks.

Model Comparison: LLaVA 7b vs Llama 3.2 Vision

I tested both models extensively. Llama 3.2 Vision is newer, larger (7.8GB vs 4.7GB), and benchmarks suggest it should outperform LLaVA on vision tasks. Reality proved more nuanced.

Aspect	LLaVA 7b	Llama 3.2 Vision
Speed	~27s per image	~60s+ per image
JSON Output	Mostly valid, occasional truncation	More verbose, sometimes malformed
Structured Output	Follows schema reliably	Occasionally enters repetition loops
Context Adherence	Good with explicit prompts	Variable, may need different prompting

LLaVA 7b's tighter, more predictable outputs made it better suited for this structured extraction pipeline. Llama 3.2 Vision's additional capabilities (stronger reasoning, better multi-turn dialogue) might shine in conversational or open-ended analysis tasks.

The lesson isn't that newer models are worse. It's that benchmarks don't tell the whole story. For constrained, schema-driven outputs on a local machine, the smaller model proved more reliable. Your mileage may vary with different prompting approaches or GPU acceleration.

Performance Optimisations

Several changes made the pipeline faster:

Image Resizing

Vision models don't need 4000x3000 pixel photos to understand what's in them. Resizing to 1024px max before analysis cut processing time without affecting quality:

max_dim = 1024
if max(img.size) > max_dim:
    img.thumbnail((max_dim, max_dim), Image.Resampling.LANCZOS)

Using Pre-Generated Variants

The Rails app already generates 1024px WebP variants for web display. Why download the original when a smaller version exists?

image_url: upload_variant_url(upload, :medium)  # 1024px, not :large (2048px)

WebP to JPG Conversion

LLaVA crashes on WebP images (segfault). Converting to JPG before analysis fixed this:

if output_path.suffix.lower() == ".webp":
    with Image.open(output_path) as img:
        img.save(jpg_path, "JPEG", quality=85)

Era Override: Trust the Metadata

The AI guesses photo era from visual cues: clothing, image quality, colour palette. It's often wrong. But I have the actual date for many photos from EXIF data or manual entry.

Rather than trust the AI's guess, I override it:

if metadata.get("date_taken"):
    decade = extract_decade(metadata["date_taken"])
    analysis_data["era"] = {
        "decade": decade,
        "confidence": "high",
        "reasoning": f"From actual date: {metadata['date_taken']}"
    }

Now a photo from 1974 is correctly tagged as 1970s with high confidence, regardless of what the AI thought.

Safety Filters

After the Llama 3.2 Vision incident, I added safeguards:

BLOCKED_TERMS = {"inappropriate", "terms", "filtered", "here"}
MAX_CATEGORIES = 20  # Prevents runaway repetition

Terms that shouldn't appear in a family photo context get filtered. Category arrays get capped to prevent repetition loops. The AI can still hallucinate, but it can't flood my family website with unsuitable content.

A Real Example

Here's an actual processing run:

Analyzing: YsbAlt.jpg
Context: Title: Auntie Wilma, Mum, Dad and Uncle Sam, Date: 1974-08-14
Waiting for llava:7b...
Response: 511 chars in 27.0s

LLaVA Response:
{
  "description": "Wedding group photo with bride and groom and guests",
  "location": {"setting": "outdoor", "type": "park"},
  "people": [{"name": "Auntie Wilma, Mum, Dad and Uncle Sam", "estimated_age": "adults"}],
  "categories": ["wedding", "celebration", "family", "special occasion", "1970s fashion"],
  "era": {"decade": "1974", "confidence": "medium"},
  "mood": "happy"
}

Overrode era with actual date: 1970s
Generated 768-dimensional embedding
Posted to API

The AI saw the context, identified it as a wedding photo, and the era was corrected to use the actual date. Not perfect (it put all four names in one person object) but usable.

What's Next

The search API issue is queued up. Once implemented, I'll be able to:

GET /api/uploads/search?person=Isobel+McCullough
GET /api/uploads/search?category=wedding&decade=1970s
GET /api/uploads/search?location=beach

Semantic search using the embeddings is also on the roadmap: find photos similar to a given photo, regardless of tags.

Lessons Learned

Context transforms capability. The same model produces dramatically different results when given domain knowledge. Don't ask AI to guess what you already know. Inject it into the prompt.
Model selection is task-specific. Benchmarks measure general capability, not fitness for your specific use case. Test with your actual data and requirements.
Hybrid approaches win. Let AI do what it's good at (visual analysis) while overriding it with ground truth where available (dates, known names). The best results come from human knowledge augmented by machine perception.
Defensive programming matters. Vision models can produce unexpected outputs: malformed JSON, repetition loops, unsuitable content. Build robust parsing and filtering from day one.
Optimise the right layer. Resizing images and using pre-generated variants had more impact on performance than model tweaking. Sometimes the boring optimisations are the most effective.

The Code

Both projects are on GitHub:

indexatron - The Python analysis service
the-mcculloughs.org - The Rails family photo site

Local vision models aren't magic. They're tools. The magic happens when you give them the context to understand what they're looking at.

A Self-Hosted Image Sharing Pipeline

Stephen McCullough — Wed, 01 Apr 2026 22:46:43 +0000

Image URLs break. You paste a screenshot into Teams, share the link, and six months later it's gone. Corporate firewalls block Imgur. Third-party services sunset features. The URLs you thought were permanent quietly rot.

I built Jotter to fix this — a Rails app that handles image uploads and returns short, stable URLs I control.

The Flow

Drop an image onto a macOS droplet (or run a CLI command), get a short URL on your clipboard. That's it.

The upload endpoint accepts multipart form data and base64 JSON (for iOS Shortcuts):

def create
  album = current_user.albums.find_or_create_by!(title: "Uploads")
  photo = album.photos.build(user: current_user)

  if params[:image_base64].present?
    decoded = Base64.decode64(params[:image_base64])
    # attach from decoded bytes...
  else
    photo.image.attach(params[:image])
  end
end

Authentication uses bearer tokens — SecureRandom.hex(32). CSRF verification is skipped for JSON requests with a valid token, so scripts and native apps don't need to fuss with form authenticity tokens.

Short URLs

Each photo gets a 6-character alphanumeric code with collision detection:

def generate_short_code
  loop do
    self.short_code = SecureRandom.alphanumeric(6)
    break unless Photo.exists?(short_code: short_code)
  end
end

62 characters, 6 positions — roughly 56 billion combinations. Won't be a problem for a personal tool, but the loop handles it gracefully anyway.

The short URL controller serves the actual image blob with disposition: :inline, so Slack and Twitter unfurl it properly without any OpenGraph gymnastics.

The CLI Glue

A small bash script ties it together:

response=$(curl -s -X POST "$JOTTER_URL/u.json" \
  -H "Authorization: Bearer $JOTTER_TOKEN" \
  -F "image=@$file")

short_url=$(echo "$response" | jq -r '.photo.short_url')
echo "$short_url" | pbcopy
osascript -e "display notification \"$short_url\" with title \"Jotter\""

There's also a compiled AppleScript droplet for drag-and-drop, plus an iOS Shortcut that base64-encodes photos from the share sheet.

Background Variants

Uploads return immediately. A Solid Queue job generates three variants — thumbnail (200px), medium (800px), large (1600px) — so the response feels instant even on larger files.

class ProcessPhotoJob < ApplicationJob
  def perform(photo_id)
    photo = Photo.find(photo_id)
    photo.image.variant(:thumbnail).processed
    photo.image.variant(:medium).processed
    photo.image.variant(:large).processed
  end
end

Worth It?

The whole thing runs on a single VPS. Every screenshot I share now has a URL I own, that won't expire, that isn't blocked by corporate proxies, and that I can move wherever I like. The friction went from "upload somewhere, copy link, hope it lasts" to "drop file, paste link."

Sometimes the best tool is the one you run yourself.

Maintaining Open Source in the AI Era

Stephen McCullough — Wed, 01 Apr 2026 22:45:25 +0000

I've been maintaining a handful of open source packages lately: mailview, mailjunky (in both Python and Ruby), and recently dusted off an old Ruby gem called tvdb_api. The experience has been illuminating - not just about package management, but about how AI is changing open source development in ways I'm still processing.

The Packages

mailview started because I missed letter_opener from the Ruby world. When you're developing a web application, you don't want emails actually being sent - you want to inspect them locally. In Rails, letter_opener handles this beautifully. In Python? The options were less elegant. So I built mailview: add the middleware to your FastAPI or ASGI app, and every outgoing email gets captured and displayed in a clean browser UI at /_mail.

mailjunky is the SDK for a transactional email service I use. I wrote both Python and Ruby versions because I work across both ecosystems and wanted a consistent interface. The Python version powers the email notifications in whatisonthe.tv, sending watchlist digests and update notifications.

tvdb_api is older. I wrote it years ago when I needed to fetch TV show metadata from TheTVDB. Recently I came back to it and found... well, it had aged poorly.

When Code Goes Stale

Opening tvdb_api after several years was humbling. The code still worked, technically, but it was written for a different era of Ruby. No keyword arguments where they'd make sense. Inconsistent error handling. Dependencies that had moved on. The API it wrapped had evolved through multiple versions.

This is the reality of open source maintenance that doesn't get discussed enough. You release something, people use it, and then life happens. You move to different projects. The ecosystem evolves. What was idiomatic becomes dated.

I spent a weekend modernising tvdb_api. Keyword arguments throughout. Proper exception hierarchies. Updated API support. Modern testing practices. The gem that emerged was recognisably the same tool but felt contemporary rather than archaeological.

The irony isn't lost on me that I did this modernisation with Claude's help. More on that shortly.

Ruby vs Python: A Tale of Two Package Managers

Here's where things get interesting. Publishing to RubyGems versus PyPI in 2026 is a study in contrasts.

RubyGems feels... creaky. The authentication flow is clunky. The web interface looks dated. I've hit mysterious failures that resolved themselves without explanation. The documentation assumes knowledge that new maintainers might not have. It works, but it feels like infrastructure that's been maintained rather than evolved.

PyPI, meanwhile, has embraced Trusted Publishing. You configure your GitHub repository as a trusted publisher, and your GitHub Actions workflow can publish packages without storing API tokens as secrets. The authentication happens via OpenID Connect - GitHub attests to the identity of the workflow, PyPI trusts that attestation.

The practical difference is significant:

# PyPI with Trusted Publishing - no secrets needed
- name: Publish to PyPI
  uses: pypa/gh-action-pypi-publish@release/v1

Compare this to RubyGems, where you're still managing API keys, storing them as secrets, and hoping you've configured the authentication correctly.

For mailview and mailjunky-python, I set up Trusted Publishing and the release process is now: tag a release, push the tag, and GitHub Actions handles the rest. For the Ruby packages, there's more ceremony involved, and I've had releases fail for reasons that weren't immediately clear.

I don't want to overstate this - RubyGems works and millions of packages depend on it. But PyPI's investment in modern authentication patterns has made the maintainer experience noticeably better.

AI Changed Everything (And I'm Not Sure How I Feel About It)

Here's where I need to be honest about something uncomfortable.

All of these packages were built with significant AI assistance. Claude helped write the initial implementations. It helped with test coverage. It modernised tvdb_api's Ruby patterns. It debugged edge cases I would have spent hours tracking down.

The productivity gains are real. What might have taken weeks of evening and weekend work happened in days. Features that I might have cut for time made it in. Test coverage that I might have skipped got written.

But.

I look at open source differently now, and I'm not sure it's for the better.

When I review pull requests on other projects, I find myself wondering: did a human think through this change, or did an AI generate it and a human click approve? When I encounter a bug in a library, I wonder: was this edge case missed because the AI-generated tests didn't think to cover it?

The social contract of open source has always been implicit: someone cared enough about this problem to spend their limited time solving it. That investment of human attention was a signal of quality, of thoughtfulness. It's why we trusted small libraries maintained by individuals - someone was paying attention.

AI disrupts this calculus. I can now create a package in an afternoon that would have taken weeks. But has the thoughtfulness kept pace with the speed? I've tried to maintain the same standards I would have without AI assistance, but I'm not certain I've succeeded. And I definitely can't evaluate whether other maintainers have.

The Testing Paradox

This concern crystallises around testing. AI is excellent at generating tests. Given a function, Claude will produce comprehensive test cases covering happy paths, edge cases, error conditions. The coverage numbers look great.

But test generation isn't the same as test thinking. When I write tests manually, I'm forced to think about how the code will be used. What assumptions am I making? What could go wrong? What would a user reasonably expect?

AI-generated tests cover the code that exists. Human-written tests often reveal the code that should exist. There's a subtle but important difference.

I've tried to mitigate this by reviewing AI-generated tests carefully and adding cases that emerge from my understanding of how the package will be used in practice. But I'd be lying if I said every test got that level of attention.

What I've Learned

A few things have become clearer through this experience:

Maintenance is the hard part. Writing the initial code is the easy bit. Keeping it current, fixing bugs, responding to issues, updating dependencies - that's where open source lives or dies. AI helps with maintenance too, but it doesn't solve the fundamental problem of limited human attention.

Modern tooling matters. PyPI's Trusted Publishing removed a category of release friction entirely. When releasing is easy, releases happen more often. When it's painful, packages go stale. This is boring infrastructure work, but it has real effects on ecosystem health.

AI is a force multiplier, not a replacement. The packages I'm happiest with are ones where I used AI to handle the mechanical work while staying engaged with the design decisions. The ones where I let AI drive too much feel... hollow, somehow. Technically correct but lacking in soul.

Transparency matters. I've started noting in my projects when AI was used significantly in development. Not as a warning, but as context. Users can decide for themselves what that means.

Where This Leaves Me

I'm going to keep maintaining these packages. People use them, and I use them myself. The experience has made me more thoughtful about what I'm building and why.

But I watch the open source ecosystem with more concern than I used to. The barriers to creating packages have dropped dramatically. That's good for getting solutions out there quickly. I'm less sure it's good for the long-term health of software we all depend on.

Maybe I'm worrying about nothing. Maybe AI-assisted development will become so normal that these concerns seem quaint. Maybe the tooling will evolve to help us distinguish thoughtful work from generated slop.

For now, I'm trying to hold myself to the standards I had before AI assistance was available, while being honest that the assistance exists. It's an imperfect balance, but it's the best I've found.

The packages are on PyPI and RubyGems if you want to use them. They work. I've tested them. Claude helped.

Make of that what you will.

The LLM Is the New Parser

Stephen McCullough — Wed, 01 Apr 2026 22:43:53 +0000

I spent the early 2000s writing parsers. HTML scrapers with regex that would make you cry. XML deserializers that handled seventeen flavours of "valid". CSV readers that knew a comma inside quotes wasn't a delimiter.

The pattern was always the same: the world gives you garbage, you write defensive code to extract meaning.

Then APIs won. JSON with schemas. Type-safe clients. The parsing era ended. We'd civilised the machines.

Now I'm building Indexatron, a local LLM pipeline for analysing family photos. LLaVA looks at an image, I ask for JSON, and I get... this:

json
{
"description": "A dog sitting on a wooden floor",
"categories": ["dog"],
"people": [
{"estimated_age": "Beer is an alcoholic beverage"}
]
}

python

The model wrapped JSON in markdown code fences. It put beer in the people array with an age field containing a Wikipedia definition. Sometimes the braces don't balance. Sometimes it returns YAML when you asked for JSON.

Sound familiar?

We're back to parsing unreliable output. The only difference is the garbage now comes from a neural network instead of a web server. The defensive patterns are identical:

# Strip markdown code blocks
if response.startswith("```

"):
    response = response.split("

```")[1]
    if response.startswith("json"):
        response = response[4:]

# Balance braces
open_braces = response.count("{")
close_braces = response.count("}")
if open_braces > close_braces:
    response += "}" * (open_braces - close_braces)

# Parse and pray
try:
    data = json.loads(response)
except JSONDecodeError:
    data = {"raw": response, "parsed": False}

Twenty years of progress and I'm back to "try to parse it, catch the exception, return something usable anyway."

The irony isn't lost on me. We built trillion-parameter models that can write poetry and explain quantum physics, but they can't reliably close a curly brace. The solution? Wrap them in the same defensive parsing code we wrote for Internet Explorer's HTML in 2003.

The LLM is the new parser. It turns unstructured data (images, documents, audio) into semi-structured output that you then parse into actually-structured data.

The more things change.

Lazy Loading Cache for whatisonthe.tv

Stephen McCullough — Wed, 01 Apr 2026 22:43:06 +0000

Working on whatisonthe.tv, I needed a caching pattern for film and star metadata lookups. The app pulls data from external APIs (TMDb for cast lists, film details) but only when the data doesn't exist in the database. A background worker fetches from the API and saves it to the database, avoiding repeated expensive API calls. The cache sits in front of the database to speed up reads.

The Problem

The app queries film and star metadata frequently - same films, same actors, multiple users browsing. Without caching:

Repeated database reads slow things down
API rate limits get hit quickly
External API calls are expensive (latency and cost)
Preloading everything wastes resources on data no one requests

The flow without caching:

User requests film metadata
Check database
If not in database, queue background worker
Worker hits API, saves to database
Return data to user
Next user requesting same film hits database again (slow)

How Lazy Loading Cache Works

The cache sits in front of the database and only the database. API lookups happen separately via background workers.

The flow with caching:

User requests film metadata
Check the cache first
If in cache and fresh, return it immediately (fast)
If not in cache, check the database
If in database, store it in cache and return it
If not in database, queue background worker to fetch from API
Worker fetches from API, saves to database
Next request will find it in cache or database (no API call needed)

The cache grows based on real usage. Popular films stay in cache, obscure ones get cached on first database hit. The background worker only runs when data is completely missing, avoiding expensive API calls for already-known films.

Implementation in Python

import time
from workers import enqueue_fetch_film

CACHE = {}
TTL = 300  # 5 minutes for film/star metadata

def get_film(film_id):
    cache_key = f"film:{film_id}"
    now = time.time()

    # Check cache first
    item = CACHE.get(cache_key)
    if item and now - item['ts'] < TTL:
        return item['data']

    # Cache miss - check database
    data = db.query_film(film_id)

    if data:
        # Found in database - cache it
        CACHE[cache_key] = {'data': data, 'ts': now}
        return data

    # Not in database - queue background worker to fetch from API
    enqueue_fetch_film(film_id)
    return None  # or return placeholder/loading state

# Background worker (runs separately)
def fetch_film_worker(film_id):
    # Hit external API (TMDb, etc)
    api_data = tmdb_api.get_film(film_id)

    # Save to database
    db.save_film(film_id, api_data)

    # Next request will find it in database and cache it

For whatisonthe.tv, this meant:

Popular films stay cached (no database or API hits)
First request for a film hits database only
Missing films trigger one API call via worker
All subsequent requests are cached
Saves API rate limits and costs

Why Use It

This pattern works well when:

External API calls are expensive (rate limits, latency, cost)
Reads are more common than writes
Slightly stale data is acceptable (film metadata doesn't change frequently)
You want a cache that maintains itself
You want to avoid extra infrastructure (Redis, Memcached)

The key benefit: API lookups only happen once per film. The database stores it permanently, and the cache speeds up repeated reads. If the cache is wiped (server restart, deployment), everything keeps working. It just warms up again based on traffic.

Trade-offs

Advantages:

Self-maintaining - no explicit invalidation logic
Minimal infrastructure
Database remains authoritative
Graceful degradation

Disadvantages:

First request after TTL expiry is slow (cache miss)
Memory grows unbounded without eviction policy
Not suitable for distributed systems (in-memory only)

For whatisonthe.tv, an in-memory cache with occasional misses is fine. If it scales beyond a single instance, Redis with the same pattern would work.

Summary

Lazy loading cache combined with database-backed storage and background workers is a safe and predictable pattern. API lookups only happen once per entity, the database stores it permanently, and the cache speeds up repeated reads.

For whatisonthe.tv, this means:

One API call per film (ever)
Database hits for first request after cache expiry
Cache hits for everything else
No wasted API calls
No rate limit issues

It's the right level of sophistication for a side project - solves the problem without introducing new ones.

Git Worktree for Multiple Branches

Stephen McCullough — Wed, 01 Apr 2026 22:42:56 +0000

Just learned about git worktree and it's genuinely useful.

Problem: Need to work on feature branch whilst also reviewing a PR or checking main. Usually means stashing changes and switching branches.

Solution: Multiple working directories for the same repo.

# Create a new worktree for a branch
git worktree add ../myrepo-feature feature-branch

# Now you have:
# ~/code/myrepo       (main branch)
# ~/code/myrepo-feature (feature branch)

Can have both open in different editors, run different dev servers, etc. Much cleaner than branch switching or having multiple clones.

Clean up when done:

git worktree remove ../myrepo-feature

List all worktrees:

git worktree list

Simple but effective.

Cypress Component Isolation Issues

Stephen McCullough — Wed, 01 Apr 2026 22:42:34 +0000

Working on a personal project, I hit a frustrating limitation with Cypress: component state bleeding between tests.

The Problem

Cypress mounts components in the same browser context across tests. Even with beforeEach cleanup, some state persists:

Event listeners accumulate
CSS-in-JS styles duplicate
Global window objects leak between tests
Memory usage grows linearly with test count

Example that failed intermittently:

describe('User form', () => {
  beforeEach(() => {
    cy.mount(<UserForm />)
  })

  it('validates email', () => {
    cy.get('[data-testid="email"]').type('invalid')
    cy.get('[data-testid="error"]').should('contain', 'Invalid email')
  })

  it('submits successfully', () => {
    cy.get('[data-testid="email"]').type('valid@example.com')
    cy.get('[data-testid="submit"]').click()
    // Fails intermittently - previous test's error message still in DOM
  })
})

Why This Happens

Cypress reuses the browser instance. Components unmount, but:

The iframe stays alive
JavaScript heap isn't cleared
Event listeners require explicit cleanup
Third-party libraries may not clean up properly

The Workaround

Force full remount between tests:

afterEach(() => {
  cy.window().then((win) => {
    win.location.reload()
  })
})

This works but adds ~500ms per test. With 200+ component tests, that's 100 seconds of wasted time.

Playwright Does This Better

Playwright's component testing uses isolated browser contexts per test. Each test gets:

Fresh browser context
Clean JavaScript heap
No state leakage
Parallel execution by default

Same test in Playwright:

test('submits successfully', async ({ mount }) => {
  const component = await mount(<UserForm />)
  await component.getByTestId('email').fill('valid@example.com')
  await component.getByTestId('submit').click()
  // Always works - completely isolated from previous test
})

No manual cleanup. No intermittent failures. No performance workaround.

Migration Considerations

Switching to Playwright would mean:

Rewriting 200+ Cypress tests (different API)
Learning new assertion patterns
Different debugging workflow
But: genuine test isolation and faster execution

The isolation model is compelling. Cypress is great for E2E, but for component testing, Playwright's architecture is superior.

Might be time to migrate.

Working with Claude: A Senior Developer's Honest Take

Stephen McCullough — Wed, 01 Apr 2026 22:42:12 +0000

I've been using Claude Code as part of my daily development workflow for several months now. This isn't a breathless endorsement or a dismissive rejection. It's an honest assessment from someone who's been writing software professionally for over two decades.

It's a Tool. Treat It Like One.

Claude is a tool. A genuinely impressive one, but still a tool. It sits in the same category as my text editor, my terminal, and my version control system. I find this framing helpful - not to diminish what it can do, but to approach it practically.

Some of the hype around AI assistants oversells what they are. Junior developers aren't obsolete. Senior developers aren't being replaced. What's actually happening is more interesting: certain categories of work have become dramatically faster, and that changes what's practical to attempt.

AI assistants are particularly good at boilerplate, repetitive transformations, exploring unfamiliar codebases, and acting as a thinking partner. They still need human judgement for architecture decisions and business context. That's not a criticism - it's just understanding where the tool excels.

The Workflow

My setup has evolved over these months. I've finally moved away from tmux after years of muscle memory. Ghostty with native splits handles my terminal needs now, and honestly, it's simpler. One less abstraction layer, one less thing to configure.

A typical session looks like this:

Left pane: Claude Code running in the terminal
Right pane: Shell for running tests, git operations, server logs
Editor: Neovim in a separate window (some habits don't change)

Claude handles the tedious bits. Writing test scaffolding. Generating boilerplate for new modules. Explaining what some legacy code does before I refactor it. Drafting commit messages (which I usually edit - it's verbose by default, but that's easy to fix).

The Game Changers

Three features have fundamentally changed how I work: planning mode, skills, and tasks. These aren't just conveniences - they've shifted how I approach problems.

Planning Mode

Before I discovered planning mode, I'd sometimes watch Claude charge off implementing something before I'd fully thought through the approach. Now, for anything non-trivial, I start in planning mode.

The workflow is: describe what I want to achieve, let Claude explore the codebase, and then review a structured plan before any code gets written. This catches architectural issues early. It surfaces questions I hadn't considered. It means we're aligned on approach before investing time in implementation.

For complex features, I'll spend fifteen minutes in planning mode refining the approach. That investment pays back tenfold by avoiding wrong turns and rework. It's like having a technical design review built into the workflow.

Skills

Skills are reusable prompts that encode workflow knowledge. I've built custom skills for my common tasks: code review, security audit, test generation, and more. Instead of explaining what I want each time, I invoke a skill and it applies consistent standards.

My /review skill knows how to examine git changes against the patterns I care about. My /audit skill applies security checks specific to my tech stack. These aren't just time savers - they're consistency enforcers. The review I get at 6pm after a long day is the same quality as the one at 9am.

The ability to chain skills is powerful too. I can run security audit, code review, and test coverage analysis in parallel, then synthesise the results. What used to be a morning's work happens while I grab a coffee.

Tasks

The task system changed how I approach larger pieces of work. When I'm implementing a feature that spans multiple files or requires several steps, I ask Claude to break it down into tasks.

Each task becomes a tracked unit of work. I can see what's done, what's in progress, and what's blocked. Claude updates task status as it works, so I always know where we are. When I step away and come back, the context is preserved in the task list.

For a recent project, I had a twelve-task implementation plan. Being able to work through it systematically, with clear progress tracking, made a complex change manageable. It's project management integrated directly into the coding workflow.

What Actually Helps

Exploration: When I'm dropped into an unfamiliar codebase, Claude can trace through call paths faster than I can grep. "Where does this function get called from?" is a question I used to spend twenty minutes on. Now it's seconds.

Boilerplate: Writing the fourteenth variation of a CRUD endpoint is mind-numbing. Claude handles it, I review and adjust. The code isn't clever, but it doesn't need to be.

Documentation: Drafting docstrings, README sections, or API documentation. I edit to match my voice, but having a solid starting point beats a blank page.

Thinking partner: Sometimes I explain a problem to Claude and realise the solution myself while typing. Other times, it suggests an approach I hadn't considered. Either way, it's valuable.

Learning unfamiliar libraries: When I need to use an API I haven't touched before, Claude provides working starting points. Better than Stack Overflow answers from 2019 that may or may not work with current versions.

Where Human Judgement Matters

Architecture: Claude can suggest architectures, and the suggestions are reasonable starting points. But the "right" architecture depends on team size, existing infrastructure, deployment targets, and factors that require human judgement to weigh.

Business logic: When the correct behaviour depends on understanding why the business works a certain way, I need to provide that context. Claude works with what it can see in the code.

Security-critical code: I review generated code carefully when it touches authentication, authorisation, or sensitive data. Trust but verify.

The Biggest Paradigm Shift I've Seen

I've been doing this long enough to have opinions about paradigm shifts. I remember when version control went from "nice to have" to essential. I watched the industry move from on-premise to cloud. I've seen languages rise and fall.

This is different. Not because AI is magic - it isn't. But because it changes the economics of certain tasks. Things that weren't worth doing because the effort exceeded the benefit are now tractable.

Writing tests for legacy code without tests? Used to be a multi-day investment that teams avoided. Now it's a few hours of guided generation and review. Documenting that internal tool nobody wants to maintain? Tedious but now practical. Exploring a new codebase before making changes? Used to take days of reading. Now I have a knowledgeable guide.

The shift isn't "AI writes code for you". It's "the effort required for certain tasks dropped significantly". That changes which projects are viable and which maintenance tasks actually get done.

Human in the Loop

Every piece of generated code gets reviewed. Every suggestion gets evaluated against what I know about the system. I modify a fair amount of what Claude produces - sometimes because it's wrong, more often because I want it slightly different.

This isn't a complaint about Claude. It's the nature of working with any tool that doesn't have your full context. Claude doesn't know that this codebase has a quirk where that function behaves differently than its signature suggests. It doesn't know that the team agreed to avoid that pattern last month. It doesn't know that this feature will be deprecated next quarter.

The value is in the collaboration. Claude moves fast on the mechanical work. I provide context, make judgement calls, and catch issues that require institutional knowledge. Neither of us would be as effective alone.

Practical Advice

If you're considering integrating AI tools into your workflow:

Invest in planning mode. It's tempting to skip straight to implementation, but the upfront investment in planning pays dividends.

Build skills for your common workflows. The time spent encoding your standards into reusable skills comes back quickly.

Use tasks for complex work. Breaking work into tracked tasks provides structure and makes progress visible.

Learn the tool's patterns. Claude has tendencies - certain stylistic preferences, default approaches. Knowing these helps you guide it effectively.

Stay engaged. The fundamentals still matter. Understanding algorithms, system design, debugging techniques - these inform how you evaluate and direct what the AI produces.

Conclusion

Claude Code has genuinely improved my productivity. The combination of planning mode, skills, and tasks has created a workflow that's more than the sum of its parts. It hasn't replaced thinking, judgement, or experience. It's amplified them.

This is the most significant shift in how I work since I started using version control. Not because the AI is doing my job - it isn't. Because it's handling the mechanical work well enough that I can focus on the parts that actually require experience and judgement.

It's a tool. A good one. And like any good tool, it rewards learning how to use it well.

Indexatron: Teaching Local LLMs to See Family Photos

Stephen McCullough — Wed, 01 Apr 2026 22:41:26 +0000

Status: ✅ SUCCESS
Hypothesis: Local LLMs can analyse family photos with useful metadata extraction

I've been building the-mcculloughs.org - a family photo sharing app. The Rails side handles uploads, galleries, and all the usual stuff. But I wanted semantic search - not just "photos from 2015" but "photos at the beach" or "pictures with grandma."

The cloud APIs exist. But uploading decades of family photos to someone else's servers? Hard pass.

Time for a science experiment - two apps working together.

The Experiment

I called it Indexatron 🤖

The goal: prove that Ollama running locally with LLaVA:7b and nomic-embed-text can:

Analyse photos - Extract descriptions, detect people/objects, estimate era
Generate embeddings - Create 768-dimensional vectors for similarity search
Process batches - Handle multiple images with progress tracking

Test Results

Metric	Value
Images Processed	3/3
Failed	0
Total Time	40.82s
Avg Time/Image	~13.6s

Sample Outputs

🐕 family_photo_03.jpg

Description: "A tan-coloured Labrador Retriever is sitting on a wooden floor indoors"
Categories: ["dog"]
Mood: calm
Processing Time: 14.73s

🍺 family_photo_02.jpg

Description: "A photo of a bottle of beer and a glass with frothy white head on top, placed on a table at a restaurant"
Location: Indoor restaurant
Objects Detected: Beer bottle (Kingfisher brand), glass with beer
Categories: ["beer", "restaurant"]
Processing Time: 14.2s

👔 family_photo_01.jpg

Description: "A man standing in an indoor conference room during a wedding reception"
Era Detected: 2010s (medium confidence)
Person: Male guest, 30s, wearing suit and tie
Categories: ["wedding"]
Processing Time: 11.89s

What Worked Well

LLaVA Vision Analysis

Correctly identified subjects (dog, beer, person)
Detected specific brands (Kingfisher)
Estimated era from visual cues
Provided useful mood/atmosphere descriptions

Embedding Generation

768-dimensional embeddings generated for all images
Based on analysis descriptions (semantic meaning)
Ready for similarity search when needed

Batch Processing

Progress bar with Rich library
Skip existing functionality
Combined JSON output

Quirks & Learnings

JSON Parsing Required Repair

LLaVA doesn't always output clean JSON. The analyser needed:

Code block stripping
Brace balancing
Type coercion for nested objects

Model Hallucinations

Some amusing observations:

The dog photo mentioned "clothing" and "fashion trends for pets" (the dog had no clothes)
Beer was classified under people array with estimated_age: "Beer is an alcoholic beverage"

These quirks don't break the system - robust parsing handles them.

Processing Time

~13.6 seconds per image is acceptable for batch processing. Real-time analysis would need:

Smaller model (llava:7b is the smallest)
GPU acceleration
Or async processing with user feedback

Development Approach

This was parallel development across two codebases - with very different approaches for each.

The Boring Bits: AI Agents for CRUD

The Rails API work? It's not exciting. Setting up API endpoints, adding pgvector, writing migrations, CRUD operations - I've done this hundreds of times. It's necessary scaffolding, but it's not where I want to spend my brain cycles.

So I let AI agents handle it. Claude Code with custom agents for code review, test writing, and documentation. The agents handled the boilerplate while I reviewed and approved. This is exactly what AI assistance is good for - augmenting the repetitive work so you can focus on what matters.

The Interesting Bits: README-Driven Development

Indexatron was different. This was an experiment - I needed to understand every piece, make deliberate choices, and document as I went. For this, I used README-driven development:

Write the README first - Document what the code should do before writing it
One branch per milestone - Each branch proves one thing works
Merge only when it works - No moving on until the milestone is complete
AI for documentation - Let agents help write up the results

README-driven development forces you to think through the design before coding. It's slower, but you end up with working code and documentation. Perfect for experiments where you need to prove something works.

Development Progress

Indexatron (Python) - The Experiment

README-driven development with one branch per milestone:

PR	Milestone	What It Proved
#5	Project Setup	Foundation ready
#1	Ollama Connection	Local LLM runtime accessible
#2	Image Analysis	LLaVA extracts useful metadata
#3	Embeddings	768-dim vectors for similarity
#4	Batch Processing	Scalable to many images

Each branch had to work before moving on. Prove it, merge it, move on.

Rails App - The Integration (Agent-Assisted)

While I focused on Indexatron, AI agents handled the Rails infrastructure:

PR	Feature
#60	AI Photo Analysis API with pgvector

Standard API endpoint, database migration, pgvector setup - all the CRUD that's been done a thousand times before. The agents wrote the code, I reviewed it, tests passed, merged. That's the right division of labour: agents handle the predictable, humans handle the novel.

Technical Stack

Ollama (local runtime)
├── llava:7b (~4.7GB) - Vision analysis
└── nomic-embed-text (~274MB) - Embeddings

Python 3.11+
├── ollama - API client
├── pydantic - Data validation
├── pillow - Image handling
└── rich - Console output

Next Steps

This proves the concept works. Future integration:

Rails API - Add endpoint for on-demand analysis
Database Storage - Save embeddings in PostgreSQL (pgvector)
Similarity Search - Find "photos like this one"
Face Recognition - Cluster photos by person (future model)

Conclusion

🤖 The robots can see our photos.

Local LLMs provide a privacy-preserving alternative to cloud APIs for photo analysis. The quality is good enough for family photo organisation, and the 768-dimensional embeddings enable future similarity search features.

Code

Repository	Description
swmcc/indexatron	Python service for local LLM photo analysis
swmcc/the-mcculloughs.org	Rails family photo sharing app

Full experiment results: RESULTS.md

Built with Ollama, LLaVA, and a healthy scepticism of cloud APIs.

Building a Personal Site with Astro

Stephen McCullough — Wed, 01 Apr 2026 22:41:15 +0000

After years of having various iterations of personal websites (and letting them languish), I decided to rebuild from scratch with Astro. Here's why and what I learned.

Why Astro?

I've built sites with Next.js, Gatsby, and plain HTML/CSS over the years. Each has its strengths, but for a personal site that's primarily static content, Astro hits a sweet spot:

Speed by default - Ships minimal JavaScript unless you explicitly need it
Content-focused - Built-in support for Markdown and content collections
Flexible - Can use React, Vue, or other frameworks when needed
Simple deployment - Static output works anywhere

The Setup

The project structure is straightforward:

/
├── src/
│   ├── content/     // Markdown content
│   ├── layouts/     // Page layouts
│   ├── components/  // Reusable components
│   └── pages/       // Routes
└── public/          // Static assets

Content collections make it easy to define schemas for different types of content (blog posts, notes, etc.) and get TypeScript validation for free.

What I Like

Content workflow is excellent. Write Markdown, commit, push, done. No CMS, no database, no complexity.

Performance is genuinely good. The homepage loads in under a second on a 3G connection. That's without any optimisation beyond Astro's defaults.

Dark mode was trivial. A bit of CSS custom properties and localStorage. No heavy theme provider or context needed.

What Could Be Better

TypeScript strictness can be overzealous. Sometimes the content collection types get in the way when you know what you're doing.

The docs assume familiarity with build tools. If you're coming from a simple HTML/CSS background, the learning curve might be steeper than necessary.

Lessons Learned

Start with content. I wrote the About and Now pages before styling anything. Helped clarify what the site actually needed to do.
Resist adding features. My first draft had tags, categories, search, and analytics. Stripped it all back. Can always add later if needed.
Automate deployment early. Set up GitHub Actions from day one. Removes friction from publishing.

Would I Recommend It?

For a personal site focused on writing? Absolutely. For a complex web app? Probably not the right tool.

Astro excels at what it's designed for: content-heavy sites that should be fast and simple to maintain. That's exactly what I needed.

If you're interested in the implementation details, the source code is on GitHub.

TypeScript Conditional Types for API Responses

Stephen McCullough — Wed, 01 Apr 2026 22:40:15 +0000

Quick pattern I keep using for API responses that can be either successful or error states:

type ApiResponse<T> =
  | { success: true; data: T }
  | { success: false; error: string };

// Helper to narrow the type
function isSuccess<T>(response: ApiResponse<T>): response is { success: true; data: T } {
  return response.success === true;
}

// Usage
const result: ApiResponse<User> = await fetchUser();

if (isSuccess(result)) {
  // TypeScript knows result.data exists here
  console.log(result.data.name);
} else {
  // And knows result.error exists here
  console.error(result.error);
}

The type guard makes the discriminated union much nicer to work with. No need for optional chaining or non-null assertions.

Dropping Down to Raw ASGI

Stephen McCullough — Wed, 01 Apr 2026 22:39:49 +0000

Building mailview, Mount looked like the obvious choice for attaching routes at /_mail. It wasn't.

The Problem with Static Mounting

Mount ties routing to application structure:

routes = [
    Mount("/_mail", app=mailview_app),
]

But mailview shouldn't exist in production. It captures emails, useful in development, a liability anywhere else. With Mount, you either include the routes or you don't. Conditional mounting means conditional route definitions, which leaks environment logic into your route table.

That's the deeper issue: Mount conflates what paths exist with what behaviour runs. Those are separate concerns.

Middleware Separates Routing from Runtime

Raw ASGI middleware moves the decision to runtime:

async def __call__(self, scope, receive, send):
    if not self.enabled:
        await self.app(scope, receive, send)
        return

    if scope["type"] == "http" and self._is_mailview_path(scope["path"]):
        await self._mailview_app(scope, receive, send)
        return

    await self.app(scope, receive, send)

The enable/disable logic lives in the middleware, not the route table. Add the middleware unconditionally; it handles the rest. In production, it's a single boolean check that passes everything through.

The payoff isn't just cleaner code. When disabled:

No routes registered, nothing to accidentally expose
No OpenAPI pollution, /_mail doesn't appear in your schema
No security surface, the endpoints don't exist, not just "protected"

What Surprised Me

Coming from Ruby's Rack, I expected more ceremony. Rack middleware is similar, call(env) returns [status, headers, body], but the response is synchronous and the contract is more rigid.

ASGI's receive/send pattern felt odd at first. You're not returning a response; you're calling send with message dicts. But it means you can stream, intercept partway through, do things that Rack makes awkward.

The other surprise: how little code it takes. The entire middleware is 40 lines, half of that docstrings and type hints. I expected to miss Starlette's conveniences more than I did.

The Boundary Bug Worth Remembering

One subtlety that bit me:

# Wrong, matches /_mail-archive, /_mailbox, etc.
if path.startswith("/_mail"):

# Right, exact match or child paths only
if path == "/_mail" or path.startswith("/_mail/"):

Obvious in hindsight. Easy to miss when you're pattern-matching paths.

When to Drop Down

I'd reach for raw ASGI middleware again when:

The sub-app needs conditional activation based on environment
You want zero footprint when disabled, no routes, no schema, no surface
The logic is simple enough that Starlette's abstractions add more than they save

For anything more complex, authentication, request modification, response transformation, I'd stick with Starlette's BaseHTTPMiddleware. But for "intercept these paths, let everything else through," raw ASGI is cleaner than I expected.