Claude Code te deja meter tu código dentro: un middleware ($, e, next) que intercepta cada tool call, dibuja UI y reescribe comandos - Mods

Claude Code ahora te deja meter tu código dentro: un middleware ($, e, next) que intercepta cada tool call, dibuja UI y reescribe comandos

Claude Code 2.1.287 añadió algo que no existía: mods. Un mod es un plugin cuyo comportamiento vive en un módulo de TypeScript que corre dentro del motor de Claude Code y se engancha a sus eventos con una función de middleware: ($, e, next). No es un settings hook que corre por fuera y habla por JSON: es tu código dentro de la sesión, que puede cambiar un tool call antes de que corra, dibujar un pane a su lado, o responder el evento tú mismo en su lugar.

La noticia: es oficial de Anthropic, está publicado (el código de los 4 mods que shippean dentro va en anthropics/claude-code/mods), y la forma es exactamente la de Express o Koa: si has escrito middleware, ya sabes lo que es un mod.

La forma: tres valores, tres jugadas

Cada hook recibe tres cosas:

• $ — la API del motor: $.ui, $.fs, $.http, $.process, $.command, $.model… la única puerta (el módulo no tiene filesystem ni red propios).
• e — el evento, como datos congelados (tool.call, prompt.submit, turn.complete, ui.render… ~125 eventos).
• next(e) — el tramo de middleware: lo que le pasas a next es lo que Claude Code ejecuta de verdad. Si no llamas next() y devuelves tú, respondes el evento en su lugar.

Tres movimientos cubren el 95% de los casos (confirmado en las guías de claude.dev y en el repo oficial):

Jugada	Cómo	Qué
Observar	const r = await next(e); /* mirar */ return r	Audit, métricas, leer un fichero
Reescribir	return next({ ...e, command: masSeguro })	Cambiar lo que ve el resto de la cadena
Responder	return { deny: 'razón' } sin next	Refusar un tool call / servir tú la respuesta

Ejemplo 1: un guard que no se salta (patrón secret-redactor / em-dash-fixer)

El patrón —agarrar un tool.call, inspeccionar su argumento y responder tú o pasarle a next una copia modificada— es el mismo que usa el mod em-dash-fixer documentado en claudecodeguide.dev y el secret-redactor del catálogo de aitmpl.com. Aquí lo aplico a bloquear comandos destructivos antes de que corran:

// hooks/register.ts  (hooks.json → { "modules": ["./register.ts"] })
import type { Register } from 'claude-code';

export const register: Register = (on) => {
  on('tool.call', { tool: 'Bash' }, ($, e, next) => {
    // Comandos con riesgo: responder nosotros, no corre
    if (/(rm -rf|git push -f|drop database)/.test(e.command ?? '')) {
      return { deny: 'Bloqueado por el guard: comando destructivo sin confirmación' }
    }
    // Lo demás pasa tal cual
    return next(e)
  })
}

Un tool.call sobre Bash ve e.command como campo propio. Si no llamas next() y devuelves { deny }, la cadena se corta ahí: no aparece el prompt de permisos, la herramienta no corre y lo único que el modelo sabe es tu texto. Eso es un guard, no una regla que el agente puede olvidar.

Ejemplo 2: dibujar tu propia UI sobre el prompt (Token Weather)

El mod Token Weather de Addy Osmani (~80 líneas) dibuja una banda sobre el prompt con el estado vivo de tu contexto. El truco es engancharte al evento ui.render filtrado por el sitio de render AbovePrompt y devolver un árbol de elementos en vez de llamar next():

on('ui.render', { component: 'AbovePrompt' }, async ($, e) => {
  const pct = await $.session.usage()            // % de contexto usado
  const { Box, Text } = $.ui.resolve(e)
  const level = pct > 80 ? 'Storm' : pct > 50 ? 'Showers' : 'Clear'
  return Box({ paddingX: 1,
    children: [ Text({ color: 'yellow', bold: true,
                       children: level + ' ' + Math.round(pct) + '%' }) ] })
})

$.ui.resolve(e) te da la tabla de elementos de la superficie (terminal o desktop) en la que estás dibujando. Y como ui.render no tiene efecto de lado del motor, devolver tu árbol reemplaza lo que Claude Code habría dibujado ahí. Así tienes una métrica viva —tokens, tiempo del turno, llamadas a herramientas— que se refresca sola.

Qué viene ya integrado (código de Anthropic)

El repo oficial shippea cuatro mods que puedes leer como referencia y cargar con claude --plugin-dir mods/diff:

• diff — /diff: tus cambios sin commitear en un pane al lado del transcripto, fichero a fichero, actualizado en vivo.
• sec-default — mantiene las políticas y deny rules de una organización fuera del alcance de los plugins que instala la gente.
• agents-md — carga AGENTS.md como instrucciones de proyecto.
• telemetry — el noun de analytics first-party.

Por qué te importa (y qué llevarte)

Claude Code pasó de una caja negra a un motor event-driven que puedes envolver. Eso desbloquea lo que un prompt no puede: un guard que no se salta, una UI propia que ves cada turno, y una auditoría de todo lo que el agente toca — con la misma disciplina de middleware que ya usas en Express. Los hooks clásicos de settings corrían por fuera y perdían estado entre eventos; un mod permanece en la sesión, mantiene variables y devuelve al motor cuando quiere.

La escala es la que tú decides: un guard de 25 líneas para los comandos que te asustan, o un panel para mirar tus subagents. En Codeia montamos estos sistemas agénticos con rastro y checkpoints — el patrón que Anthropic acaba de hacer extensible a cualquier proyecto. Si quieres ver un mod funcionando sobre una app real, en la comunidad lo montamos junto a otros.

Fuente

Repositorio oficial anthropics/claude-code/mods (los 4 mods integrados y sus tests); guía de claude.dev (Token Weather, Blast Radius); claudemods.dev; claudecodeguide.dev (em-dash-fixer). La mecánica base viene del vídeo de Lily Hallie; los ejemplos de este post son de las fuentes anteriores, verificados contra el repo de Anthropic. Requiere Claude Code 2.1.287+ (los mods van por defecto).