DEV Community: CloudX

How I Built a Personal AI super-app by Wrapping Codex App Server

German Burgardt — Fri, 19 Jun 2026 20:10:30 +0000

For months I used Codex like everyone else: one terminal, one session, one long output. Then I found codex app-server, the same engine exposed as JSON-RPC over stdio. It gave me a more useful idea, building my own interface for the work I actually do.

What a super-app means today

OpenAI has been pretty explicit about this: a unified AI superapp is a place where agents, tools, context, and history live together. Instead of jumping from chat to terminal, from terminal to browser, from browser to docs, everything happens in one working surface.

Theo built a version of that intuition with T3 Chat: he got tired of waiting for the perfect chat app and built his own. My version started from a similar feeling, Codex was already great, but the way I actually work needed a different interface on top.

I built my own super-app

Some context first. Over the last months I've been building a desktop app that wraps Codex. It runs several agent sessions in parallel in a grid, improves my prompts before the agent sees them, explains the agent's output in plain language, and spawns subagents with one click.

I never planned a product. I automated my own frictions, one at a time, until the wrapper became the place where I actually work. Theo did the same thing with T3 Chat: no existing AI chat fit him, so he built his own.

My point is that you can build yours too. The harness is already exposed, you just need to find the door.

The super-app starts with a small door

Most people use Codex the way it's marketed, an agent chatting in your terminal. But the same binary ships another mode:

codex app-server

That subcommand turns the CLI into a server that speaks JSON-RPC over stdio.

And you only need a little to do something real with it:

thread/start: open a session
turn/start: give it work
turn/steer: inject a message into a turn that's already running

There are more like thread/resume, turn/interrupt, thread/settings/update.

First need: subagents in ~10 lines

The feature I needed was simple: one click, and a fresh Codex instance inherits my session's context and chases a parallel idea while my main session keeps its focus.

const context = packTimeline(parent.timeline, 48_000); // newest-first
const briefing = [
  "You are a sub-agent delegated from an active parent session…",
  "The parent keeps editing in parallel; inspect current files and preserve its changes.",
  houseRules,
  context,
  newTask,
].join("\n\n");

const child = await rpc("thread/start", { cwd });
await rpc("turn/start", { threadId: child.id, input: briefing });

The important part was turning one of my frictions into a button I could press.

That's the mental shift, a super-app can be small and concrete; it gathers the operations that used to be scattered across your head, your terminal, your notes, and your prompts.

Example: one main session keeps focus while a delegated subagent inherits context and tests edge cases.

Context is everything

Spawning a second agent is easy. The hard part is giving it enough context to work without stepping on the parent session.

The briefing packs project name, working directory, current focus, and a snapshot of the parent's timeline capped at 48,000 characters, newest entries first. The child's window shows only the task you typed; the runtime receives the full context.

The briefing also tells the child something that matters a lot in practice: you are not alone in this repository. The parent session is still working next to you. Inspect the current file state, respect parallel changes, and keep your scope tight.

And the door swings both ways. When the child is created, the parent gets a coordination note with turn/steer. When the child finishes or gets stuck, it reports back explicitly: task_completed, blocked.

The timeline became the backbone

The next shift was quieter.

app-server gives you a stream of structured events: user messages, agent messages, commands, file changes, tool calls, approvals, status changes. My wrapper turns those events into a timeline and treats that timeline as working state.

The real object is boring in the best way:

const timelineItem = {
  id,
  itemType,
  thread_id: threadId ?? null,
  turn_id: turnId ?? null,
  title: null,
  text: null,
  command: null,
  cwd: null,
  output: null,
  status: null,
  changes: [],
  awaiting_approval: false,
};

From there, features share the same source of truth. The explainer receives the timeline as context, so it reads the session from the actual sequence of events:

const timelineContext = buildExplainerTimelineContext(codexNativeTimeline, explanationLlm);
contextText: hasTimelineContext ? timelineContext.text : null,
contextSource: hasTimelineContext ? "app_server_timeline" : null,

Subagents use the same backbone. The child gets the parent's recent timeline packed into its first task, so it starts with the real session state: what was asked, what Codex tried, which commands ran, which files changed.

const timelineContext = buildTimelineContext(codexNativeTimeline, SUBAGENT_CONTEXT_MAX_CHARS);
const contextText = timelineContext.text || buildSubagentHistoryContext();
contextText ? `COPIED SESSION CONTEXT:\n${contextText}` : null,

That detail is where the app starts to feel alive. Codex keeps being the engine. The product lives around the session: shared context, explanations, approvals, delegation, recovery. The timeline is the backbone that lets all of those features talk about the same work.

Needs that appear once the wrapper exists

Subagents were the first one. Then I looked at the rest of my day and saw the same pattern: small repeated frictions that no tool was going to prioritize for me.

My prompts get improved before Codex ever sees them. When I hit send, a dedicated investigator digs through the repo and extracts high-signal context. Then another model rewrites my messy draft into a precise prompt and shows me why it rewrote it that way.

Codex does the work; Claude translates around it. Codex is great at moving through code, but its output often comes back raw: dense, literal, closer to a log than to an explanation. Claude sits one layer above. It explains Codex back to me, and it also explains my messy ideas to Codex before the turn starts.

Example: how the transformer restructures a vague prompt into clarity.

Example: how Claude explains what Codex output was missing and how to improve it.

That is the pattern I kept seeing: one model executes, another model translates, and the wrapper keeps the loop together. I can write rough intent, Claude turns it into something sharper, Codex executes, and Claude helps me understand what came back.

Build yours

Start with a friction before thinking about a platform.

Launch codex app-server.
Talk to it over JSON-RPC.
Pick one action you repeat every day.
Turn that action into an interface.

The big version of the AI world is moving toward super-apps: one place where agents, tools, and context mix. But the useful version can start on your machine, with a button that solves something that bothered you yesterday.

A year ago I wrote that agents are just loops. Here's this year's version: a super-app is loops, context, and the right model in the right place.

Next time you think "I wish Codex could do this", it probably can. You just have to wrap it.

Questions? Leave a comment below.

One Brain, Many Hands: Building a Parallel Task Orchestrator for AI Agents

Pablo Calofatti — Wed, 20 May 2026 15:39:00 +0000

The Problem No One Talks About

AI coding assistants are fast. Absurdly fast. They can scaffold a service, write tests, and refactor a module in the time it takes me to finish my coffee.

But they do it one thing at a time.

I was working on a microservices audit logging system. Four tasks, all independent, all well-scoped: implement the event schema, build the ingestion endpoint, add the query API, write the integration tests. I could see the finish line from the start. And yet, I sat there feeding tasks one by one into my Claude Code session like I was hand-loading a washing machine with individual socks.

Each task took 10-15 minutes of agent time. Four tasks, run sequentially: an hour.

But they didn't need to be sequential. They touched different files, different concerns, different parts of the codebase. If I had four developers, I'd assign all four tasks at once and go make lunch.

So why couldn't I do that with AI agents?

The Stripe Spark

Around early March 2026, Stripe published a blog post about their internal system called Minions: one-shot, end-to-end coding agents that handle tasks in parallel. The core insight hit me immediately:

You don't need smarter agents. You need an orchestrator that knows how to keep dumb-ish agents on rails.

Stripe's blueprint pattern was elegant: wrap the agentic steps (the creative, unpredictable part — writing code, fixing bugs) inside deterministic guardrails (git operations, linting, testing). The agent can hallucinate all it wants during implementation, but if the tests don't pass, it loops back. If the lint fails, it fixes. And the whole thing is bounded: two attempts max, then stop.

I wasn't trying to build AGI.

I was building a foreman for a construction crew.

The Architecture: Markdown All the Way Down

Here's where it gets a little unhinged. The entire orchestrator is pure markdown. No TypeScript runtime. No Python glue. No code to maintain, compile, or debug. Just three markdown files that Claude Code loads as instructions:

Orchestrator (commands/minion.md): the brain. Parses your task list, figures out dependency order, computes parallel waves, spawns workers.
Worker (agents/minion-worker.md): the hands. Each worker gets a task, a git worktree, and a blueprint to follow.
Blueprint (skills/minion-blueprint/SKILL.md): the rails. A step-by-step execution pattern: branch, implement, lint, test, commit, report.

I call this zero-code prompt engineering. The "code" is the prompt. Claude Code interprets the markdown instructions and executes them using its built-in tools (bash, file editing, git). No SDK, no API calls, no infrastructure.

You (human)
  └── Claude Code session (orchestrator)
        ├── Worker-1 (worktree: .worktrees/task-1)
        ├── Worker-2 (worktree: .worktrees/task-2)
        └── Worker-3 (worktree: .worktrees/task-3)

Each worker runs in an isolated git worktree. That's the key. A worktree is like a parallel checkout of your repo: same git history, different working directory. Worker-1 can edit src/api/events.ts while Worker-2 edits src/api/queries.ts and they never step on each other's toes.

How It Actually Works

You invoke the orchestrator with a task list:

/minion

Tasks:
1. Implement event schema with Zod validation in src/events/schema.ts
2. Build ingestion POST endpoint at /api/events (depends on: 1)
3. Add query GET endpoint at /api/events with filtering (depends on: 1)
4. Write integration tests for both endpoints (depends on: 2, 3)

The orchestrator reads these, builds a dependency graph, and computes waves:

Wave 1: Task 1 (no dependencies)
Wave 2: Tasks 2 and 3 (both depend on 1, but not each other, so they run in parallel)
Wave 3: Task 4 (depends on 2 and 3)

Before spawning anything, it runs conflict detection — scanning the file paths each task is likely to touch. If two tasks in the same wave would edit the same file, it flags the conflict and serializes them.

Then it spawns workers. Each one gets:

A fresh worktree branched from the current HEAD
The task description with full context
A domain agent overlay, auto-selected by keywords. "Endpoint" and "API" gets backend-architect. "React component" gets frontend-architect. "Dockerfile" gets devops-engineer.
A role overlay for the current phase. Planning? You get researcher. Implementing? tdd-developer. Reviewing? code-reviewer.
Auto-detected project tools: it reads your package.json to find your lint command, test runner, and build script.

Here's how it looks in practice, running a real 12-task HAL refactor with wave-based parallel execution:

The blueprint each worker follows looks like this:

Create branch from base
Implement the task (agentic — this is where creativity happens)
Run lint. If fails, fix (1 attempt)
Run tests. If fails, fix (1 attempt)
If still failing after fixes, STOP and report partial progress
Commit with conventional commit message
Push branch, create PR

The two-iteration maximum is sacred. Without it, an agent can loop forever trying to fix a cascading lint error. With it, the worst case is a partially complete PR with a clear status report.

And here's something I learned: incomplete runs are still an excellent starting point. A PR that's 80% done with a clear "tests fail because X" note is infinitely better than an agent spinning its wheels for 20 minutes.

When the full workflow runs with plan, implement, and review phases, it looks like this:

The First Real Test (And the First Real Crash)

I tested minion-toolkit on a real project — a microservices tracing system called traza-microservicios. Two tasks, two parallel workers.

Worker-2 nailed it. Clean branch, passing tests, PR ready.

Worker-1... corrupted git.

Turns out, running concurrent git worktree operations on macOS can trigger a SIGBUS signal — a low-level memory bus error. The git index file gets corrupted when two processes try to update refs simultaneously. This had nothing to do with prompt engineering or AI. It was a filesystem concurrency problem that human developers rarely hit because they don't create three worktrees in the same second.

The fix was unglamorous: add a small delay between worktree creation, use --no-optional-locks on git operations, and as a last resort, clone fresh to /tmp and work from there.

This is the kind of lesson you only learn by shipping. No amount of design documents would have predicted "macOS git worktrees have a race condition under parallel agent spawning."

Lessons Learned the Hard Way

Merge conflicts are the #1 issue. Not AI hallucinations. Not wrong code. Not failing tests. The most common failure mode is two workers editing the same file. Conflict detection before spawning was the single most impactful feature I added.

Workers create extra files. An agent told to "add an endpoint" might also create a utility module, update a barrel export, or add a type file. These out-of-scope changes cause merge conflicts downstream. The solution: git cherry-pick specific commits instead of merging entire branches.

gh pr checks lies to you. GitHub's CLI reports check status using a bucket field, not conclusion. I spent an embarrassing amount of time wondering why "passing" PRs were being flagged as failed.

Dry-run mode saves sanity. Before spawning 4 parallel workers that each burn tokens, preview what would happen — which waves, which agents, which files. --dry-run was an afterthought that became a daily habit.

Cost tracking matters. Parallel workers multiply your API usage. Knowing that a 4-task run costs ~$2.50 vs. a single sequential run at ~$1.80 helps you decide when parallelism is worth it. (Spoiler: when time matters more than tokens, it almost always is.)

The Evolution

What started as a 200-line markdown file on March 4th grew into a proper open-source tool by March 8th:

Version	What Changed
1.0	Basic orchestrator, manual task parsing
2.0	Cross-phase memory, dry-run, worker health monitoring
2.1	Conflict prevention, smart context gathering, cost tracking
2.2	MCP optional delegation, CLI installer (`npx minion-toolkit install`)
2.3	Workflows, domain agents, role overlays, intent capture, stall detection

The CLI installer copies the markdown assets into your ~/.claude/ directory and configures the plugins. One command, and your Claude Code session becomes a parallel orchestrator:

npx minion-toolkit install

After that, /minion is available in any Claude Code session.

Who Is This For?

If you use Claude Code (or plan to) and regularly work on tasks that can be parallelized — feature development across multiple files, multi-service changes, test suites, documentation batches — this tool turns your single-threaded AI session into a coordinated team.

It's especially useful for:

Solo developers who want to simulate a small team
Tech leads who want to delegate a batch of well-scoped tasks
Anyone who's tired of feeding tasks one at a time into an AI session

It's not for tasks that are deeply intertwined — where every file depends on every other file. The orchestrator can handle dependencies between waves, but within a wave, tasks must be independent. If your tasks can't be parallelized, a single session is still the right tool.

Try It

The whole project is open source:

GitHub: pablocalofatti/minion-toolkit
npm: npx minion-toolkit install

Star it if the idea resonates. Open an issue if something breaks (something will break — that's the fun part). And if you build something cool with it, I want to hear about it.

Claude Code is already a remarkably capable developer. But even the best developer can only type on one keyboard. minion-toolkit gives them a crew.

One brain. Many hands. That's the whole idea.

Your agent follows instructions. Until it doesn't.

Daniel Diaz — Tue, 19 May 2026 19:08:52 +0000

Hooks over flowers

Instructions suggest. Skills guide. Hooks enforce.

That's the whole story, but it took me a while to understand why it matters.

You've set up your agent well. Custom instructions for coding standards. Skills for your team's specific patterns. Copilot knows your stack, follows your conventions, generates code that looks like yours.

Then one day it decides to run rm -rf dist/ before rebuilding. Or it edits a file and moves on without running the formatter. Or it completes a task without touching the test suite. All technically valid moves. All not what you wanted.

The problem isn't instructions or skills failing. It's that they guide the agent. They inform its decisions. But an agent that's informed can still decide differently. Instructions are context. They're not guarantees.

Hooks are guarantees.

What are Agent Hooks?

Agent Hooks are shell commands that VS Code runs at specific lifecycle points during an agent session. Not suggested. Not requested. Run.

They live in your repo at:

.github/
└── hooks/
    └── hooks.json

The filename can be anything. VS Code loads all *.json files inside .github/hooks/.

A hook that auto-formats every file the agent edits looks like this:

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\""
      }
    ]
  }
}

Save the file. VS Code picks it up automatically. The next time the agent edits any file, Prettier runs. No prompt needed, no skill invocation, no agent cooperation required.

VS Code added agent-scoped hooks in version 1.111 (March 2026). Workspace hooks via .github/hooks/ were available earlier. Use /create-hook in chat to scaffold a hook configuration.

Meet the eight

This is where hooks get interesting. VS Code exposes eight points in an agent session where your code can run:

Event	When it fires	What you can do
`SessionStart`	User submits the first prompt	Inject context, validate project state
`UserPromptSubmit`	User submits any prompt	Audit requests, add system context
`PreToolUse`	Before the agent invokes any tool	Block dangerous operations, require approval
`PostToolUse`	After a tool completes	Run formatters, trigger follow-up actions
`PreCompact`	Before conversation context is compacted	Export state before it gets truncated
`SubagentStart`	A subagent is spawned	Initialize subagent resources
`SubagentStop`	A subagent completes	Aggregate results, clean up
`Stop`	Agent session ends	Run tests, generate reports, send notifications

Most people, when they first hear about hooks, think PostToolUse: run a formatter. That's valid and immediately useful.

But look at PreToolUse. That's where you can stop the agent before it does something.

And SessionStart. That's where you can inject context that the agent doesn't have yet: current branch, environment, version, whether production deploys are frozen.

PreCompact is the one nobody talks about. When a long session gets too big for the context window, VS Code compacts it. You can hook into that moment to export state, save important context to a file, or log what's about to be truncated.

Stop. Before anything happens

PreToolUse fires before every tool invocation. Your hook receives the tool name and its input via stdin as JSON:

{
  "hookEventName": "PreToolUse",
  "tool_name": "run_in_terminal",
  "tool_input": { "command": "rm -rf dist/" }
}

Your hook can return one of three permissionDecision values:

"allow": proceed without asking the user
"deny": block the operation entirely
"ask": stop and require explicit user confirmation

A simple shell script that blocks destructive commands:

#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command // ""')

if echo "$command" | grep -qE '(rm -rf|DROP TABLE|git push --force)'; then
  echo '{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Destructive command blocked by policy"}}'
  exit 0
fi

echo '{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow"}}'

Wire it up:

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/validate-command.sh"
      }
    ]
  }
}

The agent never sees the operation. It doesn't try to negotiate. The hook returns deny, the tool call stops.

There's also a simpler way to block without writing any JSON at all. Every script, when it finishes, returns a number to whoever called it. That's an exit code. 0 means success. VS Code specifically watches for exit code 2 as a "stop this right now" signal. You just write your reason to stderr and exit:

echo "Production deploys are frozen" >&2
exit 2

VS Code passes that message to the model as context and blocks the tool call. No JSON, no hookSpecificOutput, no ceremony.

One more thing worth knowing: continue: false in the JSON output stops the entire agent session, not just one tool call. Think of exit code 2 as hitting the brakes on a single operation. continue: false is turning off the engine. Use the second one carefully.

If you define more than one hook for the same event, VS Code runs all of them. When multiple PreToolUse hooks return conflicting permissionDecision values, the most restrictive wins: deny beats ask, and ask beats allow. You can stack a validation hook and a logging hook on the same event without worrying about one canceling the other.

Full protocol reference: Hook input and output, VS Code docs

The morning briefing

Instructions are static. They were written at the time you created the file. But some context only exists at runtime: the current git branch, which environment is active, whether the CI pipeline is currently broken.

SessionStart fires before the agent does anything. Your hook can inject that information directly into the session:

#!/bin/bash
branch=$(git branch --show-current)
node_version=$(node -v)
env_name=${NODE_ENV:-development}

jq -n \
  --arg branch "$branch" \
  --arg node "$node_version" \
  --arg env "$env_name" \
  '{
    hookSpecificOutput: {
      hookEventName: "SessionStart",
      additionalContext: ("Branch: " + $branch + " | Node: " + $node + " | Env: " + $env)
    }
  }'

Every session the agent starts, it already knows what branch it's on and what environment it's working in. No need to tell it.

Not every hook is for everyone

Workspace hooks apply to every agent interaction. But sometimes you want a hook that only runs for a specific agent.

Since VS Code 1.111, you can define hooks directly in a custom agent's frontmatter. The hooks field here uses YAML syntax because it lives inside the .agent.md frontmatter, but the structure maps directly to what you'd write in a JSON config file.

---
name: "PM Explainer"
description: "Explains to your PM why it's taking longer. Also formats code."
hooks:
  PostToolUse:
    - type: command
      command: "./scripts/format-and-lint.sh"
---

You are a code editing agent. After making changes, files are formatted and linted automatically.

Enable chat.useCustomAgentHooks to use this. The hook only runs when this specific agent is active, either selected by the user or invoked as a subagent.

The part everyone skips (don't)

Hooks run shell commands with the same permissions as VS Code. That's the power and the responsibility.

Before enabling hooks from any source, read the scripts. Hooks receive JSON input from the agent. Validate and sanitize that input before using it. Never hardcode secrets in hook scripts; use environment variables.

One specific risk: if the agent has access to edit scripts that your hooks run, it can modify those scripts during a session and execute code it writes. Use chat.tools.edits.autoApprove to prevent the agent from editing hook scripts without manual approval.

When your hook does nothing

If a hook runs but nothing seems to happen, check the GitHub Copilot Chat Hooks output channel. Open the Output panel in VS Code, select that channel from the list, and you'll see which hooks were loaded, which fired, their exit codes, and any stdout or stderr output.

Hook scripts that exit with code 1 produce a non-blocking warning: the agent continues, but the issue shows up in the channel. Exit code 2 is the one that blocks and surfaces the message to the model. If your hook is supposed to stop something and it isn't, check which exit code your script is returning.

Already have Claude hooks? You're closer than you think

If you're coming from Claude Code, VS Code reads hook configurations from .claude/settings.json and .claude/settings.local.json by default. The format is the same, with two differences to watch for:

Tool input property names: Claude Code uses snake_case (e.g. tool_input.file_path), VS Code uses camelCase (e.g. tool_input.filePath)
Tool names: different. Claude uses Write/Edit, VS Code uses create_file/replace_string_in_file

Where Hooks Fit

Hooks are the third piece of a larger customization system:

Instructions (copilot-instructions.md / .github/instructions/): always-on context. Good for project-wide rules.
Skills (.github/skills/): domain-specific, activated on demand. Good for encoding your conventions.
Hooks ← you're here: deterministic automation at lifecycle points. Good for guarantees.
MCP Servers: external tools: database access, browser automation, external APIs.
Plugins: installable bundles that package all of the above together.

Instructions tell the agent how to work. Skills tell the agent what patterns to follow. Hooks make sure certain things happen regardless of what the agent decides.

They're not interchangeable. They're complementary.

Takeaways

The difference between guidance and guarantee matters.

Instructions and skills are probabilistic. They shift the agent's behavior in the right direction. Hooks are deterministic. Your code runs, period. Both have their place. Knowing which to reach for is the skill.

Start with one hook.

One PostToolUse Prettier hook that auto-formats on every file edit. Ship it, live with it for a week, see what else you want to automate. The scope expands naturally.

This is the second post in a series on VS Code agent customizations: Skills, Hooks, MCP Servers, CLI, and Plugins.

Previous post: I stopped fighting Copilot's conventions. I taught it mine instead.

Official docs: Agent Hooks (VS Code)

Stop getting generic output from Copilot. Teach it your patterns.

Daniel Diaz — Thu, 23 Apr 2026 13:11:44 +0000

The Problem

You use Copilot. You ask it to build something, and it does sort of. It follows your prompt, generates working code, and you ship it.

Then you do it again the next day. And the day after.

A month later, your codebase has class names in PascalCase next to camelCase functions, three different error handling styles, two ways to structure the same kind of module, and hooks that work differently from each other for no clear reason.

All of it generated by Copilot. All of it reviewed and accepted by you.

The problem isn't that Copilot generates bad code. It generates generic code. It doesn't know your stack, your team's decisions, or the patterns you settled on six months ago. It works from its training data. And your codebase slowly starts to look like it was written by the internet.

What are Agent Skills?

Agent Skills are Markdown files that tell Copilot what your conventions are, for a specific domain, task, or workflow. Persistent context the agent reads before generating anything in that area.

They live in your repo at:

.github/
└── skills/
    └── your-skill-name/
        └── SKILL.md

That's the entire setup. No config files, no registration, no CLI step. The file being there is enough for VS Code to discover it.

When you mention the skill in a chat prompt like "Use the component-structure skill to create a new button", Copilot reads that SKILL.md first, then generates code that follows your conventions.

This is what separates skills from regular prompts: they're reusable, versioned, and shared through the repo. Your conventions stop living in someone's head or a doc nobody reads; they live next to the code they govern.

With a well-written description, Copilot can automatically load the relevant skill based on your request without explicit mention. Explicitly referencing skills is more common with smaller models that need extra guidance to identify the right context.

VS Code added native skill support and the /create-skill command in version 1.110. In version 1.113, a dedicated Chat Customizations editor was added, providing a centralized UI to manage skills, instructions, and agents from a single place.

A minimal SKILL.md

Here's the minimum a skill needs to actually work:

.github/skills/component-structure/SKILL.md

Frontmatter:

---
name: component-structure
description: Guidelines for creating React components following team conventions: named exports, props interface, no inline JSX logic.
---

Body:

# Component Structure Skill

## When to use
Creating new React components or reviewing component patterns.

## Conventions
- One component per file
- Props interface defined above the component
- Named exports only (no default exports)
- No inline logic in JSX, extract to handlers or custom hooks
- Error boundaries at page level, not inside components

## Never do this
- Default exports
- Logic directly in JSX
- Props without an explicit interface

Pattern example:

interface ButtonProps {
  label: string;
  onClick: () => void;
  disabled?: boolean;
}

export function Button({ label, onClick, disabled = false }: ButtonProps) {
  const handleClick = () => {
    if (!disabled) onClick();
  };

  return (
    <button onClick={handleClick} disabled={disabled}>
      {label}
    </button>
  );
}

The name field must match the directory name exactly. The description is what Copilot reads to decide whether to load the skill, so be specific. Full frontmatter reference: SKILL.md file format.

Four sections. One pattern. A few explicit don'ts.

When Copilot reads this before generating a component, it follows the same structure every time not because it guessed right, but because you told it.

The skill doesn't need to be exhaustive. It needs to be specific. A skill that covers one thing well beats one that tries to cover everything and ends up covering nothing.

Creating a skill from a conversation

One of the more useful additions in VS Code 1.110 is /create-skill. After debugging a problem across several chat turns and landing on the right approach, you type:

/create-skill

The agent extracts the pattern from your conversation and scaffolds a SKILL.md for you. You review, adjust, commit.

This is how skills actually get created in practice. You don't design a skill from scratch. You solve a problem, recognize you'll solve it the same way every time, and capture that. /create-skill removes the friction of doing the capture manually.

The Ecosystem

Skills are one piece of a larger customization system. Here's a quick map:

Instructions (copilot-instructions.md / .github/instructions/): always-on context loaded in every session. Good for project-wide rules.
Skills ← you're here: domain-specific, activated on demand when mentioned in chat.
Hooks: scripts that run at specific points in the agent lifecycle: before a response, after a file write, on session start.
MCP Servers: external tools that give the agent capabilities your codebase doesn't have natively, like database access, browser automation, or external APIs.
Plugins: installable bundles that package all of the above together.

Each of these has its own post coming. Skills are the easiest starting point entirely local to your repo, zero infrastructure, and the effect on the agent is immediate.

What I Learned

The model doesn't know your stack. You have to teach it.

Copilot is trained on public code. Your team's specific decisions aren't in that data. Skills are the mechanism for closing that gap.

One good skill beats ten prompts.

A well-written skill invoked consistently produces better results than re-explaining your conventions in each prompt. The repeatability is the point.

The skill itself is documentation.

Writing a SKILL.md forces you to articulate things that previously existed informally. Once it's committed, the team has a shared reference, not just for Copilot.

The real value shows up at review time.

When everyone uses the same skill, code review stops being about style. You argue about logic instead. That's the conversation worth having.

This is the first post in a series on VS Code agent customizations: Skills, MCP Servers, CLI, Hooks, and Plugins.

Official docs: Agent Skills VS Code

What Backend Engineers Get Wrong About AI Integration

Juan M. Altamirano — Mon, 13 Apr 2026 17:26:14 +0000

So you've been asked to "add AI" to your project. Maybe it's a chatbot, maybe it's a smart search, maybe it's just your PM watching too many YouTube videos about agents. Either way, here you are.

And look, as backend engineers, we're actually well-positioned for this. We know how to design APIs, handle async flows, think about failure modes. The problem is that LLMs don't behave like anything we've integrated before, and our instincts sometimes work against us.

Here, I will try to cover eight common mistakes that I've seen (and made).

1. Treating the LLM like a deterministic function

This is the big one.

We're used to thinking in terms of: same input → same output. Call a database, get a row. Call an API, get a JSON response. Write a unit test, pin the behavior forever.

LLMs don't work like that. Under the hood, they're predicting the next most probable token based on everything that came before, which means there's inherent randomness added into every response. Same prompt, different temperature, different day, and you might get a slightly different answer. Or a wildly different one.

Think of it less like calling a function and more like asking a very smart contractor to do some work for you. They'll usually get it right, but you need to review the output, define what "right" looks like, and have a plan for when they hand you something unexpected.

The practical consequence: don't build flows that assume the model always returns what you expect. Validate the output. Have fallbacks. Don't let a malformed response crash your service.

2. Not handling retries and timeouts

If you call an external REST API and it times out, you probably have retry logic. Maybe exponential backoff. Maybe a circuit breaker.

For some reason, when we start calling LLM APIs, all of that discipline disappears.

LLM calls are slow. We're talking in the order of seconds depending on the model and the response length. And they fail. Rate limits, provider outages, network issues, it all happens.

Set a timeout. Retry with backoff. If you're building something user-facing, stream the response so it doesn't feel like the app is frozen. Treat the LLM provider like what it is: an external dependency that can and will go down.

3. Ignoring token costs in loops

Token costs have a way of sneaking up on you.

A common pattern that seems harmless: you have a list of items, you loop over them, you call the LLM for each one. 50 items? 50 calls. Each one dragging along the same massive system prompt like dead weight. The model isn't doing 50x the thinking. You're just paying 50x for the setup.

It's like printing the entire company handbook before every meeting just to discuss one item.

Some things to think about:

Can you batch items into a single prompt? Sometimes yes, sometimes the quality drops.
Is the system prompt really 2000 tokens? Can it be 400?
Are you sending context the model doesn't need for that specific call?
Could you cache responses for identical or near-identical inputs?

Token costs are easy to ignore in development (small dataset, free tier) and painful to discover in production.

4. Breaking prompt caching without realizing it

This one is especially relevant if you're building agents.

Most providers cache prompts automatically and give you significant discounts when a request matches a previously seen prefix. In an agent loop where you're continuously resending the system prompt, full conversation history and tool calls, that cache is what keeps your bill reasonable.

The catch: think of it like a prefix match. The moment something differs from the previous call, the cache stops there and you pay full price from that point on.

A classic example is injecting the current timestamp into your system prompt. Seems harmless, but since it changes on every call, nothing after it ever gets cached, and you're paying full price every time.

Treat everything before the dynamic part of your prompt as sacred. Same order, same content, same whitespace. Push dynamic context as far down the message history as possible, after the static parts that can be cached.

This leads to decisions that look counterintuitive: sometimes you deliberately send more tokens just to keep the cacheable prefix intact. A 2000-token cached call is cheaper than a 1500-token cache miss. Once you internalize that, it changes how you structure your payloads entirely.

5. Treating prompt engineering as someone else's problem

"The AI team handles the prompts."

If you're building the integration, you need to understand how prompts work. Not at a research level, but enough to know why your endpoint is returning garbage.

The prompt is part of your application logic. It deserves the same attention as your SQL queries or your request validation. A bad prompt will produce bad output no matter how clean your surrounding code is.

At minimum, know the difference between system and user messages, understand what temperature does to your outputs, and learn when to use structured outputs, instead of trying to parse free-form text. Which brings me to...

6. Trusting free-form text when you don’t have to

I've seen code like this in the wild:

response = llm.complete("Analyze this and return: risk level, explanation, recommendation")
lines = response.split("\n")
risk = lines[0].split(":")[1].strip()

Please don't do this.

Modern LLM APIs support structured outputs — you define a schema, the model returns valid JSON that matches it. Every time. No parsing, no IndexError because the model decided to add an extra line.

In Python, pair it with Pydantic. In Typescript, use Zod for validation and parsing. In Go, define a struct and unmarshal directly. Your future self will thank you.

class AnalysisResult(BaseModel):
    risk_level: Literal["HIGH", "MEDIUM", "LOW", "NONE"]
    explanation: str
    recommendation: str

result = llm.complete_structured(prompt, schema=AnalysisResult)
# result.risk_level is always there. Always a string. Always one of the four values.

7. Putting everything in the context window and calling it RAG

RAG (Retrieval Augmented Generation) is genuinely useful. The idea is simple: instead of stuffing all your knowledge into the prompt, you retrieve only the relevant bits and include those.

But a lot of implementations I've seen are just... dumping documents into the prompt and calling it RAG.

Real RAG has a retrieval step. You embed the user's query, find the most semantically similar chunks from your knowledge base, and only send those. If you're sending 50 pages of documentation on every call, you're not doing RAG, you're doing expensive copy-paste.

The retrieval quality matters as much as the generation. Bad retrieval means irrelevant context, and irrelevant context means bad answers (no matter how good your model is).

8. Not thinking about what happens when the model is wrong

LLMs hallucinate. They confidently state things that are false. This isn't a bug that will get patched, it's just how these models work.

So the question isn't "what if the model is wrong?"... it's "what happens in my system when the model is wrong?"

If you're using an LLM to triage support tickets, a wrong answer means someone spends extra time investigating. Annoying, not catastrophic. But if you're using it to generate financial reports or medical summaries, wrong answers have a very different impact.

Design your system with the assumption that the model will sometimes be wrong. Add human review steps where it matters. Log the inputs and outputs so you can audit. Don't pipe raw LLM output into anything irreversible.

Wrapping up

None of this means LLMs aren't useful, they absolutely are. But they're a new kind of dependency with failure modes we're not used to. The good news is that most of the solid engineering practices we already have (validation, retries, observability, defensive design) apply here too. We just need to remember to actually use them.

One last thing: this space moves fast. What's a workaround today might be a built-in feature tomorrow. If you're already the kind of engineer who keeps up with tech, just make sure AI topics are in the mix. It's worth it.

If you've run into other footguns that aren't on this list, drop them in the comments. I'm curious what patterns other backend engineers have hit.

From 'The Bench' to 'Ready to Ship': How AI Redefined My Learning Curve

Joaquin Islas — Tue, 07 Apr 2026 19:46:52 +0000

The Hook: The Bench Moment

We’ve all been there: you’re on the bench, and the pressure is mounting. Two potential assignments land on your desk, but there’s a catch—they are built on tech stacks you’ve only touched on the surface. The traditional anxiety sets in: How fast can I get up to speed without slowing the team down? In the past, that moment felt like staring at a mountain you had to climb alone. But recently, I realized the climb has changed.

The Old Way vs. The New Way

Before AI, the process was linear and often isolating. You’d spend days digging through dense documentation and watching generic tutorials. Now, the dynamic is flipped. It’s no longer about consuming static content; it’s about on-demand, interactive tutoring.

Feature	Traditional Training	AI-Powered Learning	Impact
Learning Curve	Weeks of passive courses.	Just-in-Time learning.	40% reduction in non-productive time.
Problem Solving	Waiting for a mentor.	Instant 24/7 tutoring.	Saves hours of Senior developers' time.
Contextualization	Generic examples.	Adapts to company standards.	Lower initial error rate.
Feedback Quality	Errors found in PR reviews.	Real-time logic suggestions.	Less rework and debt.

Real-World Case: Bridging Java and Go

To illustrate this, I recently had to pivot from my Java background into a Go project. Instead of starting from zero, I used AI as a "paradigm translator."

💡 The Strategy: I asked the AI: "I'm used to Java's Spring Boot; how do I achieve this same pattern idiomatically in Go?"

Here is a concrete example of how I mapped a common Java pattern (Service/Repository) to idiomatic Go in minutes, thanks to the AI's guidance:

// What I knew: Java Implementation (Spring-like)
public class UserService {
    private final UserRepository repo;

    // Standard constructor injection
    public UserService(UserRepository repo) {
        this.repo = repo;
    }

    public User getUser(String id) {
        // Linear stream-like flow
        return repo.findById(id).orElseThrow(() -> new UserNotFoundException(id));
    }
}

// What I learned (Idiomatic Go): Guided by AI
package service

import "errors"

// AI suggested defining an interface here for the dependency, 
// emphasizing Go's implicit interface satisfaction.
type UserRepository interface {
    FindByID(id string) (*User, error)
}

type UserService struct {
    repo UserRepository // AI explained composition over inheritance
}

// AI helped me write the constructor function
func NewUserService(r UserRepository) *UserService {
    return &UserService{repo: r}
}

func (s *UserService) GetUser(id string) (*User, error) {
    user, err := s.repo.FindByID(id)
    if err != nil {
        return nil, err // AI emphasized Go's explicit error handling pattern
    }
    if user == nil {
        return nil, errors.New("user not found")
    }
    return user, nil
}

✅ The Result: I quickly understood the shift from Object-Oriented inheritance to Go's composition and interfaces. This didn't just teach me syntax; it gave me the confidence to show up as a contributor, not a beginner, from week one.

The Metrics: Why This Matters for the Company

The shift isn't just a feeling; the data supports it:

🚀 Productivity Boost: According to GitHub Research, developers using AI complete tasks up to 55% faster.
⚖️ The Leveling Effect: A study by MIT and Stanford suggests that AI helps developers close the skills gap 43% faster, acting as a "great leveler" for the whole team.
📈 Continuous Learning: As highlighted by the Harvard Business Review, AI-powered training can reduce time-to-productivity by 40% compared to traditional, passive methods.

⚠ The Limits: Being Honest

However, let’s be clear: AI is not a silver bullet. It can teach you syntax and explain complex concepts, but it cannot replace human judgment. It doesn't know the specific business context or the long-term architectural risks of our project. AI provides the tools, but you provide the engineering intuition. Experience still matters; AI just lets you acquire it faster.

🛠️ A Practical Framework

If you're looking to replicate this, here is the routine I used:

🌉 Bridge the Gap: Always start by asking the AI to compare the new technology to a stack you already master.
🔀 The "English + AI" Combo: Use AI to simulate technical interviews or draft documentation in English while you learn the tech—it's a double win for professional growth.
💪 Contribution as Practice: Don't just watch videos. Take a small internal spike or task and use your AI assistant to guide your implementation.

🎯 The Closing Thought

In 2026, "being prepared" no longer means knowing everything by heart. It means being agile enough to adapt. AI has changed the definition of a Senior Engineer: it’s less about having all the answers and more about knowing how to leverage tools to bridge the gap between "I don't know this" and "I’m ready to ship."

References & Sources

EdTech Global (2025): AI in Corporate Education: Efficiency and ROI Statistics.
GitHub / Microsoft (2023): The impact of AI on developer productivity.
MIT & Stanford (NBER, 2024): Generative AI at Work and the Leveling Effect.
Harvard Business Review (2024): How Generative AI Is Changing the Way We Learn.

Stop Wasting Time on CVEs That Don't Affect You

Juan M. Altamirano — Mon, 16 Mar 2026 18:47:53 +0000

The Problem

Aren't you tired of pushing new code and then a few days later receiving an alert from Github's Dependabot? Well, I am.
The most annoying part is looking for the CVE, reviewing your code and then detecting that you aren't using the affected part.
Rinse and repeat for every single alert.

The solution?

That's why I built dep_shield — a CLI that I can plug into my common workflow (lint -> dep_shield -> tests -> sonar) and get a straight answer: "this CVE affects you" or "relax, you're fine."

How dep_shield Works

The flow is straightforward:

Parse dependencies — Read requirements.txt or pyproject.toml, extract packages and versions
Check for CVEs — Query the OSV database for known vulnerabilities
Find usage in code — Scan your Python files to see where you import vulnerable packages
AI-powered analysis — Send the CVE description + your import context to an LLM and ask: "Does this actually affect me?"

The Interesting Parts

Parsing Dependencies (Both Formats)

The tool supports requirements.txt and pyproject.toml — it figures out which one you're using.
Why both? Well, requirements.txt is still widely used, but uv is taking over fast.

Querying OSV (the free vulnerability database)

OSV over NVD or Snyk? No API key, no rate limits, no pricing tiers. NVD is slow and wants you to parse CPE identifiers. Snyk needs auth and has usage limits.
OSV just works — POST a package name, get vulnerabilities back. For a CLI tool meant to run locally and fast, that's exactly what I needed.

OSV_API_URL = "https://api.osv.dev/v1/query"

def query_vulnerabilities(package_name: str, version: str | None) -> list[Vulnerability]:
    payload = {
        "package": {
            "name": package_name,
            "ecosystem": "PyPI"
        }
    }
    if version:
        payload["version"] = version

    response = httpx.post(OSV_API_URL, json=payload, timeout=10.0)
    return parse_vulnerabilities(response.json())

{
    "vulns": [
        {
            "id": "GHSA-cpwx-vrp4-4pq7",
            "summary": "Jinja2 vulnerable to sandbox breakout through attr filter selecting format method",
            "details": "An oversight in how the Jinja sandboxed environment interacts with the `|attr` filter allows an attacker that controls the content of a template to execute arbitrary Python code.\n\nTo exploit the vulnerability, an attacker needs to control the content of a template. Whether that is the case depends on the type of application using Jinja. This vulnerability impacts users of applications which execute untrusted templates.\n\nJinja's sandbox does catch calls to `str.format` and ensures they don't escape the sandbox. However, it's possible to use the `|attr` filter to get a reference to a string's plain format method, bypassing the sandbox. After the fix, the `|attr` filter no longer bypasses the environment's attribute lookup.",
            "aliases": ["CVE-2025-27516"],
            "modified": "2026-02-04T04:14:58.595738Z",
            "published": "2025-03-05T20:40:14Z",
            "affected": [
                {
                    "package": { "name": "jinja2", "ecosystem": "PyPI", "purl": "pkg:pypi/jinja2" },
                    "ranges": [{ "type": "ECOSYSTEM", "events": [{ "introduced": "0" }, { "fixed": "3.1.6"}] }]
                }
            ]
        }
    ]
}

The full response has more fields (references, versions, etc.), but these are the relevant ones.

Finding Where You Actually Use the Package

It's easy to forget where you actually use a dependency — especially in large projects with dozens of packages. And not all usage is equal: importing requests in your core API is very different from importing it in a one-off migration script.

def scan_file_for_package(file_path: Path, package_name: str) -> list[CodeUsage]:
    pattern_import = rf"^import\s+{package_name}(\s|,|$|\.)"
    pattern_from = rf"^from\s+{package_name}(\s|\.)"
    result = []

    with open(file_path, 'r', encoding='utf-8', errors='ignore') as file:
        for line_num, line in enumerate(file, 1):
            line = line.strip()
            if line.startswith("#"):
                continue

            if re.match(pattern_import, line):
                import_type = "import"
            elif re.match(pattern_from, line):
                import_type = "from"
            else:
                continue

            result.append(CodeUsage(
                file_path=str(file_path),
                line_number=line_num,
                line_content=line,
                import_type=import_type
            ))
    return result

The AI Part: Asking A Model If It Matters

Now, here's where it gets interesting. I send the LLM:

The CVE description
The import statements from your code

And ask: "Given how this code uses the package, does this vulnerability apply?"

Important: Only import lines are sent to the LLM — not your actual business logic. The model sees from requests import Session, not the body of your functions. Your code stays local.

_SYSTEM_PROMPT = """You are a security analyst reviewing Python dependency vulnerabilities.
You will be given a CVE description and import-level code evidence.
Your job is to determine if the vulnerability realistically affects this codebase.

Risk level definitions:
- HIGH: The imports directly expose the vulnerable code path
- MEDIUM: Package is imported but no clear evidence the vulnerable feature is used
- LOW: Package only imported in tests or dev tooling
- NONE: CVE conditions are not plausible in this codebase"""

I use Pydantic to force the model into a consistent format, no free-form text that I'd have to parse.
It either gives me a valid ImpactAnalysis or it fails. No "well, it depends..." answers.

class ImpactAnalysis(BaseModel):
    risk_level: Literal["HIGH", "MEDIUM", "LOW", "NONE"]
    explanation: str
    recommendation: str

Making It Smarter Over Time (RAG)

Here's the thing — the LLM doesn't know your codebase. It analyzes each CVE in isolation. But what if it could remember past analyses?

That's where ChromaDB comes in. Every time the tool analyzes a vulnerability, it stores the result. Next time a similar CVE shows up (same package, similar vulnerability type), it retrieves past analyses as context.

def store_analysis(vulnerability_id: str, analysis: ImpactAnalysis, code_context: str):
    collection.add(
        documents=[f"{vulnerability_id}: {analysis.explanation}"],
        metadatas=[{"risk": analysis.risk_level, "package": package_name}],
        ids=[vulnerability_id]
    )

def get_similar_analyses(vulnerability_description: str, limit: int = 3):
    results = collection.query(
        query_texts=[vulnerability_description],
        n_results=limit
    )
    return results

The result? The tool gets better the more you use it. If you analyzed a requests CVE last month and a new one appears, the model sees how you handled it before.

What the Output Looks Like

What I Learned

Honestly? It reinforced an ancient rule: context is everything
A CVE that sounds critical in the abstract becomes irrelevant when you realize you only import that package in a test helper. OSV turned out to be the perfect data source — free, fast, no API keys, solid Python coverage. And while the LLM does a surprisingly good job at triage, I still treat its output as a suggestion, not a verdict. The RAG layer (ChromaDB) was an afterthought, but it's become one of the most useful parts: the tool genuinely gets better as it sees more of your codebase.

What's Next

I have a few ideas in mind:

More languages — JavaScript and Go are probably the next ones
CI/CD integration — run it in your pipeline, make it fail the build if there is any 'HIGH' impact
Offline mode — run it against a local LLM

Try It Yourself

Give it a shot and let me know what breaks. Seriously — I'd appreciate any feedback.
dep_shield

Who tests the tests?

Lucas Gabriel Sánchez — Fri, 20 Feb 2026 17:05:58 +0000

This post is based on a Gophercon talk by Daniela Petruzalek: Who tests the tests?

A little bit of history

In the beginning, we checked our code manually, running the application and trying different inputs: we called that manual testing. Then we discovered that we could write code to test application code to check if it's correct: we called that automatic testing (unit, integration, functional, etc.)

Now we are in the AI era where we write fewer tests and even less code, we need a way to swiftly check that the tests are correct and that they are testing the cases we expect in our application.

How can we know if code written by AI is correct?

You can use automatic tests in the same way we used to check code written by humans.

One option would be to let the AI write the application code and you write the tests, you can even use TDD where you, the human, write the tests and let the AI write the implementation after.

Another option is to let the AI write the application code and the tests, but then how can you be sure that those tests are testing the things you want or need? Reading and understanding the tests would be the best, but can we do that automatically?

Enter: mutation tests

Mutation testing is a way to check that the tests you have are testing the code the way you want by making small changes to the application code and checking that the tests fail as expected.

It's based on a concept known as a mutant: a version of your application with a small change.

How does it work?

The mutation testing cycle is this:

Create a mutant: change the application code by applying just one change
Run your test suite
Check how many mutants were killed

After running your tests, the ones that failed are said to have killed the mutant, those tests are testing something related to the code you changed and are, from the perspective of that change, good tests.

After many changes, if a test never failed it means that test didn't kill any mutant and is a weak test. You should probably delete that test or write a better one.

If a mutant is never killed, then that code is not being tested (no coverage) or is being tested poorly, you have an opportunity to write a test to check that piece of code if needed.

Do I have to make these changes manually?

You can do it manually, but there are some tools to aid you:

C#, TypeScript and Scala: Stryker
Go: go-gremlins
Java: pitest
Python: mutatest
Rust: mutants.rs

These tools provide a way to make those changes automatically and some of them run the tests for you.

Why do we need mutation testing?

Let's see a very simple example in Python:

def divide(a, b):
    if b == 0:
        raise ValueError("can't divide by 0")
    return a/b

A simple test suite we can have is:

import unittest
from divide import divide

class TestDivide(unittest.TestCase):
    def test_divide_error(self):
        with self.assertRaises(ValueError):
            divide(1, 0)

    def test_divide_success(self):
        self.assertEqual(1, divide(1, 1))

if __name__ == '__main__':
    unittest.main()

Run the tests and everything is fine:

$ python tests.py
..
----------------------------------------------------------------------
Ran 2 tests in 0.000s

OK

Here we are testing both flows, when an error is raised and when we complete a successful operation, coverage is at 100% but those tests are not great, and here's why: let's change the implementation of divide from a/b to a*b:

def divide(a, b):
    if b == 0:
        raise ValueError("can't divide by 0")
    return a*b

Running the tests should fail, right? They don't, because 1*1 is still 1:

$ python tests.py
..
----------------------------------------------------------------------
Ran 2 tests in 0.000s

OK

This is a problematic test:

def test_divide_success(self):
    self.assertEqual(1, divide(1, 1))

Even when you have 100% test coverage, that doesn't mean you have 100% test case coverage; some cases may be missing or not being tested correctly.

What we did here was a mutation: from a/b to a*b, that mutation gives us information about our tests that we didn't have before.

How to read the results of mutation testing?

When you run your test suite against mutated code, each test can do one of two things: kill the mutant (the test fails, so it detected the change) or survive (the test still passes, so it missed the change). After many mutation, you can summarize how often each test killed mutants, for example:

After 200 Mutations:
TestA: 140 Kills, 60 Survived
TestB: 200 Kills
TestC: 30 Kills, 170 Survived

How to interpret this:

TestA: is good test because on most mutations it was killed.
TestB: is your strongest test, it detects every mutation you ran.
TestC: is the weak one, it usually doesn't detect mutations.

When not to use mutation testing?

In some projects or languages, running mutation tests can take hours. For each mutant, the tool has to compile (if needed) and run the full test suite. If your test suite takes 10 minutes, each mutation will take at least that long, so keep this in mind.

Use this approach on small projects or ones where the "edit, compile, test" cycle is small.

Closing

So who tests the tests? In practice, mutation testing does that: by checking that your tests react when the code is deliberately broken.

Bicycles Are All Your AI Agents Need

Federico Pascarella — Thu, 13 Nov 2025 12:47:16 +0000

From Condors to Code

Somewhere between a condor and a keyboard lies human genius. Steve Jobs once told a story about how humans are terrible movers compared to animals. The condor beats us easily in the race of energy efficiency, but put a person on a bicycle and they fly.
The bicycle, Jobs said, is "a tool that amplifies our efficiency." Computers, he added, are bicycles for the mind.
That thought never left me. And now, with AI agents evolving super-fast, I can't help seeing the same pattern repeat.
My humble view is that tools are still the key. Only this time, the cyclists are our AI agents with its brain (the LLM), and the bicycles are the functions we build for them.
With the right tools, an agent moves with purpose. With clumsy tools, it stalls.

The Engineering of Great Tools

Great agents sit on top of small, sharp Python functions. They are plain, predictable, and fast.

1. Single Responsibility

Specialize each function. Do one job well, then compose.

# Bad: Swiss-army function
def create_user(name, email, send_welcome=True, log=True):
    user = db.save(name, email)
    if send_welcome:
        send_email(email, "Welcome!")
    if log:
        logger.info(f"User {name} created")
    return user

# Good: Focused, composable tools
def save_user(name: str, email: str) -> dict:
    return db.save(name, email)

def send_welcome_email(email: str) -> bool:
    return send_email(email, "Welcome!")

2. Clear interfaces

Name things so intent is obvious. Keep arguments explicit. Return data instead of printing.

# Bad: Vague names and side effects
def discCalc(p, x, t=None):
    result = p - (p * x / 100)
    print(f"Discount applied: ${result}")

# Good: Straight names and returns
def calculate_discount(price: float, percentage: float) -> float:
    return price - (price * percentage / 100)

3. Structured outputs

Agents prefer structure. Return dicts or JSON, not prose.

# Bad: Unstructured string
def get_weather(city):
    temp = fetch_temperature(city)
    return f"It's about {temp} degrees in {city}, partly cloudy"

# Good: MCP tool with schema
from pydantic import BaseModel, Field
from mcp.server import Server
from mcp.types import Tool

server = Server("weather")

class WeatherData(BaseModel):
    city: str = Field(description="City name")
    temperature: float = Field(description="Temperature in Celsius")
    condition: str = Field(description="Weather condition")
    humidity: int = Field(description="Humidity percentage")

@server.call_tool()
async def get_weather(city: str) -> WeatherData:
    temp = await fetch_temperature(city)
    condition = await fetch_condition(city)
    return WeatherData(city=city, temperature=temp, condition=condition, humidity=65)

4. Efficiency

Use built-ins, cache where it helps, and profile before optimizing.

# Bad: Manual loops
def filter_active_users(users):
    result = []
    for user in users:
        if user.get("active"):
            result.append(user)
    return result

# Good: Built-ins plus caching
from functools import lru_cache
from typing import Tuple, List

@lru_cache(maxsize=128)
def filter_active_users(users_tuple: Tuple[dict, ...]) -> List[dict]:
    return [u for u in users_tuple if u.get("active")]

5. Robustness

Validate inputs and fail loudly with helpful errors.

# Bad: No validation
def read_file(path):
    with open(path) as f:
        return f.read()

# Good: Validation and clear errors
def read_file(path: str) -> str:
    if not isinstance(path, str) or not path:
        raise ValueError("Path must be a non-empty string")
    try:
        with open(path, "r") as f:
            return f.read()
    except FileNotFoundError:
        raise FileNotFoundError(f"File not found: {path}")

6. The micro-tooling mindset

Break big jobs into small tools you can test and swap. MCP benefits from chains of simple, named steps.

# Bad: Monolith
def process_user_data(user_id):
    user = db.fetch(user_id)
    validated = validate(user)
    enriched = api.enrich(validated)
    return transform(enriched)

# Good: Composable steps
def fetch_user(user_id: str) -> dict:
    return db.fetch(user_id)

def validate_user(user: dict) -> dict:
    return validate(user)

def enrich_user(user: dict) -> dict:
    return api.enrich(user)

7. Trade-offs

Hundreds of tiny tools can create orchestration overhead. Clear names, steady input and output shapes, and basic docs keep things manageable.

Show, Don't Tell: Two Decision Flows

A concrete example makes the difference clear. Here is the same task, done with weak tools and with strong tools.

Task: Extract newly signed customers from a CSV in cloud storage, enrich each with firmographic data, and email an account summary.

Agent with poorly designed tools

Calls a generic process_file() that auto-detects type and tries to parse everything.
Uses one do everything enrich_user() that accepts many flags, then times out on third party rate limits.
Prints logs to stdout, returns a mixed string summary, and the agent fails to decide what to send.

Decision flow with weak tools

Input: blob path
Branch: auto-detect format, guess schema
Loop: enrich with side effects
Output: unstructured string
Failure mode: retries loop, hallucinates missing fields, no clear errors

Agent with well designed tools

load_csv(path, schema) returns a typed dataframe.
batch_enrich(users, provider, rate_limit) yields structured rows with retry metadata.
render_account_summary(users) returns JSON for send_email(to, subject, body_html).

Decision flow with strong tools

Input: explicit path and schema
Transform: strict parser
Enrich: idempotent, rate limited, returns status per row
Render: deterministic template
Output: email send result with IDs

Result: same goal, three clean steps, easy to test and to explain.

Conclusion

I believe that innovation often hides in simplicity. Building efficient AI agents isn't about giving them infinite intelligence; it's about giving them great tools. Write them clean, focused, and well-documented; think in micro-tooling: small parts, big impact.
So, next time you're debugging that stubborn Python function, just remember: you're not fixing a bug. You're tuning a bicycle for the mind of an AI.

WhatsApp + MCP: automatic audio transcription

German Burgardt — Mon, 29 Sep 2025 19:39:53 +0000

Introduction

MCP (Model Context Protocol) can look complicated until you ship something real with it. Let's use it on something practical: expose your WhatsApp voice notes with your own MCP server and turn them into transcripts.

What is MCP?

MCP is a connection standard that connects AI agents with external systems.

It has a server and a client, and they have two different ways to talk to each other:

stdio (stdin/stdout): the standard Unix mechanism for a process to receive or send data to the environment or another process.
Server-Sent Events (SSE): an HTTP mechanism where the server keeps the connection open and streams events to the client (one-way).

Quick comparison of stdio and SSE transports in MCP.

MCP architecture

Host: Claude Desktop / Cursor / any AI agent. It coordinates the LLM, spins up MCP clients, and shows results.
MCP Client: an implementation embedded in the host that connects to your server. It speaks the protocol, opens/manages the connection, and sends/receives requests.
MCP Server: your program that exposes tools. It runs actions and returns data/events to the client.

An MCP server can expose different capabilities, but in this project we stick to tools (actions like transcribing audio). MCP also supports resources or prompts; we skip them here to keep the flow simple.

MCP Client -> MCP Server" width="600" height="400">

Diagram of the Host → MCP Client → MCP Server flow.

Building the WhatsApp MCP

WhatsApp Desktop on macOS stores everything locally: an SQLite database with chats and folders containing the media files.

Our MCP server will:

Read the WhatsApp database
Find audio files per contact
Transcribe them with Whisper
Send the text back to the Client (Cursor in this case)

The working code lives in the repository: mcp-whatsapp-whisper. Let's walk through the key pieces.

The STDIN/STDOUT connection

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const transport = new StdioServerTransport();
await this.server.connect(transport);

With that the server listens to every client request on STDIN and replies through STDOUT.

We pick stdio because this MCP server runs locally. It's the simplest and most stable transport on desktop/CLI: no open ports, no HTTP dependency, avoids CORS/firewalls, and hosts (Claude Desktop/Cursor) support it natively. SSE makes sense when the server lives remotely behind HTTP.

Exposing capabilities

this.server = new Server(
  {
    name: "whatsapp-audio-mcp",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {}, // We will expose actions
    },
  }
);

Designing the tools

The server lives on three tools each with a specific role:

getRecentAudio(contactName, count?): pulls the latest audio paths for a contact.
searchAudios(query, date?): narrows the list by name or date when the history is large. We get filtering without touching SQLite directly.
transcribeAudio(audioPath): turns a path into text with Whisper. It finishes the loop by delivering the result we care about.

The goal was a minimal set: find, refine, transcribe. Each tool lines up with one of those stages.

{
  name: 'transcribeAudio',
  description: 'Transcribe an audio file using OpenAI Whisper (SDK)',
  inputSchema: {
    type: 'object',
    properties: {
      audioPath: {
        type: 'string',
        description: 'Path to the audio file',
      },
    },
    required: ['audioPath'],
  },
}

The schema follows JSON Schema. With it, Cursor knows which parameters to send.

Accessing WhatsApp

WhatsApp Desktop keeps everything under predictable paths:

this.dbPath = path.join(
  homeDir,
  "Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite"
);
this.mediaPath = path.join(
  homeDir,
  "Library/Group Containers/group.net.whatsapp.WhatsApp.shared/Message/Media"
);

The database is SQLite:

const query = `
  SELECT DISTINCT 
    ZCONTACTJID as jid,
    ZPARTNERNAME as name,
    ZLASTMESSAGEDATE as lastMessageDate
  FROM ZWACHATSESSION
  WHERE ZPARTNERNAME IS NOT NULL
  AND ZCONTACTJID NOT LIKE '%@g.us'  -- Exclude groups
`;

Audio files are organized per contact. We scan recursively:

const audioExtensions = [".opus", ".m4a", ".mp3", ".aac", ".wav"];

async function scanDirectory(dir: string): Promise<void> {
  const entries = await fs.readdir(dir, { withFileTypes: true });

  for (const entry of entries) {
    if (audioExtensions.some((ext) => entry.name.endsWith(ext))) {
      // Found an audio file
      audioFiles.push({
        path: fullPath,
        filename: entry.name,
        modifiedDate: stats.mtime.toISOString(),
      });
    }
  }
}

The transcription: FFmpeg + Whisper

WhatsApp ships audio in Opus, but OpenAI Whisper prefers MP3. We use FFmpeg:

const ffmpeg = spawn("ffmpeg", [
  "-i",
  inputPath, // WhatsApp Opus audio
  "-acodec",
  "mp3",
  "-b:a",
  "128k",
  outputPath, // Temporary MP3
]);

Then we transcribe with OpenAI Whisper (SDK):

import OpenAI from "openai";
import fs from "node:fs";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const transcription = await openai.audio.transcriptions.create({
  file: fs.createReadStream(outputPath), // Temporary MP3
  model: "whisper-1",
});

const transcriptionText = transcription.text;

Configuring Cursor (the client)

In the Cursor config (~/.cursor/mcp.json) we add:

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/path/to/mcp-whatsapp-whisper/dist/server.js"],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_KEY"
      }
    }
  }
}

Cursor can now invoke our server whenever it needs to.

MCP in action

The user asks Cursor:

"Send me the transcript of Elian's last audio."

Cursor automatically:

Calls getRecentAudio(contactName: "elian")
Receives the audio file path
Calls transcribeAudio(audioPath: "/path/to/audio.opus")
Receives the transcription
Summarizes or shows the full text

The transcription flows through the OpenAI API; the temporary MP3 is sent to get the text back. Cursor orchestrates; your server prepares the file and makes the call.

Cursor showing the transcription returned by the WhatsApp MCP server.

Limitations: macOS only

This server is macOS only. The WhatsApp paths are specific to Mac.

It depends on:

WhatsApp Desktop installed
FFmpeg (brew install ffmpeg)
OpenAI SDK (npm i openai) with OPENAI_API_KEY configured
Internet connection

We also skip Prompts and Resource Templates.

Security depends on the host. Cursor can ask for approval before it runs tools.

Keep it running with PM2

Build the project once (npm run build) and keep the server alive with pm2 start ecosystem.config.cjs. The provided config watches the compiled dist/server.js and restarts it if it crashes.

Conclusion

Your AI agent can now reach your data, use your tools, work in your context.

The WhatsApp server is just one idea. Once you realize any program that speaks STDIN/STDOUT can be an MCP server, the possibilities get wild.

Next time you think "I wish Cursor could access...", remember: it probably can. You just need to build the bridge.

How AI Reflects Your Thinking

German Burgardt — Tue, 26 Aug 2025 13:36:38 +0000

When we code using AI we ask ourselves: "what's the best prompt?" or "what magic prompt should I use?".

We'd be better off asking: "what kind of interaction is this?". Trying to understand the nature of the interaction between us and the model.

Maybe the problem isn't the technology, but us.

An Analogy

Imagine you hire a remote programmer. Brilliant, but with some quirks:

Never worked on your project before (0 context)
Extremely literal. If you don't explicitly tell them, they never assume anything.
Doesn't infer context
Completely loses their memory every day, returning to their initial state

How would you communicate with them?

You'd probably:

Explain all the necessary context, very detailed
Be very specific with requirements
Not assume they'll "figure out" anything. You explain everything
Expect some iterations before the final result
Maybe save context files to resend them every day

That's the best way to interact with an AI model.

AI As a Mirror

The model isn't just a task executor. It's also a mirror of your clarity when communicating a problem.

If you give it vague instructions, you get vague results simply because it faithfully reflects how vague your thinking was.

Most of the time when the model "doesn't understand" the problem isn't the model. It's that we ourselves weren't clear about what we wanted.

Clarity As a Skill

The real skill isn't "writing good prompts". It's thinking clearly about problems and communicating that clarity. This is a fundamental skill for any programmer.

Example

What we usually do:

Optimize this function

Why it fails: Optimize in what sense? Speed? Memory? Readability? There's no success criteria.

What we should do:

The processOrders() function in orders.js takes 5 seconds with 1000 orders.
I need it to take less than 1 second.
Orders come from the database already sorted by date.
You can assume there are no duplicate orders.
Logs: <<detailed logs>>

This is much clearer and less abstract. It describes:

The problem (5 seconds is too much)
The measurable goal (less than 1 second)
Constraints (already sorted)
Assumptions (no duplicates)

Breaking Down Problems

One of the skills that improves working with AI is breaking problems down into smaller pieces. AI won't save you the work of thinking. The clarification process itself is valuable work in programming.

Instead of:

Implement a complete authentication system

You learn to think:

Step 1: Define the User model with minimum required fields: <fields>
Step 2: Create the registration endpoint with basic validation (validation type, etc)
[etc...]

The Limitations

AI can only handle 3-4 files well at a time. It's a limitation but with its bright side:

It forces you to keep responsibilities separated and create clear interfaces. You need to avoid coupling and think in small modules.

It incentivizes you to follow good architecture practices.

The Importance of Context

AI needs all the context possible, don't skimp.

CONTEXT: Users report the checkout page hangs
SYMPTOM: The "Pay" button stays in "Processing..." state indefinitely
FILE: checkout.js, handlePayment() function
SUSPICION: Probably missing a catch to handle API errors
TASK: Add robust error handling and visual feedback to the user

The Value of Programming with AI

Programming with AI trains you in thinking clearly and communicating precisely. It forces you to break problems into manageable pieces and be explicit with your requirements while constantly verifying results.

These seem like fundamental skills for any dev regardless of language.

Final Reflection

AI doesn't save you from thinking, or at least you shouldn't use it that way. It's the opposite, every prompt you write is an opportunity to clarify your understanding. Every response you receive is feedback on your clarity. Every iteration is a chance to improve.

Next time you use AI and don't get the expected result, before blaming the model, ask yourself:

Did I really have clarity on what I wanted?
Did I break down the problem into manageable parts?

These models are honest, literal collaborators. They give you exactly what you ask for, but they demand clarity. Learning to be clear is learning to think well. AI used properly makes you a better programmer.

Automate Any Repetitive Task with MCP

German Burgardt — Mon, 28 Jul 2025 17:30:01 +0000

The Problem: Repetitive Detailed Prompting

Every time I start a new task in Claude Code / Cursor, I type a detailed prompt to guide the AI through an internal monologue before proceeding. For example:

"You will generate an internal monologue of 200 numbered lines where two thinkers debate the approach:

Pragmatic focuses on functionality and efficiency
Creative on innovation and elegance
Follow these rules: exactly 200 lines, each starting with [Pragmatic] or [Creative]
Be specific about code without abstractions
Reflect and question without solutions
Mention files/functions/variables
Consider edge cases/performance/maintainability/user experience
Debate simplicity vs functionality
Question decisions, no repeats, end without conclusion
Then address the task: [actual task here]."

Typing this repeatedly 20+ times a day wastes time and disrupts focus.

As someone researching practical AI applications, we can fix that.

// Before: 200+ word prompt every time
// After: "internal monologue 200 lines - implement auth system"

Enter MCPs: The Missing Link

Model Context Protocols (MCPs) allow extending AI agents with custom tools. While common examples include fetching data, web browsing, or integrating with Slack, I used it in a novel way to automate my repetitive prompt.

From Repetition to Automation

I built an MCP server in my Remix app (essentially the same as plain Node.js) that generates these monologues on demand. Now, Claude detects the trigger and handles it automatically.

Here's a glimpse of what it generates:

1. [Pragmatic] We need to implement auth - start with basic JWT in middleware.js
2. [Creative] But what about OAuth? Users expect social login nowadays...
3. [Pragmatic] OAuth adds complexity - first nail down password flow, then extend
...

The difference:

Before: Type the full detailed prompt each time, then describe the task.
After: Simply say "internal monologue 200 lines about X - [task]", and Claude generates the monologue via the tool, then proceeds.

Time saved: ~2 minutes per task

Characters typed: 300+ → 40

Building Your Own Monologue MCP

Here's how to implement it in a Node.js server (adaptable from my Remix example).

Step 1: Install Dependencies

npm install @modelcontextprotocol/sdk zod @anthropic-ai/sdk

Step 2: Create the MCP Server Handler

Create app/lib/mcp-server.ts:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import { z } from "zod";
import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

export function createMCPServer() {
  const server = new Server(
    {
      name: "monologue-mcp",
      version: "1.0.0",
    },
    {
      capabilities: {
        tools: {},
      },
    }
  );

  // Define the monologue tool
  server.setRequestHandler("tools/list", async () => ({
    tools: [
      {
        name: "generate-monologue",
        description:
          "Generate a reflective internal monologue in the style of Pragmatic vs Creative thinker",
        inputSchema: {
          type: "object",
          properties: {
            lines: {
              type: "number",
              description: "Number of lines in the monologue (default: 100)",
              default: 100,
            },
            context: {
              type: "string",
              description: "Current conversation context",
            },
            task: {
              type: "string",
              description: "Description of the task to perform",
            },
          },
          required: ["task"],
        },
      },
    ],
  }));

  // The actual tool implementation
  server.setRequestHandler("tools/call", async (request) => {
    if (request.params.name === "generate-monologue") {
      const ArgsSchema = z.object({
        lines: z.number().int().min(1).max(500).default(100),
        context: z.string().max(2000).optional().default(""),
        task: z.string().min(1).max(1000),
      });

      const { lines, context, task } = ArgsSchema.parse(
        request.params.arguments
      );

      try {
        const systemPrompt = `You are two thinkers having an internal dialogue about programming.
Pragmatic is focused on functionality and efficiency.
Creative is obsessive about innovation and elegance.

STRICT RULES:
1. Generate EXACTLY ${lines} numbered lines
2. Each line must start with [Pragmatic] or [Creative]
3. NO abstractions - be specific about the code
4. NO complete solutions - REFLECT and QUESTION
5. Mention specific files, functions, variables when relevant
6. Think about: edge cases, performance, maintainability, user experience
7. Debate simplicity vs functionality
8. Question every technical decision
9. NO repeated ideas - each line must add new value
10. End without a definitive conclusion - it's reflection, not decision`;

        const userPrompt = `${
          context ? `Previous context:\n${context}\n\n` : ""
        }Current task: ${task}

Generate an internal monologue of EXACTLY ${lines} numbered lines where the two thinkers debate the best way to approach this task.`;

        const response = await anthropic.messages.create({
          model: "claude-opus-4-20250514",
          max_tokens: 32000,
          temperature: 1,
          system: systemPrompt,
          messages: [
            {
              role: "user",
              content: userPrompt,
            },
          ],
        });

        const monologue = response.content[0].text;

        return {
          content: [
            {
              type: "text",
              text: monologue,
            },
          ],
        };
      } catch (error: any) {
        return {
          content: [
            {
              type: "text",
              text: `Error generating monologue: ${error.message}`,
            },
          ],
          isError: true,
        };
      }
    }

    throw new Error(`Unknown tool: ${request.params.name}`);
  });

  return server;
}

Step 3: Create the API Route

Create app/routes/api.mcp.ts:

The MCP server needs to be exposed as an HTTP endpoint. We use Bearer authentication to secure it. Only Claude (or other authorized clients) with the correct API key can access your server. This prevents random people from using your tools.

import type { LoaderFunctionArgs } from "@remix-run/node";
import { createMCPServer } from "~/lib/mcp-server";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";

// SSE (Server Sent Events) keeps an open connection between Claude and your server
// This allows Claude to call your tools in real time without polling

// Simple auth check
function verifyAuth(request: Request): boolean {
  const authHeader = request.headers.get("Authorization");
  const expectedKey = process.env.MCP_API_KEY || "your-secret-key";
  return authHeader === `Bearer ${expectedKey}`;
}

export async function loader({ request }: LoaderFunctionArgs) {
  if (!verifyAuth(request)) {
    return new Response("Unauthorized", { status: 401 });
  }

  const responseHeaders = new Headers({
    "Content-Type": "text/event-stream",
    "Cache-Control": "no-cache",
    Connection: "keep-alive",
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Headers": "Authorization, Content-Type",
  });

  const server = createMCPServer();

  const transport = new SSEServerTransport({
    endpoint: "/api/mcp",
    requestHeaders: Object.fromEntries(request.headers.entries()),
    responseHeaders: Object.fromEntries(responseHeaders.entries()),
  });

  const stream = new ReadableStream({
    async start(controller) {
      try {
        await server.connect(transport);

        // Keep connection alive (SSE connections timeout after 30 seconds of silence)
        const keepAlive = setInterval(() => {
          controller.enqueue(new TextEncoder().encode(": keepalive\n\n"));
        }, 30000);

        request.signal.addEventListener("abort", () => {
          clearInterval(keepAlive);
          controller.close();
        });
      } catch (error) {
        controller.error(error);
      }
    },
  });

  return new Response(stream, {
    headers: responseHeaders,
  });
}

Step 4: Configure Environment Variables

Add to your .env:

ANTHROPIC_API_KEY=your-anthropic-api-key
MCP_API_KEY=a-secret-key-for-your-mcp

The ANTHROPIC_API_KEY lets your server call Claude's API to generate monologues. The MCP_API_KEY is your own secret, it's what Claude will use to authenticate with your server.

Step 5: Deploy and Connect

Deploy your changes (I use Vercel, but any platform works):

git add .
git commit -m "Add MCP server for internal monologues"
git push

Then connect from Claude:

claude mcp add --transport sse monologue https://yourdomain.com/api/mcp --header "Authorization: Bearer your-secret-key"

The sse transport tells Claude to use Server Sent Events (the streaming connection type we set up). Replace your-secret-key with the same MCP_API_KEY from your .env file.

How It Works in Practice

Now, when working in Claude:

> internal monologue 150 lines - design user experience for login flow

Claude detects the phrase, calls the MCP tool, generates the detailed monologue (e.g., a debate on intuitive interfaces vs secure processes, navigation logic, etc.), and uses it to design the feature thoughtfully.

A sample monologue excerpt:

1. [Creative] Login flow should be innovative and seamless – perhaps biometric integration for delight?
2. [Pragmatic] Biometrics add complexity; focus on reliable password handling in auth.js first.
3. [Creative] But user experience suffers with forms – question if we can animate transitions smoothly.
4. [Pragmatic] Animations might impact performance on mobile; consider edge cases in responsive design.
...

Why This Matters

This MCP setup boosts programming efficiency by leveraging AI tools for consistent planning and productivity gains, while experimenting with a non typical application to explore MCPs more creatively and deeply.

What's Next?

One could build other creative tools, such as one that fetches and analyzes server logs directly, or another that integrates with external APIs for real time data checks.

Your Turn

What repetitive tasks do you deal with in your daily work? Maybe you can create an MCP. The code is ready to adapt and build something.

Questions? Leave a comment below and I'll be happy to help!