DEV Community

I built a live secret scanner for VS Code (and why CI scanning is too late)

thunderbird — Mon, 22 Jun 2026 23:35:30 +0000

We've all done it: pasted an API key into a file "just to test," then a week later
it's in your git history, a screenshot, or a livestream. Most secret scanners —
gitleaks, trufflehog — run in CI, after the secret is already committed.

So I built Secret Guardian, a VS Code extension that catches secrets live, in
the editor, the moment they appear — and visually masks them so they never show
up in screenshots or screen-shares.

👉 Secret Guardian on the VS Code Marketplace (free)

What it does

Detects 17+ secret types as you type: AWS, GitHub, GitLab, Google, Slack, Stripe, OpenAI, SendGrid, Twilio, npm tokens, private keys, JWTs, credentials in URLs.
A generic high-entropy rule catches the long-tail.
Masks detected secrets with a lock overlay — safe for demos.
Flags everything in the Problems panel + a one-click workspace scan.
100% local. Nothing leaves your machine.

How detection works

Two layers: tight regexes for known formats (e.g. AKIA…, ghp_…), and an
entropy + context check for unknown secrets (high Shannon entropy assigned to a
secret-like name), with placeholders like your_api_key filtered out.

Try it

Install from the Marketplace,
open a file, paste a fake key. I'd love feedback on accuracy and false positives.

I built 168 pages of free trading tools with vanilla HTML/JS — here's how

Mobin Moharami — Mon, 22 Jun 2026 23:35:12 +0000

The idea

Prop firm traders (people who trade with other people's money) need specific calculators that account for strict drawdown rules. Every existing calculator is either ugly, full of ads, or doesn't know that FTMO has a 5% daily drawdown limit.

So I built PropWise — 10 interactive tools across 168 SEO-optimized pages, all in vanilla HTML, CSS, and JS. No framework. No build step. No dependencies.

What I built

10 core tools:

Position Size Calculator (pre-configured for 12 prop firms)
Challenge Cost Calculator (expected cost to get funded based on pass rate)
Risk of Ruin Calculator (probability of blowing your account)
Revenge Trade Calculator (mathematical damage of emotional trading)
Overtrading Detector (optimal trading frequency analysis)
Live Session Timer with ICT kill zones
Compound Growth Calculator
Pip Value Calculator
Prop Firm Comparison (12 firms)
"Am I Ready?" readiness quiz

Plus 158 programmatic pages:

55 firm + account size specific calculators (e.g. "FTMO 100K Position Size Calculator")
66 head-to-head comparison pages (e.g. "FTMO vs FundedNext")
36 brand-specific tool pages (e.g. "Topstep Risk Calculator")

Tech stack

Intentionally simple:

Vanilla HTML/CSS/JS
Python build script to generate 168 pages from templates
Nginx on a VPS
Certbot for SSL
Google Analytics
No database, no API, no framework

The programmatic SEO approach

Instead of 10 pages targeting broad keywords like "position size calculator," I generated pages for every combination:

Every firm × every account size = unique page with pre-calculated lot sizes
Every firm × every firm = comparison page with side-by-side data
Every firm × every tool type = brand-specific landing page

Each page has:

Unique title, description, and keywords
Schema.org markup (SoftwareApplication, BreadcrumbList, FAQPage)
Breadcrumb navigation
Heavy internal linking (5+ contextual links per page)
Pre-calculated data tables (not just a blank calculator)

One Python script generates everything:


python
for firm in FIRMS:
    for account in firm["accounts"]:
        # Generate unique page with pre-filled calculations
        build_page(
            slug=f"{firm['slug']}-{format(account)}-position-size-calculator",
            title=f"{firm['name']} {format(account)} Position Size Calculator",
            body=generate_calculator_page(firm, account)
        )




/// Design decisions
Dark theme — traders stare at dark charts all day. A bright white tool site would feel jarring.
No signup wall — every tool works immediately. No email capture, no "sign up to see results." Trust is built by being useful, not by gating.
Share cards — every calculation produces a shareable card with the result, optimized for Twitter screenshots. Organic distribution > paid ads.
Sound effects — subtle audio feedback: a cha-ching for positive results, an alert for dangerous risk levels. Small detail, big UX impact.
What I'd do differently
Would use a static site generator instead of a custom Python script
Would add a service worker for offline use
Would build a proper design system instead of inline styles
Results
Just launched. 168 pages indexed in Google, zero budget spent. Let's see what happens.
Check it out: propwise.site
Source approach and all tools are free. If you're a trader, I'd love feedback on what's missing.
---

Superconductor review: the cleanest way I've found to run AI agents in parallel

Daniel Bergholz — Mon, 22 Jun 2026 23:33:02 +0000

I use Claude Code every single day. At my day job, it's my main agent, and I've talked plenty about how much I love it. But on my side projects, I like to play around with other agents: Codex, OpenCode, whatever new CLI shows up that week. And recently I hit a wall that turned out to be more annoying than I expected.

I wanted to run a bunch of agents in parallel. Not one at a time, but several, across different projects, at the same time. And the moment I tried to do that, I realized every tool was trying to lock me into its own little world.

So I went looking for something better, and I found a product I've been using for the past few days that I genuinely can't stop recommending. This is not sponsored. I'm paying nothing and using it on my own machine. It's called Superconductor, and this post is my honest review.

If you'd rather watch me click through the whole thing instead of reading, the full walkthrough is right here:

Why I needed this in the first place

Here's the situation. If I'm on Claude, I can open the Claude desktop app and run multiple Claudes in parallel. Cool. I can do the same with OpenAI's Codex app. Also cool.

But what if I want a different agent? What if I want to run OpenCode, or the Pi coding agent? Suddenly I'm stuck. Each desktop app only knows about its own provider. The second I commit to one app, I'm locked into whatever model that company ships.

I don't want that. I want one interface that doesn't care which agent I'm using. One place where I can run Claude Code for my day job and Codex for my side projects, side by side, without juggling three separate apps. Agent-agnostic is the whole point.

That's exactly what Superconductor is: a single workspace for running coding agents in parallel, across different projects and different worktrees, with whatever agent you feel like using.

What Superconductor actually is

A few things make it stand out before we even open it.

First, it's written 100% in Rust. No Electron. The whole thing is a native macOS binary rendered on your GPU with Metal, and the startup time is around 50 milliseconds. That number sounds like marketing until you feel it. Some of the provider apps, like the Codex app, are genuinely nice but also pretty janky. Every time you open a sidebar, it slides in this sluggish way. Superconductor just snaps. Everything is instant.

Second, because it's built for developers, it's absolutely covered in keyboard shortcuts. You can drive the entire app without touching the mouse. Here are the ones I lean on the most:

Shortcut	What it does
`Cmd + Shift + E`	Toggle the left side panel
`Cmd + E`	Toggle the right side panel
`Cmd + Shift + A`	Add a new project
`Cmd + T`	Open your default agent (Claude Code, for me)
`Cmd + Shift + T`	Pick from all available agents
`Cmd + W`	Close the current tab
`Cmd + N`	Create a new worktree
`Cmd + R`	Run your run script (dev server, etc.)
`Option + Cmd + Left`	Switch between workspaces

Let me walk through how I actually use it.

The layout

On the left, you have your projects. Open a project folder and you see all of its worktrees. Right now I just have the main branch for two projects: my personal website and CourseShelf v2. That starred branch row is the primary worktree, which is just the original checkout Superconductor opened, the source of truth you branch off from.

On the right, you have a panel you can fully customize. By default it shows your files, changes, and checks on top, and a terminal on the bottom (where you can also wire up a run script and a setup script, more on that in a second).

I don't love that default arrangement, so I switched it to show two tabs on the right instead: one for my terminal with setup and run, and another for my files. It takes ten seconds and the layout sticks.

Adding a new project is just Cmd + Shift + A (or the "Add Project" button on the bottom left), pick your folder, done.

Starting an agent

This is where the "just like a browser" mental model clicks. Press Cmd + T to open your default agent, which in my case is Claude Code. Or press Cmd + Shift + T to pick from every agent you've got configured. Superconductor supports a long list out of the box: Claude Code, Codex, Gemini CLI, OpenCode, Cursor Agent, Grok, Pi, Kiro, Copilot, basically any CLI agent you already use.

There's a native chat UI too, where you can switch providers and models from a dropdown. It's nice. But honestly, I almost always stick to the CLIs. So I'll close the chat with Cmd + W, hit Cmd + Shift + T again, choose "terminal," and just run the CLI straight from there. The point is, Superconductor doesn't force a workflow on you. CLI, native chat, plain terminal, it's your call.

One thing worth knowing: it never routes your prompts or code through its own servers. You bring your own provider CLIs and your own subscriptions, and everything stays local. No account to create, no credentials proxied anywhere.

Running real parallel work

Let me actually test the parallel part. I'll open a tab for OpenCode and pick a model. Do they have Kimi? Nope, not yet. Fine, I'll grab DeepSeek V4 Pro on high reasoning and ask it: "what is this project about?" Enter.

Now I switch tabs to another project and start a second agent. I'd normally reach for Claude Fable here, but it got banned right when I was recording this, so I switched to Claude Opus on X-high effort instead. Same question: "what is this project about?"

And that's it. Two agents, two different providers, two different projects, both working at the same time. I flip between tabs and watch OpenCode finish while Opus is still thinking. This already solves my original problem: multiple agents, multiple projects, zero provider lock-in.

But running across separate projects is the easy case. The real question is: what about parallel work inside the same project?

Worktrees: parallel work inside one project

This is where worktrees come in, and where Superconductor gets genuinely clever.

To create a new worktree, press Cmd + N (or the plus button). Under the hood you're still using Git, but a worktree copies your codebase into a brand new folder so each task gets its own isolated working directory. Concurrent agents never step on each other's files. That's the whole appeal.

But copying your code into a fresh folder creates two very real headaches:

Environment variables. Your .env is gitignored, so a fresh worktree doesn't have it. Your new folder is missing the one file your app can't run without.
Dependencies. No node_modules either. So... do I have to manually run npm install every single time I spin up a worktree?

If that's the deal, this feature is dead on arrival. Nobody wants to babysit npm install and copy .env files by hand all day.

Worry not, my friend. This is exactly the problem the scripts solve.

The magic: setup and run scripts

Open your project settings (you can do this per project on the left sidebar), scroll down, and you'll find the scripts section. This is where everything gets automated.

There are a few hooks. The two I care about are:

Setup script runs automatically whenever a new worktree is created.
Run script runs when you hit the run button.

For my personal website, my setup script does two things: copy my environment variables from the main folder into the new worktree, then run npm install. My run script is simply npm run dev.

You can configure these in the app's project settings, or commit them to your repo so the whole team shares them. Superconductor reads a .superconductor/config.json from the worktree (falling back to the primary worktree if there isn't one):

// .superconductor/config.json
{
  "setup": ["cp ../main/.env .env", "npm install"],
  "run": ["npm run dev"],
  "teardown": ["rm -rf tmp/superconductor-preview"]
}

The setup array is what runs on a fresh worktree, run is what the run button executes, and teardown cleans up when you delete a worktree. (My actual setup uses my own paths for the env copy, so treat the cp line above as the shape of it, not my literal command.)

Now watch what happens. I press Cmd + N on my Next.js personal website. The setup script kicks off, and I can see its output right there in the panel: added 49 packages. That's the classic npm install output. The worktree is ready to go.

Jump to the files and check it out. First, node_modules is there, so dependencies are installed. Second, my .env is sitting right there too. I didn't run a single cp or npm install by hand. It's all automated. Create another worktree with Cmd + N and the same thing happens again: dependencies, env vars, ready.

The built-in browser

Remember that run script? To run it, press Cmd + R. My dev server boots up. You can open it in a regular browser like normal, or you can use Superconductor's built-in browser: click "Open Preview" and a browser pane opens right inside the app.

It's got some nice touches: a button to copy the URL, a button to open the site in your external browser, and a button to inspect.

So now picture the full parallel setup. I start CourseShelf, press Cmd + R, open its preview. I do the same for my personal website. Two dev servers, two previews, both live at once. And on the left sidebar, any worktree with a running server gets a glowing blue dot, so at a glance I know exactly what's up without hunting through tabs.

This is the part that sold me. Parallel work across different projects, and parallel work inside the same project, each task fully isolated with its own deps, env, server, and preview.

Workspaces and themes

The last feature, and honestly one of my favorites, is workspaces.

At the bottom left I keep one workspace for work and another for side projects. Want a new one? Create it (I made a "work number two" just to show it off). It feels a lot like Arc's spaces. Each workspace can even have its own theme. I gave one a deep, intense red. You set a chrome and accent color per workspace, so personal, work, and client contexts stay visually distinct and you always know where you are.

To jump between workspaces, press Option + Cmd + Left. And like everything else in this app, it's instant. The animations are flawless, with zero lag.

What I'm not using (yet)

Time for the honest part, because a review that's all praise is useless.

Superconductor has a bunch of heavier features I'm not touching. It can automatically review your changes, open pull requests for you, and there's a smart action button that walks through commit, push, PR creation, fixing CI, resolving conflicts, and merging, all without leaving the app. It tracks PR status per worktree too. It's clearly built for people who want to run a whole review-and-ship loop inside one window.

Me? I'm using the simple stuff: create projects, run agents in parallel, spin up worktrees with automated setup, run my dev servers, and switch between workspaces. That's all I need. But if you're a hardcore user, there's a lot of room to go deep.

A couple of caveats to set expectations:

It's still in alpha. Things will change.
I went looking for a pricing page and couldn't find one. As far as I can tell it's free right now, and I'd assume paid features show up eventually.
The documentation is genuinely extensive if you want to dig into the advanced flows.

Should you try it?

Yes. If you run more than one agent at a time, or you bounce between providers like I do, this is the cleanest setup I've found. It's fast, it's keyboard-driven, it's agent-agnostic, and the worktree automation alone saves me from a hundred tiny npm install papercuts a week. The fact that it's free and this polished while still in alpha is wild. Give it a shot and tell me what you think.

Thanks for reading all the way to the end, you're awesome. See you in the next one.

CtroEnv vs Zod, envalid, t3-env, Which Env Validator Should You Use?

Odejobi Abiola Samuel — Mon, 22 Jun 2026 23:25:31 +0000

I've built enough projects to know that environment variable validation isn't glamorous — until your app silently uses undefined as a database URL. There are a bunch of tools for this now, and picking the wrong one means either fighting your tool or fighting your own config. Here's how they stack up.

The candidates

Tool	Size	Dependencies	CLI	Framework support
CtroEnv	under 5 KB gzip	0	Yes	Node, Vite, Next.js
Zod + manual	50 KB+	0 (Zod itself is ~13 KB gzip, plus your glue)	No	You build it
envalid	8 KB gzip	6 (legacy deps)	No	Node only
t3-env	~15 KB	Depends on Zod	No	Next.js only

Let's look at each one.

Zod + manual parsing

Zod is great for runtime validation in general, and lots of people use it for env vars because they already have it in their project.

import { z } from "zod";

const schema = z.object({
  DATABASE_URL: z.string().url(),
  PORT: z.coerce.number().int().min(0).max(65535).default("3000"),
  NODE_ENV: z.enum(["dev", "prod"]),
});

const parsed = schema.safeParse(process.env);
if (!parsed.success) {
  console.error(parsed.error.format());
  process.exit(1);
}

const env = parsed.data;

What it does well: If you're already using Zod, this is zero extra dependencies. Zod's type inference is excellent. The error formatting is detailed.

What it doesn't do: No CLI, no .env.example generation, no secret masking, no framework adapters. You write your own process.exit(1) boilerplate every time. Coercion for numbers/booleans is manual — z.coerce.number() doesn't reject non-numeric strings gracefully. No way to generate docs from your schema.

When to pick it: You already have Zod in your project, you only have 3-4 env vars, and you don't mind writing the glue code. For anything bigger, the boilerplate gets annoying fast.

envalid

envalid was the early leader here. It's been around since the days of dotenv and has a simple API.

import { cleanEnv, str, port, num, makeValidator } from "envalid";

const env = cleanEnv(process.env, {
  DATABASE_URL: str(),
  PORT: port({ default: 3000 }),
  NODE_ENV: str({ choices: ["dev", "prod"] }),
});

What it does well: Dead simple. The makeValidator API for custom types is straightforward. Reports all errors at once instead of failing on the first one.

What it doesn't do: It's Node-only, so no Vite or Next.js integrations. The error messages are pretty basic — you get a string like "DATABASE_URL" is missing, but no grouped or colored output. The choices option is oddly attached to str() rather than being a proper pick type. It has 6 legacy dependencies (some unmaintained). No CLI, no env file generation, no ENVIRONMENT.md generation. Secret masking isn't built in.

When to pick it: You need something simple for a Node backend and don't want to learn a new API. It works, but you'll outgrow it quickly if your project grows.

t3-env

Created by the t3-stack team, this one wraps Zod with nice DX and is tightly coupled to Next.js.

import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
  },
  client: {
    NEXT_PUBLIC_API_URL: z.string().url(),
  },
  runtimeEnv: process.env,
});

What it does well: The server/client split is genius for Next.js. It prevents accidentally leaking server-only vars to the client bundle. Great integration with Next.js build process.

What it doesn't do: It's Next-only. If you extract it for other frameworks, you're fighting it. It depends on Zod (15 KB+ added). No CLI, no .env.example generation, no docs generation. The runtimeEnv option is annoying — you have to manually pass process.env in development and inline values in production. Secret masking isn't built in.

When to pick it: You're all-in on the Next.js / t3-stack ecosystem. If you ever leave Next, you'll need to replace it.

CtroEnv

Full disclosure: I built this one. I wanted something that worked everywhere without dragging in a schema library I didn't need.

import { defineEnv, string, number, pick } from "@ctroenv/core";

const env = defineEnv({
  DATABASE_URL: string().url(),
  PORT: number().port().default(3000),
  NODE_ENV: pick(["dev", "prod"] as const),
});

env.DATABASE_URL; // typed as string

Zero dependencies. under 5 KB gzipped. Validators are chainable and self-contained — no Zod dependency.

// Secret masking is built in
const env = defineEnv({
  JWT_SECRET: string().min(32).secret(),
});

console.log(env.JWT_SECRET);    // "********"
env.meta.get("JWT_SECRET");     // actual value

# CLI is included
npx @ctroenv/cli validate        # validate current env
npx @ctroenv/cli generate        # create .env.example from schema
npx @ctroenv/cli docs            # generate ENVIRONMENT.md
npx @ctroenv/cli check           # CI-friendly diff

// Framework adapters
// @ctroenv/node — reads process.env + .env files
// @ctroenv/vite — reads import.meta.env, build plugin
// @ctroenv/nextjs — server/client split like t3-env

What it does well: Framework-agnostic core, but has adapters when you need them. CLI for everyday tasks. Generates .env.example and docs from schema so they can't drift. Secret masking is built into the runtime, not bolted on. Error grouping and colored output for CI.

What it doesn't do: It's newer, so smaller ecosystem. No Zod compatibility layer (and that's by design — the APIs are different). The custom validator API uses a different pattern than Zod's.

When to pick it: You want zero-dependency validation that works across frameworks. You hate maintaining .env.example by hand. You want one tool for dev, CI, and docs.

Which one should you use?

If you're on Next.js and already have Zod, t3-env is fine. If you just need 3 vars validated, envalid works. If you love Zod and want to own your parsing pipeline, go for it.

If you want something that handles the whole lifecycle — validation, docs generation, CI checks, secret masking — CtroEnv does that without pulling in a 50 KB schema library. But it's also the newest option, so weigh that.

Pick based on your project, not hype. Each of these tools solves the same problem differently, and none of them are wrong.

How to make an AI research agent label facts vs inferences — a deterministic provenance pipeline

John — Mon, 22 Jun 2026 23:23:16 +0000

Originally published on hexisteme notes, part of a series on building and running an AI agent fleet.

To stop an AI research or RAG agent from presenting its own inferences as retrieved facts, split the work so the LLM never decides what is a fact: let the LLM only extract and summarize, and let a deterministic, non-LLM pipeline do all scoring, cross-checking, and labeling. Tag a claim FACT only when a rule is satisfied — corroboration by ≥2 independent sources, or one official API — and downgrade everything else to INFERENCE. Because labeling is rule-based, the agent can't launder a guess into a fact, and the same query produces the same labels every run.

An AI agent that gathers information has two kinds of output tangled together: things it retrieved and things it concluded. A web page said the market was 1.2 trillion won (retrieved); the agent inferred the market is "growing fast" (concluded). Both come out in the same confident prose. For anything you'll act on, that blend is the problem — you can't tell which sentence is grounded and which is the model filling a gap.

The fix isn't a better prompt ("only state facts you can cite"). Prompts are probabilistic; under pressure the model reverts. The fix is structural: take the fact/inference decision away from the model entirely and put it in code.

The split: LLM extracts, code judges

Draw a hard line through the pipeline:

The LLM does	Deterministic code does
Extract claims from a fetched page; summarize a passage	Score, cross-check, sort, deduplicate, label FACT/INFERENCE, decide freshness

The LLM is excellent at reading messy text and pulling out a structured claim. It is unreliable at judging that claim — ask it to "rate confidence 0–1" and it will turn a guess into 0.85, and give a different number next run. So nothing downstream of extraction is allowed to be an LLM call. Scores are token matches, source counts, and recency math. Labels are rule outputs. This buys two things at once: reproducibility (same query → same labels, which you can unit-test) and no laundering (the model can't promote its own inference to a fact, because it never holds the pen on labeling).

Reproducibility is the tell. If your research agent gives different confidence on the same question across runs, an LLM is scoring somewhere in the pipeline. Find it and replace it with a function. The goal is: re-run the exact query, get the exact same FACT/INFERENCE split.

A six-phase pipeline

Make the stages explicit so each is testable in isolation:

PLAN → HARVEST → NORMALIZE → CORROBORATE → SCORE → RENDER

PLAN — turn the question into concrete sub-queries and the sources to try.
HARVEST — fetch from multiple paths (see below). LLM-free; just collection.
NORMALIZE — LLM extracts structured claims from each fetched item. This is the only place the model touches the data.
CORROBORATE — group claims; count independent sources per claim.
SCORE — assign labels and scores by rule.
RENDER — emit FACTs, INFERENCEs, and an explicit gap list.

The FACT gate: earn the label

FACT is not a default; it's a status a claim must earn, enforced as a type invariant:

# A claim constructed as FACT without evidence is a bug, not a soft warning.
Claim(provenance=FACT, evidence_ids=[])   # -> raises

# The corroboration rule (the knob is the count; the principle is independence)
def label(claim):
    independent = count_independent_sources(claim)   # distinct domains, not pages
    if independent >= 2 or claim.from_official_api:
        return FACT          # carries the evidence_ids that corroborated it
    return INFERENCE         # single-source or model-derived

"Independent" is doing real work: one blog quoting another blog is one source, not two. Two different domains, or a single authoritative API (a government dataset, an exchange's own endpoint), clear the bar. Everything else is rendered as INFERENCE — visible to the reader as exactly that.

⚠️ Watch for order-dependence. An early version of this scored a cross-corroborated FACT lower than a single-source INFERENCE because the score depended on processing order. That silently breaks reproducibility. Scores must be a pure function of the claim and its evidence, independent of the order claims were processed.

Multi-path harvest, without redundancy

Diversity of sources is what makes corroboration meaningful, but firing every source at once is wasteful and noisy. Use escalation, not broadcast: try a primary search, and only escalate to the next path when the first is insufficient.

Path	Order
Web search	primary → escalate to a news-grade engine (ad/spam pollution) → escalate to a semantic engine (papers, near-duplicates)
Official API	a government/first-party dataset; one official source may stand alone as FACT

Never send the same query to three engines simultaneously — read the first result, then decide whether to escalate. And when a source fails or is rate-limited, log the failure and the escalation; never substitute a guess for a missing fetch.

Freshness and gaps are first-class

Two more rules complete the provenance picture. Freshness: every datum carries a confirmation date, and a rule marks it stale when it ages past a threshold — a fact true last quarter is labeled as such, not silently presented as current. Gaps: the render step emits an explicit list of what was asked but not found or not corroborated. A silent gap reads as completeness and is the most dangerous output a research agent can produce; surfacing it is what makes the FACT list trustworthy.

Why this is worth the structure

The payoff is a research output a reader (or a downstream AI) can trust per-claim: every FACT points at the independent sources that earned it, every INFERENCE is flagged as the agent's own leap, stale data says so, and the gaps are named. The model still does what it's good at — reading and extracting — but it never gets to decide what's true. In an era where AI answers are increasingly cited as sources themselves, the agents worth citing are the ones that label their own confidence honestly, by rule, and reproducibly.

More notes on building an AI agent fleet — falsifier-driven AI decisions, reusable decision units, a file-based agent work-bus — at hexisteme.github.io/notes.

how do you get real-world experience before your first job?

arianna — Mon, 22 Jun 2026 23:19:39 +0000

hello ! im a CS student (2nd year) and ive been look around for some tech jobs. any kind because honestly i just want a tech related job (i <3 tech). but the problem is,so many jobs/places want you to have experience in the real-world but literally no one is willing to offer it. they want minimum 3-years experience. im considered learning some other programming languages that they require for jobs that could be useful. however, i want to practice what ive learnt in a real job setting. of course after learning a lot about said-subject. but im just confused on how im going to land a job after college with no experience.

and please dont come for me; im genuinely just trying to think ahead instead of leaving it for when i get there

any advice would be appreciated !! :p

Running Async Python Inside Celery Is Harder Than You Think.

Kolade Fajimi — Mon, 22 Jun 2026 23:17:50 +0000

The problem is straightforward to state and surprisingly hard to solve correctly.

Celery workers are synchronous. Celery spawns prefork worker processes, and when a task arrives, it calls your task function like this: task_function(*args, **kwargs). It expects a return value. It blocks the worker thread until it gets one. It does not know or care that you wrote async def.

But modern Python services are async. FastAPI is async. SQLAlchemy 2.0 is async. httpx, aiohttp, asyncpg the entire interesting half of the ecosystem has gone async-first. The idea of maintaining two parallel code paths, one async for your web layer, one sync for your task layer is exactly the kind of thing that creates maintenance debt, copy-paste bugs, and the kind of divergence you only notice when something breaks in production.

So you want to write async def task functions and have them work inside a Celery worker. How hard can it be?

Harder than it looks.

Why `asyncio.run()` doesn't work

The first thing most people try:

def task_wrapper(*args, **kwargs):
    return asyncio.run(your_async_function(*args, **kwargs))

This works in isolation. It fails in production for a specific reason: asyncio.run() creates a new event loop, runs the coroutine to completion, then closes the loop. If there is already a running event loop on the current thread, and there frequently is, in test environments, in newer Celery versions, in signal handlers, it raises:

RuntimeError: This event loop is already running.

The fix most people find next is nest_asyncio:

import nest_asyncio
nest_asyncio.apply()
# now asyncio.run() "works" from inside a running loop

nest_asyncio patches the event loop to allow re-entrant calls. It works in simple cases. The subtle failure mode: re-entrant event loops change the execution order of scheduled callbacks and coroutines. Code that was safe under normal scheduling assumptions becomes non-deterministic under concurrent load. Bugs appear only at production concurrency, only under specific timing, and are nearly impossible to reproduce in development.

The prefork complication

Even if you solve the asyncio.run() problem, Celery's prefork concurrency model introduces a second failure that takes longer to diagnose because it manifests as infinite silence rather than an immediate error.

When Celery starts, it forks N worker processes from a single parent. After fork(), the child process inherits the parent's memory including any event loop objects that existed before the fork.

The problem: fork() does not copy threads. A Python asyncio.AbstractEventLoop is driven by a thread calling loop.run_forever(). After fork(), the child has the loop object but not the thread running it. The loop's internal state may indicate it was running; nothing is actually driving it. Any coroutine scheduled onto this loop hangs indefinitely.

@worker_process_init.connect
def bad_init(**kwargs):
    loop = asyncio.get_event_loop()
    # This loop was inherited from the parent.
    # The thread driving it died when the parent forked.
    # loop.is_running() → False.
    # Scheduling coroutines onto it produces no results and no errors.
    future = asyncio.run_coroutine_threadsafe(some_coro(), loop)
    future.result()  # blocks forever

This is the kind of bug that produces a zero-width failure window. The loop object exists and looks valid. No exception is raised. Work just never completes. I spent the better part of a day convinced the issue was in the Redis client before realizing the loop scheduled to drive it had died at fork time.

The solution: a persistent bridge loop per worker process

The correct approach is to create a brand-new event loop inside each forked worker process and start a dedicated daemon thread to drive it. The bridge loop is the only asyncio runtime in the worker process. All async work runs on it. Celery's synchronous worker threads never touch an event loop directly.

worker_loop: asyncio.AbstractEventLoop | None = None

@worker_process_init.connect
def init_worker_process(**kwargs):
    global worker_loop

    # Always create a fresh loop in the forked child.
    # Never reuse the inherited parent loop object.
    worker_loop = asyncio.new_event_loop()

    # A daemon thread drives the loop independently of Celery's
    # synchronous execution threads.
    t = threading.Thread(
        target=_run_event_loop,
        args=(worker_loop,),
        daemon=True
    )
    t.start()

def _run_event_loop(loop):
    asyncio.set_event_loop(loop)
    loop.run_forever()

Now the bridge is asyncio.run_coroutine_threadsafe. When Celery calls the synchronous task wrapper, the wrapper schedules the async orchestration coroutine onto the background loop and blocks the worker thread waiting for the result:

def wrapper(self, *args, **kwargs):
    async def _orchestrate():
        # Schema migration, idempotency check, Phoenix heartbeat,
        # OTel span setup, task execution, fence validation, DLQ quarantine.
        result = await your_async_task_function(*args, **kwargs)
        return result

    # Schedule the coroutine from this synchronous thread onto
    # the event loop running on the background thread.
    future = asyncio.run_coroutine_threadsafe(_orchestrate(), worker_loop)

    # Block the Celery worker thread here. All actual work happens
    # on the bridge loop thread.
    return future.result(timeout=300)

run_coroutine_threadsafe is the correct API for this pattern. It is thread-safe, it returns a concurrent.futures.Future (not an asyncio Future), and future.result() blocks without touching the event loop. The background loop thread does all the async I/O. The Celery worker thread just waits.

This solves both problems cleanly:

No asyncio.run() from inside a running loop. The loop lives on a different thread.
No inherited-but-dead loop. Each worker creates its own after fork.

The `push/apush` split

Dispatching tasks has its own version of this problem. Celery's send_task is synchronous and blocking, it opens a broker connection and writes a message. If you call it from inside an async FastAPI route handler, you block the event loop during a network round-trip.

This is why Relier has two dispatch methods:

# From async code (FastAPI, async Django):
receipt = await send_invoice.apush(invoice_id)

# From sync code (Flask routes, sync Django views, scripts):
receipt = send_invoice.push(invoice_id)

apush runs the blocking broker send in an executor so the async caller is never blocked:

async def apush(self, *args, **kwargs):
    # Admission check, schema wrapping, OTel context injection...

    loop = asyncio.get_running_loop()
    return await loop.run_in_executor(
        None,
        lambda: celery_app.send_task(
            self.name,
            args=(envelope,),
            queue=queue,
            task_id=task_id,
        ),
    )

push explicitly guards against being called from inside a running loop:

def push(self, *args, **kwargs):
    try:
        asyncio.get_running_loop()
    except RuntimeError:
        pass  # No running loop on this thread. Safe.
    else:
        raise RuntimeError(
            f"{self.name}.push() was called from inside a running event loop, "
            "where it would block and deadlock that loop. "
            f"Use `await {self.name}.apush(...)` instead."
        )

    # Inside a Celery worker: reuse the bridge loop.
    if worker_loop and worker_loop.is_running():
        future = asyncio.run_coroutine_threadsafe(
            self.apush(*args, **kwargs), worker_loop
        )
        return future.result(timeout=5.0)

    # Outside Celery (Flask route, script):
    return asyncio.run(self.apush(*args, **kwargs))

The error message in the RuntimeError matters. When someone calls push() from a FastAPI route handler, they get an actionable message telling them exactly what to do instead. Not a silent deadlock. Not a timeout with no context. A specific message at the exact moment the mistake is made.

The check itself, asyncio.get_running_loop() in a try/except RuntimeError is the canonical way to detect whether the current thread is running an event loop. It raises RuntimeError if no loop is running on this thread, which is the safe case for push().

Sync tasks in an async world

What about existing sync task functions? A codebase of def tasks shouldn't require a full rewrite to benefit from Relier's reliability stack.

Inside the orchestration coroutine, execution branches on whether the function is async:

if inspect.iscoroutinefunction(func):
    result = await func(*actual_args, **actual_kwargs)
else:
    result = await asyncio.to_thread(func, *actual_args, **actual_kwargs)

asyncio.to_thread runs the sync function in Python's default thread pool executor. The orchestration layer awaits it without blocking the bridge loop. All the async infrastructure, heartbeat refreshes, Phoenix registration, OTel span updates, fence validation keeps running concurrently on the bridge loop while the sync function runs on a thread pool thread.

The constraint is honest: two-tier timeouts (soft_timeout, hard_timeout) only work for async def tasks. A sync function running in asyncio.to_thread cannot be cooperatively cancelled from outside. Relier raises ValueError at decoration time if you pass timeout parameters to a sync task, rather than silently providing no protection:

@rl_task(soft_timeout=8, hard_timeout=10)  # ValueError at import time
def sync_task(data: str) -> dict:
    ...

# Fix: convert to async def, or remove the timeout parameters.

Failing loudly at decoration time is better than failing silently at runtime when the timeout fires and nothing happens.

Timeout enforcement without thread kills

Two-tier timeouts deserve their own explanation because they interact with the bridge loop in a non-obvious way.

When a task starts, Relier spawns two watcher coroutines as asyncio tasks alongside the actual work:

task_coro = asyncio.create_task(func(*args, **kwargs))

async def _soft_timeout_handler():
    await asyncio.sleep(float(soft))
    if not task_coro.done():
        # Fire the recovery hook. Task keeps running.
        if on_soft:
            await on_soft(ctx)

async def _hard_timeout_handler():
    await asyncio.sleep(float(hard))
    if not task_coro.done():
        task_coro.cancel()  # Delivers CancelledError at next await point.

soft_watcher = asyncio.create_task(_soft_timeout_handler())
hard_watcher = asyncio.create_task(_hard_timeout_handler())

done, pending = await asyncio.wait(
    {task_coro, hard_watcher},
    return_when=asyncio.FIRST_COMPLETED,
)

All three coroutines run concurrently on the bridge loop. The soft timeout fires and calls your recovery hook, where you can call ctx.set_partial(state) to checkpoint work in progress while the task keeps running. If the task doesn't finish before the hard deadline, task_coro.cancel() delivers asyncio.CancelledError at the task's next await point.

No thread kills. No SIGALRM. No OS-level signals. Pure cooperative asyncio cancellation. This matters for cleanup: CancelledError propagates through finally blocks. Resources get released. Partial state gets checkpointed. The task gets quarantined to the DLQ with its full payload and resurrection history. None of that happens with a hard OS kill.

The disposable loop case

One edge case worth knowing: outside a Celery worker in a CLI script, a management command, a test, there's no bridge loop. The task wrapper's loop resolution falls through to creating a fresh event loop just for that call:

def _get_worker_loop():
    # 1. Check for persistent worker bridge.
    if relier.tasks.app.worker_loop is not None:
        return relier.tasks.app.worker_loop

    # 2. Check for a running loop on this thread (test contexts).
    try:
        return asyncio.get_running_loop()
    except RuntimeError:
        pass

    # 3. Create a disposable loop for this one call.
    loop = asyncio.new_event_loop()
    asyncio.set_event_loop(loop)
    return loop

Disposable loops are cleaned up after the call: Redis connections are closed, the loop is stopped and closed, and asyncio.set_event_loop(None) clears the thread-local reference. The persistent worker_loop is specifically excluded from this cleanup path closing the bridge loop mid-execution would kill all in-flight tasks.

What I learned

The prefork problem is the kind of failure that shows up as "nothing happens" rather than an exception. You schedule coroutines, they don't run, no error surfaces. It took a day of debugging the wrong thing before I isolated it to the inherited-but-dead loop. The fix (create a fresh loop in worker_process_init) is obvious in retrospect. Getting there required understanding exactly what fork() does to threads.

asyncio.run_coroutine_threadsafe is underused. Most Python developers never need to cross a thread boundary into a running event loop, so the API is obscure. But for anything that marries a sync framework (Celery, Django ORM, WSGI in general) with async internals, it is the correct and safe way to do it. It appears in the Python docs in a single paragraph. It deserves more.

The two-method dispatch split (push/apush) is the right API surface even though it introduces surface area. The alternative, a single method that auto-detects the context and does the right thing sounds better but produces confusing failures when the auto-detection is wrong. The explicit split makes the contract clear. Async code always uses apush. Sync code always uses push. The guard in push() exists so that misuse produces a useful error immediately rather than a deadlock ten seconds later.

Cooperative timeout cancellation is better than OS-level signals for tasks that care about cleanup. The finally block guarantee is the part that matters: partial state can be persisted, connections can be closed, the DLQ entry gets written with everything needed to re-inspect or re-dispatch. An OS kill gives you none of that.

The whole bridge, bridge loop thread, run_coroutine_threadsafe, push/apush split, disposable loop cleanup is about 200 lines in app.py and decorator.py combined. The complexity is real but contained. Once the pattern is in place, every async def task function just works, without the task author knowing anything about the event loop infrastructure underneath.

GitHub: github.com/getrelier/relier

Docs: getrelier.github.io/relier

pip install relier

Building a Design System Without Recreating CSS

Drew Marshall — Mon, 22 Jun 2026 23:17:44 +0000

One of the easiest traps to fall into when building a design system is accidentally recreating CSS.

At first, it seems harmless.

You add a few utility classes.

Then a few responsive options.

Then a few layout helpers.

Then a few exceptions.

Before long, you've built an entirely new syntax for doing the exact same thing CSS already does.

I've become increasingly interested in a different approach.

Not replacing CSS.

Not hiding CSS.

Creating a layer above CSS that focuses on intent.

The Problem With More Options

Developers love flexibility.

I do too.

The challenge is that flexibility often comes with complexity.

Consider responsive layouts.

Many systems solve this by exposing every possible breakpoint and layout combination.

The result is powerful.

But it's also easy to end up with markup that spends more time describing implementation details than communicating purpose.

The system becomes harder to understand.

Not because it's incapable.

Because it's trying to describe everything.

Intent Versus Implementation

Lately I've been thinking less about how a layout is built and more about what the layout is trying to accomplish.

For example:

<div content adapt="grid" mobile="stack">

This isn't trying to replace CSS.

It's trying to express intent.

The content should adapt as a grid.

On mobile, it should stack.

The implementation details can remain inside the design system.

The goal isn't more abstraction.

The goal is better communication.

Strong Defaults Create Simplicity

One lesson I've learned from building software is that good defaults are often more valuable than endless configuration.

Most layouts follow common patterns.

Most responsive behavior follows common patterns.

Most developers aren't trying to create entirely new layout systems.

They're trying to organize content.

A design system can help by providing thoughtful defaults rather than exposing every possible option.

The Danger Of Recreating CSS

The moment a design system attempts to expose every CSS capability, it starts competing with CSS itself.

That's usually a losing battle.

CSS already exists.

CSS is already powerful.

CSS is already standardized.

The job of a design system isn't to replace CSS.

The job of a design system is to reduce cognitive load.

To create consistency.

To communicate intent.

To make common patterns easier.

Designing For Readability

One question I increasingly ask when designing APIs is:

"Can I understand this six months from now?"

Not:

"Can I configure everything?"

Not:

"Can I support every edge case?"

Simply:

"Can I read this and understand what it is trying to do?"

Readability scales.

Complexity doesn't.

The Goal Isn't Less Power

Sometimes simplicity gets mistaken for limitation.

I don't think that's true.

The goal isn't to remove power.

The goal is to place power where it belongs.

Common workflows should be simple.

Advanced workflows should remain possible.

The design system should help developers move quickly without preventing them from solving unique problems.

Final Thoughts

I've become increasingly convinced that the best design systems don't try to replace CSS.

They try to create a shared language around common design decisions.

A language focused on intent rather than implementation.

A language that helps developers communicate purpose.

Because at the end of the day, most developers aren't trying to build layouts.

They're trying to build products.

The layout is simply one part of the system.

Why Daily Transaction Volume is the Wrong Number to Quote in System Design Interviews

Aliasgar — Mon, 22 Jun 2026 23:14:14 +0000

The Mistake Most Candidates Make
Picture this: You are in a system design interview. The interviewer asks you to design a ledger system or a payment settlement pipeline. Eager to show you can handle scale, you confidently state, "We'll design this to handle 100K transactions a day."

The interviewer nods. But that number just told them very little about whether you can actually engineer the system.

Leading with total daily volume is the most common trap candidates fall into. It sounds like a big, impressive number. But in reality, quoting a daily aggregate proves you are looking at the system through a marketing lens, not an engineering one.

What Actually Matters: The Shape of the Workload
Systems do not experience load as a perfectly smooth, distributed stream over 24 hours. They experience load in waves, spikes, and violent bursts. To design a resilient architecture, the raw daily number is useless. You need three specific dimensions:

Peak TPS (Transactions Per Second): The absolute highest throughput the system must sustain during peak traffic.

Workload Shape: How traffic distributes over time — business hours concentration, sudden marketing flashes, or scheduled batch windows.

Burst Duration: How long that peak sustained load lasts. Is it a 5-second spike or a 45-minute sustained mountain?

Let's do the math that most engineers skip in an interview.

If you take 100K transactions and spread them evenly across 24 hours, you get roughly 1 TPS — one transaction per second. A modest, single-core database instance running on a laptop can handle that in its sleep. You don't need a distributed system for 1 TPS; you barely need a framework.

But real-world systems don't work that way.

A Real-World Case Study: The Deceptive Average
I ran into this exact problem while building an end-of-day (EOD) reconciliation service for a major instant payment rail — one that processes tens of thousands of financial transactions daily and must verify every single one against an external banking ledger within a strict compliance window.

On paper, the system processed around 100K transactions a day. Reasonable. Manageable. Nothing alarming.

But the shape of the workload told a completely different story.

Daytime traffic trickled in slowly. Then, as merchants settled their books, payroll batches triggered, and consumers made last-minute transfers, load climbed sharply toward end of day. And at the reconciliation window itself — where the external bank flushed the final ledger data in a concentrated burst — everything had to be processed before the next business day opened.

When we actually measured the workload shape during that final window, the naive average and the engineering reality had almost nothing in common:

Naive average: ~1 TPS, spread across 24 hours

Actual peak: 22 TPS, concentrated in a 45-minute EOD window

That is a 22x gap between the number you'd quote in a planning meeting and the number your system actually has to survive.

Why This Changes Every Engineering Decision
If you design for 1 TPS average, you might reasonably ask: do we even need a message queue here? A simple cron job running a sequential loop would work.

But when you design for a 22 TPS burst with heavy downstream dependencies, the entire architectural conversation shifts.

Thread pool sizing — your reconciliation worker can no longer be a single-threaded job. You have to reason about concurrency, resource contention, and memory footprints before writing a single line of code.

Idempotency is non-negotiable — at burst load, network hiccups happen and retries are guaranteed. If your database upsert logic isn't strictly idempotent, you will be reconciling duplicates at 3 AM wondering why the ledgers don't balance.

Downstream capacity limits — the external banking APIs you are calling have their own strict rate limits. Your 22 TPS ambition is irrelevant if the counterparty throttles you at 5 TPS. This forces you to design token-bucket rate limiters and robust client-side queuing — and to invest in building an in-house downstream simulator that covers all failure paths, not just the happy path.

Pragmatic architecture over greenfield hype — when faced with a compressed burst window and complex recovery paths, a trendy event-driven microservices approach might introduce massive operational complexity. If the external bank operates on a secure, file-based exchange model, a robust file-chunking batch architecture might actually be the more defensible, resilient choice for Phase 1. It's boring, but it's correct.

The Questions an Interviewer Actually Wants You to Ask
Whenever an interviewer hands you a vague requirement like "Design a system that handles X hundred thousand requests a day," don't immediately start drawing boxes on the whiteboard.

Stop. And ask the single question that separates senior practitioners from theorists:

"What does the peak traffic look like, and over what specific window does it occur?"

From there, you want to understand whether specific business events — market close, midnight clearing, payroll batches — concentrate the load into a predictable window, and what the latency and rate limits of your downstream dependencies look like precisely during that window.

When you ask these questions, the interviewer knows you have actually operated systems at scale. You are no longer guessing; you are gathering the constraints required to build a real system.

Closing Thought
Daily transaction volume is a marketing number.

Peak TPS over a compressed burst window is an engineering number.

The next time you are in the hot seat, ignore the aggregate daily volume. Figure out the shape of the peak, calculate the true strain on the system, and design for that instead.

If this kind of thinking is what you want to sharpen before your next system design round, I work with senior engineers on exactly this — translating real production experience into interview-ready depth. You can find me at topmate.io/aliasgar_kantawala.

Have you ever built a scale web app, testing it everything works well, only for it to break when there are many visits on the site? Here below is a guide to prevent this from happening while using Django.

CodeXmingle — Mon, 22 Jun 2026 23:13:28 +0000

CodeXmingle

Jun 22

Why Your Django Application Becomes Slow — And How Experienced Developers Prevent It

#django #python #beginners #database

3 min read

Automate creation of Amazon CloudWatch alarms

Jonas Barros — Mon, 22 Jun 2026 23:13:10 +0000

Recently I developed a new feature for this Github Action to automate the creation of AWS Cloudwatch alarms.
Next steps I will show you the settings you need to add to your project to automate creation of CloudWatch alarms.

Prerequisites

1- Your project should use the github actions

2- Your user must have permissions to create an OpenID Connect IDP, policies, and roles in your AWS account.

3- AWS CLI installed on your computer to make it easier to create IAM policies, roles, and a new IDP to connect to the GitHub account.

More informations about other features and prerequisites is available at Automate Dashboards Quick Start

Quick Start

Before starting, add the code snipet to your Github Actions file:

#... before code

# *** ADD THE CODE SNIPET BELOW ***
jobs:
  AssumeRoleAndCallIdentity:
    runs-on: ubuntu-latest
    steps:
      # Add this step to authenticate on the AWS account 
      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@v1.7.0
        with:
          role-to-assume: arn:aws:iam::AWS_ACCOUNT_ID:role/to_enable_creating_dashbaords
          role-session-name: GitHub_to_AWS_via_FederatedOIDC
          aws-region: ${{ env.AWS_REGION }}

      # Add this step to load the github action
      - name: create dash
        env: 
          ACTION_NAME: ${{ secrets.ACTION_NAME }} # Create a new environment in your repository with the SNS ARN value
        uses: "JonasBarros1998/automate-dashboards@latest"

#... after code

The full Github workflow file should look similar to this:

# File location: .github/workflows/action.yml
name: Connect to an AWS role from a GitHub repository and install the action to create dashbaord in the CloudWatch

# Execute the action when the user opens a new issue
on:
  issues:
    types: [opened]

# Change the region to your current region
env:
  AWS_REGION: "us-east-1"

permissions:
  id-token: write
  contents: read

# *** ADD THE CODE SNIPPET BELOW ***
jobs:
  AssumeRoleAndCallIdentity:
    runs-on: ubuntu-latest
    steps:
      # Add this step to authenticate with AWS account 
      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@v1.7.0
        with:
          role-to-assume: arn:aws:iam::AWS_ACCOUNT_ID:role/to_enable_creating_dashbaords
          role-session-name: GitHub_to_AWS_via_FederatedOIDC
          aws-region: ${{ env.AWS_REGION }}

      # Add this step to load the Github Action
      - name: create dash
        env: 
          ACTION_NAME: ${{ secrets.ACTION_NAME }} # Create a new environment in your repository with the SNS ARN value
        uses: "JonasBarros1998/automate-dashboards@latest"

${{ secrets.ACTION_NAME }}: Add a new repository secret to your Github repository with your SNS ARN value. Create an SNS topic to send notifications to you when an alarm status is triggered.

**If your project is public, we highly recommend creating a Github repository secret to safely store the ARN value of your SNS topic.

How to execute the action to create alarms in AWS CloudWatch alarms

To automate AWS CloudWatch Alarms, you need to open a new issue with the title Create Dashboard. In body of the issue, add the JSON configuration specifyng the settings for your new alarms.

For example, you can send this json if you want to create a new alarm for an AWS Lambda.

{
  "title": "dashboard-services",
  "region": "us-east-1",
  "services": [
    {
      "enable": false,
      "serviceName": "change-data-capture",
      "serviceType": "Lambda",
      "alarms": [
        {
          "metric": "Duration",
          "period": 600, 
          "statistic": "Average",
          "condition": "GreaterThanOrEqualToThreshold",
          "threshold": 1
        },
        {
          "metric": "Invocations",
          "period": 600, 
          "statistic": "Sum",
          "condition": "LessThanOrEqualToThreshold",
          "threshold": 1
        },
        {
          "metric": "Errors",
          "period": 600, 
          "statistic": "Sum",
          "condition": "GreaterThanThreshold",
          "threshold": 1
        }
      ]
    }
  ]
}

If you wish to add 2 or more services, use the JSON format below:

{
    "title": "dashboard-services",
    "region": "us-east-1",
    "services": [
        {
            "enable": false,
            "serviceName": "change-data-capture",
            "serviceType": "Lambda",
            "alarms": [
                {
                    "metric": "Duration",
                    "period": 600,
                    "statistic": "Average",
                    "condition": "GreaterThanOrEqualToThreshold",
                    "threshold": 1
                },
                {
                    "metric": "Invocations",
                    "period": 600,
                    "statistic": "Sum",
                    "condition": "LessThanOrEqualToThreshold",
                    "threshold": 1
                },
                {
                    "metric": "Errors",
                    "period": 600,
                    "statistic": "Sum",
                    "condition": "GreaterThanThreshold",
                    "threshold": 1
                }
            ]
        },
        {
            "enable": true,
            "serviceName": "dashboard",
            "serviceType": "Dynamodb",
            "alarms": [
                {
                    "metric": "ConsumedReadCapacityUnits",
                    "period": 600,
                    "statistic": "Sum",
                    "condition": "GreaterThanThreshold",
                    "threshold": 1
                },
                {
                    "metric": "ConsumedWriteCapacityUnits",
                    "period": 600,
                    "statistic": "Sum",
                    "condition": "GreaterThanThreshold",
                    "threshold": 1
                }
            ]
        },
        {
            "enable": false,
            "serviceName": "my-topic-dashboards",
            "serviceType": "SNS",
            "alarms": [
                {
                    "metric": "NumberOfNotificationsFailed",
                    "period": 600,
                    "statistic": "Sum",
                    "condition": "GreaterThanThreshold",
                    "threshold": 1
                },
                {
                    "metric": "NumberOfMessagesPublished",
                    "period": 600,
                    "statistic": "Sum",
                    "condition": "GreaterThanThreshold",
                    "threshold": 1
                }
            ]
        }
    ]
}

Yout opened issue should should look similar to this example

More informations about the JSON attributes

enable:
  description: If set `true`, it enables the creation of a new CloudWatch dashboard, but if to set `false`, the action will create a new CloudWatch alarm instead. 
  type: boolean
  accept values: true or false

metric: 
  description: The metric name for the CloudWatch alarm
  type: String
  accept values: NumberOfObjects, BucketSizeBytes, NumberOfMessagesSent, NumberOfMessagesReceiver, NumberEmptyMessages, NumberOfNotificationsFailed, NumberOfMessagesPublished, Duration, Invocations, Errors, ConsumedReadCapacityUnits, ConsumedWriteCapacityUnits, CPUUtilization, StatusCheckFailed_Instance.

period:
  description: To monitoring period specified in seconds
  type: Integer
  requiriment values: Any value greather than 0. For example 600 seconds is equivalent to 10 minutes

statistic: 
  description: The metric statistic
  type: String
  requiriment values: We currently accept the `Sum` value. 

condition: 
  decsription: The alarm condition. If the condition is met, the alarm triggers and sends a notification to the specified SNS topic.
  type: String 
  requiriment values: "GreaterThanThreshold", "LessThanOrEqualToThreshold", "GreaterThanOrEqualToThreshold", "LessThanLowerThreshold"

Once you have completed all steps, create your issue and monitor the workflow execution.

The issue format should follow the example provided below.
Example

Open a new issue if you search some problem after executed the workflow.

Currently supported AWS services for CloudWatch alarm automation:

AWS Lambda
AWS Dynamodb
AWS EC2
AWS SNS
AWS SQS
AWS S3

Cron jobs sin Celery, sin Redis, sin Beat: cómo Fitz mete un scheduler distribuido adentro del lenguaje

Martin Palopoli — Mon, 22 Jun 2026 23:10:31 +0000

Para correr una task cada 5 minutos en Python necesitás Celery + Redis + Celery Beat + worker process + Dockerfile dedicado. En Fitz es un decorador. Con retry, timezone, persistencia y catch-up adentro del lenguaje.

La historia de siempre

Tu cliente está contento con la API. Está corriendo. Entonces te pide tres cosas:

"¿Podemos limpiar sesiones vencidas cada noche?"
"¿Podés mandar el email de bienvenida en background así el signup no espera?"
"El reporte diario tiene que correr a las 9 AM hora de Buenos Aires."

Tres pedidos chicos. Si estás en Python, la respuesta honesta es: "ok, dame dos días para meter Celery."

El stack típico de Python

pip install celery redis

celery_app.py:

from celery import Celery
from celery.schedules import crontab

celery_app = Celery(
    "myapp",
    broker="redis://redis:6379/0",
    backend="redis://redis:6379/1",
)

celery_app.conf.beat_schedule = {
    "cleanup-sessions-nightly": {
        "task": "myapp.tasks.cleanup_old_sessions",
        "schedule": crontab(hour=3, minute=0),
    },
    "daily-report": {
        "task": "myapp.tasks.generate_daily_report",
        "schedule": crontab(hour=12, minute=0),  # 9am Buenos Aires = 12:00 UTC
        # ojo: si DST cambia, esto te llega tarde
    },
}
celery_app.conf.timezone = "UTC"

tasks.py:

from .celery_app import celery_app
from .db import get_session

@celery_app.task(autoretry_for=(Exception,), retry_backoff=True, max_retries=3)
def cleanup_old_sessions():
    with get_session() as s:
        s.execute("DELETE FROM sessions WHERE expires_at < now()")
        s.commit()

@celery_app.task(autoretry_for=(SMTPError,), retry_backoff=True, max_retries=5)
def send_welcome_email(email: str):
    smtp.send(email, "Welcome!")

api.py:

@app.post("/signup")
def signup(creds: Credentials):
    user = create_user(creds)
    send_welcome_email.delay(user.email)  # fire-and-forget vía broker
    return user

docker-compose.yml:

services:
  api:
    build: .
    command: uvicorn api:app --host 0.0.0.0
  celery-worker:
    build: .
    command: celery -A celery_app worker --loglevel=info
    depends_on: [redis]
  celery-beat:
    build: .
    command: celery -A celery_app beat --loglevel=info
    depends_on: [redis]
  redis:
    image: redis:7-alpine

Mas:

Un supervisord.conf o systemd unit que mantenga viva la cosa cuando crashee.
(Opcional) flower para visibility — 4to proceso.
Conversiones de timezone hechas a mano (Celery beat trabaja en UTC, vos tenés que calcular el offset).
Cuando el worker crashea entre que pegó al broker y completó la task: ¿se reintenta? ¿queda colgada? Depende de cómo te configuraste el acks_late y task_reject_on_worker_lost.

Cuatro procesos en producción. Tres librerías nuevas. Un broker. Convenciones nuevas. Un día de setup.

Lo mismo en Fitz

@cron("0 3 * * *", tz="UTC")
async fn cleanup_old_sessions(db: DbConn) {
    db.exec("DELETE FROM sessions WHERE expires_at < now()").await
}

@cron("0 9 * * *", tz="America/Argentina/Buenos_Aires")
async fn daily_report(db: DbConn) {
    // ...
}

@background
async fn send_welcome_email(email: Str) {
    // cosa cara
}

@post("/signup")
fn signup(creds: Credentials) -> User {
    let user = create_user(creds)
    spawn(send_welcome_email(user.email))  // fire-and-forget tipado
    return user
}

docker-compose.yml:

services:
  api:
    build: .

Eso es todo. Un binario. Un proceso. Sin broker. Sin worker dedicado. Sin beat. El scheduler corre adentro del proceso de Fitz.

La tabla cruda

Item	Python (Celery + Redis + Beat)	Fitz
Setup inicial	4 archivos + 3 servicios + 1 broker	1 decorador
Schedule	`crontab(hour=3, minute=0)` en config	`@cron("0 3 * * *")`
Timezone	UTC + offset manual	`tz="America/Argentina/Buenos_Aires"`
Retry/backoff	`autoretry_for=(...)` + `retry_backoff=True`	`retry={max=3, backoff="exponential", initial_secs=1, max_secs=30}`
Persistencia de runs	Redis result backend + visualización con Flower	`store=db`, tabla auto-creada en Postgres
Catch-up de runs perdidos	No nativo	`catch_up=true`
Background fire-and-forget	`.delay(arg)` con broker	`spawn(fn_call)` directo
Type checking de args	Ninguno (todo serializado vía JSON)	Static —`spawn` exige `@background` y refina a `Future<T>`
Procesos en prod	api + worker + beat + redis	api
Imagen Docker	3 (api, worker, beat) + redis	1

Persistencia opt-in con `store=db`

Cuando querés history de runs para auditoría:

@cron("0 3 * * *", store=db, retry={max=3, backoff="exponential"})
async fn cleanup_old_sessions(db: DbConn) {
    db.exec("DELETE FROM sessions WHERE expires_at < now()").await
}

Al boot, Fitz crea (si no existe) fitz_cron_jobs y fitz_cron_runs. Cada attempt queda persistida con started_at/finished_at/status/attempt/error. Lo consultás con SQL plano:

SELECT job_name, status, attempt, error, started_at
FROM fitz_cron_runs
WHERE started_at > now() - interval '24 hours'
ORDER BY started_at DESC;

Sin instalar Flower. Sin webhook para Sentry. Tu DB que ya tenés.

Catch-up

Si el binario estuvo caído entre las 3 AM y las 7 AM y el cron era a las 3:

Celery beat: la oportunidad se pierde. La task no se vuelve a disparar hasta la próxima medianoche siguiente.
Fitz con catch_up=true: al boot, calcula que hubo un run perdido entre last_run_at y now, ejecuta UN run inmediato (no N — evita spam), y vuelve al schedule normal.

@cron("0 3 * * *", store=db, catch_up=true)
async fn cleanup_old_sessions(db: DbConn) { ... }

Retry con backoff configurable

Tres modos de backoff: exponential (1s, 2s, 4s, 8s...), linear (1s, 2s, 3s, 4s...), constant (1s, 1s, 1s...). Con cap max_secs:

@cron("*/10 * * * *",
    retry={ max=5, backoff="exponential", initial_secs=1, max_secs=60 })
async fn sync_external_api(db: DbConn) {
    // 1s → 2s → 4s → 8s → 16s (capeado a 60s si llegara más alto)
}

En Python con Celery:

@celery_app.task(
    autoretry_for=(ConnectionError, TimeoutError),
    retry_backoff=True,
    retry_backoff_max=60,
    retry_jitter=False,
    max_retries=5,
)
def sync_external_api():
    ...

Equivalente. Pero notá que Celery tenés que enumerar las excepciones que disparan retry, y el backoff es un bool en lugar de un kind enum. Fitz hace retry ante cualquier error que devuelva la fn (consistente con el modelo Result del lenguaje), y el modo de backoff es explícito.

Timezone real, no offset hardcoded

Las DST changes son el bug que te despiertan a las 4 AM. Celery beat trabaja en UTC y vos tenés que recordar que entre marzo y noviembre tu cron de las 9 AM Buenos Aires se corre a las 12 UTC, pero el resto del año cambia. Tu cliente está en otro huso. Tu app vende a tres países más.

Fitz acepta IANA timezones directamente:

@cron("0 9 * * *", tz="America/Argentina/Buenos_Aires") async fn buenos_aires() { ... }
@cron("0 9 * * *", tz="America/New_York")              async fn new_york()      { ... }
@cron("0 9 * * *", tz="Asia/Tokyo")                    async fn tokyo()         { ... }

Cada uno corre a las 9 AM local de su tz, con DST manejado por la lib subyacente (chrono-tz). No conversiones a mano.

Background jobs sin broker

# Python
@app.post("/signup")
def signup(creds: Credentials):
    user = create_user(creds)
    send_welcome_email.delay(user.email)  # serializa args → Redis → worker
    return user

// Fitz
@background
async fn send_welcome_email(email: Str) {
    smtp.send(email, "Welcome!")
}

@post("/signup")
fn signup(creds: Credentials) -> User {
    let user = create_user(creds)
    spawn(send_welcome_email(user.email))  // tokio::spawn nativo, tipado
    return user
}

El compilador exige que la fn esté decorada con @background para autorizar el spawn(...) — sin esto, el callsite tira error de tipo en build time. Y refina el retorno a Future<Null> con el tipo concreto del target, no Any. Si send_welcome_email retorna Result<()>, el spawn(...) te lo da tipado.

¿Cuándo NO usar @background y volver a Celery?

Si necesitás que los jobs sobrevivan crashes del proceso → persistencia explícita con store=db cubre cron jobs; para @background con persistencia es deuda residual.
Si necesitás distribuir jobs en N workers en N nodos → Celery con un broker compartido sigue siendo la respuesta. @background corre en el proceso.

Para el 90% de servicios (cleanup nocturno, email transaccional, recálculo de KPIs, sync de cache) el modelo de Fitz alcanza y sobra.

Cron-only mode para systemd

Para servicios que SOLO tienen jobs (sin HTTP), fitz build produce un binario que arranca el scheduler y bloquea con ctrl+c:

@cron("0 3 * * *") async fn cleanup() { ... }
@cron("*/15 * * * *") async fn sync() { ... }

Como systemd unit:

[Unit]
Description=Scheduled jobs for myapp
After=network.target

[Service]
ExecStart=/usr/local/bin/myapp-jobs
Restart=always
User=myapp

[Install]
WantedBy=multi-user.target

Cero brokers. El binario es 5 MB. systemctl restart myapp-jobs y listo.

Paridad bit-a-bit `fitz run` ↔ `fitz build`

Esto es lo que vuelve esto entregable: el binario que producís con fitz build ejecuta el mismo scheduler que fitz run, con el mismo cron expression parser, los mismos retries, la misma timezone. Misma sintaxis, mismas semánticas, sin "ah esto solo funciona en producción si configurás Celery".

Lo que Fitz NO te da (todavía)

Soy honesto sobre dónde no llega:

Distribuir jobs en N workers/nodos compartiendo cola. @cron corre en el proceso. Si corrés dos binarios con el mismo @cron, ambos disparan — bug, no feature. Para horizontal scaling de jobs, sigue siendo Celery (o NATS JetStream, o Temporal). Hay deuda explícita en el roadmap sobre locks distribuidos.
UI tipo Flower. Los datos están en fitz_cron_jobs y fitz_cron_runs. Si querés dashboards, dashboards externos (Grafana, Metabase) cubren.
@background con persistencia entre restarts. Para @cron está en v0.11.2 (cierre 9.w.3.iter2). Para @background arranca el spawn pero no sobrevive crash — diferido a iter3 si entra demanda.
Cancelación de jobs en flight. Hoy no hay API para "cancelar todos los runs en cola de X job". El proceso muere → los runs en flight mueren con él.

Si estás en uno de esos casos, Fitz no es la herramienta hoy. Si no, el modelo de un solo binario cubre el caso real con menos partes móviles.

Cierre

El argumento para sumar Celery a una API en Python típicamente es: "pero después escala mejor." En el 90% de los servicios que escribí en la última década, ese "después" nunca llegó — la app pasó toda su vida útil con menos de 100 jobs por hora y nunca necesitó un cluster de workers.

Para ese 90%, Fitz reemplaza 4 procesos + 3 librerías + 1 broker con un decorador. Cuando llegues al otro 10% donde necesitás scaling horizontal real, Celery sigue ahí — from python import celery también está disponible, podés hacerlo tú mismo.

Pero arrancar el proyecto con el modelo más simple posible y subir la complejidad solo cuando lo necesitás es el ciclo de feedback que Fitz quiere darte.

Próximo post de la serie: "Auth con JWT, RBAC y token blacklist sin pegar 5 librerías: Fitz vs FastAPI + python-jose + passlib + Redis blacklist" — el flow completo de auth, lado a lado.

Repo: github.com/Thegreekman76/fitz
Capítulo 30 de la guía (Jobs sin Celery): docs/guide.md