DEV Community: אחיה כהן

One command adds import, WhatsApp drip and campaigns to self-hosted Chatwoot

אחיה כהן — Sun, 05 Jul 2026 13:12:46 +0000

I run a self-hosted Chatwoot for support, and I genuinely love it. But every time I wanted to actually grow on it, I hit the same wall.

Import a few thousand contacts? Hand-write API calls, or click them in one at a time. Run WhatsApp follow-up sequences? Not built in. Send a bulk campaign with a real variable preview, or attach a video over WhatsApp's 16 MB limit? Nope.

And every off-the-shelf "fix" was the same shape: a separate SaaS, a second server, or a subdomain — each with its own login and its own copy of my customers' data.

So I built the missing layer and open-sourced it: chatwoot-power-tools (MIT).

One command, same-origin, no second server

curl -fsSL https://github.com/achiya-automation/chatwoot-power-tools/archive/refs/heads/main.tar.gz | tar xz \
  && cd chatwoot-power-tools-main && sudo bash install.sh

The installer detects your existing Chatwoot Docker Compose stack, provisions a least-privilege DB role, starts one small sidecar container (cwpt-engine) next to your own containers, adds a single reverse-proxy route, and injects a dashboard script. Everything it adds is served same-origin under one /chatwoot-addons/* path — no subdomain, no CORS, no extra account, and no customer data ever leaving your box.

It's a plain, readable Bash installer (no opaque binary piped to root), it's --dry-run-previewable, and --uninstall reverses everything while preserving your data and any existing DASHBOARD_SCRIPTS.

What it adds

📥 Smart contact import — a CSV/Excel wizard styled to look native, detects columns bilingually (Hebrew + English headers), flags duplicates before import, and maps onto custom attributes.

🔁 WhatsApp drip sequences — automated template-message sequences managed from inside Chatwoot. Enroll a lead by setting a conversation attribute; messages then send at the intervals you configure, automatically skipping quiet hours, Shabbat and Jewish holidays.

✨ Dashboard upgrades — a "Sequences" sidebar item, variable chips + a live preview on the native campaign modal, and client-side video compression (WebCodecs) so you can send video past WhatsApp's 16 MB limit with no server-side transcode.

The part I'm most proud of: least-privilege by design

The engine talks to your Chatwoot only through the API, and its database role is deliberately tiny. It gets SELECT on the handful of tables it reads, plus UPDATE on a single column — contacts.custom_attributes. That's it.

It literally cannot read or change names, phones, emails, or anything else. A bug in the engine can't touch them, because the grant doesn't exist. The role's password is generated on your server with openssl rand and written only to your Chatwoot .env — it never enters logs, command output, or git. No telemetry, no third parties.

Fully bilingual, automatically

The entire UI localizes to each agent's own Chatwoot language — Hebrew (RTL) or English (LTR) — detected automatically, no configuration. Same screen, either way.

Try it

It's MIT, self-hosted Docker Compose only (not Chatwoot Cloud), with a full CI suite. If you self-host Chatwoot, I'd genuinely love your feedback — and issues/PRs are welcome.

👉 github.com/achiya-automation/chatwoot-power-tools

Exactly-Once by Default: How Durable Execution Changed the Way I Build Automations

אחיה כהן — Thu, 02 Jul 2026 11:21:39 +0000

In the previous article I described moving 34 production automations off a visual no-code platform and rewriting them in TypeScript. The single feature that made that migration worth the effort was durable execution with exactly-once semantics. This post is the deep-dive.

The problem: a crash in the middle

Here's a scenario every automation eventually hits. A workflow receives a new lead, sends them a welcome message, then writes them to the CRM:

Send welcome message
Save to CRM

Now imagine the process crashes exactly between step 1 and step 2 — a deploy, an OOM kill, a dropped node. What happens on restart?

Re-run the whole thing → the lead gets the welcome message twice.
Don't re-run it → the lead never lands in the CRM.

Both outcomes are wrong. This is the at-least-once vs at-most-once dilemma, and in a system doing real side effects (sending messages, charging cards, creating records) it is not academic.

The usual fix, and why it hurts

Most tools give you retry-on-failure. But retry alone re-runs side effects. To get exactly-once you build it yourself:

Generate an idempotency key per lead.
Before each side effect, check "did I already do this?" against some store.
Persist progress after each step so a restart knows where to resume.
Repeat this bookkeeping for every workflow you ever write.

It works, but it's tedious, easy to get subtly wrong, and it clutters every automation with plumbing that has nothing to do with the business logic.

How DBOS makes it the default

DBOS flips this: durability is the baseline, not a feature you assemble. You annotate ordinary TypeScript functions. A workflow orchestrates; steps are the units that do side effects and get checkpointed.

import { DBOS } from "@dbos-inc/dbos-sdk";

export class Onboarding {
  @DBOS.workflow()
  static async welcomeLead(lead: Lead) {
    await Onboarding.sendWelcome(lead);   // step 1
    await Onboarding.saveToCRM(lead);     // step 2
  }

  @DBOS.step()
  static async sendWelcome(lead: Lead) {
    await whatsapp.send(lead.phone, "Welcome aboard!");
  }

  @DBOS.step()
  static async saveToCRM(lead: Lead) {
    await crm.upsert(lead);
  }
}

As the workflow runs, DBOS records the completion of each step in Postgres. From the docs:

"If a workflow is interrupted for any reason (e.g., an executor restarts or crashes), when your program restarts the workflow automatically resumes execution from the last completed step."

And crucially:

"Steps are tried at least once but are never re-executed after they complete."

So in our crash scenario: sendWelcome already completed and was recorded. On restart, DBOS skips it and resumes at saveToCRM. The welcome message is not sent twice; the CRM write finally happens. Exactly-once, with zero idempotency bookkeeping in my code.

No separate workflow server, no queue broker to babysit — just your program and Postgres.

The one rule to internalize

Durability isn't free magic — there's a contract. The workflow function must be deterministic: given the same recorded step results, replaying it must take the same path. So anything non-deterministic — network calls, random values, reading the clock, DB writes — belongs inside a step, never loose in the workflow body. Steps are the checkpointed boundary; the workflow is the recomposable script that ties them together.

Once that clicks, the mental model is clean: workflow = the plan, steps = the effects.

What this replaced

On the visual platform, I got retry and error branches, but exactly-once across a crash was something I had to design per flow — manual idempotency keys and "already done?" checks. Here it's the substrate. My code shrank to the business logic, and the reliability guarantee got stronger, not weaker.

That reliability is also what I sell to clients: fewer leads slipping through the cracks, no duplicate messages, no half-finished processes. (See the client-facing angle in the LinkedIn series.)

A note on how I built it

I'm one person, and wiring durable execution into 34 real automations is a lot of surface area. I did it in pairing with Claude Code — it turned "I understand exactly-once in theory" into workflows running in production, TypeScript module by TypeScript module. The barrier between a concept and a shipped system is thinner than it's ever been.

Sources: DBOS Workflows tutorial · Workflows & Steps reference

How do you handle mid-workflow crashes today — hand-rolled idempotency, an outbox, something else? Curious what patterns people have settled on.

I Deleted My No-Code Automation Platform and Rewrote 34 Workflows in TypeScript

אחיה כהן — Thu, 02 Jul 2026 11:20:45 +0000

A few weeks ago I deleted two years of work.

Thirty-four automations that run every day — for me and for my clients. WhatsApp AI bots, lead capture from Facebook and web forms, PDF report generation, calendar booking, CRM sync, notifications. All of them built the same way: box after box, dragged and dropped onto a visual canvas.

I deleted the lot and rewrote them in code.

This isn't a "no-code is bad" post. The visual platform I used (n8n) is genuinely excellent and open-source, and it let me ship fast for years. But as the system grew, I started fighting the tooling instead of building. So I want to walk through why code-first won for my use case, the numbers that came out of it, and — importantly — the parts that did not improve, because I have no interest in hype.

What "code-first" actually changed

Here's the before/after, minus the buzzwords.

Maintenance. Before, every change meant opening a browser, hunting for the right node inside a diagram, and dragging. Now every change is a line of code and a git commit. Full history, real diffs, code review, and instant rollback when something breaks.

Building. Before, each new automation was assembled from scratch on the canvas. Now I compose typed, reusable modules. Faster, and consistent across the whole system.

Control. The logic is mine, written explicitly. No magic behind a box, no surprises.

No lock-in. It's standard code in an open format. It runs anywhere; it isn't married to any one platform's JSON schema.

I built on DBOS — a framework that runs workflows written as ordinary TypeScript, backed by Postgres, with durable execution built in. More on that below.

The numbers

The headline that still makes me smile:

Memory: from ~1.4GB down to ~150MB. Roughly 10×.

Same 34 automations, same work, a tenth of the footprint. At idle the new stack sits around 48MB. A smaller, cheaper server now runs the same load with plenty of room to grow.

A couple more measured figures:

Metric	Result
Throughput	~1,167 workflows/second
Per-workflow overhead	~30ms
Idle memory	~48MB
Memory vs. old stack	~150MB vs ~1.4GB (~10×)

Where did the memory go before? To scale under load I had to add worker processes and a queue layer — each one eating more RAM. Now the base is so light that most of the time there's simply nothing to talk about.

The honest part (because I hate hype)

The bots themselves are not faster to respond. Here's why: when a bot talks to a large language model, the LLM sets the pace, not the infrastructure around it. The model's "thinking" takes what it takes, and no runtime swap changes that.

So what did I actually gain? A server that breathes, far higher concurrency, and lower infrastructure cost. Stability and efficiency — not the latency of a single reply. If someone tells you a runtime swap made their AI bot "instant," be skeptical.

How one person did all this

Translating 34 live automations to code, keeping behavior identical, testing each one, and shipping to production without a single client noticing — that is not a one-person job. Historically it's a team, over weeks.

I did it solo, working with Claude Code.

In practice it was a dialogue with a tool that reads code like a senior engineer: it helped me understand each existing automation, rewrite it in TypeScript, catch bugs before production, and verify each flow against the original. I direct, decide, and approve; it does the heavy lifting, fast.

And the migration itself was invisible to the outside world. A Caddy reverse proxy routes all the inbound traffic — WhatsApp, webhooks, forms — so every sender kept hitting the same endpoints. I swapped the engine mid-flight; nobody felt a thing.

The takeaway

The real story here isn't DBOS versus n8n. It's that the ceiling moved.

For years we all learned to work inside limits: "too complex to hand-write," "needs a team," "not worth the weeks." A lot of those limits just quietly disappeared, and our habits haven't caught up yet.

So the question I keep asking myself now isn't "how do I do what I already do, a bit faster?" It's "what would I build if the technical barrier weren't there?" Half of my someday-list turns out to be within reach today.

Next article: a technical deep-dive into the one feature that made this migration worth it — exactly-once durable execution — with real code.

Have you moved something from no-code to code-first? What pushed you over the edge? I'd genuinely like to hear it.

Apple shipped an official Safari MCP. I read all 17 tools. Here's why I'm keeping mine.

אחיה כהן — Thu, 02 Jul 2026 07:15:08 +0000

Apple shipped the tool I've spent a year building as open source.

For about ten minutes on Tuesday night, I thought I was cooked. Safari Technology Preview 247 dropped with an official Safari MCP server, built by the WebKit team, the people who actually make the browser. I maintain a scrappy AppleScript version of the same idea. David, meet Goliath's in-house team.

So I did the only thing that made sense. I read all 17 of their tools, one by one. Somewhere around tool #9 I stopped feeling cooked. By the end I knew I wasn't deleting my repo, and the reason is a single sentence Apple wrote themselves.

First, credit where it's due

The design is clean. It runs on safaridriver, the WebDriver binary already shipping inside Safari, so setup is one command. It runs entirely on your machine. No page content, no screenshots, nothing phones home to Apple. The 17 tools cover the boring-but-essential debugging loop: open a URL, read the DOM, click things, watch the network tab, grab the console, screenshot the result.

If what you want is an agent that debugs how a page renders in WebKit, this is a first-party, well-built way to get it. And honestly? It's the best validation I could ask for. A year ago people asked me why anyone would let an AI drive a browser. Apple just answered that for me.

The one sentence

Here's the line, straight from Apple's own docs:

"The Safari MCP server does not have access to your personal information in Safari (e.g. AutoFill or other browser activity)."

Read that again if you build automation. safaridriver spins up a clean, isolated WebDriver session. Fresh window. A "controlled by automation" banner across the top. None of your logins. None of your cookies. Not the twelve tabs you already have open.

For a debugging tool, that's the right call. Reproducible, sandboxed, no personal state leaking into a test run. I'd have designed it the same way.

It's also the exact problem I built my tool to avoid.

Why mine exists at all

I never built safari-mcp to debug rendering. I built it because I wanted an agent to drive the Safari I'm already logged into: my Gmail, my GitHub, my Ahrefs dashboard, my bank. No re-auth, no fresh profile, no QR code. It runs on native AppleScript in the background, on the stable Safari you already have, on any Mac. No Technology Preview required.

That's the whole difference. Apple's server opens a sterile room and hands your agent a key. Mine walks into the room you're already sitting in.

Here's the honest scorecard I dropped into my README:

	safari-mcp	Apple `safaridriver --mcp`
Your real logins / cookies	✅ Your actual Safari	⚠️ Isolated automation session
Runs on	✅ Stable Safari, every Mac	❌ Technology Preview 247 only
Background, no focus steal	✅ Yes	❌ Dedicated automation window
Tools	96	~17
Cookies / localStorage / IndexedDB	✅ 10 tools	❌
Network mocking + throttling	✅ Yes	❌ Read-only
Official Apple support	❌ Community, MIT	✅ Apple, WebDriver-standard

I checked two of those rows on my own machine before writing this, because I didn't want to bluff. Stable safaridriver in Safari 26.5 has --port, --bidi, --enable, --diagnose. No --mcp. It only exists in the Preview today. And the isolated session really does mean no logins. That's the wall, and I built safari-mcp to climb over it.

So am I changing anything? Yes. Three things, none of them "switch."

Positioning. Apple didn't kill safari-mcp. They told the world what it's for. Theirs is the clean-room debugger; mine drives the browser you live in. I rewrote my README to say that out loud instead of pretending we compete.

A safaridriver backend, eventually. My tool already runs two engines under the hood, a Safari extension and AppleScript. Bolting on a third opt-in WebDriver backend, for people who genuinely want a sterile session, isn't a rewrite. It's a weekend. But it waits until --mcp reaches stable Safari, because right now it only lives in the Preview.

Stealing their best idea. WebDriver synthesizes input events the official, rock-solid way. My native-click path leans on CGEvent, which macOS quietly breaks every other release (ask me how I know). Apple just handed me a sturdier fallback. I'd be silly not to take it.

The takeaway

When the company that makes the browser ships an official version of your side project, the reflex is to panic. Don't. "Official" and "replacement" are different words. I read all 17 tools before I reacted, and the honest comparison turned out to be better marketing than any launch-day panic post could have been.

Apple built the sterile room. I built the tool for the room you already live in. Both should exist.

I just know which one I'll actually reach for on a Tuesday.

safari-mcp is open source (MIT): github.com/achiya-automation/safari-mcp. 96 tools, npx safari-mcp, no Chrome, native macOS. I write about the things I build at achiya-automation.com.

Genuine question, because I keep flip-flopping on it: would you ever trade your logged-in browser for a clean automation session? What would have to be true to make that worth it?

My MCP server had 32 green tests. Not one of them had ever called a tool.

אחיה כהן — Mon, 29 Jun 2026 07:18:15 +0000

For weeks my CI badge was green and I believed it.

Safari MCP is an open-source tool that lets an AI coding agent drive a real, logged-in Safari — click, type, read the page, switch tabs. It registers 96 tools. The test suite ran on every push across three Node versions and came back 32 passed, 0 failed. Green is green. I shipped on it.

Then I went to extract a chunk of index.js into its own module, and while staring at the diff I asked a question I should have asked months earlier:

Which of these 32 tests would fail if I broke the security boundary?

The answer was none of them.

What the tests actually tested

I read the suite line by line. Two of the tests carried almost all the weight:

server starts and lists all registered tools — boots the server, asserts the tool count.
valid schemas + unique names — every tool has a schema, no duplicate names.

The rest were string-escaping and JS-injection helpers. All useful. All real. And all of them answered the same kind of question: does the thing exist and is it shaped correctly?

Not one of them answered: does calling it do the right thing?

It's the test-suite equivalent of checking into a hotel by confirming the building has 96 doors with correct room numbers — and never once trying a key in a lock.

The boundary nobody was watching

The most security-critical code in Safari MCP is tab ownership. The rule is simple to say and easy to get subtly wrong: the agent may only touch tabs it opened. It must never navigate, click, or read a tab the human opened — that's someone's half-written email, their banking session, their unsaved work.

That logic lived in a tangle of module-local state: a map of owned tabs, a TTL so stale entries expire, a blank-URL sentinel for tabs mid-load, a matcher that decides whether https://app.example.com/org is "the same" tab as https://app.example.com/org-evil.

Read that last one again. /org vs /org-evil. If the matcher is even slightly too loose — a startsWith where it needed a path-boundary check — the agent could decide it "owns" a look-alike tab and start typing into it.

There was not a single test exercising that comparison. The suite was 100% green the whole time the security boundary had zero behavioral coverage. A regression there wouldn't have turned CI red. It would have turned CI green and wrong — the worst color a test suite can be.

Why "green and wrong" is worse than red

A red build is honest. It stops you. The failure is the feature.

A green build that proves nothing gives you the feeling of safety without the substance — and you make decisions on that feeling. You refactor confidently. You merge contributor PRs confidently. You tell users the boundary holds. Every one of those is a small bet placed on a test that was never actually watching the thing you care about.

This is the same failure mode I keep running into in this project, wearing a different costume each time:

A macOS API that accepted my click and silently delivered it nowhere — "success" that did nothing.
A README that claimed 80 tools while the code had 96 — a fact nobody had pinned down.
And now a test suite that reported confidence it hadn't earned.

The pattern is always the same: the system doesn't fail loudly. It quietly does less, and the signal you're trusting keeps saying "fine."

The fix: make the boundary fail loudly

Before extracting anything, I wrote the tests that should have existed from day one — behavioral tests that call the ownership logic and assert on its decisions:

/org does not own /org-evil (the path-boundary case).
An entry past its TTL is no longer owned.
The blank-URL sentinel is treated as in-flight, not as a match.
Ownership survives the kind of state round-trip the refactor was about to perform.

Nine of them. The suite went from 32 to 41 (it's 46 today, after a later round for macOS compatibility). More importantly: now if I loosen that matcher by one character, a test goes red and names the boundary in the failure message. The security rule finally has a tripwire.

Only then did I do the refactor — extract the state layer into its own module — and the new tests held identity across the move, which is exactly the confidence I'd been pretending to have.

The rule I'd give past-me

Counting your tools is not testing your tools. Schema validation is not behavior. A green suite tells you what it checks — and stays silent about everything it doesn't, in the most reassuring tone possible.

So the question to ask of any test suite, especially one you've been trusting:

What is the single worst thing that could break in this codebase — and would a test go red if it did?

If the honest answer is "no," your CI badge isn't lying. You just never asked it the right question.

Safari MCP is open source — the ownership tests are in test/ownership-state.test.mjs if you want to see what "test the boundary" looks like in practice. More on what I'm building at achiya-automation.com.

What's the security boundary in your project that your test suite has never once exercised?

My tool said "clicked." Safari never saw it. macOS 26 quietly broke a system API.

אחיה כהן — Thu, 25 Jun 2026 15:04:26 +0000

I maintain an open-source MCP server that lets AI coding agents drive real Safari on macOS. One of its tools sends a native mouse click — an OS-level CGEvent, not a JavaScript element.click() — because some forms (Vue/React with anti-bot checks, OAuth consent screens) reject anything that isn't isTrusted: true. For two years that tool worked.

Then a user on macOS 26 filed a bug, and it took me an embarrassingly long time to believe what I was reading:

The MCP returns Native clicked: BUTTON "Next" at screen (x, y). But the click listener on the page never fires. window.__clicks stays empty.

The tool said it clicked. The page swears nothing happened. Both were telling the truth.

The most expensive kind of bug: the one that succeeds

Here's the failure mode that cost me a weekend. The API call returned success. No exception, no error code, no permission dialog. CGEvent.postToPid(safariPID) took my event, said "sure," and dropped it on the floor.

A bug that throws is a gift — it points at itself. A bug that silently succeeds sends you hunting everywhere except the actual cause. So I hunted.

Accessibility permission? Granted. Verified auth_value=2 in the TCC database for the exact helper binary.
Code-signing identity stable? Yes — signed with a fixed identifier so the grant survives reinstalls. (An earlier macOS bug had silently revoked it; I'd already fixed that.)
Coordinates wrong? No. document.elementFromPoint(x, y) returned the exact <button> I was aiming at, to within a pixel.
Did Apple remove the private window-targeting fields? No. kCGMouseEventWindowUnderMousePointer and its can-handle-this-event sibling are still public in the macOS 26.5 SDK headers.

Every single thing that's supposed to make a synthetic click land was correct. And the click still didn't land.

What actually changed

macOS 26 (Tahoe) tightened the delivery semantics of CGEvent.postToPid for processes that render sandboxed WebKit content. The private fields are still accepted at the API surface — that's why there's no error — but the event never crosses the boundary into Safari's WebContent process. It's authorized, it's well-formed, and it goes nowhere.

This is the gap that breaks debugging: the API contract ("post this event to that PID") still holds, while the behavioral contract ("and the target will receive it") quietly does not. Your code is correct against the documentation. The documentation is correct about the API. Neither is correct about reality on this OS version.

And nothing in the stack tells you which macOS you're on, because for two years it never mattered.

The fix wasn't a permission. It was a fact.

My first instinct was wrong: keep chasing the grant. Try a different event tap. Re-sign the binary again. That's the trap — treating an OS behavior change as a misconfiguration you can fix with one more checkbox.

The real fix was to stop pretending the environment is uniform and surface the one fact that disambiguates the whole bug class: the macOS version itself.

My server has a doctor command — run it first when "clicks don't work even with permissions granted." It checked Safari, Apple Events, the helper daemon, Accessibility, Screen Recording, codesigning… and never printed the OS version. The single most relevant number for a "native input silently fails" report was missing.

So I added a small, pure function — no I/O, unit-tested directly — that classifies the version and flags the risky range:

export function macosCompatNote(productVersion) {
  const major = parseInt(String(productVersion ?? "").trim().split(".")[0], 10);
  if (!Number.isFinite(major)) {
    return { risky: false, line: "macOS version: unknown" };
  }
  const risky = major >= 26;
  const line = risky
    ? `macOS ${productVersion} ⚠ CGEvent native clicks/keys may silently no-op on ` +
      `macOS 26+ even with Accessibility granted (issue #29) — for trust-gated ` +
      `forms prefer JS evaluation or extension-based clicks.`
    : `macOS ${productVersion} — CGEvent native input supported.`;
  return { version: productVersion, major, risky, line };
}

Then doctor calls it as best-effort — sw_vers is macOS-only and absent in CI sandboxes, so it's wrapped in a try/catch that can never block the rest of the diagnostics:

try {
  const { stdout } = await execFileAsync("sw_vers", ["-productVersion"], { timeout: 2000 });
  osLine = macosCompatNote(stdout).line;
} catch { /* sw_vers unavailable — skip the line, the other checks still stand */ }

That's the entire change. It doesn't fix the regression — I can't patch Apple's event delivery. What it does is convert a multi-hour phantom-permission hunt into a single line at the top of the diagnostic output: you're on a version where this API path is known to no-op; reach for the JavaScript or extension path instead.

The lesson I keep relearning

Three things stuck:

A success that does nothing is worse than a failure that screams. When you wrap a platform API, the dangerous case isn't the one that errors — it's the one that returns OK and silently misbehaves. Assume your dependencies can lie politely.
Put the environment in the diagnostics. Every "works on my machine" bug is really "my machine differs from yours in a way neither of us is looking at." The cheapest fix is to make your tool print the difference. The OS version cost me a weekend precisely because nothing surfaced it.
Detect-and-warn beats assume-and-fail. I can't make postToPid work on Tahoe. I can make sure nobody else spends a weekend re-deriving why it doesn't.

The native click still doesn't land on macOS 26 — that's Apple's to change, and I'm tracking it. But now the very first thing the tool tells you is the truth about where you're standing. Sometimes the best you can ship isn't a fix. It's an honest map.

This is from Safari MCP, an open-source MCP server for native Safari automation on macOS (no Chrome, no WebDriver). The full macosCompatNote + doctor change is on main. I write about the unglamorous edges of browser automation and indie automation work at achiya-automation.com.

What's the worst "the API said success but did nothing" bug you've hit — and how long before you stopped blaming your own code?

How Far You Can Actually Customize Chatwoot (Self-Hosted)

אחיה כהן — Wed, 24 Jun 2026 12:17:44 +0000

Originally published on achiya-automation.com.

Most "customer support platform" comparisons end the same way: pick a SaaS, accept its limits, pay per seat forever. This one doesn't. Chatwoot is open-source, and when you self-host it, "customization" stops meaning "which toggles did the vendor expose" and starts meaning "what does your team actually need." I've been running Chatwoot in production for clients long enough to know where that line really is — so here's the honest map of how far you can push it.

There's a specific reason I keep recommending Chatwoot over a closed platform like Intercom, and it isn't price. It's that with a closed SaaS, your customization ceiling is whatever the vendor decided to put in the settings page. With self-hosted Chatwoot you have the source code, the database, and the deployment — so the ceiling is essentially "what can you build." This article is a practical tour of that gap.

TL;DR

Widget — colors, position, locale, behavior, and custom CSS are all configurable; on self-hosted you can patch the widget strings and launcher icon directly
White-label — INSTALLATION_NAME, BRAND_NAME, BRAND_URL remove Chatwoot branding (self-hosted only)
Two APIs — the Application API works inside one account (conversations, contacts, messages); the Platform API manages accounts, users, and bots across the whole install
Webhooks — events like conversation_created and message_created push to n8n / your CRM / custom logic
Dashboard apps — embed your own web app inside the agent inbox via an iframe, with conversation context passed in
Self-hosted unlocks — direct DB access, custom code/forks, no API rate limits, custom channels, full rebranding

A note before the technical part: every fact below maps to Chatwoot's official developer documentation at developers.chatwoot.com. I run this stack daily, but I'd rather you trust the docs than trust me — so check anything load-bearing for your project against them.

1. Widget Customization

The website live-chat widget is the most visible surface, and it's also the easiest to bend. The standard embed is the Chatwoot SDK script plus a settings object you define before the script loads:

<script>
  window.chatwootSettings = {
    locale: "en",            // any locale Chatwoot ships, e.g. "he", "ar", "fr"
    position: "right",       // "left" or "right"
    type: "expanded_bubble", // "standard" or "expanded_bubble"
    launcherTitle: "Chat with us",
    darkMode: "auto",        // "light" or "auto"
  };

  (function (d, t) {
    var BASE_URL = "https://app.chatwoot.com"; // your self-hosted URL
    var g = d.createElement(t), s = d.getElementsByTagName(t)[0];
    g.src = BASE_URL + "/packs/js/sdk.js";
    g.defer = true; g.async = true;
    s.parentNode.insertBefore(g, s);
    g.onload = function () {
      window.chatwootSDK.run({
        websiteToken: "YOUR_WEBSITE_TOKEN",
        baseUrl: BASE_URL,
      });
    };
  })(document, "script");
</script>

The widget color and avatar come from the inbox settings in the dashboard, so non-developers can change them without touching code. Beyond that, the SDK gives you runtime methods to make the widget aware of who's chatting — which is where it stops being a generic bubble:

// Identify the logged-in user so conversations attach to the right contact
window.$chatwoot.setUser("USER_IDENTIFIER", {
  name: "Jane Doe",
  email: "jane@example.com",
});

// Attach structured context that shows up on the agent side
window.$chatwoot.setCustomAttributes({
  plan: "business",
  signup_date: "2026-01-15",
});

// Route or segment by setting a conversation label
window.$chatwoot.setLabel("vip");

// Switch locale at runtime (e.g. when the user changes site language)
window.$chatwoot.setLocale("he");

That setCustomAttributes call is the underrated one: whatever you pass shows up next to the conversation for the agent, so support sees the customer's plan, account age, or cart value without asking. On a closed platform you'd be limited to whatever attributes the vendor supports; here it's just key-value data you define.

Where self-hosting changes the game: the widget strings and the launcher icon are part of the source. On the installs I run, the default widget copy assumed a team ("we're online"), but the business is a solo operator — so the right phrasing was singular ("I'm online"). On Cloud you'd file a feature request and wait. On self-hosted I patched the locale file and swapped the launcher SVG with an idempotent script that re-applies automatically on every container start, so it survives version upgrades with zero manual steps. That's the difference between configuring and owning.

2. White-Label / Rebranding

This is the cleanest example of "self-hosted only." Chatwoot exposes branding through environment variables:

# Replaces the product name across the dashboard and system emails
INSTALLATION_NAME="Acme Support"

# Brand name + URL used in branding references
BRAND_NAME="Acme"
BRAND_URL="https://acme.example.com"

Set those, restart, and the dashboard, the page titles, and the transactional emails reflect your brand instead of Chatwoot's. For an agency reselling support-as-a-service, or a company that simply doesn't want a third-party product name in front of staff and customers, this matters. Combined with a custom domain and the widget tweaks above, a client never has to know which open-source project is underneath.

To be precise about the boundary: full rebranding is a self-hosted capability. Chatwoot Cloud keeps its own branding — which is fair, it's their hosted product. If white-label is a hard requirement, that requirement alone decides self-hosted for you.

3. Application API vs Platform API

This distinction trips people up, so it's worth getting right because it determines what you can automate.

The Application API (you'll also see it called the Client/Agent API) is authenticated with a user access token and operates inside a single account. It's the workhorse for integrations — listing and creating conversations, sending messages, managing contacts, applying labels, reading reports. Example: posting an outgoing message into a conversation:

curl -X POST \
  "https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages" \
  -H "api_access_token: USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Thanks for reaching out — an agent will be with you shortly.",
    "message_type": "outgoing"
  }'

The Platform API sits a level above accounts. It's authenticated with a Platform App access token and is used to create and manage accounts, users, and agent bots across the whole installation. This is what you reach for when you're provisioning tenants — for example, spinning up a fresh account for every new client and creating their first admin user programmatically:

curl -X POST "https://app.chatwoot.com/platform/api/v1/accounts" \
  -H "api_access_token: PLATFORM_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "New Client Workspace" }'

The mental model: Application API = act within an account; Platform API = manage the accounts themselves. Most day-to-day automation lives in the Application API. The Platform API is the multi-tenant / provisioning layer — and having it at all is part of why Chatwoot scales from "one inbox" to "a platform you run for many clients."

4. Webhooks and Automation

Webhooks are the integration backbone. Chatwoot can fire an HTTP POST on account events — conversation_created, message_created, conversation_status_changed, conversation_updated, and more — to any URL you register. That's the hook that lets external logic react to what's happening in the inbox.

The pattern I use constantly: Chatwoot → n8n → back into Chatwoot.

A message_created webhook hits an n8n webhook node.
n8n inspects the payload (sender, content, conversation, inbox), runs whatever logic the client needs — classify intent, look something up in a CRM, call an LLM.
n8n calls the Application API to post the reply, add a label, or update a contact attribute.

That loop is how you build an AI first-responder, a CRM sync, or a routing rule that's smarter than anything a settings page offers — without a vendor-specific "app." Because it's just webhooks and REST, the same approach connects Chatwoot to n8n, Make, your own backend, or all three.

Automation rules and macros (no code required)

Not everything needs a webhook. Chatwoot ships two built-in tools that cover a lot of ground:

Automation rules — event-driven if/then logic configured in the dashboard. On conversation creation you can auto-assign to a team, add a label, send a canned reply, or set an attribute based on conditions. No code.
Macros — a saved sequence of actions an agent runs with one click (e.g. "send the refund template, label it billing, resolve"). Great for repetitive multi-step handling.

The rule of thumb: use automation rules and macros for in-app workflow, and reach for webhooks + the API when you need external data or real logic.

5. Custom Integrations and Dashboard Apps

This is the feature that most surprises people coming from closed platforms. Chatwoot lets you embed your own web application inside the agent dashboard as a Dashboard App. You register a URL, and Chatwoot renders it in an iframe in a panel beside the conversation — and it passes the current conversation and contact context to your app via a postMessage event.

Concretely: your app listens for the context Chatwoot sends in.

// Inside your embedded dashboard app
window.addEventListener("message", function (event) {
  // Chatwoot posts the conversation + contact context here
  try {
    var data = JSON.parse(event.data);
    if (data.event === "appContext") {
      // data.data.conversation and data.data.contact are available
      renderCustomerPanel(data.data);
    }
  } catch (e) {
    /* ignore non-Chatwoot messages */
  }
});

Now your agents see your tooling — order history, a subscription manager, internal notes from another system — right next to the chat, without leaving Chatwoot. On a closed SaaS you'd be waiting for an official integration or a marketplace app. Here you build the panel you actually want and point Chatwoot at it.

6. Why Self-Hosted Unlocks What Cloud/SaaS Can't

Pulling the thread together — here's what specifically becomes possible once you own the deployment:

Direct database access. Chatwoot stores everything in PostgreSQL. For reporting beyond the built-in dashboards, you can query the database directly or pipe it into a BI tool. Closed SaaS exposes only what its export API allows.
Custom code and forks. It's open-source. If a behavior doesn't fit, you can change it and run your fork. The widget-string and launcher patches I described above are exactly this — small, surgical, and impossible on a hosted product.
No API rate limits. Self-hosted, the API is bounded by your server, not by a vendor's throttle. Heavy syncs and high-volume bots don't hit a per-plan ceiling.
Custom channels via the API channel. Beyond the built-in channels, Chatwoot's API channel lets you pipe messages from any source into a Chatwoot inbox and send replies back out — so a proprietary or niche messaging system becomes just another inbox.
Full white-label. As covered above — your brand, end to end.
Data residency and control. Every conversation lives on infrastructure you choose. For regulated industries or strict data-protection regimes, that's often non-negotiable.

None of this is a knock on hosted products. It's a description of a different trade: Cloud trades flexibility for zero maintenance; self-hosted trades maintenance for total control. Which one is "right" depends entirely on whether the customizations above are nice-to-haves or requirements for you.

The fork in the road: Cloud or self-hosted?

Both are legitimate. Pick by what you're optimizing for:

You want it managed, with zero maintenance → Chatwoot Cloud is the pragmatic choice — the vendor handles updates, backups, and uptime, and you still get the API, webhooks, and automation rules. Readers here get 5% off Chatwoot Cloud: chatwoot.com (5% off), coupon ACHIYADEV. > Affiliate disclosure: that's an affiliate link — if you subscribe through it, I may earn a commission at no extra cost to you (the coupon gives you 5% off either way). I recommend Chatwoot because I run it in production, not because of the link.
You need the customizations in this article — white-label, custom code, dashboard apps, direct DB access, no rate limits → that's self-hosted, and it's exactly what I set up and manage for clients. One-time setup, no recurring SaaS seat fees.

A Realistic Word of Caution

Customization is a capability, not a to-do list. The most common mistake I see is treating "we can change everything" as "we should change everything." Every fork you maintain is a thing you have to re-test on upgrade; every webhook is a thing that can fail at 2 a.m. The discipline that makes self-hosted Chatwoot pay off is restraint: start with the dashboard settings, use automation rules and macros before you write code, keep custom patches small and idempotent, and only reach for a fork when configuration genuinely can't get you there. Done that way, customization is an asset. Done carelessly, it's a maintenance bill.

I'm Achiya Cohen, founder of Achiya Automation. I build WhatsApp bots and business automation, and I run self-hosted, customized Chatwoot in production for clients. If you want open-source customer support tailored to how your business actually works — get in touch. And if managed Cloud fits you better, start here for 5% off with code ACHIYADEV (affiliate link).

My README said 80 tools. My code had 96. Nobody noticed for weeks.

אחיה כהן — Mon, 22 Jun 2026 06:24:41 +0000

I run an open-source MCP server. It exposes browser-automation tools to AI coding agents — click this, read that page, fill this form. The README has a big proud table: "80 tools." It's in the tagline. It's in the nav anchor. It's in the alt text of the social-preview image. It's in two comparison tables. It's even in the pre-written tweet text for the share button.

Eighty. Eighty everywhere.

Last week I ran a boring audit — just diffing what the README claims against what the code actually registers at startup. The code registered 96.

Not 80. Ninety-six. The number had been wrong in nine different places, and I'd been the one typing it each time.

How a number rots

Nobody decides to lie in their README. Drift happens one merge at a time.

You ship a feature. It adds three tools. You update the tool list (because that's the part reviewers look at) but you forget the count in the tagline. Next release adds four more. Now the list says one thing and the tagline says another, and both are behind reality. A month of "small, fast" releases later, the gap is sixteen.

The worst part wasn't even the tagline. When I actually counted the entries in the tool list itself, it documented 83 tools. So I had three different truths living in one file:

The marketing number: 80
The documented list: 83
The code: 96

Thirteen tools existed, worked, shipped to npm, and ran on real users' machines — completely undocumented. They weren't in the README at all. If you only read my docs, you didn't know they existed.

The tools you forget are the ones that matter

Here's the part that turned a docs cleanup into a genuinely uncomfortable afternoon.

I expected the undocumented thirteen to be boring helpers — the safari_wait_for_new_tabs of the world. Some were. But four of them were the native input tools: synthetic keyboard and mouse events driven through the OS-level event API (CGEvent), not through JavaScript injected into the page.

Those are the most powerful tools in the whole project. JavaScript-level automation is sandboxed by the page; OS-level input is not. It types into anything that has focus. It's the difference between "fill this <input>" and "press these physical-looking keys at the system level." It's exactly the category a security-conscious user would want to read about before granting Accessibility permissions.

And it was the category I'd never written down.

That's the real lesson, and it's not "keep your docs updated." It's this: documentation drift is selection-biased toward the things you'd least want undocumented. The tools you forget to document are the ones added in a hurry, in a feature branch, under a deadline — which correlates almost perfectly with the tools that are powerful, sharp, or security-relevant. The mundane stuff gets documented because it's easy. The dangerous stuff gets a TODO.

If you want to find the riskiest, least-reviewed surface of any project, don't read the docs. Read the gap between the docs and the code.

"Just update the README" is the wrong fix

The tempting fix is to fix the number. Change 80 → 96, add the thirteen missing entries, commit, done. I did that part. But it's treating the symptom.

The number was wrong because it was hand-maintained. Any fact a human types by hand will eventually disagree with reality. The only durable fix is to make the fact impossible to get wrong — derive it from the source of truth instead of restating it.

The irony: my project already had this solved, in one place. The smoke test — contributed by someone else, not me — boots the server over a real stdio transport, asks it how many tools it registered, and asserts against a count derived from the source. No hardcoded number. When you add a tool, the test's expectation moves with it automatically. That test could never have drifted to 80, because it never stored an 80 to drift from.

So the fix isn't "be more disciplined about the README." Discipline is what failed for a month straight. The fix is:

Counts → generate them. A tiny script that reads the registrations and writes the number into the README at build time. The human never types it.
Tool lists → generate them too, ideally from the same registry the server reads at startup. The schema is already structured data. Rendering it as a Markdown table is a formatting problem, not a writing problem.
The prose around them → that's the part humans should actually spend their attention on, because it's the part a generator can't write.

Every fact in your docs is either derivable or it isn't. Derivable facts should never be typed by hand. They are drift waiting to happen.

The check that takes thirty seconds

If you maintain anything with a "we have N features / N tools / N integrations" claim, here's the audit. It took me one command:

Count the real thing in code (registrations, exported functions, route handlers — whatever your N actually counts).
Count what your README claims.
If they disagree, you don't just have a stale number. You have a list of things that exist and that nobody chose to write down. Go read that list. It's the most interesting list in your repo.

I found mine had grown to a sixteen-tool gap, with the project's sharpest tools sitting inside it. Yours might be smaller. But "we never check" and "the number is correct" are not the same state, and the only way to tell them apart is to look.

This is from maintaining Safari MCP, an open-source Safari automation server for AI agents on macOS (the one that now correctly says 96). I write up the unglamorous parts of running a small OSS project at achiya-automation.com.

What's the widest doc-vs-code gap you've ever found in your own project — and was the stuff in the gap boring, or was it the scary stuff?

A rival to my open-source tool shipped. I read all of it — then ported its 4 best ideas the same afternoon.

אחיה כהן — Thu, 18 Jun 2026 16:40:24 +0000

A new MCP server showed up in the official Model Context Protocol registry last week, three slots above mine: safari-devtools-mcp. Same platform (macOS), same browser (Safari), same audience (AI coding agents). My first reaction was the honest one — a small jolt of oh no. My second reaction was more useful: I cloned it and read the entire thing.

I maintain Safari MCP — a browser-automation server that drives your real, logged-in Safari through AppleScript and a native extension. No Chromium, no headless, no second browser melting your fan. So a competitor called "Safari DevTools MCP" is squarely in my lane.

Here's what I found, what I deliberately didn't copy, and the four tools I shipped into my own server before dinner.

The architectural fork in the road

The very first line of its package.json told me most of the story:

"dependencies": {
  "selenium-webdriver": "...",
  "@modelcontextprotocol/sdk": "...",
  "zod": "..."
}

It drives Safari through safaridriver — Apple's official WebDriver. That's a legitimate, well-supported choice. But it's the exact choice my project exists to avoid. A WebDriver session launches a clean, isolated automation instance of Safari: no cookies, no logins, no sessions, a "Safari is controlled by automation" banner across the top. It's the headless-browser problem wearing a Safari costume.

Safari MCP does the opposite: it talks to the Safari you already have open, with all your auth intact, and never steals your foreground.

So I wasn't going to rip out my engine. Architecture is a position, not a feature. Copying it would erase the entire reason my tool exists.

But tools are a different question.

Diffing 48 tools against my 91

I dumped both tool lists and diff'd them. ~44 of its 48 tools mapped cleanly onto something I already had — click, fill, screenshot, get_cookies, network capture, the usual surface area.

Then there was a cluster of four that I had nothing equivalent to:

inspect_viewport_meta
get_safe_area_insets
check_ios_web_app_readiness
check_webkit_compatibility

This is a genuinely smart niche: iOS-Safari web-dev validation. The stuff every mobile web developer fights with — the notch, the viewport meta tag, "why won't my PWA add to the home screen," and Safari's long tail of CSS quirks. My server could automate Safari all day but couldn't answer any of those questions.

And here's the part that made it a no-brainer: all four are pure JavaScript inspection. No WebDriver capability, no protocol magic — just document.querySelector, getComputedStyle, and CSS.supports() run inside the page. Which means they port directly onto my AppleScript do JavaScript engine. The competitor's architecture wasn't portable. Its best ideas were.

The one I like most: compatibility checking with zero false positives

Most "is this CSS supported in Safari?" tools work off a static database (think caniuse). They go stale, and they can't see your actual Safari version.

check_webkit_compatibility does something better. It walks every stylesheet on the page, pulls each property: value pair via the structured CSSOM (no regex — so custom properties don't create false positives), and then asks the live browser the only question that matters:

CSS.supports(property, value)  // tested in THIS Safari, right now

If it fails unprefixed, it retries with -webkit-. If that works, it tells you to add the prefix. If neither works, it's genuinely unsupported here. Then it layers on a tiny hand-curated list of behavioral quirks CSS.supports() can't catch — like the classic:

position: sticky silently fails inside an overflow: hidden/auto ancestor. Use overflow: clip instead.

I reimplemented it as a synchronous IIFE returning JSON (my engine can't await inside do JavaScript — a [object Promise] lesson I've written about before), wired it into a safari_webkit_compat tool, and tested it against a live page with a deliberately sticky header:

{ "totalProperties": 6, "ok": false,
  "quirks": ["position:sticky silently fails inside an overflow:hidden/auto ancestor…"] }

Caught it. The other three — safari_inspect_viewport, safari_safe_area_insets, safari_check_pwa — went in the same way, each verified against a controlled DOM in real Safari before I trusted it.

What I took, and what competition is actually for

I ported four ideas. I rewrote every line to fit my engine and my conventions, credited the inspiration, and skipped the parts that conflicted with what my project is. That feels like the honest version of "competition makes everything better" — not a press-release platitude, but a real afternoon of reading someone else's careful work and being better for it.

A rival didn't make my tool worse. It handed me a roadmap for a category — iOS web-dev validation — I hadn't even thought to cover.

If you're building on macOS and want an agent that drives your actual Safari (logged in, no headless), it's one line: npx safari-mcp. The four new validators shipped in v2.14.0 (out now). More at achiya-automation.com.

Question for the room: when a competitor ships, do you read their code? I used to skip it out of some weird pride. I don't anymore. Where do you land — study it closely, or deliberately look away to protect your own taste?

Make.com has an MCP endpoint now. The auth token goes in the URL — and 3 other walls the docs skip

אחיה כהן — Sun, 14 Jun 2026 16:26:58 +0000

I already let my AI agent read and repair my self-hosted n8n workflows. So when a client's Make.com scenario started misfiring — duplicate WhatsApp order notifications, fired in bursts — my first instinct wasn't to log into the web UI. It was: can I give the agent the same remote access to Make that it has to n8n?

Make.com shipped both a REST API and an MCP endpoint. So yes. But getting from "they have an API" to "my agent is connected and patching a live scenario blueprint" meant walking into four undocumented walls. Here they are, in the order they hit me.

Wall 1: The API is behind Cloudflare, and it hates your User-Agent

My first call was a throwaway Python script — urllib.request to GET /api/v2/users/me. It came back 403.

Not 401 (bad auth). 403. The token was fine. The request never reached Make's application layer — Cloudflare's WAF bounced it on the User-Agent. The default Python-urllib/3.x UA is on a block list.

The fix is unglamorous: use curl (whose UA sails through) and pipe the body into Python only for parsing.

T=$(security find-generic-password -s make-api-token -a "$USER" -w)
curl -s -H "Authorization: Token $T" \
  "https://eu2.make.com/api/v2/users/me" | python3 -m json.tool

Two things worth noting even in this tiny snippet:

Auth is Authorization: Token <token> — not Bearer. (Hold that thought; it comes back.)
The token never gets typed or echoed. It lives in the macOS Keychain and is read at call time. Secrets in shell history are secrets you've already leaked.

Wall 2: Listing scenarios needs a teamId, not an organizationId

The object hierarchy is Organization → Team → Scenario. Natural assumption: list scenarios by the org you're in.

GET /api/v2/scenarios?organizationId=<org>   → not what you want
GET /api/v2/scenarios?teamId=<team>          → ✅

/scenarios is scoped to a team, not an organization. So the real discovery sequence is:

GET /organizations
GET /teams?organizationId=<org>
GET /scenarios?teamId=<team>

Skip the middle call and you'll spend ten minutes convinced your token lacks scope, when it's just keyed on the wrong ID.

Wall 3: The blueprint JSON won't parse — and it's not your code

The whole point was to fix the scenario, and on Make the editable definition is the blueprint:

GET   /api/v2/scenarios/{id}/blueprint     # read it
PATCH /api/v2/scenarios/{id}               # write it back, blueprint as a JSON string

I pulled the blueprint, piped it through jq, and got a parse error. The JSON was, by the spec, invalid.

The cause: the scenario sends Hebrew WhatsApp messages, and the message templates contain raw, unescaped newline characters inside string values. Strict JSON forbids literal control characters in strings; Make emits them anyway.

jq refuses. So does Python's default json.loads. The escape hatch is one keyword:

import json, sys
blueprint = json.loads(sys.stdin.read(), strict=False)  # tolerate raw control chars

strict=False tells the parser to accept the control characters instead of throwing. Once it's a Python object you can edit the module you care about, re-serialize, and PATCH it back as a string.

Wall 4: The MCP endpoint 404s on a Bearer header

This was the one that cost me the most time, because everything looked right.

Make exposes an MCP server. I added it to my agent the way I add every other remote MCP — URL plus an Authorization: Bearer header. 404. Not 401. 404, as if the endpoint didn't exist.

It doesn't — not at the path I was using. The Make MCP doesn't authenticate via header at all. The token goes in the URL path:

https://eu2.make.com/mcp/u/<token>/stateless

Header auth on /mcp: 404. Token baked into the path on /mcp/u/<token>/stateless: 200, connected.

That's an awkward shape if you care about not pasting secrets into config files — a URL with a live token in it is exactly the kind of string that ends up committed. The way out is to assemble the URL at launch time from the Keychain, so the token is never written to disk:

// MCP server entry
{
  "command": "bash",
  "args": [
    "-c",
    "exec mcp-remote \"https://eu2.make.com/mcp/u/$(security find-generic-password -s make-api-token -a $USER -w)/stateless\""
  ]
}

mcp-remote bridges the streamable HTTP endpoint to a local stdio MCP server. The $(...) runs every launch, so the config on disk contains a Keychain lookup, never the token itself. Same pattern I use for other path-token services.

The payoff

Four walls — a WAF User-Agent block, a team-vs-org ID, control characters in "valid" JSON, and path-based MCP auth — and on the other side the agent can do, remotely and unattended, what used to mean opening the Make UI and clicking through a scenario by hand: list orgs and teams, pull a misbehaving scenario's blueprint, diff it, and PATCH the fix.

None of these are in the quickstart. All four are the difference between "they have an API" and "it actually works." If you're wiring an AI agent into Make.com, start with curl (not your HTTP library), scope /scenarios by team, parse blueprints with strict=False, and put the MCP token in the path.

I build WhatsApp bots and business automation for companies — self-hosted n8n, Make.com, WAHA, the works. More war stories and guides at Achiya Automation.

My safety guard protected 2 tools and trusted the other 20

אחיה כהן — Sun, 14 Jun 2026 15:36:54 +0000

I maintain an MCP server that lets a coding agent drive your real, logged-in Safari — the same browser where your bank, your email, and your half-written Slack messages live. The whole premise only works if there's one ironclad rule:

The agent may only touch tabs it opened. Never yours.

I wrote that guard early. It was a small function: before any page-mutating action, check that the target tab is one the agent owns. I dropped it into the wrapper that safari_click and safari_fill both flow through, watched the two of them refuse to act on an unowned tab, and moved on feeling responsible.

It took three separate audits to discover that the guard was, for most of its life, decorative.

Round 1: the guard was in a place almost nothing went through

The wrapper I'd guarded — call it extensionOrFallback — was the path for click and fill. It was not the path for the other twenty-ish tools that mutate a page.

safari_set_cookie. safari_delete_cookies. Every local-storage and session-storage writer. safari_import_storage. safari_drag. safari_upload_file. safari_paste_image. safari_select_option. safari_mock_route. safari_throttle_network. safari_override_geolocation. safari_handle_dialog. safari_resize.

Every one of them called the engine directly. None of them touched the wrapper. So the ownership check — the entire safety story of the project — applied to two tools and was silently absent from the rest. An agent that got confused about which tab was in front could write a cookie or dump localStorage into your logged-in session, and nothing would stop it.

The fix was conceptually trivial (extract the check into _assertTabOwnership() and call it first in all of them) and that triviality is exactly the point. A guard living in one convenient wrapper is not a guard. It's a guard-shaped object that happens to sit on the two code paths you tested. The real invariant is "every path that mutates a page calls the check," and a wrapper can only ever promise that for the paths that go through the wrapper.

Round 2: the batch tool had an escape hatch

safari_run_script runs a batch of steps — navigate, click, fill, evaluate — in one call. It did check ownership… once, pre-flight, before the batch started.

A single pre-flight check on a batch that can move between tabs is not a check. Two holes:

evaluate was exempt. You could run arbitrary JavaScript in an unowned tab simply by wrapping it in a batch instead of calling it standalone.
A switchTab or navigate step mid-batch could walk onto your tab, and the next step — a click, say — would land there, because the only gate was at the door, not on each step.

Now ownership is enforced per step while the batch runs. A navigate step registers ownership of its destination exactly like the standalone tool does, and any refused step aborts the whole batch instead of letting the rest proceed on freshly-stolen ground.

The lesson rhymes with Round 1: I'd put the check at the start of the operation when the dangerous thing was the transition between steps. Guards belong on the state change, not on the entrance.

Round 3: the state itself was lying

The third audit was the unsettling one, because the guard was now called everywhere — and could still be wrong, because the data it consulted was rotten in three different ways.

/org owned /org-evil. Ownership was matched with a path-prefix test and no segment boundary. If the agent legitimately owned https://site.com/org, my matcher cheerfully concluded it also owned https://site.com/org-evil on the same origin. A string prefix is not a security boundary; I had quietly treated it as one. Matching now requires a real / boundary, and — because this is precisely the kind of rule that rots silently — I pulled the whole matching/TTL semantics out into a pure ownership-match.js module with a unit suite that locks the /org vs /org-evil case in place forever.

The TTL leaked ownership across sessions. Every time the ownership file was saved, it rewrote each entry's timestamp to now. The 30-minute expiry could therefore never fire on a long-lived session — owned URLs accumulated indefinitely, potentially carrying a stale claim onto a tab that was now yours. Original timestamps are preserved now, and expiry is enforced on use, not just at load.

A worker restart failed open. The browser extension is MV3, so its service worker is killed and restarted at the platform's whim. When it restarted, the in-memory map of owned tabs was wiped — and the code interpreted "no tabs owned yet" as the startup compatibility path, which is permissive by design. So a routine worker restart silently disabled the guard entirely until the next new_tab. The owned-tab state now survives restarts in storage.session. State that resets must fail closed. Mine had been failing open, in the one direction that mattered.

What I actually changed about how I work

The code fixes are in the changelog. The habits are the takeaway:

Guard the chokepoint, or guard every call site — never the convenient wrapper. If you can't put the check on a single line every path provably crosses, you have to put it on every path. There's no third option that's safe.
"Owns" is a security boundary; startsWith is not. Any time a string comparison stands in for an authorization decision, assume it's wrong at the boundary and write the test that proves it.
Decide what your state does when it resets. Caches get cleared, workers get killed, files get reloaded. The only question is whether that reset opens the gate or closes it. Pick on purpose.
Extract the security-relevant logic into something a test can pin. The matching rules lived inline, tangled with I/O, untestable — which is why the boundary bug survived. Pure module + unit suite turned an invisible invariant into a red build.

None of these are clever. They're the boring discipline that the exciting "give your AI agent a real browser" headline quietly depends on. The guard isn't the feature. The guard is what lets the feature be allowed to exist.

Safari MCP is open source (MIT) — a Safari automation server for AI coding agents on macOS: native WebKit, your real logins, no Chrome, no headless. The full three-pass hardening shipped in v2.13.0; the blow-by-blow is in the changelog. Repo: github.com/achiya-automation/safari-mcp. I build automation like this at achiya-automation.com.

Have you found one of these in your own code — a guard on the wrapper, a prefix standing in for a boundary, state that fails open on restart? I'd genuinely like to hear which of the three bit you.

Your branch protection is quietly turning away first-time contributors

אחיה כהן — Mon, 08 Jun 2026 09:24:40 +0000

Ten weeks ago I did the thing every "grow your open source project" guide tells you to do. I carved a few small, self-contained tasks out of my backlog, labeled them good first issue, wrote crisp descriptions, and waited for contributors to roll in.

They didn't roll in. The issues just sat there.

This morning, one of them finally got picked up. A first-time contributor opened a clean PR against my MCP server: a smoke-test suite, no new dependencies, green across the whole Node CI matrix. Exactly the contribution the label was advertising for.

And then my own repository spent the next twenty minutes trying to stop it from getting merged.

Not with anything dramatic. With three quiet, individually-reasonable "best practice" gates that, stacked together, form a gauntlet aimed squarely at the one person you spent ten weeks trying to attract. I want to walk through each gate, because almost everything written about contributors is about attracting them, and almost nothing is about the last hundred feet — the silent friction between a willing PR and a merged commit.

The advice is only half the story

"Add good first issues and contributors will come" is true in the same way "build it and they will come" is true: technically, eventually, for a small subset, with survivorship bias baked in. My good first issue opened on March 31. The PR that closed it merged on June 8. That's sixty-nine days of a clearly-labeled, beginner-friendly task sitting untouched.

I'm not complaining about the wait — that part is normal. I'm pointing out that the advice stops exactly where the interesting problem starts. Because the bottleneck was never finding someone willing. When someone willing finally showed up, the friction was entirely on my side of the fence.

Gate 1: the CI that silently refuses to run

GitHub Actions does not run workflows on pull requests from first-time contributors until a maintainer approves the run. This is a sane anti-abuse measure — fork PRs can run arbitrary code in your CI — and I'd keep it on. But look at it from the contributor's seat.

They open a careful PR. They watch the checks section. And nothing happens. No green check. No red X. No "running." Just a quiet:

no checks reported on the 'codex/add-smoke-tests-for-mcp-tools' branch

From the maintainer's side it shows up as action_required:

27117992338  [completed/action_required]  pull_request  CI

To you it's a one-click "Approve and run." To them it is indistinguishable from "this maintainer doesn't care / this repo is dead / I did something wrong." There is no message telling them it's waiting on you. A motivated first-timer who doesn't know this is a normal GitHub behavior will quietly assume the worst and never come back. The gate didn't reject their code — it rejected their confidence.

Gate 2: `BLOCKED`, reason unspecified

Approved the run, watched it go green on Node 20, 22, and 24. Posted a review. Hit merge. Got:

Pull request is not mergeable: the base branch policy prohibits the merge.

So I checked the branch protection. The classic API was almost entirely empty:

{ "required_pull_request_reviews": null, "required_status_checks": null }

Reviews: not required. Status checks: not required. The PR itself reported mergeable: MERGEABLE, reviewDecision: APPROVED, every check SUCCESS — and mergeStateStatus: BLOCKED. Blocked by what? Nothing the obvious endpoint admitted to. I had to pull the full protection object to find the real culprits:

{
  "required_signatures":               { "enabled": true },
  "required_conversation_resolution":  { "enabled": true },
  "enforce_admins":                    { "enabled": false }
}

Here's the thing: I set those, and even I had to dig to remember they were on and reconcile them against a half-empty API response. A first-time contributor staring at "the base branch policy prohibits the merge" has zero ability to diagnose this. It's not their branch, not their settings, not their problem to solve — and yet it's their PR sitting in limbo.

Gate 3: the unsigned fork commit

required_signatures was the actual wall. My main requires verified commit signatures. A commit authored on someone else's fork is, naturally, not signed with anything my branch trusts. The escape hatch turned out to be the squash merge: when GitHub creates the squash commit server-side, it signs it with its own web-flow key, so the resulting commit on main is verified:

a4b29a054  verified=true  | test: add smoke tests for registered MCP tools (#35)

It worked. But notice the shape of the solution: the contributor's commit was never going to satisfy the rule, and the only reason it merged is a side effect of how GitHub squashes. That's not a policy a contributor can reason about. It's tribal maintainer knowledge.

None of these are bugs. That's the problem.

Every gate here is defensible in isolation. Approval-gating fork CI prevents crypto-miners in your Actions minutes. Required signatures raise the bar on supply-chain tampering. Conversation resolution stops half-finished reviews from merging. I'm not telling you to turn them off.

I'm telling you that nobody adds them together on purpose, with the contributor experience in mind. They accrete. You enable one after a scare, another because a security checklist said so, a third because it was the default in a template. And the cumulative effect is an invisible obstacle course that your most valuable, least-experienced contributor runs blind — with no signposts, while you're not looking.

The "growth" content optimizes the funnel right up to the PR and then goes silent. The actual leak is after the PR.

What I'm changing

Document the approval gate. One line in CONTRIBUTING.md: "Your first PR's CI won't run until I approve it — that's a GitHub default, not you. Ping me if it sits." That single sentence converts "this repo is dead" into "ah, normal."
Watch the Actions tab, not just the PR list. action_required runs don't page you. If you're seeding good first issues, you've explicitly invited PRs from people whose CI will always start out gated. Treat that queue as a first-class inbox.
Re-audit protection rules as a set, from the contributor's chair. Pull the full protection object, not the two-field summary. Ask of each rule: "if a stranger's clean PR hits this, will they understand what happened?" If the answer is no, at minimum it needs documentation.
Reply fast and warm on the first one. The first external PR is a confidence transaction as much as a code transaction. I approved CI, left a specific review calling out what was good, and merged inside the hour. That contributor is far more likely to send a second one.

The smoke suite, by the way, is genuinely nice work: it boots the server over the real stdio transport — the same path actual MCP clients use — and asserts that all 91 registered tools show up with unique safari_* names and valid schemas. It derives the expected count from the source instead of hardcoding it, so it stays honest as the tool surface grows. It runs on safari-mcp, a browser-automation MCP server for Safari on macOS, if you want to see the shape of it.

Maintainers: how do you handle the first-time-contributor CI gate — pre-approve, automate it with a workflow, or just keep the Actions tab open? I'd genuinely like to steal a better answer than "watch it like a hawk."

DEV Community: אחיה כהן

One command adds import, WhatsApp drip and campaigns to self-hosted Chatwoot

One command, same-origin, no second server

What it adds

The part I'm most proud of: least-privilege by design

Fully bilingual, automatically

Try it

Exactly-Once by Default: How Durable Execution Changed the Way I Build Automations

The problem: a crash in the middle

The usual fix, and why it hurts

How DBOS makes it the default

The one rule to internalize

What this replaced

A note on how I built it

I Deleted My No-Code Automation Platform and Rewrote 34 Workflows in TypeScript

What "code-first" actually changed

The numbers

The honest part (because I hate hype)

How one person did all this

The takeaway

Apple shipped an official Safari MCP. I read all 17 tools. Here's why I'm keeping mine.

First, credit where it's due

The one sentence

Why mine exists at all

So am I changing anything? Yes. Three things, none of them "switch."

The takeaway

My MCP server had 32 green tests. Not one of them had ever called a tool.

What the tests actually tested

The boundary nobody was watching

Why "green and wrong" is worse than red

The fix: make the boundary fail loudly

The rule I'd give past-me

My tool said "clicked." Safari never saw it. macOS 26 quietly broke a system API.

The most expensive kind of bug: the one that succeeds

What actually changed

The fix wasn't a permission. It was a fact.

The lesson I keep relearning

How Far You Can Actually Customize Chatwoot (Self-Hosted)

TL;DR

1. Widget Customization

2. White-Label / Rebranding

3. Application API vs Platform API

4. Webhooks and Automation

Automation rules and macros (no code required)

5. Custom Integrations and Dashboard Apps

6. Why Self-Hosted Unlocks What Cloud/SaaS Can't

The fork in the road: Cloud or self-hosted?

A Realistic Word of Caution

My README said 80 tools. My code had 96. Nobody noticed for weeks.

How a number rots

The tools you forget are the ones that matter

"Just update the README" is the wrong fix

The check that takes thirty seconds

A rival to my open-source tool shipped. I read all of it — then ported its 4 best ideas the same afternoon.

The architectural fork in the road

Diffing 48 tools against my 91

The one I like most: compatibility checking with zero false positives

What I took, and what competition is actually for

Make.com has an MCP endpoint now. The auth token goes in the URL — and 3 other walls the docs skip

Wall 1: The API is behind Cloudflare, and it hates your User-Agent

Wall 2: Listing scenarios needs a teamId, not an organizationId

Wall 3: The blueprint JSON won't parse — and it's not your code

Wall 4: The MCP endpoint 404s on a Bearer header

The payoff

My safety guard protected 2 tools and trusted the other 20

Round 1: the guard was in a place almost nothing went through

Round 2: the batch tool had an escape hatch

Round 3: the state itself was lying

What I actually changed about how I work

Your branch protection is quietly turning away first-time contributors

The advice is only half the story

Gate 1: the CI that silently refuses to run

Gate 2: BLOCKED, reason unspecified

Gate 3: the unsigned fork commit

None of these are bugs. That's the problem.

What I'm changing

Gate 2: `BLOCKED`, reason unspecified