DEV Community: Baptiste Bouillot

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