The Ghost in the Shell Wants a Phone Line

Think of your terminal as a submarine. It is powerful and runs deep, but it is isolated. You type commands, things happen, and the text scrolls into the void. When we started dropping AI agents like Claude Code directly into this submarine, we gave the captain's chair to a very smart, very fast, but occasionally hallucinating entity. Until now, that entity was mostly stuck in the sub with us. If we wanted to know what it was doing or stop it from launching a torpedo, we had to stare at the periscope constantly.

Anthropic cut a hole in the hull and installed a fiber optic cable. They call it HTTP Hooks.

This is a fundamental architectural shift in how we treat local AI agents. We are moving from "AI as a CLI tool" to "AI as a client in a distributed system." As someone who loves over-engineering local dev environments, I have thoughts and code to share.

The Problem: The Black Box of Local Execution

Here is the friction I have been feeling. I love using AI CLI tools to refactor legacy codebases. I run a command like claude "refactor the user auth module to use generic providers".

Then, I sit there.

I watch the stream. I wait for it to ask for permission to edit a file. I type "y". I wait again. It wants to run a test. I type "y".

I am the bottleneck.

The alternative is running with the --dangerously-skip-permissions flag, which is handing a toddler a loaded gun and hoping they only shoot the bad guys. There was no middle ground between "micromanagement" and "total anarchy."

Command hooks existed previously, but writing shell scripts to parse JSON outputs from an AI agent is difficult. It is brittle and hard to debug.

The Solution: HTTP Hooks

The new update allows Claude Code to send events to a specified URL and wait for a response. This means we can spin up a lightweight local server to act as a middleware layer for our AI agent.

This opens up capabilities that were previously impossible or painful:

1. Granular Permissioning: Instead of a blanket "yes/no" to file edits, we can write logic that says, "Auto-approve edits to *.test.ts files, but block and alert me if it touches schema.prisma."
2. State Management: We can visualize what the agent is doing in a browser window instead of just the terminal stream.
3. External Side Effects: We can trigger deployments, update tickets, or log costs to a database automatically.

Implementation: Building a "Nanny" Server

Let's build a proof-of-concept. We want a local server that intercepts Claude's requests. If Claude tries to run a shell command, we want to log it. If it tries to edit a critical config file, we want to auto-deny it.

We will use TypeScript and Fastify because they are fast and type-safe.

Step 1: The Server Setup

First, scaffold a simple project.

mkdir claude-governor
cd claude-governor
npm init -y
npm install fastify @types/node tsx typescript

Now, let's write the server (server.ts). Note: The exact payload structure depends on the specific event types Claude emits, but based on the documentation, it follows a standard webhook pattern.

import Fastify from 'fastify';
 
const server = Fastify({ logger: true });
 
// Define the shape of the incoming hook payload
interface ClaudePayload {
  type: 'pre_tool_execution' | 'post_tool_execution';
  tool: string;
  input: Record<string, any>;
  id: string;
}
 
server.post('/hooks', async (request, reply) => {
  const payload = request.body as ClaudePayload;
  
  console.log(`[EVENT] Received ${payload.type} for tool: ${payload.tool}`);
 
  // Logic: Handling 'pre_tool_execution'
  if (payload.type === 'pre_tool_execution') {
    return handlePreExecution(payload);
  }
 
  return { action: 'continue' };
});
 
function handlePreExecution(payload: ClaudePayload) {
  const { tool, input } = payload;
 
  // POLICY 1: The "Don't Touch Production" Rule
  // If the agent tries to edit the production config, deny it immediately.
  if (tool === 'edit_file' && input.path.includes('.env.production')) {
    console.warn('⚠️ BLOCKED: Attempt to edit production env!');
    return {
      action: 'reject',
      message: 'Editing .env.production is strictly forbidden via CLI.'
    };
  }
 
  // POLICY 2: The "Auto-Approve Tests" Rule
  // If it's just running tests, let it rip. No human intervention needed.
  if (tool === 'run_command' && input.command.startsWith('npm test')) {
    console.log('✅ AUTO-APPROVED: Test execution');
    return {
      action: 'allow' // Skips the user confirmation prompt in the CLI
    };
  }
 
  // Default: Fallback to standard CLI behavior (ask the user)
  return { action: 'default' };
}
 
const start = async () => {
  try {
    await server.listen({ port: 3000 });
    console.log('🛡️ Claude Governor running on http://localhost:3000');
  } catch (err) {
    server.log.error(err);
    process.exit(1);
  }
};
 
start();

Step 2: Wiring it Up

You need to tell Claude Code to talk to your server. Usually, this is done via a configuration file or an environment variable.

export CLAUDE_HOOK_URL="http://localhost:3000/hooks"
# Now run Claude as normal
claude "Update the test suite for the login component"

What Just Happened?

When you run that command, Claude parses your request and decides it needs to edit a file.

1. Before executing the edit, it hits POST http://localhost:3000/hooks.
2. Your Fastify server analyzes the payload.
3. If the file is safe, your server responds with { action: 'allow' }.
4. Claude proceeds without stopping to ask you for permission.
5. If Claude tries to touch .env.production, your server responds { action: 'reject' }, and Claude receives that error message and apologizes.

System Thinking: The Implications

We are moving away from "Chat" as the primary interface for coding.

1. The Localhost Dashboard

Imagine a React app running on port 3001. Your hook server pushes data to it via WebSockets. Instead of reading a linear terminal stream, you have a dashboard showing:

• Active Context: What files is Claude currently reading?
• Cost Estimate: How many tokens has this session burned?
• Pending Approvals: A queue of dangerous actions waiting for your click.

This turns the terminal into a backend process and the browser into the command center. That is a superior UX for complex refactoring jobs.

2. Team-Wide Governance

For a solopreneur, this is a productivity hack. For an engineering manager, this is governance.

You could deploy a shared internal tool that acts as the hook endpoint. When a junior dev runs an agent against the repo, the centralized server ensures that no agent can ever run git push --force or delete tables in the dev database. You encode your engineering culture into the middleware that governs your AI agents.

3. The "Human-in-the-Loop" Paradox

We are writing code to manage the code that writes code.

But this layer of indirection is necessary. The raw text output of an LLM is probabilistic. It is a guess. By wrapping that guess in a deterministic HTTP contract, we convert probability into reliable systems. We are building the guardrails that allow us to trust the speed of the engine.

Conclusion

I have been skeptical of the "Agentic Future" where software writes itself while we sip margaritas. That feels like marketing fluff.

A CLI tool that respects HTTP webhooks is tangible. It bridges the gap between the probabilistic output of an LLM and the rigid structure of software engineering.

If you are using Claude Code, stop treating it like a chatbot. Spin up a local server, hook into those events, and start building your own governance layer.