aliou.me

exe.dev's ssh host header

Mon, 08 Jun 2026 00:00:00 GMT

been playing with exe.dev this weekend and was curious how they made ssh [vm-name].exe.dev just work, and it’s pretty cool: https://blog.exe.dev/ssh-host-header

pi-guardrails: Fix feature and permission gate toggles

Thu, 04 Jun 2026 00:00:00 GMT

Toggling features.* or permissionGate.requireConfirmation in the settings command stored the raw display string ("enabled"/"disabled", "on"/"off") instead of converting to true/false. Since any non-empty string is truthy, features appeared stuck “on” when toggled to “disabled” or “off”.

pi-neuralwatt: Add Devstral tool-result role ordering compatibility

Tue, 02 Jun 2026 00:00:00 GMT

Compatibility update for Devstral’s tool-result role ordering requirements.

pi-processes: Fix cwd parameter being ignored on process start

Tue, 02 Jun 2026 00:00:00 GMT

The process tool always used the session working directory (ctx.cwd) when spawning processes, ignoring the cwd parameter passed by the LLM. This caused commands with relative paths to fail when a different working directory was specified.

pi-utils-settings: Settings enum fix for disabled values

Mon, 01 Jun 2026 00:00:00 GMT

Settings enum fix for "disabled" values.

Thoughts on Claude Code's Workflow feature

Fri, 29 May 2026 00:00:00 GMT

i like the idea of claude’s workflow thingy but since it’s writing code, it keeps failing with these kind of errors:

but claude feels a bit overwhelming to me 😅

makes sense but wonder if this could still be handled? also, curious why they don’t give guidance about this and/or linting to have this be caught before running the workflow

pi-synthetic: Pi 0.77.0 compatibility and model metadata refresh

Fri, 29 May 2026 00:00:00 GMT

Removed models no longer returned by Synthetic (hf:zai-org/GLM-5, hf:deepseek-ai/DeepSeek-V3.2), added hf:Qwen/Qwen3.6-27B, and updated syn:small:vision to point at the new Qwen target.

Claude Opus's fast mode

Thu, 28 May 2026 00:00:00 GMT

missed that claude/opus has a fast mode so had pi make a quick extension to play with it. comparison with the vanilla pi

ext: https://gist.github.com/aliou/b7fe59004e023691c2e75c8458f3c0a8

(don’t look to closely at that horrendous code that kimi no thinking produced loooool)

pi-dev-kit: Default Pi core peer dependency ranges to wildcard

Sat, 23 May 2026 00:00:00 GMT

Update extension guidance to default Pi core peer dependency ranges to *, using minimum ranges only for APIs introduced after Pi 0.74.0.

pi-theme-jellybeans: Jellybeans Mono themes for Pi

Sat, 09 May 2026 00:00:00 GMT

Jellybeans Mono themes for Pi in dark and light variants.

pi-linkup: Migrate Pi core package dependencies

Fri, 08 May 2026 00:00:00 GMT

Name tools explicitly in promptGuidelines so they make sense in the global system prompt Guidelines section.

pi-toolchain: Migrate Pi core package dependencies

Fri, 08 May 2026 00:00:00 GMT

Migrate Pi core package dependencies from @mariozechner/* to @earendil-works/* namespace.

pi-ts-aperture: Fix gateway model checks and rewrite extension architecture

Mon, 27 Apr 2026 00:00:00 GMT

Fix gateway model checks to match models by provider and limit warning output per provider.

Custom providers in Pi

Sat, 04 Apr 2026 00:00:00 GMT

Two ways to connect Pi to a custom model endpoint, using Synthetic as an example

Why I Use Pi

Wed, 11 Feb 2026 00:00:00 GMT

I randomly read Mario Zechner’s article about what he learned building his own coding agent, which inspired me to try it. After a few days I made some small contributions, and within that first week I moved on from Claude Code to using Pi entirely.

Pi is also one of the building blocks of OpenClaw, which you’ve probably seen going around the past few weeks.

I mentioned to some friends that I had been contributing to the Pi repo and some asked why I started using it and whether they should too. Here’s why I use it, which might help answer that.

A tool that works for me first

One of the first reasons is that Pi is a tool that is easier to make work for me, the same way I’ve made Neovim work for me for the past 15 years.In other words, Pi is Vim. One thing that always bothered me with the different agents I’ve tried, whether it’s Claude Code or Amp, is that they’re either catered towards everyone or highly opinionated. That completely makes sense business-wise, but I always found myself trying to adapt to them instead of the tools adapting to the way I work. It felt somewhat backwards in a world where AI lets you create any tool you need that completely works for you. Why shouldn’t that extend to the tools you use to create those tools?Claude Code has a plugin system and you can set up marketplaces to package different plugins. I still felt limited. I also hear Amp is working on a plugin system I haven’t tried but will probably take a look at when it comes out.

Easily extensible

Pi by itself is very tiny but very complete. It has everything needed for a coding agent and you can simply use it without any changes. On top of that, you can create extensions that register custom tools for the agent to use or custom commands for you to use. What makes this even more powerful is that Pi knows it is extensible and knows where to find its own documentation because its system prompt references it. What ends up happening is that while you’re working, you can ask the agent “this was a difficult workflow, let’s abstract this into an extension we can reuse across projects.”

For example, I’ve needed multiple times to have the agent run a process in the background and continue working, whether it’s TDD with tests running on a loop while it implements features (session) or having the agent run a server and generate an OpenAPI client from it as it iterates (session, video). Before, I would just watch the agent struggle: either it wouldn’t try to start the server or it would try and stall because the server wasn’t running in the background. To avoid this, I created my own extension that runs processes in the background and that the agent knows about.This is not a novel idea; Claude Code has background bash commands as well.

The trade-offs

With all of this comes some trade-offs. You are building your own harness, which means you cannot delegate keeping up with models and tools to someone else. With Claude Code, the team building the models is also building the harness. With Amp, the team thoroughly tests how new models can improve their product. With Pi, you figure out which model provides what you need to do your work.

Pi is open source, and every time I’ve seen a bug or something that doesn’t work as expected or a small addition that could improve the tool, I open an issue or a pull request (e.g., allowing the tool to be put in the background, fixing image forwarding during streaming).

My extensions are also my responsibility. They can break for different reasons, and if I want to improve them, that’s on me too. (My extensions.)

Pi is open source if you want to look at it. Mario Zechner wrote about why he built it and Armin Ronacher wrote about why he uses it. Both are worth reading.

Coding Agents at Team Scale

Tue, 03 Feb 2026 00:00:00 GMT

The previous posts in this series covered keeping your AGENTS.md lean, loading domain knowledge with Skills, and using infrastructure to enforce rules. All of those assume one thing: that someone on the team is keeping those files up to date.

Unfortunately, that’s not always the case. At the pace our industry moves, and as priorities shift within a team or company, it’s easy to forget to keep those files up to date. On a recent client project, the AGENTS.md referenced a library and one of its commands that had been deprecated weeks earlier (they had moved from Kysely to Drizzle). Every day, the agent kept running kysely migrate latest instead of the new Drizzle equivalent. It would then read the package.json, notice the error, and correct itself — so developers wouldn’t see the issue immediately and never thought to update the AGENTS.md. The file wasn’t particularly long, but it was already stale.

Context rots as the code and priorities change. That’s one of the problems at team scale, and this post is about the unglamorous, less talked about part that determines whether your agent setup actually works over time: maintenance.

The drift problem

Your AGENTS.md is probably already out of date and it’s not particularly your fault. The codebase just moved or someone renamed a package or a new service got added or the schema changed.

Agents make decisions based on what they read and the first thing they read is that file. If it’s stale, the decisions are stale too and the cost compounds over weeks. Every outdated instruction is a wrong turn that humans need to correct or additional inference costs.

Eventually you stop trusting the agent, you stop maintaining the file and the cycle goes on.

Ownership

The fix starts with someone specific owning the AGENTS.md, the same way a team would own a package in a monorepo. In most smaller teams, this can end up being the tech lead or a senior developer. This doesn’t mean nobody else can change it, it means that this person makes sure it stays current and leverages their complete vision of the project and of the company/business.

Over time, this can change as the codebase and the team grows. What they do is review changes, flag drift and push back when the file gets too bloated.

To enforce this, make the boundary explicit. On GitHub, the best way is a CODEOWNERS file so that changes to any AGENTS.md request a review from the right people:

# CODEOWNERS
**/AGENTS.md       @platform-team @tech-leads
.agents/skills/    @platform-team

You can also add CI checks: e.g. if the package.json file changes, the nearest AGENTS.md should be reviewed or confirmed as still accurate.

You can also have a check on the length of the AGENTS.md. In one of my projects, this wasn’t a hard rule, but some necessary friction so that developers would ask themselves whether what they’re adding is relevant and if it is, whether it should be split into a child file or moved into toolingAs covered in The Infrastructure Around Your AGENTS.md. .

Maintenance strategies

However, ownership alone isn’t enough without processes behind it. Here are a few things that have worked for me.

Hooks and reminders

Set up hooks that prompt updates when key files change. They’re just nudges so that someone with enough context can actually make the changes. A CI annotation that says “key files changed, consider reviewing AGENTS.md” is sometimes more than enough:

# .github/workflows/agents-md-check.yml
name: Check AGENTS.md freshness

on:
  pull_request:
    paths:
      - "package.json"
      - "packages/*/package.json"

jobs:
  check-freshness:
    steps:
      - uses: actions/checkout@v4

      - name: Warn if no AGENTS.md changed
        run: |
          changed_files="$(git diff --name-only origin/${{ github.base_ref }}...HEAD)"
          echo "$changed_files" | grep -Eq '(^|/)AGENTS\.md$' && exit 0
          echo "::warning::Key files changed but no AGENTS.md was updated. Consider reviewing agent context for drift."

Regular review cadence

Do it weekly or every other week, but not quarterly. Things are moving way too fast for that. You can pair it with something that already happens: dependency updates, sprint planning, sprint retrospectives or internal demos. Most of the time, five minutes is enough assuming you’re doing it regularly and consistently.

LLM audits

This is the one that has given me the best results: using an LLM and an agentic loop to audit your own AGENTS.md files against what the code actually looks like. What is pretty great is that it checks for actual staleness concretely. It looks in the AGENTS.md and checks whether the commands mentioned there still exist. It checks if the paths are still relevant and if new packages or services that are important are mentioned.

The most realistic way to do this is to run the audit on a schedule and open an issue when drift is detected. It’s a maintenance signal, and we still leave the actual update to a person.

The setup is pretty simple: a GitHub Action that runs on the main branch, gathers repository facts and sends them to a model with the right prompt. Here’s one of the prompts I’ve used as a starting point. For each team, you would iterate on it:

Review all AGENTS.md files in this repository for drift and bloat.

Definition of "stale" (use these checks):
- Commands mentioned in AGENTS.md that do not exist in package.json / Makefile / task runner configs.
- File paths or package names mentioned that no longer exist (moved/renamed/deleted).
- Stack/tool versions mentioned that conflict with version sources (lockfiles, .tool-versions, .nvmrc, Dockerfiles).
- Missing coverage: new workspace packages or services that exist but are not referenced.

For each AGENTS.md file:
1. List concrete findings (quote the exact line and explain what it conflicts with).
2. Propose a minimal fix (1-3 bullet points). Prefer deleting or moving text over adding more.
3. Enforce brevity: if a file is >50 lines, suggest what to cut or split into a child AGENTS.md.

For bigger teams, allocate budget for this the same way you would for faster CI runners. You can use cheaper and/or open source models. It’s a fairly simple task, but something that LLMs excel at.

What triggers drift

Triggers usually come from small changes over time, not from big rewrites. It’s adding a new script, updating a package, removing a package or renaming a service. Here’s a table of what usually starts drift and which guardrail you could attach to avoid itI’ll be honest: this table was extracted from coding agent sessions by an LLM, based on actual work I’ve been doing with different teams. .

What changed	Typical symptom	Guardrail	Who updates
New/changed scripts in `package.json`	Agent suggests commands that don’t exist	PR rule: if scripts change, touch the nearest AGENTS.md	Package owner
Schema change (Prisma/Drizzle/migrations)	Agent generates migrations wrong, references renamed columns	CI nudge + PR checklist item	DB/service owner
New service or package added	Agent doesn’t know it exists	Root AGENTS.md has a services list; new package means updating it	Repo owner
Deprecated endpoint or behavior	Agent keeps calling the old route	Deprecation note in AGENTS.md + failing contract test	API owner
Renamed or moved module	Agent references old import paths	PR checklist item + optional CI grep for old paths	Package owner

The first post was about keeping instructions lean. The second was about loading context on demand. The third was about enforcement through tools. This one is about making all of that work at team scale.

This has been a series about the best way of working with coding agents as I’ve seen it in the last year of working with teams trying to increase their productivity with these new tools. Every team’s setup is of course different. If you want help figuring out what works for yours, feel free to reach out or learn more about what I do.

The Infrastructure Around Your AGENTS.md

Tue, 20 Jan 2026 00:00:00 GMT

In the previous post, we talked about loading specific domain knowledge when it is most relevant thanks to Skills. But there is something I intentionally left out: how do you actually make sure the agent is following what you have written in those Skills?

One of the answers I found working for my projects and for personal and client work is not adding more instructions but setting up an infrastructure.

One thing I realized is that the AGENTS.md is about 10% of the work. The ecosystem around it is the rest. A lean AGENTS.md works if you have guardrails that enforce rules and make sure the agent is following them when writing code.

Deterministic tools beat prose rules

This is a simple rule that has been working for both my client projects and my personal projects: deterministic tools beat prose rules. If something can be linted, do not write it in your AGENTS.md. Instead of a convention section that says “use consistent formatting,” “keep imports sorted,” “use camelCase,” and so on, configure your linter — Biome for TypeScript, Ruff for Python. Then tell your agent to run it when it is done with a piece of code or with work.

You can even skip telling your agent to run the linter and simply have a formatter in place that rewrites the code the way you expect it.The only caveat to automating formatting is that agents have a hard time with files that change right after they write them. Even though models are increasingly trained to re-read files before additional updates, they sometimes revert formatting changes, which is why linting is preferred here, at least for me. It also works with type checkers, where they immediately catch APIs that do not exist and have been hallucinated by your agent.

This is what I mean by deterministic: the feedback is immediate, unambiguous, and can be automated. This way, contrary to prose rules that can feel like suggestions, these are blockers for your agent.

Scripts as the Interface

An additional pattern I have seen work pretty well is using scripts as an explicit interface instead or in addition to documentation.

As an example, if you use Drizzle for migrations, you could have written the following in your AGENTS.md:

## Database Migrations

When creating migrations:
1. Update the schema file first
2. Use snake_case for table names
3. Run the generate command with the format...
4. Name migrations using YYYYMMDD_description...

Instead, you could define those scripts in the package.json:

{
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate"
  }
}

And in your AGENTS.md:

## Database

- Drizzle ORM + PostgreSQL
- Scripts in package.json. Never write migrations by hand.

I have noticed that agents already read the package.json file naturally, so there is no need to document how your migrations should be written or created. They can “just” call the script.

Tests as the feedback loop

The best thing you can give to your agent is a small and simple feedback loop. As I wrote about this a couple of weeks ago in Smaller and simpler feedback loops, it is worth repeating here. If the agent can run tests and see its results immediately, it can iterate instead of guessing or instead of you having to describe what needs to be changed.

For UI components, using Storybook interaction tests works extremely well. The agent sees the test fail, reads the error, fixes the code, and rebounds. In addition, if you have it set up, it can also check what the component looks like by using Playwright via MCP or any other custom tools.Tools like: Playwright MCP, Playwriter Chrome extension, dev-browser tool, browser tools skill.

Example setups

Here is what a minimal but effective infrastructure looks like for the stacks I have worked with the most, both for client projects and personal projects:

JavaScript/TypeScript:

Biome for formatting + linting (one tool, one config)
TypeScript strict mode (noUncheckedIndexedAccess, strictNullChecks)
Vitest for unit tests
Storybook interaction tests for components

Python:

uv for package/env management
ruff for linting + formatting
ty for type checking
pytest for unit tests

For other languages, the idea is the same: fast tools, strict settings, immediate and concise feedback.

What goes where

When I need to figure out where to put things, here is the template I follow.

What	Where
Project context, north star	AGENTS.md
Non-obvious conventions	AGENTS.md
Style, import order, naming	Lint rules
API shapes, data structures	Type definitions
Behavior verification	Tests

To repeat myself, but if it is something that can be enforced, it should be enforced either via rules or via scripts. If it is more context for the agent, it should be in the AGENTS.md.

The setup in action

When the infrastructure is set up correctly, here is what a change made by an agent can look like:

Agent makes a change and commits it
Pre-commit hooks run the formatter → code is styled correctly
Linter runs → catches import issues, naming violations
Type checker runs → catches hallucinated APIs, missing null checks
Tests run → verify behavior works
Human reviews → focuses on intent, not nitpicks

At each of those steps, the agent has the possibility of fixing its mistakes or the issues. It does the fix, retries it by running the test, and then it moves on. Finally, by the time you actually are reviewing, you can focus on what is important:At least in my opinion. the UX of the feature, the intent of the update, whether it matches the direction of the product you are working on, and so on.

Skills for Domain-Specific Knowledge

Wed, 07 Jan 2026 00:00:00 GMT

Progressive disclosure for coding agents: load context only when needed

Your AGENTS.md can be shorter now

Sat, 20 Dec 2025 00:00:00 GMT

The new wave of coding models needs less hand-holding than you think

Smaller and simpler feedback loops

Fri, 28 Nov 2025 00:00:00 GMT

How coding agents changed the way I worked

Upgrading the nvim-treesitter plugin

Fri, 17 Oct 2025 00:00:00 GMT

Every couple of weeks, I run MiniDeps’s :DepsUpdate and cross my fingers that everything is going to be fine. Most of the time it is but not this morningYou’d think after more than 15 years, I’d understand that Friday are not the days to be nonchalant about potentially breaking things. .

Immediately, I got the following errors:

Error detected while processing ~/.config/nvim/init.lua:
E5113: Error while calling lua chunk: ~/.config/nvim/lua/_/ui/treesitter.lua:1: module 'nvim-treesitter.configs' not found:
        no field package.preload['nvim-treesitter.configs']
        no file '/nix/store/w997z7g0ii6figi4z98id0b0yn2jzala-luajit-2.1.1741730670-env/share/lua/5.1/nvim-treesitter/configs.lua'
        no file '/nix/store/w997z7g0ii6figi4z98id0b0yn2jzala-luajit-2.1.1741730670-env/share/lua/5.1/nvim-treesitter/configs/init.lua'
        no file '/nix/store/bmdviv9ljgqb6siq2p3dsll497fjzpif-luajit2.1-fzy-1.0.3-1/share/lua/5.1/nvim-treesitter/configs.lua'
        no file '/nix/store/bmdviv9ljgqb6siq2p3dsll497fjzpif-luajit2.1-fzy-1.0.3-1/share/lua/5.1/nvim-treesitter/configs/init.lua'
        no file '/nix/store/w997z7g0ii6figi4z98id0b0yn2jzala-luajit-2.1.1741730670-env/lib/lua/5.1/nvim-treesitter/configs.so'
        no file '/nix/store/bmdviv9ljgqb6siq2p3dsll497fjzpif-luajit2.1-fzy-1.0.3-1/lib/lua/5.1/nvim-treesitter/configs.so'
        no file '/nix/store/w997z7g0ii6figi4z98id0b0yn2jzala-luajit-2.1.1741730670-env/lib/lua/5.1/nvim-treesitter.so'
        no file '/nix/store/bmdviv9ljgqb6siq2p3dsll497fjzpif-luajit2.1-fzy-1.0.3-1/lib/lua/5.1/nvim-treesitter.so'

Investigating further, I saw that the master branch of nvim-treesitter is now frozen and they’re now working on the main branch. The new branch is a complete rewrite. The fix could have been a simple:

  MiniDeps.add({
    source = 'nvim-treesitter/nvim-treesitter',
-   checkout = 'master',
+   checkout = 'main',
    hooks = { post_checkout = function() vim.cmd('TSUpdate') end },
  })

However, since I was there and I figured I’ll just do the update properly. First, my configuration looked like this:

local configs = require('nvim-treesitter.configs')
local mdx = require('mdx')

---@diagnostic disable-next-line: missing-fields
configs.setup({
  auto_install = true,
  highlight = { enable = true },
  endwise = { enable = true },
  indent = { enable = true },
})

The rewrite removes the need for manual config except for customization on where the parsers are installed. To keep the behaviours I had before, in my case, the auto_install option and the highlighting, I update my config like this:

First, I installed parsers for files in my dotfile on startup. Thankfully, this is a no-op when they’re already installed:

local ts = require('nvim-treesitter')

-- Wait at most 30 seconds to finish installation.
ts.install(
  {
    'lua', 'vim', 'vimdoc', 'query',
    'markdown', 'markdown_inline',
    'json', 'yaml',
  },
  -- Do not print summary, as this will run at startup always, all the time.
  { summary = false }
):wait(30000)

Then, I install the parser and enable highlighting and other plugin using an autocmd that triggers on FileType:

---@type fun(args: vim.api.keyset.create_autocmd.callback_args): boolean?
local install_parser_and_enable_features = function(event)
  local lang = event.match

  -- Try to start the parser install for the language.
  local ok, task = pcall(ts.install, { lang }, { summary = true })
  if not ok then return end

  -- Wait for the installation to finish (up to 10 seconds).
  task:wait(10000)

  -- Enable syntax highlighting for the buffer
  ok, _ = pcall(vim.treesitter.start, event.buf, lang)
  if not ok then return end

  -- Enable other features as needed.

  -- Enable indentation based on treesitter for the buffer.
  -- vim.bo.indentexpr = "v:lua.require'nvim-treesitter'.indentexpr()"

  -- Enable folding based on treesitter for the buffer.
  -- vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'
end

-- Install missing parsers on file open.
vim.api.nvim_create_autocmd('FileType', {
  group = vim.api.nvim_create_augroup('ui.treesitter', { clear = true }),
  pattern = { '*' },
  callback = install_parser_and_enable_features
})

And like that, no more errors and treesitter works as expected. I should probably read more about the reasons of the rewrite, but I’ll leave this for another Friday.

In-Memory DuckDB with GCS Parquet Files in Cube

Thu, 21 Aug 2025 00:00:00 GMT

I needed to quickly investigate some data and used the following pattern to do so. Using the model of an e-commerce store as example, here’s what I did.

The Setup

First, setup a cube.js defining the dbType:

module.exports = {
  dbType: 'duckdb',
}

Then, define the driverFactory, and configure the access to the GCS bucket:

const driverFactory = async () => {
  const { DuckDBDriver } = require('@cubejs-backend/duckdb-driver');

  return new DuckDBDriver({
    database: ':memory:',
    initSql: `
      INSTALL httpfs;
      LOAD httpfs;

      CREATE SECRET (
        TYPE gcs,
        KEY_ID 'YOUR_KEY_ID',
        SECRET 'YOUR_SECRET_ID'
      );
    `,
  });
}

Finally, add to initSql the commands to setup our views and access our data:

CREATE VIEW orders AS
SELECT * FROM read_parquet('gs://tmp-bucket/orders/*.parquet');

CREATE VIEW products AS
SELECT * FROM read_parquet('gs://tmp-bucket/products/*.parquet');

CREATE VIEW line_items AS
SELECT * FROM read_parquet('gs://tmp-bucket/line_items/*.parquet');

CREATE VIEW users AS
SELECT * FROM read_parquet('gs://tmp-bucket/users/*.parquet');

CREATE VIEW inventory_transactions AS
SELECT * FROM read_parquet('gs://tmp-bucket/inventory/*.parquet');

Key Implementation Details

Views, Not Tables: I specifically used CREATE VIEW instead of CREATE TABLE AS to avoid loading all the data into memory. Views just store the query definition - DuckDB streams the Parquet data chunk by chunk when you actually query it. With tables, DuckDB would copy everything into its internal format, eating up memory or disk space.

Zero Infrastructure: The :memory: database means no provisioning. Each Cube process gets a fresh DuckDB instance that reads directly from existing Parquet files.

Direct Access: No ETL pipeline, no data loading. The read_parquet() function streams data directly from GCS, and DuckDB’s columnar engine only fetches the columns needed for each query.

Wildcard Patterns: The /*.parquet pattern lets you treat multiple files as a single table without any preprocessing. Perfect for data that’s already partitioned by date or other dimensions.

Performance Characteristics

In this example, you could run complex queries across orders, products, line items, and inventory - joining across millions of rows within seconds. What would normally require hours of data pipeline setup can be done immediately.

DuckDB’s aggressive caching means the first query might take a few seconds to fetch metadata, but subsequent queries run pretty much instantly even on larger datasets.

Trade-offs

Benefits:

Zero data movement—queries run directly against GCS files
No infrastructure to manage
Instant setup for ad-hoc analysis
Reuses existing Parquet files from other processes

Drawbacks:

:memory: means state vanishes on restart
Not suitable for production workloads
Performance degrades on datasets larger than available RAM

Notes

This pattern works for any quick data investigation. Got Parquet files? Throw them in GCS, point Cube at them with this config, and you’re analyzing data in minutes. For more permanent setups, swap :memory: for a file path to persist the DuckDB catalog between restarts.

Your data lake is already an OLAP database. You just need DuckDB to unlock it.

Template Literal Types for Dynamic API Generation

Fri, 15 Aug 2025 00:00:00 GMT

Continuing my work on cube-records, I wanted to support joined field names like orders.total or users.email - matching exactly how the underlying Cube names them. Instead of manually defining these combinations, TypeScript’s template literal types generate them automatically.

The Pattern

Here’s a simplified version of the Cube schema:

// User defines their schema
interface Schema {
  users: {
    fields: { id: string; email: string };
    joins: ['orders'];
  };
  orders: {
    fields: { total: number; status: string };
    joins: [];
  };
}

Then, we use a template literal type to defined our joined fields:

// Template literal magic
type JoinedFields<T extends keyof Schema> =
  Schema[T]['joins'][number] extends infer Join
    ? Join extends keyof Schema
      ? `${Join}.${keyof Schema[Join]['fields'] & string}`
      : never
    : never;

Finally, we can also use the type to create our own custom type.

// TypeScript now knows these fields exist:
type UserJoinedFields = JoinedFields<'users'>;
// Result: 'orders.total' | 'orders.status'

The infer keyword extracts each join name, then template literals compose the dot-notation paths.

Usage

With the schema defined above and our new type, we can define a Query type like the following:

type Query<T extends keyof Schema> = {
  model: T;
  fields: (Schema[T]['fields'] & JoinedFields<T>)[];
}

And in our code, we can declare a query serenely thanks to the type system preventing us from writing a query with invalid fields:

const query: Query = {
  model: 'users',
  fields: [
    'email',          // ✓ users field
    'orders.total',   // ✓ joined field
    'orders.status',  // ✓ joined field
    'invalid.field'   // ✗ Type error
  ]
};

The real implementation has more conditionals for safety, but the core idea remains the same: extract the join names, then use template literals to compose the field paths.

Trade-offs

Benefits:

Zero maintenance—add a field to the schema, get autocompletion everywhere
Catches typos at compile time instead of runtime
Scales to hundreds of field combinations without manual work

Drawbacks:

Type computation can slow down in massive schemas
Error messages become cryptic when deeply nested
Only works with predictable string patterns

Notes

This pattern shines when you control the schema and need to generate predictable string patterns. It’s less suitable for user-defined schemas or when you need runtime validation anyway. The sweet spot is internal APIs where you want compiler-enforced consistency between your types and runtime behavior.

What you don’t write is as important as what you do. No manual string unions. No keeping field lists in sync. Add a new join relationship, and TypeScript immediately knows about every possible field combination.

Smooth Theme-Aware Images with CSS Transitions

Tue, 12 Aug 2025 00:00:00 GMT

When Ghostty came out, I wrote this blog post which contained a few screenshots. I forgot how I managed to have both light and dark mode work seamlessly in Eleventy, so I figured I’d write it down for future me or anyone that sees this.

The Pattern

I use an Eleventy shortcode that conditionally renders different images based on theme preference. The basic version wraps images in figure tags with captions:

config.addShortcode('image', (src: string, alt: string, withDarkMode = false) => {
  const lastDotIndex = src.lastIndexOf('.');
  const basePath = src.slice(0, lastDotIndex);
  const extension = src.slice(lastDotIndex);

  const lightPath = `${basePath}-light${extension}`;
  const darkPath = `${basePath}-dark${extension}`;

  return `<figure>${
    withDarkMode
      ? `<img class="not-dark:hidden" src="${darkPath}" alt="${alt}">` +
        `<img class="dark:hidden" src="${lightPath}" alt="${alt}">`
      : `<img src="${src}" alt="${alt}">`
  }<figcaption>${alt}</figcaption></figure>`;
});

Smooth Transitions

The images would swap instantly when toggling themes, which felt jarring. Adding Tailwind’s transition utilities creates a cross-fade effect:

withDarkMode
  ? `<img class="not-dark:hidden not-dark:opacity-0 dark:opacity-100 starting:dark:opacity-0 transition-discrete transition-opacity duration-1000" src="${darkPath}" alt="${alt}">` +
    `<img class="dark:hidden dark:opacity-0 not-dark:opacity-100 starting:not-dark:opacity-0 transition-discrete transition-opacity duration-1000" src="${lightPath}" alt="${alt}">`
  : `<img src="${src}" alt="${alt}">`

The starting: modifiers prevent the fade animation on initial page load, which I borrowed from how Tailwind’s own docs handle theme switching.

Usage

Now {% raw %}{% image "ghostty-screenshot.png" "Terminal with ligatures" true %}{% endraw %} automatically looks for ghostty-screenshot-light.png and ghostty-screenshot-dark.png, then smoothly transitions between them when you toggle themes.

Trade-offs

Benefits:

Smooth 1-second cross-fade between theme variants
Both images preload—no flicker on theme switch
Simple to maintain with clear naming conventions

Drawbacks:

Downloads both variants even if user never switches themes
Requires maintaining two versions of every screenshot

Notes

This approach works well for static sites where you control every image. For dynamic content or high-traffic sites, you’d want lazy loading for the hidden variant or CSS filters for automatic adjustments.

References

Figured how to create custom shortcode after reading this article by Anh.

Type-Safe Domain Models with Interface Augmentation in TypeScript

Thu, 07 Aug 2025 00:00:00 GMT

While working on @general-dexterity/cube-records, I needed a way to defineOr use codegen with another library. my domain-specific Cube models in a way that would provide type-safe autocompletion. The solution was ended up pretty simple: global interface augmentation.

The Problem

The lib defines an empty global interface that users can augment with their own cube definitions. However, after publishing, I discovered that tsup was optimizing the empty interface into a type alias during the build:

// What we write
export interface CubeRecordMap {}

// What tsup outputs with dts: true
export type CubeRecordMap = {}

// Now augmentation fails
declare global {
  interface CubeRecordMap { // Error: can't augment a type alias
    users: { /* ... */ }
  }
}

The Solution

Adding a dummy property prevents this optimization:

export interface CubeRecordMap {
  __empty: {
    measures: {};
    dimensions: {};
    joins: [];
  };
}

That __empty property isn’t arbitrary - it ensures the interface remains augmentable through the entire build pipelineThis is specifically a build tool optimization when generating declaration files, not a TypeScript language limitation. .

Implementation

Users can now extend the interface in their projects:

declare global {
  interface CubeRecordMap {
    users: {
      measures: { count: { type: number } };
      dimensions: {
        id: { type: string };
        email: { type: string };
      };
      joins: readonly ['orders'];
    };
    // ... other models and views
  }
}

The library extracts type-safe cube names and fields:

type CubeRecordName = keyof CubeRecordMap;
type CubeRecordMeasure<T extends CubeRecordName> =
  keyof CubeRecordMap[T]['measures'] & string;

Trade-offs

Benefits:

Interface stays augmentable through the build pipeline
Zero runtime overhead - types exist only at compile time
Incremental cube definitions with immediate IDE support

Drawbacks:

The interface includes a dummy property
Requires some documentation to explain the pattern

Notes

This isn’t just for my personal benefitsEven though it was pretty fun to try to figure this out. , this pattern provides domain-specific autocompletion without runtime cost. Instead of searching through Cube models for field names, TypeScript provides instant feedback as you type.

Adding Custom Language Support to Shiki

Wed, 06 Aug 2025 00:00:00 GMT

While writing my Ghostty blog post, I wanted syntax highlighting for the configuration snippets. Since Shiki doesn’t support Ghostty’s config format, I added a custom language definition.

const ghostty = {
  name: 'ghostty',
  scopeName: 'source.ghostty',
  fileTypes: ['ghostty'],
  repository: {},
  patterns: [
    {
      include: '#strings',
    },
    {
      name: 'comment.line.number-sign.ghostty',
      match: '^\\s*#.*$',
    },
    {
      match: '\\b(font-family|font-feature)\\b',
      name: 'keyword.other.ghostty',
    },
  ],
};

I only defined patterns for comments (#) and the font keywords I was actually using. The grammar follows TextMate rules but doesn’t try to implement the full Ghostty spec - just enough for my examples.

highlighter = await createHighlighter({
  themes: ['github-dark', 'github-light'],
  langs: ['ruby', 'javascript', 'json', 'elixir', 'typescript', ghostty],
});

Enabling font ligatures for GitHub Monaspace in Ghostty

Sat, 28 Dec 2024 00:00:00 GMT

Enabling Monaspace’s stylistic sets for code ligatures in Ghostty

Using named captures to extract information from ruby strings

Thu, 09 Apr 2020 00:00:00 GMT

For an internal project at work, I recently had to parse the names of Heroku review applications to retrieve some data. The application names looked like this:

<project_name>-pr-<pull_request_id>

At first, since each part I needed was separated by a dash, I had some code that looked like this:

*project_name, _, pull_request_id = application_name.split('-')
project_name = project_name.join('-')

Because the project name could also have some dashes in it, I needed to rejoin it after extracting the pull request data. At first, for a prototype, this worked fine. But when this internal project transitioned into being an important part of my team’s tooling, I started looking at a better and cleaner way to achieve the same result.

Since we were already validating the format of the application name with a regular expression, I figured I’d use it to also retrieve the data using named captures.

Regular expressions in Ruby

For a refresher on a regular expressions, I highly recommend this articleWhile the article is intended for designers and UX writers, I found that it was an excellent introduction to regular expressions for everyone. by Dan Eden.

As a reminder, there are multiple ways to create regular expressions in Ruby:

Using /xxxx/
Using percent literal : %r{}
Using the class initializer: Regexp#new

With your newly created regular expression, there are two main ways to check if a string matches a regular expression:

Calling String#match with the regular expression as argument:

'abc'.match(/a/)
# => #<MatchData "a">

Calling Regexp#match on the regular expression with the string as argument:

/a/.match('abc')
# => #<MatchData "a">

If the String matches the regular expression, it will return a MatchData object, otherwise it will return nil. The MatchData object encapsulates the result of matching a String against a Regexp, including the different submatches. It also contains the eventual captures and named captures.

Named captures

Named captures allow you to describe submatches of a regular expression and then retrieve them from the resulting MatchData object. In our case, our regular expression looked like this:

/.*-pr-\d+/

To use named captures, we first need to add capture them into groups to our regular expressions. Adding capture groups is as simple as wrapping them inside parentheses:

/(.*)-pr-(\d+)/

Finally, name the different captures. To do this, we need to prefix the content of the capture group with its name:

/(?<project_name>.*)-pr-(?<pull_request_id>\d+)/

Now that we’ve done this, we can easily retrieve the data we want from the application name using our resulting object:

expression = /(?<project_name>.*)-pr-(?<pull_request_id>\d+)/
application_name = 'my_app-pr-1234'
matches = expression.match(application_name)

matches[:project_name] # => 'my_app'
matches.named_captures # => {"project_name"=>"my_app", "pull_request_id"=>"1234"}

Thanks to Bachir Çaoui, Alexis Woo and Alexis Focheux for reviewing draft versions of this post.

Changing perception of objects by overriding the inspect method

Tue, 18 Feb 2020 00:00:00 GMT

While writing my previous post, I realized that while using the attributes API allows us to avoid making mistakes when instantiating our value objects, it might not entirely convey that there’s a limited number of objects that can be instantiated Of course, we could look at the file defining the constants, but where would be the fun in that? .

To this end, I thought about a way to prevent this: let’s pretend that our value objects are constants.

Generating constants

First, let’s take our Ship::Category from the previous post:

class Ship::Category
  VALID_CATEGORIES = %w(
    shuttle supply_carrier troop_carrier war_ship
  ).freeze

  def initialize(category)
    raise "invalid category: #{category.inspect}" unless category.in?(VALID_CATEGORIES)

    @raw_category = category
  end

  def to_s
    raw_category
  end

  private

  attr_reader :raw_category
end

Let’s start by defining constants for each of our values. Under the initialize method Because our constants are set directly in the class, the new method needs to be already defined, hence defining them under the initialize method. , let’s create the constants using const_set and a bit of metaprogramming:

class Shift::Category
  # ...

  VALID_CATEGORIES.each do |raw_category|
    const_set(raw_category.upcase, new(raw_category))
  end
end

Calling Ship::Category.constants show us that our constants have correctly been created:

pry(main)> Ship::Category.constants
# => [:WAR_SHIP, :TROOP_CARRIER, :SHUTTLE, :SUPPLY_CARRIER, :VALID_CATEGORIES]

However, inspecting the constant reveals our trickery:

pry(main)> Ship::Category::SHUTTLE
# => #<Ship::Category:0x00007fbddc853350 @raw_category="shuttle">

So, how do we really pretend that our Ship::Category object is truly a constant ? We can do this by overriding the inspect method:

Overriding inspect

As we can see above, by default, inspect returns the class name, a representation of the memory address of the object and a list of instance variables of the object.

In our case, we want inspect to instead display how the object should be accessed. This means making it look like the constants we’ve created above:

class Shift::Category
  # ...

  def inspect
    "#{self.class}::#{raw_category.upcase}"
  end
end

With this, the value object is now displayed as a constant when inspecting the object or in logs:

# Before we had:
pry(main)> Ship::Category::SHUTTLE
# => #<Ship::Category:0x00007fbddc853350 @raw_category="shuttle">

# Now we have
pry(main)> Ship::Category::SHUTTLE
# => Ship::Category::SHUTTLE

Besides indulging in my whims, there are other interesting reasons to override inspect:

This is useful to hide sensitive values like emails or encrypted passwords, as Devise does it.
Since Rails 6, you can configure ActiveRecord to filter attributes from inspection. This is also done by overriding the inspect method.
The IPAddr class also overrides the inspect method to display a human readable representation of the IP address.

The code examples in this post are also available on GitHub{target=“_blank”}. Thanks to Bachir Çaoui and Stéphanie Chhim for reviewing a draft version of this post.

Using Rails's Attributes API to serialize Value Objects

Tue, 08 Oct 2019 00:00:00 GMT

Continuing my deep dive into Rails features See my previous post about Namespaced Rails validators. , I recently read about the Attributes API{:target=“_blank”} and more particularly about how it can be used with custom types.

The `attribute` API

The attributes method allows you to define an attribute with a type on a model. This type can be a completely custom.

In our example, we have spaceships that are defined by their category. Those categories are both immutable and interchangeable, and are good candidates to be transformed into value objects{:target=“_blank”}.

Our current model looks like this:

# app/models/ship.rb
class Ship < ApplicationRecord
  validates :name, presence: true
  validates :category, presence: true

  validates :category, inclusion: { in: Ship::Category::VALID_CATEGORIES }
end

And our Ship::Category value type looks like this:

# app/models/ship/category.rb
class Ship::Category
  VALID_CATEGORIES = %w(
    shuttle supply_carrier troop_carrier war_ship
  ).freeze

  def initialize(category)
    raise "invalid category '#{category.inspect}'" unless category.in?(VALID_CATEGORIES)

    @raw_category = category
  end

  def to_s
    raw_category
  end

  # Conform to comparable.
  def <=>(other)
    VALID_CATEGORIES.index(to_s) <=> VALID_CATEGORIES.index(other.to_s)
  end

  private

  attr_reader :raw_category
end

Now, let’s update our model to retrieve our value object:

# app/models/ship.rb
class Ship < ApplicationRecord
  # ...

  def category
    @category ||= Ship::Category.new(self[:category])
  end
end

While this does what we want, this can be improved by creating a custom type.

Creating a custom type

We create our custom type by inheriting from ActiveRecord::Type::Value and overriding the necessary methods:

type is the type of our object when saved in the database. In our case this will be :string.
cast is the method called by ActiveRecord when setting the attribute in the model. In our case, we will instantiate our value object.
deserialize converts the value from the database to our value object. By default it calls cast.
serialize converts our value object to a type that the database understands. In our case, we’ll send back the string containing the raw category.

For our type it looks like this:

# app/types/ship_category.rb

class CategoryType < ActiveRecord::Type::Value
  def type
    :string
  end

  def cast(value)
    Ship::Category.new(value)
  end

  def deserialize(value)
    cast(value)
  end

  def serialize(value)
    value.to_s
  end
end

Registering our type

Now that our type is created, we need to register it so ActiveRecord knows about it:

# config/initializers/types.rb
ActiveRecord::Type.register(:ship_category, CategoryType)

You will need to restart your Rails server or re-register your type every time you update it.

Using it in our model

Finally, we can use it in our model:

class Ship < ApplicationRecord
  attribute :category, :ship_category

  validates :name, presence: true
  validates :category, presence: true
end

At this point, you might be wondering: Why would I do this? Personally, I feel like it is cleaner to let Rails handle the instantiation of objects instead of the usual memoization-with-instance-variables dance.

Furthermore, it allows you to add additional features to your model without having pollute the model class. In our case, we allow our ships to be compared based on their categories by implementing Comparable{:target=“_blank”} in our Category.

However, there are ways to make this particular use case fall down. In our example above, we limit the category to the values defined in VALID_CATEGORIES. This means that creating a row in our database with a value that isn’t valid will make our application raise when trying to instantiate the row into a Ship object:

INSERT INTO ships(id, name, category, created_at, updated_at)
VALUES (10, 'USS Enterprise', 'interstellar_liner', NOW(), NOW());

enterprise = Ship.find(10)
# => Error: invalid category 'interstellar_liner'

For the purpose of this blog post, I chose a fairly simple example to present the attributes API. To achieve a similar result, you could also define the categories as a ActiveRecord Enum, as a Postgres EnumHowever, this would require you to change your schema format to :sql or to override Rails’s Schema dumper to handle Postgres Enums. or even have them in their own table and have a Postgres association between a Ship and its category, that is backed by a foreign key to achieve integrity of your data.

Thanks to Bachir Çaoui and Baicheng Yu for reviewing draft versions of this post.

Three ways to ignore files in Git

Thu, 17 Jan 2019 00:00:00 GMT

TIL I learned that there are different ways to ignore files in Git:

1. Using a `.gitignore` file in a repository

When created in a Git repository, this .gitignore is only applied to the directory it is in and its children. This means that you can ignore files in the whole repository and also ignore some files in some subdirectories.

Start by creating a .gitignore in a subdirectory:

# lib/.gitignore
*.md

With the following directory structure:

.
├── lib
│   ├── .gitignore
│   ├── todo.md        # <- Will be ignored
└── Readme.md          # <- Will not be ignored

This file should be version-controlled and includes files that all developers working on the repository will want to ignore.

2. Using the local exclusion file `.git/info/exclude`

Start by creating the info directory and the exclude file in our repository .git directory:

mkdir -p .git/info
touch exclude

Then you can add files or pattern of files you want to ignore:

TODO.md
NOTES.txt

I mainly use it to ignore files that do not need to be shared with other developers. I usually leave notes a list of TODOs at the root of a project and ignore them in this file.

3. Using a global `.gitignore`

Start by making a .gitignore file in your home directory, with the files you want to ignore, and place in your home directory:

# ~/.gitignore

.vimrc.local
*.swp

.idea
.DS_Store

Then, tell Git to use this file as global .gitignore by running in your shell:

git config --global core.excludesfile ~/.gitignore

I use it to ignore file I never want to be committed, e.g. backup or temporary files, build artifacts, etc.

Postgres timestamp ranges in Ecto

Tue, 18 Sep 2018 00:00:00 GMT

I recently read a post on Postgres’s range types{target=’_blank’} and have been trying to take advantage of them in my code.

However, because some of these types aren’t shared between the different SQL databases, most Object Relation Mapping like Ruby on Rails’s ActiveRecord and database wrappers (e.g. Elixir’s Ecto{target=’_blank’}) don’t support them.

Thankfully, Ecto allows us to define our custom types that can represent an unknown database type. We’ll now try to implement one to represent timestamp ranges.

Let’s say we need to schedule chores between different members of a team in a spaceship. If you know me this might be familiar{:target=“_blank”}.

The simplest way to do this would be to store the range of our chore and who is assigned to it. With Ecto, the migration creating this table would look like this:

create table(:chores) do
  add(:user_id, references("users"), null: false)
  add(:note, :string)
  add(:range, :tsrange, null: false)

  timestamps(default: fragment("NOW()"))
end

We also need to make sure a user can’t have multiple chores overlapping with each other. For this we’ll add an exclusion constraint{target=’_blank’} on our range:

# Add the btree_gist extension to allow using `gist` indexes
# with scalar types, in our case the `user_id`.
execute("CREATE EXTENSION btree_gist")

create(
  constraint(
    "chores",
    :no_overlaping_chores_for_user,
    exclude: ~s|gist (user_id with =, range with &&)|
  )
)

Creating the schema

We now create our schema representing a chore in the application. Let’s try to use the :tsrange as the type of our chore range:

defmodule Chore do
  use Ecto.Schema

  schema "chores" do
    field(:note, :string)
    field(:range, :tsrange)

    belongs_to(:user, User)

    timestamps()
  end

  def changeset(chore, attrs) do
    chore
    |> cast(attrs, [:user_id, :note, :range])
    |> validate_required([:user_id, :range])
  end
end

When compiling this, we have an error:

== Compilation error in file lib/chore.ex ==
** (ArgumentError) invalid or unknown type :tsrange
    for field :range

Because :tsrange is not a type known by Ecto, we will need to create our own type adopting the Ecto.Type behaviour{:target=“_blank”}. But first we’ll create a struct that represents a timestamp range.

Representing our Range

We define our Timestamp.Range as a struct with the first and last elements of the range and with options for the inclusivity of those elements in the range.

defmodule Timestamp.Range do
  defstruct [:first, :last, opts: []]

  @type t :: %__MODULE__{
          first: NaiveDateTime.t(),
          last: NaiveDateTime.t(),
          opts: [
            lower_inclusive: boolean(),
            upper_inclusive: boolean()
          ]
        }
end

We also define a convenience function to create a Timestamp.Range:


@default_opts [lower_inclusive: true, upper_inclusive: false]

@spec new(NaiveDateTime.t(), NaiveDateTime.t(), Keyword.t()) :: t
def new(first, last, opts \\ []) do
    opts = Keyword.merge(@default_opts, opts)

    %__MODULE__{
      first: first,
      last: last,
      opts: opts
    }
end

We can now represent a Postgres’s tsrange in Elixir.

Implementing the `Ecto.Type` behaviour

The Ecto.Type behaviour expects four functions to be defined:

type/0: The underlying type of our custom type, known by either Ecto or Postgrex
cast/1: A function to transform anything into our custom type.
load/1: A function to transform something from the database into our custom type.
dump/1: A function to transform our custom type into something understood by the database.

The type implementation:

def type, do: :tsrange

The cast implementation: we only allow our custom type to be cast:

def cast(%Timestamp.Range{} = range), do: {:ok, range}
def cast(_), do: :error

The load implementation receives a Postgrex.Range and transforms it to a Timestamp.Range:

def load(%Postgrex.Range{} = range) do
  {:ok,
    Timestamp.Range.new(
      range.lower,
      range.upper,
      lower_inclusive: range.lower_inclusive,
      upper_inclusive: range.upper_inclusive
    )}
end

def load(_), do: :error

And finally, the dump implementation takes a Timestamp.Range and transforms it to a Postgrex.Range:

def dump(%Timestamp.Range{} = range) do
  [lower_inclusive: lower_inclusive, upper_inclusive: upper_inclusive] = range.opts

  {:ok,
    %Postgrex.Range{
      lower: range.first,
      upper: range.last,
      lower_inclusive: lower_inclusive,
      upper_inclusive: upper_inclusive
    }}
end

def dump(_), do: :error

Using our new type in the schema

Now that we have our custom Ecto type, we can use it in our schema:

schema "chores" do
  field(:note, :string)
  field(:range, Timestamp.Range)

  belongs_to(:user, User)

  timestamps()
end

And we can insert new chores into the table:

iex(1)> range_start = ~N[2018-09-17 10:00:00]
iex(2)> range_end = ~N[2018-09-17 12:00:00]
iex(3)> attrs = %{user_id: 1, range: Timestamp.Range.new(range_start, range_end)}
iex(4)> Chore.changeset(%Chore{}, attrs) |> Repo.insert!
%Radch.Chore{
  __meta__: #Ecto.Schema.Metadata<:loaded, "chores">,
  id: 1,
  note: nil,
  range: #Timestamp.Range<~N[2018-09-17 10:00:00], ~N[2018-09-17 12:00:00]>,
  user_id: 1
  updated_at: ~N[2018-09-17 16:30:05],
  inserted_at: ~N[2018-09-17 16:30:05],
}

The code examples in this post are also available on GitHub{:target=“blank”}. Thanks to Bachir Çaoui for reviewing a draft version of this post.

Namespaced Rails validators

Mon, 27 Aug 2018 00:00:00 GMT

While going source spelunking, I came across this piece of code in Rails’ ActiveModel:

key = "#{key.to_s.camelize}Validator"

begin
  validator = key.include?("::".freeze) ? key.constantize : const_get(key)
rescue NameError
  raise ArgumentError, "Unknown validator: '#{key}'"
end

active_model/validations/validates.rb{:target=“_blank”} {: .ma0}

This means that you can namespace your custom validators:

# lib/internal/email_validator.rb
module Internal
  class EmailValidator
    def validate_each(record, attribute, value)
      return if value.ends_with?('@private_domain.com')

      record.errors.add(attribute, 'not from private domain')
    end
  end
end

And then use them like this:

# app/models/admin.rb
class Admin < ApplicationRecord
  validates :email, 'internal/email': true
end

Thanks to Bachir Çaoui for reviewing a draft version of this post.

A global .gitignore

Sun, 26 Aug 2018 00:00:00 GMT

A small tip that I’ve come across recently: It is possible to have a global .gitignore file that applies to every Git repository on your machine.

Start by making a .gitignore file in your home directory, with the files you want to ignore, and place in your home directory:

# ~/.gitignore

.vimrc.local
*.swp

.idea
.DS_Store

Then, tell Git to use this file as global .gitignore by running in your shell:

git config --global core.excludesfile ~/.gitignore

You can also take inspiration from my own global .gitignore file. Enjoy!

aliou.me

exe.dev's ssh host header

pi-guardrails: Fix feature and permission gate toggles

pi-neuralwatt: Add Devstral tool-result role ordering compatibility

pi-processes: Fix cwd parameter being ignored on process start

pi-utils-settings: Settings enum fix for disabled values

Thoughts on Claude Code's Workflow feature

pi-synthetic: Pi 0.77.0 compatibility and model metadata refresh

Claude Opus's fast mode

pi-dev-kit: Default Pi core peer dependency ranges to wildcard

pi-theme-jellybeans: Jellybeans Mono themes for Pi

pi-linkup: Migrate Pi core package dependencies

pi-toolchain: Migrate Pi core package dependencies

pi-ts-aperture: Fix gateway model checks and rewrite extension architecture

Custom providers in Pi

Why I Use Pi

A tool that works for me first

Easily extensible

The trade-offs

Coding Agents at Team Scale

The drift problem

Ownership

Maintenance strategies

Hooks and reminders

Regular review cadence

LLM audits

What triggers drift

The Infrastructure Around Your AGENTS.md

Deterministic tools beat prose rules

Scripts as the Interface

Tests as the feedback loop

Example setups

What goes where

The setup in action

Skills for Domain-Specific Knowledge

Your AGENTS.md can be shorter now

Smaller and simpler feedback loops

Upgrading the nvim-treesitter plugin

In-Memory DuckDB with GCS Parquet Files in Cube

The Setup

Key Implementation Details

Performance Characteristics

Trade-offs

Notes

Template Literal Types for Dynamic API Generation

The Pattern

Usage

Trade-offs

Notes

Smooth Theme-Aware Images with CSS Transitions

The Pattern

Smooth Transitions

Usage

Trade-offs

Notes

References

Type-Safe Domain Models with Interface Augmentation in TypeScript

The Problem

The Solution

Implementation

Trade-offs

Notes

Adding Custom Language Support to Shiki

Enabling font ligatures for GitHub Monaspace in Ghostty

Using named captures to extract information from ruby strings

Regular expressions in Ruby

Named captures

Changing perception of objects by overriding the inspect method

Generating constants

Overriding inspect

Using Rails's Attributes API to serialize Value Objects

The attribute API

Creating a custom type

Registering our type

Using it in our model

Further reading

Three ways to ignore files in Git

1. Using a .gitignore file in a repository

2. Using the local exclusion file .git/info/exclude

3. Using a global .gitignore

The `attribute` API

1. Using a `.gitignore` file in a repository

2. Using the local exclusion file `.git/info/exclude`

3. Using a global `.gitignore`

Implementing the `Ecto.Type` behaviour