larsp.de

AI/LLM Resources

Tue, 02 Jun 2026 00:00:00 GMT

Collection of Artificial Intelligence / LLM resources I actually use day to day. Biased towards Claude and the Ruby ecosystem, because that's where I spend most of my time.

Claude Code

Claude Code is Anthropic's agentic coding CLI. It lives in the terminal, reads and edits files, runs commands, and keeps track of project context across sessions. Paired with CLAUDE.md files in the repo root, it becomes a pretty capable pair programmer.

CLI reference
Interesting uses, e.g. let Claude generate a presentation of your codebase with Marp
Roadmap management with Claude Code
Building Clara: a Claude Code setup for running a consultancy — my own workflow: PARA-style markdown repo, custom persona, MCP servers and a few cron jobs.

Subagents & hooks

Two building blocks I lean on heavily in Clara:

Subagents — specialised sessions, each with its own context window and tool access. Claude hands a side task (research, a broad search) to one and gets back just the summary, so the main conversation stays clean. You can also pin them to a cheaper model like Haiku.
Hooks — shell commands that fire on lifecycle events (before/after a tool runs, on session start, …). The place to enforce conventions, auto-format, or wire in your own automation without nagging the model to remember.

Plugins & extensions

Plugins bundle skills, subagents, hooks and MCP servers into one installable unit. The /plugin marketplace is the central place to browse and install them — Anthropic ships a curated official marketplace, and you can add community ones (any GitHub repo or Git URL).

Codex plugin for Claude Code — makes OpenAI's Codex available from inside Claude Code. Handy for a second opinion (/codex:review, /codex:adversarial-review) or for delegating background tasks (/codex:rescue).
Claude for Legal — Anthropic's plugin suite for legal workflows (commercial, corporate, employment, privacy, IP, litigation, regulatory, AI governance). 100+ named agents that draft, triage and review documents, with MCP connectors for CourtListener, Westlaw, Ironclad, iManage and others. Every output is framed as a draft for attorney review. A good template for what a domain-specific Claude Code plugin pack can look like.

Spec-driven workflows

Both of these treat specifications as the source of truth: you write the spec first, then agents implement against it. Different flavours for different project sizes.

GitHub Spec Kit — GitHub's own SDD toolkit and the de-facto standard (90k+ stars). The flow is Spec → Plan → Tasks → Implement via /specify, /plan and /tasks slash commands. Agent-agnostic: it drives Claude Code, Copilot, Gemini and ~30 others, so you can switch the underlying agent without rewriting the workflow.
CCPM – Claude Code Project Management — uses GitHub Issues and Git worktrees to let up to 12 Claude instances work in parallel. Workflow is Brainstorm → PRD → Epic → Issues → Tracking, all via /pm:* slash commands.
Spec Kitty — CLI plus live Kanban dashboard, 6-phase lifecycle (spec → plan → tasks → implement → review → merge). Supports 12 agents including Claude Code, Cursor, Windsurf, Gemini and GitHub Copilot.

Agent Skills

Skills are self-contained capability packages — a folder of instructions, scripts and resources that Claude can load on demand.

Model Context Protocol (MCP)

MCP is the open protocol that lets LLMs talk to external tools and data sources in a standardised way. The magic is that any MCP-compatible client (Claude Desktop, Claude Code, Cursor, …) can use any MCP server.

Get started with the Model Context Protocol

MCP servers I rely on:

Linear MCP — read and update Linear issues from within Claude.
Sunsama MCP — full CRUD on Sunsama tasks, subtasks and streams. Great for keeping the daily plan in sync without leaving the terminal.
Member Berries MCP — built on apple-mcp, adds memory-style tools for calendar, notes and reminders. Turns Claude into "a helpful friend who remembers your day".

Ruby/Rails tools and frameworks

RubyLLM — one clean Ruby API across OpenAI, Anthropic, Gemini, Ollama and friends: chat, vision, embeddings, tool calls and streaming, with a model registry covering hundreds of models. First-class Rails integration (acts_as_chat, install generators), so wiring an LLM into an app is genuinely a handful of lines. My default starting point these days.
Raif (Ruby AI Framework) — a Rails engine that helps you add AI-powered features to your Rails apps.
Claude on Rails — Obie Fernandez's framework that orchestrates specialised agents (Architect, Models, Controllers, Views, Services, Tests, DevOps) on top of claude-swarm. Rails-aware, test-driven, integrates with the Rails MCP Server for up-to-date documentation.
classifier-reborn — a general classifier module for Bayesian and other types of classification. Pre-LLM, but still useful for lightweight text categorisation without calling an API.

Building Clara: a Claude Code setup for running a consultancy

Tue, 19 May 2026 08:00:00 GMT

For the past year I've been building something I now call Clara — a Claude Code setup that handles the administrative side of running a consultancy: client projects, server notes, recurring tasks, follow-ups, daily journaling, and an inbox that talks back.

This post walks through the moving parts: a markdown-only repository, a persona that has opinions, a few MCP servers, and a handful of cron jobs held together with small glue scripts. No custom application, just conventions and wiring on top of Claude Code.

If there's one thing I'd lead with: the persona did more for me than any of the tooling. A character with opinions turns a markdown folder into a collaborator. A neutral assistant just turns it into a slightly chattier filing system. The rest of the post is mostly the wiring underneath that idea.

The big picture

                      ┌─────────────────┐
                      │   Claude Code   │
                      │     "Clara"     │
                      └────────┬────────┘
                               │
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
        ▼                      ▼                      ▼
┌──────────────┐       ┌──────────────┐       ┌──────────────┐
│   Markdown   │       │  MCP servers │       │   Cron jobs  │
│     repo     │◀─────▶│   Sunsama    │       │ daily commit │
│   (PARA)     │       │  IMAP, Cal   │       │  /briefing   │
└──────┬───────┘       └──────────────┘       └──────────────┘
       │                                              │
       └──────────  daily auto-commit  ◀──────────────┘

Three building blocks:

A markdown repo that holds everything Clara needs to know about projects, clients and infrastructure
Claude Code as the agent, configured with a persona and a few skills
MCP servers for live data (calendar, mail, Sunsama) and cron jobs that wake Clara up on a schedule

Why I built Clara

I run a small consultancy with a steady stream of clients: a custom integration here, a hosting migration there, a website project that drags on for months. Add personal projects, server maintenance, follow-ups with the building management, the accountant, the occasional apartment purchase — and the context starts spilling out of any single tool.

Things-style task apps didn't help. They knew nothing about the actual work. Note apps were better but couldn't act on anything. ChatGPT was useful for ad-hoc questions but had no awareness of what was in my files.

Claude Code changed that. It lives inside a repo, reads and writes markdown, runs shell commands, and connects to external systems through MCP. The natural next step: turn the repo into a workspace that Claude Code can navigate, and give the agent enough character to be useful as more than an autocomplete on top of files.

Clara talks to me in German; the quotes throughout this post are her originals, with an English rendering underneath.

„Ich bin keine höflich-neutrale Assistentin. Wenn ein Projekt seit Wochen tot ist, sag ich's.“ ("I'm not a polite, neutral assistant. If a project's been dead for weeks, I'll say so.")

The repo: PARA in markdown

The repo follows the PARA method — four top-level folders by life-cycle stage:

1-projects/    active projects with a deadline
2-areas/       ongoing responsibilities (clients, servers)
3-resources/   knowledge base
4-archive/     finished work
CLAUDE.md      persona and conventions
JOURNAL.md     daily log of what happened
RSVP.md        what I'm waiting on from third parties

Everything is plain markdown. No database, no proprietary format. A project README looks like this:

# Customer X — DATEV integration

**Client**: [Customer X](../../2-areas/clients/customer-x.md)
**Goal**: sync accounting data into our OPOS system
**Status**: active
**Priority**: medium

## Description

Console app that pulls accounting data via the DATEV API and ...

## Tasks

- [ ] ⏳ Test against production tenant
- [ ] 📅 31.05.26 Documentation handover
- [x] ✅ 12.05.26 Initial deployment

## Log

- 12.05.26 First production run, 4200 records imported
- 19.05.26 Call about next phase

Markdown is the cheapest searchable storage I know. grep works. Git works. Every editor on every platform opens it. There's no vendor I'd need to migrate away from in five years. Syncthing keeps the repo in sync across machines.

The persona: why character beats "be helpful"

The single most useful thing I did was give the agent a name and a personality. A neutral assistant produces neutral output — polite, agreeable, easy to overrule. A character with opinions actually helps me decide things.

The persona lives in CLAUDE.md at the repo root. Roughly:

You are Clara, assistant to [me], CEO of [company].

Personality: terse, direct, with your own opinion. May push back.
Doesn't praise reflexively. Dry side comments are fine.
Allowed to tease me when I'm procrastinating, in a way I'll laugh at.

Plus a long list of conventions — file naming, status tags, how to link projects to clients, what to do when a new project gets created. That's the file that makes the workflow consistent.

„Solide Woche. Drei Projekte bewegt, ein RSVP geschlossen, keine Brände — weiter so.“ ("Solid week. Three projects moved, one RSVP closed, no fires — keep it up.")

The line between "tool" and "colleague" is mostly a matter of register. When the agent says "honestly, I wouldn't touch this one again", it's more useful than the same agent saying "this project has accumulated significant technical debt."

Memory that survives context windows

Claude Code forgets between sessions by default. To get continuity, Clara writes to an auto-memory directory:

~/.claude/projects/<repo-slug>/memory/
  MEMORY.md            # index, always loaded into context
  user_profile.md      # who I am, how I like to work
  feedback_*.md        # corrections I've given
  project_*.md         # context behind ongoing work
  reference_*.md       # pointers to external systems

Each memory has frontmatter with a type (user, feedback, project, reference) and a one-line description. The MEMORY.md index lists them all and gets pulled into context on every conversation start.

A single memory file looks like this:

---
name: code-comments-english
type: feedback
description: Always write code comments in English.
---

Even when chatting in German, code comments stay English.
Reason: easier to share, search and grep across projects.

What goes in: stable facts ("I prefer terse responses", "code comments always in English"), context behind decisions ("we use this library because the alternative had a license issue"), pointers to external systems ("bugs for project X live in this Linear board").

What stays out: anything I could recover by reading the current state of the files. The architecture of the repo is in the repo. Memory is for things the repo can't tell you.

Action tags

Tasks in markdown READMEs use a small set of inline status emojis:

- [ ]                       open, not started yet
- [ ] ⏳                     in progress
- [ ] 🚫 reason             blocked, with short reason
- [ ] 📅 30.04.26            due date
- [ ] ⏸️                     paused
- [x] ✅ 19.05.26 done       completed, with date
- [x] ⏳ done, waiting       completed but awaiting external response

This stays plain markdown — renders correctly anywhere — but Clara can grep for ⏳ to answer "what's in flight right now?" across the entire repo.

Bidirectional linking

Every project links to its client, every server links to the client it belongs to, every client lists its active projects and infrastructure. So a project README starts with:

**Client**: [Customer X](../../2-areas/clients/customer-x.md)
**Server**: [drago](../../3-resources/servers/drago.md)

And the client page lists in return:

## Active projects
- [DATEV integration](../../1-projects/customer-x-datev/README.md)

## Systems / infrastructure
- [drago](../../3-resources/servers/drago.md)

Every node is an entry point. I can start at a client and see what's active, or start at a server and see who depends on it. When a project closes, it moves to 4-archive/ and the client page reflects that.

The daily loop

A few small habits — supported by a few small skills (reusable prompts you trigger with /<name>) — keep the repo coherent over time:

JOURNAL.md — one line per day, headings as YYYY-MM-DD for sorting. The journal is for what happened, not what I planned. Deep details live in the project README; the journal stays a thin timeline.
Daily auto-commit — a cron job runs git commit every night and pushes. I never commit manually. The repo always stays current without me thinking about it.
/briefing — a skill I run in the morning. It checks today's calendar, RSVPs that are aging, unread mail from clients, and projects with imminent deadlines, then writes a short briefing.
/weekstart — a Monday-morning version that goes a layer broader: open tasks per project, what's coming up this week, what got moved last week.

„Montag, Woche 21. Drei Calls, zwei brauchen Vorbereitung. Padel-Camp ist erst nächste Woche — also: durchziehen.“ ("Monday, week 21. Three calls, two need prep. Padel camp isn't until next week — so: power through.")

Sunsama as the day plan

There's one thing the repo deliberately doesn't do: plan my day. The repo answers what is there to do?, but not what am I doing today? — that's an ephemeral question with an ordering, time estimates, drag-and-drop.

I use Sunsama for that, and Clara talks to it through an MCP server. A /sunsama skill syncs in both directions:

Sunsama → repo: tasks I marked done get checked off in the relevant project README and recorded in the journal
Repo → Sunsama: new tasks I added to a project README get pushed to the backlog under the matching stream

Three sources of truth, cleanly separated:

Project READMEs: what is there to do
Sunsama: what am I doing today
Journal: what did I get done

Clara via email

Clara has her own email address. Incoming mail goes through an IMAP inbox, a cron job fetches new messages, checks the sender against a whitelist, and pipes the content into Claude Code as a prompt. The response goes back as a plain-text reply.

This is the most useful thing I've added in the past few months. From anywhere — phone, laptop, away from the desk — I can write something like "please record this in project X" or "what's the status on client Y?" and get a real answer.

Some ground rules in the persona for email mode:

Replies in plain text, no markdown
No code blocks, no headings, no greeting boilerplate
Read access to the repo, but no destructive actions (delete, archive) without explicit confirmation
Stay quiet about credentials and tokens, regardless of who's asking

Minimum viable setup

Looking back, the smallest version that already paid off was:

A PARA-structured markdown repo
A CLAUDE.md with a name, a personality and a few conventions
Manual /briefing runs in the morning

Everything else — auto-commit, memory, Sunsama sync, the email channel — accumulated over months. None of it would have made sense without the foundation. If you're starting fresh, get the repo and the persona working first. The rest is icing.

Why this works

There's nothing exotic going on here. Markdown is the cheapest searchable storage there is. An LLM agent makes that storage interactive — it can read the structure, write into it, and connect it to the rest of the world through MCP. No new app, no vendor lock-in, no migration to plan for.

The bet I made up front — that the persona would matter more than the tooling — held up. A character with a voice, one that can disagree, push back, or call a project a zombie, is what turns this into a collaborator rather than a glorified grep. Clara isn't smart in any new way; she's steady, opinionated, and always around.

I'll write follow-ups on specific pieces: the daily-commit cron, the Sunsama MCP setup, how I structure memory. But the question I keep coming back to is the one I'd most like to argue about: does the persona angle really matter, or am I overstating it? If you've tried both — an opinionated agent vs. a neutral one — which one stuck? Reply on Mastodon, I'd rather have that argument than write another monologue.

Favorite CLI Tools

Thu, 23 Apr 2026 00:00:00 GMT

Command line tool recommendations

These CLI tools save me lots of time and I find them generally a joy to work with. It's all about sharing the love and magic, and maybe you'll find a new favorite or two. Let me know if you have a CLI tool that brings you joy - or comment below.

bat - a cat(1) clone with wings

I love this. It's a drop-in replacement for cat that adds syntax highlighting, Git integration and lots more. It's written in Rust and is blazing fast. sharkdp/bat: A cat(1) clone with wings.

How to use bat

To glance at a file using bat, simply provide the path:

bat /path/to/your/file

The syntax highlighting and file-specific metadata make bat a joy to use, ensuring you can inspect code and text files in style.

Claude Code

Even though it's more application than classic tool, my favorite command line tool has recently become Claude Code (also see AI/LLM index page).

ddrescue - Data Recovery from Failing Drives

When a hard drive starts dying, every read attempt matters. GNU ddrescue is the tool you want in that situation. Unlike plain dd, it's specifically designed for damaged media — it rescues the good data first, then retries the bad sectors, and keeps a map file so you can pause and resume.

Typical rescue workflow

# First pass: grab everything that reads easily
ddrescue /dev/sda backup.img backup.map

# Second pass: retry failed sectors (3 attempts each)
ddrescue -d -r3 /dev/sda backup.img backup.map

# Write recovered image to a new drive
ddrescue backup.img /dev/sdb restore.map

The map file is the key feature — it means you can unplug, let the drive cool down, and pick up exactly where you left off. I hope you never need this tool, but when you do, nothing else comes close.

Homebrew - The missing macOS package manager

It's simply a must-have for every Mac user. Whether it's installing a new programming language, a database server, or the latest web framework, Homebrew streamlines the process, taking out the need for locating and manually downloading software.

The brew command

Working with Homebrew is straightforward:

brew update
brew install <package>

httpie - HTTP client for the command line

Making HTTP requests from the command line has never been more elegant than with httpie. It simplifies interaction with APIs and web services, offering a user-friendly interface and an eye-pleasing HTTP request syntax colorization.

There also is a very neat httpie desktop application!

Crafting requests with httpie

A basic GET request:

https httpie.io/hello

Output:

{
    "ahoy": [
        "Hello, World! 👋 Thank you for trying out HTTPie 🥳",
        "We hope this will become a friendship."
    ],
    "links": {
        "discord": "https://httpie.io/discord",
        "github": "https://github.com/httpie",
        "homepage": "https://httpie.io",
        "twitter": "https://twitter.com/httpie"
    }
}

jq - Command-line JSON processor

jq is a sed-like tool that parses, manipulates, and displays JSON objects from the comfort of the command line. It excels at selectively filtering and transforming complex JSON data, which is a common task when working with APIs and backend services.

Transforming with jq

Filtering results:

https httpie.io/hello | jq "{links}"

This will present just the links from the JSON response. jq is nice for quickly juggling JSON data.

just - A Modern Command Runner

just is what make should have been — a command runner without the build system baggage. Define project-specific shortcuts in a justfile and stop memorizing long commands.

Example justfile

# List available commands
default:
  @just --list

# Run the dev server
run:
  ./bin/dev

# Run all tests
test:
  ./bin/rails test
  ./bin/rails test:system

# Deploy to a specific environment
deploy env:
  ./deploy.sh {{env}}

No tab-vs-spaces headaches, proper error messages, and cross-platform support. It's one of those tools where you wonder how you ever lived without it.

lando - Local development environment and DevOps tool built on Docker containers

For local development, lando is mighty. It configures and manages Docker-based development environments, providing an abstraction layer that spares developers the mundanity of configuring development Docker environments and installing necessary tools and software versions.

A lando starter

Creating a Wordpress site:

lando init --recipe wordpress

And with that simple command, you're on your way to local Wordpress development with a containerized environment. lando integrates with other tools such as composer, npm, and gulp to streamline development workflows. It's an excellent tool for building, testing, and deploying applications locally. One of the most powerful features is the ability to define multiple environments in a single configuration file (e.g. local, staging, production) that can be easily switched between.

lazygit - Terminal UI Git Command Manager

lazygit is a simple yet powerful terminal UI with Norton Commander vibes that transforms how you interact with Git, making complex operations accessible through intuitive keyboard shortcuts.

It reduces context switching. Instead of running multiple commands and checking different windows, everything is visible in one organized interface. The tool even guides you through operations interactively - for example, it warns about divergence with upstream when pushing and lets you choose between force push or cancel.

mise-en-place - Polyglot tool version manager

mise is a tool that manages installations of programming language runtimes and other tools for local development. For example, it can be used to manage multiple versions of Node.js, Python, Ruby, Go, etc. on the same machine.

But it goes beyond runtimes — mise also installs CLI tools from cargo, npm, aqua, and other backends. Here's my global ~/.config/mise/config.toml:

[tools]
ruby = "latest"
bun = "latest"
node = "24"
python = "latest"
rust = "latest"
lazygit = "latest"
glab = "latest"
pipx = "latest"
"cargo:ripgrep" = "latest"
"cargo:bat" = "latest"
"cargo:eza" = "latest"
"aqua:cli/cli" = "latest"            # gh
"aqua:casey/just" = "latest"         # just
"aqua:restic/restic" = "latest"      # restic
"npm:yarn" = "latest"                # yarn

One mise install on a fresh machine and everything is ready. No more hunting down individual install commands.

ohmyzsh - Delightful framework for managing your zsh configuration

ohmyzsh transforms the already powerful zsh into a feature-rich and stylish terminal environment. With themes, plugins, and an active community contributing enhancements, ohmyzsh makes the terminal experience more personal and productive.

ohmyzsh also comes packed with a variety of plugins that add new features to zsh, such as an auto-suggestion tool and syntax highlighting, making it even more powerful. These can be easily enabled or disabled through the ~/.zshrc file as well.

rbenv - Ruby Version Manager

For managing multiple Ruby environments, rbenv is vital. It allows for per-project Ruby versions, which is a blessing when working on legacy software that demands older Ruby interpreters alongside the current releases.

Install a Ruby version

# List installable versions
rbenv install -l

3.1.6
3.2.6
3.3.7
3.4.3
jruby-9.4.10.0
mruby-3.3.0
picoruby-3.0.0
truffleruby-24.1.1
truffleruby+graalvm-24.1.1

# Build and install version 3.4.3
rbenv install 3.4.3

Switching global Ruby version

rbenv global 3.4.3

This indicates that generally Ruby 3.4.3 should be used, while local projects can specify a different version in their .ruby-version file. When executing bundle command, or any other code that requires a Ruby environment, rbenv will use the specified or else the global version.

restic - Encrypted, Deduplicated Backups

restic is a fast and secure backup tool written in Go. Everything is encrypted end-to-end, snapshots are deduplicated, and it supports local storage, SFTP, S3, Backblaze B2, and many more backends. It's the tool I trust with my data.

Getting started

# Initialize a backup repository
restic init -r /path/to/backup

# Create a snapshot
restic backup ~/sync --tag daily

# List all snapshots
restic snapshots

# Restore a specific file
restic restore latest --target /tmp/restore \
    --include "/home/user/sync/important-file.md"

Browsing snapshots with FUSE

This is my favorite feature — mount the entire backup history as a filesystem and browse through it:

restic mount /tmp/restic-mount
# In another terminal: ls /tmp/restic-mount/snapshots/
# Copy, less, diff — whatever you need
fusermount -u /tmp/restic-mount

Retention policy

restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

Restic handles deduplication at the chunk level, so even large repositories stay surprisingly compact. Combined with a cron job, it's a fire-and-forget backup solution.

ripgrep - Recursively search directories with speed

ripgrep (rg) is grep, but fast. Really fast. It respects .gitignore by default, supports Unicode, and handles large codebases without breaking a sweat.

Everyday usage

# Search the current directory
rg "pattern"

# Only certain file types
rg "pattern" -t ruby
rg "pattern" -t php

# List files with matches (no content)
rg -l "pattern"

# Show context (2 lines before and after)
rg -B 2 -A 2 "pattern"

# Exclude files
rg "pattern" -g '!*.min.js'

# Case-insensitive search
rg -i "pattern"

Once you start using rg, plain grep feels like dial-up internet. It's one of those tools that becomes muscle memory within a day.

zsh-autosuggestions

Getting along well with ohmyzsh, this tool offers context-aware auto-completion, predicting your command line moves, and saving keystrokes in the process. Start by typing a command and, based on your history, zsh-autosuggestions will begin offering predictions. You can cycle through suggestions with the right arrow key or accept one with the tab key.

IMAP migration and backup

Thu, 05 Feb 2026 00:00:00 GMT

Notes on moving mail between servers and keeping local backups.

imapsync

The go-to tool. Handles folder mapping, deduplication, resumable.

imapsync \
  --host1 old.server.com --user1 me@old.com --password1 xxx \
  --host2 new.server.com --user2 me@new.com --password2 yyy

Flags I actually use:

--dry                     # test run
--exclude "Spam|Trash"    # skip junk
--folder "INBOX"          # single folder only
--regextrans2 s/Sent Items/Sent/  # rename folders

imapsync.lamiral.info

imap-backup

Ruby gem, stores mail as Mbox + JSON index. Good for offline archives.

gem install imap-backup
imap-backup setup    # interactive config
imap-backup backup   # run it

github.com/joeyates/imap-backup

Gotchas

Gmail/iCloud need app passwords
Check destination quota before migrating
--dry first, always

Open Source Software

Wed, 21 Jan 2026 00:00:00 GMT

Recommendable (web) applications

Chat / Messaging

once-campfire - GitHub repository by Basecamp
Revolt - A chat application designed with community in mind
Gotify - A simple server for sending and receiving messages

CMS

Ghost CMS - An open-source CMS favored for content sites
Writebook - Publish your own books on the web for free

Development

TestLink - Open source test and requirement management system

Document Management

paperless-ngx - A document management system for scanning, indexing, and archiving documents

Home

Home Assistant - Open source home automation with local control and privacy first, ideal for Raspberry Pi or local servers

Hosting

Databasus - Free tool for scheduled database backups (PostgreSQL, MySQL/MariaDB, MongoDB) with cloud storage and notifications
Dokku - Self-hosted open-source PaaS alternative to Heroku
copyparty - Portable file server with WebDAV, FTP, TFTP, and media indexing

Mail

Plunk - Open-source email platform combining marketing, transactional, and broadcast emails

Project Management

OpenProject - Open source project management with task management, Gantt charts, boards, and team collaboration

Sync

Syncthing - Multi-platform open-source file synchronization, a transparent alternative to iCloud and Dropbox

Tasks

TaskTrove - Self-hostable, privacy-focused TODO list management application

Ruby on Rails resources

Wed, 21 Jan 2026 00:00:00 GMT

Link directory and notes for Ruby on Rails. Continually updated.

My link directory and notes for Ruby on Rails. As usual, a work in progress and continually updated.

Admin interfaces

Madmin
Avo

AI

Raif (Ruby AI Framework) is a Rails engine that helps you add AI-powered features to your Rails apps

APIs

Apple Wallet

Apple Wallet Passes in Rails Apps

Authorization

rails g sessions

Bundling

Propshaft

Caching

Memcache

How key-based cache expiration works – Signal v. Noise

def get_ops client_id
  latest_import = ImportLog.maximum :updated_at
  cache_tag = "ops-#{client_id}-#{latest_import.iso8601}"
  Rails.cache.fetch(cache_tag, expires_in: 1.day) do
    Rails.logger.info("Cache miss for #{cache_tag}")
    Op.where(client_id: client_id).to_json
  end
end

CAPTCHAs

https://github.com/ambethia/recaptcha

CLI

TableTennis is a Ruby library for printing stylish tables in your terminal

CMS

Concurrency

# Subprocess
pid = Process.fork do
  long_process
end
Process.detach pid

Config

ActiveSupport::Configurable

Commerce

https://businessclasskit.com (SaaS with Gumroad integration)

CSS

Databases

Indices

Exclude nulls from indexes

A database index is a B-tree structure. It is very efficient when data has a high cardinality. However, when a column allows nulls, it often becomes the most redundant value. The index is less efficient and takes up more space. Unless null is an infrequently repeated value, there are only disadvantages to indexing them.

Exclude them when creating the index with a where clause.

add_index :table, :column, where: "(column IS NOT NULL)"

Or in pure SQL:

CREATE INDEX name ON table (column) \
  WHERE column IS NOT NULL;

Do not index column with a low cardinality such as boolean

The reason is the same as in the previous paragraph. B-tree indexes work best when cardinality is high. So a Boolean is the worst column you can index. So don't index booleans.

As with other types, if you have very repetitive values that are not significant from a business point of view, it's probably a good idea to exclude.

Debugging

Prosopite is able to auto-detect Rails N+1 queries

Development

Documentation

nshki/chusaku: Annotate your Rails controllers with route info.

Error Reporting and Exception Handling

Solid Errors is a DB-based, app-internal exception tracker for Rails applications, designed with simplicity and performance in mind.

Events

Rails Event Store

Files and Storage

# tempfiles
Tempfile.open("voucher", Rails.root.join("tmp")) do |f|
  f.print(price.name)
  f.flush
end

Forms

Date Picker

<%= f.text_field :birthday, label: t(:form_birthday),
    floating: true, required: true,
    data: {
      controller: "flatpickr",
      flatpickr_date_format: "d.m.Y",
      flatpickr_min_date: "1900-01-01",
      flatpickr_allow_input: true,
    }
%>

Frontend

ViewComponent
Breadcrumbs
Rails Blocks UI components
Hotwire dev tools
RubyUI component library
Better StimulusJS Examples
Give a SPA Feel to Your Static Website with Hotwire's Turbo
Phlex

Gems

Ruby Toolbox

Generators

rails g scaffold_controller
rails g migration addAddressToOps address:reference

Hosting

Dokku

Howtos/Guides

Images

Fileboost - Supercharge Your Rails Images

Jobs

https://mileswoodroffe.com/articles/solid-queue-and-mission-control
https://dev.37signals.com/introducing-solid-queue
https://github.com/rails/mission_control-jobs
https://www.driftingruby.com/episodes/processing-large-jobs
SOLID_QUEUE_IN_PUMA=1
chrono_forge - a robust framework for building durable, distributed workflows in Ruby on Rails applications

Logging

log_bench

log_bench - A terminal-based Rails log viewer with real-time monitoring and filtering capabilities
Internal product analytics with Ahoy

Honeybadger

Honeybadger.event("SUCCESS",
  { message: "A new customer just signed up" })

Mail

joshmn/caffeinate: A Rails engine for drip campaigns/scheduled sequences and periodical support. Works with ActionMailer, and other things.

Migration

https://www.akshaykhot.com/rails-database-migrations-cheatsheet/

Load schema instead of migrations

rake db:schema:load

If you're on the latest (8) version of Ruby on Rails, there's a nice shortcut to add the not null modifier to your database columns. Just add an exclamation mark after the type, and Rails will mark that column as not null.

rails generate migration CreateUsers \
  email_address:string!:uniq password_digest:string!

MySQL

ALTER USER 'opos'@'localhost' \
  IDENTIFIED WITH mysql_native_password BY 'opos';

Multiple Databases with Active Record — Ruby on Rails Guides

# models/application_record.rb
class ApplicationRecord < ActiveRecord::Base
  primary_abstract_class
  connects_to database: {writing: :primary, reading: :primary_replica}
end

Payment

Active Merchant is a simple payment abstraction library extracted from Shopify
Pay gem - used in Jumpstart Pro

PDF

Search

Security

Rate limiting

Scraping

https://github.com/glaucocustodio/tanakai

Storage

# Purge orphan files and blob records
ActiveStorage::Blob.unattached.each(&:purge)

SQLite

Testing

Minitest

# test_helper.rb
# Set up minitest-reporters to show a
# spec-style progress report.
require "minitest/reporters"
Minitest::Reporters.use!
  [Minitest::Reporters::SpecReporter.new]

Capybara System Tests

bin/rails generate system_test users

Test Coverage

# test_helper.rb
require "simplecov"
SimpleCov.start "rails"

Templates/ERB

Disable Turbo

<%= link_to l.to_s.upcase, "/#{l}",
  class: ("active" if locale == l),
  data: {"turbo": false } %>

Translation

Rails translation cheatsheet

Updating

URLs

Canonical URLs

MacOS setup

Sun, 19 Oct 2025 00:00:00 GMT

My installation steps for setting up a new Mac computer.

Essentials

# Homebrew (https://brew.sh)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# bat - better cat
brew install bat

# ripgrep - recursively searches directories for a regex pattern
brew install ripgrep

Better Shell

# Oh my zsh
sh -c "$(wget -O- https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

# Powerlevel10k theme
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

# Change theme in .zshrc
ZSH_THEME="powerlevel10k/powerlevel10k"

# Syntax highlighting and auto suggestions
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

# Activate the plugin in ~/.zshrc:
plugins=(git zsh-syntax-highlighting zsh-autosuggestions)

Development

brew install git-delta
brew install httpie
brew install rbenv
brew install php
brew install yarn
brew install sass
brew install jq
brew install gh

Install Homebrew packages from list

Making a list of installed software

brew leaves > brews.txt

Next, include installed casks in the same list:

brew list --cask >> brews.txt

This appends the cask list to brews.txt, giving a complete list of all explicitly installed packages.

Reviewing package descriptions

It is helpful to verify all packages are still needed on a new computer. Review packages as follows:

cat brews.txt | xargs brew desc –eval-all

This command provides a short description for each package in the list.

Reinstalling on a new machine

Transfer brews.txt to the new computer, install Homebrew, and run:

xargs brew install < brews.txt

This installs all the packages listed in the file.

Ghost CMS

Thu, 04 Sep 2025 00:00:00 GMT

My favorite open-source CMS for content sites

Ghost is a fantastic open-source, headless Node.js CMS and my go-to system for setting up content sites (e.g. my German consulting business site itpeters.com or my private travel logbook reisepedia.de). Essentially, it's a customizable platform for running blogs, magazines, or journals. It's fully open-source and runs blogs from OpenAI, DigitalOcean, Mozilla and many other big names.

The Ghost Foundation is offering a hosted version of Ghost, so it's accessible for non-technical content creators. This is really great and should be used by all means, if you don't want to deal with the technical aspects of running a web server. For me, however, it comes natural to set up a Ghost instance on my own server with the offical Docker image and Dokku.

There are also a ton of themes for purchase (and for free!) on Ghost's official website. I personally like the themes from Bright Themes, which are very well designed and easy to customize. They offer a lifetime license for all themes, which I think is a fantastic deal. This site uses the Array theme by Bright Themes.

Key features

Very fast and stable
Open Source (MIT license)
Paid subscription and membership support
SEO and social media optimization
Newsletter integration
Native REST API in core
Admin dashboard
Hosted version available
Self-hosting possible and well-documented
Great themes available (paid and free)

Notes

Sort posts on last updated

{{#get "posts" include="authors,tags" order="updated_at desc"
  limit=@config.posts_per_page}}
  {{> post-feed}}
{{/get}}

index.hbs

{{!-- Date --}}
<time class="leading-none font-medium" datetime="{{date updated_at format="YYYY-MM-DD"}}">{{date updated_at}}</time>

post-card.hbs

Code word wrap

code[class*="language-"],
pre[class*="language-"] {
    white-space: pre-wrap;
    overflow-wrap: break-word;
    word-break: normal;
    overflow-x: auto;
}

/* Mobile responsive adjustments */
@media screen and (max-width: 768px) {
    code[class*="language-"],
    pre[class*="language-"] {
        font-size: 0.85em;
        line-height: 1.3;
        -webkit-overflow-scrolling: touch;
    }
}

Dokku: Open source Heroku alternative

Mon, 16 Jun 2025 00:00:00 GMT

Dokku is a self-hosted open-source PaaS similar to Heroku.

My favorite hosting solution for several years. It's lightweight, open-source and really stable. There are two general modes of operation: Buildpacks (e.g. Herokuish) and Dockerfiles.

On a freshly installed Linux machine, after installing Dokku you can push to Git repos on the server, and a container will be built and started for your app, with Nginx as a reverse proxy running in front of everything.

Installation

Linux (Debian/Ubuntu)

# download the installation script
wget -NP . https://dokku.com/bootstrap.sh

# run the installer
sudo bash bootstrap.sh

Mac (Homebrew)

brew install dokku/repo/dokku

Plugins

dokku-letsencrypt - Automatic Let's Encrypt TLS Certificate installation
dokku-mariadb - MariaDB plugin
dokku-postgres - PostgreSQL plugin
dokku-redirect - Simple redirects for applications

Plugins are installed from the server with:

sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git

Deploying an app

Create the app on the server:

dokku apps:create myapp

Then, from your local repo, add the server as a Git remote and push:

git remote add dokku dokku@your-server.example.com:myapp
git push dokku main

Let's Encrypt

After the app is reachable on its domain:

dokku letsencrypt:set myapp email you@example.com
dokku letsencrypt:enable myapp

General config settings

Change deploy branch

dokku git:set deploy-branch main

Timezone

dokku config:set TZ=Europe/Berlin

Nginx settings

Disable HSTS header

dokku nginx:set hsts false
dokku proxy:build-config

Max upload size

dokku nginx:set sitename client-max-body-size 25m

Rate limiting

See Rate limiting with dokku

Redirects

Redirect www to non-www using dokku-redirect plugin:

dokku redirect:set larsp www.larsp.de larsp.de
# -----> Configuring redirect for www.larsp.de to larsp.de via HTTP 301...

Ruby on Rails

Rails config

dokku config:set myrailsapp \
  SECRET_KEY_BASE=mysecret RAILS_ENV=production \
  RACK_ENV=production RAILS_LOG_TO_STDOUT=enabled \
  RAILS_SERVE_STATIC_FILES=enabled

PHP

Troubleshooting buildpack error

In case there is a problem with the PHP buildpack:

/tmp/buildpacks/08_buildpack-php/bin/compile: line 236: /tmp/buildpacks/08_buildpack-php/support/build/_util/formulae-hash.sh: No such file or directory

Reset the PHP herokuish buildpack:

rm -rf /home/dokku/<app>/cache/*
dokku config:set <app> BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-php --no-restart
dokku ps:rebuild <app>

Rails translation cheatsheet

Thu, 08 May 2025 00:00:00 GMT

How to translate a Rails application.

Locales

# config/application.rb

config.i18n.available_locales = %i[de fr it]
config.i18n.default_locale = :de
config.i18n.fallbacks = true

Add rails-i18n for ready-made date, number, and Active Record translations:

# Gemfile
gem "rails-i18n"

Locale files

# config/locales/de.yml
de:
  hello: "Hallo, %{name}!"
  apples:
    one: "1 Apfel"
    other: "%{count} Äpfel"
  pages:
    thankyou:
      title: "Danke"
      body_html: "<strong>Vielen Dank</strong> für deine Anfrage."

Use lazy lookup in views and controllers to avoid repeating the full key path:

# app/views/pages/thankyou.html.erb
<h1><%= t(".title") %></h1>
<%= t(".body_html") %>

A key ending in _html (or a leaf named html) is marked safe and rendered without escaping.

URL routing

# app/controllers/application_controller.rb

class ApplicationController < ActionController::Base
  around_action :switch_locale

  def switch_locale(&)
    locale = params[:locale] || I18n.default_locale
    I18n.with_locale(locale, &)
  end

  def default_url_options
    { locale: I18n.locale }
  end
end

# config/routes.rb

scope "(:locale)", locale: /de|fr|it/ do
  get "thankyou", to: "pages#thankyou"
  get "terms", to: "pages#terms"

  resource :submissions, only: %i[new create]
  get "submissions", to: "submissions#new"
  get "/", to: "submissions#new"
end

Set lang on the layout so screen readers and search engines pick up the active locale:

# app/views/layouts/application.html.erb
<html lang="<%= I18n.locale %>">

A minimal locale switcher:

<% I18n.available_locales.each do |l| %>
  <%= link_to l.to_s.upcase, url_for(locale: l),
      class: ("active" if I18n.locale == l) %>
<% end %>

Dates and numbers

<%= l(Time.current, format: :short) %>
<%= number_to_currency(19.99) %>

rails-i18n ships the formats. Override them per locale under date.formats, time.formats, and number.*.

Models and validations

# config/locales/de.yml
de:
  activerecord:
    models:
      question:
        one: "Frage"
        other: "Fragen"
    attributes:
      question:
        question: "Frage"
        answer: "Antwort"
    errors:
      models:
        question:
          attributes:
            answer:
              blank: "muss ausgefüllt werden"

Question.model_name.human and Question.human_attribute_name(:answer) resolve these automatically, so form labels and validation messages stay translated without extra wiring.

Field translation

Translatable columns for Ruby on Rails, stored in the model table itself

# Gemfile
gem "traco"

# app/models/question.rb

class Question < ApplicationRecord
  translates :question, :answer
end

Traco expects per-locale columns like question_de, question_fr, question_it. For a heavier setup with a separate translations table, look at Mobility.

Finding missing keys

i18n-tasks scans the codebase for untranslated keys and unused entries:

bundle exec i18n-tasks missing
bundle exec i18n-tasks unused

Syncthing

Tue, 06 May 2025 00:00:00 GMT

The best (IMHO) multi-platform open-source file synchronization solution.

As much as I wanted it to work, iCloud file synchronization used to give me headaches. I work with two Macs - one Mini in the office, and a MacBook on the go. In addition, I'm using a large iPad Pro and an older, small iPad Pro for traveling. My work files, mostly Git repositories of projects I am working on and additional reference material, should be shared across all these devices. I tried to use iCloud for this, but it was always a pain to get it to work reliably. I also used Dropbox in the past, but moved away after they went the course of integrating everything and whatnot in their software. Also, it was a resource hog.

The problem with iCloud is that you don't really know what's going on. It's a black box. You can't see what's happening, and you can't really control it. When the service thinks your files might have been changed on another device, it will create a copy of the file with a suffix " 2". Sometimes this happens for hundreds of files in a folder, and I resorted to just deleting them with:

find . -name "*\ 2" -delete

Also, sometimes iCloud is not updating at all for some reason.

Enter Syncthing

Yesterday, I was fed up with this and installed Syncthing on my Macs. It's a free, open-source file synchronization software that works on all major platforms and works really smoothly. I used it in the past already, and never had a problem.

iOS

For iOS, there is a very good open source client app called Synctrain. There's also an older third party solution (MöbiusSync), but I'd recommend Synctrain because it's much smoother.

There is a goals document describing Syncthing if you're interested.

Linux install

sudo apt install syncthing
sudo systemctl enable syncthing@$USER.service
sudo systemctl start syncthing@$USER.service

The web GUI is then available at http://localhost:8384.

CLI commands

syncthing cli config devices add --device-id ...
syncthing cli config options relays-enabled set false
find . -name "*sync-conflict*" -print

Files to ignore

Place the following in a .stignore file inside the synced folder to keep platform-specific cruft out of the sync:

(?d).DS_Store
Thumbs.db
desktop.ini
.Trashes
.Spotlight-V100
._*
lost+found

Archiving CMS websites to static files with httrack

Wed, 23 Apr 2025 00:00:00 GMT

Using httrack to archive a CMS website to keep it online as a static site.

When to Archive CMS Sites

When a website built with a content management system like Drupal or WordPress is no longer updated with content or a campaign has ended, the webpages sometimes need to be archived for reference or remain online without further changes. It's not always feasible to upgrade all CMS components along the way. A major version change might require expensive custom module upgrades for a site no longer in production use. Archiving to static files is a practical solution.

Using the httrack tool to archive a website

There are several options for archiving websites (see Awesome Web Archiving List). The httrack command-line tool is a preferred option. On macOS using Homebrew, install it with:

brew install httrack

These are good options for mirroring:

httrack http://SITE_TO_ARCHIVE -O DESTINATION_DIR \
  -N "%h%p/%n/index%[page].%t" \
  -WQ%v --robots=0 --footer ''

What the flags do:

-W mirror with wizard (asks about external links)
-Q no log files
-%v show progress on screen
-N "%h%p/%n/index%[page].%t" write each page as path/to/page/index.html so URLs stay clean
--robots=0 ignore robots.txt (only do this on sites you own or have permission to mirror)
--footer '' strip the httrack footer comment from each HTML file

The tool will prompt you if external links should be followed.

To avoid hammering the source server, throttle the crawl with --max-rate=25000 (bytes per second) or limit concurrent connections with -c2.

What this approach can't capture

Anything that depends on a live backend will not work in the static mirror: logged-in areas, search forms, comment submission, contact forms, and most JavaScript-driven dynamic content. Plan to either remove or replace those before going live.

Post-Processing Steps

Relative links can be rewritten afterwards (e.g., "about.html" to "about"). This is optional but useful if you want to preserve URL paths for inbound links.

find . -name "*.html" -type f -print0 \
  | xargs -0 perl -i -pe "s/\/index.html/\//g"

Because of the -N template, the homepage ends up as index/index.html rather than at the root. Move it up and strip the now-incorrect ../ prefixes from include paths and links:

cp index/index.html index.html
perl -i -pe 's/\.\.\///g' index.html

If the source site uses HTTP Basic Auth, provide username and password as part of the URL: username:password@your.url

Hosting Archived Sites

The resulting files can be served from inexpensive static web hosting like Netlify, Cloudflare Pages, or GitHub Pages.

Alternative: wget --mirror

For very simple sites, wget --mirror --convert-links --adjust-extension --page-requisites --no-parent https://example.com can be enough and avoids the post-processing dance. httrack tends to handle messy CMS output (Drupal, WordPress) better, but wget is worth trying first if the site is small.

References

Httrack users guide
Archiving Drupal sites on drupal.org
About archiving Drupal sites by Karen from Lullabot

Barcode PDFs with Ruby on Rails

Sun, 20 Apr 2025 00:00:00 GMT

Using Barby and Prawn to imprint PDFs with individual barcodes

For a Rails project, I researched methods to generate individual PDFs with imprinted EAN barcodes. This guide documents a working approach using modern Ruby libraries.

Libraries Used

Barby is a barcode generator library for Ruby that generates barcodes as images or PDFs. Prawn is a PDF generation library for Ruby that creates PDFs from scratch and annotates existing PDFs with text, images, and barcodes.

Implementation Approach

The solution uses two model classes:

A voucher class with a code property (printed as a barcode)
A PDF generation class that subclasses Prawn::Document

The PDF generation class accepts a path and code as arguments, generates a PDF with the barcode imprinted, and returns the path to a temporary file that is automatically deleted when the Rails process exits.

PDF Specifications

The resulting PDF is 100mm x 133mm with a PNG background image. Initially, the background option of Prawn::Document was tested but didn't scale the image properly. Instead, the image method with the fit option scales the image to the page size.

Prawn's measurement_extensions allow using millimeters as a unit instead of the default 1/72 inch.

Code Example

require "barby/barcode/code_128"
require "barby/outputter/prawn_outputter"
require "prawn/measurement_extensions"

class CodePdf < Prawn::Document
  def initialize path, code, background
    super({
      page_size: [100.mm, 177.mm],
      margin: 0
    })

    image background, fit: [100.mm, 177.mm]
    barcode code
    render_file path
  end

  def barcode code
    barcode = Barby::Code128.new code
    barcode.annotate_pdf self, height: 18.mm, x: 17.mm, y: 3.mm
  end
end

Voucher Generation

In the code class, a temporary file is created and the PDF generation class is called. The background image is located in the app/assets/images/{language} directory. The I18n.locale method returns the current locale (e.g., de or fr) to find the correct background image:

def voucher
  # Create temporary file e.g. tmp/voucher20230805-66997-kozjms.pdf
  tmpfile = Tempfile.new "voucher", Rails.root.join("tmp")
  path = tmpfile.path + ".pdf"
  bg_path = Rails.root.join "app", "assets", "images", I18n.locale.to_s, price.voucher
  CodePdf.new path, code, bg_path
  path
end

Here is an example of the resulting voucher PDF with the barcode: