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. When a state value changes, the engine draws again each render hook that reads it.

There is no switch. A file is at most 4 MiB. $.store holds at most 4 MiB of JSON. $.fs uses the real file system. $.store and $.state belong to the plugin.

Official pages: Draw in the Interface, Mods Reference. Source: the Mod API type file of the 2.1.312 program (schemas/claude-code.d.ts). "Run time" appears in a "Where it can be used" cell. It means in a hook, in a closure that a hook drew, or in a timer callback. It does not mean inside register.

Example

on("turn.complete", async ($, e, next) => {
  const count = Number((await $.store.get("count")) ?? 0) + 1;
  await $.store.set("count", count);
  return next(e);
});

Members

Item	Status	What it does	How it works	Where it can be used
$.fs.read	Documented: An official docs page names this item.	Reads a file and returns its text. With { as: "bytes" } it returns the bytes as { base64 }.	Three call forms. Rejects when the file is missing or over 4 MiB. options.as is "text" (default) or "bytes".	Run time.
$.fs.write	Documented: An official docs page names this item.	Writes text to a file, creating it and its directories as needed.	(path, text) => Promise<void>. path is relative to the working directory, or absolute. text is the whole new content.	Run time.
$.fs.list	Documented: An official docs page names this item.	Lists a directory: { name, kind, size, mtimeMs, isLink } for each entry.	(path?) => Promise<FsEntry[]>. A symbolic link is other with isLink.	Run time.
$.fs.exists	Documented: An official docs page names this item.	Returns whether the path exists.	(path) => Promise<boolean>. Rejects only for a network location.	Run time.
$.fs.stat	Documented: An official docs page names this item.	Returns { kind, size, mtimeMs, isLink } of the path. Rejects when missing.	(path, options?) => Promise<FsStat>. With { resolve: true } it also gives realPath. A missing path rejects with ENOENT.	Run time.
$.fs.ancestors	Documented: An official docs page names this item.	Reads the named instruction files in every directory above the session's first working directory, the way the engine reads CLAUDE.md.	(request) => Promise<readonly FsAncestor[]>. Returns the .md files on the path from the root to a file, root first.	Run time.
$.store.get	Documented: An official docs page names this item.	Returns the value under key, or undefined when unset.	(key) => Promise<unknown>.	Run time.
$.store.set	Documented: An official docs page names this item.	Sets key to value, which must be JSON data.	(key, value) => Promise<void>. Rejects a function, a cycle, or a store over 4 MiB.	Run time.
$.store.delete	Documented: An official docs page names this item.	Removes key.	(key) => Promise<void>.	Run time.
$.store.keys	Documented: An official docs page names this item.	Returns every key set, in insertion order.	() => Promise<string[]>.	Run time.
$.state.get	Documented: An official docs page names this item.	Resolves the value under ref and its version. A value never written is undefined at version 0.	(ref) => Promise<StateRead>. plugin and key must be literals in the source. Resolves { value, version }.	Run time.
$.state.set	Documented: An official docs page names this item.	Writes value under ref, which must be this plugin's own. The engine draws again the sites that read it while drawing, at the redraw rate.	(ref, value, options?) => Promise<StateSetResult>. ifVersion writes only at that version. Resolves { isSet, version }.	Not while a ui.render hook draws.

State Helpers Imported from claude-code

These helpers are pure code. They run in the plugin's own environment.

Item	Status	What it does	How it works
atom	Documented: An official docs page names this item.	A named value with an initial value. read gives the initial value until code writes a value, so never undefined.	Type AtomFunction.
derive	Documented: An official docs page names this item.	A value computed from atoms and references, cached by their versions.	Type DeriveFunction. Example: derive([workers], list => list.filter(w => w.isBusy).length).
memberOf	Documented: An official docs page names this item.	A family's member for the instance being drawn, keyed by e.requestId.	Type MemberOfFunction. Example: await read($, memberOf(isOpen, e)).
read	Documented: An official docs page names this item.	Reads an atom, a derived value, or a reference through $.state.get while a ui.render hook draws. That subscribes the drawing.	Type ReadFunction. Example: await read($, count).
update	Documented: An official docs page names this item.	Reads, applies fn, writes with ifVersion, and tries again on a miss. A handler closure calls it.	Type UpdateFunction. Example: <Button key="more" onPress={() => update($, count, n => n + 1)} />.

Events Raised by These Calls

For each call, a hook above the caller returns next(e), { deny: reason }, or { value }.

Item	Status	The argument	Input and value
fs.read	Documented: An official docs page names this item.	$.fs.read(path, { as }). as is text unless the caller asked for bytes.	Input { path: string, as: FsReadAs }. Value string | FsBytes.
fs.write	Documented: An official docs page names this item.	$.fs.write(path, text)	Input { path: string, text: string }. Value void.
fs.list	Documented: An official docs page names this item.	$.fs.list(path)	Input { path: string }. Value FsEntry[].
fs.exists	Documented: An official docs page names this item.	$.fs.exists(path)	Input { path: string }. Value boolean.
fs.stat	Documented: An official docs page names this item.	$.fs.stat(path, { resolve }). resolve is false unless asked.	Input { path: string, resolve: boolean }. Value FsStat.
fs.ancestors	Documented: An official docs page names this item.	$.fs.ancestors({ names, of, below })	Input FsAncestorsRequest. Value readonly FsAncestor[].
store.get	Documented: An official docs page names this item.	$.store.get(key)	Input { key: string }. Value unknown.
store.set	Documented: An official docs page names this item.	$.store.set(key, value)	Input { key: string, value: unknown }. Value void.
store.delete	Documented: An official docs page names this item.	$.store.delete(key)	Input { key: string }. Value void.
store.keys	Documented: An official docs page names this item.	$.store.keys()	Input NoArgs. Value string[].
state.get	Documented: An official docs page names this item.	$.state.get(ref): the reference itself (plugin, key, and a family member's id). Pinned.	Input StateGetEvent. Value StateRead.
state.set	Documented: An official docs page names this item.	$.state.set(ref, value, { ifVersion }) plus previous, what stood there.	Input StateSetEvent. Value StateSetResult. Only the value's owner raises it.

Related Pages

• Mod API Overview
• Clock, HTTP, Process, Env, and Settings
• Files, State, Clock, HTTP, Process, and Settings Types (shapes of FsEntry, FsStat, StateRef, and more)