I benchmarked Claude Code context management strategies and discovered the biggest cost savings come from somewhere else entirely.

To /compact or not to /compact, that is the question.


Every team I've worked on eventually reaches the same point with E2E tests: they start as a handful of scripts someone wrote in a hurry, and six months later they're a tangled mess that breaks on every deploy. Tests duplicate locators, share state in weird ways, and nobody wants to touch them.

I got tired of rebuilding the same structure from scratch every time, so I built a template that captures the patterns I keep reaching for. It's open source and you can grab it here: [playwright-ts-template-pom](https://github.com/Kazaz-Or/playwright-ts-template-pom).

To be honest I wanted to do it for a while but never had the time to write it down. Nowdays with the assist from your favorite coding agent I finally did, and this post is the write-up of the design decisions, the architecture, and how each piece fits together.

This post walks through the design decisions, the architecture, and how each piece fits together. It's not a Playwright tutorial — the docs are excellent for that. This is about the layer on top: how to organize a real test suite that doesn't fall apart at scale.

### Why Page Object Model?

The Page Object Model isn't new or exciting. That's kind of the point.

The idea is simple: every page in your app gets a class that owns all the locators and actions for that page. Tests never call `page.locator()` directly. Instead, they talk to the page object.

```typescript
// Without POM — locators scattered everywhere
test('should display hero heading', async ({ page }) => {
  await page.goto('/')
  const heading = page.getByRole('heading', { level: 1 })
  await expect(heading).toBeVisible()
})

// With POM — clean, readable, maintainable
test('should display hero heading @sanity', async ({ homePage }) => {
  await homePage.navigate()
  await expect(homePage.heroTitle).toBeVisible()
})
```

When a UI element changes, you fix it in one place — the page object — not in thirty tests. I've seen teams waste entire sprints updating selectors across test files because they didn't have this separation. It's the single most impactful pattern in test automation, and it's boring in the best possible way.

### The Architecture

Here's how everything is layered:

![Architecture Diagram](https://res.cloudinary.com/dtt2usukl/image/upload/v1788378917/pomframeworkstrucutre_dfbkox.png)

Tests sit at the top and only talk to the fixtures layer. Fixtures inject page objects, helpers, and API clients. Page objects compose shared components (like the navbar and footer). Everything below is infrastructure that tests don't need to know about.

This layering means a test file looks like a specification, not like Playwright API calls stitched together.

### Fixtures Are the Glue

Playwright's fixture system is one of its best features, and it's the backbone of this template. Instead of manually creating page objects in every test, they're injected automatically:

```typescript
import { test as base } from '@playwright/test'
import { HomePage } from '../pages/home.page'
import { AssertionsHelper } from '../helpers/assertions.helper'

export const test = base.extend<TestFixtures>({
  homePage: async ({ page }, use) => {
    await use(new HomePage(page))
  },
  assertions: async ({ page }, use) => {
    await use(new AssertionsHelper(page))
  },
  blogApi: async ({}, use) => {
    await use(new BlogApi())
  },
  // ... 11 fixtures total
})
```

Every test destructures exactly what it needs. No global setup, no shared mutable state, no import chains. If a test needs the homepage and the assertions helper, it asks for them. If it only needs the API client, it asks for that. Playwright handles lifecycle and teardown.

This is dependency injection done right — lightweight, explicit, and type-safe.

### Components: Shared UI Pieces

Most apps have elements that appear on every page — a navbar, a footer, a search bar. In the template, these are modeled as components that get composed into page objects through a base class:

```typescript
export abstract class BasePage {
  readonly navbar: NavbarComponent
  readonly footer: FooterComponent

  constructor(protected readonly page: Page) {
    this.navbar = new NavbarComponent(page)
    this.footer = new FooterComponent(page)
  }

  abstract get path(): string

  async navigate(): Promise<void> {
    await this.page.goto(this.path)
    await this.page.waitForLoadState('domcontentloaded')
  }
}
```

Every page object extends `BasePage`, so every page automatically has access to navbar and footer actions. No duplication, no forgetting to initialize them.

### Helpers: Reusable Assertions and Utilities

Raw `expect()` calls work fine, but they get repetitive. The template includes helpers that wrap common assertion patterns:

```typescript
// Domain-specific assertions
await assertions.assertNoImageErrors() // Checks every <img> loaded
await assertions.assertMetaTag({ property: 'og:title', content: 'My Post' })
await assertions.assertOpenGraphTags()
await assertions.assertHasHeadings()

// Navigation helpers
await navigation.assertLinkNavigation('About', /\/about/)
await navigation.goBack()

// Performance measurement
const metrics = await performance.assertBudget(PerformanceBudgets.static)
performance.printMetrics(metrics)

// Accessibility (axe-core)
await a11y.assertNoCriticalViolations({ disableRules: ['color-contrast'] })
```

These aren't clever abstractions — they're shortcuts for things you'd write over and over. The accessibility helper wraps `@axe-core/playwright` so you can run WCAG audits in a single line. The performance helper measures Web Vitals (TTFB, FCP, LCP, CLS) and asserts them against configurable budgets.

The image checker was actually an interesting problem to solve. On Chromium, checking `naturalWidth > 0` works immediately. On Firefox and WebKit, lazy-loaded images (especially Next.js optimized ones) report `naturalWidth` as 0 because they haven't decoded yet. The fix was to scroll each image into view and wait for the load event before checking:

```typescript
async assertNoImageErrors(): Promise<void> {
  const images = await this.page.locator('img').all();
  for (const img of images) {
    await img.scrollIntoViewIfNeeded();
    const naturalWidth = await img.evaluate((el) => {
      const imgEl = el as HTMLImageElement;
      if (imgEl.complete && imgEl.naturalWidth > 0) return imgEl.naturalWidth;
      return new Promise<number>((resolve) => {
        imgEl.onload = () => resolve(imgEl.naturalWidth);
        imgEl.onerror = () => resolve(0);
        setTimeout(() => resolve(imgEl.naturalWidth), 5000);
      });
    });
    const src = await img.getAttribute('src');
    expect(naturalWidth, `Image failed to load: ${src}`).toBeGreaterThan(0);
  }
}
```

Small detail, but this is exactly the kind of thing that breaks your CI at 3am and takes an hour to debug. Having it solved once in a helper means you never think about it again.

### API Testing Without a Browser

Not everything needs a browser. The template includes an API layer built on axios for testing endpoints directly:

```typescript
export class BlogApi {
  private readonly client: AxiosInstance

  constructor(baseURL?: string) {
    this.client = axios.create({
      baseURL: baseURL ?? EnvConfig.baseUrl,
      timeout: 15_000,
      validateStatus: () => true, // Never throw on status codes
    })
  }

  async checkPageExists(path: string): Promise<boolean> {
    const response = await this.client.get(path, { maxRedirects: 5 })
    return response.status >= 200 && response.status < 400
  }

  async getRssFeed(): Promise<ApiResponse<string>> {
    /* ... */
  }
  async getResponseHeaders(path: string): Promise<Record<string, string>> {
    /* ... */
  }
}
```

The `validateStatus: () => true` is intentional — it means axios never throws on HTTP errors, so you can assert on status codes explicitly in tests rather than catching exceptions. Makes tests much more readable.

API tests are fast because they skip browser rendering entirely. They're good for smoke-checking that pages return 200, RSS feeds are valid XML, and headers are set correctly.

### Test Data Factory

Hardcoded test data is a trap. It makes tests brittle and hides assumptions. The template uses a factory pattern with faker.js:

```typescript
test('search handles random queries @regression', async ({ homePage }) => {
  await homePage.navigate()
  const query = TestDataFactory.searchQuery() // Random word
  await homePage.navbar.search(query)
})

test('XSS payloads are handled safely @regression', async ({ homePage }) => {
  await homePage.navigate()
  for (const payload of TestDataFactory.xssPayloads()) {
    await homePage.navbar.search(payload)
    const title = await homePage.page.title()
    expect(title).not.toContain('xss')
    await homePage.navbar.clearSearch()
  }
})
```

The factory generates random search queries, fake blog slugs for 404 testing, XSS payloads for security tests, and viewport sizes for responsive testing. It keeps test data close to the tests that use it without coupling them to specific values.

### The Tagging Strategy

Every test in the template is tagged as either `@sanity` or `@regression`:

```typescript
test('should display hero heading @sanity', async ({ homePage }) => {
  /* ... */
})
test('clicking Explore Articles navigates to blogs @regression', async ({
  homePage,
}) => {
  /* ... */
})
```

This isn't just for organization — it drives the CI pipeline. Sanity tests are the critical path: page loads, core navigation, the things that must work. They run first, and if they fail, regression tests are skipped entirely. No point running 73 regression tests when the homepage doesn't load.

The current split is 28 sanity tests that run in about 8 seconds and 73 regression tests that cover edge cases, SEO, performance, accessibility, and security.

### CI Pipeline

The GitHub Actions workflow has four stages:

```
Sanity (3 browsers) → Regression (3 shards × 3 browsers) → Report (merge + GitHub Pages) → Summary
```

**Sanity** runs fast across chromium, firefox, and webkit. If any browser fails, regression is skipped entirely (`fail-fast: true`).

**Regression** shards tests across 3 workers per browser — that's 9 parallel jobs. Sharding is important because regression tests include things like performance budgets and accessibility scans that are inherently slower. Running everything sequentially on a single runner would take several minutes. With sharding, it's typically under a minute.

The sharding required adding the `blob` reporter to the Playwright config. Without it, `playwright merge-reports` has nothing to merge — a lesson I learned the hard way when CI reports kept failing to deploy:

```typescript
reporter: [
  ['html', { outputFolder: 'playwright-report', open: 'never' }],
  ['list'],
  ...(process.env.CI ? [['github'], ['blob']] : []),
],
```

**Report** merges all blob reports from the sharded runs into a single HTML report and deploys it to GitHub Pages. Every CI run produces a browsable report with traces, screenshots, and video for failures.

**Summary** writes a GitHub Step Summary with a status table and a direct link to the Pages report. It's a small thing, but it saves time when you're scanning through notifications at 7am.

The workflow triggers on PRs to master, nightly at 04:00 UTC, and manual dispatch with a configurable base URL.

There's also a separate `static-checks.yml` that runs ESLint, Prettier, and TypeScript type checking on every push. These are fast and cheap — there's no reason not to run them on every commit.

### Logging

All scripts use winston instead of `console.log`. This might seem like overkill for a test framework, but structured logging with timestamps and log levels makes debugging CI failures significantly easier. When you're staring at a wall of CI output trying to figure out what happened, having `14:23:05 [ERROR] Failed to send Slack notification: 403` is much more useful than a bare string.

The logger is configured via `LOG_LEVEL` environment variable, so you can crank it up to `debug` when investigating issues without changing code.

### Scripts: Slack and LLM Analysis

The template includes two optional scripts for CI integration:

**Slack Notifier** reads the Playwright JSON report and sends a formatted Block Kit message with test results. Without a webhook URL configured, it prints the payload to the logger — useful for testing the format before hooking it up.

**LLM Failure Analyzer** reads error context files from `test-results/` and sends them to Claude or OpenAI for root-cause analysis. It categorizes failures as test issues (bad selectors), app issues (regressions), or environment issues (timeouts). Without an API key, it falls back to local pattern matching that handles the common cases.

Both are wired into the custom reporter but disabled by default. Uncomment one line in the Playwright config to enable them:

```typescript
reporter: [
  ['./scripts/custom-reporter.ts', { slack: true, llmAnalysis: true }],
],
```

### How to Use This Template

The template is built against my blog ([kazis.dev](https://kazis.dev)) but it's designed to be adapted. The process is:

1. Update `BASE_URL` in your `.env` or `config/env.config.ts`
2. Update routes in `constants/routes.enum.ts`
3. Create page objects by extending `BasePage`
4. Register them in `fixtures/base.fixture.ts`
5. Write tests

That's it. The helpers, components, CI pipeline, reporters, and tagging strategy all carry over. You're not adopting a framework — you're forking a working setup and adjusting the page objects to match your app.

### What I Intentionally Left Out

- **Visual regression testing.** Playwright supports screenshot comparison, but it adds complexity (baseline management, flaky diffs from font rendering) that most teams don't need initially.
- **Database seeding.** This template tests against a live URL. If you need to seed data, add it to the fixtures — the pattern supports it, but the implementation is app-specific.
- **Authentication flows.** Same reasoning — the storage state pattern varies too much between apps to include a generic version.
- **Docker.** The CI runs directly on GitHub runners. If you need containerized execution, wrapping it in Docker is straightforward but adds a layer I didn't want to bake in.

These are all things you might add, but starting without them keeps the template focused on what's universal: structure, patterns, and CI.

### Final Thoughts

The best test frameworks are the boring ones. They use well-known patterns, they're easy to navigate for someone who didn't write them, and they get out of the way so you can focus on what actually matters — writing good tests.

This template is the result of building the same thing several times and finally writing it down. If it saves you a few days of setup, or if it gives you ideas for organizing your own suite, that's a win.

Check it out: [github.com/Kazaz-Or/playwright-ts-template-pom](https://github.com/Kazaz-Or/playwright-ts-template-pom)


A Playwright template I keep reaching for — POM pattern, fixtures, helpers, CI pipeline, and the reasoning behind each piece.

My Go-to Playwright Template Framework for E2E Tests


### The Gauntlet Loop: A Quality Bar AI Can’t Talk Its Way Around

Before getting into the technique, here is what I was building. [Dance of Ashes](https://danceofashes.pages.dev/) is a mobile-first, choice-driven dark-fantasy browser game in which players create a character and navigate ten consequential decisions during a civil war fought with dragons. Each choice affects the character’s relationships, abilities, reputation, achievements, and eventual ending. I began the project using [Legionnaire](https://www.legionnaire.xyz/), developed by [Gal Bartov](https://x.com/Krysuss), as a quality reference—not to copy its football setting or design, but to learn from the way it turns a simple series of decisions into a compelling, persistent career.

The first version was not broken. That was the problem.

It loaded. The buttons worked. The colors were tasteful. It was recognizably the thing I had asked for—and it was completely forgettable.

This is a common failure mode in AI-assisted work. A capable model can produce something locally coherent on its first attempt. Because nothing is obviously wrong, both the model and the human are tempted to call it done. The result clears the low bar of “it works” while missing the much harder bar of “I want to keep using this.”

The Gauntlet Loop is a way to keep that first plausible draft from certifying itself.

Before going further, the credits should be explicit because this project owes two different debts:

- **The method:** This article is a continuation of [Matt Shumer’s original post on X](https://x.com/mattshumer_/status/2081830214384886228?lang=en) and his later explanation, [How to Run a Gauntlet Loop](https://somethingbig.ai/gauntlet-loop). The prompt and project that demonstrated the method are also public in the [Claude of Duty repository](https://github.com/mshumer/Claude-of-Duty).
- **The product reference:** the source and quality bar for my game was [Legionnaire](https://www.legionnaire.xyz/), developed by [Gal Bartov (@Krysuss)](https://x.com/Krysuss). Dance of Ashes is an independent adaptation of lessons I observed in his work; it is not the origin of those interaction ideas.

Gal’s development deserves real praise. Legionnaire compresses an enormous career simulation into a remarkably approachable mobile loop. It makes identity, progression, risk, history, and the next decision legible without making the player feel as though they are operating a spreadsheet. That balance is difficult product work. Its restraint is especially impressive: the game understands that persistent consequences and good pacing can create more attachment than spectacle alone.

What follows is my attempt to apply the idea, understand why it works, and make it useful outside one spectacular demo.

### The real problem is not generation. It is stopping.

Most prompting advice focuses on the input: add context, define a role, request a format, include examples. All of that helps. But once an agent can edit files, run code, inspect a browser, and test its own work, the larger opportunity is no longer a single perfect prompt. It is a better process for deciding when the work is good enough.

A normal agent loop looks something like this:

1. Interpret the request.
2. Build a solution.
3. Look at the solution it just built.
4. Explain why the solution is reasonable.
5. Stop.

Step four is the trap. The builder knows every constraint it encountered and every compromise it made. That context makes it an excellent defense attorney for its own work. It can explain why the spacing is acceptable, why the test coverage is sufficient, or why the interaction is “intuitive.”

But users do not experience the explanation. They experience the artifact.

The Gauntlet Loop changes the stopping rule. Instead of asking the builder whether the work is good, it introduces a real quality bar and a separate critical pass that inspects the finished output. If the reference still wins, the loop continues.

In its simplest form:

> Set a concrete bar. Build. Compare the real artifact against the bar. Fix the largest gap. Repeat.

The loop is simple. Choosing the bar is not.

### A reference is not a mood board

“Make it amazing” is not a quality bar. Neither is “production-ready,” “premium,” or “addictive.” These phrases express ambition, but they give the critic nothing falsifiable to inspect.

A useful bar is concrete enough to win or lose against.

For a visual product, that may be a live site at a specific mobile viewport. For prose, it may be a handful of exemplary passages judged on clarity and compression. For infrastructure, it may be a recovery test, a latency distribution, or a known implementation. Shumer’s write-up makes the same point: the reference does not need to be realistically beatable; it needs to keep the work moving in the right direction instead of allowing “pretty good for AI” to become the finish line.

I used Gal Bartov’s [Legionnaire](https://www.legionnaire.xyz/) as the bar for a mobile browser game. The goal was not to copy its football theme, artwork, content, or interface. It was to study the excellent product decisions underneath them and understand why a session felt like a career rather than a sequence of forms.

That distinction matters. A weak comparison says:

> The reference has large background images, so add large background images.

A stronger comparison asks:

> What does the reference make the player understand, feel, and anticipate—and what mechanisms create that effect?

The live comparison surfaced things that a screenshot alone would have missed. The reference made identity persistent. It showed accumulation clearly. It kept a season-by-season record. Every decision immediately changed a visible career. A collection created unfinished business. The next choice arrived before the energy of the previous one disappeared.

My game, [Dance of Ashes](https://danceofashes.pages.dev/), already had more atmosphere: generated character art, dragons, cinematic endings, music, sound, and animated fire. More spectacle was not the largest remaining gap. The gap was legible continuity.

That led to a different set of changes: a daily shared prophecy, completion streaks, a visible legacy score, persistent decision ledgers, and a Vault that turns old lives into a collection. The reference supplied the standard, not the skin.

## The anatomy of a useful gauntlet

A strong Gauntlet Loop has five parts.

### 1. A destination

Describe the outcome at full ambition. Do not prematurely prescribe the architecture.

“Build a mobile-first browser game people want to replay” leaves room for the agent to discover the right systems. “Add three modals, a WebGL dragon, a PostgreSQL database, and a daily login bonus” may lock the work into an implementation before anyone has proven those are the right ingredients.

Constraints still belong in the prompt. The distinction is between constraints and guesses. “Must work on a phone and deploy as a static site” is a constraint. “Must use React” may just be a guess.

### 2. An inspectable reference

Name the real artifact, test, measurement, or example that represents the bar. The agent must be able to access it and compare against it directly.

If the reference is a website, inspect the live interaction—not only the landing-page screenshot. If the goal involves motion, pacing, audio, or responsiveness, the evidence must include those dimensions. A still image cannot tell you that the pause between two questions feels dead.

### 3. Separation between builder and critic

The full version of the method uses fresh-context critics: the critic receives the goal, rules, reference, and actual artifact, but not the builder’s diary of effort.

That context separation is not ceremony. It removes the story of how hard the work was. The critic sees what a user sees.

When a separate agent is unavailable, the principle still helps: split building and evaluation into distinct phases, discard the builder’s self-description, and restart the critique from observable evidence. It is weaker than a genuinely independent critic, so say so honestly, but it is still better than asking “how did I do?” in the same breath as the implementation.

### 4. One largest gap per round

A critic that returns 47 observations often creates less progress than one that identifies the most important failure.

The next round should have a sharp target:

- first minute does not establish identity;
- choice feedback takes too long;
- the player cannot explain why the run ended;
- mobile controls obscure the scene;
- the test passes on average latency while p99 is unacceptable.

Fix the largest gap, render or run again, then re-evaluate. This makes each round directional and keeps the agent from polishing low-impact details while the central experience remains weak.

### 5. Evidence and a stopping condition

“The critic loved it” is not evidence.

Useful evidence can be screenshots at fixed viewports, interaction traces, real-device recordings, accessibility checks, test output, performance distributions, or structured blind comparisons. The artifact determines the evidence.

In my case, the visual pass was paired with a simulation of 7,200 careers. That test verified that all 36 events were reachable, no phase was skipped, all four ambition paths could reach their rare endings, and the resulting runs did not collapse into a handful of identical sequences. It did not prove that the game was fun. It did eliminate several ways the game could quietly be broken while looking polished.

The stop condition should also be honest. Stop when the artifact clears the bar, when marginal improvements are no longer worth their cost, or when the compute budget is exhausted. Do not quietly redefine the reference downward.

The public Claude of Duty repository is unusually valuable here because its own assessment says the project did **not** beat Call of Duty in blind comparisons. The bar still produced a far stronger artifact. A gauntlet is a direction and a discipline, not a magical guarantee of victory.

### What usually breaks the loop

The first failure is a vague bar. If the critic must invent what “great” means, it can invent a reason to pass the work.

The second is self-grading. The builder’s context leaks into the judgment, and effort gets mistaken for quality.

The third is evaluating a summary instead of the artifact. “Implemented responsive design and polished animations” tells us nothing about whether the mobile layout clips or the animations feel sluggish.

The fourth is using the wrong evidence surface. Screenshots are good for hierarchy, density, alignment, and visual character. They are poor evidence for latency, sound, pacing, game feel, focus behavior, and failure recovery.

The fifth is arbitrary iteration. “Do five rounds” may stop while the work is still improving—or waste three rounds after progress has stalled. The exit should depend on evidence, not a ritual number.

The sixth is uncontrolled parallelism. Some components can be improved independently; others share state, timing, style, and performance constraints. If ten builders simultaneously optimize tightly coupled parts, integration debt can erase their local gains. Parallelize along real boundaries, then run a whole-artifact smoothing pass.

## A practical prompt shape

The most useful prompt is usually shorter than the operating process behind it. Here is a domain-neutral version:

```text
Build [OUTCOME] at the level of [CONCRETE REFERENCE]. Preserve these
constraints: [CONSTRAINTS]. Decide the implementation yourself.

Break the result into the smallest parts that can be improved and judged
independently. For each important part, use a builder and a separate critic
with fresh context. The critic must inspect the real artifact—not the builder’s
summary—and compare it directly with the reference using [EVIDENCE].

When ours loses, identify the single largest meaningful gap, fix it, and run
the comparison again. Maintain an integration pass across the whole artifact.
Stop only when ours clears the agreed bar, improvements stall under the stated
rule, or the budget is reached. Report any remaining gap honestly.
```

The bracket people pay the least attention to is `[EVIDENCE]`, and it may be the most important one.

For a landing page, it might say: “screenshots at 390×844 and 1440×900, plus keyboard navigation and a performance trace.” For an API: “contract tests, fault injection, p50/p95/p99 latency, and recovery after process termination.” For an article: “a blind edit against these five reference passages, scored for clarity, argument density, and unsupported claims.”

Once the evidence is explicit, criticism becomes actionable.

### What changes for the human

The Gauntlet Loop does not remove human judgment. It moves it upstream.

Instead of manually specifying every feature, the human chooses the ambition, reference, constraints, evidence, and budget. Those decisions shape everything the agent does afterward.

This may be the more durable skill in an age of capable agents: not describing every step, but constructing an environment in which weak work cannot easily approve itself.

There is also a psychological advantage. A high reference gives you permission to reject the first competent result. You are no longer being “too picky.” The work simply has not cleared the bar yet.

## The loop in one sentence

The Gauntlet Loop turns quality from an adjective into a comparison.

That is why it works. The agent is no longer asked to feel more ambitious, praise itself less, or somehow know when a product is addictive. It is given a destination, a rival, an independent judgment, and another round.

The first draft can still be forgettable. It just no longer gets the final vote.

---

_With appreciation to [Matt Shumer](https://x.com/mattshumer_) for developing and sharing the Gauntlet Loop method, and to [Gal Bartov](https://x.com/Krysuss) for building [Legionnaire](https://www.legionnaire.xyz/)—the source product whose thoughtful game design gave this experiment a meaningful bar to pursue.\_

And if you want to see the result of this experiment, you can play [Dance of Ashes](https://danceofashes.pages.dev/). It is a work in progress, but it is playable and demonstrates the ideas discussed here.

![Dance of Ashes](https://res.cloudinary.com/dtt2usukl/image/upload/v1787771881/Screenshot_20260826_221739_avvxol.png)


Why better AI work comes from concrete references, independent criticism, and evidence-driven iteration—not a more enthusiastic version of ‘make it better.

Experimenting With A Gauntlet Loop


Before I get into the details, I must say in advance - This solution was created a long time ago - These days we have many other options available, while they are deffinitley better and easier to use or implement, but since I did this while there were no other good options available, I decided to still write a blog post about it.

For a long time, coding agents have been tied to the machine they're running on. If you wanted Claude Code to review code, create files, or work on a project, you had to sit in front of your dev station. Sometimes, I found it a bit frastrating when I came up with ideas I wanted to implement but it wasn't a good time to do that, thats why I decided to do this.

The goal was simple:

Send a command from my phone and have Claude Code execute it on my development machine from anywhere in the world.

What emerged was a mini architecture built from a handful of lightweight components that many of us have or can get easily:

- A smartphone
- Termux (or any other terminal emulator)
- Tailscale
- A Raspberry Pi
- Coding agent (e.g. Claude Code)
- SSH

The result feels like carrying a personal software engineer in your pocket.

### The Architecture

At a high level, the system looks like this:

Phone
↓
Termux
↓
Tailscale
↓
Raspberry Pi Gateway
↓
SSH
↓
Development Workstation
↓
Claude Code

Instead of exposing a workstation directly to the internet, the Raspberry Pi acts as a gateway layer.
The phone never talks directly to the development machine. Everything flows through a secure private network and a controlled entry point.

Why Not Just SSH Into The Laptop?

Because the goal wasn't remote shell access.
The goal was intent-based development.

Instead of ssh laptop > cd project > open editor > run commands,

I wanted, cc <project-name> "prompt"

The phone becomes a command console for AI-driven development rather than a remote desktop replacement.

### The Power Of A Gateway

The Raspberry Pi ended up serving an important purpose.
Technically, the phone could have talked directly to the workstation.
However, introducing a gateway provides several benefits:

The workstation is never directly exposed, and all requests arrive through a dedicated machine whose sole purpose is routing and validation.

Also, the gateway can eventually queue requests, rate limit usage, log activity, add authentication layers, and route requests to different machines.

Today it forwards commands. Tomorrow it could become a complete AI orchestration layer.

### The Role of Tailscale

One of the biggest challenges in personal infrastructure is networking. Static IPs, port forwarding, dynamic DNS, firewall rules—these are all problems developers have historically had to solve. Tailscale largely eliminates that complexity.

Every device becomes part of a private mesh network. The phone can securely reach the Raspberry Pi regardless of Home Wi-Fi, mobile network, public Wi-Fi, or travel.
Also, no ports need to be opened to the public internet.

The entire setup feels local, even when it's distributed globally.

### Why Termux?

Most mobile development workflows rely on custom apps, web dashboards, or messaging bots (I do have multiple dedicated agents for specific tasks triggered via Telegram, but this one felt different for me).
Termux provides something more powerful: A real terminal.

This means the interaction model remains familiar, no UI needs to be built, no mobile application needs to be maintained, and the phone becomes a portable command-line client.

For developers, this is often the most productive interface possible.

### Claude Code As Infrastructure (Can be any other coding agent of course)

One interesting realization from this project is that Claude Code stops feeling like a coding agent and starts feeling like infrastructure.
Instead of opening Claude and asking it to help with a task, the system treats Claude as a service endpoint.

A request arrives.
A project is selected.
Claude receives context.
Work is performed.
Results are returned.

This shifts AI from an interactive tool to an operational component.

### Things I improved on the way

- Dedicated Worker User: Instead of running under a primary workstation account, Claude could operate under a restricted user with access only to project directories.
- Containerized Execution: Each request could execute inside a disposable container, providing stronger isolation and reproducibility.
- Job Queue: Long-running tasks could be queued and tracked asynchronously.
- Notifications: Results could automatically return through push notifications, Telegram, Discord, Slack, and multi-agent routing.
- Different requests could be routed to different agents: Code reviewer, Test engineer, Documentation writer, Architecture advisor, etc.

### The Bigger Picture

The most interesting part of this project isn't the technology itself.
It's what it represents.
We're moving toward a world where software development isn't tied to a specific device.

The workstation/cloud remains where the compute lives.
The developer becomes location-independent.

Your phone becomes a secure command center capable of initiating meaningful engineering work from anywhere.
A Raspberry Pi, a private network, and an AI coding agent are enough to create something that would have felt like science fiction only a few years ago.

And the best part?
The entire system runs on hardware that most developers already have sitting around at home.

![Sequence-diagram](https://res.cloudinary.com/dtt2usukl/image/upload/v1787765418/7ad1f280-ff80-4dd0-a811-e342e4a52f52_fu5bdf.png)_Sequence diagram of the first iteration_


Have you ever had an idea but not the time or resources to implement it? That is why I built a Remote AI Development Gateway

Running Claude Code From Anywhere


## The Next Step Beyond Chatbots

Most people interact with AI through chat interfaces. They ask a question, receive an answer, and move on.

While this interaction model is powerful, it still requires humans to initiate every task. The AI remains passive, waiting for instructions.

A more interesting direction is emerging: autonomous personal agents.

Instead of answering questions, these systems continuously perform useful work on behalf of a user. They monitor information sources, collect relevant data, make decisions, filter noise, and proactively deliver results.

The difference is subtle but important.

A chatbot responds.

An agent acts.

---

## The Real Problem: Information Consumption Does Not Scale

Software engineers, technology leaders, and technical enthusiasts consume information from dozens of sources:

- RSS feeds
- GitHub repositories
- Hacker News
- Reddit communities
- Technical blogs
- Product announcements
- AI research updates
- Social media discussions

The volume of content has become impossible to process manually.

Ironically, the problem is no longer finding information.

The problem is deciding what deserves attention.

Every day thousands of articles are published, hundreds of repositories trend, and dozens of new tools appear. Most are irrelevant. A few are valuable.

Finding those few valuable items is increasingly difficult.

---

## Personal Agents as Information Filters

A personal agent changes the flow of information.

Instead of:

```text
Sources → Human → Knowledge
```

the system becomes:

```text
Sources → Agent → Human → Knowledge
```

The agent acts as a filtering layer.

Its responsibilities include:

- discovering content
- removing duplicates
- scoring relevance
- ranking results
- summarizing findings
- delivering actionable insights

The goal is not replacing human judgment.

The goal is preserving human attention.

---

## NanoClaw as an Agent Runtime

One of the interesting frameworks for building lightweight personal agents is NanoClaw.

Rather than focusing on large enterprise workflows, NanoClaw enables the creation of small autonomous systems that can run continuously on inexpensive hardware.

The architecture is intentionally simple:

```text
Scheduler
    ↓
Data Collection
    ↓
Filtering
    ↓
LLM Evaluation
    ↓
Delivery Channel
```

Each stage performs a specific responsibility.

This separation makes the system easier to extend and maintain.

---

## A Practical Example

In our implementation, the agent runs continuously on a Raspberry Pi.

Its purpose is straightforward:

Collect articles from multiple technical sources and deliver only the most valuable content through Telegram.

While this sounds simple, the interesting work happens between collection and delivery.

The pipeline performs several stages:

### Collection

The system aggregates content from multiple feeds and communities.

Instead of relying on a single source, it gathers a large candidate set of articles.

```text
142 articles fetched
```

A large pool increases the probability of finding high-quality content.

---

### Quality Filtering

Most content is immediately discarded.

Common filtering criteria include:

- low information density
- clickbait titles
- duplicate content
- promotional material
- irrelevant topics

The majority of collected articles never reach the next stage.

---

### Relevance Ranking

The remaining candidates are evaluated using an LLM.

Rather than simply ranking popularity, the model attempts to answer:

> Would this be interesting to this specific user?

This distinction is important.

Popularity is global.

Relevance is personal.

The most valuable article is often not the most popular one.

---

### Delivery

The final result is delivered through a channel that already fits into existing workflows.

In our case:

```text
Telegram
```

No new application.

No dashboard.

No web portal.

The information arrives where attention already exists.

---

## Why Small Hardware Is Enough

One surprising aspect of modern agent systems is how little infrastructure they require.

The Raspberry Pi hosting this workflow performs:

- scheduling
- feed aggregation
- ranking orchestration
- storage
- messaging

The computationally intensive reasoning is delegated to cloud LLMs.

As a result, the local machine acts primarily as an orchestrator.

This architecture provides several benefits:

- low cost
- low power consumption
- continuous operation
- minimal maintenance

The agent remains available 24/7 without requiring dedicated servers.

---

## The Importance of Memory

An agent becomes significantly more useful when it remembers.

Without memory:

```text
Every day starts from zero.
```

With memory:

```text
The system learns history.
```

Examples include:

- avoiding articles already sent
- tracking previously discovered tools
- remembering user preferences
- detecting recurring topics
- identifying emerging trends

Memory transforms automation into personalization.

---

## Beyond Article Delivery

Content discovery is only one use case.

The same architecture can be extended to:

### Trend Detection

Monitoring GitHub repositories and identifying rapidly growing projects.

### Technical Research

Tracking specific technologies across multiple sources.

### Open Source Discovery

Finding promising new tools before they become mainstream.

### Personal Knowledge Management

Building curated collections of information over time.

### Automated Reporting

Generating daily or weekly technical briefings.

The agent becomes a continuously operating research assistant.

---

## The Shift Toward Ambient Intelligence

The long-term significance of personal agents is not that they automate tasks.

Software has automated tasks for decades.

The difference is that modern agents can evaluate information and make lightweight decisions.

They operate in the background.

They monitor.

They filter.

They prioritize.

They surface what matters.

This creates a new interaction model where users spend less time searching and more time consuming relevant information.

The technology fades into the background while useful outcomes become more visible.

---

## Conclusion

The future of personal AI is unlikely to be a single chat window.

Instead, it may consist of many small autonomous systems quietly working on our behalf.

A lightweight NanoClaw deployment running on a Raspberry Pi illustrates this direction well.

The system is not attempting to replace human expertise.

Its purpose is much simpler:

Reduce noise.

Preserve attention.

Deliver the right information at the right time.

As AI capabilities continue to improve, personal agents may become one of the most practical and impactful applications of large language models—not because they answer questions better, but because they know which questions we never needed to ask.

For further implementation details, reach me out on [Linkedin](https://www.linkedin.com/in/or-kazaz/).

![rasberry-pi](https://res.cloudinary.com/dtt2usukl/image/upload/v1783102141/af25b4ee-a33b-423c-b958-2f13d8fb4abe_vhu8am.jpg)_My RP Setup_


How a NanoClaw-powered personal AI agent cuts through information overload with autonomous research and smart automation.

Autonomous Knowledge Assistant with NanoClaw


For years, Ubuntu was the undisputed king of the Linux desktop for those who wanted a stable, reliable and easy to use desktop environment. It was the "default" choice for many, including myself.

From the early days of 16.04, it was the reliable and worked amazingly well as your "daily driver", but the landscape of Linux has shifted. After 10 years I've made the move to Fedora, specifically Fedora KDE, and the experience has been nothing short of liberating.

In this article I'll try to explain the nuances of the move, and why Fedora has become my new daily driver.

### The Elephant in the Room: The Rise of Snaps

For me, the defining moment that broke the camel's back and made me want to leave Ubuntu was the forceful push of Snaps.

While the concept of universally package-managed applications is a worthy goal, the implementation and execution of Snaps have been increasingly problematic for users like me.

#### The "Firefox Incident" as a Turning Point:

The most common example was the shift of Firefox, a core component of any desktop Linux experience, to a Snap-only distribution model in recent Ubuntu versions. This wasn't just a change in package management; it felt like an imposition.

Forced Compliance: When I tried to install Firefox via the standard apt command on Ubuntu 22.04, even with common workarounds found on Reddit, it's still forced to install it as a Snap package.

The Problem with a Closed Ecosystem: This move highlighted a fundamental flaw in the Snap system. While Fedora's Flatpaks and Arch's AUR promote decentralized repositories and user control, Snaps are heavily controlled by Ubuntu's Snap Store. The proprietary nature of the Snap backend, the centralized control over the Snap Store, and the lack of a true, community-driven alternative made it feel less like an open-source solution and more like a walled garden.

Slow Start Times: The single biggest complaint about Snaps, and one that I personally experienced on some applications, is the slow startup time. My Firefox browser would hang for an agonizing few seconds before opening, a noticeable degradation in performance compared to the native .deb package. For any user who values responsiveness, this was a major deal-breaker.

Beyond Firefox: The Ubiquity of Snaps

It wasn't just Firefox. More and more software was being "snapped," often without a clear reason or a direct benefit to the user. This aggressive promotion of Snaps, coupled with the slow development and adoption of Flatpak in Ubuntu, created a sense of a forced ecosystem. Users were being nudged, or outright pushed, into a specific path, often sacrificing choice and performance along the way.

### The Contrasting World of Flatpaks and Fedora:

Fedora, by contrast, takes a different approach. While they are a major driver of the Flatpak format, they don't force it upon users. You can still install software via the traditional dnf package manager. Furthermore, the Flatpak ecosystem, with Flathub as a central repository, feels much more collaborative and community-driven. This distinction is crucial, as it speaks to the philosophies of the two projects.

### The KDE Plasma Renaissance: Customization without Chaos

The second major reason for my migration was the sheer brilliance of the KDE Plasma desktop environment. For a long time, I was content with GNOME, the default on Ubuntu. Its simplicity and focus on getting things done were appealing. However, as I grew more comfortable with Linux and my needs evolved, I craved more control and a sense of ownership over my desktop.

For example, for my work, I use Mac for years now, and switching from Mac to any other Linux distro might feel in-affective, but with KDE Plasma, I can still use my Mac-like workflow (Only for the things I like about Mac)and still have the power of Linux.
This results in a more efficient and productive workflow and usage of my desktop.

### GNOME's Limitations

GNOME, while elegant, often feels restrictive. The "GNOME way" of doing things can sometimes feel like a straightjacket, where customization is limited and often requires extensions that can be unstable and poorly maintained. The removal of features, like the desktop icons and the tray icon, felt like a step backward in terms of usability for me.

### Enter KDE Plasma

My first experience with KDE Plasma was a revelation. It wasn't just another desktop environment; it was a suite of tools and a framework for building your ideal workspace. The beauty of Plasma is that it can be as simple or as complex as you want it to be, and you can easily customize it to your needs. On some aspect, I even built a custom plugin for KDE Plasma Search to improve my workflow.

#### Ultimate Customization:

Every aspect of Plasma is customizable. From the themes, icons, and fonts to the window managers, panels, and widgets, you are in complete control. Want a traditional Windows-like taskbar? You can do it. Prefer a Mac-like dock? No problem. Crave a minimal, tiling-inspired setup? Plasma has you covered.

#### The Power of Widgets:

Plasma's widget system is incredibly powerful. You can add widgets for everything from system monitoring and media controls to weather and calendar. This ability to tailor your desktop to your exact needs is unparalleled.

#### The Elegant Side of Plasma:

Modern Plasma is a thing of beauty. The design is clean, polished, and contemporary. The default Breeze theme is fantastic, but you can easily change it with a single click.

What makes the Fedora KDE spin so compelling is the polish and care that goes into it. This isn't just a stock KDE installation slapped on top of Fedora; it's a well-integrated, cohesive experience. The default configurations are thoughtful, and the KDE team's focus on stability and performance shines through.

#### Performance and Stability: Fedora's Secret Weapon

One of the most immediate and pleasant surprises after moving to Fedora was the significant improvement in performance. Fedora feels faster, and more responsive than Ubuntu, even on older hardware.

Fedora's secret lies in its philosophy of using the latest upstream software and its leaner default installation.

Bleeding-Edge but Stable: Fedora is known for using newer kernel versions and more recent versions of software packages. This gives you access to the latest performance improvements and features. However, unlike rolling release distributions like Arch, Fedora's release schedule is biannual, which provides a level of stability and predictability that I appreciate.

dnf vs. apt: While both are excellent package managers, I've found dnf to be generally faster and more efficient than apt, especially when dealing with large updates. The use of delta RPMs also helps to speed up the process.

Fedora's "First Principles" Approach: Fedora is developed by Red Hat, a company with a long history of investing in the Linux ecosystem. This means that Fedora benefits from Red Hat's expertise in core Linux technologies like the kernel, systemd, and GNOME. This focus on "upstream first" development means that Fedora often gets improvements and new features earlier than other distributions.

Fedora's "Upstream First" philosophy is another major plus for me. This means that Fedora developers contribute their work directly to the upstream projects (like the Linux kernel, GNOME, KDE, etc.) rather than maintaining a separate fork of the software. This approach benefits the entire Linux ecosystem and ensures that the improvements are available to everyone.

---

To sum up, my migration to Fedora has been a journey of discovery and a reclaiming of my freedom as a Linux user. The push towards Snaps and the rigidity of the default desktop environment in Ubuntu became points of frustration, while Fedora's embrace of Flatpaks, the power and flexibility of KDE Plasma, and the distribution's focus on performance and innovation have made it a superior choice for my needs.

Fedora KDE feels like the future of the Linux desktop. It's a system that respects user choice, prioritizes performance and stability, and provides a level of polish and integration that is truly impressive. Whether you're a seasoned Linux pro or just starting your journey, I highly encourage you to give Fedora a try. You might just find your new desktop home.

![my-fedora-workstation](/images/fedoraworkstation.jpeg)


After years of using Ubuntu GNOME, I have decided to switch to Fedora KDE Plasma. A Migration to Freedom and Modernity.

Goodbye Ubuntu, Hello Fedora!


When your Node.js or Electron application needs to interact with the OS, it uses the `child_process` module. While `spawn` is better for large data streams, `exec` is the go-to for command-line utilities because it buffers the output and provides a simple interface.

However, how you consume that interface impacts your application's memory usage, error handling, and maintainability.

Let's look at the three primary ways to handle asynchronous execution.

**The Low-Level Foundation: The Callback Pattern**

The exec function spawns a shell and runs the command within that shell. Internally, Node.js allocates a buffer (defaulting to 1MB) to store the stdout and stderr results.

```js
import { exec } from 'child_process'

const options = {
  cwd: '/path/to/repo', // Current Working Directory
  env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }, // custom env vars
  timeout: 10000, // Kill process if it exceeds 10s
  maxBuffer: 1024 * 1024 * 10, // Extend buffer to 10MB
}

exec('git status --porcelain', options, (error, stdout, stderr) => {
  if (error) {
    // error.code: The exit code of the process (e.g., 128 for Git errors)
    // error.signal: The signal that terminated the process (e.g., SIGTERM)
    console.error(`Process exited with code ${error.code}`)
    return
  }
  // stdout and stderr are strings containing the full output
  console.log(stdout)
})
```

Memory Management: The callback only fires once the process is closed and the entire output is buffered. If a command outputs 2MB and your maxBuffer is 1MB, the callback fires with an ERR_CHILD_PROCESS_STDIO_MAXBUFFER error, and the process is killed.

Execution Context: This pattern is strictly "Push" based. You are handing control to the OS and waiting for a signal to return.

The Problem (Sequential Dependency): If you need to check git status, then git fetch, then git pull, you create a recursive execution context. Each nested exec keeps the previous one in memory (closure), leading to potential memory leaks in long-running processes if not handled carefully.

**Using a Promise Wrapper**

By wrapping `exec` in a new `Promise`, you transition the function from a Push-based callback to a Pull-based awaitable.

```js
function execAsyncManual(command, options = {}) {
  return new Promise((resolve, reject) => {
    // Logic executed immediately upon Promise instantiation
    const child = exec(command, options, (error, stdout, stderr) => {
      if (error) {
        // Enriched Error Object
        reject({
          message: error.message,
          exitCode: error.code,
          command: command,
          stderr: stderr,
        })
      } else {
        // Resolve only on successful exit (code 0)
        resolve({ stdout, stderr })
      }
    })

    // We can even attach listeners to the child process object if needed
    child.on('spawn', () => console.log(`PID ${child.pid} started.`))
  })
}
```

Control Flow: This allows for Try/Catch blocks. In the compiled JavaScript, this transforms your logic into a state machine. Instead of nesting closures, the state machine pauses execution, allowing the Event Loop to process other tasks while waiting for the OS kernel to signal the process completion.

Why Manual? Some CLI tools (like curl or ffmpeg) are "noisy." They might write progress logs to stderr. A manual wrapper lets you write logic like: if (stderr && !stderr.includes('Warning')) reject().

The Trap: If you forget to handle the reject, you will trigger an unhandledRejection event, which in modern Node.js versions, will crash your entire process.

**The Abstraction: Promisify**

Node's `util.promisify` uses a specific internal Symbol (`util.promisify.custom`) or a standard argument-guessing logic to wrap the function for you.

```js
import { exec } from 'child_process'
import { promisify } from 'util'

const execAsync = promisify(exec)

async function gitWorkflow() {
  try {
    // Destructuring the returned object
    const { stdout, stderr } = await execAsync('git pull origin main')

    // Technical Note: If stderr is not empty, it doesn't mean the command failed.
    // promisify only rejects if the error argument in the callback is truthy.
  } catch (err) {
    // err is an instance of Error but with extra properties:
    // err.stdout, err.stderr, err.code, err.signal, err.cmd
    console.error(`Command [${err.cmd}] failed with: ${err.stderr}`)
  }
}
```

Standardization: promisify ensures that the Promise always resolves to an object with { stdout, stderr } keys. This is critical for team-based projects where custom wrappers might return different formats.

Microtask Queue: Using await places the continuation of your function into the Microtask Queue. This is higher priority than the Macrotask Queue (where setTimeout lives), meaning your code resumes almost instantly after the OS process finishes.

Limitations: You lose access to the ChildProcess object (the PID, the .stdin stream, etc.) unless you use the advanced promisify features. You only get the final result.

Important thing to take into account is a common pitfall called Shell Injection.

When you use `exec`, Node.js calls `/bin/sh -c [command]` (on Unix) or `cmd.exe /d /s /c [command]` (on Windows). The shell is an interpreter.

If your code looks like this:

```js
execAsync(`cat ${filename}`)
```

And a user provides:

```bash
"important.txt; rm -rf /"
```

The shell interprets the `;` as a command separator. It finishes the `cat` and then immediately starts the `rm`.

Never pass raw input to `exec`. Use a strict Whitelisting Regex. If you need to handle complex arguments with spaces and special characters, consider using `child_process.spawn` instead, which passes arguments as an array and does not spawn a shell by default, bypassing the injection risk entirely.

---

For 90% of use cases in Electron or Backend services, promisify(exec) is the superior choice for maintainability. However, if you are building a tool that requires real-time monitoring of a process (like a progress bar based on PID stats), the Manual Wrapper or raw Callbacks are necessary to maintain a handle on the ChildProcess instance.


Handling Node shell commands can be tricky. Should you use Callbacks, manual Promises, or an abstraction layer like Promisify?

Executing Shell Commands in Node.js: Callbacks vs Promises vs Promisify


I was recently browsing Reddit and saw a developer mention how much they love the itertools module. One comment stuck with me:

> "On top of my head I think pairwise is my preferred. It is very useful in so many contexts."

If you’re building backends with FastAPI, "many contexts" usually means handling data streams, calculating changes, or optimizing database hits. Today, let’s look at two specific tools—pairwise and its newer sibling batched—and how they can transform your API code.

### Analyzing Trends with itertools.pairwise

In a financial app, you rarely care about a single price; you care about the change. pairwise (introduced in Python 3.10) is the cleanest way to compare a value with the one that came before it.

**The FastAPI Example: Stocks Volatility Checker**

Imagine an endpoint that receives a sequence of stock prices and needs to identify "volatile" moments where the price jumped more than 2% between ticks.

```python
from fastapi import FastAPI, HTTPException
from itertools import pairwise
from pydantic import BaseModel

app = FastAPI()

class StockData(BaseModel):
    symbol: str
    prices: list[float]

@app.post("/analyze-volatility")
async def analyze_volatility(data: StockData):
    if len(data.prices) < 2:
        raise HTTPException(status_code=400,
                            detail="Need at least 2 prices to compare")

    jumps = []
    # (p1, p2), (p2, p3), (p3, p4)...
    for prev_price, current_price in pairwise(data.prices):
        change = (current_price - prev_price) / prev_price

        if abs(change) > 0.02:  # Over 2% change
            jumps.append({
                "from": prev_price,
                "to": current_price,
                "change_percent": round(change * 100, 2)
            })

    return {"symbol": data.symbol, "volatile_moments": jumps}
```

The API endpoint can be tested with a simple curl request:

```bash
curl -X POST http://localhost:8000/analyze-volatility -H "Content-Type: application/json" -d '{"symbol": "AAPL", "prices": [150.0, 152.0, 151.0, 153.0, 154.0]}'
```

Before `pairwise`, we usually had to mess around with range indexes or "zip with a slice," which looked like this: `zip(prices, prices[1:])`. Not only is that harder to read, but it also creates an unnecessary copy of the list in memory.

**So why use it?**

- Zero Memory Overhead: It uses an iterator, meaning it yields values one by one rather than creating a new list.

- Less Logic Needed: Unlike chunking, pairwise creates an overlapping window. If you have [A, B, C, D], it yields:

(A, B)

(B, C)

(C, D)

- Excellent for: Calculation of deltas, trend analysis, and pathfinding (connecting point A to point B).

### Scaling with itertools.batched

While pairwise helps us read the data, batched (new in Python 3.12) helps us write or send it.
If you have 10,000 stock updates to save to a database or send to a third-party notification service, doing it one-by-one is a performance killer. You need to group them.

**The FastAPI Example: Bulk Notification Service**

Let's build a service that takes a massive list of price alerts and sends them to a messaging provider in batches of 10 to respect rate limits.

```python
from fastapi import FastAPI
from itertools import batched
import asyncio

app = FastAPI()

async def send_to_provider(batch):
    # Simulate an external API call
    await asyncio.sleep(0.1)
    print(f"Sent batch: {batch}")

@app.post("/push-alerts")
async def push_alerts(alerts: list[str]):
    # batched('ABCDEFG', 3) --> ABC, DEF, G
    count = 0
    for chunk in batched(alerts, 10):
        await send_to_provider(chunk)
        count += 1

    return {"status": "Alerts sent", "total_batches": count}

```

Batching (also known as chunking) is one of the most common patterns in backend engineering. Before Python 3.12, we had to use complicated "recipes" from the documentation or third-party libraries like more-itertools.

**So why use it?**

- The Efficiency Factor: In a FastAPI context, the biggest bottleneck is usually I/O (Input/Output).

- The Problem Solved: Sending 1,000 individual SQL INSERT statements or 1,000 separate HTTP requests creates massive overhead, therefore batched allows you to group these into a single database transaction or a single bulk API call.

- Pro-Tip: batched yields tuples. If your downstream function (like a database driver) requires a list, you can simply call list(chunk).

---

You don't always need a heavy data-processing library like Pandas to handle sequences. Sometimes, the most elegant solution is already sitting inside Python’s standard library. By using pairwise and batched, you make your FastAPI endpoints more readable and significantly more efficient.


pairwise and batched are two free power-ups that can be used to improve the performance of your Python backend, without much effort.

Welcome toKazi's Dev Blog

Latest Articles