Forem: Sabahattin Kalkan

I built a permission-first CLAUDE.md + agent stack for Claude Code (free, MIT)

Sabahattin Kalkan — Thu, 14 May 2026 21:01:45 +0000

I've been using Claude Code daily for months. And I kept hitting the same wall:

The agent would just start doing things. No plan. No approval. Just... acting.

It deleted files I didn't want deleted. It refactored things I didn't ask it to refactor. It made "helpful" assumptions that broke my architecture.

So I built Full Stack HQ — a configuration kit that enforces a permission-first workflow. Here's what I learned.

The core problem with AI coding agents

Most people configure their AI agent once (or never) and just... let it go. The result is an agent that:

Makes assumptions about what you want
Takes irreversible actions without asking
Mixes planning and execution in the same step
Has no consistent code style or architectural awareness

The agent is powerful but unpredictable. That's the worst combination in software development.

The solution: permission-first workflow

Nothing happens without your explicit approval. The agent plans, shows you what it intends to do, and waits.

You:    "Add user authentication with JWT"

Agent:  Here's my plan:
        Phase 1: Create auth module + JWT strategy
        Phase 2: Add guards to protected routes  
        Phase 3: Implement refresh token rotation

        [APPROVAL NEEDED] Should I proceed with Phase 1?

You:    PLAN APPROVED

Agent:  [implements Phase 1 only, then stops and reports]

The only valid approval keywords:

PLAN APPROVED
IMPLEMENTATION APPROVED
PROCEED
DO IT

Anything else — the agent waits. No exceptions.

What's inside Full Stack HQ

Component	Count	Description
`CLAUDE.md`	1	Global rules for Claude Code
`GEMINI.md`	1	Global rules for Google Antigravity IDE
Agents	10	Specialist AI personas
Skills	28	Domain-specific knowledge modules
Workflows	10	Slash command procedures

10 Specialist Agents

Instead of one generic agent trying to do everything, you get domain experts:

Agent	What it handles
`frontend-specialist`	React, Next.js, Tailwind
`backend-specialist`	NestJS, Node.js, APIs
`database-specialist`	Prisma, PostgreSQL, migrations
`architect`	System design, trade-offs, ADRs
`code-reviewer`	Quality, patterns, best practices
`test-engineer`	Vitest, Jest, Playwright
`security-auditor`	Auth, OWASP, input validation
`performance-optimizer`	Bundle, queries, rendering
`devops-engineer`	Docker, CI/CD
`documentation-writer`	READMEs, technical writing

Calling them is simple:

Use the database-specialist to design a user schema with soft deletes.

28 Skills

Deep knowledge modules for the tools you actually use:

Frontend: nextjs-app-router, react-best-practices, ui-ux-pro-max, frontend-design
Backend: nestjs-patterns, prisma-workflow, software-architecture
Testing: test-driven-development, systematic-debugging, webapp-testing
Meta: brainstorming, prompt-engineering, skill-creator

10 Workflows (Slash Commands)

/plan       → phased breakdown with approval checkpoints
/brainstorm → explore architecture options
/debug      → systematic root-cause analysis
/create     → implement an approved plan
/enhance    → improve existing code quality
/test       → generate or fix tests
/orchestrate → coordinate multiple agents

Install in 30 seconds

Mac/Linux:

curl -fsSL https://raw.githubusercontent.com/sabahattink/antigravity-fullstack-hq/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/sabahattink/antigravity-fullstack-hq/main/install.ps1 | iex

Options:

./install.sh --only-claude        # Claude Code only
./install.sh --only-antigravity   # Antigravity only
./install.sh --force              # Overwrite existing configs

The script detects which IDEs you have installed and configures them automatically.

What gets installed where

~/.claude/
├── CLAUDE.md          ← global rules (Claude Code)
├── agents/            ← 10 specialist agents
└── skills/            ← 28 skill modules

~/.gemini/
├── GEMINI.md          ← global rules (Antigravity)
└── antigravity/
    ├── agents/
    ├── skills/
    └── workflows/

The CLAUDE.md philosophy

The rules file enforces several things I found critical in practice:

1. Separation of planning and execution

The agent never does both in the same step. First it plans, you approve, then it executes. This alone eliminates 80% of unwanted surprises.

2. Role-based reasoning

Before acting, the agent asks: "Who is the right specialist for this?" A database schema question goes to the database specialist, not the frontend agent pretending to know Prisma.

3. Explicit code style

No semicolons. Single quotes. 2-space indentation. Arrow functions. Named exports. These aren't suggestions — they're enforced rules the agent follows on every file, every time.

4. Security checklist

Before every commit: no hardcoded secrets, all inputs validated, no unbounded queries, rate limiting on public endpoints. The agent checks these automatically.

Why it works

The mental model I was missing: AI agents should behave like senior engineers, not interns with root access.

Senior engineers don't start typing when you describe a problem. They think, propose a plan, get sign-off, then execute — one reversible step at a time.

Full Stack HQ enforces this discipline by default.

Repo

⭐ github.com/sabahattink/antigravity-fullstack-hq

MIT license. Open to PRs — especially new agents and skills.

What does your current CLAUDE.md look like? I'd love to see what rules others have found valuable.

Building MailTest: An Open Source Email Deliverability Debugger

Sabahattin Kalkan — Mon, 13 Apr 2026 03:53:52 +0000

Building MailTest: An Open Source Email Deliverability Debugger

The Problem

[Story about client's 50K emails going to spam]

Why Existing Tools Fall Short

Expensive ($100+/month)
No explanations
SaaS lock-in

What I Built

[Demo GIF/screenshots]

Technical Architecture

Backend

NestJS + Fastify (why not Express)
BullMQ for async jobs
RS256 JWT (why not HS256)

Frontend

Next.js 15 App Router
Radix UI primitives
Real-time updates with SSE

Infrastructure

Docker Compose
PostgreSQL 16
Redis 7
Paddle billing

Interesting Challenges

IMAP Polling: How to catch emails reliably
Scoring Algorithm: Weighted checks (SPF 15%, DKIM 20%, etc.)
PDF Generation: Server-side with Puppeteer

Code Snippets

[Show interesting parts]

What's Next

More integrations
Auto-fix features
API monetization

Try It

https://mailtest.scuton.com

Discussion

What features would you want in a deliverability tool?

I built a CLI that diagnoses your code before you ship

Sabahattin Kalkan — Sat, 28 Mar 2026 10:45:57 +0000

I built a CLI that diagnoses your code before you ship
Every NestJS project I've worked on had the same problems:

POST endpoints without auth guards
Hardcoded API keys in source code
.env not in .gitignore
Zero tests
No Swagger documentation

I was tired of catching these manually in code reviews. So I built codediag.
What it does
bashnpx codediag scan .
One command. It auto-detects your stack and runs 5 analyzers:
codediag — Diagnostic Report

Project: my-nestjs-app
Stack: nestjs + typescript + prisma
Score: B+ (87/100)

API Health ███████████████░░░░░ 78
Security ██████████████████░░ 92
Dependencies ██████████████████░░ 91
Testing ████████████████░░░░ 82
Structure █████████████████░░░ 88
The 5 Analyzers

API Health (NestJS) This is the differentiator. codediag uses ts-morph to do real AST analysis of your NestJS decorators — not regex pattern matching. It discovers every endpoint from @get(), @post(), @Put(), @Delete(), @Patch() decorators and checks:

Auth guards: Does this endpoint have @UseGuards()? Especially important for mutating endpoints.
DTO validation: Is the @body() parameter typed with a DTO class?
Swagger docs: Are @ApiOperation() and @ApiResponse() present?
Return types: Is there an explicit return type annotation?

Security The stuff that ends up on HackerNews for the wrong reasons:

Hardcoded secrets (API keys, Stripe keys, AWS keys, GitHub tokens)
.env in .gitignore
Helmet middleware for HTTP security headers
CORS wildcard (origin: '*') detection
Rate limiting package installed
Password hashing library present

Dependencies Your node_modules is a supply chain. codediag treats it like one:

npm audit vulnerabilities
Lock file existence
Deprecated packages
Engine specification
Essential scripts

Testing

Test file existence and count
Framework detection (Jest, Vitest, Mocha, Ava)
Test-to-source file ratio
E2E test directory
Coverage threshold configuration

Structure

README quality
Linter configuration (ESLint or Biome)
Formatter configuration (Prettier)
TypeScript strict mode
NestJS module organization
.env.example presence

Scoring
Each analyzer scores 0-100. The total is a weighted average:
AnalyzerWeightAPI Health25%Security30%Dependencies20%Testing15%Structure10%
Security gets the highest weight because shipping vulnerable code is the worst bug.
CI/CD
One line in your GitHub Actions:
yaml- run: npx codediag scan . --ci --threshold 80
Exits with code 1 if the score drops below your threshold.
What's next

Next.js analyzer
Express route analyzer
Web dashboard with trend tracking
AI-powered fix suggestions
VS Code extension

Try it
bashnpx codediag scan .
Zero config. MIT licensed. 33KB bundled.

GitHub: https://github.com/scuton-technology/codediag
npm: https://www.npmjs.com/package/codediag

I'd love to hear what checks you'd want added. Drop a comment or open an issue!

Stop switching to GitHub.com for standup — I built a CLI for that

Sabahattin Kalkan — Tue, 17 Mar 2026 09:30:29 +0000

Every morning it's the same routine.

Open GitHub. Filter by author. Scroll through commits. Switch repos. Try
to remember what you did yesterday. Piece together a standup from five
different tabs.

Or worse — you're juggling three different repos, two orgs, and a
contractor's fork, and the GitHub web UI has no idea you want to see all
of it at once.

I built gpulse to fix this.

What it does

gpulse is a CLI toolkit that brings the GitHub insights you actually need
into your terminal. Six focused commands, zero browser required.

npm install -g @sabahattinkalkan/gpulse
export GITHUB_TOKEN=ghp_your_token_here

`gpulse standup`

What did you actually do since yesterday?

gpulse standup           # last 24 hours, all repos
gpulse standup -d 3      # last 3 days
gpulse standup -u alice  # another user's activity

Output:
Standup for @sabahattinkalkan
Since Mar 15, 2026 12:00 AM
Commits
a1b2c3d feat: add user authentication (org/app)
d4e5f6a fix: resolve memory leak in worker (org/api)
Pull Requests

42 Add OAuth2 support (org/app)

Reviews

41 Refactor database layer (org/api)

──────────────────────────────────────────
Summary: 2 commits, 2 PRs, 1 review

This is what I actually read out at standup. Copy, paste, done.

`gpulse health`

Repo health score (A–F). Checks README, LICENSE, CI, stale issues.

gpulse health vercel/next.js
# Score: 90/100 (A)

`gpulse review`

PR dashboard — review requests, assigned PRs, your open PRs.

gpulse review
# Review Requested (2)
#   #87 Add rate limiting middleware (org/api)

`gpulse changelog`

Auto-generate changelog from git tags using Conventional Commits.

gpulse changelog -o CHANGELOG.md

`gpulse digest`

Weekly repo digest — commits, issues, merged PRs, contributors.

gpulse digest -d 7

Why terminal?

Context switching kills flow. gpulse keeps you in the terminal where
you're already working. Also useful in SSH sessions and CI scripts.

Setup

npm install -g @sabahattinkalkan/gpulse
export GITHUB_TOKEN=ghp_...

No config files. No YAML. Just the token and go.

Try it

GitHub: https://github.com/scuton-technology/ghx
npm: npm install -g @sabahattinkalkan/gpulse

MIT licensed. What would you add to a GitHub CLI toolkit? Drop it in the comments.

I built a self-hosted LLM proxy that supports 12 providers (Claude, GPT-4o, Gemini, Ollama...)

Sabahattin Kalkan — Mon, 16 Mar 2026 10:18:50 +0000

Every time a new LLM comes out, someone on your team adds a new SDK,
a new API key in .env, and a new set of error handling logic. Repeat
for OpenAI, Anthropic, Gemini, Groq, Mistral, Ollama...

I got tired of this. So I built llm-gateway.

What it does

llm-gateway is a single Go binary that sits between your app and every
LLM provider. Your code sends one request format (OpenAI-compatible),
and the gateway routes it to the right provider based on the model name.

# One endpoint for all providers
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "hello"}]}'

# Switch provider by changing the model name — zero code changes
curl http://localhost:8080/v1/chat/completions \
  -d '{"model": "gpt-4o", "messages": [...]}'

# Local model — no API key needed
curl http://localhost:8080/v1/chat/completions \
  -d '{"model": "llama3.2", "messages": [...]}'

Model routing is automatic:

claude-* → Anthropic
gpt-*, o1, o3 → OpenAI
gemini-* → Google
llama* → Ollama or Groq
mistral-* → Mistral
grok-* → xAI
sonar-* → Perplexity
command-* → Cohere

Install in 30 seconds

docker run -p 8080:8080 -v gateway-data:/data scutontech/llm-gateway

Open http://localhost:8080/admin → set your admin password → add API
keys from the Settings page. No .env files, no YAML editing.

Admin dashboard

The gateway ships with a full admin dashboard:

Real-time stats — requests, tokens, latency, error rate, estimated cost
Provider breakdown — which providers you're actually using
Cost analytics — daily/monthly spend by model, with CSV export
Request log — last 50 requests with model, provider, tokens, cost, latency
Dark mode — because of course

Streaming support

SSE streaming works for all providers. The gateway normalizes
Anthropic's stream format to OpenAI's SSE format transparently.

curl http://localhost:8080/v1/chat/completions \
  -d '{"model": "claude-sonnet-4-20250514", "stream": true, "messages": [...]}'

Supported providers

Provider	Models
Anthropic	claude-opus-4, claude-sonnet-4, claude-haiku-4
OpenAI	gpt-4o, gpt-4o-mini, o1, o3-mini
Google	gemini-2.0-flash, gemini-1.5-pro
Groq	llama-3.3-70b, mixtral-8x7b
Mistral	mistral-large, codestral
Cohere	command-r-plus, command-r
xAI	grok-2, grok-2-mini
Perplexity	sonar-large, sonar-small
Together AI	50+ open source models
Ollama	any local model
LM Studio	any local model
vLLM	any hosted model

Why Go?

~15MB binary. Under 100ms cold start. ~20MB memory at idle.
Drop it on a $5 VPS and forget about it.

Try it

GitHub: https://github.com/scuton-technology/llm-gateway
Docker: docker pull scutontech/llm-gateway

MIT licensed. PRs welcome.

Stop writing bad commit messages — I built a free AI CLI for that

Sabahattin Kalkan — Mon, 16 Mar 2026 07:09:21 +0000

We've all done it.

git commit -m "fix"
git commit -m "wip"
git commit -m "asdfgh"
git commit -m "changes"

You're deep in flow, you just want to save progress, and writing a meaningful commit message feels like a speed bump. So you write something meaningless and move on.

The problem? Three months later, you (or your teammate) is trying to understand why a change was made. The git log is full of "fix" and "update" and tells you nothing.

The solution: let AI read the diff

I built ai-commit — a CLI that reads your staged git diff and generates 3 Conventional Commit suggestions for you to pick from.

npm install -g @scuton/ai-commit

Then just:

git add .
aic

You get something like:
? Pick a commit message:
❯ feat(auth): add JWT refresh token rotation
feat(auth): implement rotating refresh token with replay protection
chore(auth): update token lifecycle and Redis TTL strategy
✎ Write my own
✗ Cancel

Pick one, hit enter, done. The whole thing takes 3 seconds.

Free option: Ollama (no API key needed)

This is the part I'm most excited about. You can run it completely free using Ollama — a local LLM runner.

# Install Ollama and pull a model
ollama pull llama3.2

# Use ai-commit with Ollama
aic -p ollama

No API key. No cost per commit. Everything stays on your machine.

Supports Claude and GPT-4o too

If you prefer cloud models:

# Claude (best quality)
export ANTHROPIC_API_KEY=sk-ant-...
aic

# GPT-4o
export OPENAI_API_KEY=sk-...
aic -p openai

Cost is around $0.001 per commit with cloud models — basically free.

Install as a git hook

If you want it to run automatically on every git commit:

aic hook

Remove it anytime:

aic hook --remove

Other useful flags

aic --dry-run        # Preview suggestions without committing
aic --count 5        # Get 5 suggestions instead of 3
aic --lang tr        # Generate in Turkish (or any language)
aic --emoji          # Add emoji to commit type

Programmatic API

You can also use it in your own tools:

import { generateCommitMessages } from '@scuton/ai-commit';

const suggestions = await generateCommitMessages({
  provider: 'anthropic',
  count: 3,
});
console.log(suggestions[0].message);
// "feat(auth): add JWT refresh token rotation"

Try it

GitHub: https://github.com/scuton-technology/ai-commit
npm: npm install -g @scuton/ai-commit

MIT licensed, open source. PRs welcome — especially for new provider integrations.

Happy committing.