Claude Mods Revealed: TypeScript Hooks for Claude Code

Introduction

Claude Mods is an upcoming extension mechanism built for Claude Code, designed to modify commands, tool invocations, UI rendering and security policies using TypeScript functions. Anthropic formally confirmed the naming of this feature on September 9, 2026, and the public discussion thread has accumulated 173 comments from the developer community.

At the time of writing, Claude Mods remains in Early Access status. The official roadmap indicates a public release within several weeks, while warning that exposed interfaces are subject to breaking changes before general availability. This new plugin architecture introduces Function Hooks, which enable developers to intercept and inject custom logic into the core agent execution pipeline of Claude Code.

This article breaks down the operating principle of Claude Mods, contrasts it against traditional hook implementations, explains the activation workflow, dissects the three officially released built-in Mods, and outlines directory structure, testing workflows and adoption considerations for engineering teams. The analysis incorporates official sample code, repository documentation and community discussion records to clarify what this plugin system can and cannot deliver.

How Claude Mods and Function Hooks Work

Multiple Mods execute in registration order, forming an onion-style middleware chain similar to routing middleware in Express or Koa web frameworks. Handlers registered earlier wrap those registered later. This architectural trait carries important security implications: organization administrators can place security enforcement Mods at the outermost layer. These top-level Mods inspect incoming requests first and validate outputs before they are delivered to subsequent pipeline stages.

The following TypeScript snippet illustrates the core handler pattern. This example intercepts tool.call events and blocks dangerous Bash commands before they are dispatched to the agent runtime.

export default function register(on) {
  on('tool.call', async ($, event, next) => {
    if (event.tool === 'Bash' && looksDangerous(event.input)) {
      return { deny: 'Command blocked by policy' }
    }
    const result = await next(event)
    return result
  })
}

Anthropic explicitly notes that this code demonstrates only the architectural paradigm, not a stable production API. Field definitions and return structures must follow type declarations generated by the installed release version. Developers should not treat this minimal sample as a contract for future upgrades.

Core Differences Between Claude Mods / Function Hooks and Classic Hooks

Function Hooks represent a fundamental shift. The older hook model relies on invoking external standalone scripts. The new design embeds custom logic directly into the engine event chain. Developers may listen to MCP and non-MCP tool calls, and access controlled side effects through the $ object exposed in the hook context.

The table highlights the most impactful distinction: Classic Hooks operate as separate external processes. Claude Mods run as typed middleware inside the agent harness, with centralized permission mediation. This greatly improves auditability for enterprise deployments, while adding stricter constraints for developers building extensions.

How to Enable Claude Mods in Early Access

As of September 15, 2026, Function Hooks have not reached stable channel status. The experimental activation method published in official GitHub Issues uses environment variables to unlock the feature.

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude

Before activation, users must upgrade to a Claude Code build compatible with this experimental interface. Official test interfaces are updated around v267/v268, and Anthropic provides no guarantee of cross-version compatibility. Engineers must avoid relying on these experimental builds inside production environments.

To run the official sample diff Mod from source code, navigate to a checked-out copy of the Claude Code repository and execute the following commands:

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1
claude --plugin-dir mods/diff

After entering a Git repository with uncommitted changes, invoke the Mod inside the Claude Code session:

/diff

According to the official README, /diff renders uncommitted repository changes for the current conversation. The panel refreshes after edits in the Claude editor, after command execution, or after completion of a full task turn.

Three Built-in Mods Released by Anthropic

Anthropic has open-sourced source code for three native Mods, each demonstrating a distinct category of use cases enabled by the plugin system.

diff: Code-diff panel implemented as a plugin

The diff Mod registers the /diff slash command. It monitors Git workspace changes and renders file lists and code hunks. It subscribes to a broad set of lifecycle events including session.start, command.run, tool.call, turn.complete and prompt.submit, alongside multiple UI events. This Mod demonstrates how extensions can combine command registration, repository inspection and dynamic UI rendering in a single TypeScript module.

sec-default: Enterprise policy enforcement

The sec-default Mod sits on the outer layer of the Mod middleware chain. It prevents user-installed plugins from overwriting managed CLAUDE.md rules, legacy Classic Hooks, configuration parameters and MCP allowlists. It does not inject custom security rules by itself; its core job is preserving priority for administrator-defined policies. This makes it essential for organizations enforcing centralized governance over agent extensions.

telemetry: Statistics interface for downstream Mods

The telemetry Mod injects the $.telemetry interface at the engine construction phase. It allows internal plugins to record structured event data. Anthropic specifies that it only activates when Claude Code’s native analytics are enabled. Setting DO_NOT_TRACK or DISABLE_TELEMETRY, or running under a third-party Provider, suppresses telemetry data transmission entirely.

Directory Structure of a Custom Mod

Official built-in Mods require at minimum a plugin manifest, hook configuration and TypeScript modules. Third-party developers should use the current official examples as templates instead of only copying isolated .ts source files. A minimal custom Mod structure looks like this:

my-mod/
├── .claude-plugin/
│   └── plugin.json
├── hooks/
│   ├── hooks.json
│   └── register.ts
├── tests/
│   └── register.test.ts
└── types/

Claude Code automatically generates type declarations for plugin references. Official examples import type definitions directly from claude-code to access event schemas and testing types.

The following commands validate and test local Mod implementations:

tsc -p mods/tsconfig.json
claude plugin test mods/diff

This workflow performs type checking and runs plugin test suites, helping developers catch type mismatches and logic errors before deploying Mods into live agent sessions.

Separation of Model API and Mod Extension Layers

Claude Mods extends the Agent Harness layer. The model API handles the underlying LLM inference service source. These two layers should be managed independently. This separation is a critical architectural point frequently misunderstood by developers.

This design suits standalone OpenAI-compatible clients and services. The model access layer is independent, and it does not replace Claude Mods, nor can it substitute for Claude Code’s native Provider support. A sample Python client for connecting to compatible model endpoints is shown below:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["YOUR_API_KEY"],
    base_url="https://4sapi.com/v1"
)

response = client.chat.completions.create(
    model="deepseek-v4",
    messages=[{"role": "user", "content": "Write a test function"}]
)

When engineering teams manage multiple LLM backends while building agent extensions like Claude Mods, a unified routing layer simplifies credential maintenance and traffic control. 4sapi, an API gateway, offers centralized request management for multi-model environments.

Evaluation: Is Claude Mods Ready for Adoption?

The target audience for Claude Mods includes Claude Code plugin developers, heavy Function Hook users, and enterprise teams requiring centralized permission enforcement. Casual users may start by experimenting with the public diff example first, without immediately migrating legacy Classic Hooks workflows.

Three major limitations currently constrain production adoption.

1. Interfaces may change without advance notice. Breaking alterations can occur between Early Access preview builds.
2. Mods are not listed in the official Marketplace. Distribution and versioning remain manual for custom plugins.
3. Experimental feature toggles do not qualify for official production support.

Testing should be confined to isolated Git repositories and non-sensitive datasets. Teams should retain Classic Hooks as a fallback migration pathway.

According to Anthropic’s official discussion and source code release for built-in Mods, the product name, core event model and initial three reference implementations have been finalized. As of September 15, 2026, the feature remains in Early Access. Readers working with production systems should recheck command syntax, installation procedures and Mod behavior after official launch or Marketplace release.

Conclusion

Claude Mods represents a major evolution in extensibility for agent coding environments. By moving extension logic from separate external scripts into TypeScript middleware running inside the agent event pipeline, Anthropic gives developers deeper control over tool calls, UI rendering and security policy enforcement. The onion-style middleware architecture, demonstrated by sec-default, is particularly valuable for enterprise teams that must maintain centralized governance while allowing plugin customization.

The three built-in reference Mods showcase the breadth of what this plugin system can accomplish: repository visualization, security guardrails and observability tooling. Developers building custom extensions benefit from native TypeScript typing and LSP support, which drastically improves the developer experience compared to Classic Hooks.

Nevertheless, the Early Access status carries tangible risks. Teams must treat this feature as experimental and maintain fallback workflows. When building multi-model agent systems, separating the agent harness extension layer from the underlying model inference API is essential.

International access: https://4sapi.com
Domestic access: https://4sapi.cn