AI coding agents write functional PHP fast, but speed isn’t the same as adherence. Left alone, an agent will happily produce verbose control flow, stale docblocks, and framework anti-patterns that any senior reviewer would bounce in code review. Spatie tackled this by packaging their production coding standards as spatie guidelines skills for Laravel Boost, a machine-readable format that agents like Claude Code, Cursor, and GitHub Copilot can load on demand instead of guessing at your team’s conventions.

This article is part of our wider AI Architecture Module coverage of agent tooling, where Laravel Boost and MCP infrastructure provide coding agents the context they need to ensure AI-generated code follows vendor-specified conventions, not just that it compiles.

If you haven’t wired up the transport layer yet, our guide to rolling out Boost across a Laravel 13 project covers the installation and agent registration steps this article assumes.

The skill activation pipeline

Why machine-readable skills beat static prompt files

A .cursorrules file or a bloated CLAUDE.md gets loaded into every single turn whether it’s relevant or not. That’s wasted context on a JavaScript formatting rule while you’re editing a migration. Skills packages solve this differently.

• Context on demand. Agents activate spatie-laravel-php or spatie-security only when the file being touched matches, not on every prompt.
• Team-wide consistency. Installing through Composer means every engineer, and every CI runner, pulls the identical ruleset. No copy-pasted markdown drifting between machines.
• One-command updates. Spatie ships changes to the package; your team pulls them with a single sync command instead of manually re-pasting guideline files.

[Architect’s Note] The distinction matters more than it sounds. A prompt file is advisory, the agent reads it and might follow it. A skill is conditional, it fires deterministically on file type and task. That’s the difference between a suggestion and a guardrail.

Installing Spatie’s guidelines skills via Laravel Boost

Laravel Boost is the primary transport for registering skill packages inside a Laravel 13 project. Install both dev dependencies through Composer:

composer require laravel/boost --dev
composer require spatie/guidelines-skills --dev

Link the repository immediately, before you run anything else: spatie/guidelines-skills on GitHub. That’s the source of truth for the skill definitions you’re about to install, and it’s the first place to check when a rule looks off.

Running the installer

php artisan boost:install

Select Spatie guidelines from the vendor list, then choose your active coding agent. Boost writes the agent binding files, one skill per convention area: spatie-laravel-php, spatie-javascript, spatie-version-control, and spatie-security.

[Production Pitfall] Don’t skip .boost/skills/ in your .gitignore by habit. Teams that treat generated agent config as disposable end up with every developer running a different skill version locally, which defeats the entire point of pulling this through Composer in the first place.

Running outside Laravel Boost: skills.sh and global Claude Code

Not every project runs Boost. A standalone JavaScript service, a non-Laravel PHP microservice, or a developer who just wants Spatie’s PHP conventions available everywhere still needs a path in.

Global Claude Code integration

To apply the conventions across every local repository without touching individual projects, register them in your user home directory:

mkdir -p ~/.claude && touch ~/.claude/CLAUDE.md
curl -o ~/.claude/laravel-php-guidelines.md https://spatie.be/laravel-php-ai-guidelines.md
echo -e '\n## Coding standards\nWhen working with Laravel/PHP projects, first read the coding guidelines at @~/.claude/laravel-php-guidelines.md' >> ~/.claude/CLAUDE.md

Runtime-agnostic install via skills.sh

For non-Laravel services, install through the cross-runtime skills.sh registry directly:

npx skills add spatie/guidelines-skills

This gets you the same four skills without a Composer dependency, and it’s the path that works across Claude Code, Cursor, Codex, and Copilot uniformly.

[Word to the Wise] If your team runs a mixed stack, decide up front which install method is canonical for which repo type. Having half your services pull skills through Boost and the other half through skills.sh isn’t wrong, but it does mean two update commands to remember, and someone will forget the second one.

Keeping guidelines current: Context7 and CI sync

Enforcing syntax conventions only solves half the problem. When an agent generates code against a specific Spatie package, spatie/laravel-permission, spatie/laravel-medialibrary, it needs accurate, current API signatures, not whatever the model’s training data happened to capture. That’s a separate failure mode from style drift, and it’s the one that produces confidently wrong method calls.

To close that gap, wire in the Context7 MCP server. For background on building or extending your own protocol gateways, see our guide on production MCP server infrastructure in Laravel.

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

With this configured, an agent implementing a Spatie package feature queries Context7 for live documentation instead of relying on stale training data.

Automating the sync

Guidelines evolve. Keeping every developer’s local skill definitions current, and catching drift in CI before it ships, means treating the sync as a scripted step rather than a reminder in Slack:

{
    "scripts": {
        "update-ai-skills": [
            "composer update spatie/guidelines-skills",
            "php artisan boost:update"
        ]
    }
}

Run composer run update-ai-skills during local setup and again as a pull-request check. This is the same discipline we cover in our CI pipeline guide for AI applications: the goal isn’t just passing tests, it’s guaranteeing the agent instructions in front of every contributor match the security and architectural rules currently in force.

[Efficiency Gain] Bundling boost:update into the same CI step you already run for schema validation costs you nothing extra in pipeline time and removes an entire class of “works on my machine, why is the agent doing something different” tickets.

Operational guardrails for teams at scale

A few practices separate a clean rollout from one that quietly rots over six months.

• Prune unused skill drivers. If your application is a pure API backend, disable spatie-javascript. Every active skill costs agent context; loading rules for code you don’t write is pure waste.
• Audit generated output, don’t trust it blindly. Skills reduce style violations, they don’t eliminate the need for review. Check that agent-produced code actually respects PSR-12 and Spatie’s return-type conventions rather than assuming the skill fired correctly.
• Keep automated formatting as your final gate. AI guidelines catch structural and naming issues; a vendor/bin/pint pre-commit hook is still your deterministic backstop for whitespace and formatting drift that skills won’t always reach.
• Match your local environment to what CI enforces. If your team’s dev containers differ from what agents run against locally, guideline enforcement gets inconsistent fast. Our breakdown of a 2026 Laravel AI development stack covers keeping that parity intact.

[Edge Case Alert] Watch for skill collisions when a project pulls in guidelines from more than one vendor package. If a second guidelines package also defines a spatie-laravel-php-equivalent skill, Boost doesn’t merge them, it’s whichever one installs last. Audit .boost/skills/ after any multi-package install, not just after a single-package one.

Where this fits in your AI governance stack

Guidelines skills solve a narrower problem than most of what we cover in Production-Grade AI Architecture in Laravel: they’re about what the agent writes, not what it decides or how much it costs to run. But narrow doesn’t mean small. Style and convention drift is one of the quieter failure modes in agentic development, it doesn’t throw an exception, it just accumulates until a codebase written by five different agent sessions looks like it was written by five different developers who never talked to each other.

The pattern here generalizes past Spatie’s specific rules. Any team with an opinionated internal style guide can package it the same way: distilled into skills, distributed through Boost or skills.sh, kept current through Context7 and a CI sync step. The specific package changes. The architecture, deterministic, versioned, and enforced at the point of generation rather than the point of review, doesn’t.

Additional external references

– Laravel Boost documentation (https://spatie.be/guidelines/ai)
– Context7 MCP server on GitHub (https://github.com/upstash/context7)

---

Frequently Asked Questions

Some Laravel applications that sell products or services need more than a flat percentage off. An e-commerce store might schedule a seasonal sale, or a SaaS product might hand out a launch coupon, and a discount that starts at 10% off can be capped at a maximum, tied to a minimum order total, a per-customer limit, and an expiry date. Laravel Discount by Milwad Khosravi stores all of that on Eloquent models and evaluates it through a single facade.

Here’s what the package covers:

• Two discount types: DiscountType::Percentage and DiscountType::Fixed, with an optional max_discount_amount cap.
• Coupon codes: Discounts with a code act as coupons, while codeless discounts apply automatically.
• Time windows: starts_at and expires_at columns, paired with a valid() query scope.
• Usage limits: Total usage_limit and per-customer usage_limit_per_user enforcement.
• Guest support: Pass a session ID to enforce per-user limits for unauthenticated users.
• Stacking rules: Mark discounts is_stackable and the package works out which combination saves the customer the most.
• Discountable models: The HasDiscounts trait attaches discounts to any Eloquent model.
• Cart integration: A CartDiscount service that applies codes to a Laravel Cart total or to a single cart item.

Percentage and Fixed Discounts

A discount is a standard Eloquent model, so you create one like any other record:

use Binafy\LaravelDiscount\Enums\DiscountType;
use Binafy\LaravelDiscount\Models\Discount;
 
$discount = Discount::query()->create([
 'name' => 'Summer Sale',
 'type' => DiscountType::Percentage,
 'value' => 20,
]);

Applying it goes through the LaravelDiscount facade, which validates the discount before calculating anything and hands back a DiscountResult:

use Binafy\LaravelDiscount\Facades\LaravelDiscount;
 
$result = LaravelDiscount::apply($discount, 200);
 
$result->originalAmount; // 200.0
$result->discountAmount; // 40.0
$result->payableAmount(); // 160.0

The DiscountResult object holds the applied discounts, the original total, and the calculated discount value. payableAmount() subtracts the discount from the original total, clamping the result to a minimum of zero so that fixed discounts never yield negative totals.

A discount of either type can carry a ceiling through max_discount_amount, which is what covers the "20% off, up to $100" case that otherwise ends up hardcoded in a controller:

$discount = Discount::query()->create([
 'code' => 'SAVE20',
 'type' => DiscountType::Percentage,
 'value' => 20,
 'max_discount_amount' => 100,
]);
 
LaravelDiscount::apply($discount, 300)->discountAmount; // 60.0
LaravelDiscount::apply($discount, 1000)->discountAmount; // 100.0

Discount Codes, Expiry, and Usage Limits

Setting a code column turns a discount into a promotional coupon. applyCode() validates the code and throws DiscountNotFoundException if no match exists:

$result = LaravelDiscount::applyCode('WELCOME10', 200, $user);

For campaigns where every customer needs their own code, the package builds them with random_int() and leaves out ambiguous characters like 0/O and 1/I, so nobody misreads a code off a printed card:

LaravelDiscount::generateCode(); // "8FJ2K9QW"
LaravelDiscount::generateCodes(100, 'VIP'); // Collection of 100 unique codes

Length, alphabet, prefix, and separator all live under the codes key in config/laravel-discount.php.

Time-limited offers use starts_at and expires_at. Applying before the window throws DiscountNotStartedException, applying after it throws DiscountExpiredException and fires a DiscountExpired event. Querying for what is live right now is a scope:

Discount::query()->valid()->get();

usage_limit caps total redemptions, and usage_limit_per_user caps them per customer, but neither is settled at the time of application alone. You call redeem() when the order is actually finalised:

LaravelDiscount::redeem($discount, $user, $result->discountAmount);

That runs within a transaction and increments used_count by the limit in the where clause, so the database decides whether the increment occurs at all. Update zero rows and the limit was already reached, which surfaces as DiscountUsageLimitReachedException. Two customers claiming the hundredth spot at the same moment cannot both win it.

Guests get the same treatment through a session ID instead of a user model, tracked in the session_id column of discount_usages alongside the nullable user_id:

$result = LaravelDiscount::applyCode('GUEST10', $total, sessionId: session()->getId());
 
LaravelDiscount::redeem($discount, amount: $result->discountAmount, sessionId: session()->getId());

Conditional and Stackable Discounts

A min_order_value column gates a discount behind a spending threshold and throws MinimumOrderValueException when the total falls short. There’s also a conditions JSON column for storing your own condition data, which is where you’d hang anything the package doesn’t model natively. If you want conditions expressed as composable PHP objects instead, the Discountify package takes that approach.

Discounts can also attach to models. Add the HasDiscounts trait, and you get a polymorphic relationship backed by the discountables table:

use Binafy\LaravelDiscount\Traits\HasDiscounts;
 
class Product extends Model
{
 use HasDiscounts;
}

$product->discounts()->attach($discount);
$product->validDiscounts();
$product->hasDiscount('TECH10');
 
$result = $product->applyDiscounts($product->price);

That last call routes through applyMany(), which is the stacking resolver. It drops any discount that fails validation, splits the rest into stackable and non-stackable, sums the stackable ones (capped at the order total), finds the single best non-stackable one, and returns whichever side saves more:

$result = LaravelDiscount::applyMany([$tenPercent, $tenFixed, $bigSolo], 100);
 
$result->discounts; // the ones that actually applied
$result->discountAmount; // the winning total

The discounts collection on the result matters here. After a stacking decision, you often need to show the customer which codes made the cut, and that collection is the answer.

Laravel Cart Integration

Install binafy/laravel-cart, the cart package from the same author that we covered previously, and a CartDiscount service becomes available for cart-level and item-level discounts:

use Binafy\LaravelDiscount\Integrations\LaravelCart\CartDiscount;
 
$cartDiscount = app(CartDiscount::class);
 
$result = $cartDiscount->applyToCart($cart, 'SUMMER-8FJ2K9QW');
 
$result = $cartDiscount->applyToItem($cartItem, $discount);
 
$result = $cartDiscount->applyItemDiscounts($cart);

applyToCart() checks the cart total against min_order_value and pulls the cart’s user for the per-user limit, so you don’t pass either one yourself. applyToItem() works against price multiplied by quantity for a single line. applyItemDiscounts() walks the cart and applies whatever each item’s underlying model has attached through HasDiscounts, which is how you run a product-level sale across a whole basket without touching the cart total.

Validation, Exceptions, and Events

Checkout forms need to reject invalid code before anything else happens, and the package includes a ValidDiscountCode rule for that. Its message names the actual reason rather than failing generically:

use Binafy\LaravelDiscount\Rules\ValidDiscountCode;
 
public function rules(): array
{
 return [
 'code' => ['required', new ValidDiscountCode(
 orderAmount: $this->cartTotal(),
 user: $this->user(),
 )],
 ];
}

It’s a standard rule object, so it composes with the rest of a form request the same way any custom validation rule does.

Outside validation, every failure case has its own exception extending DiscountException: DiscountNotFoundException, DiscountNotActiveException, DiscountNotStartedException, DiscountExpiredException, DiscountUsageLimitReachedException, and MinimumOrderValueException. Each one exposes the discount that failed through getDiscount(), so you can catch the specific case you want to message differently and let the base class handle the rest:

try {
 $result = LaravelDiscount::applyCode($code, $total, $user);
} catch (DiscountExpiredException $e) {
 return back()->withErrors("Code {$e->getDiscount()->code} has expired.");
} catch (DiscountException $e) {
 return back()->withErrors($e->getMessage());
}

Three events cover the lifecycle: DiscountApplied when discounts are applied to an amount, DiscountRedeemed after a redemption transaction commits, and DiscountExpired when validation hits an expired discount. The redeemed event carries both the discount and the usage row, which is enough to drive analytics or a notification without querying again.

Installation

Laravel Discount requires PHP 8.1+ and Laravel 9-13. Install the package via Composer and run the migrations:

composer require binafy/laravel-discount
php artisan migrate

The service provider registers itself, and the migrations create discounts, discount_usages, and discountables. Publishing the config is optional, and only worth doing if you need to change table names, point at a different user model, or adjust code generation defaults:

php artisan vendor:publish --tag="laravel-discount-config"

Two Artisan commands come along with it. discount:generate produces codes from the terminal, and discount:prune deletes expired discounts along with their usage records, which is a reasonable thing to put on the scheduler:

Schedule::command('discount:prune --days=30')->daily();

The full documentation, including the config reference, is on the Laravel Discount GitHub repository.

Ask a coding agent to write a query against a table it hasn’t seen this session, and it will guess. Confidently, plausibly, and wrong: a foreign key named author_id when the column is actually created_by, a status treated as a free-text string when it’s a tinyint enum, a table it’s sure exists because a table like it usually does. It isn’t lying, it just doesn’t know, and nothing forces it to say so.

The usual fix is pasting a schema dump into the chat at the start of a session. That works until the next migration, at which point it’s just a different kind of wrong: confidently out of date instead of confidently invented.

There’s an obvious third option: let the agent run queries itself, most coding agents can already execute SQL. But that means handing over real database credentials, and a connection that can query can also see rows, not just structure. That’s a bigger grant than the problem needs.

Truss has always been a live, zoomable ER diagram of your Laravel app’s real database schema, structure only, never a row of data. Version 1.8 points that same live structure at a coding agent instead of a browser tab.

Give it meaning a type can’t carry

A column tells an agent its name and type, not what it means. status = 1 doesn’t say “paid” on its own. Annotate it once and every export carries it:

// config/truss.php
'annotations' => [
 'source' => ['config', 'database'],
 'tables' => [
 'orders' => [
 'note' => 'One row per checkout attempt, not per completed order.',
 'columns' => [
 'status' => 'tinyint: 0 pending, 1 paid, 2 refunded',
 ],
 ],
 ],
],

If your database already carries COMMENT strings on tables and columns, leave 'database' in annotations.source and Truss reads those directly, no duplicate config to keep in sync. Either way, a comment is part of the CREATE TABLE definition, not a row: still structure only. Strip them from any single export with --no-annotations when you just want the bare shape.

Trim it to what the question needs

A forty-table schema is a lot of tokens to spend on a question about one table. --compact drops column defaults and non-unique indexes without dropping a single table, column, or foreign key. --focus=orders --depth=1 narrows the export to one table and its foreign-key neighbourhood, the same idea as the dashboard’s focus mode, now available from the command line. And there’s a new llm format alongside the existing five (DBML, JSON, CSV, Markdown, Mermaid), a dense plaintext export tuned for a token budget rather than for a human reading a data dictionary:

php artisan truss:export --format=llm --focus=orders --depth=1 --compact

That’s what the export produces. Calling it is just as direct, in code or over HTTP.

Building the same thing in code goes through a new fluent, immutable Truss facade instead of the command:

Truss::snapshot()->focus('orders', depth: 1)->compact()->toDbml();

And a gated GET {prefix}/export/{format} route serves the identical output to any HTTP client, behind the same viewTruss gate as the dashboard. Command, facade, route, dashboard download: one pipeline underneath all four, so they can never quietly disagree with each other.

Ask it live, instead of pasting a snapshot

The part I actually wanted, though, wasn’t a better export. It was not exporting anything at all.

Truss 1.8 adds an optional server for MCP, the Model Context Protocol that Claude Code, Claude Desktop, and Cursor use to reach outside tools. Built on laravel/mcp, it talks to a coding agent directly over local stdio:

composer require laravel/mcp
php artisan mcp:start truss

Point one at it and the agent gets five tools, list_tables, describe_table, get_schema, focus_table, and get_structural_review, plus a truss://schema resource, all reading the live schema on demand. Every tool advertises MCP’s readOnlyHint, so a client can present them as read-only instead of prompting for write approval on a call that was never going to write anything. No row data, ever, and the same exclusion and managed-connection safeguards as the rest of Truss apply here too, opt-in and off by default behind truss.mcp.enabled.

I pointed it at a real project I’ve worked on for a while, in Claude Desktop, and the difference was immediate: instead of me pasting a schema dump at the start of the conversation, or the agent asking me to run a query to check a column name, it just called describe_table before it wrote anything, the same check that would have caught the guessed author_id from the start of this post. No staleness, because there’s nothing to go stale, it’s reading the same live introspection the diagram uses.

Try it

Update with composer update albertoarena/laravel-truss, and if you want the MCP server too, composer require laravel/mcp on top.

What’s next

More truss:doctor rules and CI-native output formats are next on the roadmap, followed by reading Eloquent relationships for semantic edge labels instead of raw foreign keys, and navigation aids for schemas with a hundred tables or more. If a tool the agent needs isn’t there yet, or an annotation source you’d want isn’t supported, open a discussion.

If there is one change that can turn a 10-second MySQL query into a millisecond one, it is adding the right index. And if there is one change that can quietly slow down your write heavy database over time, it is adding too many. 

Indexes are the most powerful performance tool in MySQL. Understanding how they work — and how they fail — is foundational to managing database performance at any scale.

How Indexes Work

An index is a separate data structure MySQL maintains alongside your table. Think of it like a book’s index: instead of reading every page to find a topic, you go directly to the right page number. 

Without an index on a filtered column, MySQL reads every row in the table on every query. With the right index, it locates matching rows in a fraction of the reads.

Reading EXPLAIN

EXPLAIN is your primary tool for understanding whether MySQL is using an index and how.

EXPLAIN SELECT * FROM customers WHERE email = ‘[email protected]’; 

The most important column in the output is type.

Other columns to watch: 

•  key — which index MySQL chose. NULL means no index used. 

•  rows — estimated rows MySQL will examine. Lower is better. 

•  Extra: Using filesort — sorting without an index. Can be expensive on large result sets.

•  Extra: Using index — the query was satisfied entirely from the index. Very efficient.

Index Types

Creating Effective Indexes

Single-Column Indexes 

The simplest case: a column you filter on frequently.

ALTER TABLE customers ADD UNIQUE INDEX idx_email (email);

Before and after:

Composite Indexes and the Left-Prefix Rule

When queries filter on multiple columns, a composite index is usually more effective than separate single-column indexes.

ALTER TABLE orders ADD INDEX idx_status_created (status, created_at);

MySQL can use this index for queries that start with the leftmost column:

Order composite index columns by how they appear in your most common queries, with the most selective column first.

Covering Indexes

A covering index includes all the columns a query needs. MySQL satisfies the entire query from the index without reading the table at all — shown as Using index in EXPLAIN’s Extra column.

— Query only needs these three columns 
SELECT id, email, status FROM customers WHERE status = ‘active’; 

— Covering index includes all three 
ALTER TABLE customers ADD INDEX idx_covering (status, id, email);

On large tables, the performance difference between a regular index lookup and a covering index can be significant.

Common Mistakes

Over-Indexing

Every index you add slows down writes. MySQL updates all indexes on every INSERT, UPDATE, and DELETE. 

Find and remove unused indexes regularly:

SELECT * FROM sys.schema_unused_indexes;
SELECT * FROM sys.schema_redundant_indexes;

Functions on Indexed Columns

Using a function on an indexed column prevents MySQL from using the index:

Low-Cardinality Columns

Columns with very few distinct values (such as a boolean or a status with three possible values) are rarely worth indexing on their own. MySQL may choose a full table scan if it estimates the index would return a large fraction of rows anyway.

Maintaining Indexes

Want to analyze query performance visually? SQLyog’s Query Profiler shows detailed index usage and execution metrics for every query you run. Try SQLyog free.

Frequently Asked Questions

You may like Pages and you may tolerate Microsoft Word, but text editor BBEdit has been rightly earning devotees on the Mac for 34 years. Here’s how.

There are very few Mac apps that go back this far, and even fewer that remain both actively developed and actually beloved by its users. And there is only one with the trademark "It doesn’t suck."

BBEdit is just a text editor, but rather than this meaning it is limited, it means that BBEdit is focused. It is and always has been a plain text editor, it does not also try to be a mind-mapping tool or an image editor or a chatbot.

This is going to read like an unqualified hymn of praise, although there are actually a few qualifications. But this is what BBEdit does to you. While there are other apps I write in for many different purposes, BBEdit does what it does extraordinarily well.

I don’t remember when I first came across it, but it would’ve been before 2000 and possibly before Steve Jobs came back to Apple. Its original version was written in 1989 because of a problem with editing text on the Mac.

After it was released as BBEdit in 1992, Bare Bones Software never stopped developing it.

The problem back then was just that Apple offered an API for handling text, but it couldn’t handle large files. The creators of BBEdit were working on a version of the Pascal programming language for Mac that effectively demanded longer files.

While Apple’s Pascal faded away, their text editor grew into this favorite for programmers and writers.

If you’ve never used it, though, it’s hard to convey just why BBEdit is so popular among its users. There are people who will never leave the Mac because there isn’t a PC version of BBEdit, for instance.

And as you use it, you have such a clear sense that so do its developers. This is not a day job or a side project, BBEdit keeps getting better because its developers add what they want it to do themselves.

"I use BBEdit for everything I produce that involves text: code (C, C++, Objective-C), web site content (HTML, Markdown, Textile), and more," said Rich Siegel, developer of the app, in a 2011 interview. "In a very real sense, BBEdit is written using itself — my daily-use build is the same one that’s being beta tested or used in the field by our customers."

So an app that has been available for more than three decades, two hardware architectures ago, is still being actively developed. An app that was meant to be just a "bare bones" text editor is still simple to use, yet it has so many features a keystroke away that it’s hard not to gush about this app.

To be fair, there are actually reasons not to use it, there are writers for whom BBEdit is just the wrong choice. But if it suits your writing or it suits how you like to work, BBEdit can make you into a passionate fan.

"BBEdit is legendary because we keep improving it to serve the needs of our customers," Siegel said on the release of version 9. It’s now on version 16, which is promoted as having "millions* of new features and refinements (*estimated)."

With marketing like that, BBEdit remains a taste of those early times with the Mac some 34 years after it was first launched. It’s serious software that doesn’t take itself too seriously.

What BBEdit does and how

The short version is that BBEdit is a text editor. That’s not the same thing as a word processor which offers formatting options like styles or margin control, as a text editor is just for getting the words down.

As such a text editor, BBEdit is fast and responsive, and it generally doesn’t get in your way. You don’t have to set any settings, you can just open it and start typing.

When you have written a lot of text, maybe even over several years, you will start to appreciate a feature called grep. This is a form of regular expression, the feature takes you beyond normal search and replace.

For instance, in any word processor you could search for a date like 01/12/2026. But in BBEdit, you can search for all dates in the document, matching every one of them simultaneously.

It’s a form of regular expression. As well as being powerful, though, the BBEdit version includes an on-screen guide to help you through it as simply as possible.

"Our base started as Mac software developers, scientists, system administrators, and other technical users," Rich Siegel told Apple in 2019. "The first big change was popularity among HTML authors and web back-end developers."

"As word spread, we were able to help folks understand that the internet was built with text that you could treat as data or you could treat it as a document," he continued. "So the next wave brought in internet architects, cryptanalysts, and scientists from unexpected disciplines."

Thos unexpected disciplines, he said, included "writers and other content creators-folks who see their text not as data but as words, and who want as little as possible between them and their words."

Overall design

Beyond the simplicity of writing in BBEdit, part of this get-on-with-it design is in how it stores your documents. Unlike most apps other than Ulysses, BBEdit can in theory be a single repository for all of your writing.

So rather than opening and saving documents all the time, you can just open BBEdit, press Command-N and be writing in a new document. Everything you’ve written before is still there, listed in a navigation bar on the left, until you choose to close it.

You don’t even have to save that previous work before you start a new one.

But then if you want to, you can. Anything you write can remain in BBEdit’s list on the left of the screen, but you can also save any of it out to separate, individual .txt files.

Then it might not require you to set anything up, and it might not get in your way, but BBEdit is built to help you. So for example, if you type an opening quote mark, BBedit immediately adds a closing one right after it and leaves your cursor in the middle.

It’s the same with brackets. Type an opening bracket, and you get that plus a closing one for free. That’s chiefly convenient in that it means you can’t ever forget to include a closing speech mark or bracket, you’d have to choose to delete them.

If you’re a programmer, that can also make the difference between your code working or not. It’s easy to forget to close brackets, unless you’re writing in BBEdit.

But it is also a little pain when you’re writing dialog. So often you’re going to follow a speech with a phrase like "she said," and to do that you have to cursor over the automatically-inserted end quote mark.

You may well have just shrugged at that, and if you did, it’s because you are the true target audience for BBEdit. While any type of writer can use it, and every type of writer does, it is best for coders and programmers.

These are people whose writing tends to be in short lines rather than paragraphs. So they may never even need to notice something about BBEdit lines that will strike a novelist or a journalist immediately.

That’s how, by default, BBEdit does not wrap text at the end of the screen or at some margin stop. You could write a novel on the same long single line if you wanted to.

But then you could alternatively go to Settings, Editor Defaults, and turn on Soft Wrap. Set it to wrap your text at a specific character count, at the width of your default page size for printing, or the width of the window.

There are hundreds upon hundreds of settings you can change, but none that you have to in order to start writing. You can readily believe the gag that it has "millions" of new features, but this is still not an app where you have to study the manual.

Although, actually, there is a manual. In another throwback to the early days of the Mac, there exists to this day a 456-page BBEdit manual, and it is constantly updated.

How it got here

BBEdit began as this way to address a problem on the Mac. Today you know TextEdit as the name of Apple’s free text editing app, but back in the day, it was what the company called its text handling API.

If you wanted to include text in your app, from a word processor to just labels on a drawing, you could use this API and it did the job. But it wouldn’t handle anything over 32K, it wouldn’t handle anything long.

BBEdit was made to show that longer files could be handled on the Mac. It did the job, it was popular, and in 1992 when it first came out, BBEdit was also free.

That didn’t last. Around a year later, Bare Bones Software launched version 2.5 and began selling it for $99 (around $230 in today’s money). Users of the previous free ones, or owners of various programming languages such as THINK Pascal, could buy it for $49.

At the same time, Bare Bones Software released a cut-down edition called BBEdit Lite. That was free, and users of it could upgrade to the full BBEdit for $49.

They could get it on a floppy disk by mailing — not emailing, regular postal mailing — the developer on an Massachusetts address. Please enclose a check for $5.

BBEdit Lite no longer exists, and nor does its brief replacement, TextWrangler. That was released in 2003 for $49, offering what Bare Bones Software thought would be a compelling mix of BBEdit features for programmers and database administrators.

Compared to some apps, TextWrangler did well, sticking around 14 years, even if it quickly became free. It may have seemed like it spent much of that time nagging users to upgrade to BBEdit, but come 2017, there was no longer any choice.

TextWrangler was ostensibly folded back into BBEdit and users were encouraged to move to the full app.

"We promise that you will feel right at home, because BBEdit and TextWrangler are identical in every way that you’re used to," said the company at the time. "They’re built on the same foundation, by the same developers, with the same care; and they work the same way."

Behind the scenes, that must’ve been a reason to drop TextWrangler. Maintaining the same code base across two apps was surely taking up time that could be spent developing new features.

It certainly wasn’t the lure of cash from upgraders that made Bare Bones Software do this. As welcome as that would doubtlessly be, the company also sweetened the deal.

If you bought or upgraded to BBEdit at that time, you could use it for free for 30 days. It’s not unusual to have such a trial period, but what happens afterward is much more rare.

Bare Bones Software made it so that you could continue using the app for free, with just a limited feature set. What it left in was generous, and really it created what was effectively a new, free, BBEdit Lite in all but name.

BBEdit and Apple

If you’re a long-time Mac user, you may distantly remember technologies such as OpenDoc, but you’re unlikely to have used any of it. Bare Bones Software has, it even added OpenDoc support to BBEdit.

BBEdit has been a good Mac citizen from the start but sometimes you don’t know what you’ve got until it’s gone. That happened with Apple and BBEdit over the Mac App Store.

While it’s never really seen a fraction of the business that the iPhone App Store has, the Mac version has been around longer than you think. It debuted in 2011 and BBEDit was right there as one of the very first products on the Mac App Store.

By 2014, though, it was gone.

The reasons given at the time were not very specific, but they centered on how the Mac App Store sandboxes apps. Any app on the store is deliberately limited to prevent it being able to control the user’s Mac or other apps.

In BBEdit’s case, the app was reportedly not allowed full access to the user’s files and folders. It needed to be able to open and save wherever the user wanted, and at the time, Apple put limits on this.

There was also, though, an issue of money. While BBEdit was a one-time purchase, Bare Bones Software has always issued paid upgrades at intervals.

The Mac App Store did not allow for paid upgrades once a user had bought the app. So the company could have gained a true believer but never know it, never profit from it, and that user would never know what new features were available.

By 2019, enough developers had complained about sandboxing that Apple made some changes. They were sufficient to mean that BBEdit came back on the Mac App Store, but perhaps chiefly because there was now a solution to the upgrade problem.

While Apple still does not allow paid upgrades, it both allows and encourages subscriptions. So today you can buy BBEdit 16 from the developer for a one-off $60, but you can subscribe via the Mac App Store for $5/month, or $50/year.

And if you were looking when BBEdit returned to the Mac App Store in 2019, you will have seen Apple rushing to make up for arguably ignoring it. That return saw an App Store front page profile of its main developer, Siegel, plus an article about BBEdit’s search features, and another about its overall feature set.

At that time, Apple’s senior vice president of worldwide marketing was Phil Schiller, who oversaw the App Store. He tweeted a welcome back to BBEdit, although that tweet is no longer available since Schiller quit Twitter/X back in 2022.

There’s something missing

BBEdit sounds perfect. Unless you’re a novelist or a screenwriter, or perhaps even a non-fiction author, maybe it is. And if you are any of those things, you can make BBEdit work for you if its comprehensive yet no-nonsense feature set appeals.

What you can’t do is make BBEdit work on anything other than a Mac. There’s no PC version, for example, although if you cared about that you wouldn’t be reading this far into an AppleInsider article.

The real missing piece is the iPad.

It’s been some years since Bare Bones Software has talked about why it’s stayed Mac-only. So perhaps things will change, but 37 years after starting it, and 34 since it went on sale, BBEdit is a legend among macOS apps.

Enough so that it’s one of the very, very few apps I would enthuse about this much. Bare Bones Software and Naomi Pearce helped out with finding images like that ancient photo of the boxed version, but they haven’t read this prior to publication, and they certainly didn’t pay for it.

Try it out for yourself. Once again, it may not be the right writing tool for you, but if it is, you’ll become a fan.

BBEdit 16 for Mac is available for $60 direct from the developer as a one-time purchase. You can also get it from the Mac App Store on subscription for $5/month, or $50/year.