This post is in Dutch — a first for this blog. It covers a topic specific to the Netherlands: I built an open-source tool that maps all 20,277 inaccessible bus stops in the country and lets citizens email the responsible authority with a legally grounded request for improvements. Apologies to my English-speaking readers; normal service will resume next post.

Vandaag publiceerde de NOS dat voor veel mensen als een verrassing kwam: ongeveer de helft van de Nederlandse bushaltes is niet of nauwelijks toegankelijk voor mensen met een beperking. Zes op de tien haltes missen goede voorzieningen voor blinden en slechtzienden. Bijna de helft is slecht ingericht voor rolstoelgebruikers. In sommige gemeenten ligt het percentage ontoegankelijke haltes boven de 90%.

Afgelopen jaren ben ik intensief bezig geweest met toegankelijkheid, onder andere als developer van de Beter Bereikbaar Applicatie - BBA, en dit bevestigt alle verhalen die ik hoorde. De data is openbaar beschikbaar, maar dat meer dan de helft van de bushaltes in Nederland slecht bereikbaar zijn is hoger dan ik zelf had verwacht. Dus heb ik de mooie kaarten bekeken, en toen dacht ik: wat nu? De gemiddelde persoon zal het getalletje zien, en of zijn schouders ophalen of het voor kennis geving aannemen. Wat moet je er immers mee? Dus toen dacht ik: wat kan ik er mee? Zou het niet mooi zijn als je een kaart zou hebben waar je deze data op ziet en die je in staat stelt om dit onder de aandacht te brengen bij de desbetreffende instantie (vaak een gemeente, soms een provincie en heel soms een waterschap) Dus bouwde ik er iets voor.

De onzichtbare data

Het Centraal Haltebestand — beheerd door DOVA, het samenwerkingsverband van OV-autoriteiten — bevat gedetailleerde informatie over elke bushalte in Nederland. Van elke halte is bekend hoe hoog de stoeprand is, hoe breed het perron, of er geleidelijnen liggen, of de halte obstakels heeft. Al die data is openbaar.

Maar “openbaar” is niet hetzelfde als “zichtbaar”. De data zit in de Halteviewer, een tool voor professionals. Je moet weten dat die bestaat, je moet weten hoe je erin zoekt. Voor een gemeenteraadslid of burger die willen weten hoeveel haltes in hun gemeente niet op orde zijn, is dat een doodlopende weg.

20.277 haltes die niet voldoen

Ik schreef een datapipeline die alle haltedata ophaalt en toetst aan de CROW-normen voor toegankelijkheid. Een halte voldoet niet als de stoeprand lager is dan 18 centimeter, het perron smaller dan 1,50 meter, er geen geleidelijnen liggen, of er geen obstakelvrije looproute is.

De cijfers:

Die 384 wegbeheerders — dat zijn 345 gemeenten, 12 provincies, 5 waterschappen, 7 kantoren van Rijkswaterstaat, en nog een handvol private partijen. Allemaal afzonderlijk verantwoordelijk voor hun eigen haltes.

De wegbeheerders met de meeste ontoegankelijke haltes:

• Rotterdam: 416
• Provincie Overijssel: 397
• Amsterdam: 393
• Provincie Gelderland: 367
• Provincie Drenthe: 268

De tool: Toegankelijke Bushaltes

Niet met de bus? is een interactieve kaart die alle 20.277 ontoegankelijke haltes toont, gegroepeerd per wegbeheerder. In de zijbalk klik je op je gemeente (of provincie, waterschap, etc.) en je ziet direct welke haltes niet voldoen. Je kunt inzoomen, haltes aanklikken, en zien welke haltes niet voldoen aan de eisen. En het belangrijkste: je kunt met één klik een e-mail genereren naar de verantwoordelijke wegbeheerder.

De e-mail: goed onderbouwd, klaar om te versturen

De gegenereerde e-mail is geen vaag verzoekje. Hij bevat:

• Het exacte aantal ontoegankelijke haltes van die wegbeheerder
• Een verwijzing naar het VN-verdrag inzake de rechten van personen met een handicap (artikelen 9 en 20) — dat Nederland in 2016 heeft geratificeerd
• Een verwijzing naar de Wet gelijke behandeling op grond van handicap of chronische ziekte (Wgbh/cz, artikelen 2 en 3)
• Een verwijzing naar het Bestuursakkoord Toegankelijkheid OV 2022-2032 — waarin overheden zelf hebben afgesproken om alle haltes toegankelijk te maken

Je hoeft geen jurist te zijn. Je hoeft geen expert te zijn in OV-wetgeving. Je klikt, je past de mail aan naar hoe jij het wilt, en je verstuurt hem. Dat is het.

Waarom dit ertoe doet

Peter Waalboer, belangenbehartiger voor mensen met een beperking, zei het treffend in het NOS-artikel: “Het openbaar vervoer is een publieke voorziening. Die moet voor iedereen toegankelijk zijn — daar is geen discussie over mogelijk.”

Helemaal waar, maar de realiteit is weerbarstig: gemeenten hebben beperkte budgetten en bushaltes aanpassen kost geld — een enkele halte kan al duizenden euro’s kosten. Er bestaan subsidies van OV-autoriteiten, en het Bestuursakkoord zet ambities neer, maar naleving is vrijwillig. Zonder druk van inwoners verschuift “toegankelijkheid” makkelijk naar de onderkant van de prioriteitenlijst.

Wat er ontbreekt is niet wetgeving of goede bedoelingen — het is zichtbaarheid. Als een raadslid niet weet dat 60% van de haltes in haar gemeente niet voldoet, gaat ze er niet naar vragen. Als een dorpsgenoot niet weet dat zijn halte ongeschikt is voor zijn buurvrouw in een rolstoel, mist hij het signaal. Data die onzichtbaar is, leidt niet tot actie.

Deze tool maakt die data zichtbaar en actionable. In een paar klikken kun je zien wat er aan de hand is en de verantwoordelijke partij aanspreken — met een juridisch onderbouwd verzoek.

Open source, voor iedereen

De tool is volledig open source. De broncode staat op GitHub. Technisch is het bewust simpel gehouden: een datapipeline in Node.js die de DOVA- en Allmanak-data ophaalt, en een statische frontend met vanilla HTML, CSS en JavaScript — met een Leaflet-kaart en marker clustering. Geen frameworks en geen build-stappen. De data is verversbaar door de pipeline opnieuw te draaien.

De timing: gemeenteraadsverkiezingen op 18 maart

Op 18 maart 2026 zijn de gemeenteraadsverkiezingen. Dat maakt dit hét moment om actie te ondernemen. Kandidaat-raadsleden en zittende politici zijn nu extra ontvankelijk voor signalen van inwoners. Stuur die e-mail nu — vóór de verkiezingen. Vraag aan je lokale partijen wat zij gaan doen aan de ontoegankelijke haltes in jouw gemeente. Toegankelijkheid hoort in elk verkiezingsprogramma, niet als voetnoot maar als prioriteit.

Wat kun jij doen?

1. Ga naar nietmetdebus.nl en zoek je eigen gemeente op
2. Bekijk welke haltes niet voldoen — misschien is het die halte bij jou om de hoek
3. Genereer een e-mail en stuur die naar je wegbeheerder — liefst vóór 18 maart
4. Deel de tool met je gemeenteraad, je lokale belangenorganisatie, je buren
5. Stel het aan de orde bij verkiezingsdebatten en inspraakavonden in je gemeente
6. Heb je suggesties of wil je bijdragen? Open een issue op GitHub

Toegankelijkheid is geen gunst. Het is een recht. En soms begint verandering met een simpele e-mail.

There is a self-reinforcing cycle forming in frontend development, and it is making people nervous.

React has the most code in LLM training data. LLMs therefore generate better React code than anything else. More React code gets written — by both humans and AI — feeding future training data. Repeat. The flywheel spins, and React’s dominance compounds with every prompt.

The evidence is hard to miss: give an LLM a vague prompt like “build me a web app” and you will almost invariably get React + Tailwind + shadcn/ui. Tools like v0, Lovable, and Bolt.new all default to this stack. v0 technically supports Vue and Svelte, but by Vercel’s own admission it “really works best using React, Tailwind and shadcn/ui.”

The usual reaction to this is concern. It is called the problem with the default AI stack. Others warn about stifled innovation, outdated patterns being perpetuated at scale, and a knowledge barrier for newcomers who never discover alternatives because the AI never suggests them.

I see it differently.

The Fragmentation Problem Nobody Talks About

Frontend development has been drowning in choice for a long time. React, Next, Vue, Svelte, Solid, Angular, Qwik, Astro, Lit, Preact, Marko, Alpine, Htmx — and many more, and that is just frameworks. Each comes with its own ecosystem of state management libraries, routing solutions, meta-frameworks, and component libraries. Every combination produces a slightly different mental model, a different set of conventions, a different way to do the same thing.

This fragmentation has real costs. Teams spend weeks evaluating frameworks. Developers switching jobs need ramp-up time to learn the local flavour. Hiring becomes framework-specific. Knowledge sharing across projects is harder than it should be. The industry has been paying a quiet tax on all this optionality, and for what? For 95% of use cases, any of these frameworks would do the job just fine.

What AI is doing — accidentally, through the cold logic of training data statistics — is pushing the community toward standardisation. And standardisation, when the standard is good enough, is not a loss. It is a relief.

Good Enough Wins

React is not the best framework. I will say that plainly. If I had to write code by hand — really sit down and build components line by line — I would pick Svelte. It is cleaner, less verbose, and gives me a better overview of what is happening. The developer experience is genuinely superior when you are the one typing.

But I am not the one typing.

I wrote about this shift in my post on vibe coding, product quality and democratisation: the value equation has changed. When AI generates 80-90% of the code, my personal preference for a framework’s syntax becomes almost irrelevant. What matters is whether the AI can produce correct, functional code — and right now, it produces better React code than anything else. That is not ideology. It is a measurable quality gap rooted in training data volume.

React is not the best. But it is good enough for the vast majority of what gets built. And “good enough + excellent AI support” beats “technically superior + mediocre AI support” in every practical scenario I can think of.

I learned this first-hand when I was using a new Svelte version with GitHub Copilot — a long time ago it seems — when the training data had not included that version yet. Not a fun experience, having to reinstruct the LLM every time.

The Time Argument

Every hour I do not spend fighting an AI tool’s weaker output in a less-supported framework is an hour I can spend on what actually matters: the product, the user experience, the business logic, the security model.

The cost savings are real. When Lovable or Claude Code can scaffold a working application in half an hour using React, the overhead of choosing a different framework — debugging AI-generated code that is slightly off, filling in gaps where training data is thin, manually correcting patterns the model has not seen enough of — becomes a luxury most projects cannot justify.

This is the argument that makes the monoculture concerns less relevant for most teams: time saved is money saved. And time is the final currency.

When I Would Not Do This

I am not saying React is the answer to everything. There are clear cases where another approach is justified:

Security-critical applications. When a project demands the highest level of security assurance, I want to understand every line of code. AI-generated code — in any framework — adds a layer of uncertainty that might be unacceptable. In those cases, the framework choice should serve the security model, not the AI tooling.

Performance as a hard requirement. If a client needs the absolute smallest bundle size or the fastest possible rendering, Svelte or Solid or plain Javascript will outperform React. When performance is a specification, not a nice-to-have, the technical choice should win over the AI convenience.

Simplicity as a constraint. Some projects need to be small, understandable, and maintainable by non-specialists. A simple static site does not need React’s complexity. The right tool here might be vanilla Javascript, Alpine, or something deliberately minimal.

These are the 5% cases. They exist, they matter, and they require deliberate technical choices. But they are the exception, not the rule.

What About Innovation?

The strongest counterargument is that a React monoculture stifles innovation. If future LLMs are trained mostly on React, the reasoning goes, new frameworks will never gain enough traction to compete.

Here is how I see it: we have not actually seen real innovation in frontend frameworks for a long time. Frontend is complicated — genuinely, deeply complicated. And so far, none of the alternatives have found a definitive answer. They are variations. Svelte’s compile step, Solid’s fine-grained reactivity, Astro’s island architecture — these are smart ideas, well-built tools, and genuine improvements in specific areas. But they are also steps back in others. They are not the next paradigm shift. They are refinements.

Meanwhile, the industry runs on a multi-year cycle that keeps repackaging older ideas under new names. Server-side rendering is back. Signals — called observables in Knockout.js back in 2010 — are back. The pendulum swings, and we call it progress.

A lot of developers see their framework of choice as real innovation. I understand that attachment — I feel it with Svelte. But in the grander scheme, these are variations on the same fundamental approach to building UIs. If something truly new comes along — something that genuinely changes how we think about frontend development — it will break through regardless of what LLMs default to. That kind of innovation does not need training data momentum. It needs to be undeniably better.

Until that happens, we are better off accepting what we have and building with it.

The Accidental Standard

React did not plan this advantage. No committee decided it should be the AI default. It happened because React was the most popular framework when the training data was collected — a decade of documentation, tutorials, Stack Overflow answers, and open-source projects.

But planned or not, it gives developers a common language. It gives teams a safe default. It gives non-developers building their first app through vibe coding a foundation that actually works. And it gives the rest of us more time to spend on what we are actually building instead of debating what to build it with.

React apparently is not that bad.

Resources

• The Problem with the Default AI Stack — Maximilian Schwarzmüller
• GitHub Copilot vs ChatGPT vs Claude for Frontend Development — 200ok Solutions
• Best Vibe Coding Tools — TechRadar
• Is React Still the Best Choice in 2025? — The Alpha Spot
• Svelte 5 and the Future of Frameworks: A Chat with Rich Harris — Smashing Magazine
• DHH on AI, Vibe Coding, and the Future of Programming — The New Stack

Further Reading

• Vibe Coding: Product Quality and Democratisation — my earlier post on vibe coding and when personal tools become products
• Securing YOLO Mode: How I Stop Claude Code from Nuking My System — on guardrails for AI-assisted development

And combine that with increases in searches for “vibe coding”: a jump of 6,700% in 2025. By late 2025, 84% of developers were using or planning to use AI coding tools.

So that seems to be quite a threat for a lot of software businesses. Bad times are coming. Or are they? There are multiple facets to the story, let’s look at two of them: product quality and social implications.

Product Quality

Most of the vibe-coded applications I have seen are quite bad. A few weeks ago I tried to contribute to an open-source project that was clearly vibe-coded. It was a great idea, I started with enthusiasm, but ran away within an hour.

The code looked fine at first glance: clean-ish syntax, impressive number of files. But the moment I tried to understand what it actually did, I hit a wall. Fragile abstractions, bad architecture and bugs, so many small bugs.

Now I believe that bad code is not a problem per se, just as ‘good’ code is not a goal in and of itself, just for the sake of writing good code (however you want to define that). (The lack of a proper definition is what keeps me from pursuing good code among other things.) I am much more pragmatic: does the code solve a problem? Yes? Then it is good code; it fulfills its purpose. However, take into account that the purpose is not just to solve the problem then and there, but also in the future. And the cost it takes to maintain the solution for the problem has by definition to be lower than the (perceived) costs the problem causes. Costs can be money, time, assets, reputation, failing to comply etc. If the costs are low enough (and good software drives down the total cost, by reducing maintenance time etc) it is a good solution.

So the main reason to write good code is to drive down the cost of the solution to below the cost of the problem. That also means that good code is not a fixed outcome or definition, it depends on the situation. That also means that for personal use a badly coded vibed app can be perfect: who cares that it is bad? It solves my problem! (Good for you, power to the people etc.)

And that touches on what for me is one enormously important aspect: democratisation of software. No-code and low-code platforms took the first steps here, making it possible to build without writing code at all. Now AI-assisted coding takes it further: you can create actual software, not just what fits within a platform’s constraints. Suddenly you do not need a masters degree to do complicated things with your computer: you can do all sorts of stuff!

I really am wondering what this will mean in terms of social improvement, equality and human rights. The keys to writing software were always in the hands of white, middle-aged, rich men with a predisposition for details and light autism, who kept their trades securely guarded and often were and are not able to properly communicate with their customers. If that is no longer the case, what will happen?

Of course there is still a barrier: LLM costs. Right now, using these tools at scale costs real money, and that creates its own form of gatekeeping. But I expect this to come down significantly in the coming years through economies of scale, efficiency gains in model architectures, reduced energy consumption, and the rise of smaller models that perform nearly as well as the large ones.

But getting back to product quality: if writing the software is no longer the hard part (no more writing ‘print’ in javascript after working with python for weeks and making some changes in a javascript project), what will change?

The Bottleneck Shift

Something strange happens when you can generate code instantly: you lose the thinking time that was hidden in the coding process.

Before AI tools, writing code forced a pace. You’d sit with a problem for days, turning it over in your mind while your fingers typed. The friction of implementation gave you space to contemplate, to look at the problem from different angles, to notice that your initial understanding was wrong.

Now? You describe what you want and get code in seconds.

The bottleneck shifts: building becomes trivial, but understanding the problem correctly becomes the new hard part, and you have less time to figure it out.

Research on vibe coding calls this the “flow-debt tradeoff”: the speed you gain now, you pay back later in technical debt. The AI doesn’t maintain a unified architectural vision across prompts, nobody documents why the code is the way it is, and the problems only surface during maintenance and scaling. The productivity gains are real, but they’re borrowed time.

This is where personal use and business use diverge, because for your own tools “it works” is enough (who cares if it’s messy, it solves your problem), but the moment software becomes a product, something others depend on and that needs to work next year, the equation changes completely. Building was always only about 10% of the work anyway, while the other 90% (compliance, security, support, maintenance, edge cases) doesn’t go away just because building got easier.

So yes, the SaaS products that were basically CRUD apps with a subscription are in trouble, but that’s not an AI problem, that’s a product problem. You were always one motivated developer away from obsolescence; AI just made that developer faster.

That said, vibe coding does have a legitimate place in professional software development. In our workflow we now use it as a scratch pad: instead of going through an entire UI design process, business research, endless meetings and iteration cycles, we vibe-code the idea first and test it with the customer. Does it answer the problem? Great, now we know what to build properly. This saves so much time that would otherwise go into design documents and alignment meetings.

The challenge is managing expectations. You have to make clear to the customer that this is just a draft to explore the idea, and the real thing will cost time and money to build. That can be difficult to grasp: “But you already built it? Why does it take so much time and cost so much?” The answer is everything we discussed above: the 90% that isn’t building.

Democratisation

Back to the social angle: what happens when software creation is widely accessible? Will we see tools built by and for communities that Silicon Valley never understood? Will existing power dynamics be rearranged? Hopefully yes to both.

The complaint that vibe-coded apps are “bad” misses the point entirely: if someone who couldn’t build software before can now solve their own problem, messy code and all, that’s a win. The quality bar for personal tools is “does it work for me?” and nothing more. The trouble comes when personal tools try to become products, when someone thinks “this works for me, I should sell it.” That’s when understanding your own problem (relatively easy) becomes understanding someone else’s problem (hard), and maybe it’s even harder now because building no longer forces you to slow down and think.

So is the time of building and selling SaaS products over? Some think so, but the narrative that “customers will just build their own” underestimates what it takes to maintain and be accountable for software others depend on. Meanwhile, go vibe-code something for yourself, seriously. That’s the democratisation promise and it’s real, just have fun building!

Thinking about vibe coding, democratisation, or the future of software products? I’d love to hear your perspective. Get in touch to share your thoughts.

Resources

• AI is Killing B2B SaaS
• Vibe Coding in Practice: Flow, Technical Debt, and Guidelines

Further Reading

On democratisation and its implications:

• Democratizing AI (IBM)
• Democratization in the age of artificial intelligence (Taylor & Francis)
• The Democratization of AI: A Pivotal Moment (Justia)
• How No-code Platforms are Democratizing Software Development

On gatekeeping in tech:

• Gatekeeping in the software industry
• No Gates, No Keepers

This works great for productivity, but it also means Claude has free rein to do whatever it wants. Format my hard disk? Sure. Leak my .env secrets to some random API? Why not. Force push to main? Go for it.

Obviously, I’d prefer to avoid those outcomes. The main thing here is: I don’t let Claude run unsupervised for hours on my system, and I add plenty of other guardrails too. If you do want to experiment with that, please do it on a Raspberry Pi or a VPS, with nothing special on it. But that’s not the subject here.

This post is about hooks: one specific defense layer I researched (again) while updating my claude workflow. Hooks let you intercept and block dangerous operations before they execute, even in YOLO mode. This post documents what I learned. Maybe it helps you too.

Hooks are also fun to use for alerts. This afternoon I added audio phrases from Command & Conquer and Red Alert to some of my hooks. Adding those sounds brought back a lot of fun memories of hours of playing. “Well done, Commander!”

From here on, this has nothing to do with Red Alert or Command & Conquer. But it is about defending your computer and software, so there is some sort of match there :-)

Reader warning: This is a long and boring post. Only read if you’re interested in securing your Claude Code setup with hooks, blocking dangerous commands, preventing path traversal attacks, or protecting sensitive files. Use it as a reference, but never trust it blindly. Don’t say I didn’t warn you!

Table of Contents

• Why Hooks Matter for Security
• The Hook Lifecycle
• Blocking Dangerous Commands
• Input Validation Best Practices
• Path Traversal Prevention
• Protecting Sensitive Files
• Complete Real-World Implementation
• PermissionRequest Hooks
• Known CVEs and Vulnerabilities
• Exit Code Reference
• Comprehensive Security Checklist
• Defense in Depth
• Final Thoughts
• Sources and Further Reading

Why Hooks Matter for Security

Hooks are user-defined shell commands or LLM prompts that execute automatically at specific points in Claude Code’s lifecycle. They execute with your full user permissions, meaning they can read, modify, or delete any file your account can access.

This is both the opportunity and the risk. Without proper controls, Claude Code could:

• Execute destructive shell commands like rm -rf
• Access sensitive files containing credentials
• Modify system configurations
• Expose secrets in logs or outputs

Hooks let you build guardrails that operate deterministically: unlike CLAUDE.md instructions that are “parsed by LLM, weighed against other context, maybe followed,” hooks execute regardless of what Claude thinks it should do.

The Hook Lifecycle

Understanding when hooks fire is essential for effective security. Here are the most relevant events for security purposes (Claude Code has additional events like Notification, SubagentStart, SubagentStop, and PreCompact):

For security, PreToolUse is your primary defense: it runs before dangerous operations execute and can block them entirely.

Blocking Dangerous Commands

The most common security use case is blocking destructive shell commands. The examples below show the concepts step by step. If you want to skip ahead to a complete, production-ready implementation, jump to Complete Real-World Implementation.

Here’s a practical implementation:

Basic Configuration

Add this to your .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/block-dangerous.sh"
          }
        ]
      }
    ]
  }
}

The Blocking Script

#!/bin/bash
# .claude/hooks/block-dangerous.sh

COMMAND=$(jq -r '.tool_input.command' < /dev/stdin)

# Block rm -rf variants (handles -rf, -fr, -r -f, etc.)
if echo "$COMMAND" | grep -qE 'rm\s+(-[a-zA-Z]*r[a-zA-Z]*f|-rf|-fr)\b'; then
  echo "Blocked: rm -rf commands are not allowed" >&2
  exit 2
fi

# Block force pushes to main/master
if echo "$COMMAND" | grep -qE 'git\s+push.*--force.*(main|master)'; then
  echo "Blocked: Force push to main/master not allowed" >&2
  exit 2
fi

# Block sudo rm
if echo "$COMMAND" | grep -qE 'sudo\s+rm'; then
  echo "Blocked: sudo rm commands require manual approval" >&2
  exit 2
fi

# Block chmod 777
if echo "$COMMAND" | grep -qE 'chmod\s+777'; then
  echo "Blocked: chmod 777 is a security risk" >&2
  exit 2
fi

exit 0  # Allow the command

Exit code 2 tells Claude Code to block the operation and feed the error message back to Claude, who can then explain the issue and suggest alternatives.

Configurable Safety Levels

For more flexibility, consider implementing configurable safety levels:

• critical: Block only catastrophic operations (rm -rf ~, fork bombs, dd to disk)
• high: Add risky operations (force push main, secrets exposure, git reset –hard)
• strict: Add cautionary items (any force push, sudo rm, docker prune)

Input Validation Best Practices

Hook input arrives via JSON on stdin. Never trust it blindly. Here are essential validation patterns:

Always Quote Variables

# Bad - breaks with spaces or special characters
FILE_PATH=$TOOL_INPUT

# Good - handles all path types
FILE_PATH="$TOOL_INPUT"

Validate Before Processing

#!/bin/bash
INPUT=$(cat)

# Extract with fallbacks
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Check if value exists
if [ -z "$FILE_PATH" ]; then
  exit 0  # No file path to validate
fi

# Validate the path looks reasonable (don't check existence - file might be new)
# Add your validation logic here

Check Tool Availability

if ! command -v prettier &> /dev/null; then
  exit 0  # Tool not available, skip gracefully
fi

Path Traversal Prevention

Path traversal attacks like ../../etc/passwd are a significant risk. Here’s how to prevent them:

Simple Detection

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Block obvious path traversal
if echo "$FILE_PATH" | grep -q '\.\.'; then
  echo '{"decision":"block","reason":"Path traversal detected"}'
  exit 0
fi

# Ensure path is within project (CVE-2025-54794: use trailing separator)
PROJECT_DIR="$CLAUDE_PROJECT_DIR"
RESOLVED_PATH=$(realpath -m "$FILE_PATH" 2>/dev/null)

# Add trailing slash to prevent /project matching /project_malicious
if [[ ! "$RESOLVED_PATH" == "$PROJECT_DIR" && ! "$RESOLVED_PATH" == "$PROJECT_DIR/"* ]]; then
  echo '{"decision":"block","reason":"Path is outside project directory"}'
  exit 0
fi

exit 0

Python Implementation

For more robust validation, use Python:

#!/usr/bin/env python3
import json
import sys
import os
from pathlib import Path

input_data = json.load(sys.stdin)
file_path = input_data.get('tool_input', {}).get('file_path', '')

if not file_path:
    sys.exit(0)

project_dir = Path(os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())).resolve()
target_path = (project_dir / file_path).resolve()

# CVE-2025-54794: Must check with trailing separator to prevent
# /project matching /project_malicious
project_str = str(project_dir)
target_str = str(target_path)

if not (target_str == project_str or target_str.startswith(project_str + os.sep)):
    print(json.dumps({
        "decision": "block",
        "reason": "Path is outside project directory"
    }))
    sys.exit(0)

sys.exit(0)

Protecting Sensitive Files

Create a blocklist for files that should never be accessed:

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Sensitive file patterns
SENSITIVE_PATTERNS=(
  "\.env$"
  "\.env\."
  "\.pem$"
  "\.key$"
  "\.p12$"
  "credentials\.json"
  "secrets\.yaml"
  "\.git/config$"
  "id_rsa"
  "id_ed25519"
)

for pattern in "${SENSITIVE_PATTERNS[@]}"; do
  if echo "$FILE_PATH" | grep -qE "$pattern"; then
    echo "Blocked: Access to sensitive file not allowed" >&2
    exit 2
  fi
done

exit 0

Complete Real-World Implementation

The snippets above are useful for understanding individual concepts, but here’s the actual Python hook I use. It combines all the security checks into a single, comprehensive PreToolUse hook:

#!/usr/bin/env python3
"""
PreToolUse security hook that blocks dangerous operations.

Checks for:
- Dangerous rm commands
- Fork bombs
- Dangerous git commands (push to main/master, force push)
- Disk write attacks (dd to /dev/)
- Sensitive file access (.env, .pem, .key, credentials, etc.)
- Path traversal attacks
- Project directory escape

Set CLAUDE_HOOKS_DEBUG=1 to enable debug logging.
"""

from __future__ import annotations

import json
import os
import re
import sys
from pathlib import Path

# Debug mode for troubleshooting
DEBUG = os.environ.get('CLAUDE_HOOKS_DEBUG', '').lower() in ('1', 'true')

# Pre-compiled regex patterns for performance
DANGEROUS_RM_PATTERNS = [
    re.compile(r'\brm\s+.*-[a-z]*r[a-z]*f'),  # rm -rf, rm -fr, rm -Rf, etc.
    re.compile(r'\brm\s+.*-[a-z]*f[a-z]*r'),  # rm -fr variations
    re.compile(r'\brm\s+--recursive\s+--force'),
    re.compile(r'\brm\s+--force\s+--recursive'),
    re.compile(r'\brm\s+-r\s+.*-f'),
    re.compile(r'\brm\s+-f\s+.*-r'),
]

DANGEROUS_RM_PATH_PATTERNS = [
    re.compile(r'\s/$'),          # Root directory
    re.compile(r'\s/\*'),         # Root with wildcard
    re.compile(r'\s~/?'),         # Home directory
    re.compile(r'\s\$HOME'),      # Home environment variable
    re.compile(r'\s\.\./?'),      # Parent directory references
    re.compile(r'\s\.$'),         # Current directory
]

RM_RECURSIVE_PATTERN = re.compile(r'\brm\s+.*-[a-z]*r')

FORK_BOMB_PATTERNS = [
    re.compile(r':\(\)\s*\{\s*:\|:&\s*\}\s*;:'),  # Classic bash fork bomb
    re.compile(r'\.\/\w+\s*&\s*\.\/\w+'),  # Self-replicating pattern
    re.compile(r'while\s+true.*fork', re.IGNORECASE),
    re.compile(r'fork\s*\(\s*\)\s*while', re.IGNORECASE),
]

DANGEROUS_GIT_PATTERNS = [
    # Block ALL pushes to main/master (including regular push)
    re.compile(r'git\s+push\s+.*\b(main|master)\b'),
    re.compile(r'git\s+push\s+origin\s+(main|master)'),
    # Block force push without explicit branch (might be on main)
    re.compile(r'git\s+push\s+.*--force'),
    re.compile(r'git\s+push\s+.*-f\b'),
    # Other dangerous commands
    re.compile(r'git\s+reset\s+--hard\s+origin/'),
    re.compile(r'git\s+clean\s+-fd'),  # Force delete untracked files
]

DANGEROUS_DISK_PATTERNS = [
    re.compile(r'\bdd\s+.*of=/dev/'),  # dd to device
    re.compile(r'\bmkfs\.'),  # Format filesystem
    re.compile(r'>\s*/dev/sd'),  # Write to disk device
]

ENV_ACCESS_PATTERNS = [
    re.compile(r'\bcat\s+[^\|]*\.env\b(?!\.sample|\.example|\.template)'),
    re.compile(r'\bless\s+[^\|]*\.env\b(?!\.sample|\.example|\.template)'),
    re.compile(r'\bhead\s+[^\|]*\.env\b(?!\.sample|\.example|\.template)'),
    re.compile(r'\btail\s+[^\|]*\.env\b(?!\.sample|\.example|\.template)'),
    re.compile(r'>\s*[^\s]*\.env\b(?!\.sample|\.example|\.template)'),
    re.compile(r'\bcp\s+[^\|]*\.env\b(?!\.sample|\.example|\.template)'),
    re.compile(r'\bmv\s+[^\|]*\.env\b(?!\.sample|\.example|\.template)'),
    re.compile(r'\bsource\s+[^\|]*\.env\b(?!\.sample|\.example|\.template)'),
    re.compile(r'\.\s+[^\|]*\.env\b(?!\.sample|\.example|\.template)'),
]

SENSITIVE_FILE_PATTERNS = [
    (re.compile(r'\.pem$'), 'PEM certificate/key file'),
    (re.compile(r'\.key$'), 'Key file'),
    (re.compile(r'\.p12$'), 'PKCS12 certificate'),
    (re.compile(r'\.pfx$'), 'PFX certificate'),
    (re.compile(r'credentials\.(json|yaml|yml|xml|ini|conf)$'), 'Credentials file'),
    (re.compile(r'secrets?\.(json|yaml|yml|xml|ini|conf)$'), 'Secrets file'),
    (re.compile(r'\.kube/config'), 'Kubernetes config'),
    (re.compile(r'\.aws/credentials'), 'AWS credentials'),
    (re.compile(r'\.ssh/'), 'SSH directory'),
    (re.compile(r'\.gnupg/'), 'GPG directory'),
    (re.compile(r'\.netrc'), 'Netrc file'),
    (re.compile(r'\.npmrc'), 'NPM config with tokens'),
    (re.compile(r'\.pypirc'), 'PyPI config with tokens'),
]

SENSITIVE_FILES = {
    '.env', '.env.local', '.env.production', '.env.development',
    'id_rsa', 'id_ed25519', 'id_ecdsa', 'id_dsa',
}

ALLOWED_ENV_FILES = {'.env.sample', '.env.example', '.env.template'}


def debug_log(message: str) -> None:
    """Log debug message if debug mode is enabled."""
    if DEBUG:
        print(f"[DEBUG] {message}", file=sys.stderr)


def is_dangerous_rm_command(command: str) -> bool:
    """Detect dangerous rm commands."""
    normalized = ' '.join(command.lower().split())

    for pattern in DANGEROUS_RM_PATTERNS:
        if pattern.search(normalized):
            return True

    if RM_RECURSIVE_PATTERN.search(normalized):
        for pattern in DANGEROUS_RM_PATH_PATTERNS:
            if pattern.search(normalized):
                return True
    return False


def is_fork_bomb(command: str) -> bool:
    """Detect fork bomb patterns."""
    for pattern in FORK_BOMB_PATTERNS:
        if pattern.search(command):
            return True
    return False


def is_dangerous_git_command(command: str) -> bool:
    """Detect dangerous git commands."""
    normalized = ' '.join(command.lower().split())
    for pattern in DANGEROUS_GIT_PATTERNS:
        if pattern.search(normalized):
            return True
    return False


def is_dangerous_disk_write(command: str) -> bool:
    """Detect dangerous disk write operations."""
    normalized = ' '.join(command.lower().split())
    for pattern in DANGEROUS_DISK_PATTERNS:
        if pattern.search(normalized):
            return True
    return False


def is_sensitive_file(file_path: str) -> tuple[bool, str | None]:
    """Check if file path points to sensitive files."""
    if not file_path:
        return False, None

    path_lower = file_path.lower()
    basename = os.path.basename(path_lower)

    if basename in ALLOWED_ENV_FILES:
        return False, None

    if basename in SENSITIVE_FILES:
        return True, f"Access to {basename} files is prohibited"

    for pattern, description in SENSITIVE_FILE_PATTERNS:
        if pattern.search(path_lower):
            return True, f"Access to {description} is prohibited"

    return False, None


def is_path_escape(file_path: str, project_dir: str) -> tuple[bool, str | None]:
    """Check if path escapes the project directory."""
    if not file_path or not project_dir:
        return False, None

    try:
        abs_path = Path(file_path).resolve()
        abs_project = Path(project_dir).resolve()

        # CVE-2025-54794: Must check with trailing separator to prevent
        # /project matching /project_malicious
        project_str = str(abs_project)
        path_str = str(abs_path)

        if not (path_str == project_str or path_str.startswith(project_str + os.sep)):
            return True, "Path is outside project directory"

        if '..' in file_path:
            return True, "Path traversal attempt detected"

    except (ValueError, OSError):
        return True, "Invalid path"

    return False, None


def check_bash_command(command: str) -> str | None:
    """Check bash command for dangerous patterns."""
    if is_dangerous_rm_command(command):
        return "Dangerous rm command detected"
    if is_fork_bomb(command):
        return "Fork bomb detected"
    if is_dangerous_git_command(command):
        return "Dangerous git command detected (push to main/master or force push)"
    if is_dangerous_disk_write(command):
        return "Dangerous disk write operation detected"

    for pattern in ENV_ACCESS_PATTERNS:
        if pattern.search(command):
            return "Access to .env files is prohibited"

    return None


def check_file_operation(tool_name: str, tool_input: dict, project_dir: str) -> str | None:
    """Check file operations for security issues."""
    file_path = tool_input.get('file_path', '')

    if tool_name == 'Grep':
        file_path = tool_input.get('path', '') or file_path
    if tool_name == 'Glob':
        file_path = tool_input.get('path', '') or file_path

    if not file_path:
        return None

    is_sensitive, reason = is_sensitive_file(file_path)
    if is_sensitive:
        return reason

    if os.path.isabs(file_path) or '..' in file_path:
        is_escape, reason = is_path_escape(file_path, project_dir)
        if is_escape:
            return reason

    return None


def main() -> None:
    try:
        input_data = json.load(sys.stdin)
        tool_name = input_data.get('tool_name', '')
        tool_input = input_data.get('tool_input', {})
        project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())

        debug_log(f"Checking tool: {tool_name}")

        if tool_name == 'Bash':
            command = tool_input.get('command', '')
            error = check_bash_command(command)
            if error:
                print(f"BLOCKED: {error}", file=sys.stderr)
                sys.exit(2)

        if tool_name in ['Read', 'Edit', 'MultiEdit', 'Write', 'Glob', 'Grep']:
            error = check_file_operation(tool_name, tool_input, project_dir)
            if error:
                print(f"BLOCKED: {error}", file=sys.stderr)
                sys.exit(2)

        sys.exit(0)

    except json.JSONDecodeError:
        sys.exit(0)  # Fail open on parse errors
    except Exception:
        sys.exit(0)  # Fail open on unexpected errors


if __name__ == '__main__':
    main()

Save this as .claude/hooks/pre_tool_use.py and configure it in your settings:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/pre_tool_use.py\""
          }
        ]
      }
    ]
  }
}

Key design decisions in this implementation:

1. Pre-compiled regex patterns for better performance on repeated checks
2. Fail-open on errors (sys.exit(0)) so parsing failures don’t break your workflow
3. Debug mode via CLAUDE_HOOKS_DEBUG=1 for troubleshooting
4. CVE-2025-54794 fix with proper path prefix checking using os.sep
5. Allows safe variants like .env.sample and .env.example
6. Covers multiple tools including Bash, Read, Edit, Write, Glob, and Grep

PermissionRequest Hooks

The PermissionRequest hook (v2.0.45+) triggers when Claude Code displays a permission dialog, allowing automatic approve/deny decisions:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/permission-handler.sh"
          }
        ]
      }
    ]
  }
}

Auto-Approve Safe Operations

#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Auto-approve read-only tools
if [[ "$TOOL_NAME" =~ ^(Read|Glob|Grep)$ ]]; then
  echo '{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}'
  exit 0
fi

# Auto-approve safe npm commands
if [[ "$TOOL_NAME" == "Bash" ]] && [[ "$COMMAND" =~ ^npm\ (test|run\ lint|run\ build) ]]; then
  echo '{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}'
  exit 0
fi

# Deny dangerous patterns
if echo "$COMMAND" | grep -qE 'rm\s+-rf'; then
  echo '{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"deny","message":"Destructive command blocked"}}}'
  exit 0
fi

# Default: show permission prompt
exit 0

Note: PermissionRequest hooks do not fire in non-interactive mode (-p). Use PreToolUse hooks for automated permission decisions.

Known CVEs and Vulnerabilities

Several vulnerabilities have been discovered in Claude Code over time. If you’re running a recent version (2.1.12 at time of writing), these are all patched. They’re listed here to illustrate the types of attacks that hooks can help defend against:

Check Anthropic’s releases for the latest patched versions.

General Mitigation

• Never execute development tools in untrusted directories
• Use strong sandboxing and isolation
• Treat Claude Code output as unverified
• Keep prompts precise and exclude sensitive data

Exit Code Reference

Understanding exit codes is essential:

Choose one approach per hook, either exit codes alone or exit 0 with JSON output. Don’t mix them; Claude Code ignores JSON when you exit 2.

Comprehensive Security Checklist

Before deploying hooks in production:

• Validate all input from stdin
• Quote all file paths and variables
• Use absolute paths for scripts (via $CLAUDE_PROJECT_DIR)
• Block sensitive files (.env, .key, .git/)
• Handle missing tools gracefully
• Set reasonable timeout (default 60s)
• Log errors to stderr or log file
• Test with edge cases (spaces, Unicode, missing files)
• Test hooks before deploying (see below)
• Consider disabling hooks when not needed

Testing Your Hooks

Before deploying, test your hooks with sample input:

# Test dangerous command blocking
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | python3 .claude/hooks/pre_tool_use.py
echo $?  # Should be 2 (blocked)

# Test safe command
echo '{"tool_name":"Bash","tool_input":{"command":"ls -la"}}' | python3 .claude/hooks/pre_tool_use.py
echo $?  # Should be 0 (allowed)

# Test sensitive file blocking
echo '{"tool_name":"Read","tool_input":{"file_path":".env"}}' | python3 .claude/hooks/pre_tool_use.py
echo $?  # Should be 2 (blocked)

Defense in Depth

Implement security at multiple layers:

1. UserPromptSubmit - Validate prompts before Claude processes them
2. PreToolUse - Block dangerous operations before execution
3. PermissionRequest - Auto-approve safe operations, deny dangerous ones
4. PostToolUse - Validate results and provide feedback
5. Deny lists - Add explicit permission denials in settings

{
  "permissions": {
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(terraform destroy:*)",
      "Bash(docker system prune:*)"
    ]
  }
}

Final Thoughts

Claude Code hooks provide powerful security controls, but they require careful implementation. The key principles:

1. Hooks execute deterministically - Unlike CLAUDE.md rules, hooks cannot be bypassed
2. Validate everything - Never trust input data
3. Exit code 2 blocks - Use it for security violations
4. Defense in depth - Implement multiple security layers
5. Stay updated - Patch promptly when vulnerabilities are discovered

Security isn’t about preventing all possible risks: it’s about reducing attack surface while maintaining productivity. Well-designed hooks let you work confidently with AI assistance while protecting your systems from accidental or malicious damage.

Sources and Further Reading

Official Documentation

• Hooks Reference - Claude Code Docs - The official reference documentation
• Automate Workflows with Hooks Guide - Quickstart guide with examples
• Claude Code Best Practices - Anthropic’s official best practices
• Agent SDK Hooks - Hooks in the Agent SDK

Security Resources

• Claude Code Security Best Practices - Backslash
• A Deep Dive into Security for Claude Code - Eesel
• Claude Code Security: Enterprise Best Practices - MintMCP
• Claude Hooks Best Practices - PRPM
• Are Claude Skills Secure? Threat Model & Permissions - Skywork

CVE Details and Security Advisories

• CVE-2025-54795: InversePrompt - Cymulate
• CVE-2025-52882: WebSocket Authentication Bypass - Datadog Security Labs
• Arbitrary Code Execution Advisory - Redguard
• Claude AI Flaws: Unauthorized Commands - GBHackers

Tutorials and Guides

• Claude Code Hooks: A Practical Guide - DataCamp
• The Ultimate Claude Code Guide - DEV Community
• Claude Code Hook Examples - Steve Kinney
• Block Dangerous Commands - Perrotta.dev
• Hooks for Automated Quality Checks - Luiz Tanure
• Claude Code Hooks: Guardrails That Work - Paddo.dev
• How to Configure Hooks - Claude Blog

GitHub Repositories

• claude-code-hooks-mastery - Comprehensive hooks examples and patterns
• claude-code-bash-guardian - Automated security layer for Bash hooks
• awesome-claude-code - Curated list of skills, hooks, and plugins
• claude-code-hooks - Collection of useful hooks
• claude-code-damage-control - Safety hooks
• everything-claude-code - Complete configuration collection
• claude-code-security-review - AI-powered security review GitHub Action

Community Resources

• ClaudeLog - Hooks Documentation
• .claude Directory - Hooks
• Claude Code CLI Cheatsheet - Shipyard
• GitButler - Claude Code Hooks
• Permission Hook Guide - Claude Fast

Working with Claude Code in production? I’d love to hear about your security patterns and hook implementations. Get in touch to share your experiences.

Why would you not be able to do that? The wonders of corporate lock-in, I suppose.

That’s a problem: no design file. What now? So on to searching for ways to extract the code.

Update - January 29, 2026

A few useful tips from readers:

• Use the file command first: Before reaching for xxd, running file ClientApp.make would have identified it as a ZIP archive immediately. Good reminder to start with the obvious tools.
• Try binwalk for unknown binaries: It scans for known file signatures and can identify embedded files within a single binary. Worth trying early in the process.

Now let’s get into it.

The Discovery: It’s Just a ZIP File

So I started clicking around the Figma interface, looking for anything useful. That’s when I noticed you can download the .make file itself. Download. A file, interesting!

But I can not read it. Hmmm, what now? Rule number one: never trust the extension. A .make file could be anything. After a while I figured out it was a ZIP file. And in it was in essence a React application.

The Discovery: It’s Just a ZIP File

First thing I did was look at the raw bytes:

xxd -l 4 "ClientApp.make"
# Output: 504b 0304

504b is PK in ASCII. That’s the ZIP file signature. The whole mysterious .make file is just a ZIP archive with a different extension. Learned something new today (about 504b).

Unzip it:

ClientApp.make (ZIP)
├── canvas.fig          # 2.3 MB binary - the interesting part
├── meta.json           # Project metadata
├── ai_chat.json        # 34 MB of AI conversation history
├── thumbnail.png       # Preview image
├── images/             # 110 image assets (hash-named, no extensions)
└── blob_store/         # Additional binary data

The ai_chat.json was massive. Every prompt, every response, every iteration the client went through while building the app. Not very useful, and not what I needed. (although i did try to extract design tokens from it at first, before turning to the binary file).

The canvas.fig file held the actual code. 2.3 MB of binary data. That extension sounds more like a standard Figma design file. How to read that and see if it contains anything useful? Time to dig deeper.

Decoding the Binary Format

Looking at the header:

xxd -l 20 canvas.fig
# Output: 6669 672d 6d61 6b65 65... (fig-makee)

Standard Figma design files use fig-kiwi as their magic header. Make files use fig-makee. Different format, same general approach.

The structure:

Two chunks. Two different compression algorithms. Thanks for some AI help here, LLMs are great at spotting patterns in binary data.

The Compression Puzzle

First attempt: zlib decompression on both chunks.

Error: Invalid stored block lengths

The first chunk decompressed fine with zlib/deflate. The second chunk refused. Checking its magic bytes: 28 B5 2F FD. That’s Zstandard compression. Different algorithm entirely.

So:

• Chunk 1 (Schema): Deflate compressed, 24KB → 59KB decompressed
• Chunk 2 (Data): Zstandard compressed, 2.2MB → 29MB decompressed

Three npm packages made this work: pako for deflate, fzstd for Zstandard, and kiwi-schema for decoding the binary data format. Again, LLMs to the rescue. I know a bit about compression, but this would have taken me a lot of time to figure out alone. And probably would have given up (rewards vs time invested).

Kiwi Schema: Figma’s Binary Format

Figma uses the Kiwi binary schema format. It’s compact but has no schema definition included. Fortunately, Chunk 1 contains exactly that: the schema.

The schema had 534 type definitions. Nodes, colors, vectors, transforms, fonts, and the one I cared about: CODE_FILE.

Decoding the message data revealed a tree structure with 159 nodes:

{
  "nodeChanges": [
    {
      "type": "DOCUMENT",
      "children": [...]
    },
    {
      "type": "CODE_FILE",
      "name": "App.tsx",
      "sourceCode": "import React from 'react'..."
    },
    // ... 157 more nodes
  ]
}

Every React component, utility function and CSS file were there in the sourceCode property. Progress! Now how to get to the content, the actual files?

Extracting the Content

Finding CODE_FILE nodes with source code was straightforward:

const codeFiles = nodeChanges.filter(
  node => node.type === 'CODE_FILE' && node.sourceCode
);

96 source files extracted:

• React components (.tsx)
• TypeScript utilities (.ts)
• CSS files including globals.css
• Data files
• React hooks

But having files isn’t the same as having a working app. Now to piece it all together, in a working structure:

From Files to Running App

The extracted code had some quirks:

Versioned package imports: Figma Make embeds version numbers directly in import statements.

// What Figma Make generates
import { Dialog } from '@radix-ui/react-dialog@1.1.6'

// What actually works
import { Dialog } from '@radix-ui/react-dialog'

Custom asset imports: Images use a proprietary format.

// What Figma Make generates
import heroImage from 'figma:asset/a1b2c3d4.png'

// What actually works
const heroImage = '/images/a1b2c3d4.png'

Missing file extensions: All images in the images/ folder were hash-named with no extensions. The browser needs .png to serve them correctly.

Tailwind CSS v4 changes: The PostCSS integration changed between versions. Needed @tailwindcss/postcss instead of using tailwindcss directly.

React StrictMode breaking animations: The original code used Framer Motion. StrictMode double-mounts components, which breaks timers and animations. Removing StrictMode fixed it.

I wrote scripts to handle all of this automatically. Analyze imports, determine folder structure (based on import references in the files), fix paths, copy images with proper extensions, generate package.json, Vite config, and TypeScript config.

The Result

cd make_extraction
./run-all.sh ../ClientApp.make
cd output/react_app
npm install --legacy-peer-deps
npm run dev

A working React application on localhost:5173. Same components, same styling, same animations. No manual conversion work. No information lost.

Design Token Extraction

Beyond source code, I also extracted design tokens using regex patterns:

• Hex colors: #1a1a1a, #ffffff
• RGBA values: rgba(0, 0, 0, 0.5)
• HSL colors: hsl(220, 14%, 96%)
• CSS variables: --primary-color: #3b82f6
• Google Fonts: Inter, Roboto

All exported to design-tokens.json for easy reference or migration to a design system.

Lessons Learned

Don’t assume compression types: The same file can use multiple compression algorithms for different chunks. Check the magic bytes.

Figma’s internal format is consistent: Whether it’s a design file or a code project, the underlying structure uses Kiwi schemas. Different content, same parsing approach.

React StrictMode has side effects: It’s great for catching bugs during development, but it can break production code that relies on mount/unmount timing.

The original code is usually correct: I wasted time “fixing” fonts that weren’t broken. The extraction was accurate; my assumptions weren’t.

And most interesting: Figma Make is a great tool, but under the hood it is straightforward React with Radix UI and Tailwind CSS. No magic, just well-structured code generation. (and i have to give it to them, the code quality is pretty good for AI-generated code!).

So after spending 3 hours reverse-engineering and an hour writing this post, I can now finally get to work on the actual app :-) Have a great day!

Get the Code

The extraction scripts are available here:

Repository: github.com/albertsikkema/figma-make-extractor

Quick start:

git clone https://github.com/albertsikkema/figma-make-extractor.git
cd figma-make-extractor/make_extraction
./run-all.sh ../YourApp.make
cd output/react_app
npm install --legacy-peer-deps
npm run dev

The scripts handle:

1. Unzipping the .make archive
2. Decoding the canvas.fig binary
3. Extracting source files
4. Extracting design tokens
5. Creating a runnable React/Vite project

When Would You Need This?

• Client hands you a Figma Make prototype but not the design file
• You want to audit AI-generated code before deployment
• You need to migrate away from Figma Make to a different stack
• You want to extract design tokens for your design system
• Pure curiosity about how Figma structures its data

Resources

CLI Tools for Binary Analysis:

• file - Identify file types from magic bytes
• binwalk - Scan for embedded files and compression signatures

Binary Format Analysis:

• Kiwi Schema Format
• Zstandard Compression

npm Packages Used:

• pako - Deflate compression
• fzstd - Zstandard for JavaScript
• kiwi-schema - Kiwi binary format decoder

Have a Figma Make file you can’t crack? Questions about the binary format? Get in touch or open an issue on GitHub.

The name is a play on words. “Dictation” because that’s what it does. “Dictator” because that’s how I sometimes view my relationship with this computer—I tell it what to do. And maybe a small nod to the times we live in.

I know, there are a lot of speech-to-text solutions out there, but I wanted something that was:

• 100% Local: All processing happens on-device using whisper.cpp—your audio never leaves your Mac
• No Internet Required: Works completely offline once installed
• Fast: Metal GPU acceleration for near-instant transcription on Apple Silicon
• Free: no hidden costs, no subscriptions
• Lightweight: Minimal resource usage, stays out of your way
• Non-obtrusive: Lives quietly in your menu bar, not the dock
• Easy to Use: Just hold a hotkey to record, release to transcribe and paste
• Push-to-talk: Natural workflow—hold to speak, release to transcribe
• Visual Feedback: Icon animates (red → orange → yellow) based on audio level
• Configurable: Choose your preferred hotkey (Right Option, Right Command, Left Option, or Left Command)
• Auto-start: Option to launch at login
• Self-contained: Model bundled in the app (no external dependencies)

And also important: I built it for myself to improve my productivity when writing code.

And since I was working on a client app that needs very sophisticated audio input handling, I figured why not use what I just learned to make something useful for myself and others?

How It Works

1. Hold your configured hotkey (default: Right Option)
2. Speak
3. Release the hotkey
4. Text appears at your cursor

The menu bar icon animates based on your voice volume so you know it’s hearing you. All transcription happens locally using whisper.cpp with Metal acceleration—no cloud, no API keys.

Note: English only for now.

Installation

Grab the .dmg from the releases page, drag the app to Applications, right-click and select “Open”. Grant microphone and accessibility permissions when prompted, and you’re set.

macOS Security

This app is not signed with an Apple Developer certificate, so macOS will show security warnings. This is normal for open-source apps distributed outside the App Store.

The app is safe—you can review the source code yourself. All audio processing happens locally on your Mac. No data is sent to any servers.

If right-click → Open doesn’t work:

1. Go to System Settings → Privacy & Security
2. Scroll down to the Security section
3. You’ll see a message about Dictator being blocked—click Open Anyway
4. Confirm by clicking Open in the dialog

Resources

• Dictator on GitHub
• whisper.cpp

Questions or feedback? Get in touch.

The initial implementation worked. Each repo got its own Claude Flow instance with a random port and local database. This created an immediate problem: hooks broke constantly because they couldn’t find the server. Dynamic ports meant hooks had no stable target. Multiple databases meant no central view of tasks across projects.

So long story short: I rebuilt it into a central app with multi-repo support. One server on a fixed port, one database with repo-aware schema, and hooks that always work. Here’s how I did it, the trade-offs, and what I learned.

The Per-Repo Problem

My first attempt followed the per repo pattern: install Claude Flow in each repo. Launch it per-repo with an available port. And store tasks in a local SQLite database inside the repo.

This seemed reasonable initially:

• Isolated: Each project has its own task database
• Simple: No coordination between repos needed
• Portable: run the install script, everything comes with it

In practice, it was a mess:

repo-A/.claude/claude-flow/  (port 52341)
repo-B/.claude/claude-flow/  (port 52387)
repo-C/.claude/claude-flow/  (port 51993)

The hooks need to post updates to the backend—new task created, task completed, artifact saved. But which port? The hooks run in .claude/hooks/ and get triggered by Claude Code. They have no idea what port the UI launched on. I tried writing the port to a file, reading it from hooks. That did not work!

Also: switching between repos meant launching different instances, losing context. Want to see all your tasks across projects? Too bad. Each database only knows about one repo.

The Global App Solution

The fix was obvious from the beginning, but I was hoping not to go their, afraid of too much complexity. But in retrospect this was the right step: stop treating Claude Flow as a per-repo tool. Make it a global system-level app.

New architecture:

• One app running on fixed port 9118
• One database at ~/Library/Application Support/claude-flow/database.db
• Repo-aware schema with repo_id column on every task
• Hooks always target localhost:9118 (why? See my previous post on choosing development ports that don’t conflict)

Now hooks just work. They don’t need to discover ports. The backend accepts tasks from any repo, tags them with repo_id, and stores everything centrally. The frontend shows a repo selector dropdown—pick which project you want to view.

Implementation Details

The refactor touched a lot. These were the main changes:

Database Schema

Added repo_id to track which repo each task belongs to:

class TaskDB(Base):
    __tablename__ = "tasks"

    id = Column(Integer, primary_key=True, index=True)
    repo_id = Column(String(500), nullable=False, index=True)
    title = Column(String(500), nullable=False)
    description = Column(Text)
    status = Column(String(50), nullable=False)
    # ... other fields

Also added a RepoDB table for tracking registered repositories (name, path, last active timestamp).

API Endpoints

All task endpoints now filter by repo_id:

@router.get("/tasks")
def get_tasks(repo_id: str = Query(None), db: Session = Depends(get_db)):
    query = db.query(TaskDB)
    if repo_id:
        query = query.filter(TaskDB.repo_id == repo_id)
    return query.order_by(TaskDB.created_at.desc()).all()

New repo management endpoints let the frontend list repos, add new ones, remove old ones. The backend auto-registers repos when hooks first post from them—reduces setup friction.

Fixed Port

The desktop app now always uses port 9118:

port = 9118  # Fixed for hook compatibility

# Check if already running
try:
    response = requests.get(f"http://localhost:{port}/health", timeout=1)
    if response.status_code == 200:
        webbrowser.open(f"http://localhost:{port}")
        return
except:
    pass

# Start server
uvicorn.run(app, host="0.0.0.0", port=port)

If you launch it twice, the second instance detects the running server and just opens your browser to the existing app. Nice UX, avoids port conflicts. Or you can just launch the ‘Claude Flow’ from applications.

Desktop App Wrapper

Claude Flow runs as a native desktop app using pywebview. Even though Electron was the obvious choice—it’s what VS Code, Slack, and Discord use—I went with pywebview for one reason: bundle size.

Electron ships an entire Chromium browser and Node.js runtime. That’s 100-200MB minimum, even for a simple app. PyWebView uses your system’s native webview (WebKit on macOS, Edge WebView2 on Windows, GTK on Linux), adding only ~5MB. Smalll, fast –> Good enough for me.

Instead of opening tabs in your default browser, pywebview creates a standalone window that feels like a proper application:

import webview
import threading

# Start FastAPI in background thread
server_thread = threading.Thread(target=start_server, daemon=True)
server_thread.start()

# Create native window
webview.create_window("Claude Flow", f"http://localhost:{port}", width=1200, height=800)
webview.start()

This gives you:

• Native window controls: Minimize, maximize, close work as expected
• Menu bar integration: On macOS, it appears in the dock like any other app
• No browser chrome: No address bar, bookmarks, or extensions cluttering the interface
• Better resource isolation: Separate from your browser’s memory footprint

PyWebView uses your system’s native webview (WebKit on macOS, Edge WebView2 on Windows, GTK on Linux), so it’s lightweight and platform-appropriate. The FastAPI backend runs in a background thread while the window displays the React frontend.

Frontend Repo Selector

Added a dropdown to the header that loads repos from /api/repos, lets you switch between them, and filters task display:

export const fetchRepos = async () => {
  const response = await fetch(`${API_BASE}/api/repos`);
  return await response.json();
};

export const fetchTasks = async (repoId: string) => {
  const response = await fetch(`${API_BASE}/api/tasks?repo_id=${repoId}`);
  return await response.json();
};

When you add a new repo through the UI, Claude Flow does something useful: it automatically scaffolds the .claude/ directory structure, helper functions, and thoughts/ folder into that repo. If they already exist, you can update them to the latest version with one click. This makes onboarding new projects trivial—add the repo path, Claude Flow sets up the structure, and hooks start working immediately.

No more copying configuration between repos or forgetting to add the hooks directory. The UI handles it, and if I update the template structure later, existing repos can pull in changes without manual file copying. “Latest iteration of my madness” as a service.

Global Config Location

The .env file moved from per-repo to global:

~/Library/Application Support/claude-flow/.env

Set your OPENAI_API_KEY once, works everywhere.

Trade-offs

This architecture isn’t perfect. Some downsides:

Shared state: All tasks in one database. Deleted database means losing task history across all repos. Regular backups matter more. Then again, this is only for local development tasks, not a shared Jira instance. So no real problem.

Port conflicts: If something else uses 9118, you’re stuck. Could make it configurable, but haven’t needed to yet.

The benefits outweigh these. Hooks work reliably. Single source of truth for tasks. One app to manage, not one per repo.

What I Learned

Pick your architecture early, but do not let it hold you back. You can always refactor: I started with per-repo because that was easy. Later I ran into problems and adjusted. Could I have foreseen this? Yes. Would I have finished this if I had thought all steps through? Probably not.

Fixed infrastructure beats dynamic discovery: Random ports felt clever—avoid conflicts automatically! But they add complexity everywhere downstream. Fixed port 9118 is simpler, more reliable, and conflicts are rare. So if you can simplify, do it.

Multi-repo support isn’t that hard: Adding repo_id filtering throughout the codebase was straightforward. SQLAlchemy made schema changes painless. FastAPI’s dependency injection kept endpoint code clean. Good tools make refactors easier.

Auto-registration reduces friction: When hooks first POST from a new repo, the backend registers it automatically. No manual setup. Removes a step the user (as in I) would forget and then get confused about.

Try It (if you dare)

Claude Flow isn’t released yet—still in the “works on my machine” phase. I do not know if there will be an official release: the goal is to help me and my specific ideas on how to work with LLM in development. I do not plan on making it easy and accessible. There will documentation, but not polished user experience.

For now, the architecture lessons apply broadly: global apps with multi-tenant filtering often beat per-instance isolation. Fixed infrastructure beats dynamic discovery. Auto-registration beats manual setup.

If you’re building tools that integrate with Claude Code or other AI-assisted development workflows, consider these patterns. They saved me from per-repo chaos.

Resources

• Vibe Kanban - Inspiration for Claude integration
• Auto Claude - Automated Claude integration tool
• SQLAlchemy ORM - Python database toolkit
• FastAPI Documentation - Modern Python web framework
• Claude Code Best Practices - Official engineering guide

Building tools for AI-assisted development? I’d love to hear what patterns you’ve found useful—get in touch.

While setting up self-hosted analytics and error tracking (Umami and GlitchTip) on my NixOS server, I needed to protect login endpoints from brute-force attacks. The standard approach is straightforward: add nginx rate limiting.

The Simple Solution: Rate Limit Everything

So to protect your site’s login, a first step is something like this—a general zone that limits all requests:

limit_req_zone $binary_remote_addr zone=general:10m rate=30r/s;

location / {
    limit_req zone=general burst=20 nodelay;
    proxy_pass http://backend;
}

This works fine for general protection, however there is a balance. This setting is too strict for normal use (‘/’ means all pages and endpoints are subjected to this rate limit regime). So we need more (a lot) room for regular traffic but that means login pages are allowed to be called way more as well, we need stricter limits specifically for login endpoints. A brute-force attacker making for instance 30 requests per second can try 1,800 passwords per minute. That’s way too permissive.

So the next step was to create a stricter zone for /login:

limit_req_zone $binary_remote_addr zone=login:10m rate=5r/m;

location /login {
    limit_req zone=login burst=3 nodelay;
    proxy_pass http://backend;
}

Five requests per minute. That should stop brute-force attacks cold. Combined with fail2ban to block persistent offenders, this is a solid defense.

The Problem: You Just Broke the Login Page

Here’s what that strict rate limiting actually does:

Every request to /login counts against the limit. User visits the login page? That’s one. Types wrong password and page reloads? That’s two. Hits refresh because the page looks stuck? Three, four, five—blocked.

Now your legitimate users are locked out of even seeing the login form. You’ve stopped brute-force attacks by making the login page unusable for everyone.

The Fix: Only Rate Limit What Matters

Login pages handle two distinct operations:

1. GET - Display the login form (no credentials transmitted)
2. POST - Submit credentials (the actual attack vector)

Attackers don’t care about loading the form—they’re hammering POST requests with credential combinations. GET requests are harmless. So why rate limit them at all? (Users should be able to refresh the login page as much as they want, within reason.)

The solution uses nginx’s map directive to create a conditional rate limit key:

map $request_method $login_limit_key {
    GET     "";                      # Empty key = no rate limit
    default $binary_remote_addr;     # Rate limit all other methods
}
limit_req_zone $login_limit_key zone=login:10m rate=5r/m;

When the key is empty, nginx skips rate limiting entirely. Users can refresh the login page as much as they want. But POST requests (and PUT/PATCH/DELETE for defense in depth) get limited to 5 per minute per IP.

Here’s the complete flow with HTTP method detection:

Why Not Just POST?

You could limit only POST requests specifically. But I prefer limiting all methods except GET—a “deny by default” approach that aligns with zero-trust security principles:

• Security-first: Block everything, then explicitly allow what’s safe (GET). If you forget to block a method, it’s already blocked
• Future-proofing: If your app adds alternative auth methods (PUT for API tokens, PATCH for password updates), they’re automatically protected
• Non-standard clients: Some HTTP clients behave unexpectedly
• Zero overhead: The performance difference is negligible

The worst case with POST-only limiting is an attacker using PUT instead—and slipping through. With “deny by default,” you’ve already blocked it.

The Full NixOS Configuration

Here’s my actual configuration running in production:

services.nginx = {
  appendHttpConfig = ''
    # Standard rate limiting zone for general API protection
    limit_req_zone $binary_remote_addr zone=api:10m rate=30r/s;
    limit_req_status 429;  # Return 429 instead of 503

    # Login endpoint rate limiting - all methods EXCEPT GET
    map $request_method $login_limit_key {
      GET     "";
      default $binary_remote_addr;
    }
    limit_req_zone $login_limit_key zone=login:10m rate=5r/m;
  '';

  virtualHosts."app.example.com" = {
    # Stricter rate limiting for login endpoint
    locations."/api/auth/login" = {
      proxyPass = "http://127.0.0.1:8080";
      extraConfig = ''
        # Nginx locations are mutually exclusive - this location won't inherit
        # rate limits from "/". We need both zones here.
        limit_req zone=login burst=3 nodelay;  # Strict for POST/PUT/PATCH/DELETE
        limit_req zone=api burst=20 nodelay;   # Standard limit for GET
        limit_conn conn_limit 5;
      '';
    };

    # General API rate limiting for all other endpoints
    locations."/" = {
      proxyPass = "http://127.0.0.1:8080";
      extraConfig = ''
        limit_req zone=api burst=100 nodelay;
        limit_conn conn_limit 50;
      '';
    };
  };
};

Watch Out: Location Mutual Exclusivity

Here’s something to keep in mind: nginx locations are mutually exclusive. When a request matches /login, it does NOT inherit rate limits from the / location. If you have a general rate limit on / and expect it to apply to /login too, that is not how it works.

From the nginx documentation: once a location is selected, only that location’s directives apply. This means login endpoints need their own complete rate limiting configuration—both the strict login zone AND any general API rate limiting you want.

The key settings:

The nodelay option is important. Without it, nginx queues excess requests and processes them at the rate limit. With nodelay, requests beyond the burst are immediately rejected. For login endpoints, you want fast feedback—don’t make attackers wait.

Finding the Right Endpoint

Do make sure you are limiting the correct endpoint, so avoid rate limiting /login when the actual authentication happens at /api/auth/login.

Different applications use different endpoints:

So test if you have the right endpoint.

Layered Defense with fail2ban

Rate limiting is your first line of defense. But what about persistent attackers who keep trying after hitting the limit?

Enter fail2ban. It monitors nginx’s error log for rate limit violations and bans repeat offenders at the firewall level:

services.fail2ban.jails.nginx-limit-req = ''
  enabled = true
  port = http,https
  backend = systemd
  journalmatch = _SYSTEMD_UNIT=nginx.service + _COMM=nginx
  maxretry = 5
  bantime = 1h
'';

The escalation path:

1. First few violations → nginx returns 429
2. 5+ violations → fail2ban blocks the IP entirely for an hour

This prevents attackers from even consuming nginx resources after repeated attempts.

The WebSocket Exception

One gotcha: some applications use WebSocket for authentication. Uptime Kuma, for example, uses Socket.io for its login flow. nginx HTTP rate limiting can’t protect WebSocket connections.

For these cases:

• Enable 2FA (essential—this is your primary protection)
• Use connection limiting (limit_conn conn_limit 5)
• Strong, unique passwords
• fail2ban if the application logs failed attempts

Testing Your Setup

Before congratulating yourself, verify it actually works:

# Should see 401/403 for first ~4 requests, then 429
for i in {1..8}; do
  code=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
    https://app.example.com/api/auth/login \
    -H "Content-Type: application/json" \
    -d '{"username":"test","password":"test"}')
  echo "Request $i: HTTP $code"
done

Expected output:

Request 1: HTTP 401
Request 2: HTTP 401
Request 3: HTTP 401
Request 4: HTTP 401
Request 5: HTTP 429
Request 6: HTTP 429
...

And verify GET isn’t affected:

# Should never see 429
for i in {1..10}; do
  code=$(curl -s -o /dev/null -w "%{http_code}" -X GET https://app.example.com/login)
  echo "GET $i: HTTP $code"
done

When Not to Use This

This pattern works well for traditional form-based login, but consider alternatives for:

• Shared IP environments: This setup limits by IP address. If many users share the same IP (corporate networks, universities, mobile carriers with CGNAT), one user’s failed attempts can lock out everyone. For public-facing apps with diverse users, consider rate limiting by username instead, or use a combination of both.
• API token authentication: Rate limit the token generation endpoint, but tokens themselves should be validated per-request without rate limiting
• OAuth flows: The redirect dance makes simple rate limiting tricky—consider rate limiting the callback URL instead
• High-traffic public APIs: You’ll need more sophisticated rate limiting (by user, by endpoint, tiered limits)

For self-hosted applications where you control the user base, IP-based limiting works well. For public apps with users behind corporate firewalls or mobile networks, you’ll want something smarter.

The Result

My Umami analytics and GlitchTip error tracking now have proper brute-force protection. Legitimate users can refresh the login page freely. Attackers get rate limited after 5 attempts, and blocked entirely after persistent abuse.

Total configuration: about 20 lines of NixOS config. Time to implement: 30 minutes.

Resources

• nginx Rate Limiting - Official NGINX blog with detailed examples
• ngx_http_limit_req_module - Official module documentation
• fail2ban nginx-limit-req filter - Built-in filter for nginx rate limit violations
• nginx map directive - For conditional rate limiting
• Umami - Privacy-focused, self-hosted web analytics
• GlitchTip - Open-source error tracking and uptime monitoring

How do you handle login rate limiting? Found edge cases I didn’t cover? I’d love to hear about it—get in touch.

I’ve been working on extending my claude-config-template with a simple UI. The idea was to make it easier to manage Claude workflows - visual task boards, quick command access, that sort of thing. I looked at existing solutions like Auto-Claude and Vibe Kanban, and while they’re interesting projects, neither quite fit what I needed.

Auto-Claude focuses on autonomous multi-agent orchestration - running a lot of agents in parallel with isolated workspaces. Interesting, but in my experience handling more than 1 complicated and 1 simple process at the same time is taxing my capabilities. Also it is quite new, so there was some trouble getting it to work (I failed). I looked at the code and the errors and there is a lot of AI generated stuff in there, including the common slop that seems to hinder a lot of current projects. So then Vibe Kanban came on my radar: it is a kanban board for managing AI coding agents. Also great, but I wanted something that integrated tightly with my existing slash commands and documentation structure without adopting a new paradigm.

So I started building my own. A few hours later, I had a FastAPI backend and a simple frontend working. Then I got on a sidequest: choosing ports for the backend and frontend servers that wouldn’t conflict with anything else on my machine. This is surprisingly tricky, so I decided to document my findings.

The Port Problem

My backend defaulted to 8000. Fastapi uses uvicorn which defaults to port 8000. So far no problem. But the idea is to import and install this project in other environments as well, so I wanted to avoid common ports. Quite annoying if you install this and first you’ll have to sort a port conflict. Same goes for 5173 (Vite) or 3000 (React, Next.js). And there are many more common ports that developers use for various frameworks and databases. So what is a safe choice? Lets dive in.

The Three Port Ranges

Ports aren’t just random numbers. They’re organized by IANA (Internet Assigned Numbers Authority):

Conclusion 1: stick to the 1024-49151 range for development servers. Seems plenty of room there.

Ports You Should Avoid

Then the ports that are commonly used by a lot of stuff: these were out of the question, since they will conflict with something on your machine:

The macOS AirPlay thing on port 5000 was new to me (never use airplay or Flask) but i found quite some stuff about it. Apparently you’ll see “address already in use” and spend 20 minutes debugging your Flask app before realizing it’s your laptop’s screen sharing feature. It was some time ago I used Flask, but do not remember this conflict back then. Anyway, avoid 5000 on macOS.

So What Should You Use?

After going through IANA registrations and Wikipedia’s comprehensive list (especially the Wikipedia page is a treasure trove, I ran into protocols and games I only heard once of a long time ago), I learned something important: there’s no such thing as a truly “free” port. Every port in the registered range has something using it somewhere.

Take the memorable patterns I initially gravitated toward:

• 5678 is the default for n8n, the workflow automation tool
• 8765 is used by GUN relay peers—decentralized storage that the Internet Archive uses for censorship-resistant mirroring

But here’s the thing: how many developers run n8n or GUN relay peers locally during active development? Probably fewer than those running React, Vite, or a database. The goal isn’t finding a port that’s never been used by anything—it’s finding one that’s unlikely to conflict with tools in your daily workflow.

An even safer option (slightly lower chance of conflict):

Backend:  9118
Frontend: 8119

Technically these aren’t completely free either: 9118 is the Prometheus Jenkins exporter, and 8119 is used by macos-fortress-proxy for CSS blocking. But these are monitoring tools, not something you’d typically run on a development machine. Less memorable than the sequential patterns, but about as safe as you’ll find.

Truly unused (if you want zero documented uses):

Backend:  9143
Frontend: 6234

To find these, I searched IANA’s registry for unassigned port ranges, then verified each candidate against SpeedGuide’s port database and Google to check for unofficial uses. Port 9143 is in the unassigned 9132-9159 range, and 6234 is in the unassigned 6223-6240 range. Neither has any registered service—official or unofficial—that I could find. Not memorable at all, but if you want guaranteed zero conflicts, here you go.

I’m sticking with 9118/8119—the memorable patterns are worth the tiny risk (and I do run n8n locally sometimes). But now please do not pick these ports for your projects, otherwise we’ll have conflicts again!

What I’m Building

Back to the actual project: a simple UI layer for my claude-config-template. The idea is straightforward - a local web interface that makes it easier to manage Claude workflows without memorizing slash commands or digging through documentation.

The backend (FastAPI on port 8765) handles the orchestration logic I already built for the template. The frontend (Vite on port 5678) provides a visual interface for:

• Launching slash commands with a click instead of typing
• Viewing task progress and agent output in real-time
• Managing the thoughts directory and documentation structure
• Quick access to plans, research, and project context

Nothing fancy. No multi-agent swarms or parallel execution complexity. Just a thin UI layer that makes my existing workflow more accessible. Sometimes simple tools that fit your workflow beat sophisticated ones that don’t.

I’ll write more about the implementation once it’s stable enough to share. The repo is archived for now while I clean things up, but I’ll unarchive it soon with a proper release post. For now, at least the ports won’t conflict with anything.

Resources

• IANA Service Name and Transport Protocol Port Number Registry - The official list
• List of TCP and UDP port numbers - Wikipedia - More readable reference
• SpeedGuide Port Database - Search by port number

What ports do you use for development? Found other conflicts I didn’t mention? I’d love to hear about it—get in touch.

Why Now?

I knew this kind of automation was possible from the start, but I deliberately waited. The underlying tools - the slash commands, the agents, the workflows - needed to prove themselves first. After give or take six months of daily use, testing edge cases, fixing bugs, and refining prompts, I trust them enough to let them run without supervision.

Are they perfect? Far from it. But they’re reliable enough for routine tasks. And that’s the threshold for automation: not perfection, but predictable behavior. When I know what the tools will do in common scenarios, I can confidently chain them together.

The Problem with Manual Orchestration

If you’ve read my previous post about the config template, you know I use a structured workflow: research the codebase, create a plan, implement it, then review. This pattern works well, but it requires babysitting. Each slash command might ask questions. You need to wait for completion. Copy file paths between steps.

For routine tasks - adding a feature you’ve spec’d out, fixing a well-understood bug - this manual coordination adds unnecessary overhead. What I wanted was to say “do this task” and come back to reviewed code.

The Nesting Problem

Here’s the challenge: Claude Code already has subagents. So why not just create an orchestrator agent that spawns other agents? Because of a fundamental limitation in Claude’s architecture: subagents cannot spawn other subagents.

This is probably by design, to limit resource usage. But it means you can’t build a meta-agent in Claude that coordinates other agents which might themselves need to spawn agents. The codebase-researcher agent, for instance, uses multiple specialized subagents internally. An orchestrator built as a Claude agent couldn’t call it without breaking the nesting rule.

The solution? Use an external LLM as the orchestrator. It doesn’t live inside Claude’s context, so it can spawn Claude Code instances without violating any nesting constraints.

How It Works

The orchestrator (claude-helpers/orchestrator.py) is a Python script that chains Claude Code slash commands together:

uv run claude-helpers/orchestrator.py "Add user authentication with JWT tokens"

This kicks off five sequential operations:

1. /index_codebase - Map out the project structure
2. /research_codebase - Investigate existing patterns and relevant code
3. /create_plan - Generate an implementation plan
4. /implement_plan - Execute the plan
5. /code_reviewer - Review the changes

Each step feeds into the next. The orchestrator extracts file paths from Claude’s output and passes them as context to subsequent commands. When Claude asks questions (which it does, especially during planning), the orchestrator uses OpenAI’s API to generate appropriate responses.

Why OpenAI?

You might wonder why not use Claude for the orchestration decisions too. Two reasons:

1. No nesting constraint - OpenAI doesn’t have the same architectural limitation, so it can coordinate without restrictions
2. Different strengths - The orchestrator needs to parse Claude’s output and make quick decisions about how to respond. It doesn’t need Claude’s deep reasoning or large context window

The orchestrator supports both OpenAI and Azure OpenAI. It reads configuration from .env.claude and auto-detects which service to use based on which environment variables are set.

Practical Usage

For a straightforward feature:

uv run claude-helpers/orchestrator.py "Add rate limiting to the API endpoints"

For exploratory work where you want to review the plan before committing:

uv run claude-helpers/orchestrator.py --no-implement "Redesign the caching layer"

For CI/CD integration:

uv run claude-helpers/orchestrator.py --json "Fix the failing payment tests" > result.json

The --json flag structures the output for parsing. The --no-implement flag stops after the planning phase - useful when you want human review before the LLM touches code.

Implementation Details

The script is built with uv for dependency management. First run automatically installs dependencies - no setup required. It uses subprocess to spawn Claude Code instances and streams output in real-time to stderr, so you see progress as it happens.

One design choice: the orchestrator is intentionally simple. It doesn’t try to be clever about which steps to skip or how to parallelize. It runs the full workflow every time. Why? Because the overhead of making smart decisions often exceeds the cost of just doing the work. And consistency matters - I always want research before planning, always want review after implementation.

When Not to Use It

The orchestrator is for routine tasks where the workflow is predictable. For exploratory work, complex debugging, or tasks requiring back-and-forth discussion, you still want to run commands manually. The human in the loop isn’t just about reviewing output - it’s about steering the process when things get complicated.

Also, be aware of cost. Running five Claude Code commands per task adds up. For small fixes, it’s probably overkill. For substantial features where you’d run those commands anyway, it saves time without changing cost much.

What’s Next

The main question now is reliability. How often does the orchestrator produce usable results without intervention? I need to track this systematically - not just “it works” but failure modes, edge cases, and where human review catches issues the automation missed.

The code review step is particularly interesting. As I wrote in my previous post about human-in-the-loop review, LLM-generated reviews miss certain classes of problems - especially meta-level issues like tests that test whether tests exist. A colleague spotted that instantly; multiple LLM passes missed it entirely. So how do I make the automated review more effective? Different prompting? Multiple review passes with different perspectives?

I’m hesitant to add complexity before understanding the baseline. The value is in automation, not optimization. A simple tool that runs reliably beats a complex one that sometimes does the wrong thing.

Try It Out

The orchestrator is included in the latest version of claude-config-template. After installation:

# Make sure you have uv installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Set up your OpenAI (or Azure OpenAI) credentials in .env.claude
echo "OPENAI_API_KEY=your-key" >> .env.claude

# Run it
uv run claude-helpers/orchestrator.py "Your task description"

The pattern of research→plan→implement→review has served me well. Now it runs without me having to shepherd each step. That’s the kind of automation that actually helps.

Resources

• Claude Code Subagents Documentation - Official docs on subagent capabilities and limitations
• Claude Code Best Practices - Anthropic’s engineering guide
• claude-config-template - The full configuration system
• OpenAI Cookbook - Examples and guides for building with OpenAI
• PydanticAI - Agent framework for building production-ready AI applications

Are you automating your AI-assisted workflows? What patterns have you found useful? I’d love to hear about your experiences—get in touch.