DEV Community: Ramu Narasinga

`acquireLock` function in claude-context codebase.

Ramu Narasinga — Thu, 02 Jul 2026 15:30:00 +0000

In this article, we review acquireLock function in claude-context codebase. You will learn:

What is claude-context?
acquireLock function explained.

What is claude-context?

Make entire codebase the context for any coding agent using claude-context. Claude Context is an MCP plugin that adds semantic code search to Claude Code and other AI coding agents, giving them deep context from your entire codebase.

🧠 Your Entire Codebase as Context: Claude Context uses semantic search to find all relevant code from millions of lines. No multi-round discovery needed. It brings results straight into the Claude’s context.

💰 Cost-Effective for Large Codebases: Instead of loading entire directories into Claude for every request, which can be very expensive, Claude Context efficiently stores your codebase in a vector database and only uses related code in context to keep your costs manageable.

Setup

Use the command line interface to add the Claude Context MCP server:

```plaintextclaude mcp add claude-context \
-e OPENAI_API_KEY=sk-your-openai-api-key \
-e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
-e MILVUS_TOKEN=your-zilliz-cloud-api-key \
-- npx @zilliz/claude-context-mcp@latest




### Why I chose to write about acquireLock?

As I was reading thru the claude-context source code, I came across the concepts like saving snapshot. Saving where? I asked this question and looked into the function implementation.

Below is a code snippet from [handler.ts,](https://github.com/zilliztech/claude-context/blob/master/packages/mcp/src/handlers.ts#L324) showing how the saveCodebaseSnapshot is invoked.



```javascript
// Check if already indexing
if (this.snapshotManager.getIndexingCodebases().includes(absolutePath)) {
    if (forceReindex) {
        console.log(`[FORCE-REINDEX] Clearing stale indexing state for '${absolutePath}'`);
        this.snapshotManager.removeCodebaseCompletely(absolutePath);
        this.snapshotManager.saveCodebaseSnapshot();
    } else {
        return {
            content: [{
                type: "text",
                text: `Codebase '${absolutePath}' is already being indexed in the background. Please wait for completion.`
            }],
            isError: true
        };
    }
}

saveCodebaseSnapshot

Below is the code snippet picked from the snapshot.ts

public saveCodebaseSnapshot(): void {
  console.log('[SNAPSHOT-DEBUG] Saving codebase snapshot to:', this.snapshotFilePath);

  const locked = this.acquireLock();
  if (!locked) {
      console.warn('[SNAPSHOT-DEBUG] Failed to acquire lock, saving without lock');
  }

  try {
      // Ensure directory exists
      const snapshotDir = path.dirname(this.snapshotFilePath);
      if (!fs.existsSync(snapshotDir)) {
          fs.mkdirSync(snapshotDir, { recursive: true });
          console.log('[SNAPSHOT-DEBUG] Created snapshot directory:', snapshotDir);
      }
...

I mean, snapshot is written to your local file system. Claude-Context uses file system to keep track of codebase indexing, is what I figured looking at some of the files and the way file-system was used.

Since we now understand what led to finding this acquireLock function, let’s take a look at this function, acquireLock.

`acquireLock` function explained.

acquireLock is defined in claude-context/packages/mcp/snapshot.ts at L555 as shown below:

private acquireLock(maxRetries = 5, retryInterval = 100): boolean {
    const lockPath = this.snapshotFilePath + '.lock';
    for (let i = 0; i < maxRetries; i++) {
        try {
            fs.mkdirSync(lockPath);
            return true;
        } catch {
            // Check for stale lock (> 10 seconds old)
            try {
                const stat = fs.statSync(lockPath);
                if (Date.now() - stat.mtimeMs > 10000) {
                    fs.rmdirSync(lockPath);
                    continue; // retry after removing stale lock
                }
            } catch { /* lock was removed by another process */ }
            // Busy wait and retry
            const waitUntil = Date.now() + retryInterval;
            while (Date.now() < waitUntil) { /* busy wait */ }
        }
    }
    return false;
}

It creates a lock file using the snapshotFilePath with .lock extension and then returns true. mkdirsync synchronously creates a directory. Returns undefined, or if recursive is true, the first directory path created. This is the synchronous version of mkdir.

About me:

Hey, my name is ramunarasinga. Email: ramunarasinga@gmail.com

Tired of AI slop?

I spent 3+ years studying OSS codebases and wrote 350+ articles on what makes them production-grade. I built

An open source tool that reviews your PR..
Codebase architecture skills, inspired by best OSS projects.

Get started for free — thinkthroo.com

References:

Hunk, terminal diffs for humans and agents.

Ramu Narasinga — Wed, 24 Jun 2026 15:30:00 +0000

In this article, we review what a hunk library is. You will learn:

What is Hunk?
Modem

What is Hunk??

Hunk is a review-first terminal diff viewer for agent-authored changesets, built on OpenTUI and Pierre diffs..

Features

multi-file review stream with sidebar navigation
inline AI and agent annotations beside the code
split, stack, and responsive auto layouts
watch mode for auto-reloading file and Git-backed reviews
keyboard, mouse, pager, and Git difftool support

Quick start

hunk           # show help
hunk --version # print the installed version

Working with Git

Hunk mirrors Git’s diff-style commands, but opens the changeset in a review UI instead of plain text.

hunk diff                      # review current repo changes, including untracked files
hunk diff --watch              # auto-reload as the working tree changes
hunk show                      # review the latest commit
hunk show HEAD~1               # review an earlier commit

Working with agents

Open Hunk in another terminal with hunk diff or hunk show.
Tell your agent to add the skill file returned by hunk skill path.
Ask your agent to use the skill against the live Hunk session.

A good generic prompt is:

Load the Hunk skill and use it for this review. Run `hunk skill path` to get the skill path.

Learn more about hunk.dev/..

Modem

Hunk is an opensource library authored by Modem. Modem captures every piece of customer feedback your team gets — from Slack, Linear, GitHub, Intercom, and PostHog — and triages it automatically so engineers spend less time PMing and more time shipping.

Build what’s actually important

Every bug report, every feature request, automatically clustered and prioritized
Unified company & user profiles to understand who matters and who can wait
Spot emerging trends before they become fires

Act on problems you didn’t know you had

Get alerted to user concerns as they happen, not days later
Create detailed tickets automatically or straight from chat
Delegate tasks to coding agents with the context they need to be successful

Learn more about Modem..

About me:

Hey, my name is ramunarasinga. Email: ramunarasinga@gmail.com

Tired of AI slop?

I spent 3+ years studying OSS codebases and wrote 350+ articles on what makes them production-grade. I built

An open source tool that reviews your PR..
Codebase architecture skills, inspired by best OSS projects.

Get started for free — thinkthroo.com

References:

`undici.setGlobalDispatcher` function in pi-coding-agent package.

Ramu Narasinga — Thu, 18 Jun 2026 15:30:00 +0000

In this article, we review undici.setGlobalDispatcher function in earendil-works/pi/packages/coding-agent. You will learn:

What is pi-coding-agent?
What is Undici?
setGlobalDispatcher method in pi-coding-agent

What is pi-coding-agent?

Pi is a minimal agent harness. Adapt Pi to your workflows, not the other way around. Customize Pi with extensions, skills, prompt templates and themes. Bundle them as Pi packages and share via npm or git.

Pi ships with powerful defaults but skips features like sub-agents and plan mode. Ask Pi to build what you want, or install a package that does it your way.

Four modes: interactive, print/JSON, RPC, and SDK.. See OpenClaw for a real-world integration.

Learn more about pi-coding-agent.

What is Undici?

Undici is a fast, modern HTTP/1.1 and HTTP/2 client written from scratch for Node.js. Maintained by the Node.js core team, it serves as the underlying engine that powers Node's built-in fetch global API.

Why Use the Standalone Package?

While Node.js embeds a version of Undici internally, installing it explicitly from the undici npm page gives you distinct advantages: [ 1, 2. ]

Advanced Features: Access specialized clients like ProxyAgent, Socks5Agent, and MockAgent.
Maximum Performance: Use the low-level undici.request function for faster request handling than standard fetch.
Connection Pooling: Configure and optimize connection limits and keep-alive behaviors manually.
HTTP Pipelining: Enable concurrent request pipelining over a single connection.
Latest Updates: Receive bug fixes, performance updates, and security patches without waiting for a full Node.js runtime upgrade. [ 1, 2, 3, 4, 5. ]

Learn more about Undici

setGlobalDispatcher method in pi-coding-agent

well, to understand why this method used in pi-coding-agent, we need to first check the official docs for this.

undici.setGlobalDispatcher(dispatcher)

Sets the global dispatcher used by Common API Methods. Global dispatcher is shared among compatible undici modules, including undici that is bundled internally with node.js.

Undici stores this dispatcher under Symbol.for('undici.globalDispatcher.2').

setGlobalDispatcher() also mirrors the configured dispatcher to Symbol.for('undici.globalDispatcher.1') using Dispatcher1Wrapper, so Node.js built-in fetch can keep using the legacy handler contract while Undici uses the new handler API.

Below is an example I picked from the Undici module docs

import { request, fetch, Agent, setGlobalDispatcher } from 'undici';

// Use undici.request for maximum performance
const { statusCode, headers, body } = await request('https://api.example.com/data');
const data = await body.json();

// Or use undici.fetch with custom configuration
const agent = new Agent({ keepAliveTimeout: 10000 });
setGlobalDispatcher(agent);
const response = await fetch('https://api.example.com/data');

This way, you can set your custom configuration and dispatch globally so the fetch uses the configuration dispatched. With this info, let's take a closer look at pi-coding-agent's usage.

The below code snippet is picked from pi/packages/coding-agent/src/core/http-dispatcher.ts..

...
export function configureHttpDispatcher(timeoutMs: number = DEFAULT_HTTP_IDLE_TIMEOUT_MS): void {
 const normalizedTimeoutMs = parseHttpIdleTimeoutMs(timeoutMs);
 if (normalizedTimeoutMs === undefined) {
  throw new Error(`Invalid HTTP idle timeout: ${String(timeoutMs)}`);
 }
 undici.setGlobalDispatcher(
  new undici.EnvHttpProxyAgent({
   allowH2: false,
   bodyTimeout: normalizedTimeoutMs,
   headersTimeout: normalizedTimeoutMs,
  }),
 );
 // Keep fetch and the dispatcher on the same undici implementation. Node 26.0's
 // bundled fetch can otherwise consume compressed responses through npm undici's
 // dispatcher without decompressing them, causing response.json() failures.
 // If a caller replaced fetch after module load, preserve that deliberate override.
 const shouldInstallGlobals =
  installedGlobalFetch === undefined
   ? globalThis.fetch === originalGlobalFetch
   : globalThis.fetch === installedGlobalFetch;
 if (shouldInstallGlobals) {
  undici.install?.();
  installedGlobalFetch = globalThis.fetch;
 }
}

Just like what we learnt, there is a custom configuration applied and dispatched:

new undici.EnvHttpProxyAgent({
   allowH2: false,
   bodyTimeout: normalizedTimeoutMs,
   headersTimeout: normalizedTimeoutMs,
}),

and this comment explains why this was configured this way:

// Keep fetch and the dispatcher on the same undici implementation. Node 26.0's
// bundled fetch can otherwise consume compressed responses through npm undici's
// dispatcher without decompressing them, causing response.json() failures.
// If a caller replaced fetch after module load, preserve that deliberate override.

About me:

Hey, my name is ramunarasinga. Email: ramunarasinga@gmail.com

Tired of AI slop?

I spent 3+ years studying OSS codebases and wrote 350+ articles on what makes them production-grade. I built

An open source tool that reviews your PR..
Codebase architecture skills, inspired by best OSS projects.

Get started for free — thinkthroo.com

References:

How to build a custom Claude plugin?

Ramu Narasinga — Thu, 18 Jun 2026 15:00:00 +0000

In this article, you will learn how to build a custom Claude plugin. We will look at the following:

What is a Claude plugin?
Build a simple Claude plugin.

What is a Claude plugin?

You can create custom plugins to extend Claude Code with skills, agents, hooks, and MCP servers. Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams.

When to use a plugin?

You can use a plugin when you want to share directories containing skills, agents, hooks etc., with teammates, things that are reusable across projects.

There is a also a standalone configuration, defined in .claude folder and this can be specific to a project, can include personal workflows or for quick experiments.

Learn more about when to use a plugin vs standalone configuration.

Let’s build a simple plugin following the official docs quick start guide..

Build a simple Claude plugin

There are 5 steps involved to create your first plugin.

Create the plugin directory

mkdir my-first-plugin

This folder can contain:

Skills
Agents or hooks
optionally, a .claude-plugin/plugin.json manifest

Create the plugin manifest.

You will define the metadata such as name, description, and version of your plugin. In plugin manager, this info is used by Claude Code to display your plugin.

// run this first
mkdir my-first-plugin/.claude-plugin

and then add this to my-first-plugin/.claude-plugin/plugin.json.

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Learn more about the manifest schema..

Add a skill

Skills are added in the skills/ directory. Folder name becomes the skill name. First, create the skills directory in your plugin folder:

mkdir -p my-first-plugin/skills/helloaxios zustand

Then create the SKILL.md file in my-first-plugin/skills/hello/ folder:

---
description: "Greet the user with a friendly message"
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

Test your plugin

You need to load your plugin by running the below command:

claude --plugin-dir ./my-first-plugin

Once the Claude Code starts, you can try your new skill by running the below command:

/my-first-plugin:hello

You’ll see Claude respond with a greeting. Run /help to see your skill listed under the plugin namespace.

Add a skill argument

You can pass user input as an argument to your skill to make it dynamic. $ARGUMENTS placeholder captures any text user provides after the skill name.

Update your SKILL.md to use this $ARGUMENTS variable in your file.

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

At this point, it is important that you run /reload-plugins to pick up changes and then you can run your skill as shown below:

/my-first-plugin:hello Ram

Claude will greet you by name.

About me:

Hey, my name is ramunarasinga. Email: ramunarasinga@gmail.com

Tired of AI slop?

I spent 3+ years studying OSS codebases and wrote 350+ articles on what makes them production-grade. I built

An open source tool that reviews your PR..
Codebase architecture skills, inspired by best OSS projects.

Get started for free — thinkthroo.com

References:

How to build a coding agent — Part 1.1

Ramu Narasinga — Wed, 17 Jun 2026 15:30:00 +0000

In this tutorial series, we build a coding agent that you can assign tasks on GitHub. In this part 1.1, we do the following:

Set up React + Vite frontend
Set up Python FastAPI backend
Design and implement database schema
Create basic API endpoints for agents

I mentioned the AI prompts used to implement tasks.

Set up React + Vite frontend

For this demo, I used React + Vite to create a frontend project. Run the below command to create a react-ts project:

npm create vite@latest frontend -- --template react-ts

Install the dependencies required:

npm install @tanstack/react-query @tanstack/react-query-devtools axios zustand

Set up Python FastAPI backend

Create a folder named backed

mkdir backend

cd into it

cd backend

setup virtual env

python3 -m venv venv
source venv/bin/activate

Install requirements

pip install fastapi uvicorn sqlalchemy psycopg2-binary pydantic websockets python-dotenv

Design and implement database schema

Let’s use Supabase for this tutorial. You will need to create an account on Supabase. Run the below script in your Supabase SQL Editor.

-- Users table
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Agents table  
CREATE TABLE agents (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    provider VARCHAR(50) NOT NULL,  -- claude, codex, etc.
    instructions TEXT,
    runtime_id UUID,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Issues table (GitHub issues synced)
CREATE TABLE issues (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    github_issue_id INTEGER,
    title TEXT NOT NULL,
    description TEXT,
    status VARCHAR(50) DEFAULT 'backlog',
    assignee_id UUID REFERENCES agents(id),
    created_at TIMESTAMP DEFAULT NOW()
);

-- Agent tasks queue
CREATE TABLE agent_task_queue (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    issue_id UUID REFERENCES issues(id),
    agent_id UUID REFERENCES agents(id),
    status VARCHAR(50) DEFAULT 'queued',  -- queued, dispatched, running, completed, failed
    priority INTEGER DEFAULT 5,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Runtimes table
CREATE TABLE agent_runtimes (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255),
    provider VARCHAR(50),
    status VARCHAR(50) DEFAULT 'offline',
    last_heartbeat TIMESTAMP
);

This is what you see after a successful run.

are these tables enough to create an agent? may be. Our goal is to setup minimal configuration to create an agent and run the agent in the background, inspired by the Multica’s architecture. You can learn more about Multica’s architecture on Deepwiki..

Create basic API endpoints for agents

Let’s get started with backend files. To setup basic API endpoints, you need to create the following files:

main.py

Create main.py in the backend folder and the following code:

from fastapi import FastAPI, WebSocket
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],
    allow_methods=["*"],
    allow_headers=["*"],
)

# Database models and routes
from routes import agents, issues, tasks, websocket
app.include_router(agents.router, prefix="/api/agents", tags=["agents"])
app.include_router(issues.router, prefix="/api/issues", tags=["issues"])
app.include_router(tasks.router, prefix="/api/tasks", tags=["tasks"])

routes/agents.py

Create routes folder and add a file named agents.py in the routes folder.

from fastapi import APIRouter, HTTPException
from pydantic import BaseModel
from database import get_db

router = APIRouter()

class AgentCreate(BaseModel):
    name: str
    provider: str  # claude, codex, etc.
    instructions: str = ""

@router.post("/")
async def create_agent(agent: AgentCreate):
    # Create agent in database
    # Return created agent
    pass

@router.get("/")
async def list_agents():
    # Return all agents
    pass

@router.get("/{agent_id}")
async def get_agent(agent_id: str):
    # Return specific agent
    pass

routes/issues.py

Create a file named issues.py and add the below code

class IssueCreate(BaseModel):
    github_issue_id: int
    title: str
    description: str = ""

@router.post("/")
async def create_issue(issue: IssueCreate):
    # Create issue in database
    # Optionally sync with GitHub API
    pass

@router.post("/{issue_id}/assign")
async def assign_issue(issue_id: str, agent_id: str):
    # Assign issue to agent
    # Enqueue task for agent
    # This triggers the agent execution flow
    pass

routes/tasks.py

Create a file named tasks.py and add the following code

@router.get("/claim")
async def claim_task(runtime_id: str):
    # Daemon calls this to claim next available task
    # Use FOR UPDATE SKIP LOCKED for concurrent safety
    pass

@router.post("/{task_id}/start")
async def start_task(task_id: str):
    # Mark task as running
    # Broadcast via WebSocket
    pass

@router.post("/{task_id}/complete")
async def complete_task(task_id: str, result: dict):
    # Mark task as completed
    # Update issue status if needed
    pass

coding-agent is open source and available at thinkthroo/coding-agent

About me:

Hey, my name is ramunarasinga. Email: ramunarasinga@gmail.com

Tired of AI slop?

I spent 3+ years studying OSS codebases and wrote 350+ articles on what makes them production-grade. I built

An open source tool that reviews your PR..
Codebase architecture skills, inspired by best OSS projects.

Get started for free — thinkthroo.com

References:

How to build a coding agent - Part 1.0

Ramu Narasinga — Wed, 03 Jun 2026 15:30:00 +0000

In this tutorial series, we build a coding agent that you can assign tasks on GitHub. In this part 1.0, we discuss:

Plan
Architecture
Table of content

This tutorial series is inspired by Multica, an open-source managed agents platform.

The plan

I noticed Multica repository has been trending on GitHub. With Multica, you can assign your GitHub issues to an agent you create via Multica platform and it picks up the work, writes code, report blockers, and update statuses autonomously.

Well, may you could just vibe code this entire Multica clone, but the reason I wrote this series is because I wanted to understand how Multica creates agents, how an issue can be assigend to an agent, how to executes in the background, underlying system architecture.

We use DeepWiki to understand the Multica's codebase architecture apply those principles in the project we build.

Multica uses Go in the backend, we will implement this in Python. Architecture and the concepts will be same, just that we use a different programming language. The goal is not to copy the exact way of Multica's architecture but rather take inspiration and implement.

Architecture

Let's just reiterate the tech stack:

Frontend:

React + Vite
TanStack Query

Backend:

FastAPI (Python)

Goal:

Create an Agent via the UI
Save this Agent info in the database
Assign a task on Github to this agent
Daemon implementation to complete the assigned task.

While we implement the above goals, we study the Multica's architecture and replicate the patterns in our project, frameworks may vary, but the principles would not change.

Table of content

Part 1: Foundation and setup
Part 2: Agent Creation System
Part 3: GitHub Integration
Part 4: Task Assignment System
Part 5: Agent Execution Layer
Part 6: Real-time updates
Part 7: Task Completion and GitHub Sync
Part 8: Advanced features

About me:

Hey, my name is ramunarasinga. Email: ramunarasinga@gmail.com

Tired of AI slop?

I spent 3+ years studying OSS codebases and wrote 350+ articles on what makes them production-grade. I built

An open source tool that reviews your PR..
Codebase architecture skills, inspired by best OSS projects.

Get started for free — thinkthroo.com

References:

gitrelease.mjs file in Nango codebase.

Ramu Narasinga — Tue, 02 Jun 2026 15:30:00 +0000

In this article, we review gitrelease.mjs file in Nango codebase. You will learn:

gitrelease.mjs file
publish workflow

gitrelease.mjs file

gitrelease.mjs. is defined in the scripts folder and is defined as shown below:

#!/usr/bin/env zx
import { $, echo } from 'zx';

const { GITHUB_TOKEN } = process.env;
const nextVersion = process.argv[3];
const branch = process.argv[4] || 'master';
const nextTag = `v${nextVersion}`;

echo`Publishing ${nextVersion} on branch ${branch}`;

await $`git config --global user.email "contact@nango.dev"`;
await $`git config --global user.name "Release Bot"`;

const tagExists = await $`git tag -l ${nextTag}`;
if (tagExists.stdout !== '') {
    echo`Tag ${nextTag} already exists`;
    process.exit(1);
}

const releaseMessage = `chore(release): ${nextVersion}`;

echo`Checkout out branch`;
await $`git fetch origin ${branch}`;
await $`git switch ${branch}`;

echo`Generating changelog`;
await $`npx git-cliff -o CHANGELOG.md -t ${nextTag}`;

echo`Adding file`;
await $`git add -A package.json package-lock.json packages/**/package.json CHANGELOG.md packages/**/lib/version.ts`;

echo`Creating commit`;
await $`git commit --allow-empty --author="Release Bot <contact@nango.dev>" -m ${releaseMessage} `;

echo`Creating tag`;
await $`git tag -a ${nextTag} HEAD -m ${releaseMessage}`;

echo`Pushing`;
// Rebase on latest to handle commits that landed on ${branch} during publish
await $`git fetch origin ${branch}`;
await $`git rebase origin/${branch}`;
// Push branch and tag separately - tag intentionally points to the pre-rebase commit
await $`git push origin HEAD:refs/heads/${branch}`;
await $`git push origin ${nextTag}`;

echo`Commit pushed, publishing release...`;
// Push GitHub release
const releaseNotes = await $`npx git-cliff --latest --strip header footer`;
const releaseData = JSON.stringify({
    name: nextTag,
    tag_name: nextTag,
    body: releaseNotes.stdout
});

try {
    await $`curl --silent --fail --show-error -H "Authorization: Bearer ${GITHUB_TOKEN}" -H "Accept: application/vnd.github.v3+json" https://api.github.com/repos/NangoHQ/nango/releases -d ${releaseData}`;
} catch (err) {
    console.log(err, releaseData);
    process.exit(1);
}

echo`✅ Done`;

You can follow the echo statements to understand what is happening in the code:

Check out branch
Generating changelog
Adding file
Creating commit
Creating tag
Pushing
Commit pushed, publishing release.

I wrote a separate article about what git-cliff is.

publish workflow

It is a common practice to define scripts and run them in the GitHub workflows. nango/.github/workflows/publish.yaml is defined as below:

name: '[Release] NPM publish'
run-name: '[Release] NPM publish ${{ inputs.version }}'

on:
    workflow_dispatch:
        inputs:
            version:
                type: string
                description: 'Version to publish'
                required: true
                default: '0.0.0'

permissions:
    contents: write
    id-token: write

jobs:
    npm-publish:
        if: github.ref == 'refs/heads/master'
        runs-on: ubuntu-latest
        steps:
            - uses: actions/create-github-app-token@v2
              id: create_github_app_token
              with:
                  app-id: ${{ secrets.GH_APP_PUSHER_ID }}
                  private-key: ${{ secrets.GH_APP_PUSHER_PRIVATE_KEY }}

            - uses: actions/checkout@v4
              with:
                  token: ${{ steps.create_github_app_token.outputs.token }}
                  fetch-depth: 0

            - uses: actions/setup-node@v4
              with:
                  cache: 'npm'
                  node-version-file: '.nvmrc'
                  registry-url: 'https://registry.npmjs.org'

            - name: Update npm to latest
              run: npm install -g npm@11.5.1

            - name: Install dependencies
              run: npm ci

            - name: Publish npm packages
              shell: bash
              run: |
                  npx zx ./scripts/publish.mjs --version="${{ inputs.version }}"

            - name: Publish release
              env:
                  GITHUB_TOKEN: ${{ steps.create_github_app_token.outputs.token }}
              run: |
                  npx zx ./scripts/gitrelease.mjs "${{ inputs.version }}" "${{ github.head_ref || github.ref_name }}"

In the run: section, you will see that this script is invoked using the command:

npx zx ./scripts/gitrelease.mjs "${{ inputs.version }}" "${{ github.head_ref || github.ref_name }}"

About me:

Hey, my name is ramunarasinga. Email: ramunarasinga@gmail.com

Tired of AI slop?

I spent 3+ years studying OSS codebases and wrote 350+ articles on what makes them production-grade. I built

An open source tool that reviews your PR..
Codebase architecture skills, inspired by best OSS projects.

Get started for free — thinkthroo.com

References:

git-cliff, a changelog generator.

Ramu Narasinga — Mon, 01 Jun 2026 15:30:00 +0000

In this article, we review git-cliff. You will learn:

What is git-cliff?
git-cliff usage in Nango

What is git-cliff?

git-cliff is a highly customizable Changelog Generator that follows Conventional Commit specifications.

High customizable

git-cliff uses regex-powered custom parsers and the changelog can be customized easily with a configuration file to match the desired format.

Conventional Commits

git-cliff can generate changelog files for any Git repository that follows the conventional commits specification.

Easy Integration

git-cliff can be easily integrated with your Rust/Python/Node.js project as a command-line tool and also can be used as a library for Rust projects.

Quick start

Install git-cliff

cargo install git-cliff

Initialise git-cliff:

git-cliff --init

Edit the default Configuration. (cliff.toml) as you like. Check out the

example. for different templates.

Generate a changelog

git-cliff -o CHANGELOG.md

git-cliff usage in Nango

I found the cliff.toml file in Nango codebase. It is defined as shown below.

# git-cliff ~ configuration file
# https://git-cliff.org/docs/configuration

[changelog]
# changelog header
header = """
# Changelog\n
All notable changes to this project will be documented in this file.\n
"""
# template for the changelog body
# https://keats.github.io/tera/docs/#introduction
body = """
{% if version -%}
    ## [{{ version }}] - {{ timestamp | date(format="%Y-%m-%d") }}
{% else -%}
    ## [Unreleased]
{% endif -%}
{% for group, commits in commits | group_by(attribute="group") %}
    ### {{ group | upper_first }}
    {% for commit in commits %}
        - {% if commit.scope %}*({{ commit.scope }})* {% endif %}\
           {{ commit.message | upper_first }}\
           {% if commit.github.username %} by @{{ commit.github.username }}{%- endif -%}
    {% endfor %}
{% endfor %}\n
"""
# template for the changelog footer
footer = """
{% for release in releases -%}
    {% if release.version -%}
        {% if release.previous.version -%}
            [{{ release.version }}]: \
                https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}\
                    /compare/{{ release.previous.version }}..{{ release.version }}
        {% endif -%}
    {% else -%}
        [unreleased]: https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}\
            /compare/{{ release.previous.version }}..HEAD
    {% endif -%}
{% endfor %}
<!-- generated by git-cliff -->
"""
# remove the leading and trailing whitespace from the templates
trim = true

[git]
# parse the commits based on https://www.conventionalcommits.org
conventional_commits = true
# filter out the commits that are not conventional
filter_unconventional = true
# process each line of a commit as an individual commit
split_commits = false
# regex for parsing and grouping commits
commit_parsers = [
  { message = "^feat", group = "Added" },
  { message = "^.*: add", group = "Added" },
  { message = "^test", group = "Fixed" },
  { message = "^fix", group = "Fixed" },
  { message = "^.*: fix", group = "Fixed" },
  { message = "^chore.release.", skip = true },
  { message = "^.*", group = "Changed" },
]
# protect breaking changes from being skipped due to matching a skipping commit_parser
protect_breaking_commits = false
# filter out the commits that are not matched by commit parsers
filter_commits = true
# regex for matching git tags
tag_pattern = "v[0-9].*"
# regex for skipping tags
skip_tags = ""
# regex for ignoring tags
ignore_tags = ""
# sort the tags topologically
topo_order = false
# sort the commits inside sections by oldest/newest order
sort_commits = "oldest"

You can find the generated Nango's changelog at CHANGELOG.md.

About me:

Hey, my name is ramunarasinga. Email: ramunarasinga@gmail.com

Tired of AI slop?

I spent 3+ years studying OSS codebases and wrote 350+ articles on what makes them production-grade. I built

An open source tool that reviews your PR..
Codebase architecture skills, inspired by best OSS projects.

Get started for free — thinkthroo.com

References:

Build product integrations with AI using Nango.

Ramu Narasinga — Thu, 28 May 2026 15:30:00 +0000

In this article, we review Nango. You will learn:

What is Nango?
How it works?
Use cases.

What is Nango?

Nango is an open-source platform for building product integrations. It supports 800+ APIs. and works with any backend language, AI coding tool, and agent SDK.

You write integration logic as TypeScript functions, or let AI generate them for you, and deploy to Nango's production runtime. Nango handles auth, execution, scaling, and observability.

Used in production by Replit, Ramp, Mercor, and hundreds more.

Learn more about Nango.

How it works?

Nango gives you three primitives that cover every integration pattern:

1. Auth

Managed OAuth, API keys, and token refresh for 800+ APIs. Embed a white-label auth flow in your app. Nango handles credentials, token storage, and multi-tenant connection management.

// Embed auth in your frontend
nango.openConnectUI({ onEvent: (event) => { /* handle completion */ } });

2. Proxy

Make authenticated API requests on behalf of your users. Send requests through Nango's proxy: it resolves the provider, injects credentials, handles retries and rate limits, and returns the response.

import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: '<NANGO-SECRET-KEY>' });

// Make an authenticated request to any API
const response = await nango.get({
    endpoint: '/v3/contacts',
    providerConfigKey: '<INTEGRATION-ID>',
    connectionId: '<CONNECTION-ID>'
});

3. Functions

Write integration logic as TypeScript functions and deploy to Nango. Functions execute on a production runtime with built-in API access, retries, storage, and observability.

Use the AI builder to generate them from a description of your use case.

export default async function run(nango: Nango) {
    const { owner, repo, title, body } = nango.input;

    const response = await nango.post({
        endpoint: `/repos/${owner}/${repo}/issues`,
        data: { title, body }
    });

    return response.data;
}

I copied this above info from theNango README..

Usecases.

I found these following in the Nango docs:

Check out the Nango documentation..

About me:

Hey, my name is ramunarasinga. Email: ramunarasinga@gmail.com

Tired of AI slop?

I spent 3+ years studying OSS codebases and wrote 350+ articles on what makes them production-grade. I built

An open source tool that reviews your PR..
Codebase architecture skills, inspired by best OSS projects.

Get started for free — thinkthroo.com

References:

DeepWiki, AI documentation you can talk to, for every repo

Ramu Narasinga — Wed, 27 May 2026 15:30:00 +0000

In this article, we review DeepWiki. You will learn:

What is DeepWiki?

What is DeepWiki?

DeepWiki. helps you understand any public repository. You can add a repository using the shown below image.

VSCode Example:

I found this wiki docs for the VSCode codebase https://deepwiki.com/microsoft/vscode.

This is quite powerful, helps you understand any codebase. You can use this to learn the codebase architecture, understand patterns, best practices.

I indexed my own open source project, thinkthroo. It says the indexing process takes anywhere between 2–10 minutes

I found this open source alternative of deepwiki — https://github.com/AsyncFuncAI/deepwiki-open.

Deepwiki-open

AsyncFuncAI/deepwiki-open. provides the following features:

Analyze the code structure
Generate comprehensive documentation
Create visual diagrams to explain how everything works
Organize it all into an easy-to-navigate wiki

DeepWiki is powered by Devin, AI software engineer. For the private repositories, DeepWiki lets you index using Devin.

About me:

Hey, my name is ramunarasinga. Email: ramunarasinga@gmail.com

Tired of AI slop?

I spent 3+ years studying OSS codebases and wrote 350+ articles on what makes them production-grade. I built

An open source tool that reviews your PR..
Codebase architecture skills, inspired by best OSS projects.

Get started for free — thinkthroo.com

References:

Here is how you can render HTML-based videos using AI coding agent.

Ramu Narasinga — Thu, 21 May 2026 15:30:00 +0000

In this article, we review HyperFrames. You will learn:

What is HyperFrames?
HyperFrames vs Remotion

What is HyperFrames?

Hyperframes is an open-source video rendering framework that lets you create, preview, and render HTML-based video compositions - with first-class support for AI agents.

Getting Started

You want to install the HyperFrames skills:

npx skills add heygen-com/hyperframes

and then, define your prompt. Below is an example prompt:

Using /hyperframes, create a 10-second product intro with a fade-in title, a background video, and background music.

Hyperframes also provides to create a project manually.

npx hyperframes init my-video
cd my-video
npx hyperframes preview # preview in browser (live reload)
npx hyperframes render # render to MP4

I highly recommend reading the HyperFrames README..

HyperFrames vs Remotion

Hyperframes is inspired by Remotion.- we used Remotion at HeyGen in production, learned a ton from it, and kept attribution comments in the source for the patterns it pioneered (Chrome launch flags, image2pipe → FFmpeg streaming, frame buffering). Both tools drive headless Chrome and both are deterministic. They differ on one decision: what the primary author writes. Remotion's bet is React components; Hyperframes' bet is HTML.

I copied this info from the README.

Remotion.also has a feature -Prompt a video.

I also did write an article about how Remotion uses Degit to download template..

About me:

Hey, my name is ramunarasinga. Email: ramunarasinga@gmail.com

Tired of AI slop?

I spent 3+ years studying OSS codebases and wrote 350+ articles on what makes them production-grade. I built

An open source tool that reviews your PR..
Codebase architecture skills, inspired by best OSS projects.

Get started for free — thinkthroo.com

References:

attw script in CopilotKit codebase.

Ramu Narasinga — Thu, 14 May 2026 15:30:00 +0000

In this article, we review attw script in CopilotKit codebase. You will learn:

What is attw?
attw script in CopilotKit

What is attw?

attw is a CLI for arethetypeswrong.github.io..This project attempts to analyze npm package contents for issues with their TypeScript types, particularly ESM-related module resolution issues. The following kinds of problems can be detected in the node10, node16, and bundler module resolution modes:

💀 Resolution failed.

❌ No types.

🎭 Masquerading as CJS.

👺 Masquerading as ESM.

⚠️ ESM (dynamic import only).

🐛 Used fallback condition.

🤨 CJS default export.

❗️ Incorrect default export.

❓ Missing export =.

🚭 Unexpected module syntax.

🥴 Internal resolution error.

🕵️‍♂️ Named exports.

Below is a check I ran on my npm package, thinkthroo and these were the issues found

attw script in CopilotKit

Since now that we understand what attw does, let’s review how CopilotKit uses this in the package.json script.

I the CopilotKit/packages/agentcore-runner/package.json,. you will find the below code nsippet:

"scripts": {
    ...
    "attw": "attw --pack . --profile node16"
  },

This has two arguments/options/flags passed.

pack

Specify a directory to run npm pack in (instead of specifying a tarball filename), analyze the resulting tarball, and delete it afterwards.

attw --pack .

profile

Profiles select a set of resolution modes to require/ignore. All are evaluated but failures outside of those required are ignored.

The available profiles are:

strict - requires all resolutions
node16 - ignores node10 resolution failures
esm-only - ignores CJS resolution failures

In the CLI: --profile

The script in CopilotKit ignores the node10 resolution failures.

About me:

Hey, my name is ramunarasinga. Email: ramunarasinga@gmail.com

Tired of AI slop?

I spent 3+ years studying OSS codebases and wrote 350+ articles on what makes them production-grade. I built

An open source tool that reviews your PR..
Codebase architecture skills, inspired by best OSS projects.

Get started for free — thinkthroo.com

DEV Community: Ramu Narasinga

`acquireLock` function in claude-context codebase.

What is claude-context?

Setup

saveCodebaseSnapshot

acquireLock function explained.

About me:

References:

Hunk, terminal diffs for humans and agents.

What is Hunk??

Features

Quick start

Working with Git

Working with agents

Modem

Build what’s actually important

Act on problems you didn’t know you had

About me:

References:

`undici.setGlobalDispatcher` function in pi-coding-agent package.

What is pi-coding-agent?

What is Undici?

Why Use the Standalone Package?

setGlobalDispatcher method in pi-coding-agent

undici.setGlobalDispatcher(dispatcher)

About me:

References:

How to build a custom Claude plugin?

What is a Claude plugin?

When to use a plugin?

Build a simple Claude plugin

Create the plugin directory

Create the plugin manifest.

Add a skill

Test your plugin

Add a skill argument

About me:

References:

How to build a coding agent — Part 1.1

Set up React + Vite frontend

Set up Python FastAPI backend

Design and implement database schema

Create basic API endpoints for agents

About me:

References:

How to build a coding agent - Part 1.0

The plan

Architecture

Goal:

Table of content

About me:

References:

gitrelease.mjs file in Nango codebase.

gitrelease.mjs file

publish workflow

About me:

References:

git-cliff, a changelog generator.

What is git-cliff?

High customizable

Conventional Commits

Easy Integration

Quick start

git-cliff usage in Nango

About me:

References:

Build product integrations with AI using Nango.

What is Nango?

How it works?

1. Auth

2. Proxy

3. Functions

Usecases.

About me:

References:

DeepWiki, AI documentation you can talk to, for every repo

What is DeepWiki?

VSCode Example:

Deepwiki-open

About me:

`acquireLock` function explained.