DEV Community: Alberto Barrago

Telemaco: a headless Rust browser engine

Alberto Barrago — Tue, 08 Sep 2026 07:39:51 +0000

Telemaco is a headless browser engine I've been building in Rust. It runs real JavaScript through V8, keeps a real DOM tree, owns its own layout and paint pipeline, and speaks the Chrome DevTools Protocol, so Puppeteer and Playwright connect to it out of the box. No Chromium, no WebView, no 300 MB download. A 70 MB binary that starts instantly and loads a page in ~85 ms.

This is the story of how it came to be, why it exists, and the choices that shaped it.

The problem: Chromium as a tax

For years, "headless browser" has meant one thing: headless Chrome. It works, but it carries a cost you only notice when you scale it.

The download. Every CI runner, every fresh container, every teammate's laptop pulls a ~300 MB Chromium. Playwright and Puppeteer make this painless, which is exactly why nobody questions it.
The memory. A single headless Chrome instance idles at 200+ MB. Spin up a few for parallel scraping and you're budgeting RAM like it's 2010.
The startup. Two seconds to launch before you've even loaded a page.
The fingerprint. Headless Chrome is trivially detectable. If you're scraping anything that cares, you're already fighting an anti-bot arms race.

None of this is inherent to the job. A browser engine is a parser, a DOM, a layout engine, a paint pipeline, and a JS runtime. Chromium is one very heavy way to assemble those pieces. I wanted a lighter one.

The need that started it

Two concrete needs drove the project.

First, efficient web search and extraction. I work with colleagues who spend their days pulling structured data out of the web, like Salesforce records, MDN docs, product pages. The tooling for that is either a raw HTTP client (which can't run JavaScript) or a full browser (which is overkill). There was no middle ground: something that runs real JS and a real DOM, but is small enough to treat as a utility, not an infrastructure project.

Second, end-to-end tests without Chromium. If you've ever run a Playwright suite in CI, you know the drill: download the browser, hope the sandbox flags are right, watch the memory climb. I wanted the same CDP automation surface, the same page.goto, the same page.evaluate, but backed by something that doesn't need a browser install at all. A single binary that is the browser.

Standing on the shoulders of many projects

I didn't want to reinvent a browser from scratch, and I didn't have to. The Rust ecosystem has quietly assembled most of the pieces, and Telemaco is deliberately built on top of them.

Servo's components: html5ever for HTML parsing, selectors for CSS matching, cssparser, servo_arc. The DOM and CSS machinery that Mozilla's research browser spent years hardening.
taffy for the layout engine, a pure-Rust flexbox/grid layout library.
tiny-skia for rasterization and ab_glyph for glyph rendering, the paint pipeline, also pure Rust.
V8 through deno_core for JavaScript. Real V8, the same engine Chrome uses, so JS semantics are exactly what you expect.
chromiumoxide and the Chrome DevTools Protocol for the automation surface.

The project started as a fork of Obscura (Apache-2.0), a headless browser engine by h4ckf0r0day. That's the honest origin: I didn't start from a blank page, I started from a solid foundation and took it in a different direction. The crate names changed, the CLI surface changed, the project identity changed, and the codebase was adapted and extended for a practical, scraping- and agent-oriented focus. The attribution is in the repo's NOTICE file; this is a derivative work, and it says so.

The architecture

Telemaco is a workspace of nine crates, one layer per crate, with cross-crate calls going through the layer above rather than sideways:

Crate	Role
`telemaco-cli`	CLI: `fetch`, `serve` (CDP server), `scrape`, `mcp`
`telemaco-cdp`	Chrome DevTools Protocol server (WebSocket)
`telemaco-js`	V8/`deno_core` runtime; DOM shim + JS/Rust bridge
`telemaco-dom`	DOM tree
`telemaco-net`	HTTP client, stealth client, cookie jar, robots cache, tracker blocklist
`telemaco-browser`	The `Page` type, navigation, JS evaluation
`telemaco-render`	Selector cascade, retained layout, paint, screenshots, PDF
`telemaco-mcp`	Stateful MCP automation tools
`telemaco`	Embeddable Rust library API

A few invariants shaped the whole design:

One V8 isolate per process. V8 is !Send, so all async runs on a tokio LocalSet, and every JS op goes through a single global lock. It serializes JS execution, which is fine for a browser engine; the DOM is single-threaded anyway.
One bad page must never hang a worker. There's a V8 termination watchdog per page and a process-level hard deadline. A page that spins in an infinite loop gets killed, not the worker.
SSRF by default. Loopback, RFC1918, and link-local fetches are blocked unless you explicitly pass --allow-private-network. A scraping tool that can reach your internal network is a liability; this closes it by default.

What it looks like

Fetch a page and run real JavaScript:

$ telemaco fetch https://news.ycombinator.com --eval "document.title"
Hacker News

Drive it like headless Chrome, from Puppeteer:

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser',
});
const page = await browser.newPage();
await page.goto('https://news.ycombinator.com');

const stories = await page.evaluate(() =>
  Array.from(document.querySelectorAll('.titleline > a'))
    .map(a => ({ title: a.textContent, url: a.href }))
);

Scrape many URLs in parallel:

$ telemaco scrape url1 url2 url3 --concurrency 25 --format json

And for AI agents, there's an MCP server that exposes the same browser to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "telemaco": { "command": "telemaco", "args": ["mcp"] }
  }
}

The numbers

Metric	Telemaco	Headless Chrome
Memory	30 MB	200+ MB
Binary size	70 MB	300+ MB
Page load	85 ms	~500 ms
Startup	Instant	~2 s
Anti-detect	Built-in	None
Puppeteer / Playwright	Yes	Yes

Roughly 12x faster page loads and 6x less memory on framework pages, with the same CDP automation surface.

Why "Telemaco"

The name is the son of Odysseus, the one who sets out to find news of his father. A searcher, by definition. It felt right for a tool whose whole job is to go out and bring back what's on the web.

Not a product, a direction

Telemaco isn't trying to sell anything. It's a different vision of what a browser engine can be: small enough to be a utility, fast enough to be a tool, and honest about where it comes from. It's built on the work of a lot of respected projects and people, like Servo, taffy, tiny-skia, deno_core, Obscura, and it's open source under Apache-2.0, so anyone can take it and point it at their own problem.

If you've ever wished your scraping or your e2e tests didn't require a browser install, that's the itch it scratches. Clone it, build it, drive it.

Landing page: albz.it/telemaco
Source: github.com/AlbertoBarrago/telemaco

I Built a CLI to Answer One Question: What Will This Change Break?

Alberto Barrago — Thu, 27 Aug 2026 16:03:12 +0000

We've all been there.

You open a repository, change a file that looks completely harmless, run the tests, and open a pull request.

Then someone comments:

“Careful. That module is also used by the billing pipeline.”

Or worse, nobody notices.

The change gets merged.

And something breaks.

The problem isn't necessarily bad code. In large or unfamiliar codebases, understanding the blast radius of a change is surprisingly difficult.

So I started building Serval.

Serval is a local-first CLI that tries to answer one simple question:

If I change this file, what am I likely to affect?

The problem

When I want to understand the impact of a change, I usually end up doing some combination of:

rg "someModule"
git log
git blame

Then I inspect imports, search CI configuration, check which files usually change together, and rely on whatever knowledge I have about the repository.

That works.

But it is mostly manual.

And on a repository you don't know well, a large part of the process becomes guesswork.

I wanted something closer to:

serval inspect src/auth/token.ts

and get:

Target
  src/auth/token.ts

Direct impact
  src/auth/middleware.ts

Indirect impact
  src/api/client.ts

CI
  integration-auth.yml

Git history
  7 significant changes
  3 frequently co-changed modules

Risk
  HIGH: 82/100

  +28  14 downstream modules
  +20  critical path
  +14  high historical churn
  +12  frequently co-changed modules
  +8   CI workflow affected

Not a prediction.

Not:

"AI thinks this change might be dangerous."

Evidence.

Four signals instead of one

Looking only at imports isn't enough.

A dependency graph can tell me:

A -> B -> C

If I change C, I know that B and potentially A are affected.

Useful.

But repositories contain more information than their dependency graph.

1. Dependency graph

Serval scans the repository and builds a graph from language-native dependencies.

It currently understands repositories containing:

JavaScript / TypeScript
Go
Python
Java
C

For a target file, Serval walks the graph in the opposite direction and calculates its dependents.

That gives us the structural blast radius.

But structure is only the first signal.

2. Git history

Git contains something surprisingly close to the memory of a codebase.

If two files repeatedly change together, that's information.

If a module has been modified constantly during the last few months, that's information too.

So Serval looks at things like:

historical churn
co-change frequency

Imagine two files with identical dependency graphs.

One hasn't changed in two years.

The other changed nine times during the last 90 days and frequently changes together with 15 other modules.

Those files probably shouldn't receive the same risk score.

3. CI configuration

Then there is another graph hiding inside most repositories:

CI/CD.

A change can trigger integration tests, builds, deployments or validation pipelines depending on path filters.

Serval currently understands configuration from:

GitHub Actions
GitLab CI
Azure Pipelines
Jenkins

This gives another useful piece of evidence:

Which automation does this change actually touch?

4. Critical paths

Some parts of a system simply deserve more attention.

Authentication is not the same as changing a README.

Payment logic is not the same as changing a CSS utility.

Serval therefore allows repository-specific critical-path rules through .serval.yml.

Again, this isn't trying to prove that something will break.

It is accumulating evidence that says:

You should probably look at this change more carefully.

Why the score is deterministic

This became one of the most important design decisions in the project.

It would have been extremely easy to send the repository context to an LLM and ask:

"How risky is this change from 0 to 100?"

I deliberately didn't do that.

The core score produced by Serval is deterministic.

The same repository state and configuration produce the same result.

More importantly, every point can be explained.

Something like:

Risk
  MEDIUM: 38/100

  +4   2 downstream modules
  +14  high historical churn
  +12  91 frequently co-changed modules
  +8   2 CI workflows affected

There is no hidden reasoning behind 38.

You can audit it.

You can disagree with it.

You can change the configuration.

But you can understand where it came from.

For engineering tooling, I think that property matters.

So... no AI?

Not exactly.

Serval does support AI explanations.

For example:

serval inspect src/auth/token.ts --explain

The interesting part is the boundary.

The AI cannot change the score.

It only receives the deterministic analysis and explains it in natural language.

And because Serval is local-first, the default provider can be a local Ollama instance.

Other providers can be used through locally installed CLIs such as Claude, Codex or Gemini.

I like this architecture much more than putting an LLM at the center of the system:

repository
    ↓
deterministic analysis
    ↓
risk model
    ↓
result
    ↓
optional AI explanation

The model explains evidence.

It doesn't invent the evidence.

Local-first was intentional

Serval doesn't require:

an account
a SaaS backend
uploading your repository
an API key for its core functionality

The analysis happens locally.

That matters for developer tooling because the repository already contains everything needed for most of the analysis:

source code
Git history
CI configuration
repository configuration

Why send all of that somewhere else if we can calculate the answer locally?

It can also become a CI gate

The same analysis can run against your current diff:

serval diff

or produce machine-readable output:

serval diff --json

And this makes another use case possible:

serval diff --fail-on high

If one of the changed files reaches HIGH risk, Serval exits with a non-zero status.

That means the tool can move from:

"interesting information for the developer"

to:

"a deterministic signal inside the delivery pipeline."

I'm particularly interested in exploring this direction.

Not as another quality gate that randomly blocks developers, but as a way to make the expected impact of a change visible before merge.

Installing it

Serval is written in Go and distributed through Homebrew.

brew install AlbertoBarrago/tap/serval

Then, inside a Git repository:

serval inspect path/to/file

or simply:

serval path/to/file

There are also commands for inspecting the graph and history directly:

serval graph path/to/file
serval history path/to/file
serval doctor

And because I have a soft spot for old-school CLI tooling:

man serval

exists too.

What I'm trying to explore

Serval is still young.

I'm less interested in pretending that a 0–100 score can magically predict whether software will break and more interested in a different question:

How much useful information about change risk is already sitting inside our repositories?

Dependency graphs tell us what is connected.

Git tells us what historically moves together.

CI tells us what operational machinery is affected.

Repository rules tell us which areas deserve additional attention.

None of these signals is particularly revolutionary on its own.

Combining them into a small, local, explainable tool is the experiment.

And perhaps that's also where AI fits best in this kind of developer tooling:

not replacing deterministic analysis,

but sitting on top of it when natural-language reasoning is useful.

Serval is open source and MIT licensed.

Project: https://albz.it/serval/

Source: https://github.com/AlbertoBarrago/serval

If you work on large repositories, monorepos, legacy systems, or CI-heavy projects, I'd be particularly interested in hearing what signals you use before touching an unfamiliar part of the codebase.

NEON INVADERS

Alberto Barrago — Tue, 21 Jul 2026 16:34:36 +0000

Enjoy

AlbertoBarrago / neon-invaders

A synthwave arcade shooter built with strict TypeScript, HTML5 Canvas, and zero runtime dependencies.

Neon Invaders

A synthwave invasion. Four enemy classes. One ship. No mercy.

A fast, fullscreen arcade shooter inspired by Space Invaders, rebuilt around fluid movement, escalating enemy behavior, procedural audio, and excessive neon.

Play Neon Invaders

Why it feels different

Fluid formations — enemies descend with layered sine-wave drift instead of rigid grid steps.
Four enemy classes — grunts, armored tanks, kamikaze divers, and multi-pattern bosses.
Escalating pressure — every wave increases movement speed, fire rate, formation size, and dive frequency.
Four power-ups — triple shot, full-height laser, timed invulnerability, and five-second bullet time.
Combo scoring — chain kills to raise the multiplier; completely missing a volley breaks it.
Local arcade leaderboard — enter three initials after a qualifying run and keep a persistent top 10.
Arcade-grade feedback — hit-stop, screen shake, impact sparks, explosions, engine trails, glow, and subtle CRT scanlines.
Procedural soundtrack — synthwave bass, arpeggios, drums…

View on GitHub

Introducing TimeLog: A Native Time Tracker for iOS and macOS

Alberto Barrago — Thu, 25 Jun 2026 15:33:33 +0000

TimeLog started from a very simple email at work:

“Reminder to register working hours.”

That was enough to make me think about the way I track my time every day.

I work mostly in the Apple ecosystem, so I wanted something that could fit naturally into my daily workflow: immediate, quiet, and almost invisible.

A tool that could accompany my work instead of interrupting it.

From Many Ideas to Fewer Features

At the beginning, I had a lot of ideas.

Advanced tracking, analytics, synchronization, automations, integrations, reports, smart workflows, and probably a few more things that sounded useful on paper.

But over time, something interesting happened.

Instead of adding more features, I kept removing them.

And eventually, TimeLog became exactly that: a tool that does a few things, but tries to do them well.

What TimeLog Does

TimeLog is a native time tracking app for iOS and macOS, designed around simplicity and daily use.

It currently focuses on:

automatic tracking by client and project
calendar-based consultation
Pomodoro and stopwatch modes
time usage statistics
data sharing by email
a native macOS experience
a mobile version for iOS

The goal is not to build the most complex time tracking platform possible.

The goal is to make time tracking feel natural.

Built for the Apple Ecosystem

TimeLog is built with SwiftUI and SwiftData.

One of the things I cared about from the beginning was making the app feel native on each platform.

The macOS version is not just a stretched mobile interface. It is designed around desktop workflows, with native macOS patterns and quick access from the system environment.

The iOS version follows a more mobile-first interaction model, with a simpler and more direct flow.

Both versions share the same core idea: tracking time should require as little friction as possible.

Simplicity as a Product Decision

I think it is very easy to add complexity to software.

It is much harder to remove things without losing value.

That has probably been the most interesting part of building TimeLog so far.

Every feature has to justify its presence. If it makes the app feel heavier, slower, or more distracting, it may not belong there.

The best feature of TimeLog might be everything I decided not to add.

At least for now.

What I Learned

Building TimeLog has been a useful reminder that product development is often more about subtraction than addition.

Some lessons that stood out:

native platform conventions matter
small tools should stay focused
not every useful idea deserves to become a feature
time tracking should be fast enough to disappear into the workflow
simplicity is not the absence of design, it is a design constraint

What’s Next

I am considering future integrations with third-party services to push time entries into external systems.

One possible example is Wethod, since it would make sense to connect TimeLog with existing work reporting workflows.

I am also looking for more feedback, especially on the mobile version. It exists, but since it is not published on the App Store yet, I have not received much real-world feedback from iOS users.

Closing

TimeLog started from a small reminder about logging work hours.

It became an attempt to build a focused, native, Apple-platform time tracker that respects the way people actually work.

You can check out the presentation page here:

https://albz.it/Timelog/

I’ll keep sharing updates as the project evolves.

AI Doesn't Read Your Mind. It Reads Your Trail.

Alberto Barrago — Wed, 24 Jun 2026 17:40:01 +0000

AI Doesn't Read Your Mind

It only feels that way because it's become incredibly good at predicting where your thoughts are going.

Every day I see more people approaching AI as if it were magic.

They ask a question.

The model responds with something surprisingly relevant.

A few messages later, they start talking about AI as if there were a tiny genius hidden behind the screen.

There isn't.

And the truth is far more interesting.

The Great Illusion

Large Language Models don't read minds.

They don't know your intentions.

They don't understand your emotions.

They don't have access to your thoughts.

What they do is something much simpler:

They predict.

They analyze patterns.

They estimate probabilities.

They generate the next most likely sequence of tokens based on the context you've provided.

The result can be so convincing that it creates the illusion of understanding.

But an illusion is not magic.

Why It Feels Like Mind Reading

Years ago I became fascinated by some concepts from Neuro-Linguistic Programming (NLP).

One idea stood out to me.

Some communicators seem capable of knowing what you're about to say before you've said it.

At first glance it looks like mind reading.

In reality, they're observing signals.

Body language
Tone of voice
Word choices
Repeated patterns
Emotional reactions

They're not reading minds.

They're reading clues.

The digital world works in a surprisingly similar way.

AI Reads Your Trail

Every interaction leaves traces behind.

When you talk to an AI, you're constantly providing signals:

The words you choose
The questions you ask
The corrections you make
The examples you provide
The assumptions you reveal

The model isn't reading your mind.

It's reading your trail.

And modern models have become exceptionally good at predicting where that trail is heading.

That's what often feels like intelligence.

That's what sometimes feels like understanding.

And that's what many people mistake for magic.

The Skill Everyone Talks About

Today everyone talks about prompting.

Prompt engineering.

Prompt frameworks.

Prompt tricks.

Prompt hacks.

Prompting matters.

But I don't think it's the most important skill of the AI era.

Not even close.

The Skill Nobody Talks About

The real skill is becoming a better:

Reviewer
Orchestrator
Architect
Editor
Decision maker

The people who get the most value from AI won't be the people who trust every answer.

They'll be the people capable of challenging answers.

The people who can identify weak reasoning.

The people who can separate confidence from correctness.

The people who understand that generating information is not the same thing as generating value.

AI Is Still A Tool

Throughout my career I've learned a simple lesson:

A tool remains a tool.

Linux is a tool.

Git is a tool.

Docker is a tool.

Kubernetes is a tool.

AI is a tool.

An extraordinarily powerful one.

Possibly the most powerful tool many of us have ever used.

But still a tool.

The danger begins when we stop using it and start worshipping it.

Why Humans Still Matter

People often ask whether humans will remain relevant.

I think the question misses the point.

The value of humans was never memory.

It was never calculation speed.

It was never information retrieval.

The uniquely human contribution is something else:

Creative judgment.

Creativity is more than prediction.

Creativity is deciding that the most probable answer isn't the most interesting one.

It's connecting ideas that don't naturally belong together.

It's challenging assumptions.

It's imagining something that doesn't exist yet.

The Future

The future doesn't belong to people who compete with AI.

The future belongs to people who learn how to direct it.

To challenge it.

To review it.

To orchestrate it.

To use it without becoming dependent on it.

Because behind every meaningful invention there is still something no model can fully automate:

A human being deciding to create.

And that act is far more important than any prediction.

Back To Fundamentals

Ironically, the rise of AI is pushing me back toward old-school engineering skills.

Reading source code.

Understanding systems.

Questioning assumptions.

Knowing how things work beneath the abstraction.

The better AI becomes at generating code, the more valuable it becomes to understand whether that code is actually correct.

We're not moving away from engineering fundamentals.

We're moving back to them.

Just with better tools.

Final Thought

AI is not magic.

AI is not consciousness.

AI is not reading your mind.

AI is the most sophisticated prediction engine humanity has ever built.

What you do with those predictions is still up to you.

The future belongs neither to AI nor to humans alone.

It belongs to humans who know how to think while using AI.

Enjoy, and give me some feedback ^^

Alberto Barrago — Thu, 16 Apr 2026 07:41:11 +0000

Alberto Barrago

Apr 9

I Built My Own Diagramming Tool

#showdev #javascript #sideprojects #webdev

1 min read

I Built My Own Diagramming Tool

Alberto Barrago — Thu, 09 Apr 2026 14:57:26 +0000

Hey! I’ve been working on Markasso, a lightweight drawing and diagramming tool. Built entirely from scratch with vanilla JS and Canvas 2D API. No frameworks, no libraries, nothing.

Why I built it: In this AI era where you can generate anything in seconds, I wanted to actually build something myself from the ground up. Understand (or try to do it) every line, every pixel, every math formula behind it.

My grandmother was a math teacher so I guess the stubbornness runs in the family, but I’ll be honest, Claude helped me a lot when the geometry got tricky and Lorenzo Cataldi with the UI.

Everything is hand-rolled: pure Canvas API (no SVG), a Redux-like state management with immutable state and action-based updates, hit detection, bounding boxes, transform handles, undo/redo via action stack. Single user, runs entirely in the browser.

It’s also packed with little things I cared about: full keyboard shortcuts, multi-language support, a magnetic grid for snapping, and custom format export. I wanted it to feel like a real tool, not just a tech demo.

The hardest part was making resize handles feel natural when you’re doing all the geometry yourself.
Once you try building this stuff from scratch you really start to appreciate what the Excalidraw team has done.

Make a trip ^^

Source Code

Would love to hear your feedback, especially on UX and what features you’d want to see next!

Fix: Eliminating Double Async Validation in TanStack Form & Zod

Alberto Barrago — Tue, 17 Feb 2026 18:10:16 +0000

A practical pattern to prevent duplicate API calls and race conditions
in complex React forms.

When building production-grade forms with TanStack Form and Zod,
especially in flows involving side effects (e.g., OTP generation,
user verification), you may encounter an elusive bug:

⚠️ Async validation running twice on submit

This can lead to duplicated API calls, inconsistent state, and poor user
experience.

In this article, we explore: - Why this happens - How to fix it
reliably - How to harden your form logic for real-world scale

🚨 The Problem: Double Async Execution

A known issue in TanStack Issue #1431 causes async
validation (superRefine) to execute multiple times during submission.

Typical Setup

const form = useForm({
  defaultValues: { ... },
  validators: {
    onChange: myZodSchema, // async superRefine
  },
  onSubmit: async ({ value }) => {
    await sendOtp(value); // ❌ may be called twice
  }
});

Why It's Dangerous

In flows like OTP authentication: - Multiple requests generate
different codes - First code becomes invalid - Users get stuck

👉 This is not just inefficiency --- it's a critical UX bug

🧠 Root Cause

TanStack Form may trigger validation multiple times internally
superRefine contains side effects
Validation ≠ Pure function anymore

👉 This breaks the expectation that validation is idempotent

✅ The Solution: Take Back Control

We fix the issue with 3 architectural decisions:

1. Manual Validation with `safeParseAsync`

Avoid relying on automatic validation during submission.

const result = await myZodSchema.safeParseAsync(form.state.values);

✔ Prevents double execution
✔ Gives full control over validation lifecycle

2. Prevent Re-entrancy with `useRef`

React state is not always fast enough to block rapid interactions.

Use a low-level semaphore:

const isSubmittingRef = useRef(false);

3. Decouple Side Effects

Never trigger API calls inside validation.

👉 Validation must remain pure
👉 Side effects go inside controlled submit flow

🧩 Full Implementation

const isSubmittingRef = useRef(false);

const handleSubmit = async () => {
  if (isSubmittingRef.current) return;

  isSubmittingRef.current = true;

  try {
    // 1. Manual validation
    const result = await myZodSchema.safeParseAsync(form.state.values);

    if (!result.success) {
      // map errors if needed
      return;
    }

    // 2. Execute side effect ONCE
    await triggerOtpRequest(result.data);

  } finally {
    isSubmittingRef.current = false;
  }
};

🌐 Network Layer Optimization

During testing, another issue emerged: 👉 unwanted re-fetching
disrupting UX

Fix your QueryClient config:

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000,
      refetchOnWindowFocus: false,
    },
  },
});

Why it matters

Users switch tabs to check OTP
Returning triggers refetch
UI state resets unexpectedly

👉 Disable it for critical flows

🏗️ Production Insights

From a real-world system serving high traffic:

Small validation bugs can scale into massive API waste
Race conditions are often invisible locally
Libraries are not always safe for side-effect-heavy flows

👉 Always design defensively

🔑 Key Takeaways

Validation must be pure
Avoid side effects inside superRefine
Control execution manually
Use safeParseAsync
Prevent race conditions
Use useRef as a semaphore
Tune network behavior
Disable refetchOnWindowFocus when needed

💬 Final Thoughts

If your validation triggers APIs, you are no longer just validating
you are orchestrating stateful workflows.

👉 Treat it like backend logic, not just form validation.

🚀 Discussion

Have you experienced similar issues with async validation or race
conditions in React forms?

Let's discuss 👇

RefAIne: Transform Casual Prompts into Expert-Level AI Instructions

Alberto Barrago — Mon, 05 Jan 2026 22:42:48 +0000

A free, open-source FastAPI microservice that converts simple prompts into detailed, production-ready AI instructions. Supports multiple LLM providers including Claude, OpenAI, Ollama, and Groq.

The Problem

Getting AI assistants to understand exactly what you need often requires multiple iterations. When you ask to "create a REST API," you might get a basic example when you actually need authentication, error handling, validation, and production-ready code.

This gap between brief prompts and detailed requirements costs developers significant time in refinement cycles.

The Solution

RefAIne is a FastAPI microservice (approximately 145 lines) that transforms casual prompts into comprehensive engineering instructions.

Example Input: "make a function to sort a list"

Example Output:

Create a Python function that sorts a list with the following requirements:

Function signature: Accept a list of comparable elements as input

Return a new sorted list (do not modify the original)

Use Python's built-in sorting (efficient O(n log n) Timsort)

Add type hints and docstrings with examples

Include error handling for None or non-list inputs

Handle edge cases: empty list, single element, already sorted

Make it generic to work with any comparable types

Provide clean, PEP 8 compliant code with tests.

RefAIne automatically adds technical context, specificity, best practices, and edge case considerations.

Key Features

Free Testing Options

Test locally with Ollama at no cost before using paid APIs. No credit card or API key required for initial testing.

Multiple Provider Support

Switch between LLM providers using a single environment variable:

Ollama (free, local, private)
Groq (free tier available)
Anthropic Claude (paid)
OpenAI (paid)
Any OpenAI-compatible API

Production Ready

Includes Docker configuration, comprehensive documentation, and environment-based configuration.

Focused Design

Single-purpose service with one endpoint and minimal dependencies.

About the Project

RefAIne was created by Alberto Barrago to automate the prompt refinement process. The project is open-source under the MIT license, allowing use in commercial projects without restrictions.

Supporting Development

RefAIne is free to use and will remain so. However, maintaining open-source software requires ongoing investment:

Server costs for testing and demonstrations
API credits for development across multiple providers
Time for bug fixes, features, and support
Documentation and example creation

If RefAIne has been useful in your work, consider supporting the project:

Star the repository: github.com/AlbertoBarrago/RefAIne
Contribute financially via GitHub Sponsors or donation platforms
Share the project with other developers
Report issues or contribute code improvements

Financial support helps maintain active development, add new provider integrations, improve refinement quality, and respond to community needs.

Quick Start

# Clone repository
git clone https://github.com/AlbertoBarrago/RefAIne.git
cd RefAIne

# Install and configure Ollama (for free local testing)
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.1

# Set up environment
cat > .env << EOF
LLM_PROVIDER=openai
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_API_KEY=ollama
OPENAI_MODEL=llama3.1
EOF

# Install and run
uv pip install -r pyproject.toml
uvicorn main:app --reload

# Test the endpoint
curl -X POST http://localhost:8000/refine \
  -H "Content-Type: application/json" \
  -d '{"prompt": "create a REST API"}'

Interactive API documentation is available at http://localhost:8000/docs.

Resources

GitHub Repository: github.com/AlbertoBarrago/RefAIne
Issue Tracker: Report bugs or request features
Documentation: Included in repository README

Contributions and feedback are welcome.

WIR - What Is Running: A CLI Tool in C to Inspect Processes and Ports

Alberto Barrago — Tue, 30 Dec 2025 20:28:59 +0000

I recently released wir (What Is Running), a command-line tool written in C to inspect what's running on specific ports and get detailed process information. A project born from a practical need that turned into an opportunity to explore system programming in C.

The Problem

How many times have you had a port occupied without knowing which process is using it? Or needed to trace a process hierarchy to understand who spawned what? We usually resort to combinations of lsof, netstat, and ps, but why not have everything in a single command?

The Solution

wir is a cross-platform tool (macOS and Linux) that allows you to:

Discover which process is using a specific port
Get detailed information about a PID
Visualize the complete ancestry tree of a process
List all running processes
View a process's environment variables
Output in normal, short, JSON, or tree format
Receive security warnings for potentially risky configurations

Practical Examples

# Who's using port 8080?
wir --port 8080

# Info about a specific process
wir --pid 1234

# Show the process ancestry tree
wir --pid 1234 --tree

# JSON output for scripting
wir --port 3000 --json

# List all processes (short format)
wir --all --short

# Security warnings only
wir --port 8080 --warnings

The Architecture

The project is structured in a modular way:

Platform abstraction layer: handles differences between Linux (/proc parsing) and macOS (libproc and sysctl)
Output formatting: supports multiple display modes without duplicating logic
Consistent error handling: every allocation is checked, every resource is freed
Strict memory management: no leaks, no undefined behavior

What I Learned

Writing wir was an excellent opportunity to practice fundamental concepts:

System programming: interfacing with /proc, system calls, process management
Cross-platform development: conditional compilation and different APIs for each OS
Memory safety in C: manual memory management without a garbage collector
Build systems: Makefile with automatic platform detection
API design: clean and composable interface

I Don't Memorize Commands

As my approach goes: I'm not interested in memorizing the exact lsof or netstat commands. I prefer understanding the underlying architecture and building tools that solve the problem more elegantly. wir isn't just a wrapper, it's an abstraction that hides the complexity of OS differences.

The Future

The project is open to extensions:

UDP port support
Advanced process filtering
Support for other OSes (BSD, etc.)
Performance optimizations
Additional output formats

Try It Out

wir

It's a learning project, so feel free to experiment and extend it. Building system tools in C is a great way to understand what's really happening under the hood.

# Build and install
brew tap AlbertoBarrago/tap
brew install wir

# Start using it
wir --port 3000

Neovim + COQ + Mason + LSP: Mini Guide

Alberto Barrago — Mon, 17 Nov 2025 22:16:29 +0000

This guide explains how to properly set up COQ.nvim autocomplete
with Mason and LSP servers in Neovim. It includes the most
common pitfalls and a working configuration.

🔧 1. Install Required Plugins

Make sure you have:

ms-jpq/coq_nvim
ms-jpq/coq.artifacts (optional, extra completions)
williamboman/mason.nvim
williamboman/mason-lspconfig.nvim
neovim/nvim-lspconfig

Example (lazy.nvim):

{
  "ms-jpq/coq_nvim",
  branch = "coq",
},
{
  "ms-jpq/coq.artifacts",
  branch = "artifacts",
},
{
  "williamboman/mason.nvim",
  config = true,
},
{
  "williamboman/mason-lspconfig.nvim",
  dependencies = { "neovim/nvim-lspconfig" },
},

⚡ 2. Enable COQ Auto-Start

COQ does not start automatically unless configured.

vim.g.coq_settings = { auto_start = 'shut-up' }

Alternatively, use manually later:

:COQnow

🧠 3. Correct Working LSP + COQ Setup

require("mason").setup()

local coq = require("coq")

require("mason-lspconfig").setup({
    ensure_installed = { "pyright", "jdtls", "dockerls", "elixirls", "ts_ls" },
    automatic_installation = true,

    handlers = {
        function(server_name)
            require("lspconfig")[server_name].setup(
                coq.lsp_ensure_capabilities({})
            )
        end,

        ["elixirls"] = function()
            require("lspconfig").elixirls.setup(
                coq.lsp_ensure_capabilities({
                    settings = {
                        flags = {
                            debounce_text_changes = 150,
                        },
                        elixirLS = {
                            dialyzerEnabled = false,
                            fetchDeps = false,
                        }
                    }
                })
            )
        end,
    },
})

❗ 4. What Not To Do

❌ Do NOT use omnifunc with COQ

autocmd FileType markdown setlocal omnifunc=coq#complete

Remove this. COQ does not use omnifunc.

🧪 5. Verification Steps

✔ Check if LSPs are connected:

:LspInfo

✔ Check COQ status:

:COQnow

✔ Test autocomplete

Open a file and type --- completion should appear.

🐛 6. Common Issues & Fixes

❗ Autocomplete doesn't show up

COQ not started → :COQnow
LSP not attached → :LspInfo
Missing capabilities → use coq.lsp_ensure_capabilities()
Remove delayed init like vim.defer_fn

❗ Markdown has no completion

Install a Markdown LSP:

ensure_installed = { "marksman", ... }

🎉 Done!

You now have a clean Neovim setup using COQ + Mason + LSP.

Level Up Your Terminal Workflow: Helix + Yazi

Alberto Barrago — Tue, 04 Nov 2025 14:35:00 +0000

If you're looking for a modern, efficient terminal-based development setup, let me introduce you to a powerful combination: Helix (a post-modern text editor) and Yazi (a blazingly fast terminal file manager).

Why This Combo?

Helix is a Kakoune-inspired editor with built-in LSP support, multiple cursors, and tree-sitter integration. It's fast, has sane defaults, and no plugin configuration needed.

Yazi is a terminal file manager written in Rust that's incredibly fast and intuitive. Think of it as a visual way to navigate your projects before diving into code.

Together, they create a lightweight alternative to heavy IDEs while keeping you productive.

Moving Away from JetBrains

I've been reflecting on my development tools lately, and I'm not particularly proud of relying on JetBrains products anymore. Their direction seems increasingly Microsoft-addicted - just look at Rider becoming primarily a .NET IDE focused on game development, while languages like Erlang and other niche but important ecosystems are left out of the scene.

The bloat, the subscription model, and the narrowing focus pushed me to explore lighter, more universal alternatives. That's how I discovered this setup.

Setup

1. Install Both Tools

# macOS
brew install helix yazi

# Linux (check your distro's package manager)
# Arch
sudo pacman -S helix yazi

# Other distros - check helix-editor.com and yazi-rs.github.io

2. Configure Yazi to Open Files in Helix

Create ~/.config/yazi/yazi.toml:

[opener]
edit = [
  { run = 'hx "$@"', block = true },
]

3. Customize Your Helix Theme (Optional)

Create a custom dark theme at ~/.config/helix/themes/my-theme.toml:

"ui.background" = { bg = "#1e1e1e" }
"ui.text" = { fg = "#d4d4d4" }
"ui.selection" = { bg = "#264f78" }
"ui.cursor" = { fg = "#1e1e1e", bg = "#aeafad" }
"ui.linenr" = { fg = "#858585" }
"ui.linenr.selected" = { fg = "#c6c6c6" }

"comment" = { fg = "#6a9955", modifiers = ["italic"] }
"keyword" = { fg = "#569cd6" }
"function" = { fg = "#dcdcaa" }
"string" = { fg = "#ce9178" }
"variable" = { fg = "#9cdcfe" }
"type" = { fg = "#4ec9b0" }

Then set it in ~/.config/helix/config.toml:

theme = "my-theme"

Workflow

Navigate with Yazi:

   cd ~/your-project
   yazi

Browse your project structure using arrow keys or hjkl
Press Enter on any file to open it in Helix
Edit in Helix with LSP support, syntax highlighting, and multiple cursors
Save and exit (Ctrl+s, then :q) to return to Yazi
Repeat - navigate to next file

Helix Quick Tips

Space + f - Fuzzy file finder
Space + b - Buffer (open files) picker
Space + / - Global search in project
mf - Select function, md - select around
Multiple cursors: C to add cursor, Alt+C to remove

Why Not Just Use Helix's Built-in Picker?

You absolutely can! Helix has excellent fuzzy finding (Space + f). But Yazi gives you:

Visual tree structure
Quick file operations (copy, move, rename)
Image previews
Directory sizes
A complementary tool for different tasks

Conclusion

This setup gives you the speed and simplicity of terminal tools with the power of modern editing features. No Electron bloat, no complex plugin configurations - just fast, efficient coding.

Give it a try and let me know what you think!

Resources:

DEV Community: Alberto Barrago

Telemaco: a headless Rust browser engine

The problem: Chromium as a tax

The need that started it

Standing on the shoulders of many projects

The architecture

What it looks like

The numbers

Why "Telemaco"

Not a product, a direction

I Built a CLI to Answer One Question: What Will This Change Break?

The problem

Four signals instead of one

1. Dependency graph

2. Git history

3. CI configuration

4. Critical paths

Why the score is deterministic

So... no AI?

Local-first was intentional

It can also become a CI gate

Installing it

What I'm trying to explore

NEON INVADERS

AlbertoBarrago / neon-invaders

A synthwave arcade shooter built with strict TypeScript, HTML5 Canvas, and zero runtime dependencies.

Neon Invaders

Play Neon Invaders

Why it feels different

Introducing TimeLog: A Native Time Tracker for iOS and macOS

From Many Ideas to Fewer Features

What TimeLog Does

Built for the Apple Ecosystem

Simplicity as a Product Decision

What I Learned

What’s Next

Closing

AI Doesn't Read Your Mind. It Reads Your Trail.

AI Doesn't Read Your Mind

The Great Illusion

Why It Feels Like Mind Reading

AI Reads Your Trail

The Skill Everyone Talks About

The Skill Nobody Talks About

AI Is Still A Tool

Why Humans Still Matter

The Future

Back To Fundamentals

Final Thought

Enjoy, and give me some feedback ^^

I Built My Own Diagramming Tool

I Built My Own Diagramming Tool

Fix: Eliminating Double Async Validation in TanStack Form & Zod

🚨 The Problem: Double Async Execution

Typical Setup

Why It's Dangerous

🧠 Root Cause

✅ The Solution: Take Back Control

1. Manual Validation with safeParseAsync

2. Prevent Re-entrancy with useRef

3. Decouple Side Effects

🧩 Full Implementation

🌐 Network Layer Optimization

Fix your QueryClient config:

Why it matters

🏗️ Production Insights

🔑 Key Takeaways

💬 Final Thoughts

🚀 Discussion

RefAIne: Transform Casual Prompts into Expert-Level AI Instructions

The Problem

The Solution

Key Features

Free Testing Options

Multiple Provider Support

Production Ready

Focused Design

About the Project

Supporting Development

Quick Start

1. Manual Validation with `safeParseAsync`

2. Prevent Re-entrancy with `useRef`