How to Build Your First Claude Code Mod: A Worked Example

Claude Code 2.1.287 added Mods on October 1, 2026: plugins whose JavaScript or TypeScript functions run inside Claude Code and can change what happens on events such as a tool call. This tutorial builds one that hides API keys and private keys from the output of shell commands and file reads before Claude sees them. We built and ran every step on Claude Code 2.1.288 on October 3, including a bug our tests missed and a live session caught.

When Claude runs cat .env or reads a config file, the output goes into the conversation, keys included. Our mod sits around every Bash and Read call, lets the tool run, and replaces anything that looks like a secret with [REDACTED] before Claude reads the result. The secret stays in the file on disk; Claude never sees it.

Claude Code’s older settings hooks can also replace a tool’s output, so a mod is not the only way to do this. A mod has two advantages for a job like this: the logic is ordinary TypeScript in one file, and Claude Code ships a test kit that runs it without a session. Our explainer on Claude Code Mods covers what else they can do, and our comparison of hooks across 12 coding agents shows which other tools can rewrite output the same way.

A mod is a plugin directory. Mods need Claude Code 2.1.287 or later; run claude --version to check. Create this layout anywhere outside your project:

redact-secrets/
├── .claude-plugin/
│   └── plugin.json
├── hooks/
│   ├── hooks.json
│   └── register.ts
└── tests/
    └── redact.test.ts

The manifest, .claude-plugin/plugin.json, needs no fields specific to mods:

{
  "name": "redact-secrets",
  "version": "0.1.0",
  "description": "Replaces API keys and private keys in tool output before Claude reads them",
  "author": { "name": "Your Name" }
}

hooks/hooks.json is what makes the plugin a mod. Its modules key points to the code file, and the mods reference accepts a TypeScript file; our .ts module ran without a build step:

{
  "description": "The redact-secrets hooks module",
  "modules": ["./register.ts"]
}

Save this as hooks/register.ts. Claude Code calls register once when the mod loads, and the tool.call hook runs around every Bash and Read call. Calling await next(e) runs the permission check and the tool; the hook then returns a redacted copy of what came back.

// Patterns for common secret formats. Extend this list for your own keys.
const PATTERNS: RegExp[] = [
  /sk-[A-Za-z0-9_-]{20,}/g, // OpenAI- and Anthropic-style API keys
  /AKIA[0-9A-Z]{16}/g, // AWS access key IDs
  /gh[pousr]_[A-Za-z0-9]{36,}/g, // GitHub tokens
  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
]

// Replace secrets in every string inside a value, counting replacements
function redact(value: unknown, hits: { count: number }): unknown {
  if (typeof value === 'string') {
    let out = value
    for (const pattern of PATTERNS) {
      out = out.replace(pattern, () => {
        hits.count += 1
        return '[REDACTED]'
      })
    }
    return out
  }
  if (Array.isArray(value)) return value.map((item) => redact(item, hits))
  if (value && typeof value === 'object') {
    return Object.fromEntries(
      Object.entries(value).map(([key, item]) => [key, redact(item, hits)]),
    )
  }
  return value
}

export function register(on) {
  // Runs around every Bash and Read call
  on('tool.call', { tool: ['Bash', 'Read'] }, async ($, e, next) => {
    // Let the tool run, then inspect what it returned
    const result = await next(e)
    // Leave refused calls alone
    if (result.deny) return result
    const hits = { count: 0 }
    // Build a redacted copy rather than editing the result in place
    const cleaned = redact(result, hits)
    if (hits.count === 0) return result
    // A dim line in the transcript that Claude doesn't read
    $.ui.log('redact-secrets: hid ' + hits.count + ' secret(s) from ' + e.tool)
    return cleaned
  })
}

Three details matter. The event arrives frozen, and the hook builds a copy of the result rather than editing it in place. A refused call comes back as { deny } and is left alone. And $.ui.log adds a dim line to the transcript that tells you something was hidden, without telling Claude.

{
  "ref": 1,
  "result": {
    "stdout": "APP_NAME=demo\nOPENAI_API_KEY=sk-fake…\nDEBUG=true",
    "stderr": "",
    "interrupted": false,
    "isImage": false,
    "noOutputExpected": false
  },
  "text": "APP_NAME=demo\nOPENAI_API_KEY=sk-fake…\nDEBUG=true",
  "isReadOnly": true
}

Claude Code’s test kit fires events through your hooks with no model, network or sign-in. Each test stubs what Claude Code would answer, here a tool result shaped like the real one, and checks what the mod returns. Save this as tests/redact.test.ts:

import { expect, test } from 'claude-code/testing'

test('an API key in Bash output is replaced', async ($, on) => {
  // Stand in for Bash: the "tool" returns a line containing a key
  on('tool.call', () => ({
    result: { stdout: 'OPENAI_API_KEY=sk-test1234567890abcdefghijklmn' },
    text: 'OPENAI_API_KEY=sk-test1234567890abcdefghijklmn',
  }))
  // Answer the mod's $.ui.log call
  on('ui.log', () => ({ value: undefined }))
  const result = await $.tool.call({ tool: 'Bash', command: 'cat .env' })
  expect(result.text).toBe('OPENAI_API_KEY=[REDACTED]')
  expect(result.result.stdout).toBe('OPENAI_API_KEY=[REDACTED]')
})

test('output without secrets passes through unchanged', async ($, on) => {
  on('tool.call', () => ({ result: { stdout: 'hello' }, text: 'hello' }))
  const result = await $.tool.call({ tool: 'Bash', command: 'echo hello' })
  expect(result.text).toBe('hello')
})

Then validate the plugin and run the tests from its directory. claude plugin validate also lists every event the mod handles and every API call it makes, which is the same view a reviewer gets before installing it.

cd redact-secrets
claude plugin validate .
claude plugin test

  ❯ ./register.ts hooks: tool.call{tool=Bash|Read}
  ❯ ./register.ts calls: $.ui.log
✔ Validation passed

 2 pass
 0 fail
Ran 2 tests across 1 file.

Make a throwaway directory with a fake key in a file, for example OPENAI_API_KEY=sk-fake followed by enough characters to look real, and load the mod for one session with --plugin-dir. We used headless mode so the result is easy to read:

claude -p "Use the Bash tool to run exactly: cat fake.env  Then reply with the tool output verbatim, nothing else." \
  --plugin-dir ./redact-secrets --allowedTools "Bash(cat:*)" --model haiku

Claude’s reply, with the mod loaded:

APP_NAME=demo
OPENAI_API_KEY=[REDACTED]
DEBUG=true

We repeated the run with the Read tool instead of Bash and got the same redacted output. In an interactive session started with claude --plugin-dir ./redact-secrets, the mod’s $.ui.log call adds a dim line to the transcript, and Claude Code reloads the module when you save a change to it.

Know what this mod does not do. It only catches the formats in its pattern list, and only on Bash and Read; Grep, web fetches and MCP tools pass through untouched unless you add them to the matcher. The secret is still in the file and in your terminal. And Claude Code’s documentation is plain that mods aren’t sandboxed: the code runs with your permissions, so a mod you install from someone else can read the same secrets this one hides. Our security checklist for Claude Code Mods covers what to check before installing one. For teams that want guardrails like this designed and rolled out across their coding agents, our AI transformation team can help.