aliou.me

How do I design the right primitive?

Tue, 30 Jun 2026 15:58:31 GMT

Agents naturally gravitate toward the smallest stable abstraction. So, in an agent-first world, the most important question facing product teams is not what features and why, but instead how do I design the right primitive ?

Building great developer tools (e.g. primitives) has always been an exercise in exquisite taste and deep domain expertise because it requires balancing a set of competing, and often contradictory, forces: namely the tension between expressivity and simplicity. — The primitive is the product

Will be super interesting to see how companies adopt this and it will truly be a differentiator in adoption.

How I use `/tree` and `/spawn` to investigate bugs

Tue, 30 Jun 2026 15:49:38 GMT

Simple context management for when you don’t know what you’re looking for.

Using MicroVMs

Tue, 30 Jun 2026 14:40:25 GMT

A VM that can reach the host’s local network is a VM that can reach things it has no business reaching. So QEMU doesn’t run in the host’s network namespace at all. We unshare into fresh user, net and mount namespaces first. Inside that namespace a small wrapper bind-mounts a resolv.conf pointing at 127.0.0.1 so that QEMU’s built-in slirp DNS isn’t used, then installs blackhole routes for every special-use IP range (RFC 6890, so private networks, link-local, loopback, etc.) before it execs QEMU. slirp4netns then provides the namespace’s outbound internet connection, with --disable-host-loopback, sandbox and seccomp all on. QEMU runs inside that namespace, and the guest’s network card is attached to QEMU’s own built-in user-mode networking. So every packet from the guest takes two hops: guest → QEMU’s slirp → the namespace’s slirp4netns → the internet. The guest never sees the host’s network and the host’s network never sees the guest. All of this is done without needing any privileges!

I’ve been reading a lot about microVMs and Firecracker lately as I work on async agent side projectMore on that soon hopefully. and I find it super interesting how people tackel the same UX problems (in this case: locking down the network).

obsidian-flint: v0.2.0

Tue, 30 Jun 2026 13:42:14 GMT

Release v0.2.0

pi-ts-aperture: v0.8.0

Mon, 29 Jun 2026 15:26:53 GMT

Minor Changes

61e66dc: Filter disabled gateway providers out of proxy and dedicated flows.

/api/providers lists every provider regardless of its disabled flag, so disabled providers and their models leaked into the proxy settings/onboarding checklist, the dedicated provider list, the dedicated model registration, and the proxy gateway-model check.

ApertureClient.providers() now also fetches /v1/models (which only lists models for enabled providers) and:
- drops any provider whose models are all absent from /v1/models, and
- intersects each surviving provider’s models with /v1/models, so only callable models are exposed.
Because every consumer (proxy settings, proxy onboarding, dedicated settings, dedicated onboarding, dedicated runtime, checkMissingModels, health) goes through providers(), all of them now exclude disabled providers without further changes. If /v1/models is unreachable, providers() falls back to the unfiltered /api/providers result so a transient models-endpoint failure never blocks the rest of the client.
9f0f70e: Rename connector discovery meta-tools with an aperture_ prefix and remove the resource proxy tools.
- The four discovery meta-tools are now aperture_connector_list, aperture_connector_tool_search, aperture_connector_tool_describe, and aperture_connector_tool_call. The prefix avoids collisions with other extensions and signals the Aperture provenance.
- Removed connector_resource_search, connector_resource_describe, and connector_resource_serve. Pi does not support MCP resources well enough yet, so the resource browsing flow is gone until that lands. The MCP session still exposes the resource methods; only the Pi tool wrappers were removed.

Keeping the harness's primitives consistent

Mon, 29 Jun 2026 14:17:23 GMT

this is a huge reason why i use pi.

i absolutely do not want my harness regularly changing behavior out from under me, including system prompt changes, on top of an already stochastic llm

Imagine I have /skill-1 and /skill-2, both with disable-model-invocation: true I tell Claude Code: “/skill-1, /skill-2 do XYZ”

Which of the skills will be invoked?

I’ll give you a clue - the behaviour was one thing 3 weeks ago, another thing 1 week ago, and back to the original today.

Matt Pocock (@mattpocockuk) on Twitter

I’ve been playing around making my own harness¹ recently, and also noticed how the behaviour of many Claude features seemingly seem to change every time I spin it up to test something. For my harness, I just decided on a simple principle: trying to keep the primitives (i.e. skills and mid-turn messages affect the agent²) consistent with how I expect agent to react.

Pi remains my main harness, but trying to think about how I work in this agent-looping world. ↩
Most of the time i want immediate steering, but I realized I do use follow-up quite a lot when leaving agents do their thing, especially when running in sandboxes and/or building prototypes where the result itself doesn’t matter much for me. ↩

Tau — a coding agent as a curriculum

Mon, 29 Jun 2026 14:15:49 GMT

introducing tau τ — an educational agent harness that teaches you how to build agent harnesses

This is so cool. I truly think we’re moving towards a world where writing/making a great agent harness ends up becoming accessible to most people because the knowledge is just readily available.

pi-toolchain: v0.10.0

Mon, 29 Jun 2026 13:31:50 GMT

Minor Changes

e86681a: Add a pythonToPython3 rule that rewrites bare python command invocations to python3 when enabled.

pi-edgee: v0.1.0

Mon, 29 Jun 2026 11:36:02 GMT

Minor Changes

983a7b2: Initial Edgee provider extension for Pi.

The Rebel Alliance

Sun, 28 Jun 2026 20:06:17 GMT

Application scope and user experience: Sun Microsystems co-founder Bill Joy famously said: “No matter who you are, most of the smartest people work for someone else.” That applies with particular force to AI. The range of what agents can do — and the variety of industries, workflows, and real-world contexts they touch — is so vast that no single company can build the best solution for all of them. We see a near-infinite opportunity to rewrite the world using agentic AI as foundational infrastructure, and it will require many companies with focused effort.

Thinking a lot about this lately, especially around my own use. I want from using Anthropic models and tools exclusively a year ago to barely using them and instead using different models in different harnesses depending on the task at hand.

It’s very likely that I’m part of the minority of AI users in this case currently but I wonder how long this will become more common ground amongst the majority of users.

pi-ts-aperture: v0.7.0

Sat, 27 Jun 2026 20:40:25 GMT

Minor Changes

6d03cf5: Add connectors extension and restructure shared config.
- Connectors: new extension that discovers MCP tools from Aperture’s /v1/mcp endpoint and registers them with Pi. Splits tools into pinned (first-class Pi tools) and proxied (reached through discovery meta-tools).
- Connectors config: connectors.enabled master switch (default false), connectors.pinnedTools stored as { connectorId; toolName } objects, and connectors.discoveryTools toggle (default true) for the list / search / describe / call meta-tools.
- Resource proxy tools (connector_resource_search / connector_resource_describe / connector_resource_serve) for browsing gateway resources.
- Connector UI redesign with @aliou/pi-utils-ui components and Markdown rendering.
- Settings: new Connectors tab with pinned-tools submenu driven by FilterableChecklist, reading live gateway tool state.
- Config: extract shared config, types, and sync bus to src/shared/; add JSON Schema generation and schema.json; parse Aperture provider config as hujson so commented gateway configs work in settings.
- API: Typebox schemas with response validation, live integration tests, and API-verified connector IDs.
- Feature request/register event dispatching between aperture and connectors extensions.
- Settings: cancel in-flight Aperture fetches when the user presses Esc on an async-loading submenu (AsyncEditor), instead of letting them run to the 5s timeout in the background. The abort signal is threaded through ApertureClient, createMcpSession, and listTools, and late resolves/rejects on a dismissed submenu are ignored so a slow gateway can no longer leave the settings panel unresponsive or silently mutate the draft.

Patch Changes

8bb0984: Tolerate the admin-only /aperture/config endpoint so non-admin Aperture grants can use the extension.
- ApertureClient._fetch now throws an ApertureHttpError that carries the HTTP status, so callers can tolerate specific responses.
- providerConfigInfos() (and providerBaseUrls()) return an empty map on HTTP 403 instead of throwing. /aperture/config requires role:admin and is the only endpoint a non-admin grant cannot access; everything else (/api/providers, /api/connectors, /v1/mcp, model calls) returns 200 for non-admin grants.
- Proxy provider matching already falls back to IDs via /api/providers when provider config info is empty, so onboarding and the proxy settings submenu keep working for non-admin users. Admin users keep the richer base-URL matching. Dedicated mode and connectors never read /aperture/config and are unaffected.
- Other non-403 errors still propagate.

New `us` jurisdiction for Durable Objects

Fri, 26 Jun 2026 20:53:20 GMT

Durable Objects now supports a new us jurisdiction. Create namespaces restricted to the US to keep compute and storage local.

i feel like i have a aluminium hatit’s called a tinfoil hat dummass , but it seems like everyone is preparing for us/non-us tiered system around llm access.

pi-guardrails: v0.15.0

Fri, 26 Jun 2026 20:40:25 GMT

Minor Changes

9f0d736: Add a “decline and stop” option to the permission-gate prompt. Choosing it (press s, or select “Decline and stop” in the RPC fallback) blocks the dangerous command, emits a guardrails:action:blocked event with the new user-stop block source, and aborts the current agent turn so the assistant does not keep going.

Patch Changes

09934f0: Update AGENTS.md to reflect the current three-extension layout and remove the unused, broken test harness.

pi-toolchain: v0.9.0

Sun, 21 Jun 2026 20:40:25 GMT

Minor Changes

11546d1: Add nix shell / devShell rewriting rule

Patch Changes

f0406b1: Update Pi devDependencies to 0.79.9. Widen peerDependency ranges for @earendil-works/pi-coding-agent and @earendil-works/pi-tui from >=0.74.0 <1 to * to match the canonical Pi package convention in docs/packages.md. No runtime behavior changes; no post-0.74 APIs are used.

pi-utils-settings: v0.18.0

Sun, 21 Jun 2026 16:17:07 GMT

Release v0.18.0

pi-synthetic: v0.20.0

Sat, 20 Jun 2026 20:40:25 GMT

Minor Changes

d3a22a8: Add a configurable utility API proxy for quotas and web search, with optional auth gating.

pi-guardrails: v0.14.0

Fri, 19 Jun 2026 20:40:25 GMT

Minor Changes

e012ea0: Migrate pathAccess.allowedPaths from a flat string[] (trailing-slash convention) to an explicit { kind, path } discriminated array.
- file grants match the exact path; directory grants match the directory and its descendants.
- Removes the implicit trailing-slash convention from config, storage, and runtime access matching.
- Fixes skill baseDir grants being matched as exact files instead of directory boundaries.
- Adds migration 010-allowed-paths-objects to convert existing string entries; 009 made format-agnostic so it no longer re-runs on migrated configs.
- Settings UI Allowed paths editor now toggles kind per entry (Tab) instead of relying on trailing slashes.
- Regenerates schema.json with the new AllowedPath definition.
- Bumps @aliou/pi-utils-settings to ^0.17.0 and switches migrations to its built-in Migration.message field. Migration warnings now flow through ConfigLoader.drainMessages() instead of guardrails’ manual addPendingWarning queue (which is retained only for non-migration warnings like invalid regex patterns). The 001 config-backup failure path drops to console.error.

Patch Changes

a7f2980: Bump @aliou/pi-utils-settings to ^0.17.0 and switch migration warnings to its built-in Migration.message field.
- Migration warnings now flow through ConfigLoader.drainMessages() (drained and rendered in the session_start handler) instead of guardrails’ manual addPendingWarning queue.
- The 001 config-backup failure path drops to console.error (it fires on an error path, not a successful run, so it cannot use the message field).
- Removes the now-unused src/shared/warnings.ts module. Invalid-regex handling in pattern compilation silently matches nothing for now (TODO: surface via ctx.ui.notify once compilation is pre-cached at setup).

pi-toolchain: v0.8.0

Fri, 19 Jun 2026 20:40:25 GMT

Minor Changes

0aca4d0: Rewrite: tool_call-based command mutation, new config surface, removed bash integration

Breaking config changes (migrations provided):
- FeatureMode "rewrite" renamed to "mutate"
- features.enforcePackageManager renamed to features.packageManager
- features.rewritePython renamed to features.python
- ui.showRewriteNotifications renamed to ui.showMutationNotifications
- bash.sourceMode and BashSourceMode removed entirely
- Config migrations automatically handle all renames and strip stale keys
New features:
- Command mutation via tool_call hook — event.input.command is mutated in place before shell execution, replacing the spawn-hook/bash-integration approach
- All three behaviors (block, mutate, notify) handled by a single tool_call handler
- Execution order: blockers first, then mutation, then notifications
Removed:
- bash-integration.ts and bash-composition.ts deleted
- createBashTool / BashSpawnContext / spawn hook registration removed
- override-bash and composed-bash source modes removed
- Mutation notifications no longer have [override-bash]/[composed-bash] prefix
Architecture:
- src/ — pure functions, zero Pi runtime imports
- extensions/toolchain/ — Pi extension entry point, hooks, settings UI
- 40 tests covering config defaults, migrations, feature predicates, tool_call hook, and pure mutation engine

pi-ts-aperture: v0.6.0

Fri, 19 Jun 2026 20:40:25 GMT

Minor Changes

b365a22: Refactor Aperture into a single extension with independent dedicated and proxy capabilities.
- Replaced the legacy mode setting with independent dedicated.enabled and proxy.enabled flags. Existing configs are migrated automatically.
- Kept dedicated enabled by default while allowing proxy to be enabled at the same time.
- Moved Pi extension code under extensions/aperture/ and kept Pi-agnostic Aperture API/provider mapping code under src/.
- Switched provider discovery to Aperture’s /api/providers and /aperture/config endpoints.
- Added shared provider mapping so onboarding and settings use the same local Pi registry matching behavior.
- Improved proxy matching with base URL child-path matching and provider ID fallback, including the Codex root URL special case.
- Removed dedicated model ID prefixes, persisted gateway model cache, temporary model-sync onboarding skill/tools, and x-upstream-provider-id request headers.
- Updated onboarding to choose dedicated, proxy, or both, then reload Pi after saving so selected providers register cleanly.
- Updated settings to edit connection, capabilities, proxy providers, dedicated provider filters, onboarding state, and onboarding extension state.

pi-neuralwatt: v0.7.0

Thu, 18 Jun 2026 20:40:28 GMT

Minor Changes

9384557: Handle Neuralwatt stream rate limits before the OpenAI SDK drops response headers. Show layer-specific 429 messages, keep Pi auto-retry detection working, and parse SSE quota comments for live quota updates.

Patch Changes

57e5ac2: Sync model list with live Neuralwatt API. Remove deprecated glm-5-fast (no longer served). Fix zai-org/GLM-5.1-FP8 context window from 202736 to 1048560 (matches the GLM-5.2-backed 1048K deployment).
7ba08db: Sync model list with live Neuralwatt API. Add glm-5.2-fast and promote zai-org/GLM-5.1-FP8 from legacy alias to a standalone canonical entry (now serving a GLM-5.2 test build). Update glm-5.1 and glm-5.1-fast context windows to 1048560 (GLM-5.2-backed, 1048K).

pi-synthetic: v0.19.0

Thu, 18 Jun 2026 20:40:28 GMT

Minor Changes

181230b: Add GLM-5.2 model and update syn:large:text alias
- Add hf:zai-org/GLM-5.2:
  - contextWindow: 524288
  - maxTokens: 65536
  - cost: input $1.4, output $4.4 per 1M tokens (cacheRead $1.4)
  - input: text only
  - reasoning: two effective levels — max (default, highest) and high (lower), per the GLM-5.2 chat template. The Synthetic OpenAI shim rejects literal max (and xhigh errors), so thinkingLevelMap maps Pi’s high -> "high" and xhigh -> "medium" (which falls through to max); minimal/low/medium are hidden.
- Update syn:large:text alias target from hf:zai-org/GLM-5.1 to hf:zai-org/GLM-5.2. Alias inherits the new two-level thinking map from its target.

preview-markdown: v0.7.0

Wed, 17 Jun 2026 16:17:17 GMT

What’s Changed

release: v0.7.0 by @github-actions[bot] in https://github.com/aliou/preview-markdown/pull/9

Full Changelog: https://github.com/aliou/preview-markdown/compare/v0.6.1…v0.7.0

pi-utils-ui: v0.5.0

Wed, 17 Jun 2026 16:17:08 GMT

Release v0.5.0

pi-neuralwatt: v0.6.0

Tue, 16 Jun 2026 20:40:28 GMT

Minor Changes

64a0791: Add a setting for showing legacy Neuralwatt model IDs. Legacy IDs now default to disabled, and existing config files are migrated with a notice pointing users to /neuralwatt:settings.

Patch Changes

2d60a83: Add Kimi K2.7 Code model

pi-dev-kit: v0.8.0

Sun, 14 Jun 2026 16:17:01 GMT

Release v0.8.0

Open Source must win

Sat, 13 Jun 2026 12:22:57 GMT

This article will sound like a schizo ramble, so prepare. To start off I want to state my true beliefs on the matter:

LLMs are not conscious and won’t ever be.

LLMs are inaccurate statistical machines.

Open Source AI is good but must get better.

I have no hatred, or malice for any closed source lab

I respect what I see as my peers at OpenAI, Anthropic, xAI etc.

You might think, well if that’s the case what’s the problem? These models aren’t intelligent, they can’t really replace people, can they?

Something is jamming GPS over Europe. Here's what we found

Fri, 12 Jun 2026 17:36:37 GMT

Yeah that’s my shit.

pi-utils-settings: v0.17.0

Wed, 10 Jun 2026 20:40:28 GMT

Minor Changes

a9e9152: Add optional message field to Migration interface for user-facing migration notifications

Migrations can now declare a message that is queued when the migration runs successfully. Extensions drain messages via ConfigLoader.drainMessages() and display them however they want (typically via ctx.ui.notify in session_start).
- Migration.message: string | ((before, after, filePath) => string | undefined)
  - Static strings are used as-is
  - Factory functions receive both pre-migration and post-migration config
  - Returning undefined from a factory skips the message
- drainMessages() returns string[], queue is cleared on drain
- Failed migrations do not queue messages
- Message factory errors are caught gracefully (logged, not queued)

exe.dev's ssh host header

Mon, 08 Jun 2026 16:07:14 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

sesame: @aliou/sesame@0.10.0

Sun, 07 Jun 2026 20:40:28 GMT

Minor Changes

84d611e: Fix high CPU in sesame watch caused by repeated full-directory re-indexing and redundant file I/O:
- Add readFirstLine utility that reads only the first 4 KiB of a file instead of loading the entire contents into memory.
- Fix PiParser.canParse() to use readFirstLine instead of reading the whole file just to check the header.
- Fix indexer mtime-skip path to use readFirstLine instead of readFileSync of the entire file.
- Add indexFile(db, filePath) for targeted single-file re-indexing without scanning the whole directory.
- Watch handler now does per-file debounce and targeted indexing for .jsonl changes, falling back to full scan only when no filename is available.
- Queue adds SourceConfig.files for targeted paths, mergeSource() to coalesce pending work, and a 2 s cooldown between consecutive indexing runs to prevent back-to-back re-indexes when Pi keeps appending to the active session.

Rift

Fri, 05 Jun 2026 17:36:37 GMT

we landed on a pretty good workflow for doing parallel work in OpenCode

this demo is with git worktrees but i also preview an alternative we’re working on at the end

this will be in 1.6.0

— @thdxr

Rift looks interesting.

Pi Agent explained in 6min

Thu, 04 Jun 2026 17:36:37 GMT

Take a look, I really like how this is explained.

sesame: @aliou/sesame@0.9.0

Tue, 02 Jun 2026 20:40:28 GMT

Minor Changes

dc5e9aa: Library changes:
- Add listSessions and getSession to the public library API.
- Keep the parser and indexing flow explicitly Pi-only after the workspace split.
- Refresh the Sesame skill and usage documentation.
CLI changes:
- Bundle @aliou/sesame into the standalone SEA binary.
- Replace lazy dynamic command imports with static imports in the CLI entrypoint.
- Refresh CLI help, metadata, and usage documentation.
- Split release automation so the library publishes to npm and the CLI creates its own GitHub release with binaries.
Repository changes:
- Split the project into @aliou/sesame and private @aliou/sesame-cli workspace packages.
- Upgrade Biome and lint plugins.
- Remove the unused Pi extension package.

sh: v0.2.0

Tue, 02 Jun 2026 20:40:28 GMT

Minor Changes

5ef2b75: Add agent skill for AST usage

New skills/sh-ast/SKILL.md provides documentation and examples for agents using the parser programmatically: extracting commands, analyzing pipelines, finding variables, checking for unsafe patterns, and traversing the AST.

pi-utils-settings: v0.16.0

Mon, 01 Jun 2026 20:40:24 GMT

Minor Changes

923804e: Allow buildSchemaUrl callers to customize schema hosting URLs with baseUrl or template options.
ec86921: Add onBeforeClose to intercept settings UI close requests before discarding drafts.

obsidian-flint: v0.1.0

Mon, 01 Jun 2026 16:17:09 GMT

Release v0.1.0

Thoughts on Claude Code's Workflow feature

Fri, 29 May 2026 16:00:13 GMT

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

In addition, the UI of Claude feels a bit overwhelming to me.

There’s also some strong validations around making the workflow deterministic and I wonder if it could still be handled? I’m also curious on why they’re not giving guidance to the model about this and/or linting workflow code to have this be caught before the harness runs the workflow.

granola-cli: v0.2.0

Thu, 28 May 2026 16:17:16 GMT

What’s Changed

release: v0.2.0 by @github-actions[bot] in https://github.com/aliou/granola-cli/pull/2

Full Changelog: https://github.com/aliou/granola-cli/compare/v0.1.0…v0.2.0

granola-cli: v0.1.0

Thu, 28 May 2026 16:17:16 GMT

What’s Changed

release: v0.1.0 by @github-actions[bot] in https://github.com/aliou/granola-cli/pull/1

New Contributors

@github-actions[bot] made their first contribution in https://github.com/aliou/granola-cli/pull/1

Full Changelog: https://github.com/aliou/granola-cli/commits/v0.1.0

Claude Opus's fast mode

Thu, 28 May 2026 16:05:27 GMT

Missed that claude/opus has a fast mode so I had Pi make a quick extension¹ to play with it. Below, a comparison with the vanilla Opus.

Don’t look too closely at that horrendous code that Kimi with reasoning disabled produced. ↩

pi-synthetic: v0.18.0

Wed, 27 May 2026 20:40:24 GMT

Minor Changes

0fde0fa: Add syn:large:text, syn:small:text, syn:large:vision, syn:small:vision alias models

pi-neuralwatt: v0.5.0

Mon, 25 May 2026 20:40:24 GMT

Minor Changes

3c467b3: Remove live model sync from provider endpoint. Models are now purely hardcoded in src/extensions/provider/models.ts and validated against the Neuralwatt /v1/models API at test time.

Removed:
- src/lib/fetch-models.ts (live model fetch + mapApiModel)
- src/utils/is-offline.ts and its test (only used by fetch flow)
- src/extensions/provider/provider-payload.ts (buildModelsPayload wrapper)
- NeuralwattModelConfig type extension (uses ProviderModelConfig directly)
- fast field on model entries
- Live re-registration on session_start
Simplified:
- NEURALWATT_MODELS_CACHE → NEURALWATT_MODELS
- Provider registers once on startup with hardcoded list
- Tests now fetch live API and compare prices, context windows, reasoning, vision, and model existence

Patch Changes

c10a189: Add requiresReasoningContentOnAssistantMessages compat flag for reasoning models. Neuralwatt docs confirm these models need reasoning_content on replayed assistant turns to preserve chain-of-thought across turns in agentic conversations.

pi-guardrails: v0.13.0

Fri, 22 May 2026 20:40:24 GMT

Minor Changes

0f4f478: Add guardrails:action:prompted event that fires when guardrails shows an interactive prompt to the user, before the user has responded. This complements the existing guardrails:action:blocked (post-decision) and guardrails:risk:detected events.

preview-markdown: v0.6.0

Tue, 19 May 2026 16:17:17 GMT

What’s Changed

release: v0.6.0 by @github-actions[bot] in https://github.com/aliou/preview-markdown/pull/7

Full Changelog: https://github.com/aliou/preview-markdown/compare/v0.5.0…v0.6.0

pi-guardrails: v0.12.0

Mon, 18 May 2026 20:40:24 GMT

Minor Changes

bd90cdf: Remove the permission gate command explainer and its subagent runtime.
5cef4eb: Split Guardrails into separate policy, path-access, and permission-gate extensions backed by shared config, generated JSON schema support, and refreshed README documentation.

Breaking: renamed public event bus events to guardrails:action:blocked, guardrails:risk:detected, guardrails:feature:request, and guardrails:feature:register. Blocked and risk events now use core Action and Safety payload shapes.

Patch Changes

7b01ab4: Move config migrations into shared modules and only show onboarding when no guardrails config exists.
5d76145: Update settings utilities to the latest version.

vite-plugin-obsidian: @aliou/vite-plugin-obsidian@0.2.0

Sun, 17 May 2026 16:17:12 GMT

Release @aliou/vite-plugin-obsidian@0.2.0

nvim-pi: v0.2.0

Fri, 15 May 2026 20:40:23 GMT

Changes

Update Pi compatibility to 0.74.0.
Migrate Pi imports and package metadata to @earendil-works scope.
Migrate TypeBox usage to typebox 1.x.
Update bundled Pi utility dependencies.
Improve Neovim hook cancellation/path handling for current Pi APIs.

Verification

pnpm typecheck
pnpm lint
pnpm test

pi-linear: 0.1.0

Fri, 15 May 2026 20:40:23 GMT

What’s Changed

feat: show delegated agents in assignee output by @aliou in https://github.com/aliou/pi-linear/pull/1

New Contributors

@aliou made their first contribution in https://github.com/aliou/pi-linear/pull/1

Full Changelog: https://github.com/aliou/pi-linear/commits/0.1.0

Self-upgradable software: a Pi setup

Fri, 15 May 2026 15:57:09 GMT

Closing my open tabs and finally read Mikker’s post. Borrowed his review workflow but wanted to have it in a Ghostty split (thanks to AppleScript).

I then had Kimi and GLM figure it out and make me an extension.

vite-plugin-obsidian: v0.1.0

Thu, 14 May 2026 16:17:12 GMT

Release v0.1.0

A prompt for knowledge gaps

Wed, 13 May 2026 15:48:58 GMT

Been using variations of this prompt every time I notice a gap in my knowledge. Choosing a starting point that I broadly understand and then throwing stuff I literally don’t know about works super well for me.

Full verbatim prompt

I want to learn more and understand what’s fine tuning for llm models, what’s lora, how does https://thinkingmachines.ai/ ‘s products fit in this etc. to do so, i want to use coding agent traces as training data, from hugging face (see https://huggingface.co/changelog/agent-trace-viewer ) , in particular traces from pi.

let’s assume i know nothing about what is finetuning and how it works. let’s go through this blog post https://leoniemonigatti.com/blog/fine-tuning-lfm2-5-1-2b-instruct-with-grpo.html and quizz me on it to see what is my current understanding. use the current directory as scratchpad / notes. download the markdown of the article here so I/we can annotate it . curl it using this url https://markdown.new/https://leoniemonigatti.com/blog/fine-tuning-lfm2-5-1-2b-instruct-with-grpo.html

LLM CLI tools in shebang lines

Mon, 11 May 2026 16:04:26 GMT

New TIL: I figured out how to use my LLM CLI tool in a shebang line, which means you can write executable scripts in English, or hook up more complex scripts with a snippet of YAML template

— @simonw

It’s becoming a meme at this point, but here’s a Pi extension to do the same:

Also watch GLM-5.1 completely overthink while trying to speed up the video and add a fast-forward overlay.

pi-processes: v0.9.0

Sat, 09 May 2026 20:40:23 GMT

Minor Changes

8f15f76: Prevent crash on /new with running background processes

Crafting Interpreters

Sat, 09 May 2026 15:48:29 GMT

Current status.

pi-linkup: v0.11.0

Fri, 08 May 2026 20:40:23 GMT

Minor Changes

a9ca926: Migrate Pi core package dependencies from @mariozechner/* to @earendil-works/* namespace.
- @mariozechner/pi-coding-agent → @earendil-works/pi-coding-agent 0.74.0
- @mariozechner/pi-ai → @earendil-works/pi-ai 0.74.0
- @mariozechner/pi-tui → @earendil-works/pi-tui 0.74.0

Patch Changes

cbec48a: Truncate Linkup search, answer, and fetch result blocks, with full content saved to temp files when truncated.

pi-synthetic: v0.17.0

Fri, 08 May 2026 20:40:23 GMT

Minor Changes

ef66a62: Migrate Pi core package dependencies from @mariozechner/* to @earendil-works/* namespace.
- @mariozechner/pi-coding-agent → @earendil-works/pi-coding-agent 0.74.0
- @mariozechner/pi-tui → @earendil-works/pi-tui 0.74.0
- @aliou/pi-utils-settings bumped to ^0.15.0
- @aliou/pi-utils-ui bumped to ^0.4.0

pi-toolchain: v0.7.0

Fri, 08 May 2026 20:40:23 GMT

Minor Changes

e4b7f9e: Migrate Pi core package dependencies from @mariozechner/* to @earendil-works/* namespace.
- @mariozechner/pi-coding-agent → @earendil-works/pi-coding-agent 0.74.0
- @aliou/pi-utils-settings bumped to ^0.15.0

pi-dev-kit: v0.7.0

Thu, 07 May 2026 20:40:23 GMT

Minor Changes

e3d118d: Update Pi dev kit guidance, entrypoints, and runtime dependencies for Pi 0.74.0 and the @earendil-works/* package namespace.

pi-utils-settings: v0.15.0

Thu, 07 May 2026 20:40:23 GMT

Minor Changes

af07e77: Update dependencies to use @earendil-works/pi- packages and bump @aliou/pi-utils-ui to v0.4.0

pi-utils-ui: v0.4.0

Thu, 07 May 2026 20:40:23 GMT

Minor Changes

e8bf742: Migrate package scopes from @mariozechner to @earendil-works

All @mariozechner/pi-coding-agent and @mariozechner/pi-tui dependencies, peer dependencies, and imports are now @earendil-works/pi-coding-agent and @earendil-works/pi-tui. Minimum supported version raised to 0.74.0.

GitHub PR and issue autocomplete for Pi

Thu, 07 May 2026 15:52:24 GMT

Currently cleaning up a backlog of issues and PRs in a client’s repo and was tired of alt-tabbing between Pi and my browser, so made a quick Pi extension to autocomplete GitHub PRs and issues.

Never going to use this ever again, but might be useful to other people so sharing it as a gist.

pi-synthetic: v0.16.0

Wed, 06 May 2026 20:40:17 GMT

Minor Changes

62e6902: Use event-driven Synthetic quota updates without polling.

Quota data is now extracted from the x-synthetic-quotas response header on Synthetic provider responses and stored centrally. Usage status and quota warnings read the latest quota snapshot through short-lived callbacks from fresh Pi lifecycle contexts, avoiding stale ExtensionContext crashes after reloads or session switches.
1176b1d: Avoid stale contexts in status update.

Use events to retrieve quotas from the shared store.

pi-utils-settings: v0.14.0

Tue, 05 May 2026 20:40:17 GMT

Minor Changes

405e0e5: Update settings editor components to render inside shared @aliou/pi-utils-ui panels while preserving the existing pi-utils-settings component APIs.

pi-utils-ui: v0.3.0

Tue, 05 May 2026 20:40:17 GMT

Minor Changes

4fcf693: Rewrite components from scratch

Amp's read thread tool

Tue, 05 May 2026 15:57:05 GMT

Was about to make a Pi extension to communicate between sessions, but actually only needed Amp’s read thread tool.

pi-synthetic: v0.15.0

Sat, 02 May 2026 20:40:17 GMT

Minor Changes

85d9896: Add setting to control Synthetic-proxied models. New installs default to Synthetic-hosted models only, while existing configs keep proxied models enabled.

pi-synthetic: v0.14.0

Sat, 02 May 2026 20:40:17 GMT

Minor Changes

327f098: Update Pi peer dependencies to 0.72.0. Migrate reasoningEffortMap to thinkingLevelMap per Pi 0.72.0 API. Replace session_switch event with session_start. Swap @sinclair/typebox for typebox. Add Kimi K2.5 model. Set reasoning: false for Llama 3.3 70B.

pi-neuralwatt: v0.2.0

Wed, 29 Apr 2026 20:40:17 GMT

Minor Changes

6f4672e: Fetch live models from Neuralwatt API on session start. The extension registers with a hardcoded model cache immediately on startup, then fetches /v1/models on session start and re-registers the provider with live data (including pricing, capabilities, and limits from the new API metadata). A notification is shown when live models differ from the cache. Falls back to the hardcoded cache if the fetch fails.

Patch Changes

0669972: Align model definitions with Neuralwatt API metadata: set reasoning true for GPT-OSS 20B, set reasoning false for Kimi K2.6 Fast, and remove unsupported supportsReasoningEffort from GLM-5.1, Kimi K2.5, Kimi K2.6, MiniMax M2.5, Qwen3.5 397B, and Qwen3.6 35B. Add supportsReasoningEffort to GPT-OSS 20B.

pi-ts-aperture: v0.5.0

Thu, 23 Apr 2026 20:40:17 GMT

Minor Changes

b51d282: Rewrite extension architecture. Moves core logic to src/lib/, introduces ApertureRuntime class with dependency injection, replaces lifecycle hooks with session_start + onSync callback pattern, and adds provider unregistration with user notification.
00ba115: Add streamSimple wrapper that sends x-session-id header with the Pi session ID. This groups all requests from the same Pi session together in the Aperture dashboard.

Patch Changes

cda19d3: Drop models from registerProvider call. Rely on the baseUrl-override path instead, which preserves built-in model definitions (reasoning, compat, thinking levels) and only updates the endpoint URL.

Just

Tue, 21 Apr 2026 15:48:29 GMT

Can’t help but re-read this every time I write “just” somewhere.

pi-neuralwatt: v0.1.0

Mon, 20 Apr 2026 20:40:17 GMT

Minor Changes

6b95048: Initial release of pi-neuralwatt — Neuralwatt inference API provider with energy transparency.

pi-processes: v0.8.0

Mon, 20 Apr 2026 20:40:17 GMT

Minor Changes

da0de08: Remove @aliou/pi-evals devDependency

pi-guardrails: v0.11.0

Fri, 17 Apr 2026 20:40:17 GMT

Minor Changes

11e88c0: Fix dd pattern (if= to of=) and expand dangerous command detection

Fixed the dd pattern to check for of= (output file) instead of if= (input file), as of= is the actual dangerous write operation. Also extracted dangerous command matchers to a separate module and added new patterns for:
- Privilege escalation: doas, pkexec
- Secure destruction: shred, wipefs, blkdiscard
- Disk partitioning: fdisk, sfdisk, cfdisk, parted, sgdisk
- Container escapes: docker/podman run with —privileged, —pid=host, —network=host, —userns=host, root mounts, docker socket mounts
Improved existing matchers to handle long options like —recursive, —force, etc.

Fixes #22
ba06d72: Add path access feature: restrict tool access to current working directory with allow/ask/block modes. Grants can be file-level (exact match) or directory-level (trailing slash convention). Session grants persist in memory, project grants persist in local config.

Patch Changes

2db56c2: Fix permission gate bypass in RPC mode: deny-by-default when ctx.ui.custom() returns undefined, with fallback to ctx.ui.select().

pi-synthetic: v0.13.0

Thu, 16 Apr 2026 20:40:20 GMT

Minor Changes

7e83e5f: feat(settings): make synthetic features configurable

Add shared Synthetic feature settings with a synthetic:settings command and pi config support. Web search, usage status, quota warnings, quotas command, and subBar integration can now be enabled or disabled individually. Web search, usage status, quota warnings, and subBar polling react to settings changes live. The quotas command still requires restart to fully unload.

Add an initial v1-seed-defaults migration that writes the current defaults to disk and bumps configVersion to 1. On first load, fresh installs seed the global config automatically. A one-time notice is shown on session start pointing users to pi config and the /synthetic:settings command.
ed77440: feat(usage-status): footer status bar showing live quota usage

Add usage-status extension that displays live quota percentages (weekly credits, rolling 5h, etc.) in the footer status bar when a Synthetic model is active. Colors follow the same severity assessment as quota-warnings for consistency. Auto-refreshes every 60s and after each turn. Hides for non-Synthetic models.

pi-synthetic: v0.12.0

Tue, 14 Apr 2026 20:40:20 GMT

Minor Changes

015e984: Add quota-warnings extension: automatic notifications when approaching or exceeding Synthetic API quotas
- Extract quota severity logic into shared src/utils/quotas-severity.ts (4-level RiskSeverity: none/warning/high/critical with usedFloor gating, showPace/paceScale support, limited flag handling)
- Refactor quotas TUI display to use shared severity utils
- New quota-warnings extension hooks into session_start and agent_end to check quotas and emit ctx.ui.notify() on severity transitions
- Transition-only notifications: escalation always notifies, high/critical have no cooldown, warning has 60min cooldown
- Notification messages use correct terminology (regen/tick/resets) and precise time formatting (2h13m)

Patch Changes

c1256cf: Fix GLM-4.7 model config: input text-only, reduced input/cacheRead cost

pi-utils-ui: v0.2.0

Tue, 14 Apr 2026 20:40:20 GMT

Minor Changes

e0ad809: Refactor Frame to extend Container from pi-tui, inheriting addChild, removeChild, and clear. borderColor is now required. Children are no longer accepted via constructor options — use addChild instead.
Add Tree component for rendering nested data with box-drawing characters

pi-synthetic: v0.11.0

Mon, 13 Apr 2026 20:40:20 GMT

Minor Changes

abe28bd: Add r key binding to the quotas command to refetch and refresh quota data without closing the panel.

Patch Changes

52ee513: Rework quotas command display: unified progress bar with single-char pace marker, updated labels (Credits / week, Requests / 5h, Search / hour), percent%/total stat format, and +amount in time subtitles. Drops legacy subscription fallback.

pi-guardrails: v0.10.0

Fri, 10 Apr 2026 20:40:20 GMT

Minor Changes

6356335: Add command-based onboarding for new users.
- add /guardrails:onboarding command and session-start hint when setup is pending
- replace auto-open onboarding with explicit overlay flow
- add onboarding completion marker for config compatibility and first-run state
- improve onboarding wizard copy and defaults/recap UX

Patch Changes

828c019: Fix dangerous command confirmation UI scrolling for long multi-line commands.
97597c2: Fix home-directory default policy rules so ~-based patterns match correctly and expand to the current user’s home directory during blocking and existence checks.

pi-synthetic: v0.10.0

Wed, 08 Apr 2026 20:40:20 GMT

Minor Changes

9d40b3f: Add support for new Synthetic API quota format with weekly token credits and rolling 5-hour limits
- Display weekly token quota with credits-based tracking ($X.XX/$Y.YY format)
- Show rolling 5-hour request quota with tick-based regeneration
- Use simple indicator bar for new quota types (marker instead of fill)
- Display regeneration info: ”+$X.XX in Xh” for credits, “+X in Xm” for requests
- Maintain backward compatibility with legacy subscription format
- Fix division-by-zero bugs and fragile currency parsing
- Harden edge cases with safePercent() and parseCurrency() helpers

pi-synthetic: v0.9.0

Mon, 06 Apr 2026 20:40:20 GMT

Minor Changes

a85b467: Switch to Pi AuthStorage for credential handling
- Replace direct env var reads with AuthStorage wrapper
- Remove preflight subscription gating - tools/commands always register
- Credentials resolved at call time, not module load
- Resolve key inside each poll tick for sub-integration
- Clear error messages guide users to ~/.pi/agent/auth.json
- Remove web-search/hooks.ts (no longer needed)

pi-utils-settings: v0.13.0

Mon, 06 Apr 2026 20:40:20 GMT

Minor Changes

cb080f5: Remove displayToStorageValue helper. The default change handler now stores raw strings as-is instead of coercing “on”/“off”/“enabled”/“disabled” to booleans. Use onSettingChange to convert display values to the correct storage types.

Building SyntaQLite

Sun, 05 Apr 2026 15:48:29 GMT

Banger.

Custom providers in Pi

Sat, 04 Apr 2026 15:12:15 GMT

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

pi-ts-aperture: v0.4.0

Fri, 03 Apr 2026 20:40:20 GMT

Minor Changes

2240e43: Extract pure core functions from Pi glue.

Move decision-making logic into pure functions in src/core/:
- URL helpers: normalizeInputUrl, resolveGatewayUrl, resolveProviderBaseUrl
- Plan builders: buildApplyPlan, planConfigChange
All core logic is now unit-testable with no Pi dependencies.
80ef5c2: Add per-provider gateway model checking.

Validates which models are available on the gateway per configured provider.
5e2d45f: Add gateway model checking to settings UI.

Shows model availability status in the settings interface.
748d8e1: Rewrite setup wizard with Wizard + FuzzyMultiSelector.

Improved UX for configuring Aperture with better multi-select support.

Patch Changes

c60bd7f: Co-locate unit tests with source files.

Moves core unit tests from tests/core/ to src/core/*.test.ts.
124404c: Rewrite e2e tests to use RpcClient.

Modernizes test infrastructure for better reliability.
ccf5c1d: Replace local ModelInfo type with Model from pi-ai.

Uses Pi canonical model type instead of duplicating the shape.
7fb1c7c: Update Pi packages to 0.64.0.

pi-processes: v0.7.0

Thu, 02 Apr 2026 20:40:20 GMT

Minor Changes

80f81ff: perf: replace polling timers with event-driven output rendering
a8965ad: Add runtime log watch alerts for managed processes.
- New logWatches option on process tool start action
- Watches match log lines on stdout, stderr, or both
- Default one-time behavior (repeat: false), with optional repeat mode
- On watch match, emit visible UI event and trigger an immediate agent turn
- Invalid watch config (including bad regex patterns) now fails fast at start time
2f33586: Process lookup now uses exact ID matching only. Fuzzy name/command matching via find() has been removed. The id parameter in tool actions accepts only the process ID returned by start and list. The /ps list UI merges the ID and Name columns into a single “Process” column showing name (id).

pi-dev-kit: v0.6.0

Wed, 01 Apr 2026 20:38:31 GMT

Minor Changes

ff71e6f: Overhaul tool rendering guidelines and update extension tools to match.

Skill updates:
- tools.md: throw errors, ToolCallHeader/ToolBody/ToolFooter from pi-utils-ui, stable isPartial, conditional footer, truncateHead + temp file, promptSnippet/promptGuidelines, multi-action tool pattern
- structure.md: core/lib pattern, action modules, config migrations, settings command, auth wizard
- additional-apis.md: two-tier guidance (per-tool metadata vs system prompt hooks)
- testing.md: unit testing core logic, testable execute with DI, handler pattern, Pi stub
- SKILL.md: new critical rules, updated checklist, standalone repo references
Tool updates:
- All tools: add promptSnippet/promptGuidelines, throw errors, simplify details
- changelog-tool: conditional footer, keyHint for expand
- docs-tool: ToolBody with showCollapsed, conditional footer
- package-manager-tool: throw on missing package.json
- version-tool: simplified details

pi-linkup: v0.10.0

Wed, 01 Apr 2026 20:38:31 GMT

Minor Changes

42481a6: refactor: per-extension entries to fix duplicate command registration

Replace monolithic entry with 4 separate extension entries:
- web-search, web-answer, web-fetch (tools)
- command-balance (shows API credits)
Delete broken singleton pattern from setup.ts that caused commands to appear 3x in palette (GitHub #24). Pi loads each extension in separate module context, so module-level guards failed. Each entry now calls ensureLinkupReady() independently.

Also remove obsolete command-settings (guidance settings no longer exist; tools declare their own promptGuidelines).

pi-linkup: v0.9.0

Wed, 01 Apr 2026 20:38:31 GMT

Minor Changes

92703e6: Truncate large linkup_web_fetch outputs in tool results and save the full fetched content to a temp file.
aac0899: Add a limit parameter to linkup_web_search so agents can cap returned result count.

pi-toolchain: v0.6.0

Tue, 31 Mar 2026 20:38:31 GMT

Minor Changes

c1cc093: Add configurable bash.sourceMode with deterministic override-bash and composed-bash routing for rewrite features.

pi-utils-settings: v0.12.0

Sun, 29 Mar 2026 20:38:31 GMT

Minor Changes

9659754: Add subOptions support and showHints option to FuzzyMultiSelector

linear-cli: v0.5.0

Fri, 27 Mar 2026 16:17:14 GMT

What’s Changed

release: v0.5.0 by @github-actions[bot] in https://github.com/aliou/linear-cli/pull/7

Full Changelog: https://github.com/aliou/linear-cli/compare/v0.4.0…v0.5.0

pi-utils-settings: v0.11.0

Wed, 25 Mar 2026 20:38:42 GMT

Minor Changes

ef47f9c: Add small-list mode to FuzzySelector via searchThreshold (default 7). When item count is at or below the threshold, it now renders a simple Up/Down/Enter list without a search input while keeping callbacks and currentValue pre-selection behavior consistent.

linear-cli: v0.4.0

Wed, 25 Mar 2026 16:17:14 GMT

What’s Changed

release: v0.4.0 by @github-actions[bot] in https://github.com/aliou/linear-cli/pull/6

Full Changelog: https://github.com/aliou/linear-cli/compare/v0.3.0…v0.4.0

Pi Init extension

Mon, 23 Mar 2026 15:52:24 GMT

Needed to scaffold a project this morning with an AGENTS.md and liked how Claude Code’s new /init looked, so had Pi figure out how it works and make its own version.

Another one-time use extension.

Source

pi-dev-kit: v0.5.0

Fri, 20 Mar 2026 20:38:31 GMT

Minor Changes

a214efa: Rename the package from @aliou/pi-extension-dev to @aliou/pi-dev-kit.

The package continues on the same release line under the new name. Update installation docs and package metadata to match the rename.

linear-cli: v0.3.0

Fri, 20 Mar 2026 16:17:14 GMT

What’s Changed

release: v0.3.0 by @github-actions[bot] in https://github.com/aliou/linear-cli/pull/5

Full Changelog: https://github.com/aliou/linear-cli/compare/v0.2.2…v0.3.0

pi-linkup: v0.8.0

Wed, 18 Mar 2026 20:38:36 GMT

Minor Changes

a4905b5: Expose Linkup tools as separate Pi extensions so pi config can enable or disable them individually.
7334153: Redesign all tool UIs to use structured rendering components
- web-search: ToolCallHeader, Container/Markdown/ToolFooter, collapsed/expanded states with blockquote snippets
- web-answer: ToolCallHeader, answer preview collapsed, full Markdown answer expanded with sources list
- web-fetch: ToolCallHeader, Markdown content preview matching read_url pattern (8 lines collapsed, full expanded)
- All tools: throw errors instead of returning error details, proper error display via content extraction
- All tools: use keyHint for expand hints, ToolFooter for metadata
cb71445: Redesign web search tool UI to match pi-synthetic pattern
- Use ToolCallHeader and ToolFooter from @aliou/pi-utils-ui for consistent styling
- Collapsed view shows result count with first result name and expand hint
- Expanded view shows each result with name, URL, and a 5-line blockquote snippet rendered as Markdown
- Error handling uses throw instead of returning error details, matching the pi framework convention
- Errors now display the actual error message instead of misleading “no results”
- Footer shows result count only
- Show search depth as option arg in header when non-standard

Patch Changes

290df71: Add a Vitest-based Pi runtime harness to verify per-tool pi config loading, shared command registration, and dynamic Linkup system prompt guidance. Closes #17.

You still need to think

Wed, 18 Mar 2026 15:48:29 GMT

The models are getting better and better which makes it easy to forget to not delegate your thinking.

pi-synthetic: v0.8.0

Tue, 17 Mar 2026 20:38:36 GMT

Minor Changes

606e829: Redesign web search tool UI to match read_url pattern
- Use ToolCallHeader and ToolFooter from @aliou/pi-utils-ui for consistent styling
- Collapsed view shows result count with first result title and expand hint
- Expanded view shows each result with title, URL, published date, and a 5-line blockquote snippet rendered as Markdown
- Error handling uses throw instead of returning error details, matching the pi framework convention
- Errors now display the actual error message instead of misleading “no results”
- Footer shows result count only (no redundant “failed: no”)

preview-markdown: v0.5.0

Tue, 17 Mar 2026 16:17:17 GMT

What’s Changed

release: v0.5.0 by @github-actions[bot] in https://github.com/aliou/preview-markdown/pull/6

Full Changelog: https://github.com/aliou/preview-markdown/compare/v0.4.1…v0.5.0

Linear's agent interaction guidelines in Pi

Mon, 16 Mar 2026 15:52:24 GMT

Finally got around to reading Linear’s Agent interaction guidelines and did a quick implementation with Pi. It was pretty simple to set up and I kinda like the UX!

Take a look at the code on GitHub.

fastmail-cli: v0.2.0

Sun, 15 Mar 2026 16:17:15 GMT

What’s Changed

release: v0.2.0 by @github-actions[bot] in https://github.com/aliou/fastmail-cli/pull/3

Full Changelog: https://github.com/aliou/fastmail-cli/compare/v0.1.1…v0.2.0

pi-synthetic: v0.7.0

Thu, 12 Mar 2026 20:38:36 GMT

Minor Changes

4547220: Add NVIDIA Nemotron-3-Super-120B-A12B-NVFP4 model

Patch Changes

018f25d: Fix Qwen3.5-397B-A17B output pricing (3 -> 3.6 per million tokens)

Restoring Ghostty tabs and splits

Thu, 12 Mar 2026 15:48:58 GMT

Had to update Ghostty to fix that annoying auto-scroll bug but didn’t want to lose my open tabs. Asked Pi/GPT-5.4 to dump and restore my tabs and splits. It mostly worked and I’m never going to reuse this.

pi-toolchain: v0.5.0

Wed, 11 Mar 2026 20:38:36 GMT

Minor Changes

520acf2: Add optional warning-level notifications for rewritten commands so demos and debugging make toolchain rewrites visible.

pi-toolchain: v0.4.0

Tue, 10 Mar 2026 20:38:36 GMT

Minor Changes

346fee2: Feature modes: rewriter features now support "disabled" | "rewrite" | "block" instead of booleans. In "block" mode the bash tool is not overridden — commands are blocked via tool_call hook instead. Config is auto-migrated on first load. preventBrew and preventDockerSecrets have been removed; use @aliou/pi-guardrails instead.

linear-cli: v0.1.0

Tue, 10 Mar 2026 16:17:14 GMT

Full Changelog: https://github.com/aliou/linear-cli/commits/v0.1.0

pi-utils-settings: v0.10.0

Fri, 06 Mar 2026 20:38:36 GMT

Minor Changes

494cebe: fix: local scope no longer resolves to ~/.pi, creates .pi/extensions/ in cwd when missing
- findLocalConfigPath now stops before $HOME so ~/.pi is never matched as project-local
- save("local") falls back to {cwd}/.pi/extensions/{name}.json when no .pi dir exists in the tree

sesame: v0.8.0

Fri, 06 Mar 2026 20:38:36 GMT

Minor Changes

9ef404e: allow searching "" to list sessions

pi-utils-settings: v0.9.0

Thu, 05 Mar 2026 20:38:28 GMT

Minor Changes

1006f56: Add JSON Schema support: buildSchemaUrl helper and schemaUrl option for ConfigLoader. When set, save() injects $schema as the first key and load() strips it from parsed config.

pi-guardrails: v0.9.0

Wed, 04 Mar 2026 20:38:28 GMT

Minor Changes

78f640d: Improve settings UX with guided policy creation and top-level examples tab.
- Add a real wizard flow for creating a new policy in settings (name, protection, patterns, review), then open the policy editor.
- Move policy examples into a dedicated top-level Examples tab using extraTabs.
- Ask target scope each time an example is applied; do not persist last selected scope.
- Upgrade @aliou/pi-utils-settings to ^0.8.0 to use extraTabs and combined settings theme support.
- Keep pattern editor compact while preserving Ctrl+R regex toggle in form mode.

pi-guardrails: v0.8.0

Wed, 04 Mar 2026 20:38:28 GMT

Minor Changes

e8eea2f: Redesign file protection from legacy envFiles to a new policies system with per-rule protection levels (noAccess, readOnly, none), add migration from old config fields, and replace the old env hook with a general policies hook.
e762afc: Add opt-in LLM command explanations to the permission gate dialog with configurable model and timeout settings, plus graceful fallback when model resolution or explanation calls fail.

Patch Changes

e4a8438: Update docs and migration semantics for config schema versioning. Bump @aliou/pi-utils-settings to latest 0.5.x, clarify fallback behavior in README/AGENTS, ignore .pi/settings.json, and ensure migrated configs write the current schema version without lexicographic version comparisons.
d9f91cd: Harden permission-gate command explanation prompt handling, fix dangerous-pattern matching flow after successful AST parses, and improve policy enforcement by skipping empty rules and resolving onlyIfExists checks relative to session cwd. Also refresh README/AGENTS docs for the policies-based architecture.

pi-processes: v0.6.0

Wed, 04 Mar 2026 20:38:28 GMT

Minor Changes

67da7e3: Add /ps:dock, /ps:focus, /ps:logs commands. Add deprecated /process:* commands. Replace status widget with log dock. Preserve ANSI colors. Fix duplicate notifications. Use proper ThemeColor type.
8cd4247: Exclude local implementation plan documents from version control.
47bd895: Split widget hook into focused modules for types, status rendering, and setup.
905a499: Add write action to write to process stdin

The process tool now supports writing to a running process’s stdin:
- process action=write id=proc_1 input="hello\n" - write data to stdin
- process action=write id=proc_1 input="quit\n" end=true - write and close stdin
Useful for interactive programs, testing RPC mode, and any scenario requiring input to be sent to a background process.
265d8ff: Reorganize process commands into per-command directories and split settings command internals.

Patch Changes

9fa2188: Restore bottom border line on log overlay
dbcd3d1: Split commands into separate files for better organization
d0814e6: Improve tool result display when collapsed: show last 2 output lines, first 3 processes with status. Remove redundant action/status footer on success.

pi-ts-aperture: v0.3.0

Wed, 04 Mar 2026 20:38:28 GMT

Minor Changes

dffb404: Refactor the Aperture routing implementation into focused modules and improve startup model discovery.

What changed
- Split the previous large src/index.ts into a clearer architecture:
  - src/providers/aperture.ts for routing/bootstrap/model refresh logic
  - src/providers/model-config.ts for model synthesis/merge helpers
  - src/lib/aperture-api.ts for Aperture API discovery calls
  - src/state/provider-model-cache.ts for in-memory model cache state
- Keep src/index.ts as orchestration only (load config, register hooks/commands).
- Preserve and explicitly inject provenance headers when routing through Aperture:
  - Referer: https://pi.dev
  - X-Title: npm:@aliou/pi-ts-aperture
- Fix active model refresh timing by awaiting model re-resolution before request execution.
- Improve OpenRouter CLI model selection reliability by bootstrapping discovered models from Aperture when needed.
Why minor

This release introduces observable behavior improvements (model availability/routing reliability and header behavior) in addition to internal refactoring.

pi-utils-settings: v0.8.0

Wed, 04 Mar 2026 20:38:28 GMT

Minor Changes

b404f50: Add optional extraTabs support to registerSettingsCommand so extensions can render non-scope top-level tabs (for example, an Examples tab) after scope tabs.
- Add ExtraSettingsTab and ExtraSettingsTabContext types and export them from package root.
- Keep existing scope-tab buildSections and save semantics unchanged.
- Make tab switching cycle across scope + extra tabs.
- Validate tab id collisions with reserved scope ids.
- Update README and skill/reference docs with extraTabs examples.
29a909d: Add Wizard-safe settings theme support by introducing a combined SettingsTheme that works as both SettingsListTheme and full pi Theme.
- Add and export SettingsTheme (SettingsListTheme & Theme).
- Add and export getSettingsTheme(theme) helper to build a combined theme object.
- Extend registerSettingsCommand buildSections ctx with theme: SettingsTheme.
- Extend ExtraSettingsTabContext with theme: SettingsTheme.
- Keep existing getSettingsListTheme() consumers and existing callbacks backward-compatible.
- Update README and example reference to show ctx.theme usage for both settings list and full Theme methods.

pi-harness: @aliou/pi-utils-settings@0.7.0

Mon, 02 Mar 2026 20:38:28 GMT

Minor Changes

a3039d9: Add a reusable SettingsDetailEditor component for focused second-level settings editing.
- Support typed detail fields: text, enum, boolean, nested submenu, and destructive action with confirmation
- Add keyboard UX for detail panels (↑/↓ or j/k, Enter, Esc)
- Show selected field descriptions and keep nested submenu handoff/return clean
- Add tests for navigation and field callback behavior
- Update docs with guidance on SectionedSettings vs SectionedSettings + SettingsDetailEditor
- Extend reference example with an array-of-objects pattern (profiles) using nested detail editors

sesame: v0.7.0

Sat, 28 Feb 2026 20:38:28 GMT

Minor Changes

54d0fca: Migrate from Bun to Node 25 + tsdown SEA for binary builds.
- Replace bun:sqlite with node:sqlite as the sole SQLite backend.
- Replace bun build --compile with tsdown exe (Node SEA) for standalone binaries.
- Migrate CLI tests from bun:test to vitest.
- Bump minimum Node version to >=25.0.0.
- CI builds binaries for linux-x64, linux-arm64, and darwin-arm64 via matrix strategy.

Patch Changes

cc89035: Fix legacy SQLite migration order so tree indexes are created after schema migrations.

This prevents sesame status from failing on existing databases with no such column: parent_session_id.

pi-synthetic: v0.6.0

Wed, 25 Feb 2026 20:38:28 GMT

Minor Changes

628616b: Update model configurations and add automated API validation tests
- Fixed GLM-4.7 maxTokens from 64000 to 65536
- Fixed MiniMax-M2.5 input modalities from [“text”,“image”] to [“text”]
- Updated pricing for MiniMax-M2.1, Kimi-K2.5, and Qwen3-Coder-480B-A35B
- Added maxTokens and reasoning field validation test
- Added vitest for testing with pnpm test and pnpm test:watch scripts
- Added test step to pre-commit hook

Patch Changes

3f41a60: Add identification headers to API requests
- Added Referer: https://pi.dev header
- Added X-Title: npm:@aliou/pi-synthetic header

sesame: v0.6.0

Wed, 25 Feb 2026 20:38:28 GMT

Minor Changes

5e1475e: Add support for session forks and custom_message entries
- Parse and index custom_message entries (extension-injected LLM context)
- Track session fork relationships via parent_session_id
- Track entry tree structure via entry_id, parent_entry_id, timestamp, source_type on chunks
- Add database migration for new columns

pi-synthetic: v0.5.0

Tue, 24 Feb 2026 20:38:33 GMT

Minor Changes

9faaa42: Add pi-sub integration via sub-core events
eee2c68: Redesign quotas display with tabbed interface and pace tracking
562cbf7: Add Qwen3.5-397B-A17B model to the available models list

Patch Changes

b29fe7c: Return JSON in RPC mode instead of plain text

preview-markdown: v0.4.0

Sun, 22 Feb 2026 16:17:17 GMT

What’s Changed

release: v0.4.0 by @github-actions[bot] in https://github.com/aliou/preview-markdown/pull/3

Full Changelog: https://github.com/aliou/preview-markdown/compare/v0.3.0…v0.4.0

pi-processes: v0.5.0

Sat, 21 Feb 2026 20:38:33 GMT

Minor Changes

da665cd: Add opt-in blocker for background bash commands: when enabled, bash tool calls that would spawn a background process (&) are held for approval before execution.

Fix process list column truncation on narrow terminals. Move @mariozechner/pi-tui to peer dependencies.

Patch Changes

3ccf461: Fix TUI crash when rendered lines exceed terminal width. Add width guards to widget status line, process list panel, and process picker component.

pi-ts-aperture: v0.2.0

Thu, 19 Feb 2026 20:38:33 GMT

Minor Changes

926f0a9: Improve /aperture:setup provider and connectivity flow.
- Add URL health check during setup (/v1/models) before provider selection, with retry/cancel UX.
- Build provider choices from Pi’s runtime model registry so extension-registered providers (for example pi-synthetic) appear in the setup list.

Patch Changes

2263fc2: mark pi SDK peer deps as optional to prevent koffi OOM in Gondolin VMs

pi-harness: @aliou/pi-utils-settings@0.4.0

Tue, 17 Feb 2026 20:38:33 GMT

Minor Changes

7df01a2: Pass ExtensionCommandContext to onSave callback in settings command options

pi-ts-aperture: v0.1.0

Tue, 17 Feb 2026 20:38:33 GMT

Minor Changes

ebb9556: Initial release. Route Pi LLM providers through Tailscale Aperture.
- /aperture:setup interactive wizard (base URL + provider multi-select)
- /aperture:settings settings UI for updating configuration
- Auto-registers selected providers with Aperture base URL on load

Patch Changes

7388139: Fix providers not taking effect immediately after setup/settings save. Register directly on modelRegistry and re-resolve the active model when it belongs to a reconfigured provider.

sesame: v0.5.0

Sat, 14 Feb 2026 20:38:33 GMT

Minor Changes

54b7450: Add schema_migrations table for lightweight DB migrations. Replaces inline ALTER TABLE with a tracked migration system using sequential migration files.
ca7cb24: Add tool call success/failure status to index and search. New is_error column on chunks, status search filter, and toolName/toolsOnly now work with wildcard queries.

pi-linkup: v0.7.0

Thu, 12 Feb 2026 20:38:33 GMT

Minor Changes

675ab1d: Export tool definitions as a library via @aliou/pi-linkup/tools

sesame: v0.4.0

Thu, 12 Feb 2026 20:38:33 GMT

Minor Changes

9b03f3c: Support * query to list all sessions with filters. When searching with *, returns all sessions ordered by modification date (newest first), respecting cwd/after/before/limit filters. Default limit of 10 ensures context safety.

pi-harness: @aliou/pi-utils-settings@0.3.0

Wed, 11 Feb 2026 20:38:33 GMT

Minor Changes

756552a: Add FuzzySelector component for picking one item from a large list using fuzzy search. Refresh sections after cycling value changes so dependent settings update immediately.

When Opus thought it was on Linux

Wed, 11 Feb 2026 15:48:58 GMT

Got absolutely screwed by Opus thinking it was running on Linux instead of macOS while debugging some CLI stuff with tmux.

But the session of Opus figuring out what happened is pretty fascinating:

Also created a small tool that uses BM25 to find content in previous sessions. It’s super useful to just say “I was running a Pi session at the same time, could it be related?” This is completely borrowed from Amp.

Why I Use Pi

Wed, 11 Feb 2026 15:17: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.

pi-linkup: v0.6.0

Tue, 10 Feb 2026 20:38:17 GMT

Minor Changes

e9fdef1: Replace deep boolean with depth enum on web-answer tool for consistency with web-search

pi-linkup: v0.4.0

Tue, 10 Feb 2026 20:38:17 GMT

Minor Changes

052fc2b: Add fast mode support to linkup_web_search tool. The depth parameter now accepts “fast”, “standard”, or “deep” modes:
- fast: Sub-second latency using pre-indexed atoms of information
- standard: Single iteration retrieval, balanced speed/depth (default)
- deep: Up to 10 iterations with chain-of-thought reasoning

Patch Changes

a238ba7: Add User-Agent header to all Linkup API requests for attribution.

sesame: v0.2.0

Tue, 10 Feb 2026 20:38:17 GMT

Minor Changes

8beab04: Migrate runtime from Bun APIs to Node.js APIs and switch project workflows to pnpm while keeping Bun only for binary builds.

Key updates:
- use node:sqlite instead of bun:sqlite
- replace Bun file APIs with Node fs APIs
- run tests with Vitest
- use pnpm lockfile/workflows in CI and release pipelines
- keep build:binary on Bun for compiled binaries

Patch Changes

2c99cb6: Enable TypeScript type emission by removing allowImportingTsExtensions and setting noEmit: false

sesame: v0.3.0

Tue, 10 Feb 2026 16:17:13 GMT

What’s Changed

Updating @aliou/sesame to version 0.3.0 by @github-actions[bot] in https://github.com/aliou/sesame/pull/6

Full Changelog: https://github.com/aliou/sesame/compare/v0.2.0…v0.3.0

preview-markdown: v0.3.0

Mon, 09 Feb 2026 16:17:17 GMT

What’s Changed

release: v0.3.0 by @github-actions[bot] in https://github.com/aliou/preview-markdown/pull/2

Full Changelog: https://github.com/aliou/preview-markdown/compare/v0.2.0…v0.3.0

sesame: v0.1.0

Mon, 09 Feb 2026 16:17:13 GMT

What’s Changed

release: v0.1.0 by @github-actions[bot] in https://github.com/aliou/sesame/pull/1

New Contributors

@github-actions[bot] made their first contribution in https://github.com/aliou/sesame/pull/1

Full Changelog: https://github.com/aliou/sesame/commits/v0.1.0

pi-harness: @aliou/pi-toolchain@0.2.0

Thu, 05 Feb 2026 20:38:17 GMT

Minor Changes

7a3f659: Add memory scope for ephemeral settings overrides

pi-harness: @aliou/pi-guardrails@0.6.0

Wed, 04 Feb 2026 20:38:17 GMT

Minor Changes

29b61a5: Remove toolchain features (preventBrew, preventPython, enforcePackageManager) — moved to @aliou/pi-toolchain. Replace custom config loader and settings UI with @aliou/pi-utils-settings.

pi-harness: @aliou/pi-toolchain@0.1.0

Wed, 04 Feb 2026 20:38:17 GMT

Minor Changes

29b61a5: Initial release: package manager rewriting, git rebase rewriting, python rewriting, and brew blocking via spawn hooks. Extracted from @aliou/pi-guardrails.

sh: v0.1.0

Wed, 04 Feb 2026 20:38:17 GMT

Minor Changes

0f1209b: Initial release.

pi-linkup: v0.3.0

Tue, 03 Feb 2026 20:38:41 GMT

Minor Changes

e57f6fe: Enhanced balance command to show remaining requests per operation type (standard search, deep search, fetch with/without JS) using a themed custom message renderer instead of a transient notification.

pi-linkup: v0.2.0

Tue, 03 Feb 2026 20:38:38 GMT

Minor Changes

2307674: Update pi packages to 0.51.0. Adapt tool execute signatures to new parameter order.

Coding Agents at Team Scale

Tue, 03 Feb 2026 16:10:32 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.

pi-synthetic: v0.4.0

Mon, 02 Feb 2026 20:38:36 GMT

Minor Changes

5cca252: Add /synthetic:quotas command to display API usage quotas

A new slash command that shows your Synthetic API subscription quotas in a rich terminal UI:
- Visual usage bar with color-coded severity (green/yellow/red based on usage)
- Aligned columns showing limit, used, and remaining requests
- ISO8601 renewal timestamp with relative time formatting (e.g., “in 5 hours”)
- Closes on any key press
The command is only registered when SYNTHETIC_API_KEY environment variable is set.
a8cacfb: Add Synthetic web search tool

New tool synthetic_web_search allows agents to search the web using Synthetic’s zero-data-retention API. Returns search results with titles, URLs, content snippets, and publication dates.

Note: Search is a subscription-only feature. The tool will only be registered if the SYNTHETIC_API_KEY belongs to an active subscription (verified via the usage endpoint).

pi-synthetic: v0.3.0

Thu, 29 Jan 2026 20:38:33 GMT

Minor Changes

5f67daf: Switch from Anthropic to OpenAI API endpoints
- Change API endpoint from /anthropic to /openai/v1
- Update from anthropic-messages to openai-completions API
- Add compatibility flags for proper role handling (supportsDeveloperRole: false)
- Use standard max_tokens field instead of max_completion_tokens

pi-synthetic: v0.2.0

Thu, 29 Jan 2026 20:38:31 GMT

Minor Changes

58d21ca: Fix model configurations from Synthetic API
- Update maxTokens for all Synthetic models using values from models.dev (synthetic provider)
- Fix Kimi-K2-Instruct-0905 reasoning flag to false

pi-synthetic: v0.1.0

Thu, 29 Jan 2026 20:38:29 GMT

Minor Changes

4a32d18: Initial release with 19 open-source models
- Add Synthetic provider with Anthropic-compatible API
- Support for DeepSeek, Qwen, MiniMax, Kimi, Llama, GLM models
- Vision and reasoning capabilities where available
- Hardcoded model definitions with per-token pricing

pi-harness: @aliou/pi-guardrails@0.5.0

Thu, 29 Jan 2026 20:38:26 GMT

Minor Changes

cb97920: Add enforce-package-manager guardrail
- New enforcePackageManager feature (disabled by default)
- Supports npm, pnpm, and bun (npm is default)
- Blocks commands using non-selected package managers
- Configurable via packageManager.selected setting
- Also documents the existing preventPython feature

Using Kimi K2.5 with Pi via Synthetic

Thu, 29 Jan 2026 15:48:58 GMT

Very meta: wanted to use Kimi K2.5 via Synthetic, so I had Pi set up a one-off extension that creates the provider and defines its model. Then reloaded Pi and asked Kimi to create the Synthetic provider.

pi-linkup: pi-linkup@0.1.0

Wed, 28 Jan 2026 13:54:15 GMT

Release pi-linkup@0.1.0

Pi Guardrails extension

Mon, 26 Jan 2026 15:52:24 GMT

Another one, but this one probably more for me than other people: guardrails!

Pi Processes extension

Mon, 26 Jan 2026 15:52:24 GMT

Fun extension I made for Pi: processes. Let your agent handle running processes in the background and be notified when they finish / die etc.

Jellybeans theme for Pi

Mon, 26 Jan 2026 15:48:58 GMT

Ported by beloved jellybeans-mono for Pi, both dark and light!

fastmail-cli: v0.1.0

Fri, 23 Jan 2026 16:17:15 GMT

What’s Changed

release: v0.1.0 by @github-actions[bot] in https://github.com/aliou/fastmail-cli/pull/1

New Contributors

@github-actions[bot] made their first contribution in https://github.com/aliou/fastmail-cli/pull/1

Full Changelog: https://github.com/aliou/fastmail-cli/commits/v0.1.0

The Infrastructure Around Your AGENTS.md

Tue, 20 Jan 2026 16:10:32 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.

preview-markdown: v0.2.0

Fri, 16 Jan 2026 16:17:17 GMT

What’s Changed

release: v0.2.0 by @github-actions[bot] in https://github.com/aliou/preview-markdown/pull/1

New Contributors

@github-actions[bot] made their first contribution in https://github.com/aliou/preview-markdown/pull/1

Full Changelog: https://github.com/aliou/preview-markdown/compare/v0.1.0…v0.2.0

Skills for Domain-Specific Knowledge

Wed, 07 Jan 2026 15:12:25 GMT

Progressive disclosure for coding agents: load context only when needed

preview-markdown: v0.1.0

Fri, 02 Jan 2026 16:17:17 GMT

Full Changelog: https://github.com/aliou/preview-markdown/commits/v0.1.0

Your AGENTS.md can be shorter now

Sat, 20 Dec 2025 15:12:11 GMT

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

Smaller and simpler feedback loops

Fri, 28 Nov 2025 15:12:18 GMT

How coding agents changed the way I worked

Upgrading the nvim-treesitter plugin

Fri, 17 Oct 2025 16:10:32 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 19:37:08 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 19:37:01 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 19:37:08 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 19:37:01 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 19:37:16 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 15:11:58 GMT

Enabling Monaspace’s stylistic sets for code ligatures in Ghostty

Using named captures to extract information from ruby strings

Thu, 09 Apr 2020 16:10:32 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 16:10:32 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 15:16:55 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 16:10:32 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 16:10:32 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 16:10:32 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 16:35:20 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

How do I design the right primitive?

How I use `/tree` and `/spawn` to investigate bugs

Using MicroVMs

obsidian-flint: v0.2.0

pi-ts-aperture: v0.8.0

Minor Changes

Keeping the harness's primitives consistent

Footnotes

Tau — a coding agent as a curriculum

pi-toolchain: v0.10.0

Minor Changes

pi-edgee: v0.1.0

Minor Changes

The Rebel Alliance

pi-ts-aperture: v0.7.0

Minor Changes

Patch Changes

New `us` jurisdiction for Durable Objects

pi-guardrails: v0.15.0

Minor Changes

Patch Changes

pi-toolchain: v0.9.0

Minor Changes

Patch Changes

pi-utils-settings: v0.18.0

pi-synthetic: v0.20.0

Minor Changes

pi-guardrails: v0.14.0

Minor Changes

Patch Changes

pi-toolchain: v0.8.0

Minor Changes

pi-ts-aperture: v0.6.0

Minor Changes

pi-neuralwatt: v0.7.0

Minor Changes

Patch Changes

pi-synthetic: v0.19.0

Minor Changes

preview-markdown: v0.7.0

What’s Changed

pi-utils-ui: v0.5.0

pi-neuralwatt: v0.6.0

Minor Changes

Patch Changes

pi-dev-kit: v0.8.0

Open Source must win

Something is jamming GPS over Europe. Here's what we found

pi-utils-settings: v0.17.0

Minor Changes

exe.dev's ssh host header

sesame: @aliou/sesame@0.10.0

Minor Changes

Rift

Pi Agent explained in 6min

sesame: @aliou/sesame@0.9.0

Minor Changes

sh: v0.2.0

Minor Changes

pi-utils-settings: v0.16.0

Minor Changes

obsidian-flint: v0.1.0

Thoughts on Claude Code's Workflow feature

granola-cli: v0.2.0

What’s Changed

granola-cli: v0.1.0

What’s Changed

New Contributors

Claude Opus's fast mode

Footnotes

pi-synthetic: v0.18.0

Minor Changes

pi-neuralwatt: v0.5.0

Minor Changes

Patch Changes

pi-guardrails: v0.13.0

Minor Changes

preview-markdown: v0.6.0

What’s Changed