Claude Code Mod not working: loading, hot reload and state

If a Claude Code Mod does not work or loses status during hot reload, start with the symptom and the real message. Installing, loading the module, executing the handler and drawing the UI are different steps. Reinstalling everything before distinguishing them can hide the cause and create incomparable copies. The Official Troubleshooting Guide describes these levels.

This procedure is verified on 9 October 2026. It serves to build a reproducible diagnosis, without inventing the result of a machine that we do not have access to. To orient yourself in architecture read What are Mods; if the problem is only updating an installed copy, parts from installation and reload.

What is the exact symptom of the mod not working?

Write the expected and observed behavior in two sentences. "The plugin is broken" is not enough. ‘The command does not appear in the list’ leads to registration and loading. "The command appears but returns an old value" leads to state or given. "The value changes but the panel is missing" leads to the surface and render. The first fork reduces the number of hypotheses.

It also indicates what has changed immediately before: updating, reloading, new session, moving directories or changing code. Do not assume that the most recent change is necessarily the cause, but use it to prepare a comparison. A useful diagnosis looks for controllable differences between before and after, not a random list of possible problems.

Preserves minimal playback: an input, a response, and a change. If the defect appears only after a long session, try to identify the event that makes it observable. Reducing the case does not mean reducing the user problem; it means making it verifiable before changing code.

Version, policy and rollout: how to separate them?

Check the actual version of Claude Code. Operating guides indicate 2.1,287 or later, but a recent feature may require more. The online reference does not update your installation. For locally developed mods compare the code with the types generated by the build you use. Creation Guide.

Then read the policy. disableAllHooks, boot mode and organizational settings can prevent the module from loading. A rejection message is more useful than a circumvention attempt. If the machine is managed, it retains the reason for the manager and completes the code verifications that are not dependent on the policy change.

Documentation also reports a remote rollout that can disable installed Mods and values saved from previous sessions. Do not infer that it happened in your case just because the possibility exists. The message must match the symptom. A new session may update that state according to the guide, but it does not replace the analysis of the reason reported.

Where to look for proof of loading?

The Panel /plugin allows you to consult the status of the plugin; the line mods active helps to recognize which modules are actually active. In the debug log the pattern may appear after hooks module, mod name and not loaded:. The Diagnosis Guide describes this reading.

Do not confuse the presence of the package with the execution of each part. Some settings may leave other components available while the module is not loaded. The fact that a plugin Skill appears does not prove that its mod is active. This distinction is useful when a pack includes more capacity and the symptom affects only one of them.

To collect logs use the documented path of claude --debug only in your controlled environment. Keep the necessary extract, eliminating sensitive content before sharing it. The report should indicate reason, event and version; it does not require the entire conversation or a copy of the customer repository. Read also AI and Data Security before exporting diagnostics.

Validation passes but the module does nothing: why?

A validation result should be read, not just searched in its last line. The creation guide shows information about recognized events and calls. If the event you wanted to manage is missing, the loader will not have the expected behavior. An incorrect name or an unrecognisable recording can be discovered before the session.

Also check the link modules of hooks/hooks.json and the export of the input file. A valid manifest is not enough if the path points to a different file. The plugin command reference distinguishes this analysis from behavior tests. The question is what the product reads from the module, not what the author imagined he had recorded.

If the structure is correct, prepare a synthetic event and an expectation. The guide to test a mod helps to verify the path without a call to the model. A small case allows the defective handler to be separated from the rest of the environment and reduces the risk of modifying components that work.

Did you update the right copy?

Identifies source, version, broom, and path. A directory loaded with --plugin-dir and a copy installed from marketplaces may have the same name but different content. A colleague can observe correct behavior in the development directory while the usual session continues to use the previous package.

For custom plugins, check that the version was incremented before deployment. For the session, check if the reload has been applied or if a new session is needed. Do not directly modify the cache to match two machines: correct the distribution path. The Guide to installation and update treat these three levels.

Distinctive behavior helps to verify the version without doing risky operations. It can be a description of the command or an answer on fixture. Do not add logs with customer data just to figure out which copy responds. A designed diagnostic should make the component recognizable, not export everything it sees.

Is the UI missing even if the command works?

This symptom shifts the diagnosis from recording to presentation. It controls which surface you use and which point the mod draws. Terminal, desktop, and other forms of execution do not have identical UI capabilities. An active handler can then work without showing the expected component. Mods Surfaces.

Then check render filters, props, and available space. One band may be occupied by another customization. A panel may require a different layout. Do not change the data source if the command shows that the value is already correct: first check where and how it is represented.

Demos offer clear cases. Token Weather has a band of its own; Replay Theater has a temporary view of the shift. If you use a surface other than the one stated, the first problem is the use contract, not necessarily a bug in the code.

Why does the hot reload lose status?

A module variable is recreated at the reload. Documentation distinguishes this duration from $.state, which survives the reload in the session life cycle, and by $.store, persistent on disk. State and store respond to different needs; persistence is not an automatic improvement. Interface and Status Mods.

End-of-session, clear, resume, or branch operations can reset the state according to the documented cycle. The store itself has a relationship to cleaning for inactivity. If the requirement is to retain a preference for a long time, write it explicitly. If the requirement is to keep only turn data, do not save it to disk to avoid an occasional reset.

For diagnosis prepare a sequence: set a synthetic value, observe the result, reload, observe again. Then repeat the life cycle step that affects the requirement. The test should distinguish what needs to continue from what needs to be erased. A value left when it should disappear is also a bug.

Choose the duration of the data before changing status

If the data serves only the currently loaded code, a variable may be sufficient. If you need to resist reloading in the session, evaluate the status predicted by the API. If you have to live on disk, define necessity, deletion, and minimal content before using the store. In any case try the step that the requirement promises to support.

Two hypothetical diagnoses in an Italian team

Hypothetical example: an agency in Pavia sees the counter return to zero. The colleague modifies the text of the UI and notes the reset. The group reproduces the case with few events and discovers that the value lives in a modulus variable. It does not interpret the episode as a repository loss or model issue. First it decides whether the reset complies with the requirement.

If the counter needs to cover the session, change the status mechanism and add a proof to the reload. If you need to describe the currently loaded code, keep the reset and correct the description. The same observation can lead to two correct choices: it matters what the product promised, not the implicit preference of the first author.

Hypothetical example: an SME from Ancona does not see an approved mod. The function appears on the manager's machine but is missing on a colleague's machine. The team collects version, source and reason for rejection. It does not lower the controls to make the panel appear. Checks if the package was distributed through the intended organizational path.

The comparison shows why installation and governance must be consistent. A plugin enabled by a managed configuration can remain in the user tier if it comes from the cache of an ordinary source. The Guide to Team and Security Mods explains this boundary, without promising that any qualification is equivalent to managed provenance.

What attempts make debugging worse?

The first is to change version, policy and code in the same attempt: you lose the comparison. The second is to erase the symptom with a reinstallation without retaining the reason. The third is to treat the session that continues as evidence that the handler has succeeded. The fourth is saving everything to disk to avoid resets. The fifth is to disable an organizational check to correct a UI issue.

A better method modifies only one hypothesis and repeats the minimum sequence. When a test fails twice in the same way, stop and double-check the level of the problem. If the module is not loaded, a render correction will not help it. If the data is right but old, the manifest may be irrelevant. The symptom hierarchy avoids directionless patches.

When to stop correcting and redrawing the proof?

If two attempts produce the same symptom, double-check the initial question. You may be trying out a UI where you need to verify the upload, or a variable when the requirement relates to the duration of the session. Go back to the minimum case and choose one piece of evidence that distinguishes two hypotheses. The next change must serve to that comparison, without multiplying settings and copies of the plugin.

How to deliver a useful diagnosis to the manager?

Prepare a note with expected behavior, observed behavior, version, surface, plugin source, and minimal playback. Add the relevant log extract and the result of the verification. Distinguish confirmed cause, excluded hypothesis and still open limit. A short report with evidence is worth more than an entire history of attempts.

If a customization needs to become stable on your team, a software house can link diagnosis, testing and distribution to the repository. The guides to Claude Code and a Mods Test They help transform the reproducible defect into a control that prevents it from reappearing.