Plugins

Add Claude Code plugins, and what their hooks do.

A plugin adds skills, commands, agents, hooks, MCP servers and language servers. ngram reads Claude Code plugins as they are. Settings › Plugins lists each one with a switch, what it adds, and any problem loading it.

ScopeLocation
Global~/.ngram/plugins/<plugin>/
Project.ngram/plugins/<plugin>/. Loads only once the folder is trusted.

Hooks

A hook runs when something happens in a thread. A plugin's hooks are in hooks/hooks.json, grouped by event:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/format.sh" }]
      }
    ]
  }
}
TypeDoes
commandRuns a program.
httpPosts the hook's input to a URL.
mcp_toolCalls a tool on an MCP server.
promptAsks a model a question.
agentRuns a read-only agent.

All five run on tool events, UserPromptSubmit, Stop and SubagentStop. Session and lifecycle events take command, http and mcp_tool, and SessionStart takes command and mcp_tool. A hook its event does not take is skipped, and the plugin's row says so.

Events that run

GroupEvents
ToolsPreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest
Messages and agentsUserPromptSubmit, UserPromptExpansion, Stop, StopFailure, SubagentStart, SubagentStop
ThreadSessionStart, SessionEnd, PreCompact, PostCompact, InstructionsLoaded, ConfigChange, FileChanged, PreModelSwitch, PostModelSwitch, MessageDisplay, Notification, TaskCreated, TaskCompleted

Events that never fire

These load, and the plugin's row lists them as Never fires here.

EventWhy
SetupIt runs only for command line flags, and a thread has none.
PermissionDeniedIt runs only when auto mode's classifier denies a call, and ngram has no classifier.
CwdChangedEach shell call starts in the thread's folder, so a cd never carries over.
DirectoryAddedA thread has the one folder it opened, with no way to add another.
TeammateIdleIt belongs to agent teams, which ngram does not have.
WorktreeCreate, WorktreeRemovengram makes no worktrees.
Elicitation, ElicitationResultngram's MCP client does not take input requests from a server.

An event name ngram does not know loads with a warning.

What a hook is sent

A command hook gets Claude Code's hook JSON on stdin, and an http hook gets it as the request body. It holds the thread's session_id, the cwd, the hook_event_name and the event's own fields, such as tool_name and tool_input. Tools go by Claude Code's names: Bash, Read, Write, Edit, Grep, Glob and Agent.

What its answer can do

  • Exit 0 succeeds, and JSON on stdout applies. Exit 2 blocks on an event that can block, and stderr is the reason the agent reads.
  • Any other exit, a timeout or a bad answer shows a notice. The turn carries on.
  • systemMessage shows as the plugin's row in the thread. The model never sees it.
  • additionalContext is added for the model.
  • continue: false ends the turn after the hook.
  • A PreToolUse hook can answer permissionDecision allow, deny or ask, and updatedInput to change the call. PostToolUse can change the result with updatedToolOutput.

allow skips the approval card the call would have raised. It never overrides a deny rule, a rule that asks, or the sandbox. A plugin from a project folder cannot allow.

Hooks run outside the sandbox

A hook runs as you, with the project folder as its working directory, and the sandbox does not apply to it. An http hook sends the hook's input, a prompt included, to its URL. Turn on only plugins you trust.