
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.

Python Backend Free Power-Ups: pairwise and batched


Testing visual elements is straightforward with Playwright, but how do you verify that a specific sound effect played when a user clicked a button or an in-game event occurred? Since automated browsers in CI pipelines don't have "ears," we have to get creative.

The easy answer is Monkey-patching for browser Web Audio APIs and the HTMLAudioElement to intercept audio playback and verify it in our test assertions.

The most reliable way to track audio in a browser is to override the global functions responsible for playing sound. This includes:

`HTMLAudioElement.prototype.play()`: For sounds triggered by `<audio>` tags or `new Audio().play()`.

`AudioBufferSourceNode.prototype.start()`: For sounds played using the Web Audio API, common in games and complex interactive experiences.

By overriding these methods, we can record every attempt to play a sound file into a global array on the window object, which Playwright can then inspect.

1. Creating the Audio Helper (as a fixture)
   First, let's build a clean, AudioMonitor class and wrap it in a Playwright fixture. This ensures that every test gets its own isolated instance of the monitor, preventing "state leaking" when running tests in parallel.

```typescript
// fixtures/audio-fixture.ts
import { test as base, Page } from '@playwright/test'

export class AudioMonitor {
  constructor(private page: Page) {}

  async start() {
    await this.page.addInitScript(() => {
      ;(window as any).soundsPlayed = []

      // --- 1. Patch Standard HTML5 Audio ---
      const originalHtmlAudioPlay = HTMLAudioElement.prototype.play
      HTMLAudioElement.prototype.play = function (...args) {
        const soundName =
          this.src.split('/').pop()?.split('.')[0] || 'unknown_html_audio'

        ;(window as any).soundsPlayed.push({
          name: soundName,
          src: this.src,
          type: 'HTMLAudio',
          timestamp: Date.now(),
        })

        return originalHtmlAudioPlay.apply(this, args)
      }

      // --- 2. Patch Web Audio API ---
      const originalBufferSourceStart = AudioBufferSourceNode.prototype.start
      AudioBufferSourceNode.prototype.start = function (...args) {
        const soundName =
          (this as any).audioName ||
          (this.buffer
            ? `buffer_len_${this.buffer.length}`
            : 'unknown_web_audio')

        ;(window as any).soundsPlayed.push({
          name: soundName,
          type: 'WebAudio',
          timestamp: Date.now(),
        })

        return originalBufferSourceStart.apply(this, args)
      }
    })
  }

  async getPlayedSounds(): Promise<string[]> {
    return await this.page.evaluate(() => {
      return (window as any).soundsPlayed?.map((s: any) => s.name) || []
    })
  }

  async verifyExpectedSounds(expectedSounds: string[]) {
    const playedSounds = await this.getPlayedSounds()
    const missing = expectedSounds.filter(
      expected => !playedSounds.some(played => played.includes(expected))
    )
    return { played: playedSounds, missing }
  }
}
```

In my case, I use a base fixture to extend the Playwright test fixture and include the audioMonitor fixture.

```typescript
// Extend Playwright's base test to include our audioMonitor fixture
export const test = base.extend<{ audioMonitor: AudioMonitor }>({
  audioMonitor: async ({ page }, use) => {
    const monitor = new AudioMonitor(page)
    await monitor.start()
    await use(monitor)
    // Cleanup is automatic as the window object is destroyed with the page
  },
})

export { expect } from '@playwright/test'
```

2. Now use it in your tests:

```typescript
// tests/audio-feature.spec.ts
import { test, expect } from '../fixtures/audio-fixture'

const SOUNDS = ['sound_1', 'sound_2', 'sound_3', 'sound_4']

test('should play expected sounds when audio is ON', async ({
  page,
  audioMonitor,
}) => {
  await page.goto('/somepage')

  // Trigger action that should play the expected sounds
  await page.getByTestId('somebuttonid').click()

  const { missing } = await audioMonitor.verifyExpectedSounds(SOUNDS)

  expect(missing.length, `Missing sounds: ${missing.join(', ')}`).toBe(0)
})
```

Pros of this approach:

- Fixture-Based Isolation: Unlike singletons, fixtures are local to the test worker. This is critical for parallel execution.

- Headless Friendly: This solution doesn't rely on system audio output, making it perfect for CI/CD environments (Docker, GitHub Actions) where no sound card exists.

- Zero Dependencies: It leverages native browser APIs and Playwright’s built-in addInitScript and test.extend capabilities.

- Timing & Sequence: Because we capture a timestamp for every sound, you can even assert that "Sound A" played before "Sound B."

- Traceability: Because these interactions happen in the browser context, these "sounds" will actually show up in your Playwright Console Logs if you add the console.log mentioned above, making the Playwright HTML Report much more descriptive.

Cons of this approach:

While powerful, this method captures the intent to play audio. It doesn't guarantee that the user actually heard it (e.g., if the OS volume is zero or a physical speaker is unplugged). However, for functional E2E verification, ensuring the application code correctly calls the playback APIs is the gold standard for automated testing.


How to test browser audio in Playwright by intercepting HTML5 and Web Audio API calls—ensuring reliable sound tests.

Testing Browser Audio with Playwright


In this blog post I will share my experience with building a native Raycast extension for repository management, which is one of my "daily drivers" on my Mac to improve my productivity and efficiency. Note there are endless possibilities and you can build anything you can imagine with Raycast.

In the past I was juggling between multiple repositories across different directories and various subdirectories like which cloned into a specific project directory. At some point I needed a fast way to open projects in Cursor. My initial solution was a shell script using AppleScript dialogs, but it had annoying issues:

- **Focus problems** - dialogs appeared in the background
- **Requires mouse** - couldn't navigate with keyboard only
- **Not native** - felt clunky and out of place

Therefore, the solution was to build a native Raycast extension that provides:

- **Repo discovery** - discover repositories across different directories and subdirectories
- **Repo focus** - always appears where Raycast is
- **Keyboard-first** - arrow keys + Enter to select
- **Live filtering** - type to search repositories instantly
- **Multiple actions** - open in Cursor, Finder, Terminal, or copy path
- **Native feel** - looks and behaves like built-in Raycast commands

So let's show an example of how to do this.

Create a new directory and initialize the project:

```bash
mkdir my-repo-extension
cd my-repo-extension
npm init -y
npm install @raycast/api
```

Create `package.json` with the Raycast extension schema:

```json
{
  "$schema": "https://www.raycast.com/schemas/extension.json",
  "name": "repository-opener",
  "title": "Repository Opener",
  "description": "Open repositories from ~/work and ~/git directories in Cursor", // these are the directories you want to scan for repositories
  "icon": "📁",
  "author": "your-name",
  "categories": ["Developer Tools"],
  "commands": [
    {
      "name": "list-repos",
      "title": "Open Repo",
      "subtitle": "Repository Opener",
      "description": "List and open repositories",
      "mode": "view",
      "keywords": ["repo", "repository"]
    }
  ],
  "dependencies": {
    "@raycast/api": "^1.62.0"
  },
  "scripts": {
    "build": "ray build -e dist",
    "dev": "ray develop"
  }
}
```

Create `src/list-repos.jsx`:

```jsx
import {
  List,
  ActionPanel,
  Action,
  showToast,
  Toast,
  Icon,
} from "@raycast/api";
import { execSync } from "child_process";
import { useState, useEffect } from "react";
import path from "path";
import os from "os";

function getRepositories() {
  const homeDir = os.homedir();
  const allRepos = [];

  // Scan main directories
  const mainDirs = [
    path.join(homeDir, "work"),
    path.join(homeDir, "git") // these are the directories you want to scan for repositories
  ];

  for (const dir of mainDirs) {
    try {
      const output = execSync(
        \`find "\${dir}" -maxdepth 1 -mindepth 1 -type d 2>/dev/null\`,
        { encoding: "utf8" }
      );
      const repos = output.split("\\n").filter(Boolean);

      for (const repoPath of repos) {
        const repoName = path.basename(repoPath);
        const parentDir = path.basename(path.dirname(repoPath));
        allRepos.push({
          name: repoName,
          path: repoPath.trim(),
          parent: parentDir,
        });
      }
    } catch (error) {
      // Skip if directory doesn't exist
    }
  }

  // Also scan subdirectories (myproject, myproject2, etc.)
  const subDirs = [
    path.join(homeDir, "work", "myproject"),
    path.join(homeDir, "git", "myproject2"),
    path.join(homeDir, "work", "myproject"),
    path.join(homeDir, "git", "myproject2"),
  ];

  for (const dir of subDirs) {
    try {
      const output = execSync(
        \`find "\${dir}" -maxdepth 1 -mindepth 1 -type d 2>/dev/null\`,
        { encoding: "utf8" }
      );
      const repos = output.split("\\n").filter(Boolean);

      for (const repoPath of repos) {
        const repoName = path.basename(repoPath);
        const grandParent = path.basename(path.dirname(path.dirname(repoPath)));
        const parent = path.basename(path.dirname(repoPath));
        allRepos.push({
          name: repoName,
          path: repoPath.trim(),
          parent: \`\${grandParent}/\${parent}\`,
        });
      }
    } catch (error) {
      // Skip if directory doesn't exist
    }
  }

  // Remove duplicates and sort
  const uniqueRepos = allRepos.filter(
    (repo, index, self) => index === self.findIndex((r) => r.path === repo.path)
  );

  return uniqueRepos.sort((a, b) => a.name.localeCompare(b.name));
}

async function openInCursor(repoPath, repoName) {
  try {
    const cursorPaths = ["/usr/local/bin/cursor", "/opt/homebrew/bin/cursor"];

    let cursorCommand = null;
    for (const cursorPath of cursorPaths) {
      try {
        execSync(\`test -x "\${cursorPath}"\`, { stdio: "ignore" });
        cursorCommand = cursorPath;
        break;
      } catch (error) {
        continue;
      }
    }

    if (cursorCommand) {
      execSync(\`"\${cursorCommand}" "\${repoPath}"\`, { stdio: "ignore" });
    } else {
      execSync(\`open -a "Cursor" "\${repoPath}"\`, { stdio: "ignore" });
    }

    showToast(Toast.Style.Success, "Success", \`Opening \${repoName} in Cursor\`);
  } catch (error) {
    showToast(Toast.Style.Failure, "Error", "Failed to open repository");
  }
}

export default function Command() {
  const [repositories, setRepositories] = useState([]);
  const [isLoading, setIsLoading] = useState(true);

  useEffect(() => {
    const fetchRepos = async () => {
      setIsLoading(true);
      const repos = getRepositories();
      setRepositories(repos);
      setIsLoading(false);
    };

    fetchRepos();
  }, []);

  return (
    <List isLoading={isLoading} searchBarPlaceholder="Search repositories...">
      {repositories.map((repo) => (
        <List.Item
          key={repo.path}
          title={repo.name}
          subtitle={repo.parent}
          accessories={[{ text: repo.path }]}
          icon={Icon.Folder}
          actions={
            <ActionPanel>
              <Action
                title="Open in Cursor"
                icon={Icon.Code}
                onAction={() => openInCursor(repo.path, repo.name)}
                closeOnAction={true}
              />
              <Action.Open
                title="Open in Finder"
                target={repo.path}
                application="Finder"
                icon={Icon.Finder}
              />
              <Action.CopyToClipboard
                title="Copy Path"
                content={repo.path}
                icon={Icon.CopyClipboard}
              />
              <Action.Open
                title="Open in Terminal"
                target={repo.path}
                application="Terminal"
                icon={Icon.Terminal}
              />
            </ActionPanel>
          }
        />
      ))}
    </List>
  );
}
```

Now build the extension and add it to Raycast:

```bash
npm run build

# Add to Raycast
# Open Raycast Settings > Extensions > Add Local Extension
# Select your project folder
```

1. Open Raycast (Cmd + Space)
2. Type "repo" to find your command
3. Start typing to filter repositories
4. Press Enter to open in Cursor
5. Raycast automatically closes!

The script extension will have the following features:

### **Smart Repository Discovery**

The extension scans multiple directory patterns:

- `~/work/*` and `~/git/*` for main repositories
- `~/work/myproject/*` for project subdirectories
- Easy to extend for your own directory structure

### ⌨️ **Keyboard-First Navigation**

- Type to filter repositories instantly
- Arrow keys to navigate
- Enter to open (primary action)
- Tab to see secondary actions

### 🎯 **Multiple Actions**

Each repository offers several actions:

- **Open in Cursor** (primary) - opens the project
- **Open in Finder** - for file browsing
- **Copy Path** - quick path copying
- **Open in Terminal** - launch terminal in repo

### 🚀 **Auto-Close Behavior**

The `closeOnAction={true}` prop makes Raycast disappear after opening a repository, creating a smooth workflow.

What else i'm going to leverage using Raycast?

- **Project Templates** - Create new projects from templates
- **Environment Manager** - Switch between development environments
  and more...

![open-repo-with-raycast](/images/raycast-kazi-repo.png)

---

_Have you built any cool Raycast extensions? Please share them with me!_


A simple example of how you can leverage Raycast to improve your workflow.

Raycast For Developers


As developers, we've all been there: pushing commit after commit just to test a GitHub Actions workflow, waiting for runners to spin up, only to discover a simple syntax error or logic bug. What if I told you there's a better way? Here enters `act` - a tool that lets you run GitHub Actions locally using Docker containers.

So what exactly is act?

act is an open-source tool that reads your GitHub Actions workflow files and runs them locally using Docker containers that closely mimic GitHub's hosted runners. Think of it as a local simulator for your CI/CD pipelines. The tool was created to solve a fundamental problem: the slow feedback loop when developing GitHub Actions. Instead of the traditional "commit, push, wait, debug, repeat" cycle, act lets you iterate quickly on your local machine.

Under the hood, act performs several key operations, such as:

- Parsing your workflow files (.github/workflows/\*.yml).
- Creating Docker containers that match GitHub's runner environments.
- Mounting your repository into the container.
- Executing the workflow steps just like GitHub would, but locally.
- Providing real-time feedback in your terminal.

act uses container images that replicate the Ubuntu, Windows, and macOS environments that GitHub provides, complete with pre-installed tools and software.

### Installation and Basic Usage

```bash
# via Homebrew
brew install act

# via curl
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
```

```bash
# Run all workflows
act

# Test specific events
act push
act pull_request
act workflow_dispatch

# Test specific workflow file
act -W .github/workflows/my-workflow.yml

# Dry run to see what would execute
act --dry-run
```

Let's try to look at a simple workflow file and see how it works. This workflow should be triggered on a pull requests and pushes.
In terms of functionality, it should detect changes in a large JSON file and if there are changes, it should run a script to update the file.
It also validates each modified JSON file in parallel and provide feedback on some required validations.

Most of the logic is handheld in a script or composite action, it's just for the sake of the example.

Here's a simplified version of the workflow:

```yaml
name: Config Validation

on:
  pull_request:
  push:
    branches: [master]
  workflow_dispatch:
    inputs:
      config_path:
        description: 'Specific config file to validate'
        required: false

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      has-changes: ${{ steps.changes.outputs.has-changes }}
      configs: ${{ steps.changes.outputs.configs }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Detect changed config files
        id: changes
        run: |
          if [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ -n "${{ inputs.config_path }}" ]; then
            CONFIG_PATH="${{ inputs.config_path }}"
            echo "Manual validation requested for: $CONFIG_PATH"
            echo "has-changes=true" >> $GITHUB_OUTPUT
            echo "configs=[\"$CONFIG_PATH\"]" >> $GITHUB_OUTPUT
            exit 0
          fi

          if [ "${{ github.event_name }}" = "pull_request" ]; then
            BASE_SHA="${{ github.event.pull_request.base.sha }}"
          else
            BASE_SHA="HEAD~1"
          fi

          CHANGED_FILES=$(git diff --name-only $BASE_SHA HEAD -- 'configs/' | grep '\.json$' || true)

          if [ -z "$CHANGED_FILES" ]; then
            echo "No config files changed"
            echo "has-changes=false" >> $GITHUB_OUTPUT
            echo "configs=[]" >> $GITHUB_OUTPUT
            exit 0
          fi

          # Assuming 'jq' is available on the runner (it is on GitHub's default runners)
          CONFIGS_JSON=$(echo "$CHANGED_FILES" | jq -R -s -c 'split("\n") | map(select(length > 0))')
          echo "has-changes=true" >> $GITHUB_OUTPUT
          echo "configs=$CONFIGS_JSON" >> $GITHUB_OUTPUT

  validate-configs:
    needs: detect-changes
    if: needs.detect-changes.outputs.has-changes == 'true'
    runs-on: ubuntu-latest
    strategy:
      matrix:
        config: ${{ fromJson(needs.detect-changes.outputs.configs) }}
      fail-fast: false
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Validate config file
        run: |
          echo "🔍 Validating: ${{ matrix.config }}"
          npm run validate-config -- "${{ matrix.config }}"
```

### Testing with act

```bash
# Test the entire workflow
act workflow_dispatch

# Test with specific input
act workflow_dispatch --input config_path="configs/app-settings.json"

# Test pull request simulation
act pull_request

# Debug with verbose output
act workflow_dispatch -v
```

This few simple commands saved me a lot of time when developing and testing the workflow.

Although it's not a perfect solution, it's a great tool to have in your arsenal when developing and testing GitHub Actions workflows. Let's look at some of its limitations that you should be aware of.

- Limited GitHub Features: No access to GitHub's REST API, can't post PR comments or update statuses, some GitHub-specific contexts might not work.
- Container Image Sizes: The full GitHub runner images are large (several GB), though act offers smaller alternatives.
- Platform Differences: On some cases, there might be differences between local Docker containers and GitHub's actual runners that can occasionally cause issues.

Some usage tips to take it further:

1. Use the `--reuse` flag to reuse containers between runs, this can speed up the process significantly.
2. Use the `--container-architecture` flag to specify the architecture of the container image to use.
3. Use the `--verbose` flag to get more detailed output.
4. Use the `--dry-run` flag to see what would execute without actually running it.
5. Use the `--list-workflows` flag to list all available workflows.
6. Make sure to run your scripts (if you use any in your workflows) independently, so you can test them separately.

Make sure to check the [act repository](https://github.com/nektos/act) for more details and advanced usage.


If you're working with GitHub Actions and workflows I'm sure you've encountered the pain of testing them. This is the solution for you.

Welcome toKazi's Dev Blog

Latest Articles