Forem: PADMANABHA DAS

Nobody Reads My Release Notes. So I Stopped Writing Them Myself

PADMANABHA DAS — Sat, 03 Jan 2026 18:57:55 +0000

When was the last time you actually read release notes?

I mean, really read them — not just skimmed for "breaking changes" before hitting update.

Probably never. And honestly? That's partly my fault. Because for years, my release notes looked like this: "Various bug fixes and performance improvements", which tells you absolutely nothing.

The Problem With "I'll Write It Later"

Here's what actually happens when you promise yourself you'll write proper release notes:

You finish the release
You tell yourself you'll document it tomorrow
Tomorrow you start the next feature
Two weeks later, someone asks, "what changed in v1.2.0?"
You open the commit history and cry

The information exists. Every commit message, every PR description, every file change — it's all there in Git. The problem isn't missing data. It's that turning raw commits into readable release notes requires context switching from "building things" to "documenting things."

And after a long sprint, that switch is brutal.

What If I Just... Didn't?

I built a GitHub MCP server with 44+ tools. One day, I realized: Claude can read my commit history. It can see what files changed. It knows which PRs got merged.

Why am I manually doing what an AI can do in 30 seconds?

So now, when I'm ready to tag a release, I just ask Claude:

"List all commits on master since the last release tag. Analyze the changes and generate release notes."

And it works!

The Actual Workflow

Let me show you what this looks like with my GitHub MCP server (v1.3.0 release).

Step 1: Find the Last Release

First, I need to know where I'm starting from:

// Tool: list-releases
{
  owner: "chayan-1906",
  repository: "GitHub-MCP",
  perPage: 1,
  currentPage: 1
}

This gives me:

{
  "tagName": "v1.2.0",
  "name": "v1.2.0",
  "publishedAt": "2025-09-14T...",
  "body": "..."
}

Now I know: everything after v1.2.0 needs to be in my release notes.

Step 2: Get Commits Since That Release

// Tool: list-commits
{
  owner: "chayan-1906",
  repository: "GitHub-MCP",
  sha: "master",
  perPage: 50
}

Claude gets back a list of commits with messages, authors, and timestamps. It filters to only commits after the v1.2.0 release date.

Step 3: Understand What Actually Changed

This is where it gets interesting. For commits with vague messages (we've all written "fix bug" at 2 AM), Claude digs deeper:

// Tool: get-commit-modifications
{
  owner: "chayan-1906",
  repository: "GitHub-MCP",
  commitSha: "abc123..."
}

This returns the actual file changes:

[
  {
    "filename": "src/routes/SystemRoutes.ts",
    "status": "added",
    "additions": 45,
    "deletions": 0
  },
  {
    "filename": "src/routes/AuthRoutes.ts",
    "status": "modified",
    "additions": 12,
    "deletions": 8
  }
]

Even if my commit message was useless, Claude can see that I added a new routing file and modified auth routes. That's enough context to understand what happened.

Step 4: Generate the Release Notes

After analyzing 15-20 commits, Claude synthesizes everything:

## v1.3.0 (2025-09-17)

### 🔄 Changes

- **Routing System**: Separated system and authentication routes
  - Created dedicated `SystemRoutes.ts` for homepage functionality
  - Moved authentication endpoints to `/auth` prefix

- **Error Handling**: Improved error reporting across GitHub tool integrations

- **Type Safety**: Added `ToolsMap` interface for better TypeScript definitions

### 📦 Dependencies

- axios: `^1.11.0` → `^1.12.2`
- mongodb: `^6.18.0` → `^6.19.0`
- typescript: `^5.8.3` → `^5.9.2`

### 🧹 Code Quality

- Removed legacy `toolHelpers.ts` in favor of `mcp-utils` package
- Centralized tool definitions with dynamic parameter descriptions

That took about 45 seconds. Writing it manually would've taken 20 minutes of scrolling through commits and trying to remember why I changed that one file.

Step 5: Create the Release

If I'm happy with the notes, Claude can create the release directly:

// Tool: create-release
{
  owner: "chayan-1906",
  repository: "GitHub-MCP",
  tagName: "v1.3.0",
  name: "v1.3.0",
  body: "## v1.3.0 (2025-09-17)\n\n### 🔄 Changes\n...",
  draft: false,
  prerelease: false
}

Done. Release published with proper documentation.

The Tools That Make This Work

Tool	Purpose
`list-releases`	Find the last release tag and date
`list-commits`	Get all commits since that release
`get-commit-modifications`	See actual file changes per commit
`create-release`	Publish the release with generated notes
`update-release`	Fix typos without recreating everything

Five tools. That's the entire workflow.

What Claude Actually Does Well Here

Pattern recognition. When Claude sees commits like:

refactor: extract routes to dedicated files
refactor: move auth endpoints
chore: update route imports

It understands these are related and groups them under "Routing System" instead of listing three separate line items.

Dependency tracking. If package.json changed, Claude reads the diff and extracts the actual version bumps. No more "updated dependencies" as a line item.

Categorization. Features vs. fixes vs. refactors vs. chores. Claude applies conventional commit patterns even when my messages weren't perfectly formatted.

The Honest Limitations

This isn't magic. There are gaps:

Breaking changes — Claude can identify API changes in code, but it can't always know if they're breaking. I still review for that.
User-facing impact — "Refactored database queries" doesn't tell users what got faster. I add context for significant performance changes.
Security fixes — I don't put security details in public release notes anyway, but Claude doesn't know what to redact. Manual review required.
First release — No previous tag to compare against. You'll need to specify a date range or commit range manually.

My Actual Prompt

Here's what I usually ask:

"Using my GitHub MCP tools, list all releases for [repo_url]. Then list commits on the master branch since the most recent release. For any commits that touch more than 3 files, get the file modifications. Finally, generate release notes grouped by: features, fixes, refactors, dependencies, and breaking changes (if any). Use emoji headers”

Claude handles the multi-step orchestration. I just review the output and hit publish.

Why This Actually Matters

Good release notes aren't just documentation theater. They're:

For your users: So they know if they should upgrade
For your future self: So you remember what v1.2.0 even was
For contributors: So they see their work acknowledged

I wasn't writing bad release notes because I didn't value them. I was writing bad release notes because the manual process was painful enough that I avoided it.

Automating the painful part means I actually ship proper documentation now.

Setting It Up

The GitHub MCP server is open source:

Repository: github.com/chayan-1906/GitHub-MCP

Download the executable, run it once, and Claude Desktop will recognize the tools automatically. Full setup takes about 2 minutes.

My release notes still aren't perfect. But they're a lot better than "bug fixes and improvements."

And honestly? That's enough.

Building AI tools for developer workflows. Find me on LinkedIn or check out my other projects on GitHub.

I Stopped Writing Commit Messages. Here's What I Do Instead.

PADMANABHA DAS — Thu, 25 Dec 2025 19:43:20 +0000

I have a confession: I'm terrible at writing commit messages.

Not the commits themselves — I know what I changed. But turning "fixed that thing where the button didn't work on mobile" into a proper fix: resolve touch event handler on mobile viewport while I'm in the zone? That's where I fall apart.

And PR descriptions? Forget it. By the time I've made 15 commits across three days, I can barely remember what the first five were about.

So I built a tool to do it for me.

The Problem No One Talks About

Here's my typical workflow before I automated this:

Make changes
git add .
Stare at terminal for 30 seconds, trying to remember what I just did
Write something vague like update stuff
Repeat 12 times
Open PR
Spend 20 minutes scrolling through commits to write a description
Give up and write "various fixes and improvements"

Sound familiar?

The thing is, I know what good commit messages look like. I just don't have the mental energy to write them while I'm deep in code. Context switching from "solving a problem" to "documenting a solution" is exhausting.

What I Actually Built

I created a GitHub MCP server — 44+ tools that let Claude interact directly with my repositories. But honestly? I use maybe 5 of them regularly. And they all revolve around one thing: making Claude do the boring parts of version control.

Here's my actual workflow now:

Workflow 1: "What Did I Even Do?"

After making changes but before committing, I ask Claude:

"Check my uncommitted changes and suggest a commit message. Use conventional commits format"

Claude uses the file system tools to scan my changes, looks at what files were modified, reads the diffs, and comes back with something like:

feat(auth): implement refresh token rotation with 7-day expiry

- Add token rotation logic in authMiddleware
- Update User model with refreshTokenFamily field

That's better than anything I would've written at 11 PM.

Workflow 2: "Summarize My Last Week"

This is the one I use before creating PRs. Let's say I'm on a feature branch with a bunch of commits, and I need to open a PR against master

I ask Claude:

"Using my GitHub MCP tools, list all commits on feature/user-dashboard that aren't on master. Analyze what changed across all of them, then give me a PR title, description, and suggested labels"

Here's what happens behind the scenes:

Step 1: Claude calls list-commits on the feature branch:

// Tool: list-commits
{
  owner: "chayan-1906",
  repository: "PulsePress",
  branch: "feature/user-dashboard",
  perPage: 30,
  currentPage: 1,
}

Step 2: For each commit, Claude calls get-commit-modifications to see the actual file changes:

// Tool: get-commit-modifications
{
  owner: "chayan-1906",
  repository: "PulsePress",
  commitSha: "a1b2c3d..."
}

This returns the filenames, additions, deletions, and even the patch diffs.

Step 3: Claude synthesizes everything and generates:

## PR Title
feat(dashboard): implement user analytics dashboard with real-time updates

## Description
This PR adds a comprehensive analytics dashboard for users to track their reading habits and content engagement.

### Changes
- New Components: AnalyticsChart, ReadingHistory, EngagementMetrics
- API Integration: Added endpoints for fetching user analytics data
- Real-time Updates: Implemented WebSocket connection for live stats
- Database: New analytics collection with aggregation pipelines

## Suggested Labels
feature, frontend, backend, needs-review

Step 4: If I'm happy with it, Claude can even create the PR directly:

// Tool: create-pull-request
{
  owner: "chayan-1906",
  repository: "PulsePress",
  title: "feat(dashboard): implement user analytics dashboard with real-time updates",
  head: "feature/user-dashboard",
  base: "master",
  body: "..." // The generated description
}

The Tools That Make This Work

Out of 44+ tools in my GitHub MCP server, here are the ones I actually use for this workflow:

Tool	What It Does
`list-commits`	Gets commits from a branch with pagination
`get-commit-modifications`	Shows file changes for a specific commit (additions, deletions, patches)
`list-branches`	Lists all branches when I forget my branch names
`create-pull-request`	Creates the PR with title, body, head/base branches
`list-pull-request-files`	Shows what files a PR touches (useful for reviewing my own PRs)

That's it. Five tools for 90% of my use case.

A Real Example

Last month, I worked on migrating my API from callback-based error handling to a centralized middleware approach. Seven commits over two days.

Here's what Claude generated after analyzing them:

## PR Title
refactor(api): migrate to centralized error handling middleware

## Description
Replaces scattered try-catch blocks with a unified error handling approach using Express middleware.

### Commits Analyzed
1. refactor: extract error types to dedicated module
2. feat: add ErrorHandler middleware
3. refactor: update auth routes to use new error handling
4. refactor: update user routes to use new error handling
5. refactor: update news routes to use new error handling
6. test: add error handling middleware tests
7. chore: remove deprecated error utility functions

### Impact
- Lines Changed: +245 / -312 (net reduction!)
- Files Modified: 14
- Breaking Changes: None (error response format unchanged)

## Suggested Labels
refactor, backend, tech-debt

I would have written: "refactor error handling". Claude gave me context I'd already forgotten.

Why This Isn't Cheating

I used to feel guilty about this. Like I was exposing some weakness by not writing my own commit messages.

But here's the thing: the commits still contain all the information. Claude isn't making up what I did — it's reading my actual changes and summarizing them. The code is mine. The decisions are mine. The documentation is just... automated.

It's the same reason we use linters and formatters. I don't manually fix indentation — why should I manually write "moved function from line 45 to line 23"?

Setting It Up

If you want to try this yourself, the GitHub MCP server is open source:

Repository: github.com/chayan-1906/GitHub-MCP

Quick start:

Download the executable for your OS from the releases page (https://github.com/chayan-1906/GitHub-MCP/releases)
Run it once (it sets up Claude Desktop integration automatically)
Start Claude and include "use available GitHub tools" in your prompts

The server runs locally and authenticates via GitHub OAuth. Your code never leaves your machine except through standard GitHub API calls.

What I'd Build Next

Honestly, this workflow has a gap: I can't analyze uncommitted changes through the GitHub API because... they're not on GitHub yet.

Right now, I use my File System MCP server for that part — it reads the local diff and suggests commit messages. But it would be cleaner to have a single tool that does both.

The Honest Takeaway

I'm not a better developer because I automated commit messages. I'm just a developer who recognized that "writing good documentation" and "writing good code" are two different skills — and I'm better at one than the other.

If you're like me — if you've ever written misc fixes or wip or asdfasdf as a commit message — maybe give this a try. Your future self (and your code reviewers) will thank you.

I write about AI tools I actually use. Find me on LinkedIn or check out my other projects on GitHub.

How I Review Pull Requests with Claude (and Actually Merge Them)

PADMANABHA DAS — Sat, 20 Dec 2025 06:57:07 +0000

Last month, I merged a critical PR that touched 14 files across 11 services. The usual process — opening GitHub, switching between tabs, mentally tracking what changed where — would've taken me an hour. I did it in 12 minutes.

The secret? I stopped treating Claude as a chatbot and started treating it as a GitHub client.

The Problem with Traditional PR Reviews

Here's my typical PR review workflow before I changed things:

Open GitHub, read the PR description
Click through each file, lose context switching between them
Open the codebase locally to understand the broader picture
Go back to GitHub, forget what I just read
Check the commit history to understand how the PR evolved
Repeat steps 2-5 until frustrated enough to just approve

The mental overhead is exhausting. And when you're reviewing your own PRs (solo developers, you know the drill), the context-switching kills whatever flow you had while coding.

I tried various solutions — GitHub CLI, VS Code extensions, even custom scripts. Nothing stuck because they all added friction in different places. What I wanted was simple: review PRs the way I think about them, not the way GitHub's UI organizes them.

Enter MCP: Making Claude Actually Useful for GitHub

MCP (Model Context Protocol) is Anthropic's open standard that lets AI assistants connect to external tools and data sources. Instead of copy-pasting code into Claude and asking "what does this do?", MCP lets Claude directly interact with services — including GitHub.

Think of it like this: without MCP, Claude is smart but blind. It can analyze code you show it, but it can't see your repositories, can't check your PR status, can't read your latest commits. With MCP, Claude gets eyes and hands.

The protocol works by running a local server that exposes "tools" — specific actions Claude can take. When I ask Claude about a PR, it doesn't scrape GitHub's website. It calls structured APIs through the MCP server, gets clean JSON responses, and reasons about them just like it reasons about any other information.

I built a GitHub MCP server with 44+ tools that gives Claude full access to repositories, branches, commits, issues, pull requests, and releases. The tools are organized by what they do:

Repository tools: Create, update, delete repos; manage collaborators; change visibility
Branch tools: Create branches, set defaults, view branch details
Commit tools: List commits, see what changed in each commit
Issue tools: Full issue lifecycle — create, update, assign, close
PR tools: The stars of this article — everything from listing PRs to merging them
Release tools: Create and manage releases

It's not a wrapper around the GitHub CLI. It's a proper integration that lets Claude understand my codebase the way I do.

Repository: github.com/chayan-1906/GitHub-MCP

How the MCP Server Works Under the Hood

When I ask Claude about a PR, here's what actually happens:

Claude recognizes it needs GitHub data and identifies the appropriate tool
It calls the MCP server with structured parameters (owner, repo, PR number)
The server authenticates with GitHub using my stored OAuth token
GitHub's API returns JSON data
The server passes that data back to Claude
Claude reasons about the data and responds in natural language

Each tool in my MCP server follows a consistent pattern. Here's a simplified look at how get-pull-request-details is registered:

server.tool(
  'get-pull-request-details',
  'Fetches detailed information about a specific GitHub pull request',
  {
    owner: z.string().describe('GitHub username or organization'),
    repository: z.string().describe('Repository name'),
    prNumber: z.number().describe('Pull request number'),
  },
  async ({ owner, repository, prNumber }) => {
    const accessToken = await getGitHubAccessToken();
    const prData = await fetchPullRequest(accessToken, owner, repository, prNumber);
    return { content: [{ type: 'text', text: JSON.stringify(prData, null, 2) }] };
  }
);

The z.string() and z.number() are Zod validators — they ensure Claude passes the right parameter types. The tool description helps Claude understand when to use each tool.

My PR Review Workflow (With a Real Example)

Let me walk you through how I actually review PRs now, using a real example from my news aggregation platform, PulsePress. This was a critical fix for my AI model fallback system — the kind of PR that would normally require careful, tedious review.

Step 1: Get the Big Picture

I start by asking Claude to fetch the PR details. No need to open GitHub at all:

Show me PR #9 from PulsePress-Node.js repository

Claude calls the get-pull-request-details tool and returns:

{
  "number": 9,
  "title": "fix: implement centralized AI model fallback system",
  "state": "closed",
  "merged": true,
  "commits": 6,
  "additions": 492,
  "deletions": 473,
  "changedFiles": 14,
  "headBranch": "fix/ai-fallback-system",
  "baseBranch": "master",
  "labels": ["critical-fix", "refactor", "system-wide", "reliability", "no-breaking-changes"]
}

Right away, I know this is a significant change — 14 files, nearly 1000 lines touched, labeled as critical. Claude also fetches the full PR description, which explains the problem: AI services were failing completely when a model became unavailable (say, Google deprecates gemini-2.3-flash-lite) instead of gracefully falling back to alternatives.

That's a critical vulnerability. If one AI model goes down, all 11 AI features in my app break. Not good.

Step 2: Understand What Changed

Next, I need to see which files were modified and how significant each change is:

List all files changed in this PR with their stats

Claude calls list-pull-request-files:

[
  { "filename": "src/services/QuotaService.ts", "status": "modified", "additions": 61, "deletions": 1 },
  { "filename": "src/services/SentimentAnalysisService.ts", "status": "modified", "additions": 32, "deletions": 31 },
  { "filename": "src/services/SummarizationService.ts", "status": "modified", "additions": 43, "deletions": 39 },
  { "filename": "src/services/ArticleEnhancementService.ts", "status": "modified", "additions": 46, "deletions": 50 },
  { "filename": "src/services/QuestionAnswerService.ts", "status": "modified", "additions": 57, "deletions": 55 },
  { "filename": "src/types/quota.ts", "status": "modified", "additions": 18, "deletions": 3 }
]

The pattern jumps out immediately: QuotaService.ts got 61 new lines with only 1 deletion — that's where the core fix lives. The service files all have roughly equal additions and deletions — they're being migrated to use the new pattern. And quota.ts has new type definitions to support the change.

This is a classic refactor structure: introduce abstraction in one place, migrate consumers everywhere else.

Step 3: Review the Core Changes

Now I dig into the actual implementation. I ask Claude to show me the new code:

Show me the new executeWithModelFallback method in QuotaService.ts

Claude uses get-file-content to read the file, and I see the heart of the fix:

static async executeWithModelFallback<T>({
  primaryModel,
  fallbackModels,
  executeAICall,
  count = 1
}: IExecuteWithModelFallbackParams<T>): Promise<IExecuteWithModelFallbackResponse<T>> {

  const modelsToTry: string[] = [primaryModel, ...fallbackModels];
  const attemptedModels: string[] = [];

  for (const modelName of modelsToTry) {
    attemptedModels.push(modelName);

    // Skip invalid models
    if (!GEMINI_MODELS.includes(modelName as TGeminiModel)) {
      console.warn('Unknown Gemini model, skipping', { modelName });
      continue;
    }

    // Try to reserve quota
    const quotaResult = await this.reserveQuotaForGeminiModel({
      modelName: modelName as TGeminiModel,
      count
    });

    if (!quotaResult.allowed) continue;

    // Quota reserved, now try the actual AI call
    try {
      const result = await executeAICall(modelName);
      return { success: true, result, selectedModel: modelName, attemptedModels };
    } catch (error: any) {
      // AI call failed, try next model
      console.warn('AI call failed, trying next model', { modelName, error: error.message });
    }
  }

  // All models exhausted
  return { success: false, error: 'ALL_AI_CALLS_FAILED', selectedModel: '', attemptedModels };
}

This is elegant. Previously, the code had a 2-step pattern: reserve quota first, then make the AI call separately. If the AI call failed (model deprecated, 404 error, rate limit), there was no retry mechanism — just complete failure. Now quota reservation and AI execution happen together inside a retry loop. If one model fails, it automatically tries the next.

Step 4: Verify the Migration Pattern

I want to make sure all 11 services migrated correctly. Consistency matters — if one service handles errors differently, that's a bug waiting to happen.

I pick one service and check:

Show me how SentimentAnalysisService.ts uses the new fallback method

The old pattern was:

// OLD: 2-step pattern (problematic)
const quotaReservation = await QuotaService.reserveQuotaForModelFallback({
  primaryModel: AI_SENTIMENT_MODELS[0],
  fallbackModels: AI_SENTIMENT_MODELS.slice(1),
  count: 1,
});
if (!quotaReservation.allowed) return { error: 'QUOTA_EXHAUSTED' };

const result = await this.analyzeWithGemini(quotaReservation.selectedModel, content);
// If this fails, no retry. Just failure.

The new pattern:

// NEW: 1-step pattern with automatic fallback
const fallbackResult = await QuotaService.executeWithModelFallback({
  primaryModel: AI_SENTIMENT_ANALYSIS_MODELS[0],
  fallbackModels: AI_SENTIMENT_ANALYSIS_MODELS.slice(1),
  executeAICall: (modelName: string) => this.analyzeWithGemini(modelName, content),
  count: 1,
});

if (!fallbackResult.success) {
  if (fallbackResult.error === 'QUOTA_EXHAUSTED') {
    return { error: 'GEMINI_DAILY_LIMIT_REACHED' };
  }
  return { error: 'SENTIMENT_ANALYSIS_FAILED' };
}

const result = fallbackResult.result!;

Clean. The AI call is now passed as a callback, and the retry logic is handled centrally. I spot-check two more services — same pattern. Consistent, reviewable, maintainable.

Step 5: Examine the Type Definitions

Good TypeScript code needs good types. I ask Claude to show me the new interfaces:

Show me the new types added in quota.ts

export interface IExecuteWithModelFallbackParams<T> {
  primaryModel: string;
  fallbackModels: string[];
  executeAICall: (modelName: string) => Promise<T>;
  count?: number;
}

export interface IExecuteWithModelFallbackResponse<T> {
  success: boolean;
  result?: T;
  error?: string;
  selectedModel: string;
  attemptedModels: string[];
}

The generic <T> is important — it means the same fallback method works for any AI service, whether it returns sentiment data, summaries, tags, or anything else. The attemptedModels array is clever too; it gives visibility into which models were tried before success (or failure). Great for debugging production issues.

Step 6: Check the Commit History

Sometimes the commit history reveals important context about how a solution evolved:

Show me the commits in this PR

Claude calls list-pull-request-commits and returns 6 commits. This tells me the solution was iterated, not rushed. The developer (me, weeks ago) made incremental progress rather than one massive "fix everything" commit.

Step 7: The Merge Decision

At this point, I have everything I need:

✅ Understood the problem (AI model failures with no fallback)
✅ Reviewed the core solution (centralized executeWithModelFallback)
✅ Verified migration consistency across all 11 services
✅ Examined type definitions for proper generics and error handling
✅ Confirmed no breaking changes (same API responses, just more reliable)
✅ Checked commit history for incremental development

The PR is solid. Ready to merge.

Claude has merge-pull-request available with configurable merge strategies (merge commit, squash, rebase). For this PR, I'd use squash merge to keep the main branch history clean. But for critical changes like this, I still click the merge button in GitHub's UI — old habits die hard, and there's something reassuring about that final manual confirmation.

The Tools That Make This Work

Here's a quick reference of the GitHub MCP tools I use most for PR reviews:

Tool	What It Does
`get-pull-request-details`	Fetches PR metadata, description, labels, merge status
`list-pull-request-files`	Lists all changed files with additions/deletions
`list-pull-request-commits`	Shows commit history within the PR
`get-file-content`	Reads any file from a specific branch
`get-commit-modifications`	Shows exactly what changed in a specific commit
`create-pull-request-review`	Submits review — approve, request changes, or comment
`merge-pull-request`	Merges with configurable strategy (merge/squash/rebase)

The server has 44+ tools total covering repositories, branches, issues, releases, and more. But for PR reviews, these seven are my daily drivers.

Why This Actually Works

Three reasons this workflow beats traditional PR reviews:

1. No context switching. Everything happens in one conversation. I don't lose track of what I read when I switch tabs because I never switch tabs. The entire review happens in Claude.

2. Claude remembers the conversation. When I ask "does the error handling in ArticleEnhancementService follow the same pattern we saw earlier?", Claude already knows what pattern I'm referring to. No need to re-explain context.

3. I can ask questions about the code. "Why did we change from return-based errors to exceptions in the Gemini methods?" Claude analyzes the diff and explains that exceptions allow the fallback loop to continue execution, while return { error } would exit immediately without trying other models.

Setting It Up

If you want to try this workflow:

Download the executable from the GitHub releases page (macOS and Windows available)
Run it once — it auto-configures Claude Desktop
Launch Claude Desktop
Start asking about your repositories

The server handles GitHub OAuth automatically. You authenticate once in your browser, and the token persists. No manual API token management.

The Honest Limitations

This isn't perfect. A few things I've learned:

Large diffs are still hard. If a PR touches 50+ files, even Claude struggles with that much context. I break those into focused questions about specific parts rather than trying to review everything at once.
It's not a replacement for running the code. I still pull branches locally for anything that needs actual testing or debugging. Claude can tell me what the code does, but it can't tell me if it actually works.
Rate limits exist. Heavy usage hits GitHub's API limits. The server handles rate limiting gracefully, but be aware during intense review sessions. I've never actually hit the limit during normal use, but batch operations (like reviewing 10 PRs in a row) might get throttled.
Private repos need proper OAuth scopes. If you're working with organization repositories or private repos, make sure your OAuth app has the right permissions. The server prompts for this during setup, but it's worth double-checking if you run into access issues.

Tips for Getting the Most Out of This Workflow

After using this setup for a few months, here's what I've learned:

Ask specific questions. "Review this PR" is too vague. "Show me all files that modify error handling" gives Claude something concrete to work with.

Start with the high-level view. I always get PR details first, then file list, then dive into specific files. This top-down approach matches how I think about code changes.

Use Claude's memory. Once you've discussed a pattern or decision earlier in the conversation, you can reference it. "Does this file follow the same pattern?" works because Claude remembers what pattern you discussed.

Don't be afraid to ask "why." "Why did we change from returns to exceptions here?" — Claude can often infer the reasoning from the surrounding code and explain it back to you.

What Changed For Me

I used to dread PR reviews. The clicking, the tab switching, the constant loss of mental context. Now I actually enjoy them. The friction is gone. I can focus on what matters — understanding the change, evaluating the design, catching potential bugs — instead of fighting with the interface.

If you're spending more time navigating GitHub than actually reviewing code, give this a shot. Setup takes five minutes. The productivity gain is permanent.

I Built a File System MCP Server — Here's Why Permissions Matter More Than Features

PADMANABHA DAS — Sun, 14 Dec 2025 15:48:53 +0000

A few months ago, I got excited about MCP (Model Context Protocol). The idea of giving Claude direct access to my file system seemed powerful — no more copy-pasting code snippets, no more describing folder structures. Just "Hey Claude, read my project and help me refactor it."

So I did what any developer does. I searched for existing implementations.

What I found scared me.

Most file system MCP tutorials hand Claude unrestricted access to your entire machine. Some have a hardcoded ALLOWED_DIRECTORIES array that you set once and forget. Others just... don't bother with permissions at all.

That's when it hit me: I was about to give an AI full read/write access to my computer. An AI that might misunderstand "clean up my Downloads" as "delete everything that looks messy".

The Trust Problem Nobody Talks About

Here's the thing about AI assistants — they're incredibly capable, but they make mistakes. Claude might reorganize your entire project to follow "best practices" when you're intentionally breaking them. It might overwrite a file while trying to help. It might decide that empty folders are useless and delete them (spoiler: sometimes they're not).

When I started building my own File System MCP server, I kept asking myself: would I actually use this on my real projects?

The honest answer was no. Not without proper guardrails.

Three Permission States: (Not Two, Why Binary Not Enough?)

Most permission systems think in binary: allowed or denied. But real-world file access isn't that simple.

Consider this scenario: I'm debugging a Next.js project. I want Claude to:

Read my source code to understand the bug
NOT write to src/ because I'll review changes first
Full access to my temp/ folder for testing fixes

This led me to three permission states:

[
  {
    "path": "/Users/padmanabhadas/next-js-projects/signalist/src",
    "operation": "read"
  },
  {
    "path": "/Users/padmanabhadas/next-js-projects/signalist/temp",
    "operation": "write"
  }
]

Notice how I can mix permissions within the same project? That granularity is crucial.

The Heart of the System: Path Resolution

Every file operation goes through one function: resolvePath(). This is where the magic (and paranoia) lives.

const resolvePath = async (relativePath: string, operation: 'read' | 'write'): Promise<string> => {
  const resolved = path.resolve(relativePath);
  const ALLOWED_ROOTS = await getAllowedRoots();

  // Find ALL matching roots, not just the first
  const matchingRoots = ALLOWED_ROOTS.filter((root: any) => {
    const resolvedBasePath = path.resolve(root.path);
    return resolved.startsWith(resolvedBasePath);
  });

  if (matchingRoots.length === 0) {
    throw new Error(`Access denied: ${relativePath} is outside allowed directories`);
  }

  // Most specific path wins - this took me weeks to debug
  const mostSpecificRoot = matchingRoots.sort((a: any, b: any) => b.path.length - a.path.length)[0];

  // Write implies read
  if (mostSpecificRoot.operation !== operation && mostSpecificRoot.operation !== 'write') {
    throw new Error(`Insufficient permissions for ${operation} operation`);
  }

  return resolved;
}

Three crucial design decisions here:

Most specific path wins. If /projects has read access but /projects/temp has write, operations in temp/ get write. This wasn't obvious initially — I had a bug where the first match won, making granular permissions impossible.
Write implies read. Obviously. But you'd be surprised how many systems make you specify both.
Absolute paths only. No ../ tricks. Everything gets resolved immediately.

Every Tool Is Paranoid (And That's Good)

Here's how tools actually use the permission system:

// read-file tool
export const getFileLines = async (filePath: string, startLine?: number, endLine?: number) => {
  // Permission check happens FIRST
  const fullPath = await resolvePath(filePath, 'read');

  // Only then we proceed
  const fileContent = await fs.readFile(fullPath, 'utf8');
  const lines = fileContent.split('\n');
  // ... rest of logic
}

// modify-file tool
export const modifyFile = async (filePath: string, operation: string, lineNumber: number, content?: string) => {
  // Different permission requirement
  const fullPath = await resolvePath(filePath, 'write');

  const fileContent = await fs.readFile(fullPath, 'utf8');
  // ... modification logic
}

I was tempted to add permission checks inside each tool, but centralizing everything in resolvePath() means I literally can't forget to check. One function, one responsibility, zero exceptions.

Shell Commands: Where Things Get Scary

Reading files? Safe. Writing files? Manageable. Shell commands? That's where my paranoia really kicked in.

When someone runs git status, that's clearly a read operation. But git push? That modifies a remote repository. What about ls > output.txt? That's reading a directory but writing a file.

const getCommandPermission = (command: string): 'read' | 'write' | 'none' => {
  const cmd = command.trim().toLowerCase();

  // No filesystem access needed
  const noAccessPatterns = [
    /^cd\s+/,
    /^pwd$/,
    /^echo\s+[^>]/,
    /^date$/,
    /^whoami$/,
  ];

  // Read-only commands
  const readOnlyPatterns = [
    /^git\s+(status|log|branch|diff|show)/,
    /^(ls|ll|la)\s*/,
    /^cat\s+[^>]/,
    /^grep\s+.*[^>]*$/,
    /^find\s+.*(?<!-delete)[^>]*$/,
  ];

  // Write operations
  const writePatterns = [
    /^git\s+(add|commit|push|pull|clone)/,
    /^(mkdir|rmdir|rm|cp|mv|touch)\s+/,
    /.*>\s*[^&]/,  // Output redirection
    /^npm\s+(install|run|build)/,
  ];

  for (const pattern of noAccessPatterns) {
    if (pattern.test(cmd)) return 'none';
  }

  for (const pattern of readOnlyPatterns) {
    if (pattern.test(cmd)) return 'read';
  }

  for (const pattern of writePatterns) {
    if (pattern.test(cmd)) return 'write';
  }

  // Default to write for safety
  return 'write';
}

Is this perfect? No. Someone could probably craft a command that slips through. But the default-to-write approach means unknown commands require write permission. Fail secure, not fail open.
The actual execution function ties it all together:

const runShellCommand = async (command: string, cwd: string) => {
  const permission = getCommandPermission(command);

  if (permission !== 'none') {
    // Command needs filesystem access — validate the working directory
    // against our permission system before running anything
    const validatedPath = await resolvePath(cwd, permission);
    const { stdout, stderr } = await execAsync(command, { cwd: validatedPath });
    return { stdout, stderr };
  } else {
    // Safe commands like 'pwd' or 'whoami' that don't touch files
    // Skip the permission check since there's nothing to protect
    const { stdout, stderr } = await execAsync(command, { cwd });
    return { stdout, stderr };
  }
}

The key insight: I’m not just checking if a command is "allowed" — I’m checking if the working directory has the right permissions for what that command wants to do. Running ls in a read-only directory? Fine. Running rm -rf * there? Blocked.

The Web UI: Because 2 AM Debugging Needs to Be Easy

Initially, I used a JSON config file you'd edit manually. That lasted exactly one late-night debugging session before I built a web UI.

app.get('/manage-permissions', (req, res) => {
  // Serve a simple HTML page
  // No React, no build process, just vanilla JS
  res.sendFile(path.join(__dirname, 'permission-manager.html'));
});

app.post('/api/permissions', async (req, res) => {
  // Update the config file
  const newPermissions = req.body;
  await fs.writeFile(configPath, JSON.stringify(newPermissions, null, 2));
  res.json({ success: true });
});

Visit http://localhost:20252, see your permissions, add new ones, remove old ones. No terminal required. Yes, you have to type paths manually (browser security prevents file pickers), but it beats editing JSON.

Default-Deny: The Only Sane Default

When the server starts for the first time:

export const getAllowedRoots = async () => {
  const filePath = path.join(getClaudeConfigDir(), 'file_system_config.json');

  try {
    const content = await fs.readFile(filePath, 'utf8');
    return JSON.parse(content);
  } catch (error: any) {
    if (error.code === 'ENOENT') {
      // No config? Start with ZERO permissions
      const defaultRoots: object[] = [];
      await fs.writeFile(filePath, JSON.stringify(defaultRoots, null, 2));
      return defaultRoots;
    }
    throw error;
  }
}

Empty array. No access. Nothing. You have to explicitly grant permissions before Claude can do anything.

This was deliberate. Most security problems come from starting open and asking users to lock down. I went the opposite direction — start locked, make users open up consciously.

Real-World Usage (With Actual Sessions)

Here's what actually happens when I use this:

Me: "Show me the structure of my signalist project"

Claude: (calls list-allowed-directories first, then directory-tree)

❌ Access denied: /Users/padmanabhadas/next-js-projects/signalist is outside allowed directories
Configure permissions at: http://localhost:20252

Right. I forgot to add permissions. Quick visit to localhost:20252, add the path with read access.

Me: "Try again"

Claude:

signalist/
├── src/
│   ├── app/
│   ├── components/
│   └── utils/
├── public/
├── package.json
└── README.md

Files: 47, Directories: 12

Me: "Update the README to include the logo from public folder"

Claude:

❌ Access denied: Insufficient permissions for write operation
Configure permissions at: http://localhost:20252

This is the system working as intended. I gave read-only access, so writes fail. If I trust Claude enough, I'll upgrade to write. If not, I'll ask for the changes and apply them myself.

The 20 Tools (But Only 5 Matter)

I built 20 tools total, but honestly, 80% of my usage is just these five:

read-file — Read any file with optional line ranges
modify-file — Surgical edits (insert/replace/delete specific lines)
directory-tree — Visualize project structure
search-file-directory — Find files by name
run-shell-command — When you really need it

The Office document tools (Excel, PowerPoint, Word) seemed cool when I built them. I've used them maybe twice. The core file operations are what matter.

Things That Went Wrong (And What I Learned)

The Path Precedence Bug: For three weeks, I couldn't figure out why granular permissions didn't work. Turns out I was taking the first matching path, not the most specific. One sort() call fixed it.

The Symlink Escape: A friend tried to break out using symlinks. Worked perfectly until I added fs.realpath() checks everywhere. Now symlinks are resolved before permission checking.

The "Clean Downloads" Incident: I asked Claude to "organize my Downloads folder" without being specific. It created 47 subfolders based on file extensions. Technically correct, absolutely not what I wanted. Now I'm very specific with instructions.

Shell Command Parsing: My regex-based command parser thought echo "rm -rf /" was trying to delete everything. It's not. Command parsing is hard. I still don't trust it 100%.

If I Started Over

Time-based permissions: "Give write access for 30 minutes" would be useful for quick tasks.

Operation logs: Not just permission checks, but what Claude actually did. An audit trail.

Workspace templates: Preconfigured permission sets for common scenarios (read-only code review, full access to test directory, etc.)

But honestly? The current system works. It's been three months, and I haven't lost any data. That's a win.

Getting Started

If you want to try this yourself:

Grab the executable from GitHub releases (macOS and Windows available)

Run it once to register with Claude Desktop:

chmod +x file-system  # macOS only
./file-system

Open http://localhost:20252 and add some paths
Launch Claude Desktop and try it: "use file system tools to show my allowed directories"

The server stays running as long as Claude Desktop is open. You don't need to start it manually each time.

The Bottom Line

Most MCP servers are built by developers, for developers, with developer assumptions about security ("I know what I'm doing"). But when you're giving an AI file system access, you need to design for the worst case — a misunderstood command at 3 AM when you're half asleep.

The permission system isn't sexy. It doesn't demo well. But it's the difference between a toy you play with and a tool you actually trust with your real work.

If you're building anything that touches the file system — MCP server or not — start with permissions. Make them granular. Make them explicit. Make them annoying if you have to. Your future self will thank you when Claude doesn't accidentally reorganize your entire home directory.

Want to try it yourself? The code's on GitHub (FS-MCP). Just remember – when you're giving an AI file system access, paranoia isn't a bug, it's a feature.

Executables:

Questions? Find me on GitHub or LinkedIn. I'm always curious how others approach the permission problem.

Building Real-Time Voice Learning with VAPI: WebRTC + AI Tutors

PADMANABHA DAS — Mon, 01 Dec 2025 06:30:37 +0000

Text-based learning apps are passive. I wanted students to have real conversations with AI tutors—natural voice interactions where they could ask questions, get explanations, and learn through dialogue. So I built IntelliCourse with VAPI's voice AI SDK, creating a platform where students talk to personalized AI companions about Math, Science, Coding, and more. Here's how I implemented real-time voice sessions, including the WebRTC connection flow and transcript management that makes it feel like talking to a real tutor.

The Problem: Why Voice Learning?

Traditional learning platforms rely on text chat or pre-recorded videos. But learning is conversational:

Students need to ask follow-up questions in real-time
Complex concepts are easier to explain through dialogue
Voice is faster than typing (150 words/min vs 40 words/min)
Natural conversation keeps attention better than reading

I needed a solution that could:

Handle real-time bidirectional audio
Transcribe speech to text (Speech-to-Text)
Process with GPT-4 for intelligent responses
Track session duration and save transcripts

The Tech Stack: VAPI + WebRTC

VAPI (Voice AI Platform Interface) handles the entire voice pipeline:

User speaks â†' Deepgram (STT) â†' GPT-4 (AI) â†' 11Labs (TTS) â†' User hears

Key components:

Transcriber: Deepgram Nova-3 (latest high-accuracy model)
AI Model: OpenAI GPT-4 (conversational intelligence)
Voice: 11Labs (4 voices: male/female Ã— formal/casual)
Connection: WebRTC (low-latency audio streaming)

Implementation: Voice Assistant Configuration

Step 1: Define Voice Personalities

I created 4 voice options based on user preferences:

// constants/index.ts
const voices = {
  male: {
    casual: '2BJW5coyhAzSr8STdHbE',  // 11Labs voice ID
    formal: 'c6SfcYrb2t09NHXiT80T'
  },
  female: {
    casual: 'ZIlrSGI4jZqobxRKprJz',
    formal: 'sarah'                  // 11Labs default
  }
};

Step 2: Configure VAPI Assistant

// lib/utils.ts
const configureAssistant = (companionName: string, subject: string, topic: string, voice: 'male' | 'female', style: 'formal' | 'casual') => {
  const voiceId = voices[voice][style];

  return {
    name: companionName,
    firstMessage: `Hello, let's start the session. Today we'll be talking about ${topic}.`,

    // Speech-to-Text Configuration
    transcriber: {
      provider: 'deepgram',
      model: 'nova-3',           // Latest Deepgram model (95%+ accuracy)
      language: 'en',
    },

    // Text-to-Speech Configuration
    voice: {
      provider: '11labs',
      voiceId: voiceId,
      stability: 0.4,            // Voice consistency (0-1)
      similarityBoost: 0.8,      // Match original voice (0-1)
      speed: 1,                  // Normal playback speed
      style: 0.5,                // Emotional range (0-1)
      useSpeakerBoost: true,     // Enhance clarity
    },

    // Conversational AI Configuration
    model: {
      provider: 'openai',
      model: 'gpt-4',
      messages: [{
        role: 'system',
        content: `You are a highly knowledgeable tutor teaching ${subject}.

        Your goal: Teach the student about ${topic}.

        Guidelines:
        - Stick to the topic and subject
        - Check student understanding regularly
        - Break down complex concepts step-by-step
        - Keep responses short (voice conversation)
        - Use ${style} style (${style === 'formal' ? 'professional' : 'friendly'})
        - No special characters (voice only)`
      }]
    }
  };
};

The Session Lifecycle

States

enum CallStatus {
  INACTIVE,    // Not started
  CONNECTING,  // Establishing WebRTC
  ACTIVE,      // Live conversation
  FINISHED,    // Session ended
}

Component State Management

// components/CompanionComponent.tsx
const [callStatus, setCallStatus] = useState<CallStatus>(CallStatus.INACTIVE);
const [isSpeaking, setIsSpeaking] = useState(false);      // AI speaking?
const [isMuted, setIsMuted] = useState(false);            // Mic muted?
const [messages, setMessages] = useState<Message[]>([]);  // Transcript
const [sessionDuration, setSessionDuration] = useState(0); // Seconds

Starting a Session: WebRTC Connection Flow

const handleCall = useCallback(() => {
  // 1. Set connecting state
  setCallStatus(CallStatus.CONNECTING);
  showLoading('Connecting to your AI companion...');

  // 2. Configure assistant
  const assistantConfig = configureAssistant(
    companion.name,
    companion.subject,
    companion.topic,
    companion.voice,
    companion.style,
  );

  // 3. Start VAPI session
  vapi.start(assistantConfig, {
    variableValues: {
      subject: companion.subject,
      topic: companion.topic,
      style: companion.style,
    },
  });
}, [companion]);

Event Handling: Real-Time Updates

Connection Events

useEffect(() => {
  // Session started
  vapi.on('call-start', () => {
    setCallStatus(CallStatus.ACTIVE);
    startTimer();
    closeModal();
  });

  // Session ended
  vapi.on('call-end', async () => {
    setCallStatus(CallStatus.FINISHED);
    await stopTimer();
    await saveSession();
  });

  // Error handling
  vapi.on('error', (error) => {
    console.error('VAPI Error:', error);
    setCallStatus(CallStatus.INACTIVE);
    alert('Connection failed. Please try again.');
  });

  return () => {
    vapi.removeAllListeners();
  };
}, []);

Transcription Events

// Real-time transcript updates
vapi.on('message', (message: Message) => {
  // Only process final transcripts (not interim)
  if (message.type === 'transcript' && message.transcriptType === 'final') {
    setMessages(prev => [{
      role: message.role,        // 'user' or 'assistant'
      content: message.transcript,
      timestamp: new Date()
    }, ...prev]);
  }
});

Speech Detection (Visual Feedback)

// AI starts speaking
vapi.on('speech-start', () => {
  setIsSpeaking(true);
  lottieRef.current?.play();  // Start soundwave animation
});

// AI stops speaking
vapi.on('speech-end', () => {
  setIsSpeaking(false);
  lottieRef.current?.stop();   // Stop soundwave animation
});

Session Timer Implementation

const startTimer = useCallback(() => {
  const startTime = new Date();
  setSessionStartTime(startTime);

  // Update every second
  const interval = setInterval(() => {
    setSessionDuration(prev => prev + 1);
  }, 1000);

  setTimerInterval(interval);
}, []);

const stopTimer = useCallback(async () => {
  if (timerInterval) {
    clearInterval(timerInterval);
  }

  const durationMinutes = Math.max(1, Math.round(sessionDuration / 60)
  );

  // Save to database
  await saveSessionData(companion.id, durationMinutes);
}, [sessionDuration, timerInterval]);

Microphone Control

const toggleMicrophone = useCallback(() => {
  if (callStatus !== CallStatus.ACTIVE) return;

  const newMutedState = !isMuted;
  vapi.setMuted(newMutedState);
  setIsMuted(newMutedState);
}, [callStatus, isMuted]);

Ending a Session: Cleanup & Data Persistence

const handleDisconnect = useCallback(async () => {
  // 1. Stop VAPI
  vapi.stop();

  // 2. Stop timer
  await stopTimer();

  // 3. Format transcript
  const transcriptText = messages
    .reverse()  // Chronological order
    .map(msg => {
      const speaker = msg.role === 'assistant' 
        ? companion.name.split(' ')[0]  // "Neura" from "Neura the Explorer"
        : userName;
      return `${speaker}: ${msg.content}`;
    })
    .join('\n');

  // 4. Save to Supabase
  const sessionId = await addToSessionHistory(companion.id);
  await updateSessionDuration(companion.id, durationMinutes);
  await saveSessionTranscript(sessionId, transcriptText);

  // 5. Show success
  showSuccess('Lesson Completed! Great job!');
}, [messages, companion, userName]);

Database Schema

CREATE TABLE session_history (
  id UUID PRIMARY KEY,
  companion_id UUID REFERENCES companions(id),
  user_id TEXT NOT NULL,
  duration_minutes INTEGER DEFAULT 0,
  transcript TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  completed_at TIMESTAMPTZ,
);

Transcript format:

John: What are neural networks?
Neura: Neural networks are computational models inspired by the brain...
John: How do they learn?
Neura: They learn through backpropagation...

UI Implementation: Live Session View

return (
  <div className="session-container">
    {/* AI Avatar with Soundwave */}
    <div className="ai-avatar">
      {callStatus === CallStatus.ACTIVE && isSpeaking ? (
        <Lottie animationData={soundwaves} autoplay loop />
      ) : (
        <Image src={subjectIcon} alt={companion.subject} />
      )}
    </div>

    {/* Session Timer */}
    <div className="timer">
      <p>Session Duration</p>
      <p className="text-2xl">{formatTime(sessionDuration)}</p>
      <div className={callStatus === CallStatus.ACTIVE ? 'pulse-indicator' : ''} />
    </div>

    {/* Microphone Toggle */}
    <button 
      onClick={toggleMicrophone}
      disabled={callStatus !== CallStatus.ACTIVE}
    >
      <Image src={isMuted ? micOff : micOn} />
    </button>

    {/* Start/End Button */}
    <button onClick={callStatus === CallStatus.ACTIVE ? handleDisconnect : handleCall}>
      {callStatus === CallStatus.ACTIVE ? 'End Session' : 'Start Session'}
    </button>

    {/* Live Transcript */}
    <div className="transcript">
      {messages.map((msg, i) => (
        <p key={i} className={msg.role === 'user' ? 'text-primary' : ''}>
          {msg.role === 'assistant' ? companion.name : userName}: {msg.content}
        </p>
      ))}
    </div>
  </div>
);

Results After 2 Months

User metrics:

Average session: 18 minutes
Completion rate: 82% (users finish sessions they start)

Technical performance:

WebRTC connection: < 2 seconds
Transcription latency: ~200ms
AI response time: 800ms average
Voice synthesis: ~400ms

User feedback:

"Feels like talking to a real tutor"
"Better than reading textbooks"
"I can ask clarifying questions immediately"

What I'd Do Differently

1. Add session pause/resume

Current: Session runs continuously
Better: Pause for breaks, resume later

2. Implement conversation branching

Track topic coverage
Suggest related concepts
Create learning paths

3. Add real-time sentiment detection

Detect confusion in voice tone
Adjust explanation complexity
Offer alternative explanations

Tech Stack

Frontend: Next.js 15 + React 19 + TypeScript
Voice AI: VAPI SDK v2.3.0
Database: Supabase (PostgreSQL)
Auth: Clerk
STT: Deepgram Nova-3
TTS: 11Labs
AI: OpenAI GPT-4

GitHub: https://github.com/chayan-1906/IntelliCourse-Next.js

Voice AI isn't just for chatbots. With VAPI handling the WebRTC complexity, you can build conversational learning experiences in a weekend. The key is good system prompts and proper event handling.

Questions about VAPI or voice AI implementation? Drop them below.

Building a Strike System: How I Prevent AI Feature Abuse in My News App

PADMANABHA DAS — Thu, 27 Nov 2025 05:44:27 +0000

AI features are expensive. When I launched PulsePress with 11 Gemini-powered features, I had a daily quota of 900 requests. Within 48 hours, users discovered they could spam "Generate social media captions" on random URLs—burning through my quota by 2 PM. I needed abuse prevention without killing the user experience. Here's the strike system I built, including the auto-reset mechanism that keeps false positives from becoming permanent bans.

The Problem: AI Feature Abuse

My AI features cost money per request. Google Gemini charges per token, and I had three abuse vectors:

Non-news content: Users submitting promotional sites, e-commerce pages, random blogs
Spam requests: Hammering "Generate Summary" 50 times on the same article
Quota farming: Bots testing API endpoints

The goal: Block bad actors without punishing legitimate users who make honest mistakes.

The Three-Strike Architecture

I built a progressive penalty system:

Strikes 1-2: Warning only (logged, no blocking)

Strike 3: 15-minute cooldown

Strike 4: 20-minute cooldown

Strike 5: 30-minute cooldown

Strike 6+: 2-day block

Key insight: Cooldowns escalate, but never permanently ban. Even chronic abusers get reset after 48 hours.

Implementation: Database Schema

I track strikes directly in the User model:

// UserSchema.ts
{
  email: string,
  newsClassificationStrikes: [
    {
      violationType: 'search_query' | 'article_summary' | 'ai_enhancement',
      strikeTimestamp: Date,
      strikeCount: number,
      blockUntil?: Date,
      blockType?: 'cooldown' | 'long_block',
    }
  ],
  createdAt: Date,
}

Why embed in the User model? Fast lookups—no joins needed on every AI request.

Step 1: Content Classification

Before processing any AI request, I classify the content:

// NewsClassificationService.ts
const classifyContent = async (text: string): Promise<Classification> => {
  const prompt = `
    Analyze this content and determine if it's news/journalism.

    Content: ${text}

    Return JSON:
    {
      "classification": "news" | "non_news",
      "confidence": 0.0-1.0,
      "reason": "brief explanation",
    }

    Non-news includes: ads, e-commerce, personal blogs, promotional content.
  `;

  const result = await callGeminiWithFallback(AI_MODELS, prompt);
  return JSON.parse(result);
};

Example classifications:

// News
{
  "classification": "news",
  "confidence": 0.95,
  "reason": "Breaking news about policy change",
}

// Non-news
{
  "classification": "non_news",
  "confidence": 0.87,
  "reason": "E-commerce product page for shoes",
}

Step 2: Strike Application

If classification returns non_news, apply a strike:

// StrikeService.ts
const applyStrike = async (userId: string, violationType: ViolationType): Promise<StrikeResult> => {
  const user = await User.findOne({ userExternalId: userId });

  if (!user) throw new Error('User not found');

  // Get existing strikes
  const strikes = user.newsClassificationStrikes || [];
  const latestStrike = strikes[strikes.length - 1];

  // Calculate new strike count
  let newStrikeCount = latestStrike ? latestStrike.strikeCount + 1 : 1;

  // Determine penalty
  const penalty = calculatePenalty(newStrikeCount);

  // Create strike record
  const newStrike = {
    violationType,
    strikeTimestamp: new Date(),
    strikeCount: newStrikeCount,
    blockUntil: penalty.blockUntil,
    blockType: penalty.blockType,
  };

  // Update user
  await User.updateOne(
    { userExternalId: userId },
    { $push: { newsClassificationStrikes: newStrike } },
  );

  // Log violation
  await NonNewsViolationLog.create({
    userExternalId: userId,
    email: user.email,
    violationType,
    content: text.substring(0, 2000),  // Truncate for storage
    violatedAt: new Date(),
  });

  return {
    strikeCount: newStrikeCount,
    blockType: penalty.blockType,
    blockUntil: penalty.blockUntil,
    message: penalty.message,
  };
};

Step 3: Penalty Calculation

// strikeHelpers.ts
const calculatePenalty = (strikeCount: number): Penalty => {
  if (strikeCount <= 2) {
    return {
      blockType: null,
      blockUntil: null,
      message: 'Warning: Detected non-news content',
    };
  }

  if (strikeCount >= 6) {
    const blockUntil = new Date();
    blockUntil.setDate(blockUntil.getDate() + 2);  // 2 days

    return {
      blockType: 'long_block',
      blockUntil,
      message: 'Account blocked for 2 days due to repeated violations',
    };
  }

  // Strikes 3-5: Escalating cooldowns
  const cooldownMinutes = 15 + ((strikeCount - 3) * 5);  // 15, 20, 25, 30 min
  const blockUntil = new Date();
  blockUntil.setMinutes(blockUntil.getMinutes() + cooldownMinutes);

  return {
    blockType: 'cooldown',
    blockUntil,
    message: `Cooldown active for ${cooldownMinutes} minutes`,
  };
};

Step 4: Enforcement

Check strike status before every AI request:

// AIController.ts
router.post('/summarize', authenticateUser, async (req, res) => {
  const { url } = req.body;
  const userId = req.user.userExternalId;

  // 1. Check if user is blocked
  const user = await User.findOne({ userExternalId: userId });
  const latestStrike = user.newsClassificationStrikes.slice(-1)[0];

  if (latestStrike?.blockUntil && latestStrike.blockUntil > new Date()) {
    return res.status(403).json({
      success: false,
      message: `Account blocked until ${latestStrike.blockUntil}`,
      strikeCount: latestStrike.strikeCount,
      blockType: latestStrike.blockType,
    });
  }

  // 2. Classify content
  const content = await scrapeArticle(url);
  const classification = await classifyContent(content.text);

  // 3. Apply strike if non-news
  if (classification.classification === 'non_news') {
    const strikeResult = await applyStrike(userId, 'article_summary');

    return res.status(400).json({
      success: false,
      message: 'Non-news content detected',
      ...strikeResult,
    });
  }

  // 4. Process legitimate request
  const summary = await SummarizationService.summarize(url);
  return res.json({ success: true, data: summary });
});

Step 5: Auto-Reset (The Secret Sauce)

Strikes auto-reset after 48 hours. I use a cron job:

// server.ts
import cron from 'node-cron';

// Run every 15 minutes
cron.schedule('*/15 * * * *', async () => {
  const cutoffTime = new Date();
  cutoffTime.setHours(cutoffTime.getHours() - 48);

  // Find users with strikes older than 48 hours
  const users = await User.find({
    'newsClassificationStrikes.strikeTimestamp': { $lt: cutoffTime }
  });

  for (const user of users) {
    const oldestStrike = user.newsClassificationStrikes[0];
    const timeSinceStrike = Date.now() - oldestStrike.strikeTimestamp.getTime();

    if (timeSinceStrike >= 48 * 60 * 60 * 1000) {
      // Reset strikes
      await User.updateOne(
        { _id: user._id },
        { $set: { newsClassificationStrikes: [] } },
      );

      console.log(`Reset strikes for user ${user.email}`);
    }
  }
});

Why 48 hours? Long enough to deter abuse, short enough to forgive honest mistakes.

User Experience: Strike Status Endpoint

Users can check their status:

// GET /api/v1/strikes/status
{
  "success": true,
  "data": {
    "strikeCount": 2,
    "isBlocked": false,
    "blockType": null,
    "blockUntil": null,
    "nextStrikeConsequence": "15-minute cooldown",
    "resetIn": "36 hours",
  }
}

Edge Cases Handled

1. Rapid-fire requests

Rate limiter (30 requests per 5 minutes)
Separate from the strike system

2. Shared accounts

Strikes tied to user ID, not IP
Each user has an independent strike count

What I'd Do Differently

1. Add strike appeal mechanism

In-app button to dispute strikes
Auto-review with different AI models

2. Tiered quotas

Free users: Strict strike system
Paid users: More lenient (higher strike threshold)

3. ML-based pattern detection

Flag users with suspicious request patterns
Block before they burn quota

Tech Stack

Backend: Node.js + Express + TypeScript
Database: MongoDB (User, NonNewsViolationLog collections)
AI: Google Gemini (content classification)
Cron: node-cron (auto-reset)
Auth: JWT (Clerk integration)

GitHub: https://github.com/chayan-1906/PulsePress-Node.js

Abuse prevention doesn't require complex ML. A three-strike system with escalating penalties and auto-reset solves 95% of cases.

Questions? Drop them below. I'm happy to discuss strike system design or share more implementation details.

How I Integrated Google Gemini for 11 AI Features in My News App

PADMANABHA DAS — Mon, 24 Nov 2025 19:17:28 +0000

How I Integrated Google Gemini for 11 AI Features in My News App

News apps today are just RSS readers with a search bar. I wanted something smarter—AI that could summarize articles, analyze sentiment, generate social media captions, and answer questions about the content. So I built PulsePress with Google Gemini & HuggingFace, creating 11 AI features that process 70+ news sources. Here's exactly how I did it, including the quota management and fallback strategy that keeps it running at scale.

The Problem: Why News Apps Need Intelligence

Traditional news aggregators give you articles. That's it. But what if you're scrolling through 50 headlines about AI regulation? You need:

Context: What's the sentiment? Is this good or bad news?
Speed: 5-minute summary, not 15-minute reads
Actionability: Social media captions, key takeaways, Q&A
Multilingual support: Not everyone reads in English

I built PulsePress to solve this. The backend aggregates from NewsAPI, The Guardian, NY Times, and 70+ RSS feeds. Then Google Gemini enhances each article with AI.

The 11 AI Features

Here's what Gemini powers in PulsePress:

News Classification - Filters spam/promotional content
Summarization - 3 styles (concise/standard/detailed) in 26 languages
Tag Generation - 5-10 relevant keywords per article
Sentiment Analysis - Positive/negative/neutral with confidence scores
Key Points Extraction - 3-7 bullet-point takeaways
Complexity Meter - Reading difficulty (easy/medium/hard)
Question Generation - Auto-creates comprehension questions
Question Answering - Users ask, AI answers from article context
Geographic Extraction - Pulls locations mentioned
Social Media Captions - Platform-specific (Twitter/Instagram/LinkedIn)
News Insights - Deep analysis: themes, impact, stakeholders

All 11 use the same Gemini API with different prompts.

Technical Architecture: The Model Hierarchy

The Challenge: Google Gemini has daily quotas. I needed a fallback system that tries newer models first, then cascades to older ones.

Here's my model hierarchy:

const AI_MODELS = [
  'gemini-2.5-flash-preview-09-2025',      // Newest, try first
  'gemini-2.5-flash-lite-preview-09-2025',
  'gemini-2.5-flash-lite',
  'gemini-2.5-flash',
  'gemini-2.0-flash',
  'gemini-2.0-flash-lite',
  'gemini-1.5-flash',                      // Fallback
];

Why this matters: If Model 1 hits quota, the system automatically tries Model 2. No failed requests.

Quota Tracking

I store daily quotas in MongoDB:

// ApiQuotaSchema
{
  service: 'gemini_summarization',
  date: '2025-01-25',
  requestCount: 45,
  lastResetAt: '2025-01-25T00:00:00Z',
}

Before each AI call:

const checkQuota = async (service: string) => {
  const today = new Date().toISOString().split('T')[0];

  const quota = await ApiQuota.findOne({ service, date: today });

  if (quota && quota.requestCount >= DAILY_LIMIT) {
    throw new Error('Quota exceeded');
  }

  // Increment count
  await ApiQuota.updateOne(
    { service, date: today },
    { $inc: { requestCount: 1 } },
    { upsert: true },
  );
};

Daily limits:

Total Gemini requests: 900/day
Per-model: 100-900 depending on tier

Implementation: Sentiment Analysis Example

Let me show you one feature end-to-end: Sentiment Analysis.

1. The API Endpoint

// AIController.ts
router.post('/sentiment', authenticateUser, async (req, res) => {
  const { url } = req.body;

  // Check quota first
  await QuotaService.checkQuota('gemini_sentiment');

  // Generate sentiment
  const result = await SentimentAnalysisService.analyze(url);

  return res.json({
    success: true,
    data: result,
  });
});

2. The Service Layer

// SentimentAnalysisService.ts
const analyze = async (url: string) => {
  // Check cache first (30-day TTL)
  const cached = await ArticleEnhancement.findOne({ 
    articleId: generateArticleId(url) 
  });

  if (cached?.sentiment) return cached.sentiment;

  // Scrape article
  const content = await scrapeArticle(url);

  // Call Gemini with fallback
  const sentiment = await callGeminiWithFallback(
    AI_MODELS,
    buildSentimentPrompt(content),
  );

  // Cache result
  await cacheEnhancement(url, { sentiment });

  return sentiment;
};

3. The Gemini Prompt

const buildSentimentPrompt = (content: string) => `
Analyze sentiment of this article:

Title: ${content.title}
Content: ${content.text}

Return JSON:
{
  "sentiment": "positive|negative|neutral",
  "confidence": 0.0-1.0,
}
`;

4. The Fallback Strategy

const callGeminiWithFallback = async (models: string[], prompt: string) => {
  for (const model of models) {
    try {
      const result = await gemini.generateContent({
        model,
        prompt,
        generationConfig: {
          temperature: 0.3,
          maxOutputTokens: 500,
        }
      });

      return JSON.parse(result.response.text());

    } catch (error) {
      if (error.message.includes('quota')) {
        continue; // Try next model
      }
      throw error;
    }
  }

  throw new Error('All models exhausted');
};

5. Response Formatting

// sentimentHelpers.ts
const formatSentiment = (raw: GeminiResponse) => ({
  type: raw.sentiment,
  confidence: raw.confidence,
  emoji: raw.sentiment === 'positive' ? '😊' : 
         raw.sentiment === 'negative' ? '😔' : '😐',
  color: raw.sentiment === 'positive' ? '#4ade80' :
         raw.sentiment === 'negative' ? '#ef4444' : '#94a3b8',
});

Final response:

{
  "success": true,
  "data": {
    "sentiment": "positive",
    "confidence": 0.87,
    "emoji": "😊",
    "color": "#4ade80",
  }
}

Scaling Strategy: Progressive/Background Enhancement

The key insight: Don't make users wait for AI.

When a user searches for news:

// Step 1: Return articles immediately
const articles = await fetchFromAPIs(query);
res.json({ 
  articles,
  processingStatus: 'pending',
});

// Step 2: Enhance in background (non-blocking)
enhanceArticlesAsync(articles);

Then users poll for enhancements:

GET /api/v1/news/enhancement-status?articleIds=hash1,hash2

Response:
{
  "hash1": { "status": "completed", "sentiment": {...} },
  "hash2": { "status": "pending" },
}

This keeps the UI fast while AI works asynchronously.

Results & Lessons Learned

What worked:

30-day caching reduced API costs by 60%
Model fallback achieved 99.8% uptime
Background enhancement cut perceived latency from 8s to 0.3s

What I'd do differently:

Start with cheaper models (1.5 Flash) for non-critical features
Batch requests for tag generation across multiple articles
Add Redis for sub-second cache hits

Tech stack:

Backend: Node.js + TypeScript + Express
Database: MongoDB (10 collections)
AI: Google Gemini (7 models)
Caching: 30-day TTL on enhancements

GitHub: https://github.com/chayan-1906/PulsePress-Node.js

Building AI features doesn't require a PhD. Start with one feature (sentiment analysis took me 2 hours), add caching, and implement fallbacks. The rest is just repeating the pattern.

Questions? Drop them below—PulsePress is complete and open source. Check out the full implementation on GitHub.