Skip to content

State ​

mod.state holds the mod's values. Claude Mod Manager (cmod) saves them, redraws the mod's panes and renders when one changes, and lets a person change the starting values without touching the mod's code.

Declare the state ​

defineMod's state groups the starting values by how long they last:

GroupHow long a value lastsSaved
memoryUntil /clear, --resume, /branch, or a reload of Claude Code or its plugins. A compaction keeps it.No
sessionThis conversation. It comes back on --resume, starts over on /clear, and a fork of the conversation starts with it.Yes
projectThis project, in every conversation.Yes
globalEvery project.Yes

cmod keeps each session value as long as Claude Code keeps the session's transcript, so a session comes back with its values for as long as --resume can find it.

A fork of the conversation, by /branch, claude --resume <id> --fork-session, or a move to the agents view, starts with the session values of the conversation it came from. Outside /branch, Claude Code does not say which conversation a fork came from, so the cmod plugin matches the fork's copied conversation to the one it came from. A fork starts with the starting values when it was taken while the conversation it came from was still answering, or in a -p run.

cmod keeps each project value for the 20 projects that wrote it last, and a project past those 20 starts that value over from its starting value.

Put values the mod works out again on every prompt, such as a git status, in memory.

Declare the state in its own file with its type, as cmod new does:

ts
export type TasksState = {
  memory: { changedFiles: readonly string[] }
  session: { prompts: number }
  project: { isFrozen: boolean }
  global: { defaultCommitPolicy: 'ask' | 'never' }
}

export const initialState: TasksState = {
  memory: { changedFiles: [] },
  session: { prompts: 0 },
  project: { isFrozen: false },
  global: { defaultCommitPolicy: 'ask' },
}

Then pass it to defineMod:

ts
import { defineMod, sessions } from '../node_modules/@cmodjs/core/mod.js'
import { initialState } from './state.js'

export const myMod = defineMod({
  name: 'my-mod',
  state: initialState,
  setup(mod) {
    sessions.current.onPrompt(() => {
      mod.state.session.prompts += 1
    })
  },
})

A group other than memory, session, project, and global throws <mod>: state.<group> is not a lifetime. when the mod starts. A group that is not an object of values throws too.

Change a value ​

Assign to a key. cmod saves the new value and redraws the mod.

  • A key the state does not declare throws <mod>: mod.state.<group>.<key> is not declared. Add it to state.<group> in defineMod with its starting value.
  • An object or an array in the state is frozen. Changing it in place throws <mod>: mod.state.<path> cannot change in place. Assign a new value instead:
ts
import { defineMod, sessions } from '../node_modules/@cmodjs/core/mod.js'

export const myMod = defineMod({
  name: 'my-mod',
  state: { memory: { readFiles: [] as readonly string[] } },
  setup(mod) {
    sessions.current.onToolResult(({ files }) => {
      mod.state.memory.readFiles = [...mod.state.memory.readFiles, ...files.read]
    })
  },
})
  • Keep only JSON data in a saved group. A value cmod cannot save, such as one that is not JSON, fails as Could not keep state.<group>.<key>, with Claude Code's reason under it.
  • cmod saves values one at a time in the order they were assigned.

Where the values come from ​

When the mod starts, each value is the value the mod saved for this session, this project, or globally, or else the starting value in defineMod. After a /cd to another project, cmod loads that project's project values.

mod.state holds what the mod owns and changes as it runs. What a person sets, such as a token or a branch to watch, is an option (options.md).

Let a person replace a Skill's text ​

Each mod has two config folders, outside its code:

text
~/.claude/cmods/<mod>/              the person's own, in every project
<project>/.claude/cmods/<mod>/      the team's, committed with the repository

CLAUDE_CONFIG_DIR moves ~/.claude. Removing the mod keeps both folders. The project folder also holds the team's options, in options.json (options.md).

A person replaces the text of a Skill the mod ships by putting a file at the same path in a config folder:

text
~/.claude/cmods/<mod>/skills/<skill>/SKILL.md
<project>/.claude/cmods/<mod>/skills/<skill>/SKILL.md
  • Claude reads that file in place of the mod's from the next time the Skill loads, and updates of the mod keep it.
  • The project file wins over the person's file.
  • cmod drops the file's frontmatter, so the mod's own name and description stay.
  • Only a Skill the mod ships in skills/<skill>/ is replaced, and only when it loads as <mod>:<skill>.
  • Deleting the file brings the mod's text back.

Test state ​

testMod(mod, { state: { session: { prompts: 3 } } }) starts the tested mod with those values over the declared ones. tested.state reads the values after a test step. testing.md covers both.

Free and open source under MIT. Privacy policy. Terms of use. Support.