DEV Community: Baptiste Bouillot

Murmure 1.2.0: a signed DMG, no ffmpeg, and dictation that doesn't lose its first word

Baptiste Bouillot — Wed, 07 Oct 2026 08:50:04 +0000

Murmure is a small menu bar app I built for voice dictation on macOS. You press Cmd+Shift+E, you talk, and the text is pasted into whatever app you're in. Transcription runs locally with whisper.cpp and the large-v3-turbo model: no account, no subscription, no API key.

I wrote about the first public version a week ago. Version 1.2.0 is out today, and it fixes the thing I was least happy with: how you install it.

Repo: github.com/croustibat/murmure

What's new in 1.2.0

A signed, notarized DMG. Version 1.1.0 meant cloning the repo, having Homebrew and the Xcode command line tools, and running ./install.sh. That's fine for me and for a few developers, and a dead end for everyone else. Now you open Murmure.dmg, drag the app to Applications, and it opens without a Gatekeeper warning.

Everything is inside the app. whisper.cpp is compiled for Apple Silicon and bundled. ffmpeg is gone, replaced by a native recorder. Nothing to install next to it.

Automatic updates. Murmure checks once a day and installs a new version when you say so. It never interrupts a dictation: if an update shows up while you're talking, it waits.

The model downloads from the app. On first launch Murmure offers to download its transcription model (about 550 MB, once). The download resumes after a network cut and the file is checked against its SHA-256 hash before use.

There are smaller fixes too. Unplugging a headset during a dictation no longer stops it: recording continues on another microphone. Long dictations keep the custom vocabulary better. And a Whisper noise label like *sad* can no longer replace what you actually said.

Why: the install was the product

With 1.1.0, before your first dictation you needed Homebrew, the Xcode command line tools and a terminal. For a dictation app, that's backwards: a tool that saves you typing shouldn't start with a terminal session.

Signing also matters for a less visible reason. macOS ties the Microphone and Accessibility permissions to the app's signature. With the old install, a copy built on your Mac and signed ad hoc was identified by its binary hash, so a rebuild could mean granting Accessibility again. With a Developer ID signature, permissions survive updates. That's what makes automatic updates bearable: an update that silently breaks auto-paste would be worse than no update.

The gotcha: the first word of every sentence

Replacing ffmpeg with a native Core Audio recorder (murmure-rec) was mostly about having one less dependency. It also fixed a bug.

With 1.1.0, the start signal came as soon as the recording process was launched. But a microphone takes a moment to actually deliver audio. If you started talking right away, which is exactly what a shortcut invites you to do, the first syllables were lost.

The new recorder only gives the start signal once the microphone is ready. It sounds obvious written down. It took a dedicated recorder to make it true.

The same recorder lists your input devices, which helps if you want to pin a specific microphone:

/Applications/Murmure.app/Contents/Helpers/murmure-rec --list-devices

You can then set the device by name in ~/.local/share/murmure/config (MURMURE_DEVICE=MacBook Pro Microphone), or pick it in the Settings window. A name is safer than an index, which changes when you plug in a headset.

Network, still

Transcription never leaves the Mac. Murmure makes two kinds of requests: the one-time model download from Hugging Face, and the daily update check, which reads appcast.xml from the latest GitHub release with Sparkle. No text, audio, identifier or system profile is sent. MURMURE_CHECK_UPDATES=0 turns update checks off.

Coming from 1.1.0

1.1.0 can't update itself. Quit Murmure, download the DMG and drag the app over the old one. Your settings, vocabulary, corrections, history and model are kept, since they live in ~/.local/share/murmure.

Because the signature changed, macOS asks for the microphone again, and the old Accessibility entry still looks checked but no longer counts. In System Settings > Privacy & Security > Accessibility, remove the old Murmure entry (–), then add the new one (+). After that, future versions arrive on their own.

Try it

You need an Apple Silicon Mac on macOS 14 or later.

Download Murmure.dmg, or
brew install --cask croustibat/tap/murmure, or
build it yourself: git clone https://github.com/croustibat/murmure.git && cd murmure && ./install.sh (Xcode required).

The menus are in French for now. Dictation is French by default and switches to English or any Whisper language in Settings, or with MURMURE_LANG=en.

It's MIT licensed. Issues and PRs are welcome, and I'm especially curious how it behaves with other languages and microphones: github.com/croustibat/murmure.

Baptiste — freelance web dev for 20 years, building in Laravel/PHP and shipping small open-source tools.

Murmure: system-wide voice dictation for macOS that never leaves your Mac

Baptiste Bouillot — Wed, 30 Sep 2026 13:14:06 +0000

The dictation tools I tried on my Mac fell into two camps. The built-in one punctuates poorly. The good ones are paid, and they send your voice to a remote service.

I wanted something smaller: press a shortcut, talk, and have the text appear in whatever app I'm in. No account, no subscription, no API key, nothing leaving the machine.

So I built Murmure. Version 1.1.0 is the first public release: github.com/croustibat/murmure.

What it does

Murmure is a menu bar app. You press Cmd+Shift+E, a small floating pill appears while it listens, you press the shortcut again, and the text is transcribed and pasted into the app that was active when you started. Mail, Slack, a terminal, an editor, a search field: it doesn't care.

Transcription runs locally with whisper.cpp and the large-v3-turbo model. It takes about two seconds between the end of a sentence and the pasted text.

There are two modes and no setting to switch between them:

Short press: toggle. Press to start, press again to transcribe.
Hold: push-to-talk. Keep the shortcut down while you speak, release to transcribe. The threshold between the two is 600 ms.

Escape cancels a dictation while it's listening. The recording is thrown away and nothing is pasted. Outside of a dictation, Escape keeps its normal role everywhere.

The menu also keeps your last 10 dictations. One click copies one back to the clipboard, which is handy when a paste fails.

The interesting bug: a script has no identity

At its core, Murmure is a shell script: it records with ffmpeg, sends the WAV to whisper-cli, and pastes the result. The obvious setup is to bind that script to a shortcut and call it a day.

Do that, and you mostly get subtitle credits.

The reason is macOS privacy permissions (TCC). A bare script has no identity that macOS can attach a microphone permission to. So macOS never asks for permission, and it doesn't return an error either: it hands the process a silent audio stream. Whisper, hearing nothing, does what it was trained to do on silent video and invents closing credits.

The fix is the reason Murmure is an .app bundle and not just a script. The bundle gets its own identity, macOS shows the microphone prompt, and the audio is real.

The pipeline today looks like this:

Cmd+Shift+E → Murmure.app (menu bar) → murmure.sh
                    ├─ ffmpeg (avfoundation) ──→ WAV 16 kHz mono
                    ├─ overlay (AppKit) ───────→ floating pill
                    ├─ whisper-cli ────────────→ text
                    ├─ corriger.pl ────────────→ vocabulary fixes
                    └─ pbcopy + Cmd+V ─────────→ active app

The same identity question comes back with the Accessibility permission, which Murmure needs to send Cmd+V. macOS ties that permission to the app's signature. If you have an Apple developer certificate in your keychain, install.sh signs the app with it and the permission survives updates. Without one, the app is signed ad hoc and recognized by its binary hash, so every rebuild means granting Accessibility again. The installer tells you when that happens, and it only rebuilds the app when something actually changed.

Murmure also checks both permissions itself. If one is missing, the menu bar icon shows an exclamation mark and the first menu entry opens the right System Settings panel.

Fixing technical words

I dictate in French, and Whisper likes to translate developer jargon into French words that sound close. "Commit" comes back as "commis", "worktree" as "worktrade".

Murmure has two files for that, both in ~/.local/share/murmure/:

vocabulaire.txt is a short text given to Whisper as a prompt before transcription. It's not a list to fill up: Whisper re-reads it before every 30-second chunk and it shares 224 tokens with the end of the previous chunk. Past roughly 150 tokens, long dictations start losing the thread between chunks.
corrections.txt is applied after transcription, one rule per line, case-insensitive, on whole words:

commis|commit
redit|Redis
worktrade|worktree

In practice the corrections file does most of the work. The vocabulary prompt is best kept for proper nouns.

Speed, and what didn't help

I spent some time trying to make transcription faster. On a short dictation the encoder still processes a full 30-second window, and that's most of the time. Shrinking that window (-ac) made Whisper repeat itself. Greedy decoding, --no-fallback, thread counts and VAD gained less than 10% or hurt the transcription. So Murmure keeps whisper-cli defaults.

If you want to measure on your own recordings, the repo includes a small benchmark script. Put a reference .txt next to each .wav and it also computes the error rate:

scripts/bench.sh -n 5 dictee1.wav dictee2.wav

Network

Transcription never leaves the Mac. The only network request is an update check, at most once a day, that reads the latest release from the public GitHub API. No text, audio or identifier is sent. MURMURE_CHECK_UPDATES=0 in the config file turns it off.

Try it

You need an Apple Silicon Mac on macOS 14 or later, Homebrew, and the Xcode command line tools.

git clone https://github.com/croustibat/murmure.git
cd murmure
./install.sh

The installer sets up ffmpeg and whisper-cpp, downloads the model once (about 550 MB, checked by SHA-256), builds the app and launches it. To update: git pull && ./install.sh.

A note for non-French speakers: the docs and the menus are in French for now, and the default transcription language is French. Set MURMURE_LANG=en (or auto) in ~/.local/share/murmure/config and it applies to the next dictation.

It's MIT licensed. Issues and PRs are welcome, and I'd like to hear how it behaves with other languages and other microphones: github.com/croustibat/murmure.

Baptiste — freelance web dev for 20 years, building in Laravel/PHP and shipping small open-source tools.

PHP FFI on Apple Silicon: your ioctl call is lying to you

Baptiste Bouillot — Sat, 15 Aug 2026 21:18:27 +0000

I spent an evening building pseudo-terminal support for PHP and lost an hour of it to a bug that reports success. If you use FFI and ioctl anywhere near production, and your CI only runs on Linux, this one is worth ten minutes of your time.

The setup

PHP can already open a pseudo-terminal. proc_open() accepts ['pty'] descriptors, and on macOS you get a real /dev/ttysNNN back.

What you do not get is any control over the window size. There is no ioctl() in PHP's standard library, so no TIOCSWINSZ, so no SIGWINCH. Interactive terminal programs render at whatever geometry they guess at startup, and they never find out the window changed. For anything that draws a full-screen UI — top, vim, an agent CLI — that is the difference between usable and useless.

That single gap is why PHP projects that need to drive a terminal end up shipping a Node sidecar just to get node-pty.

ext-ffi should close it. openpty(), login_tty() and ioctl() are all sitting in libc. So I wrote the obvious binding:

$ffi = FFI::cdef(<<<'C'
    struct winsize {
        unsigned short ws_row;
        unsigned short ws_col;
        unsigned short ws_xpixel;
        unsigned short ws_ypixel;
    };
    int openpty(int *amaster, int *aslave, char *name, void *termp, void *winp);
    int login_tty(int fd);
    int ioctl(int fd, unsigned long request, void *arg);
    int close(int fd);
C);

Then set the size, fork, login_tty(), exec, and ask the child what it thinks its terminal looks like.

The symptom

I asked for 30 rows by 120 columns. The child printed:

/dev/ttys018
0 2046

The tty is real. The size is not. And 2046 is not a plausible number of columns for anything — it is not a truncation of 120, not a byte-swap, not a field-order mistake. It is garbage.

The part that cost me the hour: ioctl() returned 0. Success. No errno, no exception, nothing to check. The only way to know something went wrong was to ask the child.

Isolating it

Three hypotheses, in decreasing order of comfort:

The struct winsize layout is wrong.
The ioctl call itself is wrong.
Something is wrong with the fork/exec path.

There is a clean way to separate the first two. openpty() takes a struct winsize * as its fifth parameter — you can set the initial size at creation time without ever calling ioctl. And openpty() is not variadic.

So: same struct, same child, same everything, three paths.

// A — size set by openpty(winp), no ioctl at all
$rc = $ffi->openpty(FFI::addr($m), FFI::addr($s), null, null, FFI::addr($ws));

// B — ioctl declared with fixed arity
// int ioctl(int fd, unsigned long request, struct winsize *arg);
$ffi->ioctl($master, TIOCSWINSZ, FFI::addr($ws));

// C — ioctl declared variadic
// int ioctl(int fd, unsigned long request, ...);
$ffi->ioctl($master, TIOCSWINSZ, FFI::addr($ws));

Ground truth is stty size run by a child attached to the pty — deliberately not TIOCGWINSZ, because reading it back would go through the exact same suspect call.

PHP 8.5.8, Darwin, arm64. Asking for 30 rows by 120 columns:

A — openpty(winp), not variadic → child reports 30 120. Correct. Return value 0.
B — ioctl declared with fixed arity → child reports 0 2046. Garbage. Return value 0.
C — ioctl declared variadic → child reports 30 120. Correct. Return value 0.

All three calls report success. Only one of them is telling the truth.

The struct is fine. openpty is fine. The declaration of ioctl is not.

Why

ioctl is variadic in C:

int ioctl(int fildes, unsigned long request, ...);

Almost every PHP + FFI snippet you will find online declares it with fixed arity instead — void *arg as the third parameter. On Linux x86-64 that is harmless: the variadic and non-variadic calling conventions agree for integers and pointers, so the value lands in the register the callee reads.

Apple's ARM64 ABI does not agree. Apple diverges from the standard AAPCS64 here: in a variadic function, every variadic argument is passed on the stack, even though fixed arguments still travel in registers.

So when you declare ioctl non-variadic, libffi builds a non-variadic call frame and places your pointer in register x2. The real ioctl — compiled as variadic — goes looking for it on the stack. It finds whatever was there, treats it as a struct winsize *, and copies eight bytes from it.

If that address happens to be unmapped you get EFAULT and at least you know. If it happens to be readable — which is common — the call succeeds and writes nonsense. That is the 0 2046. It is not a corrupted value; it is a different piece of memory entirely.

This is not PHP-specific. Chez Scheme hit the same wall on arm64 macOS (issue #745); any FFI over libffi can reproduce it.

The fix

One line:

- int ioctl(int fd, unsigned long request, void *arg);
+ int ioctl(int fd, unsigned long request, ...);

PHP's FFI parser accepts ... and libffi then uses ffi_prep_cif_var() with the correct fixed-argument count, which produces a Darwin-correct call frame.

How to check your own code

If you have FFI::cdef and ioctl in the same file:

Grep for the declaration. If the third parameter is typed rather than ..., you have this bug on Apple Silicon.
Do not trust the return value. It will be 0.
Write an assertion that a child process observes the effect, and run it in CI on macos-latest. Ubuntu alone gives you a false green — both declarations behave identically there.

That last point is the one I would underline. This class of bug is invisible on the platform most CI runs on and silent on the platform most PHP developers write code on.

The same reasoning applies to any variadic libc function you bind: open, fcntl, printf and friends. If the C header ends in ..., your cdef must too.

The package

The pty work became php-pty — node-pty for PHP, MIT, nothing to compile:

use Croustibat\Pty\Pty;

$session = Pty::spawn(['top'], rows: 30, cols: 120);

$session->resize(40, 100);   // real TIOCSWINSZ, real SIGWINCH
echo $session->read();
$session->write('q');

$session->stream();          // non-blocking, for stream_select()
$session->wait();            // exit code

Three classes, about 300 lines. login_tty() so the child gets a real controlling terminal, which is what makes job control and Ctrl-C work — the thing proc_open cannot give you. CI on Ubuntu and macOS, PHP 8.2 to 8.4.

CLI SAPI only, and it refuses to load elsewhere: pcntl_fork() duplicates the whole process, open database connections included. No Windows either — Windows has no pty, ConPTY is a different API.

Three more things that cost me time

Written down in case they save you some:

PHP retries stream writes internally. It buffers writes in userspace and loops on the flush. On a pty master whose buffer is full, fwrite() then never returns, and no application-level timeout helps because you are stuck inside the call. stream_set_write_buffer($stream, 0) makes each fwrite() map to exactly one write(2) and hand EAGAIN straight back.

Partial writes are the normal case, not an edge case. Pushing 1 MB through a pty master in 8 KB calls took 1,677 fwrite() calls instead of the 128 a full write would need — roughly 625 bytes accepted per call. Code that ignores the return value loses data thirteen times out of fourteen. When the truncation lands inside an escape sequence, your terminal prints the tail as literal text: a stray 7G on screen where a cursor move was meant.

stty -echo is not stty raw. The first only silences the echo; the line discipline stays canonical and holds at most MAX_CANON bytes while it waits for a newline. Push half a megabyte with no \n through it and it jams solid.

If you are doing anything with FFI and libc from PHP, check your variadic declarations. The bug that returns 0 is always the expensive one.

Running parallel Claude Code agents on Laravel with Orca: my setup and archive scripts

Baptiste Bouillot — Tue, 28 Jul 2026 09:34:12 +0000

Running parallel Claude Code agents on Laravel with Orca: my setup and archive scripts

David Hemphill wrote a great post about getting started with Conductor using Laravel — how to wire up per-worktree setup and archive scripts so each parallel agent gets its own clean environment. I run the same idea, but with Orca instead of Conductor. This is my take, with the two scripts I actually use.

The problem: agents stepping on each other

The moment you run more than one coding agent at a time, they start fighting over shared state. Two agents against the same database means one's migrate:fresh --seed wipes the other's work mid-task. Two Laravel apps on the same local domain, the same queue, the same Reverb port — collisions everywhere.

Git worktrees fix the files part: each branch gets its own directory on disk. But a Laravel app isn't just files. It's a database, a signed local domain, a websocket port, a built frontend. If you don't isolate those too, "parallel" is a lie.

What Orca gives you

Orca is an agent development environment: it runs Claude Code, Codex, Gemini and other CLI agents in parallel, each in its own real git worktree. One worktree = one branch = one workspace. You review the diff, ship a PR, then archive the worktree in one click.

The part that makes it usable for Laravel is two lifecycle hooks in the repository settings:

a Setup Script that runs when a worktree is created, and
an Archive Script that runs right before a worktree is destroyed.

Inside those scripts Orca hands you two environment variables I lean on heavily:

ORCA_ROOT_PATH — the path to the main repo (the "real" checkout, where my root .env lives).
ORCA_WORKSPACE_NAME — the name of the current workspace/branch.

Both of my scripts fall back to plain git if those aren't set, so the exact same file also works when I run it by hand outside Orca.

The principle: one SQLite file and one Herd site per worktree

My whole convention fits in one sentence: inside a worktree, the database is always an isolated SQLite file, never the project's shared database. A local file that gets created with the worktree and deleted with it. No seed collisions between parallel agents, ever.

Local serving is Laravel Herd, one isolated, HTTPS-secured site per worktree. So agent A works on myapp-feature-invoices.test while agent B is on myapp-fix-webhooks.test, each on its own PHP version, its own database, its own everything.

The setup script

This runs on worktree creation. I keep the real thing in ~/.scripts/laravel/worktree-setup.sh and reference it from each project with a tiny shim (more on that at the end). Here's what matters.

Find the main repo, copy its .env:

if [ -n "${ORCA_ROOT_PATH:-}" ]; then
    main_root="$ORCA_ROOT_PATH"
else
    main_root="$(dirname "$(cd "$(git rev-parse --git-common-dir)" && pwd)")"
fi

if [ -f "$main_root/.env" ]; then
    cp "$main_root/.env" .env
else
    cp .env.example .env
fi
set -a && source .env && set +a

The root .env holds my real secrets and API keys, so every worktree inherits a working config with zero manual copy-paste. set -a exports everything so I can use those values later in the script.

Build a unique, cert-safe site name:

workspace="${ORCA_WORKSPACE_NAME:-$(git rev-parse --abbrev-ref HEAD)}"
workspace_slug="$(echo "$workspace" | sed 's#[^a-zA-Z0-9]#-#g' | tr '[:upper:]' '[:lower:]')"
repo="$(basename "$main_root")"
site_name="${repo}-${workspace_slug}"
max_site_len=58
if [ "${#site_name}" -gt "$max_site_len" ]; then
    ws_hash="$(printf '%s' "$workspace" | cksum | awk '{print $1}')"
    keep=$(( max_site_len - ${#ws_hash} - 1 ))
    site_name="$(printf '%s' "$site_name" | cut -c1-"$keep")-${ws_hash}"
fi

That 58-character cap is a gotcha I learned the hard way: the site name becomes the Common Name of the TLS certificate Herd generates, and a CN longer than 64 characters is invalid. Long branch names (feature/some-very-descriptive-thing) blow past that, so past the limit I truncate and append a short cksum hash to keep it unique.

Point .env at the isolated SQLite DB and neutralize mail:

sqlite_path="$(pwd)/database/database.sqlite"
set_env "APP_URL"       "https://${site_name}.test"
set_env "DB_CONNECTION" "sqlite"
set_env "DB_DATABASE"   "${sqlite_path}"
set_env "MAIL_MAILER"   "log"

(set_env is a small helper that updates a key if present or appends it — BSD sed, since this is macOS.) Mail goes to the log so an agent can't accidentally send real email from a workspace.

A deterministic Reverb port, only if the project uses Reverb:

if [ -f config/reverb.php ] || grep -q '"laravel/reverb"' composer.json 2>/dev/null; then
    hash_val="$(echo -n "$site_name" | cksum | awk '{print $1}')"
    reverb_port=$((8100 + (hash_val % 100)))
    set_env "REVERB_SERVER_PORT" "${reverb_port}"
    set_env "REVERB_PORT"        "${reverb_port}"
    set_env "VITE_REVERB_PORT"   "${reverb_port}"
fi

Two worktrees can't both bind 8080. Deriving the port from a hash of the site name gives each worktree a stable, collision-resistant port without me tracking anything.

Link the site to Herd, isolate the PHP version, secure it:

php_ver="$(grep -oE '"php"[^,}]*' composer.json 2>/dev/null | grep -oE '8\.[0-9]+' | head -1 || true)"

herd link "$site_name"
if [ -n "$php_ver" ]; then
    herd isolate "$php_ver" --site="$site_name" || true
fi
herd secure "$site_name"
herd restart

The PHP version is read straight from composer.json, so a legacy project on 8.2 and a new one on 8.4 each get the right runtime automatically.

Fresh database, dependencies, and a built frontend:

mkdir -p "$(dirname "$sqlite_path")"
rm -f "$sqlite_path"
touch "$sqlite_path"

# copy git-ignored MCP config so the agent has its tools
[ -f "$main_root/.mcp.json" ] && cp "$main_root/.mcp.json" .mcp.json

herd composer install --no-interaction --prefer-dist --optimize-autoloader
php artisan config:clear
php artisan key:generate --force --no-interaction
php artisan migrate:fresh --seed --force
php artisan storage:link 2>/dev/null || true

if [ -f yarn.lock ]; then
    yarn && yarn build
elif [ -f pnpm-lock.yaml ]; then
    pnpm install && pnpm build
elif [ -f package.json ]; then
    npm install && npm run build
fi

A couple of details I care about: I copy the git-ignored .mcp.json from the root so the agent inherits my MCP servers, and I detect the frontend package manager from the lockfile instead of hardcoding npm. I also gate private Composer auth (Flux Pro) behind "is it actually a dependency and are the creds present" so the script stays generic across projects.

By the time this finishes, the agent opens onto a fully working https://myapp-feature-x.test with its own seeded database. Zero manual setup.

The archive script

This runs before Orca destroys the worktree. Its whole job is to undo what setup did — and to never block the deletion, so every command is best-effort with || true.

#!/usr/bin/env bash
set -uo pipefail

if [ -n "${ORCA_ROOT_PATH:-}" ]; then
    main_root="$ORCA_ROOT_PATH"
else
    main_root="$(dirname "$(cd "$(git rev-parse --git-common-dir)" && pwd)")"
fi

# same site name derivation as setup
workspace="${ORCA_WORKSPACE_NAME:-$(git rev-parse --abbrev-ref HEAD)}"
workspace_slug="$(echo "$workspace" | sed 's#[^a-zA-Z0-9]#-#g' | tr '[:upper:]' '[:lower:]')"
repo="$(basename "$main_root")"
site_name="${repo}-${workspace_slug}"
# (same 58-char truncation as setup)

if [ -z "$workspace_slug" ]; then
    echo "⚠️  Empty workspace name, cleanup aborted for safety."
    exit 0
fi

herd unsecure "$site_name"  || true
herd unisolate "$site_name" || true
herd unlink "$site_name"    || true
rm -f "$(pwd)/database/database.sqlite" || true
herd restart || true

It rebuilds the exact same site_name with identical logic, then tears the Herd site down (unsecure → unisolate → unlink), deletes the SQLite file, and restarts Herd to purge the config. The empty-name guard matters: if the branch name ever resolves to nothing, I'd rather abort than run herd unlink "" and nuke something I didn't mean to.

The one tip that makes this maintainable

I don't paste these scripts into every project. The source of truth lives once in ~/.scripts/laravel/, and each repo carries a two-line shim:

# scripts/worktree-setup.sh
#!/usr/bin/env bash
exec "$HOME/.scripts/laravel/worktree-setup.sh" "$@"

In Orca's repository settings I point the Setup Script at scripts/worktree-setup.sh and the Archive Script at scripts/worktree-archive.sh. Improve the shared script once and every project — and every future worktree — gets the fix. The scripts auto-detect PHP version, frontend manager, Reverb and Flux, so the same file really does work everywhere.

Give it a try

If you're running agents in parallel on Laravel, the isolation is the whole game: one SQLite file and one Herd site per worktree, created on setup and torn down on archive. Once that's in place, spinning up a third or fourth agent costs nothing, and none of them can corrupt each other's state.

Credit where it's due — the pattern is straight out of David Hemphill's Conductor post; I just adapted it to Orca and my stack. If you've got a sharper version of any of these scripts, I'd genuinely like to see it.

Baptiste — freelance web dev for 20 years, building in Laravel/PHP and shipping small open-source tools.

Pinpoint 0.6.0: a crop tool, capture timers, and a changelog you can actually find

Baptiste Bouillot — Wed, 15 Jul 2026 18:12:38 +0000

Pinpoint 0.6.0: a crop tool, capture timers, and a changelog you can actually find

Quick refresher if this is your first time seeing it: Pinpoint is a free, MIT-licensed macOS menu-bar app that lets you capture a region of your screen, drop numbered markers on it, and copy an annotated image plus a structured text block that maps every marker to a position and a note. The point is to stop describing pixels to your AI agent in prose ("the button in the top-right, no, the other one") and start pointing at them instead. Source and download are on GitHub; there's a landing page at pinpoint-ashy.vercel.app.

I just shipped 0.6.0, and this one is special for a reason I'll get to at the end. Here's what's new.

1. A crop tool in the editor

You can now trim a capture right in the editor, with eight handles and a rule-of-thirds grid. The part I care about most: existing markers and arrows are remapped into the cropped frame — they don't drift, they stay pinned to the elements you pointed at.

Why this matters for an agent workflow: the tighter the region you hand the model, the less irrelevant UI it has to reason about. Before, if I over-captured, I'd either re-shoot or send a noisy image. Now I capture generously, then crop down to exactly the elements I'm talking about — and because positions are stored as percentages of the image, the marker map stays correct after the crop.

2. An optional capture timer

There's now a 3, 5, or 10-second countdown before the shot fires. Press Esc to cancel.

This sounds small until you hit the case it solves: capturing UI that only exists while you're interacting with it. Hover states, open menus, dropdowns, tooltips — anything that disappears the moment you reach for a shortcut. Start the timer, arrange the UI, let it fire. It's the classic screenshot-timer trick, but wired into the same capture-to-clipboard flow so you don't leave the app.

3. A "What's New…" menu item

Tiny, but I'd been meaning to add it: a "What's New…" entry in the menu that opens the changelog. So you can always see what each release actually added without digging through GitHub tags. Dogfooding the idea that a tool should tell you about itself.

The part that makes this release special

The crop tool and the capture timer weren't written by me. They were contributed by @ganuong11 — the first external contributions to Pinpoint.

I built this thing for myself, scratched my own itch, open-sourced it mostly so it wouldn't rot in a private repo. Watching someone else read the code, understand the marker-remapping model well enough to make crop preserve it, and send a clean PR — that's the moment an "open-source project" stops being a solo repo with a license file and becomes an actual project. It's a good feeling, and I wanted to say so publicly.

Try it

If you pair-program with an AI agent on a Mac, grab 0.6.0 — it's notarized, signed, and everything stays local (captures never leave your machine). If you've got a better idea for the annotated-capture format, or a feature you want, issues and PRs are welcome — there are a couple of good-first-issues open, and as of this release, merged PRs are officially a thing that happens here.

Next on my list: refining the copied prompt format further. The percentage-based marker map plus a baked-in legend is my current answer to "what does a screenshot prompt need to contain for an agent to act without follow-up questions?" — but I'm still iterating, and I'd like to hear how you're solving it.

Baptiste — freelance web dev for 20 years, building in Laravel/PHP and shipping small open-source tools.

Stop describing pixels to your AI agent — annotate them instead

Baptiste Bouillot — Wed, 15 Jul 2026 10:03:00 +0000

Stop describing pixels to your AI agent — annotate them instead

If you pair-program with an AI agent — Claude Code, Codex, Cursor, whatever — you've lived this moment. You take a screenshot of your UI, paste it into the chat, and then you start typing:

"See the button in the top-right? No, not that one, the other one, next to the misaligned icon — make it full width on mobile and fix the icon while you're at it."

You're describing pixels in prose. And the agent, bless it, does its best to guess which of the six buttons in the screenshot you actually meant.

It gets worse. A lot of chat UIs only keep the image from your clipboard and silently throw away any text you copied alongside it. So even the careful caption you wrote never makes it through. Half your context evaporates between Cmd+C and Cmd+V.

I hit this wall every single day. So I built a tool to fix it, and I open-sourced it. This post is about the underlying idea more than the tool — but I'll use the tool to make it concrete.

The core idea: point, don't describe

Humans don't describe pixels to each other. We point. "This one." "Right here." We use our finger, a cursor, a circle drawn in the air.

So the fix is obvious once you say it out loud: annotate the image with markers, and give each marker a stable identity the agent can reference. Instead of "the button in the top-right," you say "marker 1," and the image literally has a numbered pin on that button.

But a visual marker alone isn't enough, because the agent reads the image as a flat raster. It doesn't know that the ring labeled "1" sits at 62% across and 48% down. So the second half of the idea is: alongside the annotated image, emit a structured text block that maps every marker to a position and a description, then appends your actual instructions.

Put together, a single paste carries everything the agent needs:

# Annotated capture — 1280×800 px

An image is attached. Numbered (ringed) badges point to specific elements.
Markers (position in % of the image, top-left origin):

1. Primary CTA button · ~62 % × 48 %
2. Misaligned icon · ~12 % × 22 %

## Instructions
Make the CTA full-width on mobile and fix the icon alignment.

Now the agent doesn't guess. "Marker 1 is the primary CTA at roughly 62% × 48%. Marker 2 is the misaligned icon near the top-left." The ambiguity is gone, and your instructions are tied to concrete anchors instead of fuzzy spatial language.

Why percentages, not pixels

A small but important detail: positions are expressed as percentages of the image, with a top-left origin — not absolute pixel coordinates. Agents reason about layout relatively ("near the top-left," "centered horizontally") far more reliably than they handle raw pixel math, and percentages survive any downscaling the chat UI applies to your image before the model sees it. If the platform resizes your 1280px capture to 768px, "62%" still points at the same button. "794px" doesn't.

Defending against UIs that drop your text

Remember the chat UIs that keep only the image? There's a defense for that too: bake the legend into the picture. Render the marker descriptions and instructions directly onto the exported image as a caption block. It's redundant with the clipboard text on purpose — if the platform keeps both, great; if it keeps only the image, the legend is still there, pixels and all. Belt and suspenders.

Making it frictionless enough to actually use

An idea like this only pays off if invoking it costs less than just typing the description would. If annotating takes 30 seconds of fiddling, you'll skip it. So the workflow has to be near-instant:

A global shortcut to capture a region (no app-switching, no window juggling).
Click to drop markers — they auto-number themselves.
A one-line note per marker.
Copy. Done. Paste into your agent.

That's the bar: capture-to-clipboard in under ten seconds, from anywhere, without leaving what you were doing. On macOS that means a menu-bar app, ScreenCaptureKit for native-resolution multi-display capture, and rebindable global shortcuts. It stays out of your way until you hit the hotkey.

The tool: Pinpoint

The implementation of all this is Pinpoint — a native macOS menu-bar app, built in SwiftUI + ScreenCaptureKit. Capture a region with a shortcut, drop numbered markers, add notes and arrows, and copy an annotated image plus the structured prompt above. Everything stays local; captures never leave your Mac. It's free, MIT-licensed, notarized and signed.

Source & download: https://github.com/croustibat/Pinpoint
Landing: https://pinpoint-ashy.vercel.app/

I built it for myself and use it every day. The interesting part for me was less the Swift and more the format question: what does a screenshot prompt actually need to contain for an agent to act on it without follow-up questions? The percentage-based marker map plus a baked-in legend is my current answer — but I'd genuinely like to hear how others are solving this.

The takeaway, even if you never touch the tool

The pattern generalizes beyond macOS and beyond this app: when you hand an agent an image, don't make it infer what you're pointing at. Give it stable, named anchors and a machine-readable map of where they are. Whether you build that into your own workflow, a browser extension, or a CLI, the principle holds — pointing beats describing, and a structured map beats a paragraph of spatial prose.

If you're shipping UI work with an AI agent, try replacing your next "the thing in the corner, no the other one" with a numbered marker. You'll feel the difference on the first paste.

Pinpoint is open source (MIT). Issues and PRs welcome — there are a couple of good-first-issues open. If you have a better prompt format for annotated captures, I want to see it.

Zed for Laravel - Complete Editor Setup in One Command

Baptiste Bouillot — Fri, 03 Oct 2025 13:34:40 +0000

Setting up a code editor for Laravel development can be time-consuming. After switching to Zed - the lightning-fast editor from Atom's creators - I spent weeks configuring it perfectly for Laravel.

Today, I'm open-sourcing that configuration as Zed for Laravel - a one-command installer that sets up everything you need.

🤔 What's Zed?

If you haven't heard of Zed yet, it's a high-performance code editor built in Rust with:

⚡ Blazing fast performance - noticeably faster than VS Code
🤝 Built-in multiplayer - collaborate like in Google Docs
🎯 Minimal & focused - less bloat, more productivity
🆓 Free & open-source

Perfect for Laravel development once properly configured.

🎯 The Problem

When I first tried Zed for Laravel, I hit several roadblocks:

Laravel Pint wouldn't format on save
No Laravel snippets out of the box
Blade syntax needed configuration
Artisan commands required manual terminal work
Extensions had to be found and installed individually

Each issue took hours to solve. So I packaged all solutions into a single installer.

✨ Features

🎨 Dual Theme System

Choose your visual experience during installation:

Default (One Dark)

Clean, familiar colors
Standard syntax highlighting
Great for getting started

Catppuccin blur (Custom)

30+ syntax overrides optimized for PHP/Laravel
Bold keywords for quick scanning
Italic types for elegant distinction
Bright green functions (Laravel helpers pop!)
Reduced eye strain for long sessions

📝 130+ Smart Snippets

PHP Snippets (50+)

// route + Tab
Route::get('uri', [Controller::class, 'method'])->name('name');

// model + Tab
class ModelName extends Model
{
    use HasFactory;
    protected $fillable = ['name'];
}

// hasMany + Tab
public function posts()
{
    return $this->hasMany(Post::class);
}

// request + Tab
class StoreUserRequest extends FormRequest
{
    public function rules(): array
    {
        return ['field' => 'required|string|max:255'];
    }
}

Full list: controllers, models, migrations, factories, tests, policies, jobs, events, listeners, middleware, seeders, and more.

Blade Snippets (40+)

<!-- @foreach + Tab -->
@foreach ($items as $item)
    {{ $item->name }}
@endforeach

<!-- component + Tab -->
<x-alert :type="success">
    Message here
</x-alert>

<!-- @auth + Tab -->
@auth
    <p>Welcome, {{ auth()->user()->name }}</p>
@endauth

All Blade directives included: @if, @forelse, @switch, @extends, @section, @include, @can, @error, and more.

Livewire 3 Snippets (30+)

// livewire-component + Tab
class ComponentName extends Component
{
    public $property;

    public function render()
    {
        return view('livewire.component-name');
    }
}

// livewire-validate + Tab
#[Validate('required|string|max:255')]
public string $email = '';

// livewire-on + Tab
#[On('user-updated')]
public function handleUserUpdate($userId)
{
    // Handle event
}

Full Livewire 3 support with properties, lifecycle hooks, events, wire directives, computed properties, and forms.

⚡ Laravel Pint Integration

Automatic code formatting on every save. The kit uses a reliable bash wrapper:

{
  "formatter": {
    "external": {
      "command": "bash",
      "arguments": [
        "-c",
        "cat > {buffer_path} && ./vendor/bin/pint --quiet {buffer_path} && cat {buffer_path}"
      ]
    }
  }
}

Respects your project's pint.json configuration and Laravel coding standards.

🔧 25 Artisan Tasks

Press Cmd/Ctrl + Shift + T to access:

Development:

Artisan Serve
Artisan Tinker
Artisan Route List
Artisan Queue Work

Database:

Artisan Migrate
Artisan Migrate Fresh (with seeding)
Artisan Migrate Rollback

Testing:

PHPUnit (all tests)
PHPUnit (current file)
PHPUnit (parallel)
PHPUnit (with coverage)
Pest (all tests)

Code Quality:

Pint Format (all files)
Pint Format (dirty files only)
Pint Test (check without formatting)

Frontend:

NPM Dev (Vite)
NPM Build (production)

Dependencies:

Composer Install
Composer Update
Composer Dump Autoload

🔌 Auto-Installing Extensions

Four essential extensions install automatically on first launch:

PHP - Full language server support
Laravel Blade - Template syntax highlighting
Env - .env file syntax support
Tailwind CSS - IntelliSense for Tailwind classes

No manual searching or clicking required.

⌨️ Optimized Keybindings

Laravel-friendly keyboard shortcuts:

Shortcut	Action
`Cmd/Ctrl + Shift + I`	Format with Pint
`Cmd/Ctrl + Shift + T`	Run Artisan task
`Cmd/Ctrl + T`	Toggle terminal
`Cmd/Ctrl + Shift + P`	Command palette
`Cmd/Ctrl + B`	Toggle sidebar

All familiar shortcuts that feel natural.

🚀 Installation

Quick Install

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/croustibat/zed-for-laravel/main/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/croustibat/zed-for-laravel/main/scripts/install.ps1 | iex

What Happens

✅ Backs up your existing Zed configuration
🎨 Prompts you to choose a theme (Default or Dracula Pro)
📋 Installs all configuration files
📝 Installs 130+ snippets
⚡ Configures Laravel Pint
🔧 Sets up Artisan tasks
🔌 Queues extensions for auto-install

Time: ~30 seconds

Restart Zed and you're ready to code!

Manual Installation

Prefer doing it manually? Full instructions in the installation guide.

📖 Complete Documentation

The kit includes comprehensive guides:

Installation Guide - Quick start and troubleshooting
Features Overview - Detailed feature breakdown
Configuration Guide - Customization options
Extensions Guide - Managing extensions
Theme Guide - Theme comparison and customization

💡 Why I Built This

After years with VS Code, I wanted something faster. Zed's performance is incredible, but the Laravel setup was fragmented across GitHub issues, forums, and documentation.

I wanted a single source of truth - one command that sets up everything perfectly.

🎯 Perfect For

Laravel developers wanting to try Zed
Zed users starting Laravel development
Development teams needing consistent setup
Anyone tired of slow editors or complex configuration

🗺️ Roadmap

Planning future releases:

v1.1 - Extended snippets

Pest-specific snippets
Inertia.js (Vue/React)
API Resource snippets

v1.2 - More themes

Nord (arctic calm)
Gruvbox (retro groove)
Tokyo Night (cyberpunk)

v2.0 - Advanced features

Laravel Pint config generator
Project scaffolding templates
Team sync features

🤝 Contributing

This is an open-source project and contributions are welcome!

GitHub: https://github.com/croustibat/zed-for-laravel

Ways to contribute:

⭐ Star the repository
🐛 Report bugs or issues
💡 Suggest features
🤝 Submit pull requests
📖 Improve documentation
💬 Help others in discussions

🏁 Getting Started

Ready to try it? Here's a quick start:

# 1. Install Zed for Laravel
curl -fsSL https://raw.githubusercontent.com/croustibat/zed-for-laravel/main/scripts/install.sh | bash

# 2. Choose your theme (I recommend Dracula Pro for Laravel)

# 3. Restart Zed

# 4. Open your Laravel project

# 5. Try a snippet: type 'route' and press Tab

# 6. Save a PHP file to see Pint auto-format

# 7. Press Cmd+Shift+T to run Artisan commands

That's it! You're configured for Laravel development.

🔗 Links

GitHub: https://github.com/croustibat/zed-for-laravel
Zed Editor: https://zed.dev
Laravel: https://laravel.com
Laravel Pint: https://laravel.com/docs/pint

🙏 Acknowledgments

Thanks to:

The Zed team for creating an amazing editor
The Laravel community for feedback and inspiration
Catppuccin theme creators for the beautiful color scheme
All contributors who help improve the project

💭 Final Thoughts

Switching editors is always a bit scary. Will I lose productivity? Will I miss features?

With Zed for Laravel, the transition is smooth. Everything works on day one. The speed improvement alone makes it worth trying.

Give it a shot! If it's not for you, uninstalling is just deleting ~/.config/zed/. No commitment, no vendor lock-in.

Happy coding! 🚀

What editor do you use for Laravel development? Have you tried Zed? Let me know in the comments!

Tags: #laravel #php #zed #productivity #webdev #opensource #developer #coding