Claude Code Mods in TypeScript: Production Guardrails for Next.js Teams (2026)

3. Plugin Layout

Claude Code loads .js, .mjs, and .ts directly. You do not need Node, a bundler, or a build step for the mod itself. This layout matches the official create-a-mod tutorial:

next-guard/
  .claude-plugin/plugin.json
  hooks/hooks.json
  hooks/register.ts

Check the CLI before you start. Mods require Claude Code v2.1.287 or later:

claude --version

4. Step-by-Step Implementation

4.1 Manifest

Save this as next-guard/.claude-plugin/plugin.json. The manifest is an ordinary plugin manifest. The modules entry in hooks.json is what makes it a mod.

{
  "name": "next-guard",
  "version": "0.1.0",
  "description": "Blocks force-pushes, asks before destructive shell commands, and redacts secrets from tool output.",
  "author": { "name": "Your Team" }
}

4.2 Point Claude Code at the module

Save this as next-guard/hooks/hooks.json:

{
  "description": "Next.js repo guardrails",
  "modules": ["./register.ts"]
}

4.3 The hooks module

Save this as next-guard/hooks/register.ts. The patterns below are taken from the official events guide: matchers, { deny }, $.ui.ask, and post-tool result rewriting. The secret scan is local string replacement. It is a backstop, not a guarantee that a secret never existed on disk.

const FORCE_PUSH = /git push\b[\s\S]*--force|git push\b[\s\S]*\s-f\b/
const RISKY = /\brm\s+-rf?\b|\bgit\s+reset\s+--hard\b|\bprisma\s+migrate\s+reset\b|\bdropdb\b/

const SECRET = /(sk-[A-Za-z0-9_\-]{20,}|postgres(?:ql)?:\/\/\S+|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]+PRIVATE KEY-----)/g

function scrub(value: string): string {
  return value.replace(SECRET, '[redacted]')
}

export function register(on: Function) {
  on('tool.call', { tool: 'Bash' }, async ($: any, e: any, next: Function) => {
    const command = String(e.command ?? '')

    if (FORCE_PUSH.test(command)) {
      return {
        deny: 'Force pushes are blocked by next-guard. Push a new branch and open a pull request.'
      }
    }

    if (!RISKY.test(command)) return next(e)

    let answer = 'Refuse'
    try {
      answer = await $.ui.ask('Run this command? ' + command, ['Run it', 'Refuse'])
    } catch {
      // Dismissed dialog, or a headless claude -p run with nobody to ask.
    }

    if (answer !== 'Run it') {
      return {
        deny: 'The user declined this command. Propose a narrower command or ask first.'
      }
    }

    return next(e)
  })

  on('tool.call', { tool: ['Edit', 'Write'] }, async ($: any, e: any, next: Function) => {
    const filePath = String(e.file_path ?? '')
    if (/(^|\/)\.env(\..*)?$/.test(filePath) || filePath.includes('secrets/')) {
      return {
        deny: 'next-guard blocks writes to env and secrets paths. Edit those files yourself.'
      }
    }
    return next(e)
  })

  on('tool.call', async (_$: any, e: any, next: Function) => {
    const result = await next(e)
    if (!result || typeof result !== 'object') return result
    const text = typeof result.result === 'string' ? result.result : ''
    if (!text || !SECRET.test(text)) return result
    SECRET.lastIndex = 0
    return { ...result, result: scrub(text) }
  })

  on('tool.check', { tool: 'Bash' }, async ($: any, e: any, next: Function) => {
    const decided = await next(e)
    const command = String(e.input?.command ?? '')
    if (!command.includes('git push')) return decided
    const branch = await $.process.run(['git', 'branch', '--show-current'])
    if (String(branch.stdout ?? '').trim() !== 'main') return decided
    return { decision: 'deny', reason: 'Push from a branch other than main.' }
  })
}

What each hook does:

• The Bash tool.call hook answers force-pushes itself, so the command never runs and no permission prompt appears. For rm -rf, git reset --hard, prisma migrate reset, and dropdb, it waits on $.ui.ask. Official docs say time spent inside a mods API call does not count against the hook time limit. A custom promise does. Default the answer to refuse so a headless claude -p run cannot click through.
• The Edit/Write hook refuses paths that look like env files. Do this in the mod and also keep those files out of the worktree the agent can see.
• The unfiltered tool.call hook runs after next and rewrites string results that match a small secret pattern. Later mods see the event first if they loaded earlier; stack order is load order. Put the redaction mod early if you want it to see raw output, and remember that a deny from an earlier hook never reaches this one.
• The tool.check hook refuses git push while the current branch is main. This is a reminder for the agent. Protect main on the Git host as well. A text match misses git -C ../other push and shell wrappers.

4.4 Load it

Start a session with the plugin directory. Claude Code watches that directory and hot-reloads when the module changes. Module-level variables reset on reload; use plugin state if you need a counter to survive a save.

claude --plugin-dir ./next-guard

Ask the agent to run git push --force on a throwaway branch. The command should not run, and the transcript should show the deny text. Ask it to print a fake sk- token from a fixture file and confirm the model’s next turn sees [redacted]. Then open /plugin, select Installed, and confirm you can disable the mod.

4.5 Share it

A mod Claude writes into ~/.claude/dev-mods// loads only in that session, and Claude Code deletes the folder after cleanupPeriodDays. Copy the directory into the repo, for example tools/next-guard, and document the launch flag. To publish it, package the plugin and submit it to the Claude plugin directory. Teammates should review the module in the same pull request as any other executable.