DEV Community: Subhraneel

Building a Self-Healing Supervisor in Node.js

Subhraneel — Tue, 23 Jun 2026 09:47:36 +0000

Recently, while reading the Reliability chapter from Designing Data-Intensive Applications (DDIA) by Martin Kleppmann, I built a small experiment to better understand one of the core ideas of reliable systems:

Failures are inevitable. Systems should be designed to detect them and recover automatically.

This experiment is a simple self-healing supervisor.

The idea is straightforward: a supervisor process monitors worker processes and automatically restarts them whenever they become unhealthy.

In production systems, these workers could be microservices, containers, or background jobs. For this experiment, they're implemented as basic Node.js child processes.

How It Works

The supervisor is intentionally kept simple.

It spawns a worker process and continuously monitors it. If the worker crashes or becomes unresponsive, the supervisor kills it and starts a new one.

Rather than trying to prevent failures entirely, the system assumes they will happen and focuses on recovery.

Worker Types

To simulate different real-world failure scenarios, the worker randomly starts in one of three modes:

Normal Worker

A healthy worker that:

Sends heartbeat messages every 3 seconds.
Performs its task.
Exits successfully after completion.

Hung Worker

A worker that appears healthy initially but later becomes unresponsive.

It sends a few heartbeat messages and then stops sending them entirely by entering an infinite loop. Since no further heartbeats are received, the supervisor detects the worker as unhealthy, terminates it, and starts a replacement.

Crashed Worker

A worker that intentionally crashes itself.

After sending a few heartbeats, it throws an error and exits with a non-zero exit code. The supervisor detects the failure and automatically restarts it.

Heartbeat-Based Liveness Detection

Workers periodically send JSON heartbeat messages:

{
  "type": "heartbeat",
  "timestamp": 123456789
}

The supervisor tracks these heartbeats to determine whether a worker is alive.

If no heartbeat is received for 10 seconds, the worker is considered unhealthy and is terminated. This mechanism allows the supervisor to detect not only crashes but also hung processes that are still running but no longer making progress.

Retry and Recovery

The supervisor includes a simple retry mechanism:

Waits 1 second before restarting a failed worker.
Limits recovery attempts to 10 consecutive failures.
Resets the retry counter whenever a worker exits successfully.

This prevents endless restart loops while still allowing recovery from transient failures.

What I Learned

This experiment reinforced a key reliability principle from DDIA:

A system does not need to eliminate every failure. Instead, it should be able to detect failures quickly and recover automatically.

It also provided a practical understanding of:

OS processes and parent-child relationships
Process supervision
Heartbeat-based liveness detection
Failure recovery strategies
Restart limits and backoff mechanisms

The supervisor itself is intentionally "dumb"—it only monitors health and restarts workers when necessary. Interestingly, that simplicity is often a strength. A small, predictable supervisor can be more reliable than a complex one.

Thanks for reading :)

Github Repo: https://github.com/subhraneel2005/ddia-lab

How I built my own Claude code in Typescript

Subhraneel — Thu, 04 Jun 2026 14:52:58 +0000

I Built a Mini Claude Code from Scratch. Here's What I Learned

A few months ago I went down a rabbit hole: reading OpenCode's GitHub repo, studying screenshots of Claude Code's behavior, reverse engineering the flows. I wanted to understand how these terminal coding agents actually work under the hood, not just use them, but build one. This post is about what I built, the real technical challenges I hit, and what I'm planning next.

What I Built

A CLI-based AI coding agent. You open your terminal, run it inside a project, describe a task, and the agent autonomously reads files, edits them, runs commands, searches the web, and commits to Git. This happens all while asking for your approval before changing any of your code.

I started it as a simple sidequest, to read and implement things side by side. It's built in TypeScript, runs on Bun, uses Vercel's AI SDK (Agents, Tools and Loop Control), and uses Google Gemini 2.5 Flash as the model (because it has a free tier, lol), and the terminal UI is built with Ink, I used it because it is very similar to writing frontends in React.

Here's a rough breakdown of what the coding agent can do:

filesystem tools: read, write, search, and edit files
bash tools: ls, pwd, grep
git tools: commit, push, pull, create/manage PRs and issues via github cli
command execution: run npm, pnpm, python, pip, cargo, etc.
web tools: search the web with any query, fetch URLs
a planner sub-agent: breaks big tasks into smaller todos
a memory system: persists context across sessions in .agent/ markdown files

Everything is strictly typed end-to-end with Zod schemas, tools have typed inputs and outputs, which I'll get into below.

The Architecture

The core is a tool-calling agent loop. The model receives your prompt, a list of available tools, and the conversation history. It decides which tool to call, the agent executes it, the result is fed back, and the loop continues until the task is done or the model stops requesting tools.

I used Vercel's AI SDK to handle the streaming and loop control, and registered all my tools in a central tools-registry.ts:

export const tools = {
  write_file: writeFileTool,
  read_file: readFileTool,
  search_files: searchFilesTool,
  edit_file: editFileTool,
  ls: lsTool,
  pwd: pwdTool,
  grep: grepTool,
  git_tool: gitTool,
  // planner sub-agent tools
  createTodoTool,
  createAllTodosTool,
  updateTodoStatusTool,
  getNextPendingTodoTool,
  checkIfAllTodosAreCompletedTool,
  // memory + web
  write_memory: writeMemoryTool,
  run_command: runCommandTool,
  web_search: webSearchTool,
  web_fetch: webfetchTool,
} satisfies ToolSet;

Every tool is defined with a Zod schema for its input and output. This gives the model a clear, typed contract for what each tool expects and returns, and it gives me safe failure handling throughout , if a tool call has malformed input, Zod can catch it before it touches the filesystem.

Challenge 1: The Edit File Tool and Human-in-the-Loop

This was the an interesting problem to solve.

All other tools: reading files, running commands, searching can execute automatically without any user intervention. But file editing is destructive. If the agent makes a wrong edit, you want a chance to catch it before it's directly written to disk.

The pattern I took inspiration (from studying Claude Code and OpenCode) is:

agent calls read_file first to read the current file content
agent calls edit_file with the old string and the new string it wants to substitute (diff)
before writing, show the user a colored diff (red for removed lines, green for added lines)
wait for the user to approve or reject

The tricky part is step 4. The agent loop is running. I can't just await a user keypress inside a tool execution without some way to pause the loop itself.

The way I solved this: Vercel's AI SDK's streamText (and generateText) exposes a stopWhen parameter on the loop control. I use this to pause the agent loop when the edit tool is waiting for approval. The TUI sets an isApproved flag asynchronously, the user sees the diff rendered in the terminal via Ink components, presses a key to approve or reject, the flag flips, and the loop resumes or the edit is discarded.

The isApproved field is actually part of the edit tool's input schema:

export const EditFileInputSchema = z.object({
  filename: z.string(),
  folder: z.string().optional(),
  oldStr: z.string(),
  newStr: z.string(),
  isApproved: z.boolean().optional().describe("Needs approval before writing new changes"),
});

And the output schema carries a needsApproval flag back:

needsApproval: z.boolean().optional().describe(
  "Needs human approval to be true for the agent to write the changes in the file"
)

This creates a clear handshake: the tool signals it needs approval, the loop pauses, the human decides, the loop resumes. Everything else runs autonomously.

I also added path traversal protection, the agent cannot operate outside the project root directory. Every file path is validated against the root before any read or write happens.

Challenge 2: The Planner Sub-Agent

For small, focused tasks, the main agent handles everything directly. But when a user gives a bigger, more open-ended task like "refactor this module", "add authentication to my nodejs backend", a single flat loop gets difficult to handle.

My solution was a planner sub-agent. The main agent calls it as a tool when it detects a bigger task. The planner sub-agent has its own system prompt focused entirely on task decomposition. It breaks the task down into a list of structured todos, each with:

A unique ID
The task description
A status (not completed, ongoing, completed)
A priority (1–5)

These are typed with Zod too:

export const SingleTodoSchema = z.object({
  id: z.string(),
  todo: z.string(),
  status: z.enum(["completed", "not completed", "ongoing"]).default("not completed"),
  priority: z.number().min(1).max(5).default(3),
});

Once the planner creates the todos, the main agent picks them up one by one using getNextPendingTodoTool, executes them using the available filesystem/git/web tools, and marks each one complete before moving to the next. The TUI renders a live todo list so you can watch the agent work through the task.

Right now this is synchronous, so one task at a time. That's the current limitation that I'm planning to address next.

What's Next: Parallel Sub-Agents

The natural evolution of the planner is running multiple smaller agents in parallel, each picking up one todo from the breakdown independently. But this introduces an obvious conflict problem: what if two agents try to edit the same file at the same time?

My planned approach is to solve this at the task metadata level, not at the execution level. When the planner sub-agent breaks down a task, each todo will also carry metadata about which files it needs to touch:

// rough idea, not yet implemented
{
  id: "task-3",
  todo: "Add input validation to auth.ts",
  files: ["src/auth.ts", "src/validators.ts"], (not guessed, these will be grepped/searched using the tools)
  status: "not completed",
  priority: 2
}

When a smaller agent picks up a task, it only has access to the files assigned to it. The planner ensures no two tasks share the same file. This way, parallel agents work completely independently with well-defined boundaries, no conflict resolution at runtime, because the conflict is prevented structurally at planning time. And to maintain the bigger context the smaller agents will update the main agent about their current status (when it gets updated), e.g: "task1 failed", "task2 succeded", "task 3 in-progress".

Why Gemini 2.5 Flash?

Cause it has a generous free tier. When you're building something from scratch and running dozens of test runs a day, it matters.

The plan is to make the model configurable, so the user will be able to select their provider and model and bring their own API key. The agent's tool-calling logic doesn't care which model is underneath as long as it supports function/tool calling.

The TUI: Ink (React for Terminals)

The terminal UI is built with [Ink], which lets you write React components that render in the terminal. If you know React, there's almost no learning curve.

I used it for:

rendering the diff display during file edits (the red/green approval screen) + used the "diff" npm package as well.
showing the live todo list as the planner sub-agent creates and the main agent completes tasks
the thinking/loading indicators while the model is streaming
the GitHub activity log component
the text input field for user prompts

Basically it gets the job done with a simple, clean UI.

Memory System

One thing I wanted from the start was for the agent to remember things across sessions. And get more personalised based on the user. The memory system stores three types of information in a .agent/ folder in your project root:

File	What it stores
`USER.md`	Your preferences and habits (e.g. "prefers pnpm")
`PROJECT.md`	Facts about the repo (e.g. "uses Next.js, tests in /tests")
`AGENT.md`	Lessons the agent learned (e.g. "avoid editing generated files")

The agent can call write_memory tool at any point of time to store something. On the next session, these files are loaded into the system prompt so the agent already knows the context without you having to re-explain it.

What I'd Do Differently

A few things I'd approach differently if I started over:

start with the edit tool's approval flow first. It touches the most parts of the system (tool schema, loop control, TUI state, async coordination) and sets the pattern for everything else.
design the todo schema with file metadata from the beginning. Adding it later to support parallel agents means touching the planner sub-agent's prompt, the schema, and the main agent's task-picking logic all at once.
Add a proper token tracking display earlier. right now it's in the upcoming features list.

Where to Find It

Here's the github repo: https://github.com/subhraneel2005/sidequests
I have started to polish this project again and will work on some improvements. You can check them in the issues section of the repo, everything I do will be completely transparent.

If you're thinking about building something similar, the best way to start is reading how tool-calling, loops, sub-agents and orchestration actually work in whatever AI SDK you're using. The rest is just building on top of that foundation.

Thanks for Reading

If you made it this far, I genuinely appreciate. This was a fun project to build and an even more fun one to write about.
I keep posting about my projects, experiments, and side quests on X. If you want to follow along, here's my X(twitter) account: @subhraneeltwt

And if you have thoughts, feedback, criticism, questions, or just want to tell me something is wrong or could be done better, DM me, drop a comment, quote the post, whatever you want. I'm always looking to learn. Nothing is too small to share. See ya' :)

How to setup Tailwind css to your Expo project

Subhraneel — Wed, 13 Aug 2025 10:58:53 +0000

Hello everynyan, here i come again!
So this time me and my friend were building a ticketing app with Expo and needed TailwindCSS. Turns out, Expo uses something called NativeWind which is basically tailwind for app dev.

The problem?
We noticed that there was no straight-forward docs for NativeWind setup in expo, so I decided why not make a simple straight-forward blog on this. Okay enough yapping

Lets start :)

If you haven't already, just setup an expo project by running

npx create-expo-app@latest

After thats done, run these 2 commands

npm install nativewind
npm install -D tailwindcss

this basically adds nativewind as a dependency and tailwindcss as a dev-dependecy in your project

Now run this

npx tailwindcss init

this will generate a tailwind.config.js file in your project at the root level

Replace the content of your tailwind.config.js file with this:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./App.tsx", "./components/**/*.{js,jsx,ts,tsx}", "./app/**/*.{js,jsx,ts,tsx}"],
  presets: [require("nativewind/preset")],
  theme: { extend: {} },
  plugins: [],
};

We are almost done :)

Now create a babel.config.js file (needed for nativewind to work properly)

and then add this in the babel file:

module.exports = function (api) {
  api.cache(true);
  return {
    presets: [
      ["babel-preset-expo", { jsxImportSource: "nativewind" }],
      "nativewind/babel",
    ],
  };
};

Now for expo to get all the styles create this file : metro.config.js and add this code into the file:

const { getDefaultConfig } = require("expo/metro-config");
const { withNativeWind } = require("nativewind/metro");

const config = getDefaultConfig(__dirname);

module.exports = withNativeWind(config, { input: "./global.css" });

And its done! Now you can simple do this and your styles will get updated instantly

className="flex-1 items-center justify-center bg-blue-500"

I have create a Expo + Tailwind starter boilerplate, here's the repo if you want
subhraneel2005/Expo-Tailwind-Starter

If you found this helpful do connect. Would love to chat :)
Heres my twitter acc: x.com/subhraneeltwt

How to add auth-flow between your webapp and extension

Subhraneel — Wed, 06 Aug 2025 05:44:23 +0000

Hey everyone! 👋

So I just wrapped up this really cool project and wanted to share what I learned. I got to work on a fullstack Chrome extension for a US company, and honestly, it was such a fun challenge!

The Challenge

They needed a Chrome extension with some pretty neat features:

Auto-apply to LinkedIn jobs
AI integration for those tricky application questions
Auto-fill for external job forms
Smart keyword matching
And a bunch of other cool stuff

We ended up going with Plasmo for the extension framework - honestly its the best out there to build chrome extensions: https://www.plasmo.com/

The Real Fun Part

Here's where things got interesting. After building the extension, they wanted it to sync seamlessly with their main website through JWT auth. The tricky part? How do we actually know if someone's logged in on the website from inside the extension?

My Solution (Pretty Simple Actually)

So Plasmo gives you these two main pieces to work with:

content.tsx
background.ts

Step 1: Capture the token in your webapp
In your React/Next.js app, find where you're handling the login POST request. If you're using Zustand or any global store, even better - just grab it from there.

Once you have the authToken, create a 'use client' component and add this:

window.postMessage(
  {
    source: "your-webapp-name",
    type: "AUTH_TOKEN",
    token: authToken // Your actual token here
  },
  "*"
)

This basically broadcasts the token from your webapp to the extension.

Step 2: Listen in the content script
In your extension's content.tsx, set up a listener:

const postMessageListener = (event: MessageEvent) => {
  if (
    event.source !== window ||
    !event.data ||
    event.data.source !== "your-webapp-name" ||
    event.data.type !== "AUTH_TOKEN"
  ) {
    return
  }

  const token = event.data.token
  chrome.runtime.sendMessage({
    type: "SAVE_AUTH_TOKEN",
    token
  })
}

Step 3: Store it in the background
Finally, in your background.ts:

if (message.type === "SAVE_AUTH_TOKEN") {
  console.log("Got the token!", message)
  chrome.storage.local.set({ authToken: message.token }, () => {
    console.log("Token safely stored:", message.token)
    sendResponse({ success: true })
  })
  return true // Keep the response channel open
}

And That's It! 🎉

Three simple steps and voila - your extension and webapp are synced seamlessly.
The cool part is you can extend this pattern for logout events, profile updates, or really anything you need to sync between the two.

I'm honestly still amazed at how clean this solution turned out. Sometimes the simplest approaches work the best!

If you have any suggestions or feedback, please comment below, would love to know and learn more about this!

Happy coding guys :)

btw this is me debugging the code ai generates🙂