Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

36.8 KB
Raw Blame
<!doctype html>
<html lang="en">
<head>
<!-- Google tag (gtag.js), Google Ads AW-18388216863. Loaded only when Do Not Track is
     off, so it follows the same rule as the PostHog block on this site. -->
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){ dataLayer.push(arguments); }
  if (navigator.doNotTrack !== '1') {
    var gtagScript = document.createElement('script');
    gtagScript.async = true;
    gtagScript.src = 'https://www.googletagmanager.com/gtag/js?id=AW-18388216863';
    document.head.appendChild(gtagScript);
    gtag('js', new Date());
    gtag('config', 'AW-18388216863');
  }
</script>

<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>The Hook Shim Pattern: Wiring Agent Hooks to a Live Process — Munder Difflin Blog</title>
<meta name="description" content="How a tiny shim bridges Claude Code&#39;s lifecycle hooks to one live process over a Unix socket, turning per-event hooks into a telemetry and control channel." />
<link rel="canonical" href="https://munderdiffl.in/blog/the-hook-shim-pattern/" />

<link rel="icon" type="image/png" href="https://munderdiffl.in/logo.png" />
<link rel="apple-touch-icon" href="https://munderdiffl.in/logo.png" />
<meta name="theme-color" content="#F5F2E8" />

<!-- Open Graph -->
<meta property="og:site_name" content="Munder Difflin Blog" />
<meta property="og:type" content="article" />
<meta property="og:title" content="The Hook Shim Pattern: Wiring Agent Hooks to a Live Process — Munder Difflin Blog" />
<meta property="og:description" content="How a tiny shim bridges Claude Code&#39;s lifecycle hooks to one live process over a Unix socket, turning per-event hooks into a telemetry and control channel." />
<meta property="og:url" content="https://munderdiffl.in/blog/the-hook-shim-pattern/" />
<meta property="og:image" content="https://munderdiffl.in/blog/assets/media/the-hook-shim-pattern/hero.png" />
<meta property="og:image:width" content="1600" />
<meta property="og:image:height" content="900" />
<meta property="og:image:alt" content="Illustration: The Hook Shim Pattern: Wiring Agent Hooks to a Live Process" />
<meta property="og:locale" content="en_US" />
<meta property="article:published_time" content="2026-06-04T00:00:00.000Z" />
<meta property="article:author" content="Chaitanya Giri" />
<meta property="article:tag" content="Internals" />
<meta property="article:tag" content="Claude Code" />
<meta property="article:tag" content="Hooks" />
<meta property="article:tag" content="Multi-Agent" />


<!-- Twitter -->
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="The Hook Shim Pattern: Wiring Agent Hooks to a Live Process — Munder Difflin Blog" />
<meta name="twitter:description" content="How a tiny shim bridges Claude Code&#39;s lifecycle hooks to one live process over a Unix socket, turning per-event hooks into a telemetry and control channel." />
<meta name="twitter:image" content="https://munderdiffl.in/blog/assets/media/the-hook-shim-pattern/hero.png" />
<meta name="twitter:image:alt" content="Illustration: The Hook Shim Pattern: Wiring Agent Hooks to a Live Process" />

<link rel="alternate" type="application/atom+xml" title="Munder Difflin Blog" href="https://munderdiffl.in/blog/feed.xml" />
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,[email protected],500;9..144,600;9..144,700;9..144,900&amp;family=Source+Serif+4:opsz,[email protected],400;8..60,600;8..60,700&amp;family=Space+Grotesk:wght@500;600;700&amp;family=JetBrains+Mono:wght@400;600&amp;display=swap" rel="stylesheet" />
<link rel="stylesheet" href="/blog/assets/blog-press.css" />

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "The Hook Shim Pattern: Wiring Agent Hooks to a Live Process",
  "description": "How a tiny shim bridges Claude Code's lifecycle hooks to one live process over a Unix socket, turning per-event hooks into a telemetry and control channel.",
  "image": ["https://munderdiffl.in/blog/assets/media/the-hook-shim-pattern/hero.png"],
  "datePublished": "2026-06-04T00:00:00.000Z",
  "dateModified": "2026-06-04T00:00:00.000Z",
  "author": { "@type": "Person", "name": "Chaitanya Giri" },
  "publisher": {
    "@type": "Organization",
    "name": "Munder Difflin",
    "logo": { "@type": "ImageObject", "url": "https://munderdiffl.in/logo.png" }
  },
  "mainEntityOfPage": { "@type": "WebPage", "@id": "https://munderdiffl.in/blog/the-hook-shim-pattern/" },
  "keywords": "claude code hook shim, claude code hooks architecture, agent lifecycle hooks, unix socket ipc agents",
  "articleSection": "Internals",
  "inLanguage": "en-US",
  "url": "https://munderdiffl.in/blog/the-hook-shim-pattern/"
}
</script>
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://munderdiffl.in/" },
    { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://munderdiffl.in/blog/" },
    { "@type": "ListItem", "position": 3, "name": "The Hook Shim Pattern: Wiring Agent Hooks to a Live Process", "item": "https://munderdiffl.in/blog/the-hook-shim-pattern/" }
  ]
}
</script>

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    { "@type": "Question", "name": "Why not put the logic directly in the hook command?", "acceptedAnswer": { "@type": "Answer", "text": "Because a hook is a per-event shell command, and burying real logic there means editing the user's repo settings, re-installing on every code change, and duplicating state across short-lived processes. A shim forwards the event to one long-running process that holds all the logic — so you change behavior in one place, and the hook config never has to move." } },
    { "@type": "Question", "name": "What does the shim actually do?", "acceptedAnswer": { "@type": "Answer", "text": "Almost nothing, on purpose. It reads the hook payload from stdin, tags it with the agent's id, opens a Unix-domain socket to the main process, writes the payload, relays the response back to stdout, and exits. Every failure path exits 0 so it can never crash the agent's turn." } },
    { "@type": "Question", "name": "Can a hook do more than observe — can it steer the agent?", "acceptedAnswer": { "@type": "Answer", "text": "Yes. Claude Code reads the hook's JSON response, so the main process can reply with a decision — for example {\"decision\":\"block\",\"reason\":\"...\"} on a Stop event to keep the agent working. That's how an autonomous inbox-drain loop is built, guarded so it can never loop forever." } }
    
  ]
}
</script>


<script>
  // Anonymous blog analytics (PostHog) — same posture as the main site and the
  // app's TELEMETRY.md: public write-only token ('' = inert), anonymous-only
  // (person_profiles 'never'), no autocapture/recording, DNT respected.
  (function () {
    var PH_KEY = 'phc_qJzsokwcbtTGHemnvywR3nSqivNNgMjHeNVEWkZNydFB';
    if (!PH_KEY || navigator.doNotTrack === '1') return;
    var s = document.createElement('script');
    s.async = true;
    s.src = 'https://us-assets.i.posthog.com/static/array.js';
    s.onload = function () {
      if (!window.posthog) return;
      window.posthog.init(PH_KEY, {
        api_host: 'https://us.i.posthog.com',
        person_profiles: 'never',
        autocapture: false,
        before_send: function (event) {
          // PostHog fills $ip from the connection unless the event carries one.
          // Null it here and disable the GeoIP lookup so no IP, city, postal
          // code or lat/long is ever derived or stored for this page view.
          if (event && event.properties) {
            event.properties.$ip = null;
            event.properties.$geoip_disable = true;
          }
          return event;
        },
        disable_session_recording: true,
        respect_dnt: true
      });
    };
    document.head.appendChild(s);
  })();
</script>
</head>
<body class="theme-press">
<a class="skip-link" href="#main">Skip to content</a>
<nav id="nav">
  <a class="brand" href="https://munderdiffl.in" aria-label="Munder Difflin home">
    <img class="brand-logo" src="https://munderdiffl.in/logo.png" width="1318" height="840" alt="Munder Difflin, Inc. — Multi-Agent Harness" />
  </a>
  <span class="spacer"></span>
  <div class="links">
    <a href="/blog/">Latest</a>
    <a href="/blog/topics/">Topics</a>
    <a href="/blog/about/">About</a>
    <a href="https://munderdiffl.in">↗ Product</a>
  </div>
  <div class="nav-actions">
    <a class="btn sm" href="https://munderdiffl.in/blog/feed.xml" aria-label="RSS feed">⤵ RSS</a>
    <a class="btn sm primary" href="https://munderdiffl.in/#install">⤓ Download</a>
  </div>
</nav>

<main id="main">

<article class="t-internals">
  <header class="post-head wrap">
    <nav class="crumbs" aria-label="Breadcrumb">
      <a href="/blog/">Blog</a>
      <span>/</span>
      <a href="/blog/topics/internals/">Internals</a>
    </nav>
    <h1>The Hook Shim Pattern: Wiring Agent Hooks to a Live Process</h1>
    <p class="dek">How a tiny shim bridges Claude Code&#39;s lifecycle hooks to one live process over a Unix socket, turning per-event hooks into a telemetry and control channel.</p>
    <div class="byline">
      <span class="av" aria-hidden="true">CG</span>
      <strong>Chaitanya Giri</strong>
      <span class="dot" aria-hidden="true">·</span>
      <time datetime="2026-06-04">Jun 4, 2026</time>
      <span class="dot" aria-hidden="true">·</span>
      <span>6 min read</span>
      <span class="tag kind">Internals</span>
    </div>
  </header>

  <div class="hero-wrap wrap"><figure class="fig fig-hero"><img src="/blog/assets/media/the-hook-shim-pattern/hero.png" alt="Illustration: The Hook Shim Pattern: Wiring Agent Hooks to a Live Process" loading="lazy" decoding="async" /></figure></div>

  <div class="post-wrap wrap">
    <div class="prose">
      <div class="callout tldr"><span class="ic">TL;DR</span><p>Claude Code fires <strong>lifecycle hooks</strong>
(Stop, PreToolUse, Notification…) as shell commands. Putting real logic in those commands is a trap —
it's per-event, lives in the user's repo, and can't share state. The <strong>hook shim pattern</strong>
fixes it: each hook runs a tiny shim that forwards its payload over a <strong>Unix-domain socket</strong>
to one long-running process holding all the logic. The shim is a dumb pipe that never crashes a turn; the
main process gets a live telemetry feed <em>and</em> a control channel back.</p></div>
<p><a href="/blog/claude-code-hooks-explained/">Claude Code hooks</a> are a great extension point: at defined moments —
a tool is about to run, the agent stopped, a notification fired — Claude Code runs a shell command you
configure, hands it a JSON payload on stdin, and reads a JSON response from stdout. Simple and powerful.</p>
<p>The trap is doing the work <em>in</em> that command. If you’re building something live — a UI that shows what
each agent is doing, an autonomous loop that re-engages an idle agent — a per-event shell script is the
wrong home for that logic. Here’s the pattern we use instead, and why it holds up.</p>
<h2 id="why-logic-in-the-hook-doesnt-scale" tabindex="-1">Why logic-in-the-hook doesn’t scale <a class="anchor" href="#why-logic-in-the-hook-doesnt-scale" aria-hidden="true">#</a></h2>
<p>A hook command has three problems as a place for real behavior:</p>
<ul>
<li><strong>It’s short-lived.</strong> Each event spawns a fresh process that dies immediately. There’s nowhere to keep
state — avatar status, a per-agent cursor, an event log — without re-reading it from disk every time.</li>
<li><strong>It lives in the user’s settings.</strong> Hook config is attached to a session via <code>--settings</code>. Bake logic
in and every code change means rewriting that config; it also can’t easily reach your app’s in-memory
state.</li>
<li><strong>It’s risky.</strong> A hook that throws or hangs can stall the agent. Logic and the agent’s turn shouldn’t
share a failure mode.</li>
</ul>
<p>You want the <em>trigger</em> to stay at the edge and the <em>logic</em> to live in one place. That’s exactly what a
shim buys you.</p>
<h2 id="the-shim-a-dumb-pipe" tabindex="-1">The shim: a dumb pipe <a class="anchor" href="#the-shim-a-dumb-pipe" aria-hidden="true">#</a></h2>
<p>The harness writes a tiny script — <code>cth-hook.cjs</code> — into the hive directory and points every hook at it.
Its entire job is to forward:</p>
<pre class="language-javascript"><code class="language-javascript"><span class="token comment">// read the hook payload on stdin, tag it, forward to the socket, relay the reply</span>
<span class="token keyword">const</span> net <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">'net'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">let</span> data <span class="token operator">=</span> <span class="token string">''</span><span class="token punctuation">;</span>
process<span class="token punctuation">.</span>stdin<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'data'</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token parameter">d</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span> data <span class="token operator">+=</span> d<span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
process<span class="token punctuation">.</span>stdin<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'end'</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
  <span class="token keyword">const</span> payload <span class="token operator">=</span> <span class="token constant">JSON</span><span class="token punctuation">.</span><span class="token function">parse</span><span class="token punctuation">(</span>data <span class="token operator">||</span> <span class="token string">'{}'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  payload<span class="token punctuation">.</span>agent_id <span class="token operator">||=</span> process<span class="token punctuation">.</span>env<span class="token punctuation">.</span><span class="token constant">AGENT_ID</span><span class="token punctuation">;</span>
  <span class="token keyword">const</span> sock <span class="token operator">=</span> process<span class="token punctuation">.</span>env<span class="token punctuation">.</span><span class="token constant">HIVE_SOCK</span><span class="token punctuation">;</span>
  <span class="token keyword">if</span> <span class="token punctuation">(</span><span class="token operator">!</span>sock<span class="token punctuation">)</span> process<span class="token punctuation">.</span><span class="token function">exit</span><span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token keyword">const</span> c <span class="token operator">=</span> net<span class="token punctuation">.</span><span class="token function">createConnection</span><span class="token punctuation">(</span>sock<span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> c<span class="token punctuation">.</span><span class="token function">write</span><span class="token punctuation">(</span><span class="token constant">JSON</span><span class="token punctuation">.</span><span class="token function">stringify</span><span class="token punctuation">(</span>payload<span class="token punctuation">)</span> <span class="token operator">+</span> <span class="token string">'\n'</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token keyword">let</span> resp <span class="token operator">=</span> <span class="token string">''</span><span class="token punctuation">;</span>
  c<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'data'</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token parameter">d</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span> resp <span class="token operator">+=</span> d<span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  c<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'end'</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span> <span class="token keyword">if</span> <span class="token punctuation">(</span>resp<span class="token punctuation">)</span> process<span class="token punctuation">.</span>stdout<span class="token punctuation">.</span><span class="token function">write</span><span class="token punctuation">(</span>resp<span class="token punctuation">)</span><span class="token punctuation">;</span> process<span class="token punctuation">.</span><span class="token function">exit</span><span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  c<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'error'</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> process<span class="token punctuation">.</span><span class="token function">exit</span><span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token function">setTimeout</span><span class="token punctuation">(</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> process<span class="token punctuation">.</span><span class="token function">exit</span><span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token number">5000</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">unref</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span></code></pre>
<p>Notice what it does <em>not</em> do: no decisions, no disk, no state. It tags the payload with the agent’s id
(from an env var the agent was spawned with), opens a Unix-domain socket to the main process, writes one
line of JSON, and relays whatever comes back. And notice the guards — missing socket, connection error,
and a 5-second timeout all <code>exit(0)</code>. <strong>The shim can never crash the agent’s turn.</strong> That’s the contract.</p>
<figure class="fig fig-inline"><img src="/blog/assets/media/the-hook-shim-pattern/note-1.png" alt="Hand-drawn sketch from “The Hook Shim Pattern: Wiring Agent Hooks to a Live Process”" loading="lazy" decoding="async" /></figure>
<h2 id="all-the-logic-lives-in-one-process" tabindex="-1">All the logic lives in one process <a class="anchor" href="#all-the-logic-lives-in-one-process" aria-hidden="true">#</a></h2>
<p>On the other end, the app’s main process listens on that socket and holds everything:</p>
<pre class="language-javascript"><code class="language-javascript"><span class="token keyword">const</span> server <span class="token operator">=</span> <span class="token function">createServer</span><span class="token punctuation">(</span><span class="token punctuation">(</span><span class="token parameter">conn</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
  <span class="token keyword">let</span> buf <span class="token operator">=</span> <span class="token string">''</span><span class="token punctuation">;</span>
  conn<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'data'</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token parameter">d</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
    buf <span class="token operator">+=</span> d<span class="token punctuation">.</span><span class="token function">toString</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
    <span class="token keyword">const</span> nl <span class="token operator">=</span> buf<span class="token punctuation">.</span><span class="token function">indexOf</span><span class="token punctuation">(</span><span class="token string">'\n'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
    <span class="token keyword">if</span> <span class="token punctuation">(</span>nl <span class="token operator">===</span> <span class="token operator">-</span><span class="token number">1</span><span class="token punctuation">)</span> <span class="token keyword">return</span><span class="token punctuation">;</span>                 <span class="token comment">// wait for the full line</span>
    <span class="token keyword">const</span> payload <span class="token operator">=</span> <span class="token constant">JSON</span><span class="token punctuation">.</span><span class="token function">parse</span><span class="token punctuation">(</span>buf<span class="token punctuation">.</span><span class="token function">slice</span><span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">,</span> nl<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
    conn<span class="token punctuation">.</span><span class="token function">end</span><span class="token punctuation">(</span><span class="token constant">JSON</span><span class="token punctuation">.</span><span class="token function">stringify</span><span class="token punctuation">(</span><span class="token function">handle</span><span class="token punctuation">(</span>payload<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
server<span class="token punctuation">.</span><span class="token function">listen</span><span class="token punctuation">(</span>sockPath<span class="token punctuation">)</span><span class="token punctuation">;</span></code></pre>
<p><code>handle()</code> is where the real work happens — and because it’s one resident process, it can keep live state
the per-event hooks never could. PreToolUse / PostToolUse / Notification events drive each agent’s avatar
on the <a href="/blog/visualizing-ai-agents-pixijs/">office floor</a>; the same feed can append to an
<a href="/blog/append-only-event-log-agents/">event log</a>. The hooks settings route all the relevant events
(<code>Stop</code>, <code>SubagentStop</code>, <code>PreToolUse</code>, <code>PostToolUse</code>, <code>UserPromptSubmit</code>, <code>Notification</code>, <code>SessionStart</code>)
through the one shim, so the main process sees the whole lifecycle of every agent in real time.</p>
<h2 id="the-real-payoff-a-control-channel-not-just-telemetry" tabindex="-1">The real payoff: a control channel, not just telemetry <a class="anchor" href="#the-real-payoff-a-control-channel-not-just-telemetry" aria-hidden="true">#</a></h2>
<p>Because Claude Code reads the hook’s JSON <em>response</em>, the shim isn’t a one-way feed — it’s a round trip.
The main process can answer. That’s what turns observation into control.</p>
<p>The clearest example is the autonomous loop. When an agent hits <code>Stop</code>, the main process checks that
agent’s <a href="/blog/atomic-file-mailboxes-for-agents/">inbox</a>. If a message is waiting, it replies with
<code>{&quot;decision&quot;:&quot;block&quot;,&quot;reason&quot;:&quot;&lt;the message&gt;&quot;}</code> — and Claude Code keeps the agent working to handle it
instead of going idle. An agent that another agent (or the <a href="/blog/how-the-god-orchestrator-works/">orchestrator</a>)
just messaged picks the work up on its own.</p>
<p>The danger with any “keep going” mechanism is an infinite loop, so the payload carries a <code>stop_hook_active</code>
flag: if a previous Stop already blocked this turn, the process lets the agent stop. Re-engage once, never
forever. A genuine stop with an empty inbox falls through to a desktop “idle” notification.</p>
<figure class="fig fig-inline"><img src="/blog/assets/media/the-hook-shim-pattern/note-2.png" alt="Hand-drawn sketch from “The Hook Shim Pattern: Wiring Agent Hooks to a Live Process”" loading="lazy" decoding="async" /></figure>
<h2 id="why-this-pattern-is-worth-copying" tabindex="-1">Why this pattern is worth copying <a class="anchor" href="#why-this-pattern-is-worth-copying" aria-hidden="true">#</a></h2>
<p>If you’re wiring agent lifecycle hooks into anything stateful, the shim pattern gives you four things at
once: <strong>decoupling</strong> (refresh the shim from code on startup; the session’s hook config never moves),
<strong>a single source of truth</strong> (one process, real in-memory state), <strong>safety</strong> (the edge can fail without
stalling the agent), and <strong>a control channel</strong> (reply with a decision, don’t just log). The trigger stays
tiny and dumb; the brains stay in one testable place.</p>
<h2 id="faq" tabindex="-1">FAQ <a class="anchor" href="#faq" aria-hidden="true">#</a></h2>
<p><strong>Why a Unix socket and not HTTP?</strong> It’s local-only, fast, and needs no port or auth — the shim and the
app are on the same machine. The payload is one line of newline-delimited JSON, so framing is trivial.</p>
<p><strong>What happens if the main app isn’t running?</strong> The shim finds no socket (or fails to connect) and exits
0. The agent’s turn proceeds normally; you lose telemetry for that event, not the agent.</p>
<p><strong>Does this only work for Claude Code?</strong> The pattern is general: any tool that runs a command per event
and reads a response can be bridged this way. Claude Code’s hook payloads and decision response just make
it a clean fit.</p>
<hr>
<p>Munder Difflin uses exactly this shim to drive a live office floor and an autonomous inbox-drain loop for a
whole <a href="https://munderdiffl.in/#how">hive of Claude Code agents</a> — all local, with the agent’s turn never
at the mercy of the bridge.
<a href="https://munderdiffl.in/#install">Download Munder Difflin</a> to see it run; it’s free and open source.</p>


      
      <section class="faq" aria-label="Frequently asked questions">
        <h2 id="faq">FAQ</h2>
        
        <div class="qa">
          <p class="q">Why not put the logic directly in the hook command?</p>
          <p class="a">Because a hook is a per-event shell command, and burying real logic there means editing the user&#39;s repo settings, re-installing on every code change, and duplicating state across short-lived processes. A shim forwards the event to one long-running process that holds all the logic — so you change behavior in one place, and the hook config never has to move.</p>
        </div>
        
        <div class="qa">
          <p class="q">What does the shim actually do?</p>
          <p class="a">Almost nothing, on purpose. It reads the hook payload from stdin, tags it with the agent&#39;s id, opens a Unix-domain socket to the main process, writes the payload, relays the response back to stdout, and exits. Every failure path exits 0 so it can never crash the agent&#39;s turn.</p>
        </div>
        
        <div class="qa">
          <p class="q">Can a hook do more than observe — can it steer the agent?</p>
          <p class="a">Yes. Claude Code reads the hook&#39;s JSON response, so the main process can reply with a decision — for example {&quot;decision&quot;:&quot;block&quot;,&quot;reason&quot;:&quot;...&quot;} on a Stop event to keep the agent working. That&#39;s how an autonomous inbox-drain loop is built, guarded so it can never loop forever.</p>
        </div>
        
      </section>
      

      
      <hr />
      <div class="share">
        <span class="lbl">Tags</span>
        <a class="tag" href="/blog/tags/internals/">Internals</a><a class="tag" href="/blog/tags/claude-code/">Claude Code</a><a class="tag" href="/blog/tags/hooks/">Hooks</a><a class="tag" href="/blog/tags/multi-agent/">Multi-Agent</a>
      </div>
      
    </div>

    
    <aside class="toc-rail" aria-label="Table of contents">
      <div class="tt">On this page</div>
      <ol>
        <li class="lvl-2"><a href="#why-logic-in-the-hook-doesnt-scale">Why logic-in-the-hook doesn’t scale</a></li><li class="lvl-2"><a href="#the-shim-a-dumb-pipe">The shim: a dumb pipe</a></li><li class="lvl-2"><a href="#all-the-logic-lives-in-one-process">All the logic lives in one process</a></li><li class="lvl-2"><a href="#the-real-payoff-a-control-channel-not-just-telemetry">The real payoff: a control channel, not just telemetry</a></li><li class="lvl-2"><a href="#why-this-pattern-is-worth-copying">Why this pattern is worth copying</a></li><li class="lvl-2"><a href="#faq">FAQ</a></li>
      </ol>
    </aside>
    
  </div>

  <footer class="post-foot wrap"><div class="prevnext">
      <a class="pn prev" href="/blog/the-lethal-trifecta-for-coding-agents/"><span class="k">← Older</span><span class="t">The Lethal Trifecta for Coding Agents</span></a>
      <a class="pn next" href="/blog/small-team-ai-agents-playbook/"><span class="k">Newer →</span><span class="t">A Small-Team Playbook for AI Coding Agents</span></a>
    </div>
    <section class="related">
      <h2>Related in Internals</h2>
      <div class="post-grid">
        <article class="card t-internals">
  <a class="thumb t-internals" href="/blog/the-spend-counter-that-went-back-to-zero/" aria-hidden="true" tabindex="-1"><img src="/blog/assets/media/the-spend-counter-that-went-back-to-zero/hero.png" alt="" loading="lazy" decoding="async" /></a>
  <div class="body">
    <div class="meta">
      <time datetime="2026-08-22">Aug 22, 2026</time>
      <span class="dot" aria-hidden="true"></span>
      <span>10 min</span>
    </div>
    <h3><a href="/blog/the-spend-counter-that-went-back-to-zero/">The Spend Counter That Went Back to Zero</a></h3>
    <p class="dek">Our own floor was under reporting what it cost by 59 percent. The counter was cumulative since process start, the app restarts, and the session id stayed the same. Here is how a monotonic invariant let us recover the real number from an append-only log.</p>
    <div class="foot">
      <span class="tag kind">Internals</span>
      <a class="more" href="/blog/the-spend-counter-that-went-back-to-zero/" aria-label="Read: The Spend Counter That Went Back to Zero">Read →</a>
    </div>
  </div>
</article>
<article class="card t-internals">
  <a class="thumb t-internals" href="/blog/the-newline-that-silenced-windows-agents/" aria-hidden="true" tabindex="-1"><img src="/blog/assets/media/the-newline-that-silenced-windows-agents/hero.png" alt="" loading="lazy" decoding="async" /></a>
  <div class="body">
    <div class="meta">
      <time datetime="2026-08-19">Aug 19, 2026</time>
      <span class="dot" aria-hidden="true"></span>
      <span>4 min</span>
    </div>
    <h3><a href="/blog/the-newline-that-silenced-windows-agents/">The Newline That Silenced Every Windows Agent</a></h3>
    <p class="dek">A cmd.exe parsing rule from the 1980s meant Windows agents received exactly one line of their multi-line startup protocol — and nothing errored. The anatomy of our worst silent failure, and the fix.</p>
    <div class="foot">
      <span class="tag kind">Internals</span>
      <a class="more" href="/blog/the-newline-that-silenced-windows-agents/" aria-label="Read: The Newline That Silenced Every Windows Agent">Read →</a>
    </div>
  </div>
</article>
<article class="card t-internals">
  <a class="thumb t-internals" href="/blog/why-our-auto-update-never-ran/" aria-hidden="true" tabindex="-1"><img src="/blog/assets/media/why-our-auto-update-never-ran/hero.png" alt="" loading="lazy" decoding="async" /></a>
  <div class="body">
    <div class="meta">
      <time datetime="2026-08-08">Aug 8, 2026</time>
      <span class="dot" aria-hidden="true"></span>
      <span>5 min</span>
    </div>
    <h3><a href="/blog/why-our-auto-update-never-ran/">Our Auto-Update Never Ran Once: A CommonJS Export That Vanished Into an ESM Namespace</a></h3>
    <p class="dek">Munder Difflin shipped auto-update in v0.3.4 and it silently never worked in a single packaged build. The cause was one destructuring assignment across the CommonJS/ESM boundary — and a catch block that threw the evidence away. Here&#39;s how we found it, and what v0.3.7 changes.</p>
    <div class="foot">
      <span class="tag kind">Internals</span>
      <a class="more" href="/blog/why-our-auto-update-never-ran/" aria-label="Read: Our Auto-Update Never Ran Once: A CommonJS Export That Vanished Into an ESM Namespace">Read →</a>
    </div>
  </div>
</article>

      </div>
    </section>
    
  </footer>
</article>

</main>
<footer class="site-foot">
  <div class="wrap">
    <div class="foot-top">
      <a class="foot-brand brand" href="https://munderdiffl.in" aria-label="Munder Difflin home">
        <img class="brand-logo" src="https://munderdiffl.in/logo.png" width="1318" height="840" alt="Munder Difflin, Inc. — Multi-Agent Harness" />
      </a>
      <div class="foot-links">
        <a href="/blog/">Latest</a>
        <a href="/blog/topics/">Topics</a>
        <a href="/blog/about/">About</a>
        <a href="https://munderdiffl.in/blog/feed.xml">RSS</a>
        <a href="https://github.com/chaitanyagiri/munder-difflin">GitHub</a>
        <a href="https://munderdiffl.in">munderdiffl.in ↗</a>
      </div>
    </div>
    <div class="foot-meta">
      © 2026 Munder Difflin · Local-first · MIT-licensed ·
      Built on <a href="https://munderdiffl.in">Electron, React, Pixi.js, xterm.js &amp; node-pty</a>.
      Run an office of agents while you sleep.
    </div>
  </div>
</footer>

<script>
  // sticky-nav border on scroll
  (function () {
    var nav = document.getElementById('nav');
    if (!nav) return;
    var onScroll = function () { nav.classList.toggle('scrolled', window.scrollY > 8); };
    onScroll(); window.addEventListener('scroll', onScroll, { passive: true });
  })();
  // YouTube click-to-load: thumbnail button → youtube-nocookie iframe
  (function () {
    document.addEventListener('click', function (e) {
      var btn = e.target.closest('.yt-load');
      if (!btn) return;
      var box = btn.closest('.yt');
      var id = box && box.getAttribute('data-yt');
      // Only an 11 character YouTube video id may reach the iframe URL.
      if (!id || !/^[A-Za-z0-9_-]{11}$/.test(id)) return;
      var frame = document.createElement('iframe');
      frame.src = 'https://www.youtube-nocookie.com/embed/' + encodeURIComponent(id) + '?autoplay=1';
      frame.title = box.getAttribute('data-title') || 'YouTube video';
      frame.allow = 'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share';
      frame.setAttribute('allowfullscreen', '');
      box.replaceChildren(frame);
    });
  })();
</script>

</body>
</html>