Claude Code Mod API Fs Store State

Mod API: Files, Store, and State

$.fs reads and writes files as the Claude Code process. $.store keeps values of the plugin between sessions. $.state holds named values with versions during a session. A render hook that reads a state value is drawn again when the value changes. Example: const readme = await $.fs.read("README.md"), then await $.store.set("count", 1). Limits: one file is at most 4 MiB, and $.store holds at most 4 MiB of JSON.

In the "Where" column, Run time means in a hook, in a closure that a hook drew, or in a timer callback. It does not mean inside register.

Members

Mark	Item	What it does	How it works	Where it can be used	Source
✅	$.fs.read	Reads a file and returns its text, or with { as: "bytes" } its bytes as { base64 }.	Type: three call forms. Rejects when the file is missing or over 4 MiB. options.as is "text" (default) or "bytes". Example: await $.fs.read("README.md").	Run time.	CoreEngineInterface line 3324, Mods Reference
✅	$.fs.write	Writes text to a file, creating it and its directories as needed.	Type: (path: string, text: string) => Promise<void>. Parameter path: relative to the working directory, or absolute. Parameter text: the whole new content.	Run time.	CoreEngineInterface line 3331, Mods Reference
✅	$.fs.list	Lists a directory by name: { name, kind, size, mtimeMs, isLink } per entry, each entry as it stands.	Type: (path?: string) => Promise<FsEntry[]>. Lists a directory. Each entry has name, kind, size, mtimeMs, and isLink. A symbolic link is other with isLink.	Run time.	CoreEngineInterface line 3345, Mods Reference
✅	$.fs.exists	Returns whether the path exists, rejects only a network location, which the implementation beneath the hooks never touches.	Type: (path: string) => Promise<boolean>.	Run time.	CoreEngineInterface line 3350, Mods Reference
✅	$.fs.stat	Returns { kind, size, mtimeMs, isLink } of the path: what it leads to, and whether it is itself a symbolic link. Rejects when missing.	Type: (path: string, options?: FsStatOptions) => Promise<FsStat>. With { resolve: true } it also gives realPath. Rejects ENOENT for a missing path.	Run time.	CoreEngineInterface line 3403, Mods Reference
✅	$.fs.ancestors	Reads the named instruction files in every directory above the session's original working directory, the way the engine reads CLAUDE.md.	Type: (request: FsAncestorsRequest) => Promise<readonly FsAncestor[]>. Returns the .md files on the path from the root to a file, root first. It is the engine's own walk for nested CLAUDE.md files.	Run time.	CoreEngineInterface line 3424, Mods Reference
✅	$.store.get	Returns the value under key, or undefined when unset.	Type: (key: string) => Promise<unknown>. Example: const count = Number((await $.store.get("count")) ?? 0) + 1.	Run time.	CoreEngineInterface line 3440, Mods Reference
✅	$.store.set	Sets key to value, which must be JSON data.	Type: (key: string, value: unknown) => Promise<void>. Stores JSON data. get reads back a JSON copy. Rejects a function, a cycle, or a store over 4 MiB.	Run time.	CoreEngineInterface line 3448, Mods Reference
✅	$.store.delete	Removes key from the store.	Type: (key: string) => Promise<void>.	Run time.	CoreEngineInterface line 3452, Mods Reference
✅	$.store.keys	Returns every key set, in insertion order.	Type: () => Promise<string[]>.	Run time.	CoreEngineInterface line 3456, Mods Reference
✅	$.state.get	Resolves the value under ref and the version it stands at, a value never written is undefined at version 0.	Type: (ref: StateRef<P, K>) => Promise<StateRead<StateValue<P, K>>>. Reads a named value. plugin and key must be literals in the source. Resolves { value, version }.	Run time.	CoreEngineInterface line 3482, Mods Reference
✅	$.state.set	Writes value under ref, which must be this plugin's own, the sites that read it while drawing are drawn again, at the redraw rate.	Type: (ref, value, options?) => Promise<StateSetResult>. Writes a named value. Refused while a ui.render hook draws. ifVersion writes only at that version. Resolves { isSet, version }.	Not while a ui.render hook draws.	CoreEngineInterface line 3498, Mods Reference

State Helpers Imported from claude-code

Mark	Item	What it does	How it works	Where it can be used	Source
✅	atom	A named value with its initial: read answers the initial while nothing is written, so never undefined. Pure, runs in the plugin's environment.	Imported from claude-code. Type AtomFunction.	Module code. Pure helpers.	atom line 15413, Mods Reference
✅	derive	A value computed from atoms and references, cached by their versions.	Imported from claude-code. Type DeriveFunction. Example: const busy = derive([workers], list => list.filter(w => w.isBusy).length).	Module code. Pure helpers.	derive line 15421, Mods Reference
✅	memberOf	A family's member for the instance being drawn, keyed by e.requestId.	Imported from claude-code. Type MemberOfFunction. Example: const open = await read($, memberOf(isOpen, e)).	Module code. Pure helpers.	memberOf line 15429, Mods Reference
✅	read	Reads an atom, a derived value or a reference through $.state.get, while a ui.render hook draws, that subscribes the drawing.	Imported from claude-code. Type ReadFunction. Example: const n = await read($, count).	Module code. Pure helpers.	read line 15438, Mods Reference
✅	update	Reads, applies fn in the plugin's environment, writes with ifVersion, and tries again on a miss: what a handler closure calls.	Imported from claude-code. Type UpdateFunction. Example: <Button key="more" onPress={() => update($, count, n => n + 1)} />.	Module code. Pure helpers.	update line 15447, Mods Reference

Events Raised by These Calls

Mark	Item	What it does	How it works	Where it can be used	Source
✅	fs.read	The argument of $.fs.read(path, { as }): as is text unless the caller asked for bytes.	Input: { path: string, as: FsReadAs, }. Value: string | FsBytes. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('fs.read', ...). Raised by the call $.fs.read(...).	OpEventOf line 7204, Mods Reference
✅	fs.write	The argument of $.fs.write(path, text).	Input: { path: string, text: string, }. Value: void. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('fs.write', ...). Raised by the call $.fs.write(...).	OpEventOf line 7211, Mods Reference
✅	fs.list	The argument of $.fs.list(path).	Input: { path: string, }. Value: FsEntry[]. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('fs.list', ...). Raised by the call $.fs.list(...).	OpEventOf line 7218, Mods Reference
✅	fs.exists	The argument of $.fs.exists(path).	Input: { path: string, }. Value: boolean. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('fs.exists', ...). Raised by the call $.fs.exists(...).	OpEventOf line 7224, Mods Reference
✅	fs.stat	The argument of $.fs.stat(path, { resolve }): resolve is false unless the caller asked where the path lands.	Input: { path: string, resolve: boolean, }. Value: FsStat. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('fs.stat', ...). Raised by the call $.fs.stat(...).	OpEventOf line 7231, Mods Reference
✅	fs.ancestors	The argument of $.fs.ancestors({ names, of, below }).	Input: FsAncestorsRequest. Value: readonly FsAncestor[]. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('fs.ancestors', ...). Raised by the call $.fs.ancestors(...).	OpEventOf line 7238, Mods Reference
✅	store.get	The argument of $.store.get(key).	Input: { key: string, }. Value: unknown. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('store.get', ...). Raised by the call $.store.get(...).	OpEventOf line 7242, Mods Reference
✅	store.set	The argument of $.store.set(key, value).	Input: { key: string, value: unknown, }. Value: void. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('store.set', ...). Raised by the call $.store.set(...).	OpEventOf line 7248, Mods Reference
✅	store.delete	The argument of $.store.delete(key).	Input: { key: string, }. Value: void. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('store.delete', ...). Raised by the call $.store.delete(...).	OpEventOf line 7255, Mods Reference
✅	store.keys	The argument of $.store.keys().	Input: NoArgs. Value: string[]. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('store.keys', ...). Raised by the call $.store.keys(...).	OpEventOf line 7261, Mods Reference
✅	state.get	The argument of $.state.get(ref): the reference itself, plugin, key and a family member's id, identity, pinned.	Input: StateGetEvent. Value: StateRead. A hook above the caller returns next(e), { deny: reason } or { value }.	Hook via on('state.get', ...). Raised by the call $.state.get(...).	OpEventOf line 7266, Mods Reference
✅	state.set	The argument of $.state.set(ref, value, { ifVersion }): the reference, the value, the condition, and previous, what stood there (the host's).	Input: StateSetEvent. Value: StateSetResult. A hook above the caller returns next(e), { deny: reason }, or { value }. Only the value's owner raises it.	Hook via on('state.set', ...). Raised by the call $.state.set(...).	OpEventOf line 7275, Mods Reference

See Also

• Mod API: Files, State, Clock, HTTP, Process, and Settings Types
• Mod API: Clock, HTTP, Process, Env, and Settings
• Claude Code Mod API
• Draw in the Interface