Claude Code, Plugin Settings.
Explains why Claude Code plugin settings must be written to a .claude/plugin-name.local.md file with YAML frontmatter, and how a sed-based hook parser can silently mangle multiline values.
Getting a Claude Code plugin's settings to survive between sessions isn't something you ask Claude to remember in conversation, it's something you write down. Each Claude Code session starts blank, so a setting mentioned only in chat is gone the moment a new session begins. What actually persists is a file.
The file that persists
The pattern is one file: .claude/plugin-name.local.md, sitting in the project root. Above the line, YAML frontmatter holds structured fields like enabled, mode, or retry counts. Below it, a markdown body holds free text that gets read back later. This split matters because it separates data a script needs to parse mechanically from notes meant for a human or for Claude's own context.
Three consumers, one file
Three different things read that same file. A hook is a bash script that parses the frontmatter with sed. A command uses Claude Code's Read tool directly. An agent references the file in its own instructions. All three consumers point at the same source of truth rather than each maintaining a separate copy of the settings.
The reliable case
One field in particular, enabled, drives a quick-exit pattern: check whether the file exists, check the enabled field, and stop before doing anything else if it's false. Flip that field between true and false repeatedly, and the hook obeys every time. A flat value like a simple boolean is exactly what a sed extraction is built to handle reliably.
Where the parsing breaks silently
Hand that same parser something more complex, a multiline value, a quoted colon, or an indented block, and it can silently mangle what it reads back. No error appears. The frontmatter simply stops matching what's actually on the page. This is the practical risk worth knowing about before relying on this pattern: it's reliable for simple flat fields and fragile for anything structurally more complex, with no warning when it breaks.
Why this matters practically
Plugin settings aren't something you ask Claude to remember, they're a file it reads back every time, in a shape simple enough to parse correctly, or not parsed correctly at all. Anyone building a Claude Code plugin that needs persistent configuration should keep the frontmatter fields flat and simple specifically because of how sed-based parsing behaves. A restart is required after changing the file for the new settings to take effect; nothing hot-swaps mid-session.
Trying it yourself
A useful test is to ask Claude to add a settings file to a plugin that stores an enabled flag and a validation mode, with a hook that checks it before running. Then check three things in the response: does it place the file at .claude/plugin-name.local.md, not somewhere else; does it use YAML frontmatter above a markdown body rather than one flat format; and does the hook check whether the file exists, then check enabled, exiting cleanly before doing anything else if either check fails.
Key takeaways
- Claude Code plugin settings persist through a file,
.claude/plugin-name.local.md, not through anything mentioned in conversation. - YAML frontmatter holds structured fields; a markdown body below holds free text.
- Hooks, commands, and agents all read the same file, each through a different mechanism.
- A flat field like
enabledparses reliably withsed, but multiline values, quoted colons, or indented blocks can be silently mangled. - Changing the settings file requires a session restart; nothing hot-swaps mid-session.
Who this is for
Developers building Claude Code plugins that need configuration to persist across sessions, and anyone debugging a plugin setting that seems to silently stop working.
Chapters
Full transcript(auto-generated, with timestamps)
How do I get Claude Code to remember my plugin's settings between sessions?
[0:00]Someone wants Claude code to remember a plugin settings between sessions. It won't. Each session starts blank. The real question, how does Claude code read those settings back? One file holds the answer. Telling Claude in conversation
A file, not a memory
[0:12]To remember a setting doesn't survive a new session. Start over and it's gone. What persists is a file, Claude/plugin name local.md sitting in the project route. Above the line YAML front matter holds structured fields, enabled mode or retry count. Below it a markdown body holds free text read back later.
Three consumers, one file — the anchor
[0:30]Three consumers read that same file. A hook is a bash script that parses the front matter with sed. A command uses the read tool in Claude's own context. An agent references it directly in its instructions. Watch the anchor one field enabled drives a quick exit. Check the file, check enabled and stop before doing anything else if it's false. Flip enabled again, false true false and the
Reliable — then silent
[0:50]Hook obeys every time. A flat field like that is exactly what a bash sed extraction is built for. But hand it something else, a multi-line value, a quoted colon, an indented block and that same parser can silently mangle what it reads back. No error appears. The front matter just stops matching what's on the page. A plugin settings aren't something
Carry-out
[1:09]You ask Claude to remember. They're a file it reads back every time in a shape simple enough to parse or not parsed at all. Your turn. Here's the prompt. Read it with me. Add a settings file to my
Your turn
[1:19]Plugin that stores an enabled flag and a validation mode and have a hook check it before running. Watch three things when Claude answers. Does it place the file at Claude/plugin name local.md not somewhere else? Does it use YAML front matter above a markdown body instead of one flat format? And does the hook check whether the file exists then check enabled? And exit zero before doing anything else if either check fails. Lay 'em in for bear. Claude code plugin settings. Lay 'em in for bear.
